orange-orm 4.9.1 → 4.10.0-beta.0

package/README.md

@@ -309,6 +309,31 @@ await pool.close();         // closes all pooled connections
 __Why close ?__  
 In serverless environments (e.g. AWS Lambda, Vercel, Cloudflare Workers) execution contexts are frequently frozen and resumed. Explicitly closing the client or pool ensures that file handles are released promptly and prevents “database locked” errors between invocations.  
 
+__SQLite user-defined functions__  
+You can register custom SQLite functions on the connection using `db.function(name, fn)`.  
+
+```javascript
+import map from './map';
+const db = map.sqlite('demo.db');
+
+db.function('add_prefix', (text, prefix) => `${prefix}${text}`);
+
+const rows = await db.query(
+  "select id, name, add_prefix(name, '[VIP] ') as prefixedName from customer"
+);
+```
+
+If you need the function inside a transaction, register it within the transaction callback to ensure it is available on that connection.  
+
+```javascript
+await db.transaction(async (db) => {
+  db.function('add_prefix', (text, prefix) => `${prefix}${text}`);
+  return db.query(
+    "select id, name, add_prefix(name, '[VIP] ') as prefixedName from customer"
+  );
+});
+```
+
 __From the browser__  
 You can securely use Orange from the browser by utilizing the Express plugin, which serves to safeguard sensitive database credentials from exposure at the client level. This technique bypasses the need to transmit raw SQL queries directly from the client to the server. Instead, it logs method calls initiated by the client, which are later replayed and authenticated on the server. This not only reinforces security by preventing the disclosure of raw SQL queries on the client side but also facilitates a smoother operation. Essentially, this method mirrors a traditional REST API, augmented with advanced TypeScript tooling for enhanced functionality. You can read more about it in the section called [In the browser](#user-content-in-the-browser)  
 <sub>📄 server.ts</sub>
@@ -1273,6 +1298,101 @@ async function updateRows() {
 
 }
 
+```
+
+__Row Level Security (Postgres)__  
+You can enforce tenant isolation at the database level by combining Postgres RLS with Express hooks. The example below mirrors the “Interceptors and base filter” style by putting the tenant id in a (fake) token on the client, then extracting it on the server and setting it inside the transaction. This is convenient for a demo because we can seed data and prove rows are filtered. In a real application you must validate signatures and derive tenant id from a trusted identity source, not from arbitrary client input.  
+
+<sub>📄 setup.sql</sub>
+
+```sql
+create role rls_app_user nologin;
+
+create table tenant_data (
+  id serial primary key,
+  tenant_id int not null,
+  value text not null
+);
+
+alter table tenant_data enable row level security;
+create policy tenant_data_tenant on tenant_data
+  using (tenant_id = current_setting('app.tenant_id', true)::int);
+
+grant select, insert, update, delete on tenant_data to rls_app_user;
+
+insert into tenant_data (tenant_id, value) values
+  (1, 'alpha'),
+  (1, 'beta'),
+  (2, 'gamma');
+```
+
+<sub>📄 server.ts</sub>
+
+```javascript
+import map from './map';
+import { json } from 'body-parser';
+import express from 'express';
+import cors from 'cors';
+
+const db = map.postgres('postgres://postgres:postgres@localhost/postgres');
+
+express().disable('x-powered-by')
+  .use(json({ limit: '100mb' }))
+  .use(cors())
+  .use('/orange', validateToken)
+  .use('/orange', db.express({
+    hooks: {
+      transaction: {
+        afterBegin: async (db, req) => {
+          const tenantId = Number.parseInt(String(req.user?.tenantId ?? ''), 10);
+          if (!Number.isFinite(tenantId)) throw new Error('Missing tenant id');
+          await db.query('set local role rls_app_user');
+          await db.query({
+            sql: 'select set_config(\'app.tenant_id\', ?, true)',
+            parameters: [String(tenantId)]
+          });
+        }
+      }
+    }
+  }))
+  .listen(3000, () => console.log('Example app listening on port 3000!'));
+
+function validateToken(req, res, next) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader) return res.status(401).json({ error: 'Authorization header missing' });
+  try {
+    const token = authHeader.replace(/^Bearer\s+/i, '');
+    const payload = decodeFakeJwt(token); // demo-only, do not use in production
+    req.user = { tenantId: String(payload.tenantId) };
+    return next();
+  } catch (error) {
+    return res.status(401).json({ error: 'Invalid token' });
+  }
+}
+
+function decodeFakeJwt(token) {
+  // Demo-only format: "tenant:<id>"
+  const match = /^tenant:(\d+)$/.exec(token);
+  if (!match) throw new Error('Invalid demo token');
+  return { tenantId: Number(match[1]) };
+}
+```
+
+<sub>📄 browser.ts</sub>
+
+```javascript
+import map from './map';
+
+const db = map.http('http://localhost:3000/orange');
+
+db.interceptors.request.use((config) => {
+  // Demo-only token: payload carries the tenant id so we can verify filtering
+  config.headers.Authorization = 'Bearer tenant:1';
+  return config;
+});
+
+const rows = await db.tenant_data.getMany();
+// rows => [{ id: 1, tenant_id: 1, value: 'alpha' }, { id: 2, tenant_id: 1, value: 'beta' }]
 ```
 </details>
 

package/deno.lock

@@ -0,0 +1,76 @@
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@std/assert@*": "1.0.17",
+    "jsr:@std/assert@^1.0.17": "1.0.17",
+    "jsr:@std/internal@^1.0.12": "1.0.12",
+    "jsr:@std/path@*": "1.1.4",
+    "jsr:@std/testing@*": "1.0.17"
+  },
+  "jsr": {
+    "@std/assert@1.0.17": {
+      "integrity": "df5ebfffe77c03b3fa1401e11c762cc8f603d51021c56c4d15a8c7ab45e90dbe",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
+    "@std/internal@1.0.12": {
+      "integrity": "972a634fd5bc34b242024402972cd5143eac68d8dffaca5eaa4dba30ce17b027"
+    },
+    "@std/path@1.1.4": {
+      "integrity": "1d2d43f39efb1b42f0b1882a25486647cb851481862dc7313390b2bb044314b5",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
+    "@std/testing@1.0.17": {
+      "integrity": "87bdc2700fa98249d48a17cd72413352d3d3680dcfbdb64947fd0982d6bbf681",
+      "dependencies": [
+        "jsr:@std/assert@^1.0.17",
+        "jsr:@std/internal"
+      ]
+    }
+  },
+  "workspace": {
+    "packageJson": {
+      "dependencies": [
+        "npm:@cloudflare/workers-types@^4.20241106.0",
+        "npm:@electric-sql/pglite@0.3",
+        "npm:@lroal/on-change@^4.0.2",
+        "npm:@rollup/plugin-commonjs@^28.0.2",
+        "npm:@rollup/plugin-json@^6.1.0",
+        "npm:@rollup/plugin-node-resolve@13",
+        "npm:@tediousjs/connection-string@~0.4.1",
+        "npm:@types/express@^4.17.13",
+        "npm:@types/oracledb@^6.0.4",
+        "npm:@types/tedious@^4.0.14",
+        "npm:@typescript-eslint/eslint-plugin@6",
+        "npm:@typescript-eslint/parser@6",
+        "npm:@vitest/coverage-v8@^3.2.4",
+        "npm:ajv@^8.17.1",
+        "npm:axios@^1.6.2",
+        "npm:better-sqlite3@^11.8.1",
+        "npm:cors@^2.8.5",
+        "npm:eslint-plugin-jest@^27.1.7",
+        "npm:eslint@^8.57.0",
+        "npm:express@^4.18.2",
+        "npm:fast-json-patch@^3.1.1",
+        "npm:findup-sync@5",
+        "npm:glob@^10.3.4 || ^11.0.2",
+        "npm:module-definition@4 || 5 || * || 6",
+        "npm:msnodesqlv8@^4.1.0",
+        "npm:mysql2@^3.9.4",
+        "npm:oracledb@^6.3.0",
+        "npm:owasp-dependency-check@^0.0.21",
+        "npm:pg-query-stream@^3.3.2",
+        "npm:pg@^8.5.1",
+        "npm:rfdc@^1.2.0",
+        "npm:rollup@^2.52.7",
+        "npm:tedious@19",
+        "npm:typescript@^5.4.5",
+        "npm:uuid@^8.3.2 || 9 || 10 || ^11.1.0",
+        "npm:vitest@^3.2.4"
+      ]
+    }
+  }
+}

package/dist/index.browser.mjs

@@ -465,6 +465,7 @@ export interface ExpressConfig {
 	concurrency?: Concurrency;
 	readonly?: boolean;
 	disableBulkDeletes?: boolean;
+	hooks?: ExpressHooks;
 }
 
 export interface ExpressContext {
@@ -473,6 +474,18 @@ export interface ExpressContext {
 	client: RdbClient;
 }		
 
+export interface ExpressTransactionHooks {
+	beforeBegin?: (db: Pool, request: import('express').Request, response: import('express').Response) => void | Promise<void>;
+	afterBegin?: (db: Pool, request: import('express').Request, response: import('express').Response) => void | Promise<void>;
+	beforeCommit?: (db: Pool, request: import('express').Request, response: import('express').Response) => void | Promise<void>;
+	afterCommit?: (db: Pool, request: import('express').Request, response: import('express').Response) => void | Promise<void>;
+	afterRollback?: (db: Pool, request: import('express').Request, response: import('express').Response, error?: unknown) => void | Promise<void>;
+}
+
+export interface ExpressHooks extends ExpressTransactionHooks {
+	transaction?: ExpressTransactionHooks;
+}
+
 export interface ExpressTables {${getExpressTables()}
 }
 `;
@@ -610,13 +623,18 @@ function requireHostExpress () {
 		const dbOptions = { db: options.db || client.db };
 		let c = {};
 		const readonly = { readonly: options.readonly};
+		const sharedHooks = options.hooks;
 		for (let tableName in client.tables) {
+			const tableOptions = options[tableName] || {};
+			const hooks = tableOptions.hooks || sharedHooks;
 			c[tableName] = hostLocal({
 				...dbOptions,
 				...readonly,
-				...options[tableName],
+				...tableOptions,
 				table: client.tables[tableName],
-				isHttp: true, client
+				isHttp: true,
+				client,
+				hooks
 
 			});
 		}
@@ -2200,6 +2218,35 @@ function requireQuery () {
 	return query;
 }
 
+var sqliteFunction;
+var hasRequiredSqliteFunction;
+
+function requireSqliteFunction () {
+	if (hasRequiredSqliteFunction) return sqliteFunction;
+	hasRequiredSqliteFunction = 1;
+	const executeChanges = requireExecuteChanges();
+	const popChanges = requirePopChanges();
+	const getSessionSingleton = requireGetSessionSingleton();
+
+	function executeQueries(context, ...rest) {
+		var changes = popChanges(context);
+
+		return executeChanges(context, changes).then(onDoneChanges);
+
+		function onDoneChanges() {
+			var client = getSessionSingleton(context, 'dbClient');
+			if (client && typeof client.function === 'function')
+				return client.function.apply(client, rest);
+			if (client && typeof client.createFunction === 'function')
+				return client.createFunction.apply(client, rest);
+			throw new Error('SQLite client does not support user-defined functions');
+		}
+	}
+
+	sqliteFunction = executeQueries;
+	return sqliteFunction;
+}
+
 var hostLocal_1;
 var hasRequiredHostLocal;
 
@@ -2210,6 +2257,7 @@ function requireHostLocal () {
 	let getMeta = requireGetMeta();
 	let setSessionSingleton = requireSetSessionSingleton();
 	let executeQuery = requireQuery();
+	let executeSqliteFunction = requireSqliteFunction();
 	let hostExpress = requireHostExpress();
 	const readonlyOps = ['getManyDto', 'getMany', 'aggregate', 'count'];
 	// { db, table, defaultConcurrency,
@@ -2220,9 +2268,12 @@ function requireHostLocal () {
 	// 	disableBulkDeletes, isBrowser }
 	function hostLocal() {
 		const _options = arguments[0];
-		let { table, transaction, db, isHttp } = _options;
+		let { table, transaction, db, isHttp, hooks, client } = _options;
+		const transactionHooks = hooks && hooks.transaction;
+		const getTransactionHook = (name) =>
+			(transactionHooks && transactionHooks[name]) || (hooks && hooks[name]);
 
-		let c = { get, post, patch, query, express };
+		let c = { get, post, patch, query, sqliteFunction, express };
 
 		function get() {
 			return getMeta(table);
@@ -2273,10 +2324,41 @@ function requireHostLocal () {
 					else
 						db = dbPromise;
 				}
-				if (readonlyOps.includes(body.path))
+				const beforeBegin = getTransactionHook('beforeBegin');
+				const afterBegin = getTransactionHook('afterBegin');
+				const beforeCommit = getTransactionHook('beforeCommit');
+				const afterCommit = getTransactionHook('afterCommit');
+				const afterRollback = getTransactionHook('afterRollback');
+				const hasTransactionHooks = !!(beforeBegin
+					|| afterBegin
+					|| beforeCommit
+					|| afterCommit
+					|| afterRollback);
+				if (!hasTransactionHooks && readonlyOps.includes(body.path))
 					await db.transaction({ readonly: true }, fn);
-				else
-					await db.transaction(fn);
+				else {
+					await db.transaction(async (context) => {
+						const hookDb = typeof client === 'function'
+							? client({ transaction: (fn) => fn(context) })
+							: (client || db);
+						if (afterCommit)
+							setSessionSingleton(context, 'afterCommitHook', () =>
+								afterCommit(hookDb, request, response)
+							);
+						if (afterRollback)
+							setSessionSingleton(context, 'afterRollbackHook', (error) =>
+								afterRollback(hookDb, request, response, error)
+							);
+						if (beforeBegin)
+							await beforeBegin(hookDb, request, response);
+						if (afterBegin)
+							await afterBegin(hookDb, request, response);
+						await fn(context);
+						if (beforeCommit)
+							await beforeCommit(hookDb, request, response);
+					});
+				}
+
 			}
 			return result;
 
@@ -2311,6 +2393,31 @@ function requireHostLocal () {
 
 		}
 
+		async function sqliteFunction() {
+			let args = arguments;
+			let result;
+
+			if (transaction)
+				await transaction(fn);
+			else {
+				if (typeof db === 'function') {
+					let dbPromise = db();
+					if (dbPromise.then)
+						db = await dbPromise;
+					else
+						db = dbPromise;
+				}
+				result = await db.sqliteFunction.apply(null, arguments);
+			}
+
+			return result;
+
+			async function fn(...args1) {
+				result = await executeSqliteFunction.apply(null, [...args1, ...args]);
+			}
+
+		}
+
 		function express(client, options) {
 			return hostExpress(hostLocal, client, options);
 		}
@@ -2401,6 +2508,7 @@ function requireNetAdapter () {
 			post,
 			patch,
 			query,
+			sqliteFunction,
 			express
 		};
 
@@ -2456,6 +2564,10 @@ function requireNetAdapter () {
 			throw new Error('Queries are not supported through http');
 		}
 
+		function sqliteFunction() {
+			throw new Error('Sqlite Function is not supported through http');
+		}
+
 		function express() {
 			throw new Error('Hosting in express is not supported on the client side');
 		}
@@ -2469,7 +2581,8 @@ function requireNetAdapter () {
 			get,
 			post,
 			patch,
-			query
+			query,
+			sqliteFunction
 		};
 
 		return c;
@@ -2494,6 +2607,11 @@ function requireNetAdapter () {
 			return adapter.query.apply(null, arguments);
 		}
 
+		async function sqliteFunction() {
+			const adapter = await getInnerAdapter();
+			return adapter.sqliteFunction.apply(null, arguments);
+		}
+
 		async function getInnerAdapter() {
 			const db = await getDb();
 			if (typeof db === 'string') {
@@ -2782,6 +2900,7 @@ function requireClient () {
 			}
 		};
 		client.query = query;
+		client.function = sqliteFunction;
 		client.transaction = runInTransaction;
 		client.db = baseUrl;
 		client.mssql = onProvider.bind(null, 'mssql');
@@ -2870,6 +2989,11 @@ function requireClient () {
 			return adapter.query.apply(null, arguments);
 		}
 
+		async function sqliteFunction() {
+			const adapter = netAdapter(baseUrl, undefined, { tableOptions: { db: baseUrl, transaction } });
+			return adapter.sqliteFunction.apply(null, arguments);
+		}
+
 		function express(arg) {
 			if (providers.express) {
 				return providers.express(client, { ...options, ...arg });
@@ -3553,6 +3677,7 @@ function requireClient () {
 					return;
 
 				let body = stringify({ patch, options: { ...tableOptions, ...concurrencyOptions, strategy, deduceStrategy } });
+
 				let adapter = netAdapter(url, tableName, { axios: axiosInterceptor, tableOptions });
 				let { changed, strategy: newStrategy } = await adapter.patch(body);
 				copyInto(changed, [row]);
@@ -12938,14 +13063,34 @@ function requireCommit () {
 	const getSessionSingleton = requireGetSessionSingleton();
 
 	function _commit(context, result) {
+		let hookError;
 		return popAndPushChanges()
+			.then(callAfterCommit)
 			.then(releaseDbClient.bind(null, context))
-			.then(onReleased);
+			.then(onReleased)
+			.then(throwHookErrorIfAny);
 
 		function onReleased() {
 			return result;
 		}
 
+		function throwHookErrorIfAny(res) {
+			if (hookError)
+				throw hookError;
+			return res;
+		}
+
+		function callAfterCommit() {
+			const hook = getSessionSingleton(context, 'afterCommitHook');
+			if (!hook)
+				return Promise.resolve();
+			return Promise.resolve()
+				.then(() => hook())
+				.catch((e) => {
+					hookError = e;
+				});
+		}
+
 		async function popAndPushChanges() {
 			let changes = popChanges(context);
 			while (changes.length > 0) {
@@ -13046,10 +13191,13 @@ function requireRollback () {
 	const getSessionSingleton = requireGetSessionSingleton();
 
 	function _rollback(context, e) {
+		let hookError;
 		var chain = resultToPromise()
 			.then(() => popChanges(context))
 			.then(executeRollback)
-			.then(() => releaseDbClient(context));
+			.then(callAfterRollback)
+			.then(() => releaseDbClient(context))
+			.then(throwHookErrorIfAny);
 
 
 		function executeRollback() {
@@ -13059,6 +13207,23 @@ function requireRollback () {
 			return executeQuery(context, rollbackCommand);
 		}
 
+		function callAfterRollback() {
+			const hook = getSessionSingleton(context, 'afterRollbackHook');
+			if (!hook)
+				return Promise.resolve();
+			return Promise.resolve()
+				.then(() => hook(e))
+				.catch((err) => {
+					hookError = err;
+				});
+		}
+
+		function throwHookErrorIfAny(res) {
+			if (hookError)
+				throw hookError;
+			return res;
+		}
+
 		if (e) {
 			if (e.message?.indexOf('ORA-01476: divisor is equal to zero') > -1)
 				return newThrow(context, new Error('Conflict when updating a column'), chain);
@@ -13940,6 +14105,7 @@ function requireNewTransaction$2 () {
 		rdb.aggregateCount = 0;
 		rdb.quote = (name) => `"${name}"`;
 		rdb.cache = {};
+		rdb.changes = [];
 
 		if (readonly) {
 			rdb.dbClient = {
@@ -14043,7 +14209,6 @@ function requireBegin () {
 	let setSessionSingleton = requireSetSessionSingleton();
 
 	function begin(context, transactionLess) {
-		setSessionSingleton(context, 'changes', []);
 		if (transactionLess) {
 			setSessionSingleton(context, 'transactionLess', true);
 			return Promise.resolve();
@@ -14840,7 +15005,6 @@ function requireNewDatabase$2 () {
 	let hostLocal = requireHostLocal();
 	let doQuery = requireQuery();
 	let releaseDbClient = requireReleaseDbClient();
-	let setSessionSingleton = requireSetSessionSingleton();
 
 	function newDatabase(d1Database, poolOptions) {
 		if (!d1Database)
@@ -14857,10 +15021,9 @@ function requireNewDatabase$2 () {
 			}
 			let domain = createDomain();
 
-			if (fn)
-				return domain.run(runInTransaction);
-			else
-				return domain.run(run);
+			if (!fn)
+				throw new Error('transaction requires a function');
+			return domain.run(runInTransaction);
 
 			async function runInTransaction() {
 				let result;
@@ -14879,13 +15042,6 @@ function requireNewDatabase$2 () {
 				return _begin(domain, transactionLess);
 			}
 
-			function run() {
-				let p;
-				let transaction = newTransaction(domain, pool, options);
-				p = new Promise(transaction);
-
-				return p.then(begin);
-			}
 
 		};
 
@@ -14913,7 +15069,6 @@ function requireNewDatabase$2 () {
 			let domain = createDomain();
 			let transaction = newTransaction(domain, pool);
 			let p = domain.run(() => new Promise(transaction)
-				.then(() => setSessionSingleton(domain, 'changes', []))
 				.then(() => doQuery(domain, query).then(onResult, onError)));
 			return p;
 
@@ -15358,6 +15513,7 @@ function requireNewTransaction$1 () {
 		rdb.aggregateCount = 0;
 		rdb.quote = quote;
 		rdb.cache = {};
+		rdb.changes = [];
 
 		if (readonly) {
 			rdb.dbClient = {
@@ -15600,7 +15756,6 @@ function requireNewDatabase$1 () {
 	let hostLocal = requireHostLocal();
 	let doQuery = requireQuery();
 	let releaseDbClient = requireReleaseDbClient();
-	let setSessionSingleton = requireSetSessionSingleton();
 
 	function newDatabase(connectionString, poolOptions) {
 		poolOptions = poolOptions || { min: 1 };
@@ -15615,10 +15770,9 @@ function requireNewDatabase$1 () {
 			}
 			let domain = createDomain();
 
-			if (fn)
-				return domain.run(runInTransaction);
-			else
-				return domain.run(run);
+			if (!fn)
+				throw new Error('transaction requires a function');
+			return domain.run(runInTransaction);
 
 			async function runInTransaction() {
 				let result;
@@ -15637,14 +15791,6 @@ function requireNewDatabase$1 () {
 				return _begin(domain, options);
 			}
 
-			function run() {
-				let p;
-				let transaction = newTransaction(domain, pool, options);
-				p = new Promise(transaction);
-
-				return p.then(begin)
-					.then(negotiateSchema);
-			}
 
 			function negotiateSchema(previous) {
 				let schema = options && options.schema;
@@ -15685,7 +15831,6 @@ function requireNewDatabase$1 () {
 			let domain = createDomain();
 			let transaction = newTransaction(domain, pool);
 			let p = domain.run(() => new Promise(transaction)
-				.then(() => setSessionSingleton(domain, 'changes', []))
 				.then(() => doQuery(domain, query).then(onResult, onError)));
 			return p;
 
@@ -15887,6 +16032,7 @@ function requireNewTransaction () {
 		rdb.aggregateCount = 0;
 		rdb.quote = quote;
 		rdb.cache = {};
+		rdb.changes = [];
 
 		if (readonly) {
 			rdb.dbClient = {
@@ -16152,7 +16298,6 @@ function requireNewDatabase () {
 	let hostLocal = requireHostLocal();
 	let doQuery = requireQuery();
 	let releaseDbClient = requireReleaseDbClient();
-	let setSessionSingleton = requireSetSessionSingleton();
 
 	function newDatabase(connectionString, poolOptions) {
 		if (!connectionString)
@@ -16169,10 +16314,9 @@ function requireNewDatabase () {
 			}
 			let domain = createDomain();
 
-			if (fn)
-				return domain.run(runInTransaction);
-			else
-				return domain.run(run);
+			if (!fn)
+				throw new Error('transaction requires a function');
+			return domain.run(runInTransaction);
 
 			async function runInTransaction() {
 				let result;
@@ -16191,15 +16335,6 @@ function requireNewDatabase () {
 				return _begin(domain, options);
 			}
 
-			function run() {
-				let p;
-				let transaction = newTransaction(domain, pool, options);
-				p = new Promise(transaction);
-
-				return p.then(begin)
-					.then(negotiateSchema);
-			}
-
 			function negotiateSchema(previous) {
 				let schema = options && options.schema;
 				if (!schema)
@@ -16239,7 +16374,6 @@ function requireNewDatabase () {
 			let domain = createDomain();
 			let transaction = newTransaction(domain, pool);
 			let p = domain.run(() => new Promise(transaction)
-				.then(() => setSessionSingleton(domain, 'changes', []))
 				.then(() => doQuery(domain, query).then(onResult, onError)));
 			return p;