@c9up/comet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C9up
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @c9up/comet
+
+Agnostic **JSON-RPC 2.0** protocol + an **isomorphic, transport-injectable client**
+for the [Ream](https://github.com/C9up) framework. Zero framework, zero transport,
+zero dependency — the browser binding (`@c9up/aurora`) and the server binding
+(`@c9up/ream`'s `RpcRouter`) both build on this core instead of hand-rolling the
+envelope and error codes.
+
+## Client
+
+The client owns the JSON-RPC logic (single + batch, id matching, error mapping)
+and delegates the actual bytes to an injected `transport` — so the same client
+runs in the browser or in Node:
+
+```ts
+import { createRpcClient } from "@c9up/comet";
+
+const rpc = createRpcClient({
+  url: "/rpc",
+  transport: (url, body, { signal }) =>
+    fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal,
+    }).then((r) => r.json()),
+});
+
+const out = await rpc.call("task.validate", { id: 7 });          // typed via call<T>()
+await rpc.call("user.find", { id }, { parse: isUser });          // runtime-validated
+await rpc.call("slow.op", p, { signal: ac.signal });             // abortable
+const results = await rpc.batch([{ method: "a" }, { method: "b" }]); // settled per call
+```
+
+> In the browser, prefer `@c9up/aurora`'s `createRpcClient` — it wires aurora's
+> `HttpClient` (base URL, auth headers, timeouts) as the transport and pairs with
+> `command()`.
+
+## Protocol
+
+The `@c9up/comet/protocol` surface exposes the spec primitives a server binding
+needs: `parseRequest`, `isNotification`, `buildRequest`/`buildSuccess`/`buildError`,
+`RpcError`/`toRpcError`/`isRpcShapedError`, and the reserved `RpcErrorCode`.

package/dist/client.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Isomorphic JSON-RPC 2.0 client — the protocol logic (single + batch) over an
+ * INJECTED transport. It owns the envelope/id/error handling (from
+ * {@link "./protocol"}) and knows nothing about how bytes travel: pass a browser
+ * transport (aurora's HttpClient) or a Node one (fetch/undici). This is the
+ * adapter seam that lets the client live outside any UI or server framework.
+ *
+ *   const rpc = createRpcClient({ transport: (url, body, { signal }) =>
+ *     fetch(url, { method: 'POST', body: JSON.stringify(body), signal })
+ *       .then((r) => r.json()) })
+ *   const out = await rpc.call('task.validate', { id })
+ */
+import { RpcError } from "./protocol.js";
+/**
+ * Sends a JSON body to `url` and resolves the parsed JSON response. Injected via
+ * {@link RpcClientOptions.transport}; the client never touches `fetch` directly.
+ */
+export type RpcTransport = (url: string, body: unknown, options: {
+    signal?: AbortSignal;
+}) => Promise<unknown>;
+export interface RpcClientOptions {
+    /** How requests are sent — the only required wiring. */
+    transport: RpcTransport;
+    /** Endpoint path. Default `/rpc`. */
+    url?: string;
+}
+/** Per-call options for {@link RpcClient.call}. */
+export interface RpcCallOptions<T = unknown> {
+    /**
+     * Validate the result at runtime, returning the typed value — skips the
+     * unchecked `T` assertion (the cast-free escape hatch).
+     */
+    parse?: (data: unknown) => T;
+    /** Abort signal — abort it to cancel the request (e.g. on unmount / new keystroke). */
+    signal?: AbortSignal;
+}
+/** 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. The `jsonrpc`/`id` envelope is handled internally. Pass
+     * `options.parse` to validate the result at runtime (skips the unchecked `T`
+     * assertion) and `options.signal` to make the call abortable.
+     */
+    call<T = unknown>(method: string, params?: unknown, options?: RpcCallOptions<T>): Promise<T>;
+    /**
+     * Send a JSON-RPC batch. Returns one settled entry per call, in request
+     * order. `options.signal` aborts the whole batch (it is one HTTP request).
+     */
+    batch(calls: RpcCall[], options?: {
+        signal?: AbortSignal;
+    }): Promise<RpcResult[]>;
+}
+export declare function createRpcClient(options: RpcClientOptions): RpcClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAGN,QAAQ,EAGR,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAC7B,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAChC,wDAAwD;IACxD,SAAS,EAAE,YAAY,CAAC;IACxB,qCAAqC;IACrC,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc,CAAC,CAAC,GAAG,OAAO;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;IAC7B,uFAAuF;IACvF,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,wFAAwF;AACxF,MAAM,WAAW,OAAO,CAAC,CAAC,GAAG,OAAO;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,CAAC;CAC7B;AAED,+EAA+E;AAC/E,MAAM,MAAM,SAAS,CAAC,CAAC,GAAG,OAAO,IAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,SAAS;IACzB;;;;;OAKG;IACH,IAAI,CAAC,CAAC,GAAG,OAAO,EACf,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAAC;IACd;;;OAGG;IACH,KAAK,CACJ,KAAK,EAAE,OAAO,EAAE,EAChB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAChC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;CACxB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CAoEpE"}

package/dist/client.js

@@ -0,0 +1,68 @@
+/**
+ * Isomorphic JSON-RPC 2.0 client — the protocol logic (single + batch) over an
+ * INJECTED transport. It owns the envelope/id/error handling (from
+ * {@link "./protocol"}) and knows nothing about how bytes travel: pass a browser
+ * transport (aurora's HttpClient) or a Node one (fetch/undici). This is the
+ * adapter seam that lets the client live outside any UI or server framework.
+ *
+ *   const rpc = createRpcClient({ transport: (url, body, { signal }) =>
+ *     fetch(url, { method: 'POST', body: JSON.stringify(body), signal })
+ *       .then((r) => r.json()) })
+ *   const out = await rpc.call('task.validate', { id })
+ */
+import { buildRequest, isObject, RpcError, RpcErrorCode, toRpcError, } from "./protocol.js";
+export function createRpcClient(options) {
+    const { transport } = options;
+    const url = options.url ?? "/rpc";
+    let nextId = 0;
+    return {
+        async call(method, params, callOptions) {
+            const id = ++nextId;
+            const res = await transport(url, buildRequest(method, params, id), {
+                signal: callOptions?.signal,
+            });
+            if (!isObject(res)) {
+                throw new RpcError(RpcErrorCode.InternalError, `Malformed JSON-RPC response for "${method}"`);
+            }
+            if (res.error !== undefined)
+                throw toRpcError(res.error);
+            // Result boundary — the same unchecked `T` assertion HTTP clients use,
+            // with `parse` as the cast-free, runtime-validated escape hatch.
+            return callOptions?.parse
+                ? callOptions.parse(res.result)
+                : res.result;
+        },
+        async batch(calls, batchOptions) {
+            if (calls.length === 0)
+                return [];
+            const requests = calls.map((c, index) => 
+            // index = request position; responses are matched back by id
+            buildRequest(c.method, c.params, index));
+            const res = await transport(url, requests, {
+                signal: batchOptions?.signal,
+            });
+            if (!Array.isArray(res)) {
+                throw new RpcError(RpcErrorCode.InternalError, "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(RpcErrorCode.InternalError, `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 };
+            });
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Comet — agnostic JSON-RPC 2.0 protocol + isomorphic, transport-injectable
+ * client. Zero framework, zero transport, zero dependency. The browser binding
+ * (aurora) and the server binding (Ream's `RpcRouter`) both build on this.
+ */
+export { createRpcClient, type RpcCall, type RpcCallOptions, type RpcClient, type RpcClientOptions, type RpcResult, type RpcTransport, } from "./client.js";
+export { buildError, buildRequest, buildSuccess, isNotification, isObject, isRpcError, isRpcShapedError, type JsonRpcErrorObject, type JsonRpcErrorResponse, type JsonRpcId, type JsonRpcRequest, type JsonRpcResponse, type JsonRpcSuccessResponse, type ParsedRpcRequest, parseRequest, RpcError, RpcErrorCode, toRpcError, } from "./protocol.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACN,eAAe,EACf,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,UAAU,EACV,gBAAgB,EAChB,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,UAAU,GACV,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+/**
+ * Comet — agnostic JSON-RPC 2.0 protocol + isomorphic, transport-injectable
+ * client. Zero framework, zero transport, zero dependency. The browser binding
+ * (aurora) and the server binding (Ream's `RpcRouter`) both build on this.
+ */
+export { createRpcClient, } from "./client.js";
+export { buildError, buildRequest, buildSuccess, isNotification, isObject, isRpcError, isRpcShapedError, parseRequest, RpcError, RpcErrorCode, toRpcError, } from "./protocol.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACN,eAAe,GAOf,MAAM,aAAa,CAAC;AACrB,OAAO,EACN,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,UAAU,EACV,gBAAgB,EAQhB,YAAY,EACZ,QAAQ,EACR,YAAY,EACZ,UAAU,GACV,MAAM,eAAe,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,101 @@
+/**
+ * JSON-RPC 2.0 protocol primitives — the agnostic core shared by every Comet
+ * consumer: the isomorphic {@link "./client".createRpcClient} AND any server
+ * binding (Ream's `RpcRouter` builds on these instead of hand-rolling its own).
+ *
+ * Zero transport, zero framework, zero dependency — just the envelope shapes,
+ * the reserved error codes, builders, and the request parser/notification rule
+ * from the spec (https://www.jsonrpc.org/specification).
+ */
+/** A JSON-RPC id — a string, a number, or `null` (spec §4). */
+export type JsonRpcId = string | number | null;
+/** An outgoing JSON-RPC 2.0 request envelope. */
+export interface JsonRpcRequest {
+    jsonrpc: "2.0";
+    method: string;
+    params?: unknown;
+    id: JsonRpcId;
+}
+/** The `error` member of a JSON-RPC 2.0 error response. */
+export interface JsonRpcErrorObject {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** A successful JSON-RPC 2.0 response envelope. */
+export interface JsonRpcSuccessResponse {
+    jsonrpc: "2.0";
+    result: unknown;
+    id: JsonRpcId;
+}
+/** An error JSON-RPC 2.0 response envelope. */
+export interface JsonRpcErrorResponse {
+    jsonrpc: "2.0";
+    error: JsonRpcErrorObject;
+    id: JsonRpcId;
+}
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/**
+ * The reserved JSON-RPC 2.0 error codes (spec §5.1). Domain handlers are free to
+ * use codes outside the reserved `-32768..-32000` range for their own errors.
+ */
+export declare const RpcErrorCode: {
+    readonly ParseError: -32700;
+    readonly InvalidRequest: -32600;
+    readonly MethodNotFound: -32601;
+    readonly InvalidParams: -32602;
+    readonly InternalError: -32603;
+};
+/** A JSON-RPC 2.0 error surfaced as a throwable (carries `code` + 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;
+/** Narrow an unknown to a plain object (non-null). */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Turn a JSON-RPC `error` member (untrusted wire value) into an {@link RpcError}.
+ * Falls back to an internal-error when the shape is malformed.
+ */
+export declare function toRpcError(error: unknown): RpcError;
+/**
+ * A domain error shaped like a JSON-RPC error — it carries a numeric `code`. A
+ * server binding can map such a throw to a JSON-RPC error response instead of
+ * collapsing every throw to InternalError.
+ */
+export declare function isRpcShapedError(err: unknown): err is {
+    code: number;
+    message?: unknown;
+    data?: unknown;
+};
+/** Build an outgoing request envelope. */
+export declare function buildRequest(method: string, params: unknown, id: JsonRpcId): JsonRpcRequest;
+/** Build a success response envelope. */
+export declare function buildSuccess(result: unknown, id: JsonRpcId): JsonRpcSuccessResponse;
+/** Build an error response envelope (omits `data` when not supplied). */
+export declare function buildError(code: number, message: string, id: JsonRpcId, data?: unknown): JsonRpcErrorResponse;
+/** Result of {@link parseRequest}. */
+export type ParsedRpcRequest = {
+    ok: true;
+    method: string;
+    params: unknown;
+    id: JsonRpcId;
+} | {
+    ok: false;
+    response: JsonRpcErrorResponse;
+};
+/**
+ * Validate an incoming JSON-RPC envelope and extract `method`/`params`/`id`.
+ * Returns an `InvalidRequest` error response when the version/method are wrong.
+ */
+export declare function parseRequest(request: unknown): ParsedRpcRequest;
+/**
+ * A JSON-RPC notification is a well-formed request with NO `id` member. The spec
+ * (§4.1) says the server MUST NOT reply to one — it still runs for side-effects.
+ * A malformed object (no method / wrong version) is NOT a notification.
+ */
+export declare function isNotification(request: unknown): boolean;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAE/C,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC9B,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,SAAS,CAAC;CACd;AAED,2DAA2D;AAC3D,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACtC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,EAAE,EAAE,SAAS,CAAC;CACd;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,KAAK,CAAC;IACf,KAAK,EAAE,kBAAkB,CAAC;IAC1B,EAAE,EAAE,SAAS,CAAC;CACd;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX,uFAAuF;AACvF,qBAAa,QAAS,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;gBACZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO;CAMzD;AAED,uCAAuC;AACvC,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAanD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,OAAO,GACV,GAAG,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,CAE5D;AAED,0CAA0C;AAC1C,wBAAgB,YAAY,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,SAAS,GACX,cAAc,CAEhB;AAED,yCAAyC;AACzC,wBAAgB,YAAY,CAC3B,MAAM,EAAE,OAAO,EACf,EAAE,EAAE,SAAS,GACX,sBAAsB,CAExB;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,EAAE,EAAE,SAAS,EACb,IAAI,CAAC,EAAE,OAAO,GACZ,oBAAoB,CAMtB;AAED,sCAAsC;AACtC,MAAM,MAAM,gBAAgB,GACzB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,SAAS,CAAA;CAAE,GAC5D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,CA8B/D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CASxD"}

package/dist/protocol.js

@@ -0,0 +1,117 @@
+/**
+ * JSON-RPC 2.0 protocol primitives — the agnostic core shared by every Comet
+ * consumer: the isomorphic {@link "./client".createRpcClient} AND any server
+ * binding (Ream's `RpcRouter` builds on these instead of hand-rolling its own).
+ *
+ * Zero transport, zero framework, zero dependency — just the envelope shapes,
+ * the reserved error codes, builders, and the request parser/notification rule
+ * from the spec (https://www.jsonrpc.org/specification).
+ */
+/**
+ * The reserved JSON-RPC 2.0 error codes (spec §5.1). Domain handlers are free to
+ * use codes outside the reserved `-32768..-32000` range for their own errors.
+ */
+export const RpcErrorCode = {
+    ParseError: -32700,
+    InvalidRequest: -32600,
+    MethodNotFound: -32601,
+    InvalidParams: -32602,
+    InternalError: -32603,
+};
+/** A JSON-RPC 2.0 error surfaced as a throwable (carries `code` + 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;
+}
+/** Narrow an unknown to a plain object (non-null). */
+export function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Turn a JSON-RPC `error` member (untrusted wire value) into an {@link RpcError}.
+ * Falls back to an internal-error when the shape is malformed.
+ */
+export 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(RpcErrorCode.InternalError, "Malformed JSON-RPC error envelope", error);
+}
+/**
+ * A domain error shaped like a JSON-RPC error — it carries a numeric `code`. A
+ * server binding can map such a throw to a JSON-RPC error response instead of
+ * collapsing every throw to InternalError.
+ */
+export function isRpcShapedError(err) {
+    return isObject(err) && typeof err.code === "number";
+}
+/** Build an outgoing request envelope. */
+export function buildRequest(method, params, id) {
+    return { jsonrpc: "2.0", method, params, id };
+}
+/** Build a success response envelope. */
+export function buildSuccess(result, id) {
+    return { jsonrpc: "2.0", result, id };
+}
+/** Build an error response envelope (omits `data` when not supplied). */
+export function buildError(code, message, id, data) {
+    return {
+        jsonrpc: "2.0",
+        error: data === undefined ? { code, message } : { code, message, data },
+        id,
+    };
+}
+/**
+ * Validate an incoming JSON-RPC envelope and extract `method`/`params`/`id`.
+ * Returns an `InvalidRequest` error response when the version/method are wrong.
+ */
+export function parseRequest(request) {
+    if (!isObject(request)) {
+        return {
+            ok: false,
+            response: buildError(RpcErrorCode.InvalidRequest, "Invalid Request", null),
+        };
+    }
+    const jsonrpc = "jsonrpc" in request && typeof request.jsonrpc === "string"
+        ? request.jsonrpc
+        : undefined;
+    const method = "method" in request && typeof request.method === "string"
+        ? request.method
+        : undefined;
+    const params = "params" in request ? request.params : undefined;
+    const rawId = "id" in request ? request.id : undefined;
+    const id = typeof rawId === "string" || typeof rawId === "number" ? rawId : null;
+    if (jsonrpc !== "2.0" || !method) {
+        return {
+            ok: false,
+            response: buildError(RpcErrorCode.InvalidRequest, "Invalid Request", id),
+        };
+    }
+    return { ok: true, method, params, id };
+}
+/**
+ * A JSON-RPC notification is a well-formed request with NO `id` member. The spec
+ * (§4.1) says the server MUST NOT reply to one — it still runs for side-effects.
+ * A malformed object (no method / wrong version) is NOT a notification.
+ */
+export function isNotification(request) {
+    return (isObject(request) &&
+        "jsonrpc" in request &&
+        request.jsonrpc === "2.0" &&
+        "method" in request &&
+        typeof request.method === "string" &&
+        !("id" in request));
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@c9up/comet",
+  "version": "0.1.0",
+  "description": "Comet — agnostic JSON-RPC 2.0 protocol + isomorphic, transport-injectable client for the Ream framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/C9up/comet.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "biome check src/",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/client.ts

@@ -0,0 +1,151 @@
+/**
+ * Isomorphic JSON-RPC 2.0 client — the protocol logic (single + batch) over an
+ * INJECTED transport. It owns the envelope/id/error handling (from
+ * {@link "./protocol"}) and knows nothing about how bytes travel: pass a browser
+ * transport (aurora's HttpClient) or a Node one (fetch/undici). This is the
+ * adapter seam that lets the client live outside any UI or server framework.
+ *
+ *   const rpc = createRpcClient({ transport: (url, body, { signal }) =>
+ *     fetch(url, { method: 'POST', body: JSON.stringify(body), signal })
+ *       .then((r) => r.json()) })
+ *   const out = await rpc.call('task.validate', { id })
+ */
+import {
+	buildRequest,
+	isObject,
+	RpcError,
+	RpcErrorCode,
+	toRpcError,
+} from "./protocol.js";
+
+/**
+ * Sends a JSON body to `url` and resolves the parsed JSON response. Injected via
+ * {@link RpcClientOptions.transport}; the client never touches `fetch` directly.
+ */
+export type RpcTransport = (
+	url: string,
+	body: unknown,
+	options: { signal?: AbortSignal },
+) => Promise<unknown>;
+
+export interface RpcClientOptions {
+	/** How requests are sent — the only required wiring. */
+	transport: RpcTransport;
+	/** Endpoint path. Default `/rpc`. */
+	url?: string;
+}
+
+/** Per-call options for {@link RpcClient.call}. */
+export interface RpcCallOptions<T = unknown> {
+	/**
+	 * Validate the result at runtime, returning the typed value — skips the
+	 * unchecked `T` assertion (the cast-free escape hatch).
+	 */
+	parse?: (data: unknown) => T;
+	/** Abort signal — abort it to cancel the request (e.g. on unmount / new keystroke). */
+	signal?: AbortSignal;
+}
+
+/** 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. The `jsonrpc`/`id` envelope is handled internally. Pass
+	 * `options.parse` to validate the result at runtime (skips the unchecked `T`
+	 * assertion) and `options.signal` to make the call abortable.
+	 */
+	call<T = unknown>(
+		method: string,
+		params?: unknown,
+		options?: RpcCallOptions<T>,
+	): Promise<T>;
+	/**
+	 * Send a JSON-RPC batch. Returns one settled entry per call, in request
+	 * order. `options.signal` aborts the whole batch (it is one HTTP request).
+	 */
+	batch(
+		calls: RpcCall[],
+		options?: { signal?: AbortSignal },
+	): Promise<RpcResult[]>;
+}
+
+export function createRpcClient(options: RpcClientOptions): RpcClient {
+	const { transport } = options;
+	const url = options.url ?? "/rpc";
+	let nextId = 0;
+
+	return {
+		async call<T>(
+			method: string,
+			params?: unknown,
+			callOptions?: RpcCallOptions<T>,
+		): Promise<T> {
+			const id = ++nextId;
+			const res = await transport(url, buildRequest(method, params, id), {
+				signal: callOptions?.signal,
+			});
+			if (!isObject(res)) {
+				throw new RpcError(
+					RpcErrorCode.InternalError,
+					`Malformed JSON-RPC response for "${method}"`,
+				);
+			}
+			if (res.error !== undefined) throw toRpcError(res.error);
+			// Result boundary — the same unchecked `T` assertion HTTP clients use,
+			// with `parse` as the cast-free, runtime-validated escape hatch.
+			return callOptions?.parse
+				? callOptions.parse(res.result)
+				: (res.result as T);
+		},
+
+		async batch(
+			calls: RpcCall[],
+			batchOptions?: { signal?: AbortSignal },
+		): Promise<RpcResult[]> {
+			if (calls.length === 0) return [];
+			const requests = calls.map((c, index) =>
+				// index = request position; responses are matched back by id
+				buildRequest(c.method, c.params, index),
+			);
+			const res = await transport(url, requests, {
+				signal: batchOptions?.signal,
+			});
+			if (!Array.isArray(res)) {
+				throw new RpcError(
+					RpcErrorCode.InternalError,
+					"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(
+							RpcErrorCode.InternalError,
+							`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/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Comet — agnostic JSON-RPC 2.0 protocol + isomorphic, transport-injectable
+ * client. Zero framework, zero transport, zero dependency. The browser binding
+ * (aurora) and the server binding (Ream's `RpcRouter`) both build on this.
+ */
+export {
+	createRpcClient,
+	type RpcCall,
+	type RpcCallOptions,
+	type RpcClient,
+	type RpcClientOptions,
+	type RpcResult,
+	type RpcTransport,
+} from "./client.js";
+export {
+	buildError,
+	buildRequest,
+	buildSuccess,
+	isNotification,
+	isObject,
+	isRpcError,
+	isRpcShapedError,
+	type JsonRpcErrorObject,
+	type JsonRpcErrorResponse,
+	type JsonRpcId,
+	type JsonRpcRequest,
+	type JsonRpcResponse,
+	type JsonRpcSuccessResponse,
+	type ParsedRpcRequest,
+	parseRequest,
+	RpcError,
+	RpcErrorCode,
+	toRpcError,
+} from "./protocol.js";

package/src/protocol.ts

@@ -0,0 +1,195 @@
+/**
+ * JSON-RPC 2.0 protocol primitives — the agnostic core shared by every Comet
+ * consumer: the isomorphic {@link "./client".createRpcClient} AND any server
+ * binding (Ream's `RpcRouter` builds on these instead of hand-rolling its own).
+ *
+ * Zero transport, zero framework, zero dependency — just the envelope shapes,
+ * the reserved error codes, builders, and the request parser/notification rule
+ * from the spec (https://www.jsonrpc.org/specification).
+ */
+
+/** A JSON-RPC id — a string, a number, or `null` (spec §4). */
+export type JsonRpcId = string | number | null;
+
+/** An outgoing JSON-RPC 2.0 request envelope. */
+export interface JsonRpcRequest {
+	jsonrpc: "2.0";
+	method: string;
+	params?: unknown;
+	id: JsonRpcId;
+}
+
+/** The `error` member of a JSON-RPC 2.0 error response. */
+export interface JsonRpcErrorObject {
+	code: number;
+	message: string;
+	data?: unknown;
+}
+
+/** A successful JSON-RPC 2.0 response envelope. */
+export interface JsonRpcSuccessResponse {
+	jsonrpc: "2.0";
+	result: unknown;
+	id: JsonRpcId;
+}
+
+/** An error JSON-RPC 2.0 response envelope. */
+export interface JsonRpcErrorResponse {
+	jsonrpc: "2.0";
+	error: JsonRpcErrorObject;
+	id: JsonRpcId;
+}
+
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+
+/**
+ * The reserved JSON-RPC 2.0 error codes (spec §5.1). Domain handlers are free to
+ * use codes outside the reserved `-32768..-32000` range for their own errors.
+ */
+export const RpcErrorCode = {
+	ParseError: -32700,
+	InvalidRequest: -32600,
+	MethodNotFound: -32601,
+	InvalidParams: -32602,
+	InternalError: -32603,
+} as const;
+
+/** A JSON-RPC 2.0 error surfaced as a throwable (carries `code` + 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;
+}
+
+/** Narrow an unknown to a plain object (non-null). */
+export function isObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+/**
+ * Turn a JSON-RPC `error` member (untrusted wire value) into an {@link RpcError}.
+ * Falls back to an internal-error when the shape is malformed.
+ */
+export 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(
+		RpcErrorCode.InternalError,
+		"Malformed JSON-RPC error envelope",
+		error,
+	);
+}
+
+/**
+ * A domain error shaped like a JSON-RPC error — it carries a numeric `code`. A
+ * server binding can map such a throw to a JSON-RPC error response instead of
+ * collapsing every throw to InternalError.
+ */
+export function isRpcShapedError(
+	err: unknown,
+): err is { code: number; message?: unknown; data?: unknown } {
+	return isObject(err) && typeof err.code === "number";
+}
+
+/** Build an outgoing request envelope. */
+export function buildRequest(
+	method: string,
+	params: unknown,
+	id: JsonRpcId,
+): JsonRpcRequest {
+	return { jsonrpc: "2.0", method, params, id };
+}
+
+/** Build a success response envelope. */
+export function buildSuccess(
+	result: unknown,
+	id: JsonRpcId,
+): JsonRpcSuccessResponse {
+	return { jsonrpc: "2.0", result, id };
+}
+
+/** Build an error response envelope (omits `data` when not supplied). */
+export function buildError(
+	code: number,
+	message: string,
+	id: JsonRpcId,
+	data?: unknown,
+): JsonRpcErrorResponse {
+	return {
+		jsonrpc: "2.0",
+		error: data === undefined ? { code, message } : { code, message, data },
+		id,
+	};
+}
+
+/** Result of {@link parseRequest}. */
+export type ParsedRpcRequest =
+	| { ok: true; method: string; params: unknown; id: JsonRpcId }
+	| { ok: false; response: JsonRpcErrorResponse };
+
+/**
+ * Validate an incoming JSON-RPC envelope and extract `method`/`params`/`id`.
+ * Returns an `InvalidRequest` error response when the version/method are wrong.
+ */
+export function parseRequest(request: unknown): ParsedRpcRequest {
+	if (!isObject(request)) {
+		return {
+			ok: false,
+			response: buildError(
+				RpcErrorCode.InvalidRequest,
+				"Invalid Request",
+				null,
+			),
+		};
+	}
+	const jsonrpc =
+		"jsonrpc" in request && typeof request.jsonrpc === "string"
+			? request.jsonrpc
+			: undefined;
+	const method =
+		"method" in request && typeof request.method === "string"
+			? request.method
+			: undefined;
+	const params = "params" in request ? request.params : undefined;
+	const rawId = "id" in request ? request.id : undefined;
+	const id: JsonRpcId =
+		typeof rawId === "string" || typeof rawId === "number" ? rawId : null;
+	if (jsonrpc !== "2.0" || !method) {
+		return {
+			ok: false,
+			response: buildError(RpcErrorCode.InvalidRequest, "Invalid Request", id),
+		};
+	}
+	return { ok: true, method, params, id };
+}
+
+/**
+ * A JSON-RPC notification is a well-formed request with NO `id` member. The spec
+ * (§4.1) says the server MUST NOT reply to one — it still runs for side-effects.
+ * A malformed object (no method / wrong version) is NOT a notification.
+ */
+export function isNotification(request: unknown): boolean {
+	return (
+		isObject(request) &&
+		"jsonrpc" in request &&
+		request.jsonrpc === "2.0" &&
+		"method" in request &&
+		typeof request.method === "string" &&
+		!("id" in request)
+	);
+}