@lankajs/typebox 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lankajs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @lankajs/typebox
+
+**▸ module** · TypeBox conveniences
+
+> A bridge for the one library in the family with no Standard Schema, and a compiled checker it caches.
+
+A library in the same box. The app imports and calls it; core does not know it exists.
+
+**Runs in:** the browser, node and React Native — everywhere.
+
+**How to use it:** [GUIDE.md](./GUIDE.md) — the user guide, with examples. **How to change it:** [SKILL.md](./SKILL.md).
+
+## Contents
+
+- `lankaTypeBoxValidator` — the bridge, over a compiled checker cached per schema
+- `TLankaInferred<S>` — schema type inference
+
+## Why a bridge rather than a name
+
+TypeBox publishes no `~standard` at all — not asynchronously like yup, not at all —
+so core's port cannot be handed a TypeBox schema. The bridge reads
+`Value`/`TypeCompiler` and produces the same two lists every package in the family
+produces.
+
+## Why the compiled checker is cached, and why that is not premature
+
+`TypeCompiler.Compile(schema)` turns a schema into a function, and the function is the
+fastest validator in JavaScript. Compilation itself is not fast. Compiling on every
+call would make this the SLOWEST package in the family while advertising the
+opposite — the exact shape of a claim that measures well in a microbenchmark and
+loses in an application.
+
+So a `WeakMap` keyed by the schema object holds the compiled checker and whether the
+schema contains a transform. Weak because the key is the consumer's schema: a strong
+map here would keep every schema a screen ever built alive for the life of the tab.
+
+## Why `Decode` is not simply always called
+
+`Value.Decode` applies transforms AND re-checks, so calling it after the compiled
+check would validate every body twice. `HasTransform` is asked once per schema and
+cached beside the checker, so a schema without transforms — which is most of them —
+pays for one pass.
+
+---
+
+Repository map: [../../../README.md](../../../README.md)

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { TSchema, Static } from '@sinclair/typebox';
+import { TLankaValidationResult } from 'lanka/validation';
+
+/**
+ * The validator's shape, typed by a TypeBox schema rather than by core's port.
+ *
+ * `ILankaValidator` takes a `TLankaSchema` — a Standard Schema — and TypeBox
+ * publishes none, so a validator declared as the port would reject every schema a
+ * consumer of this package has. The SHAPE is the port's, member for member, and
+ * `check:family` holds the barrel to the family's surface; what differs is the
+ * one type the library makes impossible to share.
+ */
+interface ILankaTypeBoxValidator {
+    /** Validates and returns the parsed value, or throws. */
+    validate<TSchemaType extends TSchema>(schema: TSchemaType, data: unknown, context: string): Static<TSchemaType>;
+    /** Validates and returns an outcome, throwing nothing. */
+    validateSafe<TSchemaType extends TSchema>(schema: TSchemaType, data: unknown): TLankaValidationResult<Static<TSchemaType>>;
+}
+/**
+ * The validator for TypeBox schemas.
+ *
+ * ## Why this one is a bridge
+ *
+ * TypeBox publishes no `~standard` at all — not asynchronously as yup does, not
+ * at all — so core's port cannot be handed a TypeBox schema and the package is
+ * what makes the library usable here.
+ *
+ * ## What it costs, and why the cache is not premature
+ *
+ * `TypeCompiler.Compile(schema)` produces the fastest validator in JavaScript,
+ * and compiling is the slow part. Compiled per call, this would be the slowest
+ * package in the family while claiming to be the fastest. The checker is cached
+ * per schema instead — see `compiledTypeBoxSchema`.
+ *
+ * A schema built inside a component body is a new object on every render and
+ * therefore a new cache key. Declare schemas at module level, which is where they
+ * belong for every other reason too.
+ */
+declare const lankaTypeBoxValidator: ILankaTypeBoxValidator;
+
+/** The type a schema infers. Shorter than `Static<typeof schema>` everywhere. */
+type TLankaInferred<TSchemaType extends TSchema> = Static<TSchemaType>;
+
+export { type TLankaInferred, lankaTypeBoxValidator };

package/dist/index.js

@@ -0,0 +1,81 @@
+// src/lanka-type-box-validator/lankaTypeBoxValidator.ts
+import { KindGuard } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { LankaValidationError } from "lanka/validation";
+import { lankaForeignSchemaMessage, lankaValueOrThrow } from "lanka/internal";
+
+// src/_internal/compiled-type-box-schema/compiledTypeBoxSchema.ts
+import { TypeCompiler } from "@sinclair/typebox/compiler";
+import { HasTransform } from "@sinclair/typebox/value";
+var compiled = /* @__PURE__ */ new WeakMap();
+var compiledTypeBoxSchema = (schema) => {
+  const known = compiled.get(schema);
+  if (known) return known;
+  const fresh = {
+    check: TypeCompiler.Compile(schema),
+    transforms: HasTransform(schema, [])
+  };
+  compiled.set(schema, fresh);
+  return fresh;
+};
+
+// src/_utils/type-box-pointer-segments/typeBoxPointerSegments.ts
+var typeBoxPointerSegments = (pointer) => {
+  if (!pointer) return [];
+  return pointer.split("/").slice(1).map((segment) => {
+    const key = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+    return /^\d+$/.test(key) ? Number(key) : key;
+  });
+};
+
+// src/lanka-type-box-validator/lankaTypeBoxValidator.ts
+var lankaTypeBoxValidator = Object.freeze({
+  validate(schema, data, context) {
+    return lankaValueOrThrow(runCompiled(schema, data), context);
+  },
+  validateSafe(schema, data) {
+    return runCompiled(schema, data);
+  }
+});
+function runCompiled(schema, data) {
+  if (!KindGuard.IsSchema(schema)) throw notATypeBoxSchema(schema);
+  const { check, transforms } = compiledTypeBoxSchema(schema);
+  if (!check.Check(data)) return describeFailure([...check.Errors(data)]);
+  if (!transforms) return { success: true, data };
+  return decode(schema, data);
+}
+function notATypeBoxSchema(schema) {
+  return new LankaValidationError(
+    lankaForeignSchemaMessage(schema, {
+      lead: "This is not a TypeBox schema: it carries no `Kind`."
+    }),
+    []
+  );
+}
+function decode(schema, data) {
+  try {
+    return { success: true, data: Value.Decode(schema, data) };
+  } catch (error) {
+    const message = decodeFailureMessage(error);
+    return { success: false, errors: [message], fields: [{ path: [], message }] };
+  }
+}
+function decodeFailureMessage(error) {
+  const original = error.error ?? error;
+  return original instanceof Error ? original.message : String(original);
+}
+function describeFailure(errors) {
+  const fields = errors.map(toFieldError);
+  return { success: false, errors: fields.map(describeField), fields };
+}
+function toFieldError(error) {
+  return { path: typeBoxPointerSegments(error.path), message: error.message };
+}
+function describeField(field) {
+  const path = field.path.join(".");
+  return path ? `${path}: ${field.message}` : field.message;
+}
+export {
+  lankaTypeBoxValidator
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lanka-type-box-validator/lankaTypeBoxValidator.ts","../src/_internal/compiled-type-box-schema/compiledTypeBoxSchema.ts","../src/_utils/type-box-pointer-segments/typeBoxPointerSegments.ts"],"sourcesContent":["import { KindGuard } from \"@sinclair/typebox\";\nimport { Value } from \"@sinclair/typebox/value\";\nimport { LankaValidationError } from \"lanka/validation\";\nimport { lankaForeignSchemaMessage, lankaValueOrThrow } from \"lanka/internal\";\nimport type { Static, TSchema } from \"@sinclair/typebox\";\nimport type { ValueError } from \"@sinclair/typebox/value\";\nimport type { TLankaValidationResult } from \"lanka/validation\";\nimport type { ILankaFieldError } from \"lanka/errors\";\nimport { compiledTypeBoxSchema } from \"../_internal/compiled-type-box-schema/compiledTypeBoxSchema\";\nimport { typeBoxPointerSegments } from \"../_utils/type-box-pointer-segments/typeBoxPointerSegments\";\n\n/**\n * The validator's shape, typed by a TypeBox schema rather than by core's port.\n *\n * `ILankaValidator` takes a `TLankaSchema` — a Standard Schema — and TypeBox\n * publishes none, so a validator declared as the port would reject every schema a\n * consumer of this package has. The SHAPE is the port's, member for member, and\n * `check:family` holds the barrel to the family's surface; what differs is the\n * one type the library makes impossible to share.\n */\nexport interface ILankaTypeBoxValidator {\n\t/** Validates and returns the parsed value, or throws. */\n\tvalidate<TSchemaType extends TSchema>(\n\t\tschema: TSchemaType,\n\t\tdata: unknown,\n\t\tcontext: string,\n\t): Static<TSchemaType>;\n\t/** Validates and returns an outcome, throwing nothing. */\n\tvalidateSafe<TSchemaType extends TSchema>(\n\t\tschema: TSchemaType,\n\t\tdata: unknown,\n\t): TLankaValidationResult<Static<TSchemaType>>;\n}\n\n/**\n * The validator for TypeBox schemas.\n *\n * ## Why this one is a bridge\n *\n * TypeBox publishes no `~standard` at all — not asynchronously as yup does, not\n * at all — so core's port cannot be handed a TypeBox schema and the package is\n * what makes the library usable here.\n *\n * ## What it costs, and why the cache is not premature\n *\n * `TypeCompiler.Compile(schema)` produces the fastest validator in JavaScript,\n * and compiling is the slow part. Compiled per call, this would be the slowest\n * package in the family while claiming to be the fastest. The checker is cached\n * per schema instead — see `compiledTypeBoxSchema`.\n *\n * A schema built inside a component body is a new object on every render and\n * therefore a new cache key. Declare schemas at module level, which is where they\n * belong for every other reason too.\n */\nexport const lankaTypeBoxValidator: ILankaTypeBoxValidator = Object.freeze<ILankaTypeBoxValidator>({\n\tvalidate<TSchemaType extends TSchema>(\n\t\tschema: TSchemaType,\n\t\tdata: unknown,\n\t\tcontext: string,\n\t): Static<TSchemaType> {\n\t\treturn lankaValueOrThrow(runCompiled(schema, data), context);\n\t},\n\n\tvalidateSafe<TSchemaType extends TSchema>(\n\t\tschema: TSchemaType,\n\t\tdata: unknown,\n\t): TLankaValidationResult<Static<TSchemaType>> {\n\t\treturn runCompiled(schema, data);\n\t},\n});\n\n/**\n * One pass through the compiled checker, and a second only if the schema asks.\n *\n * `Value.Decode` applies transforms AND re-checks, so calling it unconditionally\n * would validate every body twice. Whether the schema transforms at all is\n * answered once per schema and cached beside the checker.\n */\nfunction runCompiled<TSchemaType extends TSchema>(\n\tschema: TSchemaType,\n\tdata: unknown,\n): TLankaValidationResult<Static<TSchemaType>> {\n\tif (!KindGuard.IsSchema(schema)) throw notATypeBoxSchema(schema);\n\n\tconst { check, transforms } = compiledTypeBoxSchema(schema);\n\n\tif (!check.Check(data)) return describeFailure([...check.Errors(data)]);\n\tif (!transforms) return { success: true, data: data as Static<TSchemaType> };\n\n\treturn decode(schema, data);\n}\n\n/**\n * The refusal for a schema from another library.\n *\n * An application whose schemas come from two libraries eventually hands one to\n * the wrong validator. Unguarded, `TypeCompiler.Compile` was handed a zod schema\n * and threw `TypeCompilerTypeGuardError: Preflight validation check failed` —\n * accurate, and useless to anyone who has not read TypeBox's source. It escaped\n * `validateSafe`, which promises to throw nothing, as a raw library error.\n *\n * `KindGuard.IsSchema` is TypeBox's own answer to the question, so the guard\n * cannot drift from what `Compile` will accept.\n *\n * It throws from `validateSafe` too, deliberately: a refused VALUE is an outcome\n * a form renders, while a schema this package cannot read is a wiring mistake,\n * and putting it in `errors` would show a programmer's error to a user beside an\n * input.\n */\nfunction notATypeBoxSchema(schema: unknown): LankaValidationError {\n\treturn new LankaValidationError(\n\t\tlankaForeignSchemaMessage(schema, {\n\t\t\tlead: \"This is not a TypeBox schema: it carries no `Kind`.\",\n\t\t}),\n\t\t[],\n\t);\n}\n\n/**\n * The transform pass, for a schema that has one.\n *\n * A decode function is consumer code and may throw — a date that does not parse,\n * an enum with no case for the value. That is a refusal of the body, not a crash\n * of the validator, so it comes back as one: `validateSafe` promises to throw\n * nothing.\n */\nfunction decode<TSchemaType extends TSchema>(\n\tschema: TSchemaType,\n\tdata: unknown,\n): TLankaValidationResult<Static<TSchemaType>> {\n\ttry {\n\t\treturn { success: true, data: Value.Decode(schema, data) };\n\t} catch (error) {\n\t\tconst message = decodeFailureMessage(error);\n\n\t\treturn { success: false, errors: [message], fields: [{ path: [], message }] };\n\t}\n}\n\n/**\n * What a failed decode should SAY.\n *\n * TypeBox wraps whatever the decode function threw in a `TransformDecodeError`\n * and copies across a message only when the thrown value was an `Error` —\n * anything else becomes the literal string \"Unknown error\", which tells a\n * consumer nothing about their own code. The original is kept on `.error`, so\n * that is what is read first.\n */\nfunction decodeFailureMessage(error: unknown): string {\n\tconst original = (error as { error?: unknown }).error ?? error;\n\n\treturn original instanceof Error ? original.message : String(original);\n}\n\n/** A TypeBox failure as the two lists the port promises: one for a banner, one for a form. */\nfunction describeFailure<TOutput>(errors: ValueError[]): TLankaValidationResult<TOutput> {\n\tconst fields = errors.map(toFieldError);\n\n\treturn { success: false, errors: fields.map(describeField), fields };\n}\n\nfunction toFieldError(error: ValueError): ILankaFieldError {\n\treturn { path: typeBoxPointerSegments(error.path), message: error.message };\n}\n\n/**\n * A field path plus its message, for a banner.\n *\n * Dots rather than TypeBox's pointer spelling, because this string is read beside\n * the other five packages' and the family reads one way.\n */\nfunction describeField(field: ILankaFieldError): string {\n\tconst path = field.path.join(\".\");\n\n\treturn path ? `${path}: ${field.message}` : field.message;\n}\n","import { TypeCompiler } from \"@sinclair/typebox/compiler\";\nimport { HasTransform } from \"@sinclair/typebox/value\";\nimport type { TSchema } from \"@sinclair/typebox\";\nimport type { TypeCheck } from \"@sinclair/typebox/compiler\";\n\n/** What is known about one schema once, and re-read on every call after that. */\nexport interface ICompiledTypeBoxSchema {\n\t/** The compiled checker: a function TypeBox generated for this schema. */\n\tcheck: TypeCheck<TSchema>;\n\t/**\n\t * Whether anything in the schema transforms.\n\t *\n\t * Asked once because the answer cannot change — a schema is a value — and\n\t * because it decides whether a second pass is needed at all. Most schemas do\n\t * not transform, and those must not pay for `Value.Decode`'s re-check.\n\t */\n\ttransforms: boolean;\n}\n\n/**\n * The compiled checker for a schema, compiled at most once.\n *\n * ## Why this exists\n *\n * `TypeCompiler.Compile` turns a schema into a generated function, and that\n * function is the fastest validator in JavaScript. Compiling is not fast.\n * Compiling per call would make this the SLOWEST package in the family while the\n * README advertised the opposite — the exact shape of a claim that wins a\n * microbenchmark and loses in an application.\n *\n * ## Why a WeakMap\n *\n * The key is the CONSUMER'S schema object. A strong map would keep every schema\n * any screen ever built alive for the life of the tab, which is a leak the\n * consumer cannot see, cannot measure and cannot clear. Weak, the entry goes when\n * the schema does.\n *\n * A schema rebuilt on every render defeats the cache — it is a new key each\n * time — and that is a fact worth knowing rather than a case to work around:\n * declare schemas at module level, which is where they belong anyway.\n */\nconst compiled = new WeakMap<TSchema, ICompiledTypeBoxSchema>();\n\nexport const compiledTypeBoxSchema = (schema: TSchema): ICompiledTypeBoxSchema => {\n\tconst known = compiled.get(schema);\n\tif (known) return known;\n\n\tconst fresh: ICompiledTypeBoxSchema = {\n\t\tcheck: TypeCompiler.Compile(schema),\n\t\ttransforms: HasTransform(schema, []),\n\t};\n\n\tcompiled.set(schema, fresh);\n\n\treturn fresh;\n};\n","/**\n * A TypeBox error pointer as segments: `/tags/0/id` → `[\"tags\", 0, \"id\"]`.\n *\n * TypeBox addresses a field with a JSON Pointer (RFC 6901). `ILankaFieldError.path`\n * is segments, on purpose: the two form libraries the shape was designed against\n * spell the same address differently, and neither can be parsed back out of a\n * joined string safely.\n *\n * The pointer's two escapes are not decoration. `~1` is a literal `/` in a key\n * and `~0` a literal `~`; unescaped, a key containing a slash would split into\n * two segments addressing nothing. **In this order** — `~1` first, then `~0` —\n * because the reverse turns `~01` into `/` instead of the literal `~1` it is.\n *\n * A segment of digits becomes a NUMBER. A form distinguishes the second element\n * of a list from a key spelled `\"1\"`, and JSON Pointer does not carry the\n * difference itself — it is recovered from the shape of the segment, which is\n * what every JSON Pointer implementation does.\n *\n * The root pointer is the empty string, and an empty array is what the port's\n * consumers already read as \"the value as a whole\".\n */\nexport const typeBoxPointerSegments = (pointer: string | undefined): (string | number)[] => {\n\tif (!pointer) return [];\n\n\treturn pointer\n\t\t.split(\"/\")\n\t\t.slice(1)\n\t\t.map((segment) => {\n\t\t\tconst key = segment.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n\n\t\t\treturn /^\\d+$/.test(key) ? Number(key) : key;\n\t\t});\n};\n"],"mappings":";AAAA,SAAS,iBAAiB;AAC1B,SAAS,aAAa;AACtB,SAAS,4BAA4B;AACrC,SAAS,2BAA2B,yBAAyB;;;ACH7D,SAAS,oBAAoB;AAC7B,SAAS,oBAAoB;AAwC7B,IAAM,WAAW,oBAAI,QAAyC;AAEvD,IAAM,wBAAwB,CAAC,WAA4C;AACjF,QAAM,QAAQ,SAAS,IAAI,MAAM;AACjC,MAAI,MAAO,QAAO;AAElB,QAAM,QAAgC;AAAA,IACrC,OAAO,aAAa,QAAQ,MAAM;AAAA,IAClC,YAAY,aAAa,QAAQ,CAAC,CAAC;AAAA,EACpC;AAEA,WAAS,IAAI,QAAQ,KAAK;AAE1B,SAAO;AACR;;;AClCO,IAAM,yBAAyB,CAAC,YAAqD;AAC3F,MAAI,CAAC,QAAS,QAAO,CAAC;AAEtB,SAAO,QACL,MAAM,GAAG,EACT,MAAM,CAAC,EACP,IAAI,CAAC,YAAY;AACjB,UAAM,MAAM,QAAQ,QAAQ,OAAO,GAAG,EAAE,QAAQ,OAAO,GAAG;AAE1D,WAAO,QAAQ,KAAK,GAAG,IAAI,OAAO,GAAG,IAAI;AAAA,EAC1C,CAAC;AACH;;;AFsBO,IAAM,wBAAgD,OAAO,OAA+B;AAAA,EAClG,SACC,QACA,MACA,SACsB;AACtB,WAAO,kBAAkB,YAAY,QAAQ,IAAI,GAAG,OAAO;AAAA,EAC5D;AAAA,EAEA,aACC,QACA,MAC8C;AAC9C,WAAO,YAAY,QAAQ,IAAI;AAAA,EAChC;AACD,CAAC;AASD,SAAS,YACR,QACA,MAC8C;AAC9C,MAAI,CAAC,UAAU,SAAS,MAAM,EAAG,OAAM,kBAAkB,MAAM;AAE/D,QAAM,EAAE,OAAO,WAAW,IAAI,sBAAsB,MAAM;AAE1D,MAAI,CAAC,MAAM,MAAM,IAAI,EAAG,QAAO,gBAAgB,CAAC,GAAG,MAAM,OAAO,IAAI,CAAC,CAAC;AACtE,MAAI,CAAC,WAAY,QAAO,EAAE,SAAS,MAAM,KAAkC;AAE3E,SAAO,OAAO,QAAQ,IAAI;AAC3B;AAmBA,SAAS,kBAAkB,QAAuC;AACjE,SAAO,IAAI;AAAA,IACV,0BAA0B,QAAQ;AAAA,MACjC,MAAM;AAAA,IACP,CAAC;AAAA,IACD,CAAC;AAAA,EACF;AACD;AAUA,SAAS,OACR,QACA,MAC8C;AAC9C,MAAI;AACH,WAAO,EAAE,SAAS,MAAM,MAAM,MAAM,OAAO,QAAQ,IAAI,EAAE;AAAA,EAC1D,SAAS,OAAO;AACf,UAAM,UAAU,qBAAqB,KAAK;AAE1C,WAAO,EAAE,SAAS,OAAO,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC,EAAE;AAAA,EAC7E;AACD;AAWA,SAAS,qBAAqB,OAAwB;AACrD,QAAM,WAAY,MAA8B,SAAS;AAEzD,SAAO,oBAAoB,QAAQ,SAAS,UAAU,OAAO,QAAQ;AACtE;AAGA,SAAS,gBAAyB,QAAuD;AACxF,QAAM,SAAS,OAAO,IAAI,YAAY;AAEtC,SAAO,EAAE,SAAS,OAAO,QAAQ,OAAO,IAAI,aAAa,GAAG,OAAO;AACpE;AAEA,SAAS,aAAa,OAAqC;AAC1D,SAAO,EAAE,MAAM,uBAAuB,MAAM,IAAI,GAAG,SAAS,MAAM,QAAQ;AAC3E;AAQA,SAAS,cAAc,OAAiC;AACvD,QAAM,OAAO,MAAM,KAAK,KAAK,GAAG;AAEhC,SAAO,OAAO,GAAG,IAAI,KAAK,MAAM,OAAO,KAAK,MAAM;AACnD;","names":[]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lankajs/typebox",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "module: A bridge for the one library in the family with no Standard Schema, and a compiled checker it caches.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lankajs/lanka.git",
+    "directory": "modules/validators/typebox"
+  },
+  "homepage": "https://github.com/lankajs/lanka/tree/main/modules/validators/typebox#readme",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "skills"
+  ],
+  "dependencies": {
+    "lanka": "^1.3.0"
+  },
+  "devDependencies": {
+    "@lankajs/tool-testing": "^1.2.0"
+  },
+  "peerDependencies": {
+    "@sinclair/typebox": "^0.34.52"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint src _playground --max-warnings=0",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "bench": "vitest bench --run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/lanka-typebox/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: lanka-typebox
+description: Validate server responses with TypeBox schemas in a lanka application. Use when adding validation to a gateway, when a lanka app's schemas are TypeBox, when core's validator cannot accept a TypeBox schema, when a response shape must be mapped into the application's own, or when reviewing code that imports `@lankajs/typebox`.
+license: MIT
+metadata:
+    author: lankajs
+    package: @lankajs/typebox
+    version: "1.0.0"
+---
+
+# @lankajs/typebox
+
+A bridge over TypeBox's compiled checker, plus `TLankaInferred`. `reference.md`
+beside this file is the full guide.
+
+> [!NOTE]
+> Only what the framework or a gate refuses is binding. Everything else here is a
+> recommendation you can adapt.
+
+## Do you need it?
+
+**Yes.** TypeBox publishes no `~standard` at all, and lanka's validation port
+speaks Standard Schema and nothing else. There is no version of "just use
+`lankaStandardValidator`" that compiles or runs.
+
+Install this **or** another package from `modules/validators/`, never two.
+
+## Declare schemas at MODULE level
+
+This is the one rule that costs real performance if ignored.
+`TypeCompiler.Compile(schema)` produces the fastest validator in JavaScript, and
+compiling is the slow part. The package compiles each schema once and caches it
+in a `WeakMap` keyed by the schema OBJECT.
+
+```ts
+// ✗ a new object every render — recompiled every render
+const Screen = () => {
+	const schema = Type.Object({ id: Type.Number() });
+};
+
+// ✓ compiled once
+const screenSchema = Type.Object({ id: Type.Number() });
+```
+
+## Use
+
+```ts
+const todoSchema = Type.Object({
+	id: Type.Number(),
+	title: Type.String(),
+	done: Type.Boolean(),
+});
+
+// in a gateway: a failing body is a broken contract, not a branch
+const todo = lankaTypeBoxValidator.validate(todoSchema, body, "todos.byId");
+
+// in a form: failure is ordinary
+const result = lankaTypeBoxValidator.validateSafe(todoSchema, body);
+if (!result.success) showErrors(result.errors);
+```
+
+```ts
+type ITodo = TLankaInferred<typeof todoSchema>;
+```
+
+The third argument is the label. It appears in the error and the log, and it is
+what turns "invalid response" into "which call".
+
+## What a failure looks like
+
+```ts
+result.errors; // ["tags.0.id: Expected number"]         — for a banner
+result.fields; // [{ path: ["tags", 0, "id"], message }] — for a form
+```
+
+TypeBox reports a JSON Pointer — `/tags/0/id`. `path` is segments with the index
+as a **number**, and `~1` / `~0` escapes are decoded. A root failure has an
+**empty** path.
+
+## Mapping a wire format
+
+```ts
+const todoFromApi = Type.Transform(Type.Object({ todo_id: Type.Number() }))
+	.Decode((wire) => ({ id: wire.todo_id }))
+	.Encode((domain) => ({ todo_id: domain.id }));
+
+const domain = lankaTypeBoxValidator.validate(todoFromApi, wire, "todos.map");
+return lankaTypeBoxValidator.validate(todoSchema, domain, "todos.check");
+```
+
+A schema without transforms never pays for the decode pass. A decode function
+that throws is a refused body, not a crash.
+
+## Never do these
+
+- **Never build a schema inside a component body.** It is a new cache key on
+  every render.
+- **Never reach for `lankaStandardValidator` with a TypeBox schema.** It cannot
+  take one.
+- **Never validate outside the gateway.**
+- **Never install two validation packages.**
+- **Never expect `validate` to return a result object.** It throws;
+  `validateSafe` returns.
+- **Never trust `format: "email"` without registering the format.** Unregistered,
+  it is reported as `Unknown format` and checks nothing. Use `pattern`, or
+  register it at start-up.
+
+## Symptom → cause
+
+| What you see                                | What it is                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| validation slower than expected             | a schema rebuilt per render — nothing is cached  |
+| "Unknown format" in a message               | a `format` keyword nothing registered            |
+| a path like `/a/b` reaching your form       | not from here — this package returns segments    |
+| "invalid response" with no idea which       | a label that does not identify the call          |
+
+## More
+
+`reference.md` — the full guide, including what the bridge does with JSON
+Pointer escapes.

package/skills/lanka-typebox/reference.md

@@ -0,0 +1,173 @@
+<!-- Generated from modules/validators/typebox/GUIDE.md by scripts/skills.mjs. Edit the guide. -->
+
+> **`@lankajs/typebox@1.0.0`** — this document describes that version.
+>
+> Install: `npm install @lankajs/typebox @sinclair/typebox react zustand` (the peers are not optional; only npm adds a missing one for you).
+>
+> Complete code, compiled and run in CI: [modules/validators/typebox/_playground/playground.test.ts](https://github.com/lankajs/lanka/blob/main/modules/validators/typebox/_playground/playground.test.ts)
+
+# @lankajs/typebox — user guide
+
+The bridge for the one library in the family with no Standard Schema, over a
+compiled checker it caches, plus a `TLankaInferred` helper.
+
+## You will learn
+
+- why this package is required rather than a matter of taste
+- why your schemas must live at module level, and what it costs when they do not
+- how to map a wire format with `Type.Transform`
+
+## When to reach for this
+
+The moment your schemas are TypeBox. Core's validator cannot be handed one.
+
+> [!NOTE]
+> Everything below is how this package is _meant_ to be used, not how it must
+> be. The framework bends at the seams it publishes — see
+> [ARCHITECTURE.md](https://github.com/lankajs/lanka/blob/main/ARCHITECTURE.md) for what is checked and what is
+> merely advice.
+
+## Install
+
+```bash
+npm install @lankajs/typebox @sinclair/typebox
+```
+
+## Do I need it?
+
+Yes. TypeBox publishes no `~standard` at all — not asynchronously as yup does,
+not at all — and core's port speaks
+[Standard Schema](https://standardschema.dev) and nothing else. There is no
+version of "just use `lankaStandardValidator`" that compiles or runs.
+
+## Use
+
+```ts
+import { lankaTypeBoxValidator } from "@lankajs/typebox";
+import { Type } from "@sinclair/typebox";
+
+// at MODULE level — see below, this is not a style point
+const todoSchema = Type.Object({
+	id: Type.Number(),
+	title: Type.String(),
+	done: Type.Boolean(),
+});
+
+// throws a LankaValidationError, with the label in the message
+const todo = lankaTypeBoxValidator.validate(todoSchema, body, "todos.byId");
+
+// or ask instead of throwing
+const result = lankaTypeBoxValidator.validateSafe(todoSchema, body);
+if (!result.success) showErrors(result.errors);
+```
+
+`validate` is what a gateway wants: a body that fails is a broken contract, not a
+branch to handle. `validateSafe` is for a form, where failure is ordinary.
+
+## Declare schemas at module level
+
+`TypeCompiler.Compile(schema)` turns a schema into a generated function — the
+fastest validator in JavaScript — and **compiling is the slow part**. This
+package compiles each schema once and keeps the result in a `WeakMap` keyed by
+the schema object.
+
+A schema built inside a component body is a **new object on every render**, so it
+is a new cache key and it is compiled again each time. The package's own bench
+measures exactly that row, beside the cached one, so the cost is a number rather
+than a warning.
+
+```ts
+// ✗ compiled on every render
+const Screen = () => {
+	const schema = Type.Object({ id: Type.Number() });
+	…
+};
+
+// ✓ compiled once, for the life of the module
+const screenSchema = Type.Object({ id: Type.Number() });
+```
+
+The map is **weak** on purpose: the key is your schema, and a strong map would
+keep every schema any screen ever built alive for the life of the tab.
+
+## Types
+
+```ts
+import type { TLankaInferred } from "@lankajs/typebox";
+
+type ITodo = TLankaInferred<typeof todoSchema>;
+```
+
+## What you get back when it fails
+
+```ts
+result.errors; // ["tags.0.id: Expected number", …]      — for a banner
+result.fields; // [{ path: ["tags", 0, "id"], message }] — for a form
+```
+
+TypeBox addresses a field with a JSON Pointer — `/tags/0/id`. `fields[].path` is
+**segments**, with the index as a number, and the pointer's `~1` / `~0` escapes
+are decoded, so a key containing a slash stays one field.
+
+A failure at the root — `Type.Number()` refusing `"no"` — has an **empty** path:
+the form's root, not an input named `""`.
+
+## Mapping a wire format
+
+A mapping is a schema, not an adapter layer. In TypeBox it is
+`Type.Transform(...).Decode(...)`:
+
+```ts
+const todoFromApi = Type.Transform(
+	Type.Object({ todo_id: Type.Number(), is_done: Type.Union([Type.Literal(0), Type.Literal(1)]) }),
+)
+	.Decode((wire) => ({ id: wire.todo_id, done: wire.is_done === 1 }))
+	.Encode((domain) => ({ todo_id: domain.id, is_done: domain.done ? 1 : 0 }));
+
+const domain = lankaTypeBoxValidator.validate(todoFromApi, wire, "todos.map");
+return lankaTypeBoxValidator.validate(todoSchema, domain, "todos.check");
+```
+
+A schema **without** transforms never pays for the decode pass: whether it has
+one is asked once and cached beside the compiled checker, because `Value.Decode`
+re-checks and calling it unconditionally would validate every body twice.
+
+A decode function that throws is a **refused body**, not a crash — it comes back
+as a failure, because `validateSafe` promises to throw nothing.
+
+## Formats are a registry, not a keyword
+
+`Type.String({ format: "email" })` checks nothing until the application registers
+that format with TypeBox. Unregistered, it is reported as `Unknown format` — a
+rule that looks present in the schema and is not. Use `pattern`, or register the
+format at start-up.
+
+## Where to validate
+
+In the gateway. A gateway is where a body stops being `unknown`; validating in
+the screen instead spreads the same three guards over every consumer, and each
+one gets it slightly differently wrong.
+
+## Common mistakes
+
+**Building the schema inside the component.** It compiles every render. Module
+level.
+
+**Installing two packages from `modules/validators/`.** Pick one.
+
+**Expecting `validate` to return a result object.** It throws. `validateSafe`
+returns.
+
+**Trusting `format` without registering it.**
+
+## Recap
+
+- TypeBox has no Standard Schema, so this package is what makes it work with lanka.
+- Schemas at module level: the compiled checker is cached by object identity.
+- Paths come back as segments, with JSON Pointer escapes decoded.
+- A mapping is `Type.Transform`, and only a schema that has one pays for the decode pass.
+
+---
+
+Maintaining this package: [SKILL.md](https://github.com/lankajs/lanka/blob/main/modules/validators/typebox/SKILL.md) · What it is:
+[README.md](https://github.com/lankajs/lanka/blob/main/modules/validators/typebox/README.md) · Repository map: [../../../README.md](https://github.com/lankajs/lanka/blob/main/README.md)