typesea 0.1.0

package/docs/api.md

@@ -0,0 +1,301 @@
+# 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
+
+```ts
+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
+
+```ts
+interface Guard<T> {
+  is(value: unknown): value is T;
+  check(value: unknown): CheckResult<T>;
+  assert(value: unknown): asserts value is T;
+  graph(): Graph;
+}
+```
+
+| Method | Use it for | Contract |
+| --- | --- | --- |
+| `is` | Hot boolean narrowing | Avoids diagnostic allocation on the success path. |
+| `check` | Validation with issues | Returns frozen `Result<T, Issue[]>` containers. |
+| `assert` | Throwing integration boundaries | Throws `TypeSeaAssertionError` with copied, frozen issues. |
+| `graph` | Runtime plan introspection | Returns the validated, optimized, frozen Sea-of-Nodes graph held by the validation plan. |
+
+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
+
+| Family | Builders |
+| --- | --- |
+| Scalars | `t.unknown`, `t.never`, `t.string`, `t.number`, `t.bigint`, `t.symbol`, `t.boolean` |
+| Literals and containers | `t.literal(value)`, `t.array(item)`, `t.tuple([a, b])`, `t.record(value)` |
+| Objects | `t.object(shape)`, `t.strictObject(shape)` |
+| Object transforms | `t.extend`, `t.pick`, `t.omit`, `t.partial`, and matching object guard methods |
+| Composition | `t.union`, `t.discriminatedUnion`, `t.intersect`, `guard.intersect` |
+| Presence | `t.optional`, `t.undefinedable`, `t.nullable` |
+| Dynamic guards | `t.lazy`, `t.refine` |
+| Decoders | `t.decoder`, `t.transform`, `t.pipe`, `t.coerce` |
+| Async decoders | `t.asyncDecoder`, `t.asyncRefine`, `t.asyncTransform`, `t.asyncPipe` |
+
+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.
+
+```ts
+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.
+- Presence-preserving wrappers keep optional-key semantics through `nullable`,
+  `undefinedable`, `brand`, and `refine`.
+
+Object combinators preserve object mode. Strict object guards remain strict
+after `extend`, `pick`, `omit`, or `partial`; passthrough object guards keep
+allowing unknown keys.
+
+## Composition
+
+`t.union(a, b)` accepts a value that satisfies at least one branch.
+
+`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`.
+
+```ts
+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
+
+```ts
+const Count = t.pipe(t.coerce.number(), t.number.int().gte(0));
+const result = Count.decode("42");
+```
+
+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.coerce.string`, `t.coerce.number`, and `t.coerce.boolean` provide explicit
+  primitive coercion.
+- `t.asyncRefine`, `t.asyncTransform`, and `t.asyncPipe` return
+  `Promise<Result<T, Issue[]>>` from `decodeAsync()`.
+
+Expected async validation failures still return `Result` values.
+
+## Messages
+
+```ts
+const checked = withMessages(User.check(input), {
+  locale: "ko",
+  catalog: defineMessages({
+    expected_string: "{path}: 문자열 필요"
+  })
+});
+```
+
+`formatIssue`, `formatIssues`, 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.
+
+## Runtime Compile
+
+```ts
+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. Dynamic schema edges such as `lazy`
+and `refine` 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.
+
+## AOT Emit
+
+```ts
+const emitted = emitAotModule(User, { name: "aotUser" });
+```
+
+`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
+
+```ts
+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.
+
+| Adapter | Export | Behavior |
+| --- | --- | --- |
+| tRPC | `toTrpcParser`, `toAsyncTrpcParser` | Return parser objects that emit decoded values or throw `TypeSeaAssertionError`. |
+| Fastify route schema | `toFastifyRouteSchema` | Converts guards to JSON Schema route fragments. |
+| Fastify validator compiler | `toFastifyValidatorCompiler` | Returns compiler-shaped validators that produce `{ value }` or `{ error }`. |
+| React Hook Form | `toReactHookFormResolver` | Returns an async resolver with TypeSea messages mapped to field errors. |
+
+## Graph and IR
+
+```ts
+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` or `refine`.
+It keeps the IR truthful instead of pretending a callback-backed edge is a
+static primitive.
+
+## JSON Schema
+
+```ts
+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`
+- `lazy`
+- `refine`
+- 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
+
+```ts
+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.

package/docs/engine-notes.md

@@ -0,0 +1,153 @@
+# 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.
+- 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` and `refine`; 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.
+
+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` and
+`refine`.
+
+Strict object IR emits two shapes. When every declared key is required and has
+already passed the data-property descriptor check, generated validators compare
+`Object.getOwnPropertyNames(value).length` with the declared key count and
+require `Object.getOwnPropertySymbols(value).length === 0`. This keeps
+non-enumerable and symbol extras rejected without paying a `Reflect.ownKeys`
+membership loop on the common all-required path. 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.
+
+## 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` and `refine` fallbacks use the same IR-backed runtime path, so
+recursive behavior stays consistent across execution engines.
+
+## 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 release smoke on 2026-07-04 KST reported this ecosystem boolean
+path over the JSON-compatible strict-object benchmark:
+
+| Case | TypeSea runtime plan | TypeSea compiled | Ajv compiled |
+| --- | ---: | ---: | ---: |
+| Valid object | 496,270 hz | 4,237,892 hz | 4,312,174 hz |
+| Invalid object | 3,422,416 hz | 27,125,445 hz | 28,953,501 hz |
+
+Benchmark numbers are machine-local telemetry. They are useful for catching
+regressions, not for promising a fixed throughput floor.