@elysiumjs/moirai 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# @elysiumjs/moirai
+
+## 0.1.0
+
+### Minor Changes
+
+- [#19](https://github.com/na2axl/elysiumjs/pull/19) [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562) Thanks [@na2axl](https://github.com/na2axl)! - Domain errors as classes with a code, returned as values.
+
+  - `DomainError` is an Elysia `HTTPError`. Each error is a class made with `DomainError.for(code, status)`, which keeps its code and status as literal types, with `errors`, `retryAfterSeconds` (served as `retryAfter` and the Retry-After header) and extensions.
+  - Ready-made errors: `BadRequestError`, `ValidationFailedError`, `UnauthenticatedError`, `ForbiddenError`, `NotFoundError` and `ConflictError`.
+  - `ProblemCatalogue`, extended through declaration merging, lists the codes of an application; once it has keys, `DomainError.for()` takes only those and `ELYSIUM_PROBLEM_CODES`.
+  - Every problem carries `code`, `requestId` (from `problems.requestId`, a valid `x-request-id` header, or a random UUID) and `instance`. Its `type` is the kebab-case slug of the code, under `problems.typeBase`.
+  - Errors as values: a handler, a flow step, `UnitOfWork.run()` or a `@Transactional()` method that returns a DomainError rolls back and sends or returns it like a thrown one. `Commands.execute()` and `Queries.ask()` return the DomainError that refused the call, and a returned error joins the route's response type for typed clients.
+
+- [#21](https://github.com/na2axl/elysiumjs/pull/21) [`0035580`](https://github.com/na2axl/elysiumjs/commit/00355809c338a68e39d67335fb820ee098f36f89) Thanks [@na2axl](https://github.com/na2axl)! - Writes are actions and reads are queries. An action extends `Action` and is marked with `@Action.register()`; a query extends `Query` and is marked with `@Query.register()`. `Moirai.execute()` runs an action and `Moirai.ask()` runs a query, and their outcomes are `ActionOutcome` and `QueryOutcome`. Outbox handlers are marked with `@Outbox.handle(kind)`.
+
+  The options, retry policy and lock are `ActionOptions`, `ActionRetry`, `ActionLock` (`MemoryActionLock`, `MOIRAI_ACTION_LOCK`), and a refused `authorize` is a `CallForbiddenError`. Idempotency records name their `action`, and the `idempotency_keys` table of `moiraiTables()` has an `action` column.
+
+- [#23](https://github.com/na2axl/elysiumjs/pull/23) [`a680a17`](https://github.com/na2axl/elysiumjs/commit/a680a177e2d82a6e85d04a9491ffc8fc05fb0010) Thanks [@na2axl](https://github.com/na2axl)! - Domain events. `Event.publish(event, payload)` publishes an event in the open unit of work, and each `@Event.on(event, { consumer, retry })` handler gets it once that unit commits: through its own outbox row, so that it retries and dies on its own, and once, through an inbox record named by its consumer. `EventCatalogue` types the names and payloads, and `EventMeta` gives handlers the id, name, publication date and attempt.
+
+  `registerEffect()` takes the attempts of a row, and the memory outbox and inbox stores drop what a unit of work that rolls back wrote.
+
+- [#24](https://github.com/na2axl/elysiumjs/pull/24) [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4) Thanks [@na2axl](https://github.com/na2axl)! - Module stores: `Moirai.stores({ outbox, inbox, ... })` lists stores and options as private services of a module, such as the outbox and inbox tables of a domain. The actions and event handlers of the module, and the code that runs in it, use them instead of the ones of `MoiraiModule`; what a module leaves out comes from `MoiraiModule`. An action runs in the module that registers it, an `@Event.on` handler records its events in the inbox of its module, a `@Once()` job in the inbox of the module that registers the job, and the relay after a commit relays the outbox the rows went to. `Outbox.relay({ module })` and `Outbox.sweep({ module })` relay the outbox of one module; `Outbox.sweep()` relays the outbox of `MoiraiModule` and of every module with its own.
+
+  Breaking: an invalid action or query input is a 422 `VALIDATION_FAILED` problem (was 400), and a missing idempotency key is a 400 `IDEMPOTENCY_KEY_REQUIRED` problem (was 428).
+
+- [#20](https://github.com/na2axl/elysiumjs/pull/20) [`1738567`](https://github.com/na2axl/elysiumjs/commit/17385674c14991f0ddb27eb6ee967afbcebcc307) Thanks [@na2axl](https://github.com/na2axl)! - Scheduled fan-out, dead letters and one consumer per queue.
+
+  - `@Scheduler.job(cron, { args })` dispatches a job on a cron with fixed arguments.
+  - A class that extends `Scheduler` and is marked with `@Scheduler.register({ cron, job })` dispatches one job per case its `fanOut(tick)` returns, with arguments typed against the job and a dispatch id made of the scheduler, the case key and the tick. Schedulers are services, so they inject what they read.
+  - `ScheduleRunner` runs the schedules on Bun and Node.js (the `heracles:schedule` command), and `Scheduler.jobsFor()` / `Scheduler.dispatch()` serve the cron triggers of Workers.
+  - `@Once()` of `@elysiumjs/moirai/heracles` runs a job once per dispatch id, in a unit of work with an inbox record.
+  - `HeraclesWorkersModule.with({ deadLetterQueue, onDead })` keeps the jobs that failed their last retry: sent to a dead letter queue with their failure, and handed to a hook.
+  - Cron triggers dispatch at the trigger's time.
+  - A named queue of a Worker has one consumer: two throw `DuplicateQueueConsumerError` when the Worker is created.
+
+- [#17](https://github.com/na2axl/elysiumjs/pull/17) [`03e062d`](https://github.com/na2axl/elysiumjs/commit/03e062d9f5d8ec761c63f05574ce96a1084fe3ea) Thanks [@na2axl](https://github.com/na2axl)! - Commands, outbox, authentication and multi-step flows, on Bun, Node.js and Cloudflare Workers.
+
+  Added:
+
+  - `@elysiumjs/moirai`: commands and queries declared with `@Moirai.command()` and `@Moirai.query()`, run with `Commands.execute` and `Queries.ask`. Inputs are validated (400 problem), `authorize` refuses with a 403 problem, commands run in a unit of work and retry transient failures, idempotent commands replay their response for a repeated key (428 without a key, 422 for a key reused with another input), and `serializeBy` runs calls with the same key one after the other. `Outbox.enqueue` writes effects that relay once the unit of work commits, to `@Moirai.effect()` handlers, with a backoff and dead rows; `Outbox.sweep` relays what is due; `Inbox.once` processes a message once per consumer. `@elysiumjs/moirai/heracles` adds `job()`, an effect that dispatches a Heracles job. Memory stores for tests.
+  - `@elysiumjs/moirai-drizzle`: Postgres stores for moirai through Drizzle ORM: `moiraiTables(schema?)`, `DrizzleIdempotencyStore`, `DrizzleOutboxStore` (claims with `FOR UPDATE SKIP LOCKED`), `DrizzleInboxStore` and `PgAdvisoryLock`.
+  - `@elysiumjs/themis`: password hashing (argon2id on Bun, PBKDF2 everywhere, scrypt on `@elysiumjs/themis/scrypt`), JWT through jose, API keys, signed URLs, sessions (memory, Redis, Workers KV, or an encrypted cookie), `@Auth()` with session, JWT and API key guards (401 problem), picked by name through `AuthMiddleware.guards()` of core middleware, CSRF protection, TOTP and backup codes, OAuth 2.0 and OpenID Connect clients with PKCE through oauth4webapi, and passkeys through SimpleWebAuthn.
+  - `@elysiumjs/ariadne`: multi-step flows as controllers: `@Flow.controller()` adds the start and state routes, each `@Flow.step()` method is a route that takes the `@Http.*()` parameter decorators, and `@Flow.state()` / `@Flow.context()` inject the flow. Replay of a repeated step id, refused steps that keep their state, back steps, guest and user owners, a flow that ends when `next` gives no step, and a memory store set by `AriadneModule.with({ store })`.
+  - `@elysiumjs/ariadne-redis`: `RedisFlowStore`, whose claims and commits are atomic Lua scripts run with `EVAL`, which Upstash runs too.
+  - `@elysiumjs/ariadne-workers`: `FlowStoreObject`, a Durable Object flow store, and `durableFlowStore(binding)`.
+
+### Patch Changes
+
+- Updated dependencies [[`6bc48fe`](https://github.com/na2axl/elysiumjs/commit/6bc48febd51f7090c582e73f349eaeff7261241c), [`e9c3d98`](https://github.com/na2axl/elysiumjs/commit/e9c3d98dd2714b69100215f7c8a80046da463148), [`557a3ca`](https://github.com/na2axl/elysiumjs/commit/557a3cab7af8053a8bab9944e492e5022d91aa82), [`ccc3f5b`](https://github.com/na2axl/elysiumjs/commit/ccc3f5bb904d1bf52d8c72ebf7ea8d10f617a8c4), [`6789879`](https://github.com/na2axl/elysiumjs/commit/678987976ecfd46b534b65276e0de3f448977562), [`87299fd`](https://github.com/na2axl/elysiumjs/commit/87299fd9da82d1a408ced1891c0c3d42991444e5), [`bee66bd`](https://github.com/na2axl/elysiumjs/commit/bee66bdc874b8f23fea356f7d3adf7555a48ca64), [`0057b67`](https://github.com/na2axl/elysiumjs/commit/0057b67df0e3abecab8a9accff6b55a6a64c21df), [`1738567`](https://github.com/na2axl/elysiumjs/commit/17385674c14991f0ddb27eb6ee967afbcebcc307), [`632d77b`](https://github.com/na2axl/elysiumjs/commit/632d77b561fc43ade605fb69b06ac1b9b9a2ffc4), [`1ea417e`](https://github.com/na2axl/elysiumjs/commit/1ea417e3583250bc2f975d795f398b7ff736115d), [`0956186`](https://github.com/na2axl/elysiumjs/commit/0956186db0ca5a83c0a6636aeb2a4c81a0033de4), [`fbcc7da`](https://github.com/na2axl/elysiumjs/commit/fbcc7dad127db29da42e7a4a5c2124966731cd88), [`ac96e55`](https://github.com/na2axl/elysiumjs/commit/ac96e55874b0ffe350b287c4278cd85afecb7576), [`98a16aa`](https://github.com/na2axl/elysiumjs/commit/98a16aae889d46f7a9fb5573188f4cbe3629dd3b)]:
+  - @elysiumjs/core@0.11.0
+  - @elysiumjs/mnemosyne@0.4.0
+  - @elysiumjs/heracles@0.8.0

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# @elysiumjs/moirai
 
-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.
+Actions and queries for [Elysium.js](../core) apps. An action is validated, runs in a unit of work, retries transient failures and can be idempotent. Its side effects go to an outbox that commits with it, and consumers use an inbox to process each message once.
+
+## Installation
+
+```bash
+bun add @elysiumjs/moirai @elysiumjs/mnemosyne
+```
+
+## Actions and queries
+
+An action is a write: a class that extends `Action`, marked with `@Action.register()`. A query is a read: a class that extends `Query`, marked with `@Query.register()`. `Moirai.execute()` runs an action and `Moirai.ask()` runs a query.
+
+```ts
+import { Service, t } from '@elysiumjs/core';
+import { Action, Moirai, Outbox, Query } from '@elysiumjs/moirai';
+
+@Action.register({
+	input: t.Object({ walletId: t.String(), amount: t.Integer({ minimum: 1 }) }),
+	idempotent: true,
+	serializeBy: (input) => `wallet:${input.walletId}`
+})
+class TopUp extends Action {
+	constructor(@Service.inject() private readonly wallets: WalletRepository) {
+		super();
+	}
+
+	public async handle(input: { walletId: string; amount: number }) {
+		const wallet = await this.wallets.credit(input.walletId, input.amount);
+		await Outbox.enqueue({ kind: 'wallet.credited', payload: { walletId: wallet.id } });
+		return { balance: wallet.balance };
+	}
+}
+
+@Query.register({ input: t.Object({ walletId: t.String() }) })
+class WalletBalance extends Query {
+	public handle(input: { walletId: string }) {
+		/* ... */
+	}
+}
+
+// `Moirai` runs them. In a controller, which returns the outcome: a result, or the DomainError that refused the call.
+return Moirai.execute(TopUp, body, { idempotencyKey: headers['idempotency-key'] });
+return Moirai.ask(WalletBalance, { walletId });
+```
+
+- A refusal is a value. `Moirai.execute()` and `Moirai.ask()` return the DomainError that refused the call, and their return type lists it next to the result. A controller that returns it sends it as the problem of its route, and typed clients see it under its status. Check one with `isDomainError(outcome)`.
+- An input that does not match the schema is refused with a 422 `VALIDATION_FAILED` problem, with one entry per mistake.
+- When `authorize(input)` returns `false`, the call is refused with a 403 `FORBIDDEN` problem.
+- An action runs in a unit of work, or joins the one already open. A transient failure retries in a new unit of work, up to 3 attempts. Transient failures are errors with `transient: true`, and Postgres serialization failures and deadlocks. `retry: { attempts, isTransient }` sets them per action, such as to retry a returned optimistic-concurrency error; `retry: false` never retries. A transient DomainError that outlasts the attempts is returned.
+- A handler refuses a call by returning a `DomainError`, or throwing one. The unit of work then rolls back, nothing is stored for idempotency, and the error is returned to the caller. An action that joined an open unit of work hands it up: the unit rolls back when its opener returns it too.
+- An idempotent action needs a key, or it is refused with a 400 `IDEMPOTENCY_KEY_REQUIRED` problem. A repeat with the same key and input replays the stored response, as JSON; with another input, it is refused with a 422 `IDEMPOTENCY_KEY_REUSED` problem.
+- A key belongs to its owner: the current user by default (`currentUserId()` of core, else `anonymous`), or what `scope(input)` of the action or `Moirai.execute(..., { scope })` returns, such as a tenant and a user. Another owner presenting the same key runs the action on its own.
+- `serializeBy` makes calls that share a key run one after the other, so a double tap waits for the first call and replays its response.
+
+## Outbox and inbox
+
+```ts
+class Mailer {
+	@Outbox.handle('wallet.credited')
+	public async notify(payload: { walletId: string }) {
+		/* send the email */
+	}
+}
+
+// From a cron trigger, for rows that failed or were delayed:
+await Outbox.sweep();
+
+// In a consumer, inside its unit of work:
+await Inbox.once({ messageId: message.id, consumer: 'billing' }, () => apply(message));
+```
+
+Effects relay once the unit of work commits. A row that fails is retried with a backoff from 5 s up to 1 h, and marked dead after 8 attempts (`onDead` is called then). Delivery is at least once, so a handler must tolerate a repeat.
+
+`@elysiumjs/moirai/heracles` adds `job(JobClass, args)`, an effect that dispatches a Heracles job once the action commits:
+
+```ts
+import { job } from '@elysiumjs/moirai/heracles';
+
+await Outbox.enqueue(job(SendReceiptJob, [order.id]));
+```
+
+`@Once()` runs a Heracles job once per dispatch id: its `execute()` runs in a unit of work with an inbox record of the id. It fits the jobs of a `Scheduler`, whose dispatch id names the scheduler, the case and the tick, so a repeated delivery or a tick handled twice does nothing.
+
+Effect handlers register when their module is imported, `@elysiumjs/moirai/heracles` included. A process that relays the outbox, such as a cron sweeper, imports the modules of the effects it relays.
+
+## Events
+
+An event says what happened. It is published in the unit of work that made it happen, and each handler gets it once that unit commits, never when it rolls back:
+
+```ts
+import type { EventMeta } from '@elysiumjs/moirai';
+
+import { Event } from '@elysiumjs/moirai';
+
+declare module '@elysiumjs/moirai' {
+	interface EventCatalogue {
+		'wallet.credited': { walletId: string; amount: number };
+	}
+}
+
+// In an action:
+await Event.publish('wallet.credited', { walletId: wallet.id, amount: input.amount });
+
+class Receipts {
+	@Event.on('wallet.credited', { consumer: 'billing.send-receipt', retry: { attempts: 5 } })
+	public async send(payload: { walletId: string; amount: number }, meta: EventMeta) {
+		/* ... */
+	}
+}
+```
+
+- `EventCatalogue` types the names and the payloads of `Event.publish()` and `@Event.on()`. While it is empty, any name and payload are accepted.
+- Each handler gets its own delivery through the outbox, so it retries and dies on its own (`retry: { attempts }`, `retry: false` for one attempt, else `maxRelayAttempts`). Delivery is at least once.
+- Each handler records the events it handled in the inbox, in the unit of work of its own writes, so a repeated delivery does nothing. `consumer` names that record and defaults to `Class.method`: keep it when the method is renamed. Two handlers with one consumer throw `DuplicateEventConsumerError`.
+- `meta` gives the id of the event, its name, when it was published and the attempt.
+- Events need the `outbox` and `inbox` stores. Handlers register when their module is imported, so the process that relays imports them.
+
+## Stores
+
+```ts
+import { MoiraiModule } from '@elysiumjs/moirai';
+import {
+	DrizzleIdempotencyStore,
+	DrizzleInboxStore,
+	DrizzleOutboxStore,
+	moiraiTables,
+	PgAdvisoryLock
+} from '@elysiumjs/moirai-drizzle';
+
+export const billing = moiraiTables('billing');
+
+MoiraiModule.with({
+	idempotency: () => new DrizzleIdempotencyStore({ table: billing.idempotencyKeys }),
+	outbox: () => new DrizzleOutboxStore({ table: billing.outbox }),
+	inbox: () => new DrizzleInboxStore({ table: billing.inbox }),
+	lock: () => new PgAdvisoryLock(),
+	// On Cloudflare Workers, answer before the relay that follows a commit:
+	defer: (work) => Workers.context().waitUntil(work)
+});
+```
+
+The memory stores (`MemoryIdempotencyStore`, `MemoryOutboxStore`, `MemoryInboxStore` and `MemoryActionLock`) are meant for tests and single-process apps. The memory outbox and inbox drop what a unit of work that rolls back wrote, like a database table.
+
+### Module stores
+
+A module can have stores of its own, such as the outbox and inbox tables of a domain. `Moirai.stores()` lists them as private services of the module; what a module leaves out comes from `MoiraiModule`, stores and options alike.
+
+```ts
+const billing = moiraiTables('billing');
+
+@Module.register({
+	controllers: [InvoiceController],
+	services: [
+		Charge,
+		Receipts,
+		...Moirai.stores({
+			outbox: () => new DrizzleOutboxStore({ table: billing.outbox }),
+			inbox: () => new DrizzleInboxStore({ table: billing.inbox }),
+			relayBatch: 20
+		})
+	]
+})
+class BillingModule extends Module {}
+```
+
+- An action runs in the module that registers it, whoever calls it: its idempotency store, its lock, its options, and the outbox of its effects and events are the ones of that module.
+- An event goes through the outbox of the module that publishes it. An `@Event.on` handler runs in the module that registers its class: the events it handled are recorded in the inbox of that module, and its own effects and events go to the outbox of that module. A handler whose class no module registers runs in the module of the outbox the event came from.
+- A `@Once()` job records its dispatch ids in the inbox of the module that registers the job.
+- The relay that follows a commit relays the outbox the rows went to. `Outbox.relay({ module })` and `Outbox.sweep({ module })` relay the outbox of one module; `Outbox.sweep()` relays the outbox of `MoiraiModule` and the one of every module that has its own, so one cron trigger covers them all.
+- Like any service, module stores are visible to the modules that import the module when it exports them.

package/dist/action.d.ts

@@ -0,0 +1,211 @@
+import type { ServiceDefinition } from '@elysiumjs/core';
+import type { Static, TSchema } from 'typebox';
+import type { MoiraiStores } from './moirai.module';
+import { DomainError } from '@elysiumjs/core';
+import { CallForbiddenError, IdempotencyKeyRequiredError, IdempotencyKeyReusedError, InvalidInputError } from './errors';
+/**
+ * What an action or a query handler receives besides its input.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type HandlerContext = {
+    /** The name of the action or the query. */
+    name: string;
+    /** The idempotency key of the call, if any. */
+    idempotencyKey?: string;
+    /** The attempt, from 1, when the action retries after a transient error. */
+    attempt: number;
+};
+/**
+ * What `handle()` gives: the result, or a DomainError that refuses the call.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type HandlerResult<TResult> = Promise<TResult | DomainError> | TResult | DomainError;
+/**
+ * An action class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ActionClass<TInput = any, TResult = any> = new (...args: any[]) => Action<TInput, TResult>;
+/**
+ * A query class.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type QueryClass<TInput = any, TResult = any> = new (...args: any[]) => Query<TInput, TResult>;
+type HandlerClass = ActionClass | QueryClass;
+type InputOf<C extends HandlerClass> = Parameters<InstanceType<C>['handle']>[0];
+type OutcomeOf<C extends HandlerClass> = Awaited<ReturnType<InstanceType<C>['handle']>>;
+/**
+ * What `Moirai.execute()` gives: the result, or the DomainError that refused the call, from the
+ * handler or from moirai itself.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ActionOutcome<C extends ActionClass> = OutcomeOf<C> | InvalidInputError | CallForbiddenError | IdempotencyKeyRequiredError | IdempotencyKeyReusedError;
+/**
+ * What `Moirai.ask()` gives: the result, or the DomainError that refused the call.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type QueryOutcome<C extends QueryClass> = OutcomeOf<C> | InvalidInputError | CallForbiddenError;
+/**
+ * How an action retries a transient failure.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ActionRetry = {
+    /** The attempts, the first included. Defaults to `maxAttempts` of the module. */
+    attempts?: number;
+    /**
+     * Whether a failure, thrown or a returned DomainError, is transient. Defaults to `isTransient`
+     * of the module.
+     */
+    isTransient?: (error: unknown) => boolean;
+};
+/**
+ * The options of an action.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type ActionOptions<S extends TSchema = TSchema> = {
+    /** The name of the action, in idempotency records and problems. Defaults to the class name. */
+    name?: string;
+    /** The schema of the input. */
+    input: S;
+    /**
+     * Whether a call needs an idempotency key. A repeat with the same key and input replays the
+     * stored response; with another input, it is refused with a 422 problem. Defaults to `false`.
+     */
+    idempotent?: boolean;
+    /**
+     * Who owns the idempotency keys of the action, so that the keys of two owners never meet,
+     * such as a tenant and a user. Defaults to the id of the current user (`currentUserId()`),
+     * else `anonymous`. `Moirai.execute()` may pass its own.
+     */
+    scope?: (input: Static<S>) => string;
+    /** Whether the action runs in a unit of work, or joins the open one. Defaults to `true`. */
+    transactional?: boolean;
+    /** The database connection of the unit of work. Defaults to `default`. */
+    connection?: string;
+    /**
+     * Serializes the calls that give the same key, so that a double tap waits for the first call
+     * and replays it instead of racing it. Needs a `lock` store.
+     */
+    serializeBy?: (input: Static<S>) => string;
+    /**
+     * Whether a transient failure retries in a new unit of work. Defaults to `true`, with the
+     * `maxAttempts` and `isTransient` of the module. An object sets them for this action, such as
+     * an `isTransient` that also retries a returned `ConcurrencyConflict` error. A transient
+     * DomainError that outlasts the attempts is returned like any refusal.
+     */
+    retry?: boolean | ActionRetry;
+    /** Decides whether the call may run, such as with the abilities of the current user. */
+    authorize?: (input: Static<S>) => boolean | Promise<boolean>;
+};
+/**
+ * The options of a query.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type QueryOptions<S extends TSchema = TSchema> = {
+    /** The name of the query. Defaults to the class name. */
+    name?: string;
+    /** The schema of the input. */
+    input: S;
+    /** Decides whether the call may run. */
+    authorize?: (input: Static<S>) => boolean | Promise<boolean>;
+};
+/**
+ * An action: a write, validated, run in a unit of work, retried on transient failures, and
+ * idempotent when asked. Mark the class with `@Action.register()` and run it with
+ * {@link Moirai.execute}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ * @example
+ * ```ts
+ * @Action.register({ input: t.Object({ amount: t.Integer({ minimum: 1 }) }), idempotent: true })
+ * class TopUp extends Action<{ amount: number }> {
+ * 	constructor(@Service.inject() private readonly wallets: WalletRepository) {
+ * 		super();
+ * 	}
+ *
+ * 	public async handle(input: { amount: number }) {
+ * 		const wallet = await this.wallets.credit(input.amount);
+ * 		await Outbox.enqueue({ kind: 'wallet.credited', payload: { id: wallet.id } });
+ * 		return { balance: wallet.balance };
+ * 	}
+ * }
+ * ```
+ */
+export declare abstract class Action<TInput = any, TResult = any> {
+    /**
+     * Marks a class as an action.
+     * @param props The options of the action.
+     */
+    static register<S extends TSchema>(props: ActionOptions<S>): (target: ActionClass) => void;
+    /**
+     * Runs the action with its validated input. Returning or throwing a DomainError refuses the
+     * call and rolls its unit of work back.
+     */
+    abstract handle(input: TInput, context: HandlerContext): HandlerResult<TResult>;
+}
+/**
+ * A query: a read, validated and run without a transaction. Mark the class with
+ * `@Query.register()` and run it with {@link Moirai.ask}.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export declare abstract class Query<TInput = any, TResult = any> {
+    /**
+     * Marks a class as a query.
+     * @param props The options of the query.
+     */
+    static register<S extends TSchema>(props: QueryOptions<S>): (target: QueryClass) => void;
+    /** Runs the query with its validated input. Returning or throwing a DomainError refuses it. */
+    abstract handle(input: TInput, context: HandlerContext): HandlerResult<TResult>;
+}
+export declare namespace Moirai {
+    /**
+     * Runs an action: validates the input, checks `authorize`, then runs the handler in a unit of
+     * work (or joins the open one), retrying transient failures, and replaying the stored response
+     * of an idempotent action called again with the same key.
+     *
+     * A refusal is a value: the DomainError the handler returns or throws, or one of moirai's own
+     * (an invalid input, a refused `authorize`, a missing or reused idempotency key). The unit of
+     * work rolls back, nothing is stored for idempotency, and the error is returned, so a handler
+     * that returns it sends it as the problem of its route.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param action The action class.
+     * @param input The raw input.
+     * @param call The idempotency key of the call.
+     */
+    const execute: <C extends ActionClass>(action: C, input: InputOf<C>, call?: {
+        idempotencyKey?: string;
+        scope?: string;
+    }) => Promise<ActionOutcome<C>>;
+    /**
+     * The stores and options of a module, as private services to list in its `services`. The
+     * actions and event handlers of the module, and the code that runs in it, use them instead of
+     * the ones of `MoiraiModule`; a store left out is the one of `MoiraiModule`, and an option left
+     * out is the one of `MoiraiModule`. Like any service, they are visible to the modules that
+     * import the module when it exports them.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param stores The stores, each an instance or a function that builds it once, and options.
+     * @example
+     * ```ts
+     * @Module.register({
+     * 	controllers: [WalletController],
+     * 	services: [
+     * 		WalletRepository,
+     * 		...Moirai.stores({
+     * 			outbox: () => new DrizzleOutboxStore({ table: billing.outbox }),
+     * 			inbox: () => new DrizzleInboxStore({ table: billing.inbox })
+     * 		})
+     * 	]
+     * })
+     * class BillingModule extends Module {}
+     * ```
+     */
+    const stores: (stores: MoiraiStores) => ServiceDefinition[];
+    /**
+     * Runs a query: validates the input, checks `authorize`, and runs the handler. A refusal is a
+     * value: the DomainError the handler returns or throws, an invalid input, or a refused
+     * `authorize`.
+     * @author Axel Nana <axel.nana@workbud.com>
+     * @param query The query class.
+     * @param input The raw input.
+     */
+    const ask: <C extends QueryClass>(query: C, input: InputOf<C>) => Promise<QueryOutcome<C>>;
+}
+export {};

package/dist/config.d.ts

@@ -0,0 +1,58 @@
+import type { ActionLock, IdempotencyStore, InboxStore, OutboxStore } from './stores';
+/** The service names of the moirai stores and options. */
+export declare const MOIRAI_IDEMPOTENCY_STORE = "moirai.idempotency";
+export declare const MOIRAI_OUTBOX_STORE = "moirai.outbox";
+export declare const MOIRAI_INBOX_STORE = "moirai.inbox";
+export declare const MOIRAI_ACTION_LOCK = "moirai.lock";
+export declare const MOIRAI_OPTIONS = "moirai.options";
+/** The service name of the options a module overrides with `Moirai.stores()`. */
+export declare const MOIRAI_MODULE_OPTIONS = "moirai.module-options";
+/**
+ * How moirai runs actions and relays the outbox.
+ * @author Axel Nana <axel.nana@workbud.com>
+ */
+export type MoiraiOptions = {
+    /** The attempts of an action that fails with a transient error. Defaults to 3. */
+    maxAttempts: number;
+    /**
+     * Whether an error is transient, so that the action retries in a new unit of work. Defaults to
+     * errors with `transient: true` and the Postgres serialization failure and deadlock codes.
+     */
+    isTransient: (error: unknown) => boolean;
+    /** Whether the effects an action enqueues relay right after it commits. Defaults to `true`. */
+    relayOnCommit: boolean;
+    /**
+     * Runs the relay that follows a commit. Defaults to awaiting it before the response. On
+     * Cloudflare Workers, pass `(work) => Workers.context().waitUntil(work)` to answer first.
+     */
+    defer?: (work: Promise<unknown>) => void;
+    /** The attempts of an outbox row before it is dead. Defaults to 8. */
+    maxRelayAttempts: number;
+    /** The rows a relay claims at once. Defaults to 50. */
+    relayBatch: number;
+    /**
+     * How long a relay holds the rows it claimed, in seconds. A row its relay did not mark in that
+     * time is due again. Defaults to 300.
+     */
+    relayLease: number;
+    /** Called when an outbox row is dead, such as to raise an alert. */
+    onDead?: (row: import('./stores').OutboxRow, error: Error) => void;
+};
+/** The default transient check: `transient: true`, or a Postgres serialization failure or deadlock. */
+export declare const isTransientError: (error: unknown) => boolean;
+export declare const DEFAULT_OPTIONS: MoiraiOptions;
+/**
+ * The options of the current module: the defaults, then the options of `MoiraiModule`, then the
+ * ones the module overrides with `Moirai.stores()`.
+ */
+export declare const options: () => MoiraiOptions;
+export declare const idempotencyStore: () => IdempotencyStore;
+export declare const outboxStore: () => OutboxStore;
+export declare const inboxStore: () => InboxStore;
+export declare const actionLock: () => ActionLock;
+/**
+ * Runs work in the context of the module that declares a service, such as the module of an
+ * action or of an event handler, so that it uses that module's stores. Without such a module, the
+ * work runs in the current context.
+ */
+export declare const inOwnerModule: <T>(service: object, work: () => T) => T;