From 08c8d4b84a6adf7888b77adc2935eb6839a937b7 Mon Sep 17 00:00:00 2001 From: Tim Jones Date: Sun, 11 Aug 2024 15:01:54 -0500 Subject: [PATCH] types and docs --- docs/readme.md | 83 +++++++++++++++++++++++++++++--------------- src/plans.js | 2 +- test/queueTest.js | 3 ++ test/scheduleTest.js | 1 - test/testHelper.js | 2 +- types.d.ts | 8 ++--- 6 files changed, 64 insertions(+), 35 deletions(-) diff --git a/docs/readme.md b/docs/readme.md index 63e948c..8d10928 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -28,11 +28,12 @@ - [`sendAfter(name, data, options, value)`](#sendaftername-data-options-value) - [`sendThrottled(name, data, options, seconds, key)`](#sendthrottledname-data-options-seconds-key) - [`sendDebounced(name, data, options, seconds, key)`](#senddebouncedname-data-options-seconds-key) - - [`insert([jobs])`](#insertjobs) + - [`insert(Job[])`](#insertjob) - [`fetch(name, options)`](#fetchname-options) - [`work()`](#work) - [`work(name, options, handler)`](#workname-options-handler) - [`work(name, handler)`](#workname-handler) + - [`notifyWorker(id)`](#notifyworkerid) - [`offWork(value)`](#offworkvalue) - [`publish(event, data, options)`](#publishevent-data-options) - [`subscribe(event, name)`](#subscribeevent-name) @@ -51,11 +52,14 @@ - [`complete(name, [ids], options)`](#completename-ids-options) - [`fail(name, id, data, options)`](#failname-id-data-options) - [`fail(name, [ids], options)`](#failname-ids-options) - - [`notifyWorker(id)`](#notifyworkerid) - - [`getQueueSize(name, options)`](#getqueuesizename-options) - [`getJobById(name, id, options)`](#getjobbyidname-id-options) - [`createQueue(name, Queue)`](#createqueuename-queue) + - [`updateQueue(name, options)`](#updatequeuename-options) + - [`purgeQueue(name)`](#purgequeuename) - [`deleteQueue(name)`](#deletequeuename) + - [`getQueues()`](#getqueues) + - [`getQueue(name)`](#getqueuename) + - [`getQueueSize(name, options)`](#getqueuesizename-options) - [`clearStorage()`](#clearstorage) - [`isInstalled()`](#isinstalled) - [`schemaVersion()`](#schemaversion) @@ -635,7 +639,7 @@ Like, `sendThrottled()`, but instead of rejecting if a job is already sent in th This is a convenience version of `send()` with the `singletonSeconds`, `singletonKey` and `singletonNextSlot` option assigned. The `key` argument is optional. -## `insert([jobs])` +## `insert(Job[])` Create multiple jobs in one request with an array of objects. @@ -662,6 +666,8 @@ interface JobInsert { ## `fetch(name, options)` +Returns an array of jobs from a queue + **Arguments** - `name`: string - `options`: object @@ -703,8 +709,6 @@ interface JobInsert { } ``` -**Resolves** -- `[job]`: array of jobs **Notes** @@ -804,6 +808,11 @@ await boss.work(queue, async ([ job ]) => { }) ``` +## `notifyWorker(id)` + +Notifies a worker by id to bypass the job polling interval (see `pollingIntervalSeconds`) for this iteration in the loop. + + ## `offWork(value)` Removes a worker by name or id and stops polling. @@ -936,31 +945,16 @@ The promise will resolve on a successful failure state assignment, or reject if > See comments above on `cancel([ids])` regarding when the promise will resolve or reject because of a batch operation. -## `notifyWorker(id)` - -Notifies a worker by id to bypass the job polling interval (see `pollingIntervalSeconds`) for this iteration in the loop. - -## `getQueueSize(name, options)` -Returns the number of pending jobs in a queue by name. +## `getJobById(name, id, options)` -`options`: Optional, object. +Retrieves a job with all metadata by name and id -| Prop | Type | Description | Default | -| - | - | - | - | -|`before`| string | count jobs in states before this state | states.active | +**options** -As an example, the following options object include active jobs along with created and retry. +* `includeArchive`: bool, default: false -```js -{ - before: states.completed -} -``` - -## `getJobById(name, id, options)` - -Retrieves a job with all metadata by id in either the primary or archive storage. + If `true`, it will search for the job in the archive if not found in the primary job storage. ## `createQueue(name, Queue)` @@ -984,15 +978,48 @@ Allowed policy values: | Policy | Description | | - | - | | standard | (Default) Supports all standard features such as deferral, priority, and throttling | -| debounced | All standard features, but only allows 1 job to be queued, unlimited active. Can be extended with `singletonKey` | +| short | All standard features, but only allows 1 job to be queued, unlimited active. Can be extended with `singletonKey` | | singleton | All standard features, but only allows 1 job to be active, unlimited queued. Can be extended with `singletonKey` | -| stately | Combination of debounced and singleton: Only allows 1 job per state, queued and/or active. Can be extended with `singletonKey` | +| stately | Combination of short and singleton: Only allows 1 job per state, queued and/or active. Can be extended with `singletonKey` | + +## `updateQueue(name, options)` + +Updates options on an existing queue. The policy can be changed, but understand this won't impact existing jobs in flight and will only apply the new policy on new incoming jobs. +## `purgeQueue(name)` + +Deletes all queued jobs in a queue. ## `deleteQueue(name)` Deletes a queue and all jobs from the active job table. Any jobs in the archive table are retained. +## `getQueues()` + +Returns all queues + +## `getQueue(name)` + +Returns a queue by name + +## `getQueueSize(name, options)` + +Returns the number of pending jobs in a queue by name. + +`options`: Optional, object. + +| Prop | Type | Description | Default | +| - | - | - | - | +|`before`| string | count jobs in states before this state | states.active | + +As an example, the following options object include active jobs along with created and retry. + +```js +{ + before: states.completed +} +``` + ## `clearStorage()` Utility function if and when needed to clear all job and archive storage tables. Internally, this issues a `TRUNCATE` command. diff --git a/src/plans.js b/src/plans.js index 58eb72e..548bc8d 100644 --- a/src/plans.js +++ b/src/plans.js @@ -400,7 +400,7 @@ function getQueues (schema) { dead_letter as "deadLetter", created_on as "createdOn", updated_on as "updatedOn" - FROM ${schema}.queue + FROM ${schema}.queue ` } diff --git a/test/queueTest.js b/test/queueTest.js index 6c0bbb8..e4e97c3 100644 --- a/test/queueTest.js +++ b/test/queueTest.js @@ -134,6 +134,7 @@ describe('queues', function () { let queueObj = await boss.getQueue(queue) + assert.strictEqual(queue, queueObj.name) assert.strictEqual(createProps.policy, queueObj.policy) assert.strictEqual(createProps.retryLimit, queueObj.retryLimit) assert.strictEqual(createProps.retryBackoff, queueObj.retryBackoff) @@ -141,6 +142,8 @@ describe('queues', function () { assert.strictEqual(createProps.expireInSeconds, queueObj.expireInSeconds) assert.strictEqual(createProps.retentionMinutes, queueObj.retentionMinutes) assert.strictEqual(createProps.deadLetter, queueObj.deadLetter) + assert(queueObj.createdOn) + assert(queueObj.updatedOn) deadLetter = `${queue}_dlq2` await boss.createQueue(deadLetter) diff --git a/test/scheduleTest.js b/test/scheduleTest.js index b8c8ade..5ce049d 100644 --- a/test/scheduleTest.js +++ b/test/scheduleTest.js @@ -63,7 +63,6 @@ describe('schedule', function () { await boss.schedule(queue, '* * * * *') assert(false) } catch (err) { - console.log(err) assert(true) } }) diff --git a/test/testHelper.js b/test/testHelper.js index 82844d7..b6c1a56 100644 --- a/test/testHelper.js +++ b/test/testHelper.js @@ -108,7 +108,7 @@ async function start (options) { try { options = getConfig(options) const boss = new PgBoss(options) - boss.on('error', err => console.log({ schema: options.schema, message: err.message })) + // boss.on('error', err => console.log({ schema: options.schema, message: err.message })) await boss.start() // auto-create queue for tests if (!options.noDefault) { diff --git a/types.d.ts b/types.d.ts index 27ba68d..9e8c43e 100644 --- a/types.d.ts +++ b/types.d.ts @@ -343,15 +343,15 @@ declare class PgBoss extends EventEmitter { fail(name: string, id: string, data: object, options?: PgBoss.ConnectionOptions): Promise; fail(name: string, ids: string[], options?: PgBoss.ConnectionOptions): Promise; - getQueueSize(name: string, options?: object): Promise; getJobById(name: string, id: string, options?: PgBoss.ConnectionOptions & { includeArchive: bool }): Promise; - + createQueue(name: string, options?: PgBoss.Queue): Promise; - getQueue(name: string): Promise; - getQueues(): Promise; updateQueue(name: string, options?: PgBoss.Queue): Promise; deleteQueue(name: string): Promise; purgeQueue(name: string): Promise; + getQueues(): Promise; + getQueue(name: string): Promise; + getQueueSize(name: string, options?: { before: 'retry' | 'active' | 'completed' | 'cancelled' | 'failed' }): Promise; clearStorage(): Promise; archive(): Promise;