mongodash 2.0.0 → 2.1.0

package/docs/getters.md

@@ -0,0 +1,31 @@
+# Collection and Client getters
+
+Utility functions for global access to Collections and MongoClient.
+
+## getCollection(name [, options]) => Collection
+
+```typescript
+getCollection(name [, options]) => Collection
+```
+
+Get a new instance of a [collection](https://mongodb.github.io/node-mongodb-native/4.0/classes/collection.html). Uses default database determined from the connection string. See [official driver documentation](http://mongodb.github.io/node-mongodb-native/3.6/api/Db.html#collection) for valid options.
+
+```typescript
+import { getCollection } from 'mongodash'; 
+const myCollection = getCollection('myCollectionName');
+```
+
+The method just shortens `getMongoClient().db().collection('myCollectionName')`.
+
+## getMongoClient() => MongoClient
+
+```typescript
+getMongoClient() => MongoClient
+```
+
+Returns the global instance of MongoClient. See [official driver documentation](https://mongodb.github.io/node-mongodb-native/4.0/classes/mongoclient.html) for documentation of MongoClient.
+
+```typescript
+import { getMongoClient } from 'mongodash'; 
+const mongoClient = getMongoClient();
+```

package/docs/getting-started.md

@@ -0,0 +1,120 @@
+---
+title: Getting Started
+---
+
+<!--
+    ⚠️ WARNING: DO NOT EDIT THIS FILE MANUALLY ⚠️
+
+    This file is strictly auto-generated from README.md.
+    Any changes made here will be overwritten by the next build.
+    To make changes, edit the README.md file in the root directory.
+-->
+
+# Getting Started
+
+Installation:
+```bash
+npm install mongodash
+```
+
+Initialization
+```typescript
+import mongodash from 'mongodash';
+
+await mongodash.init({
+    uri: 'mongodb://mongodb0.example.com:27017/myDatabase' 
+});
+```
+See more initialization options [here](https://vaclavobornik.github.io/mongodash/initialization).
+
+<br>
+
+## Reactive Tasks
+
+```typescript
+import { reactiveTask } from 'mongodash';
+
+// Trigger a task when a user is updated
+await reactiveTask({
+    task: 'on-user-update', 
+    collection: 'users',
+    handler: async (doc) => {
+        console.log('User changed:', doc._id);
+    }
+});
+```
+See detailed description [here](https://vaclavobornik.github.io/mongodash/reactive-tasks).
+
+<br>
+
+## cronTask
+```typescript
+import { cronTask } from 'mongodash';
+
+await cronTask('my-task-id', '5m 20s', async () => {
+  
+    console.log('Hurray the task is running!');
+
+});
+```
+See detailed description and more cron tasks methods [here](https://vaclavobornik.github.io/mongodash/cron-tasks).
+
+<br>
+
+## withLock
+
+```typescript
+import { withLock } from 'mongodash';
+
+await withLock('my-lock-id', async () => {
+  
+  // it is quaranteed this callback will never run in parallel, 
+  // so all race-conditions are solved
+  const data = await loadFromDatabase();
+  data.counter += 1;
+  await saveToDatabase(data);
+  
+});
+```
+See detailed description [here](https://vaclavobornik.github.io/mongodash/with-lock).
+
+<br>
+
+## withTransaction
+```typescript
+import { withTransaction, getCollection } from 'mongodash';
+
+const createdDocuments = await withTransaction(async (session) => {
+    
+  const myDocument1 = { value: 1 };
+  const myDocument2 = { value: 2 };
+  
+  const collection = getCollection('myCollection');
+  await collection.insertOne(myDocument1, { session });
+  await collection.insertOne(myDocument2, { session });
+  
+  return [myDocument1, myDocument2];
+});
+```
+See detailed description [here](https://vaclavobornik.github.io/mongodash/with-transaction).
+
+<br>
+
+## getCollection
+```typescript
+import { getCollection } from 'mongodash';
+
+const myCollection = getCollection('myCollectionName');
+```
+See detailed description [here](https://vaclavobornik.github.io/mongodash/getters).
+
+<br>
+
+## getMongoClient
+```typescript
+import { getMongoClient } from 'mongodash';
+
+const mongoClient = getMongoClient();
+```
+See detailed description [here](https://vaclavobornik.github.io/mongodash/getters).
+

package/docs/index.md

@@ -0,0 +1,29 @@
+---
+layout: home
+
+hero:
+  name: "Mongodash"
+  text: "Modern MongoDB Utility Library"
+  tagline: "Cron, Locks, Transactions, and more made simple."
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/VaclavObornik/mongodash
+
+features:
+  - title: Reactive Tasks
+    details: Instant background jobs triggered by MongoDB Change Streams.
+    link: /reactive-tasks
+  - title: Cron Tasks
+    details: Reliable distributed cron tasks stored in MongoDB.
+    link: /cron-tasks
+  - title: Concurrency Control
+    details: Distributed locks to manage critical sections across instances.
+    link: /with-lock
+  - title: Transactions
+    details: Simplified transaction management with automatic session handling.
+    link: /with-transaction
+---

package/docs/initialization.md

@@ -0,0 +1,59 @@
+# Initialization
+
+## Installation
+
+```bash
+npm install mongodash
+```
+
+## mongodash.init(options) => Promise
+
+Initializes the `mongodash` library. This method must be called before using any other features.
+
+```typescript
+import mongodash from 'mongodash';
+
+// Initialize with connection string
+await mongodash.init({
+    uri: 'mongodb://localhost:27017/my-app',
+    // ...other options
+});
+
+// OR initialize with existing MongoClient
+await mongodash.init({
+    mongoClient: myExistingClient,
+    // ...other options
+});
+```
+
+### Options Reference
+
+#### Connection Options
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `uri` | `string` | **Required** (if `mongoClient` is not provided). The MongoDB connection string. `mongodash` will connect automatically. |
+| `mongoClient` | `MongoClient` | **Required** (if `uri` is not provided). An existing, connected `MongoClient` instance. |
+| `clientOptions` | `MongoClientOptions` | Optional. Used only when `uri` is provided. Options passed to the MongoDB driver. |
+
+#### General Options
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `globalsCollection` | `string` \| `Collection` | Name of the collection used for distributed locking and coordination. Mongodash uses a fixed set of documents identified by unique derived `_id`s, so it has a minimal storage footprint and doesn't pollute the collection. Default: `_mongodash_globals`. |
+| `onError` | `(err: Error) => void` | Global error handler. Default: `console.error`. |
+| `onInfo` | `(info: Info) => void` | Global info/debug handler. Default: `console.info`.  |
+
+#### Cron Tasks Options
+
+See [Cron Tasks](./cron-tasks.md#initialization-options-optional) for feature-specific options (e.g. `runCronTasks`, `cronExpressionParserOptions`, etc).
+
+#### Reactive Tasks Options
+
+See [Reactive Tasks](./reactive-tasks.md#5-advanced-initialization) for feature-specific options (e.g. `concurrency`, `monitoring`, etc).
+
+#### Testing Options
+
+| Option | Type | Description |
+| :--- | :--- | :--- |
+| `collectionFactory` | `Function` | **Internal**. Used for injecting mock collections during testing. |

package/docs/process-in-batches.md

@@ -0,0 +1,73 @@
+# Process In Batches
+
+Efficiently process large datasets by iterating through a collection in batches.
+
+This utility handles cursor management, batch accumulation, and memory efficiency for you.
+
+## processInBatches
+
+```typescript
+import { processInBatches } from 'mongodash';
+
+// 1. Fetch users
+// 2. Transform them (e.g. enrich data)
+// 3. Save them (e.g. bulk write)
+await processInBatches(
+    // 1. Collection
+    db.collection('users'), 
+    
+    // 2. Filter or Pipeline
+    { status: 'active' }, 
+    // OR: [{ $match: { status: 'active' } }]
+    
+    // 3. Transform: Return an operation, or null to skip
+    async (user) => {
+        const enrichment = await fetchEnrichment(user._id);
+        return {
+            updateOne: {
+                filter: { _id: user._id },
+                update: { $set: { enrichment } }
+            }
+        };
+    },
+    
+    // 4. Execute Batch: Receives array of operations
+    async (batchOps) => {
+        if (batchOps.length > 0) {
+            await db.collection('users').bulkWrite(batchOps);
+        }
+    },
+    
+    // 5. Options
+    { batchSize: 500 }
+);
+```
+
+### Signature
+
+```typescript
+function processInBatches<TDoc, TOp>(
+    collection: Collection<TDoc>, 
+    queryOrPipeline: Filter<TDoc> | Document[], 
+    transform: (doc: TDoc) => TOp | TOp[] | null | undefined | Promise<...>, 
+    executeBatch: (ops: TOp[]) => Promise<void>, 
+    options?: { batchSize?: number; shouldStop?: () => boolean }
+): Promise<{ processedDocuments: number, operationsPerformed: number }>
+```
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `collection` | `Collection` | The source MongoDB collection. |
+| `queryOrPipeline` | `Filter` \| `Document[]` | Standard query object OR Aggregation Pipeline. |
+| `transform` | `Function` | Function called for **each document**. Returns an operation (to be batched), an array of operations, or `null`/`undefined` to skip. |
+| `executeBatch` | `Function` | Function called when `batchSize` is reached. Receives the array of accumulated operations. |
+| `options` | `Object` | Optional configuration. |
+
+### Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `batchSize` | `number` | `1000` | Size of the batch passed to `executeBatch`. |
+| `shouldStop` | `() => boolean` | `undefined` | Callback checked before processing each document. If returns `true`, processing stops gracefully. |