@afora/core 0.0.8 → 0.0.11

package/dist/core/property/define-property.d.ts

@@ -1,9 +1,16 @@
 import type { Static, TSchema } from "typebox";
-import type { ParseResult } from "../parse/types/parse.interface.js";
+import type { Issue, ParseResult } from "../parse/types/parse.interface.js";
 import { State } from "../symbols/state.js";
 import { PropertyStates } from "./enums/property-states.js";
 import type { IDefineProperty } from "./types/define-property.interface.js";
 import type { IPropertyType } from "./types/property-type.interface.js";
+/**
+ * Adds to `issues` those of the value a pipeline has just rejected, each
+ * under `path`, where the value is. An issue of the value itself has `path`
+ * as it is, not a copy.
+ * @internal
+ */
+export declare function takeRejectionIssues(path: readonly (string | number)[], issues: Issue[]): void;
 /** How a property handles its value; `Value` is the value of its schema, as in `ISchema`. */
 export declare abstract class AbstractDefineProperty<SchemaType extends TSchema, Value = Static<SchemaType>> implements IDefineProperty<SchemaType, Value> {
     [State]: PropertyStates;
@@ -27,9 +34,13 @@ export declare abstract class AbstractDefineProperty<SchemaType extends TSchema,
     protected afterHandle(value: Value): Value;
     /** The value, or `MISMATCH` when the schema rejects it. */
     protected handle(value: Value): Value;
-    /** `attempt`, with the error of any step as a failure. */
+    /** `attempt`, with the error of any step as a rejection. */
     private attemptWithoutThrowing;
-    /** Runs the pipeline, updating the state, and tells why it stopped if it did. */
+    /**
+     * Runs the pipeline, updating the state: the handled value, or `REJECTED`
+     * with the reason in `rejection`. A handler that is not declared is not
+     * run, and neither is the shape check that protects it.
+     */
     private attempt;
     /**
      * Runs a handler: an `Exception` it throws goes up as it is, any other
@@ -38,11 +49,28 @@ export declare abstract class AbstractDefineProperty<SchemaType extends TSchema,
     private runHandler;
     /** The `InvalidPropertyValue` of an error that is not an `Exception`, as its cause. */
     private invalidValue;
-    /** The failure of an `exception` that a step threw. */
+    /** Rejects the value with an `exception` that a step threw. */
     private raise;
     /**
-     * The failure of `value`, which the schema rejects: an issue for each of its
-     * errors, found once and kept for the details of the exception too.
+     * Rejects `value`, which the schema rejects, with its errors, found once
+     * and kept for the details of the exception too.
      */
     private mismatch;
 }
+/**
+ * Tells that the definitions of `prototype` are as `propertyOf` declares them.
+ * @internal
+ */
+export declare function declarePipeline(prototype: object): void;
+/**
+ * `definition.parse` without its result object: a function giving the handled
+ * value, or `REJECTED`, with the issues for `takeRejectionIssues` to take.
+ * `undefined` when `definition` has a `parse` of its own, which must be
+ * called instead.
+ *
+ * For a definition declared by `propertyOf`, the function is the pipeline of
+ * `attempt` with what never changes read once: which steps there are, the
+ * schema, and no state, which nobody can read.
+ * @internal
+ */
+export declare function parserOf(definition: AbstractDefineProperty<TSchema>): ((value: unknown) => unknown) | undefined;

package/dist/core/property/define-property.js

@@ -0,0 +1,209 @@
+import { Exception } from "../exception/exception.js";
+import { LazyIssue, REJECTED } from "../parse/issue.js";
+import {
+  checksOfSchema,
+  describeError,
+  errorsOfSchema
+} from "../schema/schema.js";
+import { State } from "../symbols/state.js";
+import { PropertyStates } from "./enums/property-states.js";
+import { InvalidPropertyValue, PropertyRequired } from "./exceptions.js";
+const MISMATCH = Symbol("mismatch");
+
+class Failure {
+  source;
+  raised;
+  errors;
+  cause;
+  constructor(source, raised, errors) {
+    this.source = source;
+    this.raised = raised;
+    this.errors = errors;
+    this.cause = raised;
+  }
+  exception() {
+    if (this.cause === undefined) {
+      const { source, errors } = this;
+      this.cause = errors ? new InvalidPropertyValue({
+        source,
+        details: { errors: errors.map(describeError) }
+      }) : new PropertyRequired({ source });
+    }
+    return this.cause;
+  }
+}
+let rejection;
+function reject(failure) {
+  rejection = failure;
+  return REJECTED;
+}
+function segmentsOf(pointer) {
+  return pointer.slice(1).split("/").map((segment) => {
+    const key = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+    return /^(0|[1-9]\d*)$/.test(key) ? Number(key) : key;
+  });
+}
+function issueOf(failure, message, path, code) {
+  return new LazyIssue(message, path, code, failure.source, failure);
+}
+export function takeRejectionIssues(path, issues) {
+  const failure = rejection;
+  rejection = undefined;
+  const { raised, errors, source } = failure;
+  if (raised) {
+    issues.push({
+      message: raised.message,
+      path,
+      code: "invalid_value",
+      source,
+      cause: raised
+    });
+  } else if (!errors) {
+    issues.push(issueOf(failure, "is required", path, "required"));
+  } else if (errors.length === 0) {
+    issues.push(issueOf(failure, "is invalid", path, "invalid_value"));
+  } else {
+    for (const { message, instancePath } of errors) {
+      issues.push(issueOf(failure, message, instancePath === "" ? path : [...path, ...segmentsOf(instancePath)], "invalid_value"));
+    }
+  }
+}
+
+export class AbstractDefineProperty {
+  [State] = PropertyStates.Declared;
+  make(value) {
+    const handled = this.attempt(value);
+    if (handled !== REJECTED)
+      return handled;
+    const failure = rejection;
+    rejection = undefined;
+    throw failure.exception();
+  }
+  parse(value) {
+    const handled = this.attemptWithoutThrowing(value);
+    if (handled !== REJECTED)
+      return { value: handled };
+    const issues = [];
+    takeRejectionIssues([], issues);
+    return { issues };
+  }
+  preHandle(value) {
+    return value;
+  }
+  afterHandle(value) {
+    return value;
+  }
+  handle(value) {
+    return this.type.schema.match(value) ? value : MISMATCH;
+  }
+  attemptWithoutThrowing(value) {
+    try {
+      return this.attempt(value);
+    } catch (error) {
+      return this.raise(error instanceof Exception ? error : this.invalidValue(error));
+    }
+  }
+  attempt(value) {
+    const { name, optional, schema } = this.type;
+    this[State] = PropertyStates.Declared;
+    if (value === undefined) {
+      if (!optional)
+        return reject(new Failure(name, undefined, undefined));
+      this[State] = PropertyStates.Done;
+      return value;
+    }
+    const preHandles = this.preHandle !== PASS.preHandle;
+    const handles = this.handle !== PASS.handle;
+    if ((preHandles || handles) && !schema.matchShape(value)) {
+      return this.mismatch(value);
+    }
+    try {
+      if (preHandles) {
+        this[State] = PropertyStates.PreHandling;
+        value = this.runHandler(this.preHandle, value);
+      }
+      this[State] = PropertyStates.Handling;
+      if (handles) {
+        const handled = this.handle(value);
+        if (handled === MISMATCH)
+          return this.mismatch(value);
+        value = handled;
+      } else if (!schema.match(value)) {
+        if (!preHandles && !schema.matchShape(value)) {
+          this[State] = PropertyStates.Declared;
+        }
+        return this.mismatch(value);
+      }
+      if (this.afterHandle !== PASS.afterHandle) {
+        this[State] = PropertyStates.AfterHandling;
+        value = this.runHandler(this.afterHandle, value);
+      }
+    } catch (error) {
+      if (error instanceof Exception)
+        return this.raise(error);
+      throw error;
+    }
+    this[State] = PropertyStates.Done;
+    return value;
+  }
+  runHandler(handler, value) {
+    try {
+      return handler.call(this, value);
+    } catch (error) {
+      if (error instanceof Exception)
+        throw error;
+      throw this.invalidValue(error);
+    }
+  }
+  invalidValue(error) {
+    return new InvalidPropertyValue({
+      source: this.type.name,
+      details: {
+        errors: [error instanceof Error ? error.message : String(error)]
+      },
+      cause: error
+    });
+  }
+  raise(exception) {
+    return reject(new Failure(this.type.name, exception, undefined));
+  }
+  mismatch(value) {
+    const { name, schema } = this.type;
+    return reject(new Failure(name, undefined, errorsOfSchema(schema, value)));
+  }
+}
+const PASS = AbstractDefineProperty.prototype;
+const declared = new WeakSet;
+export function declarePipeline(prototype) {
+  declared.add(prototype);
+}
+export function parserOf(definition) {
+  const pipeline = definition;
+  if (pipeline.parse !== AbstractDefineProperty.prototype.parse) {
+    return;
+  }
+  if (!declared.has(Object.getPrototypeOf(definition)) || pipeline.handle !== PASS.handle || Object.hasOwn(definition, "preHandle") || Object.hasOwn(definition, "afterHandle")) {
+    return (value) => pipeline.attemptWithoutThrowing(value);
+  }
+  const { name, optional, schema } = pipeline.type;
+  const { match, matchShape } = checksOfSchema(schema);
+  const preHandle = pipeline.preHandle === PASS.preHandle ? undefined : pipeline.preHandle;
+  const afterHandle = pipeline.afterHandle === PASS.afterHandle ? undefined : pipeline.afterHandle;
+  return (value) => {
+    if (value === undefined) {
+      return optional ? value : reject(new Failure(name, undefined, undefined));
+    }
+    try {
+      if (preHandle !== undefined) {
+        if (!matchShape(value))
+          return pipeline.mismatch(value);
+        value = preHandle.call(pipeline, value);
+      }
+      if (!match(value))
+        return pipeline.mismatch(value);
+      return afterHandle === undefined ? value : afterHandle.call(pipeline, value);
+    } catch (error) {
+      return pipeline.raise(error instanceof Exception ? error : pipeline.invalidValue(error));
+    }
+  };
+}

package/dist/core/property/enums/property-states.js

@@ -0,0 +1,8 @@
+export var PropertyStates;
+((PropertyStates) => {
+  PropertyStates[PropertyStates["Declared"] = 0] = "Declared";
+  PropertyStates[PropertyStates["PreHandling"] = 1] = "PreHandling";
+  PropertyStates[PropertyStates["Handling"] = 2] = "Handling";
+  PropertyStates[PropertyStates["AfterHandling"] = 3] = "AfterHandling";
+  PropertyStates[PropertyStates["Done"] = 4] = "Done";
+})(PropertyStates ||= {});

package/dist/core/property/exceptions.js

@@ -0,0 +1,12 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const PropertyRequired = exceptionOf({
+  layer: ExceptionLayers.Property,
+  name: "PropertyRequired",
+  message: (_, source) => `Property "${source}" is required.`
+});
+export const InvalidPropertyValue = exceptionOf({
+  layer: ExceptionLayers.Property,
+  name: "InvalidPropertyValue",
+  message: ({ errors }, source) => `Invalid value for property "${source}": ${errors.join("; ")}`
+});

package/dist/core/property/input.js

@@ -0,0 +1,10 @@
+import { fieldOf } from "../blueprint/callable.js";
+import { isProperty } from "./is-property.js";
+export const PropertyInput = Symbol("propertyInput");
+export function propertyInputOf(field) {
+  const property = fieldOf(field);
+  if (!isProperty(property))
+    return;
+  const declared = property[PropertyInput];
+  return typeof declared === "object" && declared !== null && isProperty(declared.accepts) && typeof declared.convert === "function" ? declared : undefined;
+}

package/dist/core/property/is-property.js

@@ -0,0 +1,3 @@
+export function isProperty(value) {
+  return typeof value === "function" && typeof value.type === "object";
+}

package/dist/core/property/lineage.js

@@ -0,0 +1,8 @@
+const lineages = new WeakMap;
+export function recordPropertyLineage(Property, lineage) {
+  if (!lineages.has(Property))
+    lineages.set(Property, lineage);
+}
+export function propertyLineageOf(Property) {
+  return typeof Property === "function" ? lineages.get(Property) : undefined;
+}

package/dist/core/property/property.d.ts

@@ -53,5 +53,32 @@ export interface PropertyClass<SchemaType extends TSchema, Value = Static<Schema
     with<Self extends AnyPropertyConstructor>(this: Self, options: PropertyOptions<SchemaType, Value>): Self;
     demo<Self extends AbstractProperty<any>>(this: new (value: never) => Self): Self;
 }
+/**
+ * Declares a property: a class that holds one value, run through
+ * `preHandle`, the validation against the TypeBox `schema` and
+ * `afterHandle`. `optional`, `sensitive` and `unique` flag it for the
+ * blueprints and records that hold it, and `default` is its `demo()` value.
+ * Extend the class to add behavior, or narrow it with `.with(options)`. A
+ * value its schema rejects makes the constructor throw
+ * {@link InvalidPropertyValue}, and `undefined` for a required one
+ * {@link PropertyRequired}.
+ *
+ * @example
+ * ```ts
+ * import { propertyOf } from "@afora/core";
+ * import { Type } from "typebox";
+ *
+ * const Name = propertyOf({
+ * 	name: "name",
+ * 	schema: Type.String({ minLength: 3 }),
+ * 	preHandle: (value) => value.trim(),
+ * 	default: "Jane", // used by Name.demo()
+ * });
+ *
+ * new Name("  Alice ").value; // "Alice"
+ * Name.demo().value; // "Jane"
+ * // new Name("a") throws InvalidPropertyValue
+ * ```
+ */
 export declare function propertyOf<SchemaType extends TSchema, Optional extends boolean = false, const Unique extends boolean = false, const Sensitive extends boolean = false>({ name, schema, optional, sensitive, unique, default: _default, preHandle: onPreHandle, afterHandle: onAfterHandle, }: PropertyOfArgs<SchemaType, Optional, Unique, Sensitive>): PropertyClass<SchemaValueType<SchemaType, Optional>, Static<SchemaType>> & UniqueMark<Unique> & SensitiveMark<Sensitive>;
 export {};

package/dist/core/property/property.js

@@ -0,0 +1,46 @@
+import { Type } from "typebox";
+import { schemaOf } from "../schema/schema.js";
+import { Demo } from "../symbols/demo.js";
+import { AbstractProperty } from "./abstract-property.js";
+import { AbstractDefineProperty, declarePipeline } from "./define-property.js";
+export function propertyOf({
+  name,
+  schema,
+  optional,
+  sensitive = false,
+  unique = false,
+  default: _default,
+  preHandle: onPreHandle,
+  afterHandle: onAfterHandle
+}) {
+  const valueSchema = optional ? Type.Optional(schema) : schema;
+  const SchemaConstructor = schemaOf(name, valueSchema);
+  const type = {
+    [Demo]: _default,
+    name,
+    schema: new SchemaConstructor,
+    optional: optional ?? false,
+    sensitive,
+    unique
+  };
+
+  class DefineProperty extends AbstractDefineProperty {
+    get type() {
+      return type;
+    }
+  }
+  const steps = DefineProperty.prototype;
+  if (onPreHandle)
+    steps.preHandle = (value) => onPreHandle(value);
+  if (onAfterHandle)
+    steps.afterHandle = (value) => onAfterHandle(value);
+  declarePipeline(DefineProperty.prototype);
+
+  class Property extends AbstractProperty {
+    static type = type;
+    createDefinition() {
+      return new DefineProperty;
+    }
+  }
+  return Property;
+}

package/dist/core/property/refine.js

@@ -0,0 +1,103 @@
+import { rawTypeOf, schemaOf } from "../schema/schema.js";
+import { Demo } from "../symbols/demo.js";
+import { recordPropertyLineage } from "./lineage.js";
+const METADATA_KEYS = [
+  "title",
+  "description",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly"
+];
+const LOWER_BOUNDS = {
+  min: ["minimum", "minLength"],
+  exclusiveMin: ["exclusiveMinimum"]
+};
+const UPPER_BOUNDS = {
+  max: ["maximum", "maxLength"],
+  exclusiveMax: ["exclusiveMaximum"]
+};
+export function derivePropertyOf(Property, type) {
+  const Base = Property;
+
+  class Derived extends Base {
+    static type = type;
+    createDefinition() {
+      const definition = super.createDefinition();
+      Object.defineProperty(definition, "type", {
+        value: type,
+        configurable: true
+      });
+      return definition;
+    }
+  }
+  Object.defineProperty(Derived, "name", { value: Property.name });
+  return Derived;
+}
+function copyOf(schema) {
+  return Object.defineProperties({}, Object.getOwnPropertyDescriptors(schema));
+}
+function addAllOf(schema, constraint) {
+  schema.allOf = [...schema.allOf ?? [], constraint];
+}
+function refinedSchemaOf(base, options) {
+  const schema = copyOf(base);
+  const keyword = (keys) => keys.length === 1 || schema.type !== "string" ? keys[0] : keys[1];
+  for (const key of METADATA_KEYS) {
+    if (options[key] !== undefined)
+      schema[key] = options[key];
+  }
+  for (const [option, keys] of Object.entries(LOWER_BOUNDS)) {
+    const value = options[option];
+    if (value === undefined)
+      continue;
+    const name = keyword(keys);
+    const current = schema[name];
+    schema[name] = current === undefined ? value : Math.max(current, value);
+  }
+  for (const [option, keys] of Object.entries(UPPER_BOUNDS)) {
+    const value = options[option];
+    if (value === undefined)
+      continue;
+    const name = keyword(keys);
+    const current = schema[name];
+    schema[name] = current === undefined ? value : Math.min(current, value);
+  }
+  if (options.multipleOf !== undefined) {
+    if (schema.multipleOf === undefined)
+      schema.multipleOf = options.multipleOf;
+    else
+      addAllOf(schema, { multipleOf: options.multipleOf });
+  }
+  if (options.pattern !== undefined) {
+    const pattern = options.pattern instanceof RegExp ? options.pattern.source : options.pattern;
+    if (schema.pattern === undefined)
+      schema.pattern = pattern;
+    else
+      addAllOf(schema, { pattern });
+  }
+  return schema;
+}
+export function refinePropertyOf(Property, options) {
+  const base = Property.type;
+  const settings = options;
+  const schema = refinedSchemaOf(rawTypeOf(base.schema), settings);
+  const SchemaConstructor = schemaOf(base.name, schema);
+  const examples = settings.examples;
+  const type = {
+    ...base,
+    [Demo]: settings.default ?? examples?.[0] ?? base[Demo],
+    schema: new SchemaConstructor,
+    ...settings.fill !== undefined && { fill: settings.fill },
+    ...typeof settings.renamedFrom === "string" && {
+      renamedFrom: settings.renamedFrom
+    }
+  };
+  const Refined = derivePropertyOf(Property, type);
+  recordPropertyLineage(Refined, {
+    kind: "refined",
+    base: Property,
+    options: Object.freeze({ ...settings })
+  });
+  return Refined;
+}

package/dist/core/property/types/property-options.interface.d.ts

@@ -14,6 +14,16 @@ export interface PropertyMetadata<Value> {
     readonly writeOnly?: boolean;
     /** The demo value, as `default` in `propertyOf`; it is not written to the schema. */
     readonly default?: Value;
+    /**
+     * The value a repository gives the key when a stored row lacks it, on read
+     * and in a backfill (`app.migrate`); unlike `default`, it fills real data.
+     */
+    readonly fill?: Value;
+    /**
+     * The key that held the value in rows stored before the key was renamed:
+     * a repository moves it on read and in a backfill.
+     */
+    readonly renamedFrom?: string;
 }
 /**
  * Bounds of a number. They only narrow the property: a bound looser than one

package/dist/core/property/types/property-type.interface.d.ts

@@ -15,6 +15,10 @@ export interface IPropertyType<SchemaType extends TSchema, Value = Static<Schema
     readonly sensitive?: boolean;
     /** Whether a record lists a key holding it in `options.unique`, for repositories to enforce. */
     readonly unique?: boolean;
+    /** `fill` of `.with()`: the value given to the key when a stored row lacks it. */
+    readonly fill?: Value;
+    /** `renamedFrom` of `.with()`: the key that held the value in older rows. */
+    readonly renamedFrom?: string;
 }
 /**
  * The type of a property declared `unique`, as `Slug`, so that the keys

package/dist/core/record/abstract-record.d.ts

@@ -1,4 +1,5 @@
 import type { BlueprintField, BlueprintInput, BlueprintValue, IBlueprint, IBlueprintCollection } from "../blueprint/types/blueprint.interface.js";
+import { type Complete } from "../parse/parse.js";
 import type { ParseResult } from "../parse/types/parse.interface.js";
 import type { StandardSchemaV1 } from "../standard/standard-schema.js";
 import { Meta } from "../symbols/meta.js";
@@ -15,6 +16,13 @@ interface RecordDeclaration<Properties extends IBlueprintCollection> {
 export declare const RESERVED_RECORD_KEYS: readonly string[];
 /** Makes each of `keys` a member of the records of `prototype`, e.g. `user.name`. */
 export declare function exposeRecordKeys(prototype: object, keys: readonly string[]): void;
+/**
+ * Tells the record whose constructor runs next that the values of `keys` are
+ * valid as they are. For a class that makes values for its own record on the
+ * way to `super()`, as an entity does of its id.
+ * @internal
+ */
+export declare function vouchFor(keys: readonly string[], complete?: Complete): void;
 /** How `recordDataOf` stores the records a record holds. */
 export interface RecordDataOptions {
     /**