@cellaflow/sdk 0.7.0

package/src/cellaflow/v1/service_pb.ts

@@ -0,0 +1,323 @@
+// @generated by protoc-gen-es v1.10.1 with parameter "target=ts,import_extension=.js"
+// @generated from file cellaflow/v1/service.proto (package cellaflow.v1, syntax proto3)
+/* eslint-disable */
+// @ts-nocheck
+
+import type { BinaryReadOptions, FieldList, JsonReadOptions, JsonValue, PartialMessage, PlainMessage } from "@bufbuild/protobuf";
+import { Message, proto3, protoInt64 } from "@bufbuild/protobuf";
+import { StepResult } from "./common_pb.js";
+import { IdempotencyCommitStatus } from "./idempotency_pb.js";
+
+/**
+ * @generated from message cellaflow.v1.StartSessionRequest
+ */
+export class StartSessionRequest extends Message<StartSessionRequest> {
+  /**
+   * @generated from field: string workflow_id = 1;
+   */
+  workflowId = "";
+
+  /**
+   * @generated from field: string version = 2;
+   */
+  version = "";
+
+  /**
+   * Optional client-proposed session identifier.
+   *
+   * @generated from field: optional string session_id = 3;
+   */
+  sessionId?: string;
+
+  constructor(data?: PartialMessage<StartSessionRequest>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.StartSessionRequest";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "workflow_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "version", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 3, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): StartSessionRequest {
+    return new StartSessionRequest().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): StartSessionRequest {
+    return new StartSessionRequest().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): StartSessionRequest {
+    return new StartSessionRequest().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: StartSessionRequest | PlainMessage<StartSessionRequest> | undefined, b: StartSessionRequest | PlainMessage<StartSessionRequest> | undefined): boolean {
+    return proto3.util.equals(StartSessionRequest, a, b);
+  }
+}
+
+/**
+ * @generated from message cellaflow.v1.StartSessionResponse
+ */
+export class StartSessionResponse extends Message<StartSessionResponse> {
+  /**
+   * @generated from field: string session_id = 1;
+   */
+  sessionId = "";
+
+  /**
+   * @generated from field: string version = 2;
+   */
+  version = "";
+
+  /**
+   * @generated from field: bool is_recovered = 3;
+   */
+  isRecovered = false;
+
+  constructor(data?: PartialMessage<StartSessionResponse>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.StartSessionResponse";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "version", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 3, name: "is_recovered", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): StartSessionResponse {
+    return new StartSessionResponse().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): StartSessionResponse {
+    return new StartSessionResponse().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): StartSessionResponse {
+    return new StartSessionResponse().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: StartSessionResponse | PlainMessage<StartSessionResponse> | undefined, b: StartSessionResponse | PlainMessage<StartSessionResponse> | undefined): boolean {
+    return proto3.util.equals(StartSessionResponse, a, b);
+  }
+}
+
+/**
+ * @generated from message cellaflow.v1.CommitStepRequest
+ */
+export class CommitStepRequest extends Message<CommitStepRequest> {
+  /**
+   * @generated from field: string session_id = 1;
+   */
+  sessionId = "";
+
+  /**
+   * @generated from field: cellaflow.v1.StepResult step_result = 2;
+   */
+  stepResult?: StepResult;
+
+  /**
+   * Idempotency lease validation fields
+   *
+   * @generated from field: optional string idempotency_key = 10;
+   */
+  idempotencyKey?: string;
+
+  /**
+   * Required whenever idempotency_key is set
+   *
+   * @generated from field: optional uint64 idempotency_fencing_token = 11;
+   */
+  idempotencyFencingToken?: bigint;
+
+  constructor(data?: PartialMessage<CommitStepRequest>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.CommitStepRequest";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "step_result", kind: "message", T: StepResult },
+    { no: 10, name: "idempotency_key", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
+    { no: 11, name: "idempotency_fencing_token", kind: "scalar", T: 4 /* ScalarType.UINT64 */, opt: true },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): CommitStepRequest {
+    return new CommitStepRequest().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): CommitStepRequest {
+    return new CommitStepRequest().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): CommitStepRequest {
+    return new CommitStepRequest().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: CommitStepRequest | PlainMessage<CommitStepRequest> | undefined, b: CommitStepRequest | PlainMessage<CommitStepRequest> | undefined): boolean {
+    return proto3.util.equals(CommitStepRequest, a, b);
+  }
+}
+
+/**
+ * @generated from message cellaflow.v1.CommitStepResponse
+ */
+export class CommitStepResponse extends Message<CommitStepResponse> {
+  /**
+   * @generated from field: string session_id = 1;
+   */
+  sessionId = "";
+
+  /**
+   * @generated from field: uint64 next_sequence = 2;
+   */
+  nextSequence = protoInt64.zero;
+
+  /**
+   * @generated from field: optional cellaflow.v1.IdempotencyCommitStatus idempotency_status = 5;
+   */
+  idempotencyStatus?: IdempotencyCommitStatus;
+
+  constructor(data?: PartialMessage<CommitStepResponse>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.CommitStepResponse";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "next_sequence", kind: "scalar", T: 4 /* ScalarType.UINT64 */ },
+    { no: 5, name: "idempotency_status", kind: "enum", T: proto3.getEnumType(IdempotencyCommitStatus), opt: true },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): CommitStepResponse {
+    return new CommitStepResponse().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): CommitStepResponse {
+    return new CommitStepResponse().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): CommitStepResponse {
+    return new CommitStepResponse().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: CommitStepResponse | PlainMessage<CommitStepResponse> | undefined, b: CommitStepResponse | PlainMessage<CommitStepResponse> | undefined): boolean {
+    return proto3.util.equals(CommitStepResponse, a, b);
+  }
+}
+
+/**
+ * @generated from message cellaflow.v1.GetGraphRequest
+ */
+export class GetGraphRequest extends Message<GetGraphRequest> {
+  /**
+   * @generated from field: string session_id = 1;
+   */
+  sessionId = "";
+
+  /**
+   * Maximum number of items to retrieve in a single page.
+   * Enforced limits: Default = 100, Max = 1000.
+   *
+   * @generated from field: optional uint32 limit = 2;
+   */
+  limit?: number;
+
+  /**
+   * Cursor for pagination token.
+   *
+   * @generated from field: optional string cursor = 3;
+   */
+  cursor?: string;
+
+  constructor(data?: PartialMessage<GetGraphRequest>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.GetGraphRequest";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "limit", kind: "scalar", T: 13 /* ScalarType.UINT32 */, opt: true },
+    { no: 3, name: "cursor", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): GetGraphRequest {
+    return new GetGraphRequest().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): GetGraphRequest {
+    return new GetGraphRequest().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): GetGraphRequest {
+    return new GetGraphRequest().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: GetGraphRequest | PlainMessage<GetGraphRequest> | undefined, b: GetGraphRequest | PlainMessage<GetGraphRequest> | undefined): boolean {
+    return proto3.util.equals(GetGraphRequest, a, b);
+  }
+}
+
+/**
+ * @generated from message cellaflow.v1.GetGraphResponse
+ */
+export class GetGraphResponse extends Message<GetGraphResponse> {
+  /**
+   * @generated from field: string session_id = 1;
+   */
+  sessionId = "";
+
+  /**
+   * @generated from field: repeated cellaflow.v1.StepResult steps = 2;
+   */
+  steps: StepResult[] = [];
+
+  /**
+   * Token for fetching the next page, or empty if there are no more pages.
+   *
+   * @generated from field: optional string next_cursor = 3;
+   */
+  nextCursor?: string;
+
+  constructor(data?: PartialMessage<GetGraphResponse>) {
+    super();
+    proto3.util.initPartial(data, this);
+  }
+
+  static readonly runtime: typeof proto3 = proto3;
+  static readonly typeName = "cellaflow.v1.GetGraphResponse";
+  static readonly fields: FieldList = proto3.util.newFieldList(() => [
+    { no: 1, name: "session_id", kind: "scalar", T: 9 /* ScalarType.STRING */ },
+    { no: 2, name: "steps", kind: "message", T: StepResult, repeated: true },
+    { no: 3, name: "next_cursor", kind: "scalar", T: 9 /* ScalarType.STRING */, opt: true },
+  ]);
+
+  static fromBinary(bytes: Uint8Array, options?: Partial<BinaryReadOptions>): GetGraphResponse {
+    return new GetGraphResponse().fromBinary(bytes, options);
+  }
+
+  static fromJson(jsonValue: JsonValue, options?: Partial<JsonReadOptions>): GetGraphResponse {
+    return new GetGraphResponse().fromJson(jsonValue, options);
+  }
+
+  static fromJsonString(jsonString: string, options?: Partial<JsonReadOptions>): GetGraphResponse {
+    return new GetGraphResponse().fromJsonString(jsonString, options);
+  }
+
+  static equals(a: GetGraphResponse | PlainMessage<GetGraphResponse> | undefined, b: GetGraphResponse | PlainMessage<GetGraphResponse> | undefined): boolean {
+    return proto3.util.equals(GetGraphResponse, a, b);
+  }
+}
+

package/src/client.ts

@@ -0,0 +1,277 @@
+import {
+  createPromiseClient,
+  PromiseClient,
+  Transport,
+} from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+import type { PartialMessage } from "@bufbuild/protobuf";
+import { WorkflowEngineService } from "./cellaflow/v1/service_connect.js";
+import type {
+  StartSessionResponse,
+  CommitStepResponse,
+} from "./cellaflow/v1/service_pb.js";
+import {
+  StartSessionRequest,
+  CommitStepRequest,
+  GetGraphRequest,
+} from "./cellaflow/v1/service_pb.js";
+import { StepStatus } from "./cellaflow/v1/common_pb.js";
+import type {
+  CheckCacheResponse,
+  RenewLeaseResponse,
+  ReleaseLeaseResponse,
+} from "./cellaflow/v1/idempotency_pb.js";
+import {
+  CheckCacheRequest,
+  RenewLeaseRequest,
+  ReleaseLeaseRequest,
+} from "./cellaflow/v1/idempotency_pb.js";
+import { serialize, deserialize } from "./serialization.js";
+
+export interface CellaflowClientOptions {
+  target?: string;
+  secure?: boolean;
+}
+
+export class CellaflowClient {
+  /**
+   * gRPC Client for the Cellaflow Engine (Connect-ES transport).
+   * Handles communication with the engine and strictly uses MessagePack
+   * for state payloads.
+   */
+  private client: PromiseClient<typeof WorkflowEngineService>;
+
+  constructor(options: CellaflowClientOptions = {}) {
+    const { target = "localhost:50051", secure = false } = options;
+
+    // Use http/https based on the secure flag
+    const baseUrl = secure ? `https://${target}` : `http://${target}`;
+
+    const transport: Transport = createGrpcTransport({
+      baseUrl,
+      httpVersion: "2",
+    });
+
+    this.client = createPromiseClient(WorkflowEngineService, transport);
+  }
+
+  /**
+   * Starts a new workflow execution session.
+   *
+   * @param workflowId - The workflow definition ID.
+   * @param version - The workflow version string.
+   * @param sessionId - Optional client-proposed session ID. When provided, the
+   *   engine performs a transactional check-and-insert to prevent concurrent
+   *   race conditions. Omit to let the engine assign one.
+   */
+  async startSession(
+    workflowId: string,
+    version: string,
+    sessionId?: string
+  ): Promise<StartSessionResponse> {
+    const req: PartialMessage<StartSessionRequest> = { workflowId, version };
+    // Only set sessionId when truthy — matches Python's `if session_id:` guard.
+    // Sending an empty string may trigger the engine's custom-ID validation path.
+    if (sessionId) {
+      req.sessionId = sessionId;
+    }
+    return await this.client.startSession(req);
+  }
+
+  /**
+   * Commits a completed step result to the session graph.
+   *
+   * @param sessionId - The session to commit to.
+   * @param sequence - The step sequence number (1-based).
+   * @param name - Human-readable step name.
+   * @param status - The step outcome status.
+   * @param outputPayload - Arbitrary step output. Serialized as MessagePack.
+   * @param idempotencyKey - Optional idempotency lease key.
+   * @param idempotencyFencingToken - Required when `idempotencyKey` is set.
+   */
+  async commitStep(
+    sessionId: string,
+    sequence: number,
+    name: string,
+    status: StepStatus,
+    outputPayload: Record<string, any>,
+    idempotencyKey?: string,
+    idempotencyFencingToken?: number
+  ): Promise<CommitStepResponse> {
+    // Strictly serialize object to MessagePack
+    const serializedState = serialize(outputPayload);
+
+    const req: PartialMessage<CommitStepRequest> = {
+      sessionId,
+      stepResult: {
+        sequence: BigInt(sequence),
+        name,
+        status,
+        outputPayload: Buffer.from(serializedState) as unknown as Uint8Array<ArrayBuffer>,
+      },
+    };
+
+    if (idempotencyKey !== undefined) {
+      req.idempotencyKey = idempotencyKey;
+      if (idempotencyFencingToken === undefined) {
+        throw new Error(
+          "idempotencyFencingToken required if idempotencyKey is set"
+        );
+      }
+      req.idempotencyFencingToken = BigInt(idempotencyFencingToken);
+    }
+
+    return await this.client.commitStep(req);
+  }
+
+  /**
+   * Returns a paginated list of committed step results for a session.
+   *
+   * @returns A tuple of (step results, next_cursor). `next_cursor` is
+   *   `undefined` when there are no more pages. Each step result's
+   *   `outputPayload` is fully deserialized from MessagePack.
+   */
+  async getGraph(
+    sessionId: string,
+    limit?: number,
+    cursor?: string
+  ): Promise<[Record<string, any>[], string | undefined]> {
+    const req: PartialMessage<GetGraphRequest> = { sessionId };
+    if (limit !== undefined) {
+      req.limit = limit;
+    }
+    if (cursor !== undefined) {
+      req.cursor = cursor;
+    }
+
+    const resp = await this.client.getGraph(req);
+
+    const results = resp.steps.map((step) => ({
+      sequence: step.sequence,
+      name: step.name,
+      status: step.status,
+      // Guard against empty payload (default Uint8Array(0)) to prevent
+      // msgpack from throwing on an empty buffer.
+      outputPayload:
+        step.outputPayload.length > 0 ? deserialize(step.outputPayload) : {},
+      idempotencyKey: step.idempotencyKey,
+    }));
+
+    const nextCursor = resp.nextCursor ? resp.nextCursor : undefined;
+    return [results, nextCursor];
+  }
+
+  /**
+   * Arbitrates the idempotency lease for `idempotencyKey`.
+   *
+   * Supplying `sessionId` also asks the engine for the session's committed
+   * position, returned as `currentSequence` on every status. The idempotency
+   * key is opaque to the engine, so the session cannot be inferred from it —
+   * without this the engine has nothing to answer from.
+   *
+   * Supplying `sequence` — the position this caller intends to write to —
+   * additionally lets the engine refuse a lease that would authorise a side
+   * effect at an already-committed position, instead of rejecting the commit
+   * afterwards once the side effect has happened. The engine raises
+   * `FAILED_PRECONDITION` when refused. Both fields are optional on the wire;
+   * omitting `sequence` keeps the position unguarded.
+   */
+  async checkIdempotencyCache(
+    agentId: string,
+    idempotencyKey: string,
+    waitTimeoutMs?: number,
+    leaseTtlMs?: number,
+    sessionId?: string,
+    sequence?: number
+  ): Promise<CheckCacheResponse> {
+    const req: PartialMessage<CheckCacheRequest> = { agentId, idempotencyKey };
+    // These proto fields are uint64 → bigint; convert from the JS number API.
+    if (waitTimeoutMs !== undefined) {
+      req.waitTimeoutMs = BigInt(waitTimeoutMs);
+    }
+    if (leaseTtlMs !== undefined) {
+      req.leaseTtlMs = BigInt(leaseTtlMs);
+    }
+    if (sessionId !== undefined) {
+      req.sessionId = sessionId;
+    }
+    if (sequence !== undefined) {
+      req.sequence = BigInt(sequence);
+    }
+
+    return await this.client.checkIdempotencyCache(req);
+  }
+
+  /**
+   * Renews a held idempotency lease.
+   *
+   * @param timeoutSecs - Bounds the RPC in **seconds**. Heartbeat callers
+   *   MUST supply a positive value: without a deadline a black-holed
+   *   connection parks the calling thread indefinitely, and the shutdown
+   *   path that joins that thread parks with it.
+   */
+  async renewLease(
+    agentId: string,
+    idempotencyKey: string,
+    fencingToken: number,
+    extendMs: number,
+    timeoutSecs?: number
+  ): Promise<RenewLeaseResponse> {
+    const req: PartialMessage<RenewLeaseRequest> = {
+      agentId,
+      idempotencyKey,
+      fencingToken: BigInt(fencingToken),
+      extendMs: BigInt(extendMs),
+    };
+
+    return await this.client.renewLease(req, {
+      // Guard against timeout=0 which would cause an instant timeout.
+      timeoutMs:
+        timeoutSecs !== undefined && timeoutSecs > 0
+          ? timeoutSecs * 1000
+          : undefined,
+    });
+  }
+
+  /**
+   * Releases a held idempotency lease.
+   *
+   * @param timeoutSecs - Bounds the RPC in **seconds**.
+   */
+  async releaseLease(
+    agentId: string,
+    idempotencyKey: string,
+    fencingToken: number,
+    reason?: string,
+    timeoutSecs?: number
+  ): Promise<ReleaseLeaseResponse> {
+    const req: PartialMessage<ReleaseLeaseRequest> = {
+      agentId,
+      idempotencyKey,
+      fencingToken: BigInt(fencingToken),
+    };
+    if (reason !== undefined) {
+      req.reason = reason;
+    }
+
+    return await this.client.releaseLease(req, {
+      timeoutMs:
+        timeoutSecs !== undefined && timeoutSecs > 0
+          ? timeoutSecs * 1000
+          : undefined,
+    });
+  }
+
+  /**
+   * Provided for API compatibility with the Python client.
+   *
+   * Connect-ES v1 with `createGrpcTransport` does not expose an explicit
+   * close/shutdown method — HTTP/2 sessions are managed by Node.js and are
+   * cleaned up on process exit or when the client is garbage-collected.
+   * Long-lived server processes with many short-lived clients should let the
+   * garbage collector handle cleanup.
+   */
+  close(): void {
+    // No-op: Connect-ES v1 does not provide a transport.close() API.
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export * from "./client.js";
+export * from "./serialization.js";
+export * from "./cellaflow/v1/common_pb.js";
+export * from "./cellaflow/v1/idempotency_pb.js";
+// Note: internal_pb is intentionally NOT re-exported here. It contains
+// engine-internal types (CacheRecord, LeaseRecord, etc.) that are not part
+// of the public SDK surface.

package/src/serialization.ts

@@ -0,0 +1,53 @@
+import { encode, decode } from "@msgpack/msgpack";
+
+/**
+ * Serializes a JavaScript object to a MessagePack byte array.
+ * This ensures we never use JSON for state payloads, mitigating RCE risks.
+ *
+ * @throws {TypeError} If `data` is not a plain, non-null object.
+ */
+export function serialize(data: Record<string, any>): Uint8Array {
+  // Explicit null check first — `typeof null === "object"` would otherwise
+  // produce a misleading error message reporting "got object" instead of "got null".
+  if (data === null) {
+    throw new TypeError("Expected an object for serialization, got null");
+  }
+  if (typeof data !== "object" || Array.isArray(data)) {
+    throw new TypeError(
+      `Expected an object for serialization, got ${Array.isArray(data) ? "array" : typeof data}`
+    );
+  }
+  return encode(data);
+}
+
+/**
+ * Deserializes a MessagePack byte array back into a JavaScript object.
+ *
+ * Uses `ArrayBuffer.isView()` instead of `instanceof Uint8Array` to work
+ * correctly across JS realms (worker threads, vm contexts, etc.).
+ *
+ * @throws {TypeError} If `data` is not a Uint8Array / ArrayBufferView.
+ * @throws {TypeError} If the deserialized value is not a plain object.
+ */
+export function deserialize(data: Uint8Array): Record<string, any> {
+  // ArrayBuffer.isView is cross-realm safe; instanceof Uint8Array is not.
+  if (!ArrayBuffer.isView(data)) {
+    throw new TypeError(
+      `Expected Uint8Array for deserialization, got ${data === null ? "null" : typeof data}`
+    );
+  }
+
+  const unpacked = decode(data);
+
+  if (
+    typeof unpacked !== "object" ||
+    unpacked === null ||
+    Array.isArray(unpacked)
+  ) {
+    throw new TypeError(
+      `Deserialized data is not an object, got ${unpacked === null ? "null" : typeof unpacked}`
+    );
+  }
+
+  return unpacked as Record<string, any>;
+}