@afora/core 0.0.5 → 0.0.6

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

@@ -52,7 +52,7 @@ export declare abstract class AbstractRepository<Entity extends AnyRepositoryEnt
  * 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`, `count`, and the queries `findMany`,
- * `exists` and `findPage`. Every method is async and reads and writes through `provider`
+ * `exists`, `findPage` and `findCursor`. 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.

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

@@ -30,6 +30,41 @@ export interface RepositoryPage<Entity> {
     readonly limit: number;
     readonly offset: number;
 }
+/**
+ * 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.
+ */
+export interface RepositoryCursorQuery<Entity = unknown> extends Omit<RepositoryQuery<Entity>, "offset" | "limit"> {
+    /** Positive integer; 20 when left out. */
+    readonly limit?: number;
+    /** The `next` of the page before; the first page when left out. */
+    readonly after?: string;
+}
+/** A page read by position: its items and, when there are more, the cursor of the next. */
+export interface RepositoryCursorPage<Entity> {
+    readonly items: readonly EntityInstanceOf<Entity>[];
+    readonly limit: number;
+    /** What to give as `after` for the next page; `undefined` on the last one. */
+    readonly next: string | undefined;
+}
+/**
+ * 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.
+ */
+export interface ProviderQuery extends RepositoryQuery {
+    readonly after?: readonly unknown[];
+}
+export interface RepositoryFindCursor<Entity> {
+    /**
+     * A page of `limit` items (20 by default) after the cursor `after`. Unlike
+     * `findPage` it reads one page with one query, does not count, and stays
+     * correct when rows are added or removed between pages.
+     */
+    findCursor(query?: RepositoryCursorQuery<Entity>): Promise<RepositoryCursorPage<Entity>>;
+}
 export interface RepositoryFindMany<Entity> {
     findMany(query?: RepositoryQuery<Entity>): Promise<EntityInstanceOf<Entity>[]>;
 }
@@ -57,6 +92,8 @@ export type ProviderDescription = {
 export interface ProviderCapabilities {
     readonly operators?: readonly string[];
     readonly transactions?: boolean;
+    /** Whether `findMany` honors `after` (`ProviderQuery`), which `findCursor` needs. */
+    readonly keyset?: 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, RepositoryExists, RepositoryFindMany, RepositoryFindPage, RepositoryQuery } from "./query.interface.js";
+import type { ProviderCapabilities, ProviderQuery, RepositoryExists, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, 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[];
@@ -67,9 +67,9 @@ 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) & ("count" extends Actions ? RepositoryCount<Entity> : unknown) & ("findMany" extends Actions ? RepositoryFindMany<Entity> : unknown) & ("exists" extends Actions ? RepositoryExists<Entity> : unknown) & ("findPage" extends Actions ? RepositoryFindPage<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) & ("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);
 /** A method a repository of `Entity` can have, e.g. `"findByEmail"`. */
-export type RepositoryAction<Entity> = keyof RepositoryFindBy<Entity> | keyof RepositoryFindManyBy<Entity> | "create" | "update" | "delete" | "count" | "findMany" | "exists" | "findPage";
+export type RepositoryAction<Entity> = keyof RepositoryFindBy<Entity> | keyof RepositoryFindManyBy<Entity> | "create" | "update" | "delete" | "count" | "findMany" | "exists" | "findPage" | "findCursor";
 /**
  * A repository of `Entity` with the methods of `Actions`, whose provider gets
  * `Environment` as `context.env`, e.g.
@@ -82,9 +82,12 @@ export type AnyRepository = AbstractRepository<any, any, any>;
 export type RepositoryData = Readonly<Record<string, unknown>>;
 /** What a provider gets with every call: whose entities, and the environment. */
 export interface RepositoryContext<Environment = unknown> {
-    /** The entity class, e.g. to name a table after it. */
+    /** The entity class; name a table after `recordNameOf(entity)`, not `entity.name`. */
     readonly entity: AnyRepositoryEntity;
-    /** The name of the repository, for the source of its exceptions. */
+    /**
+     * The name of the repository, `<entity name>Repository`, for the source of
+     * its exceptions; stable under minification when the entity declares a `name`.
+     */
     readonly name: string;
     /** The keys no two entities may share, `id` first. */
     readonly unique: readonly string[];
@@ -99,7 +102,8 @@ export interface RepositoryContext<Environment = unknown> {
  */
 export interface IRepositoryProvider<Environment = unknown> {
     findOne(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<RepositoryData | undefined>;
-    findMany(context: RepositoryContext<Environment>, query?: RepositoryQuery): Promise<readonly RepositoryData[]>;
+    /** `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>;
     remove(context: RepositoryContext<Environment>, id: string): Promise<void>;

package/dist/core/use-case/steps/types/steps.interface.d.ts

@@ -11,7 +11,7 @@ export type StepValue = StepReference | string | number | boolean | null | reado
     readonly [key: string]: StepValue;
 };
 /** The actions of a repository that only read. */
-export type StepReadAction = `findBy${string}` | `findManyBy${string}` | "findMany" | "exists" | "findPage" | "count";
+export type StepReadAction = `findBy${string}` | `findManyBy${string}` | "findMany" | "exists" | "findPage" | "findCursor" | "count";
 type RepositoryKeys<Dependencies> = {
     [Key in keyof Dependencies & string]: Dependencies[Key] extends AnyRepository ? Key : never;
 }[keyof Dependencies & string];

package/dist/experimental.js

@@ -2,6 +2,7 @@ import {
   isBlueprint2,
   isRecordClass2,
   recordFieldOf2,
+  recordNameOf2,
   listOf2,
   isBlueprintList2,
   AbstractRecord2,
@@ -9,7 +10,7 @@ import {
   UndeclaredBlueprintProperty2,
   optionalOf2,
   blueprintFromProperties
-} from "./index-hn82hm31.js";
+} from "./index-3nd9bjnc.js";
 
 // src/core/blueprint/slice.ts
 function propertiesOfField(field) {
@@ -69,7 +70,7 @@ function slicedRecordOf(Original, mask, path) {
     sensitive: kept(sensitive),
     unique: kept(unique),
     change: kept(change)
-  }, Original.name);
+  }, recordNameOf2(Original));
   Object.defineProperty(Sliced, Symbol.hasInstance, {
     value(value) {
       return Function.prototype[Symbol.hasInstance].call(this, value) || value instanceof Original;

package/dist/{index-hn82hm31.js → index-3nd9bjnc.js}

@@ -17,6 +17,7 @@ var __export = (target, all) => {
 var exports_exceptions = {};
 __export(exports_exceptions, {
   IncompatibleRecordPlugin: () => IncompatibleRecordPlugin2,
+  InvalidRecordDeclaration: () => InvalidRecordDeclaration2,
   InvalidRecordPlugin: () => InvalidRecordPlugin2,
   InvalidRecordValue: () => InvalidRecordValue2,
   RecordPluginConflict: () => RecordPluginConflict2,
@@ -307,6 +308,31 @@ function recordFieldOf2(field) {
   return;
 }
 
+// src/core/record/name.ts
+var RECORD_NAME = /^[A-Za-z_$][\w$]*$/;
+function isRecordName(name) {
+  return typeof name === "string" && RECORD_NAME.test(name);
+}
+function recordNameOf2(Class) {
+  const { recordName, name } = Class;
+  return typeof recordName === "string" ? recordName : String(name);
+}
+var declaredNames = new WeakMap;
+function declareRecordName(Class, name) {
+  declaredNames.set(Class, name);
+}
+function declaredRecordNameOf(Class) {
+  for (let current = Class;typeof current === "function"; current = Object.getPrototypeOf(current)) {
+    const own = Object.getOwnPropertyDescriptor(current, "recordName")?.value;
+    if (typeof own === "string")
+      return own;
+    const declared = declaredNames.get(current);
+    if (declared !== undefined)
+      return declared;
+  }
+  return;
+}
+
 // src/core/parse/issue.ts
 function withLazyCause(issue, build) {
   let cause;
@@ -454,7 +480,7 @@ function fieldAt(field, value, parent, key, source) {
     if (value instanceof record.record)
       return { value };
     if (!isPlainObject(value)) {
-      return rejection("not_record", `must be an instance of record "${record.record.name}"`, pathAt(parent, key), source);
+      return rejection("not_record", `must be an instance of record "${recordNameOf2(record.record)}"`, pathAt(parent, key), source);
     }
     const result = record.record.safeParse(value);
     return result.issues ? underPath(result, pathAt(parent, key)) : result;
@@ -587,14 +613,16 @@ class Exception2 extends Error {
     message = this.message,
     details
   }) {
-    return new Exception2({
+    const keepsClass = name === this.name && details === undefined && isDeclaredInstance(this);
+    const init = {
       layer,
       source,
       name,
       message,
-      details,
+      details: keepsClass ? this.details : details,
       cause: this
-    });
+    };
+    return keepsClass ? Reflect.construct(Exception2, [init], this.constructor) : new Exception2(init);
   }
   toJSON() {
     return { ...this.frame, trace: this.trace };
@@ -612,6 +640,13 @@ class Exception2 extends Error {
   }
 }
 var declarations = new WeakMap;
+function isDeclaredInstance(exception) {
+  for (let current = exception.constructor;typeof current === "function"; current = Object.getPrototypeOf(current)) {
+    if (declarations.has(current))
+      return true;
+  }
+  return false;
+}
 function isDeclaredException(value) {
   return typeof value === "function" && declarations.has(value);
 }
@@ -660,6 +695,11 @@ var InvalidRecordValue2 = exceptionOf2({
     errors
   }, source) => `Invalid value for ${key ? `"${key}" of ` : ""}record "${source}": ${errors.join("; ")}`
 });
+var InvalidRecordDeclaration2 = exceptionOf2({
+  layer: "record" /* Record */,
+  name: "InvalidRecordDeclaration",
+  message: (reason, source) => `Invalid declaration of record "${source}": ${reason}`
+});
 var UndeclaredRecordProperty2 = exceptionOf2({
   layer: "record" /* Record */,
   name: "UndeclaredRecordProperty",
@@ -781,7 +821,10 @@ function checkMembers(record, keys) {
   for (let prototype = Object.getPrototypeOf(record);prototype !== null && !Object.hasOwn(prototype.constructor, "blueprint"); prototype = Object.getPrototypeOf(prototype)) {
     const key = Object.getOwnPropertyNames(prototype).find((name) => keys.includes(name));
     if (key !== undefined) {
-      throw new ReservedRecordKey2({ source: Class.name, details: { key } });
+      throw new ReservedRecordKey2({
+        source: recordNameOf2(Class),
+        details: { key }
+      });
     }
   }
   checked.add(Class);
@@ -837,7 +880,7 @@ function parseRecord(Class, value) {
   try {
     return { value: new Class(value) };
   } catch (error) {
-    return { issues: issuesOfError(error, Class.name) };
+    return { issues: issuesOfError(error, recordNameOf2(Class)) };
   }
 }
 function recordValue(record) {
@@ -868,7 +911,7 @@ function recordFieldDataOf(field, value, options) {
   return value;
 }
 function storeRecordValue(record, key, value) {
-  const source = record.constructor.name;
+  const source = recordNameOf2(record.constructor);
   const { properties } = record[Meta2].blueprint;
   if (!Object.hasOwn(properties, key)) {
     throw exceptionOfIssues([
@@ -921,7 +964,7 @@ class AbstractRecord2 {
   }
   constructor(value) {
     checkMembers(this, Object.keys(this[Meta2].blueprint.properties));
-    const source = this.constructor.name;
+    const source = recordNameOf2(this.constructor);
     const result = parseCollection(this[Meta2].blueprint.properties, value, [], source);
     if (result.issues)
       throw exceptionOfIssues(result.issues, source);
@@ -1140,7 +1183,14 @@ function pluginContextOf(catalogs) {
   return Object.freeze(Object.assign({}, ...catalogs.map((catalog) => catalog.plugins)));
 }
 var recordOf3 = recordBuilderOf2();
-function declareRecord(Base, declared, { plugins = [], ...declaredOptions }, name, reserved = [], context = {}) {
+function declareRecord(Base, declared, { plugins = [], name: declaredName, ...declaredOptions }, fallback, reserved = [], context = {}) {
+  if (declaredName !== undefined && !isRecordName(declaredName)) {
+    throw new InvalidRecordDeclaration2({
+      source: fallback,
+      details: `"name" must be an identifier, got ${JSON.stringify(declaredName)}.`
+    });
+  }
+  const name = declaredName ?? fallback;
   const applied = applyPlugins(declared, typeof plugins === "function" ? plugins(context) : plugins, name, reserved);
   const blueprint = applied.blueprint;
   const sensitive = [
@@ -1192,6 +1242,15 @@ function declareRecord(Base, declared, { plugins = [], ...declaredOptions }, nam
     static [RecordPlugins] = applied.plugins;
     static [RecordPluginHooks] = applied.hooks;
   }
+  if (declaredName !== undefined) {
+    declareRecordName(DeclaredRecord, declaredName);
+  }
+  Object.defineProperty(DeclaredRecord, "recordName", {
+    get() {
+      return declaredName ?? this.name;
+    },
+    configurable: true
+  });
   exposeRecordKeys(DeclaredRecord.prototype, keys);
   for (const [member, descriptor] of Object.entries(applied.descriptors)) {
     Object.defineProperty(DeclaredRecord.prototype, member, descriptor);
@@ -1648,4 +1707,4 @@ function schemaOfField(key, field) {
   });
 }
 
-export { __export, isProperty2, schemaOf2, Demo2, recordPropertyLineage, propertyLineageOf2, fieldOf, Kind2, isBlueprint2, isRecordClass2, isOptionalRecord2, recordFieldOf2, listOf2, isBlueprintList2, ExceptionLayers2, UNEXPECTED_ERROR2, Exception2, isDeclaredException, declaredMessageOf, exceptionOf2, Meta2, InvalidRecordValue2, UndeclaredRecordProperty2, ReservedRecordKey2, InvalidRecordPlugin2, RecordPluginConflict2, UnknownRecordPlugin2, IncompatibleRecordPlugin2, exports_exceptions, MASK2, RESERVED_RECORD_KEYS2, recordDataOf, recordFieldDataOf, storeRecordValue, runRecordEffects, AbstractRecord2, IdentifiedRecord, isVersion, versionParts, pluginsOf2, isRecordPlugin2, hasPlugin2, recordPluginOf2, recordBuilderOf2, pluginContextOf, recordOf3, declareRecord, ReservedBlueprintKey2, UndeclaredBlueprintProperty2, exports_exceptions2, PropertyRequired2, InvalidPropertyValue2, exports_exceptions3, State2, AbstractProperty2, PropertyStates2, AbstractDefineProperty2, propertyOf2, optionalOf2, blueprintBuilderOf2, blueprintFromProperties };
+export { __export, isProperty2, schemaOf2, Demo2, recordPropertyLineage, propertyLineageOf2, fieldOf, Kind2, isBlueprint2, isRecordClass2, isOptionalRecord2, recordFieldOf2, recordNameOf2, declaredRecordNameOf, listOf2, isBlueprintList2, ExceptionLayers2, UNEXPECTED_ERROR2, Exception2, isDeclaredException, declaredMessageOf, exceptionOf2, Meta2, InvalidRecordValue2, InvalidRecordDeclaration2, UndeclaredRecordProperty2, ReservedRecordKey2, InvalidRecordPlugin2, RecordPluginConflict2, UnknownRecordPlugin2, IncompatibleRecordPlugin2, exports_exceptions, MASK2, RESERVED_RECORD_KEYS2, recordDataOf, recordFieldDataOf, storeRecordValue, runRecordEffects, AbstractRecord2, IdentifiedRecord, isVersion, versionParts, pluginsOf2, isRecordPlugin2, hasPlugin2, recordPluginOf2, recordBuilderOf2, pluginContextOf, recordOf3, declareRecord, ReservedBlueprintKey2, UndeclaredBlueprintProperty2, exports_exceptions2, PropertyRequired2, InvalidPropertyValue2, exports_exceptions3, State2, AbstractProperty2, PropertyStates2, AbstractDefineProperty2, propertyOf2, optionalOf2, blueprintBuilderOf2, blueprintFromProperties };