@jxsuite/schema 3.0.0 → 4.1.0

package/src/guards.ts

@@ -8,9 +8,11 @@
 
 import type {
   JsonObject,
+  JsonPrimitive,
   JsonValue,
   JxClassDef,
   JxElement,
+  JxElementTagName,
   JxEventBinding,
   JxExpressionDef,
   JxFunctionDef,
@@ -25,6 +27,58 @@ import type {
   JxTagExpression,
 } from "../types";
 
+// ─── Primitive guards ───────────────────────────────────────────────────────────
+/*
+ * The one sanctioned home of `typeof`. Lint allows the operator only inside a type predicate
+ * (`deslop/no-runtime-typeof`), so code that has to tell a string from a number calls one of these
+ * and gets a narrowed type back instead of a bare boolean. Prefer a domain guard below when the
+ * value is a Jx shape; these are for the primitives a decoder bottoms out on.
+ */
+
+/** A string primitive. */
+export function isString(value: unknown): value is string {
+  return typeof value === "string";
+}
+
+/** A number primitive, `NaN` and the infinities included (use `Number.isFinite` to refuse them). */
+export function isNumber(value: unknown): value is number {
+  return typeof value === "number";
+}
+
+/** A boolean primitive. */
+export function isBoolean(value: unknown): value is boolean {
+  return typeof value === "boolean";
+}
+
+/** A bigint primitive. */
+export function isBigInt(value: unknown): value is bigint {
+  return typeof value === "bigint";
+}
+
+/** A symbol primitive. */
+export function isSymbol(value: unknown): value is symbol {
+  return typeof value === "symbol";
+}
+
+/**
+ * Anything callable. The predicate admits no arguments (`never[]`), so a value that was `unknown`
+ * still needs its real signature established before it is called; narrowing a declared union
+ * (`string | (() => void)`) yields the union's own function member.
+ */
+export function isFunction(value: unknown): value is (...args: never[]) => void {
+  return typeof value === "function";
+}
+
+/** Any non-null object, arrays included. {@link isJsonObject} is the narrower plain-object check. */
+export function isNonNullObject(value: unknown): value is object {
+  return typeof value === "object" && value !== null;
+}
+
+/** A JSON primitive: string, number, boolean or `null`. */
+export function isJsonPrimitive(value: unknown): value is JsonPrimitive {
+  return value === null || isString(value) || isNumber(value) || isBoolean(value);
+}
+
 // ─── JSON shape guards ──────────────────────────────────────────────────────────
 
 /** A plain object: not null, not an array. The base check for all object-shaped defs. */
@@ -153,11 +207,12 @@ export function isMappedArray(value: unknown): value is JxMappedArray {
  * slot (legacy) or as a member of the children array. Used by renderers and the compiler to decide
  * if a children list needs inline repeater expansion.
  */
-export function childrenContainArray(children?: unknown): boolean {
-  if (isMappedArray(children)) {
-    return true;
-  }
-  return Array.isArray(children) && children.some((c) => isMappedArray(c));
+export function childrenContainArray(
+  children?: JxElement["children"] | JxMutableNode["children"] | JsonValue,
+): boolean {
+  // The legacy bare slot is a one-member list, so both forms take the same test.
+  const members = Array.isArray(children) ? children : [children];
+  return members.some((member) => isMappedArray(member));
 }
 
 /** A .class.json schema-defined class document — `{ $prototype: "Class" }`. */
@@ -200,7 +255,7 @@ export function bodyReturnsValue(body: string): boolean {
  * array to look properties up on, which finds nothing and reports nothing.
  */
 export function isNestedStyle(
-  value: string | number | JxStyle | JxStyle[] | undefined,
+  value: string | number | JxStyle | JxStyle[] | null | undefined,
 ): value is JxStyle {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -248,7 +303,22 @@ export function paramNames(parameters: JxFunctionDef["parameters"]): string[] {
   if (!parameters) {
     return [];
   }
-  return parameters.map((p) => (typeof p === "string" ? p : p.name));
+  return parameters.map((p) => (isString(p) ? p : p.name));
+}
+
+/**
+ * What an element's `tagName` slot holds: one of the two declared forms, nothing, or whatever other
+ * JSON a hand-edited document put there. The readers below take the slot as found, because refusing
+ * a malformed one gracefully is part of their contract.
+ */
+export type TagNameSlot = JxElementTagName | JsonValue | undefined;
+
+/**
+ * Whether an element's `tagName` slot holds a plain name: the other form {@link isTagExpression}
+ * admits.
+ */
+function isPlainTagName(tagName: TagNameSlot): tagName is string {
+  return typeof tagName === "string";
 }
 
 /**
@@ -268,8 +338,13 @@ export function paramNames(parameters: JxFunctionDef["parameters"]): string[] {
  * A `$expression` this refuses is not a tag choice, so it has no candidates and no static tag; the
  * readers fall back to their own "nothing declared" answer (`[]`, `"div"`) instead of throwing.
  */
-export function isTagExpression(tagName: unknown): tagName is { $expression: JxTagExpression } {
-  if (!isJsonObject(tagName) || !isJsonObject(tagName.$expression)) {
+export function isTagExpression(tagName: TagNameSlot): tagName is { $expression: JxTagExpression } {
+  if (
+    typeof tagName !== "object" ||
+    tagName === null ||
+    Array.isArray(tagName) ||
+    !isJsonObject(tagName.$expression)
+  ) {
     return false;
   }
   const expression = tagName.$expression;
@@ -279,7 +354,7 @@ export function isTagExpression(tagName: unknown): tagName is { $expression: JxT
   if (expression.operator === "switch") {
     return (
       isJsonObject(expression.cases) &&
-      Object.values(expression.cases).every((tag) => typeof tag === "string") &&
+      Object.values(expression.cases).every((tag) => isString(tag)) &&
       typeof expression.default === "string"
     );
   }
@@ -296,8 +371,8 @@ export function isTagExpression(tagName: unknown): tagName is { $expression: JxT
  *
  * A plain name yields itself, so every caller can treat the two forms alike.
  */
-export function tagNameCandidates(tagName: unknown): string[] {
-  if (typeof tagName === "string") {
+export function tagNameCandidates(tagName: TagNameSlot): string[] {
+  if (isPlainTagName(tagName)) {
     return [tagName];
   }
   if (!isTagExpression(tagName)) {
@@ -317,8 +392,8 @@ export function tagNameCandidates(tagName: unknown): string[] {
  * says "this is one element whose tag is chosen" without pretending to know which. Rendering the
  * first candidate would have been a quieter lie.
  */
-export function displayTagName(tagName: unknown): string {
-  return typeof tagName === "string" ? tagName : tagNameCandidates(tagName).join("|");
+export function displayTagName(tagName: TagNameSlot): string {
+  return isPlainTagName(tagName) ? tagName : tagNameCandidates(tagName).join("|");
 }
 
 /**

package/src/ijson.ts

@@ -65,7 +65,7 @@ export function findIJsonProblems(text: string): IJsonProblem[] {
           out += String.fromCodePoint(Number.parseInt(text.slice(index + 2, index + 6), 16));
           index += 6;
         } else {
-          out += ESCAPES[next] ?? next;
+          out += ESCAPES.get(next) ?? next;
           index += 2;
         }
         continue;
@@ -151,13 +151,13 @@ export function findIJsonProblems(text: string): IJsonProblem[] {
   return problems;
 }
 
-const ESCAPES: Record<string, string> = {
-  b: "\b",
-  f: "\f",
-  n: "\n",
-  r: "\r",
-  t: "\t",
-};
+const ESCAPES = new Map([
+  ["b", "\b"],
+  ["f", "\f"],
+  ["n", "\n"],
+  ["r", "\r"],
+  ["t", "\t"],
+]);
 
 /** The next non-whitespace character at or after `from`, or "" at the end. */
 function nextMeaningful(text: string, from: number): string {

package/src/json-layout.ts

@@ -49,6 +49,9 @@
  * @docs studio/interface/tabs
  */
 
+import { isFunction, isNumber, isSymbol } from "./guards";
+import type { JsonObject, JxDocumentValue } from "../types";
+
 /** A JSON Pointer (RFC 6901) segment: `~` and `/` are the two characters that need escaping. */
 function segment(key: string): string {
   return key.replaceAll("~", "~0").replaceAll("/", "~1");
@@ -69,6 +72,12 @@ export interface JsonLayout {
   escaped: Map<string, Set<number>>;
 }
 
+/** A JSON string token the scanner consumed: its raw source text and the code units it escaped. */
+interface ScannedString {
+  raw: string;
+  escaped: Set<number>;
+}
+
 /** The print width the repository formats to — `.oxfmtrc.json` leaves oxfmt's default in place. */
 export const JSON_PRINT_WIDTH = 100;
 
@@ -100,7 +109,7 @@ export function deriveJsonLayout(text: string): JsonLayout {
   };
 
   /** Consume the string starting at `i`; return its raw text and the code units it escaped. */
-  const string = (): { raw: string; escaped: Set<number> } => {
+  const string = (): ScannedString => {
     const start = i;
     const escaped = new Set<number>();
     i += 1;
@@ -153,6 +162,7 @@ export function deriveJsonLayout(text: string): JsonLayout {
       }
       layout.inline.set(path, !broken);
       while (i < text.length) {
+        // SAFETY: `string()` consumed one whole JSON string token, so its raw text parses to a string.
         const key = JSON.parse(string().raw) as string;
         space();
         i += 1; // ":"
@@ -193,12 +203,18 @@ export function deriveJsonLayout(text: string): JsonLayout {
   return layout;
 }
 
-/** Parse a JSON file into the document it holds and the layout it was written in. */
-export function parseJsonDocument(text: string): {
-  document: Record<string, unknown>;
+/** A JSON file read for editing: the document it holds and the layout it was written in. */
+export interface ParsedJsonDocument {
+  document: JsonObject;
   layout: JsonLayout;
-} {
-  const document = JSON.parse(text) as Record<string, unknown>;
+}
+
+/** Parse a JSON file into the document it holds and the layout it was written in. */
+export function parseJsonDocument(text: string): ParsedJsonDocument {
+  /* SAFETY: `JSON.parse` without a reviver yields a JSON value, and every file read through here (a
+     Jx document, `project.json`, a surface) is one whose schema requires a top-level object. That
+     contract is what the cast states, as the `Record` it replaced did; the parse does not check it. */
+  const document = JSON.parse(text) as JsonObject;
   return { document, layout: deriveJsonLayout(text) };
 }
 
@@ -263,18 +279,36 @@ export function displayWidth(text: string): number {
   return width;
 }
 
-type Entry = [key: string, value: unknown];
+/**
+ * What {@link serializeJson} writes: a Jx document value, or a container holding one, where a member
+ * may also be something `JSON.stringify` drops from an object (`undefined`, a function, a symbol),
+ * as a live editor document can briefly hold.
+ */
+export type SerializableValue =
+  | JxDocumentValue
+  | undefined
+  | symbol
+  | ((...args: never[]) => void)
+  | SerializableValue[]
+  | SerializableObject;
+
+/** An object {@link serializeJson} writes member by member. */
+export interface SerializableObject {
+  [key: string]: SerializableValue;
+}
+
+type Entry = [key: string, value: SerializableValue];
 
 /** Whether `JSON.stringify` would drop this value from an object. */
-function omitted(value: unknown): boolean {
-  return value === undefined || typeof value === "function" || typeof value === "symbol";
+function omitted(value: SerializableValue): boolean {
+  return value === undefined || isFunction(value) || isSymbol(value);
 }
 
-function entriesOf(value: object): Entry[] {
+function entriesOf(value: SerializableObject): Entry[] {
   return Object.entries(value).filter(([, v]) => !omitted(v));
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
+function isObject(value: SerializableValue): value is SerializableObject {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -283,7 +317,7 @@ function isObject(value: unknown): value is Record<string, unknown> {
  * one key or all arrays with more than one element (Prettier's "concisely printed" rule,
  * inverted).
  */
-function forcedOpen(items: unknown[]): boolean {
+function forcedOpen(items: SerializableValue[]): boolean {
   if (items.length < 2) {
     return false;
   }
@@ -299,13 +333,16 @@ function forcedOpen(items: unknown[]): boolean {
 }
 
 /** Two or more numbers: the formatter fills lines with them rather than stacking one per line. */
-function isNumberRun(items: unknown[]): boolean {
-  return items.length > 1 && items.every((item) => typeof item === "number");
+function isNumberRun(items: SerializableValue[]): boolean {
+  return items.length > 1 && items.every((item) => isNumber(item));
 }
 
-/** A scalar, as `JSON.stringify` spells it — with the code units the source escaped, escaped. */
-function scalar(value: unknown, escaped?: Set<number>): string {
-  const text = JSON.stringify(value) ?? "null";
+/**
+ * A scalar, as `JSON.stringify` spells it — with the code units the source escaped, escaped. What
+ * `JSON.stringify` cannot spell (it answers `undefined`) is written `null`, as it is in an array.
+ */
+function scalar(value: SerializableValue, escaped?: Set<number>): string {
+  const text = omitted(value) ? "null" : JSON.stringify(value);
   return escaped === undefined
     ? text
     : text.replaceAll(/[\u0080-\uFFFF]/g, (c) => {
@@ -323,7 +360,7 @@ function scalar(value: unknown, escaped?: Set<number>): string {
  * result ends with exactly one newline, as every formatted file does.
  */
 export function serializeJson(
-  value: unknown,
+  value: SerializableValue,
   layout: JsonLayout | null,
   printWidth = JSON_PRINT_WIDTH,
 ): string {
@@ -342,7 +379,7 @@ export function serializeJson(
    * blank line, or an array the formatter always breaks — so that the break propagates outward the
    * way the formatter's does.
    */
-  const flat = (v: unknown, path: string, inherited: boolean): string | null => {
+  const flat = (v: SerializableValue, path: string, inherited: boolean): string | null => {
     if (Array.isArray(v)) {
       if (v.length === 0) {
         return "[]";
@@ -396,17 +433,19 @@ export function serializeJson(
    * parent adds, which counts toward the width the formatter measures).
    */
   const render = (
-    v: unknown,
+    v: SerializableValue,
     path: string,
     indent: number,
     column: number,
     inherited: boolean,
     trailing: number,
   ): string => {
+    if (!Array.isArray(v) && !isObject(v)) {
+      // A scalar is never broken, however long: only a container has a second layout to fall to.
+      return scalar(v, escaped.get(path));
+    }
     const line = flat(v, path, inherited);
-    // A scalar is never broken, however long: only a container has a second layout to fall to.
-    const container = Array.isArray(v) || isObject(v);
-    if (line !== null && (!container || column + displayWidth(line) + trailing <= printWidth)) {
+    if (line !== null && column + displayWidth(line) + trailing <= printWidth) {
       return line;
     }
     const pad = " ".repeat(indent + 2);
@@ -424,7 +463,7 @@ export function serializeJson(
       });
       return `[\n${stack(items)}${close}]`;
     }
-    const entries = entriesOf(v as object);
+    const entries = entriesOf(v);
     const own = soft(path, inherited);
     const members = entries.map(([key, item], index) => {
       const member = `${path}/${segment(key)}`;
@@ -447,7 +486,7 @@ export function serializeJson(
  * {@link displayWidth}: a line of numbers and spaces is ASCII, so the two agree.
  */
 function fill(
-  numbers: unknown[],
+  numbers: SerializableValue[],
   pad: string,
   printWidth: number,
   blank: (index: number) => boolean,

package/src/locale.ts

@@ -17,8 +17,9 @@
  * @docs framework/site/i18n
  */
 
-/* Type-only, so this module still imports nothing at runtime and a browser host can load it. */
-import type { ProjectConfig } from "../types.ts";
+/* The guards module is pure predicates with no node imports, so a browser host can still load this. */
+import type { JsonValue, ProjectConfig } from "../types.ts";
+import { isNonNullObject, isString } from "./guards";
 
 /**
  * Scripts written right to left (ISO 15924, per UAX #9).
@@ -99,11 +100,11 @@ export const LANGUAGE_TAG_PATTERN = "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$";
  * becomes `en-US`, which matters because a tag is compared as a string in a route table and in a
  * `hreflang` attribute.
  *
- * @param {unknown} tag
+ * @param {JsonValue | undefined} tag - Any configured value; non-strings are not tags
  * @returns {string | null}
  */
-export function canonicalizeLocale(tag: unknown): string | null {
-  if (typeof tag !== "string" || tag.trim() === "") {
+export function canonicalizeLocale(tag: JsonValue | undefined): string | null {
+  if (!isString(tag) || tag.trim() === "") {
     return null;
   }
   try {
@@ -114,7 +115,7 @@ export function canonicalizeLocale(tag: unknown): string | null {
 }
 
 /** True when the tag is a well-formed BCP 47 language tag. */
-export function isWellFormedLocale(tag: unknown): boolean {
+export function isWellFormedLocale(tag: JsonValue | undefined): boolean {
   return canonicalizeLocale(tag) !== null;
 }
 
@@ -125,10 +126,10 @@ export function isWellFormedLocale(tag: unknown): boolean {
  * validation has already happened at config load, and guessing left-to-right is what every browser
  * does with an unusable `lang`.
  *
- * @param {unknown} tag
+ * @param {JsonValue | undefined} tag - Any configured value; non-strings are not tags
  * @returns {TextDirection}
  */
-export function localeDirection(tag: unknown): TextDirection {
+export function localeDirection(tag: JsonValue | undefined): TextDirection {
   const canonical = canonicalizeLocale(tag);
   if (canonical === null) {
     return "ltr";
@@ -160,13 +161,13 @@ export function localeDirection(tag: unknown): TextDirection {
  * `Intl.Locale` here, so neither the constructor nor `of` can reject it, and a guard would be an
  * untestable branch pretending otherwise.
  *
- * @param {unknown} tag
+ * @param {JsonValue | undefined} tag - Any configured value; non-strings are not tags
  * @returns {string}
  */
-export function localeLabel(tag: unknown): string {
+export function localeLabel(tag: JsonValue | undefined): string {
   const canonical = canonicalizeLocale(tag);
   if (canonical === null) {
-    return typeof tag === "string" ? tag : "";
+    return isString(tag) ? tag : "";
   }
   return new Intl.DisplayNames([canonical], { type: "language" }).of(canonical) ?? canonical;
 }
@@ -182,6 +183,12 @@ export interface ResolvedI18n {
   routing: LocaleRouting;
 }
 
+/** What {@link resolveI18n} answers: the resolved block, and every problem found on the way. */
+export interface I18nResolution {
+  i18n: ResolvedI18n | null;
+  errors: string[];
+}
+
 const DEFAULT_ROUTING: LocaleRouting = "prefix-except-default";
 
 /**
@@ -192,15 +199,13 @@ const DEFAULT_ROUTING: LocaleRouting = "prefix-except-default";
  * every page claims a language that does not exist, and nothing downstream can tell.
  *
  * @param {ProjectConfig} projectConfig
- * @returns {{ i18n: ResolvedI18n | null; errors: string[] }}
+ * @returns {I18nResolution}
  */
-export function resolveI18n(projectConfig: ProjectConfig): {
-  i18n: ResolvedI18n | null;
-  errors: string[];
-} {
+export function resolveI18n(projectConfig: ProjectConfig): I18nResolution {
   const raw = projectConfig.i18n;
   const errors: string[] = [];
-  if (!raw || typeof raw !== "object") {
+  // Checked rather than trusted: the block comes straight from project.json.
+  if (!isNonNullObject(raw)) {
     return { errors, i18n: null };
   }
 
@@ -423,7 +428,7 @@ function localeSlot(segments: readonly string[]): number {
 }
 
 /** The primary language subtag of a tag: `en` for `en-GB`, `zh` for `zh-Hant-TW`. */
-export function primaryLanguage(tag: unknown): string | null {
+export function primaryLanguage(tag: JsonValue | undefined): string | null {
   const canonical = canonicalizeLocale(tag);
   return canonical === null ? null : (canonical.split("-")[0] ?? null);
 }

package/src/media-type.ts

@@ -15,6 +15,9 @@
  * @docs extending/extensions/formats
  */
 
+import type { JsonValue } from "../types";
+import { isString } from "./guards";
+
 /** RFC 6838 §4.2: the first character, then up to 126 more from the restricted set. */
 const RESTRICTED_NAME = /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$/;
 
@@ -37,11 +40,11 @@ export interface MediaType {
 /**
  * Parse a media type, or return null when it does not match the grammar.
  *
- * @param {unknown} value
+ * @param {JsonValue | undefined} value - Any configured value; non-strings are not media types
  * @returns {MediaType | null}
  */
-export function parseMediaType(value: unknown): MediaType | null {
-  if (typeof value !== "string") {
+export function parseMediaType(value: JsonValue | undefined): MediaType | null {
+  if (!isString(value)) {
     return null;
   }
   const [essence, ...paramParts] = value.split(";");
@@ -113,11 +116,11 @@ export function formatMediaType(media: MediaType): string {
  * Separate from {@link parseMediaType} because a caller validating configuration needs to say what
  * is wrong, and a caller reading a type only needs to know whether it could.
  *
- * @param {unknown} value
+ * @param {JsonValue | undefined} value - Any configured value; non-strings are not media types
  * @returns {string | null}
  */
-export function mediaTypeProblem(value: unknown): string | null {
-  if (typeof value !== "string" || value.trim() === "") {
+export function mediaTypeProblem(value: JsonValue | undefined): string | null {
+  if (!isString(value) || value.trim() === "") {
     return "expected a media type string";
   }
   if (!value.includes("/")) {
@@ -137,10 +140,10 @@ export function mediaTypeProblem(value: unknown): string | null {
  * moment a format declared the `variant` parameter RFC 7763 defines, so the distinction belongs
  * here rather than in each caller's `split`.
  *
- * @param {unknown} value
+ * @param {JsonValue | undefined} value - Any configured value; non-strings are not media types
  * @returns {string | null} Null when the value is not a media type at all
  */
-export function mediaTypeEssence(value: unknown): string | null {
+export function mediaTypeEssence(value: JsonValue | undefined): string | null {
   const media = parseMediaType(value);
   if (media === null) {
     return null;
@@ -151,7 +154,7 @@ export function mediaTypeEssence(value: unknown): string | null {
 }
 
 /** True when the type names an unregistered format under the `x.` or deprecated `x-` convention. */
-export function isUnregisteredMediaType(value: unknown): boolean {
+export function isUnregisteredMediaType(value: JsonValue | undefined): boolean {
   const media = parseMediaType(value);
   return media !== null && (media.tree === "x" || media.subtype.startsWith("x-"));
 }
@@ -191,12 +194,22 @@ export const YAML_MEDIA_TYPE = "application/yaml";
  * text and a browser that guesses the encoding of a UTF-8 document guesses wrong for exactly the
  * non-Latin content the rest of this repo works to support.
  */
-export const MEDIA_TYPE_BY_EXTENSION: Readonly<Record<string, string>> = {
+export const MEDIA_TYPE_BY_EXTENSION = {
   ".markdown": `${MARKDOWN_MEDIA_TYPE}; charset=utf-8`,
   ".md": `${MARKDOWN_MEDIA_TYPE}; charset=utf-8`,
   ".yaml": `${YAML_MEDIA_TYPE}; charset=utf-8`,
   ".yml": `${YAML_MEDIA_TYPE}; charset=utf-8`,
-};
+} as const satisfies Readonly<Record<string, string>>;
+
+/**
+ * True when {@link MEDIA_TYPE_BY_EXTENSION} corrects this extension. Every key starts with a dot,
+ * so no `Object.prototype` member can answer for one.
+ */
+function isOverriddenExtension(
+  extension: string,
+): extension is keyof typeof MEDIA_TYPE_BY_EXTENSION {
+  return extension in MEDIA_TYPE_BY_EXTENSION;
+}
 
 /**
  * The media type for a path, or null to leave the host's own answer alone.
@@ -213,5 +226,6 @@ export function mediaTypeForPath(path: string): string | null {
   if (dot <= path.lastIndexOf("/") || dot <= path.lastIndexOf("\\")) {
     return null;
   }
-  return MEDIA_TYPE_BY_EXTENSION[path.slice(dot).toLowerCase()] ?? null;
+  const extension = path.slice(dot).toLowerCase();
+  return isOverriddenExtension(extension) ? MEDIA_TYPE_BY_EXTENSION[extension] : null;
 }