spec.js

A runtime validation and assertion library.

Define executable specifications from types, shapes, and predicates. The library validates without coercion or transformation; it does not provide schema serialization, compilation, masking, or timeouts.

Why

Executable schema reference: Document data shapes, pinpoint breaking changes, and catch unexpected or missing values early.

System invariant checks: Use runtime assertions to stop when program state violates a contract.

Inspired by Clojure Spec and TigerStyle.

Quick Start

import { spec, t } from './spec.js';

// Define a schema using composable validators
const configSchema = spec({
  server: {
    host: t.string,
    port: t.number.min(1).max(65535)
  },
  database: t.optional({
    urls: [t.string],          // Repeating array
    retries: t.number.and(n => n >= 0)
  })
});

// 1. INSPECTION (diff)
const badData = { server: { host: 'localhost', port: '8080' } }; // port is string!
const mismatch = configSchema.diff(badData);

if (mismatch) {
  console.log(mismatch.displayPath); // ".server.port"
  console.log(mismatch.kind);        // "type"
}

// 2. ENFORCEMENT (assert)
const validData = { server: { host: 'localhost', port: 8080 } };
const config = configSchema.assert(validData); // Returns data safely

Edge runtimes and serverless environments.

spec.js is incidentally also a good fit for cloud functions.

• Low bundle size
• Fast startup (no compilation to native code)
• Fail fast - halts on first error

Non-goals

• Coercion
  • No defaults, not transformations.
• FE client validation
  • Returns the first error only, not all errors, ergo not suitable for browser-autofill multi-validation.
  • Doesn't include a plethora of validation utils.
• Server-side request validation -
  • Performance: Specs are thunks, not compiled ahead of time. Technically not the fastest way possible, but practically fast enough for most use cases.
  • Security: It's up to you to defend against ReDOS (regex denial of service), remember to check .max() lengths, and to configure your proxy/load balancer to reject oversized requests.
  • Privacy: No masking.

Documentation

To get to know spec.js completely, check out the guides below:

• Step-by-Step Walkthrough — A comprehensive introduction to all APIs, safety behaviors, and quirks.
• Background & Philosophy — The rationale, Clojure's Spec/TigerStyle inspirations, and the design behind the project.
• Design Decisions — Architectural tradeoffs, uncompiled closures (thunks), and open validation.
• Idea Bucket — Scratchpad of ideas, possible upcoming features, and what is intentionally left out of the library.

Installation

Copy spec.js into your project to use this repository's current version, or install the published tigerspec package. Published releases may lag this repository.

Maintainer release instructions are in npm/README.md.