@weipertda/sigiljs 0.0.1 → 0.2.0

package/src/core/compile.js

@@ -1,5 +1,9 @@
 import { realType } from '../core/realType.js';
-import { validatorCache, canonicalize } from './cache.js';
+import {
+  canonicalize,
+  validatorCache,
+} from './cache.js';
+import { resolve } from './registry.js';
 
 /**
  * Compiles a normalized+partially-evaluated SigilJS AST into a fast validator function.
@@ -25,9 +29,10 @@ export function compile(ast) {
 /**
  * Recursively builds a validator closure from an AST node.
  * @param {object} ast
+ * @param {Set<string>} [visited] - Track visited identifiers for recursion safety
  * @returns {Function}
  */
-function build(ast) {
+function build(ast, visited = new Set()) {
   switch (ast.kind) {
     case 'primitive': {
       const p = ast.name;
@@ -80,7 +85,7 @@ function build(ast) {
     }
 
     case 'union': {
-      const fns = ast.members.map(build);
+      const fns = ast.members.map((m) => build(m, visited));
       const len = fns.length;
       return (v, opts) => {
         for (let i = 0; i < len; i++) {
@@ -91,7 +96,7 @@ function build(ast) {
     }
 
     case 'array': {
-      const el = build(ast.element);
+      const el = build(ast.element, visited);
       return (v, opts) => {
         if (!Array.isArray(v)) return false;
         for (let i = 0; i < v.length; i++) {
@@ -102,7 +107,7 @@ function build(ast) {
     }
 
     case 'optional': {
-      const inner = build(ast.inner);
+      const inner = build(ast.inner, visited);
       return (v, opts) => v === undefined || inner(v, opts);
     }
 
@@ -114,27 +119,35 @@ function build(ast) {
         hints ?
           hints.requiredKeys.map((k) => ({
             key: k,
-            check: build(properties.find((p) => p.key === k).value),
+            check: build(properties.find((p) => p.key === k).value, visited),
           }))
         : properties
             .filter((p) => !p.optional)
-            .map((p) => ({ key: p.key, check: build(p.value) }));
+            .map((p) => ({ key: p.key, check: build(p.value, visited) }));
       const opt =
         hints ?
           hints.optionalKeys.map((k) => ({
             key: k,
-            check: build(properties.find((p) => p.key === k).value),
+            check: build(properties.find((p) => p.key === k).value, visited),
           }))
         : properties
             .filter((p) => p.optional)
-            .map((p) => ({ key: p.key, check: build(p.value) }));
+            .map((p) => ({ key: p.key, check: build(p.value, visited) }));
 
       const reqLen = req.length;
       const optLen = opt.length;
+      const allowedKeys = ast.exact ? new Set(properties.map((p) => p.key)) : null;
 
       return (v, opts) => {
         if (typeof v !== 'object' || v === null || Array.isArray(v))
           return false;
+
+        if (ast.exact) {
+          for (const key in v) {
+            if (!allowedKeys.has(key)) return false;
+          }
+        }
+
         for (let i = 0; i < reqLen; i++) {
           const p = req[i];
           if (!(p.key in v) || !p.check(v[p.key], opts)) return false;
@@ -148,6 +161,27 @@ function build(ast) {
       };
     }
 
+    case 'identifier': {
+      const name = ast.name;
+      const sigil = resolve(name);
+
+      // If the sigil isn't registered yet, or if we are currently visiting it (circularity),
+      // we return a lazy wrapper that resolves the sigil at validation time.
+      if (!sigil || visited.has(name)) {
+        return (val, o) => {
+          const resolved = resolve(name);
+          if (!resolved) throw new Error(`Unknown sigil reference: ${name}`);
+          return resolved.check(val, o);
+        };
+      }
+
+      visited.add(name);
+      const target = sigil.normalized || sigil.ast;
+      const check = build(target, visited);
+      visited.delete(name);
+      return check;
+    }
+
     default:
       return () => false;
   }

package/src/core/errors.js

@@ -1,14 +1,22 @@
 /**
  * Thrown by `assert()` when a value fails validation.
  *
- * Properties:
- *   - message  — human-readable description of the failure
- *   - code     — always "SIGIL_VALIDATION_FAILED" (machine-readable)
- *   - path     — array of keys to the failing property (e.g. ["user", "email"])
- *   - expected — type string that was expected
- *   - actual   — type string that was received
+ * Shape:
+ *   {
+ *     code:     "SIGIL_VALIDATION_FAILED",  // always — machine-readable
+ *     message:  "Expected property \"age\" to be number, got string",
+ *     path:     ["user", "age"],             // key path to the failing field
+ *     expected: "number",                    // type that was required
+ *     actual:   "string"                     // type that was received
+ *   }
  */
 export class SigilValidationError extends Error {
+  /**
+   * @param {string}   message  - Human-readable description of the failure
+   * @param {string[]} path     - Property path to the failure (e.g. ["user", "age"])
+   * @param {string}   expected - Type that was expected
+   * @param {string}   actual   - Type that was actually received
+   */
   constructor(message, path, expected, actual) {
     super(message);
     this.name = 'SigilValidationError';
@@ -23,6 +31,21 @@ export class SigilValidationError extends Error {
     }
   }
 
+  /**
+   * Returns the canonical JSON shape for structured logging / API responses.
+   *
+   * @returns {{ code: string, message: string, path: string[], expected: string, actual: string }}
+   */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      path: this.path,
+      expected: this.expected,
+      actual: this.actual,
+    };
+  }
+
   /** Consistent devtools / console.log labeling */
   get [Symbol.toStringTag]() {
     return 'SigilValidationError';

package/src/core/normalize.js

@@ -43,7 +43,7 @@ export function normalize(ast) {
         optional: p.optional,
         value: normalize(p.value),
       }));
-      return { kind: 'object', properties };
+      return { kind: 'object', properties, exact: ast.exact };
     }
 
     default:

package/src/core/parser.js

@@ -29,13 +29,14 @@ const PRIMITIVES = new Set([
  *   { kind: 'union',      members }
  *   { kind: 'array',      element }
  *   { kind: 'optional',   inner }
- *   { kind: 'object',     properties: [{ key, optional, value }] }
+ *   { kind: 'object',     properties: [{ key, optional, value }], exact }
  *   { kind: 'identifier', name }
  *
  * @param {string|Array} input
+ * @param {object} [options]
  * @returns {object} AST node
  */
-export function parse(input) {
+export function parse(input, options = {}) {
   const tokens = typeof input === 'string' ? tokenize(input) : input;
   let pos = 0;
 
@@ -212,7 +213,7 @@ export function parse(input) {
     }
 
     consume('}', 'Expected closing block brace');
-    return { kind: 'object', properties };
+    return { kind: 'object', properties, exact: !!options.exact };
   }
 
   return parseSigil();

package/src/core/partial.js

@@ -54,6 +54,7 @@ export function partial(ast) {
         kind: 'object',
         properties,
         hints: { requiredKeys, optionalKeys },
+        exact: ast.exact,
       };
     }
 

package/src/core/registry.js

@@ -0,0 +1,33 @@
+/**
+ * Global registry for named sigils.
+ * Allows sigils to be referenced by name in other sigils.
+ */
+const registry = new Map();
+
+/**
+ * Registers a sigil by name.
+ * @param {string} name
+ * @param {object} sigil
+ */
+export function register(name, sigil) {
+  if (typeof name !== 'string') {
+    throw new Error('Sigil name must be a string');
+  }
+  registry.set(name, sigil);
+}
+
+/**
+ * Resolves a sigil by name.
+ * @param {string} name
+ * @returns {object|undefined}
+ */
+export function resolve(name) {
+  return registry.get(name);
+}
+
+/**
+ * Clears the registry (mainly for testing).
+ */
+export function clear() {
+  registry.clear();
+}

package/src/core/validate.js

@@ -2,6 +2,9 @@ import { compile } from './compile.js';
 
 export function validate(astOrSigil, value, opts) {
   // Can be called with a raw AST, or a Sigil object possessing `.ast` / `.normalized`
+  if (astOrSigil && typeof astOrSigil.validator === 'function') {
+    return astOrSigil.validator(value, opts);
+  }
   const targetAst = astOrSigil.normalized || astOrSigil.ast || astOrSigil;
   const check = compile(targetAst);
   return check(value, opts);

package/src/index.js

@@ -4,3 +4,4 @@ export {
   realType as real,
   realType as Real,
 } from './core/realType.js';
+export { SigilValidationError } from './core/errors.js';

package/src/playground/playground.js

@@ -1,4 +1,4 @@
-import { T } from './index.js';
+import { T } from '../index.js';
 
 const jsonStr = process.argv[2];
 const sigilStr = process.argv[3];

package/src/sigil.js

@@ -3,6 +3,7 @@ import { compile } from './core/compile.js';
 import { normalize } from './core/normalize.js';
 import { parse } from './core/parser.js';
 import { partial } from './core/partial.js';
+import { register } from './core/registry.js';
 import { validate } from './core/validate.js';
 
 // Memoize fully-constructed Sigil objects by raw schema string.
@@ -16,40 +17,79 @@ const _sigilCache = new Map();
  * Each unique schema string is parsed, normalized, and compiled exactly once.
  * Subsequent calls with the same schema string return the cached sigil object.
  *
- * @param {TemplateStringsArray} strings
- * @param {...*} values - Interpolations (embedded JS values)
- * @returns {{ raw, ast, normalized, check, assert, compile }}
- *
- * @example
- * const User = Sigil`{ name: string, age?: number }`
- * User.check({ name: 'Alice' })  // true
- * User.assert({ name: 42 })      // throws SigilValidationError
+ * The returned sigil exposes:
+ *   .check(value)    → boolean
+ *   .assert(value)   → void | throws
+ *   .validator       → compiled validator function (same stable reference always)
+ *   .compile()       → same as .validator (method form, for back-compat)
+ *   .raw / .ast / .normalized / .options
  */
-export function Sigil(strings, ...values) {
+function createSigil(options, strings, ...values) {
   // Reconstruct raw string from template parts (supports interpolations)
   let raw = strings[0];
   for (let i = 0; i < values.length; i++) raw += values[i] + strings[i + 1];
 
-  // Return memoized sigil if already compiled
-  const cached = _sigilCache.get(raw);
+  // Cache key includes options to distinguish exact vs non-exact versions of same schema
+  const cacheKey = JSON.stringify(options) + raw;
+  const cached = _sigilCache.get(cacheKey);
   if (cached !== undefined) return cached;
 
   // Parse → Normalize → Partial-evaluate → Compile pipeline
-  const ast = parse(raw);
+  const ast = parse(raw, options);
   const normalized = partial(normalize(ast));
 
-  // Warm validator cache eagerly (avoids cold-start cost on first .check() call)
-  compile(normalized);
+  // Pre-compile eagerly and capture the function reference.
+  // This warms the cache on creation and ensures sigil.validator always
+  // returns the exact same cached function — no re-compilation ever.
+  const validator = compile(normalized);
 
   const sigil = Object.freeze({
     raw,
     ast,
     normalized,
+    options,
+    validator,
     check: (value, opts) => validate(sigil, value, opts),
     assert: (value, opts) => assert(sigil, value, opts),
-    compile: () => compile(normalized),
+    compile: () => validator,
   });
 
-  _sigilCache.set(raw, sigil);
+  _sigilCache.set(cacheKey, sigil);
   return sigil;
 }
+
+/**
+ * Default Sigil tagged template (non-strict objects).
+ */
+export function Sigil(strings, ...values) {
+  return createSigil({ exact: false }, strings, ...values);
+}
+
+/**
+ * Strict Sigil tagged template (exact objects, fails on extra properties).
+ */
+Sigil.exact = function (strings, ...values) {
+  return createSigil({ exact: true }, strings, ...values);
+};
+
+/**
+ * Creates a named Sigil and registers it in the global registry.
+ *
+ * @param {string} name
+ * @returns {Function} Tagged template function
+ */
+Sigil.named = function (name) {
+  return function (strings, ...values) {
+    const sigil = createSigil({ exact: false, named: name }, strings, ...values);
+    register(name, sigil);
+    return sigil;
+  };
+};
+
+/**
+ * Alias for Sigil.named — preferred ergonomic name for defining reusable sigils.
+ *
+ * @param {string} name
+ * @returns {Function} Tagged template function
+ */
+Sigil.define = Sigil.named;

package/CHANGELOG.md

@@ -1,28 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
----
-
-## [0.0.1] — 2026-03-10
-
-### Added
-- **`realType(value, opts?)`** — cross-realm-safe runtime type detection fixing all `typeof` gaps (`null`, `array`, `nan`, `map`, `set`, `date`, `regexp`, `promise`, `asyncfunction`, `generatorfunction`, `asyncgeneratorfunction`, `weakmap`, `weakset`); extensible via hook array.
-- **`Sigil` / `T` / `S` tagged template** — compile a schema string into a fast, memoized validator object exposing `.check()` and `.assert()`.
-- **Schema language** — primitives, literals, unions (`|`), arrays (`[]`), optionals (`?`), and nested object schemas.
-- **`SigilValidationError`** — structured error with `code`, `path`, `expected`, and `actual` properties.
-- **Two-level memoization** — Sigil-level cache (identical schema strings share one object reference) and compiled-validator cache (structural AST identity).
-- **Partial evaluation** — literal unions optimize to `Set` membership checks; pure primitive unions skip `realType` entirely; object hints pre-compute required/optional key sets.
-- **CLI playground** — `bun run src/playground.js '<json>' '<schema>'` for shell-level validation.
-
-### Engineering
-- Single-source-of-truth `realType` implementation in `src/core/realType.js`.
-- Module-scope frozen `Set` for O(1) tokenizer punctuation lookup.
-- Array-join accumulation in tokenizer hot string loops (no `+=` reallocation).
-- Module-scope frozen `Set` for parser primitive name lookup (not rebuilt per call).
-- Sigil objects are `Object.freeze()`-d — immutable public API surface.
-- `Error.captureStackTrace` on `SigilValidationError` for clean V8/Bun stack traces.
-- Full `package.json` with `exports`, `files`, `sideEffects: false`, `engines`, `keywords`.