@narrative.io/jsonforms-provider-protocols 2.11.0 → 2.12.0

package/src/core/initFormData.ts

@@ -0,0 +1,208 @@
+/**
+ * Initialize a form data object from a JSON Schema.
+ * Resolves $ref, const, default, oneOf/discriminator, and typed empty values.
+ *
+ * Optional fields (not listed in the parent schema's `required` array) that
+ * have no `const`, no single-value `enum`, and no `default` are omitted
+ * entirely from the result. This avoids seeding values (e.g. `null` for
+ * `type: "integer"`) that fail AJV's type check and surface spurious errors
+ * on untouched fields. Required fields retain legacy typed-empty seeding
+ * (`""`, `null`, `false`, `[]`) so that "is required" surfaces cleanly.
+ *
+ * @param schema - The full JSON Schema (must include $defs if $refs are used)
+ * @param seed   - Optional existing data to merge (seed values take priority)
+ * @returns A data object with schema-defined fields initialized
+ */
+export function initFormDataFromSchema(
+  schema: Record<string, unknown>,
+  seed?: Record<string, unknown>,
+): Record<string, unknown> {
+  const result = initProperty(schema, schema, seed, true) as
+    | Record<string, unknown>
+    | undefined;
+
+  const base =
+    result && typeof result === "object" && !Array.isArray(result)
+      ? result
+      : {};
+
+  // Preserve seed keys not described by the schema's properties.
+  if (seed && typeof seed === "object") {
+    const schemaKeys = new Set(
+      Object.keys(
+        (resolveRef(schema, schema) as Record<string, unknown>)?.properties ??
+          {},
+      ),
+    );
+    for (const key of Object.keys(seed)) {
+      if (!schemaKeys.has(key) && !(key in base)) {
+        base[key] = seed[key];
+      }
+    }
+  }
+
+  return base;
+}
+
+import { resolveRef } from "./refs";
+
+/**
+ * Initialize a single property value based on its schema definition.
+ * Returns `undefined` when the property is optional and has nothing
+ * concrete to seed — the caller then omits the key from its result.
+ */
+function initProperty(
+  property: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seed: unknown,
+  required: boolean,
+): unknown {
+  if (!property || typeof property !== "object") {
+    return required ? null : undefined;
+  }
+
+  const resolved = resolveRef(property, root);
+  const type = resolved.type as string | undefined;
+  const isOneOf = Array.isArray(resolved.oneOf);
+
+  // Priority 1: seed wins for non-object, non-oneOf types. For oneOf we still
+  // descend so that a partial seed (e.g. `{value: 5}` missing the
+  // discriminator) picks up the variant's const/default for untouched fields.
+  if (seed !== undefined && seed !== null && type !== "object" && !isOneOf) {
+    return seed;
+  }
+
+  // Priority 2: const (schema-invariant — always set).
+  if ("const" in resolved) {
+    return resolved.const;
+  }
+
+  // Priority 3: single-value enum (same reasoning — only one valid value).
+  if (
+    Array.isArray(resolved.enum) &&
+    (resolved.enum as unknown[]).length === 1
+  ) {
+    return (resolved.enum as unknown[])[0];
+  }
+
+  // Priority 4: default (explicit author intent — always honored).
+  if ("default" in resolved) {
+    return resolved.default;
+  }
+
+  // Priority 5: oneOf. Recurse into the first variant, propagating the
+  // `required` flag so that the variant's own schema-declared required fields
+  // only get typed-empty seeding when the container is required. For optional
+  // containers, the variant's const / default / single-value enum still seed
+  // (author intent is unconditional) but typed-empty placeholders do not.
+  // If recursion yields nothing forced, we collapse back to undefined.
+  if (isOneOf) {
+    const value = initOneOf(resolved, root, seed, required);
+    if (
+      !required &&
+      (value === undefined ||
+        (value !== null &&
+          typeof value === "object" &&
+          !Array.isArray(value) &&
+          Object.keys(value as Record<string, unknown>).length === 0))
+    ) {
+      return undefined;
+    }
+    return value;
+  }
+
+  // Priority 6: objects recurse. The `required` flag propagates downward:
+  // inside an optional ancestor, nested required primitives also collapse,
+  // so an optional object with nested required fields stays absent instead
+  // of materializing a shell that AJV would flag.
+  if (type === "object") {
+    const obj = initObject(
+      resolved,
+      root,
+      seed as Record<string, unknown>,
+      required,
+    );
+    if (!required && Object.keys(obj).length === 0) return undefined;
+    return obj;
+  }
+
+  // Priority 7: optional primitives — omit.
+  if (!required) return undefined;
+
+  // Priority 8: required primitives — legacy typed empty.
+  switch (type) {
+    case "array":
+      return seed !== undefined && seed !== null ? seed : [];
+    case "string":
+      return "";
+    case "boolean":
+      return false;
+    case "number":
+    case "integer":
+    default:
+      return null;
+  }
+}
+
+/**
+ * Initialize an object type by recursing into its properties.
+ * Keys whose initialization returns `undefined` are omitted.
+ *
+ * `parentRequired` controls how schema.required propagates: a child is
+ * treated as required only if both its parent is required AND it appears in
+ * the parent's required array. Inside an optional ancestor the whole
+ * subtree collapses (except for author-forced values: const, default,
+ * single-value enum, or seeded values).
+ */
+function initObject(
+  schema: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seed: Record<string, unknown> | undefined,
+  parentRequired: boolean,
+): Record<string, unknown> {
+  const properties = schema.properties as
+    | Record<string, Record<string, unknown>>
+    | undefined;
+  if (!properties) {
+    return seed && typeof seed === "object" ? { ...seed } : {};
+  }
+
+  const requiredSet = new Set<string>(
+    Array.isArray(schema.required) ? (schema.required as string[]) : [],
+  );
+
+  const result: Record<string, unknown> = {};
+
+  for (const [key, propSchema] of Object.entries(properties)) {
+    const seedValue = seed && typeof seed === "object" ? seed[key] : undefined;
+    const effectiveRequired = parentRequired && requiredSet.has(key);
+    const value = initProperty(propSchema, root, seedValue, effectiveRequired);
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Handle oneOf schemas — pick the first variant and initialize it.
+ * `required` propagates: if the outer oneOf is required, the variant is
+ * materialized with typed-empty seeding for its required fields; if optional,
+ * only author-forced values (const / default / single-enum / seed) survive.
+ */
+function initOneOf(
+  schema: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seed: unknown,
+  required: boolean,
+): unknown {
+  const variants = schema.oneOf as Record<string, unknown>[];
+  if (!variants || variants.length === 0) return required ? null : undefined;
+
+  const first = variants[0];
+  if (!first) return required ? null : undefined;
+
+  const firstVariant = resolveRef(first, root);
+  return initProperty(firstVariant, root, seed, required);
+}

package/src/core/projection.ts

@@ -0,0 +1,147 @@
+import { deref as derefSchema, tryCombinatorBranches } from "./refs";
+
+/**
+ * Projection utilities for navigating complex data structures
+ * through a dot-separated path where numeric segments are array indices.
+ *
+ * Examples:
+ *   "0"                → first element of an array
+ *   "include"          → the `include` property of an object
+ *   "0.video_rate_usd" → nested property inside the first array element
+ */
+
+export type ProjectionSegment = string | number;
+
+/**
+ * Parse a projection path string into typed segments.
+ * Numeric strings become numbers (array indices), others stay as strings (object keys).
+ */
+export function parseProjectionPath(path: string): ProjectionSegment[] {
+  if (!path) return [];
+  return path.split(".").map((s) => {
+    const n = Number(s);
+    return Number.isInteger(n) && n >= 0 ? n : s;
+  });
+}
+
+/**
+ * Read a value from `data` by following the projection path.
+ * Returns `undefined` if any segment along the path is missing.
+ */
+export function getProjectedValue(data: unknown, path: string): unknown {
+  const segments = parseProjectionPath(path);
+  let current: unknown = data;
+
+  for (const seg of segments) {
+    if (current === null || current === undefined) return undefined;
+
+    if (typeof seg === "number") {
+      if (!Array.isArray(current)) return undefined;
+      current = current[seg];
+    } else {
+      if (typeof current !== "object") return undefined;
+      current = (current as Record<string, unknown>)[seg];
+    }
+  }
+
+  return current;
+}
+
+/**
+ * Immutably set a value at the projection path, preserving all sibling data.
+ * Constructs missing intermediate structures (arrays for numeric segments, objects for string segments).
+ */
+export function setProjectedValue(
+  data: unknown,
+  path: string,
+  value: unknown,
+): unknown {
+  const segments = parseProjectionPath(path);
+  return setAtPath(data, segments, 0, value);
+}
+
+function setAtPath(
+  current: unknown,
+  segments: ProjectionSegment[],
+  index: number,
+  value: unknown,
+): unknown {
+  if (index === segments.length) {
+    return value;
+  }
+
+  const seg = segments[index]!;
+
+  if (typeof seg === "number") {
+    // Array index — ensure we have an array
+    const arr = Array.isArray(current) ? [...current] : [];
+    // Pad array if index is out of bounds
+    while (arr.length <= seg) {
+      arr.push(undefined);
+    }
+    arr[seg] = setAtPath(arr[seg], segments, index + 1, value);
+    return arr;
+  } else {
+    // Object key — ensure we have an object
+    const obj: Record<string, unknown> =
+      current !== null &&
+      current !== undefined &&
+      typeof current === "object" &&
+      !Array.isArray(current)
+        ? { ...(current as Record<string, unknown>) }
+        : {};
+    obj[seg] = setAtPath(obj[seg], segments, index + 1, value);
+    return obj;
+  }
+}
+
+/**
+ * Resolve the schema at the projected path.
+ * Numeric segments traverse into `items` (array item schema).
+ * String segments traverse into `properties[segment]`.
+ *
+ * Dereferences `$ref` nodes transparently at every step, and falls through
+ * to `oneOf` / `anyOf` / `allOf` branches when a segment can't resolve
+ * directly — picks the first branch that satisfies the navigation.
+ */
+export function getProjectedSchema(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  schema: Record<string, any>,
+  path: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> {
+  const segments = parseProjectionPath(path);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: Record<string, any> | undefined = schema;
+
+  for (const seg of segments) {
+    current = derefSchema(current, schema);
+    if (!current) return {};
+
+    const navigate = (
+      node: Record<string, unknown>,
+    ): Record<string, unknown> | undefined => {
+      if (typeof seg === "number") {
+        const items = (node as { items?: unknown }).items;
+        return items && typeof items === "object"
+          ? (items as Record<string, unknown>)
+          : undefined;
+      }
+      const properties = (node as { properties?: unknown }).properties as
+        | Record<string, Record<string, unknown>>
+        | undefined;
+      if (properties && properties[seg]) return properties[seg];
+      return undefined;
+    };
+
+    let next = navigate(current);
+    if (next === undefined) {
+      next = tryCombinatorBranches(current, schema, navigate);
+    }
+    if (!next) return {};
+    current = next;
+  }
+
+  const resolved = derefSchema(current, schema);
+  return resolved ?? {};
+}

package/src/core/refs.ts

@@ -0,0 +1,166 @@
+/**
+ * JSON Schema $ref resolution helpers.
+ *
+ * Supports the pointer grammar used across consumer schemas:
+ *   - "#/$defs/Name"
+ *   - "#/properties/foo/items"
+ *
+ * External refs (URIs, file refs) are intentionally out of scope. A ref that
+ * doesn't resolve leaves the node untouched — callers can still inspect the
+ * unresolved `$ref` for debugging.
+ */
+
+/**
+ * Resolve a JSON pointer (`#/a/b/c`) against an object. Returns the node at
+ * that path, or `undefined` if any segment is missing or the pointer doesn't
+ * start with `#/`.
+ */
+export function resolvePointer(
+  obj: Record<string, unknown>,
+  pointer: string,
+): unknown {
+  if (!pointer.startsWith("#/")) return undefined;
+  const parts = pointer.slice(2).split("/");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in current) {
+      current = (current as Record<string, unknown>)[part];
+    } else {
+      return undefined;
+    }
+  }
+  return current;
+}
+
+/**
+ * Dereference a schema node along a chain of `$ref`s. Follows `A → B → C`
+ * transitively. A cycle (same `$ref` seen twice in one chain) returns the
+ * last unresolved node rather than hanging. An unresolvable pointer returns
+ * the current node unchanged.
+ */
+export function resolveRef(
+  property: Record<string, unknown>,
+  root: Record<string, unknown>,
+  seen?: Set<string>,
+): Record<string, unknown> {
+  if (!property || typeof property !== "object") return property;
+
+  const ref = property.$ref as string | undefined;
+  if (!ref) return property;
+
+  const visited = seen ?? new Set<string>();
+  if (visited.has(ref)) return property;
+  visited.add(ref);
+
+  const resolved = resolvePointer(root, ref);
+  if (!resolved) return property;
+
+  return resolveRef(resolved as Record<string, unknown>, root, visited);
+}
+
+/**
+ * Convenience wrapper around `resolveRef` that starts a fresh cycle-detection
+ * set. Intended for schema walkers that need to dereference at every step;
+ * each call is an independent resolution.
+ */
+export function deref(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> | undefined {
+  if (!node || typeof node !== "object") return node;
+  return resolveRef(node, root) as Record<string, unknown> | undefined;
+}
+
+/**
+ * Depth limit for combinator (oneOf/anyOf/allOf) branch descent. Schemas
+ * rarely nest combinators beyond one or two levels; this guard protects
+ * against pathological nesting and cycles (e.g. `oneOf: [$ref back to self]`).
+ */
+const COMBINATOR_DEPTH_LIMIT = 8;
+
+/**
+ * Try to navigate a segment through a schema node's combinator branches
+ * (`oneOf` / `anyOf` / `allOf`) when direct navigation has failed.
+ *
+ * Semantics: for walker purposes (renderer-tester matching), we only need
+ * ONE concrete schema that satisfies the next navigation step. First-match
+ * by structural shape wins, same convention as `initOneOf` uses for seeding.
+ *
+ * @param node     the schema node to search (already dereffed by caller)
+ * @param root     the root schema, for dereferencing branch `$ref`s
+ * @param tryFn    predicate that attempts navigation on a candidate branch
+ *                 and returns the navigated value, or `undefined` if the
+ *                 branch doesn't have what the caller's looking for
+ * @param depth    recursion depth (capped at `COMBINATOR_DEPTH_LIMIT`)
+ */
+export function tryCombinatorBranches<T>(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: Record<string, any> | undefined,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  tryFn: (candidate: Record<string, any>) => T | undefined,
+  depth = 0,
+): T | undefined {
+  if (depth > COMBINATOR_DEPTH_LIMIT) return undefined;
+  if (!node || typeof node !== "object") return undefined;
+
+  const branches = (node.oneOf || node.anyOf || node.allOf) as
+    | Record<string, unknown>[]
+    | undefined;
+  if (!Array.isArray(branches)) return undefined;
+
+  for (const raw of branches) {
+    const branch = deref(raw as Record<string, unknown>, root);
+    if (!branch || typeof branch !== "object") continue;
+
+    const direct = tryFn(branch);
+    if (direct !== undefined) return direct;
+
+    const nested = tryCombinatorBranches(branch, root, tryFn, depth + 1);
+    if (nested !== undefined) return nested;
+  }
+  return undefined;
+}
+
+/**
+ * Recursively dereference every `$ref` in a schema subtree, producing a
+ * concrete schema with no remaining refs. Cycles along any single chain are
+ * handled by leaving the first recursion back into a seen ref as the
+ * unresolved node — matching `resolveRef`'s semantics.
+ *
+ * Intended for use at API boundaries (e.g. `resolveScopeSchema`'s return)
+ * so downstream walkers can operate on self-contained schemas without
+ * needing the original root.
+ */
+export function deepDeref(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  node: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  root: Record<string, any>,
+  seen: Set<string> = new Set(),
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  if (!node || typeof node !== "object") return node;
+  if (Array.isArray(node)) return node.map((n) => deepDeref(n, root, seen));
+
+  const ref = (node as Record<string, unknown>).$ref as string | undefined;
+  if (typeof ref === "string") {
+    if (seen.has(ref)) return node;
+    const resolved = resolvePointer(root, ref);
+    if (!resolved || typeof resolved !== "object") return node;
+    const nextSeen = new Set(seen);
+    nextSeen.add(ref);
+    return deepDeref(resolved, root, nextSeen);
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(node)) {
+    result[key] = deepDeref(value, root, seen);
+  }
+  return result;
+}

package/src/core/resolveScope.ts

@@ -0,0 +1,54 @@
+import { deepDeref, deref, tryCombinatorBranches } from "./refs";
+
+/**
+ * Resolve a JSON Forms scope path to its schema within a root schema.
+ * Handles nested paths like "#/properties/parent/properties/child".
+ *
+ * Follows JSON Schema structure:
+ *   - "properties" segments navigate into object `.properties`
+ *   - "items" segments navigate into array `.items`
+ *   - all other segments index directly into the current object
+ *
+ * Dereferences `$ref` nodes transparently at every step, and falls through
+ * to `oneOf` / `anyOf` / `allOf` branches when a segment can't resolve
+ * directly — picks the first branch that satisfies the navigation. The
+ * returned schema is deep-dereferenced so downstream walkers can operate on
+ * a self-contained sub-schema without needing the original root.
+ */
+export function resolveScopeSchema(
+  scope: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  rootSchema: Record<string, any>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): Record<string, any> | undefined {
+  if (!scope || !rootSchema) return undefined;
+
+  // Remove the leading "#/" and split into segments
+  const path = scope.replace(/^#\/?/, "");
+  if (!path) return deepDeref(rootSchema, rootSchema);
+
+  const segments = path.split("/");
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let current: any = rootSchema;
+
+  for (const segment of segments) {
+    current = deref(current, rootSchema);
+    if (!current || typeof current !== "object") return undefined;
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const navigate = (node: Record<string, any>): unknown => {
+      if (segment === "properties") return node.properties;
+      if (segment === "items") return node.items;
+      return node[segment];
+    };
+
+    let next = navigate(current);
+    if (next === undefined) {
+      next = tryCombinatorBranches(current, rootSchema, navigate);
+    }
+    if (next === undefined) return undefined;
+    current = next;
+  }
+
+  return deepDeref(current, rootSchema);
+}