@afora/core 0.0.8 → 0.0.11

package/dist/core/entity/abstract-entity.js

@@ -0,0 +1,181 @@
+import {
+  AbstractRecord,
+  runRecordEffects,
+  storeRecordValue,
+  vouchFor
+} from "../record/abstract-record.js";
+import { recordNameOf } from "../record/name.js";
+import { Meta } from "../symbols/meta.js";
+import {
+  enqueueEvent,
+  enqueueLifecycle,
+  pullEntityEvents
+} from "./event.js";
+import { DeletedEntity, ImmutableEntityKey } from "./exceptions.js";
+export const ENTITY_IDENTITY_KEYS = Object.freeze(["id", "createdAt", "updatedAt", "deletedAt"]);
+export const ENTITY_MEMBERS = Object.freeze([
+  "destroy",
+  "isDeleted",
+  "equals",
+  "onDestroy",
+  "emit",
+  "pullEvents"
+]);
+export const RESERVED_ENTITY_KEYS = Object.freeze([
+  ...ENTITY_IDENTITY_KEYS,
+  ...ENTITY_MEMBERS
+]);
+export const EntityClock = Symbol("entityClock");
+export const EntityUniqueKeys = Symbol("entityUniqueKeys");
+export const EntitySettings = Symbol("entitySettings");
+export const EntityLifetime = Symbol("entityLifetime");
+export const EXPIRES_AT = "expiresAt";
+export const ENTITY_VERSION_KEY = "version";
+export const SCHEMA_VERSION_KEY = "$v";
+export function isVersionedEntityClass(entityClass) {
+  if (typeof entityClass !== "function")
+    return false;
+  return entityClass[EntitySettings]?.versioned === true;
+}
+export function identityKeysOf(entityClass) {
+  const keys = [...ENTITY_IDENTITY_KEYS];
+  if (isVersionedEntityClass(entityClass))
+    keys.push(ENTITY_VERSION_KEY);
+  if (typeof entityClass === "function" && entityClass[EntityLifetime] !== undefined) {
+    keys.push(EXPIRES_AT);
+  }
+  return keys;
+}
+function isIdentityKey(Entity, key) {
+  return identityKeysOf(Entity).includes(key);
+}
+export function storeEntityVersion(entity, version) {
+  storeRecordValue(entity, ENTITY_VERSION_KEY, version);
+}
+const ID_MADE = Object.freeze(["id"]);
+const CREATED_AT_MADE = Object.freeze(["createdAt"]);
+const BOTH_MADE = Object.freeze(["id", "createdAt"]);
+const CREATED_AT_EXPIRES = Object.freeze([
+  "createdAt",
+  EXPIRES_AT
+]);
+const BOTH_EXPIRES = Object.freeze([
+  "id",
+  "createdAt",
+  EXPIRES_AT
+]);
+export const EntityComplete = Symbol("entityComplete");
+export function completeOf(clock, lifetime) {
+  return (handled) => {
+    if (handled.createdAt === undefined)
+      handled.createdAt = clock.now();
+    if (handled.id === undefined)
+      handled.id = clock.generateId();
+    if (lifetime !== undefined && handled[EXPIRES_AT] === undefined) {
+      const created = handled.createdAt;
+      const start = typeof created === "string" ? Date.parse(created) : NaN;
+      if (!Number.isNaN(start)) {
+        handled[EXPIRES_AT] = new Date(start + lifetime).toISOString();
+        return [EXPIRES_AT];
+      }
+    }
+    return;
+  };
+}
+function identityOf(entity) {
+  return entity;
+}
+function clockOf(entity) {
+  return entity.constructor[EntityClock];
+}
+function assertAlive(entity) {
+  if (entity.isDeleted) {
+    throw new DeletedEntity({
+      source: recordNameOf(entity.constructor),
+      details: { id: identityOf(entity).id }
+    });
+  }
+}
+function withIdentity(value, clock, lifetime, versioned, complete) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return value;
+  }
+  const { id, createdAt, expiresAt, version } = value;
+  const expiring = lifetime !== undefined && expiresAt === undefined;
+  const unversioned = versioned && version === undefined;
+  if (id !== undefined && createdAt !== undefined && !expiring && !unversioned)
+    return value;
+  const { makesValid } = clock;
+  const idLater = id === undefined && makesValid?.id() === true;
+  const createdAtLater = createdAt === undefined && makesValid?.createdAt() === true;
+  const expiresLater = expiring && createdAtLater;
+  const vouched = idLater && createdAtLater ? expiresLater ? BOTH_EXPIRES : BOTH_MADE : createdAtLater ? expiresLater ? CREATED_AT_EXPIRES : CREATED_AT_MADE : idLater ? ID_MADE : undefined;
+  if (!unversioned && !(expiring && !expiresLater) && (id !== undefined || idLater) && (createdAt !== undefined || createdAtLater)) {
+    if (vouched !== undefined)
+      vouchFor(vouched, complete);
+    return value;
+  }
+  const created = createdAt === undefined && !createdAtLater ? clock.now() : createdAt;
+  const identity = {
+    id: undefined,
+    createdAt: undefined,
+    ...value
+  };
+  identity.id = id === undefined && !idLater ? clock.generateId() : id;
+  identity.createdAt = created;
+  if (unversioned)
+    identity[ENTITY_VERSION_KEY] = 1;
+  if (expiring && !expiresLater) {
+    const start = typeof created === "string" ? Date.parse(created) : NaN;
+    if (!Number.isNaN(start)) {
+      identity[EXPIRES_AT] = new Date(start + lifetime).toISOString();
+    }
+  }
+  if (vouched !== undefined)
+    vouchFor(vouched, complete);
+  return identity;
+}
+
+export class AbstractEntity extends AbstractRecord {
+  constructor(value) {
+    super(withIdentity(value, new.target[EntityClock], new.target[EntityLifetime], isVersionedEntityClass(new.target), new.target[EntityComplete]));
+    const input = value;
+    if (input.id === undefined && input.createdAt === undefined) {
+      enqueueLifecycle(this, "onCreate");
+    }
+  }
+  emit(event) {
+    enqueueEvent(this, event);
+  }
+  pullEvents() {
+    return pullEntityEvents(this);
+  }
+  get isDeleted() {
+    return identityOf(this).deletedAt !== undefined;
+  }
+  equals(other) {
+    return other instanceof AbstractEntity && other[Meta].blueprint === this[Meta].blueprint && identityOf(other).id === identityOf(this).id;
+  }
+  destroy() {
+    assertAlive(this);
+    storeRecordValue(this, "deletedAt", clockOf(this).now());
+    enqueueLifecycle(this, "onDelete");
+    this.onDestroy();
+    return this;
+  }
+  set(key, value) {
+    const name = String(key);
+    if (isIdentityKey(this.constructor, name)) {
+      throw new ImmutableEntityKey({
+        source: recordNameOf(this.constructor),
+        details: { key: name }
+      });
+    }
+    assertAlive(this);
+    const { next, previous } = storeRecordValue(this, name, value);
+    storeRecordValue(this, "updatedAt", clockOf(this).now());
+    enqueueLifecycle(this, "onUpdate");
+    return runRecordEffects(this, key, next, previous);
+  }
+  onDestroy() {}
+}

package/dist/core/entity/entity.d.ts

@@ -9,7 +9,7 @@ import type { EntityBuilder, EntityBuilderSettings, IEntityIdentity } from "./ty
  * `options.plugins` picks from the plugins of `plugins`, catalogs made by
  * `recordPluginCatalogOf`.
  */
-export declare function entityBuilderOf<Identity extends IEntityIdentity, const Catalogs extends readonly IRecordPluginCatalog[] = []>({ identity, generateId, now, expiresAt, plugins: catalogs, }: EntityBuilderSettings<Identity, Catalogs>): EntityBuilder<Identity, RecordPluginContext<Catalogs>>;
+export declare function entityBuilderOf<Identity extends IEntityIdentity, const Catalogs extends readonly IRecordPluginCatalog[] = []>(settings: EntityBuilderSettings<Identity, Catalogs>): EntityBuilder<Identity, RecordPluginContext<Catalogs>>;
 /** Whether `value` is a class made by `entityOf`, or one extending it. */
 export declare function isEntityClass(value: unknown): value is AnyRecordClass & AnyEntityClass;
 /** Whether `value` is an entity, an instance of a class made by `entityOf`. */

package/dist/core/entity/entity.js

@@ -0,0 +1,209 @@
+import { blueprintFromProperties } from "../blueprint/blueprint.js";
+import { isRecordClass } from "../blueprint/record-field.js";
+import { isProperty } from "../property/is-property.js";
+import { isRecordName } from "../record/name.js";
+import { IdentifiedRecord } from "../record/plugin.js";
+import { declareRecord, pluginContextOf } from "../record/record.js";
+import { rawTypeOf } from "../schema/schema.js";
+import {
+  AbstractEntity,
+  completeOf,
+  ENTITY_IDENTITY_KEYS,
+  ENTITY_MEMBERS,
+  ENTITY_VERSION_KEY,
+  EntityClock,
+  EntityComplete,
+  EntityLifetime,
+  EntitySettings,
+  EntityUniqueKeys,
+  EXPIRES_AT,
+  RESERVED_ENTITY_KEYS,
+  SCHEMA_VERSION_KEY
+} from "./abstract-entity.js";
+import {
+  EntityClassBrand,
+  EntityEventSettings
+} from "./event.js";
+import {
+  ImmutableEntityKey,
+  InvalidEntityExpiry,
+  InvalidEntitySchemaVersion,
+  ReservedEntityKey
+} from "./exceptions.js";
+import { validMakersOf } from "./trust.js";
+import { VersionIdentity } from "./version.js";
+export function entityBuilderOf(settings) {
+  const { identity, generateId, now, expiresAt, plugins: catalogs } = settings;
+  const clock = Object.freeze({
+    generateId,
+    now,
+    makesValid: validMakersOf(settings)
+  });
+  const context = pluginContextOf(catalogs ?? []);
+  return (blueprint, options = {}) => {
+    const lifetime = lifetimeOf(blueprint, options);
+    const complete = completeOf(clock, lifetime);
+    const expiring = lifetime !== undefined;
+    const versioned = options.versioned === true;
+    const added = [
+      ...versioned ? [ENTITY_VERSION_KEY] : [],
+      ...expiring ? [EXPIRES_AT] : []
+    ];
+    if (expiring && expiresAt === undefined) {
+      throw new InvalidEntityExpiry({
+        source: options.name ?? "entity",
+        details: {
+          reason: "the entity builder has no expiresAt field, which expires: { after } needs."
+        }
+      });
+    }
+    const schemaVersioned = options.schemaVersion !== undefined;
+    checkSchemaOptions(options);
+    if (schemaVersioned)
+      added.push(SCHEMA_VERSION_KEY);
+    for (const key of Object.keys(blueprint.properties)) {
+      if (RESERVED_ENTITY_KEYS.includes(key) || added.includes(key)) {
+        throw new ReservedEntityKey({ source: "entity", details: { key } });
+      }
+    }
+    for (const key of options.change ?? []) {
+      if (ENTITY_IDENTITY_KEYS.includes(key) || added.includes(key)) {
+        throw new ImmutableEntityKey({ source: "entity", details: { key } });
+      }
+    }
+    const DeclaredEntity = declareRecord(AbstractEntity, identity.join(...versioned ? [VersionIdentity] : [], ...expiring ? [
+      blueprintFromProperties([], {
+        [EXPIRES_AT]: expiresAt
+      })
+    ] : [], blueprint), {
+      ...withoutStorage(options),
+      unique: ["id", ...options.unique ?? []]
+    }, "entity", ENTITY_MEMBERS, context);
+    Object.defineProperty(DeclaredEntity, IdentifiedRecord, { value: true });
+    Object.defineProperty(DeclaredEntity, EntityClock, { value: clock });
+    Object.defineProperty(DeclaredEntity, EntityClassBrand, { value: true });
+    Object.defineProperty(DeclaredEntity, EntityUniqueKeys, {
+      value: DeclaredEntity.options.unique
+    });
+    Object.defineProperty(DeclaredEntity, EntityLifetime, { value: lifetime });
+    Object.defineProperty(DeclaredEntity, EntityComplete, { value: complete });
+    Object.defineProperty(DeclaredEntity, EntitySettings, {
+      value: Object.freeze({
+        versioned,
+        expires: options.expires,
+        schemaVersioned,
+        schemaVersion: options.schemaVersion ?? 1,
+        upgrade: Object.freeze({ ...options.upgrade }),
+        previousNames: Object.freeze([...options.previousNames ?? []])
+      })
+    });
+    Object.defineProperty(DeclaredEntity, EntityEventSettings, {
+      value: Object.freeze({
+        onCreate: options.onCreate,
+        onUpdate: options.onUpdate,
+        onDelete: options.onDelete
+      })
+    });
+    return DeclaredEntity;
+  };
+}
+export function isEntityClass(value) {
+  return isRecordClass(value) && value.prototype instanceof AbstractEntity;
+}
+export function isEntity(value) {
+  return value instanceof AbstractEntity;
+}
+function checkSchemaOptions(options) {
+  const source = options.name ?? "entity";
+  const fail = (reason) => {
+    throw new InvalidEntitySchemaVersion({ source, details: { reason } });
+  };
+  const { schemaVersion = 1, upgrade, previousNames } = options;
+  if (!Number.isSafeInteger(schemaVersion) || schemaVersion < 1) {
+    fail("expected schemaVersion to be a positive integer.");
+  }
+  if (upgrade !== undefined) {
+    if (typeof upgrade !== "object" || upgrade === null) {
+      fail("expected upgrade to be an object of steps by version.");
+    }
+    for (const [key, step] of Object.entries(upgrade)) {
+      const version = Number(key);
+      if (!Number.isSafeInteger(version) || version < 2 || version > schemaVersion) {
+        fail(`the upgrade step "${key}" must reach a version from 2 to the schemaVersion (${schemaVersion}).`);
+      }
+      if (typeof step !== "function") {
+        fail(`the upgrade step ${key} is not a function.`);
+      }
+    }
+  }
+  if (previousNames !== undefined) {
+    if (!Array.isArray(previousNames)) {
+      fail("expected previousNames to be a list of names.");
+    }
+    for (const previous of previousNames) {
+      if (!isRecordName(previous) || previous === options.name) {
+        fail(`"${String(previous)}" cannot be a previous name: expected an identifier other than the name of the entity.`);
+      }
+    }
+  }
+}
+function withoutStorage(options) {
+  const {
+    versioned: _versioned,
+    expires: _expires,
+    schemaVersion: _schemaVersion,
+    upgrade: _upgrade,
+    previousNames: _previousNames,
+    ...rest
+  } = options;
+  return rest;
+}
+const DURATION_UNITS = {
+  days: 86400000,
+  hours: 3600000,
+  minutes: 60000,
+  seconds: 1000
+};
+function isDateField(field) {
+  if (!isProperty(field))
+    return false;
+  const schema = rawTypeOf(field.type.schema);
+  return schema.type === "string" && (schema.format === "date-time" || schema.format === "date");
+}
+function lifetimeOf(blueprint, options) {
+  const { expires } = options;
+  if (expires === undefined)
+    return;
+  const fail = (reason) => {
+    throw new InvalidEntityExpiry({
+      source: options.name ?? "entity",
+      details: { reason }
+    });
+  };
+  const plain = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+  if (!plain(expires) || Object.keys(expires).length !== 1)
+    return fail("expected { after: duration } or { at: key }.");
+  if ("at" in expires) {
+    const { at } = expires;
+    if (typeof at !== "string" || !Object.hasOwn(blueprint.properties, at))
+      return fail(`"${String(at)}" is not a key of the blueprint.`);
+    if (!isDateField(blueprint.properties[at]))
+      return fail(`"${at}" does not hold a date.`);
+    return;
+  }
+  if (!("after" in expires)) {
+    return fail("expected { after: duration } or { at: key }.");
+  }
+  const { after } = expires;
+  if (!plain(after) || Object.keys(after).length === 0)
+    return fail("after must be a non-empty duration, e.g. { days: 400 }.");
+  let total = 0;
+  for (const [unit, amount] of Object.entries(after)) {
+    if (!Object.hasOwn(DURATION_UNITS, unit))
+      return fail(`"${unit}" is not a unit of a duration (days, hours, minutes, seconds).`);
+    if (typeof amount !== "number" || !Number.isFinite(amount) || amount <= 0)
+      return fail(`${unit} must be a positive finite number.`);
+    total += amount * DURATION_UNITS[unit];
+  }
+  return total;
+}

package/dist/core/entity/event.d.ts

@@ -1,6 +1,10 @@
 import { type ILogger } from "../logger/logger.js";
 /** A class made by `entityOf`, including subclasses. */
 export declare const EntityClassBrand: unique symbol;
+/**
+ * Any class made by {@link entityOf}, subclasses included: what {@link eventOf}
+ * takes as the entity of an event.
+ */
 export type AnyEntityClass = (abstract new (value: never) => object) & {
     readonly [EntityClassBrand]: true;
 };
@@ -25,7 +29,18 @@ export interface EntityEvent<Entity = object> {
     /** Runs the handler; `logger` replaces the one it would get. */
     handle(context?: Partial<EventHandlerContext>): Promise<void>;
 }
+/**
+ * An event of the lifecycle of an entity, as `onCreate`, `onUpdate` and
+ * `onDelete` take it: a definition made by {@link eventOf}, a list of them, or
+ * a function that gives either, which lets the entity name an event declared
+ * after its class.
+ */
 export type EntityEventReference = EventDefinition | readonly EventDefinition[] | (() => EventDefinition | readonly EventDefinition[]);
+/**
+ * The lifecycle events of an entity, the options of {@link entityOf}:
+ * `onCreate` is queued when a new entity is built, `onUpdate` after each
+ * change, and `onDelete` when it is destroyed.
+ */
 export interface EntityEvents {
     readonly onCreate?: EntityEventReference;
     readonly onUpdate?: EntityEventReference;
@@ -36,6 +51,30 @@ export declare const EntityEventSettings: unique symbol;
  * Defines an event without executing its handler. Without a handler, the
  * event only carries the entity, for a policy such as `publishEvents`, and
  * `handle()` does nothing.
+ *
+ * @throws {TypeError} when `entityClass` is not an entity class, or `handler` is given and is not a function.
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf, type EventDefinition, entityOf, eventOf } from "@afora/core";
+ *
+ * class Post extends entityOf(blueprintOf((ctx) => ({ title: ctx.string }))) {
+ * 	publish(): void {
+ * 		this.emit(PostPublished);
+ * 	}
+ * }
+ *
+ * // The annotation breaks TypeScript's circular inference through the base class.
+ * const PostPublished: EventDefinition = eventOf(
+ * 	"post.published",
+ * 	Post,
+ * 	async (post, { logger }) => logger.info("post.published", { id: post.id }),
+ * );
+ *
+ * const post = new Post({ title: "Hi" });
+ * post.publish();
+ * for (const event of post.pullEvents()) await event.handle();
+ * ```
  */
 export declare function eventOf<Class extends AnyEntityClass>(name: string, entityClass: Class, handler?: (entity: InstanceType<Class>, context: EventHandlerContext) => Promise<void>): EventDefinition;
 /** Whether `event` was given a handler by `eventOf`. @internal */

package/dist/core/entity/event.js

@@ -0,0 +1,80 @@
+import { resolveLogger, silentLogger } from "../logger/logger.js";
+import { isEntityClass } from "./entity.js";
+export const EntityClassBrand = Symbol("entityClass");
+const EventBrand = Symbol("event");
+export const EntityEventSettings = Symbol("entityEvents");
+const definitions = new WeakMap;
+const queues = new WeakMap;
+const withHandler = new WeakSet;
+export function eventOf(name, entityClass, handler) {
+  if (!isEntityClass(entityClass)) {
+    throw new TypeError("An event requires an entity class");
+  }
+  if (handler !== undefined && typeof handler !== "function") {
+    throw new TypeError(`The handler of event ${name} must be a function`);
+  }
+  const event = Object.freeze({
+    name,
+    [EventBrand]: true
+  });
+  if (handler)
+    withHandler.add(event);
+  definitions.set(event, (entity) => {
+    if (!(entity instanceof entityClass)) {
+      throw new TypeError(`Incompatible entity for event ${name}`);
+    }
+    return Object.freeze({
+      name,
+      entity,
+      async handle(context) {
+        if (!handler)
+          return;
+        await handler(entity, {
+          logger: context?.logger ?? resolveLogger(undefined, undefined) ?? silentLogger
+        });
+      }
+    });
+  });
+  return event;
+}
+export function eventHasHandler(event) {
+  return withHandler.has(event);
+}
+export function lifecycleEventsOf(entityClass) {
+  const settings = entityClass[EntityEventSettings];
+  const found = {};
+  for (const cycle of ["onCreate", "onUpdate", "onDelete"]) {
+    const reference = settings?.[cycle];
+    if (reference === undefined)
+      continue;
+    const events = typeof reference === "function" ? reference() : reference;
+    const list = Array.isArray(events) ? events : [events];
+    if (list.length > 0)
+      found[cycle] = list;
+  }
+  return found;
+}
+export function enqueueEvent(entity, event) {
+  const bind = definitions.get(event);
+  if (!bind)
+    throw new TypeError("Expected an eventOf definition");
+  const occurrence = bind(entity);
+  const queue = queues.get(entity) ?? [];
+  queue.push(occurrence);
+  queues.set(entity, queue);
+}
+export function pullEntityEvents(entity) {
+  const queue = queues.get(entity) ?? [];
+  queues.delete(entity);
+  return queue;
+}
+export function enqueueLifecycle(entity, cycle) {
+  const settings = entity.constructor[EntityEventSettings];
+  const reference = settings?.[cycle];
+  if (reference === undefined)
+    return;
+  const events = typeof reference === "function" ? reference() : reference;
+  for (const event of Array.isArray(events) ? events : [events]) {
+    enqueueEvent(entity, event);
+  }
+}

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

@@ -25,3 +25,12 @@ export declare const DeletedEntity: import("../../index.js").DeclaredExceptionCl
 export declare const InvalidEntityExpiry: import("../../index.js").DeclaredExceptionClass<{
     readonly reason: string;
 }>;
+/**
+ * The schema evolution options of an entity are invalid: `schemaVersion` is
+ * not a positive integer, a step of `upgrade` is not a function or reaches a
+ * version outside `2..schemaVersion`, or `previousNames` holds something
+ * that cannot name a record, or its own name; `source` is the entity name.
+ */
+export declare const InvalidEntitySchemaVersion: import("../../index.js").DeclaredExceptionClass<{
+    readonly reason: string;
+}>;

package/dist/core/entity/exceptions.js

@@ -0,0 +1,27 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const ReservedEntityKey = exceptionOf({
+  layer: ExceptionLayers.Entity,
+  name: "ReservedEntityKey",
+  message: ({ key }, source) => `"${key}" is a key or a member of every entity and cannot be a key of the blueprint of "${source}".`
+});
+export const ImmutableEntityKey = exceptionOf({
+  layer: ExceptionLayers.Entity,
+  name: "ImmutableEntityKey",
+  message: ({ key }, source) => `"${key}" of entity "${source}" cannot be changed.`
+});
+export const DeletedEntity = exceptionOf({
+  layer: ExceptionLayers.Entity,
+  name: "DeletedEntity",
+  message: ({ id }, source) => `Entity "${source}" of id "${id}" was destroyed and cannot change.`
+});
+export const InvalidEntityExpiry = exceptionOf({
+  layer: ExceptionLayers.Entity,
+  name: "InvalidEntityExpiry",
+  message: ({ reason }, source) => `Invalid expires of entity "${source}": ${reason}`
+});
+export const InvalidEntitySchemaVersion = exceptionOf({
+  layer: ExceptionLayers.Entity,
+  name: "InvalidEntitySchemaVersion",
+  message: ({ reason }, source) => `Invalid schema evolution options of entity "${source}": ${reason}`
+});

package/dist/core/entity/trust.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Under this key, the settings of an entity builder tell when what their
+ * `generateId` and `now` make is known to be valid, so that an entity does
+ * not check again the id and the date it has just made. Only for a builder
+ * that knows its own makers, as `std` does of its defaults: a generator an
+ * application configures is never vouched for.
+ * @internal
+ */
+export declare const MakesValid: unique symbol;
+/** @internal */
+export interface ValidMakers {
+    /** Whether the id `generateId` is about to make is one `id` accepts as it is. */
+    readonly id: () => boolean;
+    /** Whether the date `now` is about to make is one `createdAt` accepts as it is. */
+    readonly createdAt: () => boolean;
+}
+/**
+ * `settings` of an entity builder with `makers` vouching for its
+ * `generateId` and `now`.
+ * @internal
+ */
+export declare function vouching<const Settings extends object>(settings: Settings, makers: ValidMakers): Settings;
+/** The makers `settings` vouch for, if any. @internal */
+export declare function validMakersOf(settings: object): ValidMakers | undefined;

package/dist/core/entity/trust.js

@@ -0,0 +1,7 @@
+export const MakesValid = Symbol("makesValid");
+export function vouching(settings, makers) {
+  return Object.defineProperty({ ...settings }, MakesValid, { value: makers });
+}
+export function validMakersOf(settings) {
+  return settings[MakesValid];
+}

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

@@ -75,6 +75,30 @@ export interface EntityStorageOptions<Key extends string = string, Expires exten
      * blueprint. A record with no date never expires.
      */
     readonly expires?: Expires;
+    /**
+     * The version of the stored shape of the entity, 1 when absent. When set,
+     * every write stores it in each row under `SCHEMA_VERSION_KEY`, and reads
+     * bring older rows up to it with `upgrade` before parsing them.
+     */
+    readonly schemaVersion?: number;
+    /**
+     * The steps that bring a stored row from the version before each key up
+     * to that key: `{ 2: (data) => ({ ...data, slug: data.path }) }`. Each
+     * gets the raw stored data, without the version key.
+     */
+    readonly upgrade?: EntityUpgrades;
+    /**
+     * The names the entity had before (its `name` option), so a backfill
+     * (`app.migrate`) moves their rows to the current name, and `start()`
+     * accepts the rename.
+     */
+    readonly previousNames?: readonly string[];
+}
+/** A step of `upgrade`: the stored data of a version, as the next one. */
+export type EntityUpgrade = (data: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+/** The `upgrade` steps of an entity, keyed by the version each one reaches. */
+export interface EntityUpgrades {
+    readonly [version: number]: EntityUpgrade;
 }
 /** A duration, e.g. `{ days: 400 }`. */
 export interface EntityDuration {
@@ -107,6 +131,12 @@ export type ExpiringIdentity<Identity extends IEntityIdentity, Expires> = Expire
 export interface EntityStorageSettings {
     readonly versioned: boolean;
     readonly expires?: EntityExpires;
+    /** Whether `schemaVersion` was declared, so rows carry the version key. */
+    readonly schemaVersioned: boolean;
+    /** `schemaVersion`, 1 when absent. */
+    readonly schemaVersion: number;
+    readonly upgrade: EntityUpgrades;
+    readonly previousNames: readonly string[];
 }
 /**
  * The unique keys of an entity: `id`, those listed in `options.unique`, and

package/dist/core/entity/version.js

@@ -0,0 +1,13 @@
+import { Type } from "typebox";
+import { blueprintBuilderOf } from "../blueprint/blueprint.js";
+import { propertyOf } from "../property/property.js";
+
+export class EntityVersion extends propertyOf({
+  name: "version",
+  schema: Type.Integer({ minimum: 1 }),
+  default: 1
+}) {
+}
+export const VersionIdentity = blueprintBuilderOf()(() => ({
+  version: EntityVersion
+}));