ziex 0.1.0-dev.786 → 0.1.0-dev.787

package/cloudflare/kv.d.ts

@@ -13,7 +13,15 @@ export interface KVNamespace {
         }[];
     }>;
 }
+/**
+ * In-memory KV namespace. Used as the default shim on platforms that don't
+ * provide a real KV binding (e.g. Vercel). Data lives only for the lifetime
+ * of the isolate instance.
+ */
+export declare function createMemoryKV(): KVNamespace;
 /**
  * Create a `__zx_kv` import object for use with `worker.run({ kv: ... })`.
+ * Always returns a valid import object. When JSPI is unavailable all KV
+ * operations are stubbed (get → not-found, put/delete → success, list → []).
  */
 export declare function createKVImports(bindings: Record<string, KVNamespace>, getMemory: () => WebAssembly.Memory): Record<string, unknown>;

package/cloudflare/worker.d.ts

@@ -13,15 +13,98 @@
  * });
  * ```
  */
-export declare function run({ request, env, ctx, module, kv: kvBindings, imports, }: {
+/** Minimal Durable Object namespace shape needed for WebSocket routing. */
+type DurableObjectNamespace = {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        fetch(req: Request): Promise<Response>;
+    };
+};
+export declare function run({ request, env, ctx, module, kv: kvBindings, imports, wasi, websocket: doNamespace, }: {
     request: Request;
     env?: unknown;
-    ctx?: unknown;
+    ctx?: {
+        waitUntil(promise: Promise<unknown>): void;
+    };
     module: WebAssembly.Module;
     /** KV namespace bindings — `{ default: env.KV, otherName: env.OTHER_KV }` */
     kv?: Record<string, import("./kv").KVNamespace>;
     imports?: (mem: () => WebAssembly.Memory) => Record<string, Record<string, unknown>>;
+    wasi?: WASI;
+    /**
+     * Durable Object namespace to use for WebSocket connections.
+     * When provided, WebSocket upgrade requests are automatically forwarded to
+     * the DO so that pub/sub works across multiple connected clients.
+     *
+     * The DO class must be created with `createWebSocketDO` and exported from
+     * your worker:
+     *
+     * ```ts
+     * export const MyDO = createWebSocketDO(module);
+     * export default {
+     *   fetch: (req, env, ctx) => run({ request: req, ctx, module, websocket: env.MyDO }),
+     * };
+     * ```
+     */
+    websocket?: DurableObjectNamespace;
 }): Promise<Response>;
+type WsState = {
+    upgraded: boolean;
+    server: WebSocket | null;
+    pendingWrites: Uint8Array[];
+    messageQueue: Uint8Array[];
+    recvResolve: ((bytes: Uint8Array | null) => void) | null;
+    /** Resolved when ws_recv is called for the first time (WASM has entered the message loop). */
+    _resolveFirstSuspend?: () => void;
+    subscribe?: (topic: string) => void;
+    unsubscribe?: (topic: string) => void;
+    publish?: (topic: string, data: Uint8Array) => number;
+    isSubscribed?: (topic: string) => boolean;
+};
+type ConnState = WsState & {
+    topics: Set<string>;
+};
+/**
+ * Create a Durable Object class that handles WebSocket connections for a ZX app.
+ *
+ * Each DO instance corresponds to one "room" (keyed by pathname). All clients
+ * connecting to the same route share a DO instance, enabling pub/sub via
+ * `ctx.socket.subscribe()` / `ctx.socket.publish()`.
+ *
+ * @example
+ * ```ts
+ * // worker.ts
+ * import { run, createWebSocketDO } from "ziex/cloudflare";
+ * import module from "./app.wasm";
+ *
+ * export const ZxWS = createWebSocketDO(module);
+ *
+ * export default {
+ *   fetch: (req: Request, env: any, ctx: any) =>
+ *     run({ request: req, ctx, module, websocket: env.ZxWS }),
+ * };
+ * ```
+ */
+export declare function createWebSocketDO(module: WebAssembly.Module, options?: {
+    /**
+     * KV namespace bindings for the DO. Pass a factory that receives the DO's
+     * `env` so bindings are resolved at runtime:
+     *
+     * ```ts
+     * createWebSocketDO(module, { kv: (env) => ({ default: env.KV }) })
+     * ```
+     */
+    kv?: (env: any) => Record<string, import("./kv").KVNamespace>;
+    imports?: (mem: () => WebAssembly.Memory) => Record<string, Record<string, unknown>>;
+}): {
+    new (state: any, env: any): {
+        readonly doState: any;
+        readonly env: any;
+        /** All active connections in this room, keyed by their server-side WebSocket. */
+        readonly connections: Map<WebSocket, ConnState>;
+        fetch(request: Request): Promise<Response>;
+    };
+};
 export declare function prepare({ request, env, ctx, }: {
     request: Request;
     env: unknown;
@@ -37,3 +120,29 @@ export declare function respond({ exec, stdout, stderr, }: {
     stdout: TransformStream;
     stderr: TransformStream | ReadableStream<Uint8Array>;
 }): Promise<Response>;
+type WASI = {
+    args?: Array<string>;
+    env?: Array<string>;
+    fds?: Array<unknown>;
+    inst?: {
+        exports: {
+            memory: WebAssembly.Memory;
+        };
+    };
+    wasiImport: Record<string, Function> | {
+        [key: string]: (...args: Array<any>) => unknown;
+    };
+    start(instance: {
+        exports: {
+            memory: WebAssembly.Memory;
+            _start: () => unknown;
+        };
+    }): number;
+    initialize?(instance: {
+        exports: {
+            memory: WebAssembly.Memory;
+            _initialize?: () => unknown;
+        };
+    }): void;
+};
+export {};

package/hono/index.d.ts

@@ -0,0 +1,92 @@
+import { Hono } from "hono";
+import type { KVNamespace } from "../cloudflare/kv";
+type DurableObjectNamespace = {
+    idFromName(name: string): unknown;
+    get(id: unknown): {
+        fetch(req: Request): Promise<Response>;
+    };
+};
+type WASI = {
+    wasiImport: Record<string, (...args: any[]) => unknown>;
+    start(instance: {
+        exports: {
+            memory: WebAssembly.Memory;
+            _start: () => unknown;
+        };
+    }): number;
+    initialize?(instance: {
+        exports: {
+            memory: WebAssembly.Memory;
+            _initialize?: () => unknown;
+        };
+    }): void;
+};
+/**
+ * Create a Hono app that runs a Ziex WASM module.
+ *
+ * The returned app handles all routes (`*`) and forwards each request to
+ * the WASM runtime. Deploy it on any platform Hono supports:
+ *
+ * @example Cloudflare Workers
+ * ```ts
+ * import { createHonoApp } from "ziex/hono";
+ * import module from "./app.wasm";
+ *
+ * const app = createHonoApp<{ KV: KVNamespace }>({
+ *   module,
+ *   kv: (env) => ({ default: env.KV }),
+ * });
+ *
+ * export default app;
+ * ```
+ *
+ * @example Node / Vercel (requires JSPI support)
+ * ```ts
+ * import { createHonoApp } from "ziex/hono";
+ * import { serve } from "@hono/node-server";
+ * import module from "./app.wasm";
+ *
+ * const app = createHonoApp({ module });
+ * serve(app);
+ * ```
+ *
+ * **Note:** The WASM async model relies on JSPI (`WebAssembly.Suspending` /
+ * `WebAssembly.promising`). Verify that your target runtime supports it.
+ */
+export declare function createHonoApp<Bindings extends Record<string, unknown> = Record<string, unknown>>(options: {
+    /** Compiled WASM module for the Ziex app. */
+    module: WebAssembly.Module;
+    /**
+     * Optional pre-configured WASI instance. When omitted the built-in WASI
+     * shim (from `ziex/cloudflare`) is used automatically.
+     */
+    wasi?: WASI;
+    /**
+     * Extra WASM import objects, keyed by module namespace.
+     * Receives a `mem` accessor so you can read WASM memory lazily.
+     */
+    imports?: (mem: () => WebAssembly.Memory) => Record<string, Record<string, unknown>>;
+    /**
+     * Factory that maps platform env bindings to Ziex KV namespaces.
+     * Called once per request so bindings are resolved at runtime.
+     *
+     * @example
+     * ```ts
+     * kv: (env) => ({ default: env.MY_KV })
+     * ```
+     */
+    kv?: (env: Bindings) => Record<string, KVNamespace>;
+    /**
+     * Factory that maps platform env bindings to a Durable Object namespace
+     * for WebSocket pub/sub support.
+     *
+     * @example
+     * ```ts
+     * websocket: (env) => env.ZxWS
+     * ```
+     */
+    websocket?: (env: Bindings) => DurableObjectNamespace;
+}): Hono<{
+    Bindings: Bindings;
+}>;
+export {};