@afora/core 0.0.7 → 0.0.8

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,7 @@ 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";
 /** Any class made by `entityOf`, or extending one, that a repository holds. */
 export type AnyRepositoryEntity = AnyRecordClass & AnyEntityClass & {
     readonly [EntityUniqueKeys]: readonly string[];
@@ -38,6 +38,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 +106,54 @@ 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;
+}
 /** 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 +165,21 @@ 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;
+    };
     /** The variables of the `environmentDependencies` of the repository. */
     readonly env: Environment;
 }
@@ -108,13 +190,30 @@ export interface RepositoryContext<Environment = unknown> {
  * `RepositoryEntityNotFound` for an unknown id.
  */
 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. */

package/dist/experimental.js

@@ -6,11 +6,11 @@ import {
   listOf2,
   isBlueprintList2,
   AbstractRecord2,
-  declareRecord,
-  optionalOf2,
   UndeclaredBlueprintProperty2,
-  blueprintFromProperties
-} from "./index-r78dsvtc.js";
+  optionalOf2,
+  blueprintFromProperties,
+  declareRecord
+} from "./index-qxfkyd6k.js";
 
 // src/core/blueprint/slice.ts
 function propertiesOfField(field) {