@supacloud/db 0.2.0 → 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/apply.d.ts

@@ -1,16 +1,16 @@
 /**
- * Apply：把 ModulePlan 落到数据库 —— 账本幂等 + advisory lock + 单事务 + catalog 回读验证。
- * 边界与 plan 一致：只管模块声明的可重复 SQL 对象，不做表结构 migration。
+ * Apply: Executes ModulePlan against database - ledger idempotency + advisory lock + single transaction + catalog verification.
+ * Boundary matches plan: handles repeatable SQL objects declared by modules, not table migrations.
  */
 import { type QueryExecutor } from './catalog.js';
 import type { ModulePlan } from './plan.js';
 export interface ApplyResult {
     module: string;
-    /** 实际执行了 SQL 的 step 名 */
+    /** Names of steps whose SQL was executed */
     applied: string[];
-    /** ledger 哈希一致跳过的 */
+    /** Steps skipped because ledger hash matched */
     skipped: string[];
-    /** 应用后在 catalog 中确认存在的对象 */
+    /** Objects confirmed to exist in catalog after apply */
     verified: string[];
     failed?: {
         step: string;

package/dist/catalog.d.ts

@@ -1,13 +1,13 @@
 /**
- * Catalog 读取：通过注入的 QueryExecutor 从 PostgreSQL 系统目录读取真实状态。
- * 所有 SQL 参数化（$1 = schemas 数组），默认只读 public schema。
+ * Catalog reading: Reads real state from PostgreSQL system catalogs via injected QueryExecutor.
+ * All SQL is parameterized ($1 = schemas array), defaulting to public schema.
  */
 import type { PolicyOperation } from './module.js';
 export interface QueryExecutor {
     query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>;
     /**
-     * 可选事务封装：提供时 apply 用它包裹 begin/commit/rollback；
-     * 缺省时退化为在 executor 上顺序执行 begin/commit/rollback 语句（mock 友好）。
+     * Optional transaction wrapper: When provided, apply wraps begin/commit/rollback with it;
+     * when omitted, falls back to sequential begin/commit/rollback on executor (mock-friendly).
      */
     transaction?<T>(fn: (executor: QueryExecutor) => Promise<T>): Promise<T>;
 }
@@ -37,7 +37,7 @@ export interface CatalogTrigger {
     schema: string;
     table: string;
     name: string;
-    /** tgenabled !== 'D'（未被 disable） */
+    /** tgenabled !== 'D' (not disabled) */
     enabled: boolean;
 }
 export interface CatalogGrant {
@@ -53,6 +53,6 @@ export interface DatabaseCatalog {
     triggers: CatalogTrigger[];
     grants: CatalogGrant[];
 }
-/** 从 proconfig（text[]）中提取 search_path=... 配置，无则 null */
+/** Extracts search_path=... setting from proconfig (text[]), or null if unset */
 export declare function extractSearchPath(config: string[] | null): string | null;
 export declare function readCatalog(executor: QueryExecutor, schemas?: string[]): Promise<DatabaseCatalog>;

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/lint.d.ts

@@ -1,5 +1,5 @@
 /**
- * Lint：对 SQL 源文本做正则级静态分析，无需数据库连接。
+ * Lint: Regex-based static analysis of SQL source text without requiring database connection.
  */
 import type { DatabaseModule } from './module.js';
 export interface LintIssue {

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 /**
- * Manifest：把若干 DatabaseModule 汇总为可序列化的数据库治理清单，
- * 并提供 explainObject 做人类可读的对象解释。
+ * Manifest: Aggregates multiple DatabaseModules into a serializable database governance inventory,
+ * and provides explainObject for human-readable object explanation.
  */
 import type { DatabaseModule, FunctionDecl, GrantDecl, PolicyDecl, TriggerDecl } from './module.js';
 export interface DatabaseManifestModule {
@@ -17,7 +17,7 @@ export interface DatabaseManifest {
 }
 export declare function buildDatabaseManifest(modules: DatabaseModule[]): DatabaseManifest;
 /**
- * 按名字解释一个对象：策略（name 或 table.name）、函数（schema.name）、
- * 触发器（name）、归属表（schema.name）、授权对象（schema.name，最后兜底）。
+ * Explains an object by name: policy (name or table.name), function (schema.name),
+ * trigger (name), owning table (schema.name), or granted object (schema.name fallback).
  */
 export declare function explainObject(manifest: DatabaseManifest, name: string): string;

package/dist/module.d.ts

@@ -1,26 +1,26 @@
 /**
- * 模块声明：数据库治理的一等资源（RLS 策略 / RPC 函数 / 触发器 / 授权）。
- * driver 无关，纯声明层。
+ * Module declaration: First-class resources for database governance (RLS policies / RPC functions / triggers / grants).
+ * Driver-agnostic, pure declaration layer.
  */
 export type PolicyOperation = 'select' | 'insert' | 'update' | 'delete' | 'all';
 export interface PolicyDecl {
-    /** 策略名，如 cases_select */
+    /** Policy name, e.g. cases_select */
     name: string;
-    /** 带 schema 的表名：public.cases */
+    /** Schema-qualified table name: public.cases */
     table: string;
     operation: PolicyOperation;
-    /** 适用角色，如 ['authenticated'] */
+    /** Target roles, e.g. ['authenticated'] */
     roles: string[];
-    /** SQL 源文件相对路径 */
+    /** Relative path to SQL source file */
     source: string;
-    /** 测试文件相对路径 */
+    /** Relative path to test file */
     tests?: string[];
 }
 export interface FunctionDecl {
-    /** 带 schema 的函数名：public.case_create */
+    /** Schema-qualified function name: public.case_create */
     name: string;
     source: string;
-    /** 业务权限标识，如 case.create */
+    /** Business permission identifier, e.g. case.create */
     permission?: string;
     transaction?: 'required' | 'none';
     security: 'invoker' | 'definer';
@@ -30,18 +30,18 @@ export interface FunctionDecl {
 }
 export interface TriggerDecl {
     name: string;
-    /** 带 schema 的表名 */
+    /** Schema-qualified table name */
     table: string;
     source: string;
 }
 export interface GrantDecl {
-    /** 带 schema 的对象名：public.cases */
+    /** Schema-qualified object name: public.cases */
     object: string;
     privilege: string;
     role: string;
     source: string;
 }
-/** drizzle Table 的内部结构形状（仅类型层兼容，不 import drizzle-orm） */
+/** Internal structure shape of Drizzle Table (type-level compatibility only, does not import drizzle-orm) */
 export interface DrizzleTableLike {
     _: {
         name: string;
@@ -51,7 +51,7 @@ export interface DrizzleTableLike {
 export type TableRef = string | DrizzleTableLike;
 export interface DatabaseModuleOptions {
     name: string;
-    /** 归属表：drizzle 表对象或带 schema 表名均可 */
+    /** Owning tables: Drizzle table object or schema-qualified table name */
     tables?: TableRef[];
     policies?: PolicyDecl[];
     functions?: FunctionDecl[];
@@ -60,7 +60,7 @@ export interface DatabaseModuleOptions {
 }
 export interface DatabaseModule {
     name: string;
-    /** 归一化为 'schema.name' 形式的表名 */
+    /** Normalized to 'schema.name' table name */
     tables: string[];
     policies: PolicyDecl[];
     functions: FunctionDecl[];

package/dist/plan.d.ts

@@ -1,15 +1,15 @@
 /**
- * Plan：把模块声明的可重复 SQL 对象（函数/策略/触发器/授权）编译为有序执行计划。
- * 边界：只管可重复对象，不做表结构 migration —— 表结构仍走前向 migration。
+ * Plan: Compiles repeatable SQL objects declared by modules (functions/policies/triggers/grants) into ordered execution plans.
+ * Boundary: Handles repeatable objects only; table schema migrations continue forward migrations.
  */
 import type { DatabaseModule } from './module.js';
 export interface PlanStep {
     kind: 'function' | 'policy' | 'trigger' | 'grant';
-    /** 对象标识：函数为 schema 限定名；策略/触发器为 table.name；授权为 object:privilege:role */
+    /** Object identifier: functions use schema-qualified name; policies/triggers use table.name; grants use object:privilege:role */
     name: string;
-    /** 模块相对路径 */
+    /** Relative module path */
     source: string;
-    /** 源文件内容哈希 */
+    /** Source file content hash */
     sha256: string;
     sql: string;
     risk: Array<{
@@ -22,9 +22,9 @@ export interface ModulePlan {
     version: 1;
     module: string;
     createdAt: string;
-    /** 依赖序：function -> policy -> trigger -> grant */
+    /** Dependency order: function -> policy -> trigger -> grant */
     steps: PlanStep[];
-    /** 全部 step sha256 的组合哈希 */
+    /** Combined hash of all step sha256 hashes */
     digest: string;
 }
 export declare function planModule(module: DatabaseModule, readFile: (path: string) => Promise<string>): Promise<ModulePlan>;

package/dist/reconcile.d.ts

@@ -1,5 +1,5 @@
 /**
- * 对账：声明式 Manifest（DatabaseModule）与 PostgreSQL 真实 Catalog 比对。
+ * Reconciliation: Compares declarative Manifest (DatabaseModule) with PostgreSQL live Catalog.
  */
 import type { DatabaseCatalog } from './catalog.js';
 import type { DatabaseModule } from './module.js';
@@ -7,15 +7,15 @@ export interface ReconcileIssue {
     severity: 'error' | 'warn';
     code: string;
     message: string;
-    /** 涉及对象名 */
+    /** Target object name */
     object: string;
 }
 export interface ReconcileReport {
     module: string;
     issues: ReconcileIssue[];
-    /** 无 error 级问题 */
+    /** True if no error-level issues */
     ok: boolean;
 }
-/** 'public.cases' → ['public', 'cases']；无 schema 前缀时默认 public */
+/** 'public.cases' -> ['public', 'cases']; defaults to public when schema prefix is absent */
 export declare function splitQualifiedName(name: string): [string, string];
 export declare function reconcileModule(module: DatabaseModule, catalog: DatabaseCatalog): ReconcileReport;

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.2.0",
+  "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",