@afora/core 0.0.9 → 0.0.11

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.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.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/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
+}));

package/dist/core/environment/environment.d.ts

@@ -4,7 +4,11 @@ import { Kind } from "../symbols/kind.js";
 export type EnvironmentSource = () => Readonly<Record<string, string | undefined>>;
 /** What `environmentOf` takes, after the blueprint. */
 export interface EnvironmentOptions {
-    /** The variables to read, e.g. `() => Bun.env`; `process.env` by default. */
+    /**
+     * The variables to read, e.g. `() => Bun.env`.
+     *
+     * @default `() => process.env`
+     */
     readonly source?: EnvironmentSource;
 }
 /**
@@ -15,7 +19,11 @@ export interface EnvironmentOptions {
 export interface IEnvironment<Properties extends IBlueprintCollection> {
     readonly [Kind]: "environment";
     readonly blueprint: IBlueprint<Properties>;
-    /** The validated variables; throws `InvalidEnvironment` when any is rejected. */
+    /**
+     * The validated variables, read on the first call and the same after.
+     *
+     * @throws {@link InvalidEnvironment} when a variable is missing or rejected.
+     */
     load(): Readonly<BlueprintValue<Properties>>;
 }
 /** Any environment, whatever its blueprint. */
@@ -40,8 +48,23 @@ export declare const InvalidEnvironment: import("../../index.js").DeclaredExcept
  * boolean (`"true"`, `"false"`) or a number when its property takes one
  * instead of a string, validates them once and
  * gives the same value after. As a dependency of a repository it reaches the
- * provider as `context.env`; of a use case, the use case gets its value, e.g.
+ * provider as `context.env`; of a use case ({@link useCaseOf}), the use case gets its value, e.g.
  * `environmentOf(blueprintOf((ctx) => ({ DATABASE_URL: ctx.url })))`.
+ *
+ * @throws {TypeError} when `blueprint` is not a blueprint, or is an optional one.
+ *
+ * @example
+ * ```ts
+ * import { blueprintOf, environmentOf } from "@afora/core";
+ *
+ * const Env = environmentOf(
+ * 	blueprintOf((ctx) => ({ DATABASE_URL: ctx.url, PORT: ctx.integer })),
+ * 	{ source: () => ({ DATABASE_URL: "https://db.example.com", PORT: "3000" }) },
+ * );
+ *
+ * Env.load().PORT; // 3000, converted from the string
+ * // Env.load() throws InvalidEnvironment when a variable is missing or invalid
+ * ```
  */
 export declare function environmentOf<Properties extends IBlueprintCollection>(blueprint: IBlueprint<Properties, boolean>, { source }?: EnvironmentOptions): IEnvironment<Properties>;
 /** The variables of every environment of `dependencies`, merged in order. */

package/dist/core/environment/environment.js

@@ -0,0 +1,71 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+import { isProperty } from "../property/is-property.js";
+import { Kind } from "../symbols/kind.js";
+export const InvalidEnvironment = exceptionOf({
+  layer: ExceptionLayers.Environment,
+  name: "InvalidEnvironment",
+  message: ({ keys }) => `Invalid environment variables: ${keys.join(", ")}.`
+});
+const processEnv = () => globalThis.process?.env ?? {};
+export function environmentOf(blueprint, { source = processEnv } = {}) {
+  if (!isBlueprint(blueprint) || blueprint.optional) {
+    throw new TypeError("An environment requires a blueprint");
+  }
+  let value;
+  return Object.freeze({
+    [Kind]: "environment",
+    blueprint,
+    load() {
+      if (value !== undefined)
+        return value;
+      value = parseEnvironment(blueprint, source());
+      return value;
+    }
+  });
+}
+function parseEnvironment(blueprint, variables) {
+  const declared = {};
+  for (const [key, field] of Object.entries(blueprint.properties)) {
+    const variable = variables[key];
+    if (variable !== undefined)
+      declared[key] = convert(field, variable);
+  }
+  const parsed = blueprint.safeParse(declared);
+  if (!parsed.issues)
+    return Object.freeze(parsed.value);
+  const issues = parsed.issues;
+  throw new InvalidEnvironment({
+    source: "environment",
+    details: {
+      keys: [...new Set(issues.map((issue) => String(issue.path[0] ?? "")))]
+    },
+    cause: issues.find((issue) => issue.cause)?.cause
+  });
+}
+function convert(field, variable) {
+  if (!isProperty(field))
+    return variable;
+  const { schema } = field.type;
+  if (schema.matchShape(variable))
+    return variable;
+  const text = variable.trim();
+  if (text === "true" || text === "false") {
+    if (schema.matchShape(text === "true"))
+      return text === "true";
+  }
+  const number = text === "" ? Number.NaN : Number(text);
+  if (Number.isFinite(number) && schema.matchShape(number))
+    return number;
+  return variable;
+}
+export function loadEnvironments(dependencies) {
+  if (dependencies === undefined)
+    return Object.freeze({});
+  const list = isEnvironment(dependencies) ? [dependencies] : dependencies;
+  return Object.freeze(Object.assign({}, ...list.map((environment) => environment.load())));
+}
+export function isEnvironment(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "environment";
+}

package/dist/core/event-policy/event-policy.js

@@ -0,0 +1,76 @@
+import { frozenJson } from "../json.js";
+import { Kind } from "../symbols/kind.js";
+import { InvalidEventPolicy } from "./exceptions.js";
+const described = new WeakMap;
+const factories = new WeakMap;
+function invalid(source, reason) {
+  throw new InvalidEventPolicy({ source, details: { reason } });
+}
+function optionsOf(name, given, validate) {
+  const options = frozenJson(given ?? {}, "Event policy options", (reason) => invalid(name, reason));
+  if (options === null || typeof options !== "object" || Array.isArray(options)) {
+    invalid(name, "Event policy options must be an object.");
+  }
+  const reason = validate?.(options);
+  if (reason !== undefined)
+    invalid(name, reason);
+  return options;
+}
+export function eventPolicyOf(settings) {
+  const name = settings?.name;
+  if (typeof name !== "string" || !/^[A-Za-z_$][\w$]*$/.test(name)) {
+    invalid("eventPolicyOf", "Expected the policy name to be an identifier.");
+  }
+  if (typeof settings.handle !== "function") {
+    invalid(name, "Expected handle to be a function.");
+  }
+  if (settings.publishers !== undefined && typeof settings.publishers !== "function") {
+    invalid(name, "Expected publishers to be a function.");
+  }
+  const { handle, validate, publishers } = settings;
+  const factory = (given) => {
+    const options = optionsOf(name, given, validate);
+    const handler = (events, info) => handle(events, info, options);
+    Object.defineProperty(handler, "name", { value: name });
+    described.set(handler, {
+      description: Object.freeze({
+        kind: "policy",
+        name,
+        options
+      }),
+      publishers: Object.freeze([...publishers?.(options) ?? []])
+    });
+    return handler;
+  };
+  factories.set(factory, name);
+  return factory;
+}
+export function eventPolicyDescriptionOf(handler) {
+  return typeof handler === "function" ? described.get(handler)?.description : undefined;
+}
+export function eventPolicyPublishersOf(handler) {
+  return typeof handler === "function" ? described.get(handler)?.publishers ?? [] : [];
+}
+export function eventPolicyCatalogOf(...policies) {
+  const byName = {};
+  for (const factory of policies) {
+    const name = factories.get(factory);
+    if (name === undefined) {
+      invalid("catalog", "A catalog takes factories made by `eventPolicyOf`.");
+    }
+    if (Object.hasOwn(byName, name)) {
+      invalid(name, "The catalog has another event policy with its name.");
+    }
+    byName[name] = factory;
+  }
+  return Object.freeze({
+    [Kind]: "event-policy-catalog",
+    policies: Object.freeze(byName),
+    resolve(name, options) {
+      const factory = Object.hasOwn(byName, name) ? byName[name] : undefined;
+      if (!factory)
+        invalid("catalog", `Unknown event policy "${name}".`);
+      return factory(options);
+    }
+  });
+}

package/dist/core/event-policy/exceptions.js

@@ -0,0 +1,12 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidEventPolicy = exceptionOf({
+  layer: ExceptionLayers.Event,
+  name: "InvalidEventPolicy",
+  message: ({ reason }) => reason
+});
+export const PublisherNotBound = exceptionOf({
+  layer: ExceptionLayers.Application,
+  name: "PublisherNotBound",
+  message: ({ publisher }) => `No publisher "${publisher}" is declared: add it to applicationOf({ publishers }).`
+});