@weipertda/sigiljs 0.0.3 → 0.2.0

package/README.md

@@ -2,260 +2,262 @@
 
 Write types. Validate reality.
 
-## What is SigilJS?
+SigilJS is a tiny, dependency-free JavaScript library for describing and validating data shapes using **sigils** (inline type expressions).
 
-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.
+No TypeScript compiler, no heavy schemas, and zero runtime dependencies. Just write your types as strings, and SigilJS compiles them into blazingly fast validator functions.
 
 ---
 
 ## Installation
 
+Install using **Bun**:
 ```bash
-
-bun add @weipertda/sigiljs
-
+bun add @antistructured/sigiljs
 ```
 
-– or –
-
+Or using **npm**:
 ```bash
-
-npm install @weipertda/sigiljs
-
+npm install @antistructured/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:
+## Quick Example
 
 ```javascript
+import { Sigil } from "@antistructured/sigiljs";
 
-string
-undefined
-
+// 1. Define your data schema using backticks
+const User = Sigil`
+{
+  name: string
+  age?: number
+  tags: string[]
+}
+`;
+
+// 2. Validate data shapes (returns boolean)
+User.check({
+  name: "Alice",
+  tags: ["admin", "dev"]
+}); // true
+
+User.check({
+  name: "Bob",
+  age: "thirty", // Wrong type!
+  tags: []
+}); // false
 ```
 
 ---
 
-### Arrays
-
-```javascript
-
-const Tags = Sigil`string[]`
+## Why SigilJS?
 
-Tags.check(["js", "bun"])
-// true
+JavaScript runtime type checking is notoriously fragile:
+1. `typeof` is notoriously weak and inconsistent (e.g., `typeof []` is `"object"`).
+2. TypeScript types completely disappear at runtime, leaving you vulnerable to invalid API responses, bad database loads, and malformed client payloads.
+3. Existing schema libraries (like Zod) require verbose builder chains and carry significant bundle sizes.
 
-```
+SigilJS solves this by giving you a **clean, string-based type DSL** that looks like standard TypeScript/flow but remains fully active and optimized at runtime.
 
 ---
 
-### Unions
-
-```javascript
+## Sigil vs Zod
 
-const ID = Sigil`string | number`
+If you have used validation libraries like Zod, you might wonder how SigilJS compares. Zod is a robust, highly expressive builder library with a powerful ecosystem. However, SigilJS approach is built on a different developer philosophy:
 
-```
+* **Zod** uses an **expressive builder API** to construct validation trees.
+* **SigilJS** uses **readable type expressions** that look like standard JavaScript/TypeScript types, compiled once into optimized runtime validator functions.
 
-Matches either type.
+### Side-by-Side Comparison
 
----
+```javascript
+// Zod: Constructing a schema using method-chaining builders
+import { z } from "zod";
 
-### Object Validation
+const UserZod = z.object({
+  name: z.string(),
+  age: z.number().optional()
+});
 
-```javascript
+// SigilJS: Writing natural, readable type expressions
+import { Sigil } from "@antistructured/sigiljs";
 
-const User = Sigil`
+const UserSigil = Sigil`
 {
   name: string
   age?: number
 }
-`
-
+`;
 ```
 
-Optional properties use ` ? `.
+| Feature | Zod | SigilJS |
+|---------|-----|---------|
+| **Philosophy** | Expressive builder API | Readable type expressions compiled to JS closures |
+| **Syntax** | Method chaining (`z.string().optional()`) | Standard inline type DSL (``Sigil`string?```) |
+| **Performance** | Runtime AST traversal | Compiled once to fast, cacheable validator functions |
+| **Recursive Schemas** | Verbose `z.lazy()` wrapper | Native, lazy resolution using Named Sigils |
+| **Bundle Size** | ~15-20kB gzipped | Tiny footprint (< 4kB), zero runtime dependencies |
 
 ---
 
-### Nested Objects
+## Core API
+
+SigilJS exports the core `Sigil` class, along with two convenient single-letter aliases: `S` (recommended shorthand) and `T` (legacy/optional alias).
 
 ```javascript
+import { Sigil, S, T, SigilValidationError } from "@antistructured/sigiljs";
 
-const Order = Sigil`
-{
-  id: string
-  customer: {
-    name: string
-    email: string
-  }
-  items: {
-    name: string
-    price: number
-  }[]
-}
-`
+// All three are identical:
+const schema1 = Sigil`string`;
+const schema2 = S`string`;
+const schema3 = T`string`;
+```
 
+### `.check(value)`
+Returns a boolean indicating if the value matches the schema.
+```javascript
+S`string`.check("hello"); // true
+S`string`.check(123);     // false
 ```
 
----
+### `.assert(value)`
+Validates the data, returning `true` on success. On failure, it throws a structured `SigilValidationError` containing detailed diagnostic information:
 
-### Runtime Type Detection
+```javascript
+try {
+  S`{ age: number }`.assert({ age: "thirty" });
+} catch (error) {
+  if (error instanceof SigilValidationError) {
+    console.log(error.code);     // "SIGIL_VALIDATION_FAILED"
+    console.log(error.message);  // "Expected property \"age\" to be number, got string"
+    console.log(error.path);     // ["age"]
+    console.log(error.expected); // "number"
+    console.log(error.actual);   // "string"
+  }
+}
+```
 
-SigilJS also provides a better ` typeof `.
+### Compiled Validators (`.validator` & `.compile()`)
+Sigils are parsed and compiled once. If you want to bypass the Sigil instance overhead entirely on ultra-hot paths, you can retrieve the stable pre-compiled validator closure:
 
 ```javascript
+const User = S`{ name: string }`;
 
-import { realType } from "@weipertda/sigiljs"
-
-realType([])        // "array"
-realType(null)      // "null"
-realType(new Map()) // "map"
+// Retrieve the pre-compiled function
+const validateUser = User.validator; // or User.compile()
 
+validateUser({ name: "Dana" }); // true
 ```
 
 ---
 
-## Why SigilJS?
-
-Sigil cleanly solves four problems:
+## Exact Mode
 
-1. JavaScript's native ` typeof ` is inconsistent and too weak for real type work.
+By default, SigilJS runs in **Normal Mode**, allowing objects to have extra undeclared keys. To enforce strict shape matches where extra properties are disallowed, use **Exact Mode** via `Sigil.exact` (or `S.exact` / `T.exact`).
 
 ```javascript
+// Normal Mode: allows extra keys
+const NormalUser = S`{ name: string }`;
+NormalUser.check({ name: "Dana", admin: true }); // true
 
-typeof []
-// "object" 😬
-
+// Exact Mode: rejects extra keys
+const ExactUser = S.exact`{ name: string }`;
+ExactUser.check({ name: "Dana", admin: true }); // false
 ```
 
-2. TypeScript solves mostly compile-time problems, often adds friction, and disappears at runtime.
+Exact mode rules apply recursively down nested objects defined inside the exact block.
 
-  * 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.
+## Named Sigils & Composition
 
-```typescript
+To build large, maintainable schemas or support self-referential/circular schemas, you can define globally-reusable named sigils using `Sigil.define` (or its alias `Sigil.named`).
 
-// TypeScript disappears at runtime
-const x: string = 123;
+```javascript
+// 1. Register a named sigil in the registry
+Sigil.define("Email")`string`;
 
-// No runtime error
+Sigil.define("Address")`
+{
+  street: string
+  city: string
+}
+`;
 
+// 2. Compose them into larger schemas by referring to them by name
+const User = S`
+{
+  name: string
+  email: Email
+  address: Address
+}
+`;
 ```
 
-3. Existing runtime validation libraries are dependency-heavy, allocation-happy, or ergonomically off.
+### Self-Referential / Recursive Schemas
+Since names are resolved lazily at validation/compilation time, schemas can reference themselves or each other circularly:
 
-4. JavaScript lacks a native-feeling type expression system for runtime truth.
+```javascript
+// Node references Node[]
+Sigil.define("Node")`
+{
+  name: string
+  children?: Node[]
+}
+`;
+```
 
 ---
 
-### Accurate Runtime Types
+## `realType()`
 
-Replacing the gaps in ` typeof ` — ` realType ` correctly identifies ` null `, ` NaN `, arrays, async and generator functions, maps, sets, and arbitrary custom classes through hooks.
+SigilJS includes `realType()`, an advanced runtime type-detector that resolves the shortcomings of JavaScript's `typeof`.
 
 ```javascript
+import { realType } from "@antistructured/sigiljs";
 
-import { realType } from '@weipertda/sigiljs';
-
-realType('x');                 // "string"
-realType(null);                // "null"
+realType("hello");             // "string"
+realType(42);                  // "number"
 realType(NaN);                 // "nan"
+realType(null);                // "null"
 realType([]);                  // "array"
 realType(new Map());           // "map"
-realType(async function() {}); // "asyncfunction"
-
+realType(async () => {});      // "asyncfunction"
+realType(function* () {});     // "generatorfunction"
 ```
 
-You can even provide custom override hooks to map instances directly back to nominal strings:
+### Custom Hooks
+You can supply custom override hooks to map instances of custom classes back to nominal type strings:
 
 ```javascript
-
-realType(myThing, {
-  hooks: [ v => v instanceof MyThing ? 'mything' : null ]
-}); // "mything"
-
+class DatabaseConnection {}
+const conn = new DatabaseConnection();
+
+realType(conn, {
+  hooks: [
+    val => val instanceof DatabaseConnection ? 'db_connection' : null
+  ]
+}); // "db_connection"
 ```
 
-SigilJS solves runtime type validation with a tiny, dependency-free, runtime-native type system.
-
 ---
 
-## Documentation
+## Examples
 
-See the [docs/](docs/README.md) folder for full, detailed documentation __(WIP)__.
+To see runnable patterns, CLI setups, and advanced test suites, check the [examples/](examples/) directory.
 
 ---
 
-## Examples
+## Roadmap
 
-See the [examples/](examples/) folder for runnable examples __(WIP)__.
+Upcoming additions to the SigilJS roadmap:
+- [ ] **Sigil.partial**: Construct partial sub-schemas dynamically.
+- [ ] **Format validation rules**: Regex support and common formats (e.g. uuid, ipv4).
+- [ ] **Schema migrations / transformers**: Parse and transform input types into mapped runtime types.
 
 ---
 
 ## 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/docs/README.md

@@ -0,0 +1,20 @@
+# SigilJS Documentation
+
+Welcome to the SigilJS documentation! Here you will find guides and specs covering all the core concepts and APIs of SigilJS.
+
+## Table of Contents
+
+- [Introduction](introduction.md) — Why SigilJS exists and the problems it solves.
+- [Quickstart](quickstart.md) — Get up and running in 60 seconds.
+- [Sigils](sigils.md) — The core concept of sigils and type blueprints.
+- [Object Schemas](objects.md) — Validating object key/value maps and nested objects.
+- [Arrays](arrays.md) — Working with array syntax, array-postfix operators, and nested arrays.
+- [Optional Fields](optional.md) — Handling optional properties and nullable fields.
+- [Exact Mode](exact-mode.md) — Rejecting extra properties on objects.
+- [Named Sigils & Composition](named-sigils.md) — Reusable schemas, composition, and circular references.
+- [Compiled Validators](compiled-validators.md) — The performance model and direct compiled validator reuse.
+- [realType()](realtype.md) — Deep runtime type-detection with support for custom hooks.
+- [CLI Playground](cli.md) — Testing schemas in your terminal.
+- [Examples](examples.md) — Concrete usage examples.
+- [Roadmap](roadmap.md) — Project milestones towards v1.0.0.
+- [Contributing](contributing.md) — Guidelines for contributing to SigilJS.

package/docs/arrays.md

@@ -0,0 +1,55 @@
+# Arrays
+
+Use ` [] ` to describe arrays.
+
+```javascript
+
+Sigil`number[]`
+
+```
+
+Example:
+
+```javascript
+
+const Scores = Sigil`number[]`
+
+Scores.check([10, 20, 30])
+
+```
+
+---
+
+Nested arrays are also supported.
+
+```javascript
+
+Sigil`string[][]`
+
+```
+
+---
+
+## Arrays of Objects
+
+```javascript
+
+const Orders = Sigil`
+{
+  id: string
+  items: {
+    name: string
+    price: number
+  }[]
+}
+`
+
+```
+
+Example:
+
+```javascript
+
+Orders.check(data)
+
+```

package/docs/cli.md

@@ -0,0 +1,48 @@
+# CLI Playground
+
+SigilJS comes with a CLI tool for experimenting with schemas and validating raw JSON data directly in your terminal.
+
+## Running the Playground
+
+You can run the playground script using Bun:
+
+```bash
+bun run src/playground/playground.js <json-data> <schema>
+```
+
+### Argument Format
+1. `<json-data>`: A valid JSON string representing the data you want to validate.
+2. `<schema>`: The Sigil validation schema string (omit the `Sigil` tag and backticks).
+
+## Examples
+
+### Valid Data
+
+```bash
+bun run src/playground/playground.js '{"name": "Alice", "age": 30}' '{ name: string, age?: number }'
+# Output:
+# ✅ Validation passed
+```
+
+### Invalid Data
+
+```bash
+bun run src/playground/playground.js '{"name": "Alice", "age": "thirty"}' '{ name: string, age?: number }'
+# Output:
+# ❌ Validation failed
+# Code: SIGIL_VALIDATION_FAILED
+# Message: Expected property "age" to be number, got string
+# Path: age
+# Expected: number
+# Actual: string
+```
+
+### Invalid JSON
+
+If the data argument is not valid JSON, the playground reports it:
+
+```bash
+bun run src/playground/playground.js 'invalid-json' '{ name: string }'
+# Output:
+# ❌ Error parsing JSON: Unexpected token i in JSON at position 0
+```

package/docs/compiled-validators.md

@@ -0,0 +1,42 @@
+# Compiled Validators
+
+Every Sigil is parsed and compiled once, then reused for all subsequent validations. This design ensures maximum performance and minimal runtime overhead.
+
+## How It Works
+
+When you create a Sigil using the template tag, SigilJS parses the type expression into an Abstract Syntax Tree (AST), normalizes it, and compiles it into an optimized validator function.
+
+This compiled validator is cached, meaning that repeated validations do not perform any string parsing, AST traversal, or tokenizing.
+
+```javascript
+import { Sigil } from "@antistructured/sigiljs";
+
+const User = Sigil`
+{
+  name: string
+  age: number
+}
+`;
+
+// Under the hood, this uses the cached, pre-compiled validator function
+User.check({ name: "Alice", age: 30 });
+```
+
+## Direct Validator Access
+
+If you need direct access to the compiled validator function, you can access the `.validator` property on any Sigil instance, or call `.compile()`. Both return the exact same function reference:
+
+```javascript
+const User = Sigil`{ name: string }`;
+
+// Retrieve the stable, compiled validator function
+const validateUser = User.validator;
+
+// Validate directly using the function
+const isValid = validateUser({ name: "Bob" }); // true
+
+// User.compile() returns the same cached reference
+console.log(User.validator === User.compile()); // true
+```
+
+By reusing the compiled validator reference, you bypass any intermediate Sigil object logic, achieving optimal execution speed.

package/docs/contributing.md

@@ -0,0 +1,43 @@
+# Contributing
+
+First off, thank you for considering contributing to SigilJS.
+
+## Local Development
+
+SigilJS uses [Bun](https://bun.sh) for package management and testing.
+
+1. Clone the repository:
+   ```bash
+
+   git clone https://github.com/weipertda/sigiljs.git
+   cd sigiljs
+
+   ```
+
+2. Install dependencies:
+
+   ```bash
+
+   bun install
+
+   ```
+
+3. Run the tests:
+
+   ```bash
+
+   bun test
+
+   ```
+
+## Pull Requests
+
+1. **Create a branch** for your feature or bugfix.
+2. **Write tests** that prove your bug was fixed or your feature works.
+3. **Format your code** using `bun run format`.
+4. **Ensure all tests pass** with `bun test`.
+5. Submit your PR with a clear description of the problem and your solution.
+
+## Code Style
+
+SigilJS keeps things simple and avoids dependencies where possible. If you're adding a feature, consider if it really belongs in the core library or if it can be built in user-land using existing sigils.