@afora/core 0.0.9 → 0.0.12

package/dist/core/repository/in-memory.js

@@ -0,0 +1,196 @@
+import { declaredRecordNameOf } from "../record/name.js";
+import {
+  InvalidRepositoryDeclaration,
+  RepositoryConcurrencyConflict,
+  RepositoryEntityNotFound,
+  RepositoryUniqueViolation
+} from "./exceptions.js";
+import { providerOf } from "./provider.js";
+import { matchesQuery, nowOf, sameValue, selectRows } from "./query.js";
+const tableKeys = new WeakMap;
+function tableKeyOf(entity) {
+  let key = tableKeys.get(entity);
+  if (key === undefined) {
+    key = declaredRecordNameOf(entity) ?? entity;
+    tableKeys.set(entity, key);
+  }
+  return key;
+}
+function idOf(data) {
+  return data.id;
+}
+function snapshotOf(tables) {
+  return new Map([...tables].map(([key, table]) => [key, new Map(table)]));
+}
+const copy = (data) => structuredClone(data);
+function scopeOf(initial, root) {
+  let tables = initial;
+  let held;
+  let closed = false;
+  const tableOf = (context) => {
+    const key = tableKeyOf(context.entity);
+    let table = tables.get(key);
+    if (!table) {
+      table = new Map;
+      tables.set(key, table);
+    }
+    return table;
+  };
+  const whenIdle = async (work) => {
+    while (held)
+      await held;
+    if (closed) {
+      throw new InvalidRepositoryDeclaration({
+        source: "inMemory",
+        details: {
+          reason: "The transaction has ended; its provider cannot be used."
+        }
+      });
+    }
+    return work();
+  };
+  const assertUnique = (context, data) => {
+    for (const stored of tableOf(context).values()) {
+      if (idOf(stored) === idOf(data))
+        continue;
+      const key = context.unique.find((key) => data[key] !== undefined && sameValue(stored[key], data[key]));
+      if (key !== undefined) {
+        throw new RepositoryUniqueViolation({
+          source: context.name,
+          details: { key }
+        });
+      }
+    }
+  };
+  const provider = {
+    capabilities: Object.freeze({
+      transactions: true,
+      keyset: true,
+      versioning: true,
+      atomic: true,
+      expiry: true
+    }),
+    findOne: (context, query = {}) => whenIdle(() => {
+      const [first] = selectRows(tableOf(context).values(), { ...query, limit: Math.min(query.limit ?? 1, 1) }, context.expiry?.key);
+      return first === undefined ? undefined : copy(first);
+    }),
+    findMany: (context, query = {}) => whenIdle(() => selectRows(tableOf(context).values(), query, context.expiry?.key).map(copy)),
+    insert: (context, data) => whenIdle(() => {
+      const table = tableOf(context);
+      if (table.has(idOf(data))) {
+        throw new RepositoryUniqueViolation({
+          source: context.name,
+          details: { key: "id" }
+        });
+      }
+      assertUnique(context, data);
+      table.set(idOf(data), copy(data));
+    }),
+    update: (context, data, options = {}) => whenIdle(() => {
+      const table = tableOf(context);
+      const stored = table.get(idOf(data));
+      if (!stored) {
+        throw new RepositoryEntityNotFound({
+          source: context.name,
+          details: { id: idOf(data) }
+        });
+      }
+      const { expectedVersion: expected } = options;
+      if (expected !== undefined && stored.version !== expected) {
+        throw new RepositoryConcurrencyConflict({
+          source: context.name,
+          details: {
+            id: idOf(data),
+            expected,
+            ...typeof stored.version === "number" ? { actual: stored.version } : {}
+          }
+        });
+      }
+      assertUnique(context, data);
+      table.set(idOf(data), copy(data));
+    }),
+    increment: (context, id, deltas, options = {}) => whenIdle(() => {
+      const table = tableOf(context);
+      const found = table.get(id);
+      const expiry = context.expiry?.key;
+      const expired = found !== undefined && expiry !== undefined && !matchesQuery(found, { withDeleted: true, now: options.now }, expiry);
+      const stored = expired ? undefined : found;
+      if (!stored || stored.deletedAt != null) {
+        if (!options.create) {
+          throw new RepositoryEntityNotFound({
+            source: context.name,
+            details: { id }
+          });
+        }
+        if (stored) {
+          throw new RepositoryUniqueViolation({
+            source: context.name,
+            details: { key: "id" }
+          });
+        }
+        const created = { ...options.create, id };
+        assertUnique(context, created);
+        table.set(id, copy(created));
+        return copy(created);
+      }
+      const next = { ...stored, ...options.set };
+      for (const [key, delta] of Object.entries(deltas)) {
+        const value = stored[key];
+        next[key] = (typeof value === "number" ? value : 0) + delta;
+      }
+      table.set(id, copy(next));
+      return copy(next);
+    }),
+    remove: (context, id) => whenIdle(() => {
+      if (!tableOf(context).delete(id)) {
+        throw new RepositoryEntityNotFound({
+          source: context.name,
+          details: { id }
+        });
+      }
+    }),
+    count: (context, query = {}) => whenIdle(() => {
+      const expiry = context.expiry?.key;
+      const now = expiry === undefined ? 0 : nowOf(query);
+      let total = 0;
+      for (const data of tableOf(context).values()) {
+        if (matchesQuery(data, query, expiry, now))
+          total++;
+      }
+      return total;
+    }),
+    async transaction(run) {
+      let release;
+      const child = await whenIdle(() => {
+        held = new Promise((resolve) => {
+          release = resolve;
+        });
+        return scopeOf(snapshotOf(tables), false);
+      });
+      try {
+        const result = await run(child.provider);
+        tables = child.close();
+        return result;
+      } finally {
+        child.close();
+        held = undefined;
+        release();
+      }
+    }
+  };
+  return {
+    provider,
+    close() {
+      if (!root)
+        closed = true;
+      return tables;
+    }
+  };
+}
+export function inMemoryProvider() {
+  return providerOf({
+    name: "inMemory",
+    options: {},
+    create: () => scopeOf(new Map, true).provider
+  });
+}

package/dist/core/repository/migrate.js

@@ -0,0 +1,254 @@
+import {
+  EntitySettings,
+  isVersionedEntityClass,
+  SCHEMA_VERSION_KEY
+} from "../entity/abstract-entity.js";
+import { Exception } from "../exception/exception.js";
+import { recordNameOf } from "../record/name.js";
+import {
+  InvalidRepositoryData,
+  InvalidRepositoryDeclaration,
+  RepositoryConcurrencyConflict
+} from "./exceptions.js";
+import { resolveReferences } from "./references.js";
+import { contextOf } from "./state.js";
+import {
+  fullUpcastPlanOf,
+  upcast
+} from "./upcast.js";
+const aliases = new WeakMap;
+function aliasOf(entity, name) {
+  let byName = aliases.get(entity);
+  if (!byName) {
+    byName = new Map;
+    aliases.set(entity, byName);
+  }
+  let alias = byName.get(name);
+  if (!alias) {
+    const Entity = entity;
+    alias = class extends Entity {
+    };
+    Object.defineProperty(alias, "name", { value: name });
+    Object.defineProperty(alias, "recordName", { value: name });
+    byName.set(name, alias);
+  }
+  return alias;
+}
+function previousContextOf(context, name) {
+  return Object.freeze({
+    ...context,
+    entity: aliasOf(context.entity, name),
+    name: `${name}Repository`
+  });
+}
+async function walk(provider, context, pageSize, visit) {
+  const keyset = provider.capabilities?.keyset === true;
+  let after;
+  let offset = 0;
+  for (;; ) {
+    const query = {
+      orderBy: [{ key: "id", direction: "asc" }],
+      withDeleted: true,
+      ...context.expiry === undefined ? {} : { withExpired: true },
+      limit: pageSize,
+      ...keyset ? after === undefined ? {} : { after } : offset === 0 ? {} : { offset }
+    };
+    const rows = await provider.findMany(context, query);
+    if (rows.length === 0)
+      return;
+    const removed = await visit(rows);
+    after = [rows.at(-1).id];
+    offset += rows.length - removed;
+    if (rows.length < pageSize)
+      return;
+  }
+}
+function issuesOf(source, error) {
+  const issues = error?.details?.issues;
+  if (Array.isArray(issues))
+    return issues;
+  const cause = error instanceof Exception && error.is(InvalidRepositoryData) ? error.cause ?? error : error;
+  return [
+    {
+      code: "invalid_value",
+      path: [],
+      message: cause instanceof Error ? cause.message : String(cause),
+      source,
+      ...cause instanceof Exception ? { cause } : {}
+    }
+  ];
+}
+async function upcastPage(state, plan, rows) {
+  const brought = rows.map((row) => {
+    const report = {
+      from: 1,
+      renamed: [],
+      filled: [],
+      removed: []
+    };
+    try {
+      return {
+        row,
+        current: upcast(state.name, plan, row, true, report),
+        report
+      };
+    } catch (error) {
+      return { row, invalid: issuesOf(state.name, error) };
+    }
+  });
+  const valid = brought.filter((item) => ("current" in item));
+  const parse = (data) => state.entity.safeParse(data);
+  const resolvedOf = async (items) => resolveReferences(state, items.map((item) => item.current), new Map);
+  let resolved;
+  try {
+    resolved = await resolvedOf(valid);
+  } catch {
+    resolved = await Promise.all(valid.map(async (item) => {
+      try {
+        return (await resolvedOf([item]))[0];
+      } catch (error) {
+        return issuesOf(state.name, error);
+      }
+    }));
+  }
+  const checked = new Map;
+  valid.forEach((item, index) => {
+    const data = resolved[index];
+    if (Array.isArray(data)) {
+      checked.set(item.row, data);
+      return;
+    }
+    const parsed = parse(data);
+    if (parsed.issues)
+      checked.set(item.row, parsed.issues);
+  });
+  return brought.map((item) => {
+    const issues = checked.get(item.row);
+    return issues === undefined ? item : { row: item.row, invalid: issues };
+  });
+}
+function writtenOf(state, plan, item, destructive) {
+  const data = destructive ? item.current : upcast(state.name, plan, item.row, false);
+  return plan.versioned ? { ...data, [SCHEMA_VERSION_KEY]: plan.version } : data;
+}
+export async function migrateRepository(state, options) {
+  const { mode, destructive, pageSize } = options;
+  const apply = mode === "apply";
+  const { provider } = state;
+  const context = contextOf(state);
+  const plan = fullUpcastPlanOf(state.entity);
+  const versioned = isVersionedEntityClass(state.entity) && provider.capabilities?.versioning === true;
+  const own = recordNameOf(state.entity);
+  const previousNames = (state.entity[EntitySettings]?.previousNames ?? []).filter((previous) => previous !== own && `${previous}Repository` !== context.name);
+  const needs = ["findMany"];
+  if (apply)
+    needs.push("update");
+  if (apply && previousNames.length > 0)
+    needs.push("insert");
+  if (apply && destructive && previousNames.length > 0)
+    needs.push("remove");
+  for (const need of needs) {
+    if (typeof provider[need] !== "function") {
+      throw new InvalidRepositoryDeclaration({
+        source: state.name,
+        details: { reason: `The provider has no "${need}" to migrate.` }
+      });
+    }
+  }
+  const tally = {
+    scanned: 0,
+    upToDate: 0,
+    upgraded: 0,
+    removalPending: 0,
+    movedFromPreviousNames: 0,
+    invalid: [],
+    removedKeys: new Set
+  };
+  if (apply) {
+    const migrated = await provider.migrate?.(context, options.plan);
+    if (typeof migrated === "object" && migrated !== null && migrated.deferred === true) {
+      return { ...reportOf(tally), deferred: true };
+    }
+  }
+  await walk(provider, context, pageSize, async (rows) => {
+    for (const item of await upcastPage(state, plan, rows)) {
+      tally.scanned += 1;
+      if ("invalid" in item) {
+        tally.invalid.push({ id: String(item.row.id), issues: item.invalid });
+        continue;
+      }
+      const { report } = item;
+      for (const key of report.removed)
+        tally.removedKeys.add(key);
+      const pending = plan.versioned && report.from < plan.version || report.renamed.length > 0 || report.filled.length > 0;
+      const removal = report.removed.length > 0;
+      if (pending || removal && destructive) {
+        tally.upgraded += 1;
+        if (apply) {
+          const expected = item.row.version;
+          try {
+            await provider.update(context, writtenOf(state, plan, item, destructive), versioned && typeof expected === "number" ? { expectedVersion: expected } : undefined);
+          } catch (error) {
+            if (!(error instanceof Exception) || !error.is(RepositoryConcurrencyConflict)) {
+              throw error;
+            }
+            tally.upgraded -= 1;
+            tally.upToDate += 1;
+          }
+        }
+      } else if (removal) {
+        tally.removalPending += 1;
+      } else {
+        tally.upToDate += 1;
+      }
+    }
+    return 0;
+  });
+  for (const previous of previousNames) {
+    const old = previousContextOf(context, previous);
+    await walk(provider, old, pageSize, async (rows) => {
+      let removed = 0;
+      const moved = new Set((await provider.findMany(context, {
+        where: { id: { in: rows.map((row) => row.id) } },
+        withDeleted: true,
+        ...context.expiry === undefined ? {} : { withExpired: true }
+      })).map((row) => String(row.id)));
+      for (const item of await upcastPage(state, plan, rows)) {
+        tally.scanned += 1;
+        if ("invalid" in item) {
+          tally.invalid.push({
+            id: String(item.row.id),
+            issues: item.invalid
+          });
+          continue;
+        }
+        for (const key of item.report.removed)
+          tally.removedKeys.add(key);
+        const id = String(item.row.id);
+        if (!moved.has(id)) {
+          tally.movedFromPreviousNames += 1;
+          if (apply) {
+            await provider.insert(context, writtenOf(state, plan, item, destructive));
+          }
+        }
+        if (apply && destructive) {
+          await provider.remove(old, id);
+          removed += 1;
+        }
+      }
+      return removed;
+    });
+  }
+  return { ...reportOf(tally), deferred: false };
+}
+function reportOf(tally) {
+  return {
+    scanned: tally.scanned,
+    upToDate: tally.upToDate,
+    upgraded: tally.upgraded,
+    removalPending: tally.removalPending,
+    invalid: tally.invalid,
+    movedFromPreviousNames: tally.movedFromPreviousNames,
+    removedKeys: [...tally.removedKeys].sort()
+  };
+}

package/dist/core/repository/plan.js

@@ -0,0 +1,27 @@
+const ID = Object.freeze({ access: "id" });
+const UNIQUE = Object.freeze({ access: "unique" });
+const SCAN = Object.freeze({ access: "scan" });
+function isMembership(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 1 && Array.isArray(value.in);
+}
+export function planQuery(repository, query = {}) {
+  const where = query.where ?? {};
+  const keys = Object.keys(where);
+  if (keys.includes("id"))
+    return ID;
+  if (keys.some((key) => repository.unique.includes(key)))
+    return UNIQUE;
+  const equal = new Set(keys.filter((key) => !isMembership(where[key])));
+  const first = query.orderBy?.[0]?.key;
+  let best;
+  for (const entry of Object.entries(repository.indexes ?? {})) {
+    const [, index] = entry;
+    if (!index.where.every((key) => equal.has(key)))
+      continue;
+    if (first !== undefined && index.orderBy !== first)
+      continue;
+    if (best === undefined || index.where.length > best[1].where.length)
+      best = entry;
+  }
+  return best === undefined ? SCAN : Object.freeze({ access: "index", index: best[0] });
+}

package/dist/core/repository/provider.js

@@ -0,0 +1,29 @@
+import { frozenJson } from "../json.js";
+import { InvalidRepositoryDeclaration } from "./exceptions.js";
+const descriptions = new WeakMap;
+const opaque = Object.freeze({ kind: "opaque" });
+function invalid(reason) {
+  throw new InvalidRepositoryDeclaration({
+    source: "providerOf",
+    details: { reason }
+  });
+}
+export function providerOf(settings) {
+  if (!settings || typeof settings.name !== "string" || settings.name.trim().length === 0 || typeof settings.create !== "function")
+    invalid("Expected a provider name and create function.");
+  const options = frozenJson(settings.options ?? {}, "Provider options", invalid);
+  if (options === null || typeof options !== "object" || Array.isArray(options))
+    invalid("Provider options must be an object.");
+  const provider = settings.create(options);
+  if (!provider || typeof provider !== "object" || ["findOne", "findMany", "insert", "update", "remove", "count"].some((key) => typeof provider[key] !== "function"))
+    invalid("Expected a repository provider from create.");
+  descriptions.set(provider, Object.freeze({
+    kind: "provider",
+    name: settings.name,
+    options
+  }));
+  return provider;
+}
+export function providerDescriptionOf(provider) {
+  return descriptions.get(provider) ?? opaque;
+}

package/dist/core/repository/query.js

@@ -0,0 +1,153 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import { isBlueprintVariant } from "../blueprint/variant.js";
+import { InvalidRepositoryQuery } from "./exceptions.js";
+function plain(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+function isMembership(value) {
+  return plain(value) && Object.keys(value).length === 1 && Array.isArray(value.in);
+}
+const QUERY_OPTIONS = [
+  "where",
+  "orderBy",
+  "limit",
+  "offset",
+  "withDeleted",
+  "withExpired"
+];
+export function prepareQuery(context, input = {}, map = (_key, value) => value, options = QUERY_OPTIONS) {
+  const fail = (reason) => {
+    throw new InvalidRepositoryQuery({
+      source: context.name,
+      details: { reason }
+    });
+  };
+  if (!plain(input))
+    return fail("Expected a query object.");
+  for (const key of Object.keys(input))
+    if (!options.includes(key))
+      fail(`Unknown query option "${key}".`);
+  const properties = context.entity.blueprint.properties;
+  const keyOf = (key) => {
+    if (!Object.hasOwn(properties, key))
+      fail(`Unknown query field "${key}".`);
+  };
+  for (const name of ["limit", "offset"]) {
+    const value = input[name];
+    if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0))
+      fail(`Expected a nonnegative integer for ${name}.`);
+  }
+  if (input.withDeleted !== undefined && typeof input.withDeleted !== "boolean")
+    fail("Expected withDeleted to be boolean.");
+  if (input.withExpired !== undefined && typeof input.withExpired !== "boolean")
+    fail("Expected withExpired to be boolean.");
+  let where;
+  if (input.where !== undefined) {
+    if (!plain(input.where))
+      return fail("Expected where to be an object.");
+    where = Object.fromEntries(Object.entries(input.where).map(([key, value]) => {
+      keyOf(key);
+      return [
+        key,
+        isMembership(value) ? { in: value.in.map((item) => map(key, item)) } : map(key, value)
+      ];
+    }));
+  }
+  if (input.orderBy !== undefined) {
+    if (!Array.isArray(input.orderBy))
+      return fail("Expected orderBy to be an array.");
+    for (const order of input.orderBy) {
+      if (!plain(order) || typeof order.key !== "string" || Object.keys(order).some((key) => key !== "key" && key !== "direction"))
+        return fail("Expected an order with key and optional direction.");
+      keyOf(order.key);
+      if (order.direction !== undefined && order.direction !== "asc" && order.direction !== "desc")
+        fail("Expected order direction asc or desc.");
+      const field = properties[order.key];
+      if (isBlueprint(field) || isBlueprintList(field) || isBlueprintVariant(field) || recordFieldOf(field))
+        fail("Only scalar fields may be ordered.");
+    }
+  }
+  return { ...input, ...where ? { where } : {} };
+}
+export function sameValue(a, b) {
+  if (a === b)
+    return true;
+  if (a instanceof Date || b instanceof Date)
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+  if (Array.isArray(a) || Array.isArray(b))
+    return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, index) => sameValue(value, b[index]));
+  if (!plain(a) || !plain(b))
+    return false;
+  const keys = Object.keys(a);
+  return keys.length === Object.keys(b).length && keys.every((key) => Object.hasOwn(b, key) && sameValue(a[key], b[key]));
+}
+function isExpired(value, now) {
+  if (value === undefined || value === null)
+    return false;
+  const at = value instanceof Date ? value.getTime() : typeof value === "string" ? Date.parse(value) : Number.NaN;
+  return !Number.isNaN(at) && at <= now;
+}
+export function nowOf(query) {
+  const now = query.now === undefined ? Number.NaN : Date.parse(query.now);
+  return Number.isNaN(now) ? Date.now() : now;
+}
+export function matchesQuery(data, query, expiry, now = expiry === undefined ? 0 : nowOf(query)) {
+  return (query.withDeleted === true || data.deletedAt === undefined) && (expiry === undefined || query.withExpired === true || !isExpired(data[expiry], now)) && Object.entries(query.where ?? {}).every(([key, value]) => isMembership(value) ? value.in.some((candidate) => sameValue(data[key], candidate)) : sameValue(data[key], value));
+}
+function codePoints(text) {
+  return Array.from(text, (char) => char.codePointAt(0));
+}
+function rank(value) {
+  return value instanceof Date ? 1 : { number: 0, bigint: 0, string: 2, boolean: 3 }[typeof value] ?? 4;
+}
+function compareScalars(a, b) {
+  const [left, right] = [rank(a), rank(b)];
+  if (left !== right)
+    return left - right;
+  if (typeof a === "string" && typeof b === "string") {
+    const [x, y] = [codePoints(a), codePoints(b)];
+    for (let index = 0;index < Math.min(x.length, y.length); index++) {
+      const difference = x[index] - y[index];
+      if (difference !== 0)
+        return difference;
+    }
+    return x.length - y.length;
+  }
+  const [x, y] = [
+    a instanceof Date ? a.getTime() : Number(a),
+    b instanceof Date ? b.getTime() : Number(b)
+  ];
+  return x < y ? -1 : x > y ? 1 : 0;
+}
+function compareRows(orders, a, b) {
+  for (const { key, direction } of orders) {
+    const [x, y] = [a[key], b[key]];
+    const [missingX, missingY] = [
+      x === undefined || x === null,
+      y === undefined || y === null
+    ];
+    let result = missingX || missingY ? Number(!missingX) - Number(!missingY) : compareScalars(x, y);
+    if (direction === "desc")
+      result = -result;
+    if (result !== 0)
+      return result;
+  }
+  return 0;
+}
+function orderRows(rows, query) {
+  const orders = query.orderBy ?? [];
+  return [...rows].sort((a, b) => compareRows(orders, a, b));
+}
+function rowsAfter(rows, orders, after) {
+  const position = Object.fromEntries(orders.map(({ key }, index) => [key, after[index]]));
+  return rows.filter((row) => compareRows(orders, row, position) > 0);
+}
+export function selectRows(rows, query, expiry) {
+  const now = expiry === undefined ? 0 : nowOf(query);
+  const ordered = orderRows([...rows].filter((data) => matchesQuery(data, query, expiry, now)), query);
+  const matched = query.after === undefined ? ordered : rowsAfter(ordered, query.orderBy ?? [], query.after);
+  const start = query.offset ?? 0;
+  return matched.slice(start, query.limit === undefined ? undefined : start + query.limit);
+}