@weipertda/sigiljs 0.0.3 → 0.2.0

package/docs/exact-mode.md

@@ -0,0 +1,82 @@
+# Exact Mode
+
+By default, SigilJS allows objects to have extra, undeclared properties. This is called **Normal Mode**. 
+
+If you want to strictly reject any undeclared properties, you can use **Exact Mode** via `Sigil.exact`.
+
+## Normal Mode vs. Exact Mode
+
+### Normal Mode (Default)
+In normal mode, extra keys are ignored and permitted. This is useful when you only care about a subset of the fields in a payload (e.g. from an API response).
+
+```javascript
+import { Sigil } from "@antistructured/sigiljs";
+
+const User = Sigil`
+{
+  name: string
+}
+`;
+
+User.check({ name: "Dana" }); // true
+User.check({ name: "Dana", admin: true }); // true (extra keys are allowed)
+```
+
+### Exact Mode
+In exact mode, any undeclared keys are rejected, causing validation to fail.
+
+```javascript
+const StrictUser = Sigil.exact`
+{
+  name: string
+}
+`;
+
+StrictUser.check({ name: "Dana" }); // true
+StrictUser.check({ name: "Dana", admin: true }); // false (extra keys are rejected!)
+```
+
+## Nested Exact Objects
+
+Exactness is applied globally to nested objects defined within a `Sigil.exact` block.
+
+```javascript
+const StrictOrder = Sigil.exact`
+{
+  id: string
+  customer: {
+    name: string
+  }
+}
+`;
+
+// Fails validation because of the extra "email" key inside the nested customer object
+StrictOrder.check({
+  id: "order_123",
+  customer: {
+    name: "Dana",
+    email: "dana@example.com"
+  }
+}); // false
+```
+
+## Validation Errors
+
+When a validation fails in exact mode due to an unexpected property, the assertion error reports exactly which property was unexpected:
+
+```javascript
+try {
+  StrictUser.assert({ name: "Dana", admin: true });
+} catch (error) {
+  console.log(error.toJSON());
+  /*
+  {
+    code: "SIGIL_VALIDATION_FAILED",
+    message: "Unexpected property \"admin\"",
+    path: ["admin"],
+    expected: "undefined",
+    actual: "boolean"
+  }
+  */
+}
+```

package/docs/examples.md

@@ -0,0 +1,92 @@
+# Examples
+
+SigilJS is useful anywhere JavaScript interacts with unknown data.
+
+Common use cases:
+
+- API response validation
+- Request body validation
+- Configuration files
+- CLI tools
+- JSON parsing
+- Database results
+
+---
+
+## API Response Validation
+
+```javascript
+
+const ApiResponse = Sigil`
+{
+  user: {
+    id: string
+    email: string
+  }
+}
+`
+
+ApiResponse.assert(await response.json())
+
+```
+
+---
+
+## Config Validation
+
+```javascript
+
+const Config = Sigil`
+{
+  port: number
+  host: string
+  debug?: boolean
+}
+`
+
+Config.assert(JSON.parse(configFile))
+
+```
+
+---
+
+## Request Validation
+
+```javascript
+
+const LoginRequest = Sigil`
+{
+  email: string
+  password: string
+}
+`
+
+LoginRequest.assert(req.body)
+
+```
+
+---
+
+## Validation Methods
+
+Each sigil provides two validation methods.
+
+### check()
+
+Returns a boolean.
+
+```javascript
+
+User.check(data)
+
+```
+
+### assert()
+
+Throws an error if validation fails.
+
+```javascript
+
+User.assert(data)
+
+```

package/docs/introduction.md

@@ -0,0 +1,29 @@
+# Introduction
+
+JavaScript programs constantly deal with data.
+
+* API responses.
+* User input.
+* Configuration files.
+* Database records.
+* JSON payloads.
+
+And the most common question we need to answer is simple:
+
+>"Does this data actually match what I expect?"
+
+JavaScript gives us very few tools to answer that question.
+
+` typeof ` is inconsistent:
+
+```javascript
+
+typeof [] // "object"
+
+```
+
+And TypeScript types disappear completely once the code runs.
+
+SigilJS solves the runtime side of the problem.
+
+Instead of writing complex validation logic, you describe the shape of your data using a **sigil**, then validate values against it.

package/docs/license.md

@@ -0,0 +1,23 @@
+# License
+
+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/docs/named-sigils.md

@@ -0,0 +1,93 @@
+# Named Sigils & Composition
+
+As your application grows, you will want to reuse sigil definitions, compose larger schemas from smaller pieces, and support self-referential or circular schemas. SigilJS supports this via **Named Sigils** created with `Sigil.define` (or its alias `Sigil.named`).
+
+## Defining a Reusable Sigil
+
+You register a named sigil globally by passing a unique name to `Sigil.define`:
+
+```javascript
+import { Sigil } from "@antistructured/sigiljs";
+
+// Register the "Email" sigil
+const Email = Sigil.define("Email")`string`;
+```
+
+Once defined, you can reference `Email` directly by name inside any other Sigil's template string:
+
+```javascript
+const User = Sigil`
+{
+  name: string
+  email: Email
+}
+`;
+
+User.check({
+  name: "Charlie",
+  email: "charlie@example.com"
+}); // true
+```
+
+## Schema Composition
+
+Composition allows you to modularize your schema architecture:
+
+```javascript
+Sigil.define("Address")`
+{
+  street: string
+  city: string
+}
+`;
+
+const UserProfile = Sigil`
+{
+  name: string
+  billingAddress: Address
+  shippingAddress: Address
+}
+`;
+```
+
+## Self-Referential & Circular Schemas
+
+Named sigils allow you to define recursive models (like trees, folder hierarchies, or linked lists).
+
+Because references are resolved lazily at validation/compilation time, you can refer to a named sigil that has not yet been registered or refers to itself.
+
+```javascript
+// A Node has a name, and an optional list of child Nodes
+const Node = Sigil.define("Node")`
+{
+  name: string
+  children?: Node[]
+}
+`;
+
+Node.check({
+  name: "root",
+  children: [
+    { name: "src" },
+    {
+      name: "tests",
+      children: [
+        { name: "validate.test.js" }
+      ]
+    }
+  ]
+}); // true
+```
+
+## Registry Lifecycle
+
+Named sigils are stored in a global registry. When testing, you may want to reset the registry to prevent cross-test contamination:
+
+```javascript
+import { registry } from "@antistructured/sigiljs";
+
+// Clear all registered named sigils
+registry.clear();
+```
+
+Duplicate registrations follow a **last-write-wins** approach, meaning redefining a name will overwrite the previous definition.

package/docs/objects.md

@@ -0,0 +1,44 @@
+# Object Schemas
+
+SigilJS can describe full object structures.
+
+```javascript
+
+const User = Sigil`
+{
+  name: string
+  age: number
+}
+`
+
+```
+
+Example:
+
+```javascript
+
+User.check({
+  name: "Alex",
+  age: 30
+})
+
+```
+
+---
+
+## Nested Objects
+
+Sigils support nested structures.
+
+```javascript
+
+const Profile = Sigil`
+{
+  user: {
+    name: string
+    email: string
+  }
+}
+`
+
+```

package/docs/optional.md

@@ -0,0 +1,48 @@
+# Optional Values
+
+Use ` ? ` to allow ` undefined `.
+
+```javascript
+
+Sigil`string?`
+
+```
+
+This means the value can be:
+
+- a string
+- undefined
+
+Example:
+
+```javascript
+
+const MaybeName = Sigil`string?`
+
+MaybeName.check(undefined)
+
+```
+
+---
+
+## Optional Object Properties
+
+Optional object properties use ` ? ` after the property name.
+
+```javascript
+
+const User = Sigil`
+{
+  name: string
+  age?: number
+}
+`
+```
+
+Example:
+
+```javascript
+
+User.check({ name: "Alex" })
+
+```

package/docs/quickstart.md

@@ -0,0 +1,65 @@
+# Quickstart
+
+## Install
+
+Using Bun:
+
+```javascript
+
+bun add @antistructured/sigiljs
+
+```
+
+Using npm:
+
+```javascript
+
+npm install @antistructured/sigiljs
+
+```
+
+---
+
+## Create Your First Sigil
+
+```javascript
+
+import { Sigil } from "@antistructured/sigiljs"
+
+const Email = Sigil`string`
+
+```
+
+This sigil describes any string.
+
+---
+
+## Validate Data
+
+```javascript
+
+Email.check("hello@example.com")
+// true
+
+Email.check(42)
+// false
+
+```
+
+If you want validation to throw errors instead:
+
+```javascript
+
+try {
+  Email.assert(42)
+} catch (error) {
+  console.log(`
+  ${error.message}  // "Expected string, got number"
+  ${error.code}     // "SIGIL_VALIDATION_FAILED"
+  ${error.path}     // []
+  ${error.expected} // "string"
+  ${error.actual}   // "number"
+`)
+}
+
+```

package/docs/realtype.md

@@ -0,0 +1,36 @@
+# realType
+
+SigilJS includes ` realType() `, which improves on JavaScript's ` typeof `.
+
+```javascript
+
+import { realType } from "sigiljs"
+
+realType([])         // "array"
+realType(null)       // "null"
+realType(new Map())  // "map"
+realType(new Date()) // "date"
+
+```
+
+This is especially useful when building validation or debugging tools.
+
+## Custom Type Hooks
+
+You can supply custom override hooks to map instances of custom classes or objects back to nominal type strings. Hooks are checked before standard type resolution:
+
+```javascript
+import { realType } from "@antistructured/sigiljs";
+
+class MyCustomConnection {}
+
+const conn = new MyCustomConnection();
+
+const typeName = realType(conn, {
+  hooks: [
+    val => val instanceof MyCustomConnection ? 'connection' : null
+  ]
+});
+
+console.log(typeName); // "connection"
+```

package/docs/roadmap.md

@@ -0,0 +1,40 @@
+# SigilJS Project Roadmap
+
+This document outlines the milestones and roadmap towards a stable `v1.0.0` release.
+
+---
+
+## v0.0.x: Foundations & Groundwork [Completed]
+*   [x] **Parser Stability**: Robust tokenization and AST parsing for basic types, nested objects, optionals, and arrays.
+*   [x] **Documentation Hub**: Reference manuals for core features.
+*   [x] **Examples & Playground**: CLI utility for testing type expressions.
+*   [x] **Packaging & Project Hygiene**: Clean npm/Bun packages with zero runtime dependencies.
+
+---
+
+## v0.1.x: Compiler & Path-Aware Diagnostics [Completed / Current]
+*   [x] **Compiled Validators**: High-performance pipeline compiled to optimized JS closures, bypassing AST lookups on validation paths.
+*   [x] **Exact Object Mode**: Recursive support for strict object schema verification.
+*   [x] **Reusable Named Sigils**: Composable, registered types with support for recursive/circular schemas.
+*   [x] **Stronger Assert Errors**: Fully path-aware diagnostic exceptions (`SigilValidationError`) indicating exact paths (`["user", "age"]`) and types (`expected`/`actual`).
+
+---
+
+## v0.2.x: Advanced Composition & Registry Tools [Next Focus]
+*   [ ] **Named Sigil Collections**: Grouping/importing collections of custom types to easily share domain vocabularies.
+*   [ ] **Better Composition API**: Fluent operators for extending and modifying existing sigils.
+*   [ ] **Canonical Schema Caching**: Global structural canonicalization cache for deduplicating syntactically identical sigils across different packages.
+
+---
+
+## v0.3.x: CLI Upgrades & Optimization Hot-Paths
+*   [x] **Benchmark Suite**: Establish comparative execution times against Zod and handwritten Javascript.
+*   [ ] **CLI Enhancements**: Enhanced formatting and interactive modes for the playground binary.
+*   [ ] **V8 Optimizer Alignment**: Fine-tune code-generation functions to maximize JIT compiler inline caching.
+
+---
+
+## v1.0.0: Production-Ready Release
+*   [ ] **Stable Grammar & AST Spec**: Lock the DSL grammar rules against breaking additions.
+*   [ ] **API Freeze**: Lock core exports (`Sigil`, `S`, `T`, `realType`) and instance methods.
+*   [ ] **Extensive Stress-Testing**: End-to-end production verification.

package/docs/sigils.md

@@ -0,0 +1,94 @@
+# Sigils
+
+A **sigil** is a small expression that describes what data should look like.
+
+Sigils are written using a tagged template:
+
+```javascript
+
+Sigil`string`
+
+```
+
+Sigils compile into fast runtime validators.
+
+---
+
+## Primitive Types
+
+SigilJS supports common JavaScript primitives.
+
+```javascript
+
+Sigil`string`
+Sigil`number`
+Sigil`boolean`
+Sigil`bigint`
+Sigil`symbol`
+Sigil`null`
+Sigil`undefined`
+
+```
+
+Example:
+
+```javascript
+
+const Name = Sigil`string`
+
+Name.check("Alex")
+
+```
+
+---
+
+## The Sigil Mental Model
+
+The easiest way to think about SigilJS is:
+
+A **sigil is a blueprint for data**.
+
+Example blueprint:
+
+```javascript
+
+const User = Sigil`
+{
+  name: string
+  age?: number
+}
+`
+
+```
+
+You can then **cast the sigil** against real values.
+
+```javascript
+
+User.check(data)
+
+```
+
+---
+
+## API Aliases: `Sigil`, `S`, and `T`
+
+To accommodate different developer preferences, SigilJS exports three aliases for the template tag:
+
+1. **`Sigil` (Recommended for clarity)**: The standard and most descriptive import. Perfect for public APIs, shared utilities, or when team readability is the priority.
+   ```javascript
+   import { Sigil } from "@antistructured/sigiljs";
+   const User = Sigil`{ name: string }`;
+   ```
+
+2. **`S` (Recommended shorthand)**: A single-letter shorthand that feels like standard types or schemas. Great for reducing boilerplate in inline declarations.
+   ```javascript
+   import { S } from "@antistructured/sigiljs";
+   const User = S`{ name: string }`;
+   ```
+
+3. **`T` (Legacy/Optional)**: Kept strictly for backwards compatibility with earlier versions. We recommend using `Sigil` or `S` in new codebases.
+   ```javascript
+   import { T } from "@antistructured/sigiljs";
+   const User = T`{ name: string }`;
+   ```

package/examples/api-response.js

@@ -0,0 +1,21 @@
+import { Sigil } from '../src/index.js'
+
+const ApiResponse = Sigil`
+{
+  user: {
+    id: string
+    email: string
+  }
+}
+`
+
+async function main() {
+  const response = await fetch("https://example.com/api/user")
+  const data = await response.json()
+
+  ApiResponse.assert(data)
+
+  console.log("Valid response")
+}
+
+main()

package/examples/api-response.md

@@ -0,0 +1,27 @@
+# [examples/api-response.js](https://github.dev/weipertda/sigiljs/blob/main/examples/scripts/api-response.js)
+
+```javascript
+
+import { Sigil } from "../src/index.js"
+
+const ApiResponse = Sigil`
+{
+  user: {
+    id: string
+    email: string
+  }
+}
+`
+
+async function main() {
+  const response = await fetch("https://example.com/api/user")
+  const data = await response.json()
+
+  ApiResponse.assert(data)
+
+  console.log("Valid response")
+}
+
+main()
+
+```