mongofire 6.5.1

package/dist/types/index.d.ts

@@ -0,0 +1,224 @@
+import { EventEmitter } from 'events';
+
+// ─── Configuration ────────────────────────────────────────────────────────────
+
+export interface SyncConfig {
+  /** Local MongoDB URI. Default: 'mongodb://localhost:27017' */
+  localUri?: string;
+  /** MongoDB Atlas connection string. Required for sync; omit for local-only mode. */
+  atlasUri?: string;
+  /** Database name. Default: 'mongofire' */
+  dbName?: string;
+  /** Collection names to sync. Required. */
+  collections: string[];
+  /**
+   * Polling interval in milliseconds.
+   * Default: 5000 (5s) when realtime:true, 30000 (30s) when realtime:false
+   */
+  syncInterval?: number;
+  /** Upload/download batch size. Default: 200 */
+  batchSize?: number;
+  /**
+   * Owner key for multi-tenant filtering.
+   * Pass '*' to sync all owners (default), a string for a specific owner,
+   * or a function that returns the current owner key.
+   */
+  syncOwner?: string | (() => string);
+  /**
+   * Enable real-time sync via Atlas Change Streams.
+   * Requires a MongoDB Atlas cluster or a local replica set.
+   * Falls back to polling if unavailable.
+   * Default: false
+   */
+  realtime?: boolean;
+  /** Called after each successful sync cycle. */
+  onSync?: (result: SyncResult) => void;
+  /** Called when a sync cycle throws an unexpected error. */
+  onError?: (err: Error) => void;
+}
+
+// ─── Results ──────────────────────────────────────────────────────────────────
+
+export interface SyncResult {
+  /** Docs downloaded from Atlas to local */
+  downloaded: number;
+  /** Docs uploaded from local to Atlas */
+  uploaded: number;
+  /** Delete operations applied */
+  deleted: number;
+  /** Operations that failed (network errors, etc.) */
+  failed: number;
+  /** Operations that produced a version conflict */
+  conflicts: number;
+  /** Upload attempts that were automatically retried */
+  retried: number;
+  /** Ops skipped via compression (offline create+delete, superseded updates) */
+  skipped: number;
+}
+
+export interface SyncStatus {
+  /** Whether Atlas is currently reachable */
+  online: boolean;
+  /** Total local ops not yet synced to Atlas */
+  pending: number;
+  /** Pending create operations */
+  creates: number;
+  /** Pending update operations */
+  updates: number;
+  /** Pending delete operations */
+  deletes: number;
+  /** Whether real-time change streams are active */
+  realtime: boolean;
+}
+
+export interface OfflineResult {
+  error: 'offline';
+  pending: number;
+}
+
+// ─── Plugin ───────────────────────────────────────────────────────────────────
+
+export interface PluginOptions {
+  /**
+   * Dot-notation path to the field used as the owner key for multi-tenant
+   * filtering. Example: 'userId' or 'org._id'.
+   * Defaults to 'global' if not set.
+   */
+  ownerField?: string;
+  /** Batch size for insertMany / updateMany / deleteMany hooks. Default: 200 */
+  batchSize?: number;
+  /** Concurrent recordChange calls per batch. Default: 4 */
+  concurrency?: number;
+}
+
+// ─── Events ───────────────────────────────────────────────────────────────────
+
+export interface MongoFireEvents {
+  /** Emitted once after start() completes successfully */
+  ready: [];
+  /** Emitted after each sync cycle with the result */
+  sync: [result: SyncResult];
+  /** Emitted when Atlas connection is (re)established */
+  online: [];
+  /** Emitted when Atlas becomes unreachable */
+  offline: [];
+  /** Emitted when real-time change streams activate */
+  realtimeStarted: [];
+  /** Emitted when real-time change streams are stopped */
+  realtimeStopped: [];
+  /** Emitted when stop() finishes */
+  stopped: [];
+  /** Emitted on unexpected sync errors */
+  error: [err: Error];
+  /**
+   * Emitted when a version conflict is detected during upload.
+   * The application should inspect conflictData and resolve manually
+   * (e.g. fetch latest remote doc and re-apply changes).
+   */
+  conflict: [data: ConflictData];
+}
+
+/** Structured data emitted with the 'conflict' event. */
+export interface ConflictData {
+  /** Collection where the conflict occurred */
+  collection: string;
+  /** Document _id (as string) */
+  docId: string;
+  /** The opId of the conflicting local operation */
+  opId: string;
+  /** The local baseVersion that was expected on Atlas */
+  localVersion: number;
+  /** The actual version currently on Atlas */
+  remoteVersion: number;
+  /** Operation type: 'create' | 'update' | 'delete' */
+  op: string;
+}
+
+// ─── Main class ───────────────────────────────────────────────────────────────
+
+export declare class MongoFire extends EventEmitter {
+  /**
+   * Connect to local and Atlas MongoDB, run an initial sync, and start
+   * background polling. Concurrent calls share one init promise.
+   */
+  start(config: SyncConfig): Promise<this>;
+
+  /**
+   * Flush pending ops, wait for any active sync to finish, and close all
+   * connections.
+   * @param timeoutMs Max ms to wait for active sync. Default: 10000
+   */
+  stop(timeoutMs?: number): Promise<void>;
+
+  /**
+   * Manually trigger a sync cycle.
+   * Returns an OfflineResult immediately if Atlas is unreachable.
+   */
+  sync(type?: 'required' | 'all'): Promise<SyncResult | OfflineResult>;
+
+  /** Returns pending op counts and online status. */
+  status(): Promise<SyncStatus>;
+
+  /**
+   * Delete synced changetrack records older than `days` days.
+   * Default: 7 (matches Atlas TTL to keep both sides consistent)
+   * @returns Number of records deleted
+   */
+  clean(days?: number): Promise<number>;
+
+  /**
+   * Returns a Mongoose schema plugin that tracks changes on the given collection.
+   *
+   * @example
+   * import mongofire from 'mongofire';
+   * userSchema.plugin(mongofire.plugin('users', { ownerField: 'userId' }));
+   */
+  plugin(collectionName: string, options?: PluginOptions): (schema: import('mongoose').Schema) => void;
+
+  /** Manually activate real-time sync (if Atlas is connected and supports change streams). */
+  startRealtime(): Promise<boolean>;
+
+  /** Stop real-time change stream (polling continues). */
+  stopRealtime(): Promise<void>;
+
+  /** Whether Atlas is currently reachable. */
+  readonly online: boolean;
+  /** Whether start() has completed. */
+  readonly started: boolean;
+  /** Whether a sync cycle is currently running. */
+  readonly syncing: boolean;
+  /** Whether real-time change streams are active. */
+  readonly realtimeActive: boolean;
+
+  // ─── Typed event emitter overloads ────────────────────────────────────────
+  on<K extends keyof MongoFireEvents>(event: K, listener: (...args: MongoFireEvents[K]) => void): this;
+  once<K extends keyof MongoFireEvents>(event: K, listener: (...args: MongoFireEvents[K]) => void): this;
+  emit<K extends keyof MongoFireEvents>(event: K, ...args: MongoFireEvents[K]): boolean;
+  off<K extends keyof MongoFireEvents>(event: K, listener: (...args: MongoFireEvents[K]) => void): this;
+}
+
+// ─── Direct plugin import ─────────────────────────────────────────────────────
+
+/**
+ * Raw Mongoose plugin factory for direct schema.plugin() usage.
+ * Equivalent to mongofire.plugin(name, opts) but requires `collection` in options.
+ *
+ * @example
+ * import mongofirePlugin from 'mongofire/plugin';
+ * userSchema.plugin(mongofirePlugin, { collection: 'users', ownerField: 'userId' });
+ *
+ * @example
+ * // Or use the factory helper (matches instance.plugin() return shape):
+ * import { factory } from 'mongofire/plugin';
+ * userSchema.plugin(factory('users', { ownerField: 'userId' }));
+ */
+export declare function mongofirePlugin(schema: import('mongoose').Schema, options?: PluginOptions & { collection?: string }): void;
+export declare namespace mongofirePlugin {
+  function factory(collectionName: string, options?: PluginOptions): (schema: import('mongoose').Schema) => void;
+}
+
+// ─── Default export ───────────────────────────────────────────────────────────
+
+/** The default MongoFire singleton instance. */
+declare const mongofire: MongoFire & { MongoFire: typeof MongoFire };
+export default mongofire;

package/index.cjs

@@ -0,0 +1,4 @@
+'use strict';
+// Entry point → obfuscated dist/ (built by: npm run build)
+// Never edit this file — edit src/index.cjs instead
+module.exports = require('./dist/src/index.cjs');

package/index.mjs

@@ -0,0 +1,6 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+// Entry point → obfuscated dist/ (built by: npm run build)
+const mf = require('./dist/src/index.cjs');
+export default mf;
+export const MongoFire = mf.MongoFire;

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "mongofire",
+  "version": "6.5.1",
+  "description": "Offline-first MongoDB sync — Local + Atlas feel like ONE database. Automatic conflict resolution, Mongoose plugin, zero boilerplate.",
+  "main": "./index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "types": "./dist/types/index.d.ts",
+      "default": "./index.cjs"
+    },
+    "./plugin": {
+      "require": "./dist/src/plugin.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "bin": {
+    "mongofire": "./dist/bin/mongofire.cjs"
+  },
+  "scripts": {
+    "build": "node scripts/build.js",
+    "prepublishOnly": "npm run build",
+    "test": "node test/smoke.test.js",
+    "verify": "npm pack --dry-run",
+    "release:patch": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public",
+    "release:major": "npm version major && npm publish --access public"
+  },
+  "files": [
+    "dist/",
+    "index.cjs",
+    "index.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mongodb",
+    "mongoose",
+    "sync",
+    "atlas",
+    "offline-first",
+    "local-first",
+    "conflict-resolution",
+    "replication",
+    "offline",
+    "sync-engine",
+    "realtime",
+    "change-streams",
+    "typescript"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "dotenv": "^16.0.0"
+  },
+  "devDependencies": {
+    "javascript-obfuscator": "^4.1.1"
+  },
+  "peerDependencies": {
+    "mongodb": ">=4.0.0",
+    "mongoose": ">=7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mongoose": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOURNAME/mongofire.git"
+  },
+  "homepage": "https://github.com/YOURNAME/mongofire#readme",
+  "bugs": {
+    "url": "https://github.com/YOURNAME/mongofire/issues"
+  }
+}