hyperschema-ts 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,229 @@
+# hyperschema-ts
+
+Generate TypeScript types from a [Hyperschema](https://github.com/holepunchto/hyperschema).
+
+Point it at the same `schema` instance you pass to `Hyperschema.toDisk`, and it writes a `.d.ts` file of `interface`/`type` declarations matching your structs, enums, aliases, arrays and records. You then `import` those types into your app to get static typing over the objects you encode and decode.
+
+## Install
+
+```sh
+npm install hyperschema-ts
+```
+
+## Usage
+
+```js
+const Hyperschema = require('hyperschema')
+const HyperschemaTS = require('hyperschema-ts')
+
+const schema = Hyperschema.from('./schema')
+const ns = schema.namespace('example')
+
+ns.register({
+  name: 'request',
+  fields: [
+    { name: 'id', type: 'uint', required: true },
+    { name: 'name', type: 'string', required: true },
+    { name: 'tags', type: 'string', array: true }
+  ]
+})
+
+// Write the compact-encoding definitions (schema.json + index.js)
+Hyperschema.toDisk(schema)
+
+// Write the matching TypeScript declarations (types.d.ts)
+HyperschemaTS.toDisk(schema)
+```
+
+This writes `./schema/types.d.ts`:
+
+```ts
+// This file is autogenerated by hyperschema-ts
+// Schema version: 1
+// Do not edit manually.
+
+export interface ExampleRequest {
+  id: number
+  name: string
+  tags?: string[] | null
+}
+```
+
+which you import as type-only:
+
+```ts
+import type { ExampleRequest } from './schema/types'
+
+const req: ExampleRequest = { id: 1, name: 'a' }
+```
+
+> On `node16`/`nodenext` resolution, import without an extension as above (a `.d.ts` has no runtime counterpart to point a `.js` specifier at). On `bundler` or classic resolution it resolves either way.
+
+## API
+
+### `HyperschemaTS.toDisk(schema, [dir], [options])`
+
+Writes the generated declarations to disk. Mirrors `Hyperschema.toDisk`:
+
+- `dir` defaults to `schema.dir` (the directory the schema was loaded from).
+- Output file defaults to `<dir>/types.d.ts`.
+
+Returns the path it wrote.
+
+> The output is pure type declarations, so it's emitted as a `.d.ts`. The default name avoids `index.d.ts` on purpose: that would sit next to hyperschema's generated `index.js` and TypeScript would treat it as the declarations _for_ that module (which actually exports `resolveStruct`/`version`, not these types).
+
+### `HyperschemaTS.toCode(schema, [options])`
+
+Returns the generated declarations as a string instead of writing them.
+
+### `HyperschemaTS.typeName(fqn)`
+
+Converts a fully-qualified hyperschema name to its generated TS type name, e.g. `@example/my-struct` → `ExampleMyStruct`.
+
+### Options
+
+- `filename` — override the output path (otherwise `<dir>/types.d.ts`).
+- `externals` — a map of fully-qualified external type name → TS expression to substitute for it (external types default to `unknown`).
+
+## Type mapping
+
+| hyperschema                                             | TypeScript                                                                    |
+| ------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `uint*`, `int*`, `float32/64`, `port`, `lexint`         | `number`                                                                      |
+| `bigint`, `biguint64`, `bigint64`                       | `bigint`                                                                      |
+| `string`, `utf8`, `ascii`, `hex`                        | `string`                                                                      |
+| `ip`, `ipv4`, `ipv6`                                    | `string`                                                                      |
+| `ipAddress`, `ipv4Address`, `ipv6Address`               | `{ host: string; family?: number; port: number }`                             |
+| `bool`                                                  | `boolean`                                                                     |
+| `buffer`, `optionalBuffer`, `fixed32`, `fixed64`, `raw` | `Buffer`                                                                      |
+| `date`                                                  | `Date`                                                                        |
+| `none`                                                  | `null`                                                                        |
+| `json`                                                  | `unknown` (a `json` field can hold any JSON value — object, array, or scalar) |
+| `@ns/name` reference                                    | the generated type name (e.g. `NsName`)                                       |
+
+And the modifiers:
+
+- `array: true` → `T[]`
+- a `record` type → `Record<string, V>` (records decode to a string-keyed object)
+- an `enum` with `strings: true` → a string-literal union (`"a" | "b"`); otherwise a numeric-literal union
+- an `alias` → `type X = <target>`
+
+## Field type overrides (`tsType`)
+
+A `json` field carries no shape information, so it defaults to `unknown`. To brand a field with a concrete TS type — like Drizzle's `.$type<T>()` — add a `tsType` to the field definition. It changes only the generated type, never the encoding:
+
+```js
+ns.register({
+  name: 'doc',
+  fields: [
+    { name: 'metrics', type: 'json', tsType: 'Metrics' }, // → metrics?: Metrics
+    { name: 'status', type: 'string', tsType: '"on" | "off"' }, // → status?: "on" | "off" | null
+    { name: 'ids', type: 'string', array: true, tsType: 'Id' } // → ids?: Id[] | null
+  ]
+})
+```
+
+The override is applied as the element type, so `array: true` still wraps it (`Id[]`). You're responsible for ensuring the referenced type is in scope where the generated file is imported.
+
+### `enum` — narrow a `string` field
+
+For a field that stays `string` on the wire but only holds a fixed set of values (a status/state field you can't model as a real hyperschema enum because of append-only versioning), add an `enum` annotation. `tsType` gives you the compile-time union; `enum` makes [the validator](#validation) enforce membership at runtime:
+
+```js
+{ name: 'state', type: 'string', enum: ['queued', 'running', 'done'], tsType: '"queued" | "running" | "done"' }
+```
+
+`Validation.validate(schema, fqn, { state: 'paused' })` then fails with `state: must be one of "queued", "running", "done"`. For an `array` field the check applies element-wise. (A genuine hyperschema `enum` type is still preferable when you can use one — it also encodes as a 1-byte index and is rejected by compact-encoding itself.)
+
+> Both `tsType` and `enum` are read from the live schema instance. Hyperschema does not persist unknown field keys to `schema.json`, so annotations only take effect when you generate types / validate in the same process that registers the schema (the usual `register` → `toDisk` build script). They are lost across a `Hyperschema.from('./dir')` reload.
+
+## Optional fields and decode semantics
+
+Hyperschema's non-`required` fields don't decode to `undefined` — they decode to the type's default. So the generated types reflect both sides:
+
+- Every optional field is marked `?` (for the encode side).
+- Optional fields whose default is `null` (objects, strings, buffers, arrays) are also unioned with `| null` (for the decode side).
+- Optional scalar fields keep their plain type, since their default is a real value (`0`, `0n`, `false`), not `null`.
+
+```ts
+export interface Example {
+  id: number // required
+  score?: number // optional scalar → decodes to 0
+  blob?: Buffer | null // optional buffer → decodes to null
+  tags?: string[] | null // optional array → decodes to null
+}
+```
+
+> Note: `bool` and bitwise uint fields are always optional, because hyperschema stores them in the struct's flags bitfield.
+
+## Validation
+
+`hyperschema-ts/validation` validates plain objects against a schema type _before_ you hand them to compact-encoding.
+
+This matters because compact-encoding is mostly **silently lenient** — it only throws in a couple of cases and otherwise corrupts bad input without complaint:
+
+| input                | compact-encoding                   |
+| -------------------- | ---------------------------------- |
+| `ipv4("hello")`      | silently encodes `143.0.0.0`       |
+| `uint8(9999)`        | silently truncates to `15`         |
+| `hex("zz")`          | silently encodes `00`              |
+| `uint(-5)`           | **throws** `uint must be positive` |
+| wrong-size `fixed32` | **throws** `Incorrect buffer size` |
+
+The validator rejects everything compact-encoding would throw on _or_ silently corrupt (out-of-range numbers, malformed IPs, wrong buffer sizes, bad enum values, missing required fields, …), with a path for each failure.
+
+```js
+const Validation = require('hyperschema-ts/validation')
+
+const { valid, errors } = Validation.validate(schema, '@example/request', {
+  id: 1,
+  host: 'hello' // not a valid IPv4
+})
+// valid === false
+// errors === [{ path: '@example/request.host', value: 'hello', message: 'must be a valid IPv4 address' }]
+
+// or throw an aggregated error:
+Validation.assert(schema, '@example/request', obj)
+```
+
+### `Validation.validate(schema, fqn, value)`
+
+Returns `{ valid, errors }`, where each error is `{ path, value, message }`. Never throws (except on an unknown `fqn`).
+
+### `Validation.assert(schema, fqn, value)`
+
+Throws an `Error` listing every failure if `value` is invalid; otherwise returns nothing.
+
+### Typed validation (`createValidator`)
+
+Every generated `types.d.ts` also exports a `SchemaTypes` registry mapping each `fqn` to its type. Pass it to `createValidator` and the validator becomes type-safe: `fqn` autocompletes (and typos fail to compile), and `is`/`assert` narrow `value` to the matching type.
+
+```ts
+import HyperschemaValidation from 'hyperschema-ts/validation'
+import type { SchemaTypes } from './schema/types'
+
+const v = HyperschemaValidation.createValidator<SchemaTypes>(schema)
+
+if (v.is('@example/request', value)) {
+  value.id // value is ExampleRequest here
+}
+
+v.assert('@example/request', value) // throws, or narrows value to ExampleRequest
+const { valid, errors } = v.validate('@example/request', value)
+```
+
+A `value is T` guard must return a boolean, so the three forms split by intent:
+
+| method     | returns              | narrows?                  |
+| ---------- | -------------------- | ------------------------- |
+| `validate` | `{ valid, errors }`  | no (use for error detail) |
+| `is`       | `value is T`         | yes (boolean guard)       |
+| `assert`   | `asserts value is T` | yes (throws on failure)   |
+
+> `createValidator` needs a live schema at runtime — typically `Hyperschema.from('./schema')` at startup. Note that a reload-from-disk schema loses field-level `tsType`/`enum` annotations (hyperschema doesn't persist them), so annotation-based `enum` membership only fires when validating against the same instance that registered the schema.
+
+> Records are validated by value; their keys are always JS strings (compact-encoding records key on `Object.keys`). External and versioned types are treated as opaque (not validated structurally).
+
+## License
+
+Apache-2.0

package/index.cjs

@@ -0,0 +1,37 @@
+const fs = require('fs')
+const p = require('path')
+
+const { emit, typeName } = require('./lib/codegen.js')
+
+const CODE_FILE_NAME = 'types.d.ts'
+
+class HyperschemaTS {
+  // Generate a TypeScript declaration string from a (resolved) Hyperschema instance.
+  static toCode(hyperschema, opts = {}) {
+    if (typeof hyperschema.linkAll === 'function') hyperschema.linkAll()
+    return emit(hyperschema, opts)
+  }
+
+  // Mirror Hyperschema.toDisk(schema, dir?, opts?).
+  static toDisk(hyperschema, dir, opts) {
+    if (typeof dir === 'object' && dir) {
+      opts = dir
+      dir = null
+    }
+    opts = opts || {}
+
+    if (typeof hyperschema.linkAll === 'function') hyperschema.linkAll()
+
+    if (!dir) dir = hyperschema.dir
+
+    const codePath = opts.filename || p.join(p.resolve(dir), CODE_FILE_NAME)
+    fs.mkdirSync(p.dirname(codePath), { recursive: true })
+    fs.writeFileSync(codePath, emit(hyperschema, opts), { encoding: 'utf-8' })
+
+    return codePath
+  }
+
+  static typeName = typeName
+}
+
+module.exports = HyperschemaTS

package/index.d.ts

@@ -0,0 +1,25 @@
+export interface HyperschemaTSOptions {
+  /** Override the output path (defaults to `<dir>/types.d.ts`). */
+  filename?: string
+  /** Map of external fully-qualified type name -> TS expression to use for it. */
+  externals?: Record<string, string>
+}
+
+/**
+ * Generates TypeScript type declarations from a Hyperschema instance.
+ * Pass the same `schema` you pass to `Hyperschema.toDisk`.
+ */
+export default class HyperschemaTS {
+  /** Generate the `.ts` source as a string. */
+  static toCode(hyperschema: any, opts?: HyperschemaTSOptions): string
+
+  /** Write the generated declarations to disk. Mirrors `Hyperschema.toDisk`. */
+  static toDisk(
+    hyperschema: any,
+    dir?: string | HyperschemaTSOptions,
+    opts?: HyperschemaTSOptions
+  ): string
+
+  /** Convert a hyperschema fully-qualified name (e.g. `@example/my-struct`) to its TS type name. */
+  static typeName(fqn: string): string
+}

package/index.mjs

@@ -0,0 +1,7 @@
+import HyperschemaTS from './index.cjs'
+
+class ESMHyperschemaTS extends HyperschemaTS {
+  static esm = true
+}
+
+export default ESMHyperschemaTS

package/lib/codegen.js

@@ -0,0 +1,171 @@
+// Generates TypeScript type declarations from a resolved Hyperschema instance.
+// Pure: reads the already-resolved `hyperschema.types` graph, returns a string.
+
+// Maps every compact-encoding primitive (see hyperschema's lib/types.js) to a TS type.
+const PRIMITIVE_GROUPS = {
+  number: [
+    'uint',
+    'uint1',
+    'uint2',
+    'uint3',
+    'uint4',
+    'uint5',
+    'uint6',
+    'uint7',
+    'uint8',
+    'uint16',
+    'uint24',
+    'uint32',
+    'uint40',
+    'uint48',
+    'uint56',
+    'uint64',
+    'int',
+    'int8',
+    'int16',
+    'int24',
+    'int32',
+    'int40',
+    'int48',
+    'int56',
+    'int64',
+    'float32',
+    'float64',
+    'port',
+    'lexint'
+  ],
+  string: ['string', 'utf8', 'ascii', 'hex', 'ip', 'ipv4', 'ipv6'],
+  bigint: ['bigint', 'biguint64', 'bigint64'],
+  Buffer: ['fixed32', 'fixed64', 'buffer', 'optionalBuffer', 'raw'],
+  boolean: ['bool'],
+  Date: ['date'],
+  null: ['none'],
+  unknown: ['json']
+}
+
+// Primitives whose encoded value is an object rather than a scalar.
+const PRIMITIVE_OBJECTS = {
+  ipAddress: '{ host: string; family?: number; port: number }',
+  ipv4Address: '{ host: string; family?: number; port: number }',
+  ipv6Address: '{ host: string; family?: number; port: number }'
+}
+
+const PRIMITIVES = new Map()
+for (const [ts, names] of Object.entries(PRIMITIVE_GROUPS)) {
+  for (const name of names) PRIMITIVES.set(name, ts)
+}
+for (const [name, ts] of Object.entries(PRIMITIVE_OBJECTS)) PRIMITIVES.set(name, ts)
+
+function pascal(segment) {
+  return segment
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((w) => w[0].toUpperCase() + w.slice(1))
+    .join('')
+}
+
+function typeName(fqn) {
+  const stripped = fqn[0] === '@' ? fqn.slice(1) : fqn
+  return stripped.split('/').map(pascal).join('')
+}
+
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+function fieldKey(name) {
+  return IDENT.test(name) ? name : JSON.stringify(name)
+}
+
+// Resolve a ResolvedType (+ array flag) to its TS expression.
+function tsType(type, array, externals) {
+  if (array) return wrap(tsType(type, false, externals)) + '[]'
+  if (type.isPrimitive) return PRIMITIVES.get(type.name) || 'unknown'
+  if (type.isExternal) return externals[type.fqn] || 'unknown'
+  return typeName(type.fqn)
+}
+
+// A field's TS type, honouring a per-field `tsType` annotation (like Drizzle's
+// `.$type<T>()`) which overrides the resolved element type without affecting encoding.
+function fieldTsType(field, externals) {
+  const override = field.description && field.description.tsType
+  if (!override) return tsType(field.type, field.array, externals)
+  return field.array ? wrap(override) + '[]' : override
+}
+
+function wrap(t) {
+  // parenthesise unions before appending `[]`
+  return /[|&]/.test(t) ? `(${t})` : t
+}
+
+function structToInterface(type, externals) {
+  const lines = [`export interface ${typeName(type.fqn)} {`]
+  for (const field of type.fields) {
+    const ts = fieldTsType(field, externals)
+    const def = field.getDefaultValue() // undefined (useDefault:false) | null | scalar
+    if (field.required) {
+      lines.push(`  ${fieldKey(field.name)}: ${ts}`)
+    } else {
+      const nullable = def === null // object/string/buffer/array optionals decode to null
+      lines.push(`  ${fieldKey(field.name)}?: ${ts}${nullable ? ' | null' : ''}`)
+    }
+  }
+  lines.push('}')
+  return lines.join('\n')
+}
+
+function enumToType(type) {
+  if (!type.enum.length) return `export type ${typeName(type.fqn)} = never`
+  const members = type.strings
+    ? type.enum.map((e) => JSON.stringify(e.key))
+    : type.enum.map((_, i) => String(type.offset + i))
+  return `export type ${typeName(type.fqn)} = ${members.join(' | ')}`
+}
+
+// fqn -> generated type name, for every type that produces a top-level declaration.
+function registryToInterface(registry) {
+  const lines = ['export interface SchemaTypes {']
+  for (const [fqn, name] of registry) lines.push(`  ${JSON.stringify(fqn)}: ${name}`)
+  lines.push('}')
+  return lines.join('\n')
+}
+
+function emit(hyperschema, { externals = {}, registry = true } = {}) {
+  const decls = []
+  const entries = []
+
+  for (const type of hyperschema.types.values()) {
+    if (type.derived) continue
+
+    if (type.isStruct) {
+      decls.push(structToInterface(type, externals))
+    } else if (type.isEnum) {
+      decls.push(enumToType(type))
+    } else if (type.isAlias) {
+      decls.push(`export type ${typeName(type.fqn)} = ${tsType(type.type, false, externals)}`)
+    } else if (type.isArray) {
+      decls.push(
+        `export type ${typeName(type.fqn)} = ${wrap(tsType(type.type, false, externals))}[]`
+      )
+    } else if (type.isRecord) {
+      decls.push(
+        `export type ${typeName(type.fqn)} = Record<string, ${tsType(type.value, false, externals)}>`
+      )
+    } else {
+      // primitives / externals / versioned: nothing top-level
+      continue
+    }
+    entries.push([type.fqn, typeName(type.fqn)])
+  }
+
+  if (registry) decls.push(registryToInterface(entries))
+
+  const header = [
+    '// This file is autogenerated by hyperschema-ts',
+    `// Schema version: ${hyperschema.version}`,
+    '// Do not edit manually.',
+    '',
+    ''
+  ].join('\n')
+
+  return header + decls.join('\n\n') + '\n'
+}
+
+module.exports = { emit, typeName }

package/lib/validate.js

@@ -0,0 +1,274 @@
+// Runtime validation of plain objects against a Hyperschema type.
+//
+// compact-encoding is mostly *silently lenient* on bad input (it will encode
+// ipv4('hello') to 143.0.0.0, truncate uint8(9999) to 15, etc.) and only throws
+// in a couple of cases. This walks the same resolved-type graph the codegen uses
+// and rejects everything compact-encoding would either throw on OR silently
+// corrupt, with a field path for each failure.
+
+const MAX_SAFE = Number.MAX_SAFE_INTEGER
+
+function isInt(v) {
+  return typeof v === 'number' && Number.isInteger(v)
+}
+
+function isBytes(v) {
+  return v instanceof Uint8Array
+}
+
+function isPlainObject(v) {
+  return (
+    typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date) && !isBytes(v)
+  )
+}
+
+function isIPv4(s) {
+  const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(s)
+  if (!m) return false
+  for (let i = 1; i <= 4; i++) {
+    if (Number(m[i]) > 255) return false
+  }
+  return true
+}
+
+function isIPv6(s) {
+  if (typeof s !== 'string' || s.indexOf(':') === -1) return false
+  const parts = s.split('::')
+  if (parts.length > 2) return false
+
+  const group = /^[0-9a-fA-F]{1,4}$/
+  const head = parts[0] === '' ? [] : parts[0].split(':')
+  const tail = parts.length === 2 ? (parts[1] === '' ? [] : parts[1].split(':')) : null
+
+  for (const g of head) if (!group.test(g)) return false
+  if (tail) for (const g of tail) if (!group.test(g)) return false
+
+  // No compression: exactly 8 groups. With `::`: fewer groups, rest is zero-filled.
+  return tail === null ? head.length === 8 : head.length + tail.length <= 7
+}
+
+// name -> { test(value) -> boolean, message }
+const PRIMITIVES = new Map()
+
+function set(name, test, message) {
+  PRIMITIVES.set(name, { test, message })
+}
+
+const UINT_BITS = {
+  uint1: 1,
+  uint2: 2,
+  uint3: 3,
+  uint4: 4,
+  uint5: 5,
+  uint6: 6,
+  uint7: 7,
+  uint8: 8,
+  uint16: 16,
+  uint24: 24,
+  uint32: 32,
+  uint40: 40,
+  uint48: 48,
+  uint56: 56,
+  uint64: 64
+}
+for (const [name, bits] of Object.entries(UINT_BITS)) {
+  const max = bits >= 53 ? MAX_SAFE : 2 ** bits - 1
+  set(name, (v) => isInt(v) && v >= 0 && v <= max, `must be an integer in [0, ${max}]`)
+}
+
+const INT_BITS = {
+  int8: 8,
+  int16: 16,
+  int24: 24,
+  int32: 32,
+  int40: 40,
+  int48: 48,
+  int56: 56,
+  int64: 64
+}
+for (const [name, bits] of Object.entries(INT_BITS)) {
+  const max = bits >= 54 ? MAX_SAFE : 2 ** (bits - 1) - 1
+  const min = bits >= 54 ? -MAX_SAFE : -(2 ** (bits - 1))
+  set(name, (v) => isInt(v) && v >= min && v <= max, `must be an integer in [${min}, ${max}]`)
+}
+
+set('uint', (v) => isInt(v) && v >= 0 && v <= MAX_SAFE, 'must be a non-negative safe integer')
+set('int', (v) => isInt(v) && v >= -MAX_SAFE && v <= MAX_SAFE, 'must be a safe integer')
+set('lexint', (v) => isInt(v) && v >= 0 && v <= MAX_SAFE, 'must be a non-negative safe integer')
+PRIMITIVES.set('port', PRIMITIVES.get('uint16'))
+
+set('float32', (v) => typeof v === 'number' && Number.isFinite(v), 'must be a finite number')
+set('float64', (v) => typeof v === 'number' && Number.isFinite(v), 'must be a finite number')
+
+set(
+  'biguint64',
+  (v) => typeof v === 'bigint' && v >= 0n && v <= 0xffffffffffffffffn,
+  'must be a bigint in [0, 2^64 - 1]'
+)
+set(
+  'bigint64',
+  (v) => typeof v === 'bigint' && v >= -(2n ** 63n) && v <= 2n ** 63n - 1n,
+  'must be a bigint in [-2^63, 2^63 - 1]'
+)
+set('biguint', (v) => typeof v === 'bigint' && v >= 0n, 'must be a non-negative bigint')
+set('bigint', (v) => typeof v === 'bigint', 'must be a bigint')
+
+set('string', (v) => typeof v === 'string', 'must be a string')
+PRIMITIVES.set('utf8', PRIMITIVES.get('string'))
+// eslint-disable-next-line no-control-regex
+set('ascii', (v) => typeof v === 'string' && /^[\x00-\x7f]*$/.test(v), 'must be an ASCII string')
+set(
+  'hex',
+  (v) => typeof v === 'string' && v.length % 2 === 0 && /^[0-9a-fA-F]*$/.test(v),
+  'must be a hex string of even length'
+)
+
+set('buffer', isBytes, 'must be a Buffer or Uint8Array')
+PRIMITIVES.set('optionalBuffer', PRIMITIVES.get('buffer'))
+PRIMITIVES.set('raw', PRIMITIVES.get('buffer'))
+set('fixed32', (v) => isBytes(v) && v.byteLength === 32, 'must be a 32-byte buffer')
+set('fixed64', (v) => isBytes(v) && v.byteLength === 64, 'must be a 64-byte buffer')
+
+set('bool', (v) => typeof v === 'boolean', 'must be a boolean')
+set('date', (v) => v instanceof Date && Number.isFinite(v.getTime()), 'must be a valid Date')
+set('none', () => true, '')
+set('json', (v) => v !== undefined, 'must be JSON-serializable')
+
+set('ipv4', (v) => typeof v === 'string' && isIPv4(v), 'must be a valid IPv4 address')
+set('ipv6', (v) => typeof v === 'string' && isIPv6(v), 'must be a valid IPv6 address')
+set('ip', (v) => typeof v === 'string' && (isIPv4(v) || isIPv6(v)), 'must be a valid IP address')
+
+const ADDRESS_HOST = {
+  ipv4Address: isIPv4,
+  ipv6Address: isIPv6,
+  ipAddress: (s) => isIPv4(s) || isIPv6(s)
+}
+
+function err(errors, path, value, message) {
+  errors.push({ path, value, message })
+}
+
+function isPort(v) {
+  return isInt(v) && v >= 0 && v <= 65535
+}
+
+function checkAddress(name, value, path, errors) {
+  if (!isPlainObject(value)) {
+    err(errors, path, value, 'must be an { host, port } object')
+    return
+  }
+  if (typeof value.host !== 'string' || !ADDRESS_HOST[name](value.host)) {
+    err(errors, path + '.host', value.host, 'must be a valid IP address')
+  }
+  if (!isPort(value.port)) {
+    err(errors, path + '.port', value.port, 'must be a port in [0, 65535]')
+  }
+}
+
+// Field-level `enum: [...]` annotation: domain membership for a field whose wire
+// type stays as-is (typically `string`). Mirrors the type-level enum check.
+function checkMembership(allowed, value, array, path, errors) {
+  const message = `must be one of ${allowed.map((a) => JSON.stringify(a)).join(', ')}`
+  const one = (val, p) => {
+    if (!allowed.includes(val)) err(errors, p, val, message)
+  }
+  if (array) {
+    if (Array.isArray(value)) value.forEach((el, i) => one(el, `${path}[${i}]`))
+  } else {
+    one(value, path)
+  }
+}
+
+function checkValue(type, value, array, path, errors) {
+  if (array) {
+    if (!Array.isArray(value)) {
+      err(errors, path, value, 'must be an array')
+      return
+    }
+    for (let i = 0; i < value.length; i++) {
+      checkValue(type, value[i], false, `${path}[${i}]`, errors)
+    }
+    return
+  }
+
+  if (type.isPrimitive) {
+    if (ADDRESS_HOST[type.name]) {
+      checkAddress(type.name, value, path, errors)
+      return
+    }
+    const p = PRIMITIVES.get(type.name)
+    if (p && !p.test(value)) err(errors, path, value, p.message)
+    return
+  }
+
+  if (type.isAlias) {
+    checkValue(type.type, value, false, path, errors)
+    return
+  }
+
+  if (type.isEnum) {
+    const keys = type.enum.map((e) => e.key)
+    const ok = type.strings
+      ? keys.includes(value)
+      : isInt(value) && value >= type.offset && value < type.offset + keys.length
+    if (!ok) {
+      const allowed = type.strings
+        ? keys.map((k) => JSON.stringify(k)).join(', ')
+        : `[${type.offset}, ${type.offset + keys.length - 1}]`
+      err(errors, path, value, `must be one of ${allowed}`)
+    }
+    return
+  }
+
+  if (type.isArray) {
+    checkValue(type.type, value, true, path, errors)
+    return
+  }
+
+  if (type.isRecord) {
+    if (!isPlainObject(value)) {
+      err(errors, path, value, 'must be an object')
+      return
+    }
+    for (const key of Object.keys(value)) {
+      checkValue(type.value, value[key], false, `${path}.${key}`, errors)
+    }
+    return
+  }
+
+  if (type.isStruct) {
+    if (!isPlainObject(value)) {
+      err(errors, path, value, 'must be an object')
+      return
+    }
+    for (const field of type.fields) {
+      const v = value[field.name]
+      const present = v !== undefined && v !== null
+      if (!present) {
+        if (field.required) err(errors, `${path}.${field.name}`, v, 'is required')
+        continue
+      }
+      const fieldPath = `${path}.${field.name}`
+      checkValue(field.type, v, field.array, fieldPath, errors)
+      if (field.description && field.description.enum) {
+        checkMembership(field.description.enum, v, field.array, fieldPath, errors)
+      }
+    }
+    return
+  }
+
+  // external / versioned: cannot validate structurally, treat as opaque
+}
+
+function validate(schema, fqn, value) {
+  if (typeof schema.linkAll === 'function') schema.linkAll()
+
+  const type = schema.resolve(fqn)
+  if (!type) throw new Error(`Unknown type: ${fqn}`)
+
+  const errors = []
+  checkValue(type, value, false, fqn, errors)
+  return { valid: errors.length === 0, errors }
+}
+
+module.exports = { validate, PRIMITIVES }

package/package.json

@@ -1 +1,67 @@
-{"name":"hyperschema-ts","version":"0.0.0"}
+{
+  "name": "hyperschema-ts",
+  "version": "0.1.0",
+  "description": "Generate TypeScript types from a Hyperschema",
+  "exports": {
+    "./package": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.mjs",
+      "default": "./index.cjs"
+    },
+    "./validation": {
+      "types": "./validation.d.ts",
+      "import": "./validation.mjs",
+      "default": "./validation.cjs"
+    }
+  },
+  "imports": {
+    "fs": {
+      "bare": "bare-fs",
+      "default": "fs"
+    },
+    "path": {
+      "bare": "bare-path",
+      "default": "path"
+    }
+  },
+  "files": [
+    "package.json",
+    "index.mjs",
+    "index.cjs",
+    "index.d.ts",
+    "validation.mjs",
+    "validation.cjs",
+    "validation.d.ts",
+    "lib"
+  ],
+  "devDependencies": {
+    "brittle": "^4.0.2",
+    "hyperschema": "^1.21.0",
+    "lunte": "^1.2.0",
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "peerDependencies": {
+    "hyperschema": "^1.21.0"
+  },
+  "scripts": {
+    "format": "prettier . --write",
+    "test": "brittle-bare test/index.js && brittle-node test/index.js",
+    "lint": "prettier . --check && lunte"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/holepunchto/hyperschema-ts.git"
+  },
+  "author": "Holepunch Inc",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/holepunchto/hyperschema-ts/issues"
+  },
+  "homepage": "https://github.com/holepunchto/hyperschema-ts",
+  "dependencies": {
+    "bare-fs": "^4.7.2",
+    "bare-path": "^3.0.1"
+  }
+}

package/validation.cjs

@@ -0,0 +1,38 @@
+const { validate } = require('./lib/validate.js')
+
+class HyperschemaValidation {
+  // Validate `value` against the type `fqn` registered on a Hyperschema instance.
+  // Returns { valid: boolean, errors: Array<{ path, value, message }> }.
+  static validate(schema, fqn, value) {
+    return validate(schema, fqn, value)
+  }
+
+  // Boolean type guard: narrows `value` to the matching type when used through
+  // a typed validator (see createValidator).
+  static is(schema, fqn, value) {
+    return validate(schema, fqn, value).valid
+  }
+
+  // Validate and throw an aggregated error if `value` is invalid.
+  static assert(schema, fqn, value) {
+    const { valid, errors } = validate(schema, fqn, value)
+    if (!valid) {
+      const summary = errors.map((e) => `  ${e.path}: ${e.message}`).join('\n')
+      throw new Error(`Invalid ${fqn}:\n${summary}`)
+    }
+  }
+
+  // Bind a schema and return a validator whose `fqn` argument is constrained to
+  // the generated `SchemaTypes` keys, and whose `is`/`assert` narrow to the
+  // matching generated type. Pass the generated `SchemaTypes` as the type param:
+  //   const v = HyperschemaValidation.createValidator<SchemaTypes>(schema)
+  static createValidator(schema) {
+    return {
+      validate: (fqn, value) => validate(schema, fqn, value),
+      is: (fqn, value) => validate(schema, fqn, value).valid,
+      assert: (fqn, value) => HyperschemaValidation.assert(schema, fqn, value)
+    }
+  }
+}
+
+module.exports = HyperschemaValidation

package/validation.d.ts

@@ -0,0 +1,56 @@
+export interface ValidationError {
+  /** Dotted path to the offending value, e.g. `@example/request.host`. */
+  path: string
+  /** The value that failed validation. */
+  value: unknown
+  /** Human-readable reason. */
+  message: string
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: ValidationError[]
+}
+
+/**
+ * A schema-bound validator whose `fqn` is constrained to the generated
+ * `SchemaTypes` keys, and whose `is`/`assert` narrow `value` to the matching
+ * generated type. `M` is the generated `SchemaTypes` interface.
+ */
+export interface TypedValidator<M> {
+  /** Rich result; `fqn` is constrained to known types but `value` is not narrowed. */
+  validate<K extends keyof M>(fqn: K, value: unknown): ValidationResult
+  /** Boolean type guard that narrows `value` to `M[K]`. */
+  is<K extends keyof M>(fqn: K, value: unknown): value is M[K]
+  /** Assertion that narrows `value` to `M[K]` or throws. */
+  assert<K extends keyof M>(fqn: K, value: unknown): asserts value is M[K]
+}
+
+/**
+ * Validates plain objects against a Hyperschema type before they are passed to
+ * compact-encoding. Rejects everything compact-encoding would throw on or
+ * silently corrupt (out-of-range numbers, malformed IPs, wrong buffer sizes, …).
+ */
+export default class HyperschemaValidation {
+  /** Validate `value` against the type `fqn` registered on `schema`. */
+  static validate(schema: any, fqn: string, value: unknown): ValidationResult
+
+  /** Boolean check that `value` is a valid `fqn`. */
+  static is(schema: any, fqn: string, value: unknown): boolean
+
+  /** Validate and throw an aggregated error if `value` is invalid. */
+  static assert(schema: any, fqn: string, value: unknown): void
+
+  /**
+   * Bind a schema and return a validator typed against the generated `SchemaTypes`.
+   *
+   * ```ts
+   * import HyperschemaValidation from 'hyperschema-ts/validation'
+   * import type { SchemaTypes } from './schema/types'
+   *
+   * const v = HyperschemaValidation.createValidator<SchemaTypes>(schema)
+   * if (v.is('@example/request', value)) value.id // value: ExampleRequest
+   * ```
+   */
+  static createValidator<M = Record<string, unknown>>(schema: any): TypedValidator<M>
+}

package/validation.mjs

@@ -0,0 +1,2 @@
+import HyperschemaValidation from './validation.cjs'
+export default HyperschemaValidation