@afora/core 0.0.8 → 0.0.9

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

@@ -18,6 +18,15 @@ export declare function isPlainObject(value: unknown): value is Record<string, u
  * 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/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,6 +18,19 @@ 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. */

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

@@ -13,8 +13,8 @@ export type InMemoryProvider = IRepositoryProvider & {
     };
 };
 /**
- * A provider that keeps the values in memory, one table per entity class,
- * enforcing its unique keys. Each `repositoryOf` without a provider gets its
+ * 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

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/state.d.ts

@@ -1,3 +1,4 @@
+import { SCHEMA_VERSION_KEY } from "../entity/abstract-entity.js";
 import { type EnvironmentDependencies } from "../environment/environment.js";
 import type { ILogger } from "../logger/logger.js";
 import type { RepositoryIndex, RepositoryScans } from "./types/query.interface.js";
@@ -27,6 +28,7 @@ export declare const states: WeakMap<object, RepositoryState>;
 export declare function findState(repository: unknown): RepositoryState | undefined;
 /** The state of the repository class of `repository`, or of a class it extends. */
 export declare function stateOf(repository: object): RepositoryState;
+export { SCHEMA_VERSION_KEY };
 /** The context of the provider, with the environment read on first use. */
 export declare function contextOf(state: RepositoryState): RepositoryContext;
 /** What an application reads from a repository, without reaching its state. */

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

@@ -4,6 +4,7 @@ import type { AnyEntityClass } from "../../entity/event.js";
 import type { RecordSettings } from "../../record/types/record.interface.js";
 import type { AbstractRepository } from "../repository.js";
 import type { ProviderCapabilities, ProviderQuery, RepositoryExists, RepositoryExplain, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, RepositoryForEachPage, RepositoryIndex, RepositoryQuery } from "./query.interface.js";
+import type { SchemaPlan } from "./schema.interface.js";
 /** Any class made by `entityOf`, or extending one, that a repository holds. */
 export type AnyRepositoryEntity = AnyRecordClass & AnyEntityClass & {
     readonly [EntityUniqueKeys]: readonly string[];
@@ -154,6 +155,12 @@ export interface ProviderIncrementOptions {
      */
     readonly now?: string;
 }
+/** `RepositoryContext.schema`. */
+export interface RepositorySchema {
+    readonly version: number;
+    readonly key: string;
+    readonly previousNames: readonly string[];
+}
 /** What a provider gets with every call: whose entities, and the environment. */
 export interface RepositoryContext<Environment = unknown> {
     /** The entity class; name a table after `recordNameOf(entity)`, not `entity.name`. */
@@ -180,6 +187,13 @@ export interface RepositoryContext<Environment = unknown> {
     readonly expiry?: {
         readonly key: string;
     };
+    /**
+     * For an entity declared with `schemaVersion`: the current version, the
+     * key of each row holding it (`SCHEMA_VERSION_KEY`, which repositories
+     * write and strip, so a provider keeping it in a column of its own maps
+     * that key), and the names the entity had before.
+     */
+    readonly schema?: RepositorySchema;
     /** The variables of the `environmentDependencies` of the repository. */
     readonly env: Environment;
 }
@@ -189,6 +203,14 @@ export interface RepositoryContext<Environment = unknown> {
  * `RepositoryUniqueViolation`; `update` and `remove` throw
  * `RepositoryEntityNotFound` for an unknown id.
  */
+/**
+ * What `IRepositoryProvider.migrate` gives when it did not apply the plan to
+ * the store (it wrote it to a file to be run later): `app.migrate` skips the
+ * backfill of the entity and reports it `deferred`.
+ */
+export type ProviderMigrationResult = {
+    readonly deferred: true;
+};
 export interface IRepositoryProvider<Environment = unknown> {
     findOne(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<RepositoryData | undefined>;
     /** `query.after` is only given to a provider with `capabilities.keyset`. */
@@ -218,5 +240,16 @@ export interface IRepositoryProvider<Environment = unknown> {
     transaction?<Result>(run: (provider: IRepositoryProvider<Environment>) => Promise<Result>): Promise<Result>;
     /** Releases what the provider holds (connections, files); `app.stop()` calls it. */
     close?(): void | Promise<void>;
+    /**
+     * Applies the structural part of `plan` (columns, tables) for a provider
+     * with a schema of its own, as SQL; `app.migrate({ mode: "apply" })` calls
+     * it before the backfill. Document stores leave it out: they rely on the
+     * upgrade on read and the backfill. Only destructive changes when
+     * `plan.destructive`. Gives `{ deferred: true }` when it did not apply
+     * the plan to the store (it wrote it to a file to be run later): the
+     * backfill of the entity is then skipped, as its rows cannot be written
+     * in the new shape yet.
+     */
+    migrate?(context: RepositoryContext<Environment>, plan: SchemaPlan): Promise<void | ProviderMigrationResult>;
 }
 export {};

package/dist/core/repository/types/schema.interface.d.ts

@@ -0,0 +1,126 @@
+import type { Issue } from "../../parse/types/parse.interface.js";
+/**
+ * Schema evolution: the lock of the stored shapes, the changes between two of
+ * them, and the plan a provider applies (`IRepositoryProvider.migrate`).
+ */
+/** What a change between two shapes is. */
+export type SchemaChangeKind = "added-required" | "added-optional" | "removed" | "renamed" | "type-changed" | "tightened" | "loosened" | "made-optional" | "made-required" | "metadata" | "unique-added" | "unique-removed" | "entity-added" | "entity-removed" | "entity-renamed";
+/**
+ * Whether afora handles a change alone (`automatic`), needs it declared
+ * (`fill`, `renamedFrom`, `previousNames`, an `upgrade` step: `declared`), or
+ * needs the stored rows checked before it holds (`check`).
+ */
+export type SchemaChangeClass = "automatic" | "declared" | "check";
+/** One change of an entity between the lock and the code. */
+export interface SchemaChange {
+    /** The entity, by its current name (its previous one when removed). */
+    readonly entity: string;
+    /** The path of the key, dot separated for nested blueprints; absent for the entity itself. */
+    readonly key?: string;
+    readonly change: SchemaChangeKind;
+    readonly class: SchemaChangeClass;
+    /** Whether the code declares what the change needs (always true when `automatic`). */
+    readonly satisfied: boolean;
+    /** Whether applying it deletes stored data (a removed key, the rows of an old name). */
+    readonly destructive: boolean;
+    /** For `renamed` and `entity-renamed`, the old name. */
+    readonly from?: string;
+    /** What is missing or what to check, for messages and stubs. */
+    readonly detail?: string;
+}
+/** A key of an entity in the lock. */
+export interface SchemaLockField {
+    /** The JSON Schema of the value. */
+    readonly schema: Readonly<Record<string, unknown>>;
+    readonly optional: boolean;
+    readonly unique?: boolean;
+    readonly fill?: unknown;
+    readonly renamedFrom?: string;
+    /** The keys of a nested blueprint or record. */
+    readonly fields?: Readonly<Record<string, SchemaLockField>>;
+}
+/** An entity in the lock. */
+export interface SchemaLockEntity {
+    readonly schemaVersion: number;
+    readonly previousNames: readonly string[];
+    readonly unique: readonly string[];
+    readonly fields: Readonly<Record<string, SchemaLockField>>;
+    /**
+     * The versions its `upgrade` has a step to, ascending; absent when none.
+     * `diffSchemas` reads it from the current side to tell whether a change
+     * that needs a step has one.
+     */
+    readonly upgrade?: readonly number[];
+}
+/** `afora.lock.json`: the stored shapes, by entity name, normalized. */
+export interface SchemaLock {
+    readonly lockVersion: 1;
+    readonly entities: Readonly<Record<string, SchemaLockEntity>>;
+}
+/** What `IRepositoryProvider.migrate` gets: the changes of one entity. */
+export interface SchemaPlan {
+    /** The entity, by its current name. */
+    readonly entity: string;
+    readonly changes: readonly SchemaChange[];
+    /** Whether destructive changes may be applied (`app.migrate({ destructive })`). */
+    readonly destructive: boolean;
+}
+/** What `app.migrate` takes. */
+export interface SchemaMigrationOptions {
+    /** The entities to walk, by name; every entity with a repository by default. */
+    readonly entities?: readonly string[];
+    /** `check` only reads and reports; `apply` rewrites the rows. */
+    readonly mode: "check" | "apply";
+    /**
+     * Remove the keys the blueprints no longer declare from the stored rows,
+     * and the rows under `previousNames` once moved. Default `false`.
+     */
+    readonly destructive?: boolean;
+    /** Rows read per page. Default 100. */
+    readonly pageSize?: number;
+    /**
+     * The committed lock (`afora.lock.json`): in `apply`, the changes of each
+     * entity from it to the code are the plan given to
+     * `IRepositoryProvider.migrate`. Without it the plan has no changes.
+     */
+    readonly lock?: SchemaLock;
+}
+/** A row `app.migrate` cannot bring up to the current shape. */
+export interface SchemaMigrationInvalidRow {
+    readonly id: string;
+    /** Why: the issues of the parse, or one for an error of the upgrade. */
+    readonly issues: readonly Issue[];
+}
+/** What `app.migrate` found and did for one entity. */
+export interface EntityMigrationReport {
+    /** Rows read, under the current name and the previous ones. */
+    readonly scanned: number;
+    /** Rows that needed nothing. */
+    readonly upToDate: number;
+    /** Rows rewritten in the current shape (in `check`, that would be). */
+    readonly upgraded: number;
+    /**
+     * Rows whose only pending change is removing keys, left as they are
+     * without `destructive`.
+     */
+    readonly removalPending: number;
+    /** Rows the entity rejects once brought up, left as they are. */
+    readonly invalid: readonly SchemaMigrationInvalidRow[];
+    /** Rows moved from a previous name (in `check`, that would be). */
+    readonly movedFromPreviousNames: number;
+    /** Paths of the stored keys the blueprint no longer declares, sorted. */
+    readonly removedKeys: readonly string[];
+    /**
+     * Whether `provider.migrate` deferred the plan (`{ deferred: true }`, it
+     * wrote it to be run later): the rows were then not walked, and every
+     * count is 0. Run `app.migrate` again once the plan is applied.
+     */
+    readonly deferred: boolean;
+}
+/** What `app.migrate` gives. */
+export interface SchemaMigrationReport {
+    readonly mode: "check" | "apply";
+    readonly destructive: boolean;
+    /** By entity name. */
+    readonly entities: Readonly<Record<string, EntityMigrationReport>>;
+}

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

@@ -0,0 +1,64 @@
+import type { EntityUpgrades } from "../entity/types/entity.interface.js";
+import type { RepositoryState } from "./state.js";
+import type { RepositoryData } from "./types/repository.interface.js";
+/** What happens to the value of one key of a collection. */
+type FieldStep = {
+    readonly kind: "property";
+    readonly fill?: unknown;
+    readonly renamedFrom?: string;
+} | {
+    readonly kind: "collection";
+    readonly fields: CollectionSteps;
+} | {
+    readonly kind: "list";
+    readonly item: FieldStep;
+} | {
+    readonly kind: "opaque";
+};
+/** The steps of the keys of a blueprint, and whether any of them does something. */
+interface CollectionSteps {
+    readonly fields: ReadonlyMap<string, FieldStep>;
+}
+/** How the rows of an entity are brought up to its current shape. */
+export interface UpcastPlan {
+    readonly versioned: boolean;
+    readonly version: number;
+    /** Whether the entity lists `previousNames`: its moved rows may hold old keys. */
+    readonly renamed: boolean;
+    readonly upgrade: EntityUpgrades;
+    readonly fields: CollectionSteps;
+}
+/** What `upcast` did to a row, for `app.migrate`. */
+export interface UpcastReport {
+    /** The version the row was stored at (1 without the version key). */
+    from: number;
+    /** Paths of the keys moved from their `renamedFrom`. */
+    readonly renamed: string[];
+    /** Paths of the keys given their `fill`. */
+    readonly filled: string[];
+    /** Paths of the keys the blueprint no longer declares. */
+    readonly removed: string[];
+}
+/** The plan of `entity`, even when it changes nothing but the keys it no longer declares. */
+export declare function fullUpcastPlanOf(entity: object): UpcastPlan;
+/**
+ * `data`, a row of an entity of `plan` as a provider gave it, in the current
+ * shape: without the version key, through each `upgrade` step from the
+ * version after the stored one up to `schemaVersion`, then the automatic
+ * steps of the current blueprint (`renamedFrom`, `fill`, and, with `drop`,
+ * leaving out keys it no longer declares). The steps run first because each
+ * is written against the shape of the version before it, which the
+ * automatic steps would already have changed. Throws
+ * `InvalidStoredSchemaVersion` for a version that is not a positive integer
+ * or is above `schemaVersion`.
+ */
+export declare function upcast(source: string, plan: UpcastPlan, data: RepositoryData, drop?: boolean, report?: UpcastReport): RepositoryData;
+/**
+ * `rows` of `state`'s entity in its current shape (see `upcast`); `rows`
+ * itself when the entity needs nothing. Throws `InvalidRepositoryData`
+ * caused by `InvalidStoredSchemaVersion` for a row it cannot bring up.
+ */
+export declare function upcastRows(state: RepositoryState, rows: readonly RepositoryData[]): readonly RepositoryData[];
+/** `data` with the version key of `state`'s entity, when it declares `schemaVersion`. */
+export declare function withSchemaVersion(entity: object, data: RepositoryData): RepositoryData;
+export {};

package/dist/core/schema/schema.d.ts

@@ -5,6 +5,34 @@ export declare function describeError(error: {
     instancePath: string;
     message: string;
 }): string;
+/** One TypeBox error, as `Errors` gives it. */
+export interface SchemaError {
+    readonly keyword: string;
+    readonly schemaPath: string;
+    readonly instancePath: string;
+    readonly params: object;
+    readonly message: string;
+}
+/**
+ * The errors of `value`, which `schema` rejects. For every schema but one
+ * they are what `schema.type.Errors(value)` gives: same errors, same order,
+ * same messages. The one is a discriminated union given an object, told by
+ * the variant its key names (see `errorsOfVariant`). TypeBox is only asked
+ * about a schema with a keyword that has no explanation here (`explainerOf`).
+ * @internal
+ */
+export declare function errorsOfSchema(schema: ISchema<TSchema>, value: unknown): readonly SchemaError[];
+/** The two checks of a schema, as functions. */
+export interface SchemaChecks {
+    match(value: unknown): boolean;
+    matchShape(value: unknown): boolean;
+}
+/**
+ * `schema.match` and `schema.matchShape`, compiled now, for who checks many
+ * values with one schema; those of a schema not made by `schemaOf` call it.
+ * @internal
+ */
+export declare function checksOfSchema(schema: ISchema<TSchema>): SchemaChecks;
 /** A schema class declared with `schemaOf`. */
 export interface SchemaClass<SchemaType extends TSchema> {
     new (type?: SchemaType): ISchema<SchemaType>;

package/dist/core/symbols/kind.d.ts

@@ -1,2 +1,2 @@
-/** Brands blueprints, lists and records, so none is told apart by its shape. */
+/** Brands blueprints, lists, variants and records, so none is told apart by its shape. */
 export declare const Kind: unique symbol;

package/dist/core/use-case/access.d.ts

@@ -0,0 +1,12 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { AccessDeclaration } from "./types/access.interface.js";
+/** Whether `access` lets anyone in. */
+export declare function isPublicAccess(access: AccessDeclaration): access is {
+    readonly public: true;
+};
+/**
+ * The frozen declaration of `access` for a use case whose input is
+ * `blueprint`, or the reason it is not valid. The keys of `context` are
+ * checked where the context is known: when the use case becomes an operation.
+ */
+export declare function accessDeclarationOf(access: unknown, blueprint: AnyBlueprint): AccessDeclaration | string;

package/dist/core/use-case/decorators.d.ts

@@ -0,0 +1,40 @@
+import type { AccessDeclaration } from "./types/access.interface.js";
+import type { RouteSettings } from "./types/route.interface.js";
+/** What a decorator of this module is given besides the class: nothing it reads. */
+type ClassContext = {
+    readonly kind: string;
+};
+/** A class decorator for use cases, in the standard form and in the legacy one of TypeScript. */
+export type UseCaseDecorator = <UseCase extends abstract new (...args: any[]) => unknown>(value: UseCase, context?: ClassContext) => void;
+/**
+ * Says where a use case is served over HTTP, on the class itself:
+ *
+ * ```ts
+ * @Route("GET", "/posts/{slug}", { query: ["page"], cookie: { session: "sid" } })
+ * class ListPosts extends useCaseOf({ name: "ListPosts", blueprint, response }) {}
+ * ```
+ *
+ * The same as the `route` setting of `useCaseOf` (see `RouteDeclaration`), so
+ * `describe()`, the sinks and `afora.json` see one declaration. It names no
+ * server: the sink of an output does. Throws `InvalidUseCaseDeclaration` on
+ * a class that is not a use case, on one that already has another route
+ * (the same one again is accepted), and for a route that does not fit the
+ * input of the use case.
+ */
+export declare function Route(method: RouteSettings["method"], path?: string, options?: Omit<RouteSettings, "method" | "path">): UseCaseDecorator;
+export declare function Route(method: RouteSettings["method"], options?: Omit<RouteSettings, "method" | "path">): UseCaseDecorator;
+/**
+ * Says who may call a use case, on the class itself:
+ *
+ * ```ts
+ * @Access({ scopes: ["posts:write"], context: { userId: "subject" } })
+ * class PublishPost extends useCaseOf({ name: "PublishPost", blueprint, response, context }) {}
+ * ```
+ *
+ * The same as the `access` setting of `useCaseOf` (see `AccessDeclaration`).
+ * Throws `InvalidUseCaseDeclaration` on a class that is not a use case, on
+ * one that already declares another access (the same one again is accepted),
+ * and for a declaration that does not fit the input of the use case.
+ */
+export declare function Access(access: AccessDeclaration): UseCaseDecorator;
+export {};

package/dist/core/use-case/route.d.ts

@@ -0,0 +1,18 @@
+import type { AnyBlueprint } from "../blueprint/types/blueprint.interface.js";
+import type { OpenAPISchema } from "../openapi/types/openapi.interface.js";
+import type { RouteDeclaration } from "./types/route.interface.js";
+/** A header name (an HTTP token), which a cookie name is too. */
+export declare const HEADER_NAME: RegExp;
+/** A path such as `/entries/{slug}`: `{name}` only as a whole segment, no `:`, `*`, query or spaces. */
+export declare function isRoutePath(value: unknown, parameters?: boolean): value is string;
+/** The names of the `{name}` segments of `path`, in order. */
+export declare function parametersOfPath(path: string): string[];
+/** Whether a JSON Schema describes a value that is neither an object nor a list. */
+export declare function isScalarSchema(schema: OpenAPISchema): boolean;
+/** Whether `name` is a key of `blueprint` that is a scalar property (no object, no list). */
+export declare function isScalarKey(blueprint: AnyBlueprint, name: string): boolean;
+/**
+ * The frozen, normalized declaration of `route` for a use case whose input is
+ * `blueprint` (the method in lower case), or the reason it is not valid.
+ */
+export declare function routeDeclarationOf(route: unknown, blueprint: AnyBlueprint, response: AnyBlueprint): RouteDeclaration | string;