mongodash 2.0.0 → 2.1.0

package/docs/.vitepress/cache/deps/vue.js

@@ -0,0 +1,347 @@
+import {
+  BaseTransition,
+  BaseTransitionPropsValidators,
+  Comment,
+  DeprecationTypes,
+  EffectScope,
+  ErrorCodes,
+  ErrorTypeStrings,
+  Fragment,
+  KeepAlive,
+  ReactiveEffect,
+  Static,
+  Suspense,
+  Teleport,
+  Text,
+  TrackOpTypes,
+  Transition,
+  TransitionGroup,
+  TriggerOpTypes,
+  VueElement,
+  assertNumber,
+  callWithAsyncErrorHandling,
+  callWithErrorHandling,
+  camelize,
+  capitalize,
+  cloneVNode,
+  compatUtils,
+  compile,
+  computed,
+  createApp,
+  createBaseVNode,
+  createBlock,
+  createCommentVNode,
+  createElementBlock,
+  createHydrationRenderer,
+  createPropsRestProxy,
+  createRenderer,
+  createSSRApp,
+  createSlots,
+  createStaticVNode,
+  createTextVNode,
+  createVNode,
+  customRef,
+  defineAsyncComponent,
+  defineComponent,
+  defineCustomElement,
+  defineEmits,
+  defineExpose,
+  defineModel,
+  defineOptions,
+  defineProps,
+  defineSSRCustomElement,
+  defineSlots,
+  devtools,
+  effect,
+  effectScope,
+  getCurrentInstance,
+  getCurrentScope,
+  getCurrentWatcher,
+  getTransitionRawChildren,
+  guardReactiveProps,
+  h,
+  handleError,
+  hasInjectionContext,
+  hydrate,
+  hydrateOnIdle,
+  hydrateOnInteraction,
+  hydrateOnMediaQuery,
+  hydrateOnVisible,
+  initCustomFormatter,
+  initDirectivesForSSR,
+  inject,
+  isMemoSame,
+  isProxy,
+  isReactive,
+  isReadonly,
+  isRef,
+  isRuntimeOnly,
+  isShallow,
+  isVNode,
+  markRaw,
+  mergeDefaults,
+  mergeModels,
+  mergeProps,
+  nextTick,
+  nodeOps,
+  normalizeClass,
+  normalizeProps,
+  normalizeStyle,
+  onActivated,
+  onBeforeMount,
+  onBeforeUnmount,
+  onBeforeUpdate,
+  onDeactivated,
+  onErrorCaptured,
+  onMounted,
+  onRenderTracked,
+  onRenderTriggered,
+  onScopeDispose,
+  onServerPrefetch,
+  onUnmounted,
+  onUpdated,
+  onWatcherCleanup,
+  openBlock,
+  patchProp,
+  popScopeId,
+  provide,
+  proxyRefs,
+  pushScopeId,
+  queuePostFlushCb,
+  reactive,
+  readonly,
+  ref,
+  registerRuntimeCompiler,
+  render,
+  renderList,
+  renderSlot,
+  resolveComponent,
+  resolveDirective,
+  resolveDynamicComponent,
+  resolveFilter,
+  resolveTransitionHooks,
+  setBlockTracking,
+  setDevtoolsHook,
+  setTransitionHooks,
+  shallowReactive,
+  shallowReadonly,
+  shallowRef,
+  ssrContextKey,
+  ssrUtils,
+  stop,
+  toDisplayString,
+  toHandlerKey,
+  toHandlers,
+  toRaw,
+  toRef,
+  toRefs,
+  toValue,
+  transformVNodeArgs,
+  triggerRef,
+  unref,
+  useAttrs,
+  useCssModule,
+  useCssVars,
+  useHost,
+  useId,
+  useModel,
+  useSSRContext,
+  useShadowRoot,
+  useSlots,
+  useTemplateRef,
+  useTransitionState,
+  vModelCheckbox,
+  vModelDynamic,
+  vModelRadio,
+  vModelSelect,
+  vModelText,
+  vShow,
+  version,
+  warn,
+  watch,
+  watchEffect,
+  watchPostEffect,
+  watchSyncEffect,
+  withAsyncContext,
+  withCtx,
+  withDefaults,
+  withDirectives,
+  withKeys,
+  withMemo,
+  withModifiers,
+  withScopeId
+} from "./chunk-LE5NDSFD.js";
+export {
+  BaseTransition,
+  BaseTransitionPropsValidators,
+  Comment,
+  DeprecationTypes,
+  EffectScope,
+  ErrorCodes,
+  ErrorTypeStrings,
+  Fragment,
+  KeepAlive,
+  ReactiveEffect,
+  Static,
+  Suspense,
+  Teleport,
+  Text,
+  TrackOpTypes,
+  Transition,
+  TransitionGroup,
+  TriggerOpTypes,
+  VueElement,
+  assertNumber,
+  callWithAsyncErrorHandling,
+  callWithErrorHandling,
+  camelize,
+  capitalize,
+  cloneVNode,
+  compatUtils,
+  compile,
+  computed,
+  createApp,
+  createBlock,
+  createCommentVNode,
+  createElementBlock,
+  createBaseVNode as createElementVNode,
+  createHydrationRenderer,
+  createPropsRestProxy,
+  createRenderer,
+  createSSRApp,
+  createSlots,
+  createStaticVNode,
+  createTextVNode,
+  createVNode,
+  customRef,
+  defineAsyncComponent,
+  defineComponent,
+  defineCustomElement,
+  defineEmits,
+  defineExpose,
+  defineModel,
+  defineOptions,
+  defineProps,
+  defineSSRCustomElement,
+  defineSlots,
+  devtools,
+  effect,
+  effectScope,
+  getCurrentInstance,
+  getCurrentScope,
+  getCurrentWatcher,
+  getTransitionRawChildren,
+  guardReactiveProps,
+  h,
+  handleError,
+  hasInjectionContext,
+  hydrate,
+  hydrateOnIdle,
+  hydrateOnInteraction,
+  hydrateOnMediaQuery,
+  hydrateOnVisible,
+  initCustomFormatter,
+  initDirectivesForSSR,
+  inject,
+  isMemoSame,
+  isProxy,
+  isReactive,
+  isReadonly,
+  isRef,
+  isRuntimeOnly,
+  isShallow,
+  isVNode,
+  markRaw,
+  mergeDefaults,
+  mergeModels,
+  mergeProps,
+  nextTick,
+  nodeOps,
+  normalizeClass,
+  normalizeProps,
+  normalizeStyle,
+  onActivated,
+  onBeforeMount,
+  onBeforeUnmount,
+  onBeforeUpdate,
+  onDeactivated,
+  onErrorCaptured,
+  onMounted,
+  onRenderTracked,
+  onRenderTriggered,
+  onScopeDispose,
+  onServerPrefetch,
+  onUnmounted,
+  onUpdated,
+  onWatcherCleanup,
+  openBlock,
+  patchProp,
+  popScopeId,
+  provide,
+  proxyRefs,
+  pushScopeId,
+  queuePostFlushCb,
+  reactive,
+  readonly,
+  ref,
+  registerRuntimeCompiler,
+  render,
+  renderList,
+  renderSlot,
+  resolveComponent,
+  resolveDirective,
+  resolveDynamicComponent,
+  resolveFilter,
+  resolveTransitionHooks,
+  setBlockTracking,
+  setDevtoolsHook,
+  setTransitionHooks,
+  shallowReactive,
+  shallowReadonly,
+  shallowRef,
+  ssrContextKey,
+  ssrUtils,
+  stop,
+  toDisplayString,
+  toHandlerKey,
+  toHandlers,
+  toRaw,
+  toRef,
+  toRefs,
+  toValue,
+  transformVNodeArgs,
+  triggerRef,
+  unref,
+  useAttrs,
+  useCssModule,
+  useCssVars,
+  useHost,
+  useId,
+  useModel,
+  useSSRContext,
+  useShadowRoot,
+  useSlots,
+  useTemplateRef,
+  useTransitionState,
+  vModelCheckbox,
+  vModelDynamic,
+  vModelRadio,
+  vModelSelect,
+  vModelText,
+  vShow,
+  version,
+  warn,
+  watch,
+  watchEffect,
+  watchPostEffect,
+  watchSyncEffect,
+  withAsyncContext,
+  withCtx,
+  withDefaults,
+  withDirectives,
+  withKeys,
+  withMemo,
+  withModifiers,
+  withScopeId
+};
+//# sourceMappingURL=vue.js.map

package/docs/.vitepress/cache/deps/vue.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": [],
+  "sourcesContent": [],
+  "mappings": "",
+  "names": []
+}

package/docs/.vitepress/config.mts

@@ -0,0 +1,48 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+    base: '/mongodash/',
+    title: "Mongodash",
+    description: "A modern JavaScript & Typescript MongoDB-based utility library",
+    cleanUrls: true,
+    themeConfig: {
+        nav: [
+            { text: 'Home', link: '/' },
+            { text: 'Getting Started', link: '/getting-started' },
+            { text: 'GitHub', link: 'https://github.com/VaclavObornik/mongodash' }
+        ],
+
+        sidebar: [
+            {
+                text: 'Introduction',
+                items: [
+                    { text: 'Getting Started', link: '/getting-started' },
+                    { text: 'Initialization', link: '/initialization' }
+                ]
+            },
+            {
+                text: 'Core Features',
+                items: [
+                    { text: 'Reactive Tasks', link: '/reactive-tasks' },
+                    { text: 'Cron Tasks', link: '/cron-tasks' },
+                    { text: 'Dashboard', link: '/dashboard' },
+                    { text: 'Concurrency Control', link: '/with-lock' },
+                    { text: 'Transactions', link: '/with-transaction' },
+                ]
+            },
+            {
+                text: 'Utilities',
+                items: [
+                    { text: 'Process In Batches', link: '/process-in-batches' },
+                    { text: 'Getters', link: '/getters' }
+                ]
+            }
+        ],
+
+        socialLinks: [
+            { icon: 'github', link: 'https://github.com/VaclavObornik/mongodash' }
+        ],
+
+        outline: [2, 3]
+    }
+})

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './style.css'
+
+export default DefaultTheme

package/docs/.vitepress/theme/style.css

@@ -0,0 +1,16 @@
+/**
+ * Custom Theme Colors - Vibrant Violet/Purple
+ */
+:root {
+  --vp-c-brand-1: #8e44ad;
+  --vp-c-brand-2: #9b59b6;
+  --vp-c-brand-3: #a569bd;
+  --vp-c-brand-soft: rgba(142, 68, 173, 0.16);
+
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe 30%, #41d1ff);
+}
+
+.VPImage.image-src {
+  filter: drop-shadow(0 0 2em #bd34feaa);
+}

package/docs/cron-tasks.md

@@ -0,0 +1,172 @@
+# Cron tasks
+
+## Usable even in scalable (multi-instance) applications
+
+Usable even in scalable (multi-instance) applications thanks to task registration in MongoDB.
+Mongodash will ensure each task is processed by only one instance at a time.
+
+You can see a short history of recent task runs here or even [manually trigger a task](#manual-task-run) if you need to!
+
+Also, check out the **[Dashboard](./dashboard.md)** for a visual interface to manage your tasks.
+```
+cronTasks
+```
+
+## cronTask(taskId, interval, taskFunction) => Promise
+
+```typescript
+cronTask(taskId, interval, taskFunction) => Promise
+```
+
+Register a cron task.
+
+```typescript
+import { cronTask } from 'mongodash';
+
+cronTask('my-task-id', '5m 20s', async () => {
+    console.log('Hurray the task is running!');
+});
+```
+
+That's it! Now the task will run every 5 minutes and 20 seconds!
+
+## First task registration also starts the internal loop
+
+First task registration also starts the internal loop watching for a task to run.
+This can be prevented by calling [`stopCronTasks()`](#stopcrontasks--void) or passing `runCronTasks: false` option to [mongodash init](#initialization-options-optional).
+
+## Valid values for interval argument
+
+The interval can be specified in several formats:
+
+*   **Duration string**: supported by [parse-duration](https://www.npmjs.com/package/parse-duration)
+    ```typescript
+    "5m 20s"
+    ```
+*   **Number**: milliseconds
+    ```typescript
+    5 * 60 * 1000
+    ```
+*   **CRON expression**: supported by [cron-parser](https://www.npmjs.com/package/cron-parser). **Must start with the `CRON ` prefix**.
+    ```typescript
+    "CRON */5 * * * *"
+    ```
+
+It also supports functions returning dynamic next run times:
+
+```typescript
+() => new Date() // next run at specific date
+```
+
+```typescript
+() => "5m 20s" // dynamic interval
+```
+
+```typescript
+() => "CRON */5 * * * *"
+```
+
+```typescript
+() => 5 * 60 * 1000
+```
+
+## scheduleCronTaskImmediately(taskId) => Promise
+
+```typescript
+scheduleCronTaskImmediately(taskId) => Promise
+```
+
+Schedule the task to run as soon as possible. Handy for cases when you need to hurry up a task based on another task or an API call.
+
+```typescript
+import { scheduleCronTaskImmediately } from 'mongodash';
+scheduleCronTaskImmediately('my-task-id');
+```
+
+## runCronTask(taskId) => Promise
+
+```typescript
+runCronTask(taskId) => Promise
+```
+
+Run a task and return a promise. The promise is resolved as soon as the task is done. The main purpose of the function is to easily test the tasks in automated tests.
+
+```typescript
+import { runCronTask } from 'mongodash';
+runCronTask('my-task-id');
+```
+
+## Do not use the runCronTask method inside a cron task
+
+**Do not use the runCronTask method inside a cron task.**
+It will not work. Use non-blocking [`scheduleCronTaskImmediately`](#schedulecrontaskimmediatelytaskid--promise) instead.
+
+## stopCronTasks() => void
+
+```typescript
+stopCronTasks() => void
+```
+
+Stop triggering registered tasks. Useful for automated tests, where is usually not desired to run tasks in the background. Calling stopCronTasks function before the first cronTask registration will prevent running any task.
+
+```typescript
+import { stopCronTasks } from 'mongodash'; 
+stopCronTasks();
+```
+
+## startCronTasks() => void
+
+```typescript
+startCronTasks() => void
+```
+
+Start triggering registered tasks. Usually not needed to call, since the registered tasks run automatically after the registration unless stopCronTasks is called or the mongodash is initialized with `runCronTasks: false`.
+
+```typescript
+import { startCronTasks } from 'mongodash';
+startCronTasks();
+```
+
+## Initialization options (optional)
+
+```typescript
+import mongodash from 'mongodash';
+
+mongodash.init({
+    // database connection
+    uri: 'mongodb://mongodb0.example.com:27017',
+    
+    // true by default
+    runCronTasks: false,
+
+    // valid only if CRON expressions used
+    // see https://www.npmjs.com/package/cron-parser for valid options
+    cronExpressionParserOptions: {
+        tz: 'Europe/Athens',
+    },
+});
+```
+
+## Manual task run
+
+Need to manually trigger a task outside the application? Mongodash Cron tasks allow you to speed up task processing by setting `runImmediately` flag to true. Just find and update the task document in `cronTasks` collection. This is helpful in a deployment environment to speed up a process.
+
+```typescript
+// In cronTasks collection
+{
+    _id: "my-task-id",
+    runImmediately: true
+}
+```
+
+## Performance & Scalability
+
+### Distributed Locking
+The system handles concurrency by locking tasks in MongoDB.
+- **Default Lock Duration**: 5 minutes.
+- **Auto-Renewal**: For long-running tasks, the lock is automatically refreshed every 15 seconds to prevent other instances from picking up the task while it's still running.
+
+### Execution History
+The system maintains a brief execution history in the database:
+- **Limit**: Only the **last 5 runs** are stored in the `runLog` of the task document.
+- Use this to monitor recent successes or failures.

package/docs/dashboard.md

@@ -0,0 +1,117 @@
+# Mongodash Dashboard
+
+The Mongodash Dashboard is a built-in administration interface for monitoring and managing your Reactive and Cron tasks. It is framework-agnostic and can be easily integrated into your existing Node.js application (Express, Koa, Fastify, or plain `http`).
+
+## Purpose
+
+The dashboard provides a visual overview of your task system's health and operational state. It allows you to:
+- **Monitor** the status of all reactive and cron tasks (pending, processing, completed, failed).
+- **Debug** issues by viewing error messages and stack traces directly in the UI.
+- **Retry** failed reactive tasks manually or in bulk based on filters.
+- **Trigger** cron tasks immediately for testing or ad-hoc execution.
+- **Analyze** performance by viewing execution history and last observed values (internal state is hidden by default).
+
+## Look and Feel
+![Dashboard Screenshot](./assets/dashboard.png)
+
+The dashboard features a clean, responsive UI with two main sections:
+
+### 1. Sidebar Navigation
+- **Task Collections**: Quickly navigate between reactive tasks grouped by their source collection.
+- **Live Stats**: See real-time counts of pending, processing, and failed tasks for each collection.
+    - **Error Counts**: An orange badge indicates the total number of errors encountered by tasks in that group.
+- **Cron Tasks**: View next run times for scheduled jobs directly in the sidebar.
+
+### 2. Reactive Tasks View
+Displays a paginated list of all reactive tasks.
+- **Filters**: Filter tasks by Name, Status (e.g., `failed`, `pending`), Error Message, and **Source Document ID**.
+    - **URL Sync**: All filters are automatically synchronized with the URL query parameters, making it easy to share specific views (e.g., "Show me all failed email tasks").
+- **Source Doc ID Filter**: A smart search that accepts exact strings, ObjectIDs, or numbers to find tasks related to a specific source document.
+- **Bulk Actions**:
+    - **Retry Matching**: A button to retry all tasks that match the current filters.
+
+### 3. Cron Tasks View
+Displays a list of all registered cron tasks.
+- **Status**: Shows the next scheduled run time (relative time) and the last execution status.
+- **Actions**:
+    - **Trigger Now**: A button to immediately execute a cron task, regardless of its schedule.
+
+## Integration
+
+You can mount the dashboard on any route in your application. The `serveDashboard` function handles both API requests and static asset serving.
+
+### Express
+```typescript
+import * as express from 'express';
+import { serveDashboard } from 'mongodash';
+
+const app = express();
+
+app.use('/dashboard', async (req, res, next) => {
+    // Check if mongodash handled the request
+    const handled = await serveDashboard(req, res);
+    if (!handled) {
+        next();
+    }
+});
+
+app.listen(3000);
+```
+
+### Koa
+```typescript
+import * as Koa from 'koa';
+import { serveDashboard } from 'mongodash';
+
+const app = new Koa();
+
+app.use(async (ctx, next) => {
+    // Koa's ctx.req and ctx.res are the native Node.js objects
+    // serveDashboard is mounted at root or check ctx.path manually if needed
+    if (ctx.path.startsWith('/dashboard')) {
+        const handled = await serveDashboard(ctx.req, ctx.res);
+        if (handled) return;
+    }
+    await next();
+});
+
+app.listen(3000);
+```
+
+### Native HTTP
+```typescript
+import * as http from 'http';
+import { serveDashboard } from 'mongodash';
+
+const server = http.createServer(async (req, res) => {
+    // Mount at /dashboard
+    if (req.url?.startsWith('/dashboard')) {
+        const handled = await serveDashboard(req, res);
+        if (handled) return;
+    }
+
+    res.statusCode = 404;
+    res.end('Not Found');
+});
+
+server.listen(3000);
+```
+
+## Manual Triggering & Retries
+
+While the system is autonomous, manual intervention might sometimes be handy.
+
+- **Reactive Tasks**: If tasks fail (e.g., due to a bug or temporary external outage), you can use the **Retry Matching** feature in the dashboard.
+    1. Filter for the failed tasks (e.g., Status: `failed`, Error: `Timeout`).
+    2. Click "**Retry now**".
+    3. Confirm the action.
+    - This will reschedule the tasks to `now` and reset their status to `pending`, allowing workers to pick them up immediately.
+    - **History Preserved**: Unlike a full reset, this action **preserves** the task's error history (attempt count, first error timestamp) for auditing purposes. The attempts count will only be reset if the task subsequently succeeds or if the source document changes (depending on `resetRetriesOnDataChange` policy).
+
+- **Cron Tasks**: You can force a cron task to run immediately via the **Trigger** button. This is helpful for testing cron logic without waiting for the schedule.
+
+## Architecture Notes
+
+### Read Preference
+- **Sidebar Statistics**: By default, the dashboard fetches statistics (counts, Sidebar badges) using `secondaryPreferred` read preference to minimize load on the Primary node.
+- **Task Lists**: The main task lists (table views) use the default read preference of your MongoDB connection (usually `primary`).