typesea 0.1.0 → 0.2.0

package/docs/engine-notes.md

@@ -18,6 +18,9 @@ allocation sites, branch behavior, and validation contracts visible in code.
 - 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.
@@ -91,14 +94,51 @@ 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.
+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.
 
 ## Recursion
 
@@ -141,13 +181,16 @@ 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:
+Last local benchmark on 2026-07-04 KST reported these ecosystem paths 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 |
+| Case | TypeSea runtime plan | TypeSea compiled safe | TypeSea compiled unsafe | TypeSea compiled unchecked | Ajv compiled |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Valid `is()` | 513,701 hz | 4,297,306 hz | 36,297,653 hz | 42,581,174 hz | 4,275,389 hz |
+| Valid `check()` | 503,232 hz | 3,903,929 hz | 35,568,425 hz | 40,084,605 hz | 4,278,587 hz |
+| Invalid `is()` | 3,636,369 hz | 42,080,241 hz | 49,654,076 hz | 50,482,732 hz | 27,820,643 hz |
+| Invalid `check()` | 420,446 hz | 2,086,129 hz | 3,077,367 hz | 3,673,508 hz | 28,713,035 hz |
 
 Benchmark numbers are machine-local telemetry. They are useful for catching
-regressions, not for promising a fixed throughput floor.
+regressions, not for promising a fixed throughput floor. Unsafe and unchecked
+numbers are not hostile-input equivalent to safe mode.

package/docs/index.html

@@ -159,31 +159,6 @@
         line-height: 1.5;
       }
 
-      .search {
-        padding: 16px 16px 8px;
-      }
-
-      .search input {
-        width: 100%;
-        min-height: 36px;
-        border: 1px solid var(--sidebar-line);
-        border-radius: 8px;
-        padding: 0 12px;
-        background: rgba(255, 255, 255, 0.06);
-        color: var(--sidebar-ink);
-        font: inherit;
-        font-size: 13px;
-        outline: none;
-      }
-
-      .search input:focus {
-        border-color: #46b48f;
-      }
-
-      .search input::placeholder {
-        color: var(--sidebar-muted);
-      }
-
       .nav {
         flex: 1;
         padding: 6px 12px 18px;
@@ -687,15 +662,12 @@
       <aside class="sidebar" aria-label="Documentation navigation">
         <div class="brand">
           <h1>TypeSea</h1>
-          <span class="version">v0.1.0</span>
+          <span class="version">v0.2.0</span>
         </div>
         <p class="brand-tagline">
           Zero-dependency runtime narrowing for TypeScript.
           ESM-only &middot; Node &ge; 20.19 &middot; MIT
         </p>
-        <div class="search">
-          <input data-search type="search" placeholder="Filter sections&hellip;" aria-label="Filter documentation sections">
-        </div>
         <nav class="nav">
           <p class="nav-group">Guide</p>
           <a href="#overview">Overview</a>
@@ -813,6 +785,22 @@ const schema = toJsonSchema(User);</code></pre>
                 environments, emit validator source ahead of time with <code>emitAotModule()</code>.
               </p>
             </div>
+            <div class="callout warn">
+              <span class="icon">&#9888;</span>
+              <p>
+                <strong>Unsafe FastMode:</strong> <code>compile(User, { mode: "unsafe" })</code>
+                and <code>emitAotModule(User, { mode: "unsafe" })</code> emit direct
+                property and index reads plus an allocation-free strict-key loop for trusted
+                normalized data. They may execute getters, may accept prototype-backed values,
+                strict objects do not reject symbol or non-enumerable extras, and escaped
+                static property keys may appear directly in unsafe predicate source.
+                <code>mode: "unchecked"</code> also skips strict extra-key loops for
+                already-trusted object shapes. Unsafe and unchecked successful
+                <code>check()</code> results are raw <code>{ ok: true, value }</code>
+                objects; failed diagnostics remain frozen and use the same direct-read
+                FastMode object/array/record/discriminant contract where possible.
+              </p>
+            </div>
           </section>
 
           <section id="semantics" data-doc-section data-title="semantics presence optional undefinedable nullable edge nan proto uuid strict">
@@ -1068,23 +1056,71 @@ const schema = toJsonSchema(User);</code></pre>
                 <tbody>
                   <tr>
                     <td>TypeSea runtime plan <code>is()</code></td>
-                    <td class="num">496,270</td>
+                    <td class="num">513,701</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled safe <code>is()</code></td>
+                    <td class="num">4,297,306</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unsafe <code>is()</code></td>
+                    <td class="num">36,297,653</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unchecked <code>is()</code></td>
+                    <td class="num"><span class="best">42,581,174</span></td>
+                  </tr>
+                  <tr>
+                    <td>Zod <code>safeParse</code></td>
+                    <td class="num">1,343,756</td>
+                  </tr>
+                  <tr>
+                    <td>Valibot <code>safeParse</code></td>
+                    <td class="num">1,406,528</td>
+                  </tr>
+                  <tr>
+                    <td>Ajv compiled</td>
+                    <td class="num">4,275,389</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Valid diagnostic path</th>
+                    <th class="num">ops/sec</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td>TypeSea runtime plan <code>check()</code></td>
+                    <td class="num">503,232</td>
                   </tr>
                   <tr>
-                    <td>TypeSea compiled <code>is()</code></td>
-                    <td class="num"><span class="best">4,237,892</span></td>
+                    <td>TypeSea compiled safe <code>check()</code></td>
+                    <td class="num">3,903,929</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unsafe <code>check()</code></td>
+                    <td class="num">35,568,425</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unchecked <code>check()</code></td>
+                    <td class="num"><span class="best">40,084,605</span></td>
                   </tr>
                   <tr>
                     <td>Zod <code>safeParse</code></td>
-                    <td class="num">1,363,792</td>
+                    <td class="num">1,355,014</td>
                   </tr>
                   <tr>
                     <td>Valibot <code>safeParse</code></td>
-                    <td class="num">1,384,892</td>
+                    <td class="num">1,378,266</td>
                   </tr>
                   <tr>
                     <td>Ajv compiled</td>
-                    <td class="num">4,312,174</td>
+                    <td class="num">4,278,587</td>
                   </tr>
                 </tbody>
               </table>
@@ -1100,35 +1136,83 @@ const schema = toJsonSchema(User);</code></pre>
                 <tbody>
                   <tr>
                     <td>TypeSea runtime plan <code>is()</code></td>
-                    <td class="num">3,422,416</td>
+                    <td class="num">3,636,369</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled safe <code>is()</code></td>
+                    <td class="num">42,080,241</td>
                   </tr>
                   <tr>
-                    <td>TypeSea compiled <code>is()</code></td>
-                    <td class="num"><span class="best">27,125,445</span></td>
+                    <td>TypeSea compiled unsafe <code>is()</code></td>
+                    <td class="num">49,654,076</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unchecked <code>is()</code></td>
+                    <td class="num"><span class="best">50,482,732</span></td>
                   </tr>
                   <tr>
                     <td>Zod <code>safeParse</code></td>
-                    <td class="num">83,501</td>
+                    <td class="num">84,272</td>
                   </tr>
                   <tr>
                     <td>Valibot <code>safeParse</code></td>
-                    <td class="num">902,616</td>
+                    <td class="num">878,521</td>
                   </tr>
                   <tr>
                     <td>Ajv compiled</td>
-                    <td class="num">28,953,501</td>
+                    <td class="num">27,820,643</td>
+                  </tr>
+                </tbody>
+              </table>
+            </div>
+            <div class="table-wrap">
+              <table>
+                <thead>
+                  <tr>
+                    <th>Invalid diagnostic path</th>
+                    <th class="num">ops/sec</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  <tr>
+                    <td>TypeSea runtime plan <code>check()</code></td>
+                    <td class="num">420,446</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled safe <code>check()</code></td>
+                    <td class="num">2,086,129</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unsafe <code>check()</code></td>
+                    <td class="num">3,077,367</td>
+                  </tr>
+                  <tr>
+                    <td>TypeSea compiled unchecked <code>check()</code></td>
+                    <td class="num">3,673,508</td>
+                  </tr>
+                  <tr>
+                    <td>Zod <code>safeParse</code></td>
+                    <td class="num">79,613</td>
+                  </tr>
+                  <tr>
+                    <td>Valibot <code>safeParse</code></td>
+                    <td class="num">887,991</td>
+                  </tr>
+                  <tr>
+                    <td>Ajv compiled</td>
+                    <td class="num"><span class="best">28,713,035</span></td>
                   </tr>
                 </tbody>
               </table>
             </div>
             <p class="footnote">
-              Local release smoke, 2026-07-04 KST, single machine &mdash; regression telemetry,
-              not throughput guarantees. The compiled path stays at Ajv-level speed while keeping
-              descriptor-based reads, strict symbol/non-enumerable key rejection, and immutable
-              diagnostics.
+              Local benchmark, 2026-07-04 KST, single machine &mdash; regression telemetry,
+              not throughput guarantees. Safe compiled mode keeps descriptor-based reads,
+              strict symbol/non-enumerable key rejection, and immutable diagnostics. Unsafe
+              and unchecked modes are faster because they are only for trusted normalized data.
             </p>
             <div class="code-block">
-              <pre><code>npm run bench -- --run</code></pre>
+              <pre><code>npm run bench -- bench/ecosystem.bench.ts --run</code></pre>
             </div>
           </section>
 
@@ -1174,69 +1258,5 @@ const schema = toJsonSchema(User);</code></pre>
       </div>
     </div>
 
-    <script>
-      const search = document.querySelector("[data-search]");
-      const sections = Array.from(document.querySelectorAll("[data-doc-section]"));
-      const links = Array.from(document.querySelectorAll(".nav a"));
-      const groups = Array.from(document.querySelectorAll(".nav-group"));
-
-      if (search instanceof HTMLInputElement) {
-        search.addEventListener("input", () => {
-          const query = search.value.trim().toLowerCase();
-          for (const section of sections) {
-            const title = section.getAttribute("data-title") ?? "";
-            const text = section.textContent?.toLowerCase() ?? "";
-            const visible = query === "" || title.includes(query) || text.includes(query);
-            section.classList.toggle("hidden", !visible);
-          }
-          for (const link of links) {
-            const target = link.getAttribute("href") ?? "";
-            const section = target.startsWith("#")
-              ? document.getElementById(target.slice(1))
-              : null;
-            const visible = section === null || !section.classList.contains("hidden");
-            link.classList.toggle("hidden", !visible);
-          }
-          for (const group of groups) {
-            let sibling = group.nextElementSibling;
-            let anyVisible = false;
-            while (sibling !== null && !sibling.classList.contains("nav-group")) {
-              if (sibling.matches("a") && !sibling.classList.contains("hidden")) {
-                anyVisible = true;
-              }
-              sibling = sibling.nextElementSibling;
-            }
-            group.classList.toggle("hidden", !anyVisible);
-          }
-        });
-      }
-
-      const linkById = new Map(
-        links
-          .map((link) => [link.getAttribute("href")?.slice(1) ?? "", link])
-          .filter(([id]) => id !== "")
-      );
-
-      if ("IntersectionObserver" in window) {
-        const observer = new IntersectionObserver(
-          (entries) => {
-            for (const entry of entries) {
-              if (entry.isIntersecting) {
-                for (const link of links) {
-                  link.classList.toggle(
-                    "active",
-                    link === linkById.get(entry.target.id)
-                  );
-                }
-              }
-            }
-          },
-          { rootMargin: "-20% 0px -70% 0px" }
-        );
-        for (const section of sections) {
-          observer.observe(section);
-        }
-      }
-    </script>
   </body>
 </html>

package/package.json

@@ -1,68 +1,68 @@
 {
-  "name": "typesea",
-  "version": "0.1.0",
-  "description": "V8-friendly runtime narrowing for TypeScript with Sea-of-Nodes graph introspection.",
-  "type": "module",
-  "author": "feral",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Feralthedogg/TypeSea.git"
-  },
-  "sideEffects": false,
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+    "name": "typesea",
+    "version": "0.2.0",
+    "description": "V8-friendly runtime narrowing for TypeScript with Sea-of-Nodes graph introspection.",
+    "type": "module",
+    "author": "feral",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Feralthedogg/TypeSea.git"
+    },
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "default": "./dist/index.js"
+        }
+    },
+    "keywords": [
+        "typescript",
+        "typeguard",
+        "type-guard",
+        "runtime-validation",
+        "schema",
+        "narrowing",
+        "v8"
+    ],
+    "files": [
+        "dist",
+        "README.md",
+        "CHANGELOG.md",
+        "docs"
+    ],
+    "scripts": {
+        "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+        "bench": "vitest bench",
+        "check": "npm run policy && npm run check:docs && npm run typecheck && npm run lint && npm run test && npm run build && npm run check:dist && npm run check:api && npm run check:pack",
+        "check:api": "node scripts/public-api-surface.mjs",
+        "check:consumer": "node scripts/consumer-smoke.mjs",
+        "check:docs": "node scripts/docs-site-check.mjs",
+        "check:dist": "node scripts/dist-policy.mjs",
+        "check:pack": "node scripts/package-contents.mjs",
+        "lint": "eslint .",
+        "pack:dry": "npm pack --dry-run --ignore-scripts",
+        "policy": "node scripts/source-policy.mjs",
+        "prepack": "npm run check",
+        "release:check": "node scripts/release-gate.mjs",
+        "test": "vitest run",
+        "typecheck": "tsc -p tsconfig.json --noEmit"
+    },
+    "engines": {
+        "node": ">=20.19"
+    },
+    "license": "MIT",
+    "devDependencies": {
+        "@eslint/js": "^10.0.1",
+        "@types/node": "^26.1.0",
+        "ajv": "^8.20.0",
+        "eslint": "^10.6.0",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.62.1",
+        "valibot": "^1.4.2",
+        "vitest": "^4.1.9",
+        "zod": "^4.4.3"
     }
-  },
-  "keywords": [
-    "typescript",
-    "typeguard",
-    "type-guard",
-    "runtime-validation",
-    "schema",
-    "narrowing",
-    "v8"
-  ],
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "docs"
-  ],
-  "scripts": {
-    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
-    "bench": "vitest bench",
-    "check": "npm run policy && npm run check:docs && npm run typecheck && npm run lint && npm run test && npm run build && npm run check:dist && npm run check:api && npm run check:pack",
-    "check:api": "node scripts/public-api-surface.mjs",
-    "check:consumer": "node scripts/consumer-smoke.mjs",
-    "check:docs": "node scripts/docs-site-check.mjs",
-    "check:dist": "node scripts/dist-policy.mjs",
-    "check:pack": "node scripts/package-contents.mjs",
-    "lint": "eslint .",
-    "pack:dry": "npm pack --dry-run --ignore-scripts",
-    "policy": "node scripts/source-policy.mjs",
-    "prepack": "npm run check",
-    "release:check": "node scripts/release-gate.mjs",
-    "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
-  },
-  "engines": {
-    "node": ">=20.19"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@types/node": "^26.1.0",
-    "ajv": "^8.20.0",
-    "eslint": "^10.6.0",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.62.1",
-    "valibot": "^1.4.2",
-    "vitest": "^4.1.9",
-    "zod": "^4.4.3"
-  }
 }