@supacloud/db 0.2.0 → 0.3.1

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/db",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",