@automate.ax/codec 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Sents
+
+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,37 @@
+# `@automate.ax/codec`
+
+Msgpack-based encoding helpers for Automate.ax runtime data.
+
+This package owns the shared `Encodable` value contract used by automation signals and storage boundaries. Most app authors should not need it directly.
+
+## Install
+
+```bash
+bun add @automate.ax/codec
+```
+
+## Usage
+
+```ts
+import { decode, encodableSchema, encode } from "@automate.ax/codec"
+
+const bytes = await encode({
+  message: "hello",
+  createdAt: new Date(),
+})
+
+const value = await decode(bytes)
+const validated = encodableSchema.parse(value)
+```
+
+## API
+
+- `encode(value)` — Checks an unknown value against the supported input surface, then serializes it.
+- `decode(bytes)` — Deserializes msgpack bytes and returns `Encodable`.
+- `encodableSchema` — Zod schema for validating unknown values against the supported input surface.
+- `isEncodable(value)` — Runtime guard for the supported input surface.
+- `Encodable` — Recursive type accepted by the encoder.
+
+## Supported Values
+
+`Encodable` includes primitives, arrays, plain objects, `Map`, `Set`, `Date`, `RegExp`, typed arrays, `ArrayBuffer`, `DataView`, and web platform values such as `Request`, `Response`, `Blob`, `File`, `Headers`, `URL`, and `URLSearchParams`.

package/dist/buffered.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Sync snapshots of async-bodied web types (`Request`, `Response`, `Blob`,
+ * `File`) after their bodies have been drained. msgpackr's extension `write`
+ * callback is synchronous, so anything with an async body must be pre-processed
+ * into one of these before packing.
+ */
+/**
+ * `Uint8Array<ArrayBuffer>` — the shape `BodyInit`/`BlobPart` expect under DOM
+ * lib.
+ */
+type Bytes = Uint8Array<ArrayBuffer>;
+/** A serializable snapshot of a request and its buffered body. */
+export declare class BufferedRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: Bytes | null;
+    /**
+     * Creates a buffered request snapshot.
+     *
+     * @param url - Original request URL.
+     * @param method - Original HTTP method.
+     * @param headers - Original headers as string entries.
+     * @param body - Buffered body, or `null` when the request has no body.
+     */
+    constructor(url: string, method: string, headers: Record<string, string>, body: Bytes | null);
+    /**
+     * Drains a request into a serializable snapshot.
+     *
+     * @param req - Request to buffer.
+     */
+    static from(req: Request): Promise<BufferedRequest>;
+    /** Reconstructs a request from this snapshot. */
+    toRequest(): Request;
+}
+/** A serializable snapshot of a response and its buffered body. */
+export declare class BufferedResponse {
+    readonly status: number;
+    readonly statusText: string;
+    readonly headers: Record<string, string>;
+    readonly body: Bytes | null;
+    /**
+     * Creates a buffered response snapshot.
+     *
+     * @param status - Original response status code.
+     * @param statusText - Original response status text.
+     * @param headers - Original headers as string entries.
+     * @param body - Buffered body, or `null` when the response has no body.
+     */
+    constructor(status: number, statusText: string, headers: Record<string, string>, body: Bytes | null);
+    /**
+     * Drains a response into a serializable snapshot.
+     *
+     * @param res - Response to buffer.
+     */
+    static from(res: Response): Promise<BufferedResponse>;
+    /** Reconstructs a response from this snapshot. */
+    toResponse(): Response;
+}
+/** A serializable snapshot of a blob and its buffered bytes. */
+export declare class BufferedBlob {
+    readonly type: string;
+    readonly bytes: Bytes;
+    /**
+     * Creates a buffered blob snapshot.
+     *
+     * @param type - Original media type.
+     * @param bytes - Buffered blob contents.
+     */
+    constructor(type: string, bytes: Bytes);
+    /**
+     * Drains a blob into a serializable snapshot.
+     *
+     * @param blob - Blob to buffer.
+     */
+    static from(blob: Blob): Promise<BufferedBlob>;
+    /** Reconstructs a blob from this snapshot. */
+    toBlob(): Blob;
+}
+/** A serializable snapshot of a file and its buffered bytes. */
+export declare class BufferedFile {
+    readonly name: string;
+    readonly type: string;
+    readonly lastModified: number;
+    readonly bytes: Bytes;
+    /**
+     * Creates a buffered file snapshot.
+     *
+     * @param name - Original file name.
+     * @param type - Original media type.
+     * @param lastModified - Original modification timestamp.
+     * @param bytes - Buffered file contents.
+     */
+    constructor(name: string, type: string, lastModified: number, bytes: Bytes);
+    /**
+     * Drains a file into a serializable snapshot.
+     *
+     * @param file - File to buffer.
+     */
+    static from(file: File): Promise<BufferedFile>;
+    /** Reconstructs a file from this snapshot. */
+    toFile(): File;
+}
+export {};

package/dist/buffered.js

@@ -0,0 +1,156 @@
+/**
+ * Sync snapshots of async-bodied web types (`Request`, `Response`, `Blob`,
+ * `File`) after their bodies have been drained. msgpackr's extension `write`
+ * callback is synchronous, so anything with an async body must be pre-processed
+ * into one of these before packing.
+ */
+const METHODS_WITHOUT_BODY = new Set(["GET", "HEAD"]);
+/**
+ * Wraps an `ArrayBuffer` in the byte-array shape accepted by web body APIs.
+ *
+ * @param buffer - Buffer to expose as bytes.
+ */
+function toBytes(buffer) {
+    return new Uint8Array(buffer);
+}
+/** A serializable snapshot of a request and its buffered body. */
+export class BufferedRequest {
+    url;
+    method;
+    headers;
+    body;
+    /**
+     * Creates a buffered request snapshot.
+     *
+     * @param url - Original request URL.
+     * @param method - Original HTTP method.
+     * @param headers - Original headers as string entries.
+     * @param body - Buffered body, or `null` when the request has no body.
+     */
+    constructor(url, method, headers, body) {
+        this.url = url;
+        this.method = method;
+        this.headers = headers;
+        this.body = body;
+    }
+    /**
+     * Drains a request into a serializable snapshot.
+     *
+     * @param req - Request to buffer.
+     */
+    static async from(req) {
+        return new BufferedRequest(req.url, req.method, Object.fromEntries(req.headers), req.body !== null && !METHODS_WITHOUT_BODY.has(req.method)
+            ? toBytes(await req.arrayBuffer())
+            : null);
+    }
+    /** Reconstructs a request from this snapshot. */
+    toRequest() {
+        return new Request(this.url, {
+            method: this.method,
+            headers: new Headers(this.headers),
+            body: this.body !== null && !METHODS_WITHOUT_BODY.has(this.method)
+                ? this.body
+                : undefined,
+        });
+    }
+}
+/** A serializable snapshot of a response and its buffered body. */
+export class BufferedResponse {
+    status;
+    statusText;
+    headers;
+    body;
+    /**
+     * Creates a buffered response snapshot.
+     *
+     * @param status - Original response status code.
+     * @param statusText - Original response status text.
+     * @param headers - Original headers as string entries.
+     * @param body - Buffered body, or `null` when the response has no body.
+     */
+    constructor(status, statusText, headers, body) {
+        this.status = status;
+        this.statusText = statusText;
+        this.headers = headers;
+        this.body = body;
+    }
+    /**
+     * Drains a response into a serializable snapshot.
+     *
+     * @param res - Response to buffer.
+     */
+    static async from(res) {
+        return new BufferedResponse(res.status, res.statusText, Object.fromEntries(res.headers), res.body !== null ? toBytes(await res.arrayBuffer()) : null);
+    }
+    /** Reconstructs a response from this snapshot. */
+    toResponse() {
+        return new Response(this.body, {
+            status: this.status,
+            statusText: this.statusText,
+            headers: new Headers(this.headers),
+        });
+    }
+}
+/** A serializable snapshot of a blob and its buffered bytes. */
+export class BufferedBlob {
+    type;
+    bytes;
+    /**
+     * Creates a buffered blob snapshot.
+     *
+     * @param type - Original media type.
+     * @param bytes - Buffered blob contents.
+     */
+    constructor(type, bytes) {
+        this.type = type;
+        this.bytes = bytes;
+    }
+    /**
+     * Drains a blob into a serializable snapshot.
+     *
+     * @param blob - Blob to buffer.
+     */
+    static async from(blob) {
+        return new BufferedBlob(blob.type, toBytes(await blob.arrayBuffer()));
+    }
+    /** Reconstructs a blob from this snapshot. */
+    toBlob() {
+        return new Blob([this.bytes], { type: this.type });
+    }
+}
+/** A serializable snapshot of a file and its buffered bytes. */
+export class BufferedFile {
+    name;
+    type;
+    lastModified;
+    bytes;
+    /**
+     * Creates a buffered file snapshot.
+     *
+     * @param name - Original file name.
+     * @param type - Original media type.
+     * @param lastModified - Original modification timestamp.
+     * @param bytes - Buffered file contents.
+     */
+    constructor(name, type, lastModified, bytes) {
+        this.name = name;
+        this.type = type;
+        this.lastModified = lastModified;
+        this.bytes = bytes;
+    }
+    /**
+     * Drains a file into a serializable snapshot.
+     *
+     * @param file - File to buffer.
+     */
+    static async from(file) {
+        return new BufferedFile(file.name, file.type, file.lastModified, toBytes(await file.arrayBuffer()));
+    }
+    /** Reconstructs a file from this snapshot. */
+    toFile() {
+        return new File([this.bytes], this.name, {
+            type: this.type,
+            lastModified: this.lastModified,
+        });
+    }
+}

package/dist/extensions.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/extensions.js

@@ -0,0 +1,66 @@
+import { addExtension } from "msgpackr";
+import { BufferedBlob, BufferedFile, BufferedRequest, BufferedResponse, } from "./buffered.js";
+import { EXT_CODES } from "./type-codes.js";
+addExtension({
+    Class: BufferedRequest,
+    type: EXT_CODES.REQUEST,
+    write(instance) {
+        return [instance.url, instance.method, instance.headers, instance.body];
+    },
+    read([url, method, headers, body]) {
+        return new BufferedRequest(url, method, headers, body).toRequest();
+    },
+});
+addExtension({
+    Class: BufferedResponse,
+    type: EXT_CODES.RESPONSE,
+    write(instance) {
+        return [
+            instance.status,
+            instance.statusText,
+            instance.headers,
+            instance.body,
+        ];
+    },
+    read([status, statusText, headers, body]) {
+        return new BufferedResponse(status, statusText, headers, body).toResponse();
+    },
+});
+addExtension({
+    Class: BufferedBlob,
+    type: EXT_CODES.BLOB,
+    write(instance) {
+        return [instance.type, instance.bytes];
+    },
+    read([type, bytes]) {
+        return new BufferedBlob(type, bytes).toBlob();
+    },
+});
+addExtension({
+    Class: BufferedFile,
+    type: EXT_CODES.FILE,
+    write(instance) {
+        return [instance.name, instance.type, instance.lastModified, instance.bytes];
+    },
+    read([name, type, lastModified, bytes]) {
+        return new BufferedFile(name, type, lastModified, bytes).toFile();
+    },
+});
+addExtension({
+    Class: Headers,
+    type: EXT_CODES.HEADERS,
+    write: (h) => Object.fromEntries(h),
+    read: (entries) => new Headers(entries),
+});
+addExtension({
+    Class: URL,
+    type: EXT_CODES.URL,
+    write: (u) => u.href,
+    read: (href) => new URL(href),
+});
+addExtension({
+    Class: URLSearchParams,
+    type: EXT_CODES.URL_SEARCH_PARAMS,
+    write: (p) => [...p.entries()],
+    read: (entries) => new URLSearchParams(entries),
+});

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import z from "zod";
+export type { ObjectProducingSchema, ProducingSchema } from "./schema.js";
+/**
+ * Values accepted by the codec encoder, including recursively nested containers
+ * and registered web-platform extension types.
+ */
+export type Encodable = null | undefined | void | boolean | number | bigint | string | Uint8Array | Uint8ClampedArray | Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | Float32Array | Float64Array | BigUint64Array | BigInt64Array | Encodable[] | readonly Encodable[] | {
+    readonly [key: string]: Encodable;
+} | Map<Encodable, Encodable> | Set<Encodable> | Date | RegExp | ArrayBuffer | DataView | Request | Response | Blob | File | Headers | URL | URLSearchParams;
+/**
+ * Checks whether an unknown value fits the codec's supported input surface.
+ *
+ * @param value - Value to inspect.
+ */
+export declare function isEncodable(value: unknown): value is Encodable;
+/** Zod schema for values accepted by the codec encoder. */
+export declare const encodableSchema: z.ZodCustom<Encodable, Encodable>;
+/**
+ * Serializes a value after checking it against the codec's supported input
+ * surface.
+ *
+ * Pre-walks the value to buffer any async-bodied values (`Request`, `Response`)
+ * before handing off to the synchronous packer.
+ *
+ * @param value - Value to validate and serialize.
+ * @throws {TypeError} When the value is outside the supported input surface.
+ */
+export declare function encode(value: unknown): Promise<Uint8Array>;
+/**
+ * Deserializes msgpack bytes.
+ *
+ * Currently synchronous under the hood, but typed as async to leave room for
+ * future concerns that need await (e.g. resolving blob refs from external
+ * storage, streaming decodes).
+ *
+ * Returns the codec's supported value surface. Callers should still validate
+ * the domain-specific shape where they know the expected type.
+ *
+ * @param bytes - Msgpack bytes to deserialize.
+ * @throws {TypeError} When the decoded payload is outside the supported
+ *   surface.
+ */
+export declare function decode(bytes: Uint8Array): Promise<Encodable>;

package/dist/index.js

@@ -0,0 +1,112 @@
+import z from "zod";
+import { isPlainObject } from "./lib/utils.js";
+import { packr } from "./packr.js";
+import { bufferAsyncValues } from "./walk.js";
+/**
+ * Asserts that a value belongs to the codec's supported input surface.
+ *
+ * @param value - Value to validate.
+ * @throws {TypeError} When the value cannot be encoded.
+ */
+function assertEncodable(value) {
+    if (!isEncodable(value)) {
+        throw new TypeError(`Value is not encodable: ${Object.prototype.toString.call(value)}`);
+    }
+}
+/**
+ * Checks whether an unknown value fits the codec's supported input surface.
+ *
+ * @param value - Value to inspect.
+ */
+export function isEncodable(value) {
+    const activePath = new WeakSet();
+    /**
+     * Validates one value while tracking the active traversal path for cycles.
+     *
+     * @param value - Value at the current traversal position.
+     */
+    function visit(value) {
+        if (value == null)
+            return true;
+        switch (typeof value) {
+            case "boolean":
+            case "bigint":
+            case "number":
+            case "string":
+                return true;
+            case "function":
+            case "symbol":
+                return false;
+            case "object":
+                break;
+            default:
+                return false;
+        }
+        if (value instanceof Date ||
+            value instanceof RegExp ||
+            value instanceof ArrayBuffer ||
+            ArrayBuffer.isView(value) ||
+            value instanceof Request ||
+            value instanceof Response ||
+            value instanceof Blob ||
+            value instanceof File ||
+            value instanceof Headers ||
+            value instanceof URL ||
+            value instanceof URLSearchParams) {
+            return true;
+        }
+        if (activePath.has(value))
+            return false;
+        activePath.add(value);
+        try {
+            return Array.isArray(value)
+                ? value.every(visit)
+                : value instanceof Map
+                    ? [...value].every(([key, item]) => visit(key) && visit(item))
+                    : value instanceof Set
+                        ? [...value].every(visit)
+                        : isPlainObject(value) && Object.values(value).every(visit);
+        }
+        finally {
+            activePath.delete(value);
+        }
+    }
+    return visit(value);
+}
+/** Zod schema for values accepted by the codec encoder. */
+export const encodableSchema = z.custom(isEncodable, {
+    message: "Value is not encodable",
+});
+/**
+ * Serializes a value after checking it against the codec's supported input
+ * surface.
+ *
+ * Pre-walks the value to buffer any async-bodied values (`Request`, `Response`)
+ * before handing off to the synchronous packer.
+ *
+ * @param value - Value to validate and serialize.
+ * @throws {TypeError} When the value is outside the supported input surface.
+ */
+export async function encode(value) {
+    assertEncodable(value);
+    return packr.pack(await bufferAsyncValues(value));
+}
+/**
+ * Deserializes msgpack bytes.
+ *
+ * Currently synchronous under the hood, but typed as async to leave room for
+ * future concerns that need await (e.g. resolving blob refs from external
+ * storage, streaming decodes).
+ *
+ * Returns the codec's supported value surface. Callers should still validate
+ * the domain-specific shape where they know the expected type.
+ *
+ * @param bytes - Msgpack bytes to deserialize.
+ * @throws {TypeError} When the decoded payload is outside the supported
+ *   surface.
+ */
+export async function decode(bytes) {
+    const value = packr.unpack(bytes);
+    assertEncodable(value);
+    return value;
+}

package/dist/lib/utils.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks whether an object has the standard object prototype or no prototype.
+ *
+ * @param value - Object to inspect.
+ */
+export declare function isPlainObject(value: object): value is Record<string, unknown>;

package/dist/lib/utils.js

@@ -0,0 +1,9 @@
+/**
+ * Checks whether an object has the standard object prototype or no prototype.
+ *
+ * @param value - Object to inspect.
+ */
+export function isPlainObject(value) {
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}

package/dist/packr.d.ts

@@ -0,0 +1,10 @@
+import { Packr } from "msgpackr";
+import "./extensions.js";
+/**
+ * Single configured `Packr` instance used for all encode/decode in the runtime.
+ *
+ * Extensions are registered globally via `addExtension` (see `./extensions`),
+ * so any `Packr` instance picks them up — but using one shared instance keeps
+ * option configuration consistent.
+ */
+export declare const packr: Packr;

package/dist/packr.js

@@ -0,0 +1,17 @@
+import { Packr } from "msgpackr";
+import "./extensions.js";
+/**
+ * Single configured `Packr` instance used for all encode/decode in the runtime.
+ *
+ * Extensions are registered globally via `addExtension` (see `./extensions`),
+ * so any `Packr` instance picks them up — but using one shared instance keeps
+ * option configuration consistent.
+ */
+export const packr = new Packr({
+    useRecords: true,
+    mapsAsObjects: false,
+    moreTypes: true,
+    int64AsType: "bigint",
+    useBigIntExtension: true,
+    encodeUndefinedAsNil: false,
+});

package/dist/schema.d.ts

@@ -0,0 +1,5 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+/** Standard Schema whose validated output is assignable to the given type. */
+export type ProducingSchema<TOutput> = StandardSchemaV1<any, TOutput>;
+/** Standard Schema whose validated output is a string-keyed object. */
+export type ObjectProducingSchema<TValue> = ProducingSchema<Record<string, TValue>>;

package/dist/schema.js

@@ -0,0 +1 @@
+export {};

package/dist/type-codes.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Stable msgpack extension type codes for built-in runtime value types.
+ *
+ * These numbers are part of the wire format. Changing an existing code is a
+ * breaking change that would invalidate all previously stored outputs. Treat
+ * this file as append-only.
+ *
+ * Msgpackr reserves negative codes for MessagePack itself and 101-127 for its
+ * own use. Codes 1-100 are available to built-in application values.
+ */
+export declare const EXT_CODES: {
+    readonly REQUEST: 1;
+    readonly RESPONSE: 2;
+    readonly BLOB: 3;
+    readonly FILE: 4;
+    readonly HEADERS: 5;
+    readonly URL: 6;
+    readonly URL_SEARCH_PARAMS: 7;
+};

package/dist/type-codes.js

@@ -0,0 +1,19 @@
+/**
+ * Stable msgpack extension type codes for built-in runtime value types.
+ *
+ * These numbers are part of the wire format. Changing an existing code is a
+ * breaking change that would invalidate all previously stored outputs. Treat
+ * this file as append-only.
+ *
+ * Msgpackr reserves negative codes for MessagePack itself and 101-127 for its
+ * own use. Codes 1-100 are available to built-in application values.
+ */
+export const EXT_CODES = {
+    REQUEST: 1,
+    RESPONSE: 2,
+    BLOB: 3,
+    FILE: 4,
+    HEADERS: 5,
+    URL: 6,
+    URL_SEARCH_PARAMS: 7,
+};

package/dist/walk.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Walks a value tree and replaces anything with an async body (`Request`,
+ * `Response`, `Blob`, `File`) with a sync-buffered snapshot, so the result can
+ * be handed to a synchronous encoder.
+ *
+ * Recurses through plain objects, arrays, `Map`s, and `Set`s. Leaves
+ * primitives, typed arrays, and sync class instances (`Headers`, `URL`, etc.)
+ * alone — those either have no async surface or msgpackr handles them natively
+ * via registered extensions at pack time.
+ *
+ * Dedupes by reference within a single call so that a tree sharing the same
+ * `Request`/`Response`/`Blob`/`File` in multiple places doesn't trigger "body
+ * already used".
+ *
+ * Does not detect cycles. Automation outputs are expected to be tree-shaped.
+ *
+ * @param value - Value tree to prepare for synchronous encoding.
+ */
+export declare function bufferAsyncValues(value: unknown): Promise<unknown>;