postgrest-parser 0.1.1 → 0.2.0

package/pkg/postgrest_parser.d.ts

@@ -39,6 +39,43 @@ export class WasmQueryResult {
  */
 export function buildFilterClause(filters_json: any): any;
 
+/**
+ * Clear all schema cache entries, freeing all cached memory.
+ *
+ * Useful as a safety net during shutdown or when all tenants are being evicted.
+ *
+ * # Example (TypeScript)
+ *
+ * ```typescript
+ * import { clearAllSchemas } from './pkg/postgrest_parser.js';
+ *
+ * // Clear everything on shutdown
+ * clearAllSchemas();
+ * ```
+ */
+export function clearAllSchemas(): void;
+
+/**
+ * Clear a schema cache entry, freeing its memory.
+ *
+ * Call this when a tenant is paused or evicted to prevent memory leaks.
+ * If the schema ID does not exist, this is a no-op.
+ *
+ * # Arguments
+ *
+ * * `schema_id` - The schema key to remove. If empty, removes "default".
+ *
+ * # Example (TypeScript)
+ *
+ * ```typescript
+ * import { clearSchema } from './pkg/postgrest_parser.js';
+ *
+ * // Clear a tenant's schema when they are paused/evicted
+ * clearSchema("tenant-123");
+ * ```
+ */
+export function clearSchema(schema_id: string): void;
+
 /**
  * Initialize schema cache from a database query executor.
  *
@@ -46,8 +83,18 @@ export function buildFilterClause(filters_json: any): any;
  * and returns results. The schema introspection queries will be executed via
  * this callback to populate the relationship cache.
  *
+ * # Trust
+ *
+ * The `query_executor` is **fully trusted**. It receives a hardcoded SQL
+ * introspection query and its result is used verbatim to build the FK cache.
+ * Only pass executors that connect to the correct tenant database.
+ *
  * # Arguments
  *
+ * * `schema_id` - A unique key to store this schema under (e.g., tenant ID).
+ *   If empty, uses "default". Callers must ensure schema IDs are not
+ *   attacker-controlled — passing another tenant's ID would overwrite their
+ *   cached schema.
  * * `query_executor` - An async JavaScript function with signature:
  *   `async (sql: string) => { rows: any[] }`
  *
@@ -65,11 +112,11 @@ export function buildFilterClause(filters_json: any): any;
  *   return { rows: result.rows };
  * };
  *
- * // Initialize schema from database
- * await initSchemaFromDb(queryExecutor);
+ * // Initialize schema for a specific tenant
+ * await initSchemaFromDb("tenant-123", queryExecutor);
  * ```
  */
-export function initSchemaFromDb(query_executor: Function): Promise<void>;
+export function initSchemaFromDb(schema_id: string, query_executor: Function): Promise<void>;
 
 /**
  * Initialize WASM module (call this first from JavaScript)
@@ -84,16 +131,9 @@ export function init_panic_hook(): void;
  * * `table` - The table name
  * * `query_string` - Query string with filters and optional returning
  * * `headers` - Optional headers as JSON string
- *
- * # Example (TypeScript)
- *
- * ```typescript
- * const result = parseDelete("users", "id=eq.123&returning=id", null);
- * console.log(result.query);   // DELETE FROM "users" WHERE ...
- * console.log(result.params);  // ["123"]
- * ```
+ * * `schema_id` - Optional schema cache key for per-tenant schema resolution
  */
-export function parseDelete(table: string, query_string: string, headers?: string | null): WasmQueryResult;
+export function parseDelete(table: string, query_string: string, headers?: string | null, schema_id?: string | null): WasmQueryResult;
 
 /**
  * Parse and generate SQL for an INSERT operation.
@@ -104,20 +144,9 @@ export function parseDelete(table: string, query_string: string, headers?: strin
  * * `body` - JSON body (single object or array of objects)
  * * `query_string` - Optional query string for returning, on_conflict, etc.
  * * `headers` - Optional headers as JSON string (e.g., '{"Prefer":"return=representation"}')
- *
- * # Example (TypeScript)
- *
- * ```typescript
- * const result = parseInsert("users",
- *   JSON.stringify({ name: "Alice", email: "alice@example.com" }),
- *   "on_conflict=email&returning=id,name",
- *   JSON.stringify({ Prefer: "return=representation" })
- * );
- * console.log(result.query);   // INSERT INTO "users" ...
- * console.log(result.params);  // ["Alice", "alice@example.com"]
- * ```
+ * * `schema_id` - Optional schema cache key for per-tenant schema resolution
  */
-export function parseInsert(table: string, body: string, query_string?: string | null, headers?: string | null): WasmQueryResult;
+export function parseInsert(table: string, body: string, query_string?: string | null, headers?: string | null, schema_id?: string | null): WasmQueryResult;
 
 /**
  * Parse only the query string without generating SQL.
@@ -141,21 +170,13 @@ export function parseOnly(query_string: string): any;
  *
  * * `table` - The table name to query
  * * `query_string` - The PostgREST query string (e.g., "select=id,name&age=gte.18")
+ * * `schema_id` - Optional schema cache key for per-tenant schema resolution
  *
  * # Returns
  *
  * Returns a `WasmQueryResult` containing the SQL query, parameters, and affected tables.
- *
- * # Example (TypeScript)
- *
- * ```typescript
- * const result = parseQueryString("users", "age=gte.18&status=eq.active");
- * console.log(result.query);   // SELECT * FROM "users" WHERE ...
- * console.log(result.params);  // ["18", "active"]
- * console.log(result.tables);  // ["users"]
- * ```
  */
-export function parseQueryString(table: string, query_string: string): WasmQueryResult;
+export function parseQueryString(table: string, query_string: string, schema_id?: string | null): WasmQueryResult;
 
 /**
  * Parse a complete HTTP request and generate appropriate SQL.
@@ -170,28 +191,11 @@ export function parseQueryString(table: string, query_string: string): WasmQuery
  * * `query_string` - URL query string
  * * `body` - Request body as JSON string (or null)
  * * `headers` - Optional headers as JSON object (for Prefer header)
- *
- * # Example (TypeScript)
- *
- * ```typescript
- * // SELECT query
- * const getResult = parseRequest("GET", "users", "age=gte.18&limit=10", null, null);
- *
- * // INSERT with upsert
- * const postResult = parseRequest("POST", "users", "on_conflict=email",
- *   JSON.stringify({ name: "Alice", email: "alice@example.com" }),
- *   JSON.stringify({ Prefer: "return=representation" })
- * );
- *
- * // RPC call
- * const rpcResult = parseRequest("POST", "rpc/my_function",
- *   "select=result",
- *   JSON.stringify({ arg1: "value" }),
- *   null
- * );
- * ```
+ * * `schema_id` - Optional schema cache key for per-tenant schema resolution.
+ *   Must match a key previously passed to [`init_schema_from_db`]. If not
+ *   provided, falls back to the "default" cache entry (if one exists).
  */
-export function parseRequest(method: string, path: string, query_string: string, body?: string | null, headers?: string | null): WasmQueryResult;
+export function parseRequest(method: string, path: string, query_string: string, body?: string | null, headers?: string | null, schema_id?: string | null): WasmQueryResult;
 
 /**
  * Parse and generate SQL for an RPC (stored procedure/function) call.
@@ -202,20 +206,9 @@ export function parseRequest(method: string, path: string, query_string: string,
  * * `body` - JSON object with function arguments (or null for no args)
  * * `query_string` - Optional query string for filtering/ordering results
  * * `headers` - Optional headers as JSON string
- *
- * # Example (TypeScript)
- *
- * ```typescript
- * const result = parseRpc("calculate_total",
- *   JSON.stringify({ order_id: 123, tax_rate: 0.08 }),
- *   "select=total,tax&limit=1",
- *   null
- * );
- * console.log(result.query);   // SELECT * FROM calculate_total(...)
- * console.log(result.params);  // [123, 0.08]
- * ```
+ * * `schema_id` - Optional schema cache key for per-tenant schema resolution
  */
-export function parseRpc(function_name: string, body?: string | null, query_string?: string | null, headers?: string | null): WasmQueryResult;
+export function parseRpc(function_name: string, body?: string | null, query_string?: string | null, headers?: string | null, schema_id?: string | null): WasmQueryResult;
 
 /**
  * Parse and generate SQL for an UPDATE operation.
@@ -226,20 +219,9 @@ export function parseRpc(function_name: string, body?: string | null, query_stri
  * * `body` - JSON object with fields to update
  * * `query_string` - Query string with filters and optional returning
  * * `headers` - Optional headers as JSON string
- *
- * # Example (TypeScript)
- *
- * ```typescript
- * const result = parseUpdate("users",
- *   JSON.stringify({ status: "active" }),
- *   "id=eq.123&returning=id,status",
- *   null
- * );
- * console.log(result.query);   // UPDATE "users" SET ...
- * console.log(result.params);  // ["active", "123"]
- * ```
+ * * `schema_id` - Optional schema cache key for per-tenant schema resolution
  */
-export function parseUpdate(table: string, body: string, query_string: string, headers?: string | null): WasmQueryResult;
+export function parseUpdate(table: string, body: string, query_string: string, headers?: string | null, schema_id?: string | null): WasmQueryResult;
 
 export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
 
@@ -247,26 +229,28 @@ export interface InitOutput {
     readonly memory: WebAssembly.Memory;
     readonly __wbg_wasmqueryresult_free: (a: number, b: number) => void;
     readonly buildFilterClause: (a: number, b: number) => void;
-    readonly initSchemaFromDb: (a: number) => number;
-    readonly parseDelete: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
-    readonly parseInsert: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly clearAllSchemas: () => void;
+    readonly clearSchema: (a: number, b: number) => void;
+    readonly initSchemaFromDb: (a: number, b: number, c: number) => number;
+    readonly parseDelete: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly parseInsert: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
     readonly parseOnly: (a: number, b: number, c: number) => void;
-    readonly parseQueryString: (a: number, b: number, c: number, d: number, e: number) => void;
-    readonly parseRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
-    readonly parseRpc: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
-    readonly parseUpdate: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
+    readonly parseQueryString: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+    readonly parseRequest: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number) => void;
+    readonly parseRpc: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
+    readonly parseUpdate: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void;
     readonly wasmqueryresult_params: (a: number) => number;
     readonly wasmqueryresult_query: (a: number, b: number) => void;
     readonly wasmqueryresult_tables: (a: number) => number;
     readonly wasmqueryresult_toJSON: (a: number) => number;
     readonly init_panic_hook: () => void;
-    readonly __wasm_bindgen_func_elem_363: (a: number, b: number) => void;
-    readonly __wasm_bindgen_func_elem_443: (a: number, b: number, c: number, d: number) => void;
-    readonly __wasm_bindgen_func_elem_364: (a: number, b: number, c: number) => void;
+    readonly __wasm_bindgen_func_elem_403: (a: number, b: number, c: number, d: number) => void;
+    readonly __wasm_bindgen_func_elem_408: (a: number, b: number, c: number, d: number) => void;
     readonly __wbindgen_export: (a: number, b: number) => number;
     readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
     readonly __wbindgen_export3: (a: number) => void;
     readonly __wbindgen_export4: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_export5: (a: number, b: number) => void;
     readonly __wbindgen_add_to_stack_pointer: (a: number) => number;
     readonly __wbindgen_start: () => void;
 }