@weipertda/sigiljs 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# 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`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SigilJS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# SigilJS
+
+Write types. Validate reality.
+
+## What is SigilJS?
+
+SigilJS is a tiny JavaScript library for describing and validating data using **sigils**.
+
+A sigil is a small expression (type expression) that describes what your data should look like.
+
+Sigils are compiled into fast validators, so repeated checks stay efficient.
+
+
+No TypeScript.
+
+No dependencies.
+
+Just JavaScript.
+
+---
+
+## Installation
+
+```bash
+
+bun add @weipertda/sigiljs
+
+```
+
+– or –
+
+```bash
+
+npm install @weipertda/sigiljs
+
+```
+
+---
+
+### Create a Sigil
+
+```javascript
+
+import { Sigil } from "@weipertda/sigiljs"
+
+const Email = Sigil`string`
+
+```
+
+### Validate a Value
+
+```javascript
+
+Email.check("hello@example.com")
+// true
+
+Email.check(42)
+// false
+
+```
+
+### Optional Values
+
+Use `?` to mark optional values.
+
+```javascript
+
+const MaybeName = Sigil`string?`
+
+```
+
+Matches:
+
+```javascript
+
+string
+undefined
+
+```
+
+---
+
+### Arrays
+
+```javascript
+
+const Tags = Sigil`string[]`
+
+Tags.check(["js", "bun"])
+// true
+
+```
+
+---
+
+### Unions
+
+```javascript
+
+const ID = Sigil`string | number`
+
+```
+
+Matches either type.
+
+---
+
+### Object Validation
+
+```javascript
+
+const User = Sigil`
+{
+  name: string
+  age?: number
+}
+`
+
+```
+
+Optional properties use ` ? `.
+
+---
+
+### Nested Objects
+
+```javascript
+
+const Order = Sigil`
+{
+  id: string
+  customer: {
+    name: string
+    email: string
+  }
+  items: {
+    name: string
+    price: number
+  }[]
+}
+`
+
+```
+
+---
+
+### Runtime Type Detection
+
+SigilJS also provides a better ` typeof `.
+
+```javascript
+
+import { realType } from "@weipertda/sigiljs"
+
+realType([])        // "array"
+realType(null)      // "null"
+realType(new Map()) // "map"
+
+```
+
+---
+
+## Why SigilJS?
+
+Sigil cleanly solves four problems:
+
+1. JavaScript's native ` typeof ` is inconsistent and too weak for real type work.
+
+```javascript
+
+typeof []
+// "object" 😬
+
+```
+
+2. TypeScript solves mostly compile-time problems, often adds friction, and disappears at runtime.
+
+  * TypeScript helps during development, but once your program runs the types are gone.
+
+  * SigilJS solves the runtime side of the problem.
+
+  * Describe your data once, then validate it anywhere.
+
+```typescript
+
+// TypeScript disappears at runtime
+const x: string = 123;
+
+// No runtime error
+
+```
+
+3. Existing runtime validation libraries are dependency-heavy, allocation-happy, or ergonomically off.
+
+4. JavaScript lacks a native-feeling type expression system for runtime truth.
+
+---
+
+### Accurate Runtime Types
+
+Replacing the gaps in ` typeof ` — ` realType ` correctly identifies ` null `, ` NaN `, arrays, async and generator functions, maps, sets, and arbitrary custom classes through hooks.
+
+```javascript
+
+import { realType } from '@weipertda/sigiljs';
+
+realType('x');                 // "string"
+realType(null);                // "null"
+realType(NaN);                 // "nan"
+realType([]);                  // "array"
+realType(new Map());           // "map"
+realType(async function() {}); // "asyncfunction"
+
+```
+
+You can even provide custom override hooks to map instances directly back to nominal strings:
+
+```javascript
+
+realType(myThing, {
+  hooks: [ v => v instanceof MyThing ? 'mything' : null ]
+}); // "mything"
+
+```
+
+SigilJS solves runtime type validation with a tiny, dependency-free, runtime-native type system.
+
+---
+
+## Documentation
+
+See the [docs/](docs/README.md) folder for full, detailed documentation __(WIP)__.
+
+---
+
+## Examples
+
+See the [examples/](examples/) folder for runnable examples __(WIP)__.
+
+---
+
+## License
+
+MIT
+
+---
+
+## CLI Playground
+
+You can securely test out Sigil validator schemas against JSON inputs directly from your shell:
+
+```bash
+
+bun run src/playground.js '{"name": "Doug"}' '{name: string, age?: number}'
+# ✅ Validation passed
+
+```
+
+## Performance Philosophy
+
+SigilJS embraces a Functional Core / Imperative Shell architecture. It takes your schema string, turns it into a typed token stream, drops parse grouping artifacts, flattens branches, optimizes primitive unions, and finally generates a blazingly fast validator closure mapped dynamically from the ground up to minimize allocations on the hot path. Repeated tagged template passes are thoroughly memoized.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@weipertda/sigiljs",
+  "version": "0.0.1",
+  "description": "Runtime type sigils for JavaScript",
+  "keywords": [
+    "types",
+    "validation",
+    "runtime",
+    "schema",
+    "type-checking",
+    "zero-dependency",
+    "sigil",
+    "bun",
+    "javascript"
+  ],
+  "author": {
+    "name": "Daniel Weipert",
+    "email": "weipertda@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/weipertda/sigiljs.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "main": "./src/index.js",
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "format": "prettier --write src/",
+    "lint": "eslint src/",
+    "test": "bun test"
+  },
+  "engines": {
+    "bun": ">=1",
+    "node": ">=18"
+  }
+}

package/src/core/assert.js

@@ -0,0 +1,191 @@
+import { validate } from './validate.js';
+import { SigilValidationError } from './errors.js';
+import { realType } from './realType.js';
+
+/**
+ * Validates a value against a schema and throws a structured `SigilValidationError`
+ * if validation fails. Returns `true` if validation passes.
+ *
+ * @param {object} astOrSigil - Raw AST, or a Sigil object with `.normalized` / `.ast`
+ * @param {*} value           - The value to validate
+ * @param {object} [opts]     - Optional hooks / options
+ * @returns {true}
+ * @throws {SigilValidationError}
+ */
+export function assert(astOrSigil, value, opts) {
+  if (validate(astOrSigil, value, opts)) return true;
+
+  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)
+    throw new SigilValidationError(
+      err.message,
+      err.path,
+      err.expected,
+      err.actual,
+    );
+
+  // Generic fallback (should rarely be reached)
+  throw new SigilValidationError(
+    'Validation failed',
+    [],
+    'match',
+    realType(value, opts),
+  );
+}
+
+/**
+ * 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.
+ *
+ * @param {object}   ast
+ * @param {*}        value
+ * @param {object}   opts
+ * @param {string[]} path - Current property path (accumulated for error reporting)
+ * @returns {{ message: string, path: string[], expected: string, actual: string } | null}
+ */
+function findError(ast, value, opts, path) {
+  if (!ast) return null;
+
+  switch (ast.kind) {
+    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,
+        };
+      }
+      // typeof-checkable primitives
+      if (
+        p === 'string' ||
+        p === 'number' ||
+        p === 'boolean' ||
+        p === 'symbol' ||
+        p === 'bigint' ||
+        p === 'undefined'
+      ) {
+        const t = typeof value;
+        return t !== p ?
+            { message: `Expected ${p}, got ${t}`, path, expected: p, actual: t }
+          : null;
+      }
+      const actual = realType(value, opts);
+      return actual !== p ?
+          { message: `Expected ${p}, got ${actual}`, path, expected: p, actual }
+        : null;
+    }
+
+    case 'literal': {
+      if (value !== ast.value) {
+        return {
+          message: `Expected literal ${JSON.stringify(ast.value)}, got ${JSON.stringify(value)}`,
+          path,
+          expected: String(ast.value),
+          actual: String(value),
+        };
+      }
+      return null;
+    }
+
+    case 'literal_union': {
+      if (!ast.values.includes(value)) {
+        const expected = ast.values.map((v) => JSON.stringify(v)).join(' | ');
+        return {
+          message: `Expected one of [${expected}], got ${JSON.stringify(value)}`,
+          path,
+          expected,
+          actual: String(value),
+        };
+      }
+      return null;
+    }
+
+    case 'primitive_union': {
+      const actual = realType(value, opts);
+      if (!ast.names.includes(actual)) {
+        const expected = ast.names.join(' | ');
+        return {
+          message: `Expected ${expected}, got ${actual}`,
+          path,
+          expected,
+          actual,
+        };
+      }
+      return null;
+    }
+
+    case 'union': {
+      // For unions we report the full set of expected types
+      const expected = ast.members.map((m) => m.name ?? m.kind).join(' | ');
+      return {
+        message: `Expected ${expected}, got ${realType(value, opts)}`,
+        path,
+        expected,
+        actual: realType(value, opts),
+      };
+    }
+
+    case 'optional': {
+      return value === undefined ? null : (
+          findError(ast.inner, value, opts, path)
+        );
+    }
+
+    case 'array': {
+      if (!Array.isArray(value)) {
+        const actual = realType(value, opts);
+        return {
+          message: `Expected array, got ${actual}`,
+          path,
+          expected: 'array',
+          actual,
+        };
+      }
+      for (let i = 0; i < value.length; i++) {
+        const err = findError(ast.element, value[i], opts, [
+          ...path,
+          String(i),
+        ]);
+        if (err) return err;
+      }
+      return null;
+    }
+
+    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,
+        };
+      }
+      for (const p of ast.properties) {
+        if (!p.optional && !(p.key in value)) {
+          return {
+            message: `Missing required property "${p.key}"`,
+            path: [...path, p.key],
+            expected: p.value.kind,
+            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;
+        }
+      }
+      return null;
+    }
+
+    default:
+      return null;
+  }
+}

package/src/core/cache.js

@@ -0,0 +1,7 @@
+export const validatorCache = new Map();
+
+export function canonicalize(ast) {
+  // A fast and structurally stable canonicalization for caching compiled validators.
+  // Because JSON.stringify preserves key order from our normalization phase.
+  return JSON.stringify(ast);
+}

package/src/core/compile.js

@@ -0,0 +1,154 @@
+import { realType } from '../core/realType.js';
+import { validatorCache, canonicalize } from './cache.js';
+
+/**
+ * Compiles a normalized+partially-evaluated SigilJS AST into a fast validator function.
+ *
+ * Validators are memoized by structural identity (via JSON canonicalization).
+ * A validator function has the signature: (value, opts?) => boolean
+ *
+ * @param {object} ast - Normalized & partially-evaluated AST node
+ * @returns {(value: *, opts?: object) => boolean}
+ */
+export function compile(ast) {
+  if (!ast) return () => true;
+
+  const key = canonicalize(ast);
+  const cached = validatorCache.get(key);
+  if (cached !== undefined) return cached;
+
+  const validator = build(ast);
+  validatorCache.set(key, validator);
+  return validator;
+}
+
+/**
+ * Recursively builds a validator closure from an AST node.
+ * @param {object} ast
+ * @returns {Function}
+ */
+function build(ast) {
+  switch (ast.kind) {
+    case 'primitive': {
+      const p = ast.name;
+      if (p === 'any' || p === 'unknown') return () => true;
+      if (p === 'never') return () => false;
+      // typeof-based fast-path for JS primitives (no realType overhead)
+      if (
+        p === 'string' ||
+        p === 'number' ||
+        p === 'boolean' ||
+        p === 'symbol' ||
+        p === 'bigint' ||
+        p === 'undefined'
+      ) {
+        return (v) => typeof v === p;
+      }
+      return (v, opts) => realType(v, opts) === p;
+    }
+
+    case 'literal': {
+      const val = ast.value;
+      return (v) => v === val;
+    }
+
+    case 'literal_union': {
+      // Fast-path: Set membership for 5+ literals, Array.includes for fewer
+      if (ast.values.length < 5) {
+        const arr = ast.values;
+        return (v) => arr.includes(v);
+      }
+      const set = new Set(ast.values);
+      return (v) => set.has(v);
+    }
+
+    case 'primitive_union': {
+      const names = ast.names;
+      // If all names are typeof-checkable, skip realType entirely
+      const allSimple = names.every(
+        (n) =>
+          n === 'string' ||
+          n === 'number' ||
+          n === 'boolean' ||
+          n === 'symbol' ||
+          n === 'bigint' ||
+          n === 'undefined',
+      );
+      return allSimple ?
+          (v) => names.includes(typeof v)
+        : (v, opts) => names.includes(realType(v, opts));
+    }
+
+    case 'union': {
+      const fns = ast.members.map(build);
+      const len = fns.length;
+      return (v, opts) => {
+        for (let i = 0; i < len; i++) {
+          if (fns[i](v, opts)) return true;
+        }
+        return false;
+      };
+    }
+
+    case 'array': {
+      const el = build(ast.element);
+      return (v, opts) => {
+        if (!Array.isArray(v)) return false;
+        for (let i = 0; i < v.length; i++) {
+          if (!el(v[i], opts)) return false;
+        }
+        return true;
+      };
+    }
+
+    case 'optional': {
+      const inner = build(ast.inner);
+      return (v, opts) => v === undefined || inner(v, opts);
+    }
+
+    case 'object': {
+      // Use pre-computed hint arrays from partial evaluation to avoid
+      // re-filtering on every validator invocation (pure win — zero cost at compile time)
+      const { hints, properties } = ast;
+      const req =
+        hints ?
+          hints.requiredKeys.map((k) => ({
+            key: k,
+            check: build(properties.find((p) => p.key === k).value),
+          }))
+        : properties
+            .filter((p) => !p.optional)
+            .map((p) => ({ key: p.key, check: build(p.value) }));
+      const opt =
+        hints ?
+          hints.optionalKeys.map((k) => ({
+            key: k,
+            check: build(properties.find((p) => p.key === k).value),
+          }))
+        : properties
+            .filter((p) => p.optional)
+            .map((p) => ({ key: p.key, check: build(p.value) }));
+
+      const reqLen = req.length;
+      const optLen = opt.length;
+
+      return (v, opts) => {
+        if (typeof v !== 'object' || v === null || Array.isArray(v))
+          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;
+        }
+        for (let i = 0; i < optLen; i++) {
+          const p = opt[i];
+          if (p.key in v && v[p.key] !== undefined && !p.check(v[p.key], opts))
+            return false;
+        }
+        return true;
+      };
+    }
+
+    default:
+      return () => false;
+  }
+}