@afora/core 0.0.8 → 0.0.11

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

@@ -10,9 +10,22 @@ import type { StandardSchemaV1 } from "../../standard/standard-schema.js";
 import type { Kind } from "../../symbols/kind.js";
 import type { listOf } from "../list.js";
 import type { optionalOf } from "../optional.js";
+import type { variantOf } from "../variant.js";
 import type { IBlueprintFactories, IBlueprintPlugin } from "./blueprint-plugin.interface.js";
 /** Any blueprint, whatever its properties, optional or not. */
 export type AnyBlueprint = IBlueprint<any, boolean>;
+/**
+ * Any variant field, whatever its key and its variants, optional or not.
+ * Written out, not as `IBlueprintVariant` of anything: every field of every
+ * blueprint is compared with it, and this way nothing is worked out for that.
+ */
+export interface AnyBlueprintVariant {
+    readonly [Kind]: "variant";
+    readonly key: string;
+    readonly variants: any;
+    readonly optional: boolean;
+    readonly "~standard": StandardSchemaV1.Props<any, any>;
+}
 /** Any list, whatever its item, optional or not. */
 export type AnyBlueprintList = IBlueprintList<any, boolean>;
 /**
@@ -40,9 +53,10 @@ export interface OptionalRecord<Record extends AnyRecordClass> {
 export type AnyOptionalRecord = OptionalRecord<AnyRecordClass>;
 /**
  * What a blueprint key holds: a property, a blueprint for a nested object, a
- * record, or a list of any of them.
+ * record, a list of any of them, or one of several blueprints told apart by a
+ * key.
  */
-export type BlueprintField = AnyPropertyConstructor | AnyBlueprint | AnyBlueprintList | AnyRecordClass | AnyOptionalRecord;
+export type BlueprintField = AnyPropertyConstructor | AnyBlueprint | AnyBlueprintList | AnyRecordClass | AnyOptionalRecord | AnyBlueprintVariant;
 /** Fields by key, e.g. `{ name: Name, address: Address }`. */
 export type IBlueprintCollection = Record<string, BlueprintField>;
 /** What a blueprint picks its fields from: a plugin, or another blueprint. */
@@ -66,7 +80,17 @@ type FieldSchema<Field, Mode extends FieldMode> = 0 extends 1 & Field ? TSchema
 } ? Optional extends true ? TOptional<CollectionSchema<Properties, Mode>> : CollectionSchema<Properties, Mode> : Field extends {
     readonly item: infer Item;
     readonly optional: infer Optional;
-} ? Optional extends true ? TOptional<TArray<FieldSchema<Item, Mode>>> : TArray<FieldSchema<Item, Mode>> : never;
+} ? Optional extends true ? TOptional<TArray<FieldSchema<Item, Mode>>> : TArray<FieldSchema<Item, Mode>> : VariantSchema<Field, Mode>;
+/**
+ * The schema of a variant field: its value as it is, since a union of objects
+ * is only read for whether the key is optional. Apart from `FieldSchema`, so
+ * that a field that is not a variant costs one comparison there.
+ */
+type VariantSchema<Field, Mode extends FieldMode> = Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+    readonly optional: infer Optional;
+} ? Optional extends true ? TOptional<TUnsafe<VariantValue<Key, Variants, Mode>>> : TUnsafe<VariantValue<Key, Variants, Mode>> : never;
 /** Declares the records a field of a record class takes besides its own. */
 export declare const RecordAccepts: unique symbol;
 /** The values besides its instances and plain input that a field of `Record` takes. */
@@ -102,7 +126,31 @@ type FieldValue<Field, Mode extends FieldMode> = 0 extends 1 & Field ? Static<TS
     readonly properties: infer Properties extends IBlueprintCollection;
 } ? CollectionValue<Properties, Mode> : Field extends {
     readonly item: infer Item;
-} ? FieldValue<Item, Mode>[] : never;
+} ? FieldValue<Item, Mode>[] : Field extends {
+    readonly key: infer Key extends string;
+    readonly variants: infer Variants;
+} ? VariantValue<Key, Variants, Mode> : never;
+/**
+ * The value of a variant field: for each variant, its own value with `Key`
+ * set to its name, so that `value[Key]` tells which one it is. Anything for a
+ * field of any variants (as `AnyBlueprintVariant`'s).
+ */
+type VariantValue<Key extends string, Variants, Mode extends FieldMode> = 0 extends 1 & Variants ? any : {
+    [Tag in keyof Variants & string]: VariantMember<Key, Tag, Variants[Tag], Mode>;
+}[keyof Variants & string];
+/**
+ * The value of one variant named `Tag`. A blueprint gives its value with the
+ * key. A record class gives an instance, which has no key and is told apart
+ * by its class; what it takes is an instance or its plain input with the key,
+ * and its plain data has the key.
+ */
+type VariantMember<Key extends string, Tag, Variant, Mode extends FieldMode> = Variant extends AnyRecordClass ? Mode extends "value" ? InstanceType<Variant> : Mode extends "input" ? InstanceType<Variant> | Evaluate<{
+    readonly [Name in Key]: Tag;
+} & RecordInput<Variant>> : Evaluate<{
+    readonly [Name in Key]: Tag;
+} & RecordValueOf<Variant, "data">> : Evaluate<{
+    readonly [Name in Key]: Tag;
+} & FieldValue<Variant, Mode>>;
 /** The value of a record field, as `RecordSchema` describes it. */
 type RecordValueOf<Record extends AnyRecordClass, Mode extends FieldMode> = Mode extends "value" ? InstanceType<Record> : Mode extends "input" ? InstanceType<Record> | RecordInput<Record> | AcceptedBy<Record> : Record["blueprint"] extends IBlueprint<infer Properties, boolean> ? CollectionValue<Properties, "data"> : never;
 type ReadonlyOptionalKeys<Schemas> = {
@@ -196,6 +244,7 @@ export interface BlueprintHelpers {
     readonly listOf: typeof listOf;
     readonly optionalOf: typeof optionalOf;
     readonly propertyOf: typeof propertyOf;
+    readonly variantOf: typeof variantOf;
 }
 /**
  * What a blueprint's definition picks from: every source field, the field
@@ -223,9 +272,24 @@ export type CallableProperties<Fields> = {
  * @internal
  */
 export type OptionalProperties<Properties> = {
-    readonly [Key in keyof Properties]: Properties[Key] extends AnyPropertyConstructor ? OptionalProperty<Properties[Key]> : Properties[Key] extends AnyBlueprint ? OptionalBlueprint<Properties[Key]> : Properties[Key] extends AnyBlueprintList ? OptionalBlueprintList<Properties[Key]> : Properties[Key] extends AnyRecordClass ? OptionalRecord<Properties[Key]> : Properties[Key] extends AnyOptionalRecord ? Properties[Key] : never;
+    readonly [Key in keyof Properties]: Properties[Key] extends AnyPropertyConstructor ? OptionalProperty<Properties[Key]> : Properties[Key] extends AnyBlueprint ? OptionalBlueprint<Properties[Key]> : Properties[Key] extends AnyBlueprintList ? OptionalBlueprintList<Properties[Key]> : Properties[Key] extends AnyRecordClass ? OptionalRecord<Properties[Key]> : Properties[Key] extends AnyOptionalRecord ? Properties[Key] : Properties[Key] extends {
+        readonly key: infer Name extends string;
+        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. */
@@ -271,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;
@@ -288,6 +356,28 @@ export interface IBlueprintList<Item extends BlueprintField, Optional extends bo
     readonly "~standard": StandardSchemaV1.Props<ListShape<Item, "input", Optional>, ListShape<Item, "value", Optional>>;
 }
 type ListShape<Item, Mode extends FieldMode, Optional extends boolean> = Optional extends true ? FieldValue<Item, Mode>[] | undefined : FieldValue<Item, Mode>[];
+/** The variants of a variant field, by the value its key has for each: blueprints, or record classes. */
+export type BlueprintVariants = Readonly<Record<string, AnyBlueprint | AnyRecordClass>>;
+/**
+ * A field holding one of the objects of `Variants`, told apart by the value
+ * of `Key`, which is the name of the variant.
+ */
+export interface IBlueprintVariant<Key extends string, Variants extends BlueprintVariants, Optional extends boolean = false> {
+    readonly [Kind]: "variant";
+    /** The key that tells the variants apart; no variant declares it. */
+    readonly key: Key;
+    readonly variants: Variants;
+    /** Whether, as a field of a blueprint, it accepts `undefined`. */
+    readonly optional: Optional;
+    /**
+     * The Standard Schema of the field: `validate` gives the frozen value of
+     * the variant the key names, or the issues that reject the value.
+     */
+    readonly "~standard": StandardSchemaV1.Props<VariantShape<Key, Variants, "input", Optional>, VariantShape<Key, Variants, "value", Optional>>;
+}
+type VariantShape<Key extends string, Variants, Mode extends FieldMode, Optional extends boolean> = Optional extends true ? VariantValue<Key, Variants, Mode> | undefined : VariantValue<Key, Variants, Mode>;
+/** `Variant` as a field that accepts `undefined`. */
+export type OptionalBlueprintVariant<Variant extends AnyBlueprintVariant> = Variant extends IBlueprintVariant<infer Key, infer Variants, boolean> ? IBlueprintVariant<Key, Variants, true> : never;
 /** `List` as a field that accepts `undefined`. */
 export type OptionalBlueprintList<List extends AnyBlueprintList> = List extends IBlueprintList<infer Item, boolean> ? IBlueprintList<Item, true> : never;
 export {};

package/dist/core/blueprint/variant.d.ts

@@ -0,0 +1,32 @@
+import type { AnyBlueprint, AnyBlueprintVariant, BlueprintVariants, IBlueprintVariant } from "./types/blueprint.interface.js";
+/**
+ * A field holding one of several objects, told apart by the value of `key`:
+ * `variantOf("type", { click: Click, signup: Signup })` takes
+ * `{ type: "click", ...a Click }` or `{ type: "signup", ...a Signup }`. Each
+ * variant is a blueprint, which does not declare `key`: the field adds it,
+ * with the name of the variant for its value. A variant can also be a record
+ * class (an entity too): the value is then an instance of it, told apart by
+ * its class, and the key is only in what is given, in `toJSON` and in what is
+ * stored.
+ */
+export declare function variantOf<const Key extends string, const Variants extends BlueprintVariants>(key: Key, variants: Variants): IBlueprintVariant<Key, Variants>;
+/** `variant`, frozen, with the `~standard` that handles a value as `variant` does. */
+export declare function standardVariantOf<Variant extends object>(variant: Variant): Variant;
+type Variant = BlueprintVariants[string];
+/** The blueprint of a variant: itself, or that of the record class it is. */
+export declare function blueprintOfVariant(variant: Variant): AnyBlueprint;
+/**
+ * The variant that the plain `value` names with the key of `field`, if it
+ * names one: a blueprint or a record class.
+ */
+export declare function namedVariantOf(field: AnyBlueprintVariant, value: unknown): Variant | undefined;
+/** The blueprint of the variant that the plain `value` names with the key of `field`, if it names one. */
+export declare function variantOfValue(field: AnyBlueprintVariant, value: unknown): AnyBlueprint | undefined;
+/**
+ * The name of the variant `instance` is, a record of one of the classes of
+ * `field`; `undefined` when it is of none.
+ */
+export declare function variantNameOf(field: AnyBlueprintVariant, instance: unknown): string | undefined;
+/** Whether `value` is a field made by `variantOf`. */
+export declare function isBlueprintVariant(value: unknown): value is AnyBlueprintVariant;
+export {};

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