@afora/core 0.0.9 → 0.0.11

package/dist/core/repository/state.js

@@ -0,0 +1,138 @@
+import {
+  EntitySettings,
+  EntityUniqueKeys,
+  EXPIRES_AT,
+  SCHEMA_VERSION_KEY
+} from "../entity/abstract-entity.js";
+import {
+  loadEnvironments
+} from "../environment/environment.js";
+import { RepositoryUsedOutsideApplication } from "./exceptions.js";
+export const states = new WeakMap;
+export function findState(repository) {
+  if (typeof repository !== "object" || repository === null)
+    return;
+  for (let Class = repository.constructor;typeof Class === "function"; Class = Object.getPrototypeOf(Class)) {
+    const state = states.get(Class);
+    if (state)
+      return state;
+  }
+  return;
+}
+export function stateOf(repository) {
+  const state = findState(repository);
+  if (!state)
+    throw new TypeError("Expected a repository made by repositoryOf");
+  return state;
+}
+function expiryKeyOf(entity) {
+  const expires = entity[EntitySettings]?.expires;
+  if (expires === undefined)
+    return;
+  return "at" in expires ? expires.at : EXPIRES_AT;
+}
+
+export { SCHEMA_VERSION_KEY };
+function schemaOf(entity) {
+  const settings = entity[EntitySettings];
+  if (!settings?.schemaVersioned)
+    return;
+  return Object.freeze({
+    version: settings.schemaVersion,
+    key: SCHEMA_VERSION_KEY,
+    previousNames: settings.previousNames
+  });
+}
+export function contextOf(state) {
+  if (state.context)
+    return state.context;
+  const key = expiryKeyOf(state.entity);
+  const schema = schemaOf(state.entity);
+  state.context = Object.freeze({
+    entity: state.entity,
+    name: state.name,
+    unique: state.entity[EntityUniqueKeys],
+    indexes: state.indexes,
+    ...key === undefined ? {} : { expiry: Object.freeze({ key }) },
+    ...schema === undefined ? {} : { schema },
+    env: loadEnvironments(state.environment)
+  });
+  return state.context;
+}
+export function inspectRepository(repository) {
+  const state = findState(repository);
+  if (!state)
+    return;
+  const { environment } = state;
+  return {
+    entity: state.entity,
+    actions: state.actions,
+    deletion: state.deletion,
+    indexes: state.indexes,
+    scans: state.scans,
+    explicitProvider: state.explicitProvider,
+    provider: state.explicitProvider ? state.provider : undefined,
+    environments: environment === undefined ? [] : Array.isArray(environment) ? environment : [environment],
+    relations: [...state.relations.values()].map(declarationOf),
+    state: declarationOf(state)
+  };
+}
+const origins = new WeakMap;
+function declarationOf(state) {
+  return origins.get(state) ?? state;
+}
+const declared = new WeakMap;
+export function declareRepository(state, repository) {
+  declared.set(state, repository);
+}
+export function relatedRepositoryOf(repository, Entity) {
+  const related = findState(repository)?.relations.get(Entity);
+  return related ? declared.get(declarationOf(related)) : undefined;
+}
+function bindState(state, provider, instances, logger, bound = new Map) {
+  const done = bound.get(state);
+  if (done)
+    return done;
+  const copy = {
+    ...state,
+    logger,
+    provider: state.explicitProvider ? instances?.get(state.provider) ?? state.provider : provider ?? state.provider,
+    context: undefined,
+    relations: new Map([...state.relations].map(([target, related]) => [
+      target,
+      bindState(related, provider, instances, logger, bound)
+    ]))
+  };
+  origins.set(copy, declarationOf(state));
+  bound.set(state, copy);
+  return copy;
+}
+const owners = new WeakMap;
+export function assertUnbound(state) {
+  const owner = owners.get(state);
+  if (owner) {
+    throw new RepositoryUsedOutsideApplication({
+      source: state.name,
+      details: owner
+    });
+  }
+}
+export function bindRepository(repository, provider, instances, binding) {
+  const state = stateOf(repository);
+  const Declared = repository.constructor;
+
+  class Bound extends Declared {
+  }
+  Object.defineProperty(Bound, "name", { value: Declared.name });
+  states.set(Bound, bindState(state, provider, instances, binding?.logger));
+  if (binding) {
+    owners.set(declarationOf(state), {
+      application: binding.application,
+      repository: binding.key
+    });
+  }
+  return Object.freeze(new Bound);
+}
+export function providerOfRepository(repository) {
+  return findState(repository)?.provider;
+}

package/dist/core/repository/types/query.interface.d.ts

@@ -98,6 +98,7 @@ export interface RepositoryPlan {
  * throw `InvalidRepositoryQuery` before the provider is called (`"reject"`).
  */
 export type RepositoryScans = "allow" | "warn" | "reject";
+/** The `explain` method of a repository, for the actions that list it. */
 export interface RepositoryExplain<Entity> {
     /**
      * How the query would be read (`{ access, index? }`), without reading
@@ -105,6 +106,7 @@ export interface RepositoryExplain<Entity> {
      */
     explain(query?: RepositoryQuery<Entity> | RepositoryCursorQuery<Entity>): Promise<RepositoryPlan>;
 }
+/** The `findCursor` method of a repository, for the actions that list it. */
 export interface RepositoryFindCursor<Entity> {
     /**
      * A page of `limit` items (20 by default) after the cursor `after`. Unlike
@@ -145,6 +147,7 @@ export interface RepositoryWalkResult {
     /** The items of those pages. */
     readonly items: number;
 }
+/** The `forEachPage` method of a repository, for the actions that list it. */
 export interface RepositoryForEachPage<Entity> {
     /**
      * Reads the pages of `query` by cursor, as `findCursor` does, and runs
@@ -155,12 +158,21 @@ export interface RepositoryForEachPage<Entity> {
      */
     forEachPage(query: RepositoryCursorQuery<Entity>, fn: (items: EntityInstanceOf<Entity>[], page: RepositoryWalkPage) => unknown, options?: RepositoryWalkOptions): Promise<RepositoryWalkResult>;
 }
+/**
+ * The `findMany` method of a repository: the entities that match a query, all
+ * of them without one.
+ */
 export interface RepositoryFindMany<Entity> {
     findMany(query?: RepositoryQuery<Entity>): Promise<EntityInstanceOf<Entity>[]>;
 }
+/** The `exists` method of a repository: whether any entity matches a query. */
 export interface RepositoryExists<Entity> {
     exists(query?: RepositoryQuery<Entity>): Promise<boolean>;
 }
+/**
+ * The `findPage` method of a repository: one page of the entities that match a
+ * query, with its total.
+ */
 export interface RepositoryFindPage<Entity> {
     /** Defaults to limit 20 and offset 0. */
     findPage(query?: RepositoryQuery<Entity>): Promise<RepositoryPage<Entity>>;
@@ -169,6 +181,7 @@ export interface RepositoryFindPage<Entity> {
 export type ProviderOption = null | boolean | number | string | readonly ProviderOption[] | {
     readonly [key: string]: ProviderOption;
 };
+/** The JSON options of a named provider, as its description keeps them. */
 export type ProviderOptions = Readonly<Record<string, ProviderOption>>;
 /** A named provider can be reconstructed; opaque providers require an import mapping. */
 export type ProviderDescription = {

package/dist/core/repository/types/repository.interface.d.ts

@@ -31,11 +31,20 @@ type ValueAt<Entity, Key extends string> = Key extends keyof EntityValueOf<Entit
 export type QueryValueOf<Value> = Value extends readonly (infer Item)[] ? Item extends AbstractEntity<any> ? readonly (Item | string)[] : Value : Value extends AbstractEntity<any> ? Value | string : Value;
 /** What `create` takes: an entity, or the input that builds one. */
 export type RepositoryCreateInput<Entity> = EntityInstanceOf<Entity> | (Entity extends new (value: infer Input) => unknown ? Input : never);
-/** `create`: stores the entity, or a new one built from the input, and gives it. */
+/**
+ * `create`: stores the entity, or a new one built from the input, and gives it.
+ *
+ * @throws {@link RepositoryUniqueViolation} when another entity holds the same value of a unique key (`id` included).
+ */
 export interface RepositoryCreate<Entity> {
     create(entity: RepositoryCreateInput<Entity>): Promise<EntityInstanceOf<Entity>>;
 }
-/** `update`: stores the current value of an entity it holds, and gives it. */
+/**
+ * `update`: stores the current value of an entity it holds, and gives it.
+ *
+ * @throws {@link RepositoryUniqueViolation} when another entity holds the same value of a unique key.
+ * @throws {@link RepositoryEntityNotFound} when the repository holds no entity with its id.
+ */
 export interface RepositoryUpdate<Entity> {
     update(entity: EntityInstanceOf<Entity>): Promise<EntityInstanceOf<Entity>>;
 }
@@ -197,12 +206,6 @@ export interface RepositoryContext<Environment = unknown> {
     /** The variables of the `environmentDependencies` of the repository. */
     readonly env: Environment;
 }
-/**
- * How a repository reads and writes: plain values of its entity, by its
- * context. `insert` and `update` enforce `context.unique`, throwing
- * `RepositoryUniqueViolation`; `update` and `remove` throw
- * `RepositoryEntityNotFound` for an unknown id.
- */
 /**
  * What `IRepositoryProvider.migrate` gives when it did not apply the plan to
  * the store (it wrote it to a file to be run later): `app.migrate` skips the
@@ -211,6 +214,15 @@ export interface RepositoryContext<Environment = unknown> {
 export type ProviderMigrationResult = {
     readonly deferred: true;
 };
+/**
+ * How a repository reads and writes: plain values of its entity, by its
+ * context. Implement it to store entities somewhere else; `inMemoryProvider`
+ * is the default, and `providerContract` (from `@afora/core/testing`) checks
+ * an implementation.
+ *
+ * @throws {@link RepositoryUniqueViolation} from `insert` and `update`, when they would break `context.unique`.
+ * @throws {@link RepositoryEntityNotFound} from `update` and `remove`, for an unknown id.
+ */
 export interface IRepositoryProvider<Environment = unknown> {
     findOne(context: RepositoryContext<Environment>, query?: ProviderQuery): Promise<RepositoryData | undefined>;
     /** `query.after` is only given to a provider with `capabilities.keyset`. */

package/dist/core/repository/types/schema.interface.d.ts

@@ -73,10 +73,16 @@ export interface SchemaMigrationOptions {
     readonly mode: "check" | "apply";
     /**
      * Remove the keys the blueprints no longer declare from the stored rows,
-     * and the rows under `previousNames` once moved. Default `false`.
+     * and the rows under `previousNames` once moved.
+     *
+     * @default false
      */
     readonly destructive?: boolean;
-    /** Rows read per page. Default 100. */
+    /**
+     * Rows read per page.
+     *
+     * @default 100
+     */
     readonly pageSize?: number;
     /**
      * The committed lock (`afora.lock.json`): in `apply`, the changes of each

package/dist/core/repository/upcast.js

@@ -0,0 +1,179 @@
+import { fieldOf } from "../blueprint/callable.js";
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { recordFieldOf } from "../blueprint/record-field.js";
+import { EntitySettings, SCHEMA_VERSION_KEY } from "../entity/abstract-entity.js";
+import { isEntityClass } from "../entity/entity.js";
+import { isProperty } from "../property/is-property.js";
+import {
+  InvalidRepositoryData,
+  InvalidStoredSchemaVersion
+} from "./exceptions.js";
+const isPlain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function stepOf(field) {
+  if (field === undefined)
+    return { kind: "opaque" };
+  if (isBlueprintList(field))
+    return { kind: "list", item: stepOf(field.item) };
+  if (isBlueprint(field)) {
+    return { kind: "collection", fields: stepsOf(field.properties) };
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    if (isEntityClass(record.record))
+      return { kind: "opaque" };
+    return {
+      kind: "collection",
+      fields: stepsOf(record.record.blueprint.properties)
+    };
+  }
+  const property = fieldOf(field);
+  if (!isProperty(property))
+    return { kind: "opaque" };
+  const { fill, renamedFrom } = property.type;
+  return {
+    kind: "property",
+    ...fill === undefined ? {} : { fill },
+    ...renamedFrom === undefined ? {} : { renamedFrom }
+  };
+}
+function stepsOf(properties) {
+  return {
+    fields: new Map(Object.entries(properties).map(([key, field]) => [key, stepOf(field)]))
+  };
+}
+function declaresSteps(steps) {
+  const visit = (step) => {
+    switch (step.kind) {
+      case "property":
+        return step.fill !== undefined || step.renamedFrom !== undefined;
+      case "collection":
+        return declaresSteps(step.fields);
+      case "list":
+        return visit(step.item);
+      case "opaque":
+        return false;
+    }
+  };
+  for (const step of steps.fields.values())
+    if (visit(step))
+      return true;
+  return false;
+}
+const plans = new WeakMap;
+function upcastPlanOf(entity) {
+  const cached = plans.get(entity);
+  if (cached !== undefined)
+    return cached ?? undefined;
+  const plan = fullUpcastPlanOf(entity);
+  const needed = plan.versioned || plan.renamed || declaresSteps(plan.fields) ? plan : null;
+  plans.set(entity, needed);
+  return needed ?? undefined;
+}
+export function fullUpcastPlanOf(entity) {
+  const settings = entity[EntitySettings];
+  return {
+    versioned: settings?.schemaVersioned === true,
+    version: settings?.schemaVersion ?? 1,
+    renamed: (settings?.previousNames.length ?? 0) > 0,
+    upgrade: settings?.upgrade ?? {},
+    fields: stepsOf(entity.blueprint.properties)
+  };
+}
+const join = (path, key) => path ? `${path}.${key}` : key;
+const fillOf = (value) => typeof value === "object" && value !== null ? structuredClone(value) : value;
+function applySteps(steps, value, drop, path, report) {
+  const result = { ...value };
+  for (const [key, step] of steps.fields) {
+    if (step.kind !== "property" || step.renamedFrom === undefined)
+      continue;
+    const from = step.renamedFrom;
+    if (result[key] === undefined && Object.hasOwn(result, from)) {
+      result[key] = result[from];
+      delete result[from];
+      report?.renamed.push(join(path, key));
+    }
+  }
+  for (const [key, step] of steps.fields) {
+    const current = result[key];
+    if (current === undefined || current === null) {
+      if (step.kind === "property" && step.fill !== undefined && current === undefined) {
+        result[key] = fillOf(step.fill);
+        report?.filled.push(join(path, key));
+      }
+      continue;
+    }
+    result[key] = applyField(step, current, drop, join(path, key), report);
+  }
+  for (const key of Object.keys(result)) {
+    if (steps.fields.has(key))
+      continue;
+    if (result[key] !== undefined)
+      report?.removed.push(join(path, key));
+    if (drop)
+      delete result[key];
+  }
+  return result;
+}
+function applyField(step, value, drop, path, report) {
+  switch (step.kind) {
+    case "collection":
+      return isPlain(value) ? applySteps(step.fields, value, drop, path, report) : value;
+    case "list":
+      return Array.isArray(value) ? value.map((item) => item === undefined || item === null ? item : applyField(step.item, item, drop, `${path}[]`, report)) : value;
+    default:
+      return value;
+  }
+}
+function storedVersionOf(data) {
+  return Object.hasOwn(data, SCHEMA_VERSION_KEY) ? data[SCHEMA_VERSION_KEY] : 1;
+}
+export function upcast(source, plan, data, drop = true, report) {
+  const stored = storedVersionOf(data);
+  if (typeof stored !== "number" || !Number.isSafeInteger(stored) || stored < 1 || stored > plan.version) {
+    throw new InvalidStoredSchemaVersion({
+      source,
+      details: { id: String(data.id), stored, current: plan.version }
+    });
+  }
+  if (report)
+    report.from = stored;
+  let value = { ...data };
+  delete value[SCHEMA_VERSION_KEY];
+  for (let version = stored + 1;version <= plan.version; version++) {
+    const step = plan.upgrade[version];
+    if (step === undefined)
+      continue;
+    const next = step(Object.freeze(value));
+    if (!isPlain(next)) {
+      throw new InvalidStoredSchemaVersion({
+        source,
+        details: {
+          id: String(data.id),
+          stored,
+          current: plan.version,
+          reason: `The upgrade step ${version} did not give an object.`
+        }
+      });
+    }
+    value = { ...next };
+    delete value[SCHEMA_VERSION_KEY];
+  }
+  return applySteps(plan.fields, value, drop, "", report);
+}
+export function upcastRows(state, rows) {
+  const plan = upcastPlanOf(state.entity);
+  if (plan === undefined)
+    return rows;
+  return rows.map((row) => {
+    try {
+      return upcast(state.name, plan, row);
+    } catch (error) {
+      throw new InvalidRepositoryData({ source: state.name, cause: error });
+    }
+  });
+}
+export function withSchemaVersion(entity, data) {
+  const plan = upcastPlanOf(entity);
+  return plan?.versioned ? { ...data, [SCHEMA_VERSION_KEY]: plan.version } : data;
+}

package/dist/core/schema/schema.d.ts

@@ -33,6 +33,15 @@ export interface SchemaChecks {
  * @internal
  */
 export declare function checksOfSchema(schema: ISchema<TSchema>): SchemaChecks;
+/**
+ * The TypeBox schema of `schema`, as it was given, without compiling it:
+ * `schema.type.Type()` gives the same schema but compiles it first, which is
+ * most of the time spent at import when only the schema is read (the
+ * meta-schema of `ctx.schema` alone takes milliseconds). A schema not made
+ * by `schemaOf` is asked through `type`.
+ * @internal
+ */
+export declare function rawTypeOf<SchemaType extends TSchema>(schema: ISchema<SchemaType>): SchemaType;
 /** A schema class declared with `schemaOf`. */
 export interface SchemaClass<SchemaType extends TSchema> {
     new (type?: SchemaType): ISchema<SchemaType>;