@typion/rpc 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simone Ergotino
+
+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

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @typion/rpc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The RPC transport for [Typion](../../typion/docs/README.md) and its browser client: a descriptor (`{ entity, op, input }`), or an
+array of them, posted to one endpoint and answered typed, with no codegen. Install it and list it in the handler's
+`transports`.
+
+```ts
+import { rpc } from '@typion/rpc'
+import { routeHandlers } from 'typion/next'
+import { config } from '@/typion.config.ts'
+
+export const { GET, POST, PATCH, PUT, DELETE, OPTIONS } = await routeHandlers(config, {
+  transports: [rpc()],
+})
+```
+
+```ts
+// a client component: the queries are values that carry their result type
+import { createClient } from '@typion/rpc/client'
+import { postCards } from '@/typion/queries.ts'
+
+const client = createClient({ url: '/api' })
+const cards = await client.run(postCards)
+```
+
+`rpc({ path })` moves the endpoint (`/api/_rpc` by default). A batch runs one descriptor after the other, each in its
+own transaction, and answers `{ results }` with the outcome of each. Every descriptor is checked by the core before it
+runs, as REST routes are. The client imports no server code and no Drizzle; a failed call throws `TypionRequestError`
+with the wire error's `code`, `status` and `issues`.

package/dist/client.d.ts

@@ -0,0 +1,28 @@
+import { AnyDescriptor, InferResult, Jsonified, WireError, WireErrorCode } from "typion/contract";
+//#region src/client.d.ts
+export type ClientResult<D extends AnyDescriptor> = Jsonified<InferResult<D>>;
+export declare class TypionRequestError extends Error {
+  readonly code: WireErrorCode | 'TRANSPORT';
+  readonly status: number;
+  readonly entity: string | undefined;
+  readonly issues: WireError['issues'];
+  readonly details: Record<string, unknown> | undefined;
+  constructor(error: WireError | {
+    code: 'TRANSPORT';
+    status: number;
+    message: string;
+  });
+}
+export type ClientHeaders = Record<string, string> | Headers;
+export type ClientOptions = {
+  url?: string;
+  headers?: ClientHeaders | (() => ClientHeaders | Promise<ClientHeaders>);
+  fetch?: (input: string, init: RequestInit) => Response | Promise<Response>;
+};
+export type TypionClient = {
+  run<D extends AnyDescriptor>(descriptor: D): Promise<ClientResult<D>>;
+  runAll<const D extends readonly AnyDescriptor[]>(descriptors: D): Promise<{ [K in keyof D]: ClientResult<Extract<D[K], AnyDescriptor>>; }>;
+};
+export declare function createClient(options?: ClientOptions): TypionClient;
+//#endregion
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,67 @@
+//#region src/client.ts
+var TypionRequestError = class extends Error {
+	code;
+	status;
+	entity;
+	issues;
+	details;
+	constructor(error) {
+		super(error.message);
+		this.name = "TypionRequestError";
+		this.code = error.code;
+		this.status = error.status;
+		this.entity = "entity" in error ? error.entity : void 0;
+		this.issues = "issues" in error ? error.issues : void 0;
+		this.details = "details" in error ? error.details : void 0;
+	}
+};
+function createClient(options = {}) {
+	const base = (options.url ?? "/api").replace(/\/$/, "");
+	const doFetch = options.fetch ?? globalThis.fetch;
+	const post = async (body) => {
+		const extra = typeof options.headers === "function" ? await options.headers() : options.headers;
+		const headers = new Headers(extra === void 0 ? void 0 : extra);
+		headers.set("content-type", "application/json");
+		let response;
+		try {
+			response = await doFetch(`${base}/_rpc`, {
+				method: "POST",
+				headers,
+				body: JSON.stringify(body)
+			});
+		} catch (cause) {
+			throw new TypionRequestError({
+				code: "TRANSPORT",
+				status: 0,
+				message: cause instanceof Error ? cause.message : String(cause)
+			});
+		}
+		const payload = await response.json().catch(() => null);
+		if (payload === null || typeof payload !== "object") throw new TypionRequestError({
+			code: "TRANSPORT",
+			status: response.status,
+			message: `The handler at ${base}/_rpc answered ${response.status} with no envelope`
+		});
+		return payload;
+	};
+	const unwrap = (envelope) => {
+		if ("error" in envelope) throw new TypionRequestError(envelope.error);
+		return envelope.data;
+	};
+	return {
+		run: async (descriptor) => unwrap(await post(descriptor)),
+		runAll: async (descriptors) => {
+			const payload = await post(descriptors);
+			if (!Array.isArray(payload.results)) throw new TypionRequestError({
+				code: "TRANSPORT",
+				status: 200,
+				message: "A batch answered without `results`"
+			});
+			return payload.results.map((envelope) => unwrap(envelope));
+		}
+	};
+}
+//#endregion
+export { TypionRequestError, createClient };
+
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import type {\n  AnyDescriptor,\n  InferResult,\n  Jsonified,\n  WireEnvelope,\n  WireError,\n  WireErrorCode,\n} from 'typion/contract'\n\n// The browser half of the HTTP handler: it posts descriptors to `/_rpc` and gives back what their type says.\n// It imports the contract only, so no Drizzle and no engine runtime reach the bundle.\n\nexport type ClientResult<D extends AnyDescriptor> = Jsonified<InferResult<D>>\n\nexport class TypionRequestError extends Error {\n  // `UNAUTHENTICATED` when the caller has not signed in: the page asks them to.\n  readonly code: WireErrorCode | 'TRANSPORT'\n  readonly status: number\n  readonly entity: string | undefined\n  readonly issues: WireError['issues']\n  readonly details: Record<string, unknown> | undefined\n\n  constructor(error: WireError | { code: 'TRANSPORT'; status: number; message: string }) {\n    super(error.message)\n    this.name = 'TypionRequestError'\n    this.code = error.code\n    this.status = error.status\n    this.entity = 'entity' in error ? error.entity : undefined\n    this.issues = 'issues' in error ? error.issues : undefined\n    this.details = 'details' in error ? error.details : undefined\n  }\n}\n\nexport type ClientHeaders = Record<string, string> | Headers\n\nexport type ClientOptions = {\n  // Where the handler is mounted; `/_rpc` is appended to it.\n  url?: string\n  // Resolved per request, so a token that changes is read at call time.\n  headers?: ClientHeaders | (() => ClientHeaders | Promise<ClientHeaders>)\n  // Any function shaped like `fetch`, a test's in-process one included (Hono's `app.request`, which may answer\n  // without a promise).\n  fetch?: (input: string, init: RequestInit) => Response | Promise<Response>\n}\n\nexport type TypionClient = {\n  run<D extends AnyDescriptor>(descriptor: D): Promise<ClientResult<D>>\n  // One request, one result per descriptor, in order; a descriptor that fails throws where it is read.\n  runAll<const D extends readonly AnyDescriptor[]>(\n    descriptors: D,\n  ): Promise<{ [K in keyof D]: ClientResult<Extract<D[K], AnyDescriptor>> }>\n}\n\nexport function createClient(options: ClientOptions = {}): TypionClient {\n  const base = (options.url ?? '/api').replace(/\\/$/, '')\n  const doFetch = options.fetch ?? globalThis.fetch\n\n  const post = async (body: unknown): Promise<unknown> => {\n    const extra = typeof options.headers === 'function' ? await options.headers() : options.headers\n    const headers = new Headers(extra === undefined ? undefined : extra)\n    headers.set('content-type', 'application/json')\n    let response: Response\n    try {\n      response = await doFetch(`${base}/_rpc`, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(body),\n      })\n    } catch (cause) {\n      throw new TypionRequestError({\n        code: 'TRANSPORT',\n        status: 0,\n        message: cause instanceof Error ? cause.message : String(cause),\n      })\n    }\n    const payload: unknown = await response.json().catch(() => null)\n    if (payload === null || typeof payload !== 'object') {\n      throw new TypionRequestError({\n        code: 'TRANSPORT',\n        status: response.status,\n        message: `The handler at ${base}/_rpc answered ${response.status} with no envelope`,\n      })\n    }\n    return payload\n  }\n\n  const unwrap = <T>(envelope: WireEnvelope<T>): T => {\n    if ('error' in envelope) throw new TypionRequestError(envelope.error)\n    return envelope.data\n  }\n\n  return {\n    run: async (descriptor) => unwrap(await (post(descriptor) as Promise<WireEnvelope<never>>)),\n    runAll: async (descriptors) => {\n      const payload = (await post(descriptors)) as { results?: WireEnvelope<unknown>[] }\n      if (!Array.isArray(payload.results)) {\n        throw new TypionRequestError({\n          code: 'TRANSPORT',\n          status: 200,\n          message: 'A batch answered without `results`',\n        })\n      }\n      return payload.results.map((envelope) => unwrap(envelope)) as never\n    },\n  }\n}\n"],"mappings":";AAcA,IAAa,qBAAb,cAAwC,MAAM;CAE5C;CACA;CACA;CACA;CACA;CAEA,YAAY,OAA2E;EACrF,MAAM,MAAM,OAAO;EACnB,KAAK,OAAO;EACZ,KAAK,OAAO,MAAM;EAClB,KAAK,SAAS,MAAM;EACpB,KAAK,SAAS,YAAY,QAAQ,MAAM,SAAS,KAAA;EACjD,KAAK,SAAS,YAAY,QAAQ,MAAM,SAAS,KAAA;EACjD,KAAK,UAAU,aAAa,QAAQ,MAAM,UAAU,KAAA;CACtD;AACF;AAsBA,SAAgB,aAAa,UAAyB,CAAC,GAAiB;CACtE,MAAM,QAAQ,QAAQ,OAAO,OAAA,CAAQ,QAAQ,OAAO,EAAE;CACtD,MAAM,UAAU,QAAQ,SAAS,WAAW;CAE5C,MAAM,OAAO,OAAO,SAAoC;EACtD,MAAM,QAAQ,OAAO,QAAQ,YAAY,aAAa,MAAM,QAAQ,QAAQ,IAAI,QAAQ;EACxF,MAAM,UAAU,IAAI,QAAQ,UAAU,KAAA,IAAY,KAAA,IAAY,KAAK;EACnE,QAAQ,IAAI,gBAAgB,kBAAkB;EAC9C,IAAI;EACJ,IAAI;GACF,WAAW,MAAM,QAAQ,GAAG,KAAK,QAAQ;IACvC,QAAQ;IACR;IACA,MAAM,KAAK,UAAU,IAAI;GAC3B,CAAC;EACH,SAAS,OAAO;GACd,MAAM,IAAI,mBAAmB;IAC3B,MAAM;IACN,QAAQ;IACR,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;GAChE,CAAC;EACH;EACA,MAAM,UAAmB,MAAM,SAAS,KAAK,CAAC,CAAC,YAAY,IAAI;EAC/D,IAAI,YAAY,QAAQ,OAAO,YAAY,UACzC,MAAM,IAAI,mBAAmB;GAC3B,MAAM;GACN,QAAQ,SAAS;GACjB,SAAS,kBAAkB,KAAK,iBAAiB,SAAS,OAAO;EACnE,CAAC;EAEH,OAAO;CACT;CAEA,MAAM,UAAa,aAAiC;EAClD,IAAI,WAAW,UAAU,MAAM,IAAI,mBAAmB,SAAS,KAAK;EACpE,OAAO,SAAS;CAClB;CAEA,OAAO;EACL,KAAK,OAAO,eAAe,OAAO,MAAO,KAAK,UAAU,CAAkC;EAC1F,QAAQ,OAAO,gBAAgB;GAC7B,MAAM,UAAW,MAAM,KAAK,WAAW;GACvC,IAAI,CAAC,MAAM,QAAQ,QAAQ,OAAO,GAChC,MAAM,IAAI,mBAAmB;IAC3B,MAAM;IACN,QAAQ;IACR,SAAS;GACX,CAAC;GAEH,OAAO,QAAQ,QAAQ,KAAK,aAAa,OAAO,QAAQ,CAAC;EAC3D;CACF;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { Transport } from "typion/http";
+//#region src/index.d.ts
+export type RpcOptions = {
+  path?: string;
+};
+export declare function rpc(options?: RpcOptions): Transport;
+//#endregion
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,23 @@
+//#region src/index.ts
+function rpc(options = {}) {
+	const path = options.path ?? "_rpc";
+	return {
+		name: "rpc",
+		async handle(call) {
+			if (call.method !== "POST" || call.segments.length !== 1 || call.segments[0] !== path) return;
+			const payload = await call.body();
+			if (!Array.isArray(payload)) return call.respond(200, { data: await call.run(call.descriptor(payload)) });
+			const results = [];
+			for (const item of payload) try {
+				results.push({ data: await call.run(call.descriptor(item)) });
+			} catch (error) {
+				results.push({ error: call.error(error) });
+			}
+			return call.respond(200, { results });
+		}
+	};
+}
+//#endregion
+export { rpc };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Transport } from 'typion/http'\n\nexport type RpcOptions = {\n  // The segment below the handler's base path; `_rpc` by default, which is what the client posts to.\n  path?: string\n}\n\n// One descriptor, or an array of them run one after the other, each in its own transaction: what the browser\n// client and `defineQueries` speak. Every descriptor is checked by the core before it runs, as REST routes are.\nexport function rpc(options: RpcOptions = {}): Transport {\n  const path = options.path ?? '_rpc'\n  return {\n    name: 'rpc',\n    async handle(call) {\n      if (call.method !== 'POST' || call.segments.length !== 1 || call.segments[0] !== path) {\n        return undefined\n      }\n      const payload = await call.body()\n      if (!Array.isArray(payload)) {\n        return call.respond(200, { data: await call.run(call.descriptor(payload)) })\n      }\n      const results: unknown[] = []\n      for (const item of payload) {\n        try {\n          results.push({ data: await call.run(call.descriptor(item)) })\n        } catch (error) {\n          results.push({ error: call.error(error) })\n        }\n      }\n      return call.respond(200, { results })\n    },\n  }\n}\n"],"mappings":";AASA,SAAgB,IAAI,UAAsB,CAAC,GAAc;CACvD,MAAM,OAAO,QAAQ,QAAQ;CAC7B,OAAO;EACL,MAAM;EACN,MAAM,OAAO,MAAM;GACjB,IAAI,KAAK,WAAW,UAAU,KAAK,SAAS,WAAW,KAAK,KAAK,SAAS,OAAO,MAC/E;GAEF,MAAM,UAAU,MAAM,KAAK,KAAK;GAChC,IAAI,CAAC,MAAM,QAAQ,OAAO,GACxB,OAAO,KAAK,QAAQ,KAAK,EAAE,MAAM,MAAM,KAAK,IAAI,KAAK,WAAW,OAAO,CAAC,EAAE,CAAC;GAE7E,MAAM,UAAqB,CAAC;GAC5B,KAAK,MAAM,QAAQ,SACjB,IAAI;IACF,QAAQ,KAAK,EAAE,MAAM,MAAM,KAAK,IAAI,KAAK,WAAW,IAAI,CAAC,EAAE,CAAC;GAC9D,SAAS,OAAO;IACd,QAAQ,KAAK,EAAE,OAAO,KAAK,MAAM,KAAK,EAAE,CAAC;GAC3C;GAEF,OAAO,KAAK,QAAQ,KAAK,EAAE,QAAQ,CAAC;EACtC;CACF;AACF"}

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@typion/rpc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "An RPC endpoint for Typion, and its browser client: descriptors posted and answered typed",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/the-escape-studio/typion.git",
+    "directory": "packages/transports/rpc"
+  },
+  "homepage": "https://github.com/the-escape-studio/typion/tree/main/packages/transports/rpc#readme",
+  "bugs": {
+    "url": "https://github.com/the-escape-studio/typion/issues"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "typion": "^0.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
 }