@afora/core 0.0.9 → 0.0.12

package/dist/core/blueprint/optional.js

@@ -0,0 +1,69 @@
+import { Type } from "typebox";
+import { recordPropertyLineage } from "../property/lineage.js";
+import { derivePropertyOf } from "../property/refine.js";
+import { rawTypeOf, schemaOf } from "../schema/schema.js";
+import { withStandard } from "../standard/standard.js";
+import { Kind } from "../symbols/kind.js";
+import { fieldOf } from "./callable.js";
+import { isBlueprint } from "./is-blueprint.js";
+import { isBlueprintList, standardListOf } from "./list.js";
+import { isOptionalRecord, isRecordClass } from "./record-field.js";
+import { isBlueprintVariant, standardVariantOf } from "./variant.js";
+const cache = new WeakMap;
+export function optionalOf(given) {
+  const field = fieldOf(given);
+  const cached = cache.get(field);
+  if (cached)
+    return cached;
+  if (isOptionalRecord(field))
+    return field;
+  if (isRecordClass(field)) {
+    const optional = Object.freeze(withStandard({
+      [Kind]: "record",
+      record: field,
+      optional: true
+    }, (value) => value === undefined ? { value } : field.safeParse(value)));
+    cache.set(field, optional);
+    return optional;
+  }
+  if (isBlueprint(field)) {
+    if (field.optional)
+      return field;
+    const optional = {
+      ...field,
+      optional: true,
+      safeParse: (value) => value === undefined ? { value } : field.safeParse(value)
+    };
+    Object.freeze(withStandard(optional, (value) => optional.safeParse(value)));
+    cache.set(field, optional);
+    return optional;
+  }
+  if (isBlueprintList(field)) {
+    if (field.optional)
+      return field;
+    const optional = standardListOf({ ...field, optional: true });
+    cache.set(field, optional);
+    return optional;
+  }
+  if (isBlueprintVariant(field)) {
+    if (field.optional)
+      return field;
+    const optional = standardVariantOf({ ...field, optional: true });
+    cache.set(field, optional);
+    return optional;
+  }
+  const Property = field;
+  if (Property.type.optional)
+    return Property;
+  const base = Property.type;
+  const SchemaConstructor = schemaOf(base.name, Type.Optional(rawTypeOf(base.schema)));
+  const type = {
+    ...base,
+    schema: new SchemaConstructor,
+    optional: true
+  };
+  const Optional = derivePropertyOf(Property, type);
+  recordPropertyLineage(Optional, { kind: "optional", base: Property });
+  cache.set(Property, Optional);
+  return Optional;
+}

package/dist/core/blueprint/record-field.js

@@ -0,0 +1,14 @@
+import { Kind } from "../symbols/kind.js";
+export function isRecordClass(value) {
+  return typeof value === "function" && value[Kind] === "record";
+}
+export function isOptionalRecord(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "record";
+}
+export function recordFieldOf(field) {
+  if (isRecordClass(field))
+    return { record: field, optional: false };
+  if (isOptionalRecord(field))
+    return field;
+  return;
+}

package/dist/core/blueprint/slice.js

@@ -0,0 +1,127 @@
+import { AbstractRecord } from "../record/abstract-record.js";
+import { recordNameOf } from "../record/name.js";
+import { declareRecord } from "../record/record.js";
+import { blueprintFromProperties } from "./blueprint.js";
+import {
+  InvalidBlueprintVariant,
+  UndeclaredBlueprintProperty
+} from "./exceptions.js";
+import { isBlueprint } from "./is-blueprint.js";
+import { isBlueprintList, listOf } from "./list.js";
+import { optionalOf } from "./optional.js";
+import { isRecordClass, recordFieldOf } from "./record-field.js";
+import { isBlueprintVariant } from "./variant.js";
+function propertiesOfField(field) {
+  if (field === undefined)
+    return;
+  if (isBlueprintList(field))
+    return propertiesOfField(field.item);
+  const record = recordFieldOf(field);
+  if (record)
+    return record.record.blueprint.properties;
+  return isBlueprint(field) ? field.properties : undefined;
+}
+function maskOf(selector, against) {
+  if (isRecordClass(selector))
+    return maskOf(selector.blueprint, against);
+  if (isBlueprint(selector)) {
+    return Object.fromEntries(Object.entries(selector.properties).map(([key, field]) => [key, fieldMaskOf(field, against?.[key])]));
+  }
+  return selector;
+}
+function fieldMaskOf(field, other) {
+  if (isBlueprintList(field)) {
+    return fieldMaskOf(field.item, isBlueprintList(other) ? other.item : other);
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    if (record.record === recordFieldOf(other)?.record)
+      return true;
+    return maskOf(record.record, propertiesOfField(other));
+  }
+  if (isBlueprint(field)) {
+    return field === other ? true : maskOf(field, propertiesOfField(other));
+  }
+  return true;
+}
+function sliceCollection(properties, mask, path) {
+  const sliced = {};
+  for (const [key, selected] of Object.entries(mask)) {
+    if (!selected)
+      continue;
+    if (!Object.hasOwn(properties, key)) {
+      throw new UndeclaredBlueprintProperty({
+        source: "blueprint",
+        details: { key: path + key }
+      });
+    }
+    sliced[key] = sliceField(properties[key], selected, path + key);
+  }
+  return sliced;
+}
+function slicedRecordOf(Original, mask, path) {
+  const source = Original.blueprint;
+  const blueprint = blueprintFromProperties(source.plugins, sliceCollection(source.properties, mask, `${path}.`));
+  const kept = (keys) => keys.filter((key) => Object.hasOwn(blueprint.properties, key));
+  const { sensitive, unique, change } = Original.options;
+  const Sliced = declareRecord(AbstractRecord, blueprint, {
+    sensitive: kept(sensitive),
+    unique: kept(unique),
+    change: kept(change)
+  }, recordNameOf(Original));
+  Object.defineProperty(Sliced, Symbol.hasInstance, {
+    value(value) {
+      return Function.prototype[Symbol.hasInstance].call(this, value) || value instanceof Original;
+    }
+  });
+  return Sliced;
+}
+function sliceField(field, selected, path) {
+  if (selected === true)
+    return field;
+  if (isBlueprintList(field)) {
+    const list = listOf(sliceField(field.item, selected, path), {
+      minItems: field.minItems,
+      maxItems: field.maxItems
+    });
+    return field.optional ? optionalOf(list) : list;
+  }
+  const record = recordFieldOf(field);
+  if (record) {
+    const sliced = slicedRecordOf(record.record, selected, path);
+    return record.optional ? optionalOf(sliced) : sliced;
+  }
+  if (isBlueprint(field)) {
+    const sliced = blueprintFromProperties(field.plugins, sliceCollection(field.properties, selected, `${path}.`));
+    return field.optional ? optionalOf(sliced) : sliced;
+  }
+  if (isBlueprintVariant(field)) {
+    throw new InvalidBlueprintVariant({
+      source: "blueprint",
+      details: {
+        key: field.key,
+        reason: `"${path}" cannot be sliced by its keys yet, only picked whole`
+      }
+    });
+  }
+  throw new UndeclaredBlueprintProperty({
+    source: "blueprint",
+    details: { key: `${path}.${Object.keys(selected)[0] ?? ""}` }
+  });
+}
+export const sliceOf = (blueprint, selector) => blueprintFromProperties(blueprint.plugins, sliceCollection(blueprint.properties, maskOf(selector, blueprint.properties), ""));
+export const sliceValue = (value, selector) => pick(value, maskOf(selector));
+function pick(value, mask) {
+  if (Array.isArray(value))
+    return value.map((item) => pick(item, mask));
+  if (typeof value !== "object" || value === null)
+    return value;
+  const source = isRecordClass(value.constructor) ? value.toJSON() : value;
+  const picked = {};
+  for (const [key, selected] of Object.entries(mask)) {
+    if (!selected || !Object.hasOwn(source, key))
+      continue;
+    picked[key] = selected === true ? source[key] : pick(source[key], selected);
+  }
+  return picked;
+}

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

@@ -277,7 +277,19 @@ export type OptionalProperties<Properties> = {
         readonly variants: infer Variants extends BlueprintVariants;
     } ? IBlueprintVariant<Name, Variants, true> : never;
 };
+/**
+ * The function {@link blueprintOf} takes: it gets the context `ctx` of the
+ * sources (the factories of their plugins, `listOf`, `optionalOf`, `propertyOf`
+ * and `variantOf`) and gives the fields of the blueprint.
+ */
 export type BlueprintDefinition<Sources extends readonly BlueprintSource[], Properties extends IBlueprintCollection> = (ctx: BlueprintContext<Sources>) => Properties;
+/**
+ * A blueprint: an object shape of named fields, made by {@link blueprintOf}. It
+ * parses a value with `safeParse` or its Standard Schema (`~standard`), joins
+ * others with `join`, and is a field of another blueprint or the base of a
+ * record (see {@link recordOf}). `Optional` is `true` for one that, as a field,
+ * accepts `undefined`.
+ */
 export interface IBlueprint<Properties extends IBlueprintCollection, Optional extends boolean = false> {
     readonly [Kind]: "blueprint";
     /** The plugins it was built from, its joined blueprints' included. */
@@ -323,6 +335,10 @@ export interface BlueprintBuilder<Base extends readonly BlueprintSource[]> {
 }
 /** `Blueprint` as a field that accepts `undefined`. */
 export type OptionalBlueprint<Blueprint extends AnyBlueprint> = Blueprint extends IBlueprint<infer Properties, boolean> ? IBlueprint<Properties, true> : never;
+/**
+ * The bounds of a list field, as `ctx.listOf(item, { minItems, maxItems })`
+ * takes them: the fewest and the most items it accepts.
+ */
 export interface BlueprintListOptions {
     readonly minItems?: number;
     readonly maxItems?: number;

package/dist/core/blueprint/variant.js

@@ -0,0 +1,72 @@
+import { parseField } from "../parse/parse.js";
+import { withStandard } from "../standard/standard.js";
+import { Kind } from "../symbols/kind.js";
+import { InvalidBlueprintVariant } from "./exceptions.js";
+import { isBlueprint } from "./is-blueprint.js";
+import { isRecordClass } from "./record-field.js";
+export function variantOf(key, variants) {
+  const fail = (reason) => {
+    throw new InvalidBlueprintVariant({
+      source: "blueprint",
+      details: { key: String(key), reason }
+    });
+  };
+  if (typeof key !== "string" || key === "") {
+    fail("its key must be a string that is not empty");
+  }
+  const tags = Object.keys(variants);
+  if (tags.length === 0)
+    fail("it needs at least one variant");
+  const classes = new Set;
+  for (const tag of tags) {
+    const variant = variants[tag];
+    if (!isBlueprint(variant) && !isRecordClass(variant)) {
+      fail(`the variant "${tag}" is not a blueprint nor a record class`);
+    }
+    if (classes.has(variant)) {
+      fail(`the variant "${tag}" is a class another variant already is`);
+    }
+    if (isRecordClass(variant))
+      classes.add(variant);
+    if (Object.hasOwn(blueprintOfVariant(variant).properties, key)) {
+      fail(`the variant "${tag}" declares "${key}", which the field adds`);
+    }
+  }
+  return standardVariantOf({
+    [Kind]: "variant",
+    key,
+    variants: Object.freeze({ ...variants }),
+    optional: false
+  });
+}
+export function standardVariantOf(variant) {
+  return Object.freeze(withStandard(variant, (value) => parseField(variant, value, [], "variant")));
+}
+export function blueprintOfVariant(variant) {
+  return isRecordClass(variant) ? variant.blueprint : variant;
+}
+export function namedVariantOf(field, value) {
+  if (typeof value !== "object" || value === null)
+    return;
+  const tag = value[field.key];
+  const variants = field.variants;
+  return typeof tag === "string" && Object.hasOwn(variants, tag) ? variants[tag] : undefined;
+}
+export function variantOfValue(field, value) {
+  const variant = namedVariantOf(field, value);
+  return variant && blueprintOfVariant(variant);
+}
+export function variantNameOf(field, instance) {
+  if (typeof instance !== "object" || instance === null)
+    return;
+  const variants = field.variants;
+  for (const tag of Object.keys(variants)) {
+    const variant = variants[tag];
+    if (isRecordClass(variant) && instance instanceof variant)
+      return tag;
+  }
+  return;
+}
+export function isBlueprintVariant(value) {
+  return typeof value === "object" && value !== null && value[Kind] === "variant";
+}