@versionzero/schema 1.0.0

package/src/helpers/stringify.js

@@ -0,0 +1,309 @@
+const randomUUID = () => crypto.randomUUID();
+
+/**
+ * Deterministic stringifier with support for extended types and deserialization.
+ * @package
+ * @param {any} value - Value to stringify
+ * @param {object} [options] - Stringification options
+ * @param {number} [options.space] - Indentation for pretty printing (default: 0)
+ * @param {number} [options.maxDepth] - Maximum recursion depth (default: 100)
+ * @param {boolean} [options.useDelimiters] - Use <<Type>> markers for extended types (default: true)
+ * @param {string} [options.delimiterOpen] - Opening delimiter for type markers (default: '<<')
+ * @param {string} [options.delimiterClose] - Closing delimiter for type markers (default: '>>')
+ * @returns {string} Deterministic JSON string with optional type markers
+ */
+export function stringify(value, options = {}) {
+  const {
+    space = 0,
+    maxDepth = 100,
+    useDelimiters = true,
+    delimiterOpen = '«',
+    delimiterClose = '»'
+  } = options;
+
+  const seen = new WeakMap();
+  const symbolIds = new WeakMap();
+
+  /**
+   * @param {string} type
+   * @param {string|null} value
+   * @returns {string|null}
+   */
+  const makeMarker = (type, value = null) => {
+    if (!useDelimiters) {
+      return null; // Signal to skip this value
+    }
+    return value !== null
+           ? `${delimiterOpen}${type}: ${value}${delimiterClose}`
+           : `${delimiterOpen}${type}${delimiterClose}`;
+  };
+
+  const getSymbolId = (sym) => {
+    const description = sym.description;
+    if (description !== undefined) {
+      return description;
+    }
+
+    if (!symbolIds.has(sym)) {
+      symbolIds.set(sym, randomUUID());
+    }
+    return symbolIds.get(sym);
+  };
+
+  const stringifyValue = (val, path = '$', depth = 0) => {
+    if (depth > maxDepth) {
+      return makeMarker('MaxDepth');
+    }
+
+    // Primitives
+    if (val === null) return null;
+    if (val === undefined) return makeMarker('undefined');
+    if (typeof val === 'number') {
+      if (Number.isNaN(val)) return makeMarker('NaN');
+      if (val === Infinity) return makeMarker('Infinity');
+      if (val === -Infinity) return makeMarker('-Infinity');
+      return val;
+    }
+    if (typeof val === 'boolean') return val;
+    if (typeof val === 'string') return val;
+    if (typeof val === 'symbol') {
+      return makeMarker('Symbol', getSymbolId(val));
+    }
+    if (typeof val === 'function') {
+      return val.name ? makeMarker('Function', val.name) : makeMarker('undefined');
+    }
+    if (typeof val === 'bigint') {
+      return makeMarker('BigInt', val.toString());
+    }
+
+    // Dates
+    if (val instanceof Date) {
+      const marker = makeMarker('Date', val.toISOString());
+      return marker !== null ? marker : val.toISOString();
+    }
+
+    // Arrays
+    if (Array.isArray(val)) {
+      if (seen.has(val)) {
+        return makeMarker('Circular', seen.get(val));
+      }
+      seen.set(val, path);
+
+      const items = val.map((item, index) =>
+        stringifyValue(item, `${path}[${index}]`, depth + 1)
+      ).filter(item => item !== null || val.includes(null)); // Keep explicit nulls
+
+      seen.delete(val);
+      return items;
+    }
+
+    // Objects
+    if (typeof val === 'object') {
+      if (seen.has(val)) {
+        return makeMarker('Circular', seen.get(val));
+      }
+      seen.set(val, path);
+
+      const keys = Object.keys(val).sort();
+      const result = {};
+
+      for (const key of keys) {
+        const keyPath = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+                        ? `${path}.${key}`
+                        : `${path}[${JSON.stringify(key)}]`;
+        const stringified = stringifyValue(val[key], keyPath, depth + 1);
+
+        // Skip only marker nulls (stripped values), not actual nulls
+        if (stringified !== null || val[key] === null) {
+          result[key] = stringified;
+        }
+      }
+
+      seen.delete(val);
+      return result;
+    }
+
+    return null;
+  };
+
+  const result = stringifyValue(value);
+  return JSON.stringify(result, null, space);
+}
+
+/**
+ * Parse a string created by stringify() back into an object.
+ * Handles both plain JSON and extended format with type markers.
+ * @package
+ * @param {string} text - JSON string to parse
+ * @param {object} [options] - Parse options
+ * @param {string} [options.delimiterOpen] - Opening delimiter for type markers (default '<<')
+ * @param {string} [options.delimiterClose] - Closing delimiter for type markers (default '>>')
+ * @returns {any} Parsed value with extended types and circular references restored
+ */
+export function parse(text, options = {}) {
+  const {
+    delimiterOpen = '«',
+    delimiterClose = '»'
+  } = options;
+
+  const parsed = JSON.parse(text);
+  const pathMap = new Map();
+  const circularRefs = [];
+
+  // Escape regex special characters
+  const escapeRegex = (str) => str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const markerPattern = new RegExp(
+    `^${escapeRegex(delimiterOpen)}([^:${escapeRegex(delimiterClose)}]+)(?::\\s*(.+?))?${escapeRegex(delimiterClose)}$`
+  );
+
+  const parseMarker = (str) => {
+    if (typeof str !== 'string') return null;
+    const match = str.match(markerPattern);
+    if (!match) return null;
+    return { type: match[1], value: match[2] };
+  };
+
+  const revive = (val, path = '$') => {
+    // Check for marker strings
+    const marker = parseMarker(val);
+    if (marker) {
+      switch (marker.type) {
+        case 'undefined': return undefined;
+        case 'NaN': return NaN;
+        case 'Infinity': return Infinity;
+        case '-Infinity': return -Infinity;
+        case 'BigInt': return BigInt(marker.value);
+        case 'Date': return new Date(marker.value);
+        case 'Symbol': return Symbol.for(marker.value);
+        case 'Function': return null;
+        case 'MaxDepth': return null;
+        case 'Circular':
+          circularRefs.push({ targetPath: path, sourcePath: marker.value });
+          return null;
+      }
+    }
+
+    if (val === null || typeof val !== 'object') {
+      return val;
+    }
+
+    // Arrays
+    if (Array.isArray(val)) {
+      const arr = [];
+      pathMap.set(path, arr);
+
+      val.forEach((item, index) => {
+        const itemPath = `${path}[${index}]`;
+        arr[index] = revive(item, itemPath);
+      });
+
+      return arr;
+    }
+
+    // Objects
+    const obj = {};
+    pathMap.set(path, obj);
+
+    for (const [key, value] of Object.entries(val)) {
+      const keyPath = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(key)
+                      ? `${path}.${key}`
+                      : `${path}[${JSON.stringify(key)}]`;
+      obj[key] = revive(value, keyPath);
+    }
+
+    return obj;
+  };
+
+  const result = revive(parsed);
+
+  // Second pass: resolve circular references
+  for (const { targetPath, sourcePath } of circularRefs) {
+    const target = resolvePath(result, targetPath);
+    const source = pathMap.get(sourcePath);
+
+    if (target && source) {
+      setPath(target.obj, target.key, source);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Resolve a JSONPath to an object and key
+ * @param {*} root - Root object
+ * @param {string} path - Path to resolve
+ * @returns {{obj: object, key: string|number}|null}
+ */
+function resolvePath(root, path) {
+  if (path === '$') {
+    return null;
+  }
+
+  const parts = parsePath(path);
+  let current = root;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    current = current[parts[i]];
+    if (current === null || current === undefined) {
+      return null;
+    }
+  }
+
+  return { obj: current, key: parts[parts.length - 1] };
+}
+
+/**
+ * Set a value at the given object/key
+ * @param {object} obj - Parent object
+ * @param {string|number} key - Key to set
+ * @param {*} value - Value to set
+ */
+function setPath(obj, key, value) {
+  obj[key] = value;
+}
+
+/**
+ * Parse a JSONPath into an array of keys
+ * @param {string} path - Path like $.foo.bar[0].baz
+ * @returns {Array<string|number>}
+ */
+function parsePath(path) {
+  const parts = [];
+  let current = '';
+  let inBracket = false;
+
+  for (let i = 0; i < path.length; i++) {
+    const char = path[i];
+
+    if (char === '$' && i === 0) {
+      continue;
+    }
+
+    if (char === '.' && !inBracket) {
+      if (current) parts.push(current);
+      current = '';
+    } else if (char === '[') {
+      if (current) parts.push(current);
+      current = '';
+      inBracket = true;
+    } else if (char === ']') {
+      if (inBracket) {
+        const trimmed = current.trim();
+        if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+          parts.push(JSON.parse(trimmed));
+        } else {
+          parts.push(Number(trimmed));
+        }
+        current = '';
+        inBracket = false;
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current) parts.push(current);
+
+  return parts;
+}

package/src/helpers/to-data.js

@@ -0,0 +1,64 @@
+import { CompiledSchema } from '../compiled-schema.js';
+import { Schema } from '../schema.js';
+
+
+import { SchemaError } from '../errors.js';
+/** @import {SchemaData} from '../types.js' */
+/**
+ * Common implementation shared by both Schema and CompiledSchema
+ * (which only share a "fake" jsdoc interface to define their shape)
+ * @package
+ * @param {Schema|CompiledSchema|SchemaData} schema
+ * @param {WeakMap<object,object>} [seen] - cycle-detection map; shared across recursive calls
+ * @returns {SchemaData}
+ */
+export function toData(schema, seen = new WeakMap()) {
+
+  if (typeof schema !== 'object') {
+    throw new SchemaError('Not a schema!')
+  }
+
+  if (seen.has(schema)) {
+    return seen.get(schema);
+  }
+
+  /** @type {SchemaData} */
+  const data = {};
+  seen.set(schema, data);
+
+  if (!(schema instanceof CompiledSchema) && schema.base) {
+    data.base = schema.base;
+  }
+  // sloppy copy so that we can also load dumb data
+  for (const group of ['properties', 'unionSchemas', 'metadata', 'options', 'handlers']) {
+    if (!schema[group]) {
+      continue;
+    }
+
+    for (const [key, value] of Object.entries(schema[group])) {
+      if (data[group] === undefined) {
+        data[group] = {};
+      }
+      const isSchema = (value instanceof Schema) || (value instanceof CompiledSchema);
+
+      let v = value;
+      if (isSchema) {
+        v = toData(value, seen);
+      }
+      else if (group === 'handlers') {
+        if (Array.isArray(value)) {
+          v = value.map(p => {
+            if (p === null) { return '$null' }
+            if (p === undefined) { return '$undefined' }
+            if (typeof p === 'object' && p.spec !== undefined) {
+              return p.spec;
+            }
+            return p;
+          });
+        }
+      }
+      (data[group])[key] = v;
+    }
+  }
+  return data;
+}

package/src/helpers/truthy.js

@@ -0,0 +1,55 @@
+/**
+ * Return true if the provided value is one of the magic truthy keywords
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isTruthyKeyword(value) {
+  return (value === 'true' || value === '1' || value === 'yes' || value === 'enabled' || value === 'active' || value === 'on');
+}
+
+/**
+ * Return true if the provided value is one of the magic falsey keywords
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isFalseyKeyword(value) {
+  return (value === 'false' || value === '0' || value === 'no' || value === 'disabled' || value === 'inactive' || value === 'off' || value === '' || value === 'undefined' || value === 'null' || value === 'none');
+}
+
+/**
+ * This library has a slightly extended notion of truthiness that includes human-friendly string representations
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isTruthy(value) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  if (typeof value === 'string') {
+    const lower = value.toLowerCase().trim();
+    if (isTruthyKeyword(lower)) { return true }
+    if (isFalseyKeyword(lower)) { return false }
+  }
+  if (value instanceof Error) { return false }
+  return Boolean(value);
+}
+
+/**
+ * This library has a slightly extended notion of truthiness that includes human-friendly string representations
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isFalsey(value) {
+  if (typeof value === 'boolean') {
+    return !value;
+  }
+  if (typeof value === 'string') {
+    const lower = value.toLowerCase().trim();
+    if (isTruthyKeyword(lower)) { return false }
+    if (isFalseyKeyword(lower)) { return true }
+  }
+  if (value instanceof Error) { return true }
+  return !Boolean(value);
+}

package/src/index.js

@@ -0,0 +1,29 @@
+// Copyright 2026 Version Zero | github.com/argh
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
+// Register core libraries before any SchemaResolver is constructed.
+// The node library is conditionally loaded based on runtime detection.
+import { registerCoreLibrary } from './schema-resolver.js';
+import coreLibrary from './core-library/index.js';
+
+registerCoreLibrary(coreLibrary);
+
+const IS_NODE = typeof globalThis.process !== 'undefined'
+  && typeof globalThis.process.versions?.node === 'string';
+
+if (IS_NODE) {
+  const { default: coreLibraryNode } = await import('./core-library-node/index.js');
+  registerCoreLibrary(coreLibraryNode);
+}
+
+export { CompiledSchema } from './compiled-schema.js';
+export { Schema, SchemaPolicy } from './schema.js';
+export { SchemaError } from './errors.js'
+export { SchemaResolver } from './schema-resolver.js';
+export { SchemaLocation } from './schema-location.js';
+export { EMPTY } from './constants.js';