@afora/core 0.0.8 → 0.0.11

package/dist/core/record/plugin.js

@@ -0,0 +1,198 @@
+import { isRecordClass } from "../blueprint/record-field.js";
+import { Kind } from "../symbols/kind.js";
+import { RESERVED_RECORD_KEYS } from "./abstract-record.js";
+import { InvalidRecordPlugin, RecordPluginConflict } from "./exceptions.js";
+export const RecordPlugins = Symbol("recordPlugins");
+export const IdentifiedRecord = Symbol("identifiedRecord");
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function isVersion(version) {
+  return typeof version === "string" && SEMVER.test(version);
+}
+function versionParts(version) {
+  const [, major, minor, patch] = SEMVER.exec(version);
+  return [Number(major), Number(minor), Number(patch)];
+}
+export function satisfies(available, requested) {
+  const [major, minor, patch] = versionParts(available);
+  const [wantedMajor, wantedMinor, wantedPatch] = versionParts(requested);
+  if (major !== wantedMajor)
+    return false;
+  if (major === 0 && minor !== wantedMinor)
+    return false;
+  if (minor !== wantedMinor)
+    return minor > wantedMinor;
+  return patch >= wantedPatch;
+}
+const HOOKS = ["onSet", "onSetAll"];
+const internals = new WeakMap;
+export function pluginsOf(value) {
+  const Class = typeof value === "function" ? value : typeof value === "object" && value !== null ? value.constructor : undefined;
+  return Class?.[RecordPlugins] ?? [];
+}
+export function isRecordPlugin(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "record-plugin";
+}
+export function hasPlugin(value, plugin) {
+  const plugins = pluginsOf(value);
+  if (typeof plugin === "string") {
+    return plugins.some((applied) => applied.name === plugin);
+  }
+  if (plugins.includes(plugin))
+    return true;
+  return typeof value === "function" ? value === plugin.record || value.prototype instanceof plugin.record : value instanceof plugin.record;
+}
+function membersOf(Record, name) {
+  const descriptors = {};
+  const hooks = {};
+  for (let prototype = Record.prototype;prototype !== null && !Object.hasOwn(prototype.constructor, "blueprint"); prototype = Object.getPrototypeOf(prototype)) {
+    for (const member of Object.getOwnPropertyNames(prototype)) {
+      if (member === "constructor")
+        continue;
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, member);
+      if (HOOKS.includes(member)) {
+        hooks[member] ??= descriptor.value;
+        continue;
+      }
+      if (RESERVED_RECORD_KEYS.includes(member)) {
+        throw new InvalidRecordPlugin({
+          source: name,
+          details: {
+            reason: `"${member}" is a member of every record and cannot be replaced`
+          }
+        });
+      }
+      descriptors[member] ??= descriptor;
+    }
+  }
+  return { descriptors: Object.freeze(descriptors), hooks };
+}
+export function recordPluginOf(name, Record, { version = "1.0.0", description } = {}) {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new InvalidRecordPlugin({
+      source: String(name),
+      details: { reason: "its name must be a non-empty string" }
+    });
+  }
+  if (!isRecordClass(Record)) {
+    throw new InvalidRecordPlugin({
+      source: name,
+      details: { reason: "it must be made from a class of `recordOf`" }
+    });
+  }
+  if (Record[IdentifiedRecord]) {
+    throw new InvalidRecordPlugin({
+      source: name,
+      details: {
+        reason: "it must be made from a record, not an entity: plugins have no identity"
+      }
+    });
+  }
+  if (!isVersion(version)) {
+    throw new InvalidRecordPlugin({
+      source: name,
+      details: { reason: `"${version}" is not a semantic version` }
+    });
+  }
+  const requires = pluginsOf(Record);
+  const inherited = new Set(requires.flatMap((required) => required.keys));
+  const declaration = Record;
+  const keys = Object.freeze(Object.keys(declaration.blueprint.properties).filter((key) => !inherited.has(key)));
+  const own = membersOf(Record, name);
+  const plugin = Object.freeze({
+    [Kind]: "record-plugin",
+    name,
+    version,
+    ...description === undefined ? {} : { description },
+    record: Record,
+    keys,
+    members: Object.freeze(Object.keys(own.descriptors)),
+    options: declaration.options,
+    requires,
+    is: (value) => hasPlugin(value, plugin),
+    toJSON: () => descriptorOf(plugin)
+  });
+  internals.set(plugin, own);
+  return plugin;
+}
+function descriptorOf(plugin) {
+  return Object.freeze({
+    kind: "record-plugin",
+    name: plugin.name,
+    version: plugin.version,
+    ...plugin.description === undefined ? {} : { description: plugin.description },
+    keys: plugin.keys,
+    sensitive: plugin.options.sensitive,
+    unique: plugin.options.unique,
+    change: plugin.options.change,
+    members: plugin.members,
+    requires: Object.freeze(plugin.requires.map(({ name, version }) => Object.freeze({ name, version })))
+  });
+}
+export function applyPlugins(blueprint, plugins, name, reserved) {
+  const flat = [];
+  for (const plugin of plugins) {
+    if (!isRecordPlugin(plugin)) {
+      throw new InvalidRecordPlugin({
+        source: name,
+        details: {
+          reason: "`options.plugins` takes plugins made by `recordPluginOf`"
+        }
+      });
+    }
+    for (const applied of [...plugin.requires, plugin]) {
+      if (flat.includes(applied))
+        continue;
+      if (flat.some((other) => other.name === applied.name)) {
+        throw new RecordPluginConflict({
+          source: name,
+          details: {
+            plugin: applied.name,
+            key: applied.name,
+            owner: "another plugin"
+          }
+        });
+      }
+      flat.push(applied);
+    }
+  }
+  const owners = new Map(Object.keys(blueprint.properties).map((key) => [key, `record "${name}"`]));
+  for (const member of reserved)
+    owners.set(member, `record "${name}"`);
+  const claim = (plugin, key) => {
+    const owner = owners.get(key);
+    if (owner !== undefined) {
+      throw new RecordPluginConflict({
+        source: name,
+        details: { plugin: plugin.name, key, owner }
+      });
+    }
+    owners.set(key, `plugin "${plugin.name}"`);
+  };
+  const descriptors = {};
+  const hooks = [];
+  for (const plugin of flat) {
+    for (const key of plugin.keys)
+      claim(plugin, key);
+    const own = internals.get(plugin);
+    for (const member of plugin.members) {
+      claim(plugin, member);
+      descriptors[member] = own.descriptors[member];
+    }
+    if (own.hooks.onSet || own.hooks.onSetAll) {
+      hooks.push(Object.freeze({
+        plugin,
+        keys: Object.freeze(Object.keys(plugin.record.blueprint.properties)),
+        ...own.hooks
+      }));
+    }
+  }
+  return {
+    blueprint: flat.length === 0 ? blueprint : blueprint.join(...flat.map((plugin) => plugin.record.blueprint)),
+    plugins: Object.freeze(flat),
+    sensitive: flat.flatMap((plugin) => plugin.options.sensitive),
+    unique: flat.flatMap((plugin) => plugin.options.unique),
+    change: flat.flatMap((plugin) => plugin.options.change),
+    descriptors,
+    hooks: Object.freeze(hooks)
+  };
+}

package/dist/core/record/record.js

@@ -0,0 +1,117 @@
+import { Kind } from "../symbols/kind.js";
+import {
+  AbstractRecord,
+  exposeRecordKeys,
+  RESERVED_RECORD_KEYS,
+  RecordPluginHooks
+} from "./abstract-record.js";
+import {
+  InvalidRecordDeclaration,
+  RecordPluginConflict,
+  ReservedRecordKey,
+  UndeclaredRecordProperty
+} from "./exceptions.js";
+import { isMarked } from "./marks.js";
+import { declareRecordName, isRecordName } from "./name.js";
+import { applyPlugins, RecordPlugins } from "./plugin.js";
+export function recordBuilderOf(...catalogs) {
+  const context = pluginContextOf(catalogs);
+  return (blueprint, options = {}) => declareRecord(AbstractRecord, blueprint, options, "record", [], context);
+}
+export function pluginContextOf(catalogs) {
+  return Object.freeze(Object.assign({}, ...catalogs.map((catalog) => catalog.plugins)));
+}
+export const recordOf = recordBuilderOf();
+export function declareRecord(Base, declared, { plugins = [], name: declaredName, ...declaredOptions }, fallback, reserved = [], context = {}) {
+  if (declaredName !== undefined && !isRecordName(declaredName)) {
+    throw new InvalidRecordDeclaration({
+      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 = [
+    ...declaredOptions.sensitive ?? [],
+    ...applied.sensitive
+  ];
+  const unique = [...declaredOptions.unique ?? [], ...applied.unique];
+  const declaredChange = declaredOptions.change ?? [];
+  const keys = Object.keys(blueprint.properties);
+  const change = keys.filter((key) => declaredChange.includes(key) || applied.change.includes(key));
+  for (const key of [...sensitive, ...unique, ...declaredChange]) {
+    if (!keys.includes(key)) {
+      throw new UndeclaredRecordProperty({
+        source: name,
+        details: { key }
+      });
+    }
+  }
+  const methods = change.length > 0 ? [CHANGE_MEMBER] : [];
+  for (const member of Object.keys(applied.descriptors)) {
+    if (methods.includes(member)) {
+      const plugin = applied.plugins.find((plugin) => plugin.members.includes(member));
+      throw new RecordPluginConflict({
+        source: name,
+        details: {
+          plugin: plugin.name,
+          key: member,
+          owner: `record "${name}" (the \`change\` namespace)`
+        }
+      });
+    }
+  }
+  for (const key of keys) {
+    if (RESERVED_RECORD_KEYS.includes(key) || reserved.includes(key) || methods.includes(key)) {
+      throw new ReservedRecordKey({ source: name, details: { key } });
+    }
+  }
+  const options = Object.freeze({
+    sensitive: Object.freeze(keys.filter((key) => sensitive.includes(key) || isMarked(blueprint.properties[key], "sensitive", { lists: true }))),
+    unique: Object.freeze(keys.filter((key) => unique.includes(key) || isMarked(blueprint.properties[key], "unique"))),
+    change: Object.freeze([...change])
+  });
+
+  class DeclaredRecord extends Base {
+    static [Kind] = "record";
+    static blueprint = blueprint;
+    static options = options;
+    static plugins = applied.plugins;
+    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);
+  }
+  if (change.length > 0) {
+    Object.defineProperty(DeclaredRecord.prototype, CHANGE_MEMBER, {
+      get() {
+        let namespace = changeNamespaces.get(this);
+        if (namespace === undefined) {
+          namespace = Object.freeze(Object.fromEntries(change.map((key) => [
+            key,
+            (value) => this.set(key, value)
+          ])));
+          changeNamespaces.set(this, namespace);
+        }
+        return namespace;
+      },
+      configurable: true
+    });
+  }
+  Object.defineProperty(DeclaredRecord, "name", { value: name });
+  return DeclaredRecord;
+}
+const CHANGE_MEMBER = "change";
+const changeNamespaces = new WeakMap;

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;
@@ -144,6 +155,11 @@ type JsonValue<Properties extends IBlueprintCollection, Sensitive, Result = 0 ex
  * lists `Sensitive`: the plain value, no key left out, sensitive values masked.
  */
 export type RecordJson<Properties extends IBlueprintCollection, Sensitive extends string = never> = JsonValue<Properties, Sensitive>;
+/**
+ * What every record class made by {@link recordOf} carries: the declaration
+ * metadata of its blueprint and options, and `toJSON`, which gives the value
+ * with the sensitive keys masked.
+ */
 export interface IRecord<Properties extends IBlueprintCollection, Sensitive extends string = never> {
     /** Declaration metadata, separate from domain keys. */
     readonly [Meta]: {

package/dist/core/repository/cursor.js

@@ -0,0 +1,83 @@
+import { InvalidRepositoryCursor } from "./exceptions.js";
+const VERSION = 1;
+const signatureOf = (orders) => orders.map(({ key, direction = "asc" }) => `${key}:${direction}`);
+function pack(value) {
+  if (value === undefined || value === null)
+    return null;
+  if (value instanceof Date)
+    return { d: value.toISOString() };
+  if (typeof value === "bigint")
+    return { b: value.toString() };
+  return value;
+}
+function unpack(value) {
+  if (value === null)
+    return;
+  if (["string", "number", "boolean"].includes(typeof value))
+    return value;
+  if (typeof value === "object") {
+    const { d, b } = value;
+    const keys = Object.keys(value);
+    if (keys.length === 1 && typeof d === "string") {
+      const date = new Date(d);
+      if (!Number.isNaN(date.getTime()))
+        return date;
+    }
+    if (keys.length === 1 && typeof b === "string" && /^-?\d+$/.test(b))
+      return BigInt(b);
+  }
+  throw new SyntaxError("value");
+}
+function encodeText(text) {
+  let binary = "";
+  for (const byte of new TextEncoder().encode(text))
+    binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeText(encoded) {
+  if (!/^[A-Za-z0-9_-]+$/.test(encoded))
+    throw new SyntaxError("alphabet");
+  const binary = atob(encoded.replaceAll("-", "+").replaceAll("_", "/"));
+  return new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(binary, (char) => char.charCodeAt(0)));
+}
+export function encodeCursor(orders, row) {
+  const payload = {
+    v: VERSION,
+    k: signatureOf(orders),
+    a: orders.map(({ key }) => pack(row[key]))
+  };
+  return encodeText(JSON.stringify(payload));
+}
+export function decodeCursor(source, orders, cursor) {
+  const fail = (reason) => {
+    throw new InvalidRepositoryCursor({
+      source,
+      details: {
+        reason,
+        issues: [
+          { code: "invalid_value", path: ["after"], message: reason, source }
+        ]
+      }
+    });
+  };
+  if (typeof cursor !== "string" || cursor === "")
+    return fail("Expected a cursor given by findCursor.");
+  let payload;
+  let values;
+  try {
+    payload = JSON.parse(decodeText(cursor));
+    if (typeof payload !== "object" || payload === null)
+      throw new SyntaxError;
+    if (!Array.isArray(payload.k) || !Array.isArray(payload.a))
+      throw new SyntaxError;
+    values = payload.a.map(unpack);
+  } catch {
+    return fail("The cursor is not one given by findCursor.");
+  }
+  if (payload.v !== VERSION)
+    return fail("The cursor was made by another version.");
+  const expected = signatureOf(orders);
+  if (payload.k?.length !== expected.length || values.length !== expected.length || expected.some((key, index) => payload.k?.[index] !== key))
+    return fail("The cursor was made for another orderBy.");
+  return values;
+}

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/exceptions.js

@@ -0,0 +1,72 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidRepositoryQuery = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidRepositoryQuery",
+  message: ({ reason }) => reason
+});
+export const InvalidRepositoryCursor = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidRepositoryCursor",
+  message: ({
+    reason
+  }) => reason
+});
+export const InvalidRepositoryDeclaration = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidRepositoryDeclaration",
+  message: ({ reason }) => reason
+});
+export const InvalidRepositoryEntity = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidRepositoryEntity",
+  message: (_details, source) => `"${source}" expected an entity of its own class.`
+});
+export const InvalidStoredSchemaVersion = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidStoredSchemaVersion",
+  message: ({
+    id,
+    stored,
+    current,
+    reason
+  }, source) => reason ?? `"${source}" read the row "${id}" stored at schema version ${JSON.stringify(stored)}, and its entity is at version ${current}.`
+});
+export const InvalidRepositoryData = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidRepositoryData",
+  message: (_details, source) => `"${source}" read a value that its entity rejects.`
+});
+export const RepositoryUniqueViolation = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "RepositoryUniqueViolation",
+  message: ({ key }, source) => `"${source}" already holds an entity with this "${key}".`
+});
+export const RepositoryUsedOutsideApplication = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "RepositoryUsedOutsideApplication",
+  message: ({
+    application,
+    repository
+  }, source) => `"${source}" is bound to the application "${application}", and its declaration no longer reads or writes: use app.repositories.${repository}, run its use cases with app.run, or give the repository of the application to execute.`
+});
+export const RepositoryEntityNotFound = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "RepositoryEntityNotFound",
+  message: ({ id }, source) => `"${source}" holds no entity of id "${id}".`
+});
+export const RepositoryConcurrencyConflict = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "RepositoryConcurrencyConflict",
+  message: ({
+    id,
+    expected
+  }, source) => `"${source}" holds another version of "${id}" than ${expected}: it changed since it was read.`
+});
+export const InvalidRepositoryIncrement = exceptionOf({
+  layer: ExceptionLayers.Repository,
+  name: "InvalidRepositoryIncrement",
+  message: ({
+    reason
+  }) => reason
+});

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