Skip to content

Home

Jump to bottom
D edited this page Jun 20, 2026 · 3 revisions

SigilJS Wiki

Welcome to the SigilJS Wiki.

SigilJS is an early-stage JavaScript project focused on one core idea:

Executable data contracts for JavaScript.

The goal is to let developers define structure once, then use that structure to validate, parse, transform, describe, and project runtime data across real application boundaries.

Define structure once. Project it everywhere.

What is SigilJS?

SigilJS is a runtime contract system for JavaScript.

A sigil is a contract object. It describes the structure of data, but it is also executable. That means a sigil can be used by your program to enforce runtime expectations, normalize data, generate structural projections, and eventually support contract lifecycle workflows.

A schema describes data. A contract enforces data. An executable contract can define, enforce, transform, and project data.

That's the direction of SigilJS.

Core Concept

Most JavaScript applications interact with data that does not originate inside the application itself.

Data enters through boundaries:

  • API requests
  • API responses
  • Config files
  • Database reads
  • Database writes
  • Forms
  • Events
  • Queues
  • Webhooks
  • Plugin systems
  • Local storage
  • AI tool calls
  • LLM structured outputs

SigilJS is designed to sit at those boundaries.

The idea is relatively simple:

Unknown data → Sigil contract → Trusted runtime data

Basic Example

import { sigil, optional, oneOf, union } from '@weipertda/sigiljs';

const User = sigil.exact({
  id: union(String, Number),
  name: String,
  role: oneOf('admin', 'user'),
  age: optional(Number)
});

const result = User.safeParse({
  id: 1,
  name: 'Alex',
  role: 'admin'
});

if (result.success) {
  console.log(result.data)
} else {
  console.error(result.error)
}

In the above example, User isn't just a validator. It's a contract object.

It can enforce structure at runtime and, as the project evolves, project that structure into other representations.

The Four Pillars

SigilJS is organized around four pillars.

1. Define

Declare structure in JavaScript.

const User = sigil({
  id: Number,
  name: String
});

The goal is to keep structure definitions readable, direct, and JavaScript-native.

2. Enforce

Validate and parse runtime data.

User.check(input);
User.parse(input);
User.safeParse(input);
User.assert(input);

Enforcement turns unknown data into trusted runtime data.

3. Transform

Normalize data into a trusted shape.

User.transform(input);
User.serialize(user);

Transformation is when a contract can prepare data for use inside an application or for output across another boundary.

4. Project

Generate other structural representations.

User.describe();
User.toJSONSchema();
User.toTypeScript();
User.toOpenAPI();

Projection is what turns SigilJS from a validation tool into a contract system.

Without projection, SigilJS would only check data. But with projection, a single contract can become the source of truth for runtime checks, documentation, generated types, API descriptions, test fixtures, and future integrations.

Why Executable Data Contracts?

JavaScript has always had a gap between expected data and actual runtime data. TypeScript helps with this during development, but its types don't enforce external data at runtime.

SigilJS also focuses on the runtime side of the problem.

It asks:

What if the structure your program expects could exist as an executable object at runtime?

That object could then be used to:

  • Validate input
  • Parse unknown data
  • Produce helpful errors
  • Normalize values
  • Describe itself
  • Generate JSON Schema
  • Generate TypeScript definitions
  • Generate OpenAPI-compatible structures
  • Compare contract versions
  • Support boundary-specific workflows
  • Help validate AI structured outputs

That's the broader goal.

Current Package

SigilJS is currently published as:

bun add @weipertda/sigiljs

or:

npm install @weipertda/sigiljs

Example import:

import { sigil } from '@weipertda/sigiljs';

The public brand is SigilJS.

The current npm package is @weipertda/sigiljs.

Future package extraction may happen later if the projection boundaries stabilize, but SigilJS currently remains a single package.

Current Status

SigilJS is early.

The project is moving quickly, and APIs may still evolve before 1.0.0.

The current focus is:

  • Stabilizing the contract object model
  • Strengthening runtime enforcement
  • Improving projection behavior
  • Documenting boundary use cases
  • Keeping the package small and dependency-free
  • Proving the category of executable data contracts

SigilJS vs Existing Tools

SigilJS is not intended to attack or replace existing tools outright. Libraries like Zod are mature, excellent, and widely used. SigilJS is exploring a different center of gravity.

Zod: Builder-style validation API SigilJS: Executable contract objects with projection as a core goal

The difference is not only syntax. The deeper goal is making contracts active runtime objects that can define, enforce, transform, project, and eventually participate in contract lifecycle workflows.

Useful Boundary Examples

SigilJS is intended to be useful anywhere data crosses a boundary.

Examples:

API Request

const CreateUserRequest = sigil.exact({
  name: String,
  email: String,
  role: oneOf('admin', 'user')
});

const body = CreateUserRequest.parse(requestBody);

API Response

const UserResponse = sigil({
  id: String,
  name: String,
  email: String
});

const user = UserResponse.parse(await response.json());

Config File

const Config = sigil.exact({
  port: Number,
  host: String,
  debug: optional(Boolean)
});

const config = Config.parse(JSON.parse(configText));

AI Structured Output

const LeadIntent = sigil.exact({
  name: String,
  email: String,
  urgency: oneOf('low', 'medium', 'high'),
  summary: String
});

const lead = LeadIntent.parse(llmOutput);

AI-structured outputs are an especially interesting boundary because LLMs often produce uncertain structured data.

SigilJS can help turn uncertain AI output into trusted runtime objects.

Project Direction

The long-term direction is:

Define → Enforce → Transform → Project

Potential future areas include:

  • Stronger projection support
  • Contract diffs
  • Generated test fixtures
  • Form constraints
  • HTTP request/response helpers
  • AI structured-output helpers
  • CLI workflows
  • Package extraction when stable

Possible future package shape:

@sigil/core
@sigil/json-schema
@sigil/ts
@sigil/openapi
@sigil/forms
@sigil/ai
@sigil/http
@sigil/testing
@sigil/cli

These packages do not exist yet.

They represent a possible future ecosystem if the core contract model proves stable enough to justify splitting.

Design Principles

SigilJS should remain:

  • JavaScript-native
  • Runtime-first
  • Small
  • Dependency-free at runtime
  • Readable
  • Projection-oriented
  • Boundary-focused
  • Honest about what it can and cannot guarantee

The project should avoid becoming bloated or magical. The goal is not to hide runtime uncertainty. The goal is to make runtime uncertainty explicit, enforceable, and useful.

Contributing Ideas

Good areas for feedback include:

  • API design
  • Contract object behavior
  • Error shape
  • Projection output
  • Boundary examples
  • TypeScript generation
  • OpenAPI behavior
  • JSON Schema behavior
  • AI structured output use cases
  • CLI workflows
  • Naming and positioning

If you are interested in the idea of executable data contracts for JavaScript, discussions, issues, examples, and critique are welcome.

Summary

SigilJS is an attempt to give JavaScript a clear runtime contract layer.

Not just types. Not just schemas. Not just validation.

Executable contracts for the data that crosses real system boundaries.

Define structure once.
Enforce it at runtime.
Transform it into trusted shape.
Project it everywhere.

Clone this wiki locally