@afora/core 0.0.7 → 0.0.9

package/dist/core/output/stage.d.ts

@@ -1,8 +1,13 @@
 import type { IStageCatalog, SinkFactory, SinkSettings, Stage, StageDescription, StageFactory, StageOptions, TransformFactory, TransformSettings } from "./types/output.interface.js";
 /** A factory of transform stages: `select({ tags: ["public"] })`. */
 export declare function transformOf<Options extends object = StageOptions>(settings: TransformSettings<Options>): TransformFactory<Options>;
-/** A factory of sink stages: `openapi({ info })`. */
-export declare function sinkOf<Result, Options extends object = StageOptions>(settings: SinkSettings<Result, Options>): SinkFactory<Result, Options>;
+/**
+ * A factory of sink stages: `openapi({ info })`. A sink that needs what JSON
+ * cannot hold (middlewares, an authenticator) takes it as a second argument,
+ * its `hooks`, which `build` receives and the description of the stage
+ * leaves out.
+ */
+export declare function sinkOf<Result, Options extends object = StageOptions, Hooks = never>(settings: SinkSettings<Result, Options, Hooks>): SinkFactory<Result, Options, Hooks>;
 /**
  * What a stage is: its kind, name and JSON options when it came from a
  * factory, `{ kind: "opaque" }` otherwise (a hand-written stage needs an

package/dist/core/output/status.d.ts

@@ -10,8 +10,8 @@ export declare function raisedOf(error: Exception): Exception;
  * The HTTP-style status of an error, in this order: `statuses` by exception
  * name; 400 for invalid input or context (and any exception whose
  * `details.issues` is a list, except `InvalidCommandEnvironment`, a 500); 404 for a missing entity or operation; 409 for
- * a unique violation or an entity that already exists; 401 for
- * `UseCaseInvalidCredentials`; 422 for a class in `operation.errors`; 500 for the
+ * a unique violation, a concurrency conflict or an entity that already exists; 401 for
+ * `UseCaseInvalidCredentials` and `Unauthenticated`; 403 for `Forbidden`; 422 for a class in `operation.errors`; 500 for the
  * rest, errors that are not exceptions included. Exceptions match by name,
  * or by class for `operation.errors`.
  */

package/dist/core/output/types/http.interface.d.ts

@@ -0,0 +1,130 @@
+import type { DescribedJwtOptions } from "../../auth/types/jwt.interface.js";
+import type { Principal } from "../../use-case/types/access.interface.js";
+import type { OpenAPIMethod, OpenAPISinkOptions, RouteOptions } from "../openapi-sink.js";
+import type { OperationDescriptor } from "./output.interface.js";
+/**
+ * The options every sink that serves HTTP takes. JSON, so the stage can live
+ * in an `afora.json`. The routing options (`basePath`, `route`, `responses`,
+ * `requestId`, `security`) are those of the `openapi` sink, so the served
+ * routes and the document agree.
+ */
+export interface HttpOptions extends RouteOptions {
+    /** Serves the OpenAPI document of the same operations at `path`. */
+    readonly docs?: {
+        readonly path: string;
+        readonly info: OpenAPISinkOptions["info"];
+        readonly servers?: OpenAPISinkOptions["servers"];
+    };
+    /** Adds the `trace` to problems and the real `detail` to 5xx ones. Off by default. */
+    readonly debug?: boolean;
+    /**
+     * The context of an operation, by context key: from request headers
+     * (`{ headers: { locale: "accept-language" } }`) and from values a
+     * middleware of the server set for the request
+     * (`{ variables: { caller: "caller" } }`).
+     */
+    readonly context?: {
+        readonly headers?: {
+            readonly [contextKey: string]: string;
+        };
+        readonly variables?: {
+            readonly [contextKey: string]: string;
+        };
+    };
+    /**
+     * Who calls, from a JSON Web Token (see `jwtOf`; the secret is named by
+     * its environment variable, `{ env: "JWT_SECRET" }`): read from the
+     * `authorization` header (`Bearer <token>`; another header with `header`)
+     * and, with `cookie`, from that cookie when the header is absent. The
+     * document gets a matching security scheme unless `security` declares
+     * its own. An `authenticator` given in the hooks of the sink replaces it.
+     */
+    readonly auth?: {
+        readonly jwt: DescribedJwtOptions & {
+            readonly header?: string;
+            readonly cookie?: string;
+        };
+    };
+}
+/** A request, as the server of a sink gives it to the route table. */
+export interface HttpRequest {
+    /** The value of the `{name}` segment of the path, decoded. */
+    param(name: string): string | undefined;
+    /** The query string, the first value of each name. */
+    query(): Readonly<Record<string, string | undefined>>;
+    /** The value of a header, by its name in lower case. */
+    header(name: string): string | undefined;
+    /** The body, as text. Called at most once, and only by routes with a body. */
+    text(): string | Promise<string>;
+    /** A value a middleware of the server set for this request, by name. */
+    variable?(name: string): unknown;
+    /** The request of the server itself, for an authenticator that needs it. */
+    readonly native?: unknown;
+}
+/** The answer to a request: what the server of a sink has to send, as is. */
+export interface HttpResult {
+    readonly status: number;
+    /** `content-type` included, when there is a body. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** One `set-cookie` header each. */
+    readonly cookies: readonly string[];
+    /** The body, already serialized (sensitive values masked), or `null` for none. */
+    readonly body: string | null;
+}
+/** What an authenticator reads of a request. */
+export interface AuthRequest {
+    /** The value of a header, by its name in lower case. */
+    header(name: string): string | undefined;
+    /** The value of a cookie of the request. */
+    cookie(name: string): string | undefined;
+    /** The operation being called. */
+    readonly operation: OperationDescriptor;
+    /** The request of the server itself. */
+    readonly native?: unknown;
+}
+/**
+ * Who is calling, from the credentials of a request: a `Principal`, or
+ * `null` for an anonymous caller. Called for each request to an operation
+ * with an `access` other than `public`. It may throw `Unauthenticated` to
+ * refuse credentials it does not accept.
+ */
+export type Authenticator = (request: AuthRequest) => Principal | null | Promise<Principal | null>;
+/** One operation, ready to serve: the server routes `method` and `path` to `handle`. */
+export interface CompiledRoute {
+    readonly operation: OperationDescriptor;
+    readonly method: OpenAPIMethod;
+    /** `basePath` included, parameters as `{name}`. */
+    readonly path: string;
+    /** The names of the `{name}` segments of `path`, in order. */
+    readonly parameters: readonly string[];
+    /** Never rejects: an error is a problem result. */
+    handle(request: HttpRequest): Promise<HttpResult>;
+}
+/** The routes of an output, compiled once (see `compileRoutes`). */
+export interface RouteTable {
+    readonly routes: readonly CompiledRoute[];
+    /** The route that serves the OpenAPI document, with `docs`. */
+    readonly docs?: {
+        readonly path: string;
+        handle(request?: Pick<HttpRequest, "header">): HttpResult;
+    };
+    /** The 404 problem for a request no route serves. */
+    notFound(request?: Pick<HttpRequest, "header">): HttpResult;
+    /**
+     * The problem for an error raised outside `handle`: its status is the one
+     * the output `statuses` give its name, else `status`, else `statusOf`.
+     */
+    failure(error: unknown, options?: {
+        readonly operation?: OperationDescriptor;
+        readonly status?: number;
+        readonly request?: Pick<HttpRequest, "header">;
+    }): HttpResult;
+}
+/** What `compileRoutes` takes besides the operations and the options. */
+export interface CompileRoutesSettings {
+    /** The name of the sink, for the messages of `InvalidOutputStage`. */
+    readonly source: string;
+    readonly authenticator?: Authenticator;
+    /** Changes the OpenAPI document before it is served (a sink with routes of its own kind). */
+    readonly document?: (document: unknown) => unknown;
+}

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

@@ -2,6 +2,8 @@ import type { AnyBlueprint } from "../../blueprint/types/blueprint.interface.js"
 import type { AnyCommand } from "../../command/types/command.interface.js";
 import type { JsonValue } from "../../json.js";
 import type { Kind } from "../../symbols/kind.js";
+import type { AccessDeclaration, Principal } from "../../use-case/types/access.interface.js";
+import type { RouteDeclaration } from "../../use-case/types/route.interface.js";
 import type { AnyExceptionClass } from "../../use-case/use-case.js";
 /** The options of a stage: a JSON object. */
 export type StageOptions = {
@@ -9,9 +11,15 @@ export type StageOptions = {
 };
 /** An HTTP-style status by exception name. */
 export type OutputStatuses = Readonly<Record<string, number>>;
-/** The call of an operation: `context` is what the command (or use case) declares. */
+/**
+ * The call of an operation: `context` is what the command (or use case)
+ * declares, and `principal` is who calls, as the sink authenticated it
+ * (`null` or absent for an anonymous caller). An operation with an `access`
+ * checks the principal before it runs.
+ */
 export interface OperationCallOptions {
     readonly context?: unknown;
+    readonly principal?: Principal | null;
 }
 /**
  * One operation of a command, as an output sees it. Frozen; transforms change
@@ -39,9 +47,16 @@ export interface OperationDescriptor {
     readonly context?: AnyBlueprint;
     /** The `errors` of the use case. */
     readonly errors: readonly AnyExceptionClass[];
+    /** The route the use case declares (`route` or `@Route`), if any. */
+    readonly route?: RouteDeclaration;
+    /** Who may call it, as the use case declares (`access` or `@Access`), if it does. */
+    readonly access?: AccessDeclaration;
     /** Set by transforms; `{}` initially. */
     readonly meta: Readonly<Record<string, unknown>>;
-    /** `command.run(name, input, options)`. */
+    /**
+     * `command.run(name, input, { context })`, after the check of `access`:
+     * it rejects with `Unauthenticated` or `Forbidden` before anything runs.
+     */
     invoke(input: unknown, options?: OperationCallOptions): Promise<unknown>;
 }
 /** What `operationOf` can change. */
@@ -92,15 +107,20 @@ export interface TransformSettings<Options extends object> {
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
-export interface SinkSettings<Result, Options extends object> {
+export interface SinkSettings<Result, Options extends object, Hooks = never> {
     readonly name: string;
-    readonly build: (operations: readonly OperationDescriptor[], options: Options, context: StageContext) => Result;
+    /**
+     * `hooks` is the second argument the stage was made with: what cannot be
+     * JSON (functions, an instance of a server). It is not part of the
+     * description of the stage.
+     */
+    readonly build: (operations: readonly OperationDescriptor[], options: Options, context: StageContext, hooks: Hooks | undefined) => Result;
     /** Why `options` cannot be used, or `undefined`. Checked when the stage is made. */
     readonly validate?: (options: Options) => string | undefined;
 }
 /** Makes a stage from JSON options. */
 export type TransformFactory<Options extends object = StageOptions> = (options?: Options) => TransformStage<Options>;
-export type SinkFactory<Result = unknown, Options extends object = StageOptions> = (options?: Options) => SinkStage<Result, Options>;
+export type SinkFactory<Result = unknown, Options extends object = StageOptions, Hooks = never> = (options?: Options, hooks?: Hooks) => SinkStage<Result, Options>;
 /** Any stage factory. */
 export type StageFactory = TransformFactory<any> | SinkFactory<any, any>;
 /** Stage factories by name. */

package/dist/core/parse/issue.d.ts

@@ -1,6 +1,31 @@
 import type { Exception } from "../exception/exception.js";
-import type { Issue } from "./types/parse.interface.js";
-/** `issue` with a `cause` that is built the first time it is read, and kept. */
-export declare function withLazyCause(issue: Issue, build: () => Exception): Issue;
+import type { Issue, IssueCode } from "./types/parse.interface.js";
+/**
+ * What a step gives back, in place of a value, for a value it rejects; the
+ * issues are then found where the step says, so a valid value costs no result
+ * object.
+ * @internal
+ */
+export declare const REJECTED: unique symbol;
+/** Who knows the exception an issue stands for, and builds it only when asked. */
+export interface IssueOrigin {
+    exception(): Exception;
+}
+/**
+ * An issue whose `cause` is built the first time it is read, by its origin,
+ * which keeps it: every issue of one origin has the same cause. Its own keys
+ * are those of any issue, `cause` is not one of them.
+ */
+export declare class LazyIssue implements Issue {
+    #private;
+    readonly message: string;
+    readonly path: readonly (string | number)[];
+    readonly code: IssueCode;
+    readonly source: string;
+    constructor(message: string, path: readonly (string | number)[], code: IssueCode, source: string, origin: IssueOrigin);
+    get cause(): Exception;
+    /** A copy of the issue at `path`, with the same cause. */
+    at(path: readonly (string | number)[]): LazyIssue;
+}
 /** A copy of `issue` at `path`, with the same `cause`, built lazily or not. */
 export declare function movedIssue(issue: Issue, path: readonly (string | number)[]): Issue;

package/dist/core/parse/parse.d.ts

@@ -1,6 +1,16 @@
 import type { BlueprintField, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
 import type { ParseResult } from "./types/parse.interface.js";
 type Path = readonly (string | number)[];
+/**
+ * `Object.entries(properties)`, kept for the next time.
+ * @internal
+ */
+export declare function fieldsOf(properties: IBlueprintCollection): readonly (readonly [string, BlueprintField])[];
+/**
+ * Whether `value` is an object made by `{}` or `Object.create(null)`, as parsed JSON is.
+ * @internal
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
 /**
  * `value` handled by each field of `properties`, or every issue found: each
  * key `properties` does not declare, then those of each field, in order. Keys
@@ -8,6 +18,15 @@ type Path = readonly (string | number)[];
  * is parsing it, e.g. a record name.
  */
 export declare function parseCollection(properties: IBlueprintCollection, value: unknown, path: Path, source: string): ParseResult<Readonly<Record<string, unknown>>>;
+/**
+ * `parseCollection` at the root, as a function of the value alone: what it
+ * needs of `properties` is looked up on the first value and kept, instead of
+ * on every one. For what parses many values of one shape, a blueprint or a
+ * record class. The values of the keys in `vouched` are kept as they are,
+ * unchecked: for what the caller made itself and knows to be valid.
+ * @internal
+ */
+export declare function collectionParserOf(properties: IBlueprintCollection, source: string): (value: unknown, vouched?: readonly string[]) => ParseResult<Readonly<Record<string, unknown>>>;
 /**
  * `value` handled by `field`, or every issue found: a property runs its
  * handlers, a blueprint each of its fields, a list each of its items, and a

package/dist/core/parse/strip.d.ts

@@ -0,0 +1,13 @@
+import type { AnyBlueprint, AnyRecordClass, BlueprintField } from "../blueprint/types/blueprint.interface.js";
+/**
+ * A copy of `value` without the keys `shape` does not declare, at any depth:
+ * in nested blueprints, the items of `listOf`, `optionalOf` and the records
+ * and entities held as fields. For a payload with more than the operation
+ * reads, such as a webhook from another service, before it is parsed, since
+ * parsing rejects an undeclared key (`undeclared_key`).
+ *
+ * It does not validate, never throws and does not change `value`: a value of
+ * the wrong type, a property's value (even an object) and a record instance
+ * come back as they are, for parsing to accept or reject.
+ */
+export declare function stripUndeclared(shape: AnyBlueprint | AnyRecordClass | BlueprintField, value: unknown): unknown;

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

@@ -9,6 +9,15 @@ import type { AnyPropertyConstructor } from "./types/property-collection.type.js
 import type { PropertyValue } from "./types/property-constructor.type.js";
 import type { PropertyOptions } from "./types/property-options.interface.js";
 import type { IPropertyType } from "./types/property-type.interface.js";
+/**
+ * The definition `Class` parses with. It does not depend on any member the
+ * constructor sets, and `parse` leaves nothing on it that the next one reads,
+ * so every `safeParse` shares one.
+ * @internal
+ */
+export declare function parsingDefinitionOf(Class: {
+    prototype: object;
+}): AbstractDefineProperty<TSchema>;
 /** A property instance; `Value` is the value of its schema, as in `ISchema`. */
 export declare abstract class AbstractProperty<SchemaType extends TSchema, Value = Static<SchemaType>> implements IProperty<SchemaType, Value> {
     get [State](): PropertyStates;

package/dist/core/property/define-property.d.ts

@@ -1,9 +1,16 @@
 import type { Static, TSchema } from "typebox";
-import type { ParseResult } from "../parse/types/parse.interface.js";
+import type { Issue, ParseResult } from "../parse/types/parse.interface.js";
 import { State } from "../symbols/state.js";
 import { PropertyStates } from "./enums/property-states.js";
 import type { IDefineProperty } from "./types/define-property.interface.js";
 import type { IPropertyType } from "./types/property-type.interface.js";
+/**
+ * Adds to `issues` those of the value a pipeline has just rejected, each
+ * under `path`, where the value is. An issue of the value itself has `path`
+ * as it is, not a copy.
+ * @internal
+ */
+export declare function takeRejectionIssues(path: readonly (string | number)[], issues: Issue[]): void;
 /** How a property handles its value; `Value` is the value of its schema, as in `ISchema`. */
 export declare abstract class AbstractDefineProperty<SchemaType extends TSchema, Value = Static<SchemaType>> implements IDefineProperty<SchemaType, Value> {
     [State]: PropertyStates;
@@ -27,9 +34,13 @@ export declare abstract class AbstractDefineProperty<SchemaType extends TSchema,
     protected afterHandle(value: Value): Value;
     /** The value, or `MISMATCH` when the schema rejects it. */
     protected handle(value: Value): Value;
-    /** `attempt`, with the error of any step as a failure. */
+    /** `attempt`, with the error of any step as a rejection. */
     private attemptWithoutThrowing;
-    /** Runs the pipeline, updating the state, and tells why it stopped if it did. */
+    /**
+     * Runs the pipeline, updating the state: the handled value, or `REJECTED`
+     * with the reason in `rejection`. A handler that is not declared is not
+     * run, and neither is the shape check that protects it.
+     */
     private attempt;
     /**
      * Runs a handler: an `Exception` it throws goes up as it is, any other
@@ -38,11 +49,28 @@ export declare abstract class AbstractDefineProperty<SchemaType extends TSchema,
     private runHandler;
     /** The `InvalidPropertyValue` of an error that is not an `Exception`, as its cause. */
     private invalidValue;
-    /** The failure of an `exception` that a step threw. */
+    /** Rejects the value with an `exception` that a step threw. */
     private raise;
     /**
-     * The failure of `value`, which the schema rejects: an issue for each of its
-     * errors, found once and kept for the details of the exception too.
+     * Rejects `value`, which the schema rejects, with its errors, found once
+     * and kept for the details of the exception too.
      */
     private mismatch;
 }
+/**
+ * Tells that the definitions of `prototype` are as `propertyOf` declares them.
+ * @internal
+ */
+export declare function declarePipeline(prototype: object): void;
+/**
+ * `definition.parse` without its result object: a function giving the handled
+ * value, or `REJECTED`, with the issues for `takeRejectionIssues` to take.
+ * `undefined` when `definition` has a `parse` of its own, which must be
+ * called instead.
+ *
+ * For a definition declared by `propertyOf`, the function is the pipeline of
+ * `attempt` with what never changes read once: which steps there are, the
+ * schema, and no state, which nobody can read.
+ * @internal
+ */
+export declare function parserOf(definition: AbstractDefineProperty<TSchema>): ((value: unknown) => unknown) | undefined;

package/dist/core/property/types/property-options.interface.d.ts

@@ -14,6 +14,16 @@ export interface PropertyMetadata<Value> {
     readonly writeOnly?: boolean;
     /** The demo value, as `default` in `propertyOf`; it is not written to the schema. */
     readonly default?: Value;
+    /**
+     * The value a repository gives the key when a stored row lacks it, on read
+     * and in a backfill (`app.migrate`); unlike `default`, it fills real data.
+     */
+    readonly fill?: Value;
+    /**
+     * The key that held the value in rows stored before the key was renamed:
+     * a repository moves it on read and in a backfill.
+     */
+    readonly renamedFrom?: string;
 }
 /**
  * Bounds of a number. They only narrow the property: a bound looser than one

package/dist/core/property/types/property-type.interface.d.ts

@@ -15,6 +15,10 @@ export interface IPropertyType<SchemaType extends TSchema, Value = Static<Schema
     readonly sensitive?: boolean;
     /** Whether a record lists a key holding it in `options.unique`, for repositories to enforce. */
     readonly unique?: boolean;
+    /** `fill` of `.with()`: the value given to the key when a stored row lacks it. */
+    readonly fill?: Value;
+    /** `renamedFrom` of `.with()`: the key that held the value in older rows. */
+    readonly renamedFrom?: string;
 }
 /**
  * The type of a property declared `unique`, as `Slug`, so that the keys

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

@@ -15,6 +15,13 @@ interface RecordDeclaration<Properties extends IBlueprintCollection> {
 export declare const RESERVED_RECORD_KEYS: readonly string[];
 /** Makes each of `keys` a member of the records of `prototype`, e.g. `user.name`. */
 export declare function exposeRecordKeys(prototype: object, keys: readonly string[]): void;
+/**
+ * Tells the record whose constructor runs next that the values of `keys` are
+ * valid as they are. For a class that makes values for its own record on the
+ * way to `super()`, as an entity does of its id.
+ * @internal
+ */
+export declare function vouchFor(keys: readonly string[]): void;
 /** How `recordDataOf` stores the records a record holds. */
 export interface RecordDataOptions {
     /**

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

@@ -120,7 +120,18 @@ type JsonField<Field, Data> = Field extends {
     readonly properties: infer Properties extends IBlueprintCollection;
 } ? Data extends object ? JsonKeys<Properties, Data, never> : Data : Field extends {
     readonly item: infer Item;
-} ? Data extends readonly (infer ItemData)[] ? JsonField<Item, ItemData>[] : Data : Data;
+} ? Data extends readonly (infer ItemData)[] ? JsonField<Item, ItemData>[] : Data : Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+} ? JsonVariant<Key, Variants, Data> : Data;
+/** What `toJSON` gives for the value `Data` of a variant field: each variant by its own blueprint. */
+type JsonVariant<Key extends string, Variants, Data> = Data extends {
+    readonly [Name in Key]: infer Tag extends keyof Variants;
+} ? Variants[Tag] extends AnyRecordClass ? {
+    readonly [Name in Key]: Tag;
+} & JsonOfRecord<Variants[Tag], Data> : Variants[Tag] extends {
+    readonly properties: infer Properties extends IBlueprintCollection;
+} ? JsonKeys<Properties, Data, never> : Data : Data;
 /** What the `toJSON` of the records of `Class` gives, in place of their plain value. */
 type JsonOfRecord<Class extends AnyRecordClass, Data> = InstanceType<Class> extends {
     toJSON(): infer Json;

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

@@ -18,13 +18,56 @@ export declare const InvalidRepositoryDeclaration: import("../../index.js").Decl
 }>;
 /** A method of a repository got a value that is not an entity of it. */
 export declare const InvalidRepositoryEntity: import("../../index.js").DeclaredExceptionClass<undefined>;
+/**
+ * A stored row holds a schema version (`SCHEMA_VERSION_KEY`) that is not a
+ * positive integer, or that is above the `schemaVersion` of its entity (it
+ * was written by newer code), or an `upgrade` step did not give an object.
+ * `source` is the repository name; reads throw it as the cause of
+ * `InvalidRepositoryData`.
+ */
+export declare const InvalidStoredSchemaVersion: import("../../index.js").DeclaredExceptionClass<{
+    readonly id: string;
+    readonly stored: unknown;
+    readonly current: number;
+    readonly reason?: string;
+}>;
 /** A provider gave a value its entity rejects; `source` is the repository name. */
 export declare const InvalidRepositoryData: import("../../index.js").DeclaredExceptionClass<undefined>;
 /** Another entity holds the value of a unique key; `source` is the repository name. */
 export declare const RepositoryUniqueViolation: import("../../index.js").DeclaredExceptionClass<{
     readonly key: string;
 }>;
+/**
+ * A repository declared at module level was called after an application
+ * bound it to its provider: the calls of the application go through
+ * `app.repositories.<key>`, its use cases (`app.run`, `app.useCase`) or a
+ * repository given to `execute`; `source` is the repository name.
+ */
+export declare const RepositoryUsedOutsideApplication: import("../../index.js").DeclaredExceptionClass<{
+    readonly application: string;
+    readonly repository: string;
+}>;
 /** No entity of the id was found; `source` is the repository name. */
 export declare const RepositoryEntityNotFound: import("../../index.js").DeclaredExceptionClass<{
     readonly id: string;
 }>;
+/**
+ * `update` of a versioned entity found another version stored than the one
+ * it read: someone else wrote it in between (optimistic concurrency).
+ * `actual` is the stored version, when the provider knows it; `source` is the
+ * repository name. An output answers it with 409.
+ */
+export declare const RepositoryConcurrencyConflict: import("../../index.js").DeclaredExceptionClass<{
+    readonly id: string;
+    readonly expected: number;
+    readonly actual?: number;
+}>;
+/**
+ * `increment` got deltas it cannot apply: a key that is not a number in the
+ * `change` list of the entity, or a value that is not a finite number. Its
+ * `issues` name each, so an output answers it as invalid input.
+ */
+export declare const InvalidRepositoryIncrement: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+    readonly issues: readonly Issue[];
+}>;

package/dist/core/repository/in-memory.d.ts

@@ -1,10 +1,23 @@
 import type { IRepositoryProvider } from "./types/repository.interface.js";
 /**
- * A provider that keeps the values in memory, one table per entity class,
- * enforcing its unique keys. Each `repositoryOf` without a provider gets its
+ * The provider of `inMemoryProvider`: it runs transactions, reads by cursor,
+ * honors expected versions, increments atomically and leaves expired records out.
+ */
+export type InMemoryProvider = IRepositoryProvider & {
+    readonly capabilities: {
+        readonly transactions: true;
+        readonly keyset: true;
+        readonly versioning: true;
+        readonly atomic: true;
+        readonly expiry: true;
+    };
+};
+/**
+ * A provider that keeps the values in memory, one table per entity name it
+ * declares (or per entity class, without one), enforcing its unique keys. Each `repositoryOf` without a provider gets its
  * own; repositories given the same one share the tables of their entities.
  * Its `transaction` works on isolated snapshots: commits on success, discards
  * on rejection, runs one at a time and makes other operations wait; nested
  * transactions are savepoints.
  */
-export declare function inMemoryProvider(): IRepositoryProvider;
+export declare function inMemoryProvider(): InMemoryProvider;

package/dist/core/repository/migrate.d.ts

@@ -0,0 +1,20 @@
+import { type RepositoryState } from "./state.js";
+import type { EntityMigrationReport, SchemaPlan } from "./types/schema.interface.js";
+/** How `migrateRepository` walks one repository. */
+export interface RepositoryMigration {
+    readonly mode: "check" | "apply";
+    readonly destructive: boolean;
+    readonly pageSize: number;
+    /** Given to `provider.migrate` in `apply`, before the rows are walked. */
+    readonly plan: SchemaPlan;
+}
+/**
+ * Brings the stored rows of the repository of `state` up to the current
+ * shape of its entity (see `app.migrate`): in `apply`, first gives
+ * `options.plan` to `provider.migrate`, then rewrites the rows below the
+ * current version or with a `renamedFrom` or `fill` pending, and moves the
+ * rows of each previous name. Keys no longer declared, and the rows of the
+ * previous names, are only removed when `destructive`. Idempotent: a second
+ * run finds every valid row up to date.
+ */
+export declare function migrateRepository(state: RepositoryState, options: RepositoryMigration): Promise<EntityMigrationReport>;

package/dist/core/repository/plan.d.ts

@@ -0,0 +1,20 @@
+import type { RepositoryIndex, RepositoryOrder, RepositoryPlan } from "./types/query.interface.js";
+/** What the planner reads of a query: its conditions and its orders. */
+export interface PlannedQuery {
+    readonly where?: Readonly<Record<string, unknown>>;
+    readonly orderBy?: readonly RepositoryOrder[];
+}
+/** What the planner reads of a repository: its unique keys and its indexes. */
+export interface PlannedRepository {
+    readonly unique: readonly string[];
+    readonly indexes?: Readonly<Record<string, RepositoryIndex>>;
+}
+/**
+ * How `query` reaches its rows. A condition on `id`, or on another unique
+ * key, by equality or `in` (a batch of key lookups) gives `id` or `unique`.
+ * An index whose `where` keys all hold a condition by equality, and whose
+ * `orderBy` is the first order of the query (when it has one), gives
+ * `index`: the one with the most keys, the first declared on a tie. The rest
+ * is a `scan`. It reads nothing, and expects a query `prepareQuery` checked.
+ */
+export declare function planQuery(repository: PlannedRepository, query?: PlannedQuery): RepositoryPlan;

package/dist/core/repository/provider.d.ts

@@ -1,6 +1,6 @@
 import type { ProviderDescription, ProviderOptions, ProviderSettings } from "./types/query.interface.js";
 import type { IRepositoryProvider } from "./types/repository.interface.js";
 /** Creates a provider once and attaches an immutable, serializable declaration out of band. */
-export declare function providerOf<Options extends ProviderOptions = ProviderOptions, Provider extends IRepositoryProvider = IRepositoryProvider>(settings: ProviderSettings<Options, Provider>): Provider;
+export declare function providerOf<Options extends ProviderOptions = ProviderOptions, const Provider extends IRepositoryProvider = IRepositoryProvider>(settings: ProviderSettings<Options, Provider>): Provider;
 /** Describes a named provider; an anonymous one needs an explicit import on extraction. */
 export declare function providerDescriptionOf(provider: IRepositoryProvider): ProviderDescription;

package/dist/core/repository/query.d.ts

@@ -4,6 +4,13 @@ import type { RepositoryContext, RepositoryData } from "./types/repository.inter
 export declare function prepareQuery(context: RepositoryContext, input?: unknown, map?: (key: string, value: unknown) => unknown, options?: readonly string[]): RepositoryQuery;
 /** Structural JSON/data equality without depending on object key insertion order. */
 export declare function sameValue(a: unknown, b: unknown): boolean;
-export declare function matchesQuery(data: RepositoryData, query: RepositoryQuery): boolean;
+/** The time of `query.now`, or the current one. */
+export declare function nowOf(query: ProviderQuery): number;
+/**
+ * Whether `data` is a row of `query`: alive unless `withDeleted`, not expired
+ * by `expiry` (the key of `context.expiry`) unless `withExpired`, and matching
+ * `where`.
+ */
+export declare function matchesQuery(data: RepositoryData, query: ProviderQuery, expiry?: string, now?: number): boolean;
 /** The rows of `query` after ordering, `after`, offset and limit. */
-export declare function selectRows(rows: Iterable<RepositoryData>, query: ProviderQuery): RepositoryData[];
+export declare function selectRows(rows: Iterable<RepositoryData>, query: ProviderQuery, expiry?: string): RepositoryData[];