@jxsuite/schema 0.28.2 → 0.28.3

package/src/format-registry.ts

@@ -66,11 +66,11 @@ export interface CapabilityInfo {
 
 export interface FormatHostIO {
   /** Read and parse a JSON file or URL. */
-  loadJson(pathOrUrl: string): Promise<Record<string, unknown>>;
+  loadJson: (pathOrUrl: string) => Promise<Record<string, unknown>>;
   /** Import a JS module by path or URL. */
-  importModule(pathOrUrl: string): Promise<Record<string, unknown>>;
+  importModule: (pathOrUrl: string) => Promise<Record<string, unknown>>;
   /** Resolve a relative reference against a base (node: path.resolve; browser: new URL). */
-  resolvePath(base: string, ref: string): string;
+  resolvePath: (base: string, ref: string) => string;
 }
 
 interface ClassMethodLike {
@@ -149,7 +149,7 @@ export class FormatEntry {
       | undefined;
     const fn = Cls?.[cap.identifier];
     if (typeof fn !== "function") {
-      throw new Error(
+      throw new TypeError(
         `Format class "${this.name}": implementation export "${title}" has no static "${cap.identifier}" method`,
       );
     }
@@ -167,7 +167,9 @@ export class FormatRegistry {
     for (const cap of FORMAT_CAPABILITIES) {
       const seen = new Map<string, FormatEntry>();
       for (const entry of entries) {
-        if (!entry.capabilities[cap]) continue;
+        if (!entry.capabilities[cap]) {
+          continue;
+        }
         for (const ext of entry.extensions) {
           const prior = seen.get(ext);
           if (prior) {
@@ -208,8 +210,12 @@ export class FormatRegistry {
   documentExtensions(kind?: FormatDocumentKind): string[] {
     const exts = new Set<string>();
     for (const entry of this.#entries) {
-      if (kind && !entry.documentKinds.includes(kind)) continue;
-      for (const ext of entry.extensions) exts.add(ext);
+      if (kind && !entry.documentKinds.includes(kind)) {
+        continue;
+      }
+      for (const ext of entry.extensions) {
+        exts.add(ext);
+      }
     }
     exts.delete(".json");
     return [...exts];
@@ -234,16 +240,23 @@ export async function buildFormatRegistry(
 ): Promise<FormatRegistry> {
   const entries: FormatEntry[] = [];
   for (const [name, ref] of Object.entries(imports ?? {})) {
-    if (typeof ref !== "string" || !ref.endsWith(".class.json")) continue;
-    const classPath = base ? io.resolvePath(base, ref) : ref;
+    if (typeof ref !== "string" || !ref.endsWith(".class.json")) {
+      continue;
+    }
+    let classPath: string;
     let classDef: ClassDefLike;
     try {
+      classPath = base ? io.resolvePath(base, ref) : ref;
       classDef = (await io.loadJson(classPath)) as ClassDefLike;
     } catch {
-      continue; // unreadable imports are not format classes
+      continue; // Unresolvable or unreadable imports are not format classes
+    }
+    if (!classDef || typeof classDef !== "object") {
+      continue;
+    }
+    if (!classDef.format || !Array.isArray(classDef.format.extensions)) {
+      continue;
     }
-    if (!classDef || typeof classDef !== "object") continue;
-    if (!classDef.format || !Array.isArray(classDef.format.extensions)) continue;
     entries.push(new FormatEntry(name, classPath, classDef, io));
   }
   return new FormatRegistry(entries);
@@ -256,7 +269,9 @@ function extractCapabilities(
   const methods = classDef.$defs?.methods ?? {};
   for (const [key, method] of Object.entries(methods)) {
     const role = method.role as FormatCapability | undefined;
-    if (!role || !FORMAT_CAPABILITIES.includes(role)) continue;
+    if (!role || !FORMAT_CAPABILITIES.includes(role)) {
+      continue;
+    }
     out[role] = {
       identifier: method.identifier ?? key,
       timing: (method.timing as FormatTiming[] | undefined) ?? DEFAULT_TIMING,

package/src/guards.ts

@@ -0,0 +1,195 @@
+/**
+ * Type predicate guards for the Jx document model.
+ *
+ * These narrow `unknown`/union-typed values to precise domain types so call sites get real property
+ * checking instead of casts. Every guard mirrors the runtime's actual detection logic (see
+ * buildScope's five-shape algorithm in the runtime).
+ */
+
+import type {
+  JsonObject,
+  JsonValue,
+  JxClassDef,
+  JxElement,
+  JxEventBinding,
+  JxExpressionDef,
+  JxFunctionDef,
+  JxMappedArray,
+  JxMutableNode,
+  JxPrototypeDef,
+  JxRef,
+  JxServerFnDef,
+  JxStateObject,
+  JxStyle,
+} from "../types";
+
+// ─── JSON shape guards ──────────────────────────────────────────────────────────
+
+/** A plain object: not null, not an array. The base check for all object-shaped defs. */
+export function isJsonObject(value: unknown): value is JsonObject {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// ─── Binding guards ─────────────────────────────────────────────────────────────
+
+/** A `{ $ref: "#/..." }` JSON Pointer reference. */
+export function isRef(value: unknown): value is JxRef {
+  return isJsonObject(value) && typeof value.$ref === "string";
+}
+
+// ─── State definition guards (the five-shape algorithm) ────────────────────────
+
+/** Shape 4: a function declaration — `{ $prototype: "Function", body | $src }`. */
+export function isFunctionDef(value: unknown): value is JxFunctionDef {
+  return isJsonObject(value) && value.$prototype === "Function";
+}
+
+/** Shape 5: a declarative expression entry — `{ $expression: { operator, target } }`. */
+export function isExpressionDef(value: unknown): value is JxExpressionDef {
+  return isJsonObject(value) && isJsonObject(value.$expression);
+}
+
+/** A non-Function `$prototype` instance (Request, Storage, ContentCollection, classes, …). */
+export function isPrototypeDef(value: unknown): value is JxPrototypeDef {
+  return (
+    isJsonObject(value) && typeof value.$prototype === "string" && value.$prototype !== "Function"
+  );
+}
+
+/** A `timing: "server"` function proxy (no `$prototype`, external `$src`/`$export`). */
+export function isServerFnDef(value: unknown): value is JxServerFnDef {
+  return (
+    isJsonObject(value) &&
+    value.timing === "server" &&
+    typeof value.$src === "string" &&
+    typeof value.$export === "string" &&
+    !value.$prototype
+  );
+}
+
+/** Shape 2: an expanded signal — an object carrying a `default` value. */
+export function isExpandedSignal(value: unknown): value is JxStateObject & { default: JsonValue } {
+  return isJsonObject(value) && !value.$prototype && !value.$expression && "default" in value;
+}
+
+/**
+ * Schema-only keywords used to detect pure type definitions (Shape 2b). An object with ONLY these
+ * keys and no `default` is a type def, not a signal.
+ */
+export const SCHEMA_KEYWORDS: ReadonlySet<string> = new Set([
+  "type",
+  "enum",
+  "minimum",
+  "maximum",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "items",
+  "properties",
+  "required",
+  "description",
+  "title",
+  "$comment",
+]);
+
+/** Shape 2b: a pure type definition — every key is a JSON Schema keyword. */
+export function isSchemaOnlyDef(value: unknown): value is JxStateObject {
+  if (!isJsonObject(value)) {
+    return false;
+  }
+  for (const k of Object.keys(value)) {
+    if (!SCHEMA_KEYWORDS.has(k)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/** True when an object carries at least one JSON Schema keyword. */
+export function hasSchemaKeywords(value: unknown): value is JxStateObject {
+  if (!isJsonObject(value)) {
+    return false;
+  }
+  for (const k of Object.keys(value)) {
+    if (SCHEMA_KEYWORDS.has(k)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ─── Document structure guards ──────────────────────────────────────────────────
+
+/** A mapped (repeater) children object — `{ $prototype: "Array", items, map }`. */
+export function isMappedArray(value: unknown): value is JxMappedArray {
+  return isJsonObject(value) && value.$prototype === "Array";
+}
+
+/** A .class.json schema-defined class document — `{ $prototype: "Class" }`. */
+export function isClassDef(value: unknown): value is JxClassDef {
+  return isJsonObject(value) && value.$prototype === "Class";
+}
+
+/** An element-shaped node object (vs. a bare string/number child). */
+export function isNodeObject(value: unknown): value is JxMutableNode & JxElement {
+  return isJsonObject(value);
+}
+
+/** A `${...}` template-expression string. */
+export function isTemplateString(value?: unknown): value is string {
+  return typeof value === "string" && value.includes("${");
+}
+
+// ─── Style guards & accessors ───────────────────────────────────────────────────
+
+/** A nested style object (selector/media block), as opposed to a scalar CSS value. */
+export function isNestedStyle(value: string | number | JxStyle | undefined): value is JxStyle {
+  return typeof value === "object" && value !== null;
+}
+
+/** Read a nested style block (`:hover`, `@--md`, `& > li`, …), if present. */
+export function getNestedStyle(style: JxStyle | undefined, key: string): JxStyle | undefined {
+  const value = style?.[key];
+  return isNestedStyle(value) ? value : undefined;
+}
+
+/** Read a nested style block, creating an empty one in place when absent or scalar. */
+export function ensureNestedStyle(style: JxStyle, key: string): JxStyle {
+  const existing = style[key];
+  if (isNestedStyle(existing)) {
+    return existing;
+  }
+  const created: JxStyle = {};
+  style[key] = created;
+  return created;
+}
+
+// ─── Event binding guards ───────────────────────────────────────────────────────
+
+/**
+ * The value of an `on*` document key: a `$ref`, an inline function declaration, or a declarative
+ * expression.
+ */
+export function isEventBinding(value: unknown): value is JxEventBinding {
+  return isRef(value) || isFunctionDef(value) || isExpressionDef(value);
+}
+
+/** Read the event binding stored under an `on*` key of a node, if there is one. */
+export function getEventBinding(
+  node: JxMutableNode | JxElement,
+  key: string,
+): JxEventBinding | undefined {
+  const value = node[key];
+  return isEventBinding(value) ? value : undefined;
+}
+
+// ─── Parameter helpers ──────────────────────────────────────────────────────────
+
+/** Resolve `parameters` entries (bare strings or CEM objects) to their names. */
+export function paramNames(parameters: JxFunctionDef["parameters"]): string[] {
+  if (!parameters) {
+    return [];
+  }
+  return parameters.map((p) => (typeof p === "string" ? p : p.name));
+}

package/src/parse.ts

@@ -0,0 +1,57 @@
+/**
+ * Typed parse boundary for Jx documents and configs.
+ *
+ * Raw `JSON.parse()` returns `any`, which silently disables checking for everything downstream.
+ * These helpers are the single sanctioned crossing point: they parse, structurally verify, and
+ * return the domain type — failures carry the source path.
+ */
+
+import type { JxClassDef, JxDocument, ProjectConfig } from "../types";
+import { isJsonObject } from "./guards";
+
+// ─── Error helpers ──────────────────────────────────────────────────────────────
+
+/** Extract a human-readable message from a caught `unknown`. */
+export function errorMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+/** Coerce a caught `unknown` to an Error without losing the original. */
+export function toError(e: unknown): Error {
+  return e instanceof Error ? e : new Error(String(e));
+}
+
+// ─── Parse helpers ──────────────────────────────────────────────────────────────
+
+function parseObject(text: string, sourcePath: string, what: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`Failed to parse ${what} at ${sourcePath}: ${errorMessage(error)}`, {
+      cause: error,
+    });
+  }
+  if (!isJsonObject(parsed)) {
+    throw new Error(`Invalid ${what} at ${sourcePath}: expected a JSON object`);
+  }
+  return parsed;
+}
+
+/** Parse a Jx document (.json page/layout/component source). */
+export function parseJxDocument(text: string, sourcePath: string): JxDocument {
+  return parseObject(text, sourcePath, "Jx document") as JxDocument;
+}
+
+/** Parse a project.json site configuration. */
+export function parseProjectConfig(text: string, sourcePath: string): ProjectConfig {
+  return parseObject(text, sourcePath, "project config") as ProjectConfig;
+}
+
+/**
+ * Parse a .class.json schema-defined class. Note: `$prototype: "Class"` is the canonical
+ * discriminator but is not required — existing class files omit it.
+ */
+export function parseClassDef(text: string, sourcePath: string): JxClassDef {
+  return parseObject(text, sourcePath, "class definition") as unknown as JxClassDef;
+}