@afora/core 0.0.8 → 0.0.11

package/dist/core/application/exceptions.d.ts

@@ -57,6 +57,23 @@ export declare const ApplicationAlreadyStarted: import("../../index.js").Declare
     readonly current: string;
     readonly attempted: string;
 }>;
+/**
+ * `app.start({ lock })` found that the code cannot run over the stores the
+ * lock describes: an entity of the lock that no entity is named or lists in
+ * `previousNames` (renamed without it, its rows would no longer be read), or
+ * an entity whose `schemaVersion` is lower than the lock's.
+ * `details.problems` lists each.
+ */
+export declare const SchemaLockMismatch: import("../../index.js").DeclaredExceptionClass<{
+    readonly problems: readonly string[];
+}>;
+/**
+ * `app.migrate` got invalid options, or names an entity without a
+ * repository; `source` is the application name.
+ */
+export declare const InvalidSchemaMigration: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;
 /**
  * `app.start()` found environments whose variables are missing or rejected;
  * `details.environments` gives the keys of each, by name.

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.d.ts

@@ -0,0 +1,19 @@
+import type { SchemaLock, SchemaMigrationOptions, SchemaMigrationReport } from "../repository/types/schema.interface.js";
+import type { ApplicationDescription } from "./types/application.interface.js";
+/** What `app.migrate` reads from its application. */
+export interface MigrationSource {
+    readonly name: string;
+    /** Its entities, by name. */
+    readonly entities: ReadonlyMap<string, object>;
+    /** Its bound repositories. */
+    readonly repositories: readonly object[];
+    describe(): ApplicationDescription;
+}
+/**
+ * `app.migrate(options)`: for each entity with a repository (or those of
+ * `options.entities`), the backfill of `migrateRepository` through the
+ * provider of its first repository, one entity after the other.
+ */
+export declare function migrateApplication(source: MigrationSource, options: SchemaMigrationOptions): Promise<SchemaMigrationReport>;
+/** Whether `value` has the shape of a schema lock. */
+export declare function isLock(value: unknown): value is SchemaLock;

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.d.ts

@@ -0,0 +1,30 @@
+import type { SchemaChange, SchemaLock } from "../repository/types/schema.interface.js";
+import type { ApplicationDescription } from "./types/application.interface.js";
+/**
+ * The lock of the entities of `description` (`app.describe()`): per entity,
+ * its schema version, previous names, unique keys and fields (each with its
+ * JSON Schema, whether it is optional or unique, its `fill` and
+ * `renamedFrom`, and the fields of a nested blueprint or record), with
+ * registered properties, blueprints and records resolved and every key
+ * sorted, so equivalent applications give equal locks. The identity keys
+ * and the keys of record plugins are left out.
+ */
+export declare function schemaLockOf(description: ApplicationDescription): SchemaLock;
+/**
+ * The changes from `lock` to `current` (both made by `schemaLockOf`), each
+ * classed as `automatic` (afora handles it: an optional key added, a key
+ * removed, a constraint loosened, metadata), `declared` (it needs a `fill`,
+ * a `renamedFrom`, `previousNames` or an `upgrade` step to a version above
+ * the lock's; `satisfied` says whether the code has it) or `check` (a new
+ * unique key: the stored rows must be checked first). `destructive` marks
+ * what deletes stored data once applied: a removed key, the rows of a
+ * previous name, a removed entity. Nested blueprints and records are
+ * compared key by key. Ordered by entity name, then key.
+ */
+export declare function diffSchemas(lock: SchemaLock, current: SchemaLock): readonly SchemaChange[];
+/**
+ * Why the code cannot run over the stores `lock` describes: an entity of
+ * the lock that no entity is named, or lists in its `previousNames`, or an
+ * entity whose `schemaVersion` is lower than the lock's. Empty when it can.
+ */
+export declare function schemaLockProblemsOf(lock: SchemaLock, current: SchemaLock): readonly string[];