hono-serialization 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.0.1
+
+Initial release.
+
+- Opt-in JSON serialization for [Hono](https://hono.dev) RPC with bring-your-own codecs: SuperJSON, devalue, Seroval, CBOR, or any `serialize`/`parse` pair.
+- Header-based negotiation (`x-hono-serialization`) with ordinary JSON for unnegotiated requests.
+- Explicit codec contracts: `types` defaults to `preserve`; declare `'json-parsed'` for ordinary JSON conversion or `'unknown'` to make no promise. Optional request-body decoding via `json.input`.
+- Strict RPC types: `s.json` marks negotiated endpoints, `createClient` maps them by codec contract, and mismatched serializers are rejected at compile time.
+- ESM-only package with `/codec` (shared definitions, no Hono runtime) and `/client` entry points.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Broman
+
+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

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# hono-serialization
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Opt-in serialization for [Hono](https://hono.dev) RPC. Bring your own SuperJSON, devalue, Seroval, or binary codec. No serializer is bundled.
+
+A client sends `x-hono-serialization: <name>`. The middleware encodes `s.json` responses and optionally decodes JSON request bodies. Requests without that header, or with an unknown name, receive ordinary Hono output.
+
+## Install
+
+```sh
+npm install hono-serialization hono
+```
+
+Peer dependency: Hono `^4.13.13`. The package is ESM-only.
+
+## Quick start
+
+Define the shared codec in `codecs/superjson.ts`:
+
+```ts
+import SuperJSON from 'superjson'
+import { defineSerializer } from 'hono-serialization/codec'
+
+export const superjson = defineSerializer({
+  name: 'superjson',
+  json: {
+    serialize: SuperJSON.stringify,
+    parse: SuperJSON.parse,
+    input: {
+      serialize: SuperJSON.stringify,
+      parse: SuperJSON.parse,
+    },
+  },
+})
+```
+
+Create the middleware in `server.ts`:
+
+```ts
+import { Hono } from 'hono'
+import { serialization } from 'hono-serialization'
+import { superjson } from './codecs/superjson'
+
+const s = serialization(superjson)
+export const app = new Hono()
+  .use('/api/*', s)
+  .get('/api/item', (c) => s.json(c, { createdAt: new Date() }))
+
+export type AppType = typeof app
+```
+
+Create the browser client in `client.ts`:
+
+```ts
+import { createClient } from 'hono-serialization/client'
+import { superjson } from './codecs/superjson'
+import type { AppType } from './server'
+
+const client = createClient<AppType>('http://localhost', superjson)
+const data = await (await client.api.item.$get()).json()
+data.createdAt // Date
+```
+
+The browser imports the codec and RPC client. The `AppType` import is erased, so it does not load `server.ts` or its middleware.
+
+`defineSerializer` is optional: `serialization({ name, json })` accepts and validates a configuration directly. A separate definition is convenient when the server and client share the codec.
+
+Put `defineSerializer` imports in shared codec files using `hono-serialization/codec`, which has no Hono runtime or middleware dependency. Create `s = serialization(codec)` only on the server. Import `AppType` with `import type` on the client. Import the client from `hono-serialization/client` and only the codec a page needs.
+
+## Codec contracts and RPC types
+
+Declare how your JSON codec changes values with `types`:
+
+- `json.types: 'preserve'` (default): the codec promises to preserve the values and types supplied to `s.json`, such as Date, Map, and Set. The client exposes the original output type.
+- `json.types: 'json-parsed'`: the codec promises ordinary JSON conversion, as if the values passed through `JSON.parse(JSON.stringify(...))`. The client exposes Hono's `JSONParsed<T>` type: Dates become strings.
+- `json.types: 'unknown'`: no promise. Decoded output is `unknown`; validate it before accessing properties.
+
+Omit `types` for lossless codecs. These are explicit codec contracts, not capabilities that TypeScript can prove about arbitrary functions. Choose `preserve` only for values supported by your codec; unsupported values must be rejected by the codec rather than silently converted. Declaring a false contract or using an unchecked cast can invalidate any TypeScript API's guarantees.
+
+`s.json` carries an opaque output type in the app schema. `createClient` maps it according to the codec contract and checks that the codec belongs to the app's typed endpoints. Direct `hc<typeof app>` cannot access negotiated output as if it were plain JSON.
+
+For ordinary JSON clients, use:
+
+```ts
+import { hc } from 'hono/client'
+import type { JsonApp } from 'hono-serialization'
+
+const plain = hc<JsonApp<AppType>>('http://localhost')
+const data = await (await plain.api.item.$get()).json()
+data.createdAt // string
+```
+
+Serializer clients reject JSON responses that omit negotiation headers or advertise a different types contract. Missing middleware, unavailable codecs, and CORS configuration errors fail explicitly instead of returning a value with the wrong static type. Mount the middleware on all JSON routes used by a serializer client, including JSON error handlers, and serve those routes with `s.json`.
+
+`c.json`, `c.text`, `c.html`, and the rest of the context keep Hono's ordinary behavior. The middleware does not patch them. Routes served with `c.json` always return ordinary JSON: stock `hc` and `hc<JsonApp<typeof app>>` read them, while a serializer client fails closed on them. Use `s.json` for routes that participate in serialization.
+
+`s.json` defaults to status **200**, even after `c.status(...)`. Pass another status explicitly; numeric and `{ status: ... }` arguments preserve the literal RPC status. `s.json` rejects contentless statuses (204, 304) at compile time.
+
+## Request bodies
+
+Bodies remain ordinary JSON unless `json.input` is provided. An input codec has its own `types`, which also defaults to `'preserve'`. The client retains rich JSON argument types only for a preserving input codec; otherwise request types undergo JSON conversion.
+
+Mount serialization **before** JSON validators. Validate the decoded values, using schemas appropriate for the input codec. Query parameters, forms, and WebSockets keep Hono's behavior.
+
+Input and response codecs can differ. For Seroval, use its safe JSON mode on requests:
+
+```ts
+import { serialize, deserialize, toJSON, fromJSON } from 'seroval'
+
+const seroval = defineSerializer({
+  name: 'seroval',
+  json: {
+    types: 'preserve',
+    serialize,
+    parse: deserialize,
+    contentType: 'application/seroval',
+    input: {
+      types: 'preserve',
+      serialize: (value: unknown) => JSON.stringify(toJSON(value)),
+      parse: (wire: string) => fromJSON(JSON.parse(wire)),
+    },
+  },
+})
+```
+
+Never evaluate request bodies with `eval`, Seroval's `deserialize`, or a devalue `uneval` decoder. A request header is not authentication, and anyone can construct an HTTP request independently of your client.
+
+## Wire formats
+
+The codec serializes to a string or to bytes and parses the same shape back. A text codec returns a string, and `parse` receives a string. A binary codec must explicitly set `binary: true`, return `Uint8Array` or `ArrayBuffer`, and accept `Uint8Array` in `parse`. MIME types do not imply binary behavior.
+
+```ts
+import { encode, decode } from 'cbor-x'
+
+const cbor = defineSerializer({
+  name: 'cbor',
+  json: {
+    binary: true,
+    contentType: 'application/cbor',
+    serialize: encode,
+    parse: decode,
+  },
+})
+```
+
+Binary codecs such as CBOR work through the same JSON slot: negotiation, request decoding, and client types behave identically; only the wire representation differs.
+
+Set `contentType` to the MIME type of the wire representation. JSON-shaped strings default to `application/json`; binary codecs default to `application/octet-stream`. JavaScript-shaped output should use a private MIME type such as `application/seroval`, rather than `application/javascript`. Invalid codec output throws instead of being coerced into an empty body.
+
+The response advertises the codec name and its types contract. Decoding uses those declarations rather than guessing from Content-Type. Response clones and per-call fetch implementations retain decoding. `json`, `text`, `arrayBuffer`, and `bytes` share a cached body; `text()` on an encoded JSON response returns its raw wire text.
+
+## Several codecs and custom headers
+
+```ts
+const s = serialization([superjson, seroval])
+app.use('/api/*', s)
+
+const jsonClient = createClient<AppType>(url, superjson)
+const serovalClient = createClient<AppType>(url, seroval)
+```
+
+A helper belongs to its middleware instance. Mixing helpers from different instances throws rather than using an unrelated codec.
+
+Configure a custom header on both ends:
+
+```ts
+const s = serialization(superjson, { header: 'x-my-serde' })
+const client = createClient<AppType>(url, superjson, { header: 'x-my-serde' })
+```
+
+For CORS, allow the negotiation request header in preflight. Encoded responses expose the negotiation header and its `-types` companion. The middleware adds the configured header to `Vary` on encoded and ordinary responses while preserving existing entries.
+
+`createClient` accepts Hono client options, including async headers and per-call fetch overrides. It always sets the negotiation header on the outgoing request. `$url`, `$path`, and `$ws` retain their Hono behavior. For private MIME types, use the wrapped `res.json()`; Hono's `parseResponse()` selects a parser by Content-Type.
+
+## Development
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run build
+npm run check:package
+npm run check:release
+```
+
+Typechecking includes positive and negative RPC assertions and dependency declarations. Publishing runs the full release check, including typechecking, tests, ESM builds, package-boundary checks, and installed tarball tests over real HTTP.
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes.

package/dist/chunk-7N7SGVDF.js

@@ -0,0 +1,14 @@
+import {
+  validateSerializer
+} from "./chunk-E2KZJRGU.js";
+
+// src/codec.ts
+function defineSerializer(serializer) {
+  validateSerializer(serializer);
+  return serializer;
+}
+
+export {
+  defineSerializer
+};
+//# sourceMappingURL=chunk-7N7SGVDF.js.map

package/dist/chunk-7N7SGVDF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/codec.ts"],"sourcesContent":["/** Shared codec definitions: no Hono runtime or server middleware. */\nimport type { Serializer } from './types'\nimport { validateSerializer } from './validation'\n\nexport function defineSerializer<const T extends Serializer>(\n  serializer: T & Record<Exclude<keyof T, keyof Serializer>, never>,\n): T {\n  validateSerializer(serializer)\n  return serializer\n}\n\nexport type {\n  Serializer,\n  JsonSerializer,\n  WireSerializer,\n  WireBody,\n  CodecTypes,\n} from './types'\n"],"mappings":";;;;;AAIO,SAAS,iBACd,YACG;AACH,qBAAmB,UAAU;AAC7B,SAAO;AACT;","names":[]}

package/dist/chunk-E2KZJRGU.js

@@ -0,0 +1,37 @@
+// src/validation.ts
+function validateSerializer(s) {
+  if (typeof s.name !== "string" || !s.name || s.name.trim() !== s.name || /[^\x21-\x7e]/.test(s.name)) {
+    throw new TypeError(
+      "defineSerializer: name must be a non-empty printable header value without surrounding whitespace"
+    );
+  }
+  if (!s.json) {
+    throw new TypeError("defineSerializer: json codec is required");
+  }
+  for (const key of Object.keys(s)) {
+    if (key !== "name" && key !== "json") {
+      throw new TypeError(`defineSerializer: unsupported field "${key}"`);
+    }
+  }
+  for (const codec of [s.json, s.json.input]) {
+    if (!codec) continue;
+    if (typeof codec.serialize !== "function" || typeof codec.parse !== "function") {
+      throw new TypeError("codecs require serialize and parse functions");
+    }
+    if (codec.binary !== void 0 && typeof codec.binary !== "boolean")
+      throw new TypeError("binary must be boolean");
+    if (codec.contentType !== void 0)
+      new Headers({ "content-type": codec.contentType });
+  }
+  if (s.json.input && !["preserve", "json-parsed"].includes(s.json.input.types ?? "preserve")) {
+    throw new TypeError("json.input.types must be preserve or json-parsed");
+  }
+  if (s.json.types !== void 0 && !["preserve", "json-parsed", "unknown"].includes(s.json.types)) {
+    throw new TypeError("json.types must be preserve, json-parsed, or unknown");
+  }
+}
+
+export {
+  validateSerializer
+};
+//# sourceMappingURL=chunk-E2KZJRGU.js.map

package/dist/chunk-E2KZJRGU.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/validation.ts"],"sourcesContent":["import type { Serializer } from './types'\n\nexport function validateSerializer(s: Serializer): void {\n  if (\n    typeof s.name !== 'string' ||\n    !s.name ||\n    s.name.trim() !== s.name ||\n    /[^\\x21-\\x7e]/.test(s.name)\n  ) {\n    throw new TypeError(\n      'defineSerializer: name must be a non-empty printable header value without surrounding whitespace',\n    )\n  }\n  if (!s.json) {\n    throw new TypeError('defineSerializer: json codec is required')\n  }\n  for (const key of Object.keys(s)) {\n    if (key !== 'name' && key !== 'json') {\n      throw new TypeError(`defineSerializer: unsupported field \"${key}\"`)\n    }\n  }\n  for (const codec of [s.json, s.json.input]) {\n    if (!codec) continue\n    if (\n      typeof codec.serialize !== 'function' ||\n      typeof codec.parse !== 'function'\n    ) {\n      throw new TypeError('codecs require serialize and parse functions')\n    }\n    if (codec.binary !== undefined && typeof codec.binary !== 'boolean')\n      throw new TypeError('binary must be boolean')\n    if (codec.contentType !== undefined)\n      new Headers({ 'content-type': codec.contentType })\n  }\n  if (\n    s.json.input &&\n    !['preserve', 'json-parsed'].includes(s.json.input.types ?? 'preserve')\n  ) {\n    throw new TypeError('json.input.types must be preserve or json-parsed')\n  }\n  if (\n    s.json.types !== undefined &&\n    !['preserve', 'json-parsed', 'unknown'].includes(s.json.types)\n  ) {\n    throw new TypeError('json.types must be preserve, json-parsed, or unknown')\n  }\n}\n"],"mappings":";AAEO,SAAS,mBAAmB,GAAqB;AACtD,MACE,OAAO,EAAE,SAAS,YAClB,CAAC,EAAE,QACH,EAAE,KAAK,KAAK,MAAM,EAAE,QACpB,eAAe,KAAK,EAAE,IAAI,GAC1B;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,MAAI,CAAC,EAAE,MAAM;AACX,UAAM,IAAI,UAAU,0CAA0C;AAAA,EAChE;AACA,aAAW,OAAO,OAAO,KAAK,CAAC,GAAG;AAChC,QAAI,QAAQ,UAAU,QAAQ,QAAQ;AACpC,YAAM,IAAI,UAAU,wCAAwC,GAAG,GAAG;AAAA,IACpE;AAAA,EACF;AACA,aAAW,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,KAAK,GAAG;AAC1C,QAAI,CAAC,MAAO;AACZ,QACE,OAAO,MAAM,cAAc,cAC3B,OAAO,MAAM,UAAU,YACvB;AACA,YAAM,IAAI,UAAU,8CAA8C;AAAA,IACpE;AACA,QAAI,MAAM,WAAW,UAAa,OAAO,MAAM,WAAW;AACxD,YAAM,IAAI,UAAU,wBAAwB;AAC9C,QAAI,MAAM,gBAAgB;AACxB,UAAI,QAAQ,EAAE,gBAAgB,MAAM,YAAY,CAAC;AAAA,EACrD;AACA,MACE,EAAE,KAAK,SACP,CAAC,CAAC,YAAY,aAAa,EAAE,SAAS,EAAE,KAAK,MAAM,SAAS,UAAU,GACtE;AACA,UAAM,IAAI,UAAU,kDAAkD;AAAA,EACxE;AACA,MACE,EAAE,KAAK,UAAU,UACjB,CAAC,CAAC,YAAY,eAAe,SAAS,EAAE,SAAS,EAAE,KAAK,KAAK,GAC7D;AACA,UAAM,IAAI,UAAU,sDAAsD;AAAA,EAC5E;AACF;","names":[]}

package/dist/chunk-HINZPU3T.js

@@ -0,0 +1,55 @@
+// src/wire.ts
+var DEFAULT_HEADER = "x-hono-serialization";
+var DEFAULT_JSON_CONTENT_TYPE = "application/json; charset=UTF-8";
+var BINARY_CONTENT_TYPE = "application/octet-stream";
+var typesHeader = (header) => `${header}-types`;
+var resolve = (codec) => ({
+  serialize: codec.serialize,
+  parse: codec.parse,
+  binary: codec.binary === true,
+  contentType: codec.contentType ?? (codec.binary ? BINARY_CONTENT_TYPE : DEFAULT_JSON_CONTENT_TYPE)
+});
+var resolveInput = (codec) => codec.input == null ? void 0 : resolve(codec.input);
+function encode(codec, value) {
+  const body = codec.serialize(value);
+  if (codec.binary) {
+    if (!(body instanceof Uint8Array) && !(body instanceof ArrayBuffer)) {
+      throw new TypeError(
+        "binary codec serialize() must return Uint8Array or ArrayBuffer"
+      );
+    }
+  } else if (typeof body !== "string") {
+    throw new TypeError(
+      "codec serialize() must return a string; use binary: true for bytes"
+    );
+  }
+  return body;
+}
+function validateHeader(header) {
+  new Headers({
+    [header]: "test",
+    [typesHeader(header)]: "preserve"
+  });
+  if ([
+    "content-type",
+    "content-length",
+    "vary",
+    "access-control-expose-headers"
+  ].includes(header.toLowerCase())) {
+    throw new TypeError(
+      "serialization header conflicts with an HTTP protocol header"
+    );
+  }
+}
+
+export {
+  DEFAULT_HEADER,
+  DEFAULT_JSON_CONTENT_TYPE,
+  BINARY_CONTENT_TYPE,
+  typesHeader,
+  resolve,
+  resolveInput,
+  encode,
+  validateHeader
+};
+//# sourceMappingURL=chunk-HINZPU3T.js.map

package/dist/chunk-HINZPU3T.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/wire.ts"],"sourcesContent":["import type { JsonSerializer, WireBody, WireSerializer } from './types'\n\nexport const DEFAULT_HEADER = 'x-hono-serialization'\nexport const DEFAULT_JSON_CONTENT_TYPE = 'application/json; charset=UTF-8'\nexport const BINARY_CONTENT_TYPE = 'application/octet-stream'\nexport const typesHeader = (header: string) => `${header}-types`\nexport type Resolved = {\n  serialize: (value: never) => WireBody\n  parse: (data: never) => unknown\n  binary: boolean\n  contentType: string | undefined\n}\nexport const resolve = (codec: WireSerializer<never>): Resolved => ({\n  serialize: codec.serialize,\n  parse: codec.parse,\n  binary: codec.binary === true,\n  contentType:\n    codec.contentType ??\n    (codec.binary ? BINARY_CONTENT_TYPE : DEFAULT_JSON_CONTENT_TYPE),\n})\nexport const resolveInput = (codec: JsonSerializer): Resolved | undefined =>\n  codec.input == null ? undefined : resolve(codec.input)\n\nexport function encode(codec: Resolved, value: unknown): WireBody {\n  const body: unknown = codec.serialize(value as never)\n  if (codec.binary) {\n    if (!(body instanceof Uint8Array) && !(body instanceof ArrayBuffer)) {\n      throw new TypeError(\n        'binary codec serialize() must return Uint8Array or ArrayBuffer',\n      )\n    }\n  } else if (typeof body !== 'string') {\n    throw new TypeError(\n      'codec serialize() must return a string; use binary: true for bytes',\n    )\n  }\n  return body as WireBody\n}\n\nexport function validateHeader(header: string): void {\n  new Headers({\n    [header]: 'test',\n    [typesHeader(header)]: 'preserve',\n  })\n  if (\n    [\n      'content-type',\n      'content-length',\n      'vary',\n      'access-control-expose-headers',\n    ].includes(header.toLowerCase())\n  ) {\n    throw new TypeError(\n      'serialization header conflicts with an HTTP protocol header',\n    )\n  }\n}\n"],"mappings":";AAEO,IAAM,iBAAiB;AACvB,IAAM,4BAA4B;AAClC,IAAM,sBAAsB;AAC5B,IAAM,cAAc,CAAC,WAAmB,GAAG,MAAM;AAOjD,IAAM,UAAU,CAAC,WAA4C;AAAA,EAClE,WAAW,MAAM;AAAA,EACjB,OAAO,MAAM;AAAA,EACb,QAAQ,MAAM,WAAW;AAAA,EACzB,aACE,MAAM,gBACL,MAAM,SAAS,sBAAsB;AAC1C;AACO,IAAM,eAAe,CAAC,UAC3B,MAAM,SAAS,OAAO,SAAY,QAAQ,MAAM,KAAK;AAEhD,SAAS,OAAO,OAAiB,OAA0B;AAChE,QAAM,OAAgB,MAAM,UAAU,KAAc;AACpD,MAAI,MAAM,QAAQ;AAChB,QAAI,EAAE,gBAAgB,eAAe,EAAE,gBAAgB,cAAc;AACnE,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF,WAAW,OAAO,SAAS,UAAU;AACnC,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAEO,SAAS,eAAe,QAAsB;AACnD,MAAI,QAAQ;AAAA,IACV,CAAC,MAAM,GAAG;AAAA,IACV,CAAC,YAAY,MAAM,CAAC,GAAG;AAAA,EACzB,CAAC;AACD,MACE;AAAA,IACE;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,EAAE,SAAS,OAAO,YAAY,CAAC,GAC/B;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { Hono } from 'hono';
+import { ClientRequestOptions, hc } from 'hono/client';
+import { C as CodecTypes, a as ClientApp, S as Serializer, W as WireSerializer, A as AppSerializer } from './types-Ce9-Amxx.js';
+import 'hono/utils/types';
+
+type CreateClientOptions = ClientRequestOptions & {
+    header?: string;
+};
+type Preserving = Serializer & {
+    json: {
+        types?: 'preserve';
+    };
+};
+type Converting = Serializer & {
+    json: {
+        types: 'json-parsed';
+    };
+};
+type Unknown = Serializer & {
+    json: {
+        types: 'unknown';
+    };
+};
+type WithInput = Serializer & {
+    json: {
+        input: WireSerializer & {
+            types?: 'preserve';
+        };
+    };
+};
+type HonoClient<T extends Hono, Prefix extends string> = ReturnType<typeof hc<T, Prefix>>;
+type SerializerClient<T extends Hono, Types extends CodecTypes, Prefix extends string = string, RichInput extends boolean = false> = HonoClient<ClientApp<T, Types, RichInput>, Prefix>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Preserving & WithInput & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'preserve', Prefix, true>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Preserving & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'preserve', Prefix>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Converting & WithInput & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'json-parsed', Prefix, true>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Converting & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'json-parsed', Prefix>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Unknown & WithInput & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'unknown', Prefix, true>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Unknown & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'unknown', Prefix>;
+declare function createClient<T extends Hono, Prefix extends string = string>(baseUrl: Prefix, serializer: Serializer & AppSerializer<T>, options?: CreateClientOptions): SerializerClient<T, 'unknown', Prefix>;
+
+export { type CreateClientOptions, Serializer, type SerializerClient, createClient };

package/dist/client.js

@@ -0,0 +1,113 @@
+import {
+  DEFAULT_HEADER,
+  encode,
+  resolve,
+  resolveInput,
+  typesHeader,
+  validateHeader
+} from "./chunk-HINZPU3T.js";
+import {
+  validateSerializer
+} from "./chunk-E2KZJRGU.js";
+
+// src/client.ts
+import { hc } from "hono/client";
+var wrapResponse = (res, serializer, header) => {
+  let buf;
+  const getBuf = () => buf ??= res.arrayBuffer();
+  const getText = async () => new TextDecoder().decode(await getBuf());
+  return new Proxy(res, {
+    get(target, prop) {
+      if (prop === "clone")
+        return () => wrapResponse(target.clone(), serializer, header);
+      if (prop === "arrayBuffer") return getBuf;
+      if (prop === "bytes") return async () => new Uint8Array(await getBuf());
+      if (prop === "json")
+        return async () => {
+          if (res.headers.get(header) !== serializer.name) {
+            throw new TypeError(
+              "JSON response did not negotiate the requested serializer; use s.json on the server and check middleware/CORS"
+            );
+          }
+          if (res.headers.get(typesHeader(header)) !== (serializer.json.types ?? "preserve")) {
+            throw new TypeError("server and client codec types differ");
+          }
+          const slot = resolve(serializer.json);
+          const data = slot.binary ? new Uint8Array(await getBuf()) : await getText();
+          return slot.parse(data);
+        };
+      if (prop === "text") return getText;
+      const value = Reflect.get(target, prop, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+};
+function createClient(baseUrl, serializer, options) {
+  validateSerializer(serializer);
+  const { header: headerName, ...rest } = options ?? {};
+  const header = headerName ?? DEFAULT_HEADER;
+  validateHeader(header);
+  const inputSlot = resolveInput(serializer.json);
+  const wrapFetch = (fetcher) => {
+    const wrapped = async (input, init) => {
+      const headers = new Headers(init?.headers);
+      headers.set(header, serializer.name);
+      return wrapResponse(
+        await fetcher(input, { ...init, headers }),
+        serializer,
+        header
+      );
+    };
+    return wrapped;
+  };
+  const raw = hc(baseUrl, {
+    ...rest,
+    fetch: wrapFetch(rest.fetch ?? globalThis.fetch)
+  });
+  const wrapClient = (client) => new Proxy(client, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof prop === "symbol" || prop === "then" || prop === "$url" || prop === "$path" || prop === "$ws")
+        return value;
+      return value !== null && (typeof value === "function" || typeof value === "object") ? wrapClient(value) : value;
+    },
+    apply(target, _thisArg, argArray) {
+      const args = argArray[0];
+      const opts = argArray[1] ?? {};
+      const callOptions = { ...opts };
+      if (opts.fetch) callOptions.fetch = wrapFetch(opts.fetch);
+      let callArgs = args;
+      if (inputSlot && args?.json !== void 0) {
+        const { json, ...otherArgs } = args;
+        callArgs = otherArgs;
+        const body = encode(inputSlot, json);
+        const requestHeaders = opts.headers;
+        callOptions.headers = async () => ({
+          ...typeof requestHeaders === "function" ? await requestHeaders() : requestHeaders,
+          "Content-Type": inputSlot.contentType ?? "application/json"
+        });
+        callOptions.init = { ...opts.init, body };
+        if (opts.init?.headers || rest.init?.headers) {
+          const headers = new Headers(
+            opts.init?.headers ?? rest.init?.headers
+          );
+          headers.set(
+            "Content-Type",
+            inputSlot.contentType ?? "application/json"
+          );
+          callOptions.init.headers = headers;
+        }
+      }
+      return Reflect.apply(
+        target,
+        void 0,
+        [callArgs, callOptions]
+      );
+    }
+  });
+  return wrapClient(raw);
+}
+export {
+  createClient
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import type { Hono } from 'hono'\nimport { hc } from 'hono/client'\nimport type { ClientRequestOptions } from 'hono/client'\nimport {\n  DEFAULT_HEADER,\n  encode,\n  typesHeader,\n  resolve,\n  resolveInput,\n  validateHeader,\n} from './wire'\nimport { validateSerializer } from './validation'\nimport type {\n  AppSerializer,\n  ClientApp,\n  CodecTypes,\n  Serializer,\n  WireSerializer,\n} from './types'\nexport type { Serializer } from './types'\n\ntype AnyClient = object\nconst wrapResponse = (\n  res: Response,\n  serializer: Serializer,\n  header: string,\n): Response => {\n  let buf: Promise<ArrayBuffer> | undefined\n  const getBuf = () => (buf ??= res.arrayBuffer())\n  const getText = async () => new TextDecoder().decode(await getBuf())\n  return new Proxy(res, {\n    get(target, prop) {\n      if (prop === 'clone')\n        return () => wrapResponse(target.clone(), serializer, header)\n      if (prop === 'arrayBuffer') return getBuf\n      if (prop === 'bytes') return async () => new Uint8Array(await getBuf())\n      if (prop === 'json')\n        return async () => {\n          if (res.headers.get(header) !== serializer.name) {\n            throw new TypeError(\n              'JSON response did not negotiate the requested serializer; use s.json on the server and check middleware/CORS',\n            )\n          }\n          if (\n            res.headers.get(typesHeader(header)) !==\n            (serializer.json.types ?? 'preserve')\n          ) {\n            throw new TypeError('server and client codec types differ')\n          }\n          const slot = resolve(serializer.json)\n          const data = slot.binary\n            ? new Uint8Array(await getBuf())\n            : await getText()\n          return slot.parse(data as never)\n        }\n      if (prop === 'text') return getText\n      const value: unknown = Reflect.get(target, prop, target)\n      return typeof value === 'function' ? value.bind(target) : value\n    },\n  })\n}\n\nexport type CreateClientOptions = ClientRequestOptions & { header?: string }\ntype Preserving = Serializer & { json: { types?: 'preserve' } }\ntype Converting = Serializer & { json: { types: 'json-parsed' } }\ntype Unknown = Serializer & { json: { types: 'unknown' } }\ntype WithInput = Serializer & {\n  json: { input: WireSerializer & { types?: 'preserve' } }\n}\ntype HonoClient<T extends Hono, Prefix extends string> = ReturnType<\n  typeof hc<T, Prefix>\n>\nexport type SerializerClient<\n  T extends Hono,\n  Types extends CodecTypes,\n  Prefix extends string = string,\n  RichInput extends boolean = false,\n> = HonoClient<ClientApp<T, Types, RichInput>, Prefix>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Preserving & WithInput & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'preserve', Prefix, true>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Preserving & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'preserve', Prefix>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Converting & WithInput & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'json-parsed', Prefix, true>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Converting & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'json-parsed', Prefix>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Unknown & WithInput & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'unknown', Prefix, true>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Unknown & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'unknown', Prefix>\nexport function createClient<T extends Hono, Prefix extends string = string>(\n  baseUrl: Prefix,\n  serializer: Serializer & AppSerializer<T>,\n  options?: CreateClientOptions,\n): SerializerClient<T, 'unknown', Prefix>\nexport function createClient(\n  baseUrl: string,\n  serializer: Serializer,\n  options?: CreateClientOptions,\n): object {\n  validateSerializer(serializer)\n  const { header: headerName, ...rest } = options ?? {}\n  const header = headerName ?? DEFAULT_HEADER\n  validateHeader(header)\n  const inputSlot = resolveInput(serializer.json)\n  const wrapFetch = (fetcher: NonNullable<ClientRequestOptions['fetch']>) => {\n    const wrapped = async (\n      input: RequestInfo | URL,\n      init?: RequestInit,\n    ): Promise<Response> => {\n      const headers = new Headers(init?.headers)\n      headers.set(header, serializer.name)\n      return wrapResponse(\n        await fetcher(input as never, { ...init, headers }),\n        serializer,\n        header,\n      )\n    }\n    return wrapped as NonNullable<ClientRequestOptions['fetch']>\n  }\n  const raw = hc(baseUrl, {\n    ...rest,\n    fetch: wrapFetch(rest.fetch ?? globalThis.fetch),\n  })\n  const wrapClient = (client: AnyClient): AnyClient =>\n    new Proxy(client, {\n      get(target, prop, receiver) {\n        const value: unknown = Reflect.get(target, prop, receiver)\n        if (\n          typeof prop === 'symbol' ||\n          prop === 'then' ||\n          prop === '$url' ||\n          prop === '$path' ||\n          prop === '$ws'\n        )\n          return value\n        return value !== null &&\n          (typeof value === 'function' || typeof value === 'object')\n          ? wrapClient(value)\n          : value\n      },\n      apply(target, _thisArg, argArray: unknown[]) {\n        const args = argArray[0] as { json?: unknown } | undefined\n        const opts = (argArray[1] ?? {}) as ClientRequestOptions\n        const callOptions: ClientRequestOptions = { ...opts }\n        if (opts.fetch) callOptions.fetch = wrapFetch(opts.fetch)\n        let callArgs = args\n        if (inputSlot && args?.json !== undefined) {\n          const { json, ...otherArgs } = args\n          callArgs = otherArgs\n          const body = encode(inputSlot, json)\n          const requestHeaders = opts.headers\n          callOptions.headers = async () => ({\n            ...(typeof requestHeaders === 'function'\n              ? await requestHeaders()\n              : requestHeaders),\n            'Content-Type': inputSlot.contentType ?? 'application/json',\n          })\n          callOptions.init = { ...opts.init, body: body as BodyInit }\n          // RequestInit headers otherwise override hc's assembled headers.\n          if (opts.init?.headers || rest.init?.headers) {\n            const headers = new Headers(\n              opts.init?.headers ?? rest.init?.headers,\n            )\n            headers.set(\n              'Content-Type',\n              inputSlot.contentType ?? 'application/json',\n            )\n            callOptions.init.headers = headers\n          }\n        }\n        return Reflect.apply(\n          target as (...args: unknown[]) => unknown,\n          undefined,\n          [callArgs, callOptions],\n        )\n      },\n    })\n  return wrapClient(raw)\n}\n"],"mappings":"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","names":[]}

package/dist/codec.d.ts

@@ -0,0 +1,10 @@
+import { S as Serializer } from './types-Ce9-Amxx.js';
+export { C as CodecTypes, e as JsonSerializer, f as WireBody, W as WireSerializer } from './types-Ce9-Amxx.js';
+import 'hono';
+import 'hono/utils/types';
+
+/** Shared codec definitions: no Hono runtime or server middleware. */
+
+declare function defineSerializer<const T extends Serializer>(serializer: T & Record<Exclude<keyof T, keyof Serializer>, never>): T;
+
+export { Serializer, defineSerializer };

package/dist/codec.js

@@ -0,0 +1,8 @@
+import {
+  defineSerializer
+} from "./chunk-7N7SGVDF.js";
+import "./chunk-E2KZJRGU.js";
+export {
+  defineSerializer
+};
+//# sourceMappingURL=codec.js.map

package/dist/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { Context, TypedResponse, MiddlewareHandler } from 'hono';
+import { ContentfulStatusCode } from 'hono/utils/http-status';
+import { S as Serializer, b as SerializedOutput, c as SerializerList, d as SerializerOf } from './types-Ce9-Amxx.js';
+export { C as CodecTypes, J as JsonApp, e as JsonSerializer, f as WireBody, W as WireSerializer } from './types-Ce9-Amxx.js';
+export { defineSerializer } from './codec.js';
+import 'hono/utils/types';
+
+declare const DEFAULT_HEADER = "x-hono-serialization";
+declare const DEFAULT_JSON_CONTENT_TYPE = "application/json; charset=UTF-8";
+declare const BINARY_CONTENT_TYPE = "application/octet-stream";
+
+type HeaderRecord = Record<string, string | string[]>;
+type ResponseOptions<U extends ContentfulStatusCode = ContentfulStatusCode> = Omit<ResponseInit, 'status'> & {
+    status?: U;
+};
+
+type SerializationMiddlewareOptions = {
+    header?: string;
+};
+type JsonHelper<S extends Serializer = Serializer> = {
+    <T, U extends ContentfulStatusCode = 200>(c: Context, object: T, status?: U, headers?: HeaderRecord): Response & TypedResponse<SerializedOutput<T, S>, U, 'json'>;
+    <T, U extends ContentfulStatusCode = 200>(c: Context, object: T, init: ResponseOptions<U>): Response & TypedResponse<SerializedOutput<T, S>, U, 'json'>;
+};
+type SerializationMiddleware<S extends Serializer = Serializer> = MiddlewareHandler & {
+    json: JsonHelper<S>;
+};
+declare function serialization<const S extends SerializerList>(serializers: S, options?: SerializationMiddlewareOptions): SerializationMiddleware<SerializerOf<S> & Serializer>;
+
+export { BINARY_CONTENT_TYPE, DEFAULT_HEADER, DEFAULT_JSON_CONTENT_TYPE, type JsonHelper, type ResponseOptions, type SerializationMiddleware, type SerializationMiddlewareOptions, Serializer, serialization };

package/dist/index.js

@@ -0,0 +1,134 @@
+import {
+  BINARY_CONTENT_TYPE,
+  DEFAULT_HEADER,
+  DEFAULT_JSON_CONTENT_TYPE,
+  encode,
+  resolve,
+  resolveInput,
+  typesHeader,
+  validateHeader
+} from "./chunk-HINZPU3T.js";
+import {
+  defineSerializer
+} from "./chunk-7N7SGVDF.js";
+import {
+  validateSerializer
+} from "./chunk-E2KZJRGU.js";
+
+// src/index.ts
+import { createMiddleware } from "hono/factory";
+
+// src/internal.ts
+var CONTEXT_KEY = "hono-serialization";
+var getActive = (c) => c.get(CONTEXT_KEY);
+var setActive = (c, active) => {
+  c.set(CONTEXT_KEY, active);
+};
+function lookup(serializers) {
+  const list = Array.isArray(serializers) ? serializers : [serializers];
+  if (!list.length)
+    throw new TypeError("serialization: at least one serializer is required");
+  const byName = /* @__PURE__ */ new Map();
+  for (const s of list) {
+    validateSerializer(s);
+    if (byName.has(s.name))
+      throw new TypeError(`serialization: duplicate name "${s.name}"`);
+    byName.set(s.name, s);
+  }
+  return byName;
+}
+function appendHeader(headers, key, value) {
+  const parts = (headers.get(key) ?? "").split(",").map((p) => p.trim()).filter(Boolean);
+  if (!parts.some((p) => p.toLowerCase() === value.toLowerCase()) && !(key.toLowerCase() === "vary" && parts.includes("*")))
+    parts.push(value);
+  headers.set(key, parts.join(", "));
+}
+var sendEncoded = (c, value, arg, headers, slot, header, serializer) => {
+  const body = encode(slot, value);
+  const payload = body instanceof Uint8Array ? new Uint8Array(body) : body;
+  const res = typeof arg === "object" ? c.newResponse(payload, arg) : c.newResponse(payload, arg, headers);
+  if (typeof arg === "object" && headers) {
+    for (const [key, value2] of Object.entries(headers)) {
+      res.headers.delete(key);
+      for (const item of typeof value2 === "string" ? [value2] : value2)
+        res.headers.append(key, item);
+    }
+  }
+  if (slot.contentType) res.headers.set("Content-Type", slot.contentType);
+  res.headers.set(header, serializer.name);
+  res.headers.set(typesHeader(header), serializer.json.types ?? "preserve");
+  appendHeader(res.headers, "Access-Control-Expose-Headers", header);
+  appendHeader(
+    res.headers,
+    "Access-Control-Expose-Headers",
+    typesHeader(header)
+  );
+  return res;
+};
+
+// src/index.ts
+function serialization(serializers, options) {
+  const byName = lookup(serializers);
+  const header = options?.header ?? DEFAULT_HEADER;
+  validateHeader(header);
+  const middleware = createMiddleware(async (c, next) => {
+    const name = c.req.header(header)?.trim();
+    const active = name ? byName.get(name) : void 0;
+    if (active) {
+      setActive(c, { serializer: active, header });
+      const input = resolveInput(active.json);
+      if (input) {
+        let parsed;
+        c.req.json = (() => parsed ??= (async () => {
+          const data = input.binary ? new Uint8Array(await c.req.arrayBuffer()) : await c.req.text();
+          return input.parse(data);
+        })());
+      }
+    }
+    await next();
+    const responseHeaders = new Headers(c.res.headers);
+    appendHeader(responseHeaders, "Vary", header);
+    c.header("Vary", responseHeaders.get("Vary"));
+    if (c.res.headers.get(header)) {
+      for (const name2 of [header, typesHeader(header)]) {
+        appendHeader(responseHeaders, "Access-Control-Expose-Headers", name2);
+      }
+      c.header(
+        "Access-Control-Expose-Headers",
+        responseHeaders.get("Access-Control-Expose-Headers")
+      );
+    }
+  });
+  const json = (c, value, arg, headers) => {
+    const active = getActive(c);
+    if (active && (active.header !== header || byName.get(active.serializer.name) !== active.serializer)) {
+      throw new TypeError(
+        "serialization helper used with a different middleware instance"
+      );
+    }
+    const init = typeof arg === "object" ? { ...arg, status: arg.status ?? 200 } : arg ?? 200;
+    if (active) {
+      return sendEncoded(
+        c,
+        value,
+        init,
+        headers,
+        resolve(active.serializer.json),
+        header,
+        active.serializer
+      );
+    }
+    return typeof init === "object" ? c.json(value, init) : c.json(value, init, headers);
+  };
+  return Object.assign(middleware, {
+    json
+  });
+}
+export {
+  BINARY_CONTENT_TYPE,
+  DEFAULT_HEADER,
+  DEFAULT_JSON_CONTENT_TYPE,
+  defineSerializer,
+  serialization
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/internal.ts"],"sourcesContent":["import type { Context, MiddlewareHandler, TypedResponse } from 'hono'\nimport { createMiddleware } from 'hono/factory'\nimport type { ContentfulStatusCode } from 'hono/utils/http-status'\nimport {\n  BINARY_CONTENT_TYPE,\n  DEFAULT_HEADER,\n  DEFAULT_JSON_CONTENT_TYPE,\n  appendHeader,\n  getActive,\n  lookup,\n  typesHeader,\n  resolve,\n  resolveInput,\n  sendEncoded,\n  setActive,\n  validateHeader,\n  type HeaderRecord,\n  type ResponseOptions,\n} from './internal'\nimport type {\n  SerializedOutput,\n  Serializer,\n  SerializerList,\n  SerializerOf,\n} from './types'\n\nexport { BINARY_CONTENT_TYPE, DEFAULT_HEADER, DEFAULT_JSON_CONTENT_TYPE }\nexport type {\n  JsonApp,\n  JsonSerializer,\n  CodecTypes,\n  Serializer,\n  WireBody,\n  WireSerializer,\n} from './types'\nexport type { ResponseOptions } from './internal'\nexport { defineSerializer } from './codec'\n\nexport type SerializationMiddlewareOptions = { header?: string }\nexport type JsonHelper<S extends Serializer = Serializer> = {\n  <T, U extends ContentfulStatusCode = 200>(\n    c: Context,\n    object: T,\n    status?: U,\n    headers?: HeaderRecord,\n  ): Response & TypedResponse<SerializedOutput<T, S>, U, 'json'>\n  <T, U extends ContentfulStatusCode = 200>(\n    c: Context,\n    object: T,\n    init: ResponseOptions<U>,\n  ): Response & TypedResponse<SerializedOutput<T, S>, U, 'json'>\n}\nexport type SerializationMiddleware<S extends Serializer = Serializer> =\n  MiddlewareHandler & { json: JsonHelper<S> }\n\nexport function serialization<const S extends SerializerList>(\n  serializers: S,\n  options?: SerializationMiddlewareOptions,\n): SerializationMiddleware<SerializerOf<S> & Serializer> {\n  const byName = lookup(serializers)\n  const header = options?.header ?? DEFAULT_HEADER\n  validateHeader(header)\n  const middleware = createMiddleware(async (c, next) => {\n    const name = c.req.header(header)?.trim()\n    const active = name ? byName.get(name) : undefined\n    if (active) {\n      setActive(c, { serializer: active, header })\n      const input = resolveInput(active.json)\n      if (input) {\n        let parsed: Promise<unknown> | undefined\n        c.req.json = (() =>\n          (parsed ??= (async () => {\n            const data = input.binary\n              ? new Uint8Array(await c.req.arrayBuffer())\n              : await c.req.text()\n            return input.parse(data as never)\n          })())) as Context['req']['json']\n      }\n    }\n    await next()\n    const responseHeaders = new Headers(c.res.headers)\n    appendHeader(responseHeaders, 'Vary', header)\n    c.header('Vary', responseHeaders.get('Vary')!)\n    if (c.res.headers.get(header)) {\n      for (const name of [header, typesHeader(header)]) {\n        appendHeader(responseHeaders, 'Access-Control-Expose-Headers', name)\n      }\n      c.header(\n        'Access-Control-Expose-Headers',\n        responseHeaders.get('Access-Control-Expose-Headers')!,\n      )\n    }\n  })\n  const json = (\n    c: Context,\n    value: unknown,\n    arg?: ContentfulStatusCode | ResponseOptions,\n    headers?: HeaderRecord,\n  ): Response => {\n    const active = getActive(c)\n    if (\n      active &&\n      (active.header !== header ||\n        byName.get(active.serializer.name) !== active.serializer)\n    ) {\n      throw new TypeError(\n        'serialization helper used with a different middleware instance',\n      )\n    }\n    // A helper's status must agree with its RPC type, even after c.status().\n    const init =\n      typeof arg === 'object'\n        ? { ...arg, status: arg.status ?? 200 }\n        : (arg ?? 200)\n    if (active) {\n      return sendEncoded(\n        c,\n        value,\n        init,\n        headers,\n        resolve(active.serializer.json),\n        header,\n        active.serializer,\n      )\n    }\n    // Unnegotiated requests keep Hono's ordinary JSON response.\n    return typeof init === 'object'\n      ? c.json(value as never, init)\n      : c.json(value as never, init, headers)\n  }\n  return Object.assign(middleware, {\n    json: json as JsonHelper<SerializerOf<S> & Serializer>,\n  })\n}\n","import type { Context } from 'hono'\nimport type { ContentfulStatusCode } from 'hono/utils/http-status'\nimport type { Serializer } from './types'\nimport { encode, typesHeader, type Resolved } from './wire'\nimport { validateSerializer } from './validation'\nexport * from './wire'\n\nconst CONTEXT_KEY = 'hono-serialization'\nexport type Active = { serializer: Serializer; header: string }\nexport const getActive = (c: Context): Active | undefined =>\n  c.get(CONTEXT_KEY) as Active | undefined\nexport const setActive = (c: Context, active: Active): void => {\n  c.set(CONTEXT_KEY, active)\n}\n\nexport function lookup(\n  serializers: Serializer | readonly Serializer[],\n): Map<string, Serializer> {\n  const list: readonly Serializer[] = Array.isArray(serializers)\n    ? serializers\n    : [serializers as Serializer]\n  if (!list.length)\n    throw new TypeError('serialization: at least one serializer is required')\n  const byName = new Map<string, Serializer>()\n  for (const s of list) {\n    validateSerializer(s)\n    if (byName.has(s.name))\n      throw new TypeError(`serialization: duplicate name \"${s.name}\"`)\n    byName.set(s.name, s)\n  }\n  return byName\n}\nexport type HeaderRecord = Record<string, string | string[]>\nexport type ResponseOptions<\n  U extends ContentfulStatusCode = ContentfulStatusCode,\n> = Omit<ResponseInit, 'status'> & { status?: U }\nexport function appendHeader(\n  headers: Headers,\n  key: string,\n  value: string,\n): void {\n  const parts = (headers.get(key) ?? '')\n    .split(',')\n    .map((p) => p.trim())\n    .filter(Boolean)\n  if (\n    !parts.some((p) => p.toLowerCase() === value.toLowerCase()) &&\n    !(key.toLowerCase() === 'vary' && parts.includes('*'))\n  )\n    parts.push(value)\n  headers.set(key, parts.join(', '))\n}\nexport const sendEncoded = (\n  c: Context,\n  value: unknown,\n  arg: ContentfulStatusCode | ResponseOptions | undefined,\n  headers: HeaderRecord | undefined,\n  slot: Resolved,\n  header: string,\n  serializer: Serializer,\n): Response => {\n  const body = encode(slot, value)\n  const payload = body instanceof Uint8Array ? new Uint8Array(body) : body\n  const res =\n    typeof arg === 'object'\n      ? c.newResponse(payload, arg)\n      : c.newResponse(payload, arg, headers)\n  if (typeof arg === 'object' && headers) {\n    for (const [key, value] of Object.entries(headers)) {\n      res.headers.delete(key)\n      for (const item of typeof value === 'string' ? [value] : value)\n        res.headers.append(key, item)\n    }\n  }\n  if (slot.contentType) res.headers.set('Content-Type', slot.contentType)\n  res.headers.set(header, serializer.name)\n  res.headers.set(typesHeader(header), serializer.json.types ?? 'preserve')\n  appendHeader(res.headers, 'Access-Control-Expose-Headers', header)\n  appendHeader(\n    res.headers,\n    'Access-Control-Expose-Headers',\n    typesHeader(header),\n  )\n  return res\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AACA,SAAS,wBAAwB;;;ACMjC,IAAM,cAAc;AAEb,IAAM,YAAY,CAAC,MACxB,EAAE,IAAI,WAAW;AACZ,IAAM,YAAY,CAAC,GAAY,WAAyB;AAC7D,IAAE,IAAI,aAAa,MAAM;AAC3B;AAEO,SAAS,OACd,aACyB;AACzB,QAAM,OAA8B,MAAM,QAAQ,WAAW,IACzD,cACA,CAAC,WAAyB;AAC9B,MAAI,CAAC,KAAK;AACR,UAAM,IAAI,UAAU,oDAAoD;AAC1E,QAAM,SAAS,oBAAI,IAAwB;AAC3C,aAAW,KAAK,MAAM;AACpB,uBAAmB,CAAC;AACpB,QAAI,OAAO,IAAI,EAAE,IAAI;AACnB,YAAM,IAAI,UAAU,kCAAkC,EAAE,IAAI,GAAG;AACjE,WAAO,IAAI,EAAE,MAAM,CAAC;AAAA,EACtB;AACA,SAAO;AACT;AAKO,SAAS,aACd,SACA,KACA,OACM;AACN,QAAM,SAAS,QAAQ,IAAI,GAAG,KAAK,IAChC,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EACnB,OAAO,OAAO;AACjB,MACE,CAAC,MAAM,KAAK,CAAC,MAAM,EAAE,YAAY,MAAM,MAAM,YAAY,CAAC,KAC1D,EAAE,IAAI,YAAY,MAAM,UAAU,MAAM,SAAS,GAAG;AAEpD,UAAM,KAAK,KAAK;AAClB,UAAQ,IAAI,KAAK,MAAM,KAAK,IAAI,CAAC;AACnC;AACO,IAAM,cAAc,CACzB,GACA,OACA,KACA,SACA,MACA,QACA,eACa;AACb,QAAM,OAAO,OAAO,MAAM,KAAK;AAC/B,QAAM,UAAU,gBAAgB,aAAa,IAAI,WAAW,IAAI,IAAI;AACpE,QAAM,MACJ,OAAO,QAAQ,WACX,EAAE,YAAY,SAAS,GAAG,IAC1B,EAAE,YAAY,SAAS,KAAK,OAAO;AACzC,MAAI,OAAO,QAAQ,YAAY,SAAS;AACtC,eAAW,CAAC,KAAKA,MAAK,KAAK,OAAO,QAAQ,OAAO,GAAG;AAClD,UAAI,QAAQ,OAAO,GAAG;AACtB,iBAAW,QAAQ,OAAOA,WAAU,WAAW,CAACA,MAAK,IAAIA;AACvD,YAAI,QAAQ,OAAO,KAAK,IAAI;AAAA,IAChC;AAAA,EACF;AACA,MAAI,KAAK,YAAa,KAAI,QAAQ,IAAI,gBAAgB,KAAK,WAAW;AACtE,MAAI,QAAQ,IAAI,QAAQ,WAAW,IAAI;AACvC,MAAI,QAAQ,IAAI,YAAY,MAAM,GAAG,WAAW,KAAK,SAAS,UAAU;AACxE,eAAa,IAAI,SAAS,iCAAiC,MAAM;AACjE;AAAA,IACE,IAAI;AAAA,IACJ;AAAA,IACA,YAAY,MAAM;AAAA,EACpB;AACA,SAAO;AACT;;;AD7BO,SAAS,cACd,aACA,SACuD;AACvD,QAAM,SAAS,OAAO,WAAW;AACjC,QAAM,SAAS,SAAS,UAAU;AAClC,iBAAe,MAAM;AACrB,QAAM,aAAa,iBAAiB,OAAO,GAAG,SAAS;AACrD,UAAM,OAAO,EAAE,IAAI,OAAO,MAAM,GAAG,KAAK;AACxC,UAAM,SAAS,OAAO,OAAO,IAAI,IAAI,IAAI;AACzC,QAAI,QAAQ;AACV,gBAAU,GAAG,EAAE,YAAY,QAAQ,OAAO,CAAC;AAC3C,YAAM,QAAQ,aAAa,OAAO,IAAI;AACtC,UAAI,OAAO;AACT,YAAI;AACJ,UAAE,IAAI,QAAQ,MACX,YAAY,YAAY;AACvB,gBAAM,OAAO,MAAM,SACf,IAAI,WAAW,MAAM,EAAE,IAAI,YAAY,CAAC,IACxC,MAAM,EAAE,IAAI,KAAK;AACrB,iBAAO,MAAM,MAAM,IAAa;AAAA,QAClC,GAAG;AAAA,MACP;AAAA,IACF;AACA,UAAM,KAAK;AACX,UAAM,kBAAkB,IAAI,QAAQ,EAAE,IAAI,OAAO;AACjD,iBAAa,iBAAiB,QAAQ,MAAM;AAC5C,MAAE,OAAO,QAAQ,gBAAgB,IAAI,MAAM,CAAE;AAC7C,QAAI,EAAE,IAAI,QAAQ,IAAI,MAAM,GAAG;AAC7B,iBAAWC,SAAQ,CAAC,QAAQ,YAAY,MAAM,CAAC,GAAG;AAChD,qBAAa,iBAAiB,iCAAiCA,KAAI;AAAA,MACrE;AACA,QAAE;AAAA,QACA;AAAA,QACA,gBAAgB,IAAI,+BAA+B;AAAA,MACrD;AAAA,IACF;AAAA,EACF,CAAC;AACD,QAAM,OAAO,CACX,GACA,OACA,KACA,YACa;AACb,UAAM,SAAS,UAAU,CAAC;AAC1B,QACE,WACC,OAAO,WAAW,UACjB,OAAO,IAAI,OAAO,WAAW,IAAI,MAAM,OAAO,aAChD;AACA,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAEA,UAAM,OACJ,OAAO,QAAQ,WACX,EAAE,GAAG,KAAK,QAAQ,IAAI,UAAU,IAAI,IACnC,OAAO;AACd,QAAI,QAAQ;AACV,aAAO;AAAA,QACL;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,QAAQ,OAAO,WAAW,IAAI;AAAA,QAC9B;AAAA,QACA,OAAO;AAAA,MACT;AAAA,IACF;AAEA,WAAO,OAAO,SAAS,WACnB,EAAE,KAAK,OAAgB,IAAI,IAC3B,EAAE,KAAK,OAAgB,MAAM,OAAO;AAAA,EAC1C;AACA,SAAO,OAAO,OAAO,YAAY;AAAA,IAC/B;AAAA,EACF,CAAC;AACH;","names":["value","name"]}

package/dist/types-Ce9-Amxx.d.ts

@@ -0,0 +1,76 @@
+import { Hono, Schema } from 'hono';
+import { JSONParsed } from 'hono/utils/types';
+
+type WireBody = string | ArrayBuffer | Uint8Array;
+type CodecTypes = 'preserve' | 'json-parsed' | 'unknown';
+/** The discriminant makes the bytes passed to parse explicit. */
+type WireSerializer<Value = unknown, Parsed = unknown> = ({
+    binary?: false;
+    serialize: (value: Value) => string;
+    parse: (data: string) => Parsed;
+} | {
+    binary: true;
+    serialize: (value: Value) => Uint8Array | ArrayBuffer;
+    parse: (data: Uint8Array) => Parsed;
+}) & {
+    contentType?: string;
+};
+type JsonSerializer<Value = unknown> = WireSerializer<Value> & {
+    input?: WireSerializer & {
+        types?: 'preserve' | 'json-parsed';
+    };
+    /**
+     * What a round trip does to types. Defaults to `preserve`: values and
+     * types survive. `json-parsed` promises ordinary JSON conversion and
+     * `unknown` makes no promise.
+     */
+    types?: CodecTypes;
+};
+type Serializer<Name extends string = string> = {
+    name: Name;
+    json: JsonSerializer;
+};
+type SerializerList = Serializer | readonly Serializer[];
+type SerializerOf<S extends SerializerList> = S extends readonly Serializer[] ? S[number] : S;
+declare const serialized: unique symbol;
+type SerializedOutput<T, S extends Serializer = Serializer> = {
+    readonly [serialized]: {
+        value: T;
+        serializer: S;
+    };
+};
+type JsonInput<I> = I extends object ? {
+    [K in keyof I]: K extends 'json' ? JSONParsed<I[K]> : I[K];
+} : I;
+type DecodeOutput<O, Types extends CodecTypes> = O extends SerializedOutput<infer T> ? Types extends 'preserve' ? T : Types extends 'json-parsed' ? JSONParsed<T> : unknown : O;
+type Endpoint<E, Types extends CodecTypes, Plain extends boolean> = E extends {
+    input: infer I;
+    output: infer O;
+    outputFormat: infer F;
+    status: infer St;
+} ? {
+    input: Plain extends true ? JsonInput<I> : I;
+    output: F extends 'json' ? DecodeOutput<O, Types> : O;
+    outputFormat: F;
+    status: St;
+} : E;
+type MapSchema<S, Types extends CodecTypes, Plain extends boolean> = {
+    [P in keyof S]: {
+        [M in keyof S[P]]: Endpoint<S[P][M], Types, Plain>;
+    };
+};
+type ClientApp<T, Types extends CodecTypes, RichInput extends boolean = false> = T extends Hono<infer E, infer S, infer P> ? MapSchema<S, Types, RichInput extends true ? false : true> extends infer M extends Schema ? Hono<E, M, P> : never : never;
+/** A plain JSON client converts both request and response JSON values. */
+type JsonApp<T> = T extends Hono<infer E, infer S, infer P> ? MapSchema<S, 'json-parsed', true> extends infer M extends Schema ? Hono<E, M, P> : never : never;
+type EndpointSerializer<E> = E extends {
+    output: infer O;
+} ? O extends SerializedOutput<unknown, infer S> ? S : never : never;
+type SchemaSerializers<S> = {
+    [P in keyof S]: {
+        [M in keyof S[P]]: EndpointSerializer<S[P][M]>;
+    }[keyof S[P]];
+}[keyof S];
+/** Restrict clients to serializer definitions carried by the app's typed helpers. */
+type AppSerializer<T> = T extends Hono<infer _E, infer S, infer _P> ? [SchemaSerializers<S>] extends [never] ? Serializer : SchemaSerializers<S> : never;
+
+export type { AppSerializer as A, CodecTypes as C, JsonApp as J, Serializer as S, WireSerializer as W, ClientApp as a, SerializedOutput as b, SerializerList as c, SerializerOf as d, JsonSerializer as e, WireBody as f };

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "hono-serialization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Opt-in Hono serialize/deserialize via a request header. Bring your own superjson, seroval, devalue or cbor-x.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./codec": {
+      "types": "./dist/codec.d.ts",
+      "import": "./dist/codec.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run check:release",
+    "check:package": "tsc -p tsconfig.package.json && node checks/package-boundaries.mjs",
+    "check:install": "node checks/package-install.mjs",
+    "check:release": "npm run typecheck && npm test && npm run build && npm run check:package && npm run check:install"
+  },
+  "keywords": [
+    "hono",
+    "rpc",
+    "serialization",
+    "serializer",
+    "superjson",
+    "seroval",
+    "devalue",
+    "cbor-x"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "hono": "^4.13.13"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "cbor-x": "^1.6.6",
+    "devalue": "^6.0.2",
+    "hono": "^4.13.13",
+    "seroval": "^1.6.9",
+    "superjson": "^2.2.6",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.4"
+  },
+  "tsup": {
+    "entry": [
+      "src/index.ts",
+      "src/client.ts",
+      "src/codec.ts"
+    ],
+    "format": [
+      "esm"
+    ],
+    "dts": {
+      "compilerOptions": {
+        "ignoreDeprecations": "6.0"
+      }
+    },
+    "splitting": true,
+    "sourcemap": true,
+    "clean": true
+  },
+  "author": "Sebastian Broman",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SebbeBroman/hono-serialization.git"
+  },
+  "homepage": "https://github.com/SebbeBroman/hono-serialization#readme",
+  "bugs": {
+    "url": "https://github.com/SebbeBroman/hono-serialization/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}