@afora/core 0.0.8 → 0.0.11

package/dist/core/repository/state.d.ts

@@ -1,3 +1,4 @@
+import { SCHEMA_VERSION_KEY } from "../entity/abstract-entity.js";
 import { type EnvironmentDependencies } from "../environment/environment.js";
 import type { ILogger } from "../logger/logger.js";
 import type { RepositoryIndex, RepositoryScans } from "./types/query.interface.js";
@@ -27,6 +28,7 @@ export declare const states: WeakMap<object, RepositoryState>;
 export declare function findState(repository: unknown): RepositoryState | undefined;
 /** The state of the repository class of `repository`, or of a class it extends. */
 export declare function stateOf(repository: object): RepositoryState;
+export { SCHEMA_VERSION_KEY };
 /** The context of the provider, with the environment read on first use. */
 export declare function contextOf(state: RepositoryState): RepositoryContext;
 /** What an application reads from a repository, without reaching its state. */

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

@@ -4,6 +4,7 @@ import type { AnyEntityClass } from "../../entity/event.js";
 import type { RecordSettings } from "../../record/types/record.interface.js";
 import type { AbstractRepository } from "../repository.js";
 import type { ProviderCapabilities, ProviderQuery, RepositoryExists, RepositoryExplain, RepositoryFindCursor, RepositoryFindMany, RepositoryFindPage, RepositoryForEachPage, RepositoryIndex, RepositoryQuery } from "./query.interface.js";
+import type { SchemaPlan } from "./schema.interface.js";
 /** Any class made by `entityOf`, or extending one, that a repository holds. */
 export type AnyRepositoryEntity = AnyRecordClass & AnyEntityClass & {
     readonly [EntityUniqueKeys]: readonly string[];
@@ -30,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>>;
 }
@@ -154,6 +164,12 @@ export interface ProviderIncrementOptions {
      */
     readonly now?: string;
 }
+/** `RepositoryContext.schema`. */
+export interface RepositorySchema {
+    readonly version: number;
+    readonly key: string;
+    readonly previousNames: readonly string[];
+}
 /** What a provider gets with every call: whose entities, and the environment. */
 export interface RepositoryContext<Environment = unknown> {
     /** The entity class; name a table after `recordNameOf(entity)`, not `entity.name`. */
@@ -180,14 +196,32 @@ export interface RepositoryContext<Environment = unknown> {
     readonly expiry?: {
         readonly key: string;
     };
+    /**
+     * For an entity declared with `schemaVersion`: the current version, the
+     * key of each row holding it (`SCHEMA_VERSION_KEY`, which repositories
+     * write and strip, so a provider keeping it in a column of its own maps
+     * that key), and the names the entity had before.
+     */
+    readonly schema?: RepositorySchema;
     /** The variables of the `environmentDependencies` of the repository. */
     readonly env: Environment;
 }
+/**
+ * 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
+ * backfill of the entity and reports it `deferred`.
+ */
+export type ProviderMigrationResult = {
+    readonly deferred: true;
+};
 /**
  * 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.
+ * 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>;
@@ -218,5 +252,16 @@ export interface IRepositoryProvider<Environment = unknown> {
     transaction?<Result>(run: (provider: IRepositoryProvider<Environment>) => Promise<Result>): Promise<Result>;
     /** Releases what the provider holds (connections, files); `app.stop()` calls it. */
     close?(): void | Promise<void>;
+    /**
+     * Applies the structural part of `plan` (columns, tables) for a provider
+     * with a schema of its own, as SQL; `app.migrate({ mode: "apply" })` calls
+     * it before the backfill. Document stores leave it out: they rely on the
+     * upgrade on read and the backfill. Only destructive changes when
+     * `plan.destructive`. Gives `{ deferred: true }` when it did not apply
+     * the plan to the store (it wrote it to a file to be run later): the
+     * backfill of the entity is then skipped, as its rows cannot be written
+     * in the new shape yet.
+     */
+    migrate?(context: RepositoryContext<Environment>, plan: SchemaPlan): Promise<void | ProviderMigrationResult>;
 }
 export {};

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

@@ -0,0 +1,132 @@
+import type { Issue } from "../../parse/types/parse.interface.js";
+/**
+ * Schema evolution: the lock of the stored shapes, the changes between two of
+ * them, and the plan a provider applies (`IRepositoryProvider.migrate`).
+ */
+/** What a change between two shapes is. */
+export type SchemaChangeKind = "added-required" | "added-optional" | "removed" | "renamed" | "type-changed" | "tightened" | "loosened" | "made-optional" | "made-required" | "metadata" | "unique-added" | "unique-removed" | "entity-added" | "entity-removed" | "entity-renamed";
+/**
+ * Whether afora handles a change alone (`automatic`), needs it declared
+ * (`fill`, `renamedFrom`, `previousNames`, an `upgrade` step: `declared`), or
+ * needs the stored rows checked before it holds (`check`).
+ */
+export type SchemaChangeClass = "automatic" | "declared" | "check";
+/** One change of an entity between the lock and the code. */
+export interface SchemaChange {
+    /** The entity, by its current name (its previous one when removed). */
+    readonly entity: string;
+    /** The path of the key, dot separated for nested blueprints; absent for the entity itself. */
+    readonly key?: string;
+    readonly change: SchemaChangeKind;
+    readonly class: SchemaChangeClass;
+    /** Whether the code declares what the change needs (always true when `automatic`). */
+    readonly satisfied: boolean;
+    /** Whether applying it deletes stored data (a removed key, the rows of an old name). */
+    readonly destructive: boolean;
+    /** For `renamed` and `entity-renamed`, the old name. */
+    readonly from?: string;
+    /** What is missing or what to check, for messages and stubs. */
+    readonly detail?: string;
+}
+/** A key of an entity in the lock. */
+export interface SchemaLockField {
+    /** The JSON Schema of the value. */
+    readonly schema: Readonly<Record<string, unknown>>;
+    readonly optional: boolean;
+    readonly unique?: boolean;
+    readonly fill?: unknown;
+    readonly renamedFrom?: string;
+    /** The keys of a nested blueprint or record. */
+    readonly fields?: Readonly<Record<string, SchemaLockField>>;
+}
+/** An entity in the lock. */
+export interface SchemaLockEntity {
+    readonly schemaVersion: number;
+    readonly previousNames: readonly string[];
+    readonly unique: readonly string[];
+    readonly fields: Readonly<Record<string, SchemaLockField>>;
+    /**
+     * The versions its `upgrade` has a step to, ascending; absent when none.
+     * `diffSchemas` reads it from the current side to tell whether a change
+     * that needs a step has one.
+     */
+    readonly upgrade?: readonly number[];
+}
+/** `afora.lock.json`: the stored shapes, by entity name, normalized. */
+export interface SchemaLock {
+    readonly lockVersion: 1;
+    readonly entities: Readonly<Record<string, SchemaLockEntity>>;
+}
+/** What `IRepositoryProvider.migrate` gets: the changes of one entity. */
+export interface SchemaPlan {
+    /** The entity, by its current name. */
+    readonly entity: string;
+    readonly changes: readonly SchemaChange[];
+    /** Whether destructive changes may be applied (`app.migrate({ destructive })`). */
+    readonly destructive: boolean;
+}
+/** What `app.migrate` takes. */
+export interface SchemaMigrationOptions {
+    /** The entities to walk, by name; every entity with a repository by default. */
+    readonly entities?: readonly string[];
+    /** `check` only reads and reports; `apply` rewrites the rows. */
+    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
+     */
+    readonly destructive?: boolean;
+    /**
+     * Rows read per page.
+     *
+     * @default 100
+     */
+    readonly pageSize?: number;
+    /**
+     * The committed lock (`afora.lock.json`): in `apply`, the changes of each
+     * entity from it to the code are the plan given to
+     * `IRepositoryProvider.migrate`. Without it the plan has no changes.
+     */
+    readonly lock?: SchemaLock;
+}
+/** A row `app.migrate` cannot bring up to the current shape. */
+export interface SchemaMigrationInvalidRow {
+    readonly id: string;
+    /** Why: the issues of the parse, or one for an error of the upgrade. */
+    readonly issues: readonly Issue[];
+}
+/** What `app.migrate` found and did for one entity. */
+export interface EntityMigrationReport {
+    /** Rows read, under the current name and the previous ones. */
+    readonly scanned: number;
+    /** Rows that needed nothing. */
+    readonly upToDate: number;
+    /** Rows rewritten in the current shape (in `check`, that would be). */
+    readonly upgraded: number;
+    /**
+     * Rows whose only pending change is removing keys, left as they are
+     * without `destructive`.
+     */
+    readonly removalPending: number;
+    /** Rows the entity rejects once brought up, left as they are. */
+    readonly invalid: readonly SchemaMigrationInvalidRow[];
+    /** Rows moved from a previous name (in `check`, that would be). */
+    readonly movedFromPreviousNames: number;
+    /** Paths of the stored keys the blueprint no longer declares, sorted. */
+    readonly removedKeys: readonly string[];
+    /**
+     * Whether `provider.migrate` deferred the plan (`{ deferred: true }`, it
+     * wrote it to be run later): the rows were then not walked, and every
+     * count is 0. Run `app.migrate` again once the plan is applied.
+     */
+    readonly deferred: boolean;
+}
+/** What `app.migrate` gives. */
+export interface SchemaMigrationReport {
+    readonly mode: "check" | "apply";
+    readonly destructive: boolean;
+    /** By entity name. */
+    readonly entities: Readonly<Record<string, EntityMigrationReport>>;
+}

package/dist/core/repository/upcast.d.ts

@@ -0,0 +1,64 @@
+import type { EntityUpgrades } from "../entity/types/entity.interface.js";
+import type { RepositoryState } from "./state.js";
+import type { RepositoryData } from "./types/repository.interface.js";
+/** What happens to the value of one key of a collection. */
+type FieldStep = {
+    readonly kind: "property";
+    readonly fill?: unknown;
+    readonly renamedFrom?: string;
+} | {
+    readonly kind: "collection";
+    readonly fields: CollectionSteps;
+} | {
+    readonly kind: "list";
+    readonly item: FieldStep;
+} | {
+    readonly kind: "opaque";
+};
+/** The steps of the keys of a blueprint, and whether any of them does something. */
+interface CollectionSteps {
+    readonly fields: ReadonlyMap<string, FieldStep>;
+}
+/** How the rows of an entity are brought up to its current shape. */
+export interface UpcastPlan {
+    readonly versioned: boolean;
+    readonly version: number;
+    /** Whether the entity lists `previousNames`: its moved rows may hold old keys. */
+    readonly renamed: boolean;
+    readonly upgrade: EntityUpgrades;
+    readonly fields: CollectionSteps;
+}
+/** What `upcast` did to a row, for `app.migrate`. */
+export interface UpcastReport {
+    /** The version the row was stored at (1 without the version key). */
+    from: number;
+    /** Paths of the keys moved from their `renamedFrom`. */
+    readonly renamed: string[];
+    /** Paths of the keys given their `fill`. */
+    readonly filled: string[];
+    /** Paths of the keys the blueprint no longer declares. */
+    readonly removed: string[];
+}
+/** The plan of `entity`, even when it changes nothing but the keys it no longer declares. */
+export declare function fullUpcastPlanOf(entity: object): UpcastPlan;
+/**
+ * `data`, a row of an entity of `plan` as a provider gave it, in the current
+ * shape: without the version key, through each `upgrade` step from the
+ * version after the stored one up to `schemaVersion`, then the automatic
+ * steps of the current blueprint (`renamedFrom`, `fill`, and, with `drop`,
+ * leaving out keys it no longer declares). The steps run first because each
+ * is written against the shape of the version before it, which the
+ * automatic steps would already have changed. Throws
+ * `InvalidStoredSchemaVersion` for a version that is not a positive integer
+ * or is above `schemaVersion`.
+ */
+export declare function upcast(source: string, plan: UpcastPlan, data: RepositoryData, drop?: boolean, report?: UpcastReport): RepositoryData;
+/**
+ * `rows` of `state`'s entity in its current shape (see `upcast`); `rows`
+ * itself when the entity needs nothing. Throws `InvalidRepositoryData`
+ * caused by `InvalidStoredSchemaVersion` for a row it cannot bring up.
+ */
+export declare function upcastRows(state: RepositoryState, rows: readonly RepositoryData[]): readonly RepositoryData[];
+/** `data` with the version key of `state`'s entity, when it declares `schemaVersion`. */
+export declare function withSchemaVersion(entity: object, data: RepositoryData): RepositoryData;
+export {};

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;
+}