@automate.ax/codec 0.1.3

package/dist/walk.js

@@ -0,0 +1,69 @@
+import { BufferedBlob, BufferedFile, BufferedRequest, BufferedResponse, } from "./buffered.js";
+import { isPlainObject } from "./lib/utils.js";
+/**
+ * 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 async function bufferAsyncValues(value) {
+    return walk(value, new WeakMap());
+}
+/**
+ * Walks a value while reusing in-flight work for repeated object references.
+ *
+ * @param value - Value at the current traversal position.
+ * @param cache - Buffered results keyed by source object identity.
+ */
+async function walk(value, cache) {
+    if (value === null || typeof value !== "object")
+        return value;
+    const cached = cache.get(value);
+    if (cached)
+        return cached;
+    const task = walkFresh(value, cache);
+    cache.set(value, task);
+    return task;
+}
+/**
+ * Buffers an object that does not yet have a cached traversal task.
+ *
+ * @param value - Object to inspect and buffer.
+ * @param cache - Buffered results keyed by source object identity.
+ */
+async function walkFresh(value, cache) {
+    if (value instanceof Request)
+        return BufferedRequest.from(value);
+    if (value instanceof Response)
+        return BufferedResponse.from(value);
+    // File extends Blob — must be checked first so we don't lose name/lastModified.
+    if (value instanceof File)
+        return BufferedFile.from(value);
+    if (value instanceof Blob)
+        return BufferedBlob.from(value);
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((v) => walk(v, cache)));
+    }
+    if (value instanceof Map) {
+        return new Map(await Promise.all([...value.entries()].map(async ([k, v]) => [await walk(k, cache), await walk(v, cache)])));
+    }
+    if (value instanceof Set) {
+        return new Set(await Promise.all([...value].map((v) => walk(v, cache))));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(await Promise.all(Object.entries(value).map(async ([k, v]) => [k, await walk(v, cache)])));
+    }
+    return value;
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@automate.ax/codec",
+  "version": "0.1.3",
+  "description": "Msgpack-based encoding helpers for Automate.ax runtime data.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zachsents/automate.ax.git",
+    "directory": "packages/codec"
+  },
+  "homepage": "https://automate.ax",
+  "bugs": {
+    "url": "https://github.com/zachsents/automate.ax/issues"
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "zshy": {
+    "exports": {
+      ".": "./src/index.ts",
+      "./*": "./src/*"
+    },
+    "cjs": false,
+    "conditions": {
+      "bun": "src"
+    }
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "bun": "./src/*",
+      "types": "./dist/*",
+      "default": "./dist/*"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --type-aware",
+    "lint:fix": "oxlint --type-aware --fix-suggestions",
+    "check": "bun run typecheck && bun run lint",
+    "test": "vitest run",
+    "build": "zshy",
+    "prepublishOnly": "bun run lint && bun run typecheck && bun run test && bun run build"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "devDependencies": {
+    "@internal/config": "0.0.0",
+    "@types/bun": "latest",
+    "vitest": "^4.1.9",
+    "zshy": "^0.7.2"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "msgpackr": "^1.11.9",
+    "zod": "^4.3.6"
+  }
+}

package/src/buffered.ts

@@ -0,0 +1,178 @@
+/**
+ * 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>
+
+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: ArrayBuffer): Bytes {
+  return new Uint8Array(buffer)
+}
+
+/** A serializable snapshot of a request and its buffered body. */
+export class BufferedRequest {
+  /**
+   * 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(
+    public readonly url: string,
+    public readonly method: string,
+    public readonly headers: Record<string, string>,
+    public readonly body: Bytes | null,
+  ) {}
+
+  /**
+   * Drains a request into a serializable snapshot.
+   *
+   * @param req - Request to buffer.
+   */
+  static async from(req: Request): Promise<BufferedRequest> {
+    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(): Request {
+    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 {
+  /**
+   * 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(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly headers: Record<string, string>,
+    public readonly body: Bytes | null,
+  ) {}
+
+  /**
+   * Drains a response into a serializable snapshot.
+   *
+   * @param res - Response to buffer.
+   */
+  static async from(res: Response): Promise<BufferedResponse> {
+    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(): Response {
+    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 {
+  /**
+   * Creates a buffered blob snapshot.
+   *
+   * @param type - Original media type.
+   * @param bytes - Buffered blob contents.
+   */
+  constructor(
+    public readonly type: string,
+    public readonly bytes: Bytes,
+  ) {}
+
+  /**
+   * Drains a blob into a serializable snapshot.
+   *
+   * @param blob - Blob to buffer.
+   */
+  static async from(blob: Blob): Promise<BufferedBlob> {
+    return new BufferedBlob(blob.type, toBytes(await blob.arrayBuffer()))
+  }
+
+  /** Reconstructs a blob from this snapshot. */
+  toBlob(): Blob {
+    return new Blob([this.bytes], { type: this.type })
+  }
+}
+
+/** A serializable snapshot of a file and its buffered bytes. */
+export class BufferedFile {
+  /**
+   * 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(
+    public readonly name: string,
+    public readonly type: string,
+    public readonly lastModified: number,
+    public readonly bytes: Bytes,
+  ) {}
+
+  /**
+   * Drains a file into a serializable snapshot.
+   *
+   * @param file - File to buffer.
+   */
+  static async from(file: File): Promise<BufferedFile> {
+    return new BufferedFile(
+      file.name,
+      file.type,
+      file.lastModified,
+      toBytes(await file.arrayBuffer()),
+    )
+  }
+
+  /** Reconstructs a file from this snapshot. */
+  toFile(): File {
+    return new File([this.bytes], this.name, {
+      type: this.type,
+      lastModified: this.lastModified,
+    })
+  }
+}

package/src/extensions.ts

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

package/src/index.ts

@@ -0,0 +1,169 @@
+import z from "zod"
+import { isPlainObject } from "./lib/utils"
+import { packr } from "./packr"
+import { bufferAsyncValues } from "./walk"
+
+export type { ObjectProducingSchema, ProducingSchema } from "./schema"
+
+/**
+ * Values accepted by the codec encoder, including recursively nested containers
+ * and registered web-platform extension types.
+ */
+export type Encodable =
+  // primitives
+  | null
+  | undefined
+  | void
+  | boolean
+  | number
+  | bigint
+  | string
+  // typed arrays
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int8Array
+  | Uint16Array
+  | Int16Array
+  | Uint32Array
+  | Int32Array
+  | Float32Array
+  | Float64Array
+  | BigUint64Array
+  | BigInt64Array
+  // other types
+  | Encodable[]
+  | readonly Encodable[]
+  | { readonly [key: string]: Encodable }
+  | Map<Encodable, Encodable>
+  | Set<Encodable>
+  | Date
+  | RegExp
+  | ArrayBuffer
+  | DataView
+  | Request
+  | Response
+  | Blob
+  | File
+  | Headers
+  | URL
+  | URLSearchParams
+
+/**
+ * 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: unknown): asserts value is Encodable {
+  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: unknown): value is Encodable {
+  const activePath = new WeakSet<object>()
+
+  /**
+   * Validates one value while tracking the active traversal path for cycles.
+   *
+   * @param value - Value at the current traversal position.
+   */
+  function visit(value: unknown): value is Encodable {
+    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<Encodable>(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: unknown): Promise<Uint8Array> {
+  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: Uint8Array): Promise<Encodable> {
+  const value = packr.unpack(bytes)
+  assertEncodable(value)
+  return value
+}

package/src/lib/utils.ts

@@ -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: object): value is Record<string, unknown> {
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}

package/src/packr.ts

@@ -0,0 +1,18 @@
+import { Packr } from "msgpackr"
+import "./extensions"
+
+/**
+ * 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/src/schema.ts

@@ -0,0 +1,13 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec"
+
+/** Standard Schema whose validated output is assignable to the given type. */
+export type ProducingSchema<TOutput> = StandardSchemaV1<
+  // oxlint-disable-next-line typescript/no-explicit-any -- schema input variance should not constrain output type
+  any,
+  TOutput
+>
+
+/** Standard Schema whose validated output is a string-keyed object. */
+export type ObjectProducingSchema<TValue> = ProducingSchema<
+  Record<string, TValue>
+>

package/src/type-codes.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 const EXT_CODES = {
+  REQUEST: 1,
+  RESPONSE: 2,
+  BLOB: 3,
+  FILE: 4,
+  HEADERS: 5,
+  URL: 6,
+  URL_SEARCH_PARAMS: 7,
+} as const