mongofire 6.5.3 → 6.5.6

package/index.mjs

@@ -1,6 +1,11 @@
 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');
+// Fall back to src/ if dist/ has not been built yet (same as index.cjs).
+let mf;
+try {
+  mf = require('./dist/src/index.cjs');
+} catch (_) {
+  mf = require('./src/index.cjs');
+}
 export default mf;
 export const MongoFire = mf.MongoFire;

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "mongofire",
-  "version": "6.5.3",
+  "version": "6.5.6",
   "description": "Offline-first MongoDB sync — Local + Atlas feel like ONE database. Automatic conflict resolution, Mongoose plugin, interactive CLI, zero boilerplate.",
   "main": "./index.cjs",
   "types": "./dist/types/index.d.ts",
   "exports": {
     ".": {
+      "types": "./types/index.d.ts",
       "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"
+      "types": "./types/index.d.ts",
+      "import": "./dist/src/plugin.mjs",
+      "require": "./dist/src/plugin.js"
     }
   },
   "bin": {
@@ -24,15 +25,16 @@
     "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"
+    "postpublish": "bash scripts/sync-public.sh",
+    "release:patch": "npm version patch --no-git-tag-version && npm publish --access public",
+    "release:minor": "npm version minor --no-git-tag-version && npm publish --access public",
+    "release:major": "npm version major --no-git-tag-version && npm publish --access public"
   },
   "files": [
     "dist/",
-    "bin/",
     "index.cjs",
     "index.mjs",
+    "types/",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -40,14 +42,14 @@
   "keywords": [
     "mongodb",
     "mongoose",
-    "sync",
     "atlas",
+    "sync",
     "offline-first",
     "local-first",
-    "conflict-resolution",
-    "replication",
     "offline",
     "sync-engine",
+    "replication",
+    "conflict-resolution",
     "realtime",
     "change-streams",
     "typescript"
@@ -57,16 +59,16 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "dotenv": "^16.0.0",
-    "inquirer": "^8.0.0"
+    "@clack/prompts": "^1.1.0"
   },
   "devDependencies": {
-    "javascript-obfuscator": "^4.1.1"
+    "javascript-obfuscator": "^4.1.1",
+    "terser": "^5.27.0"
   },
   "peerDependencies": {
+    "dotenv": ">=16.0.0",
     "mongodb": ">=4.0.0",
-    "mongoose": ">=7.0.0",
-    "dotenv": ">=16.0.0"
+    "mongoose": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "mongoose": {

package/types/index.d.ts

@@ -0,0 +1,317 @@
+import { EventEmitter } from 'events';
+
+// ─── Utility types ────────────────────────────────────────────────────────────
+type MaybePromise<T> = T | Promise<T>;
+type Timestamp = Date | number;
+type DocId = string;
+type CircuitBreakerState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
+
+// ─── JSON Patch / Diff ───────────────────────────────────────────────────────
+export interface JsonPatchOp { op: 'add'|'remove'|'replace'|'move'|'copy'|'test'; path: string; value?: unknown; from?: string; }
+export interface PatchPayload { _mf_patch: JsonPatchOp[]; _mf_full: Record<string,unknown>; _mf_fieldCount: number; _mf_changedFields: string[]; _mf_patchSize: number; _mf_fullSize: number; _mf_field_meta?: FieldMeta; }
+export interface DiffResult { patch: JsonPatchOp[]; fieldCount: number; changedFields: string[]; }
+export interface CompressResult { data: unknown; compressed: boolean; encoding?: 'gzip+base64'; originalSize: number; compressedSize: number; }
+export declare function computeDiff(original: Record<string,unknown>, updated: Record<string,unknown>): DiffResult | null;
+export declare function buildUpdatePayload(doc: Record<string,unknown>, diffResult: DiffResult | null): Record<string,unknown> | PatchPayload;
+export declare function applyPatch(baseDoc: Record<string,unknown> | null, payload: Record<string,unknown> | PatchPayload): Record<string,unknown>;
+export declare function isPatchPayload(payload: unknown): payload is PatchPayload;
+export declare function compressPayload(payload: unknown): Promise<CompressResult>;
+export declare function decompressPayload(data: string | unknown, compressed: boolean): Promise<unknown>;
+
+// ─── Field-level Merge ────────────────────────────────────────────────────────
+export interface FieldMetaEntry { ts: number; deviceId: string; version: number; }
+export type FieldMeta = Record<string, FieldMetaEntry>;
+export interface MergeResult { merged: Record<string,unknown>; resolvedFields: Record<string,'local'|'remote'>; conflictedFields: Record<string,{local:unknown;remote:unknown;winner:'local'|'remote'}>; }
+export declare function buildFieldMeta(patch: object[], timestamp: Timestamp, deviceId: string, version: number): FieldMeta;
+export declare function mergeFields(baseDoc: Record<string,unknown>, localMeta: {_mf_field_meta?: FieldMeta}, remotePayload: Record<string,unknown>, remoteMeta: {timestamp:Timestamp;deviceId:string;version:number;field_meta?:FieldMeta}): MergeResult;
+export declare function hasFieldOverlap(opA: {payload?:{_mf_field_meta?:FieldMeta;_mf_patch?:object[]}}, opB: {payload?:{_mf_field_meta?:FieldMeta;_mf_patch?:object[]}}): boolean;
+export declare function mergeScore(mergeResult: Pick<MergeResult,'resolvedFields'|'conflictedFields'>): number;
+
+// ─── Schema Manager ───────────────────────────────────────────────────────────
+export type MigrationFn<T=Record<string,unknown>> = (doc: T) => MaybePromise<T>;
+export type ValidatorFn<T=Record<string,unknown>> = (doc: T) => string[];
+export interface ValidationResult { valid: boolean; errors: string[]; }
+export interface SchemaRegistryEntry { collection: string; currentVersion: number; versions: number[]; updatedAt: Date; }
+export declare class SchemaManager {
+  register<T=Record<string,unknown>>(collection: string, version: number, migrateFn: MigrationFn<T>): void;
+  registerValidator<T=Record<string,unknown>>(collection: string, version: number, validateFn: ValidatorFn<T>): void;
+  currentVersion(collection: string): number;
+  needsMigration(collection: string, doc: Record<string,unknown>): boolean;
+  migrate<T=Record<string,unknown>>(collection: string, doc: T): Promise<T & {_mf_schemaVersion:number}>;
+  migrateBatch<T=Record<string,unknown>>(collection: string, docs: T[], concurrency?: number): Promise<Array<T & {_mf_schemaVersion:number}>>;
+  validate(collection: string, doc: Record<string,unknown>): ValidationResult;
+  persistRegistry(conn?: unknown): Promise<void>;
+  getRegistry(conn?: unknown): Promise<SchemaRegistryEntry[]>;
+  list(): Array<{collection:string;currentVersion:number;versions:number[]}>;
+}
+export declare const schemaManager: SchemaManager;
+
+// ─── Rate Limiter ─────────────────────────────────────────────────────────────
+export interface TokenBucketOptions { capacity?: number; refillRate?: number; initialFill?: number; }
+export interface CircuitBreakerOptions { failureThreshold?: number; successThreshold?: number; timeout?: number; halfOpenMax?: number; name?: string; }
+export interface SyncRateLimiterOptions { tokenBucket?: TokenBucketOptions; circuitBreaker?: CircuitBreakerOptions; }
+export interface CircuitBreakerStats { name: string; state: CircuitBreakerState; failureCount: number; successCount: number; lastFailureAt: number|null; }
+export interface TokenBucketStats { available: number; capacity: number; refillRate: number; throttleCount: number; }
+export interface SyncRateLimiterStats { tokenBucket: TokenBucketStats; circuitBreaker: CircuitBreakerStats; }
+export declare class TokenBucket {
+  constructor(opts?: TokenBucketOptions);
+  consume(count?: number): boolean;
+  waitAndConsume(count?: number, timeoutMs?: number): Promise<boolean>;
+  waitTimeMs(count?: number): number;
+  readonly available: number;
+}
+export declare class CircuitBreaker {
+  constructor(opts?: CircuitBreakerOptions);
+  execute<T>(fn: ()=>Promise<T>): Promise<T>;
+  reset(): void;
+  on(event:'open'|'close'|'halfOpen', listener:(d:{prev:CircuitBreakerState;current:CircuitBreakerState})=>void): this;
+  stats(): CircuitBreakerStats;
+  readonly state: CircuitBreakerState;
+  readonly isOpen: boolean;
+  readonly isClosed: boolean;
+}
+export declare class CircuitOpenError extends Error { readonly circuitData: {state:CircuitBreakerState;retryAfterMs:number}; readonly retryAfterMs: number; }
+export declare class SyncRateLimiter {
+  constructor(opts?: SyncRateLimiterOptions);
+  execute<T>(fn:()=>Promise<T>, tokenCost?: number, timeoutMs?: number): Promise<T>;
+  isBlocked(): boolean;
+  recordSuccess(): void;
+  recordFailure(err?: Error): void;
+  stats(): SyncRateLimiterStats;
+  reset(): void;
+  readonly circuitBreaker: CircuitBreaker;
+  readonly tokenBucket: TokenBucket;
+}
+export declare class RateLimitError extends Error { readonly rateLimitData: {availableIn: number}; }
+export declare function backoffDelay(attempt: number, baseDelayMs?: number, maxDelayMs?: number, strategy?: 'full'|'decorrelated'|'exponential'): number;
+
+// ─── Log Compactor ────────────────────────────────────────────────────────────
+export interface CompactionOptions { conn?: unknown; retentionDays?: number; batchSize?: number; collection?: string; verbose?: boolean; }
+export interface CompactionResult { scanned: number; deleted: number; kept: number; durationMs: number; }
+export interface CompactionStats { totalSynced: number; oldSynced: number; retentionDays: number; cutoffDate: Date; collections: Array<{collection:string;count:number}>; estimatedDeletable: number; }
+export declare function compactChangelog(opts?: CompactionOptions): Promise<CompactionResult>;
+export declare function getCompactionStats(opts?: Omit<CompactionOptions,'batchSize'>): Promise<CompactionStats>;
+
+// ─── Configuration ────────────────────────────────────────────────────────────
+export interface SyncConfig {
+  localUri?: string; atlasUri?: string; dbName?: string;
+  collections: string[];
+  syncInterval?: number; batchSize?: number;
+  syncOwner?: string | (()=>string);
+  realtime?: boolean;
+  onSync?: (result: SyncResult) => void;
+  onError?: (err: Error) => void;
+  cleanDays?: number;
+  reconcileOnStart?: boolean; reconcileFullScan?: boolean;
+  rateLimiter?: SyncRateLimiterOptions;
+  schemaManager?: SchemaManager;
+  /** Enable per-field LWW merge. Firebase can't do this. Default: true */
+  fieldLevelMerge?: boolean;
+  autoCompact?: boolean; compactEvery?: number; compactRetentionDays?: number;
+  compression?: boolean;
+}
+
+// ─── Results & Status ─────────────────────────────────────────────────────────
+export interface SyncResult { downloaded: number; uploaded: number; deleted: number; failed: number; conflicts: number; retried: number; skipped: number; fieldMerged?: number; }
+export interface SyncStatus { online: boolean; pending: number; creates: number; updates: number; deletes: number; realtime: boolean; circuitBreaker?: CircuitBreakerState; rateLimiter?: SyncRateLimiterStats; }
+export interface OfflineResult { error: 'offline'; pending: number; }
+export interface ConflictRecord { _id: unknown; opId: string; type: 'create'|'update'|'delete'; collection: string; docId: DocId; ownerKey: string; baseVersion: number; version: number; timestamp: Date; lastError?: string; retryCount: number; mergeAttempted?: boolean; }
+export interface ReconcileCollectionResult { collection: string; phase1: {scanned:number;queued:number}; phase2: {scanned:number;queued:number}; totalQueued: number; replicaSet: boolean; error?: string; }
+
+// ─── Plugin ───────────────────────────────────────────────────────────────────
+export interface PluginOptions { ownerField?: string; batchSize?: number; concurrency?: number; diffEnabled?: boolean; }
+
+// ─── Events ───────────────────────────────────────────────────────────────────
+export interface ConflictData { collection: string; docId: DocId; opId: string; localVersion: number; remoteVersion: number; op: 'create'|'update'|'delete'; fieldMerge?: {attempted:boolean;resolvedFields:Record<string,'local'|'remote'>;conflictedFields:Record<string,{local:unknown;remote:unknown;winner:'local'|'remote'}>;score:number}; }
+export interface MongoFireEvents {
+  /**
+   * Fires as soon as the local MongoDB connection is live — BEFORE Atlas
+   * connect, reconcile, or the sync timers start.  Use this to gate
+   * `app.listen()` so the server never accepts requests before the DB is ready.
+   */
+  localReady: [db: import('mongodb').Db];
+  ready: []; sync: [result: SyncResult]; online: []; offline: [];
+  realtimeStarted: []; realtimeStopped: []; stopped: []; error: [err: Error];
+  conflict: [data: ConflictData];
+  fieldMerged: [data: {collection:string;docId:DocId;opId:string;resolvedFields:Record<string,'local'|'remote'>;score:number}];
+  reconcileComplete: [result: {collections:ReconcileCollectionResult[];totalQueued:number}];
+  conflictResolved: [data: {opId:string;resolution:'retried'|'dismissed'}];
+  compacted: [result: CompactionResult];
+  circuitOpen: [data: {retryAfterMs:number}]; circuitClose: [];
+  migrated: [data: {collection:string;docId:DocId;fromVersion:number;toVersion:number}];
+}
+
+// ─── Internal document structure ──────────────────────────────────────────────
+export interface MfDocFields { _mf_version: number; _mf_lastWriterDeviceId: string; _mf_opId: string; _mf_lastOpId: string; _mf_schemaVersion?: number; }
+export interface ChangetrackRecord extends MfDocFields { _id: unknown; opId: string; type: 'create'|'update'|'delete'; collection: string; docId: DocId; payload: Record<string,unknown>|PatchPayload|null; ownerKey: string; deviceId: string; timestamp: Date; updatedAt: Date; baseVersion: number; version: number; lastWriterDeviceId: string; payloadChecksum: string|null; synced: boolean; ackState: 'pending'|'acked'|'verified'|'conflict'|'error'|'compressed'|'superseded'|'dismissed'; retryCount: number; createdAt: Date; syncedAt: Date|null; remoteAckAt: Date|null; checksumVerifiedAt: Date|null; lastError: string|null; applyStatus?: 'pending'|'applied'|'conflict'; }
+export interface DocMetaRecord { _id: string; collection: string; docId: DocId; version: number; updatedAt: Date; lastWriterDeviceId: string; deleted: boolean; ownerKey: string; updatedByOpId: string|null; lastOpId: string|null; payloadChecksum: string|null; createdAt: Date; }
+
+// ─── LocalManager ─────────────────────────────────────────────────────────────
+/**
+ * Auto-manages the Mongoose connection to local MongoDB.
+ * Spawns `mongod` via the system binary if MongoDB is not running,
+ * and retries until the connection succeeds.
+ *
+ * **Developers should never call `mongoose.connect()` directly.**
+ * MongoFire calls `ensureConnected()` internally during `start()`.
+ */
+export declare class LocalManager {
+  /**
+   * Ensure Mongoose is connected to local MongoDB.
+   * Idempotent — returns immediately if already connected.
+   * Uses `process.env.LOCAL_URI` / `process.env.DB_NAME`, falling back to
+   * the supplied values when the env vars are absent.
+   */
+  ensureConnected(fallbackUri?: string, fallbackDbName?: string): Promise<void>;
+  /**
+   * Disconnect Mongoose and stop the spawned `mongod` process (if any).
+   * Called automatically by `mongofire.stop()`.
+   */
+  closeAll(): Promise<void>;
+  readonly isConnected: boolean;
+  readonly mongodProcess: import('child_process').ChildProcess | null;
+}
+/** Singleton LocalManager shared across all MongoFire instances in the process. */
+export declare const localManager: LocalManager;
+
+// ─── Main class ───────────────────────────────────────────────────────────────
+export declare class MongoFire extends EventEmitter {
+  /**
+   * Start MongoFire with the given config.  Connects to local MongoDB first,
+   * then Atlas.  The returned Promise resolves when Atlas is connected and the
+   * initial sync is complete (or when Atlas is determined to be offline).
+   *
+   * **Do not call `mongoose.connect()` manually** — MongoFire manages this.
+   * Use `localReady` / `waitForLocal()` to gate `app.listen()` instead.
+   */
+  start(config: SyncConfig): Promise<this>;
+
+  /**
+   * Returns a Promise that resolves with the native `Db` handle as soon as the
+   * LOCAL MongoDB connection is ready — before Atlas connect, reconcile, or
+   * the sync timer start.
+   *
+   * Use this to gate `app.listen()` so incoming requests never arrive before
+   * the local database is available:
+   *
+   * ```js
+   * const { localReady } = require('./mongofire');
+   * localReady.then(() => app.listen(3000));
+   * // or: await mongofire.waitForLocal(); app.listen(3000);
+   * ```
+   *
+   * If `start()` has not been called yet (and no `mongofire.config.js` was
+   * found for auto-start), this Promise rejects after 60 s with a clear
+   * "did you forget to call start()?" message.
+   */
+  waitForLocal(): Promise<import('mongodb').Db>;
+
+  /**
+   * Convenience alias for `waitForLocal()` — a Promise getter so you can
+   * destructure it at module level without calling a function:
+   *
+   * ```js
+   * const { localReady } = require('./mongofire');
+   * localReady.then(() => app.listen(3000));
+   * ```
+   */
+  readonly localReady: Promise<import('mongodb').Db>;
+
+  /**
+   * Automatically loads `mongofire.config.js` (or `.cjs` / `.mjs`) from
+   * `process.cwd()` and calls `start(config)`.  Called internally when the
+   * package is required outside the CLI context so that users do not need a
+   * separate `mongofire.js` entry file.
+   *
+   * Safe to call manually; `start()` is idempotent.
+   */
+  autoStart(): Promise<this>;
+
+  /**
+   * **Primary developer API** — replaces `app.listen()`.
+   *
+   * Waits for local MongoDB to be ready, then starts the Express (or any
+   * Node `http.Server`) application on the given port.  If the local DB
+   * fails to connect, logs a descriptive error and calls `process.exit(1)`
+   * so the server never starts in a broken state.
+   *
+   * ```js
+   * // server.js
+   * import { startApp } from './mongofire.js';
+   * startApp(app, process.env.PORT || 3000);
+   * ```
+   *
+   * @param app  Any object with a `.listen(port, callback)` method (Express, Fastify, etc.)
+   * @param port TCP port to listen on (default: 3000)
+   * @returns    Promise resolving to the `http.Server` returned by `app.listen()`
+   */
+  startApp(app: { listen: (port: number, cb?: (err?: Error) => void) => import('http').Server }, port?: number | string): Promise<import('http').Server>;
+
+  stop(timeoutMs?: number): Promise<void>;
+  sync(type?: 'required'|'all'): Promise<SyncResult|OfflineResult>;
+  status(): Promise<SyncStatus>;
+  clean(days?: number, opts?: {conflictDays?:number}): Promise<number>;
+  conflicts(collection?: string): Promise<ConflictRecord[]>;
+  retryConflict(opId: string): Promise<void>;
+  dismissConflict(opId: string): Promise<void>;
+  /**
+   * Drops all MongoFire internal collections and the configured data
+   * collections so the next `start()` performs a clean bootstrap from Atlas.
+   * **Any unsynced local changes are permanently lost.**
+   */
+  resetLocal(): Promise<{ dropped: number }>;
+  plugin(collectionName: string, options?: PluginOptions): (schema: import('mongoose').Schema) => void;
+  startRealtime(): Promise<boolean>;
+  stopRealtime(): Promise<void>;
+  reconcile(collectionOrOpts?: string|string[]|{fullScan?:boolean;verbose?:boolean}, opts?: {fullScan?:boolean;verbose?:boolean}): Promise<ReconcileCollectionResult[]>;
+  compact(opts?: CompactionOptions): Promise<CompactionResult>;
+  rateLimiterStats(): SyncRateLimiterStats | null;
+  resetCircuit(): void;
+  readonly online: boolean;
+  readonly started: boolean;
+  readonly syncing: boolean;
+  readonly realtimeActive: boolean;
+  readonly schemaManager: SchemaManager | null;
+  readonly rateLimiter: SyncRateLimiter | null;
+  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 ─────────────────────────────────────────────────────
+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; }
+
+// ─── Standalone named exports (destructurable from the package / wrapper) ─────
+/**
+ * Starts the Express app after waiting for local MongoDB.
+ * Exits the process if the DB is unavailable.
+ *
+ * ```ts
+ * import { startApp } from './mongofire.js';
+ * startApp(app, 3000);
+ * ```
+ */
+export declare function startApp(
+  app: { listen: (port: number, cb?: (err?: Error) => void) => import('http').Server },
+  port?: number | string
+): Promise<import('http').Server>;
+
+/**
+ * Attaches MongoFire change-tracking to a Mongoose schema.
+ *
+ * ```ts
+ * import { plugin } from './mongofire.js';
+ * UserSchema.plugin(plugin('users'));
+ * StudentSchema.plugin(plugin('students', { ownerField: 'userId' }));
+ * ```
+ */
+export declare function plugin(
+  collectionName: string,
+  options?: PluginOptions
+): (schema: import('mongoose').Schema) => void;
+
+// ─── Default export ───────────────────────────────────────────────────────────
+declare const mongofire: MongoFire & { MongoFire: typeof MongoFire; startApp: typeof startApp; plugin: typeof plugin; };
+export default mongofire;