@afora/core 0.0.7 → 0.0.9

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

@@ -1,16 +1,24 @@
 import { type EnvironmentDependencies, type MergedEnvironment } from "../environment/environment.js";
 import { Kind } from "../symbols/kind.js";
-import type { AnyRepository, AnyRepositoryEntity, EntityInstanceOf, IRepositoryProvider, RepositoryAction, RepositoryContext, RepositoryData, RepositoryOf as RepositoryType } from "./types/repository.interface.js";
+import type { ProviderCapabilities, RepositoryIndex, RepositoryScans } from "./types/query.interface.js";
+import type { AnyRepository, AnyRepositoryEntity, EntityInstanceOf, EntityKeyOf, IRepositoryProvider, ProviderKeyset, RepositoryAction, RepositoryContext, RepositoryData, RepositoryOf as RepositoryType } from "./types/repository.interface.js";
 /** What `repositoryOf` takes. */
-export interface RepositorySettings<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment extends EnvironmentDependencies | undefined> {
+export interface RepositorySettings<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment extends EnvironmentDependencies | undefined, Capabilities extends ProviderCapabilities = ProviderCapabilities> {
     /** The entity class whose entities it holds. */
     readonly entity: Entity;
     /** Its methods, e.g. `["findById", "findByEmail", "findManyByName", "create"]`. */
     readonly actions: Actions;
     /** Physically remove rows (default), or retain them with `deletedAt`. */
     readonly deletion?: "hard" | "soft";
-    /** How it reads and writes; a new `inMemoryProvider()` by default. */
-    readonly provider?: IRepositoryProvider<MergedEnvironment<Environment>>;
+    /**
+     * How it reads and writes; a new `inMemoryProvider()` by default. When the
+     * type of its `capabilities.keyset` cannot be `true`, the repository has no
+     * `findCursor`. Only `capabilities` is inferred, so the methods of a
+     * provider written inline keep their parameter types.
+     */
+    readonly provider?: IRepositoryProvider<MergedEnvironment<Environment>> & {
+        readonly capabilities?: Capabilities;
+    };
     /** The environments the provider gets, merged, as `context.env`. */
     readonly environmentDependencies?: Environment;
     /**
@@ -19,7 +27,25 @@ export interface RepositorySettings<Entity extends AnyRepositoryEntity, Actions
      * loaded when read.
      */
     readonly relations?: readonly AnyRepository[];
+    /**
+     * Its access patterns, by name, e.g.
+     * `{ byTypeStatus: { where: ["type", "status"], orderBy: "publishedAt" } }`:
+     * a query that matches one reads through it, and the provider gets its
+     * name as `query.index` and every index as `context.indexes`.
+     */
+    readonly indexes?: Readonly<Record<string, RepositoryIndex<EntityKeyOf<Entity>>>>;
+    /**
+     * What a query only a scan serves does: runs (`"allow"`, the default),
+     * logs `repository-scan` and runs (`"warn"`), or throws
+     * `InvalidRepositoryQuery` (`"reject"`).
+     */
+    readonly scans?: RepositoryScans;
 }
+/**
+ * The repository `repositoryOf` gives: without `findCursor` when its provider
+ * cannot read by cursor (`Keyset` is `false`).
+ */
+type RepositoryOfProvider<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment, Keyset extends boolean> = Keyset extends true ? RepositoryType<Entity, Actions, Environment> : RepositoryType<Entity, Actions, Environment, false>;
 /**
  * A repository: the base of every class `repositoryOf` makes. Its methods are
  * the actions it was declared with; extend it, through `RepositoryOf`, to add
@@ -51,19 +77,24 @@ export declare abstract class AbstractRepository<Entity extends AnyRepositoryEnt
  * A repository of `entity` with the methods of `actions`: `findBy<Key>` for a
  * unique key (`id`, `options.unique`, a `unique` property), giving the entity
  * or `undefined`; `findManyBy<Key>` for any other key, giving a list;
- * `create`, `update`, `delete`, `restore` (soft deletion only), `count`, and the queries `findMany`,
- * `exists`, `findPage` and `findCursor`. Every method is async and reads and writes through `provider`
+ * `create`, `update`, `delete`, `restore` (soft deletion only), `increment`, `count`, and the queries `findMany`,
+ * `exists`, `findPage` and `findCursor`, and `forEachPage`, which walks the
+ * pages of a cursor query, resumably. Every method is async and reads and writes through `provider`
  * (a new `inMemoryProvider()` by default), which gets the variables of
  * `environmentDependencies` as `context.env`. The repository can be a
  * dependency of a use case, and `RepositoryOf` extends it with a class.
  */
-export declare function repositoryOf<Entity extends AnyRepositoryEntity, const Actions extends readonly RepositoryAction<Entity>[], const Environment extends EnvironmentDependencies | undefined = undefined>(settings: RepositorySettings<Entity, Actions, Environment>): RepositoryType<Entity, Actions, MergedEnvironment<Environment>>;
+export declare function repositoryOf<Entity extends AnyRepositoryEntity, const Actions extends readonly RepositoryAction<Entity>[], const Environment extends EnvironmentDependencies | undefined = undefined, const Capabilities extends ProviderCapabilities = {
+    readonly keyset: true;
+}>(settings: RepositorySettings<Entity, Actions, Environment, Capabilities>): RepositoryOfProvider<Entity, Actions, MergedEnvironment<Environment>, ProviderKeyset<{
+    readonly capabilities: Capabilities;
+}>>;
 /**
  * A repository of `Entity` with the methods of `Actions`, whose provider gets
  * `Environment` as `context.env`, e.g.
  * `RepositoryOf<typeof User, ["findById", "create"]>`.
  */
-export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment = Readonly<Record<never, never>>> = RepositoryType<Entity, Actions, Environment>;
+export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment = Readonly<Record<never, never>>, Keyset extends boolean = true> = RepositoryType<Entity, Actions, Environment, Keyset>;
 /**
  * The class of `repository`, to extend: its instances share the entity,
  * actions, provider and environment of `repository`, e.g.
@@ -73,3 +104,4 @@ export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends rea
 export declare function RepositoryOf<Repository extends AnyRepository>(repository: Repository): new () => Repository;
 /** Whether `value` is a repository, made by `repositoryOf` or extending one. */
 export declare function isRepository(value: unknown): value is AnyRepository;
+export {};

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

@@ -1,4 +1,7 @@
+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";
 import type { AnyRepositoryEntity, IRepositoryProvider, RepositoryContext } from "./types/repository.interface.js";
 /** What a repository class holds, shared by the classes extending it. */
 export interface RepositoryState {
@@ -12,6 +15,12 @@ export interface RepositoryState {
     readonly environment: EnvironmentDependencies | undefined;
     /** The repository of each entity class its entities hold, at any depth. */
     readonly relations: ReadonlyMap<object, RepositoryState>;
+    /** Its declared indexes, normalized and frozen. */
+    readonly indexes: Readonly<Record<string, RepositoryIndex>>;
+    /** What it does with a query only a scan serves. */
+    readonly scans: RepositoryScans;
+    /** The logger of the application that bound it, for `scans: "warn"`. */
+    readonly logger?: ILogger;
     context?: RepositoryContext;
 }
 export declare const states: WeakMap<object, RepositoryState>;
@@ -19,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. */
@@ -26,6 +36,8 @@ export interface RepositoryInspection {
     readonly entity: AnyRepositoryEntity;
     readonly actions: readonly string[];
     readonly deletion: "hard" | "soft";
+    readonly indexes: Readonly<Record<string, RepositoryIndex>>;
+    readonly scans: RepositoryScans;
     readonly explicitProvider: boolean;
     /** The provider, only when the repository declared it. */
     readonly provider: IRepositoryProvider | undefined;
@@ -46,9 +58,27 @@ export declare function declareRepository(state: RepositoryState, repository: ob
  * @internal
  */
 export declare function relatedRepositoryOf(repository: object, Entity: object): object | undefined;
+/**
+ * Throws `RepositoryUsedOutsideApplication` when `state` is a declaration an
+ * application bound to its provider: its calls would read another store.
+ */
+export declare function assertUnbound(state: RepositoryState): void;
+/** Where the application binding a repository comes from. */
+export interface RepositoryBinding {
+    /** The name of the application. */
+    readonly application: string;
+    /** The key of the repository in the application. */
+    readonly key: string;
+    /** The logger of the application, for `scans: "warn"`. */
+    readonly logger?: ILogger;
+}
 /**
  * A repository sharing the declaration of `repository` that reads and writes
  * through `provider`, unless it declared a provider of its own; a declared
- * provider found in `instances` is replaced by its value.
+ * provider found in `instances` is replaced by its value. With `binding`,
+ * the declaration (made by `repositoryOf`) throws
+ * `RepositoryUsedOutsideApplication` from then on.
  */
-export declare function bindRepository<Repository extends object>(repository: Repository, provider: IRepositoryProvider | undefined, instances?: ReadonlyMap<object, IRepositoryProvider>): Repository;
+export declare function bindRepository<Repository extends object>(repository: Repository, provider: IRepositoryProvider | undefined, instances?: ReadonlyMap<object, IRepositoryProvider>, binding?: RepositoryBinding): Repository;
+/** The provider `repository` reads and writes through. @internal */
+export declare function providerOfRepository(repository: unknown): IRepositoryProvider | undefined;

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

@@ -22,6 +22,11 @@ export interface RepositoryQuery<Entity = unknown> {
     readonly offset?: number;
     /** Include destroyed rows; repository defaults depend on its deletion policy. */
     readonly withDeleted?: boolean;
+    /**
+     * Include expired rows, of an entity declared with `expires`; `false` by
+     * default.
+     */
+    readonly withExpired?: boolean;
 }
 /** A page and the unpaginated number of matching live (or explicitly included) rows. */
 export interface RepositoryPage<Entity> {
@@ -32,8 +37,8 @@ export interface RepositoryPage<Entity> {
 }
 /**
  * The query of `findCursor`: as `RepositoryQuery`, with the `next` of the
- * previous page as `after` in place of `offset`. `where`, `orderBy` and
- * `withDeleted` must stay the same from one page to the next.
+ * previous page as `after` in place of `offset`. `where`, `orderBy`,
+ * `withDeleted` and `withExpired` must stay the same from one page to the next.
  */
 export interface RepositoryCursorQuery<Entity = unknown> extends Omit<RepositoryQuery<Entity>, "offset" | "limit"> {
     /** Positive integer; 20 when left out. */
@@ -49,13 +54,56 @@ export interface RepositoryCursorPage<Entity> {
     readonly next: string | undefined;
 }
 /**
- * What a provider gets from `findCursor` on `findMany`: `after` holds one
+ * What a provider gets. From `findCursor` on `findMany`, `after` holds one
  * value for each order of `orderBy`, those of the last row already read, and
- * the provider gives the rows strictly after it in that order. Only a
- * provider with `capabilities.keyset` is given it.
+ * the provider gives the rows strictly after it in that order; only a
+ * provider with `capabilities.keyset` is given it. For an entity that expires
+ * (`context.expiry`), `now` is the current date and time as an ISO 8601
+ * string, from the clock of the entity: unless `withExpired`, the provider
+ * leaves out the rows whose `context.expiry.key` is at or before it.
  */
 export interface ProviderQuery extends RepositoryQuery {
     readonly after?: readonly unknown[];
+    /**
+     * The name of the declared index (`context.indexes`) that serves the
+     * query, when one does; a provider without `capabilities.indexes` can
+     * ignore it, and the rows must be the same either way.
+     */
+    readonly index?: string;
+    /** The current date and time (ISO 8601), given for entities that expire. */
+    readonly now?: string;
+}
+/**
+ * An access pattern a repository declares: queries whose `where` holds every
+ * key of `where` by equality, and whose first order (if any) is `orderBy`.
+ */
+export interface RepositoryIndex<Key extends string = string> {
+    /** The keys the query matches by equality, at least one. */
+    readonly where: readonly Key[];
+    /** The scalar key the rows are read in order of. */
+    readonly orderBy?: Key;
+}
+/**
+ * How a query reaches its rows: by `id`, by another unique key, through a
+ * declared index (named by `index`), or by reading every row (`scan`).
+ */
+export interface RepositoryPlan {
+    readonly access: "id" | "unique" | "index" | "scan";
+    /** The declared index that serves the query, when `access` is `"index"`. */
+    readonly index?: string;
+}
+/**
+ * What a repository does with a query that only a scan serves: run it
+ * (`"allow"`, the default), log `repository-scan` and run it (`"warn"`), or
+ * throw `InvalidRepositoryQuery` before the provider is called (`"reject"`).
+ */
+export type RepositoryScans = "allow" | "warn" | "reject";
+export interface RepositoryExplain<Entity> {
+    /**
+     * How the query would be read (`{ access, index? }`), without reading
+     * anything; takes the query of `findMany` or of `findCursor`.
+     */
+    explain(query?: RepositoryQuery<Entity> | RepositoryCursorQuery<Entity>): Promise<RepositoryPlan>;
 }
 export interface RepositoryFindCursor<Entity> {
     /**
@@ -65,6 +113,48 @@ export interface RepositoryFindCursor<Entity> {
      */
     findCursor(query?: RepositoryCursorQuery<Entity>): Promise<RepositoryCursorPage<Entity>>;
 }
+/** Where `forEachPage` is in its walk, given with each page. */
+export interface RepositoryWalkPage {
+    /** The position of the page in this call, from 0. */
+    readonly index: number;
+    /**
+     * The cursor after this page, `undefined` on the last: save it once the
+     * page is done to resume from the next one.
+     */
+    readonly next?: string;
+}
+/** When `forEachPage` stops before the end. */
+export interface RepositoryWalkOptions {
+    /**
+     * A deadline (a `Date` or epoch milliseconds) or a function that says when
+     * to stop; checked before each page, never while one runs.
+     */
+    readonly until?: Date | number | (() => boolean);
+}
+/** What `forEachPage` did. */
+export interface RepositoryWalkResult {
+    /** Whether it walked to the last page; `false` when `until` stopped it. */
+    readonly done: boolean;
+    /**
+     * When it stopped early, the `after` to resume from: the `next` of the
+     * last page it ran, or the `after` it was given if it ran none.
+     */
+    readonly next?: string;
+    /** The pages it ran `fn` on. */
+    readonly pages: number;
+    /** The items of those pages. */
+    readonly items: number;
+}
+export interface RepositoryForEachPage<Entity> {
+    /**
+     * Reads the pages of `query` by cursor, as `findCursor` does, and runs
+     * `fn` on each, one after the other, until the last or until `until`
+     * says to stop (checked between pages). Rows added or removed between
+     * pages, by `fn` too, are neither repeated nor skipped. An error of `fn`
+     * stops the walk and rejects; resume from the last `next` saved.
+     */
+    forEachPage(query: RepositoryCursorQuery<Entity>, fn: (items: EntityInstanceOf<Entity>[], page: RepositoryWalkPage) => unknown, options?: RepositoryWalkOptions): Promise<RepositoryWalkResult>;
+}
 export interface RepositoryFindMany<Entity> {
     findMany(query?: RepositoryQuery<Entity>): Promise<EntityInstanceOf<Entity>[]>;
 }
@@ -94,6 +184,17 @@ export interface ProviderCapabilities {
     readonly transactions?: boolean;
     /** Whether `findMany` honors `after` (`ProviderQuery`), which `findCursor` needs. */
     readonly keyset?: boolean;
+    /**
+     * Whether the provider serves the indexes a repository declares
+     * (`context.indexes`) from storage, reading `ProviderQuery.index`.
+     */
+    readonly indexes?: boolean;
+    /** Whether `update` honors an expected `version` (versioned entities, #44). */
+    readonly versioning?: boolean;
+    /** Whether the provider has an atomic `increment` (#34). */
+    readonly atomic?: boolean;
+    /** Whether reads leave out expired records (entities with `expires`, #35). */
+    readonly expiry?: boolean;
 }
 /** Declaration input for a named provider, implemented by providerOf in T10. */
 export interface ProviderSettings<Options extends ProviderOptions = ProviderOptions, Provider extends IRepositoryProvider = IRepositoryProvider> {

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

@@ -3,7 +3,8 @@ import type { AbstractEntity, EntityUniqueKeys } from "../../entity/abstract-ent
 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, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, RepositoryQuery } from "./query.interface.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[];
@@ -38,6 +39,38 @@ export interface RepositoryCreate<Entity> {
 export interface RepositoryUpdate<Entity> {
     update(entity: EntityInstanceOf<Entity>): Promise<EntityInstanceOf<Entity>>;
 }
+type ChangeKeyOf<Entity> = EntityInstanceOf<Entity> extends {
+    readonly change: infer Change;
+} ? keyof Change & string : never;
+/**
+ * The keys `increment` takes for `Entity`: those of its `change` list that
+ * hold a number.
+ */
+export type EntityIncrementKeyOf<Entity> = {
+    [Key in ChangeKeyOf<Entity>]: NonNullable<ValueAt<Entity, Key>> extends number ? Key : never;
+}[ChangeKeyOf<Entity>];
+/** What `increment` adds to each key, e.g. `{ views: 1 }`. */
+export type RepositoryIncrementDeltas<Entity> = {
+    readonly [Key in EntityIncrementKeyOf<Entity>]?: number;
+};
+/** The options of `increment`. */
+export interface RepositoryIncrementOptions<Entity> {
+    /**
+     * The input of the entity to create when the id holds none, without its
+     * `id` (the one given) and with the keys of the deltas optional (0 when
+     * left out); the deltas are added to it.
+     */
+    readonly create?: Omit<Entity extends new (value: infer Input) => unknown ? Input : never, "id" | EntityIncrementKeyOf<Entity>> & {
+        readonly [Key in EntityIncrementKeyOf<Entity>]?: number;
+    };
+}
+/**
+ * `increment`: adds the deltas to the numeric keys of the entity of the id
+ * (or the one given) in one atomic write, and gives the entity as stored.
+ */
+export interface RepositoryIncrement<Entity> {
+    increment(entity: EntityInstanceOf<Entity> | string, deltas: RepositoryIncrementDeltas<Entity>, options?: RepositoryIncrementOptions<Entity>): Promise<EntityInstanceOf<Entity>>;
+}
 /** `delete`: destroys the entity (or the one of the id), removes it and gives it. */
 export interface RepositoryDelete<Entity> {
     delete(entity: EntityInstanceOf<Entity> | string): Promise<EntityInstanceOf<Entity>>;
@@ -74,19 +107,60 @@ export type RepositoryFindManyBy<Entity, Actions extends string = string> = {
  * so that a class extending a repository can override them.
  * @internal
  */
-export type RepositoryMethods<Entity, Actions extends string = string> = RepositoryFindBy<Entity, Actions> & RepositoryFindManyBy<Entity, Actions> & ("create" extends Actions ? RepositoryCreate<Entity> : unknown) & ("update" extends Actions ? RepositoryUpdate<Entity> : unknown) & ("delete" extends Actions ? RepositoryDelete<Entity> : unknown) & ("restore" extends Actions ? RepositoryRestore<Entity> : unknown) & ("count" extends Actions ? RepositoryCount<Entity> : unknown) & ("findMany" extends Actions ? RepositoryFindMany<Entity> : unknown) & ("exists" extends Actions ? RepositoryExists<Entity> : unknown) & ("findPage" extends Actions ? RepositoryFindPage<Entity> : unknown) & ("findCursor" extends Actions ? RepositoryFindCursor<Entity> : unknown);
+export type RepositoryMethods<Entity, Actions extends string = string> = RepositoryFindBy<Entity, Actions> & RepositoryFindManyBy<Entity, Actions> & ("create" extends Actions ? RepositoryCreate<Entity> : unknown) & ("update" extends Actions ? RepositoryUpdate<Entity> : unknown) & ("delete" extends Actions ? RepositoryDelete<Entity> : unknown) & ("restore" extends Actions ? RepositoryRestore<Entity> : unknown) & ("increment" extends Actions ? RepositoryIncrement<Entity> : unknown) & ("count" extends Actions ? RepositoryCount<Entity> : unknown) & ("findMany" extends Actions ? RepositoryFindMany<Entity> : unknown) & ("exists" extends Actions ? RepositoryExists<Entity> : unknown) & ("findPage" extends Actions ? RepositoryFindPage<Entity> : unknown) & ("findCursor" extends Actions ? RepositoryFindCursor<Entity> : unknown) & ("explain" extends Actions ? RepositoryExplain<Entity> : unknown) & ("forEachPage" extends Actions ? RepositoryForEachPage<Entity> : unknown);
 /** A method a repository of `Entity` can have, e.g. `"findByEmail"`. */
-export type RepositoryAction<Entity> = keyof RepositoryFindBy<Entity> | keyof RepositoryFindManyBy<Entity> | "create" | "update" | "delete" | "restore" | "count" | "findMany" | "exists" | "findPage" | "findCursor";
+export type RepositoryAction<Entity> = keyof RepositoryFindBy<Entity> | keyof RepositoryFindManyBy<Entity> | "create" | "update" | "delete" | "restore" | "increment" | "count" | "findMany" | "exists" | "findPage" | "findCursor" | "explain" | "forEachPage";
+/**
+ * Whether a repository given `Provider` keeps `findCursor`: `false` when the
+ * type of its `capabilities.keyset` cannot be `true` (left out of the
+ * capabilities, or `false`), `true` for `true`, for a wide `boolean`, and
+ * with no provider (the default in-memory one reads by cursor). `repositoryOf`
+ * infers only the `capabilities` of a provider: one without them keeps
+ * `findCursor` in the type and is rejected at declaration.
+ */
+export type ProviderKeyset<Provider> = undefined extends Provider ? true : Provider extends {
+    readonly capabilities?: infer Capabilities;
+} ? [NonNullable<Capabilities>] extends [{
+    readonly keyset?: infer Keyset;
+}] ? true extends Keyset ? true : false : false : false;
 /**
  * A repository of `Entity` with the methods of `Actions`, whose provider gets
  * `Environment` as `context.env`, e.g.
  * `RepositoryOf<typeof User, ["findById", "create"]>`.
  */
-export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment = Readonly<Record<never, never>>> = AbstractRepository<Entity, Actions, Environment> & RepositoryMethods<Entity, Actions[number]>;
+export type RepositoryOf<Entity extends AnyRepositoryEntity, Actions extends readonly RepositoryAction<Entity>[], Environment = Readonly<Record<never, never>>, Keyset extends boolean = true> = AbstractRepository<Entity, Actions, Environment> & RepositoryMethods<Entity, Keyset extends true ? Actions[number] : Exclude<Actions[number], "findCursor">>;
 /** Any repository, whatever its entity, actions and environment. */
 export type AnyRepository = AbstractRepository<any, any, any>;
 /** A value of an entity as a provider stores it: plain, unmasked. */
 export type RepositoryData = Readonly<Record<string, unknown>>;
+/** What `update` of a provider gets after the data. */
+export interface ProviderUpdateOptions {
+    /** The `version` the stored row must hold for the write to happen. */
+    readonly expectedVersion?: number;
+}
+/** What `increment` of a provider gets after the deltas. */
+export interface ProviderIncrementOptions {
+    /** Values stored as they are by the same write, e.g. `updatedAt`. */
+    readonly set?: RepositoryData;
+    /**
+     * The row to insert when the id holds none, or holds one that expired
+     * (which it replaces).
+     */
+    readonly create?: RepositoryData;
+    /**
+     * For an entity that expires (`context.expiry`), the current date and
+     * time (ISO 8601) by the clock of the entity: a row whose expiry is at or
+     * before it counts as absent. A provider called without it uses the
+     * current time.
+     */
+    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`. */
@@ -98,6 +172,28 @@ export interface RepositoryContext<Environment = unknown> {
     readonly name: string;
     /** The keys no two entities may share, `id` first. */
     readonly unique: readonly string[];
+    /**
+     * The indexes the repository declares, by name, for a provider to build
+     * (a GSI, an SQL index); a repository always gives it, empty when it
+     * declares none (optional for contexts built by hand).
+     */
+    readonly indexes?: Readonly<Record<string, RepositoryIndex>>;
+    /**
+     * For an entity declared with `expires`, the key holding the date at which
+     * a record expires (`expiresAt`, or the key of `at`): reads leave out the
+     * records whose date is at or before `query.now`, unless
+     * `query.withExpired`. A record without a date never expires.
+     */
+    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;
 }
@@ -107,17 +203,53 @@ 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?: RepositoryQuery): Promise<RepositoryData | undefined>;
+    findOne(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<RepositoryData | undefined>;
     /** `query.after` is only given to a provider with `capabilities.keyset`. */
     findMany(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<readonly RepositoryData[]>;
     insert(context: RepositoryContext<Environment>, data: RepositoryData): Promise<void>;
-    update(context: RepositoryContext<Environment>, data: RepositoryData): Promise<void>;
+    /**
+     * With `options.expectedVersion`, writes only when the stored `version` is
+     * that one, and throws `RepositoryConcurrencyConflict` otherwise; only a
+     * provider with `capabilities.versioning` is given it.
+     */
+    update(context: RepositoryContext<Environment>, data: RepositoryData, options?: ProviderUpdateOptions): Promise<void>;
     remove(context: RepositoryContext<Environment>, id: string): Promise<void>;
-    count(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<number>;
+    /**
+     * Adds each of `deltas` to the stored number of its key (a missing one
+     * counts as 0) and stores `options.set` in the same atomic write, then
+     * gives the row as stored. Only rows that are not soft-deleted, nor expired
+     * (`context.expiry`, at `options.now`), match. When the id holds none (or
+     * an expired one), inserts `options.create` as it is, replacing the expired
+     * row, and gives it, or throws `RepositoryEntityNotFound` without it; a
+     * concurrent insert of the same id still gets the deltas added. A
+     * soft-deleted row with `create` is a `RepositoryUniqueViolation` on `id`.
+     * Advertised by `capabilities.atomic`.
+     */
+    increment?(context: RepositoryContext<Environment>, id: string, deltas: Readonly<Record<string, number>>, options?: ProviderIncrementOptions): Promise<RepositoryData>;
+    count(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<number>;
     readonly capabilities?: ProviderCapabilities;
     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>>;
+}