@maroonedog/luq 0.1.2-alpha → 2.0.0

package/dist/json-schema/schema-to-declarations.mjs

@@ -0,0 +1,116 @@
+import { isDefinitionContainer } from "./collect-definitions.mjs";
+import { composeConditional } from "./compose-conditional.mjs";
+import { composeAllOf, composeAnyOf, composeNot, composeOneOf, } from "./compose-keyword.mjs";
+import { declareAdditionalPropertiesSchema, declareDependencies, declareObjectRules, declarePatternProperties, declarePropertyNames, readPropertyChildren, } from "./declare-object-keywords.mjs";
+import { declareRequiredProperties } from "./declare-required-properties.mjs";
+import { declareFormatRules, declareNumberRules, declareStringRules, } from "./declare-scalar-keywords.mjs";
+import { declareConstRules, declareEnumRules, declareIntegerRules, declareTypeRules, } from "./declare-value-keywords.mjs";
+import { composeContains, composeTupleItems, declareArrayRules, readItemChildren, } from "./flatten-array-schema.mjs";
+import { NON_DRAFT07_KEYWORDS, findKeywordHandling } from "./keyword-map.mjs";
+import { readChildExpansion, readRuleExpansion, } from "./structural-expansion.types.mjs";
+import { UnsupportedKeywordError } from "./unsupported-keyword-error.mjs";
+const CONSUMED_BY_IF = "inert without `if` (Draft-07 §6.6.2); composed there";
+export const STRUCTURAL_EXPANSIONS = {
+    $ref: {
+        expandsTo: "consumed",
+        consumedBy: "resolve-ref",
+        reason: "the node is replaced before any keyword is read",
+    },
+    definitions: {
+        expandsTo: "consumed",
+        consumedBy: "collect-definitions",
+        reason: "a container of schemas, never a constraint",
+    },
+    type: {
+        expandsTo: "rules",
+        toRules: (schema, context) => [
+            ...declareTypeRules(schema, context),
+            ...declareIntegerRules(schema, context),
+        ],
+    },
+    enum: { expandsTo: "rules", toRules: declareEnumRules },
+    allOf: { expandsTo: "rules", toRules: composeAllOf },
+    anyOf: { expandsTo: "rules", toRules: composeAnyOf },
+    oneOf: { expandsTo: "rules", toRules: composeOneOf },
+    not: { expandsTo: "rules", toRules: composeNot },
+    if: { expandsTo: "rules", toRules: composeConditional },
+    then: {
+        expandsTo: "consumed",
+        consumedBy: "compose-conditional",
+        reason: CONSUMED_BY_IF,
+    },
+    else: {
+        expandsTo: "consumed",
+        consumedBy: "compose-conditional",
+        reason: CONSUMED_BY_IF,
+    },
+    format: { expandsTo: "rules", toRules: declareFormatRules },
+    items: {
+        expandsTo: "rules-and-declarations",
+        toRules: composeTupleItems,
+        toChildren: readItemChildren,
+    },
+    additionalItems: {
+        expandsTo: "consumed",
+        consumedBy: "flatten-array-schema",
+        reason: "the rest branch of the tuple form of `items`",
+    },
+    contains: { expandsTo: "rules", toRules: composeContains },
+    properties: { expandsTo: "declarations", toChildren: readPropertyChildren },
+    patternProperties: { expandsTo: "rules", toRules: declarePatternProperties },
+    dependencies: { expandsTo: "rules", toRules: declareDependencies },
+    propertyNames: { expandsTo: "rules", toRules: declarePropertyNames },
+};
+export function isStructuralKeyword(name) {
+    return Object.prototype.hasOwnProperty.call(STRUCTURAL_EXPANSIONS, name);
+}
+/** Every child path a schema declares: `properties` keys and `items`' `[*]`. */
+export function readChildSchemas(schema) {
+    const children = [];
+    for (const expansion of Object.values(STRUCTURAL_EXPANSIONS)) {
+        const toChildren = readChildExpansion(expansion);
+        if (toChildren === undefined)
+            continue;
+        children.push(...toChildren(schema));
+    }
+    return Object.freeze(children);
+}
+/**
+ * A name the table does not know is an ANNOTATION and is ignored (Draft-07
+ * §4.3.2). A name Luq recognises as belonging to another dialect is not: it
+ * would change the meaning of the document, so it is refused by name.
+ */
+function assertKeywordIsConvertible(keyword) {
+    if (findKeywordHandling(keyword) !== undefined)
+        return;
+    if (isDefinitionContainer(keyword))
+        return;
+    const note = NON_DRAFT07_KEYWORDS[keyword];
+    if (note !== undefined)
+        throw new UnsupportedKeywordError(keyword, note);
+}
+/** The rules a schema imposes ON ITS OWN SUBJECT, children excluded. */
+export function expandSchemaRules(schema, context) {
+    const rules = [
+        ...declareStringRules(schema, context),
+        ...declareNumberRules(schema, context),
+        ...declareArrayRules(schema, context),
+        ...declareObjectRules(schema, context),
+        ...declareConstRules(schema, context),
+        ...declareAdditionalPropertiesSchema(schema, context),
+        ...declareRequiredProperties(schema, context),
+    ];
+    for (const keyword of Object.keys(schema)) {
+        assertKeywordIsConvertible(keyword);
+    }
+    // Driven by the TABLE, not by the keys somebody remembered to look at: every
+    // expansion self-gates on its own keyword, so a structural keyword can never
+    // be present in the document and unreached here.
+    for (const expansion of Object.values(STRUCTURAL_EXPANSIONS)) {
+        const toRules = readRuleExpansion(expansion);
+        if (toRules === undefined)
+            continue;
+        rules.push(...toRules(schema, context));
+    }
+    return Object.freeze(rules);
+}

package/dist/json-schema/structural-expansion.types.d.ts

@@ -0,0 +1,83 @@
+import type { ChainBuildContext } from "../chain/create-chain-node";
+import type { CompositeBranch, Rule } from "../plugin-kit/compiled-rule";
+import type { RuleBuildContext } from "../plugin-kit/rule-build-context";
+import type { MessageContextExtra } from "../types";
+import type { Draft07Schema, Draft07SchemaObject } from "./draft07.types";
+import type { JsonSchemaBag } from "./json-schema-bag.types";
+/**
+ * The nineteen keywords `draft07KeywordMap` marks `structural`. Written out by
+ * hand so the table below can be total over it; a runtime test in
+ * test/unit/json-schema/convert/ asserts this union has EXACTLY the members the
+ * keyword map marks structural, in both directions, so the two cannot drift.
+ */
+export type StructuralKeyword = "$ref" | "definitions" | "type" | "enum" | "allOf" | "anyOf" | "oneOf" | "not" | "if" | "then" | "else" | "format" | "items" | "additionalItems" | "contains" | "properties" | "patternProperties" | "dependencies" | "propertyNames";
+/**
+ * One step down from a schema to a sub-schema that gets its OWN declared path.
+ * `step` is already in the L1 path grammar: `.name` for a property, `[*]` for
+ * an array element, so joining is concatenation and never string surgery.
+ */
+export interface ChildSchema {
+    readonly step: string;
+    readonly schema: Draft07Schema;
+    readonly isRequired: boolean;
+}
+/**
+ * What an expansion may reach. `collectSubSchemaRules` and `toBranch` are
+ * INJECTED rather than imported: compose-keyword needs to convert its own
+ * sub-schemas, and schema-to-declarations needs compose-keyword, so importing
+ * either way round would close a cycle. schema-to-declarations is the single
+ * supplier of both.
+ */
+export interface StructuralContext {
+    readonly bag: JsonSchemaBag;
+    readonly build: ChainBuildContext;
+    readonly root: Draft07Schema;
+    /**
+     * The `$ref` pointers already entered on this branch of the conversion. A
+     * repeat is a RECURSIVE definition, whose expansion does not terminate, so
+     * the sub-schema converter stops there instead of building forever.
+     */
+    readonly visitedRefs: readonly string[];
+    /** Rules a SUB-schema imposes on the SAME subject (allOf arms, if/then). */
+    collectSubSchemaRules(schema: Draft07Schema): readonly Rule[];
+    /** A sub-schema as one composite branch: own rules plus relative fields. */
+    toBranch(label: string, schema: Draft07Schema): CompositeBranch;
+    /**
+     * What a bag plugin's `build()` needs. Written once here so no expansion
+     * assembles a RuleBuildContext of its own and drifts on severity or code.
+     */
+    ruleContextFor<C extends MessageContextExtra>(pluginName: string, code: string): RuleBuildContext<C>;
+}
+export type ExpandToRules = (schema: Draft07SchemaObject, context: StructuralContext) => readonly Rule[];
+export type ExpandToChildren = (schema: Draft07SchemaObject) => readonly ChildSchema[];
+/** The modules allowed to consume a keyword on another keyword's behalf. */
+export type StructuralConsumer = "resolve-ref" | "collect-definitions" | "compose-conditional" | "flatten-array-schema";
+interface RulesExpansion {
+    readonly expandsTo: "rules";
+    readonly toRules: ExpandToRules;
+}
+interface ChildrenExpansion {
+    readonly expandsTo: "declarations";
+    readonly toChildren: ExpandToChildren;
+}
+interface RulesAndChildrenExpansion {
+    readonly expandsTo: "rules-and-declarations";
+    readonly toRules: ExpandToRules;
+    readonly toChildren: ExpandToChildren;
+}
+/** The only entry with no function, and it must name its consumer. */
+interface ConsumedExpansion {
+    readonly expandsTo: "consumed";
+    readonly consumedBy: StructuralConsumer;
+    readonly reason: string;
+}
+export type StructuralExpansion = RulesExpansion | ChildrenExpansion | RulesAndChildrenExpansion | ConsumedExpansion;
+/** Total over the vocabulary: a forgotten recursion is a compile error. */
+export type StructuralExpansionTable = {
+    readonly [Keyword in StructuralKeyword]: StructuralExpansion;
+};
+/** Narrows an expansion to the ones that contribute rules at this path. */
+export declare function readRuleExpansion(expansion: StructuralExpansion): ExpandToRules | undefined;
+/** Narrows an expansion to the ones that contribute child declarations. */
+export declare function readChildExpansion(expansion: StructuralExpansion): ExpandToChildren | undefined;
+export {};

package/dist/json-schema/structural-expansion.types.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRuleExpansion = readRuleExpansion;
+exports.readChildExpansion = readChildExpansion;
+/** Narrows an expansion to the ones that contribute rules at this path. */
+function readRuleExpansion(expansion) {
+    if (expansion.expandsTo === "rules")
+        return expansion.toRules;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toRules;
+    }
+    return undefined;
+}
+/** Narrows an expansion to the ones that contribute child declarations. */
+function readChildExpansion(expansion) {
+    if (expansion.expandsTo === "declarations")
+        return expansion.toChildren;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toChildren;
+    }
+    return undefined;
+}

package/dist/json-schema/structural-expansion.types.mjs

@@ -0,0 +1,18 @@
+/** Narrows an expansion to the ones that contribute rules at this path. */
+export function readRuleExpansion(expansion) {
+    if (expansion.expandsTo === "rules")
+        return expansion.toRules;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toRules;
+    }
+    return undefined;
+}
+/** Narrows an expansion to the ones that contribute child declarations. */
+export function readChildExpansion(expansion) {
+    if (expansion.expandsTo === "declarations")
+        return expansion.toChildren;
+    if (expansion.expandsTo === "rules-and-declarations") {
+        return expansion.toChildren;
+    }
+    return undefined;
+}

package/dist/json-schema/unsupported-keyword-error.d.ts

@@ -0,0 +1,5 @@
+export declare class UnsupportedKeywordError extends Error {
+    readonly keyword: string;
+    readonly reason: string;
+    constructor(keyword: string, reason: string);
+}

package/dist/json-schema/unsupported-keyword-error.js

@@ -0,0 +1,24 @@
+"use strict";
+// ===========================================================================
+// L8  src/json-schema/unsupported-keyword-error.ts
+//
+// 1.x's answer to a keyword it could not honour was to store it in a DSL field
+// and never read it again: `enum`, `contains`, `not`, `if`/`then`/`else`,
+// `patternProperties` and five more all looked supported and did nothing. A
+// validator that silently drops a constraint is worse than one that refuses
+// the schema, so the refusal is a typed error carrying the keyword, the reason
+// the table gives, and — when the reason is a missing plugin — its name.
+// ===========================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedKeywordError = void 0;
+class UnsupportedKeywordError extends Error {
+    constructor(keyword, reason) {
+        super(`JSON Schema keyword "${keyword}" is not supported: ${reason}`);
+        this.name = "UnsupportedKeywordError";
+        this.keyword = keyword;
+        this.reason = reason;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, UnsupportedKeywordError.prototype);
+    }
+}
+exports.UnsupportedKeywordError = UnsupportedKeywordError;

package/dist/json-schema/unsupported-keyword-error.mjs

@@ -0,0 +1,20 @@
+// ===========================================================================
+// L8  src/json-schema/unsupported-keyword-error.ts
+//
+// 1.x's answer to a keyword it could not honour was to store it in a DSL field
+// and never read it again: `enum`, `contains`, `not`, `if`/`then`/`else`,
+// `patternProperties` and five more all looked supported and did nothing. A
+// validator that silently drops a constraint is worse than one that refuses
+// the schema, so the refusal is a typed error carrying the keyword, the reason
+// the table gives, and — when the reason is a missing plugin — its name.
+// ===========================================================================
+export class UnsupportedKeywordError extends Error {
+    constructor(keyword, reason) {
+        super(`JSON Schema keyword "${keyword}" is not supported: ${reason}`);
+        this.name = "UnsupportedKeywordError";
+        this.keyword = keyword;
+        this.reason = reason;
+        // Without this, `instanceof` fails when the package is compiled to ES5.
+        Object.setPrototypeOf(this, UnsupportedKeywordError.prototype);
+    }
+}

package/dist/path/create-array-reader.d.ts

@@ -0,0 +1,13 @@
+import type { PathSegment } from "./path-segment.types";
+export type ArrayReader = (subject: unknown) => readonly unknown[] | null;
+/**
+ * null means "there is no array here", which the runner treats as "element
+ * rules are vacuous" — the must-preserve contract that a non-array at an `[*]`
+ * path produces no issue from the element rule. Asserting that the container
+ * IS an array is a separate, declared rule on the container path.
+ *
+ * An empty array is an array: it reads back as `[]`, and the element loop then
+ * runs zero times. That distinction is the whole reason this returns
+ * `readonly unknown[] | null` and not `readonly unknown[]`.
+ */
+export declare function createArrayReader(template: readonly PathSegment[]): ArrayReader;

package/dist/path/create-array-reader.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createArrayReader = createArrayReader;
+const create_value_reader_1 = require("./create-value-reader");
+const types_1 = require("../types");
+/**
+ * null means "there is no array here", which the runner treats as "element
+ * rules are vacuous" — the must-preserve contract that a non-array at an `[*]`
+ * path produces no issue from the element rule. Asserting that the container
+ * IS an array is a separate, declared rule on the container path.
+ *
+ * An empty array is an array: it reads back as `[]`, and the element loop then
+ * runs zero times. That distinction is the whole reason this returns
+ * `readonly unknown[] | null` and not `readonly unknown[]`.
+ */
+function createArrayReader(template) {
+    const read = (0, create_value_reader_1.createValueReader)(template);
+    return (subject) => {
+        const value = read(subject);
+        return (0, types_1.isArray)(value) ? value : null;
+    };
+}

package/dist/path/create-array-reader.mjs

@@ -0,0 +1,19 @@
+import { createValueReader } from "./create-value-reader.mjs";
+import { isArray } from "../types/index.mjs";
+/**
+ * null means "there is no array here", which the runner treats as "element
+ * rules are vacuous" — the must-preserve contract that a non-array at an `[*]`
+ * path produces no issue from the element rule. Asserting that the container
+ * IS an array is a separate, declared rule on the container path.
+ *
+ * An empty array is an array: it reads back as `[]`, and the element loop then
+ * runs zero times. That distinction is the whole reason this returns
+ * `readonly unknown[] | null` and not `readonly unknown[]`.
+ */
+export function createArrayReader(template) {
+    const read = createValueReader(template);
+    return (subject) => {
+        const value = read(subject);
+        return isArray(value) ? value : null;
+    };
+}

package/dist/path/create-value-reader.d.ts

@@ -0,0 +1,26 @@
+import type { PathSegment } from "./path-segment.types";
+export type ValueReader = (subject: unknown) => unknown;
+/** True for arrays too: both are indexable by a string key. */
+export declare function isIndexableObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Own properties only. `in` and plain member access walk the prototype chain,
+ * which is how the legacy tree reported `toString` as a present field. A
+ * primitive intermediate does NOT descend (`{user:"John"}` at `user.name` is
+ * undefined, not `"John".name`), and an array hole is absent rather than
+ * undefined-valued — the same answer either way, reached honestly.
+ */
+export declare function readOwnProperty(subject: unknown, key: string): unknown;
+/**
+ * Validates a template and flattens it to plain keys. Shared with the writer
+ * so the two directions cannot disagree about what a template may contain.
+ *
+ * A `[*]` segment is rejected: a wildcard names many values, and this reader
+ * has one return value. The array runner splits a wildcard template into an
+ * array node plus an element template before it ever gets here.
+ */
+export declare function collectKeySegments(template: readonly PathSegment[]): readonly string[];
+/**
+ * An empty template is the identity reader: the element of `items[*]` is
+ * declared relative to itself, and that is a real compiled field.
+ */
+export declare function createValueReader(template: readonly PathSegment[]): ValueReader;

package/dist/path/create-value-reader.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isIndexableObject = isIndexableObject;
+exports.readOwnProperty = readOwnProperty;
+exports.collectKeySegments = collectKeySegments;
+exports.createValueReader = createValueReader;
+const reserved_segment_1 = require("./reserved-segment");
+const hasOwnProperty = Object.prototype.hasOwnProperty;
+/** True for arrays too: both are indexable by a string key. */
+function isIndexableObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Own properties only. `in` and plain member access walk the prototype chain,
+ * which is how the legacy tree reported `toString` as a present field. A
+ * primitive intermediate does NOT descend (`{user:"John"}` at `user.name` is
+ * undefined, not `"John".name`), and an array hole is absent rather than
+ * undefined-valued — the same answer either way, reached honestly.
+ */
+function readOwnProperty(subject, key) {
+    if (!isIndexableObject(subject))
+        return undefined;
+    return hasOwnProperty.call(subject, key) ? subject[key] : undefined;
+}
+/**
+ * Validates a template and flattens it to plain keys. Shared with the writer
+ * so the two directions cannot disagree about what a template may contain.
+ *
+ * A `[*]` segment is rejected: a wildcard names many values, and this reader
+ * has one return value. The array runner splits a wildcard template into an
+ * array node plus an element template before it ever gets here.
+ */
+function collectKeySegments(template) {
+    const rendered = describeTemplate(template);
+    const keys = [];
+    for (const segment of template) {
+        if (segment.kind === "each") {
+            throw new reserved_segment_1.PathSyntaxError(rendered, "a single-value template must not contain a wildcard segment");
+        }
+        (0, reserved_segment_1.assertDeclarableKey)(segment.key, rendered);
+        keys.push(segment.key);
+    }
+    return keys;
+}
+function describeTemplate(template) {
+    return template
+        .map((segment) => (segment.kind === "each" ? "[*]" : segment.key))
+        .join(".");
+}
+/**
+ * An empty template is the identity reader: the element of `items[*]` is
+ * declared relative to itself, and that is a real compiled field.
+ */
+function createValueReader(template) {
+    const keys = collectKeySegments(template);
+    const only = keys[0];
+    if (keys.length === 0)
+        return (subject) => subject;
+    if (keys.length === 1 && only !== undefined) {
+        return (subject) => readOwnProperty(subject, only);
+    }
+    return (subject) => {
+        let current = subject;
+        for (const key of keys) {
+            current = readOwnProperty(current, key);
+            if (current === undefined)
+                return undefined;
+        }
+        return current;
+    };
+}

package/dist/path/create-value-reader.mjs

@@ -0,0 +1,65 @@
+import { PathSyntaxError, assertDeclarableKey } from "./reserved-segment.mjs";
+const hasOwnProperty = Object.prototype.hasOwnProperty;
+/** True for arrays too: both are indexable by a string key. */
+export function isIndexableObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Own properties only. `in` and plain member access walk the prototype chain,
+ * which is how the legacy tree reported `toString` as a present field. A
+ * primitive intermediate does NOT descend (`{user:"John"}` at `user.name` is
+ * undefined, not `"John".name`), and an array hole is absent rather than
+ * undefined-valued — the same answer either way, reached honestly.
+ */
+export function readOwnProperty(subject, key) {
+    if (!isIndexableObject(subject))
+        return undefined;
+    return hasOwnProperty.call(subject, key) ? subject[key] : undefined;
+}
+/**
+ * Validates a template and flattens it to plain keys. Shared with the writer
+ * so the two directions cannot disagree about what a template may contain.
+ *
+ * A `[*]` segment is rejected: a wildcard names many values, and this reader
+ * has one return value. The array runner splits a wildcard template into an
+ * array node plus an element template before it ever gets here.
+ */
+export function collectKeySegments(template) {
+    const rendered = describeTemplate(template);
+    const keys = [];
+    for (const segment of template) {
+        if (segment.kind === "each") {
+            throw new PathSyntaxError(rendered, "a single-value template must not contain a wildcard segment");
+        }
+        assertDeclarableKey(segment.key, rendered);
+        keys.push(segment.key);
+    }
+    return keys;
+}
+function describeTemplate(template) {
+    return template
+        .map((segment) => (segment.kind === "each" ? "[*]" : segment.key))
+        .join(".");
+}
+/**
+ * An empty template is the identity reader: the element of `items[*]` is
+ * declared relative to itself, and that is a real compiled field.
+ */
+export function createValueReader(template) {
+    const keys = collectKeySegments(template);
+    const only = keys[0];
+    if (keys.length === 0)
+        return (subject) => subject;
+    if (keys.length === 1 && only !== undefined) {
+        return (subject) => readOwnProperty(subject, only);
+    }
+    return (subject) => {
+        let current = subject;
+        for (const key of keys) {
+            current = readOwnProperty(current, key);
+            if (current === undefined)
+                return undefined;
+        }
+        return current;
+    };
+}

package/dist/path/create-value-writer.d.ts

@@ -0,0 +1,5 @@
+import type { PathSegment } from "./path-segment.types";
+/** Returns the new root. It is NOT `void`: a copy-on-write write cannot report
+ *  its result through the argument it refused to mutate. */
+export type ValueWriter = (subject: unknown, value: unknown) => unknown;
+export declare function createValueWriter(template: readonly PathSegment[]): ValueWriter;

package/dist/path/create-value-writer.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createValueWriter = createValueWriter;
+const create_value_reader_1 = require("./create-value-reader");
+const types_1 = require("../types");
+function createValueWriter(template) {
+    const keys = (0, create_value_reader_1.collectKeySegments)(template);
+    if (keys.length === 0)
+        return (_subject, value) => value;
+    return (subject, value) => writeInto(subject, keys, 0, value);
+}
+function writeInto(container, keys, depth, value) {
+    const key = keys[depth];
+    if (key === undefined)
+        return value;
+    if (container === null || container === undefined) {
+        return vivify(key, writeInto(undefined, keys, depth + 1, value));
+    }
+    if (!(0, create_value_reader_1.isIndexableObject)(container))
+        return container;
+    const child = (0, create_value_reader_1.readOwnProperty)(container, key);
+    const written = writeInto(child, keys, depth + 1, value);
+    if (written === child)
+        return container;
+    return copyWith(container, key, written);
+}
+/**
+ * Auto-vivification, restricted to the one case the legacy rule got wrong:
+ * only a missing or null intermediate is created. A present primitive is left
+ * exactly as it is (the `if (!isIndexableObject) return container` above), so
+ * writing `a.b` into `{a: 0}` destroys nothing and returns the original root
+ * by identity.
+ *
+ * The container created is always a plain object. A numeric segment does not
+ * conjure an array — the declaration grammar cannot express `items[0]`, so a
+ * numeric key here is a Record key.
+ */
+function vivify(key, written) {
+    const created = {};
+    created[key] = written;
+    return created;
+}
+function copyWith(container, key, value) {
+    if ((0, types_1.isArray)(container)) {
+        const index = Number(key);
+        if (!Number.isInteger(index) || index < 0)
+            return container;
+        const copy = container.slice();
+        copy[index] = value;
+        return copy;
+    }
+    const copy = { ...container };
+    copy[key] = value;
+    return copy;
+}

package/dist/path/create-value-writer.mjs

@@ -0,0 +1,52 @@
+import { collectKeySegments, isIndexableObject, readOwnProperty, } from "./create-value-reader.mjs";
+import { isArray } from "../types/index.mjs";
+export function createValueWriter(template) {
+    const keys = collectKeySegments(template);
+    if (keys.length === 0)
+        return (_subject, value) => value;
+    return (subject, value) => writeInto(subject, keys, 0, value);
+}
+function writeInto(container, keys, depth, value) {
+    const key = keys[depth];
+    if (key === undefined)
+        return value;
+    if (container === null || container === undefined) {
+        return vivify(key, writeInto(undefined, keys, depth + 1, value));
+    }
+    if (!isIndexableObject(container))
+        return container;
+    const child = readOwnProperty(container, key);
+    const written = writeInto(child, keys, depth + 1, value);
+    if (written === child)
+        return container;
+    return copyWith(container, key, written);
+}
+/**
+ * Auto-vivification, restricted to the one case the legacy rule got wrong:
+ * only a missing or null intermediate is created. A present primitive is left
+ * exactly as it is (the `if (!isIndexableObject) return container` above), so
+ * writing `a.b` into `{a: 0}` destroys nothing and returns the original root
+ * by identity.
+ *
+ * The container created is always a plain object. A numeric segment does not
+ * conjure an array — the declaration grammar cannot express `items[0]`, so a
+ * numeric key here is a Record key.
+ */
+function vivify(key, written) {
+    const created = {};
+    created[key] = written;
+    return created;
+}
+function copyWith(container, key, value) {
+    if (isArray(container)) {
+        const index = Number(key);
+        if (!Number.isInteger(index) || index < 0)
+            return container;
+        const copy = container.slice();
+        copy[index] = value;
+        return copy;
+    }
+    const copy = { ...container };
+    copy[key] = value;
+    return copy;
+}

package/dist/path/element-of.types.d.ts

@@ -0,0 +1 @@
+export type ElementOf<T> = unknown extends T ? unknown : NonNullable<T> extends infer U ? U extends readonly (infer E)[] ? E : never : never;

package/dist/path/element-of.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/path/element-of.types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/path/field-path.types.d.ts

@@ -0,0 +1,13 @@
+import type { IsOpaqueObject } from "./opaque-object.types";
+import type { PathDepthBudget, PreviousDepth } from "./path-depth.types";
+import type { ElementOf } from "./element-of.types";
+/** The union of legal path literals for T. `[*]` is the only array wildcard and
+ *  array members are never enumerated, which removes `items.name`,
+ *  `items[0].name`, `tags.length` and `items.map` with ONE rule. */
+export type FieldPath<T, D extends number = PathDepthBudget> = RecordPaths<T, D>;
+type RecordPaths<T, D extends number> = NonNullable<T> extends infer U ? U extends readonly unknown[] ? never : IsOpaqueObject<U> extends true ? never : U extends object ? {
+    [K in Extract<keyof U, string>]-?: K | DescendantPaths<K, U[K], D>;
+}[Extract<keyof U, string>] : never : never;
+type DescendantPaths<Prefix extends string, V, D extends number> = D extends 0 ? never : NonNullable<V> extends infer U ? U extends readonly unknown[] ? `${Prefix}[*]` | DescendantPaths<`${Prefix}[*]`, ElementOf<U>, PreviousDepth[D]> : IsOpaqueObject<U> extends true ? never : U extends object ? JoinPath<Prefix, RecordPaths<U, PreviousDepth[D]>> : never : never;
+type JoinPath<Prefix extends string, Sub> = Sub extends string ? `${Prefix}.${Sub}` : never;
+export {};