@plexspaces/sdk 0.1.1

package/README.md

@@ -0,0 +1,225 @@
+# PlexSpaces TypeScript SDK
+
+Build PlexSpaces actors with minimal boilerplate using **inheritance** (TypeScript analogue to the Python SDK’s decorators).
+
+## Installation
+
+From the repo (development):
+
+```bash
+cd sdks/typescript
+npm install
+npm run build
+```
+
+Proto-shaped SDK types live in **`src/proto.ts`** and keep canonical proto field names even when generated files are not present yet. When you run **`make proto`** or **`make proto-typescript`**, richer generated models can be added on top, but application code can already stay proto-first at the SDK boundary.
+
+The SDK now supports decorator-based authoring metadata in addition to the existing base classes:
+
+- `@actor`
+- `@gen_server_actor`
+- `@event_actor`
+- `@fsm_actor` / `@fsm_actor({ states: [...], initial: "..." })` — FSM actor with optional state list and initial state
+- `@workflow_actor`
+- `@run_handler`
+- `@signal_handler("name")`
+- `@query_handler("name")`
+- `@handler`
+
+These decorators align the TypeScript surface with the Rust and Python SDKs while keeping `PlexSpacesActor` and `WorkflowActor` as the runtime substrate.
+
+In an example or app, add a dependency:
+
+```json
+"dependencies": {
+  "@plexspaces/sdk": "file:../../../../sdks/typescript"
+}
+```
+
+## Tests
+
+From the repo root, **`make test`** runs **`npm test`** here (`node --test`). Locally: `cd sdks/typescript && npm test`.
+
+## Quick start
+
+### 1. Extend `PlexSpacesActor`
+
+Override `getDefaultState()` and add handlers as `on<Op>(payload)` methods. The base class wires WIT `init`, `handle`, `getState`, `setState` and dispatches by `payload.op`.
+
+```ts
+import { PlexSpacesActor } from "@plexspaces/sdk";
+
+interface MyState {
+  count: number;
+}
+
+export class CounterActor extends PlexSpacesActor<MyState> {
+  getDefaultState(): MyState {
+    return { count: 0 };
+  }
+
+  onIncrement(payload: Record<string, unknown>) {
+    const amount = Number(payload.amount ?? 1);
+    this.state.count += amount;
+    return { count: this.state.count };
+  }
+
+  onGet() {
+    return { count: this.state.count };
+  }
+}
+
+const instance = new CounterActor();
+export const actor = {
+  init: (c: string) => instance.init(c),
+  handle: (from: string, msg: string, payload: string) => instance.handle(from, msg, payload),
+  getState: () => instance.getState(),
+  setState: (s: string) => instance.setState(s),
+};
+```
+
+### 2. Build to WASM
+
+- Compile: `tsc`
+- Bundle (e.g. esbuild) your entry into a single ESM file that exports `actor`.
+- Build WASM: `jco componentize your-bundle.mjs --wit wit/plexspaces-actor -o actor.wasm --disable all`
+
+See [examples/typescript/apps/bank_account](../../examples/typescript/apps/bank_account) for a full example and E2E test.
+
+## Virtual Actors (Orleans-Style)
+
+Virtual actors are automatically activated on first message and deactivated after idle timeout. Configure via `app-config.toml`:
+
+```toml
+[[supervisor.children]]
+id = "my-actor"
+type = "worker"
+facets = [
+  { type = "virtual_actor", priority = 100, config = { idle_timeout = "5m", activation_strategy = "lazy" } }
+]
+```
+
+The TypeScript SDK works seamlessly with virtual actors - no code changes needed. The framework handles activation/deactivation automatically.
+
+## API
+
+- **`PlexSpacesActor<TState>`**  
+  Base class. `TState` is your state shape (plain object).
+
+- **`getDefaultState(): TState`**  
+  Override to return initial state.
+
+- **`onInit(config: Record<string, unknown>): void`**  
+  Optional. Called from `init()` with parsed config JSON.
+
+- **Handlers**  
+  Implement `on<Op>(payload)` for each message op (e.g. `onDeposit`, `onBalance`). The runtime calls `handle(from, msgType, payloadJson)` and the base class dispatches by `payload.op` (or `payload`) to `on` + capitalized op name. Return a JSON-serializable value; the base class serializes it (or `"ERROR:..."` on throw).
+
+- **`protected state: TState`**  
+  Current state; read/write in handlers.
+
+- **`protected json(obj), error(msg)`**  
+  Helpers for returning JSON or error strings.
+
+## WIT Interface
+
+The SDK targets the **plexspaces-actor** WIT world: `init`, `handle`, `get-state`, `set-state`. All data crosses the boundary as strings (JSON). See `wit/plexspaces-actor/world.wit`.
+
+### Host Functions
+
+The SDK uses WIT host functions for runtime capabilities. Host functions are provided by the PlexSpaces runtime when the WASM component is instantiated.
+
+**Virtual Import Pattern**: jco componentize uses virtual imports for WIT host interfaces. The SDK handles these internally - you don't need to import them directly.
+
+The SDK automatically handles logging via `host.log()` for error reporting and observability. In non-WASM environments (e.g., Node.js verification), host functions are undefined and logging gracefully degrades to no-op.
+
+**Available Host Functions** (from `plexspaces:actor/host@0.1.0`):
+- `log(level: string, message: string)` - Log a message (used internally by SDK)
+- `send(to: string, msgType: string, payloadJson: string)` - Send message to another actor
+- `now_ms()` - Get current timestamp in milliseconds
+- `kv_get(key: string)`, `kv_put(key: string, value: string)`, etc. - Key-value storage
+- **TupleSpace**: Prefer `host.ts` (list-in, list-out): `host.ts.write(tuple)`, `host.ts.take(pattern)` → tuple or null, `host.ts.readAll(pattern)` → tuple[]. Use `null` in patterns for wildcards. Low-level: `ts_write(tupleJson)`, `ts_take(patternJson)`, etc.
+- **Process groups**: `host.processGroups.broadcast(group, msgType, payload)` — `msgType` is used by the host for routing; payload can be data-only.
+- **Elastic pool**: `host.poolCheckout(poolName, timeoutMs)` → `{ actor_id, pool_name, checkout_id } | null`; `host.poolCheckin(poolName, actorId, checkoutId, healthy)`; `host.poolGetMetrics(poolName)` → metrics object or null. When the pool is not configured, checkout returns null; use process group broadcast as fallback. See [Parameter sweep (migrating_merlin)](../../examples/typescript/apps/migrating_merlin/README.md).
+- **Object Registry**: `host.registry.register(reg)`, `host.registry.lookup(id, type)`, `host.registry.lookupByAlias(alias)`, `host.registry.discover(opts)`, `host.registry.heartbeat(id, type)`. All wire encoding is proto-first (see below).
+- See `wit/plexspaces-actor/world.wit` for complete interface
+
+**Note**: The SDK uses `host.log()` internally for error logging. For custom logging in your actors, you can import and use host functions directly using the virtual import pattern (future enhancement: SDK may provide helper methods).
+
+### Tier 1 Ergonomics Helpers
+
+Convenience wrappers on the `host` singleton and `EventLog` class.
+
+```typescript
+import { host, EventLog } from "@plexspaces/sdk";
+
+// Process Groups — first member
+const routerId: string | null = host.processGroups.first("svc:llm_router");
+const routerIdStrict: string = host.processGroups.firstOrThrow("svc:llm_router");
+
+// KV JSON helpers
+interface Task { seq: number; kind: string; }
+host.kvPutJson("task:1", { seq: 1, kind: "summarize" });
+const task: Task | null = host.kvGetJson<Task>("task:1");
+
+// Metrics (errors swallowed)
+host.incrCounter("my-app", "requests_processed");
+host.incrCounters("my-app", { cacheHits: 5, cacheMisses: 2 });
+
+// EventLog — embed in actor state
+class MyActor extends PlexSpacesActor<{ auditLog: EventLog }> {
+  getDefaultState() { return { auditLog: new EventLog() }; }
+
+  onRecord(payload: unknown) {
+    const seq = this.state.auditLog.append(host, "audit:", payload);
+    return { seq };
+  }
+
+  onPoll(payload: { consumerId: string; limit?: number }) {
+    const [events, cursor] = this.state.auditLog.poll(
+      host, "audit:", payload.consumerId, payload.limit ?? 50
+    );
+    return { events, cursor };
+  }
+}
+```
+
+### Object Registry
+
+Service registration and discovery via the host registry surface. The SDK handles protobuf wire encoding automatically; the proto schema is `proto/plexspaces/v1/registry/object_registry.proto`.
+
+```typescript
+import { host, RegistryObjectType } from "@plexspaces/sdk";
+
+// Register this actor as a service
+host.registry.register({
+  objectId: actorId,
+  objectType: "actor",
+  objectCategory: "worker",
+  grpcAddress: "http://node:8080",
+  capabilities: ["persistent"],
+  labels: ["env=prod"],
+});
+
+// Lookup by object ID
+const reg = host.registry.lookup(actorId, RegistryObjectType.ACTOR);
+
+// Lookup by alias
+const reg2 = host.registry.lookupByAlias("my-service-alias");
+
+// Discover all actors of a type
+const regs = host.registry.discover({ objectType: RegistryObjectType.ACTOR });
+
+// Send heartbeat to refresh liveness
+host.registry.heartbeat(actorId, RegistryObjectType.ACTOR);
+```
+
+**Tenant isolation**: `tenant_id` is injected by the host from the deployment context (JWT for API deploys, or `tenant_id` in `app-config.toml` for file-copy deploys). Any `tenant_id` in the SDK call is silently overridden. `namespace` may be supplied; empty string falls back to the application's default namespace.
+
+### Type Generation
+
+WIT TypeScript types are generated automatically as part of the SDK build process (`npm run build`). These types are optional and only used internally by the SDK for type checking. Client code doesn't need to generate or import these types - the SDK abstracts all WIT details away.
+
+## License
+
+AGPL-3.0-or-later

package/dist/actor.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Base class for PlexSpaces actors (actor-world WIT: init, handle, get-state, set-state).
+ *
+ * Subclass and override:
+ * - getDefaultState(): initial state
+ * - onInit(config): optional, called from init() with parsed config
+ * - on<Op>(payload): handler for message op (e.g. onDeposit, onBalance).
+ *   Op is derived from payload.op or payload; method name is "on" + capitalized op.
+ *
+ * Example:
+ *   class BankAccountActor extends PlexSpacesActor<BankAccountState> {
+ *     getDefaultState() { return { account_id: '', balance: 0, transactions: [] }; }
+ *     onDeposit(p: { amount: number }) { ...; return { status: 'ok', balance: this.state.balance }; }
+ *     onBalance() { return { account: this.state.account_id, balance: this.state.balance }; }
+ *   }
+ */
+export declare abstract class PlexSpacesActor<TState extends object = Record<string, unknown>> {
+    protected state: TState;
+    private cachedStateJson;
+    constructor();
+    /** Return initial state. Override in subclass. */
+    abstract getDefaultState(): TState;
+    /** Optional: called from init() with parsed config. Override to apply config to state. */
+    protected onInit(_config: Record<string, unknown>): void;
+    /**
+     * WIT `init(config: payload) -> result<_, actor-error>`.
+     * Success: return (unit). Failure: throw (jco maps throws to `err` for function-return `result`).
+     */
+    init(configJson: string | Uint8Array | ArrayBuffer | ArrayBufferView): void;
+    /**
+     * WIT `handle(...) -> result<payload, actor-error>` (`payload` is `list<u8>` → `Uint8Array` in jco).
+     * Dispatches by msgType for Workflow behavior (workflow_run, workflow_signal:name, workflow_query:name),
+     * then by payload.op (or payload) to on<Op>(payload). Returns UTF-8 JSON bytes.
+     * Uses iterative serializer to avoid WASM recursion.
+     *
+     * Workflow behavior (aligned with Rust Workflow trait and Python @workflow_actor):
+     * - msgType "workflow_run" -> run(payload)
+     * - msgType "workflow_signal:name" -> signal(name, payload)
+     * - msgType "workflow_query:name" -> query(name, payload)
+     */
+    handle(_fromActor: string, msgType: string, payloadJson: string | Uint8Array | ArrayBuffer | ArrayBufferView): Uint8Array;
+    /** WIT `get-state() -> result<payload, actor-error>`. Returns JSON state as UTF-8 bytes. */
+    getState(): Uint8Array;
+    /** WIT `set-state(state: payload) -> result<_, actor-error>`. */
+    setState(stateJson: string | Uint8Array | ArrayBuffer | ArrayBufferView): void;
+    protected capitalize(s: string): string;
+    protected resolveDecoratedHandler(op: string, definition?: import("./decorators.js").ActorDefinitionMetadata | undefined): string | null;
+    /**
+     * Serialize object to JSON string using fully iterative approach (zero recursion).
+     *
+     * jco componentize compiles JS to WASM (StarlingMonkey) with a tiny call stack.
+     * Native JSON.stringify recurses per-element and per-nesting-level, hitting
+     * stack limits with arrays of 2+ items. This iterative serializer uses a work
+     * stack instead of recursive function calls.
+     */
+    protected json(obj: unknown): string;
+    protected error(message: string): string;
+}
+/**
+ * Base class for Workflow behavior actors (aligned with Rust Workflow trait and Python @workflow_actor).
+ *
+ * Implement run(), signal(), and query() for durable workflows (Temporal/Restate-style).
+ * Message routing: framework sends msgType "workflow_run" | "workflow_signal:name" | "workflow_query:name";
+ * PlexSpacesActor.handle() dispatches to these methods when present.
+ *
+ * Example:
+ *   class OrderFulfillmentActor extends WorkflowActor<OrderState> {
+ *     getDefaultState() { return { orderId: '', status: 'pending', steps: [] }; }
+ *     run(payload: Record<string, unknown>) { ...; return { status: 'completed' }; }
+ *     signal(name: string, data: Record<string, unknown>) { if (name === 'cancel') this.state.status = 'cancelled'; }
+ *     query(name: string, params: Record<string, unknown>) { if (name === 'status') return this.state; return {}; }
+ *   }
+ */
+export declare abstract class WorkflowActor<TState extends object = Record<string, unknown>> extends PlexSpacesActor<TState> {
+    /** Main workflow execution (exclusive). Called when msgType is "workflow_run". Return result for ask/call. */
+    abstract run(payload: Record<string, unknown>): Record<string, unknown> | unknown;
+    /** Handle external signal (e.g. cancel). Called when msgType is "workflow_signal:name". */
+    abstract signal(name: string, data: Record<string, unknown>): void;
+    /** Read-only query. Called when msgType is "workflow_query:name". Return result for ask/call. */
+    abstract query(name: string, params: Record<string, unknown>): Record<string, unknown> | unknown;
+}