Write types. Validate reality.

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.

bun add @weipertda/sigiljs

– or –

npm install @weipertda/sigiljs

import { Sigil } from "@weipertda/sigiljs"

const Email = Sigil`string`

Email.check("hello@example.com")
// true

Email.check(42)
// false

Use ? to mark optional values.

const MaybeName = Sigil`string?`

Matches:

string
undefined

const Tags = Sigil`string[]`

Tags.check(["js", "bun"])
// true

const ID = Sigil`string | number`

Matches either type.

const User = Sigil`
{
  name: string
  age?: number
}
`

Optional properties use ?.

const Order = Sigil`
{
  id: string
  customer: {
    name: string
    email: string
  }
  items: {
    name: string
    price: number
  }[]
}
`

SigilJS also provides a better typeof.

import { realType } from "@weipertda/sigiljs"

realType([])        // "array"
realType(null)      // "null"
realType(new Map()) // "map"

Sigil cleanly solves four problems:

1. JavaScript's native typeof is inconsistent and too weak for real type work.

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 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.

Replacing the gaps in typeof — realType correctly identifies null, NaN, arrays, async and generator functions, maps, sets, and arbitrary custom classes through hooks.

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:

realType(myThing, {
  hooks: [ v => v instanceof MyThing ? 'mything' : null ]
}); // "mything"

SigilJS solves runtime type validation with a tiny, dependency-free, runtime-native type system.

See the docs/ folder for full, detailed documentation (WIP).

See the examples/ folder for runnable examples (WIP).

MIT

You can securely test out Sigil validator schemas against JSON inputs directly from your shell:

bun run src/playground.js '{"name": "Doug"}' '{name: string, age?: number}'
# ✅ Validation passed

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.