@plexspaces/sdk 0.1.1

package/dist/wire/tuplespace-proto-wire.d.ts

@@ -0,0 +1,8 @@
+/** Build WriteRequest protobuf bytes (field 1: tuple with repeated TupleField). */
+export declare function encodeWriteRequest(tuple: unknown[]): Uint8Array;
+/** Build ReadRequest protobuf bytes. */
+export declare function encodeReadRequest(pattern: unknown[], take: boolean, maxResults: number): Uint8Array;
+/** Parse ReadResponse bytes into list of tuple field arrays. */
+export declare function parseReadResponseTuples(data: Uint8Array): unknown[][];
+export declare function decodeReadResponseFirstTuple(raw: Uint8Array): unknown[] | null;
+export declare function decodeReadResponseAllTuples(raw: Uint8Array): unknown[][];

package/dist/wire/tuplespace-proto-wire.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+//
+// Protobuf wire for plexspaces.tuplespace.v1 WriteRequest / ReadRequest / ReadResponse
+// (subset for WASM host imports). Byte-compatible with:
+// - sdks/go/plexspaces/tuplespace_proto_wire.go
+// - crates/wasm-runtime simple_component_host (prost)
+import { appendLengthDelimited, appendVarint, concatBytes, readLengthDelimited, readVarint, skipField, } from './proto-wire-common.js';
+const MIN_INT64 = -9223372036854775808n;
+const MAX_INT64 = 9223372036854775807n;
+function encodeTupleField(v, allowWildcardStar) {
+    if (v === null || v === undefined) {
+        return appendVarint(new Uint8Array([0x38]), 1);
+    }
+    if (typeof v === 'string') {
+        if (allowWildcardStar && v === '*') {
+            return appendVarint(new Uint8Array([0x38]), 1);
+        }
+        const enc = new TextEncoder();
+        const bytes = new Uint8Array(enc.encode(v));
+        let inner = new Uint8Array([0x1a]);
+        inner = appendVarint(inner, bytes.length);
+        inner = concatBytes(inner, bytes);
+        return inner;
+    }
+    if (typeof v === 'boolean') {
+        const inner = new Uint8Array([0x20]);
+        return appendVarint(inner, v ? 1 : 0);
+    }
+    if (typeof v === 'number' && Number.isFinite(v)) {
+        const t = Math.trunc(v);
+        if (t === v && t >= Number(MIN_INT64) && t <= Number(MAX_INT64)) {
+            let inner = new Uint8Array([0x08]);
+            inner = appendVarintSigned(inner, t);
+            return inner;
+        }
+        let inner = new Uint8Array([0x11]);
+        const tmp = new Uint8Array(8);
+        new DataView(tmp.buffer).setFloat64(0, v, true);
+        inner = concatBytes(inner, tmp);
+        return inner;
+    }
+    throw new Error(`unsupported tuple field type ${typeof v}`);
+}
+function appendVarintSigned(buf, xIn) {
+    let x = BigInt(xIn);
+    if (x < 0n)
+        x = BigInt.asUintN(64, x);
+    const parts = [];
+    let n = x;
+    while (n >= 0x80n) {
+        parts.push(Number(n & 0xffn) | 0x80);
+        n >>= 7n;
+    }
+    parts.push(Number(n));
+    return concatBytes(buf, new Uint8Array(parts));
+}
+function encodeTupleFields(tuple, allowWildcardStar) {
+    let out = new Uint8Array(0);
+    for (const el of tuple) {
+        const tf = encodeTupleField(el, allowWildcardStar);
+        out = appendLengthDelimited(out, 2, tf);
+    }
+    return out;
+}
+/** Build WriteRequest protobuf bytes (field 1: tuple with repeated TupleField). */
+export function encodeWriteRequest(tuple) {
+    const tupleBody = encodeTupleFields(tuple, false);
+    return appendLengthDelimited(new Uint8Array(0), 1, tupleBody);
+}
+/** Build ReadRequest protobuf bytes. */
+export function encodeReadRequest(pattern, take, maxResults) {
+    const templateBody = encodeTupleFields(pattern, true);
+    let out = appendLengthDelimited(new Uint8Array(0), 1, templateBody);
+    if (take) {
+        out = concatBytes(out, new Uint8Array([0x20, 0x01]));
+    }
+    out = concatBytes(out, new Uint8Array([0x28]));
+    out = appendVarint(out, maxResults >>> 0);
+    return out;
+}
+function parseTupleFieldMsg(msg) {
+    let pos = 0;
+    let last = undefined;
+    while (pos < msg.length) {
+        const { value: tag, n: tn } = readVarint(msg, pos);
+        pos += tn;
+        const fn = Number(tag >> 3n);
+        const wt = Number(tag & 7n);
+        if (wt === 0) {
+            const { value: v, n: m } = readVarint(msg, pos);
+            pos += m;
+            if (fn === 1)
+                last = Number(v);
+            else if (fn === 4)
+                last = v !== 0n;
+            else if (fn === 6 || fn === 7)
+                last = null;
+        }
+        else if (wt === 1) {
+            if (pos + 8 > msg.length)
+                throw new Error('double underflow');
+            const view = new DataView(msg.buffer, msg.byteOffset + pos, 8);
+            const d = view.getFloat64(0, true);
+            pos += 8;
+            if (fn === 2)
+                last = d;
+        }
+        else if (wt === 2) {
+            const { slice: chunk, nextPos } = readLengthDelimited(msg, pos);
+            pos = nextPos;
+            if (fn === 3 || fn === 5) {
+                last = new TextDecoder('utf-8', { fatal: false }).decode(chunk);
+            }
+        }
+        else {
+            pos = skipField(msg, pos, wt);
+        }
+    }
+    return last;
+}
+function parseTupleMsg(msg) {
+    const fields = [];
+    let pos = 0;
+    while (pos < msg.length) {
+        const { value: tag, n: tn } = readVarint(msg, pos);
+        pos += tn;
+        const fn = Number(tag >> 3n);
+        const wt = Number(tag & 7n);
+        if (fn === 2 && wt === 2) {
+            const { slice: sub, nextPos } = readLengthDelimited(msg, pos);
+            pos = nextPos;
+            fields.push(parseTupleFieldMsg(sub));
+        }
+        else {
+            pos = skipField(msg, pos, wt);
+        }
+    }
+    return fields;
+}
+/** Parse ReadResponse bytes into list of tuple field arrays. */
+export function parseReadResponseTuples(data) {
+    const tuples = [];
+    let pos = 0;
+    while (pos < data.length) {
+        const { value: tag, n: tn } = readVarint(data, pos);
+        pos += tn;
+        const fn = Number(tag >> 3n);
+        const wt = Number(tag & 7n);
+        if (fn === 1 && wt === 2) {
+            const { slice, nextPos } = readLengthDelimited(data, pos);
+            pos = nextPos;
+            tuples.push(parseTupleMsg(slice));
+        }
+        else {
+            pos = skipField(data, pos, wt);
+        }
+    }
+    return tuples;
+}
+export function decodeReadResponseFirstTuple(raw) {
+    if (raw.length === 0)
+        return null;
+    try {
+        const tuples = parseReadResponseTuples(raw);
+        if (tuples.length === 0)
+            return null;
+        return tuples[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function decodeReadResponseAllTuples(raw) {
+    if (raw.length === 0)
+        return [];
+    try {
+        return parseReadResponseTuples(raw);
+    }
+    catch {
+        return [];
+    }
+}

package/dist/wit-payload.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Decode WIT `payload` (`list<u8>`) or a UTF-8 string for JSON/text handling in the guest.
+ *
+ * jco/wasmtime passes `list<u8>` as `Uint8Array`. Using `payload.trim` is wrong (undefined on
+ * TypedArray), which skips `JSON.parse` and drops `op` / `message_type` from the body when the
+ * host falls back to envelope `msgType` "call".
+ *
+ * Some embeddings surface other `ArrayBufferView` types; treat any view like `Uint8Array`.
+ *
+ * @param input - Raw config, message body, or state bytes from the component boundary
+ * @returns UTF-8 string (may be empty)
+ */
+export declare function decodeWitPayloadUtf8(input: string | Uint8Array | ArrayBuffer | ArrayBufferView): string;
+/**
+ * Encode a UTF-8 string as WIT `payload` (`list<u8>`) for guest exports.
+ *
+ * jco maps `list<u8>` to `Uint8Array` on the JavaScript side — not `string`. Returning a plain
+ * string from `handle` / `get-state` can lift as an empty success payload at the component ABI.
+ *
+ * @param text - JSON or other UTF-8 text to pass to the host
+ * @returns Bytes for the canonical ABI
+ */
+export declare function encodeWitPayloadUtf8(text: string): Uint8Array;

package/dist/wit-payload.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+//
+// Pure UTF-8 helpers for WIT `payload` (`list<u8>`) at the component boundary.
+// Kept separate from actor.ts so Node tests can import without `plexspaces:` virtual imports.
+/**
+ * Decode WIT `payload` (`list<u8>`) or a UTF-8 string for JSON/text handling in the guest.
+ *
+ * jco/wasmtime passes `list<u8>` as `Uint8Array`. Using `payload.trim` is wrong (undefined on
+ * TypedArray), which skips `JSON.parse` and drops `op` / `message_type` from the body when the
+ * host falls back to envelope `msgType` "call".
+ *
+ * Some embeddings surface other `ArrayBufferView` types; treat any view like `Uint8Array`.
+ *
+ * @param input - Raw config, message body, or state bytes from the component boundary
+ * @returns UTF-8 string (may be empty)
+ */
+export function decodeWitPayloadUtf8(input) {
+    if (typeof input === 'string') {
+        return input;
+    }
+    if (input instanceof ArrayBuffer) {
+        return new TextDecoder('utf-8', { fatal: false }).decode(new Uint8Array(input));
+    }
+    if (ArrayBuffer.isView(input)) {
+        const v = input;
+        return new TextDecoder('utf-8', { fatal: false }).decode(new Uint8Array(v.buffer, v.byteOffset, v.byteLength));
+    }
+    return '';
+}
+/**
+ * Encode a UTF-8 string as WIT `payload` (`list<u8>`) for guest exports.
+ *
+ * jco maps `list<u8>` to `Uint8Array` on the JavaScript side — not `string`. Returning a plain
+ * string from `handle` / `get-state` can lift as an empty success payload at the component ABI.
+ *
+ * @param text - JSON or other UTF-8 text to pass to the host
+ * @returns Bytes for the canonical ABI
+ */
+export function encodeWitPayloadUtf8(text) {
+    return new TextEncoder().encode(text);
+}

package/dist/workflow.d.ts

@@ -0,0 +1,14 @@
+import type { RetryConfig } from './proto.js';
+export type { RetryConfig } from './proto.js';
+/** Default retry config: single attempt (no retries). Aligns with proto when fields unset. */
+export declare function defaultRetryConfig(): RetryConfig;
+/**
+ * Execute a step with retries. Uses RetryConfig. When config is omitted or max_attempts unset, 3 attempts.
+ * When config.max_attempts is 0 or 1, single attempt. Aligns with Rust run(name, retry, op) and proto RetryConfig.
+ *
+ * @param fn - Function to execute. Must return a value or throw.
+ * @param config - Optional RetryConfig (omitted => 3 attempts; max_attempts: 1 => one attempt).
+ * @returns The result of fn() after a successful attempt.
+ * @throws The last error if all attempts fail.
+ */
+export declare function withRetry<T>(fn: () => T, config?: RetryConfig): T;

package/dist/workflow.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2025 PlexSpaces Contributors
+//
+// Workflow retry helpers aligned with proto RetryConfig (plexspaces.workflow.v1.RetryConfig).
+// Single run-with-config semantics: use defaultRetryConfig() for one attempt; pass config with
+// max_attempts > 1 for retries.
+/** Default retry config: single attempt (no retries). Aligns with proto when fields unset. */
+export function defaultRetryConfig() {
+    return {
+        max_attempts: 1,
+        initial_interval_ms: 100,
+        backoff_rate: 2,
+        max_interval_ms: 30000,
+        retryable_errors: [],
+    };
+}
+/** Effective max attempts: 0 or unset means 1. */
+function effectiveMaxAttempts(c) {
+    const n = c.max_attempts ?? 0;
+    return n === 0 ? 1 : n;
+}
+/**
+ * Execute a step with retries. Uses RetryConfig. When config is omitted or max_attempts unset, 3 attempts.
+ * When config.max_attempts is 0 or 1, single attempt. Aligns with Rust run(name, retry, op) and proto RetryConfig.
+ *
+ * @param fn - Function to execute. Must return a value or throw.
+ * @param config - Optional RetryConfig (omitted => 3 attempts; max_attempts: 1 => one attempt).
+ * @returns The result of fn() after a successful attempt.
+ * @throws The last error if all attempts fail.
+ */
+export function withRetry(fn, config = {}) {
+    const fromConfig = config.max_attempts !== undefined ? effectiveMaxAttempts(config) : 0;
+    const maxAttempts = fromConfig > 0 ? fromConfig : 3;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            return fn();
+        }
+        catch (e) {
+            lastError = e;
+            if (attempt === maxAttempts) {
+                throw e;
+            }
+        }
+    }
+    throw lastError;
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@plexspaces/sdk",
+  "version": "0.1.1",
+  "description": "PlexSpaces TypeScript SDK - build actors with minimal boilerplate (inheritance-based)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run generate:types && tsc -p .",
+    "generate:types": "node scripts/generate-types.mjs",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@bytecodealliance/jco": "^1.17.0",
+    "typescript": "^5.0.0"
+  },
+  "license": "AGPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plexobject/plexspaces.git",
+    "directory": "sdks/typescript"
+  }
+}