@weipertda/sigiljs 0.0.3 → 0.2.0

package/examples/basic-user.js

@@ -0,0 +1,16 @@
+import { Sigil } from '../src/index.js';
+
+const User = Sigil`
+{
+  name: string
+  age?: number
+  tags: string[]
+}
+`
+
+const data = {
+  name: "Alex",
+  tags: ["js", "bun"]
+}
+
+console.log(User.check(data))

package/examples/basic-user.md

@@ -0,0 +1,22 @@
+# [examples/basic-user.js](https://github.dev/weipertda/sigiljs/blob/main/examples/basic-user.js)
+
+```javascript
+
+import { Sigil } from "../src/index.js"
+
+const User = Sigil`
+{
+  name: string
+  age?: number
+  tags: string[]
+}
+`
+
+const data = {
+  name: "Alex",
+  tags: ["js", "bun"]
+}
+
+console.log(User.check(data))
+
+```

package/examples/config-file.md

@@ -0,0 +1,16 @@
+# Configuration File Example
+
+```js
+import { Sigil } from 'sigiljs';
+
+const Config = Sigil`
+{
+  port: number
+  host: string
+  debug?: boolean
+}
+`
+
+
+Config.assert(JSON.parse(file))
+```

package/examples/config-validation.js

@@ -0,0 +1,18 @@
+import { Sigil } from '../src/index.js'
+import fs from 'fs'
+
+const Config = Sigil`
+{
+  port: number
+  host: string
+  debug?: boolean
+}
+`
+
+const config = JSON.parse(
+  fs.readFileSync("./config.json", "utf8")
+)
+
+Config.assert(config)
+
+console.log("Config valid")

package/examples/config-validation.md

@@ -0,0 +1,24 @@
+# [examples/config-validation.js](https://github.dev/weipertda/sigiljs/blob/main/examples/scripts/config-validation.js)
+
+```javascript
+
+import { Sigil } from "../src/index.js"
+import fs from "fs"
+
+const Config = Sigil`
+{
+  port: number
+  host: string
+  debug?: boolean
+}
+`
+
+const config = JSON.parse(
+  fs.readFileSync("./config.json", "utf8")
+)
+
+Config.assert(config)
+
+console.log("Config valid")
+
+```

package/examples/login-request.js

@@ -0,0 +1,19 @@
+import { Sigil } from '../src/index.js'
+
+const LoginRequest = Sigil`
+{
+  email: string
+  password: string
+}
+`
+
+function login(body) {
+  LoginRequest.assert(body)
+
+  console.log("Login request valid")
+}
+
+login({
+  email: "hello@example.com",
+  password: "secret"
+})

package/examples/login-request.md

@@ -0,0 +1,25 @@
+# [examples/login-request.js](https://github.dev/weipertda/sigiljs/blob/main/examples/scripts/login-request.js)
+
+```javascript
+
+import { Sigil } from "../src/index.js"
+
+const LoginRequest = Sigil`
+{
+  email: string
+  password: string
+}
+`
+
+function login(body) {
+  LoginRequest.assert(body)
+
+  console.log("Login request valid")
+}
+
+login({
+  email: "hello@example.com",
+  password: "secret"
+})
+
+```

package/examples/nested-order.js

@@ -0,0 +1,28 @@
+import { Sigil } from '../src/index.js'
+
+const Order = Sigil`
+{
+  id: string
+  customer: {
+    name: string
+    email: string
+  }
+  items: {
+    name: string
+    price: number
+  }[]
+}
+`
+
+const order = {
+  id: "123",
+  customer: {
+    name: "Alex",
+    email: "alex@example.com"
+  },
+  items: [
+    { name: "Keyboard", price: 99 }
+  ]
+}
+
+console.log(Order.check(order))

package/examples/nested-order.md

@@ -0,0 +1,34 @@
+# [examples/nested-order.js](https://github.dev/weipertda/sigiljs/blob/main/examples/scripts/nested-order.js)
+
+```javascript
+
+import { Sigil } from "../src/index.js"
+
+const Order = Sigil`
+{
+  id: string
+  customer: {
+    name: string
+    email: string
+  }
+  items: {
+    name: string
+    price: number
+  }[]
+}
+`
+
+const order = {
+  id: "123",
+  customer: {
+    name: "Alex",
+    email: "alex@example.com"
+  },
+  items: [
+    { name: "Keyboard", price: 99 }
+  ]
+}
+
+console.log(Order.check(order))
+
+```

package/examples/realtype-demo.js

@@ -0,0 +1,6 @@
+import { realType } from '../src/index.js'
+
+console.log(realType([]))
+console.log(realType(null))
+console.log(realType(new Map()))
+console.log(realType(new Date()))

package/examples/realtype-demo.md

@@ -0,0 +1,12 @@
+# [examples/realtype-demo.js](https://github.dev/weipertda/sigiljs/blob/main/examples/scripts/realtype-demo.js)
+
+```javascript
+
+import { realType } from "../src/index.js"
+
+console.log(realType([]))
+console.log(realType(null))
+console.log(realType(new Map()))
+console.log(realType(new Date()))
+
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@weipertda/sigiljs",
-  "version": "0.0.3",
-  "description": "Runtime type sigils for JavaScript",
+  "version": "0.2.0",
+  "description": "Runtime-native type sigils for JavaScript",
   "keywords": [
     "types",
     "validation",
@@ -15,7 +15,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/weipertda/sigiljs.git"
+    "url": "git+https://github.com/antistructured/sigiljs.git"
   },
   "license": "MIT",
   "author": {
@@ -29,18 +29,26 @@
   },
   "main": "./src/index.js",
   "files": [
-    "src/",
+    "src",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "docs",
+    "examples"
   ],
   "scripts": {
     "format": "prettier --write src/",
     "lint": "eslint src/",
-    "test": "bun test"
+    "test": "bun test",
+    "bench": "bun run bench/validate-user.js"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "engines": {
     "bun": ">=1",
     "node": ">=18"
+  },
+  "devDependencies": {
+    "zod": "^4.4.3"
   }
 }

package/src/core/assert.js

@@ -1,6 +1,7 @@
 import { validate } from './validate.js';
 import { SigilValidationError } from './errors.js';
 import { realType } from './realType.js';
+import { resolve } from './registry.js';
 
 /**
  * Validates a value against a schema and throws a structured `SigilValidationError`
@@ -13,19 +14,37 @@ import { realType } from './realType.js';
  * @throws {SigilValidationError}
  */
 export function assert(astOrSigil, value, opts) {
-  if (validate(astOrSigil, value, opts)) return true;
+  try {
+    if (validate(astOrSigil, value, opts)) return true;
+  } catch (e) {
+    // validate() may throw when a lazy identifier resolver can't find a named sigil.
+    // Re-wrap as a structured SigilValidationError so callers always get a consistent type.
+    throw new SigilValidationError(
+      e.message ?? 'Validation failed',
+      [],
+      'unknown',
+      realType(value, opts),
+    );
+  }
 
   const ast = astOrSigil.normalized ?? astOrSigil.ast ?? astOrSigil;
 
-  // Walk the AST to find the precise failure point for a rich error
-  const err = findError(ast, value, opts, []);
-  if (err)
+  let err;
+  try {
+    err = findError(ast, value, opts, []);
+  } catch (e) {
+    // findError's identifier case may also throw for unresolvable names.
     throw new SigilValidationError(
-      err.message,
-      err.path,
-      err.expected,
-      err.actual,
+      e.message ?? 'Validation failed',
+      [],
+      'unknown',
+      realType(value, opts),
     );
+  }
+
+  if (err) {
+    throw new SigilValidationError(err.message, err.path, err.expected, err.actual);
+  }
 
   // Generic fallback (should rarely be reached)
   throw new SigilValidationError(
@@ -36,33 +55,72 @@ export function assert(astOrSigil, value, opts) {
   );
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a human-readable type string for any AST node.
+ * Used in error messages as the "expected" description.
+ *
+ * @param {object} ast
+ * @returns {string}
+ */
+function describeType(ast) {
+  if (!ast) return 'unknown';
+  switch (ast.kind) {
+    case 'primitive':
+      return ast.name;
+    case 'literal':
+      return JSON.stringify(ast.value);
+    case 'literal_union':
+      return ast.values.map((v) => JSON.stringify(v)).join(' | ');
+    case 'primitive_union':
+      return ast.names.join(' | ');
+    case 'union':
+      return ast.members.map(describeType).join(' | ');
+    case 'array':
+      return `${describeType(ast.element)}[]`;
+    case 'optional':
+      return `${describeType(ast.inner)}?`;
+    case 'object':
+      return 'object';
+    case 'identifier':
+      return ast.name;
+    default:
+      return ast.kind ?? 'unknown';
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Core error-finding walker
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
- * Recursively walks the AST to find the deepest node that fails for `value`,
- * returning a structured error descriptor or null if no specific failure is found.
+ * Recursively walks the AST to find the deepest, most-specific failure point.
+ *
+ * Returns a structured error descriptor, or null if no specific failure is found.
  *
  * @param {object}   ast
  * @param {*}        value
  * @param {object}   opts
- * @param {string[]} path - Current property path (accumulated for error reporting)
+ * @param {string[]} path - Accumulated property path (e.g. ["user", "address", "zip"])
  * @returns {{ message: string, path: string[], expected: string, actual: string } | null}
  */
 function findError(ast, value, opts, path) {
   if (!ast) return null;
 
   switch (ast.kind) {
+    // ── Primitive ────────────────────────────────────────────────────────────
     case 'primitive': {
       const p = ast.name;
       if (p === 'any' || p === 'unknown') return null;
+
       if (p === 'never') {
         const actual = realType(value, opts);
-        return {
-          message: `Expected never, got ${actual}`,
-          path,
-          expected: 'never',
-          actual,
-        };
+        return { message: `Expected never, got ${actual}`, path, expected: 'never', actual };
       }
-      // typeof-checkable primitives
+
       if (
         p === 'string' ||
         p === 'number' ||
@@ -71,29 +129,34 @@ function findError(ast, value, opts, path) {
         p === 'bigint' ||
         p === 'undefined'
       ) {
-        const t = typeof value;
-        return t !== p ?
-            { message: `Expected ${p}, got ${t}`, path, expected: p, actual: t }
+        const actual = typeof value;
+        return actual !== p ?
+            { message: `Expected ${p}, got ${actual}`, path, expected: p, actual }
           : null;
       }
+
       const actual = realType(value, opts);
       return actual !== p ?
           { message: `Expected ${p}, got ${actual}`, path, expected: p, actual }
         : null;
     }
 
+    // ── Literal ───────────────────────────────────────────────────────────────
     case 'literal': {
       if (value !== ast.value) {
+        const expected = JSON.stringify(ast.value);
+        const actual = JSON.stringify(value);
         return {
-          message: `Expected literal ${JSON.stringify(ast.value)}, got ${JSON.stringify(value)}`,
+          message: `Expected literal ${expected}, got ${actual}`,
           path,
-          expected: String(ast.value),
+          expected,
           actual: String(value),
         };
       }
       return null;
     }
 
+    // ── Literal union ─────────────────────────────────────────────────────────
     case 'literal_union': {
       if (!ast.values.includes(value)) {
         const expected = ast.values.map((v) => JSON.stringify(v)).join(' | ');
@@ -107,6 +170,7 @@ function findError(ast, value, opts, path) {
       return null;
     }
 
+    // ── Primitive union ───────────────────────────────────────────────────────
     case 'primitive_union': {
       const actual = realType(value, opts);
       if (!ast.names.includes(actual)) {
@@ -121,70 +185,129 @@ function findError(ast, value, opts, path) {
       return null;
     }
 
+    // ── Union (mixed / complex) ───────────────────────────────────────────────
+    //
+    // Strategy: try every branch and keep the error with the deepest path
+    // (most specific failure). If any sub-error reaches deeper than the current
+    // path, return that — it gives the user the most actionable location.
+    // If all failures are at the same depth, fall back to a union-level message.
     case 'union': {
-      // For unions we report the full set of expected types
-      const expected = ast.members.map((m) => m.name ?? m.kind).join(' | ');
+      let bestErr = null;
+      for (const member of ast.members) {
+        const err = findError(member, value, opts, path);
+        if (!bestErr || (err && err.path.length > bestErr.path.length)) {
+          bestErr = err;
+        }
+      }
+      // A sub-branch had a deeper, more specific failure — surface it
+      if (bestErr && bestErr.path.length > path.length) {
+        return bestErr;
+      }
+      // All branches failed at the current depth — report the union itself
+      const expected = ast.members.map(describeType).join(' | ');
+      const actual = realType(value, opts);
       return {
-        message: `Expected ${expected}, got ${realType(value, opts)}`,
+        message: `Expected ${expected}, got ${actual}`,
         path,
         expected,
-        actual: realType(value, opts),
+        actual,
       };
     }
 
+    // ── Optional ─────────────────────────────────────────────────────────────
     case 'optional': {
-      return value === undefined ? null : (
-          findError(ast.inner, value, opts, path)
-        );
+      return value === undefined ? null : findError(ast.inner, value, opts, path);
     }
 
+    // ── Array ─────────────────────────────────────────────────────────────────
     case 'array': {
       if (!Array.isArray(value)) {
         const actual = realType(value, opts);
-        return {
-          message: `Expected array, got ${actual}`,
-          path,
-          expected: 'array',
-          actual,
-        };
+        return { message: `Expected array, got ${actual}`, path, expected: 'array', actual };
       }
+      const elemType = describeType(ast.element);
       for (let i = 0; i < value.length; i++) {
-        const err = findError(ast.element, value[i], opts, [
-          ...path,
-          String(i),
-        ]);
-        if (err) return err;
+        const err = findError(ast.element, value[i], opts, [...path, String(i)]);
+        if (err) {
+          return {
+            ...err,
+            message: `Expected item [${i}] to be ${elemType}, got ${err.actual}`,
+          };
+        }
       }
       return null;
     }
 
+    // ── Object ────────────────────────────────────────────────────────────────
     case 'object': {
       if (typeof value !== 'object' || value === null || Array.isArray(value)) {
         const actual = realType(value, opts);
-        return {
-          message: `Expected object, got ${actual}`,
-          path,
-          expected: 'object',
-          actual,
-        };
+        return { message: `Expected object, got ${actual}`, path, expected: 'object', actual };
+      }
+
+      // Exact mode: report the first unexpected property
+      if (ast.exact) {
+        const allowed = new Set(ast.properties.map((p) => p.key));
+        for (const key in value) {
+          if (!allowed.has(key)) {
+            return {
+              message: `Unexpected property "${key}"`,
+              path: [...path, key],
+              expected: 'never',
+              actual: realType(value[key], opts),
+            };
+          }
+        }
       }
+
+      // Check required properties
       for (const p of ast.properties) {
         if (!p.optional && !(p.key in value)) {
+          const expected = describeType(p.value);
           return {
-            message: `Missing required property "${p.key}"`,
+            message: `Missing required property "${p.key}" (expected ${expected})`,
             path: [...path, p.key],
-            expected: p.value.kind,
+            expected,
             actual: 'undefined',
           };
         }
+
         if (p.key in value && value[p.key] !== undefined) {
           const err = findError(p.value, value[p.key], opts, [...path, p.key]);
-          if (err) return err;
+          if (err) {
+            // Only override the message if the error is exactly one level deep
+            // (i.e., the failure IS the property itself). Deeper errors already
+            // carry their own enriched contextual message and must not be re-wrapped.
+            const isDirectFailure = err.path.length === path.length + 1;
+            return {
+              ...err,
+              message: isDirectFailure ?
+                `Expected property "${p.key}" to be ${err.expected}, got ${err.actual}`
+              : err.message,
+            };
+          }
         }
       }
+
       return null;
     }
 
+    // ── Identifier (named sigil reference) ───────────────────────────────────
+    case 'identifier': {
+      const name = ast.name;
+      const sigil = resolve(name);
+      if (!sigil) {
+        // Unknown at error-finding time — mirror the runtime throw as an error object
+        return {
+          message: `Unknown sigil reference: ${name}`,
+          path,
+          expected: name,
+          actual: realType(value, opts),
+        };
+      }
+      return findError(sigil.normalized ?? sigil.ast, value, opts, path);
+    }
+
     default:
       return null;
   }