GearmanStore — Gearman job server

GearmanStore — Gearman job server Overview Gearman is a generic application framework for farming out work — a job server, not a database. A client submits a job for a named function, the job server routes it to a worker that has registered a handler for that function, and the result flows back. There is no query language and no SQL-shaped access pattern. Because none of that fits the SQL-shaped Dialect interface, GearmanStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Gearman's real submit/register operations (enqueue/process/getJob/remove/stats) directly rather than forcing them into a query(sql) shape. Identity: Property | Value | --------- | ----------- | name | 'gearman' | library | 'gearman' | The store is built on the gearman driver. Lazy loading — not a hard dependency gearman is not a hard dependency of this package. It is an optional peer, loaded lazily via require('gearman') inside connect() rather than a top-level import. Importing this module therefore does not require the driver to be installed — it is only needed when a Gearman store is actually connected. Injected client GearmanStoreOptions accepts a pre-built client. When provided, connect() adopts it directly and does not require('gearman'). This is how the test suite injects a mock client (no driver, no network), and how callers can supply a custom-configured client. Connection Build a store from connection options and call connect(): When no injected client is present, connect() lazy-requires gearman and builds a client via gearman.createClient(port, host) (falling back to new gearman.Client(port, host)), then awaits client.connect() if the driver exposes it. Failures are wrapped in a ConnectionError (a message containing ECONNREFUSED is normalized to 'Connection refused'). Option | Type | Purpose | -------- | -------- | ------------------------------------------------------------ | host | string | Gearman job-server host. Defaults to '127.0.0.1'. | port | number | Gearman job-server port. Defaults to 4730. | client | any | A pre-built gearman client to adopt directly (mock or custom). When set, the driver is not required. | Injected-client form Methods Driver failures are wrapped in a DatabaseError (message Gearman <action> failed: ..., preserving the original error). Using the client before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Adopts an injected client, otherwise lazy-requires gearman, builds a client, and connects. Idempotent when already connected. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Calls the client's close() (or disconnect()) and clears connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): any | Returns the underlying gearman client. Throws ConnectionError if not connected. | Queue operations Method | Signature | Behavior | --------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | enqueue | enqueue(queue: string, jobData: unknown, opts?: GearmanSubmitOptions): Promise<string> | Submits a job for the named function (queue) via client.submitJob(func, payload, opts). Payload is JSON-serialized (strings pass through). Returns the job handle/id (job.handle ?? job.id, or the string itself, or ''). | process | process(queue: string, handler: (job: any) => void \| Promise<void>): Promise<void> | Registers a worker handler for the named function via client.registerWorker(func, handler), falling back to client.addFunction(func, handler) when registerWorker is absent. | getJob | getJob(queue: string, id: string): Promise<any> | Queries the status of a submitted job by handle/id via client.getJobStatus(id). | remove | remove(queue: string, id: string): Promise<any> | Cancels/forgets a submitted job by handle/id via client.removeJob(id). | stats | stats(queue?: string): Promise<any> | Returns job-server status (registered functions, queued/running counts) via client.getStatus(). | Supporting type: Example Verification status Unit / mock-verified only. The tests in tests/nosql/gearman.test.ts are fully mock-driven: a fake gearman client with spies for submitJob/registerWorker/addFunction/getJobStatus/removeJob/getStatus/close is injected via GearmanStoreOptions.client, so connect() adopts it and skips require('gearman'). The real gearman package is not installed, and there is no live Gearman job server and no network in the test run. What this proves: name/library identity and injected-client adoption without loading the driver. Lifecycle: disconnect() calling close(), and ConnectionError when using the client before connecting. enqueue submitting the JSON-serialized job with options and returning the handle. process calling registerWorker, and falling back to addFunction when registerWorker is absent. getJob querying status, remove cancelling, stats reading server status. Error handling: submit failures wrapped in DatabaseError. What this does not prove: live execution against a real Gearman job server. Call shapes are verified against the driver's documented contract, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories