@afora/core 0.0.9 → 0.0.11

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/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";
@@ -21,7 +22,7 @@ export declare function exposeRecordKeys(prototype: object, keys: readonly strin
  * way to `super()`, as an entity does of its id.
  * @internal
  */
-export declare function vouchFor(keys: readonly string[]): void;
+export declare function vouchFor(keys: readonly string[], complete?: Complete): void;
 /** How `recordDataOf` stores the records a record holds. */
 export interface RecordDataOptions {
     /**

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

@@ -0,0 +1,307 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import {
+  isBlueprintVariant,
+  variantNameOf,
+  variantOfValue
+} from "../blueprint/variant.js";
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { Exception } from "../exception/exception.js";
+import { collectionParserOf, parseField } from "../parse/parse.js";
+import { standardOfClass } from "../standard/standard.js";
+import { Meta } from "../symbols/meta.js";
+import {
+  InvalidRecordValue,
+  ReservedRecordKey,
+  UndeclaredRecordProperty
+} from "./exceptions.js";
+import { maskCollection } from "./mask.js";
+import { recordNameOf } from "./name.js";
+const values = new WeakMap;
+const metadata = new WeakMap;
+export const RESERVED_RECORD_KEYS = Object.freeze([
+  "onSet",
+  "onSetAll",
+  "set",
+  "toJSON",
+  "toString",
+  "toLocaleString",
+  "valueOf",
+  "hasOwnProperty",
+  "propertyIsEnumerable",
+  "isPrototypeOf",
+  "__defineGetter__",
+  "__defineSetter__",
+  "__lookupGetter__",
+  "__lookupSetter__",
+  "__proto__",
+  "constructor"
+]);
+export function exposeRecordKeys(prototype, keys) {
+  for (const key of keys) {
+    Object.defineProperty(prototype, key, {
+      get() {
+        return values.get(this)?.[key];
+      },
+      enumerable: true,
+      configurable: true
+    });
+  }
+}
+const checked = new WeakSet;
+function checkMembers(record, properties) {
+  const Class = record.constructor;
+  if (checked.has(Class))
+    return;
+  const keys = Object.keys(properties);
+  for (let prototype = Object.getPrototypeOf(record);prototype !== null && !Object.hasOwn(prototype.constructor, "blueprint"); prototype = Object.getPrototypeOf(prototype)) {
+    const key = Object.getOwnPropertyNames(prototype).find((name) => keys.includes(name));
+    if (key !== undefined) {
+      throw new ReservedRecordKey({
+        source: recordNameOf(Class),
+        details: { key }
+      });
+    }
+  }
+  checked.add(Class);
+}
+let vouched;
+let vouchedComplete;
+export function vouchFor(keys, complete) {
+  vouched = keys;
+  vouchedComplete = complete;
+}
+const constructions = new WeakMap;
+function constructionOf(record) {
+  const Class = record.constructor;
+  let construction = constructions.get(Class);
+  if (!construction) {
+    const { properties } = record[Meta].blueprint;
+    checkMembers(record, properties);
+    const source = recordNameOf(Class);
+    construction = { source, parse: collectionParserOf(properties, source) };
+    constructions.set(Class, construction);
+  }
+  return construction;
+}
+function withIssues(details, issues) {
+  return Object.defineProperty(details, "issues", {
+    value: Object.freeze([...issues]),
+    enumerable: false
+  });
+}
+function recordMessageOf(cause, key, source) {
+  if (key === "" || cause.layer !== ExceptionLayers.Property) {
+    return cause.message;
+  }
+  if (cause.name === "PropertyRequired") {
+    return `Property "${key}" of record "${source}" is required.`;
+  }
+  const errors = cause.details?.errors;
+  if (cause.name === "InvalidPropertyValue" && Array.isArray(errors)) {
+    return `Invalid value for "${key}" of record "${source}": ${errors.join("; ")}`;
+  }
+  return cause.message;
+}
+function exceptionOfIssues(issues, source) {
+  const [first] = issues;
+  const key = first.path.join(".");
+  if (first.cause) {
+    return first.cause.propagate({
+      layer: ExceptionLayers.Record,
+      source,
+      message: recordMessageOf(first.cause, key, source),
+      details: withIssues({ key }, issues)
+    });
+  }
+  if (first.code === "undeclared_key") {
+    return new UndeclaredRecordProperty({
+      source,
+      details: withIssues({ key }, issues)
+    });
+  }
+  return new InvalidRecordValue({
+    source,
+    details: withIssues({ key, errors: [first.message] }, issues)
+  });
+}
+function issuesOfError(error, source) {
+  const issues = error?.details?.issues;
+  if (error instanceof Exception && issues)
+    return issues;
+  const cause = Exception.from(error, {
+    layer: ExceptionLayers.Record,
+    source
+  });
+  return [
+    {
+      code: "invalid_value",
+      message: cause.message,
+      path: [],
+      source,
+      cause
+    }
+  ];
+}
+let request;
+function exceptionOfRejection(rejection) {
+  rejection.exception ??= exceptionOfIssues(rejection.issues, rejection.source);
+  return rejection.exception;
+}
+const REJECTION_HANDLER = {
+  get: (rejection, key) => Reflect.get(exceptionOfRejection(rejection), key),
+  set: (rejection, key, value) => Reflect.set(exceptionOfRejection(rejection), key, value),
+  has: (rejection, key) => Reflect.has(exceptionOfRejection(rejection), key),
+  getPrototypeOf: (rejection) => Reflect.getPrototypeOf(exceptionOfRejection(rejection)),
+  ownKeys: (rejection) => Reflect.ownKeys(exceptionOfRejection(rejection)),
+  getOwnPropertyDescriptor: (rejection, key) => {
+    const descriptor = Reflect.getOwnPropertyDescriptor(exceptionOfRejection(rejection), key);
+    return descriptor && { ...descriptor, configurable: true };
+  }
+};
+function parseRecord(Class, value) {
+  if (value instanceof Class)
+    return { value };
+  const outer = request;
+  const own = { Class };
+  request = own;
+  try {
+    return { value: new Class(value) };
+  } catch (error) {
+    if (own.issues !== undefined && own.rejection === error) {
+      return { issues: own.issues };
+    }
+    return { issues: issuesOfError(error, recordNameOf(Class)) };
+  } finally {
+    request = outer;
+  }
+}
+function recordValue(record) {
+  return values.get(record);
+}
+export function recordDataOf(record, options) {
+  const { properties } = record[Meta].blueprint;
+  return dataOfCollection(properties, values.get(record), options);
+}
+function dataOfCollection(properties, value, options) {
+  return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    recordFieldDataOf(properties[key], item, options)
+  ])));
+}
+export function recordFieldDataOf(field, value, options) {
+  if (value === undefined || value === null)
+    return value;
+  if (isBlueprintVariant(field) && value instanceof AbstractRecord) {
+    const name = variantNameOf(field, value);
+    if (name !== undefined) {
+      const reference = options?.reference?.(value);
+      return Object.freeze(reference === undefined ? { [field.key]: name, ...recordDataOf(value, options) } : { [field.key]: name, id: reference });
+    }
+  }
+  if (value instanceof AbstractRecord) {
+    return options?.reference?.(value) ?? recordDataOf(value, options);
+  }
+  if (isBlueprintList(field) && Array.isArray(value)) {
+    return Object.freeze(value.map((item) => recordFieldDataOf(field.item, item, options)));
+  }
+  if (isBlueprint(field) && typeof value === "object") {
+    return dataOfCollection(field.properties, value, options);
+  }
+  if (isBlueprintVariant(field)) {
+    const variant = variantOfValue(field, value);
+    return variant ? dataOfCollection(variant.properties, value, options) : value;
+  }
+  return value;
+}
+export function storeRecordValue(record, key, value) {
+  const source = recordNameOf(record.constructor);
+  const { properties } = record[Meta].blueprint;
+  if (!Object.hasOwn(properties, key)) {
+    throw exceptionOfIssues([
+      {
+        code: "undeclared_key",
+        message: "is not declared",
+        path: [key],
+        source
+      }
+    ], source);
+  }
+  const current = values.get(record);
+  const previous = current[key];
+  const result = parseField(properties[key], value, [key], source);
+  if (result.issues)
+    throw exceptionOfIssues(result.issues, source);
+  const next = result.value;
+  const { [key]: _, ...rest } = current;
+  values.set(record, Object.freeze(next === undefined ? rest : { ...rest, [key]: next }));
+  return { next, previous };
+}
+export const RecordPluginHooks = Symbol("recordPluginHooks");
+export function runRecordEffects(record, key, next, previous) {
+  const pluginHooks = record.constructor[RecordPluginHooks];
+  if (pluginHooks !== undefined && pluginHooks.length > 0) {
+    const name = String(key);
+    for (const hook of pluginHooks) {
+      if (!hook.keys.includes(name))
+        continue;
+      hook.onSetAll?.call(record, { key, value: next, previous });
+      hook.onSet?.call(record)[name]?.call(record, next, previous);
+    }
+  }
+  const hooks = record;
+  hooks.onSetAll({ key, value: next, previous });
+  hooks.onSet()[key]?.(next, previous);
+  return record;
+}
+
+export class AbstractRecord {
+  get [Meta]() {
+    const Class = this.constructor;
+    let declaration = metadata.get(Class);
+    if (!declaration) {
+      const { blueprint, options } = Class;
+      declaration = Object.freeze({ blueprint, options });
+      metadata.set(Class, declaration);
+    }
+    return declaration;
+  }
+  constructor(value) {
+    let asked;
+    if (request !== undefined && request.Class === this.constructor) {
+      asked = request;
+      request = undefined;
+    }
+    const made = vouched;
+    const complete = vouchedComplete;
+    vouched = undefined;
+    vouchedComplete = undefined;
+    const { source, parse } = constructionOf(this);
+    const result = parse(value, made, complete);
+    if (result.issues) {
+      if (asked === undefined)
+        throw exceptionOfIssues(result.issues, source);
+      asked.issues = result.issues;
+      asked.rejection = new Proxy({ issues: asked.issues, source }, REJECTION_HANDLER);
+      throw asked.rejection;
+    }
+    values.set(this, result.value);
+  }
+  static safeParse(value) {
+    return parseRecord(this, value);
+  }
+  static get "~standard"() {
+    return standardOfClass(this);
+  }
+  toJSON() {
+    return maskCollection(this[Meta].blueprint.properties, recordValue(this), this[Meta].options.sensitive);
+  }
+  set(key, value) {
+    const { next, previous } = storeRecordValue(this, String(key), value);
+    return runRecordEffects(this, key, next, previous);
+  }
+  onSetAll(_change) {}
+  onSet() {
+    return {};
+  }
+}

package/dist/core/record/exceptions.js

@@ -0,0 +1,49 @@
+import { ExceptionLayers } from "../exception/enums/exception-layers.js";
+import { exceptionOf } from "../exception/exception.js";
+export const InvalidRecordValue = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "InvalidRecordValue",
+  message: ({
+    key,
+    errors
+  }, source) => `Invalid value for ${key ? `"${key}" of ` : ""}record "${source}": ${errors.join("; ")}`
+});
+export const InvalidRecordDeclaration = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "InvalidRecordDeclaration",
+  message: (reason, source) => `Invalid declaration of record "${source}": ${reason}`
+});
+export const UndeclaredRecordProperty = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "UndeclaredRecordProperty",
+  message: ({ key }, source) => `Property "${key}" is not declared in record "${source}".`
+});
+export const ReservedRecordKey = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "ReservedRecordKey",
+  message: ({ key }, source) => `"${key}" is a member of record "${source}" and cannot be a key of its blueprint.`
+});
+export const InvalidRecordPlugin = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "InvalidRecordPlugin",
+  message: ({ reason }, source) => `Invalid record plugin "${source}": ${reason}.`
+});
+export const RecordPluginConflict = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "RecordPluginConflict",
+  message: ({
+    plugin,
+    key,
+    owner
+  }, source) => `Plugin "${plugin}" of record "${source}" adds "${key}", which ${owner} already has.`
+});
+export const UnknownRecordPlugin = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "UnknownRecordPlugin",
+  message: ({ name }) => `No record plugin named "${name}" in the catalog.`
+});
+export const IncompatibleRecordPlugin = exceptionOf({
+  layer: ExceptionLayers.Record,
+  name: "IncompatibleRecordPlugin",
+  message: ({ reason }, source) => `Record plugin "${source}" does not satisfy the reference: ${reason}.`
+});

package/dist/core/record/marks.js

@@ -0,0 +1,7 @@
+import { isBlueprintList } from "../blueprint/list.js";
+import { isProperty } from "../property/is-property.js";
+export function isMarked(field, mark, { lists = false } = {}) {
+  if (lists && isBlueprintList(field))
+    return isMarked(field.item, mark, { lists });
+  return isProperty(field) && field.type[mark] === true;
+}

package/dist/core/record/mask.js

@@ -0,0 +1,60 @@
+import { isBlueprint } from "../blueprint/is-blueprint.js";
+import { isBlueprintList } from "../blueprint/list.js";
+import { isRecordClass, recordFieldOf } from "../blueprint/record-field.js";
+import {
+  isBlueprintVariant,
+  variantNameOf,
+  variantOfValue
+} from "../blueprint/variant.js";
+import { isMarked } from "./marks.js";
+export const MASK = "********";
+function maskAll(value) {
+  if (value === undefined || value === null)
+    return value;
+  if (Array.isArray(value))
+    return Object.freeze(value.map(maskAll));
+  if (typeof value === "object" && isRecordClass(value.constructor)) {
+    return maskAll(value.toJSON());
+  }
+  if (typeof value === "object") {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, maskAll(item)])));
+  }
+  return MASK;
+}
+function maskField(field, value, sensitive) {
+  if (value === undefined)
+    return value;
+  if (isBlueprintVariant(field)) {
+    const name = variantNameOf(field, value);
+    if (name !== undefined) {
+      const json = Object.freeze({
+        [field.key]: name,
+        ...value.toJSON()
+      });
+      return sensitive ? maskAll(json) : json;
+    }
+  }
+  if (recordFieldOf(field)) {
+    const json = value.toJSON();
+    return sensitive ? maskAll(json) : json;
+  }
+  if (sensitive || isMarked(field, "sensitive"))
+    return maskAll(value);
+  if (isBlueprintList(field) && Array.isArray(value)) {
+    return Object.freeze(value.map((item) => maskField(field.item, item, false)));
+  }
+  if (isBlueprint(field) && typeof value === "object" && value !== null) {
+    return maskCollection(field.properties, value);
+  }
+  if (isBlueprintVariant(field)) {
+    const variant = variantOfValue(field, value);
+    return variant ? maskCollection(variant.properties, value) : value;
+  }
+  return value;
+}
+export function maskCollection(properties, value, sensitive = []) {
+  return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [
+    key,
+    maskField(properties[key], item, sensitive.includes(key))
+  ])));
+}

package/dist/core/record/name.js

@@ -0,0 +1,23 @@
+const RECORD_NAME = /^[A-Za-z_$][\w$]*$/;
+export function isRecordName(name) {
+  return typeof name === "string" && RECORD_NAME.test(name);
+}
+export function recordNameOf(Class) {
+  const { recordName, name } = Class;
+  return typeof recordName === "string" ? recordName : String(name);
+}
+const declaredNames = new WeakMap;
+export function declareRecordName(Class, name) {
+  declaredNames.set(Class, name);
+}
+export function declaredRecordNameOf(Class) {
+  for (let current = Class;typeof current === "function"; current = Object.getPrototypeOf(current)) {
+    const own = Object.getOwnPropertyDescriptor(current, "recordName")?.value;
+    if (typeof own === "string")
+      return own;
+    const declared = declaredNames.get(current);
+    if (declared !== undefined)
+      return declared;
+  }
+  return;
+}