@supacloud/db 0.3.1 → 0.5.0

package/README.md

@@ -79,6 +79,40 @@ const userDb = await database.forUser(requireTrustedIdentity(requestContext));
 const workerDb = await database.forService("scheduled-worker");
 ```
 
+### Typed RPC boundary
+
+`createRpcClient(transport, contracts)` validates arguments before transport and results
+before returning them. Names, arguments and results are inferred from the registry;
+callers cannot supply an arbitrary result type. It uses the supplied client without
+changing its identity, RLS policy or credentials.
+
+```ts
+import { createRpcClient, defineRpcContract } from '@supacloud/db';
+
+const rpc = createRpcClient(userDb, {
+  case_create: defineRpcContract({
+    args: decodeCreateCaseArgs,
+    result: decodeCreatedCase,
+  }),
+});
+const result = await rpc.call('case_create', { title: 'Investigation' });
+if (result.ok) {
+  console.log(result.data);
+} else {
+  handleDatabaseFailure(result.error);
+}
+```
+
+Decoders must accept `unknown`, validate it at runtime and throw on invalid values.
+They may project extra fields away. Schema libraries such as TypeBox can supply
+these functions; this driver-independent package adds no schema-library dependency.
+Database failures bypass result decoding. Contract failures throw `RpcContractError`
+with a phase and no raw payload or decoder error. Calls are never retried automatically,
+including result-validation failures after a potentially committed command.
+
+This is an explicit contract boundary, not inference of JSONB fields from SQL,
+authorization, migration execution or automatic HTTP client generation.
+
 ## 诊断码
 
 ### 对账（reconcile）

package/dist/index.d.ts

@@ -6,3 +6,4 @@ export { planModule, type ModulePlan, type PlanStep } from './plan.js';
 export { applyModulePlan, type ApplyResult } from './apply.js';
 export { buildDatabaseManifest, explainObject, type DatabaseManifest, type DatabaseManifestModule, } from './manifest.js';
 export { createDatabaseAccessBoundary, DatabaseAccessError, type AuthenticatedDatabaseIdentity, type DatabaseAccessBoundary, type DatabaseAccessBoundaryOptions, type DatabaseAccessErrorCode, } from './access.js';
+export { createRpcClient, defineRpcContract, RpcContractError, type RpcArgs, type RpcCallResult, type RpcContract, type RpcDecoder, type RpcResult, type RpcTransport, } from './rpc.js';

package/dist/index.js

@@ -682,12 +682,66 @@ function createDatabaseAccessBoundary(options) {
     }
   };
 }
+// src/rpc.ts
+class RpcContractError extends Error {
+  rpcName;
+  phase;
+  code = "RPC_CONTRACT_INVALID";
+  constructor(rpcName, phase) {
+    super(`RPC contract validation failed (${phase})`);
+    this.rpcName = rpcName;
+    this.phase = phase;
+    this.name = "RpcContractError";
+  }
+}
+function defineRpcContract(contract) {
+  return Object.freeze({ ...contract });
+}
+function createRpcClient(transport, contracts) {
+  const registered = new Map(Object.entries(contracts).map(([name, contract]) => [
+    name,
+    defineRpcContract(contract)
+  ]));
+  return {
+    async call(name, args) {
+      const contract = registered.get(name);
+      if (!contract)
+        throw new RpcContractError(name, "registration");
+      let decodedArgs;
+      try {
+        decodedArgs = contract.args(args);
+        if (!decodedArgs || typeof decodedArgs !== "object" || Array.isArray(decodedArgs)) {
+          throw new TypeError("RPC arguments must decode to an object");
+        }
+      } catch {
+        throw new RpcContractError(name, "args");
+      }
+      const response = await transport.rpc(name, decodedArgs);
+      if (!response || typeof response !== "object" || Array.isArray(response) || !Object.hasOwn(response, "error")) {
+        throw new RpcContractError(name, "result");
+      }
+      if (response.error != null)
+        return { ok: false, data: null, error: response.error };
+      if (!Object.hasOwn(response, "data"))
+        throw new RpcContractError(name, "result");
+      try {
+        const data = contract.result(response.data);
+        return { ok: true, data, error: null };
+      } catch {
+        throw new RpcContractError(name, "result");
+      }
+    }
+  };
+}
 export {
   DatabaseAccessError,
+  RpcContractError,
   applyModulePlan,
   buildDatabaseManifest,
   createDatabaseAccessBoundary,
+  createRpcClient,
   defineDatabaseModule,
+  defineRpcContract,
   explainObject,
   extractSearchPath,
   lintModule,

package/dist/rpc.d.ts

@@ -0,0 +1,34 @@
+export type RpcDecoder<T> = (value: unknown) => T;
+export interface RpcContract<Args extends Record<string, unknown>, Result> {
+    args: RpcDecoder<Args>;
+    result: RpcDecoder<Result>;
+}
+export type RpcArgs<Contract> = Contract extends RpcContract<infer Args, unknown> ? Args : never;
+export type RpcResult<Contract> = Contract extends RpcContract<Record<string, unknown>, infer Result> ? Result : never;
+export interface RpcTransport {
+    rpc(name: string, args: Record<string, unknown>): PromiseLike<{
+        data: unknown;
+        error: unknown;
+    }>;
+}
+export type RpcCallResult<T> = {
+    ok: true;
+    data: T;
+    error: null;
+} | {
+    ok: false;
+    data: null;
+    error: unknown;
+};
+export declare class RpcContractError extends Error {
+    readonly rpcName: string;
+    readonly phase: 'registration' | 'args' | 'result';
+    readonly code = "RPC_CONTRACT_INVALID";
+    constructor(rpcName: string, phase: 'registration' | 'args' | 'result');
+}
+export declare function defineRpcContract<Args extends Record<string, unknown>, Result>(contract: RpcContract<Args, Result>): Readonly<RpcContract<Args, Result>>;
+type Contracts = Record<string, RpcContract<Record<string, unknown>, unknown>>;
+export declare function createRpcClient<const Registry extends Contracts>(transport: RpcTransport, contracts: Registry): {
+    call<Name extends Extract<keyof Registry, string>>(name: Name, args: RpcArgs<Registry[NoInfer<Name>]>): Promise<RpcCallResult<RpcResult<Registry[Name]>>>;
+};
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/db",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Database governance layer for SupaCloud: RLS policies, RPC functions and grants as first-class resources, with manifest/catalog reconciliation",
   "type": "module",
   "main": "./dist/index.js",