@afora/core 0.0.9 → 0.0.11

package/dist/core/application/exceptions.js

@@ -0,0 +1,85 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidApplicationDeclaration = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "InvalidApplicationDeclaration",
+  message: ({ reason }) => reason
+});
+export const DuplicateApplicationDeclaration = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "DuplicateApplicationDeclaration",
+  message: ({
+    first,
+    second
+  }) => `The same object is registered as ${first} and as ${second}.`
+});
+export const ApplicationConflict = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "ApplicationConflict",
+  message: ({
+    reason
+  }) => reason
+});
+export const UnregisteredApplicationReference = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "UnregisteredApplicationReference",
+  message: ({
+    holder,
+    reference
+  }) => `${holder} holds ${reference}, which is not registered in the application.`
+});
+export const UnregisteredRepositoryDependency = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "UnregisteredRepositoryDependency",
+  message: ({
+    repository,
+    dependency
+  }) => `Repository ${repository} depends on ${dependency}, which is not registered in the application.`
+});
+export const UnregisteredUseCaseDependency = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "UnregisteredUseCaseDependency",
+  message: ({
+    useCase,
+    dependency
+  }) => `Use case ${useCase} depends on ${dependency}, which is not registered in the application.`
+});
+export const ApplicationNotStarted = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "ApplicationNotStarted",
+  message: ({
+    application
+  }) => application === undefined ? "No application is started: call await app.start() first." : `The application "${application}" is not started: call await app.start() first.`
+});
+export const ProviderNotBound = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "ProviderNotBound",
+  message: ({
+    provider
+  }) => `The provider "${provider}" is made by an application: register its storage in applicationOf({ providers }) and call the repository through the application.`
+});
+export const ApplicationAlreadyStarted = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "ApplicationAlreadyStarted",
+  message: ({
+    current,
+    attempted
+  }) => `The application "${current}" is already started, so "${attempted}" cannot be: stop it, or call start({ replace: true }).`
+});
+export const SchemaLockMismatch = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "SchemaLockMismatch",
+  message: ({ problems }) => `The application does not match its schema lock: ${problems.join(" ")}`
+});
+export const InvalidSchemaMigration = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "InvalidSchemaMigration",
+  message: ({ reason }) => reason
+});
+export const InvalidApplicationEnvironment = exceptionOf({
+  layer: ExceptionLayers.Environment,
+  name: "InvalidApplicationEnvironment",
+  message: ({
+    environments
+  }) => `Invalid environment variables: ${Object.entries(environments).map(([name, keys]) => `${name} (${keys.join(", ")})`).join("; ")}.`
+});

package/dist/core/application/migrate.js

@@ -0,0 +1,67 @@
+import { migrateRepository } from "../repository/migrate.js";
+import { findState } from "../repository/state.js";
+import { InvalidSchemaMigration } from "./exceptions.js";
+import { diffSchemas, schemaLockOf } from "./schema.js";
+export async function migrateApplication(source, options) {
+  const fail = (reason) => {
+    throw new InvalidSchemaMigration({
+      source: source.name,
+      details: { reason }
+    });
+  };
+  if (typeof options !== "object" || options === null) {
+    fail('Expected the options of migrate, e.g. { mode: "check" }.');
+  }
+  const { mode, destructive = false, pageSize = 100, lock } = options;
+  if (mode !== "check" && mode !== "apply") {
+    fail('Expected mode to be "check" or "apply".');
+  }
+  if (typeof destructive !== "boolean") {
+    fail("Expected destructive to be a boolean.");
+  }
+  if (!Number.isSafeInteger(pageSize) || pageSize < 1) {
+    fail("Expected pageSize to be a positive integer.");
+  }
+  if (lock !== undefined && !isLock(lock)) {
+    fail("Expected lock to be a schema lock ({ lockVersion: 1, entities }).");
+  }
+  const byEntity = new Map;
+  for (const repository of source.repositories) {
+    const state = findState(repository);
+    if (state && !byEntity.has(state.entity))
+      byEntity.set(state.entity, state);
+  }
+  const names = options.entities ?? [...source.entities].filter(([, entity]) => byEntity.has(entity)).map(([name]) => name);
+  if (!Array.isArray(names))
+    fail("Expected entities to be a list of names.");
+  const targets = [];
+  for (const name of names) {
+    const entity = source.entities.get(name);
+    if (entity === undefined) {
+      fail(`"${name}" is not an entity of the application.`);
+    }
+    const state = byEntity.get(entity);
+    if (state === undefined) {
+      fail(`The entity "${name}" has no repository to migrate it through.`);
+    }
+    targets.push([name, state]);
+  }
+  const changes = lock === undefined ? [] : diffSchemas(lock, schemaLockOf(source.describe()));
+  const entities = {};
+  for (const [name, state] of targets) {
+    entities[name] = await migrateRepository(state, {
+      mode,
+      destructive,
+      pageSize,
+      plan: Object.freeze({
+        entity: name,
+        changes: changes.filter((change) => change.entity === name),
+        destructive
+      })
+    });
+  }
+  return { mode, destructive, entities };
+}
+export function isLock(value) {
+  return typeof value === "object" && value !== null && value.lockVersion === 1 && typeof value.entities === "object" && value.entities !== null;
+}

package/dist/core/application/providers.js

@@ -0,0 +1,108 @@
+import { Kind } from "../symbols/kind.js";
+import { InvalidApplicationDeclaration, ProviderNotBound } from "./exceptions.js";
+import { isProviderFactory } from "./start.js";
+const slots = new WeakMap;
+const storages = new WeakMap;
+const METHODS = [
+  "findOne",
+  "findMany",
+  "insert",
+  "update",
+  "remove",
+  "count"
+];
+const KEY = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const RESERVED = new Set(["inMemory", "__proto__", "constructor", "prototype"]);
+function invalid(reason) {
+  throw new InvalidApplicationDeclaration({
+    source: "providersOf",
+    details: { reason }
+  });
+}
+function isProviderObject(value) {
+  return typeof value === "object" && value !== null && !isProviderFactory(value) && METHODS.some((method) => typeof value[method] === "function");
+}
+function slotOf(key, storage, value) {
+  const slot = {
+    [Kind]: "provider-slot",
+    key
+  };
+  if (isProviderFactory(value)) {
+    const unbound = () => {
+      throw new ProviderNotBound({ source: key, details: { provider: key } });
+    };
+    for (const method of METHODS)
+      slot[method] = unbound;
+    slot.transaction = unbound;
+    slot.increment = unbound;
+    Object.defineProperty(slot, "capabilities", {
+      get: () => {
+        return;
+      },
+      enumerable: true
+    });
+  } else {
+    const target = value;
+    for (const method of [
+      ...METHODS,
+      "increment",
+      "transaction",
+      "close",
+      "migrate"
+    ]) {
+      if (typeof target[method] === "function") {
+        slot[method] = (...args) => target[method]?.(...args);
+      }
+    }
+    Object.defineProperty(slot, "capabilities", {
+      get: () => value.capabilities,
+      enumerable: true
+    });
+  }
+  Object.freeze(slot);
+  slots.set(slot, { key, storage, value });
+  return slot;
+}
+export function providersOf(entries) {
+  if (typeof entries !== "object" || entries === null || Array.isArray(entries) || Object.keys(entries).length === 0) {
+    invalid("Expected an object of providers by key.");
+  }
+  const storage = Object.create(null);
+  storage[Kind] = "provider-storage";
+  const seen = new Map;
+  const list = [];
+  for (const [key, value] of Object.entries(entries)) {
+    if (!KEY.test(key) || RESERVED.has(key)) {
+      invalid(key === "inMemory" ? `"inMemory" is the built-in provider; choose another key.` : `Expected "${key}" to be an identifier that is not reserved.`);
+    }
+    if (isProviderSlot(value)) {
+      invalid(`"${key}" holds a provider of another storage; a storage holds providers, not slots.`);
+    }
+    if (!isProviderFactory(value) && !isProviderObject(value)) {
+      invalid(`Expected "${key}" to be a repository provider or a factory of providerFrom.`);
+    }
+    const other = seen.get(value);
+    if (other !== undefined) {
+      invalid(`"${other}" and "${key}" hold the same provider.`);
+    }
+    seen.set(value, key);
+    const slot = slotOf(key, storage, value);
+    storage[key] = slot;
+    list.push(slot);
+  }
+  Object.freeze(storage);
+  storages.set(storage, Object.freeze(list));
+  return storage;
+}
+export function isProviderSlot(value) {
+  return typeof value === "object" && value !== null && slots.has(value);
+}
+export function isProviderStorage(value) {
+  return typeof value === "object" && value !== null && storages.has(value);
+}
+export function slotsOf(storage) {
+  return storages.get(storage) ?? [];
+}
+export function slotEntry(slot) {
+  return slots.get(slot);
+}

package/dist/core/application/registry.js

@@ -0,0 +1,23 @@
+import { ApplicationNotStarted } from "./exceptions.js";
+const SLOT = Symbol.for("afora.application");
+function slot() {
+  const global = globalThis;
+  global[SLOT] ??= { current: undefined };
+  return global[SLOT];
+}
+export function useApplication() {
+  const { current } = slot();
+  if (current === undefined) {
+    throw new ApplicationNotStarted({ source: "useApplication", details: {} });
+  }
+  return current;
+}
+export function resetApplication() {
+  slot().current = undefined;
+}
+export function startedApplication() {
+  return slot().current;
+}
+export function setStartedApplication(application) {
+  slot().current = application;
+}

package/dist/core/application/schema.js

@@ -0,0 +1,398 @@
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function sorted(value) {
+  if (Array.isArray(value))
+    return value.map(sorted);
+  if (!isObject(value))
+    return value;
+  return Object.fromEntries(Object.keys(value).filter((key) => !key.startsWith("~") && value[key] !== undefined).sort().map((key) => [key, sorted(value[key])]));
+}
+function evolutionOf(property, description, found = {}, depth = 0) {
+  if (property === undefined || depth > 64)
+    return found;
+  const resolved = "ref" in property ? description.properties[property.ref] : property;
+  const lineage = resolved?.lineage;
+  if (lineage === undefined || lineage.kind === "factory")
+    return found;
+  if (lineage.kind === "refined") {
+    const { fill, renamedFrom } = lineage.options;
+    if (!("fill" in found) && fill !== undefined)
+      found.fill = fill;
+    if (found.renamedFrom === undefined && typeof renamedFrom === "string") {
+      found.renamedFrom = renamedFrom;
+    }
+  }
+  return evolutionOf(lineage.base, description, found, depth + 1);
+}
+function fieldsOf(fields, description) {
+  if (fields === undefined)
+    return;
+  return Object.fromEntries(Object.keys(fields).sort().map((key) => [
+    key,
+    lockFieldOf(fields[key], description)
+  ]));
+}
+function lockFieldOf(field, description) {
+  switch (field.kind) {
+    case "property": {
+      const property = "ref" in field ? description.properties[field.ref] : field;
+      const evolution = evolutionOf("ref" in field ? { ref: field.ref } : field, description);
+      return {
+        schema: sorted(property?.schema ?? {}),
+        optional: field.optional,
+        ...property?.unique ? { unique: true } : {},
+        ..."fill" in evolution ? { fill: sorted(evolution.fill) } : {},
+        ...evolution.renamedFrom === undefined ? {} : { renamedFrom: evolution.renamedFrom }
+      };
+    }
+    case "list": {
+      const item = lockFieldOf(field.item, description);
+      return {
+        schema: sorted({
+          type: "array",
+          items: item.schema,
+          minItems: field.minItems,
+          maxItems: field.maxItems
+        }),
+        optional: field.optional,
+        ...item.fields === undefined ? {} : { fields: item.fields }
+      };
+    }
+    case "blueprint": {
+      const fields = "ref" in field ? description.blueprints[field.ref]?.fields : field.fields;
+      return {
+        schema: { type: "object" },
+        optional: field.optional,
+        fields: fieldsOf(fields, description) ?? {}
+      };
+    }
+    case "record": {
+      const fields = description.records[field.ref]?.fields;
+      return {
+        schema: { type: "object" },
+        optional: field.optional,
+        fields: fieldsOf(fields, description) ?? {}
+      };
+    }
+    case "variant":
+      return {
+        schema: { discriminator: field.key, type: "object" },
+        optional: field.optional,
+        fields: Object.fromEntries(Object.keys(field.variants).sort().map((tag) => [
+          tag,
+          {
+            ...lockFieldOf(field.variants[tag], description),
+            optional: true
+          }
+        ]))
+      };
+    case "entity":
+      return {
+        schema: { entity: field.ref, type: "string" },
+        optional: field.optional
+      };
+  }
+}
+function lockEntityOf(entity, description) {
+  const declared = fieldsOf(entity.fields, description) ?? {};
+  const unique = new Set(entity.options.unique.filter((key) => key !== "id"));
+  for (const [key, field] of Object.entries(declared)) {
+    if (field.unique)
+      unique.add(key);
+  }
+  const fields = Object.fromEntries(Object.entries(declared).map(([key, field]) => [
+    key,
+    unique.has(key) ? { ...field, unique: true } : field
+  ]));
+  return {
+    schemaVersion: entity.schemaVersion ?? 1,
+    previousNames: [...entity.previousNames ?? []].sort(),
+    unique: [...unique].sort(),
+    fields,
+    ...entity.upgrade === undefined || entity.upgrade.length === 0 ? {} : { upgrade: [...entity.upgrade].sort((a, b) => a - b) }
+  };
+}
+export function schemaLockOf(description) {
+  return {
+    lockVersion: 1,
+    entities: sorted(Object.fromEntries(Object.keys(description.entities).map((name) => [
+      name,
+      lockEntityOf(description.entities[name], description)
+    ])))
+  };
+}
+const METADATA = new Set([
+  "title",
+  "description",
+  "examples",
+  "default",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "$comment"
+]);
+const UPPER = new Set([
+  "maximum",
+  "exclusiveMaximum",
+  "maxLength",
+  "maxItems",
+  "maxProperties"
+]);
+const LOWER = new Set([
+  "minimum",
+  "exclusiveMinimum",
+  "minLength",
+  "minItems",
+  "minProperties"
+]);
+const NARROWING = new Set([
+  "pattern",
+  "format",
+  "multipleOf",
+  "allOf",
+  "const"
+]);
+const same = (a, b) => JSON.stringify(sorted(a)) === JSON.stringify(sorted(b));
+function literalsOf(schema) {
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map((value) => JSON.stringify(value));
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.every((item) => isObject(item) && ("const" in item))) {
+    return schema.anyOf.map((item) => JSON.stringify(item.const));
+  }
+  return;
+}
+function compareSchemas(previous, next) {
+  if (same(previous, next))
+    return "same";
+  const strip = (schema) => Object.fromEntries(Object.entries(schema).filter(([key]) => !METADATA.has(key)));
+  const [a, b] = [strip(previous), strip(next)];
+  if (same(a, b))
+    return "metadata";
+  if (!same(a.type, b.type) || !same(a.entity, b.entity))
+    return "type-changed";
+  const [before, after] = [literalsOf(a), literalsOf(b)];
+  let loosened = false;
+  let tightened = false;
+  if (before !== undefined || after !== undefined) {
+    if (before === undefined || after === undefined)
+      return "type-changed";
+    const kept = before.every((value) => after.includes(value));
+    const gained = after.some((value) => !before.includes(value));
+    if (!kept)
+      tightened = true;
+    if (gained)
+      loosened = true;
+  }
+  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (["type", "entity", "enum", "anyOf"].includes(key))
+      continue;
+    if (same(a[key], b[key]))
+      continue;
+    const [x, y] = [a[key], b[key]];
+    if (key === "items") {
+      const items = compareSchemas(isObject(x) ? x : {}, isObject(y) ? y : {});
+      if (items === "type-changed")
+        return "type-changed";
+      if (items === "tightened")
+        tightened = true;
+      if (items === "loosened")
+        loosened = true;
+    } else if (UPPER.has(key) || LOWER.has(key)) {
+      if (x === undefined)
+        tightened = true;
+      else if (y === undefined)
+        loosened = true;
+      else if (typeof x !== "number" || typeof y !== "number")
+        return "type-changed";
+      else if (UPPER.has(key) ? y > x : y < x)
+        loosened = true;
+      else
+        tightened = true;
+    } else if (NARROWING.has(key)) {
+      if (y === undefined)
+        loosened = true;
+      else
+        tightened = true;
+    } else {
+      return "type-changed";
+    }
+  }
+  if (tightened)
+    return "tightened";
+  return loosened ? "loosened" : "metadata";
+}
+function push(context, change, klass, satisfied, extra = {}) {
+  context.changes.push({
+    entity: context.entity,
+    ...extra.key === undefined ? {} : { key: extra.key },
+    change,
+    class: klass,
+    satisfied,
+    destructive: extra.destructive ?? false,
+    ...extra.from === undefined ? {} : { from: extra.from },
+    ...extra.detail === undefined ? {} : { detail: extra.detail }
+  });
+}
+const STEP = "an upgrade step (bump schemaVersion and add upgrade[n])";
+function diffFields(context, previous, next, path) {
+  const join = (key) => path ? `${path}.${key}` : key;
+  const renamedFrom = new Map;
+  for (const [key, field] of Object.entries(next)) {
+    const from = field.renamedFrom;
+    if (from !== undefined && !(key in previous) && from in previous && !(from in next)) {
+      renamedFrom.set(key, from);
+    }
+  }
+  const moved = new Set(renamedFrom.values());
+  const keys = [...new Set([...Object.keys(previous), ...Object.keys(next)])].filter((key) => !moved.has(key)).sort();
+  for (const key of keys) {
+    const was = previous[key];
+    const is = next[key];
+    if (is === undefined) {
+      push(context, "removed", "automatic", true, {
+        key: join(key),
+        destructive: true,
+        detail: "Left out on read; a backfill removes it only with destructive: true. Rename it with renamedFrom to keep the data."
+      });
+      continue;
+    }
+    const from = renamedFrom.get(key);
+    if (from !== undefined) {
+      push(context, "renamed", "declared", true, {
+        key: join(key),
+        from: join(from)
+      });
+      diffField(context, previous[from], is, join(key));
+      continue;
+    }
+    if (was === undefined) {
+      if (is.optional) {
+        push(context, "added-optional", "automatic", true, { key: join(key) });
+      } else {
+        const satisfied = "fill" in is || context.stepped;
+        push(context, "added-required", "declared", satisfied, {
+          key: join(key),
+          ...satisfied ? {} : {
+            detail: `Needs a fill (.with({ fill })) or ${STEP} that sets it.`
+          }
+        });
+      }
+      continue;
+    }
+    diffField(context, was, is, join(key));
+  }
+}
+function diffField(context, was, is, key) {
+  const compared = compareSchemas(was.schema, is.schema);
+  if (compared === "type-changed") {
+    push(context, "type-changed", "declared", context.stepped, {
+      key,
+      ...context.stepped ? {} : { detail: `Needs ${STEP} that converts the stored values.` }
+    });
+  } else if (compared === "tightened") {
+    const satisfied = context.stepped || "fill" in is;
+    push(context, "tightened", "declared", satisfied, {
+      key,
+      detail: satisfied ? "Run app.migrate({ mode: 'check' }) to list the rows that violate it." : `Needs ${STEP} or a fill; app.migrate({ mode: 'check' }) lists the rows that violate it.`
+    });
+  } else if (compared === "loosened") {
+    push(context, "loosened", "automatic", true, { key });
+  } else if (compared === "metadata") {
+    push(context, "metadata", "automatic", true, { key });
+  }
+  if (was.optional && !is.optional) {
+    const satisfied = context.stepped || "fill" in is;
+    push(context, "made-required", "declared", satisfied, {
+      key,
+      ...satisfied ? {} : {
+        detail: `Needs a fill (.with({ fill })) or ${STEP} for the rows without it.`
+      }
+    });
+  } else if (!was.optional && is.optional) {
+    push(context, "made-optional", "automatic", true, { key });
+  }
+  if (!was.unique && is.unique) {
+    push(context, "unique-added", "check", true, {
+      key,
+      detail: "Run app.migrate({ mode: 'check' }) and look for duplicates before it is enforced."
+    });
+  } else if (was.unique && !is.unique) {
+    push(context, "unique-removed", "automatic", true, { key });
+  }
+  if (was.fields !== undefined || is.fields !== undefined) {
+    diffFields(context, was.fields ?? {}, is.fields ?? {}, key);
+  }
+}
+function diffEntity(entity, from, to, changes) {
+  const stepped = to.schemaVersion > from.schemaVersion && (to.upgrade ?? []).some((version) => version > from.schemaVersion && version <= to.schemaVersion);
+  const context = { entity, from, to, stepped, changes };
+  diffFields(context, from.fields, to.fields, "");
+}
+export function diffSchemas(lock, current) {
+  const changes = [];
+  const claimed = new Set;
+  for (const name of Object.keys(current.entities).sort()) {
+    const to = current.entities[name];
+    let from = lock.entities[name];
+    if (from === undefined) {
+      const previous = to.previousNames.find((old) => lock.entities[old] !== undefined && !current.entities[old]);
+      if (previous === undefined) {
+        changes.push({
+          entity: name,
+          change: "entity-added",
+          class: "automatic",
+          satisfied: true,
+          destructive: false
+        });
+        continue;
+      }
+      claimed.add(previous);
+      from = lock.entities[previous];
+      changes.push({
+        entity: name,
+        change: "entity-renamed",
+        class: "declared",
+        satisfied: true,
+        destructive: true,
+        from: previous,
+        detail: "app.migrate moves its rows; it removes them from the previous name only with destructive: true."
+      });
+    }
+    diffEntity(name, from, to, changes);
+  }
+  for (const name of Object.keys(lock.entities).sort()) {
+    if (current.entities[name] !== undefined || claimed.has(name))
+      continue;
+    changes.push({
+      entity: name,
+      change: "entity-removed",
+      class: "declared",
+      satisfied: false,
+      destructive: true,
+      detail: `No entity is named "${name}": list it in the previousNames of the entity that replaces it, or remove it from the lock if it is gone.`
+    });
+  }
+  return changes;
+}
+export function schemaLockProblemsOf(lock, current) {
+  const problems = [];
+  const renamed = new Map;
+  for (const [name, entity] of Object.entries(current.entities)) {
+    for (const old of entity.previousNames) {
+      if (!renamed.has(old))
+        renamed.set(old, name);
+    }
+  }
+  for (const name of Object.keys(lock.entities).sort()) {
+    const locked = lock.entities[name];
+    const now = current.entities[name] === undefined ? renamed.get(name) : name;
+    const entity = now === undefined ? undefined : current.entities[now];
+    if (entity === undefined) {
+      problems.push(`The lock holds the entity "${name}", which no entity is named or lists in previousNames.`);
+    } else if (entity.schemaVersion < locked.schemaVersion) {
+      problems.push(`The schemaVersion of "${now}" (${entity.schemaVersion}) is lower than the lock's (${locked.schemaVersion}).`);
+    }
+  }
+  return problems;
+}