@afora/core 0.0.6 → 0.0.8

package/README.md

@@ -1,4 +1,24 @@
-# afora
+<h1 align="center">afora</h1>
+
+<p align="center"><strong>Model the domain. Keep the invariants.</strong><br>Domain modeling for TypeScript, built on TypeBox.</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@afora/core"><img alt="npm" src="https://img.shields.io/npm/v/@afora/core?color=cb3837&logo=npm"></a>
+  <a href="https://github.com/afora-framework/core/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/afora-framework/core/actions/workflows/ci.yml/badge.svg?branch=main"></a>
+  <a href="https://www.npmjs.com/package/@afora/core"><img alt="npm provenance" src="https://img.shields.io/badge/npm-provenance-2ea44f?logo=npm"></a>
+  <a href="https://standardschema.dev"><img alt="Standard Schema V1" src="https://img.shields.io/badge/Standard%20Schema-V1-3178c6"></a>
+  <img alt="Bun >= 1.4.4 and Node >= 22" src="https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.4.4%20%7C%20Node%20%E2%89%A5%2022-555">
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/github/license/afora-framework/core"></a>
+</p>
+
+<p align="center">
+  <a href="https://getafora.com">Website</a> ·
+  <a href="docs/README.md">Docs</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="docs/afora-json.md">afora.json</a> ·
+  <a href="CHANGELOG.md">Changelog</a> ·
+  <a href="https://github.com/afora-framework/core/discussions">Discussions</a>
+</p>
 
 Domain modeling on [TypeBox](https://github.com/sinclairzx81/typebox): entities with invariants, sensitive data masking and exceptions that know their layer, usable by any [Standard Schema](https://standardschema.dev) consumer.
 
@@ -10,7 +30,8 @@ afora is not a general-purpose validator. It is for code that models a domain, a
 - **Typed change namespace and side effects.** `change: ["password"]` generates `change.password(value)` (also destructurable, as `const { change } = user`), which re-validates the value and runs `onSetAll` and `onSet`.
 - **Exceptions that know their layer.** Each error carries a layer (`Property`, `Record`, `UseCase`, `Output`...) and a `trace` that grows as it goes up.
 - **Standard Schema V1 on every field.** Properties, blueprints, lists and record classes work as is in Hono, tRPC and TanStack Form, and `safeParse` never throws for an invalid value.
-- **Commands and outputs.** `commandOf` groups use cases behind one execution boundary (context, transactions, event policies); `outputOf` turns commands into operations and pipes them to a sink: an HTTP API with `@afora/hono`, an OpenAPI 3.1 document, or MCP tools, with problem+json errors and masked responses.
+- **Commands and outputs.** `commandOf` groups use cases behind one execution boundary (context, transactions, event policies); `outputOf` turns commands into operations and pipes them to a sink: an HTTP API with `@afora/hono`, WebSocket messages with `@afora/ws`, an OpenAPI 3.1 document, or MCP tools, with problem+json errors and masked responses.
+- **Standard use cases.** `commandOf({ useCases: (ctx) => ({ create: ctx.create(Posts), publish: ctx.publish(Posts) }) })` picks ready-made use cases that follow the repository and its entity: the actions it declares, its record plugins and the properties of its keys ([docs](docs/std-use-cases.md)).
 - **The whole application in JSON.** An `afora.json` generates the code (`@afora/codegen`), use cases included, as data (steps), and `extractSpec(app)` gives back the `afora.json` of an application written by hand.
 - **Repositories on any store.** A provider contract with typed queries, soft deletion and transactions, a runner-agnostic kit to test one (`@afora/core/testing`), in memory by default and on Drizzle ORM with `@afora/drizzle`.
 
@@ -300,11 +321,18 @@ Every field (a property, blueprint, list or record class) implements Standard Sc
 
 ## Packages
 
-`@afora/codegen` generates afora code from an `afora.json` (and extracts the `afora.json` of an `Application` back), and `@afora/mcp` is an MCP server that lets an agent build a domain with it: see [packages/codegen](packages/codegen/README.md) and [packages/mcp](packages/mcp/README.md). `@afora/hono` is a `hono` sink for outputs: it serves the operations as a Hono app, with problem+json errors, masked responses and an optional OpenAPI document ([packages/hono](packages/hono/README.md)). `@afora/drizzle` is a repository provider on Drizzle ORM (SQLite and Postgres) that passes the provider contract kit: see [packages/drizzle](packages/drizzle/README.md).
+| Package                                                    | What it does                                                                                                                                                  |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`@afora/core`](https://www.npmjs.com/package/@afora/core) | Properties, blueprints, records, entities, repositories, use cases, commands and outputs (this repository's root).                                            |
+| [`@afora/codegen`](packages/codegen/README.md)             | Generates afora code from an `afora.json`, and extracts the `afora.json` of an `Application` back.                                                            |
+| [`@afora/mcp`](packages/mcp/README.md)                     | An MCP server that lets an agent build a domain with `@afora/codegen`.                                                                                        |
+| [`@afora/hono`](packages/hono/README.md)                   | A `hono` sink for outputs: serves the operations as a Hono app, with problem+json errors, masked responses, signed webhooks and an optional OpenAPI document. |
+| [`@afora/ws`](packages/ws/README.md)                       | A `websocket` sink: operations over JSON messages on any runtime, with topic subscriptions that `publishEvents` feeds with domain events.                     |
+| [`@afora/drizzle`](packages/drizzle/README.md)             | A repository provider on Drizzle ORM (SQLite and Postgres) that passes the provider contract kit.                                                             |
 
 ## Example
 
-`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, use cases written as steps, a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`), a password hashing function and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
+`examples/blog` is a blog (users with the `authenticatable` plugin, posts with soft deletion, every use case a [standard one](docs/std-use-cases.md), a Hono API on Drizzle and SQLite) whose whole `src/domain` is generated from one `afora.json` by `@afora/codegen`. Only the database, the schema, the provider (made from a `Database` environment with `providerFrom` when the server calls `App.start()`, and named `database` in the `providers` of the spec) and the server are hand-written. Its tests check that the committed code is what the spec generates, drive the API end to end and extract the spec back from the application: `bun run test:blog`.
 
 ## Performance
 
@@ -335,9 +363,9 @@ Where the others win: Zod and Valibot are faster, have far larger ecosystems and
 
 ## Contributing
 
-Issues open from a template: bug report, feature request, or feedback from building on afora. Questions go to [Discussions](https://github.com/afora-framework/core/discussions). Pull requests follow [the PR template](.github/PULL_REQUEST_TEMPLATE.md).
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the setup, the checks and how releases work. Issues open from a template: bug report, feature request, or feedback from building on afora. Questions go to [Discussions](https://github.com/afora-framework/core/discussions); security issues go through [SECURITY.md](SECURITY.md), never a public issue.
 
-Commits follow [Conventional Commits](https://www.conventionalcommits.org) (`feat(repository): …`, `fix: …`), checked by commitlint in a Husky `commit-msg` hook; the `pre-commit` hook runs Biome and Knip. CI runs lint, Knip, type checks, unit and interop tests, the build and the Node smoke test on every push and pull request. Pushing a `v*` tag that matches `package.json` publishes to npm with provenance.
+Commits follow [Conventional Commits](https://www.conventionalcommits.org) (`feat(repository): …`, `fix: …`), checked by commitlint in a Husky `commit-msg` hook; the `pre-commit` hook runs Biome and Knip. CI runs lint, Knip, type checks, unit and interop tests, the build and the Node smoke test on every push and pull request. A pull request that bumps the version in `package.json`, once merged to `main`, publishes to npm with provenance and creates the tag and the GitHub release.
 
 Scripts:
 
@@ -359,8 +387,9 @@ bun run build         # build dist/ (ESM + .d.ts)
 bun run test:codegen  # tests of packages/codegen
 bun run test:mcp      # tests of packages/mcp
 bun run test:hono     # tests of packages/hono
+bun run test:ws       # tests of packages/ws
 bun run test:drizzle  # tests of packages/drizzle (SQLite and PGlite)
-bun run build:packages # build the core, then packages/codegen, packages/mcp, packages/hono and packages/drizzle
+bun run build:packages # build the core, then packages/codegen, packages/mcp, packages/hono, packages/ws and packages/drizzle
 ```
 
 ## Versioning

package/dist/core/application/start.d.ts

@@ -73,3 +73,10 @@ export declare function stopProvider(provider: IRepositoryProvider): Promise<voi
  * @internal
  */
 export declare function checkTransactions(source: string, provider: IRepositoryProvider, commands: readonly string[]): void;
+/**
+ * Throws `InvalidApplicationDeclaration` when `provider` does not read by
+ * cursor (`capabilities.keyset`) and some of `repositories` declare
+ * `findCursor`.
+ * @internal
+ */
+export declare function checkCapabilities(source: string, provider: IRepositoryProvider, repositories: readonly string[]): void;

package/dist/core/application/types/application.interface.d.ts

@@ -1,11 +1,13 @@
 import type { AnyBlueprint, BlueprintInput, IBlueprint } from "../../blueprint/types/blueprint.interface.js";
 import type { AnyCommand } from "../../command/types/command.interface.js";
+import type { EntityExpires } from "../../entity/types/entity.interface.js";
 import type { AnyEnvironment, EnvironmentValue } from "../../environment/environment.js";
+import type { EventPolicyDescription, IEventPublisher } from "../../event-policy/types/event-policy.interface.js";
 import type { ExceptionLayers } from "../../exception/enums/exception-layers.js";
 import type { ILogger, LogLevel, LogSettings } from "../../logger/logger.js";
 import type { AnyOutput, StageDescription } from "../../output/types/output.interface.js";
 import type { RecordPluginDescriptor } from "../../record/types/plugin.interface.js";
-import type { ProviderDescription } from "../../repository/types/query.interface.js";
+import type { ProviderDescription, RepositoryIndex, RepositoryScans } from "../../repository/types/query.interface.js";
 import type { AnyRepository, IRepositoryProvider } from "../../repository/types/repository.interface.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { UseCaseStepDescription } from "../../use-case/steps/types/steps.interface.js";
@@ -96,6 +98,13 @@ export interface ApplicationSettings<Name extends string, Extended extends reado
      * it, the one of the last extended application that has one; none by default.
      */
     readonly log?: LogSettings | LogFactory;
+    /**
+     * Where event policies such as `publishEvents` publish, by key: a
+     * WebSocket hub, a queue, a broker. Commands of the application find them
+     * by key, those of the extended applications included; a command whose
+     * policy names a key that is not here throws `UnregisteredApplicationReference`.
+     */
+    readonly publishers?: Readonly<Record<string, IEventPublisher>>;
 }
 /**
  * What an application gives the factories it runs on start (`providerFrom`,
@@ -293,6 +302,22 @@ export interface RecordDescription {
         readonly change: readonly string[];
     };
     readonly plugins: readonly RecordPluginDescriptor[];
+    /**
+     * The lifecycle events of an entity, by cycle: each event's name and
+     * whether `eventOf` was given a handler. Present only when it has some.
+     */
+    readonly events?: Readonly<Partial<Record<"onCreate" | "onUpdate" | "onDelete", readonly {
+        readonly name: string;
+        readonly handler: boolean;
+    }[]>>>;
+    /** Whether the entity is versioned (`entityOf(..., { versioned: true })`); present only when it is. */
+    readonly versioned?: true;
+    /**
+     * When the records of an entity expire, as `entityOf` was given it:
+     * `{ after: duration }` (kept in its `expiresAt` identity key, left out of
+     * `fields`) or `{ at: key }`. Present only when it has one.
+     */
+    readonly expires?: EntityExpires;
 }
 /** What a use case depends on, by the name it has in the application. */
 export interface UseCaseDependencyDescription {
@@ -340,6 +365,17 @@ export interface UseCaseDescription {
     } | {
         readonly kind: "opaque";
     };
+    /**
+     * The use case plugin that made it, the registered repository it was made
+     * for and the options given, with classes by name as in the steps; absent
+     * for a use case declared by hand.
+     */
+    readonly generic?: {
+        readonly name: string;
+        readonly version: string;
+        readonly repository: string;
+        readonly options: Readonly<Record<string, unknown>>;
+    };
 }
 /** A command: its metadata, context, operations and policies. */
 export interface CommandDescription {
@@ -359,7 +395,8 @@ export interface CommandDescription {
     readonly transaction: boolean;
     /** The names of its environments, when it declares any. */
     readonly environments?: readonly string[];
-    readonly events: "after-commit" | "manual" | {
+    /** The policy: a name, a policy made by `eventPolicyOf` by name and options, else opaque. */
+    readonly events: "after-commit" | "manual" | EventPolicyDescription | {
         readonly kind: "opaque";
     };
     readonly onEventError?: {
@@ -411,6 +448,10 @@ export interface ApplicationDescription {
     readonly log?: LogDescription | {
         readonly kind: "opaque";
     };
+    /** Its publishers (inherited ones included), by key, with the application that declared each; present only when it has some. */
+    readonly publishers?: Readonly<Record<string, {
+        readonly from: string;
+    }>>;
     readonly properties: Readonly<Record<string, PropertyDescription & {
         readonly from: string;
     }>>;
@@ -429,6 +470,10 @@ export interface ApplicationDescription {
         readonly entity: string;
         readonly actions: readonly string[];
         readonly deletion: "hard" | "soft";
+        /** Its declared indexes, by name. */
+        readonly indexes: Readonly<Record<string, RepositoryIndex>>;
+        /** What it does with a query only a scan serves. */
+        readonly scans: RepositoryScans;
         /** The names of the repositories of the entities its entity holds. */
         readonly relations: readonly string[];
         /** The names of its `environmentDependencies`. */

package/dist/core/command/command.d.ts

@@ -1,7 +1,6 @@
-import type { IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
-import { type EnvironmentDependencies } from "../environment/environment.js";
 import type { IRepositoryProvider } from "../repository/types/repository.interface.js";
-import type { AnyCommand, CommandOf, CommandSettings, CommandUseCases } from "./types/command.interface.js";
+import type { IUseCaseCatalog, UseCasePluginContext } from "../use-case/types/plugin.interface.js";
+import type { AnyCommand, CommandBuilder } from "./types/command.interface.js";
 /**
  * Checks now that the repositories of `command` share a provider that has
  * `transaction`, as its first call would; an application calls it when it
@@ -15,11 +14,19 @@ export declare function verifyCommand(command: object): void;
  * @internal
  */
 export declare function commandTransactionProvider(command: object): IRepositoryProvider | undefined;
+/**
+ * A `commandOf` whose `useCases` may be a function of the use case plugins
+ * of `catalogs`, by name, a later catalog winning a name:
+ * `useCases: (ctx) => ({ create: ctx.create(Posts), custom: MyUseCase })`.
+ * Throws `InvalidCommandDeclaration` for what is not a catalog made by
+ * `useCaseCatalogOf`.
+ */
+export declare function commandBuilderOf<const Catalogs extends readonly IUseCaseCatalog[] = []>(...catalogs: Catalogs): CommandBuilder<UseCasePluginContext<Catalogs>>;
 /**
  * Groups use cases under operation names and is the boundary of a call: the
  * context is validated once, a transaction can wrap the use case, and the
  * events it raised are handled by a policy once it succeeded.
  */
-export declare function commandOf<const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandSettings<UseCases, Context, Environment>): CommandOf<UseCases, Context, Environment>;
+export declare const commandOf: CommandBuilder<Record<never, never>>;
 /** Whether `value` is a command made by `commandOf`. */
 export declare function isCommand(value: unknown): value is AnyCommand;

package/dist/core/command/types/command.interface.d.ts

@@ -1,6 +1,7 @@
 import type { BlueprintInput, IBlueprint, IBlueprintCollection } from "../../blueprint/types/blueprint.interface.js";
 import type { EntityEvent } from "../../entity/event.js";
 import type { AnyEnvironment, EnvironmentDependencies, MergedEnvironment } from "../../environment/environment.js";
+import type { IEventPublisher } from "../../event-policy/types/event-policy.interface.js";
 import type { ILogger } from "../../logger/logger.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { AnyUseCaseClass, UseCaseInput, UseCaseOptions, UseCaseResponse } from "../../use-case/use-case.js";
@@ -19,6 +20,12 @@ export interface CommandEventInfo {
      * application's; a logger that writes nothing without either.
      */
     readonly logger: ILogger;
+    /**
+     * The publisher declared under `name` in `applicationOf({ publishers })`:
+     * of the application that bound the command, else of the started
+     * application. Throws `PublisherNotBound` when neither declares it.
+     */
+    publisher(name: string): IEventPublisher;
 }
 /** Handles all the events of a call, once it succeeded. */
 export type CommandEventHandler = (events: readonly EntityEvent[], info: CommandEventInfo) => void | Promise<void>;
@@ -48,6 +55,25 @@ export interface CommandSettings<UseCases extends CommandUseCases, Context exten
     readonly events?: CommandEvents;
     readonly onEventError?: CommandEventErrorHandler;
 }
+/**
+ * The `useCases` of a command made by a builder: the object, or a function
+ * of the use case plugins of its catalogs that gives it.
+ */
+export type CommandUseCasesOption<UseCases extends CommandUseCases, Generics> = UseCases | ((ctx: Generics) => UseCases);
+/** `CommandSettings` with `useCases` as a builder takes it. */
+export interface CommandBuilderSettings<UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined, Environment extends EnvironmentDependencies | undefined, Generics> extends Omit<CommandSettings<UseCases, Context, Environment>, "useCases"> {
+    /**
+     * The use cases, by operation name; or a function that gets the use
+     * case plugins of the builder's catalogs, each called with a repository,
+     * and gives them: `(ctx) => ({ create: ctx.create(Posts) })`.
+     */
+    readonly useCases: CommandUseCasesOption<UseCases, Generics>;
+}
+/**
+ * What `commandBuilderOf` gives: `commandOf`, with the use case plugins
+ * `Generics` to pick from.
+ */
+export type CommandBuilder<Generics> = <const UseCases extends CommandUseCases, Context extends IBlueprintCollection | undefined = undefined, Environment extends EnvironmentDependencies | undefined = undefined>(settings: CommandBuilderSettings<UseCases, Context, Environment, Generics>) => CommandOf<UseCases, Context, Environment>;
 /** The names of the operations of a command. */
 export type CommandOperation<Command extends {
     readonly useCases: object;

package/dist/core/entity/abstract-entity.d.ts

@@ -12,10 +12,37 @@ export declare const RESERVED_ENTITY_KEYS: readonly string[];
 export declare const EntityClock: unique symbol;
 /** The unique keys of a class made by `entityOf`, as `options.unique` lists them. */
 export declare const EntityUniqueKeys: unique symbol;
+/** The storage options of an entity class (`versioned`, `expires`). */
+export declare const EntitySettings: unique symbol;
+/**
+ * The milliseconds after `createdAt` at which the entities of a class
+ * declared with `expires: { after }` expire, kept in `expiresAt`.
+ *
+ * @internal
+ */
+export declare const EntityLifetime: unique symbol;
+/** The key the entities of a class declared with `expires: { after }` keep their expiry in. */
+export declare const EXPIRES_AT = "expiresAt";
+/** The key a versioned entity adds to its identity. */
+export declare const ENTITY_VERSION_KEY = "version";
+/** Whether `entityClass` was declared with `versioned: true`. */
+export declare function isVersionedEntityClass(entityClass: unknown): boolean;
+/**
+ * The identity keys of the entities of `entityClass`, which only the entity
+ * changes: `ENTITY_IDENTITY_KEYS`, `version` when it is versioned, and
+ * `expiresAt` when it expires `after` a duration.
+ */
+export declare function identityKeysOf(entityClass: unknown): readonly string[];
+/**
+ * Stores `version` as the version of `entity`, as its repository does once
+ * a write succeeded. @internal
+ */
+export declare function storeEntityVersion(entity: object, version: number): void;
 /**
  * A record with identity: an `id` and a `createdAt`, made when it is built
  * and never changed after, an `updatedAt` set by each change, and a
- * `deletedAt` set by `destroy`, after which it no longer changes.
+ * `deletedAt` set by `destroy`, after which it no longer changes. A versioned
+ * entity also has a `version`, 1 when built, which only its repository changes.
  */
 export declare abstract class AbstractEntity<Properties extends IBlueprintCollection, Sensitive extends string = never> extends AbstractRecord<Properties, Sensitive> {
     constructor(value: BlueprintInput<Properties>);

package/dist/core/entity/entity.d.ts

@@ -9,7 +9,7 @@ import type { EntityBuilder, EntityBuilderSettings, IEntityIdentity } from "./ty
  * `options.plugins` picks from the plugins of `plugins`, catalogs made by
  * `recordPluginCatalogOf`.
  */
-export declare function entityBuilderOf<Identity extends IEntityIdentity, const Catalogs extends readonly IRecordPluginCatalog[] = []>({ identity, generateId, now, plugins: catalogs, }: EntityBuilderSettings<Identity, Catalogs>): EntityBuilder<Identity, RecordPluginContext<Catalogs>>;
+export declare function entityBuilderOf<Identity extends IEntityIdentity, const Catalogs extends readonly IRecordPluginCatalog[] = []>({ identity, generateId, now, expiresAt, plugins: catalogs, }: EntityBuilderSettings<Identity, Catalogs>): EntityBuilder<Identity, RecordPluginContext<Catalogs>>;
 /** Whether `value` is a class made by `entityOf`, or one extending it. */
 export declare function isEntityClass(value: unknown): value is AnyRecordClass & AnyEntityClass;
 /** Whether `value` is an entity, an instance of a class made by `entityOf`. */

package/dist/core/entity/event.d.ts

@@ -32,8 +32,19 @@ export interface EntityEvents {
     readonly onDelete?: EntityEventReference;
 }
 export declare const EntityEventSettings: unique symbol;
-/** Defines an event without executing its handler. */
-export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler: (entity: InstanceType<Class>, context: EventHandlerContext) => Promise<void>): EventDefinition;
+/**
+ * Defines an event without executing its handler. Without a handler, the
+ * event only carries the entity, for a policy such as `publishEvents`, and
+ * `handle()` does nothing.
+ */
+export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler?: (entity: InstanceType<Class>, context: EventHandlerContext) => Promise<void>): EventDefinition;
+/** Whether `event` was given a handler by `eventOf`. @internal */
+export declare function eventHasHandler(event: EventDefinition): boolean;
+/**
+ * The lifecycle events of an entity class, by cycle, with their function
+ * references resolved: what `describe()` gives. @internal
+ */
+export declare function lifecycleEventsOf(entityClass: object): Partial<Record<keyof EntityEvents, readonly EventDefinition[]>>;
 export declare function enqueueEvent(entity: object, event: EventDefinition): void;
 export declare function pullEntityEvents<Entity extends object>(entity: Entity): EntityEvent<Entity>[];
 export declare function enqueueLifecycle(entity: object, cycle: keyof EntityEvents): void;

package/dist/core/entity/exceptions.d.ts

@@ -17,3 +17,11 @@ export declare const ImmutableEntityKey: import("../../index.js").DeclaredExcept
 export declare const DeletedEntity: import("../../index.js").DeclaredExceptionClass<{
     readonly id: string;
 }>;
+/**
+ * The `expires` option of an entity is invalid: `at` names no date key of its
+ * blueprint, `after` is not a duration of positive numbers, or the entity
+ * builder has no `expiresAt` field; `source` is the entity name.
+ */
+export declare const InvalidEntityExpiry: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

package/dist/core/entity/types/entity.interface.d.ts

@@ -1,11 +1,14 @@
+import type { TString } from "typebox";
 import type { BlueprintField, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection, JoinedProperties } from "../../blueprint/types/blueprint.interface.js";
 import type { ParseResult } from "../../parse/types/parse.interface.js";
+import type { PropertyClass } from "../../property/property.js";
 import type { AnyRecordPlugin, IRecordPluginCatalog, PluginMembers, PluginSensitiveKey, PluginUniqueKey, WithPluginProperties } from "../../record/types/plugin.interface.js";
 import type { MarkedUniqueKey, RecordChanges, RecordKey, RecordOptions, RecordSettings } from "../../record/types/record.interface.js";
 import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { AbstractEntity, EntityUniqueKeys } from "../abstract-entity.js";
 import type { EntityClassBrand, EntityEvents } from "../event.js";
+import type { EntityVersion } from "../version.js";
 /** The keys every entity has, which its blueprint cannot declare. */
 export type EntityIdentityKey = "id" | "createdAt" | "updatedAt" | "deletedAt";
 /**
@@ -15,6 +18,12 @@ export type EntityIdentityKey = "id" | "createdAt" | "updatedAt" | "deletedAt";
 export type IEntityIdentity = {
     readonly [Key in EntityIdentityKey]: BlueprintField;
 };
+/** The identity key a versioned entity adds: `version`, a positive integer. */
+export type IEntityVersion = {
+    readonly version: typeof EntityVersion;
+};
+/** `Identity`, with `version` when `Versioned` is `true`. */
+export type VersionedIdentity<Identity extends IEntityIdentity, Versioned extends boolean> = Versioned extends true ? Identity & IEntityVersion : Identity;
 /** What an entity builder needs: the identity fields, and how to make an id and a timestamp. */
 export interface EntityBuilderSettings<Identity extends IEntityIdentity, Catalogs extends readonly IRecordPluginCatalog[] = []> {
     /** The blueprint of `id`, `createdAt`, `updatedAt` and `deletedAt`. */
@@ -23,6 +32,11 @@ export interface EntityBuilderSettings<Identity extends IEntityIdentity, Catalog
     readonly generateId: () => string;
     /** The current date and time, as the timestamps accept it. */
     readonly now: () => string;
+    /**
+     * The field of `expiresAt`, a date and time, which entities declared with
+     * `expires: { after }` get; without it such a declaration throws.
+     */
+    readonly expiresAt?: ExpiresAtField;
     /**
      * Catalogs of plugins, made by `recordPluginCatalogOf`, that
      * `options.plugins` picks from, as `(ctx) => [ctx.publishable]`.
@@ -45,7 +59,55 @@ export type EntityProperties<Identity extends IEntityIdentity, Properties extend
  */
 export type EntityInput<Identity extends IEntityIdentity, Properties extends IBlueprintCollection> = BlueprintInput<Properties> & Partial<BlueprintInput<Identity>>;
 /** What `entityOf` takes, after the blueprint, to describe its keys. */
-export type EntityOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown, Sensitive extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[]> = RecordOptions<Properties, Change, Unique, Plugins, Context, Sensitive> & EntityEvents;
+export type EntityOptions<Properties extends IBlueprintCollection, Change extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Unique extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Plugins extends readonly AnyRecordPlugin[] = readonly AnyRecordPlugin[], Context = unknown, Sensitive extends readonly RecordKey<Properties>[] = readonly RecordKey<Properties>[], Expires extends EntityExpires<RecordKey<Properties>> | undefined = EntityExpires<RecordKey<Properties>> | undefined> = RecordOptions<Properties, Change, Unique, Plugins, Context, Sensitive> & EntityEvents & EntityStorageOptions<RecordKey<Properties>, Expires>;
+/** How an entity is stored: optimistic concurrency and expiry. */
+export interface EntityStorageOptions<Key extends string = string, Expires extends EntityExpires<Key> | undefined = EntityExpires<Key> | undefined> {
+    /**
+     * Adds a `version` identity key (1 when created) that the `update` of its
+     * repository checks and increments, throwing `RepositoryConcurrencyConflict`
+     * when the stored one differs: optimistic concurrency.
+     */
+    readonly versioned?: boolean;
+    /**
+     * When records of the entity expire, which reads then leave out:
+     * `{ after: { days: 400 } }` from `createdAt`, kept in an `expiresAt`
+     * identity key, or `{ at: "until" }`, the date held by a key of the
+     * blueprint. A record with no date never expires.
+     */
+    readonly expires?: Expires;
+}
+/** A duration, e.g. `{ days: 400 }`. */
+export interface EntityDuration {
+    readonly days?: number;
+    readonly hours?: number;
+    readonly minutes?: number;
+    readonly seconds?: number;
+}
+/**
+ * `after` a duration from `createdAt` (stored as `expiresAt`), or `at` the
+ * date held by a key of the blueprint, `Key`.
+ */
+export type EntityExpires<Key extends string = string> = {
+    readonly after: EntityDuration;
+} | {
+    readonly at: Key;
+};
+/**
+ * The field `expiresAt` of the entities that expire `after` a duration: a
+ * required date and time, as `createdAt`.
+ */
+export type ExpiresAtField = PropertyClass<TString, string>;
+/** `Identity`, with `expiresAt` when `Expires` is `{ after }`. */
+export type ExpiringIdentity<Identity extends IEntityIdentity, Expires> = Expires extends {
+    readonly after: EntityDuration;
+} ? Identity & {
+    readonly expiresAt: ExpiresAtField;
+} : Identity;
+/** What `entityOf` stores under `EntitySettings`. */
+export interface EntityStorageSettings {
+    readonly versioned: boolean;
+    readonly expires?: EntityExpires;
+}
 /**
  * The unique keys of an entity: `id`, those listed in `options.unique`, and
  * those holding a property declared `unique`, as `Slug`.
@@ -86,4 +148,6 @@ export type EntityConstructor<Identity extends IEntityIdentity, Properties exten
  * What `entityBuilderOf` returns: `entityOf`, declaring entities with the
  * identity it was given, whose `options.plugins` picks from `Context`.
  */
-export type EntityBuilder<Identity extends IEntityIdentity, Context = Record<never, never>> = <Properties extends IBlueprintCollection & Partial<Record<EntityIdentityKey, never>>, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = [], const Sensitive extends readonly RecordKey<Properties>[] = []>(blueprint: IBlueprint<Properties, boolean>, options?: EntityOptions<NoInfer<Properties>, Change, Unique, Plugins, Context, Sensitive>) => EntityConstructor<Identity, WithPluginProperties<Properties, Plugins>, Change, readonly (Unique[number] | PluginUniqueKey<Plugins>)[], PluginMembers<Plugins>, Sensitive[number] | PluginSensitiveKey<Plugins>>;
+export type EntityBuilder<Identity extends IEntityIdentity, Context = Record<never, never>> = <Properties extends IBlueprintCollection & Partial<Record<EntityIdentityKey, never>>, const Change extends readonly RecordKey<Properties>[] = [], const Unique extends readonly RecordKey<Properties>[] = [], const Plugins extends readonly AnyRecordPlugin[] = [], const Sensitive extends readonly RecordKey<Properties>[] = [], const Versioned extends boolean = false, const Expires extends EntityExpires<RecordKey<Properties>> | undefined = undefined>(blueprint: IBlueprint<Properties, boolean>, options?: EntityOptions<NoInfer<Properties>, Change, Unique, Plugins, Context, Sensitive, Expires> & {
+    readonly versioned?: Versioned;
+}) => EntityConstructor<VersionedIdentity<ExpiringIdentity<Identity, Expires>, Versioned>, WithPluginProperties<Properties, Plugins>, Change, readonly (Unique[number] | PluginUniqueKey<Plugins>)[], PluginMembers<Plugins>, Sensitive[number] | PluginSensitiveKey<Plugins>>;

package/dist/core/entity/version.d.ts

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+declare const EntityVersion_base: import("../../index.js").PropertyClass<Type.TInteger, number>;
+/**
+ * The `version` of a versioned entity: a positive integer, 1 when created,
+ * which each `update` of its repository checks and increments.
+ */
+export declare class EntityVersion extends EntityVersion_base {
+}
+/** The identity key a versioned entity adds after the others. */
+export declare const VersionIdentity: import("../../index.js").IBlueprint<import("../property/types/property-options.interface.js").StoredFields<{
+    version: typeof EntityVersion;
+}>, false>;
+export {};

package/dist/core/event-policy/event-policy.d.ts

@@ -0,0 +1,25 @@
+import type { EventPolicyDescription, EventPolicyFactory, EventPolicyOptions, EventPolicySettings, IEventPolicyCatalog } from "./types/event-policy.interface.js";
+/**
+ * A factory of event policies for the `events` setting of `commandOf`:
+ * `events: publishEvents({ publisher: "realtime", topic: "posts/{id}" })`.
+ * Its options are JSON, checked by `validate` when the policy is made (an
+ * `InvalidEventPolicy` otherwise), so the policy can be written in an
+ * `afora.json` and an application describes it by name and options instead
+ * of `{ kind: "opaque" }`. `handle` gets the events of a call that succeeded,
+ * what a handler policy gets, and the options.
+ */
+export declare function eventPolicyOf<Options extends object = EventPolicyOptions>(settings: EventPolicySettings<Options>): EventPolicyFactory<Options>;
+/**
+ * The name and options of a policy made by `eventPolicyOf`; `undefined` for
+ * any other value, such as a handler written by hand.
+ */
+export declare function eventPolicyDescriptionOf(handler: unknown): EventPolicyDescription | undefined;
+/** The keys of the application `publishers` a policy uses; none for a handler written by hand. @internal */
+export declare function eventPolicyPublishersOf(handler: unknown): readonly string[];
+/**
+ * A catalog of event policy factories, by name: what resolves
+ * `{ "policy": name, "options": {...} }` back to a policy. Throws
+ * `InvalidEventPolicy` for a function that is not a factory made by
+ * `eventPolicyOf` or for two with the same name.
+ */
+export declare function eventPolicyCatalogOf(...policies: readonly EventPolicyFactory<never>[]): IEventPolicyCatalog;

package/dist/core/event-policy/exceptions.d.ts

@@ -0,0 +1,11 @@
+/** `eventPolicyOf`, a policy's options or a catalog got something it cannot use; `details.reason` says what. */
+export declare const InvalidEventPolicy: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/**
+ * An event policy asked for a publisher that neither the application that
+ * bound the command nor the started application declares.
+ */
+export declare const PublisherNotBound: import("../../index.js").DeclaredExceptionClass<{
+    readonly publisher: string;
+}>;

package/dist/core/event-policy/publish.d.ts

@@ -0,0 +1,17 @@
+import type { PublishEventsOptions } from "./types/event-policy.interface.js";
+/**
+ * An event policy that publishes the events of a call to a publisher of the
+ * application, once the call succeeded (and committed):
+ * `events: publishEvents({ publisher: "realtime", topic: "posts/{id}" })`.
+ *
+ * For each event, in order, it runs the event's own handler first (unless
+ * `handle: false`), then publishes `{ name, command, operation, entity }`
+ * to the topic, the entity as JSON with sensitive values masked; the context
+ * and the variables are never published. `events` limits it to some names.
+ * A handler that fails stops the call with `CommandEventFailed`, as with
+ * `"after-commit"`. A publish that fails is logged and skipped
+ * (`onPublishError: "log"`, the default) or fails the call (`"throw"`). A
+ * publisher the application does not declare fails the call, caused by
+ * `PublisherNotBound`.
+ */
+export declare const publishEvents: import("./types/event-policy.interface.js").EventPolicyFactory<PublishEventsOptions>;

package/dist/core/event-policy/publishers.d.ts

@@ -0,0 +1,18 @@
+import type { IEventPublisher } from "./types/event-policy.interface.js";
+/** The publishers of an application, by key. */
+export type Publishers = Readonly<Record<string, IEventPublisher>>;
+/**
+ * Carries the publishers of an application, when it declares any: on the
+ * application itself. @internal
+ */
+export declare const ApplicationPublishersKey: unique symbol;
+/** Gives `command` the publishers of the application that bound it. @internal */
+export declare function bindPublishers(command: object, publishers: Publishers): void;
+/** Whether `value` can publish: an object with a `publish` function. @internal */
+export declare function isEventPublisher(value: unknown): value is IEventPublisher;
+/**
+ * The publisher `name` for a call of `command`: one of the application that
+ * bound the command, else one of the started application. Throws
+ * `PublisherNotBound` when neither declares it. @internal
+ */
+export declare function resolvePublisher(command: object, name: string, source: string): IEventPublisher;