web_plsql 1.0.0 → 1.3.0

package/README.md

@@ -1,7 +1,6 @@
   [![NPM Version][npm-image]][npm-url]
   [![NPM Downloads][downloads-image]][downloads-url]
-  [![Linux Build](https://travis-ci.org/doberkofler/web_plsql.svg?branch=master)](https://travis-ci.org/doberkofler/web_plsql)
-  [![Build status][appveyor-image]][appveyor-url]
+  [![Node.js CI](https://github.com/doberkofler/web_plsql/actions/workflows/node.js.yml/badge.svg)](https://github.com/doberkofler/web_plsql/actions/workflows/node.js.yml)
   [![Coverage Status](https://coveralls.io/repos/github/doberkofler/web_plsql/badge.svg?branch=master)](https://coveralls.io/github/doberkofler/web_plsql?branch=master)
 
 # Oracle PL/SQL Gateway Middleware for the Express web framework for Node.js
@@ -12,6 +11,8 @@ and serve the content using the Express web framework for Node.js.
 
 Please feel free to try and suggest any improvements. Your thoughts and ideas are most welcome.
 
+![Dashboard](docs/images/admin_console.png)
+
 # Release History
 See the [changelog](https://github.com/doberkofler/web_plsql/blob/master/CHANGELOG.md).
 
@@ -58,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:
 
@@ -120,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
+
+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`.
 
-WIP
+**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
 
@@ -179,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`.
 
 ...
 
@@ -200,12 +296,14 @@ The following mod_plsql DAD configuration translates to the configuration option
 - PlsqlRequestValidationFunction -> routePlSql[].pathAliasProcedure
 - PlsqlExclusionList
 - Basic and custom authentication methods, based on the OWA_SEC package and custom packages.
+- Caching of procedure metadata and validation results for high performance.
+- Real-time monitoring and management via a built-in Admin Console.
 
 ## 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.
@@ -233,6 +331,3 @@ The following mod_plsql DAD configuration translates to the configuration option
 
 [downloads-image]: https://img.shields.io/npm/dm/web_plsql.svg
 [downloads-url]: https://npmjs.org/package/web_plsql
-
-[appveyor-image]: https://ci.appveyor.com/api/projects/status/github/doberkofler/web_plsql?branch=master&svg=true
-[appveyor-url]: https://ci.appveyor.com/project/doberkofler/web-plsql

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 };