@afora/core 0.0.9 → 0.0.12

package/dist/core/record/plugin-catalog.js

@@ -0,0 +1,115 @@
+import { Kind } from "../symbols/kind.js";
+import {
+  IncompatibleRecordPlugin,
+  InvalidRecordPlugin,
+  UnknownRecordPlugin
+} from "./exceptions.js";
+import { isRecordPlugin, isVersion, satisfies } from "./plugin.js";
+const LISTS = ["keys", "sensitive", "unique", "change", "members"];
+function isDescriptor(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const descriptor = value;
+  const isList = (list) => Array.isArray(list) && list.every((item) => typeof item === "string");
+  return descriptor.kind === "record-plugin" && typeof descriptor.name === "string" && isVersion(descriptor.version) && LISTS.every((list) => isList(descriptor[list])) && Array.isArray(descriptor.requires) && descriptor.requires.every((required) => typeof required === "object" && required !== null && typeof required.name === "string" && isVersion(required.version));
+}
+function mismatchOf(plugin, descriptor) {
+  if (!satisfies(plugin.version, descriptor.version)) {
+    return `version ${plugin.version} does not satisfy ${descriptor.version}`;
+  }
+  const current = {
+    keys: plugin.keys,
+    sensitive: plugin.options.sensitive,
+    unique: plugin.options.unique,
+    change: plugin.options.change,
+    members: plugin.members
+  };
+  for (const list of LISTS) {
+    const missing = descriptor[list].find((item) => !current[list].includes(item));
+    if (missing !== undefined)
+      return `"${missing}" is not in its ${list}`;
+  }
+  for (const required of descriptor.requires) {
+    const found = plugin.requires.find(({ name }) => name === required.name);
+    if (!found)
+      return `it does not require "${required.name}"`;
+    if (!satisfies(found.version, required.version)) {
+      return `its "${required.name}" ${found.version} does not satisfy ${required.version}`;
+    }
+  }
+  return;
+}
+export function recordPluginCatalogOf(...plugins) {
+  const byName = {};
+  for (const plugin of plugins) {
+    if (!isRecordPlugin(plugin)) {
+      throw new InvalidRecordPlugin({
+        source: "catalog",
+        details: {
+          reason: "a catalog takes plugins made by `recordPluginOf`"
+        }
+      });
+    }
+    if (Object.hasOwn(byName, plugin.name)) {
+      throw new InvalidRecordPlugin({
+        source: plugin.name,
+        details: { reason: "the catalog has another plugin with its name" }
+      });
+    }
+    byName[plugin.name] = plugin;
+  }
+  const find = (name) => {
+    const plugin = Object.hasOwn(byName, name) ? byName[name] : undefined;
+    if (!plugin) {
+      throw new UnknownRecordPlugin({ source: "catalog", details: { name } });
+    }
+    return plugin;
+  };
+  const resolve = (reference) => {
+    if (typeof reference === "string") {
+      const at = reference.lastIndexOf("@");
+      if (at <= 0)
+        return find(reference);
+      const plugin = find(reference.slice(0, at));
+      const version = reference.slice(at + 1);
+      if (!isVersion(version)) {
+        throw new IncompatibleRecordPlugin({
+          source: plugin.name,
+          details: { reason: `"${version}" is not a semantic version` }
+        });
+      }
+      if (!satisfies(plugin.version, version)) {
+        throw new IncompatibleRecordPlugin({
+          source: plugin.name,
+          details: {
+            reason: `version ${plugin.version} does not satisfy ${version}`
+          }
+        });
+      }
+      return plugin;
+    }
+    if (!isDescriptor(reference)) {
+      const name = reference?.name;
+      throw new IncompatibleRecordPlugin({
+        source: typeof name === "string" ? name : "unknown",
+        details: { reason: "it is not a record plugin descriptor" }
+      });
+    }
+    const plugin = find(reference.name);
+    const reason = mismatchOf(plugin, reference);
+    if (reason !== undefined) {
+      throw new IncompatibleRecordPlugin({
+        source: plugin.name,
+        details: { reason }
+      });
+    }
+    return plugin;
+  };
+  return Object.freeze({
+    [Kind]: "record-plugin-catalog",
+    plugins: Object.freeze(byName),
+    list: Object.freeze([...plugins]),
+    resolve,
+    resolveAll: (references) => Object.freeze(references.map(resolve))
+  });
+}

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

@@ -155,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.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
+});