TypeSea

   TypeScript Dependencies Tree-shakeable Side-effect free No dependencies Module Node

TypeSea is a zero-runtime-dependency TypeScript runtime narrowing library built around immutable guards, optimized Sea-of-Nodes validation plans, runtime compilation, and AOT source generation.

Benchmark Headline

Latest committed local benchmark on 2026-07-06 KST: npm run bench:record, median of 3 full runs, strict-object contract, operations per second on one machine. The chart is generated from [bench/results/latest.json](./bench/results/latest.json).

TypeSea safe compiled validators are already in Ajv's boolean hot-path class while keeping descriptor-based hostile-input semantics. Unsafe and unchecked FastMode are the bragging-rights path for trusted normalized data: direct field loads, allocation-light strict-key loops, and V8-friendly monomorphic codegen.

Goal: not "probably valid", but provably parity-tested validation that never executes user code, never throws on expected failures, and never leaks mutable state across a public boundary.

---

Why

Many validation libraries fall short when you care about:

• untrusted input that fights back (getters with side effects, prototype

pollution keys, forged schema objects, revoked proxies)

• identical verdicts across execution strategies (runtime plan vs compiled

vs AOT-generated validators)

• diagnostics without exceptions (Result values instead of throw)
• immutability at every public boundary

TypeSea focuses on:

• no user-code execution during validation
• runtime plan / compiled / AOT parity, enforced by a seeded generative fuzzer
• injection-safe code generation (side tables, never string interpolation)
• explicit presence semantics (optional vs undefinedable)

---

Key Properties

• Zero dependencies: no runtime, peer, optional, or bundled dependencies —

mechanically enforced by package policy before every release.

• Three engines, one semantics: is()/check() execute a cached validation

plan, compile() emits runtime predicates from optimized IR, and emitAotModule() emits standalone validator source. The runtime plan owns both the graph and a schema-specialized kernel, so the graph is the source of truth for generated validators without forcing ordinary is() through a per-node interpreter. Parity is fuzz-tested with sparse arrays, accessor properties, symbol keys, and non-enumerable extras included.

• Frozen public surface: guards, schemas, graphs, diagnostics, and JSON

Schema payloads are frozen before they cross an API boundary.

• Lossless-only export: JSON Schema and AOT export succeed only when no

semantics would be lost; runtime-only contracts return typed issues instead of silently weakening the schema.

---

Quick Start

import { compile, t, toJsonSchema, type Infer } from "typesea";

const User = t.strictObject({
  id: t.string.uuid(),
  email: t.string.email(),
  age: t.number.int().nonnegative(),
  role: t.enum(["admin", "user"]),
  tags: t.array(t.string.min(1)).max(8)
});

type User = Infer<typeof User>;

// 1) Boolean narrowing — avoids diagnostic allocation on success
if (User.is(input)) {
  input.id; // narrowed
}

// 2) Immutable diagnostics — frozen Result, never throws on expected failure
const checked = User.check(input);
if (!checked.ok) {
  console.log(checked.error); // frozen issue list with paths
}

// 3) Hot path — generated validator code
const FastUser = compile(User, { name: "isUser" });

// 4) Interop — lossless-only JSON Schema export
const schema = toJsonSchema(User);

Use is() for the allocation-light boolean path. Use check() when callers need the full immutable diagnostic list, or checkFirst() when a hot rejection path only needs one machine-readable issue. Use compile() or emitAotModule() when a stable schema is hot enough to deserve generated validator code. Compiled and AOT checkFirst() use a dedicated first-fault collector instead of building the full issue list and slicing it afterward.

Cold Starts, Fail-Fast, And Large Payloads

import {
  compileAsync,
  compileBoolean,
  compileCached,
  createTypeSeaVitePlugin,
  warmup
} from "typesea";

const FastUser = compileCached("user:v1", () => User, { name: "isUser" });
const BooleanUser = compileBoolean(User, { name: "isUserBoolean" });
const AsyncUsers = compileAsync(t.array(User), {
  name: "isUsersAsync",
  yieldEvery: 4096,
  yieldTimeout: 5
});

warmup([User, { key: "user:v1", guard: User, options: { name: "isUser" } }]);

export default createTypeSeaVitePlugin({
  entries: [{ id: "user:v1", guard: User, options: { name: "isUser" } }],
  transformCompileCached: true
});

Use compileCached() when schema construction might otherwise happen inside a request handler. It caches by caller-owned semantic keys, so cold-start work can be paid once and reused deliberately. compile() also caches repeated calls for the same guard instance, and development builds warn when repeated codegen comes from the same callsite.

Use warmup() in Lambda/serverless module scope or service startup to prefill compiled guards before the first request. Use compileBoolean() when a hot path only needs true/false; it emits no diagnostic collectors at all. Use compileAsync() or isAsync() for huge arrays, records, maps, sets, or object graphs that should yield back to the Node.js event loop between validation chunks.

The zero-dependency AOT plugin helpers expose Rollup, Vite, and esbuild compatible plugin objects. All three can rewrite static compileCached("id", ...) calls into imports from typesea:aot/<id> when the entry is listed in the plugin config. esbuild reads source through an optional readFile hook or a dynamic node:fs/promises import inside setup().

Unsafe FastMode

const FastButLooseUser = compile(User, {
  name: "isUserFast",
  mode: "unsafe"
});

const FastTrustedShapeUser = compile(User, {
  name: "isUserTrustedShape",
  mode: "unchecked"
});

compile(..., { mode: "unsafe" }) and emitAotModule(..., { mode: "unsafe" }) emit the V8-friendliest predicate TypeSea can generate: required object fields are read with direct bracket access, arrays and tuples use direct indexed loads, discriminants avoid descriptor reads, and strict-object extras are checked with an allocation-free for...in loop. This mode is for trusted, already-normalized data on extremely hot paths.

The default is still mode: "safe". Unsafe mode may execute getters, may accept prototype-backed values, and strict objects do not reject symbol or non-enumerable extras. Use it only when the caller owns the object graph or has already normalized input into plain data records. Unsafe generated predicates may also embed escaped static property keys directly in source so V8 can use ordinary property-load inline caches.

mode: "unchecked" goes one step further: it trusts the object shape and skips strict extra-key loops entirely. That is the fastest path for already-owned DTOs, but strict objects no longer reject any extra keys.

In unsafe and unchecked modes, successful compiled check() calls return a raw { ok: true, value } object instead of freezing the success result. Failed diagnostics are still frozen. Safe mode keeps the fully frozen Result contract. FastMode diagnostic collectors also use the same trusted direct-read object shape where possible, so their issue codes can be less hostile-input-specific than safe mode for missing/accessor-backed fields and sparse/accessor-backed array or record slots. Discriminant diagnostics also read tags directly.

Use safe at every public boundary. Use unsafe only after data has already been normalized into ordinary records. Use unchecked only when the caller owns the shape and treats extra-key rejection as unnecessary work.

---

Presence Semantics

Object presence is explicit — two different wrappers express two different contracts:

---

Execution Model

TypeSea keeps the public schema tree for builder validation and diagnostics, then lowers each schema identity into a cached validation plan. The plan owns an optimized Sea-of-Nodes graph and a schema-specialized predicate kernel. Guard.is() uses the kernel to avoid per-node interpreter dispatch, while compile() and emitAotModule() emit predicates from the optimized graph. check() first asks the same plan for the verdict; failed values then replay the schema-aware diagnostic collector to produce issue paths and codes.

builder -> frozen schema -> lower -> Sea-of-Nodes IR -> optimize
optimize -> ValidationPlan { graph, schema kernel }
schema kernel -> Guard.is() / check() preflight
graph -> compile() predicate / emitAotModule() predicate / Guard.graph()
failed check() -> schema-aware diagnostic collector

---

Performance Snapshot

Last local benchmark on 2026-07-06 KST, using npm run bench:record with the median of 3 full Vitest runs over the benchmark strict-object contract. The raw Vitest JSON is stored in [bench/results/raw.json](./bench/results/raw.json), and the stable summary used by the README graph is stored in [bench/results/latest.json](./bench/results/latest.json). These are operations per second on one machine, not release guarantees.

The safe compiled path stays close to Ajv while retaining TypeSea hostile-input semantics: descriptor-based property reads, symbol/non-enumerable strict-key rejection, presence semantics, immutable diagnostics, and TypeScript guard inference. Unsafe and unchecked compiled modes are faster because they deliberately give up parts of that hostile-input contract.

---

API Reference

All public entry points are exported from the package root; builders are also grouped under the t table.

Builders

Decoders

Execution & Export

Messages & Adapters

Adapters accept compiled guards too. Compile once at startup, then pass the compiled guard into parser or validator-compiler adapters so framework hot paths reuse the generated predicate.

const FastUser = compile(User);
const trpcParser = toTrpcParser(FastUser);
const fastifyCompiler = toFastifyValidatorCompiler(FastUser);

// Trusted normalized data only: trades hostile-input hardening for direct reads.
const UnsafeUser = compile(User, { mode: "unsafe" });
const internalParser = toTrpcParser(UnsafeUser);

---

Edge Semantics

Deliberate, documented, and pinned by tests:

---

Best Practices & Pitfalls

• **Boundary data enters as unknown.** Do not pre-narrow with as — the

builder API is typed so that narrowing happens through validation.

• **Recursive contracts go through t.lazy.** Direct schema object cycles are

rejected at construction.

• Choose the engine by schema lifetime. One-off schemas: runtime plan.

Stable hot schemas: compile(). CSP environments or build-time generation: emitAotModule().

• Shape object unions by required keys. `t.union(t.object({ and: ... }),

t.object({ or: ... }), t.object({ path: ... })) lowers to presence dispatch and skips impossible branches. Do not model an optional operator bag as many near-identical union branches; use one object and superRefine` for "at least one operator exists".

• Decoders do not embed in object shapes. Compose transformations with

t.pipe around a validated shape instead of mixing decoders into t.object entries.

---

Verification

Every gate that CI runs is a local npm script:

npm run check           # policy, docs, typecheck, lint, tests, build, dist, API snapshot, pack
npm run check:consumer  # tarball install + runtime/type smoke in a temp project
npm run bench:compare   # compare committed benchmark JSON against release floors
npm run bench:record    # full benchmark run + committed JSON/SVG refresh
npm run bench:render    # regenerate SVG from committed benchmark JSON
npm run bench -- --run  # benchmark smoke
npm run pack:dry        # package contents dry run
npm run release:check   # the full pre-publish gate (everything above)
npm run release:publish # npm publish with provenance and ignored lifecycle scripts

npm run release:check runs the same gate expected before publishing: typecheck, lint, tests, build, docs smoke, dist policy, public API snapshot, package contents, consumer install, benchmark smoke, and pack dry run. CI executes it on Node 20.19, 22, and 24; releases publish with npm provenance.

Release path:

1. Push a vX.Y.Z tag or run the GitHub Release workflow with that tag.
2. The release workflow verifies that the tag matches package.json.
3. The same release workflow runs npm run release:check, then npm run release:publish, which expands to npm publish --provenance --access public --ignore-scripts.
4. The workflow verifies npm registry visibility and then creates the GitHub Release.

Local publishing with NPM_TOKEN is reserved for manual recovery releases. It must still run npm run release:check first, and it cannot attach GitHub OIDC provenance.

---

Documentation

• Documentation site
• API reference
• Engine notes
• Security policy

---

Migration Notes

0.3.2 to 0.4.0

Existing schemas keep working. 0.4.0 is a minor release because it adds new public APIs: superRefine, compileCached, createCompileCache, warmup, compileBoolean, cooperative async validation, and zero-dependency Vite, Rollup, and esbuild AOT plugin helpers. Compiled object unions are also faster when branches have required keys, such as AST or query objects shaped by and, or, not, or path fields.

0.3.1 to 0.3.2

No application code changes are required. 0.3.2 is a performance-regression hardening patch: it adds benchmark floors, pins representative generated source fingerprints, strengthens FastMode fuzz parity, and normalizes unions by flattening nested unions, removing never, and absorbing unknown.

0.3.0 to 0.3.1

No application code changes are required. 0.3.1 is a release-hardening patch: it tightens manual release tag handling, documents npm provenance expectations, adds a security policy, and verifies that npm exposes the published version after the GitHub publish workflow completes.

---

License

MIT License. See LICENSE.

import { compile, t, toJsonSchema, type Infer } from "typesea";

const User = t.strictObject({
  id: t.string.uuid(),
  email: t.string.email(),
  age: t.number.int().nonnegative(),
  role: t.enum(["admin", "user"]),
  tags: t.array(t.string.min(1)).max(8)
});

type User = Infer<typeof User>;

// 1) Boolean narrowing: 성공 경로에서 진단 객체를 만들지 않습니다.
if (User.is(input)) {
  input.id; // narrowed
}

// 2) Immutable diagnostics: 예상 가능한 실패는 Result로 받습니다.
const checked = User.check(input);
if (!checked.ok) {
  console.log(checked.error); // path가 포함된 동결 issue 목록
}

// 3) Hot path: 검증 코드를 생성합니다.
const FastUser = compile(User, { name: "isUser" });

// 4) Interop: 의미 손실이 없을 때만 JSON Schema로 내보냅니다.
const schema = toJsonSchema(User);

import {
  compileAsync,
  compileBoolean,
  compileCached,
  createTypeSeaVitePlugin,
  warmup
} from "typesea";

const FastUser = compileCached("user:v1", () => User, { name: "isUser" });
const BooleanUser = compileBoolean(User, { name: "isUserBoolean" });
const AsyncUsers = compileAsync(t.array(User), {
  name: "isUsersAsync",
  yieldEvery: 4096,
  yieldTimeout: 5
});

warmup([User, { key: "user:v1", guard: User, options: { name: "isUser" } }]);

export default createTypeSeaVitePlugin({
  entries: [{ id: "user:v1", guard: User, options: { name: "isUser" } }],
  transformCompileCached: true
});

const FastButLooseUser = compile(User, {
  name: "isUserFast",
  mode: "unsafe"
});

const FastTrustedShapeUser = compile(User, {
  name: "isUserTrustedShape",
  mode: "unchecked"
});

builder -> frozen schema -> lower -> Sea-of-Nodes IR -> optimize
optimize -> ValidationPlan { graph, schema kernel }
schema kernel -> Guard.is() / check() preflight
graph -> compile() predicate / emitAotModule() predicate / Guard.graph()
failed check() -> schema-aware diagnostic collector

const FastUser = compile(User);
const trpcParser = toTrpcParser(FastUser);
const fastifyCompiler = toFastifyValidatorCompiler(FastUser);

// 신뢰된 정규화 데이터 전용: 적대적 입력 방어를 direct read 성능과 맞바꿉니다.
const UnsafeUser = compile(User, { mode: "unsafe" });
const internalParser = toTrpcParser(UnsafeUser);

npm run check           # policy, docs, typecheck, lint, tests, build, dist, API snapshot, pack
npm run check:consumer  # tarball install + runtime/type smoke in a temp project
npm run bench:compare   # committed benchmark JSON을 릴리즈 기준선과 비교
npm run bench:record    # full benchmark run + committed JSON/SVG refresh
npm run bench:render    # committed benchmark JSON에서 SVG 재생성
npm run bench -- --run  # benchmark smoke
npm run pack:dry        # package contents dry run
npm run release:check   # the full pre-publish gate
npm run release:publish # provenance를 붙이고 lifecycle script를 무시하는 npm publish

TypeSea API Reference

TypeSea accepts untrusted input as unknown and narrows it through immutable guard values. The public API is small by design; most complexity lives behind builder validation, graph introspection, diagnostics, and export checks.

Import

import {
  compile,
  emitAotModule,
  t,
  toJsonSchema,
  type Guard,
  type Infer
} from "typesea";

The package exposes one root entry point. Subpath imports are intentionally not part of the public API. TypeSea is ESM-only and does not publish a CommonJS condition.

Guard Contract

interface Guard<T> {
  is(value: unknown): value is T;
  check(value: unknown): CheckResult<T>;
  checkFirst(value: unknown): CheckResult<T>;
  assert(value: unknown): asserts value is T;
  graph(): Graph;
  transform<U>(mapper: (value: T) => U): Decoder<U>;
  pipe(next: Guard<unknown> | Decoder<unknown>): Decoder<unknown>;
  default(value: T | (() => T)): Decoder<T>;
  prefault(value: unknown): Decoder<T>;
  catch(value: T | (() => T)): Decoder<T>;
}

Diagnostic paths contain only object keys and zero-based array or tuple indexes. Public diagnostic validators reject malformed path segments before diagnostics cross the API boundary.

Builder Families

Builder functions validate inputs before a schema can enter the validation plan, compiler, AOT emitter, diagnostic collector, or JSON Schema exporter. Forged guard-like values, invalid schema tags, invalid predicates, invalid bounds, malformed regexps, and invalid discriminated union case sets are rejected during construction.

Accepted schemas are frozen before storage. Public schema collection fields use frozen arrays and frozen key lookup records instead of mutable collection objects.

Object Presence

TypeSea separates key presence from value domain.

const Shape = t.object({
  name: t.optional(t.string),
  nickname: t.undefinedable(t.string)
});

• name may be absent. If name exists, its value must be a string.
• nickname must be present. Its value may be a string or undefined.
• t.nullable(inner) adds null to the value domain.
• t.nullish(inner) combines nullable value semantics with optional object-key

presence.

• Presence-preserving wrappers keep optional-key semantics through nullable,

undefinedable, brand, refine, and superRefine.

Object combinators preserve object mode. Strict object guards remain strict after extend, pick, omit, or partial; passthrough object guards keep allowing unknown keys.

catchall(schema) validates every undeclared own key with schema. strip() is validation-only in TypeSea: guards return the original value, so it has the same validation behavior as passthrough(). pick and omit accept either key arrays or Zod-style { key: true } masks. deepPartial() recursively partializes pure object, array, tuple, tuple rest, record, map, set, property, union, intersection, nullable, undefinedable, optional, and brand schemas. Lazy and refinement schemas are semantic barriers.

property validates only own data descriptors. It is useful for class instances with stable fields; prototype getters and accessor-backed properties are rejected instead of executed.

Composition

t.union(a, b) accepts a value that satisfies at least one branch.

refine and superRefine attach semantic checks after structural validation. Use refine when a boolean predicate is enough, and superRefine when the check is easier to write as a callback that can call context.addIssue(). addIssue() accepts no argument for the default refinement issue, a string as a message shorthand, or { path, message } when the failure should point at a nested relative path.

const Range = t.object({
  min: t.number,
  max: t.number
}).superRefine((value, context) => {
  if (value.min > value.max) {
    context.addIssue({
      path: ["max"],
      message: "max must be greater than or equal to min"
    });
  }
}, "ordered_range");

t.discriminatedUnion("kind", cases) requires string case keys. Each case must be a statically inspectable object case whose dispatch key is a required string literal matching the case name.

t.intersect(a, b) and guard.intersect(other) require the same input value to satisfy both guards. check() collects diagnostics from both sides.

Recursion

Recursive contracts must use t.lazy.

interface ListNode {
  readonly value: string;
  readonly next?: ListNode;
}

const Node: Guard<ListNode> = t.lazy((): Guard<ListNode> =>
  t.object({
    value: t.string,
    next: t.optional(Node)
  })
);

Direct cyclic schema objects are rejected at builder boundaries. Lazy guards resolve once per guard instance and keep recursive schema identity stable. A lazy chain must eventually resolve to a concrete non-lazy schema.

Decoder Pipelines

const Count = t.pipe(t.coerce.number(), t.number.int().gte(0));
const result = Count.decode("42");

const Port = t.number.int().gte(0).lte(65535).default(3000);
const SafePort = t.number.int().gte(0).lte(65535).catch(3000);
const Name = t.default(t.string.min(1), "anonymous");
const NormalizedName = t.string
  .trim()
  .pipe(t.string.min(1))
  .transform((value) => value.toLowerCase())
  .default("anonymous")
  .catch("anonymous");
const NumberText = t.codec(
  t.string.regex(/^\d+$/u, "digits"),
  t.number.int().nonnegative(),
  {
    decode: (value) => Number(value),
    encode: (value) => String(value)
  }
);

Decoders are for output-producing operations. They return Result from decode() and do not expose is() predicates, because the decoded output may not be the same runtime value as the input.

• t.transform(source, mapper) decodes source, then maps the decoded value.
• t.pipe(source, next) feeds a successful decoded value into the next guard or decoder.
• t.default(source, value) returns a fallback output for undefined input.
• t.prefault(source, value) feeds a fallback input through the source.
• t.catch(source, value) returns a fallback output after a failed decode.
• Guard methods guard.transform, guard.pipe, guard.default,

guard.prefault, and guard.catch are shorthand for the same decoder helpers. They do not change guard.is().

• t.codec(input, output, mapping) validates both sides of a bidirectional decode/encode pair.
• t.coerce.string, t.coerce.number, and t.coerce.boolean provide explicit

primitive coercion.

• t.string.trim(), t.string.toLowerCase(), and t.string.toUpperCase()

are decoder helpers. They validate the string first, then return transformed output from decode().

• t.asyncRefine, t.asyncTransform, and t.asyncPipe return

Promise<Result<T, Issue[]>> from decodeAsync().

Expected async validation failures still return Result values.

Messages

const checked = withMessages(User.check(input), {
  locale: "ko",
  catalog: defineMessages({
    expected_string: "{path}: 문자열 필요"
  })
});

formatIssue, formatIssues, flattenIssues, and withMessages render diagnostics after validation has finished. This keeps is() and ordinary check() paths free from message allocation.

Built-in locales are en and ko. Custom catalogs can use string templates with {path}, {code}, {expected}, and {actual}, or formatter callbacks. withMessages(result, options) preserves successful results and returns a new failed Result with copied, frozen issues whose message fields are populated. flattenIssues(issues, options) groups rendered messages into formErrors and top-level fieldErrors buckets.

Runtime Compile

const FastUser = compile(User, { name: "isUser" });

FastUser.is(input);
FastUser.check(input);

compile emits generated predicate functions from the optimized Sea-of-Nodes validation graph plus diagnostics collectors for failed values. Static scalar, object, array, record, union, and strict-key nodes lower to straight-line JavaScript or indexed loops where possible. Union lowering specializes discriminant literals, primitive domains, required-key presence checks, and coarse root-kind masks before falling back to ordered branch probing. Dynamic schema edges such as lazy, refine, and superRefine keep semantics by using the same IR-backed runtime fallback as ordinary guards.

The optional name is a debugging and profiling hint. TypeSea normalizes it into a strict-mode-safe JavaScript function name, prefixes reserved names, and caps generated name length. Direct compiled guard construction validates the predicate, collector, and source arguments. Collector diagnostics are validated, copied, and frozen before check() returns them.

Generated source never interpolates user-controlled values directly. Literals, regexps, property keys, keysets, and dynamic schema fallbacks are captured in side tables and referenced by numeric index.

Compile Cache And Warmup

const FastUser = compileCached("user:v1", () => User, { name: "isUser" });

warmup([
  User,
  {
    key: "user:v1",
    guard: User,
    options: { name: "isUser" }
  }
], {
  namePrefix: "boot_"
});

compileCached(key, factory, options) uses a process-local explicit cache. createCompileCache() creates an isolated cache for tests, workers, or multi-tenant servers. The cache key combines the caller key, compile mode, generated function name, and debug-source flag.

warmup() compiles guards during service startup or serverless module initialization. Plain guards fill the per-guard WeakMap cache. Entries with key fill an explicit cache, so the first real request does not pay schema construction or codegen cost.

Boolean-Only And Async Validation

const BooleanUser = compileBoolean(User, { name: "isUserBoolean" });
const AsyncUsers = compileAsync(t.array(User), {
  name: "isUsersAsync",
  yieldEvery: 4096,
  yieldTimeout: 5
});

BooleanUser.is(input);
await AsyncUsers.is(largePayload);

compileBoolean() is the fail-fast surface: it emits only a predicate and generated source. It has no check, no assert, and no diagnostic collector. Use it when the caller only needs a boolean verdict.

isAsync(), checkAsync(), and compileAsync() validate cooperatively. Long array, tuple, record, map, set, union, and object loops yield with setImmediate() when available, otherwise setTimeout(0). yieldEvery limits node-count bursts and yieldTimeout limits wall-clock bursts in milliseconds. Diagnostics are still collected only after failure. checkAsync() and compileAsync().check() return the same full diagnostic result as check(); use isAsync() when the hot path needs only the cooperative boolean verdict.

AOT Bundler Plugins

export default createTypeSeaVitePlugin({
  entries: [
    {
      id: "user:v1",
      guard: User,
      options: { name: "isUser", mode: "unsafe" }
    }
  ],
  transformCompileCached: true
});

createTypeSeaVitePlugin, createTypeSeaRollupPlugin, and createTypeSeaEsbuildPlugin are zero-dependency structural plugin factories. They serve virtual modules such as typesea:aot/user:v1 by running emitAotModule() at build time. Vite, Rollup, and esbuild can rewrite static compileCached("user:v1", ...) calls into default imports from those virtual modules, so production bundles can drop the schema factory and runtime compiler for that guard. esbuild source reads use an optional readFile hook or a dynamic node:fs/promises import inside plugin setup().

Union Schema Shape

TypeSea optimizes object unions best when each branch advertises a required own key. AST-like contracts such as and, or, not, path, or elemMatch lower to presence dispatch: the compiled predicate checks the required key first and skips branches that cannot match.

const Query = t.union(
  t.object({ and: t.array(t.unknown).min(1) }),
  t.object({ or: t.array(t.unknown).min(1) }),
  t.object({ not: t.unknown }),
  t.object({ path: t.string, eq: t.optional(t.string) })
);

Avoid splitting optional operator bags into many near-identical union branches only to express "at least one key exists". That shape repeats the same property walk for every branch and can dominate recursive query validation. Prefer one object schema for the structural pass, then add a semantic refinement if the non-empty operator rule matters.

const Operators = t.object({
  eq: t.optional(t.string),
  neq: t.optional(t.string),
  exists: t.optional(t.boolean),
  gt: t.optional(t.number),
  between: t.optional(t.tuple([t.number, t.number]))
}).superRefine((value, context) => {
  if (!("eq" in value) &&
      !("neq" in value) &&
      !("exists" in value) &&
      !("gt" in value) &&
      !("between" in value)) {
    context.addIssue();
  }
}, "at_least_one_operator");

Unsafe Compile Mode

const FastButLooseUser = compile(User, {
  name: "isUserFast",
  mode: "unsafe"
});

CompileOptions["mode"] and AotCompileOptions["mode"] are "safe" | "unsafe" | "unchecked" | undefined; omitted options default to "safe". Safe mode keeps TypeSea's hostile-input contract: descriptor-based property reads, no getter execution, and strict-object rejection for symbol and non-enumerable extras.

Unsafe mode is an explicit performance escape hatch for trusted, normalized plain data:

• Required object fields read with value[key] when the field schema rejects

undefined.

• Discriminant dispatch reads the tag with direct bracket access.
• Arrays and tuples read items with direct indexed loads.
• Strict-object extra-key rejection uses an allocation-free own-enumerable

for...in loop.

This may execute getters, may accept prototype-backed values, and does not reject symbol or non-enumerable extras on strict objects. Because compiled check() first trusts the generated predicate verdict, an unsafe predicate that returns true also returns a successful check() result. Use unsafe mode only after the input has crossed a trusted normalization boundary.

Unsafe mode may embed escaped static property keys directly into generated predicate source so V8 can attach ordinary property-load inline caches. Safe mode keeps property keys in side tables.

Unchecked mode uses the unsafe direct-read shape and also skips strict-object extra-key loops. It is only for input whose object shape has already been trusted or normalized; strict objects no longer reject extra keys in this mode. Unsafe and unchecked compiled check() calls also return raw successful Result objects without Object.freeze(). Failure diagnostics remain frozen. Safe mode keeps frozen success and failure Result objects. FastMode diagnostic collectors use direct field reads and FastMode strict-key rules for object diagnostics where possible, so missing/accessor issue codes are not guaranteed to match safe mode. Array and tuple diagnostics also use direct indexed reads in fast modes, so sparse slots are diagnosed from the loaded undefined value. Record diagnostics use direct record[key] reads; unchecked mode also visits inherited enumerable keys. Discriminant diagnostics read the tag directly and compare string cases with ===.

The practical rule is: public boundary data uses safe; trusted normalized records may use unsafe; caller-owned fixed-shape DTOs may use unchecked.

AOT Emit

const emitted = emitAotModule(User, { name: "aotUser" });
const unsafeEmitted = emitAotModule(User, {
  name: "aotUserFast",
  mode: "unsafe"
});
const uncheckedEmitted = emitAotModule(User, {
  name: "aotUserTrustedShape",
  mode: "unchecked"
});

emitAotModule returns Result<AotModule, AotIssue[]>. A successful result contains standalone ESM validator source plus declaration source. The generated module exports is, check, assert, and a default frozen guard-like object, without requiring dynamic source compilation at module load time.

AOT generation is lossless-only. Schemas that require runtime callbacks or identity that cannot be serialized return explicit AOT issues.

Ecosystem Adapters

const parser = toTrpcParser(User);
const routeSchema = toFastifyRouteSchema(User);
const validatorCompiler = toFastifyValidatorCompiler(User);
const resolver = toReactHookFormResolver(User);

Adapters are structural and zero-dependency. TypeSea does not import tRPC, Fastify, or React Hook Form.

Compiled guards can be passed to the same adapters. This is the preferred shape for hot request paths: compile once during startup, then let the adapter reuse the generated predicate.

const FastUser = compile(User);
const fastParser = toTrpcParser(FastUser);
const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);

Use the default compiled mode at public input boundaries. It keeps the safe descriptor-read contract even when an adapter hides the direct is() call. For trusted, already-normalized internal data, the faster modes can be wired through adapters the same way.

const UnsafeUser = compile(User, { mode: "unsafe" });
const internalParser = toTrpcParser(UnsafeUser);

const TrustedShapeUser = compile(User, { mode: "unchecked" });
const internalValidatorCompiler = toFastifyValidatorCompiler(TrustedShapeUser);

Graph and IR

const graph = User.graph();
const optimized = optimizeGraph(graph);

Guard.graph() returns the optimized Sea-of-Nodes validation graph held by the runtime validation plan. The same plan also owns the specialized predicate kernel used by is(). The graph is the source for compile() and emitAotModule(), while the kernel keeps ordinary guard execution out of a generic per-node interpreter. Public graph values are validated, dependency-checked, dense, and frozen.

optimizeGraph(graph) validates direct graph inputs before optimizing them. Regex graph nodes accept only plain RegExp values and store non-extensible regexps, cloning extensible inputs before the graph is frozen.

SchemaCheck records dynamic runtime schema logic such as lazy, refine, or superRefine. It keeps the IR truthful instead of pretending a callback-backed edge is a static primitive.

JSON Schema

const result = toJsonSchema(User);

toJsonSchema returns Result<JsonSchema, JsonSchemaExportIssue[]>. It succeeds only when TypeSea can represent the contract over JSON-compatible input values without semantic loss.

Runtime-only concepts return explicit export issues:

• undefined
• bigint
• symbol
• JavaScript Date, Map, Set, instanceOf, and property contracts
• lazy
• refine
• superRefine
• decoder transforms
• async validation
• regexps with flags
• numeric literals that JSON cannot preserve, such as NaN, Infinity, and

-0

schemaToJsonSchema(schema) is the direct schema API. It validates the supplied schema and freezes it before export. JSON Schema options are also validated; schemaId, when present, must be a string.

Object properties maps are emitted as null-prototype records so special keys such as __proto__, constructor, and hasOwnProperty remain ordinary own schema properties.

Edge Semantics

• Literal guards use Object.is, so t.literal(Number.NaN) matches NaN and

t.literal(-0) does not match 0.

• t.number accepts only finite JavaScript numbers. NaN, Infinity, and

-Infinity are rejected before configured numeric predicates run.

• String length bounds must be non-negative integers.
• Numeric comparison bounds must be finite.
• Predicate callbacks must return strict true; truthy non-boolean values do

not pass validation.

• RegExp checks reset lastIndex before each test, so global and sticky

regexps do not leak state across validations.

• String regex builders and direct string regex schemas accept only plain

RegExp instances. Accepted regex checks are cloned before storage.

Result Contract

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

Expected validation failures use Result. Result containers are frozen at runtime. Successful values are not recursively frozen because they are caller-owned data.

import {
  compile,
  emitAotModule,
  t,
  toJsonSchema,
  type Guard,
  type Infer
} from "typesea";

interface Guard<T> {
  is(value: unknown): value is T;
  check(value: unknown): CheckResult<T>;
  checkFirst(value: unknown): CheckResult<T>;
  assert(value: unknown): asserts value is T;
  graph(): Graph;
  transform<U>(mapper: (value: T) => U): Decoder<U>;
  pipe(next: Guard<unknown> | Decoder<unknown>): Decoder<unknown>;
  default(value: T | (() => T)): Decoder<T>;
  prefault(value: unknown): Decoder<T>;
  catch(value: T | (() => T)): Decoder<T>;
}

const Shape = t.object({
  name: t.optional(t.string),
  nickname: t.undefinedable(t.string)
});

const Range = t.object({
  min: t.number,
  max: t.number
}).superRefine((value, context) => {
  if (value.min > value.max) {
    context.addIssue({
      path: ["max"],
      message: "max는 min보다 크거나 같아야 합니다"
    });
  }
}, "ordered_range");

interface ListNode {
  readonly value: string;
  readonly next?: ListNode;
}

const Node: Guard<ListNode> = t.lazy((): Guard<ListNode> =>
  t.object({
    value: t.string,
    next: t.optional(Node)
  })
);

const Count = t.pipe(t.coerce.number(), t.number.int().gte(0));
const result = Count.decode("42");

const Port = t.number.int().gte(0).lte(65535).default(3000);
const SafePort = t.number.int().gte(0).lte(65535).catch(3000);
const Name = t.default(t.string.min(1), "anonymous");
const NormalizedName = t.string
  .trim()
  .pipe(t.string.min(1))
  .transform((value) => value.toLowerCase())
  .default("anonymous")
  .catch("anonymous");
const NumberText = t.codec(
  t.string.regex(/^\d+$/u, "digits"),
  t.number.int().nonnegative(),
  {
    decode: (value) => Number(value),
    encode: (value) => String(value)
  }
);

const checked = withMessages(User.check(input), {
  locale: "ko",
  catalog: defineMessages({
    expected_string: "{path}: 문자열 필요"
  })
});

const FastUser = compile(User, { name: "isUser" });

FastUser.is(input);
FastUser.check(input);

const FastUser = compileCached("user:v1", () => User, { name: "isUser" });

warmup([
  User,
  {
    key: "user:v1",
    guard: User,
    options: { name: "isUser" }
  }
], {
  namePrefix: "boot_"
});

const BooleanUser = compileBoolean(User, { name: "isUserBoolean" });
const AsyncUsers = compileAsync(t.array(User), {
  name: "isUsersAsync",
  yieldEvery: 4096,
  yieldTimeout: 5
});

BooleanUser.is(input);
await AsyncUsers.is(largePayload);

export default createTypeSeaVitePlugin({
  entries: [
    {
      id: "user:v1",
      guard: User,
      options: { name: "isUser", mode: "unsafe" }
    }
  ],
  transformCompileCached: true
});

const Query = t.union(
  t.object({ and: t.array(t.unknown).min(1) }),
  t.object({ or: t.array(t.unknown).min(1) }),
  t.object({ not: t.unknown }),
  t.object({ path: t.string, eq: t.optional(t.string) })
);

const Operators = t.object({
  eq: t.optional(t.string),
  neq: t.optional(t.string),
  exists: t.optional(t.boolean),
  gt: t.optional(t.number),
  between: t.optional(t.tuple([t.number, t.number]))
}).superRefine((value, context) => {
  if (!("eq" in value) &&
      !("neq" in value) &&
      !("exists" in value) &&
      !("gt" in value) &&
      !("between" in value)) {
    context.addIssue();
  }
}, "at_least_one_operator");

const FastButLooseUser = compile(User, {
  name: "isUserFast",
  mode: "unsafe"
});

const emitted = emitAotModule(User, { name: "aotUser" });
const unsafeEmitted = emitAotModule(User, {
  name: "aotUserFast",
  mode: "unsafe"
});
const uncheckedEmitted = emitAotModule(User, {
  name: "aotUserTrustedShape",
  mode: "unchecked"
});

const parser = toTrpcParser(User);
const routeSchema = toFastifyRouteSchema(User);
const validatorCompiler = toFastifyValidatorCompiler(User);
const resolver = toReactHookFormResolver(User);

const FastUser = compile(User);
const fastParser = toTrpcParser(FastUser);
const fastValidatorCompiler = toFastifyValidatorCompiler(FastUser);

const UnsafeUser = compile(User, { mode: "unsafe" });
const internalParser = toTrpcParser(UnsafeUser);

const TrustedShapeUser = compile(User, { mode: "unchecked" });
const internalValidatorCompiler = toFastifyValidatorCompiler(TrustedShapeUser);

const graph = User.graph();
const optimized = optimizeGraph(graph);

const result = toJsonSchema(User);

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

Engine Notes

TypeSea is written for predictable machine behavior after TypeScript emits JavaScript. The goal is not obscurity; the goal is to make object shapes, allocation sites, branch behavior, and validation contracts visible in code.

Hot Path Rules

• Use prototype methods instead of per-instance method closures.
• Use numeric tags for schema, check, issue, and IR node variants.
• Initialize class fields in one constructor order.
• Keep successful is() validation free of diagnostic allocation.
• Allocate Issue objects and path arrays only when diagnostics are requested.
• Prefer indexed loops on recursive validation paths.
• Precompute object-entry arrays during schema construction.
• After required object fields have proved their data-property descriptors, load

descriptor values directly instead of rechecking missing-property fallbacks.

• For all-required strict objects, reject extras by counting own string names

and own symbols after field validation. Optional strict objects keep the full key membership scan.

• Keep compile() and emitAotModule() safe by default. Unsafe mode is an

explicit opt-in that may use direct property/index loads and own-enumerable strict-key loops after the caller accepts getter/prototype/symbol-extra risk.

• Mark constructed guards out-of-band so normal receivers avoid repeated schema

validation while forged receivers still fall back to structural checks.

• Use Readonly<Record<string, unknown>> after object guards.
• Store generated-validator literals, regexps, keysets, and dynamic fallbacks in

side tables instead of interpolating user-controlled values into source text.

Type-System Rules

• optional(inner) means an object key may be absent.
• undefinedable(inner) means the key must exist when used in an object shape,

but its value may be undefined.

• nullable(inner) means the value may be null.
• Presence-preserving wrappers do not erase optional-key semantics.
• number means finite JavaScript number.
• unknown is the only accepted boundary type for untrusted input.
• Builder validation is the hard barrier before a schema reaches the engine.

IR Rules

The public schema tree is the semantic source used by builders and diagnostic collectors. Boolean validation executes a cached ValidationPlan: schema identity is lowered into Sea-of-Nodes IR, the optimizer runs, and the plan keeps both the frozen graph and a schema-specialized predicate kernel.

The graph is not decorative. compile(), AOT emission, and Guard.graph() all consume the optimized graph held by the plan. Ordinary Guard.is() deliberately uses the sibling schema-specialized kernel instead of a generic node interpreter, because per-node dispatch and scratch-slot bookkeeping cost more than they buy on the most common hot path.

Current lowering hash-conses pure value and predicate nodes. Strict object schemas lower an explicit keyset check into the IR, so extra-key rejection does not depend on out-of-band schema knowledge. Required and optional object fields separate key presence from data-property presence, which keeps accessor-backed properties from executing getters or being misclassified as valid values.

Guard.graph() returns the same optimized graph held by the validation plan. Public graph values are validated and frozen before leaving the API. The first optimizer pass performs reachable node elimination and compacts node ids so every dependency points at an existing dense node index. compile() and AOT emission use this graph as their predicate source.

Array, tuple, and record schemas lower to native composite IR nodes whose child schemas are executed through child validation plans. SchemaCheck is reserved for dynamic schemas such as lazy, refine, and superRefine; the graph records that callback or resolver-backed semantics are required instead of pretending they are static predicates.

Runtime Compiler

Compiled guards emit boolean predicates from optimized Sea-of-Nodes graphs and schema-aware diagnostics collectors for failed values. Runtime is() uses the plan-owned schema-specialized kernel to avoid recursive node dispatch and scratch buffer churn. check() first asks the plan predicate for the pass/fail verdict; successful values skip diagnostic collection, while failed values replay the diagnostic collector to build paths and issue codes.

User-controlled literals, regexps, object keys, keysets, dynamic schemas, and diagnostic names live in side tables captured by the generated factory. The generated source contains numeric side-table indexes, fixed helper strings, and sanitized function names.

compileBoolean() uses the same predicate emitter but stops before diagnostic collector emission. That keeps the fail-fast artifact smaller than a full compiled guard and makes the "boolean only" contract explicit. compileAsync() does not make generated predicates async; it wraps a compiled diagnostic guard with a separate cooperative evaluator so ordinary compiled hot paths never pay for await state machines.

The AOT bundler plugins are thin build-time adapters around emitAotModule(). Virtual modules are resolved by id, and the Rollup, Vite, and esbuild macro paths rewrite only static compileCached("id", ...) calls whose id was declared in plugin config. No schema expression is evaluated from source text.

Scalar nodes emit direct JavaScript tests where the semantics are local: finite-number checks, integer checks, string length bounds, literal equality, and regexp tests all lower without helper calls on the generated hot path.

Array and record IR nodes emit indexed loops. Static child schemas are inlined into those loops from their optimized graphs, which avoids function-call boundaries for small scalar or union element contracts. Tuple nodes preserve descriptor-based element access, and dynamic edges use the same IR-backed runtime fallback as ordinary guard execution, preserving behavior for lazy, refine, and superRefine.

Union IR now has four increasingly general fast paths. Literal-tag object unions use discriminant dispatch, primitive unions use a compact root-kind dispatch, object unions with required branch keys use presence dispatch, and the remaining mixed unions use ordered root-kind branch probing. Presence dispatch keeps declaration order but skips object branches whose required own data key is absent, which avoids recursive union explosions in AST-like inputs.

Strict object IR emits two shapes. When every declared key is required, generated validators run the strict-key count before field descriptor reads: they compare Object.getOwnPropertyNames(value).length with the declared key count and require Object.getOwnPropertySymbols(value).length === 0. V8 optimizes this count-only path better than a generic Reflect.ownKeys count, and it rejects obvious extra-key objects before touching field descriptors. Optional strict objects still emit the full own-key membership scan because a missing optional key cannot be distinguished by the final key count alone.

compile(..., { mode: "unsafe" }) and emitAotModule(..., { mode: "unsafe" }) switch generated predicates to a trusted-data code shape. Required object fields whose schemas reject undefined use direct value[key] loads without descriptor or own-key checks. Required fields that can accept undefined retain an own-key presence guard so missing required keys do not collapse into valid undefined values. Optional fields take the direct-load fast path for present non-undefined values and fall back to an own-key check only for the ambiguous undefined case.

Unsafe array, tuple, record, and discriminant paths also prefer direct loads. Strict objects use a for...in own-enumerable key loop instead of allocating own-key arrays. Object keys that are ASCII identifier names emit as dot-property loads such as value.id; other keys emit as escaped string-literal bracket loads. That is intentionally not hostile-input equivalent: getters can execute, prototype-backed values can be accepted, symbol or non-enumerable strict extras are not rejected, and static property names may appear in unsafe generated predicate source.

mode: "unchecked" keeps the unsafe direct-read shape and removes strict extra-key loops. It is a trusted-shape path for objects already normalized by the caller; strict objects no longer reject any extra keys there.

Fast modes also remove Object.freeze() from successful compiled check() results. The returned object keeps the same { ok: true, value } shape, but it is intentionally not frozen. Failed diagnostics stay frozen because those objects are off the success hot path and are often retained for reporting. Object diagnostics in fast modes are generated from the same direct-read contract as predicates. Required fields load through value.key, optional fields use direct load plus an own-key fallback for undefined, unsafe strict objects scan own enumerable string keys, and unchecked strict objects skip the strict-key diagnostic scan. Array and tuple diagnostics in fast modes read items through direct indexes instead of descriptor probes. Record diagnostics read through record[key]; unchecked mode intentionally keeps inherited enumerable keys visible. Discriminant diagnostics read the tag directly and compare literal string cases with strict equality.

FastMode is therefore an engine contract, not a security default:

The intended rule is simple: boundary data uses safe; trusted normalized records may use unsafe; fixed-shape DTOs owned by the caller may use unchecked.

Recursion

Lazy schemas resolve their getter once per guard instance. Recursive validation therefore sees stable schema identity, and repeated validations do not rebuild the recursive schema graph.

Recursive validation uses a root-local active pair table keyed by runtime object identity and schema identity. Re-entering the same schema/value pair short-circuits that edge, which lets cyclic object graphs validate finitely while still checking the original object fields on the outer frame.

Compiled lazy, refine, and superRefine fallbacks use the same IR-backed runtime path, so recursive behavior stays consistent across execution engines. When superRefine emits custom issue paths or messages, the generated diagnostic fallback copies those nested issues under the current compiled path prefix.

checkFirst() has a separate generated collector. It returns one frozen issue as soon as the first diagnostic is known, instead of running the full check() collector and truncating its issue array.

JSON Schema Export

JSON Schema export succeeds only when the TypeSea schema can be represented over JSON-compatible input values without semantic loss. Runtime-only concepts return typed Result errors.

Export diagnostics keep paths at the failed child slot instead of collapsing everything to the parent container. Nested unsupported schemas therefore remain actionable without reconstructing the schema tree manually.

Literal checks use Object.is in runtime-plan and compiled paths. Diagnostics use the same literal formatting, including -0, so compiled and runtime-plan check() results stay byte-for-byte comparable in tests.

Benchmark Scope

The benchmark suite keeps two questions separate:

• compile.bench.ts compares TypeSea runtime-plan and compiled validators over

the same TypeSea schema.

• ecosystem.bench.ts compares TypeSea runtime-plan, TypeSea compiled, Zod,

Valibot, and Ajv over one JSON-compatible strict-object contract.

Zod, Valibot, and Ajv are dev dependencies for measurement only. They are not imported by src, and package policy rejects runtime, peer, optional, or bundled dependency fields before release.

Last local benchmark on 2026-07-06 KST reported these ecosystem paths over the JSON-compatible strict-object benchmark. The committed source of truth is bench/results/latest.json; npm run bench:record refreshes that summary and the README SVG from the median of 3 full Vitest runs. npm run bench:compare checks the committed summary against release regression floors for unchecked valid hot path, safe invalid fast-fail, safe valid throughput, and presence-dispatch object union paths. check:benchmarks runs the same floor check after verifying the SVG is fresh.

Benchmark numbers are machine-local telemetry. They are useful for catching regressions, not for promising a fixed throughput floor. Unsafe and unchecked numbers are not hostile-input equivalent to safe mode.