@afora/core 0.0.7 → 0.0.9

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

@@ -1,14 +1,19 @@
 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 { SchemaLock, SchemaMigrationOptions, SchemaMigrationReport } from "../../repository/types/schema.interface.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { UseCaseStepDescription } from "../../use-case/steps/types/steps.interface.js";
+import type { AccessDeclaration } from "../../use-case/types/access.interface.js";
+import type { RouteDeclaration } from "../../use-case/types/route.interface.js";
 import type { AnyExceptionClass, AnyUseCaseClass, UseCaseInput, UseCaseResponse } from "../../use-case/use-case.js";
 import type { ProviderSlot, ProviderStorage } from "../providers.js";
 import type { LogFactory, ProviderFactory } from "../start.js";
@@ -96,6 +101,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`,
@@ -197,6 +209,17 @@ export interface IApplication<Name extends string, Collections extends Applicati
      * started application of the process.
      */
     stop(): Promise<void>;
+    /**
+     * Brings the stored rows of its entities up to their current shape,
+     * walking each provider directly: in `check` it only reports, in `apply`
+     * it gives each provider the plan of its entity (`provider.migrate`, the
+     * changes from `lock`), then rewrites the rows below the current
+     * `schemaVersion` or with a `fill` or `renamedFrom` pending, and moves the
+     * rows stored under `previousNames`. Keys no longer declared, and the
+     * rows of the previous names, are only removed with `destructive: true`.
+     * Idempotent and resumable.
+     */
+    migrate(options: SchemaMigrationOptions): Promise<SchemaMigrationReport>;
     /** The variables of an environment registered in the application. */
     get<Environment extends AnyEnvironment>(environment: Environment): EnvironmentValue<Environment>;
     /** The bound version of a command registered in the application. */
@@ -222,6 +245,13 @@ export interface ApplicationStartOptions {
     readonly register?: boolean;
     /** Stop the started application of the process and take its place, e.g. on hot reload. Default `false`. */
     readonly replace?: boolean;
+    /**
+     * The committed schema lock (`afora.lock.json`): start throws
+     * `SchemaLockMismatch` when an entity of the lock is no longer named, and
+     * no entity lists it in `previousNames`, or when the `schemaVersion` of
+     * an entity is lower than the lock's.
+     */
+    readonly lock?: SchemaLock;
 }
 /** Any application. */
 export type AnyApplication = IApplication<string, any>;
@@ -281,6 +311,12 @@ export type FieldDescription = {
     readonly kind: "record" | "entity";
     readonly ref: string;
     readonly optional: boolean;
+} | {
+    /** One of several blueprints, told apart by the value of `key`, the name of the variant. */
+    readonly kind: "variant";
+    readonly key: string;
+    readonly optional: boolean;
+    readonly variants: Readonly<Record<string, FieldDescription>>;
 };
 export type FieldsDescription = Readonly<Record<string, FieldDescription>>;
 /** A record or an entity: its fields (an entity's identity and its plugins' keys left out), options and plugins. */
@@ -293,6 +329,28 @@ 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;
+    /** The `schemaVersion` of an entity; present only when declared. */
+    readonly schemaVersion?: number;
+    /** The versions the `upgrade` of an entity has a step to, ascending; present only when it has some. */
+    readonly upgrade?: readonly number[];
+    /** The `previousNames` of an entity; present only when it has some. */
+    readonly previousNames?: readonly string[];
 }
 /** What a use case depends on, by the name it has in the application. */
 export interface UseCaseDependencyDescription {
@@ -308,6 +366,10 @@ export interface UseCaseDescription {
     readonly description?: string;
     readonly tags: readonly string[];
     readonly deprecated: boolean;
+    /** Where it is served over HTTP, from the `route` setting or `@Route`. */
+    readonly route?: RouteDeclaration;
+    /** Who may call it, from the `access` setting or `@Access`. */
+    readonly access?: AccessDeclaration;
     readonly input: FieldsDescription;
     readonly response: FieldsDescription;
     readonly context?: FieldsDescription;
@@ -370,7 +432,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?: {
@@ -422,6 +485,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;
     }>>;
@@ -440,6 +507,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/auth/jwt.d.ts

@@ -0,0 +1,30 @@
+import type { Jwt, JwtOptions } from "./types/jwt.interface.js";
+/** `jwtOf` got options it cannot use, or its secret is missing; `details.reason` says what. */
+export declare const InvalidJwtOptions: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
+/**
+ * Why `options` cannot be the options of `jwtOf`, naming them `where`;
+ * `undefined` when they can. `extra` are other keys the caller accepts, and
+ * `described` is for options that `describe()` and `afora.json` show, where
+ * the secret must be named by its environment variable, never written.
+ */
+export declare function jwtOptionsIssue(options: unknown, where: string, extra?: readonly string[], described?: boolean): string | undefined;
+/**
+ * Signs and verifies JSON Web Tokens with a shared secret (HMAC), on Web
+ * Crypto, so it runs on Bun, Node and Workers alike:
+ *
+ * ```ts
+ * const jwt = jwtOf({ secret: { env: "JWT_SECRET" }, issuer: "blog" });
+ * const token = await jwt.sign({ subject: user.id, scopes: ["posts:write"] });
+ * const principal = await jwt.verify(token); // { subject, scopes, claims? }
+ * hono(options, { authenticator: jwt.authenticator() });
+ * ```
+ *
+ * A token is refused (`Unauthenticated`) when it is malformed, signed with
+ * another algorithm or secret, expired, not yet valid, of another issuer,
+ * audience or use, or has no subject. Throws `InvalidJwtOptions` for options
+ * it cannot use, and when the secret of `{ env }` is missing or shorter than
+ * 32 characters, on the first token.
+ */
+export declare function jwtOf(options: JwtOptions): Jwt;

package/dist/core/auth/types/jwt.interface.d.ts

@@ -0,0 +1,66 @@
+import type { Authenticator } from "../../output/types/http.interface.js";
+import type { Principal } from "../../use-case/types/access.interface.js";
+/** The algorithms `jwtOf` signs and verifies with: HMAC with a shared secret. */
+export type JwtAlgorithm = "HS256" | "HS384" | "HS512";
+/** The options of `jwtOf`. JSON, so they can live in the options of a sink. */
+export interface JwtOptions {
+    /**
+     * The secret tokens are signed with: the text itself, or the name of the
+     * environment variable that holds it (`{ env: "JWT_SECRET" }`), read when
+     * the first token is signed or verified. At least 32 characters.
+     */
+    readonly secret: string | {
+        readonly env: string;
+    };
+    /** The `iss` claim: set when signing, required when verifying. */
+    readonly issuer?: string;
+    /** The `aud` claim: set when signing, required when verifying. */
+    readonly audience?: string;
+    /** The seconds a token lives: 900 (15 minutes) by default. */
+    readonly expiresIn?: number;
+    /** `"HS256"` by default. */
+    readonly algorithm?: JwtAlgorithm;
+}
+/** What a token is signed for. */
+export interface JwtSubject {
+    readonly subject: string;
+    readonly scopes?: readonly string[];
+    readonly claims?: Principal["claims"];
+}
+/** What changes for one token. */
+export interface JwtTokenOptions {
+    /** The seconds this token lives, instead of the `expiresIn` of the options. */
+    readonly expiresIn?: number;
+    /**
+     * What the token is for, e.g. `"refresh"`: kept in its `use` claim, and a
+     * token verifies only for the use it was signed for (none by default), so
+     * a refresh token is not accepted as an access token.
+     */
+    readonly use?: string;
+}
+/** Signs and verifies the tokens of one secret (see `jwtOf`). */
+export interface Jwt {
+    /** A signed token for `subject`: `sub`, `scope` (the scopes, space separated), `iat`, `exp` and the claims. */
+    sign(subject: JwtSubject, options?: JwtTokenOptions): Promise<string>;
+    /** The caller a token was signed for. Rejects with `Unauthenticated` for a token it does not accept. */
+    verify(token: string, options?: Pick<JwtTokenOptions, "use">): Promise<Principal>;
+    /**
+     * An authenticator that reads the token from the `authorization` header
+     * (`Bearer <token>`; another header with `header`) and, with `cookie`,
+     * from that cookie when the header is absent. No token is an anonymous
+     * caller; one that does not verify is refused.
+     */
+    authenticator(options?: {
+        readonly header?: string;
+        readonly cookie?: string;
+    }): Authenticator;
+}
+/**
+ * The options of `jwtOf` where they are described (`describe()`,
+ * `afora.json`): the secret is named by its environment variable.
+ */
+export interface DescribedJwtOptions extends Omit<JwtOptions, "secret"> {
+    readonly secret: {
+        readonly env: string;
+    };
+}

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

@@ -2,6 +2,11 @@
 export declare const ReservedBlueprintKey: import("../../index.js").DeclaredExceptionClass<{
     readonly key: string;
 }>;
+/** `variantOf` was given something it cannot make a field of; `reason` says what. */
+export declare const InvalidBlueprintVariant: import("../../index.js").DeclaredExceptionClass<{
+    readonly key: string;
+    readonly reason: string;
+}>;
 /** A blueprint picks a key that no plugin provides. */
 export declare const UndeclaredBlueprintProperty: import("../../index.js").DeclaredExceptionClass<{
     readonly key: string;

package/dist/core/blueprint/optional.d.ts

@@ -1,6 +1,6 @@
 import type { OptionalProperty } from "../property/types/optional-property.type.js";
 import type { AnyPropertyConstructor } from "../property/types/property-collection.type.js";
-import type { AnyBlueprint, AnyBlueprintList, AnyRecordClass, BlueprintField, OptionalBlueprint, OptionalBlueprintList, OptionalRecord } from "./types/blueprint.interface.js";
+import type { AnyBlueprint, AnyBlueprintList, AnyBlueprintVariant, AnyRecordClass, BlueprintField, OptionalBlueprint, OptionalBlueprintList, OptionalBlueprintVariant, OptionalRecord } from "./types/blueprint.interface.js";
 /**
  * The version of `Property` that accepts `undefined`. Returns `Property` itself
  * when it is already optional, and the same class for the same `Property`.
@@ -13,6 +13,8 @@ export declare function optionalOf<Property extends AnyPropertyConstructor>(Prop
 export declare function optionalOf<Blueprint extends AnyBlueprint>(blueprint: Blueprint): OptionalBlueprint<Blueprint>;
 /** The version of `list` that, as a field of a blueprint, accepts `undefined`. */
 export declare function optionalOf<List extends AnyBlueprintList>(list: List): OptionalBlueprintList<List>;
+/** The version of `variant` that, as a field of a blueprint, accepts `undefined`. */
+export declare function optionalOf<Variant extends AnyBlueprintVariant>(variant: Variant): OptionalBlueprintVariant<Variant>;
 /**
  * The version of `record` that, as a field of a blueprint, accepts `undefined`
  * or an instance of `record`. Returns `record` itself when it is already optional.

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

@@ -10,9 +10,22 @@ import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { listOf } from "../list.js";
 import type { optionalOf } from "../optional.js";
+import type { variantOf } from "../variant.js";
 import type { IBlueprintFactories, IBlueprintPlugin } from "./blueprint-plugin.interface.js";
 /** Any blueprint, whatever its properties, optional or not. */
 export type AnyBlueprint = IBlueprint<any, boolean>;
+/**
+ * Any variant field, whatever its key and its variants, optional or not.
+ * Written out, not as `IBlueprintVariant` of anything: every field of every
+ * blueprint is compared with it, and this way nothing is worked out for that.
+ */
+export interface AnyBlueprintVariant {
+    readonly [Kind]: "variant";
+    readonly key: string;
+    readonly variants: any;
+    readonly optional: boolean;
+    readonly "~standard": StandardSchemaV1.Props<any, any>;
+}
 /** Any list, whatever its item, optional or not. */
 export type AnyBlueprintList = IBlueprintList<any, boolean>;
 /**
@@ -40,9 +53,10 @@ export interface OptionalRecord<Record extends AnyRecordClass> {
 export type AnyOptionalRecord = OptionalRecord<AnyRecordClass>;
 /**
  * What a blueprint key holds: a property, a blueprint for a nested object, a
- * record, or a list of any of them.
+ * record, a list of any of them, or one of several blueprints told apart by a
+ * key.
  */
-export type BlueprintField = AnyPropertyConstructor | AnyBlueprint | AnyBlueprintList | AnyRecordClass | AnyOptionalRecord;
+export type BlueprintField = AnyPropertyConstructor | AnyBlueprint | AnyBlueprintList | AnyRecordClass | AnyOptionalRecord | AnyBlueprintVariant;
 /** Fields by key, e.g. `{ name: Name, address: Address }`. */
 export type IBlueprintCollection = Record<string, BlueprintField>;
 /** What a blueprint picks its fields from: a plugin, or another blueprint. */
@@ -66,7 +80,17 @@ type FieldSchema<Field, Mode extends FieldMode> = 0 extends 1 & Field ? TSchema
 } ? Optional extends true ? TOptional<CollectionSchema<Properties, Mode>> : CollectionSchema<Properties, Mode> : Field extends {
     readonly item: infer Item;
     readonly optional: infer Optional;
-} ? Optional extends true ? TOptional<TArray<FieldSchema<Item, Mode>>> : TArray<FieldSchema<Item, Mode>> : never;
+} ? Optional extends true ? TOptional<TArray<FieldSchema<Item, Mode>>> : TArray<FieldSchema<Item, Mode>> : VariantSchema<Field, Mode>;
+/**
+ * The schema of a variant field: its value as it is, since a union of objects
+ * is only read for whether the key is optional. Apart from `FieldSchema`, so
+ * that a field that is not a variant costs one comparison there.
+ */
+type VariantSchema<Field, Mode extends FieldMode> = Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+    readonly optional: infer Optional;
+} ? Optional extends true ? TOptional<TUnsafe<VariantValue<Key, Variants, Mode>>> : TUnsafe<VariantValue<Key, Variants, Mode>> : never;
 /** Declares the records a field of a record class takes besides its own. */
 export declare const RecordAccepts: unique symbol;
 /** The values besides its instances and plain input that a field of `Record` takes. */
@@ -102,7 +126,31 @@ type FieldValue<Field, Mode extends FieldMode> = 0 extends 1 & Field ? Static<TS
     readonly properties: infer Properties extends IBlueprintCollection;
 } ? CollectionValue<Properties, Mode> : Field extends {
     readonly item: infer Item;
-} ? FieldValue<Item, Mode>[] : never;
+} ? FieldValue<Item, Mode>[] : Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+} ? VariantValue<Key, Variants, Mode> : never;
+/**
+ * The value of a variant field: for each variant, its own value with `Key`
+ * set to its name, so that `value[Key]` tells which one it is. Anything for a
+ * field of any variants (as `AnyBlueprintVariant`'s).
+ */
+type VariantValue<Key extends string, Variants, Mode extends FieldMode> = 0 extends 1 & Variants ? any : {
+    [Tag in keyof Variants & string]: VariantMember<Key, Tag, Variants[Tag], Mode>;
+}[keyof Variants & string];
+/**
+ * The value of one variant named `Tag`. A blueprint gives its value with the
+ * key. A record class gives an instance, which has no key and is told apart
+ * by its class; what it takes is an instance or its plain input with the key,
+ * and its plain data has the key.
+ */
+type VariantMember<Key extends string, Tag, Variant, Mode extends FieldMode> = Variant extends AnyRecordClass ? Mode extends "value" ? InstanceType<Variant> : Mode extends "input" ? InstanceType<Variant> | Evaluate<{
+    readonly [Name in Key]: Tag;
+} & RecordInput<Variant>> : Evaluate<{
+    readonly [Name in Key]: Tag;
+} & RecordValueOf<Variant, "data">> : Evaluate<{
+    readonly [Name in Key]: Tag;
+} & FieldValue<Variant, Mode>>;
 /** The value of a record field, as `RecordSchema` describes it. */
 type RecordValueOf<Record extends AnyRecordClass, Mode extends FieldMode> = Mode extends "value" ? InstanceType<Record> : Mode extends "input" ? InstanceType<Record> | RecordInput<Record> | AcceptedBy<Record> : Record["blueprint"] extends IBlueprint<infer Properties, boolean> ? CollectionValue<Properties, "data"> : never;
 type ReadonlyOptionalKeys<Schemas> = {
@@ -196,6 +244,7 @@ export interface BlueprintHelpers {
     readonly listOf: typeof listOf;
     readonly optionalOf: typeof optionalOf;
     readonly propertyOf: typeof propertyOf;
+    readonly variantOf: typeof variantOf;
 }
 /**
  * What a blueprint's definition picks from: every source field, the field
@@ -223,7 +272,10 @@ export type CallableProperties<Fields> = {
  * @internal
  */
 export type OptionalProperties<Properties> = {
-    readonly [Key in keyof Properties]: Properties[Key] extends AnyPropertyConstructor ? OptionalProperty<Properties[Key]> : Properties[Key] extends AnyBlueprint ? OptionalBlueprint<Properties[Key]> : Properties[Key] extends AnyBlueprintList ? OptionalBlueprintList<Properties[Key]> : Properties[Key] extends AnyRecordClass ? OptionalRecord<Properties[Key]> : Properties[Key] extends AnyOptionalRecord ? Properties[Key] : never;
+    readonly [Key in keyof Properties]: Properties[Key] extends AnyPropertyConstructor ? OptionalProperty<Properties[Key]> : Properties[Key] extends AnyBlueprint ? OptionalBlueprint<Properties[Key]> : Properties[Key] extends AnyBlueprintList ? OptionalBlueprintList<Properties[Key]> : Properties[Key] extends AnyRecordClass ? OptionalRecord<Properties[Key]> : Properties[Key] extends AnyOptionalRecord ? Properties[Key] : Properties[Key] extends {
+        readonly key: infer Name extends string;
+        readonly variants: infer Variants extends BlueprintVariants;
+    } ? IBlueprintVariant<Name, Variants, true> : never;
 };
 export type BlueprintDefinition<Sources extends readonly BlueprintSource[], Properties extends IBlueprintCollection> = (ctx: BlueprintContext<Sources>) => Properties;
 export interface IBlueprint<Properties extends IBlueprintCollection, Optional extends boolean = false> {
@@ -288,6 +340,28 @@ export interface IBlueprintList<Item extends BlueprintField, Optional extends bo
     readonly "~standard": StandardSchemaV1.Props<ListShape<Item, "input", Optional>, ListShape<Item, "value", Optional>>;
 }
 type ListShape<Item, Mode extends FieldMode, Optional extends boolean> = Optional extends true ? FieldValue<Item, Mode>[] | undefined : FieldValue<Item, Mode>[];
+/** The variants of a variant field, by the value its key has for each: blueprints, or record classes. */
+export type BlueprintVariants = Readonly<Record<string, AnyBlueprint | AnyRecordClass>>;
+/**
+ * A field holding one of the objects of `Variants`, told apart by the value
+ * of `Key`, which is the name of the variant.
+ */
+export interface IBlueprintVariant<Key extends string, Variants extends BlueprintVariants, Optional extends boolean = false> {
+    readonly [Kind]: "variant";
+    /** The key that tells the variants apart; no variant declares it. */
+    readonly key: Key;
+    readonly variants: Variants;
+    /** Whether, as a field of a blueprint, it accepts `undefined`. */
+    readonly optional: Optional;
+    /**
+     * The Standard Schema of the field: `validate` gives the frozen value of
+     * the variant the key names, or the issues that reject the value.
+     */
+    readonly "~standard": StandardSchemaV1.Props<VariantShape<Key, Variants, "input", Optional>, VariantShape<Key, Variants, "value", Optional>>;
+}
+type VariantShape<Key extends string, Variants, Mode extends FieldMode, Optional extends boolean> = Optional extends true ? VariantValue<Key, Variants, Mode> | undefined : VariantValue<Key, Variants, Mode>;
+/** `Variant` as a field that accepts `undefined`. */
+export type OptionalBlueprintVariant<Variant extends AnyBlueprintVariant> = Variant extends IBlueprintVariant<infer Key, infer Variants, boolean> ? IBlueprintVariant<Key, Variants, true> : never;
 /** `List` as a field that accepts `undefined`. */
 export type OptionalBlueprintList<List extends AnyBlueprintList> = List extends IBlueprintList<infer Item, boolean> ? IBlueprintList<Item, true> : never;
 export {};

package/dist/core/blueprint/variant.d.ts

@@ -0,0 +1,32 @@
+import type { AnyBlueprint, AnyBlueprintVariant, BlueprintVariants, IBlueprintVariant } from "./types/blueprint.interface.js";
+/**
+ * A field holding one of several objects, told apart by the value of `key`:
+ * `variantOf("type", { click: Click, signup: Signup })` takes
+ * `{ type: "click", ...a Click }` or `{ type: "signup", ...a Signup }`. Each
+ * variant is a blueprint, which does not declare `key`: the field adds it,
+ * with the name of the variant for its value. A variant can also be a record
+ * class (an entity too): the value is then an instance of it, told apart by
+ * its class, and the key is only in what is given, in `toJSON` and in what is
+ * stored.
+ */
+export declare function variantOf<const Key extends string, const Variants extends BlueprintVariants>(key: Key, variants: Variants): IBlueprintVariant<Key, Variants>;
+/** `variant`, frozen, with the `~standard` that handles a value as `variant` does. */
+export declare function standardVariantOf<Variant extends object>(variant: Variant): Variant;
+type Variant = BlueprintVariants[string];
+/** The blueprint of a variant: itself, or that of the record class it is. */
+export declare function blueprintOfVariant(variant: Variant): AnyBlueprint;
+/**
+ * The variant that the plain `value` names with the key of `field`, if it
+ * names one: a blueprint or a record class.
+ */
+export declare function namedVariantOf(field: AnyBlueprintVariant, value: unknown): Variant | undefined;
+/** The blueprint of the variant that the plain `value` names with the key of `field`, if it names one. */
+export declare function variantOfValue(field: AnyBlueprintVariant, value: unknown): AnyBlueprint | undefined;
+/**
+ * The name of the variant `instance` is, a record of one of the classes of
+ * `field`; `undefined` when it is of none.
+ */
+export declare function variantNameOf(field: AnyBlueprintVariant, instance: unknown): string | undefined;
+/** Whether `value` is a field made by `variantOf`. */
+export declare function isBlueprintVariant(value: unknown): value is AnyBlueprintVariant;
+export {};

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>;

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

@@ -12,10 +12,42 @@ 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";
+/**
+ * The key of each stored row holding its schema version, for entities
+ * declared with `schemaVersion`; it is never a key of the entity.
+ */
+export declare const SCHEMA_VERSION_KEY = "$v";
+/** 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[] = []>(settings: 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,20 @@ 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;
+}>;
+/**
+ * The schema evolution options of an entity are invalid: `schemaVersion` is
+ * not a positive integer, a step of `upgrade` is not a function or reaches a
+ * version outside `2..schemaVersion`, or `previousNames` holds something
+ * that cannot name a record, or its own name; `source` is the entity name.
+ */
+export declare const InvalidEntitySchemaVersion: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

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

@@ -0,0 +1,24 @@
+/**
+ * Under this key, the settings of an entity builder tell when what their
+ * `generateId` and `now` make is known to be valid, so that an entity does
+ * not check again the id and the date it has just made. Only for a builder
+ * that knows its own makers, as `std` does of its defaults: a generator an
+ * application configures is never vouched for.
+ * @internal
+ */
+export declare const MakesValid: unique symbol;
+/** @internal */
+export interface ValidMakers {
+    /** Whether the id `generateId` is about to make is one `id` accepts as it is. */
+    readonly id: () => boolean;
+    /** Whether the date `now` is about to make is one `createdAt` accepts as it is. */
+    readonly createdAt: () => boolean;
+}
+/**
+ * `settings` of an entity builder with `makers` vouching for its
+ * `generateId` and `now`.
+ * @internal
+ */
+export declare function vouching<const Settings extends object>(settings: Settings, makers: ValidMakers): Settings;
+/** The makers `settings` vouch for, if any. @internal */
+export declare function validMakersOf(settings: object): ValidMakers | undefined;