web_plsql 1.2.0 → 1.3.1

package/README.md

@@ -59,10 +59,10 @@ Access the console at `http://localhost:<port>/admin` (e.g., `http://localhost:8
 # Configuration
 
 There are 2 options on how to use the web_plsql express middleware:
-- Use the predefined `startServer` api in `src/server.js` like in the `examples/config-native.js` example
-- Hand craft a new Express server using the `handlerWebPlSql` middleware in `src/handlerPlSql.js`
+- Use the predefined `startServer` api in `dist/backend/index.js` like in the `examples/config-native.js` example
+- Hand craft a new Express server using the `handlerWebPlSql` middleware in `dist/backend/index.js`
 
-## Use the predefined `startServer`
+## Use the predefined `startServer` function
 
 The `startServer` api uses the following configuration object:
 
@@ -121,9 +121,104 @@ The `startServer` api uses the following configuration object:
  */
 ```
 
-## Hand craft a new Express server using the `handlerWebPlSql` middleware
+## Hand Craft Express Server with Composable Middleware
 
-WIP
+web_plsql exports composable middleware components that can be integrated into any Express application.
+
+### Complete Manual Setup
+
+For full control over your Express application with PL/SQL routes and admin console:
+
+```typescript
+import express from 'express';
+import path from 'path';
+import {
+	handlerWebPlSql,
+	handlerAdminConsole,
+	AdminContext,
+	oracledb,
+	type configType,
+	type PoolCacheEntry,
+} from 'web_plsql';
+
+(async () => {
+	const app = express();
+
+	// 1. Define configuration
+	const config: configType = {
+		port: 8080,
+		routeStatic: [],
+		routePlSql: [{
+			route: '/myapp',
+			user: 'sample',
+			password: 'sample',
+			connectString: 'localhost:1521/ORCL',
+			defaultPage: 'myapp.home',
+			documentTable: 'doctable',
+			errorStyle: 'debug',
+		}],
+		uploadFileSizeLimit: 50 * 1024 * 1024,
+		loggerFilename: 'access.log',
+	};
+
+	// 2. Create Oracle connection pool
+	const pool = await oracledb.createPool({
+		user: config.routePlSql[0].user,
+		password: config.routePlSql[0].password,
+		connectString: config.routePlSql[0].connectString,
+	});
+
+	// 3. Create PL/SQL handler
+	const plsqlHandler = handlerWebPlSql(pool, {
+		defaultPage: config.routePlSql[0].defaultPage,
+		documentTable: config.routePlSql[0].documentTable,
+		errorStyle: config.routePlSql[0].errorStyle,
+	});
+
+	// 4. Create AdminContext (required for admin console)
+	const caches: PoolCacheEntry[] = [{
+		poolName: config.routePlSql[0].route,
+		procedureNameCache: plsqlHandler.procedureNameCache,
+		argumentCache: plsqlHandler.argumentCache,
+	}];
+	const adminContext = new AdminContext(config, [pool], caches);
+
+	// 5. Mount PL/SQL handler with stats tracking
+	app.use(config.routePlSql[0].route, (req, res, next) => {
+		const start = process.hrtime();
+		res.on('finish', () => {
+			const [s, ns] = process.hrtime(start);
+			adminContext.statsManager.recordRequest(s * 1000 + ns / 1e6, res.statusCode >= 400);
+		});
+		plsqlHandler(req, res, next);
+	});
+
+	// 6. Mount admin console
+	app.use('/admin', handlerAdminConsole({
+		staticDir: path.join(__dirname, 'node_modules/web_plsql/dist/frontend'),
+		user: 'admin',
+		password: 'secret',
+	}, adminContext));
+
+	// 7. Start server
+	app.listen(config.port, () => {
+		console.log(`Server running on port ${config.port}`);
+	});
+})();
+```
+
+### AdminContext Requirement
+
+The admin console requires an `AdminContext` instance to be passed as the second argument to `handlerAdminConsole`.
+
+**Using `startServer()` API:** `AdminContext` is managed automatically.
+
+**Using custom Express app:** You must instantiate `AdminContext` and pass it to the handler.
+
+```typescript
+const adminContext = new AdminContext(config, pools, caches);
+app.use('/admin', handlerAdminConsole(config, adminContext));
+```
 
 # Compare with mod_plsql
 
@@ -180,7 +275,7 @@ The following mod_plsql DAD configuration translates to the configuration option
 }
 ```
 
-## Create a custom Express application based on the default server implemented in `src/server.js`.
+## Create a custom Express application based on the default server implemented in `src/backend/server/server.ts`.
 
 ...
 
@@ -207,8 +302,8 @@ The following mod_plsql DAD configuration translates to the configuration option
 ## Features that are only available in web_plsql
 - The option `transactionModeType` specifies an optional transaction mode.
   "commit" this automatically commits any open transaction after each request. This is the defaults because this is what mod_plsql and ohs are doing.
-  "rollback" this automatically rolles back any open transaction after each request.
-  "transactionCallbackType" this allows to defined a custom handler as a JavaScript function.
+  "rollback" this automatically rolls back any open transaction after each request.
+  "transactionCallbackType" this allows defining a custom handler as a JavaScript function.
 
 ## Features that are planned to be available in web_plsql
 - Support for APEX 5 or greater.

package/dist/chunk-DQk6qfdC.mjs

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };