Interface PayloadCodec

Synchronous codec for encoding/decoding serialized payload data.

Register a PayloadCodec to transparently transform all serialized object values (/s{json}) before they are stored and after they are read. Common use cases: encryption at rest, compression, or custom binary encoding.

How It Works

The serializer stores JavaScript objects as /s{json}. When a codec is registered, objects are instead stored as /b{encoded}:

Write: value → JSON.stringify → codec.encode(json) → "/b{encoded}"
Read:  "/b{encoded}" → codec.decode(encoded) → JSON.parse → value
       "/s{json}" → JSON.parse → value  (backward compatible)
Copy

Constraints

• Synchronous — encode and decode must be synchronous. Use Node.js crypto (e.g., createCipheriv) or zlib (e.g., deflateSync) for sync operations.
• String-safe — encode output must be a valid UTF-8 string (Postgres TEXT column). Use base64 encoding for binary output.
• Deterministic decode — decode(encode(x)) must equal x.

Scope

The codec applies to all data flowing through the serializer's package/unpackage path — job state, activity inputs/outputs, timeline markers, and workflow metadata. It does not apply to search(), entity(), or enrich() data, which bypass the serializer.

Example: AES-256-GCM Encryption

import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';
import { PayloadCodec } from '@hotmeshio/hotmesh';

const key = randomBytes(32);

const codec: PayloadCodec = {
  encode(json: string): string {
    const iv = randomBytes(12);
    const cipher = createCipheriv('aes-256-gcm', key, iv);
    const enc = Buffer.concat([cipher.update(json, 'utf8'), cipher.final()]);
    const tag = cipher.getAuthTag();
    return Buffer.concat([iv, tag, enc]).toString('base64');
  },
  decode(encoded: string): string {
    const buf = Buffer.from(encoded, 'base64');
    const iv = buf.subarray(0, 12);
    const tag = buf.subarray(12, 28);
    const data = buf.subarray(28);
    const decipher = createDecipheriv('aes-256-gcm', key, iv);
    decipher.setAuthTag(tag);
    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
  },
};

// Register globally — applies to all HotMesh and Durable instances
HotMesh.registerCodec(codec);
Copy