@jxsuite/schema 5.5.0 → 6.0.0

package/src/jxn/schema-types.ts

@@ -0,0 +1,299 @@
+/**
+ * The type a JSON Schema says, as TypeScript writes it (`spec.md` §5.2, §23.3).
+ *
+ * A document's `$defs` holds its type definitions, and a `state` entry names one or carries a
+ * schema of its own (§5.3). Both readers of a document's types ask here, through `state-types.ts`,
+ * so the two say the same thing about the same schema.
+ *
+ * **A type is written as parts**, because two kinds of name in one are names the author wrote: a
+ * property of an object, and the definition a `$ref` ends in. The whole-document reader maps each
+ * to its token, which is what lets an editor rename one and find where it was declared, and the
+ * reader of one body joins them.
+ *
+ * **What a schema does not say is `any`, and never an error**: a keyword that is not read here, a
+ * `$ref` that leaves the document, a definition whose name is no identifier. A schema with no
+ * `type` constrains nothing, as JSON Schema has it, so `properties` alone does not make an object.
+ *
+ * @docs framework/concepts/type-checking
+ */
+import { isBoolean, isJsonObject, isNumber, isString } from "../guards";
+import type { JsonObject, JsonValue } from "../../types";
+
+/** Whether a key can be written as a bare property name. */
+export const IDENTIFIER = /^[A-Za-z_$][\w$]*$/u;
+
+/** The namespace a document's definitions are written in. */
+export const DEFINITIONS = "$defs";
+
+/** A reference to one definition of the document it is written in. */
+const LOCAL_DEFINITION = /^#\/\$defs\/([^/]+)$/u;
+
+/** A property name as TypeScript writes it. */
+export function propertyName(key: string): string {
+  return IDENTIFIER.test(key) ? key : JSON.stringify(key);
+}
+
+/** A JSON Pointer one step down. */
+export function pointerInto(pointer: string, key: string | number): string {
+  return `${pointer}/${String(key).replaceAll("~", "~0").replaceAll("/", "~1")}`;
+}
+
+/** A name in a type that the document wrote. */
+export interface WrittenName {
+  /**
+   * Which name it is: a `member` is the name of the property or definition at `pointer`, a `ref` is
+   * the definition that the `$ref` at `pointer` ends in, and a `text` is no name but a whole type,
+   * the TypeScript the string at `pointer` holds.
+   */
+  kind: "member" | "ref" | "text";
+  /** The name as the document holds it. */
+  name: string;
+  pointer: string;
+  /** The name as TypeScript writes it here. */
+  written: string;
+}
+
+/** One stretch of a type: text the author did not write, or a name they did. */
+export type TypePart = string | WrittenName;
+
+/** Where a schema is, and what its document gives it. */
+export interface SchemaSite {
+  /** Whether the document has `$defs`, without which a `$ref` into it names nothing. */
+  defs: boolean;
+  /** The schema's JSON Pointer. */
+  pointer: string;
+}
+
+/** What joins a type's members at its outermost level, which decides where it needs brackets. */
+type Joins = "&" | "|" | null;
+
+/** A type being written. */
+interface Typed {
+  joins: Joins;
+  parts: TypePart[];
+}
+
+/** A type as text. */
+export function written(parts: readonly TypePart[]): string {
+  return parts.map((part) => (isString(part) ? part : part.written)).join("");
+}
+
+/** A type that is one word. */
+function plain(text: string): Typed {
+  return { joins: null, parts: [text] };
+}
+
+/** A type as a member of another, in brackets where it would otherwise be read apart. */
+function within(typed: Typed, around: "&" | "|" | "[]"): TypePart[] {
+  // `&` binds tighter than `|`, so only a union inside an intersection, or either in a list, needs them.
+  const apart =
+    typed.joins !== null && (around === "[]" || (around === "&" && typed.joins === "|"));
+  return apart ? ["(", ...typed.parts, ")"] : typed.parts;
+}
+
+/**
+ * Several types as one. A member that is only words is said once. One that holds a name the
+ * document wrote is said each time it is written, because each is a place a rename has to reach.
+ */
+function joined(members: readonly Typed[], by: "&" | "|"): Typed {
+  const seen = new Set<string>();
+  const kept: Typed[] = [];
+  for (const member of members) {
+    const text = written(member.parts);
+    if (!member.parts.every(isString) || !seen.has(text)) {
+      kept.push(member);
+      seen.add(text);
+    }
+  }
+  const [only = plain("any"), ...rest] = kept;
+  const parts = [...within(only, by)];
+  for (const member of rest) {
+    parts.push(` ${by} `, ...within(member, by));
+  }
+  return rest.length > 0 ? { joins: by, parts } : only;
+}
+
+/** The type of a list of values that are each a type themselves, or null when one is not. */
+function literals(values: JsonValue | undefined): Typed | null {
+  if (!Array.isArray(values) || values.length === 0) {
+    return null;
+  }
+  const members: Typed[] = [];
+  for (const value of values) {
+    if (!(isString(value) || isNumber(value) || isBoolean(value) || value === null)) {
+      return null;
+    }
+    members.push(plain(JSON.stringify(value)));
+  }
+  return joined(members, "|");
+}
+
+/** The definition a `$ref` names, when the schema is one. */
+function referenced(schema: JsonObject, site: SchemaSite): Typed | null {
+  if (!isString(schema.$ref)) {
+    return null;
+  }
+  const name = LOCAL_DEFINITION.exec(schema.$ref)?.[1];
+  if (!site.defs || name === undefined || !IDENTIFIER.test(name)) {
+    return plain("any");
+  }
+  const { pointer } = site;
+  return {
+    joins: null,
+    parts: [`${DEFINITIONS}.`, { kind: "ref", name, pointer, written: name }],
+  };
+}
+
+/** The type `anyOf`, `oneOf` or `allOf` says, when the schema has it. */
+function combined(
+  schema: JsonObject,
+  site: SchemaSite,
+  keyword: "allOf" | "anyOf" | "oneOf",
+): Typed | null {
+  const members = schema[keyword];
+  if (!Array.isArray(members) || members.length === 0) {
+    return null;
+  }
+  const at = pointerInto(site.pointer, keyword);
+  const typed = members.map((member, index) =>
+    typeOf(member, { ...site, pointer: pointerInto(at, index) }),
+  );
+  return joined(typed, keyword === "allOf" ? "&" : "|");
+}
+
+/** An object: each property it names, optional unless `required`, and whether it holds others. */
+function objectType(schema: JsonObject, site: SchemaSite): Typed {
+  const properties = isJsonObject(schema.properties) ? schema.properties : {};
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const others = schema.additionalProperties;
+  const at = pointerInto(site.pointer, "properties");
+  const parts: TypePart[] = ["{"];
+  for (const [key, member] of Object.entries(properties)) {
+    const pointer = pointerInto(at, key);
+    parts.push(
+      " ",
+      { kind: "member", name: key, pointer, written: propertyName(key) },
+      required.has(key) ? ": " : "?: ",
+      ...typeOf(member, { ...site, pointer }).parts,
+      ";",
+    );
+  }
+  const named = parts.length > 1;
+  if (!named) {
+    // An object that names no property is a map, of what `additionalProperties` says when it does.
+    const held = typeOf(others, {
+      ...site,
+      pointer: pointerInto(site.pointer, "additionalProperties"),
+    });
+    parts.push(" [key: string]: ", ...held.parts, ";");
+  } else if (others === true || isJsonObject(others)) {
+    // Beside named properties an index must admit every one of them, and only `any` always does.
+    parts.push(" [key: string]: any;");
+  }
+  return { joins: null, parts: [...parts, " }"] };
+}
+
+/** A list of what `items` says. */
+function listType(schema: JsonObject, site: SchemaSite): Typed {
+  if (!isJsonObject(schema.items)) {
+    return plain("any[]");
+  }
+  const item = typeOf(schema.items, { ...site, pointer: pointerInto(site.pointer, "items") });
+  return { joins: null, parts: [...within(item, "[]"), "[]"] };
+}
+
+/** The type one `type` keyword names. */
+function keywordType(keyword: JsonValue | undefined, schema: JsonObject, site: SchemaSite): Typed {
+  switch (keyword) {
+    case "array": {
+      return listType(schema, site);
+    }
+    case "boolean": {
+      return plain("boolean");
+    }
+    case "integer":
+    case "number": {
+      return plain("number");
+    }
+    case "null": {
+      return plain("null");
+    }
+    case "object": {
+      return objectType(schema, site);
+    }
+    case "string": {
+      return plain("string");
+    }
+    default: {
+      return plain("any");
+    }
+  }
+}
+
+/** The type a schema says. */
+function typeOf(schema: JsonValue | undefined, site: SchemaSite): Typed {
+  if (!isJsonObject(schema)) {
+    return plain("any");
+  }
+  const { type } = schema;
+  const narrowed =
+    referenced(schema, site) ??
+    literals("const" in schema ? [schema.const ?? null] : schema.enum) ??
+    combined(schema, site, "anyOf") ??
+    combined(schema, site, "oneOf") ??
+    combined(schema, site, "allOf");
+  if (narrowed) {
+    return narrowed;
+  }
+  return Array.isArray(type)
+    ? joined(
+        type.map((keyword) => keywordType(keyword, schema, site)),
+        "|",
+      )
+    : keywordType(type, schema, site);
+}
+
+/**
+ * The type a JSON Schema says.
+ *
+ * @param schema The schema.
+ * @param site Where it is, and whether its document has `$defs`.
+ * @returns The type, in parts.
+ */
+export function schemaParts(schema: JsonValue | undefined, site: SchemaSite): TypePart[] {
+  return typeOf(schema, site).parts;
+}
+
+/** The definitions a document holds, or null when it has no `$defs`. */
+export function definitionsOf(doc: JsonValue | undefined): JsonObject | null {
+  return isJsonObject(doc) && isJsonObject(doc.$defs) ? doc.$defs : null;
+}
+
+/**
+ * The namespace that holds a document's definitions, each a type under its own name.
+ *
+ * A namespace, because a definition is then named in every message and every hover as the author
+ * named it (`$defs.TodoItem`), which an interface's member is not. One whose name is not an
+ * identifier cannot be declared in one and is left out, and a `$ref` to it is `any`.
+ *
+ * @param defs The document's `$defs`.
+ * @param exported Whether the namespace is exported, as it is from a document's module.
+ * @returns The declaration, in parts, with no line break after it.
+ */
+export function definitionParts(defs: JsonObject, exported: boolean): TypePart[] {
+  const parts: TypePart[] = [`${exported ? "export " : ""}namespace ${DEFINITIONS} {\n`];
+  const site: SchemaSite = { defs: true, pointer: `/${DEFINITIONS}` };
+  for (const [name, schema] of Object.entries(defs)) {
+    if (IDENTIFIER.test(name)) {
+      const pointer = pointerInto(site.pointer, name);
+      parts.push(
+        "  export type ",
+        { kind: "member", name, pointer, written: name },
+        " = ",
+        ...schemaParts(schema, { ...site, pointer }),
+        ";\n",
+      );
+    }
+  }
+  return [...parts, "}"];
+}

package/src/jxn/schema-walk.ts

@@ -0,0 +1,221 @@
+/**
+ * A JSON Schema, read as far as a completion needs (`spec.md` §22.6).
+ *
+ * Nothing here validates. A completion asks a schema three things: what members an object may have,
+ * what the schema of one of them is, and what values a schema names. Each is answered over every
+ * schema the one asked about is made of, because a document's schema says most of what it says
+ * through `$ref`, `allOf` and `oneOf`.
+ *
+ * A schema travels with the document it was read from, since that is what its `$ref`s point into. A
+ * project's composed schema keeps the core under `#/$defs/v1`, so nothing here knows a definition
+ * by its name.
+ */
+import { isJsonObject, isJsonPrimitive, isString } from "../guards.ts";
+import type { JsonObject, JsonPrimitive, JsonValue } from "../../types.ts";
+
+/** A schema, and the document its `$ref`s point into. */
+export interface RootedSchema {
+  root: JsonObject;
+  schema: JsonObject;
+}
+
+/** The keywords whose every member says something of the same value. */
+const COMBINERS = ["allOf", "anyOf", "oneOf"];
+
+/** The keywords whose one schema does. */
+const BRANCHES = ["then", "else"];
+
+/** What a `$ref` into its own document points at, or null. */
+function resolve(root: JsonObject, ref: string): JsonObject | null {
+  if (!ref.startsWith("#")) {
+    return null;
+  }
+  let at: JsonValue | undefined = root;
+  for (const part of ref.split("/").slice(1)) {
+    const key = part.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (Array.isArray(at)) {
+      at = at[Number(key)];
+    } else if (isJsonObject(at)) {
+      at = at[key];
+    } else {
+      return null;
+    }
+  }
+  return isJsonObject(at) ? at : null;
+}
+
+/**
+ * Every schema that says something of the value this one describes: itself, what it refers to, and
+ * the members of its `allOf`, `anyOf`, `oneOf`, `then` and `else`, each read the same way.
+ *
+ * @param rooted The schema.
+ * @returns Each once, the schema itself first. A schema that refers to itself ends there.
+ */
+export function leavesOf(rooted: RootedSchema): JsonObject[] {
+  const seen = new Set<JsonObject>();
+  const visit = (one: JsonValue | undefined): void => {
+    if (!isJsonObject(one) || seen.has(one)) {
+      return;
+    }
+    seen.add(one);
+    if (isString(one.$ref)) {
+      visit(resolve(rooted.root, one.$ref));
+    }
+    for (const key of COMBINERS) {
+      const members = one[key];
+      if (Array.isArray(members)) {
+        for (const member of members) {
+          visit(member);
+        }
+      }
+    }
+    for (const key of BRANCHES) {
+      visit(one[key]);
+    }
+  };
+  visit(rooted.schema);
+  return [...seen];
+}
+
+/** Several schemas of one value as one schema, or null where there is none. */
+function joined(root: JsonObject, schemas: JsonObject[]): RootedSchema | null {
+  const [first] = schemas;
+  if (!first) {
+    return null;
+  }
+  return { root, schema: schemas.length === 1 ? first : { anyOf: schemas } };
+}
+
+/**
+ * The members an object of this schema is declared to have.
+ *
+ * @param rooted The schema.
+ * @returns Each name once with its schema, in the order the schema declares them.
+ */
+export function namesOf(rooted: RootedSchema): Map<string, RootedSchema> {
+  const names = new Map<string, RootedSchema>();
+  for (const leaf of leavesOf(rooted)) {
+    if (isJsonObject(leaf.properties)) {
+      for (const [name, schema] of Object.entries(leaf.properties)) {
+        if (!names.has(name) && isJsonObject(schema)) {
+          names.set(name, { root: rooted.root, schema });
+        }
+      }
+    }
+  }
+  return names;
+}
+
+/** The schemas a leaf gives a member it does not declare by name. */
+function undeclared(leaf: JsonObject, key: string): JsonObject[] {
+  const found: JsonObject[] = [];
+  if (isJsonObject(leaf.patternProperties)) {
+    for (const [pattern, schema] of Object.entries(leaf.patternProperties)) {
+      if (isJsonObject(schema) && matches(pattern, key)) {
+        found.push(schema);
+      }
+    }
+  }
+  if (isJsonObject(leaf.additionalProperties)) {
+    found.push(leaf.additionalProperties);
+  }
+  return found;
+}
+
+/** Whether a `patternProperties` pattern matches a name. One that is no pattern matches nothing. */
+function matches(pattern: string, key: string): boolean {
+  try {
+    return new RegExp(pattern, "u").test(key);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The schema of one member of an object of this schema.
+ *
+ * @param rooted The object's schema.
+ * @param key The member's name.
+ * @returns Its entry in `properties` wherever one is declared, and otherwise every
+ *   `patternProperties` entry the name matches together with `additionalProperties`. Null where the
+ *   schema says nothing of it.
+ */
+export function memberOf(rooted: RootedSchema, key: string): RootedSchema | null {
+  const leaves = leavesOf(rooted);
+  const declared = leaves.flatMap((leaf) => {
+    const schema = isJsonObject(leaf.properties) ? leaf.properties[key] : undefined;
+    return isJsonObject(schema) ? [schema] : [];
+  });
+  return joined(
+    rooted.root,
+    declared.length > 0 ? declared : leaves.flatMap((leaf) => undeclared(leaf, key)),
+  );
+}
+
+/**
+ * The schema of an item of a list of this schema.
+ *
+ * @param rooted The list's schema.
+ * @returns Its `items`, or null where the schema is of no list.
+ */
+export function itemsOf(rooted: RootedSchema): RootedSchema | null {
+  return joined(
+    rooted.root,
+    leavesOf(rooted).flatMap((leaf) => (isJsonObject(leaf.items) ? [leaf.items] : [])),
+  );
+}
+
+/** Whether a schema's `type` is, or includes, the one named. */
+function hasType(leaf: JsonObject, type: string): boolean {
+  return Array.isArray(leaf.type) ? leaf.type.includes(type) : leaf.type === type;
+}
+
+/**
+ * The values this schema names.
+ *
+ * @param rooted The schema.
+ * @returns Its `const`, its `enum`, both booleans where it is any boolean, and its `examples`, each
+ *   once. Only what one token can hold: an object or a list among them is left out.
+ */
+export function valuesOf(rooted: RootedSchema): JsonPrimitive[] {
+  const values = new Set<JsonPrimitive>();
+  const add = (value: JsonValue | undefined): void => {
+    if (isJsonPrimitive(value)) {
+      values.add(value);
+    }
+  };
+  const leaves = leavesOf(rooted);
+  for (const leaf of leaves) {
+    add(leaf.const);
+    for (const value of Array.isArray(leaf.enum) ? leaf.enum : []) {
+      add(value);
+    }
+    // A boolean held to one value by `const` is not both.
+    if (hasType(leaf, "boolean") && leaf.const === undefined && leaf.enum === undefined) {
+      values.add(true);
+      values.add(false);
+    }
+  }
+  // After everything the schema requires, since an example is only a suggestion.
+  for (const leaf of leaves) {
+    for (const value of Array.isArray(leaf.examples) ? leaf.examples : []) {
+      add(value);
+    }
+  }
+  return [...values];
+}
+
+/**
+ * What this schema says it is for.
+ *
+ * @param rooted The schema.
+ * @returns The first `description` among the schemas it is made of, or null.
+ */
+export function descriptionOf(rooted: RootedSchema): string | null {
+  for (const leaf of leavesOf(rooted)) {
+    if (isString(leaf.description)) {
+      return leaf.description;
+    }
+  }
+  return null;
+}

package/src/jxn/serialize.ts

@@ -204,6 +204,73 @@ function writeFunction(key: string, fn: JsonObject, indent: string, where: strin
   return [parts.join(" ")];
 }
 
+/**
+ * Whether a Function is an export of the document's own script (`spec.md` §23.2) with the
+ * `(export)` spelling. One with a body or parameters is a `(fn)` row, as any Function is.
+ */
+function isExportRow(value: JsonValue | undefined): value is JsonObject {
+  if (
+    !isObject(value) ||
+    value.$prototype !== "Function" ||
+    value.$src !== "#client" ||
+    !isString(value.$export) ||
+    Object.hasOwn(value, "body") ||
+    Object.hasOwn(value, "parameters")
+  ) {
+    return false;
+  }
+  return Object.values(value).every((entry) => scalar(entry, "", "") !== null);
+}
+
+/** An `(export)` node. The export is the node's name unless it is written. */
+function writeExport(key: string, fn: JsonObject, indent: string, where: string): string[] {
+  const { $export, $prototype: _prototype, $src: _src, ...rest } = fn;
+  const parts = [`${indent}(export)${writeName(key, where)}`];
+  if ($export !== key) {
+    parts.push(`$export=${scalar($export, indent, down(where, "$export"))}`);
+  }
+  for (const [name, value] of Object.entries(rest)) {
+    parts.push(`${writeName(name, where)}=${scalar(value, indent, down(where, name))}`);
+  }
+  return [parts.join(" ")];
+}
+
+/** What a `(server)` row may hold, and nothing else: anything more is a plain block. */
+const SERVER_ROW_KEYS = new Set(["$export", "$src", "arguments", "timing"]);
+
+/**
+ * Whether an entry is a function of the document's own server script with the `(server)` spelling:
+ * exported under the entry's own name, with arguments that each fit in a value.
+ */
+function isServerRow(key: string, value: JsonValue | undefined): value is JsonObject {
+  if (
+    !isObject(value) ||
+    value.timing !== "server" ||
+    value.$src !== "#server" ||
+    value.$export !== key ||
+    !Object.keys(value).every((entry) => SERVER_ROW_KEYS.has(entry))
+  ) {
+    return false;
+  }
+  const { arguments: args } = value;
+  if (args === undefined) {
+    return true;
+  }
+  const values = isObject(args) ? Object.values(args) : [];
+  return values.length > 0 && values.every((entry) => scalar(entry, "", "") !== null);
+}
+
+/** A `(server)` node, with its arguments as names. */
+function writeServer(key: string, entry: JsonObject, indent: string, where: string): string[] {
+  const parts = [`${indent}(server)${writeName(key, where)}`];
+  const at = down(where, "arguments");
+  const args = isObject(entry.arguments) ? entry.arguments : {};
+  for (const [name, value] of Object.entries(args)) {
+    parts.push(`${writeName(name, at)}=${scalar(value, indent, down(at, name))}`);
+  }
+  return [parts.join(" ")];
+}
+
 /** A JSON block. */
 export function writeValue(key: string, value: JsonValue, indent: string, where: string): string[] {
   const name = writeName(key, where);
@@ -212,6 +279,12 @@ export function writeValue(key: string, value: JsonValue, indent: string, where:
   if (single !== null) {
     return [`${head} ${single}`];
   }
+  if (isExportRow(value)) {
+    return writeExport(key, value, indent, where);
+  }
+  if (isServerRow(key, value)) {
+    return writeServer(key, value, indent, where);
+  }
   if (isFunctionRow(value)) {
     return writeFunction(key, value, indent, where);
   }
@@ -358,11 +431,40 @@ function isPlainAttribute(key: string, spelled: string | null): spelled is strin
   );
 }
 
-/** An element. */
-function writeElement(element: JsonObject, indent: string, where: string): string[] {
+/**
+ * A document's `$script` as the `script` nodes of its root element (`spec.md` §23.2), or null when
+ * it holds anything a `script` node cannot say and so has to be a plain `$script` block.
+ */
+function writeScripts(scripts: JsonValue, indent: string): string[] | null {
+  const sides = isObject(scripts) ? Object.entries(scripts) : [];
+  const lines: string[] = [];
+  for (const [side, text] of sides) {
+    if ((side !== "client" && side !== "server") || !isString(text)) {
+      return null;
+    }
+    const timing = side === "server" ? "timing=server " : "";
+    lines.push(`${indent}script ${timing}${writeString(text, indent, `/$script/${side}`)}`);
+  }
+  return lines.length > 0 ? lines : null;
+}
+
+/**
+ * An element.
+ *
+ * @param element The element.
+ * @param indent Where it sits.
+ * @param where Its JSON Pointer.
+ * @param scripts The document's `script` nodes, which only its root element holds.
+ */
+function writeElement(
+  element: JsonObject,
+  indent: string,
+  where: string,
+  scripts: string[] = [],
+): string[] {
   const parts = [writeHead(element, indent, where)];
   const inner = indent + INDENT;
-  const blocks: string[] = [];
+  const blocks: string[] = [...scripts];
   const leftoverAttributes: JsonObject = {};
   let textPositional: string | null = null;
   for (const [key, value] of Object.entries(element)) {
@@ -519,8 +621,14 @@ function writeCanonical(document: JxDocument): string {
   const source = document;
   const lines = ["/- kdl-version 2"];
   const root: JsonObject = {};
+  const hasRoot = Object.keys(source).some((key) => !key.startsWith("$"));
+  let scripts: string[] = [];
   for (const [key, value] of Object.entries(source)) {
-    if (key === "$head" && Array.isArray(value)) {
+    // A script is written inside the root element, so a document with none keeps the plain block.
+    const written = key === "$script" && hasRoot ? writeScripts(value, INDENT) : null;
+    if (written) {
+      scripts = written;
+    } else if (key === "$head" && Array.isArray(value)) {
       lines.push(...writeHeadBlock(value, INDENT));
     } else if (key === "$head") {
       // Not a list, so not rows. The annotation is what stops it being read as them.
@@ -532,7 +640,7 @@ function writeCanonical(document: JxDocument): string {
     }
   }
   if (Object.keys(root).length > 0) {
-    lines.push("", ...writeElement(root, "", ""));
+    lines.push("", ...writeElement(root, "", "", scripts));
   }
   return `${lines.join("\n")}\n`;
 }