@ayepi/codec 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,79 @@
+# @ayepi/codec
+
+Rich, reversible JSON. A **tagged codec** that round-trips the values plain
+`JSON.stringify`/`parse` silently lose or mangle — `Date`, `BigInt`, `Map`, `Set`,
+`undefined`, `Error`, `RegExp`, `URL`, and the number specials `NaN`/`±Infinity` —
+plus any custom types you register. Zero dependencies.
+
+```sh
+pnpm add @ayepi/codec
+```
+
+```ts
+import { stringify, parse } from '@ayepi/codec'
+
+const s = stringify({ when: new Date(), ids: new Set([1n, 2n]), missing: undefined })
+const value = parse(s)
+// value.when  → Date
+// value.ids   → Set<bigint>
+// value.missing === undefined   (preserved, not dropped)
+```
+
+Bare `import` has **no side effects**.
+
+## How it works
+
+A value a codec handles is wrapped as `{ "$t": "<tag>", "value": <payload> }`.
+Encoding/decoding is **recursive**, so a `Map` of `Date`s, a `Set` of objects, and
+deeply nested mixes all round-trip. Ordinary JSON values (`null`, booleans, finite
+numbers, strings, plain arrays/objects) pass through untouched.
+
+If a *plain* object legitimately owns a `$t` property, it is **escaped** so it still
+round-trips:
+
+```ts
+parse(stringify({ $t: 'hello' })) // → { $t: 'hello' }  ✅
+```
+
+## Custom types
+
+Register a `TypeCodec` (a `tag`, a `test`, and `encode`/`decode`):
+
+```ts
+import { createCodec } from '@ayepi/codec'
+
+class Point { constructor(public x: number, public y: number) {} }
+
+const codec = createCodec({
+  types: [{
+    tag: 'Point',
+    test: (v) => v instanceof Point,
+    encode: (p: Point) => [p.x, p.y],
+    decode: ([x, y]: [number, number]) => new Point(x, y),
+  }],
+})
+
+codec.parse(codec.stringify(new Point(3, 4))) // → Point { x: 3, y: 4 }
+```
+
+Custom types are checked **before** the built-ins, so a custom codec can override one
+(e.g. store `Date` as epoch millis). Pass `replaceBuiltins: true` to drop the built-ins
+entirely, or `tagKey` to change the sentinel key from `'$t'`.
+
+`encode`/`decode` are also exposed standalone (value ⇄ JSON-safe value, no string step).
+
+> No circular-reference support — a cycle overflows the stack, exactly like
+> `JSON.stringify`.
+
+## For AI coding agents
+
+This package ships dense, machine-oriented reference docs written for **AI coding agents**
+(Claude Code, Cursor, and the like) to understand and drive the package — point your agent at them:
+
+- [`ayepi-codec.md`](./ayepi-codec.md)
+
+They live next to the source in the [repo](https://github.com/ClickerMonkey/ayepi/tree/main/packages/codec) and are **not** shipped in the npm tarball.
+
+## License
+
+MIT © Philip Diffenderfer

package/dist/index.cjs

@@ -0,0 +1,194 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/builtins.ts
+/** `{@link Number}` payloads are the IEEE-754 specials JSON renders as `null`. */
+const NEGATIVE_INFINITY = "-Infinity";
+const POSITIVE_INFINITY = "Infinity";
+const NOT_A_NUMBER = "NaN";
+/**
+* The default codecs, in match order. They are ordered most-specific first; note that
+* `Map`/`Set`/`Date`/`Error`/`RegExp`/`URL` are mutually exclusive `instanceof`
+* checks, so order among them is immaterial.
+*/
+const builtinTypes = [
+	{
+		tag: "undefined",
+		test: (value) => value === void 0,
+		encode: () => 0,
+		decode: () => void 0
+	},
+	{
+		tag: "Number",
+		test: (value) => typeof value === "number" && !Number.isFinite(value),
+		encode: (value) => {
+			if (Number.isNaN(value)) return NOT_A_NUMBER;
+			return value > 0 ? POSITIVE_INFINITY : NEGATIVE_INFINITY;
+		},
+		decode: (payload) => {
+			if (payload === NOT_A_NUMBER) return NaN;
+			return payload === POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+		}
+	},
+	{
+		tag: "BigInt",
+		test: (value) => typeof value === "bigint",
+		encode: (value) => value.toString(),
+		decode: (payload) => BigInt(payload)
+	},
+	{
+		tag: "Date",
+		test: (value) => value instanceof Date,
+		encode: (value) => value.toISOString(),
+		decode: (payload) => new Date(payload)
+	},
+	{
+		tag: "Map",
+		test: (value) => value instanceof Map,
+		encode: (value, recurse) => [...value.entries()].map(([k, v]) => [recurse(k), recurse(v)]),
+		decode: (payload, recurse) => new Map(payload.map(([k, v]) => [recurse(k), recurse(v)]))
+	},
+	{
+		tag: "Set",
+		test: (value) => value instanceof Set,
+		encode: (value, recurse) => [...value.values()].map((v) => recurse(v)),
+		decode: (payload, recurse) => new Set(payload.map((v) => recurse(v)))
+	},
+	{
+		tag: "Error",
+		test: (value) => value instanceof Error,
+		encode: (value) => {
+			return {
+				name: value.name,
+				message: value.message,
+				stack: value.stack
+			};
+		},
+		decode: (payload) => {
+			const data = payload;
+			const error = new Error(data.message);
+			error.name = data.name;
+			if (data.stack === void 0) delete error.stack;
+			else error.stack = data.stack;
+			return error;
+		}
+	},
+	{
+		tag: "RegExp",
+		test: (value) => value instanceof RegExp,
+		encode: (value) => {
+			return {
+				source: value.source,
+				flags: value.flags
+			};
+		},
+		decode: (payload) => {
+			const data = payload;
+			return new RegExp(data.source, data.flags);
+		}
+	},
+	{
+		tag: "URL",
+		test: (value) => value instanceof URL,
+		encode: (value) => value.href,
+		decode: (payload) => new URL(payload)
+	}
+];
+//#endregion
+//#region src/codec.ts
+/**
+* # The codec engine
+*
+* {@link createCodec} composes a list of {@link TypeCodec}s into a {@link Codec} that
+* recursively encodes/decodes values to and from a JSON-safe shape.
+*
+* ## Wire format
+*
+* A value handled by a {@link TypeCodec} is wrapped as
+* `{ [tagKey]: tag, value: <payload> }`. Plain objects and arrays are walked and their
+* entries encoded recursively. Everything else (`null`, booleans, finite numbers,
+* strings) passes through.
+*
+* ## Collision escape
+*
+* If a *plain* user object already owns a property equal to `tagKey`, it would be
+* indistinguishable from a wrapper. Such objects are escaped as
+* `{ [tagKey]: ESCAPE_TAG, value: <encoded plain object> }` so they round-trip
+* losslessly. Decoding recognizes the escape tag and unwraps it.
+*
+* Circular references are **not** supported and will overflow the stack, exactly as
+* with `JSON.stringify`.
+*
+* @module
+*/
+/** Default sentinel key for the tagged wrapper. */
+const DEFAULT_TAG_KEY = "$t";
+/** Reserved tag used to escape plain objects that collide with the {@link tagKey}. */
+const ESCAPE_TAG = "$escape";
+/** Whether `value` is a non-null, non-array object (a candidate for walking). */
+const isPlainObjectLike = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Build a {@link Codec} from the built-in type codecs plus any custom {@link TypeCodec}s.
+*
+* @param options - custom types, built-in replacement, and the wrapper tag key.
+* @returns a codec exposing `stringify`/`parse`/`encode`/`decode`.
+*/
+function createCodec(options = {}) {
+	const { types = [], replaceBuiltins = false, tagKey = DEFAULT_TAG_KEY } = options;
+	const codecs = replaceBuiltins ? types : [...types, ...builtinTypes];
+	const byTag = new Map(codecs.map((codec) => [codec.tag, codec]));
+	/** Recursively encode `value` into its JSON-safe shape. */
+	const encode = (value) => {
+		for (const codec of codecs) if (codec.test(value)) return {
+			[tagKey]: codec.tag,
+			value: codec.encode(value, encode)
+		};
+		if (Array.isArray(value)) return value.map((item) => encode(item));
+		if (isPlainObjectLike(value)) {
+			const encoded = {};
+			for (const [key, inner] of Object.entries(value)) encoded[key] = encode(inner);
+			if (Object.prototype.hasOwnProperty.call(value, tagKey)) return {
+				[tagKey]: ESCAPE_TAG,
+				value: encoded
+			};
+			return encoded;
+		}
+		return value;
+	};
+	/** Decode the own properties of an (already-encoded) plain object, one by one. */
+	const decodeEntries = (value) => {
+		const decoded = {};
+		for (const [key, inner] of Object.entries(value)) decoded[key] = decode(inner);
+		return decoded;
+	};
+	/** Recursively decode a JSON-safe `value` back into a rich value. */
+	const decode = (value) => {
+		if (Array.isArray(value)) return value.map((item) => decode(item));
+		if (!isPlainObjectLike(value)) return value;
+		if (Object.prototype.hasOwnProperty.call(value, tagKey)) {
+			const tag = value[tagKey];
+			if (tag === ESCAPE_TAG) return decodeEntries(value.value);
+			const codec = typeof tag === "string" ? byTag.get(tag) : void 0;
+			if (codec !== void 0) return codec.decode(value.value, decode);
+		}
+		return decodeEntries(value);
+	};
+	return {
+		encode,
+		decode,
+		stringify: (value) => JSON.stringify(encode(value)),
+		parse: (text) => decode(JSON.parse(text))
+	};
+}
+//#endregion
+//#region src/index.ts
+/** A ready-to-use {@link Codec} with the default built-in types and tag key (`'$t'`). */
+const defaultCodec = createCodec();
+/** Encode + `JSON.stringify` a value, bound to {@link defaultCodec}. */
+const stringify = (value) => defaultCodec.stringify(value);
+/** `JSON.parse` + decode a string, bound to {@link defaultCodec}. */
+const parse = (text) => defaultCodec.parse(text);
+//#endregion
+exports.builtinTypes = builtinTypes;
+exports.createCodec = createCodec;
+exports.defaultCodec = defaultCodec;
+exports.parse = parse;
+exports.stringify = stringify;

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+//#region src/types.d.ts
+/**
+ * # Public types for `@ayepi/codec`
+ *
+ * The codec is built from a list of {@link TypeCodec}s. Each one claims a slice of
+ * the value space ({@link TypeCodec.test}) and knows how to turn its values into a
+ * JSON-safe payload and back. {@link createCodec} composes a list into a working
+ * {@link Codec}.
+ *
+ * @module
+ */
+/**
+ * Recurses into a nested value during encode/decode. A {@link TypeCodec} calls it on
+ * the inner values of a container (e.g. a `Map`'s entries) so that nested rich types
+ * are encoded/decoded too.
+ */
+type Recurse = (value: unknown) => unknown;
+/**
+ * Handles one kind of value that plain JSON can't represent. A codec is registered by
+ * its {@link tag} and turns matching values into a JSON-safe payload (and back).
+ *
+ * @typeParam T - the value type this codec handles; defaults to `unknown`.
+ */
+interface TypeCodec<T = unknown> {
+  /** Unique short tag stored in the wire wrapper, e.g. `'Date'`. */
+  readonly tag: string;
+  /** Whether this codec handles `value` (decides which codec encodes a value). */
+  test(value: unknown): boolean;
+  /** Turn `value` into a JSON-safe payload, using `recurse` for any nested values. */
+  encode(value: T, recurse: Recurse): unknown;
+  /** Rebuild the value from a payload produced by {@link encode}. */
+  decode(payload: unknown, recurse: Recurse): T;
+}
+/** Options for {@link createCodec}. */
+interface CodecOptions {
+  /**
+   * Custom type codecs. By default they are checked *before* the built-ins, so a
+   * custom codec can override a built-in; set {@link replaceBuiltins} to use them
+   * instead of the built-ins. Within the combined list, earlier codecs win when more
+   * than one matches a value.
+   */
+  readonly types?: readonly TypeCodec[];
+  /**
+   * Replace the built-in codecs entirely with {@link types} rather than prepending.
+   * @defaultValue `false`
+   */
+  readonly replaceBuiltins?: boolean;
+  /**
+   * The sentinel key marking a tagged wrapper on the wire.
+   * @defaultValue `'$t'`
+   */
+  readonly tagKey?: string;
+}
+/** A bidirectional rich-JSON codec produced by {@link createCodec}. */
+interface Codec {
+  /** Encode then `JSON.stringify` a value to a string. */
+  stringify(value: unknown): string;
+  /** `JSON.parse` then decode a string back to a value. */
+  parse(text: string): unknown;
+  /** Encode a value to a JSON-safe value (no stringification). */
+  encode(value: unknown): unknown;
+  /** Decode a JSON-safe value back to a rich value (no parsing). */
+  decode(value: unknown): unknown;
+}
+//#endregion
+//#region src/builtins.d.ts
+/**
+ * The default codecs, in match order. They are ordered most-specific first; note that
+ * `Map`/`Set`/`Date`/`Error`/`RegExp`/`URL` are mutually exclusive `instanceof`
+ * checks, so order among them is immaterial.
+ */
+declare const builtinTypes: readonly TypeCodec[];
+//#endregion
+//#region src/codec.d.ts
+
+/**
+ * Build a {@link Codec} from the built-in type codecs plus any custom {@link TypeCodec}s.
+ *
+ * @param options - custom types, built-in replacement, and the wrapper tag key.
+ * @returns a codec exposing `stringify`/`parse`/`encode`/`decode`.
+ */
+declare function createCodec(options?: CodecOptions): Codec;
+//#endregion
+//#region src/index.d.ts
+
+/** A ready-to-use {@link Codec} with the default built-in types and tag key (`'$t'`). */
+declare const defaultCodec: Codec;
+/** Encode + `JSON.stringify` a value, bound to {@link defaultCodec}. */
+declare const stringify: (value: unknown) => string;
+/** `JSON.parse` + decode a string, bound to {@link defaultCodec}. */
+declare const parse: (text: string) => unknown;
+//#endregion
+export { type Codec, type CodecOptions, type Recurse, type TypeCodec, builtinTypes, createCodec, defaultCodec, parse, stringify };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+//#region src/types.d.ts
+/**
+ * # Public types for `@ayepi/codec`
+ *
+ * The codec is built from a list of {@link TypeCodec}s. Each one claims a slice of
+ * the value space ({@link TypeCodec.test}) and knows how to turn its values into a
+ * JSON-safe payload and back. {@link createCodec} composes a list into a working
+ * {@link Codec}.
+ *
+ * @module
+ */
+/**
+ * Recurses into a nested value during encode/decode. A {@link TypeCodec} calls it on
+ * the inner values of a container (e.g. a `Map`'s entries) so that nested rich types
+ * are encoded/decoded too.
+ */
+type Recurse = (value: unknown) => unknown;
+/**
+ * Handles one kind of value that plain JSON can't represent. A codec is registered by
+ * its {@link tag} and turns matching values into a JSON-safe payload (and back).
+ *
+ * @typeParam T - the value type this codec handles; defaults to `unknown`.
+ */
+interface TypeCodec<T = unknown> {
+  /** Unique short tag stored in the wire wrapper, e.g. `'Date'`. */
+  readonly tag: string;
+  /** Whether this codec handles `value` (decides which codec encodes a value). */
+  test(value: unknown): boolean;
+  /** Turn `value` into a JSON-safe payload, using `recurse` for any nested values. */
+  encode(value: T, recurse: Recurse): unknown;
+  /** Rebuild the value from a payload produced by {@link encode}. */
+  decode(payload: unknown, recurse: Recurse): T;
+}
+/** Options for {@link createCodec}. */
+interface CodecOptions {
+  /**
+   * Custom type codecs. By default they are checked *before* the built-ins, so a
+   * custom codec can override a built-in; set {@link replaceBuiltins} to use them
+   * instead of the built-ins. Within the combined list, earlier codecs win when more
+   * than one matches a value.
+   */
+  readonly types?: readonly TypeCodec[];
+  /**
+   * Replace the built-in codecs entirely with {@link types} rather than prepending.
+   * @defaultValue `false`
+   */
+  readonly replaceBuiltins?: boolean;
+  /**
+   * The sentinel key marking a tagged wrapper on the wire.
+   * @defaultValue `'$t'`
+   */
+  readonly tagKey?: string;
+}
+/** A bidirectional rich-JSON codec produced by {@link createCodec}. */
+interface Codec {
+  /** Encode then `JSON.stringify` a value to a string. */
+  stringify(value: unknown): string;
+  /** `JSON.parse` then decode a string back to a value. */
+  parse(text: string): unknown;
+  /** Encode a value to a JSON-safe value (no stringification). */
+  encode(value: unknown): unknown;
+  /** Decode a JSON-safe value back to a rich value (no parsing). */
+  decode(value: unknown): unknown;
+}
+//#endregion
+//#region src/builtins.d.ts
+/**
+ * The default codecs, in match order. They are ordered most-specific first; note that
+ * `Map`/`Set`/`Date`/`Error`/`RegExp`/`URL` are mutually exclusive `instanceof`
+ * checks, so order among them is immaterial.
+ */
+declare const builtinTypes: readonly TypeCodec[];
+//#endregion
+//#region src/codec.d.ts
+
+/**
+ * Build a {@link Codec} from the built-in type codecs plus any custom {@link TypeCodec}s.
+ *
+ * @param options - custom types, built-in replacement, and the wrapper tag key.
+ * @returns a codec exposing `stringify`/`parse`/`encode`/`decode`.
+ */
+declare function createCodec(options?: CodecOptions): Codec;
+//#endregion
+//#region src/index.d.ts
+
+/** A ready-to-use {@link Codec} with the default built-in types and tag key (`'$t'`). */
+declare const defaultCodec: Codec;
+/** Encode + `JSON.stringify` a value, bound to {@link defaultCodec}. */
+declare const stringify: (value: unknown) => string;
+/** `JSON.parse` + decode a string, bound to {@link defaultCodec}. */
+declare const parse: (text: string) => unknown;
+//#endregion
+export { type Codec, type CodecOptions, type Recurse, type TypeCodec, builtinTypes, createCodec, defaultCodec, parse, stringify };

package/dist/index.js

@@ -0,0 +1,189 @@
+//#region src/builtins.ts
+/** `{@link Number}` payloads are the IEEE-754 specials JSON renders as `null`. */
+const NEGATIVE_INFINITY = "-Infinity";
+const POSITIVE_INFINITY = "Infinity";
+const NOT_A_NUMBER = "NaN";
+/**
+* The default codecs, in match order. They are ordered most-specific first; note that
+* `Map`/`Set`/`Date`/`Error`/`RegExp`/`URL` are mutually exclusive `instanceof`
+* checks, so order among them is immaterial.
+*/
+const builtinTypes = [
+	{
+		tag: "undefined",
+		test: (value) => value === void 0,
+		encode: () => 0,
+		decode: () => void 0
+	},
+	{
+		tag: "Number",
+		test: (value) => typeof value === "number" && !Number.isFinite(value),
+		encode: (value) => {
+			if (Number.isNaN(value)) return NOT_A_NUMBER;
+			return value > 0 ? POSITIVE_INFINITY : NEGATIVE_INFINITY;
+		},
+		decode: (payload) => {
+			if (payload === NOT_A_NUMBER) return NaN;
+			return payload === POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : Number.NEGATIVE_INFINITY;
+		}
+	},
+	{
+		tag: "BigInt",
+		test: (value) => typeof value === "bigint",
+		encode: (value) => value.toString(),
+		decode: (payload) => BigInt(payload)
+	},
+	{
+		tag: "Date",
+		test: (value) => value instanceof Date,
+		encode: (value) => value.toISOString(),
+		decode: (payload) => new Date(payload)
+	},
+	{
+		tag: "Map",
+		test: (value) => value instanceof Map,
+		encode: (value, recurse) => [...value.entries()].map(([k, v]) => [recurse(k), recurse(v)]),
+		decode: (payload, recurse) => new Map(payload.map(([k, v]) => [recurse(k), recurse(v)]))
+	},
+	{
+		tag: "Set",
+		test: (value) => value instanceof Set,
+		encode: (value, recurse) => [...value.values()].map((v) => recurse(v)),
+		decode: (payload, recurse) => new Set(payload.map((v) => recurse(v)))
+	},
+	{
+		tag: "Error",
+		test: (value) => value instanceof Error,
+		encode: (value) => {
+			return {
+				name: value.name,
+				message: value.message,
+				stack: value.stack
+			};
+		},
+		decode: (payload) => {
+			const data = payload;
+			const error = new Error(data.message);
+			error.name = data.name;
+			if (data.stack === void 0) delete error.stack;
+			else error.stack = data.stack;
+			return error;
+		}
+	},
+	{
+		tag: "RegExp",
+		test: (value) => value instanceof RegExp,
+		encode: (value) => {
+			return {
+				source: value.source,
+				flags: value.flags
+			};
+		},
+		decode: (payload) => {
+			const data = payload;
+			return new RegExp(data.source, data.flags);
+		}
+	},
+	{
+		tag: "URL",
+		test: (value) => value instanceof URL,
+		encode: (value) => value.href,
+		decode: (payload) => new URL(payload)
+	}
+];
+//#endregion
+//#region src/codec.ts
+/**
+* # The codec engine
+*
+* {@link createCodec} composes a list of {@link TypeCodec}s into a {@link Codec} that
+* recursively encodes/decodes values to and from a JSON-safe shape.
+*
+* ## Wire format
+*
+* A value handled by a {@link TypeCodec} is wrapped as
+* `{ [tagKey]: tag, value: <payload> }`. Plain objects and arrays are walked and their
+* entries encoded recursively. Everything else (`null`, booleans, finite numbers,
+* strings) passes through.
+*
+* ## Collision escape
+*
+* If a *plain* user object already owns a property equal to `tagKey`, it would be
+* indistinguishable from a wrapper. Such objects are escaped as
+* `{ [tagKey]: ESCAPE_TAG, value: <encoded plain object> }` so they round-trip
+* losslessly. Decoding recognizes the escape tag and unwraps it.
+*
+* Circular references are **not** supported and will overflow the stack, exactly as
+* with `JSON.stringify`.
+*
+* @module
+*/
+/** Default sentinel key for the tagged wrapper. */
+const DEFAULT_TAG_KEY = "$t";
+/** Reserved tag used to escape plain objects that collide with the {@link tagKey}. */
+const ESCAPE_TAG = "$escape";
+/** Whether `value` is a non-null, non-array object (a candidate for walking). */
+const isPlainObjectLike = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Build a {@link Codec} from the built-in type codecs plus any custom {@link TypeCodec}s.
+*
+* @param options - custom types, built-in replacement, and the wrapper tag key.
+* @returns a codec exposing `stringify`/`parse`/`encode`/`decode`.
+*/
+function createCodec(options = {}) {
+	const { types = [], replaceBuiltins = false, tagKey = DEFAULT_TAG_KEY } = options;
+	const codecs = replaceBuiltins ? types : [...types, ...builtinTypes];
+	const byTag = new Map(codecs.map((codec) => [codec.tag, codec]));
+	/** Recursively encode `value` into its JSON-safe shape. */
+	const encode = (value) => {
+		for (const codec of codecs) if (codec.test(value)) return {
+			[tagKey]: codec.tag,
+			value: codec.encode(value, encode)
+		};
+		if (Array.isArray(value)) return value.map((item) => encode(item));
+		if (isPlainObjectLike(value)) {
+			const encoded = {};
+			for (const [key, inner] of Object.entries(value)) encoded[key] = encode(inner);
+			if (Object.prototype.hasOwnProperty.call(value, tagKey)) return {
+				[tagKey]: ESCAPE_TAG,
+				value: encoded
+			};
+			return encoded;
+		}
+		return value;
+	};
+	/** Decode the own properties of an (already-encoded) plain object, one by one. */
+	const decodeEntries = (value) => {
+		const decoded = {};
+		for (const [key, inner] of Object.entries(value)) decoded[key] = decode(inner);
+		return decoded;
+	};
+	/** Recursively decode a JSON-safe `value` back into a rich value. */
+	const decode = (value) => {
+		if (Array.isArray(value)) return value.map((item) => decode(item));
+		if (!isPlainObjectLike(value)) return value;
+		if (Object.prototype.hasOwnProperty.call(value, tagKey)) {
+			const tag = value[tagKey];
+			if (tag === ESCAPE_TAG) return decodeEntries(value.value);
+			const codec = typeof tag === "string" ? byTag.get(tag) : void 0;
+			if (codec !== void 0) return codec.decode(value.value, decode);
+		}
+		return decodeEntries(value);
+	};
+	return {
+		encode,
+		decode,
+		stringify: (value) => JSON.stringify(encode(value)),
+		parse: (text) => decode(JSON.parse(text))
+	};
+}
+//#endregion
+//#region src/index.ts
+/** A ready-to-use {@link Codec} with the default built-in types and tag key (`'$t'`). */
+const defaultCodec = createCodec();
+/** Encode + `JSON.stringify` a value, bound to {@link defaultCodec}. */
+const stringify = (value) => defaultCodec.stringify(value);
+/** `JSON.parse` + decode a string, bound to {@link defaultCodec}. */
+const parse = (text) => defaultCodec.parse(text);
+//#endregion
+export { builtinTypes, createCodec, defaultCodec, parse, stringify };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ayepi/codec",
+  "version": "0.1.0",
+  "description": "Rich JSON codec — tagged, reversible serialization of Date, BigInt, Map, Set, undefined, Error, and custom types through JSON.stringify/parse",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClickerMonkey/ayepi.git",
+    "directory": "packages/codec"
+  },
+  "homepage": "https://github.com/ClickerMonkey/ayepi/tree/main/packages/codec#readme",
+  "bugs": {
+    "url": "https://github.com/ClickerMonkey/ayepi/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^2.1.8",
+    "publint": "^0.3.0",
+    "tsdown": "^0.12.0",
+    "vitest": "^2.1.8"
+  },
+  "keywords": [
+    "ayepi",
+    "json",
+    "codec",
+    "serialization",
+    "date",
+    "bigint",
+    "map",
+    "set"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "publint": "publint"
+  }
+}