From c79792f55bed0f06d35c5dda3d1b77f3fc3c3d32 Mon Sep 17 00:00:00 2001 From: Maxime LUCE Date: Fri, 25 Oct 2019 22:40:46 +0200 Subject: [PATCH] Add node-beanstalkd-client library types (#39434) --- types/beanstalkd/beanstalkd-tests.ts | 22 ++ types/beanstalkd/index.d.ts | 536 +++++++++++++++++++++++++++ types/beanstalkd/tsconfig.json | 23 ++ types/beanstalkd/tslint.json | 1 + 4 files changed, 582 insertions(+) create mode 100644 types/beanstalkd/beanstalkd-tests.ts create mode 100644 types/beanstalkd/index.d.ts create mode 100644 types/beanstalkd/tsconfig.json create mode 100644 types/beanstalkd/tslint.json diff --git a/types/beanstalkd/beanstalkd-tests.ts b/types/beanstalkd/beanstalkd-tests.ts new file mode 100644 index 0000000000..4700a2e21a --- /dev/null +++ b/types/beanstalkd/beanstalkd-tests.ts @@ -0,0 +1,22 @@ +import Beanstalkd from 'beanstalkd'; + +const host = '127.0.0.1'; +const port = 11300; +const tube = 'TestTube'; + +const beanstalkd = new Beanstalkd(host, port); + +beanstalkd.connect().then(beanstalkd => { + const priority = 1; + const delay = 10 * 60; + const ttr = 5 * 60; + + // Verbosely put a new job + beanstalkd.use(tube).then(() => beanstalkd.put(priority, delay, ttr)); + + // Or use fancy bluebird features + beanstalkd.call('use', tube).call('put', priority, delay, ttr); + + // Close when done + beanstalkd.quit(); +}); diff --git a/types/beanstalkd/index.d.ts b/types/beanstalkd/index.d.ts new file mode 100644 index 0000000000..51983a3a64 --- /dev/null +++ b/types/beanstalkd/index.d.ts @@ -0,0 +1,536 @@ +// Type definitions for beanstalkd 2.2 +// Project: https://github.com/burstable/node-beanstalkd-client +// Definitions by: Maxime LUCE +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 3.0 + +/// + +import { Socket } from "net"; + +export type FunctionsNames = { [K in keyof T]: T[K] extends (...args: any[]) => any ? K : never }[keyof T] & string; +export type ArgsType = T extends (...args: infer A) => any ? A : never; +export type UnPromise = T extends Promise ? R : T; +export type MergePromise = Promise>; + +export default class BeanstalkdClient { + host?: string; + port?: number; + options?: {}; + + closed: boolean; + protocol: BeanstalkdProtocol; + + constructor(host?: string, port?: number, options?: {}); + + /** + * Prepare a command which will be applied on the Client. + * + * @param command The command to prepare. + * @param expected The expected reply. + */ + static addCommand(command: string, expected: string): void; + + /** + * Prepare a command which will be applied on the Client. + * + * @param command The command to prepare. + * @param expected The expected reply. + */ + static addYamlCommand(command: string, expected: string): void; + + /** + * Connect the Client to the configured Server. + */ + connect(): Promise & BeanstalkdCaller; + + /** + * Close the Client connection. + */ + quit(): Promise; + + /** + * Calling unref() on a socket will allow the program to exit if this is the only active socket in the event system. + * If the socket is already unrefed calling unref() again will have no effect. + */ + unref(): void; + + /** + * Delete the specified job. Responds with null if successful, a string error otherwise. + * This is the only method not named identically to its beanstalkd counterpart, because delete is a reserved word in Javascript. + * + * @param id The job id to delete. + */ + destroy(id: number): Promise; + + /** + * Execute a command on Beanstalkd protocol. + * + * @param command Command name to execute. + * @param args Arguments for the command. + * @param writer The Writer to use for this command. + * @param reader The Reader to use for this command. + */ + _command( + command: string, + args: any[], + writer: BasicWriter, + reader: BasicReader | YamlReader, + ): Promise; + + //#region Connection events + + /** + * Listen on given event. + * + * @param event The event to listen on. + * @param listeners The listeners for this event. + */ + on(event: string, ...listeners: Array<(...args: any[]) => void>): void; + /** + * The connect event is triggered when the connection is ready. + * The drain event is triggered when connection drains. + * The end event is triggered when connection ends. + * The timeout event is triggered when connection timeout. + * + * @param event The event to listen on. + * @param listeners Listeners for the event. + */ + on(event: 'connect' | 'drain' | 'end' | 'timeout', ...listeners: Array<() => void>): void; + /** + * The error event is triggered when an error occured on the connection. + * + * @param event The event to listen on. + * @param listeners Listeners for the error event. + */ + on(event: 'error', ...listeners: Array<(err: Error) => void>): void; + /** + * The close event is triggered when connection closes. + * + * @param event The event to listen on. + * @param listener Listeners for the close event. + */ + on(event: 'close', ...listeners: Array<(had_error: boolean) => void>): void; + /** + * The data event is triggered when socket receives data. + * + * @param event The event to listen on. + * @param listener Listeners for the data event. + */ + on(event: 'data', ...listeners: Array<(data: Buffer) => void>): void; + /** + * The lookup event is triggered when connection performs a lookup on a new address. + * + * @param event The event to listen on. + * @param listener Listeners for the lookup event. + */ + on( + event: 'lookup', + ...listeners: Array<(err: Error, address: string, family: string | number, host: string) => void> + ): void; + + //#endregion + + //#region Commands + + /** + * Use the specified tube. + * Reponds with the name of the tube being used. + * + * @param tube Tube name to use. + */ + use(tube: string): Promise; + + /** + * Responds with the name of the tube currently being used by the client. + */ + listTubeUsed(): Promise; + + /** + * Submit a job with the specified priority (smaller integers are higher priority), delay in seconds, and allowed time-to-run in seconds. + * The payload contains the job data the server will return to clients reserving jobs; it can be either a Buffer object or a string. + * No processing is done on the data. Responds with the id of the newly-created job. + * + * @param priority Priority of the job. + * @param delay Delay of the job in seconds. + * @param ttr Time-to-run of the job in seconds. + * @param payload The job payload. + */ + put(priority: number, delay: number, ttr: number, payload?: string | Buffer): Promise; + + /** + * Peek at the data for the job at the top of the ready queue of the tube currently in use. + * Responds with the job id and payload of the next job, or 'NOT_FOUND' if there are no qualifying jobs in the tube. + * The payload is a Buffer object. + */ + peekReady(): Promise<[string, Buffer]>; + + /** + * Peek at the data for the delayed job with the shortest delay in the tube currently in use. + * Responds with the job id and payload of the next job, or 'NOT_FOUND' in err if there are no qualifying jobs in the tube. + * The payload is a Buffer object. + */ + peekDelayed(): Promise<[string, Buffer]>; + + /** + * Peek at the data for the next buried job in the tube currently in use. + * Responds with the job id and payload of the next job, or 'NOT_FOUND' in err if there are no qualifying jobs in the tube. + * The payload is a Buffer object. + */ + peekBuried(): Promise<[string, Buffer]>; + + /** + * Watch the named tube. + * Responds with the number of tubes currently watched by the client. + * + * @param tube The Tube name to watch. + */ + watch(tube: number): Promise; + + /** + * Ignore the named tube. + * Responds with the number of tubes currently watched by the client. + * + * @param tube The Tube name to ignore. + */ + ignore(tube: number): Promise; + + /** + * Responds with an array containing the names of the tubes currently watched by the client. + */ + listTubeWatched(): Promise; + + /** + * Reserve a job. + * Responds with the id and the job data. + * The payload is a Buffer object. + */ + reserve(): Promise<[string, Buffer]>; + + /** + * Reserve a job, waiting the specified number of seconds before timing out. + * err contains the string "TIMED_OUT" if the specified time elapsed before a job became available. + * Payload is a buffer. + * + * @param seconds Timeout in seconds. + */ + reserveWithTimeout(seconds: number): Promise; + + /** + * Inform the server that the client is still processing a job, thus requesting more time to work on it. + * + * @param id The job id to reset TTR on. + */ + touch(id: number): Promise; + + /** + * Delete the specified job. Responds with null if successful, a string error otherwise. + * This is the only method not named identically to its beanstalkd counterpart, because delete is a reserved word in Javascript. + * + * @param id The job id to delete. + */ + delete(id: number): Promise; + + /** + * Release the specified job and assign it the given priority and delay (in seconds). + * + * @param id The job id to release. + * @param priority The new priority in seconds. + * @param delay The new delay in seconds. + */ + release(id: number, priority: number, delay: number): Promise; + + /** + * Bury the specified job and assign it the given priority. Responds with null if successful, a string error otherwise. + * + * @param id The job id to bury. + * @param priority The new priority to assign. + */ + bury(id: number, priority: number): Promise; + + /** + * Kick at most maxToKick delayed and buried jobs back into the active queue. + * Responds with the number of jobs kicked. + * + * @param maxToKick Max number of job to kick and bury. + */ + kick(maxToKick: number): Promise; + + /** + * Kick the specified job id. Responds with NOT_FOUND if the job was not found. + * Supported in beanstalkd versions >= 1.6. + * + * @param id The job id to kick. + */ + kickJob(id: number): Promise; + + /** + * Peek at the data for the specified job. + * Payload is a Buffer object. + * + * @param id The job id to peek. + */ + peek(id: number): Promise; + + /** + * Pause the named tube for the given number of seconds. + * No new jobs may be reserved from the tube while it is paused. + * + * @param tube The name of the tube to pause. + * @param delay The pause duration (in seconds). + */ + pauseTube(tube: string, delay: number): Promise; + + /** + * List all the existing tubes. Responds with an array of tube names. + */ + listTubes(): Promise; + + /** + * Request statistics for the specified job. + * Responds with a hash containing information about the job. + * + * @param id The job id to request stats for. + */ + statsJob(id: number): Promise; + + /** + * Request statistics for the specified tube. + * Responds with a hash containing information about the tube. + * + * @param tube The name of the Tube to request stats for. + */ + statsTube(tube: string): Promise; + + /** + * Request statistics for the beanstalkd server. + * Responds with a hash containing information about the server. + */ + stats(): Promise; + + //#endregion +} + +export interface BeanstalkdCaller { + call, "on" | "unref" | "call">>( + fn: K, + ...args: ArgsType[K]> + ): MergePromise[K]>> & BeanstalkdCaller; +} + +export interface BeanstalkdProtocol { + add(signature: string, key: string): void; + addCommand(signature: string): void; + addType(key: string, type: any): void; + addReply(signature: string): void; + + reset(): void; + + build(identifier: string, args: any[], key: string): Buffer; + buildCommand(command: string, args: any[]): Buffer; + buildreply(reply: string, args: any[]): Buffer; + buildPut(args: any[]): Buffer; + + parse(buffer: Buffer, key: string): [Buffer | null, BeanstalkdProtocolCommand | BeanstalkdProtocolReply | null]; + parseCommand(buffer: Buffer): [Buffer | null, BeanstalkdProtocolCommand | null]; + parseReply(buffer: Buffer): [Buffer | null, BeanstalkdProtocolReply | null]; +} + +export interface BeanstalkdProtocolCommand { + command: string; + args: any[]; +} + +export interface BeanstalkdProtocolReply { + reply: string; + args: any[]; +} + +export type BeanstalkdJobState = "ready" | "delayed" | "reserved" | "buried"; + +export interface BeanstalkdJobStats { + /** The job id. */ + id: string; + /** The name of the tube that contains this job. */ + tube: string; + /** The job state. */ + state: string; + /** The priority value set by the put, release, or bury commands. */ + pri: number; + /** The time in seconds since the put command that created this job. */ + age: number; + /** The integer number of seconds to wait before putting this job in the ready queue. */ + delay: number; + /** Time to run: The integer number of seconds a worker is allowed to run this job. */ + ttr: number; + /** + * The number of seconds left until the server puts this job into the ready queue. + * This number is only meaningful if the job is reserved or delayed. + * If the job is reserved and this amount of time elapses before its state changes, it is considered to have timed out. + */ + "time-left": number; + /** + * The number of the earliest binlog file containing this job. + * If -b wasn't used, this will be 0. + */ + file: number; + /** The number of times this job has been reserved. */ + reserves: number; + /** The number of times this job has timed out during a reservation. */ + timeouts: number; + /** The number of times a client has released this job from a reservation. */ + releases: number; + /** The number of times this job has been buried. */ + buries: number; + /** The number of times this job has been kicked. */ + kicks: number; +} + +export interface BeanstalkdTubeStats { + /** The tube's name. */ + name: string; + /** The number of ready jobs with priority < 1024 in this tube. */ + "current-jobs-urgent": number; + /** The number of jobs in the ready queue in this tube. */ + "current-jobs-ready": number; + /** The number of jobs reserved by all clients in this tube. */ + "current-jobs-reserved": number; + /** The number of delayed jobs in this tube. */ + "current-jobs-delayed": number; + /** The number of buried jobs in this tube. */ + "current-jobs-buried": number; + /** The cumulative count of jobs created in this tube in the current beanstalkd process. */ + "total-jobs": number; + /** The number of open connections that are currently using this tube. */ + "current-using": number; + /** The number of open connections that have issued a reserve command while watching this tube but not yet received a response. */ + "current-waiting": number; + /** The number of open connections that are currently watching this tube. */ + "current-watching": number; + /** The number of seconds the tube has been paused for. */ + pause: number; + /** The cumulative number of delete commands for this tube. */ + "cmd-delete": number; + /** The cumulative number of pause-tube commands for this tube. */ + "cmd-pause-tube": number; + /** The number of seconds until the tube is un-paused. */ + "pause-time-left": number; +} + +export interface BeanstalkdStats { + /** The number of ready jobs with priority < 1024. */ + "current-jobs-urgent": number; + /** The number of jobs in the ready queue. */ + "current-jobs-ready": number; + /** The number of jobs reserved by all clients. */ + "current-jobs-reserved": number; + /** The number of delayed jobs. */ + "current-jobs-delayed": number; + /** The number of buried jobs. */ + "current-jobs-buried": number; + /** The cumulative number of put commands. */ + "cmd-put": number; + /** The cumulative number of peek commands. */ + "cmd-peek": number; + /** The cumulative number of peek-ready commands. */ + "cmd-peek-ready": number; + /** The cumulative number of peek-delayed commands. */ + "cmd-peek-delayed": number; + /** The cumulative number of peek-buried commands. */ + "cmd-peek-buried": number; + /** The cumulative number of reserve commands. */ + "cmd-reserve": number; + /** The cumulative number of use commands. */ + "cmd-use": number; + /** The cumulative number of watch commands. */ + "cmd-watch": number; + /** The cumulative number of ignore commands. */ + "cmd-ignore": number; + /** The cumulative number of delete commands. */ + "cmd-delete": number; + /** The cumulative number of release commands. */ + "cmd-release": number; + /** The cumulative number of bury commands. */ + "cmd-bury": number; + /** The cumulative number of kick commands. */ + "cmd-kick": number; + /** The cumulative number of stats commands. */ + "cmd-stats": number; + /** The cumulative number of stats-job commands. */ + "cmd-stats-job": number; + /** The cumulative number of stats-tube commands. */ + "cmd-stats-tube": number; + /** The cumulative number of list-tubes commands. */ + "cmd-list-tubes": number; + /** The cumulative number of list-tube-used commands. */ + "cmd-list-tube-used": number; + /** The cumulative number of list-tubes-watched commands. */ + "cmd-list-tubes-watched": number; + /** The cumulative number of pause-tube commands. */ + "cmd-pause-tube": number; + /** The cumulative count of times a job has timed out. */ + "job-timeouts": number; + /** The cumulative count of jobs created. */ + "total-jobs": number; + /** The maximum number of bytes in a job. */ + "max-job-size": number; + /** The number of currently-existing tubes. */ + "current-tubes": number; + /** The number of currently open connections. */ + "current-connections": number; + /** The number of open connections that have each issued at least one put command. */ + "current-producers": number; + /** The number of open connections that have each issued at least one reserve command. */ + "current-workers": number; + /** The number of open connections that have issued a reserve command but not yet received a response. */ + "current-waiting": number; + /** The cumulative count of connections. */ + "total-connections": number; + /** The process id of the server. */ + pid: string; + /** The version string of the server. */ + version: string; + /** The cumulative user CPU time of this process in seconds and microseconds. */ + "rusage-utime": number; + /** The cumulative system CPU time of this process in seconds and microseconds. */ + "rusage-stime": number; + /** The number of seconds since this server process started running. */ + uptime: number; + /** The index of the oldest binlog file needed to store the current jobs. */ + "binlog-oldest-index": number; + /** The index of the current binlog file being written to. If binlog is not active this value will be 0. */ + "binlog-current-index": number; + /** The maximum size in bytes a binlog file is allowed to get before a new binlog file is opened. */ + "binlog-max-size": number; + /** The cumulative number of records written to the binlog. */ + "binlog-records-written": number; + /** The cumulative number of records written as part of compaction. */ + "binlog-records-migrated": number; + /** Set to "true" if the server is in drain mode, "false" otherwise. */ + draining: boolean; + /** A random id string for this server process, generated every time beanstalkd process starts. */ + id: string; + /** The hostname of the machine as determined by uname. */ + hostname: string; + /** The OS version as determined by uname */ + os: string; + /** The machine architecture as determined by uname */ + platform: string; +} + +export interface BasicReader { + parseData(data: string): any; + handle(protocol: BeanstalkdProtocol, data: any, resolve: (data?: any) => void, reject: (err?: any) => any): Buffer; +} + +export interface YamlReader extends BasicReader { + parseData(data: string): object; +} + +export interface Writer { + command: string; +} + +export interface BasicWriter extends Writer { + handle(protocol: BeanstalkdProtocol, connection: Socket, ...args: any[]): Promise; +} diff --git a/types/beanstalkd/tsconfig.json b/types/beanstalkd/tsconfig.json new file mode 100644 index 0000000000..d6255b74ac --- /dev/null +++ b/types/beanstalkd/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "baseUrl": "../", + "typeRoots": [ + "../" + ], + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "beanstalkd-tests.ts" + ] +} \ No newline at end of file diff --git a/types/beanstalkd/tslint.json b/types/beanstalkd/tslint.json new file mode 100644 index 0000000000..3db14f85ea --- /dev/null +++ b/types/beanstalkd/tslint.json @@ -0,0 +1 @@ +{ "extends": "dtslint/dt.json" }