@bumail/queue 0.1.0 → 0.3.0

package/docs/troubleshooting.md

@@ -34,8 +34,12 @@ parts shown as … vary.
 
 - [`QueueError: The lease on … was lost before its outcome was recorded; another worker will try it again`](#queueerror-the-lease-on--was-lost-before-its-outcome-was-recorded-another-worker-will-try-it-again)
 - [`QueueError: The lease on … was lost while it was delivered`](#queueerror-the-lease-on--was-lost-while-it-was-delivered)
+- [`QueueError: The lease on … expired before its outcome was recorded, and the item is gone: lost to another worker that finished it, the message then sent twice, or cancelled`](#queueerror-the-lease-on--expired-before-its-outcome-was-recorded-and-the-item-is-gone-lost-to-another-worker-that-finished-it-the-message-then-sent-twice-or-cancelled)
+- [`QueueError: The lease on … was lost while it was delivered, and the item is gone: finished by the worker that took it, the message then sent twice, or cancelled`](#queueerror-the-lease-on--was-lost-while-it-was-delivered-and-the-item-is-gone-finished-by-the-worker-that-took-it-the-message-then-sent-twice-or-cancelled)
 - [`SmtpError: sendMail(): …` (`INVALID_OPTION`), with recipients deferred as `4.3.5`](#smtperror-sendmail--invalid_option-with-recipients-deferred-as-435)
 - [`SQLiteError: database is locked`, or another store error, during a delivery](#sqliteerror-database-is-locked-or-another-store-error-during-a-delivery)
+- [`PostgresError: …`, or a connection error, during a delivery](#postgreserror--or-a-connection-error-during-a-delivery)
+- [`RedisError: …` during a delivery: `Connection closed`, `OOM command not allowed …`, `READONLY …`](#rediserror--during-a-delivery-connection-closed-oom-command-not-allowed--readonly-)
 
 **The `bun:sqlite` store** (`@bumail/queue/sqlite`)
 
@@ -45,6 +49,25 @@ parts shown as … vary.
 - [`QueueError: busyTimeout must be an integer of at least 0, not …`](#queueerror-busytimeout-must-be-an-integer-of-at-least-0-not-)
 - [`QueueError: The queue store is closed`](#queueerror-the-queue-store-is-closed)
 
+**The PostgreSQL store** (`@bumail/queue/postgres`)
+
+- [`QueueError: A PostgreSQL queue store needs sql: a Bun.SQL client or a postgres:// URL`](#queueerror-a-postgresql-queue-store-needs-sql-a-bunsql-client-or-a-postgres-url)
+- [`QueueError: sql is a … client; the queue needs a PostgreSQL one`](#queueerror-sql-is-a--client-the-queue-needs-a-postgresql-one)
+- [`QueueError: tablePrefix must be lowercase letters, digits and underscores, starting with a letter or an underscore, at most 40 characters, not …`](#queueerror-tableprefix-must-be-lowercase-letters-digits-and-underscores-starting-with-a-letter-or-an-underscore-at-most-40-characters-not-)
+- [`QueueError: The URL in sql cannot be opened: …`](#queueerror-the-url-in-sql-cannot-be-opened-)
+- [`QueueError: The PostgreSQL queue cannot be set up: …`](#queueerror-the-postgresql-queue-cannot-be-set-up-)
+- [`QueueError: The database is at schema version …, newer than this store's …`](#queueerror-the-database-is-at-schema-version--newer-than-this-stores-), and [`QueueError: The queue store is closed`](#queueerror-the-queue-store-is-closed), as for `bun:sqlite`
+
+**The Redis store** (`@bumail/queue/redis`)
+
+- [`QueueError: A Redis queue store needs client, a Bun.RedisClient, or url, a redis:// URL`](#queueerror-a-redis-queue-store-needs-client-a-bunredisclient-or-url-a-redis-url)
+- [`QueueError: A Redis queue store takes client or url, not both`](#queueerror-a-redis-queue-store-takes-client-or-url-not-both)
+- [`QueueError: keyPrefix must be lowercase letters, digits, '_', ':', '.' and '-', starting with a letter, at most 40 characters, not …`](#queueerror-keyprefix-must-be-lowercase-letters-digits-_---and---starting-with-a-letter-at-most-40-characters-not-)
+- [`QueueError: The URL in url cannot be opened: …`](#queueerror-the-url-in-url-cannot-be-opened-)
+- [`QueueError: The Redis queue cannot be set up: …`](#queueerror-the-redis-queue-cannot-be-set-up-)
+- [`QueueError: The key …schema does not hold a layout version: is the prefix another application's?`](#queueerror-the-key-schema-does-not-hold-a-layout-version-is-the-prefix-another-applications)
+- [`QueueError: The database is at schema version …, newer than this store's …`](#queueerror-the-database-is-at-schema-version--newer-than-this-stores-), and [`QueueError: The queue store is closed`](#queueerror-the-queue-store-is-closed), as for `bun:sqlite`
+
 **Listing** (`list`)
 
 - [`QueueError: limit must be an integer from 1 to 1000, not …`](#queueerror-limit-must-be-an-integer-from-1-to-1000-not-)
@@ -53,6 +76,10 @@ parts shown as … vary.
 **A store's own checks** (a store of your own, called directly)
 
 - [`QueueError: … must be a finite number`, `owner must be a non-empty string`, and the others](#a-stores-own-checks)
+- [`QueueError: A reply is an object with a text`](#queueerror-a-reply-is-an-object-with-a-text)
+- [`QueueError: reply.status must be a string`](#queueerror-replystatus-must-be-a-string)
+- [`QueueError: reply.host must be a string`](#queueerror-replyhost-must-be-a-string)
+- [`QueueError: … holds a NUL or a lone surrogate, which a store cannot keep`](#queueerror--holds-a-nul-or-a-lone-surrogate-which-a-store-cannot-keep)
 
 **Delivery**
 
@@ -228,8 +255,10 @@ or `… must be a number from … to …, not …`. A number option out of its r
 
 ### `QueueError: owner must be a non-empty string`
 
-**Code:** `INVALID`. Leave `owner` out for a random one, or give each
-worker its own name.
+**Code:** `INVALID`, also as
+[`owner holds a NUL or a lone surrogate, which a store cannot keep`](#queueerror--holds-a-nul-or-a-lone-surrogate-which-a-store-cannot-keep).
+Leave `owner` out for a random one, or give
+each worker its own name.
 
 ## The `error` event
 
@@ -245,8 +274,54 @@ the process stalled longer than that, or the store could not be reached.
 
 ### `QueueError: The lease on … was lost while it was delivered`
 
-**Code:** `LEASE_LOST`. A renewal found the lease taken: the same cause as
-above, seen sooner.
+**Code:** `LEASE_LOST`. A renewal was refused while the item was still in
+the store, held by another worker or by none (another worker took it and
+let go of it): the same cause as above, seen sooner. A renewal that finds the item gone
+says nothing: the outcome, once the sessions end, tells a cancel from a
+lease lost (below).
+
+### `QueueError: The lease on … expired before its outcome was recorded, and the item is gone: lost to another worker that finished it, the message then sent twice, or cancelled`
+
+**Code:** `LEASE_LOST`.
+**When:** a delivery ran past its lease's expiry — no renewal reached the
+store in time — and, when it tried to record its outcome, the item was no
+longer in the store. No `delivered`, `deferred` or `failed` event and no
+DSN come from this attempt.
+**Why:** past its expiry, another worker may claim the item, deliver it
+and drop it; but a `cancel` drops it too, and the store keeps no record of
+which happened. The worker cannot tell them apart, so it says both rather
+than report outcomes nobody recorded. When another worker took it, the
+recipients both reached got the message twice; that worker's events tell
+what it delivered.
+**Fix:** as for the lease lost above: a longer `leaseMs`, or find what
+stalled the process — an event loop blocked, a store out of reach. A
+cancel under a lease that still held is told as before: its outcomes on
+the events, with no error and no DSN.
+
+When the instances' clocks are out of step, one whose clock runs ahead
+can claim the item while this worker's own clock says the lease still
+holds. If it finishes and drops the item between two of this worker's
+renewals, no renewal saw it taken and the expiry has not passed by this
+clock: the attempt reads as a cancel, its outcomes told on the events
+with no error. Keep the machines on NTP; the 10-minute `leaseMs` leaves
+room for seconds of skew.
+
+### `QueueError: The lease on … was lost while it was delivered, and the item is gone: finished by the worker that took it, the message then sent twice, or cancelled`
+
+**Code:** `LEASE_LOST`, after
+[`The lease on … was lost while it was delivered`](#queueerror-the-lease-on--was-lost-while-it-was-delivered).
+**When:** a renewal was refused while the item was still in the store,
+held by another worker or by none, and when this worker tried to record
+its outcome the item was gone. No outcome event and no DSN come from this
+attempt.
+**Why:** another worker claimed the item once this one's lease had
+expired by its own clock — this worker stalled, or the instances' clocks
+disagree (an instance whose clock runs ahead sees leases expire early) —
+and has most likely finished and dropped it, the recipients both reached
+getting the message twice. A `cancel` after the renewal drops it too, and
+the store keeps no record of which happened, so the message names both.
+**Fix:** a longer `leaseMs`, find what stalled the process, and keep the
+machines on NTP.
 
 ### `SmtpError: sendMail(): …` (`INVALID_OPTION`), with recipients deferred as `4.3.5`
 
@@ -271,6 +346,47 @@ tries again; only a renewal that finds the lease taken stops (as
 **Fix:** a longer `busyTimeout` when several processes write a lot; a
 store that keeps failing will lose the lease once it expires.
 
+### `PostgresError: …`, or a connection error, during a delivery
+
+**When:** the `error` event, with the item's `id`, while it is delivered,
+on `@bumail/queue/postgres`.
+**Why:** a lease renewal failed: the database restarted, a connection
+dropped, or the server refused one past its `max_connections`. As on
+`bun:sqlite`, the next renewal tries again, and only a lease taken by
+another instance stops them. A claim that fails the same way rejects
+`deliverDue()`, or is told on `error` under `start()`, which tries again
+at its next pass. An outcome that cannot be recorded is told on `error`
+with the item's `id`; the item stays as it was, and is claimed again once
+its lease expires — its recipients may then get the message twice.
+**Fix:** check the database is up and reachable; when the server counts
+too many connections, give each instance's client a smaller `max` (see
+the guide's Pool size) or raise `max_connections`.
+
+### `RedisError: …` during a delivery: `Connection closed`, `OOM command not allowed …`, `READONLY …`
+
+**When:** the `error` event, with the item's `id`, while it is delivered,
+on `@bumail/queue/redis`. A call of yours — `enqueue`, `list`, `get`,
+`retryNow`, `cancel` — rejects with the same `RedisError` for the same
+reasons: an `enqueue` refused with `OOM …` kept nothing.
+**Why:** a lease renewal failed. `Connection closed`: Redis restarted,
+or the connection dropped, while the command was on its way; a command
+sent while the client is reconnecting waits instead. `Max reconnection
+attempts reached` or `Connection has failed`: Redis is out of reach, and
+`Bun.RedisClient` gave up reconnecting (20 tries by default). `OOM
+command not allowed when used memory > 'maxmemory'`: Redis is full and
+refuses writes. `READONLY You can't write against a read only replica`:
+the client reaches a replica, or a primary that was demoted by a
+failover. As on PostgreSQL, the next renewal tries again, only a lease
+taken by another instance stops them, a claim that fails rejects
+`deliverDue()` or is told on `error` under `start()`, and an outcome
+that cannot be recorded leaves the item to be claimed again once its
+lease expires — its recipients may then get the message twice.
+**Fix:** check Redis is up and that the URL names the primary (through
+your provider's endpoint or Sentinel's, which follows a failover). For
+`OOM`, give Redis more `maxmemory`, or drain the queue; keep
+`maxmemory-policy noeviction` (the guide's [Redis](guide.md#redis)), or
+Redis drops queue items to make room instead of refusing.
+
 ## The `bun:sqlite` store
 
 ### `QueueError: A SQLite queue store needs a directory`
@@ -287,8 +403,10 @@ should read the queue.
 
 ### `QueueError: The database is at schema version …, newer than this store's …`
 
-**Code:** `INVALID`. A newer version of the package wrote the database:
-upgrade this one.
+**Code:** `INVALID`. A newer version of the package wrote the database
+(`queue.sqlite`, on PostgreSQL the prefix's tables, on Redis the
+prefix's keys, whose layout version is `<prefix>schema`): upgrade this
+one.
 
 ### `QueueError: busyTimeout must be an integer of at least 0, not …`
 
@@ -297,7 +415,137 @@ upgrade this one.
 ### `QueueError: The queue store is closed`
 
 **Code:** `CLOSED`. The store was used after `close()`: call
-`queue.stop()` first, then `store.close()`.
+`queue.stop()` first, then `store.close()`. The PostgreSQL and Redis
+stores say the same.
+
+## The PostgreSQL store
+
+### `QueueError: A PostgreSQL queue store needs sql: a Bun.SQL client or a postgres:// URL`
+
+**Code:** `INVALID`.
+**When:** `PostgresQueueStore.open` without `sql`, or with a string that
+is not a `postgres://` or `postgresql://` URL, or an object without
+`unsafe`, `begin` and `close`. The message never repeats the URL, which
+may hold a password.
+**Fix:**
+
+```ts
+PostgresQueueStore.open({ sql: 'postgres://bumail:secret@db.internal:5432/mail' });
+// or a client of yours, sized as you need:
+PostgresQueueStore.open({ sql: new Bun.SQL({ url, max: 10 }) });
+```
+
+### `QueueError: sql is a … client; the queue needs a PostgreSQL one`
+
+**Code:** `INVALID`. A `Bun.SQL` client made for SQLite or MySQL
+(`adapter: 'sqlite'`, a `mysql://` URL). For SQLite, use
+`@bumail/queue/sqlite`; otherwise give a PostgreSQL client.
+
+### `QueueError: tablePrefix must be lowercase letters, digits and underscores, starting with a letter or an underscore, at most 40 characters, not …`
+
+**Code:** `INVALID`.
+**Why:** the prefix is written into every statement, never bound as a
+value, so anything that is not a plain name is refused — and 40
+characters keep the longest name built on it within PostgreSQL's 63.
+**Fix:** `tablePrefix: 'mail_queue_'`. To put the tables in another
+schema, set the connection's `search_path` rather than a dotted prefix.
+
+### `QueueError: The URL in sql cannot be opened: …`
+
+**Code:** `INVALID`.
+**When:** `PostgresQueueStore.open` with a URL `Bun.SQL` refuses before
+connecting, such as a `sslmode` it does not know. The rest is Bun's
+reason (`The argument 'sslmode' must be one of: disable, allow, prefer,
+require, verify-ca, verify-full. Received '…'`); the URL is never
+repeated, and the password is masked should the reason name it.
+**Fix:** correct the parameter: `?sslmode=require`, or `verify-full` to
+check the server's certificate.
+
+### `QueueError: The PostgreSQL queue cannot be set up: …`
+
+**Code:** `INVALID`.
+**When:** the first call on a store, or `migrate()`, when the tables
+cannot be made or brought up to date. The rest of the message is the
+database's: `Failed to connect`, `password authentication failed for
+user "…"`, `permission denied for schema public`.
+**Why:** the database is out of reach, the credentials are wrong, or the
+tables are missing or behind and the role may not create them: a role
+without `CREATE` can use tables that are current, never make them.
+**Fix:** check the URL and that the server answers. For `permission
+denied`, run `migrate()` once with an owner's role — on a new database,
+and after an upgrade that adds a migration — and keep the workers on
+their narrower role (the guide's [Migrations](guide.md#migrations)); or
+give the role `CREATE` on the schema. The next call tries again: nothing is left half made,
+since a migration is one transaction.
+
+## The Redis store
+
+### `QueueError: A Redis queue store needs client, a Bun.RedisClient, or url, a redis:// URL`
+
+**Code:** `INVALID`.
+**When:** `RedisQueueStore.open` with neither `client` nor `url`, a
+`url` that is not a URL of a scheme `Bun.RedisClient` takes (`redis://`,
+`rediss://`, `valkey://`, `valkeys://`, `redis+tls://`, `redis+unix://`,
+`redis+tls+unix://`), or a `client` without `send`, `getBuffer` and
+`close`. The message never repeats the URL, which may hold a password.
+**Fix:**
+
+```ts
+RedisQueueStore.open({ url: 'rediss://bumail:secret@cache.internal:6380/0' });
+// or a client of yours, configured as you need:
+RedisQueueStore.open({ client: new Bun.RedisClient(url, { connectionTimeout: 5000 }) });
+```
+
+### `QueueError: A Redis queue store takes client or url, not both`
+
+**Code:** `INVALID`. Give one: `client` for a client you configure and
+close, `url` for one the store opens and closes.
+
+### `QueueError: keyPrefix must be lowercase letters, digits, '_', ':', '.' and '-', starting with a letter, at most 40 characters, not …`
+
+**Code:** `INVALID`.
+**Why:** the prefix starts every key the store writes. Anything Redis or
+a `SCAN MATCH` reads specially is refused: `{` (a Cluster hash tag), `*`,
+`?`, `[` and `\` (glob characters), spaces and control characters.
+**Fix:** `keyPrefix: 'mail:queue:'`. Give each queue in one Redis
+database its own prefix.
+
+### `QueueError: The URL in url cannot be opened: …`
+
+**Code:** `INVALID`.
+**When:** `RedisQueueStore.open` with a URL `Bun.RedisClient` refuses
+before connecting, such as a database that is not a number (`Invalid
+database number in Redis URL: "…"`). The URL is never repeated, and the
+password is masked should the reason name it.
+**Fix:** correct the URL: the database is the path, `/0` to `/15` on a
+default Redis.
+
+### `QueueError: The Redis queue cannot be set up: …`
+
+**Code:** `INVALID`.
+**When:** the first call on a store, which reads the layout version of
+its keys (`<prefix>schema`), writing it on a new queue. The rest of the
+message is Redis's or Bun's: `Max reconnection attempts reached` (out of
+reach), `WRONGPASS invalid username-password pair or user is disabled.`,
+`ERR DB index is out of range`, `NOPERM …` (an ACL user without
+`EVALSHA`, `EVAL` or the keys).
+**Why:** the server is out of reach, the credentials or the database are
+wrong, or the user may not run scripts. With `Bun.RedisClient`'s
+defaults an unreachable server takes about half a minute of reconnecting
+before the call fails.
+**Fix:** check the URL and that Redis answers. An ACL user needs the
+commands the store sends and those its scripts call, on the keys under
+its prefix, and nothing else (the guide's [Redis](guide.md#redis) has
+the `ACL SETUSER` line). The next call tries again.
+
+### `QueueError: The key …schema does not hold a layout version: is the prefix another application's?`
+
+**Code:** `INVALID`.
+**When:** the first call on a store whose `<prefix>schema` key holds
+something other than a whole number of at least 1.
+**Why:** the store keeps its layout version there; anything else means
+another application, or a hand, wrote under the same prefix.
+**Fix:** give the queue a `keyPrefix` of its own. Nothing was written.
 
 ## Listing
 
@@ -337,9 +585,71 @@ never gives it. Each message names what is wrong:
 - `QueueError: delayNotified must be true or false`
 - `QueueError: recipients must be an array of { address, status:
   delivered, deferred or failed }`
+- [`QueueError: A reply is an object with a text`](#queueerror-a-reply-is-an-object-with-a-text),
+  [`reply.status must be a string`](#queueerror-replystatus-must-be-a-string),
+  [`reply.host must be a string`](#queueerror-replyhost-must-be-a-string)
+- [`QueueError: … holds a NUL or a lone surrogate, which a store cannot
+  keep`](#queueerror--holds-a-nul-or-a-lone-surrogate-which-a-store-cannot-keep)
 
 A list's `offset` and `limit` are checked as under [Listing](#listing).
 
+### `QueueError: A reply is an object with a text`
+
+**Code:** `INVALID`.
+**When:** `complete` called directly with a recipient whose `reply` is
+not an object, or has no string `text`.
+**Why:** a reply is a `Diagnostic`, `{ code?, status?, text, host? }`:
+`text` is what a DSN and the events show, so every store needs it. The
+queue's own outcomes always have one.
+**Fix:** give the text, even for a reply with no code:
+
+```ts
+await store.complete(id, owner, {
+	...result,
+	recipients: [{ address, status: 'deferred', reply: { status: '4.4.1', text: 'No answer' } }],
+});
+```
+
+### `QueueError: reply.status must be a string`
+
+**Code:** `INVALID`.
+**When:** `complete` called directly with a `reply.status` that is
+neither left out nor a string — often the reply code given as a number.
+**Why:** `status` is the enhanced status code, `x.y.z` (RFC 3463), kept
+as text; the reply code goes in `code`.
+**Fix:** `reply: { code: 451, status: '4.3.0', text: 'Try later' }`, or
+leave `status` out.
+
+### `QueueError: reply.host must be a string`
+
+**Code:** `INVALID`.
+**When:** `complete` called directly with a `reply.host` that is neither
+left out nor a string, such as an address object from a socket.
+**Why:** `host` is the name or address the attempt was for, kept as text.
+**Fix:** give it as text — `host: 'mx1.example.com'` or
+`host: '192.0.2.1'` — or leave it out.
+
+### `QueueError: … holds a NUL or a lone surrogate, which a store cannot keep`
+
+**Code:** `INVALID`. The … is `from`, `A recipient`, `owner`,
+`reply.text`, `reply.status` or `reply.host`.
+**When:** `add`, `complete`, or any call that takes an `owner`, called
+directly with a text holding U+0000 or half of a surrogate pair — a string cut in the
+middle of an emoji, say. `createQueue` refuses such an `owner` the same
+way.
+**Why:** PostgreSQL cannot keep a NUL in text, and no UTF-8 encoding can
+carry a lone surrogate (`Bun.RedisClient` would write one as U+FFFD
+without a word), so every store refuses them alike — whichever
+store you give it, the same text is kept or refused. The queue's own
+replies never hold one: it cuts a reply's text only between whole
+characters.
+**Fix:** drop the NULs and cut text on whole characters before you give
+it to the store:
+
+```ts
+const clean = text.replaceAll('\0', '').toWellFormed();
+```
+
 ## Delivery
 
 ### A recipient stays `deferred` with `4.4.1` or `4.4.2`

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@bumail/queue",
-	"version": "0.1.0",
-	"description": "The outbound mail queue of a mail server: every recipient's state, retries with back-off, delivery status notifications (RFC 3464), leases for several workers, and a memory and a bun:sqlite store, delivering through @bumail/smtp/client",
+	"version": "0.3.0",
+	"description": "The outbound mail queue of a mail server: every recipient's state, retries with back-off, delivery status notifications (RFC 3464), leases for several workers, and a memory, a bun:sqlite, a PostgreSQL (Bun.sql) and a Redis (Bun.redis) store, delivering through @bumail/smtp/client",
 	"license": "MIT",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -29,6 +29,16 @@
 			"import": "./dist/sqlite/index.js",
 			"default": "./dist/sqlite/index.js"
 		},
+		"./postgres": {
+			"types": "./dist/postgres/index.d.ts",
+			"import": "./dist/postgres/index.js",
+			"default": "./dist/postgres/index.js"
+		},
+		"./redis": {
+			"types": "./dist/redis/index.d.ts",
+			"import": "./dist/redis/index.js",
+			"default": "./dist/redis/index.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"repository": {
@@ -49,7 +59,9 @@
 		"entrypoints": [
 			"src/index.ts",
 			"src/memory/index.ts",
-			"src/sqlite/index.ts"
+			"src/sqlite/index.ts",
+			"src/postgres/index.ts",
+			"src/redis/index.ts"
 		]
 	},
 	"devDependencies": {

package/dist/chunks/index-p4k4rjb7.js

@@ -1,15 +0,0 @@
-// src/errors.ts
-class QueueError2 extends Error {
-  name = "QueueError";
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-  }
-}
-var invalid = (message) => new QueueError2("INVALID", message);
-
-export { QueueError2, invalid };
-
-//# debugId=465D2E3985AB194764756E2164756E21
-//# sourceMappingURL=index-p4k4rjb7.js.map

package/dist/chunks/index-p4k4rjb7.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/errors.ts"],
-  "sourcesContent": [
-    "/**\n * Why the queue or a store refused a call. `INVALID`: an option or an\n * argument it cannot take. `MESSAGE_TOO_BIG`, `TOO_MANY_RECIPIENTS` and\n * `QUEUE_FULL`: a limit `enqueue` enforces. `CLOSED`: a store used after\n * `close()`. `LEASE_LOST`: given to the `error` event when another worker\n * took an item before its outcome was recorded.\n */\nexport type QueueErrorCode =\n\t| 'INVALID'\n\t| 'MESSAGE_TOO_BIG'\n\t| 'TOO_MANY_RECIPIENTS'\n\t| 'QUEUE_FULL'\n\t| 'CLOSED'\n\t| 'LEASE_LOST';\n\n/** Thrown by the queue and by every store, whichever answers the contract, with the same codes. */\nexport class QueueError extends Error {\n\toverride readonly name = 'QueueError';\n\treadonly code: QueueErrorCode;\n\n\tconstructor(code: QueueErrorCode, message: string) {\n\t\tsuper(message);\n\t\tthis.code = code;\n\t}\n}\n\n/** `INVALID`, for an option or an argument. */\nexport const invalid = (message: string) => new QueueError('INVALID', message);\n"
-  ],
-  "mappings": ";AAgBO,MAAM,oBAAmB,MAAM;AAAA,EACnB,OAAO;AAAA,EAChB;AAAA,EAET,WAAW,CAAC,MAAsB,SAAiB;AAAA,IAClD,MAAM,OAAO;AAAA,IACb,KAAK,OAAO;AAAA;AAEd;AAGO,IAAM,UAAU,CAAC,YAAoB,IAAI,YAAW,WAAW,OAAO;",
-  "debugId": "465D2E3985AB194764756E2164756E21",
-  "names": []
-}

package/dist/chunks/index-xhsw4xcz.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/contract/checks.ts"],
-  "sourcesContent": [
-    "import { invalid } from '../errors';\nimport type {\n\tAttemptResult,\n\tClaimRequest,\n\tNewQueueItem,\n\tQueueItem,\n\tQueueListOptions,\n\tRecipientState,\n} from './types';\n\n/** What every store checks the same way, so each refuses the same input with the same error. */\n\nconst isTime = (value: unknown): value is number =>\n\ttypeof value === 'number' && Number.isFinite(value);\n\n/** A time in milliseconds since the epoch, or `INVALID` naming it. */\nexport function checkTime(name: string, value: unknown): number {\n\tif (!isTime(value)) throw invalid(`${name} must be a finite number`);\n\treturn value;\n}\n\n/** A lease owner: a non-empty string. */\nexport function checkOwner(owner: unknown): string {\n\tif (typeof owner !== 'string' || owner === '') {\n\t\tthrow invalid('owner must be a non-empty string');\n\t}\n\treturn owner;\n}\n\nexport function checkNewItem(item: NewQueueItem): void {\n\tif (typeof item !== 'object' || item === null) {\n\t\tthrow invalid('A new item is an object');\n\t}\n\tif (typeof item.from !== 'string') throw invalid('from must be a string');\n\tconst to = item.to as unknown;\n\tif (\n\t\t!Array.isArray(to) ||\n\t\tto.length === 0 ||\n\t\t!to.every((a) => typeof a === 'string' && a !== '')\n\t) {\n\t\tthrow invalid('to must be a non-empty array of addresses');\n\t}\n\tif (!(item.message instanceof Uint8Array)) {\n\t\tthrow invalid('message must be a Uint8Array');\n\t}\n\tcheckTime('createdAt', item.createdAt);\n}\n\n/** `maxItems`: a positive integer, or nothing. */\nexport function checkMaxItems(max: unknown): number | undefined {\n\tif (max === undefined) return undefined;\n\tif (typeof max !== 'number' || !Number.isInteger(max) || max < 1) {\n\t\tthrow invalid(`maxItems must be an integer of at least 1, not ${max}`);\n\t}\n\treturn max;\n}\n\nexport function checkClaim(request: ClaimRequest): void {\n\tif (typeof request !== 'object' || request === null) {\n\t\tthrow invalid('A claim is an object');\n\t}\n\tcheckOwner(request.owner);\n\tcheckTime('now', request.now);\n\tif (!isTime(request.leaseMs) || request.leaseMs <= 0) {\n\t\tthrow invalid('leaseMs must be a positive number');\n\t}\n}\n\nexport function checkResult(result: AttemptResult): void {\n\tif (typeof result !== 'object' || result === null) {\n\t\tthrow invalid('An attempt result is an object');\n\t}\n\tcheckTime('now', result.now);\n\tcheckTime('nextAttemptAt', result.nextAttemptAt);\n\tif (!Number.isInteger(result.attempts) || result.attempts < 0) {\n\t\tthrow invalid('attempts must be an integer of at least 0');\n\t}\n\tif (typeof result.delayNotified !== 'boolean') {\n\t\tthrow invalid('delayNotified must be true or false');\n\t}\n\tconst statuses = ['delivered', 'deferred', 'failed'];\n\tif (\n\t\t!Array.isArray(result.recipients) ||\n\t\t!result.recipients.every(\n\t\t\t(u) => typeof u?.address === 'string' && statuses.includes(u.status),\n\t\t)\n\t) {\n\t\tthrow invalid(\n\t\t\t'recipients must be an array of { address, status: delivered, deferred or failed }',\n\t\t);\n\t}\n}\n\n/** The offset and limit of a list: integers, the limit 1 to 1000. */\nexport function checkList(options: QueueListOptions = {}): {\n\toffset: number;\n\tlimit: number;\n} {\n\tconst offset = options.offset ?? 0;\n\tconst limit = options.limit ?? 100;\n\tif (!Number.isInteger(offset) || offset < 0) {\n\t\tthrow invalid(`offset must be an integer of at least 0, not ${offset}`);\n\t}\n\tif (!Number.isInteger(limit) || limit < 1 || limit > 1000) {\n\t\tthrow invalid(`limit must be an integer from 1 to 1000, not ${limit}`);\n\t}\n\treturn { offset, limit };\n}\n\n/** Every recipient is `delivered` or `failed`. */\nexport const isDone = (item: Pick<QueueItem, 'recipients'>): boolean =>\n\titem.recipients.every(\n\t\t(r) => r.status === 'delivered' || r.status === 'failed',\n\t);\n\n/**\n * The item once an attempt is recorded: its recipients' outcomes, a final\n * state never changed again, the schedule, and no lease.\n */\nexport function applyAttempt(\n\titem: QueueItem,\n\tresult: AttemptResult,\n): QueueItem {\n\tconst updates = new Map(result.recipients.map((u) => [u.address, u]));\n\tconst recipients = item.recipients.map((r): RecipientState => {\n\t\tconst update = updates.get(r.address);\n\t\tif (!update || r.status === 'delivered' || r.status === 'failed') return r;\n\t\treturn {\n\t\t\taddress: r.address,\n\t\t\tstatus: update.status,\n\t\t\t...(update.reply ? { reply: update.reply } : {}),\n\t\t\tupdatedAt: result.now,\n\t\t};\n\t});\n\tconst { lease: _, ...rest } = item;\n\treturn {\n\t\t...rest,\n\t\trecipients,\n\t\tnextAttemptAt: result.nextAttemptAt,\n\t\tattempts: result.attempts,\n\t\tdelayNotified: result.delayNotified,\n\t};\n}\n\n/** A new item as a store first keeps it. */\nexport function newItem(id: string, item: NewQueueItem): QueueItem {\n\treturn {\n\t\tid,\n\t\tfrom: item.from,\n\t\trecipients: item.to.map((address) => ({ address, status: 'pending' })),\n\t\tsize: item.message.length,\n\t\tcreatedAt: item.createdAt,\n\t\tnextAttemptAt: item.createdAt,\n\t\tattempts: 0,\n\t\tdelayNotified: false,\n\t};\n}\n\n/** Whether a lease, if any, leaves the item free to claim at `now`. */\nexport const claimable = (item: QueueItem, now: number): boolean =>\n\titem.nextAttemptAt <= now &&\n\t(item.lease === undefined || item.lease.expiresAt <= now);\n"
-  ],
-  "mappings": "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",
-  "debugId": "70E823C3942B47A164756E2164756E21",
-  "names": []
-}