@c9up/aurora 0.1.11 → 0.1.12

package/dist/index.d.ts

@@ -9,14 +9,15 @@ export { html, isTemplateResult } from "./html.js";
 export type { HttpClientOptions, HttpRequestOptions, HttpResult, } from "./http.js";
 export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";
 export { hydrate } from "./hydrate.js";
+export { type LiveComponentDefinition, type LiveSession, mountLiveSession, type SlotPatch, } from "./live.js";
+export { connectPatches, type LiveStore, liveStore, type RelayBroadcaster, } from "./liveBroadcast.js";
+export { buildLiveTransport, type LiveClientOptions, type LiveClientTransport, type LiveHttpPoster, liveClient, type RelaySubscribeClient, } from "./liveClient.js";
+export { createLiveRegistry, type LiveRegistry, type LiveSessionHandle, } from "./liveRegistry.js";
+export { createLiveRouter, type LiveMount, type LiveRouter, } from "./liveRouter.js";
+export { DEFAULT_LIVE_EVENT_PATH, type LiveHttpContext, type LiveHttpRouter, type WireLiveEventsOptions, wireLiveEvents, } from "./liveServer.js";
 export { batch, effect, isSignal, memo, onCleanup, type ReadSignal, type Signal, signal, untrack, } from "./reactive.js";
 export { type Disposer, render } from "./render.js";
 export { type AuroraHttpContext, type AuroraResponse, type AuroraRouteConfig, auroraRoute, } from "./route.js";
+export { createRpcClient, isRpcError, type RpcCall, type RpcClient, type RpcClientOptions, RpcError, type RpcResult, } from "./rpc.js";
 export { renderToString } from "./ssr.js";
-export { type LiveComponentDefinition, type LiveSession, mountLiveSession, type SlotPatch, } from "./live.js";
-export { createLiveRegistry, type LiveRegistry, type LiveSessionHandle, } from "./liveRegistry.js";
-export { connectPatches, type LiveStore, liveStore, type RelayBroadcaster, } from "./liveBroadcast.js";
-export { createLiveRouter, type LiveMount, type LiveRouter, } from "./liveRouter.js";
-export { buildLiveTransport, liveClient, type LiveClientOptions, type LiveClientTransport, type LiveHttpPoster, type RelaySubscribeClient, } from "./liveClient.js";
-export { DEFAULT_LIVE_EVENT_PATH, type LiveHttpContext, type LiveHttpRouter, wireLiveEvents, type WireLiveEventsOptions, } from "./liveServer.js";
 export type { TemplateResult } from "./types.js";

package/dist/index.js

@@ -5,13 +5,14 @@ export { form } from "./form.js";
 export { html, isTemplateResult } from "./html.js";
 export { HttpClient, HttpError, http, isAbortError, isHttpError, } from "./http.js";
 export { hydrate } from "./hydrate.js";
-export { batch, effect, isSignal, memo, onCleanup, signal, untrack, } from "./reactive.js";
-export { render } from "./render.js";
-export { auroraRoute, } from "./route.js";
-export { renderToString } from "./ssr.js";
 export { mountLiveSession, } from "./live.js";
-export { createLiveRegistry, } from "./liveRegistry.js";
 export { connectPatches, liveStore, } from "./liveBroadcast.js";
-export { createLiveRouter, } from "./liveRouter.js";
 export { buildLiveTransport, liveClient, } from "./liveClient.js";
+export { createLiveRegistry, } from "./liveRegistry.js";
+export { createLiveRouter, } from "./liveRouter.js";
 export { DEFAULT_LIVE_EVENT_PATH, wireLiveEvents, } from "./liveServer.js";
+export { batch, effect, isSignal, memo, onCleanup, signal, untrack, } from "./reactive.js";
+export { render } from "./render.js";
+export { auroraRoute, } from "./route.js";
+export { createRpcClient, isRpcError, RpcError, } from "./rpc.js";
+export { renderToString } from "./ssr.js";

package/dist/rpc.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
+ * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
+ * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
+ * headers, and timeouts.
+ *
+ *   const rpc = createRpcClient()                          // POST /rpc, same-origin
+ *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
+ *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
+ *
+ * Pairs with aurora's `command()` for reactive calls:
+ *   const validate = command((p) => rpc.call('task.validate', p))
+ */
+import { HttpClient } from "./http.js";
+export interface RpcClientOptions {
+    /** Endpoint path. Default `/rpc` (matches RpcProvider's default). */
+    url?: string;
+    /** Reuse an existing HttpClient — its baseURL / headers / auth carry over. */
+    http?: HttpClient;
+    /** Default headers — only used when no `http` client is supplied. */
+    headers?: Record<string, string>;
+}
+/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** Type guard for {@link RpcError}. */
+export declare function isRpcError(value: unknown): value is RpcError;
+/** One call in a batch. `parse` optionally validates that call's result (cast-free). */
+export interface RpcCall<T = unknown> {
+    method: string;
+    params?: unknown;
+    parse?: (data: unknown) => T;
+}
+/** A settled batch entry — the result, or the JSON-RPC error for that call. */
+export type RpcResult<T = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: RpcError;
+};
+export interface RpcClient {
+    /**
+     * Call one method. Returns the result, or throws {@link RpcError} on a
+     * JSON-RPC error. Pass `parse` to validate the result at runtime (and skip
+     * the unchecked `T` assertion).
+     */
+    call<T = unknown>(method: string, params?: unknown, parse?: (data: unknown) => T): Promise<T>;
+    /** Send a JSON-RPC batch. Returns one settled entry per call, in request order. */
+    batch(calls: RpcCall[]): Promise<RpcResult[]>;
+}
+export declare function createRpcClient(options?: RpcClientOptions): RpcClient;

package/dist/rpc.js

@@ -0,0 +1,97 @@
+/**
+ * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
+ * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
+ * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
+ * headers, and timeouts.
+ *
+ *   const rpc = createRpcClient()                          // POST /rpc, same-origin
+ *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
+ *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
+ *
+ * Pairs with aurora's `command()` for reactive calls:
+ *   const validate = command((p) => rpc.call('task.validate', p))
+ */
+import { HttpClient } from "./http.js";
+/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = "RpcError";
+        this.code = code;
+        this.data = data;
+    }
+}
+/** Type guard for {@link RpcError}. */
+export function isRpcError(value) {
+    return value instanceof RpcError;
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/** Turn a JSON-RPC `error` member into an {@link RpcError}. */
+function toRpcError(error) {
+    if (isObject(error) &&
+        typeof error.code === "number" &&
+        typeof error.message === "string") {
+        return new RpcError(error.code, error.message, error.data);
+    }
+    return new RpcError(-32603, "Malformed JSON-RPC error envelope", error);
+}
+export function createRpcClient(options = {}) {
+    const http = options.http ?? new HttpClient({ headers: options.headers });
+    const url = options.url ?? "/rpc";
+    let nextId = 0;
+    return {
+        async call(method, params, parse) {
+            const id = ++nextId;
+            const res = await http.post(url, {
+                jsonrpc: "2.0",
+                method,
+                params,
+                id,
+            });
+            if (!isObject(res)) {
+                throw new RpcError(-32603, `Malformed JSON-RPC response for "${method}"`);
+            }
+            if (res.error !== undefined)
+                throw toRpcError(res.error);
+            // Result boundary — the same unchecked `T` assertion HttpClient uses,
+            // with `parse` as the cast-free, runtime-validated escape hatch.
+            return parse ? parse(res.result) : res.result;
+        },
+        async batch(calls) {
+            if (calls.length === 0)
+                return [];
+            const requests = calls.map((c, index) => ({
+                jsonrpc: "2.0",
+                method: c.method,
+                params: c.params,
+                id: index, // index = request position; responses are matched back by id
+            }));
+            const res = await http.post(url, requests);
+            if (!Array.isArray(res)) {
+                throw new RpcError(-32603, "Malformed JSON-RPC batch response");
+            }
+            const byId = new Map();
+            for (const item of res)
+                if (isObject(item))
+                    byId.set(item.id, item);
+            return calls.map((c, index) => {
+                const envelope = byId.get(index);
+                if (!envelope) {
+                    return {
+                        ok: false,
+                        error: new RpcError(-32603, `No response for "${c.method}"`),
+                    };
+                }
+                if (envelope.error !== undefined) {
+                    return { ok: false, error: toRpcError(envelope.error) };
+                }
+                const value = c.parse ? c.parse(envelope.result) : envelope.result;
+                return { ok: true, value };
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/aurora",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Aurora — reactive UI runtime for the Ream framework. Tagged-template DOM, signal-based state, isomorphic SSR + hydration, zero build step.",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -60,60 +60,69 @@ export {
 	isHttpError,
 } from "./http.js";
 export { hydrate } from "./hydrate.js";
-export {
-	batch,
-	effect,
-	isSignal,
-	memo,
-	onCleanup,
-	type ReadSignal,
-	type Signal,
-	signal,
-	untrack,
-} from "./reactive.js";
-export { type Disposer, render } from "./render.js";
-export {
-	type AuroraHttpContext,
-	type AuroraResponse,
-	type AuroraRouteConfig,
-	auroraRoute,
-} from "./route.js";
-export { renderToString } from "./ssr.js";
 export {
 	type LiveComponentDefinition,
 	type LiveSession,
 	mountLiveSession,
 	type SlotPatch,
 } from "./live.js";
-export {
-	createLiveRegistry,
-	type LiveRegistry,
-	type LiveSessionHandle,
-} from "./liveRegistry.js";
 export {
 	connectPatches,
 	type LiveStore,
 	liveStore,
 	type RelayBroadcaster,
 } from "./liveBroadcast.js";
-export {
-	createLiveRouter,
-	type LiveMount,
-	type LiveRouter,
-} from "./liveRouter.js";
 export {
 	buildLiveTransport,
-	liveClient,
 	type LiveClientOptions,
 	type LiveClientTransport,
 	type LiveHttpPoster,
+	liveClient,
 	type RelaySubscribeClient,
 } from "./liveClient.js";
+export {
+	createLiveRegistry,
+	type LiveRegistry,
+	type LiveSessionHandle,
+} from "./liveRegistry.js";
+export {
+	createLiveRouter,
+	type LiveMount,
+	type LiveRouter,
+} from "./liveRouter.js";
 export {
 	DEFAULT_LIVE_EVENT_PATH,
 	type LiveHttpContext,
 	type LiveHttpRouter,
-	wireLiveEvents,
 	type WireLiveEventsOptions,
+	wireLiveEvents,
 } from "./liveServer.js";
+export {
+	batch,
+	effect,
+	isSignal,
+	memo,
+	onCleanup,
+	type ReadSignal,
+	type Signal,
+	signal,
+	untrack,
+} from "./reactive.js";
+export { type Disposer, render } from "./render.js";
+export {
+	type AuroraHttpContext,
+	type AuroraResponse,
+	type AuroraRouteConfig,
+	auroraRoute,
+} from "./route.js";
+export {
+	createRpcClient,
+	isRpcError,
+	type RpcCall,
+	type RpcClient,
+	type RpcClientOptions,
+	RpcError,
+	type RpcResult,
+} from "./rpc.js";
+export { renderToString } from "./ssr.js";
 export type { TemplateResult } from "./types.js";

package/src/rpc.ts

@@ -0,0 +1,145 @@
+/**
+ * Browser JSON-RPC 2.0 client for Ream's RPC endpoint. `@c9up/ream`'s
+ * RpcProvider mounts `POST /rpc` and speaks JSON-RPC 2.0 (single + batch); this
+ * client builds on aurora's {@link HttpClient}, inheriting its base URL, auth
+ * headers, and timeouts.
+ *
+ *   const rpc = createRpcClient()                          // POST /rpc, same-origin
+ *   const result = await rpc.call('task.validate', { id }) // typed via call<T>()
+ *   const user = await rpc.call('user.find', { id }, isUser) // validated, cast-free
+ *
+ * Pairs with aurora's `command()` for reactive calls:
+ *   const validate = command((p) => rpc.call('task.validate', p))
+ */
+import { HttpClient } from "./http.js";
+
+export interface RpcClientOptions {
+	/** Endpoint path. Default `/rpc` (matches RpcProvider's default). */
+	url?: string;
+	/** Reuse an existing HttpClient — its baseURL / headers / auth carry over. */
+	http?: HttpClient;
+	/** Default headers — only used when no `http` client is supplied. */
+	headers?: Record<string, string>;
+}
+
+/** A JSON-RPC 2.0 error returned by the server (code + message + optional data). */
+export class RpcError extends Error {
+	readonly code: number;
+	readonly data?: unknown;
+	constructor(code: number, message: string, data?: unknown) {
+		super(message);
+		this.name = "RpcError";
+		this.code = code;
+		this.data = data;
+	}
+}
+
+/** Type guard for {@link RpcError}. */
+export function isRpcError(value: unknown): value is RpcError {
+	return value instanceof RpcError;
+}
+
+/** One call in a batch. `parse` optionally validates that call's result (cast-free). */
+export interface RpcCall<T = unknown> {
+	method: string;
+	params?: unknown;
+	parse?: (data: unknown) => T;
+}
+
+/** A settled batch entry — the result, or the JSON-RPC error for that call. */
+export type RpcResult<T = unknown> =
+	| { ok: true; value: T }
+	| { ok: false; error: RpcError };
+
+export interface RpcClient {
+	/**
+	 * Call one method. Returns the result, or throws {@link RpcError} on a
+	 * JSON-RPC error. Pass `parse` to validate the result at runtime (and skip
+	 * the unchecked `T` assertion).
+	 */
+	call<T = unknown>(
+		method: string,
+		params?: unknown,
+		parse?: (data: unknown) => T,
+	): Promise<T>;
+	/** Send a JSON-RPC batch. Returns one settled entry per call, in request order. */
+	batch(calls: RpcCall[]): Promise<RpcResult[]>;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/** Turn a JSON-RPC `error` member into an {@link RpcError}. */
+function toRpcError(error: unknown): RpcError {
+	if (
+		isObject(error) &&
+		typeof error.code === "number" &&
+		typeof error.message === "string"
+	) {
+		return new RpcError(error.code, error.message, error.data);
+	}
+	return new RpcError(-32603, "Malformed JSON-RPC error envelope", error);
+}
+
+export function createRpcClient(options: RpcClientOptions = {}): RpcClient {
+	const http = options.http ?? new HttpClient({ headers: options.headers });
+	const url = options.url ?? "/rpc";
+	let nextId = 0;
+
+	return {
+		async call<T>(
+			method: string,
+			params?: unknown,
+			parse?: (data: unknown) => T,
+		): Promise<T> {
+			const id = ++nextId;
+			const res = await http.post<unknown>(url, {
+				jsonrpc: "2.0",
+				method,
+				params,
+				id,
+			});
+			if (!isObject(res)) {
+				throw new RpcError(
+					-32603,
+					`Malformed JSON-RPC response for "${method}"`,
+				);
+			}
+			if (res.error !== undefined) throw toRpcError(res.error);
+			// Result boundary — the same unchecked `T` assertion HttpClient uses,
+			// with `parse` as the cast-free, runtime-validated escape hatch.
+			return parse ? parse(res.result) : (res.result as T);
+		},
+
+		async batch(calls: RpcCall[]): Promise<RpcResult[]> {
+			if (calls.length === 0) return [];
+			const requests = calls.map((c, index) => ({
+				jsonrpc: "2.0",
+				method: c.method,
+				params: c.params,
+				id: index, // index = request position; responses are matched back by id
+			}));
+			const res = await http.post<unknown>(url, requests);
+			if (!Array.isArray(res)) {
+				throw new RpcError(-32603, "Malformed JSON-RPC batch response");
+			}
+			const byId = new Map<unknown, Record<string, unknown>>();
+			for (const item of res) if (isObject(item)) byId.set(item.id, item);
+			return calls.map((c, index) => {
+				const envelope = byId.get(index);
+				if (!envelope) {
+					return {
+						ok: false,
+						error: new RpcError(-32603, `No response for "${c.method}"`),
+					};
+				}
+				if (envelope.error !== undefined) {
+					return { ok: false, error: toRpcError(envelope.error) };
+				}
+				const value = c.parse ? c.parse(envelope.result) : envelope.result;
+				return { ok: true, value };
+			});
+		},
+	};
+}