@hecto/schema

One typed schema, from development to standalone deployment.

@hecto/schema is a framework-neutral schema graph for authoring typed contracts, validating values, transforming or encoding at explicit boundaries, and exchanging JSON Schema. The product promise is one immutable schema used in three stable beta modes:

| Mode | Declared status | Use it for | | --- | --- | --- | | Interpreted | Stable | Immediate parsing, checking, encoding, and development feedback. | | Prepared | Stable | Reusable execution under a strict CSP; preparation is the default compiled backend. | | Standalone generated | Stable for its declared capability subset | Node-only generation of ESM validators whose manifest declares no authoring-runtime dependency. | | JIT | Experimental only | An explicit research boundary selected with { backend: 'jit' }; no speed or production claim. |

“Stable” here is the declared beta mode boundary, not a release or runtime certification. As of 2026-09-08, source review is complete for this snapshot; package checks, runtime checks, backend equivalence, CSP probes, generated consumer checks, declarations, release readiness, and publication are UNVERIFIED.

Install

When the package is available from your registry (UNVERIFIED), install it with:

pnpm add @hecto/schema

The package manifest declares Node 22 or newer for Node usage. Registry availability and a published artifact are UNVERIFIED.

Getting started

The shortest path is: define a schema, infer its input and output types, call safeParse, and inspect the issues without throwing.

import {
  defaulted,
  integer,
  object,
  safeParse,
  string,
} from '@hecto/schema'
import type { Input, Output } from '@hecto/schema'

const Settings = object({
  name: string({ minLength: 1 }),
  retries: defaulted(integer({ minimum: 0 }), 3),
})

type SettingsInput = Input<typeof Settings>
type SettingsOutput = Output<typeof Settings>

const input: SettingsInput = { name: 'worker' }
const result = safeParse(Settings, input)

if (result._tag === 0) {
  for (const problem of result.error.issues) {
    console.error(problem.path, problem.message)
  }
} else {
  const settings: SettingsOutput = result.value
  console.log(settings.retries)
}

defaulted makes retries optional in the input and present in the parsed output. safeParse returns a Result; parse is the throwing counterpart. Use safeParseAsync or parseAsync for a schema with an asynchronous effect. The source-level type and error contracts are reviewed; actual parsing and type test results are UNVERIFIED.

Prepared execution under CSP

Use the compile entry point when the same schema will be executed repeatedly. The prepared backend is the default; the explicit option below makes the CSP boundary visible in copied examples.

import { object, string } from '@hecto/schema'
import { compile } from '@hecto/schema/compile'

const Request = object({
  requestId: string({ minLength: 1 }),
})

const prepared = compile(Request, { backend: 'prepared' })
const result = prepared.safeParse({ requestId: 'req_123' })

The prepared source path captures an immutable plan and does not use eval, a Function constructor, dynamic import, or source generation. CSP execution, result equivalence, and browser behavior are UNVERIFIED.

Standalone generated validation

The Node-only codegen entry point emits a self-contained ESM validator for a closed, synchronous schema subset. Use explicit import bindings for runtime callbacks; unsupported graphs return structured diagnostics.

import { integer, object, string } from '@hecto/schema'
import { emitStandalone } from '@hecto/schema/codegen'

const StandaloneSettings = object({
  name: string({ minLength: 1 }),
  retries: integer({ minimum: 0 }),
})

const generated = emitStandalone(StandaloneSettings, {
  moduleName: 'settings-validator',
})

if (generated._tag === 0) {
  console.error(generated.error)
} else {
  // This import executes generated ESM, not @hecto/schema.
  const validator = await import(
    `data:text/javascript,${encodeURIComponent(generated.value.source)}`
  )
  const result = validator.safeParse({ name: 'worker', retries: 2 })
  console.log(result._tag === 1)
}

The generated manifest declares format: 'esm', async: false, and authoringRuntime: false. Generation, clean-consumer execution, and the absence of the authoring package at runtime are UNVERIFIED. Use writeStandalone when the source, declaration, and manifest should be written to disk. Code generation does not claim support for every effect, callback, native value, or JSON Schema feature.

JIT is experimental

JIT is never selected implicitly:

import { object, string } from '@hecto/schema'
import { compile } from '@hecto/schema/compile'

const schema = object({ id: string() })
const experimental = compile(schema, { backend: 'jit' })

The source reports a SchemaCompileError when executable-source construction is unavailable and does not silently fall back to prepared execution. JIT speed, production suitability, and CSP behavior are UNVERIFIED; this mode is not part of the stable product promise.

The code that generates source (the structural lowerer) is a lazy chunk. Load it once with await loadJit() (exported from the package root and from @hecto/schema/compile); compile() itself stays synchronous:

• default backend: execution.output reports prepared with reason Structural lowerer is not loaded; await loadJit() until the load resolves, and the same compiled instance (cached or not) serves the generated output program afterwards — nothing is pinned.
• { backend: 'jit' } before the load: the interpreter dispatch with that fallback, and the compilation is not cached, so a compile after the load specializes.
• { backend: 'aot' } never needs the lowerer to run. An artifact's staleness check against the current schema runs at compile time once the lowerer is loaded; before that it is deferred to loadJit(), which rejects with Stale AOT schema executor|output program; regenerate its artifact.

Public entry points

The package manifest declares these public imports:

• @hecto/schema — authoring, runtime, types, issues, metadata, and Standard Schema helpers.
• @hecto/schema/json-schema — JSON Schema import, evaluation, export, profiles, and diagnostics.
• @hecto/schema/compile — prepared-by-default and explicit JIT compilation.
• @hecto/schema/codegen — Node-only standalone ESM emission and writing.
• @hecto/schema/formats — conservative built-in formats and caller-owned registries.

Examples in this README use only those public package entries (plus generated artifacts). Site guides cover object policies, effects and codecs, async validation, JSON Schema profiles, consumer boundaries, and Zod/TypeBox migration. Declaration resolution, documentation checks, packed consumers, and publication remain UNVERIFIED.