@krizaka/outbox 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @krizaka/outbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The transactional outbox of every Krizaka product. An event is **written in the caller's transaction**, so it exists exactly when the work committed, and is **delivered after the commit, at least once**, by workers that lease a batch. No broker: PostgreSQL and `FOR UPDATE SKIP LOCKED` share the work between instances. It replaces Akinaza's `mail_outbox` (whose `flushOutbox` nobody called), Orochia's `reco_outbox` and analytics outbox and Yasakia's `analytics_outbox`; it is the TypeScript twin of `krizaka-messaging`'s `krizaka_outbox` (the envelope is `id`, `type`, `occurredAt`, `payload`).
+
+> **The guarantee is *at least once*. Consumers must be idempotent on the message id.** A claim is exclusive while its lease is valid. A worker that delivers and then crashes before `complete` lets the lease expire, and the message is delivered **again**. The outbox never promises « exactly once ».
+
+```ts
+import { emitMigration, transaction } from "@krizaka/db";
+import { consumeOnce, createOutbox, outboxSchema, runWorker } from "@krizaka/outbox";
+import { readOutboxSettings } from "@krizaka/outbox/settings";
+
+emitMigration(outboxSchema, 1, { tables: {} }); // commit the SQL once, in your migrations: outbox.message and outbox.processed
+
+const outbox = createOutbox({ clock: { now: () => new Date() }, settings: () => readOutboxSettings((key) => settings.get(key)) });
+
+// 1. in the use case: the message commits or rolls back with the work
+await transaction(connect, async (tx) => {
+  const redemption = await coupons.redeem(tx, { code, accountId });
+  await outbox.append(tx, { topic: "credits", type: "evt.coupon.redeemed.v1", payload: { redemptionId: redemption.id }, id: redemption.eventId });
+});
+
+// 2. a worker the product starts (Next.js instrumentation.ts); the package has no timer, you pass `sleep`
+const stop = new AbortController();
+void runWorker({
+  outbox, query: pool.query.bind(pool) /* a pool-level Query */, owner: `${hostname}:${process.pid}`, topic: "credits", signal: stop.signal,
+  sleep: (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000)),
+  deliver: async (message) => { /* throw to retry */ },
+});
+
+// 3. a consumer with an effect in the database applies it once per message id, in the effect's transaction
+await transaction(connect, (tx) => consumeOnce(tx, "credits", message.id, clock.now(), () => credits.grant(tx, …)));
+```
+
+- **`append(tx, { topic, type, payload, id?, availableAt? })`** takes the transaction's `Query` first. A given `id` makes the append idempotent (the same fact twice is one message). `type` is a routing key, `evt.<module>.<fact>.v1` like Java's.
+- **`claim(query, { owner, topic? })`** is `UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED)` and sets the lease. **`complete`** and **`fail(error)`** act only for the lease's owner (a worker that lost its lease cannot overwrite the new holder). `fail` backs off — `availableAt = now + backoffSeconds × 2^(attempts−1)`, capped — and after `maxAttempts` the message is **dead** (kept, with its last error; `retryDead` gives it another life). A message whose *last* allowed attempt's lease expired with no answer is dead too, not delivered a ninth time.
+- **`runWorker`** loops `drainOnce` (claim a batch, deliver in order, record each outcome), sleeps through the `sleep` you pass when a round found nothing, and ends when the signal is aborted. Run `drainOnce` from a scheduler instead if you prefer cron to a loop.
+- **Settings** (`@krizaka/outbox/settings`, needs `@krizaka/settings` and `zod`): `outbox.batchSize` (50, 1–500), `outbox.leaseSeconds` (60, 10–3600: longer than your slowest delivery), `outbox.maxAttempts` (8, 1–50), `outbox.backoffSeconds` (30, 1–3600), `outbox.backoffMaxSeconds` (3600), `outbox.retentionDays` (7). `purge` removes delivered and dead messages older than the retention: call it from the product's job.
+- **Tables** (`outboxSchema`, Postgres schema `outbox`): `message` (id, topic, event_type, payload, created_at, available_at, attempts, leased_until, lease_owner, delivered_at, dead_at, last_error) and `processed` (consumer, message_id), which `consumeOnce` uses: the marker and the effect commit in the same transaction, so a crash leaves neither and a redelivery finds the marker.
+- `outboxStoreContract` (from `@krizaka/outbox/testkit`) is the contract every store runs; `memoryOutboxStore()` is for unit tests.

package/dist/chunk-7WIJNAGK.js

@@ -0,0 +1,24 @@
+// src/port.ts
+var FAIL_STATE = { retry: "retry", dead: "dead", lost: "lost" };
+var OUTBOX_CODE = {
+  badTopic: "OUTBOX_BAD_TOPIC",
+  badType: "OUTBOX_BAD_TYPE",
+  badId: "OUTBOX_BAD_ID",
+  badPayload: "OUTBOX_BAD_PAYLOAD",
+  badSettings: "OUTBOX_BAD_SETTINGS"
+};
+var OutboxError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "OutboxError";
+  }
+  code;
+};
+
+export {
+  FAIL_STATE,
+  OUTBOX_CODE,
+  OutboxError
+};
+//# sourceMappingURL=chunk-7WIJNAGK.js.map

package/dist/chunk-7WIJNAGK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/port.ts"],"sourcesContent":["/**\n * The ports of « outbox »: a message written in the caller's transaction and delivered after the commit, AT LEAST ONCE. Generic:\n * no broker, no product import, no database client (a `Query` comes in), no wall clock (a `Clock` comes in).\n *\n * THE GUARANTEE. A claim is exclusive while its lease is valid. A worker that delivers and then crashes before `complete` lets the\n * lease expire, and the message is delivered AGAIN. So every consumer must be idempotent on the message id (see `consumeOnce`).\n * The outbox never promises « exactly once ».\n */\nexport type { Clock, Query } from \"@krizaka/db\";\n\n/** What a product appends. */\nexport interface NewMessage {\n  /** Where it goes: a worker claims one topic (`mail`, `recommender`, `webhooks`). Lower-case letters, digits, `_ . : -`. */\n  topic: string;\n  /** What happened, as a routing key (`evt.credit.granted.v1`): the Java kit's form. Lower-case letters, digits, `_ . -`. */\n  type: string;\n  /** The event's data: JSON. Never a secret, and as little personal data as the consumer needs. */\n  payload: unknown;\n  /** A stable id (a UUID) when the same fact can be appended twice: the second append is a no-op. Default: a fresh UUID. */\n  id?: string;\n  /** Not before this instant (a scheduled delivery). Default: now. */\n  availableAt?: Date;\n}\n\n/** The envelope a worker receives: the Java kit's `id`, `type`, `occurredAt`, `payload`, and where it is in its attempts. */\nexport interface OutboxMessage {\n  id: string;\n  topic: string;\n  type: string;\n  payload: unknown;\n  occurredAt: Date;\n  /** How many deliveries have been started for it, this one included. */\n  attempts: number;\n}\n\n/** The knobs of the outbox, read from the admin's settings (`@krizaka/outbox/settings`). */\nexport interface OutboxSettings {\n  /** Messages a worker claims at once. */\n  batchSize: number;\n  /** Seconds a claim holds a message before another worker may take it. Longer than the slowest delivery. */\n  leaseSeconds: number;\n  /** Deliveries started before a message is dead. */\n  maxAttempts: number;\n  /** Seconds before the second attempt; it doubles with each attempt. */\n  backoffSeconds: number;\n  /** The most seconds a retry waits. */\n  backoffMaxSeconds: number;\n  /** Days a delivered or dead message is kept before `purge`. */\n  retentionDays: number;\n}\n\n/** What `claim` takes. */\nexport interface ClaimOptions {\n  /** Only this topic; default every topic. */\n  topic?: string;\n  /** Who claims: a worker's id, so that only the holder of a lease can complete or fail the message. */\n  owner: string;\n}\n\n/** What became of a failed delivery. */\nexport const FAIL_STATE = { retry: \"retry\", dead: \"dead\", lost: \"lost\" } as const;\n\n/** The result of `fail`: the message will be retried, is dead, or was not this worker's any more. */\nexport type FailOutcome = { state: typeof FAIL_STATE.retry; availableAt: Date } | { state: typeof FAIL_STATE.dead } | { state: typeof FAIL_STATE.lost };\n\nexport interface OutboxStats {\n  /** Waiting for a worker (including retries). */\n  pending: number;\n  /** Held by a worker right now. */\n  leased: number;\n  delivered: number;\n  dead: number;\n}\n\n/** Where the messages live. Every adapter runs `outboxStoreContract` (`@krizaka/outbox/testkit`). Times come from the caller. */\nexport interface OutboxStore {\n  /** Writes the message. A second append of the same id writes nothing and answers `false`. */\n  append(message: { id: string; topic: string; type: string; payload: unknown; createdAt: Date; availableAt: Date }): Promise<boolean>;\n  /** First marks dead the messages whose last attempt's lease expired with no answer, then leases up to `limit` due messages. */\n  claim(options: ClaimOptions & { limit: number; leaseSeconds: number; maxAttempts: number; now: Date }): Promise<OutboxMessage[]>;\n  /** Marks it delivered, when `owner` still holds it. `false` when the lease was lost: the other worker delivers. */\n  complete(id: string, owner: string, now: Date): Promise<boolean>;\n  /** Records the failure: back off, or dead after `maxAttempts`. */\n  fail(id: string, owner: string, error: string, options: { now: Date; maxAttempts: number; backoffSeconds: number; backoffMaxSeconds: number }): Promise<FailOutcome>;\n  /** Gives a dead message another life: no attempts, due now. `false` when it is not dead. */\n  retryDead(id: string, now: Date): Promise<boolean>;\n  /** Removes the delivered and dead messages older than `before`. Returns how many. */\n  purgeBefore(before: Date): Promise<number>;\n  stats(now: Date): Promise<OutboxStats>;\n}\n\nexport const OUTBOX_CODE = {\n  badTopic: \"OUTBOX_BAD_TOPIC\",\n  badType: \"OUTBOX_BAD_TYPE\",\n  badId: \"OUTBOX_BAD_ID\",\n  badPayload: \"OUTBOX_BAD_PAYLOAD\",\n  badSettings: \"OUTBOX_BAD_SETTINGS\",\n} as const;\nexport type OutboxCode = (typeof OUTBOX_CODE)[keyof typeof OUTBOX_CODE];\n\nexport class OutboxError extends Error {\n  constructor(\n    readonly code: OutboxCode,\n    message: string,\n  ) {\n    super(message);\n    this.name = \"OutboxError\";\n  }\n}\n"],"mappings":";AA4DO,IAAM,aAAa,EAAE,OAAO,SAAS,MAAM,QAAQ,MAAM,OAAO;AA+BhE,IAAM,cAAc;AAAA,EACzB,UAAU;AAAA,EACV,SAAS;AAAA,EACT,OAAO;AAAA,EACP,YAAY;AAAA,EACZ,aAAa;AACf;AAGO,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YACW,MACT,SACA;AACA,UAAM,OAAO;AAHJ;AAIT,SAAK,OAAO;AAAA,EACd;AAAA,EALW;AAMb;","names":[]}

package/dist/chunk-AD76AB44.js

@@ -0,0 +1,44 @@
+import {
+  OUTBOX_CODE,
+  OutboxError
+} from "./chunk-7WIJNAGK.js";
+
+// src/rules.ts
+var OUTBOX_DEFAULTS = { batchSize: 50, leaseSeconds: 60, maxAttempts: 8, backoffSeconds: 30, backoffMaxSeconds: 3600, retentionDays: 7 };
+var OUTBOX_BOUNDS = {
+  batchSize: [1, 500],
+  leaseSeconds: [10, 3600],
+  maxAttempts: [1, 50],
+  backoffSeconds: [1, 3600],
+  backoffMaxSeconds: [1, 86400],
+  retentionDays: [1, 365]
+};
+var TOPIC = /^[a-z][a-z0-9_.:-]{0,59}$/;
+var TYPE = /^[a-z][a-z0-9_.-]{0,99}$/;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function checkMessage(input) {
+  if (!TOPIC.test(input.topic)) throw new OutboxError(OUTBOX_CODE.badTopic, `topic \xAB ${input.topic} \xBB: lower-case letters, digits and _ . : -, starting with a letter, at most 60 characters`);
+  if (!TYPE.test(input.type)) throw new OutboxError(OUTBOX_CODE.badType, `type \xAB ${input.type} \xBB: lower-case letters, digits and _ . -, starting with a letter, at most 100 characters (evt.credit.granted.v1)`);
+  if (input.id !== void 0 && !UUID.test(input.id)) throw new OutboxError(OUTBOX_CODE.badId, `id \xAB ${input.id} \xBB is not a UUID`);
+  if (input.payload === void 0 || JSON.stringify(input.payload) === void 0) throw new OutboxError(OUTBOX_CODE.badPayload, "the payload must be JSON-serialisable (and not undefined)");
+}
+function checkSettings(settings) {
+  for (const key of Object.keys(OUTBOX_BOUNDS)) {
+    const [min, max] = OUTBOX_BOUNDS[key];
+    const value = settings[key];
+    if (!Number.isInteger(value) || value < min || value > max) throw new OutboxError(OUTBOX_CODE.badSettings, `outbox.${key} must be a whole number from ${min} to ${max}, got ${value}`);
+  }
+  return settings;
+}
+function backoffSeconds(attempts, settings) {
+  return Math.min(settings.backoffMaxSeconds, settings.backoffSeconds * 2 ** Math.max(0, attempts - 1));
+}
+
+export {
+  OUTBOX_DEFAULTS,
+  OUTBOX_BOUNDS,
+  checkMessage,
+  checkSettings,
+  backoffSeconds
+};
+//# sourceMappingURL=chunk-AD76AB44.js.map

package/dist/chunk-AD76AB44.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/rules.ts"],"sourcesContent":["import { OUTBOX_CODE, OutboxError, type OutboxSettings } from \"./port\";\n\n/**\n * The defaults of the settings, and their bounds. The settings fragment (`@krizaka/outbox/settings`) is built from these, so the\n * admin sees the same numbers the code falls back to.\n */\n// @fixed: the defaults and bounds of the admin's knobs; the admin chooses within them\nexport const OUTBOX_DEFAULTS: OutboxSettings = { batchSize: 50, leaseSeconds: 60, maxAttempts: 8, backoffSeconds: 30, backoffMaxSeconds: 3600, retentionDays: 7 };\n\n/** The bounds of each setting: [min, max]. */\n// @fixed: what an admin may set\nexport const OUTBOX_BOUNDS: Readonly<Record<keyof OutboxSettings, readonly [number, number]>> = {\n  batchSize: [1, 500],\n  leaseSeconds: [10, 3600],\n  maxAttempts: [1, 50],\n  backoffSeconds: [1, 3600],\n  backoffMaxSeconds: [1, 86_400],\n  retentionDays: [1, 365],\n};\n\nconst TOPIC = /^[a-z][a-z0-9_.:-]{0,59}$/;\nconst TYPE = /^[a-z][a-z0-9_.-]{0,99}$/;\nconst UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;\n\n/** @throws OutboxError for a topic, a type or an id that is not well formed, or a payload that is not JSON */\nexport function checkMessage(input: { topic: string; type: string; id?: string; payload: unknown }): void {\n  if (!TOPIC.test(input.topic)) throw new OutboxError(OUTBOX_CODE.badTopic, `topic « ${input.topic} »: lower-case letters, digits and _ . : -, starting with a letter, at most 60 characters`);\n  if (!TYPE.test(input.type)) throw new OutboxError(OUTBOX_CODE.badType, `type « ${input.type} »: lower-case letters, digits and _ . -, starting with a letter, at most 100 characters (evt.credit.granted.v1)`);\n  if (input.id !== undefined && !UUID.test(input.id)) throw new OutboxError(OUTBOX_CODE.badId, `id « ${input.id} » is not a UUID`);\n  if (input.payload === undefined || JSON.stringify(input.payload) === undefined) throw new OutboxError(OUTBOX_CODE.badPayload, \"the payload must be JSON-serialisable (and not undefined)\");\n}\n\n/** @throws OutboxError when a setting is not a whole number within its bounds */\nexport function checkSettings(settings: OutboxSettings): OutboxSettings {\n  for (const key of Object.keys(OUTBOX_BOUNDS) as (keyof OutboxSettings)[]) {\n    const [min, max] = OUTBOX_BOUNDS[key];\n    const value = settings[key];\n    if (!Number.isInteger(value) || value < min || value > max) throw new OutboxError(OUTBOX_CODE.badSettings, `outbox.${key} must be a whole number from ${min} to ${max}, got ${value}`);\n  }\n  return settings;\n}\n\n/**\n * The seconds a message waits after its `attempts`-th delivery failed: the base for the first, doubling with each, capped.\n * @param attempts deliveries started so far (1 for the first failure)\n */\nexport function backoffSeconds(attempts: number, settings: Pick<OutboxSettings, \"backoffSeconds\" | \"backoffMaxSeconds\">): number {\n  return Math.min(settings.backoffMaxSeconds, settings.backoffSeconds * 2 ** Math.max(0, attempts - 1));\n}\n"],"mappings":";;;;;;AAOO,IAAM,kBAAkC,EAAE,WAAW,IAAI,cAAc,IAAI,aAAa,GAAG,gBAAgB,IAAI,mBAAmB,MAAM,eAAe,EAAE;AAIzJ,IAAM,gBAAmF;AAAA,EAC9F,WAAW,CAAC,GAAG,GAAG;AAAA,EAClB,cAAc,CAAC,IAAI,IAAI;AAAA,EACvB,aAAa,CAAC,GAAG,EAAE;AAAA,EACnB,gBAAgB,CAAC,GAAG,IAAI;AAAA,EACxB,mBAAmB,CAAC,GAAG,KAAM;AAAA,EAC7B,eAAe,CAAC,GAAG,GAAG;AACxB;AAEA,IAAM,QAAQ;AACd,IAAM,OAAO;AACb,IAAM,OAAO;AAGN,SAAS,aAAa,OAA6E;AACxG,MAAI,CAAC,MAAM,KAAK,MAAM,KAAK,EAAG,OAAM,IAAI,YAAY,YAAY,UAAU,cAAW,MAAM,KAAK,8FAA2F;AAC3L,MAAI,CAAC,KAAK,KAAK,MAAM,IAAI,EAAG,OAAM,IAAI,YAAY,YAAY,SAAS,aAAU,MAAM,IAAI,qHAAkH;AAC7M,MAAI,MAAM,OAAO,UAAa,CAAC,KAAK,KAAK,MAAM,EAAE,EAAG,OAAM,IAAI,YAAY,YAAY,OAAO,WAAQ,MAAM,EAAE,qBAAkB;AAC/H,MAAI,MAAM,YAAY,UAAa,KAAK,UAAU,MAAM,OAAO,MAAM,OAAW,OAAM,IAAI,YAAY,YAAY,YAAY,2DAA2D;AAC3L;AAGO,SAAS,cAAc,UAA0C;AACtE,aAAW,OAAO,OAAO,KAAK,aAAa,GAA+B;AACxE,UAAM,CAAC,KAAK,GAAG,IAAI,cAAc,GAAG;AACpC,UAAM,QAAQ,SAAS,GAAG;AAC1B,QAAI,CAAC,OAAO,UAAU,KAAK,KAAK,QAAQ,OAAO,QAAQ,IAAK,OAAM,IAAI,YAAY,YAAY,aAAa,UAAU,GAAG,gCAAgC,GAAG,OAAO,GAAG,SAAS,KAAK,EAAE;AAAA,EACvL;AACA,SAAO;AACT;AAMO,SAAS,eAAe,UAAkB,UAAgF;AAC/H,SAAO,KAAK,IAAI,SAAS,mBAAmB,SAAS,iBAAiB,KAAK,KAAK,IAAI,GAAG,WAAW,CAAC,CAAC;AACtG;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+import * as _krizaka_db from '@krizaka/db';
+import { Query, Clock } from '@krizaka/db';
+export { Clock, Query } from '@krizaka/db';
+import { O as OutboxStore, N as NewMessage, C as ClaimOptions, a as OutboxMessage, F as FailOutcome, b as OutboxStats, c as OutboxSettings } from './port-CXch5iMa.js';
+export { d as FAIL_STATE, e as OUTBOX_CODE, f as OutboxCode, g as OutboxError } from './port-CXch5iMa.js';
+
+/**
+ * The idempotent consumer: the outbox delivers AT LEAST ONCE, so a consumer that has an effect in the database applies it once per
+ * message id. Run it inside the transaction of the effect: the marker and the effect commit together, so a crash between them
+ * leaves neither and the redelivery applies both; a redelivery after the commit finds the marker and does nothing.
+ *
+ * ```ts
+ * await db.transaction(async (tx) => {
+ *   const result = await consumeOnce(tx, "credits", message.id, clock.now(), () => credits.grant(tx, …));
+ * });
+ * ```
+ * @param tx the transaction the effect writes through
+ * @param consumer who applies it (`credits`, `mail`): a message may be consumed once by each consumer
+ * @param messageId the outbox message's id
+ * @param effect what to do the first time; its failure rolls the marker back with the transaction
+ * @param schema the Postgres schema of the module, default `outbox`
+ * @returns `applied` the first time, `duplicate` after
+ */
+declare function consumeOnce(tx: Query, consumer: string, messageId: string, now: Date, effect: () => Promise<void>, schema?: string): Promise<"applied" | "duplicate">;
+
+interface Row {
+    id: string;
+    topic: string;
+    type: string;
+    payload: unknown;
+    createdAt: Date;
+    availableAt: Date;
+    attempts: number;
+    leasedUntil: Date | null;
+    leaseOwner: string | null;
+    deliveredAt: Date | null;
+    deadAt: Date | null;
+    lastError: string | null;
+}
+/** An in-memory outbox store, for unit tests and demos (the same behaviour as the database's: the contract kit runs on both). */
+declare function memoryOutboxStore(): OutboxStore & {
+    rows(): readonly Readonly<Row>[];
+};
+
+interface OutboxDeps {
+    clock: Clock;
+    /** The settings, read at each call so the admin's change applies at once: an object, or a function over the settings service. */
+    settings: OutboxSettings | (() => OutboxSettings | Promise<OutboxSettings>);
+    /** The store over a query (a pool or a transaction). Default: the PostgreSQL store on schema `outbox`. */
+    storeFor?: (query: Query) => OutboxStore;
+    /** The Postgres schema, when the product renamed the module's (used by the default store). */
+    schema?: string;
+}
+/** The outbox as a product uses it. Every function takes the `Query` it works through: pass `tx` to join a unit of work. */
+interface Outbox {
+    /** Appends a message INSIDE the caller's transaction: it commits or rolls back with it. Answers its id, and `false` when that id was already appended. */
+    append(tx: Query, message: NewMessage): Promise<{
+        id: string;
+        appended: boolean;
+    }>;
+    /** Leases a batch of due messages to `owner`. Exclusive while each lease is valid. */
+    claim(query: Query, options: ClaimOptions & {
+        limit?: number;
+        leaseSeconds?: number;
+    }): Promise<OutboxMessage[]>;
+    /** The delivery succeeded. `false` when the lease was lost to another worker. */
+    complete(query: Query, id: string, owner: string): Promise<boolean>;
+    /** The delivery failed: back off (doubling, capped), or dead after `maxAttempts`. */
+    fail(query: Query, id: string, owner: string, error: unknown): Promise<FailOutcome>;
+    /** A dead message gets another life, due now. */
+    retryDead(query: Query, id: string): Promise<boolean>;
+    /** Removes delivered and dead messages older than the retention. Returns how many. */
+    purge(query: Query): Promise<number>;
+    stats(query: Query): Promise<OutboxStats>;
+}
+/**
+ * The outbox of a product.
+ * @param deps the clock, the settings, and optionally the store and schema
+ * @returns the outbox's functions
+ */
+declare function createOutbox(deps: OutboxDeps): Outbox;
+
+/**
+ * The PostgreSQL store of the outbox, in `outbox.message` (see `outboxSchema`), over the `Query` it is given: the caller's
+ * transaction for `append` (so the message commits or rolls back with the work), a pool for the worker's calls.
+ *
+ * `claim` is `UPDATE … WHERE id IN (SELECT … FOR UPDATE SKIP LOCKED)`: two workers never lease the same message while a lease is
+ * valid. `complete` and `fail` only act for the lease's owner, so a worker that lost its lease cannot overwrite the new holder's outcome.
+ * Times come from the caller (the injected clock), never from the database's `now()`.
+ * @param schema the Postgres schema of the module, default `outbox`
+ */
+declare function dbOutboxStore(query: Query, schema?: string): OutboxStore;
+
+/**
+ * The defaults of the settings, and their bounds. The settings fragment (`@krizaka/outbox/settings`) is built from these, so the
+ * admin sees the same numbers the code falls back to.
+ */
+declare const OUTBOX_DEFAULTS: OutboxSettings;
+/** The bounds of each setting: [min, max]. */
+declare const OUTBOX_BOUNDS: Readonly<Record<keyof OutboxSettings, readonly [number, number]>>;
+/** @throws OutboxError for a topic, a type or an id that is not well formed, or a payload that is not JSON */
+declare function checkMessage(input: {
+    topic: string;
+    type: string;
+    id?: string;
+    payload: unknown;
+}): void;
+/** @throws OutboxError when a setting is not a whole number within its bounds */
+declare function checkSettings(settings: OutboxSettings): OutboxSettings;
+/**
+ * The seconds a message waits after its `attempts`-th delivery failed: the base for the first, doubling with each, capped.
+ * @param attempts deliveries started so far (1 for the first failure)
+ */
+declare function backoffSeconds(attempts: number, settings: Pick<OutboxSettings, "backoffSeconds" | "backoffMaxSeconds">): number;
+
+/**
+ * The tables of « outbox », in their own Postgres schema (ADR-001 §3). `message` is the outbox itself, the columns of the Java kit's
+ * envelope (id, type, occurredAt = created_at, payload) and the state of its delivery; `processed` is the idempotent consumers'
+ * record of the message ids they already applied. They reference no product table. Version 1 is frozen once released: a change is version 2.
+ */
+declare const outboxSchema: _krizaka_db.ModuleSchema;
+
+interface DrainSummary {
+    claimed: number;
+    delivered: number;
+    retried: number;
+    dead: number;
+    /** Deliveries whose outcome could not be recorded because the lease had been lost to another worker. */
+    lost: number;
+}
+interface DrainOptions {
+    outbox: Outbox;
+    /** A pool-level query: each call is its own statement, never one long transaction, so a lease is all that holds a message. */
+    query: Query;
+    /** Who this worker is (a hostname and a process id): only the holder of a lease can complete or fail its message. */
+    owner: string;
+    /** Delivers one message: resolve on success, throw on failure. It must be idempotent on `message.id` (at-least-once). */
+    deliver: (message: OutboxMessage) => Promise<void>;
+    /** Only this topic; default every topic. */
+    topic?: string;
+}
+/**
+ * One round: leases a batch, delivers each message in order, records each outcome. Safe to run from several instances at once.
+ * A delivery that throws is retried later (or is dead after `maxAttempts`); the round goes on with the next message.
+ * @returns what happened
+ */
+declare function drainOnce(options: DrainOptions): Promise<DrainSummary>;
+interface WorkerOptions extends DrainOptions {
+    /** Waits this many seconds (a timer: the package has none of its own). */
+    sleep: (seconds: number) => Promise<void>;
+    /** The worker stops when this signal is aborted (checked between rounds). */
+    signal?: AbortSignal;
+    /** Seconds to wait when a round found nothing. Default 5. */
+    idleSeconds?: number;
+    /** Told of a round that threw (the store was unreachable): the loop waits and goes on. */
+    onError?: (error: unknown) => void;
+}
+/**
+ * The loop a product starts (Next.js `instrumentation.ts`, a worker process): drain, and sleep when there was nothing. It has no
+ * timer of its own — the product passes `sleep` — and it ends when the signal is aborted.
+ */
+declare function runWorker(options: WorkerOptions): Promise<void>;
+
+export { ClaimOptions, type DrainOptions, type DrainSummary, FailOutcome, NewMessage, OUTBOX_BOUNDS, OUTBOX_DEFAULTS, type Outbox, type OutboxDeps, OutboxMessage, OutboxSettings, OutboxStats, OutboxStore, type WorkerOptions, backoffSeconds, checkMessage, checkSettings, consumeOnce, createOutbox, dbOutboxStore, drainOnce, memoryOutboxStore, outboxSchema, runWorker };