@afora/core 0.0.8 → 0.0.11

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

package/dist/core/record/plugin-catalog.js

@@ -0,0 +1,115 @@
+import { Kind } from "../symbols/kind.js";
+import {
+  IncompatibleRecordPlugin,
+  InvalidRecordPlugin,
+  UnknownRecordPlugin
+} from "./exceptions.js";
+import { isRecordPlugin, isVersion, satisfies } from "./plugin.js";
+const LISTS = ["keys", "sensitive", "unique", "change", "members"];
+function isDescriptor(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const descriptor = value;
+  const isList = (list) => Array.isArray(list) && list.every((item) => typeof item === "string");
+  return descriptor.kind === "record-plugin" && typeof descriptor.name === "string" && isVersion(descriptor.version) && LISTS.every((list) => isList(descriptor[list])) && Array.isArray(descriptor.requires) && descriptor.requires.every((required) => typeof required === "object" && required !== null && typeof required.name === "string" && isVersion(required.version));
+}
+function mismatchOf(plugin, descriptor) {
+  if (!satisfies(plugin.version, descriptor.version)) {
+    return `version ${plugin.version} does not satisfy ${descriptor.version}`;
+  }
+  const current = {
+    keys: plugin.keys,
+    sensitive: plugin.options.sensitive,
+    unique: plugin.options.unique,
+    change: plugin.options.change,
+    members: plugin.members
+  };
+  for (const list of LISTS) {
+    const missing = descriptor[list].find((item) => !current[list].includes(item));
+    if (missing !== undefined)
+      return `"${missing}" is not in its ${list}`;
+  }
+  for (const required of descriptor.requires) {
+    const found = plugin.requires.find(({ name }) => name === required.name);
+    if (!found)
+      return `it does not require "${required.name}"`;
+    if (!satisfies(found.version, required.version)) {
+      return `its "${required.name}" ${found.version} does not satisfy ${required.version}`;
+    }
+  }
+  return;
+}
+export function recordPluginCatalogOf(...plugins) {
+  const byName = {};
+  for (const plugin of plugins) {
+    if (!isRecordPlugin(plugin)) {
+      throw new InvalidRecordPlugin({
+        source: "catalog",
+        details: {
+          reason: "a catalog takes plugins made by `recordPluginOf`"
+        }
+      });
+    }
+    if (Object.hasOwn(byName, plugin.name)) {
+      throw new InvalidRecordPlugin({
+        source: plugin.name,
+        details: { reason: "the catalog has another plugin with its name" }
+      });
+    }
+    byName[plugin.name] = plugin;
+  }
+  const find = (name) => {
+    const plugin = Object.hasOwn(byName, name) ? byName[name] : undefined;
+    if (!plugin) {
+      throw new UnknownRecordPlugin({ source: "catalog", details: { name } });
+    }
+    return plugin;
+  };
+  const resolve = (reference) => {
+    if (typeof reference === "string") {
+      const at = reference.lastIndexOf("@");
+      if (at <= 0)
+        return find(reference);
+      const plugin = find(reference.slice(0, at));
+      const version = reference.slice(at + 1);
+      if (!isVersion(version)) {
+        throw new IncompatibleRecordPlugin({
+          source: plugin.name,
+          details: { reason: `"${version}" is not a semantic version` }
+        });
+      }
+      if (!satisfies(plugin.version, version)) {
+        throw new IncompatibleRecordPlugin({
+          source: plugin.name,
+          details: {
+            reason: `version ${plugin.version} does not satisfy ${version}`
+          }
+        });
+      }
+      return plugin;
+    }
+    if (!isDescriptor(reference)) {
+      const name = reference?.name;
+      throw new IncompatibleRecordPlugin({
+        source: typeof name === "string" ? name : "unknown",
+        details: { reason: "it is not a record plugin descriptor" }
+      });
+    }
+    const plugin = find(reference.name);
+    const reason = mismatchOf(plugin, reference);
+    if (reason !== undefined) {
+      throw new IncompatibleRecordPlugin({
+        source: plugin.name,
+        details: { reason }
+      });
+    }
+    return plugin;
+  };
+  return Object.freeze({
+    [Kind]: "record-plugin-catalog",
+    plugins: Object.freeze(byName),
+    list: Object.freeze([...plugins]),
+    resolve,
+    resolveAll: (references) => Object.freeze(references.map(resolve))
+  });
+}