meadow-connection-mongodb 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,128 @@
+# meadow-connection-mongodb
+
+MongoDB connection service for the Meadow data access layer.
+
+[![Coverage Status](https://coveralls.io/repos/github/stevenvelozo/meadow-connection-mongodb/badge.svg?branch=main)](https://coveralls.io/github/stevenvelozo/meadow-connection-mongodb?branch=main)
+[![Build Status](https://github.com/stevenvelozo/meadow-connection-mongodb/workflows/Tests/badge.svg)](https://github.com/stevenvelozo/meadow-connection-mongodb/actions)
+[![npm version](https://badge.fury.io/js/meadow-connection-mongodb.svg)](https://www.npmjs.com/package/meadow-connection-mongodb)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- **Fable Service Provider** -- integrates with the Fable dependency injection ecosystem
+- **Connection Pooling** -- built-in pool management via the official MongoDB Node.js driver
+- **Collection & Index Management** -- automatic collection creation and index generation from Meadow schemas
+- **Meadow-Compatible Settings** -- accepts both Meadow-style (`Server`, `Port`) and native MongoDB property names
+- **Authentication Support** -- optional username/password credentials with URL-encoded connection URIs
+- **Auto-Connect Mode** -- optionally connect during service construction
+- **Idempotent Schema** -- safe to call `createTable()` on startup; existing collections are preserved
+
+## Installation
+
+```shell
+npm install meadow-connection-mongodb
+```
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libMeadowConnectionMongoDB = require('meadow-connection-mongodb');
+
+let _Fable = new libFable(
+	{
+		"MongoDB":
+		{
+			"Server": "localhost",
+			"Port": 27017,
+			"Database": "myapp"
+		}
+	});
+
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowMongoDBProvider', libMeadowConnectionMongoDB);
+
+_Fable.MeadowMongoDBProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		if (pError) { return console.error(pError); }
+
+		let tmpDB = _Fable.MeadowMongoDBProvider.pool;
+		// tmpDB is the MongoDB Db instance -- ready for queries
+	});
+```
+
+## Configuration
+
+Settings are read from `fable.settings.MongoDB`:
+
+| Setting | Alias | Default | Description |
+|---------|-------|---------|-------------|
+| `Server` | `host` | `127.0.0.1` | MongoDB host |
+| `Port` | `port` | `27017` | MongoDB port |
+| `User` | `user` | `''` | Authentication username |
+| `Password` | `password` | `''` | Authentication password |
+| `Database` | `database` | `test` | Database name |
+| `ConnectionPoolLimit` | `maxPoolSize` | `10` | Maximum connections in pool |
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `connect()` | Synchronous -- create MongoClient and Db handle |
+| `connectAsync(fCallback)` | Callback-style connection (recommended) |
+| `pool` | Getter -- returns the `Db` instance |
+| `client` | Getter -- returns the raw `MongoClient` |
+| `generateCreateTableStatement(schema)` | Generate a collection/index descriptor |
+| `createTable(schema, fCallback)` | Create a collection and its indexes |
+| `createTables(schema, fCallback)` | Create multiple collections sequentially |
+| `generateDropTableStatement(name)` | Generate a drop descriptor |
+
+## Collection & Index Mapping
+
+| Meadow DataType | Index Created | Unique |
+|-----------------|---------------|--------|
+| `ID` | Ascending | Yes |
+| `GUID` | Ascending | Yes |
+| `ForeignKey` | Ascending | No |
+| `String` | None | -- |
+| `Numeric` | None | -- |
+| `Decimal` | None | -- |
+| `Text` | None | -- |
+| `DateTime` | None | -- |
+| `Boolean` | None | -- |
+
+## Part of the Retold Framework
+
+This module is a Meadow connector that plugs into the Retold application framework. It provides the MongoDB persistence layer for the Meadow data access abstraction.
+
+## Testing
+
+```shell
+npm test
+```
+
+Coverage:
+
+```shell
+npm run coverage
+```
+
+## Related Packages
+
+- [meadow](https://github.com/stevenvelozo/meadow) -- Data access layer and ORM
+- [fable](https://github.com/stevenvelozo/fable) -- Application framework and service manager
+- [foxhound](https://github.com/stevenvelozo/foxhound) -- Query generation DSL (includes MongoDB dialect)
+- [stricture](https://github.com/stevenvelozo/stricture) -- Schema definition and DDL tools
+- [meadow-endpoints](https://github.com/stevenvelozo/meadow-endpoints) -- RESTful endpoint generation
+- [meadow-connection-mysql](https://github.com/stevenvelozo/meadow-connection-mysql) -- MySQL/MariaDB connector
+- [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) -- Microsoft SQL Server connector
+- [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) -- SQLite connector
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

package/docs/README.md

@@ -0,0 +1,104 @@
+# meadow-connection-mongodb
+
+MongoDB connection service for the Meadow data access layer. This module provides connection management, collection creation, and index generation for applications using MongoDB as their persistence store.
+
+## Quick Start
+
+```javascript
+const libFable = require('fable');
+const libMeadowConnectionMongoDB = require('meadow-connection-mongodb');
+
+// 1. Create a Fable instance with MongoDB settings
+let _Fable = new libFable(
+	{
+		"MongoDB":
+		{
+			"Server": "localhost",
+			"Port": 27017,
+			"Database": "myapp"
+		}
+	});
+
+// 2. Register and instantiate the service
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowMongoDBProvider', libMeadowConnectionMongoDB);
+
+// 3. Connect
+_Fable.MeadowMongoDBProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		if (pError) { return console.error(pError); }
+
+		// 4. Use the Db instance
+		let tmpDB = _Fable.MeadowMongoDBProvider.pool;
+		let tmpCollection = tmpDB.collection('animals');
+
+		tmpCollection.find({}).toArray()
+			.then((pDocs) => { console.log(pDocs); });
+	});
+```
+
+## Configuration
+
+Settings are read from `fable.settings.MongoDB`. Both Meadow-style names and native MongoDB names are supported:
+
+| Setting | Alias | Default | Description |
+|---------|-------|---------|-------------|
+| `Server` | `host` | `127.0.0.1` | MongoDB hostname or IP |
+| `Port` | `port` | `27017` | MongoDB port |
+| `User` | `user` | `''` | Authentication username |
+| `Password` | `password` | `''` | Authentication password |
+| `Database` | `database` | `test` | Target database name |
+| `ConnectionPoolLimit` | `maxPoolSize` | `10` | Maximum connection pool size |
+
+### Connection URI
+
+The driver builds a standard MongoDB connection URI from these settings:
+
+```
+mongodb://host:port/database
+mongodb://user:password@host:port/database   (with authentication)
+```
+
+Credentials are URL-encoded automatically for safe handling of special characters.
+
+## How It Fits
+
+```
+Application
+    |
+    v
+ Meadow (ORM)
+    |
+    v
+ FoxHound (MongoDB Dialect)
+    |
+    v
+ meadow-connection-mongodb  <-- this module
+    |
+    v
+ Official MongoDB Driver (mongodb ^6.12.0)
+    |
+    v
+ MongoDB Server
+```
+
+## Learn More
+
+- [Quickstart Guide](quickstart.md) -- step-by-step setup
+- [Architecture](architecture.md) -- connection lifecycle and design diagrams
+- [Collections & Indexes](schema.md) -- collection creation and index mapping
+- [API Reference](api/reference.md) -- complete method documentation
+
+## Companion Modules
+
+| Module | Purpose |
+|--------|---------|
+| [meadow](https://github.com/stevenvelozo/meadow) | Data access layer and ORM |
+| [foxhound](https://github.com/stevenvelozo/foxhound) | Query generation DSL (MongoDB dialect) |
+| [stricture](https://github.com/stevenvelozo/stricture) | Schema definition and DDL tools |
+| [meadow-connection-mysql](https://github.com/stevenvelozo/meadow-connection-mysql) | MySQL / MariaDB connector |
+| [meadow-connection-mssql](https://github.com/stevenvelozo/meadow-connection-mssql) | Microsoft SQL Server connector |
+| [meadow-connection-sqlite](https://github.com/stevenvelozo/meadow-connection-sqlite) | SQLite connector |
+| [meadow-connection-rocksdb](https://github.com/stevenvelozo/meadow-connection-rocksdb) | RocksDB key-value connector |
+| [meadow-connection-dgraph](https://github.com/stevenvelozo/meadow-connection-dgraph) | Dgraph graph database connector |

package/docs/_cover.md

@@ -0,0 +1,17 @@
+# meadow-connection-mongodb
+
+<small>v1.0.0</small>
+
+> MongoDB connection service for the Meadow data access layer
+
+- **Fable Service Provider** -- seamless dependency injection integration
+- **Connection Pooling** -- built-in pool management via the official MongoDB driver
+- **Collection & Index Management** -- automatic creation from Meadow schemas
+- **Authentication Support** -- optional credential-based connection URIs
+- **Meadow-Compatible Settings** -- accepts both Meadow-style and native property names
+- **Idempotent Schema** -- safe to call on every startup
+
+[Overview](README.md)
+[Quickstart](quickstart.md)
+[API Reference](api/reference.md)
+[GitHub](https://github.com/stevenvelozo/meadow-connection-mongodb)

package/docs/_sidebar.md

@@ -0,0 +1,33 @@
+- **Getting Started**
+  - [Overview](README.md)
+  - [Quickstart](quickstart.md)
+
+- **Concepts**
+  - [Architecture](architecture.md)
+  - [Collections & Indexes](schema.md)
+
+- **API Reference**
+  - [Full Reference](api/reference.md)
+  - Connection
+    - [connectAsync(fCallback)](api/connectAsync.md)
+    - [connect()](api/connect.md)
+  - Accessors
+    - [pool](api/pool.md)
+    - [client](api/client.md)
+  - Schema Management
+    - [generateCreateTableStatement()](api/generateCreateTableStatement.md)
+    - [createTable()](api/createTable.md)
+    - [createTables()](api/createTables.md)
+    - [generateDropTableStatement()](api/generateDropTableStatement.md)
+
+- **Ecosystem**
+  - [Meadow](https://github.com/stevenvelozo/meadow)
+  - [FoxHound](https://github.com/stevenvelozo/foxhound)
+  - [Stricture](https://github.com/stevenvelozo/stricture)
+  - [Fable](https://github.com/stevenvelozo/fable)
+  - Connectors
+    - [MySQL](https://github.com/stevenvelozo/meadow-connection-mysql)
+    - [MSSQL](https://github.com/stevenvelozo/meadow-connection-mssql)
+    - [SQLite](https://github.com/stevenvelozo/meadow-connection-sqlite)
+    - [RocksDB](https://github.com/stevenvelozo/meadow-connection-rocksdb)
+    - [Dgraph](https://github.com/stevenvelozo/meadow-connection-dgraph)

package/docs/_topbar.md

@@ -0,0 +1,5 @@
+- [Overview](README.md)
+- [Quickstart](quickstart.md)
+- [Architecture](architecture.md)
+- [API Reference](api/reference.md)
+- [GitHub](https://github.com/stevenvelozo/meadow-connection-mongodb)

package/docs/api/client.md

@@ -0,0 +1,106 @@
+# client (getter)
+
+Returns the raw `MongoClient` instance for server-level operations.
+
+## Signature
+
+```javascript
+get client()
+```
+
+## Return Value
+
+| Type | Description |
+|------|-------------|
+| `MongoClient` | The MongoDB client instance (after connecting) |
+| `false` | Before connection |
+
+## Primary Use
+
+The `client` getter exposes the underlying `MongoClient` from the official MongoDB driver. In most cases you should use the `pool` getter (which returns the `Db`) instead. The `client` is useful for:
+
+- Accessing other databases on the same server
+- Managing client sessions for transactions
+- Watching change streams at the cluster level
+- Closing the connection when shutting down
+- Monitoring connection pool events
+
+```javascript
+let tmpClient = _Fable.MeadowMongoDBProvider.client;
+```
+
+## Comparison with pool
+
+| Getter | Returns | Purpose |
+|--------|---------|---------|
+| `pool` | `Db` | Database-level operations (collections, queries, aggregations) |
+| `client` | `MongoClient` | Server-level operations (sessions, other databases, shutdown) |
+
+The `pool` getter returns the `Db` instance for the configured database. The `client` getter returns the `MongoClient` that wraps the connection pool and provides server-level access.
+
+## Access Another Database
+
+```javascript
+let tmpClient = _Fable.MeadowMongoDBProvider.client;
+
+// Access a different database on the same server
+let tmpAnalyticsDB = tmpClient.db('analytics');
+let tmpEvents = tmpAnalyticsDB.collection('events');
+```
+
+## Client Session (Transactions)
+
+```javascript
+let tmpClient = _Fable.MeadowMongoDBProvider.client;
+
+let tmpSession = tmpClient.startSession();
+tmpSession.startTransaction();
+
+try
+{
+	let tmpDB = _Fable.MeadowMongoDBProvider.pool;
+	let tmpAnimals = tmpDB.collection('Animal');
+
+	await tmpAnimals.insertOne({ Name: 'Fido' }, { session: tmpSession });
+	await tmpAnimals.updateOne(
+		{ Name: 'Luna' },
+		{ $set: { Age: 6 } },
+		{ session: tmpSession });
+
+	await tmpSession.commitTransaction();
+}
+catch (pError)
+{
+	await tmpSession.abortTransaction();
+}
+finally
+{
+	tmpSession.endSession();
+}
+```
+
+## Close Connection
+
+```javascript
+let tmpClient = _Fable.MeadowMongoDBProvider.client;
+
+tmpClient.close()
+	.then(() =>
+	{
+		console.log('MongoDB connection closed.');
+	});
+```
+
+## Before Connection
+
+Returns `false` before connection:
+
+```javascript
+let tmpClient = _Fable.MeadowMongoDBProvider.client;
+// tmpClient => false (not connected yet)
+```
+
+## Related
+
+- [pool](pool.md) -- The Db instance (recommended for most use)
+- [connectAsync](connectAsync.md) -- Establish the connection

package/docs/api/connect.md

@@ -0,0 +1,97 @@
+# connect()
+
+Synchronous method that creates the MongoDB client and obtains the database handle.
+
+## Signature
+
+```javascript
+connect()
+```
+
+## Parameters
+
+None.
+
+## Return Value
+
+None.
+
+## Behavior
+
+1. If already connected (`this._Client` exists), logs an error with masked password and returns
+2. Builds the connection URI via `_buildConnectionURI()`
+3. Creates a new `MongoClient` with the URI and pool size option
+4. Calls `client.db(database)` to obtain the `Db` instance
+5. Sets `this.connected = true`
+
+## Usage
+
+```javascript
+_Fable.MeadowMongoDBProvider.connect();
+
+if (_Fable.MeadowMongoDBProvider.connected)
+{
+	let tmpDB = _Fable.MeadowMongoDBProvider.pool;
+	// Use the Db instance
+}
+```
+
+## Why Both connect() and connectAsync()?
+
+The MongoDB Node.js driver v6 creates connections lazily -- the `MongoClient` constructor and `client.db()` are synchronous, with actual TCP connections established on first use. The `connect()` method works reliably for immediate use. However, `connectAsync()` is preferred because:
+
+- It follows the Fable service provider convention
+- It provides error handling via the callback
+- It guards against missing callbacks
+- It is consistent with other Meadow connector APIs
+
+## Double-Connect Protection
+
+If `connect()` is called when already connected, it logs an error with the settings (password masked) and returns without action:
+
+```javascript
+_Fable.MeadowMongoDBProvider.connect();
+_Fable.MeadowMongoDBProvider.connect();
+// Logs: "Meadow-Connection-MongoDB trying to connect but is already connected - skipping."
+// Settings logged with password: '*****************'
+```
+
+## Auto-Connect
+
+The `connect()` method is called automatically during construction if `MeadowConnectionMongoDBAutoConnect` is `true`:
+
+```javascript
+let _Fable = new libFable(
+	{
+		"MongoDB":
+		{
+			"Server": "localhost",
+			"Port": 27017,
+			"Database": "myapp"
+		},
+		"MeadowConnectionMongoDBAutoConnect": true
+	});
+
+_Fable.serviceManager.addAndInstantiateServiceType(
+	'MeadowMongoDBProvider', libMeadowConnectionMongoDB);
+
+// Already connected -- pool is ready
+let tmpDB = _Fable.MeadowMongoDBProvider.pool;
+```
+
+## Connection URI Format
+
+The `_buildConnectionURI()` method builds the URI from configuration:
+
+```
+mongodb://host:port/database                          (no auth)
+mongodb://user:password@host:port/database            (with auth)
+```
+
+Credentials are URL-encoded with `encodeURIComponent()` to handle special characters safely.
+
+## Related
+
+- [connectAsync](connectAsync.md) -- Callback-style connection (recommended)
+- [pool](pool.md) -- Access the Db instance after connecting
+- [client](client.md) -- Access the raw MongoClient

package/docs/api/connectAsync.md

@@ -0,0 +1,93 @@
+# connectAsync(fCallback)
+
+Callback-style connection method. Creates the `MongoClient` and obtains the `Db` instance, or returns the existing connection if already connected.
+
+## Signature
+
+```javascript
+connectAsync(fCallback)
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fCallback` | `function` | Callback receiving `(error, database)` |
+
+## Return Value
+
+Returns the result of the callback invocation.
+
+## Behavior
+
+1. If no callback is provided, logs an error and substitutes a no-op function
+2. If already connected (`this._Client` exists), calls `fCallback(null, this._Database)` immediately
+3. Otherwise, calls `this.connect()` to create the client and database handle
+4. On success: calls `fCallback(null, this._Database)`
+5. On error: logs the error, calls `fCallback(pError)`
+
+## Basic Usage
+
+```javascript
+_Fable.MeadowMongoDBProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		if (pError)
+		{
+			console.error('Connection failed:', pError);
+			return;
+		}
+		console.log('Connected! Database:', pDatabase.databaseName);
+	});
+```
+
+## Idempotent Calls
+
+Calling `connectAsync()` multiple times is safe. If already connected, the existing `Db` instance is returned without creating a new connection:
+
+```javascript
+// First call -- creates the connection
+_Fable.MeadowMongoDBProvider.connectAsync(
+	(pError, pDatabase) =>
+	{
+		// pDatabase is the Db instance
+
+		// Second call -- reuses the existing connection
+		_Fable.MeadowMongoDBProvider.connectAsync(
+			(pError2, pDatabase2) =>
+			{
+				// pDatabase2 === pDatabase (same Db instance)
+			});
+	});
+```
+
+## Missing Callback
+
+If called without a callback, a warning is logged and a no-op function is used:
+
+```javascript
+// Logs: "Meadow MongoDB connectAsync() called without a callback."
+_Fable.MeadowMongoDBProvider.connectAsync();
+```
+
+## Error Handling
+
+If `connect()` throws, the error is caught and passed to the callback:
+
+```javascript
+_Fable.MeadowMongoDBProvider.connectAsync(
+	(pError) =>
+	{
+		if (pError)
+		{
+			// Handle connection failure
+			console.error('MongoDB connection error:', pError.message);
+		}
+	});
+```
+
+## Related
+
+- [connect()](connect.md) -- Synchronous connection method
+- [pool](pool.md) -- Access the Db instance after connecting
+- [client](client.md) -- Access the raw MongoClient