mongofire 6.5.3 → 6.5.6

package/dist/types/index.d.ts

@@ -1,323 +1,278 @@
 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;
-  /**
-   * Run a reconciliation scan on every start() to recover writes lost due to
-   * a crash between the Mongoose data write and the changetrack insertOne.
-   * Default: true. Set false only if startup latency is critical.
-   */
-  reconcileOnStart?: boolean;
-  /**
-   * Include Phase 2 of reconciliation: scan the data collection for documents
-   * with no _mf_docmeta entry (written before MongoFire was initialized, or
-   * crash before recordChange() was called at all).
-   * Default: true. Set false to run only the fast orphaned-meta check (Phase 1).
-   */
-  reconcileFullScan?: boolean;
+// ─── 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[]}>;
 }
-
-// ─── Reconcile ────────────────────────────────────────────────────────────────
-
-/** Result for one collection from a reconciliation scan. */
-export interface ReconcileCollectionResult {
-  collection: string;
-  /** Phase 1 stats: orphaned _mf_docmeta rows (crash between version-bump and insertOne). */
-  phase1: { scanned: number; queued: number };
-  /** Phase 2 stats: docs with no _mf_docmeta entry at all (crash before recordChange ran). */
-  phase2: { scanned: number; queued: number };
-  /** Total ops re-queued for this collection. */
-  totalQueued: number;
-  /** Whether local MongoDB is a replica set (Phase 1 is skipped on replica sets). */
-  replicaSet: boolean;
-  /** Set if this collection's reconcile threw an error. */
-  error?: string;
+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 interface ReconcileResult {
-  collections: ReconcileCollectionResult[];
-  /** Total ops re-queued across all collections. */
-  totalQueued: 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;
 }
-
-// ─── Conflict record ──────────────────────────────────────────────────────────
-
-/** A changetrack record with ackState:'conflict' — unresolved sync conflict. */
-export interface ConflictRecord {
-  _id: unknown;
-  opId: string;
-  type: 'create' | 'update' | 'delete';
-  collection: string;
-  docId: string;
-  ownerKey: string;
-  baseVersion: number;
-  version: number;
-  timestamp: Date;
-  lastError?: string;
-  retryCount: number;
+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;
 
-// ─── 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;
-}
+// ─── 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>;
 
-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;
+// ─── 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;
 }
 
-export interface OfflineResult {
-  error: 'offline';
-  pending: number;
-}
+// ─── 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 {
-  /**
-   * 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;
-}
+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 {
-  /** 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.
+   * 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 {
   /**
-   * Emitted after a reconciliation scan completes (startup or manual).
-   * totalQueued > 0 means previously-lost writes were recovered and will sync
-   * on the next upload cycle.
+   * 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.
    */
-  reconcileComplete: [result: ReconcileResult];
+  ensureConnected(fallbackUri?: string, fallbackDbName?: string): Promise<void>;
   /**
-   * Emitted when SyncConfig.reconcileOnStart is true and conflicts are detected
-   * after the reconciliation scan finishes. Also emitted when clean() removes
-   * stale conflict records.
+   * Disconnect Mongoose and stop the spawned `mongod` process (if any).
+   * Called automatically by `mongofire.stop()`.
    */
-  conflictResolved: [data: { opId: string; resolution: 'retried' | 'dismissed' }];
-}
-
-/** 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;
+  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 {
   /**
-   * Connect to local and Atlas MongoDB, run an initial sync, and start
-   * background polling. Concurrent calls share one init promise.
+   * 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>;
 
   /**
-   * 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
+   * 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.
    */
-  stop(timeoutMs?: number): Promise<void>;
+  waitForLocal(): Promise<import('mongodb').Db>;
 
   /**
-   * Manually trigger a sync cycle.
-   * Returns an OfflineResult immediately if Atlas is unreachable.
+   * 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));
+   * ```
    */
-  sync(type?: 'required' | 'all'): Promise<SyncResult | OfflineResult>;
-
-  /** Returns pending op counts and online status. */
-  status(): Promise<SyncStatus>;
+  readonly localReady: Promise<import('mongodb').Db>;
 
   /**
-   * Delete old synced and stale conflict changetrack records.
+   * 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.
    *
-   * CRIT-6 FIX: The original clean() only removed records with synced:true.
-   * Conflict records (ackState:'conflict', synced:false) were never touched
-   * and grew indefinitely. This version also cleans stale conflict records.
-   *
-   * @param days          Delete synced records older than this many days. Default: 7
-   * @param opts.conflictDays  Delete conflict records older than this many days.
-   *                           Default: same as `days`.
-   * @returns Total number of records deleted
+   * Safe to call manually; `start()` is idempotent.
    */
-  clean(days?: number, opts?: { conflictDays?: number }): Promise<number>;
+  autoStart(): Promise<this>;
 
   /**
-   * Returns all unresolved conflict records, optionally filtered to one collection.
+   * **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);
+   * ```
    *
-   * @example
-   * const conflicts = await mongofire.conflicts();
-   * for (const c of conflicts) {
-   *   console.log(`Conflict in ${c.collection}/${c.docId} — local v${c.version}, error: ${c.lastError}`);
-   *   await mongofire.retryConflict(c.opId);    // retry upload
-   *   // OR
-   *   await mongofire.dismissConflict(c.opId);  // accept local state, discard record
-   * }
+   * @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()`
    */
-  conflicts(collection?: string): Promise<ConflictRecord[]>;
+  startApp(app: { listen: (port: number, cb?: (err?: Error) => void) => import('http').Server }, port?: number | string): Promise<import('http').Server>;
 
-  /**
-   * Reset a conflict record back to 'pending' so the next sync cycle retries
-   * the upload.  Use this after manually resolving the remote state on Atlas.
-   */
+  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>;
-
-  /**
-   * Dismiss a conflict record — marks it as resolved without retrying the upload.
-   * Use this when the local write should be silently discarded (remote wins).
-   * The record is marked synced:true so the TTL index will clean it up.
-   */
   dismissConflict(opId: string): Promise<void>;
-
   /**
-   * Returns a Mongoose schema plugin that tracks changes on the given collection.
-   *
-   * @example
-   * import mongofire from 'mongofire';
-   * userSchema.plugin(mongofire.plugin('users', { ownerField: 'userId' }));
+   * 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;
-
-  /** 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>;
-
-  /**
-   * Run a reconciliation scan to recover any writes that were lost due to a
-   * crash between the Mongoose data write and the changetrack insertOne.
-   *
-   * Also runs automatically at startup (controlled by `reconcileOnStart` config).
-   *
-   * @param collectionOrOpts  A single collection name, an array of names, or
-   *                          an options object to scan all configured collections.
-   * @param opts              { fullScan?: boolean; verbose?: boolean }
-   *
-   * @example
-   * // Scan all collections
-   * const results = await mongofire.reconcile();
-   *
-   * @example
-   * // Scan one collection, Phase 1 only (fast)
-   * await mongofire.reconcile('orders', { fullScan: false });
-   *
-   * @example
-   * // Listen for recovery events
-   * mongofire.on('reconcileComplete', ({ totalQueued }) => {
-   *   if (totalQueued > 0) console.warn(`Recovered ${totalQueued} lost writes`);
-   * });
-   */
-  reconcile(
-    collectionOrOpts?: string | string[] | { fullScan?: boolean; verbose?: boolean },
-    opts?: { fullScan?: boolean; verbose?: boolean }
-  ): Promise<ReconcileCollectionResult[]>;
-
-  /** Whether Atlas is currently reachable. */
+  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;
-  /** 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 ────────────────────────────────────────
+  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;
@@ -325,27 +280,38 @@ export declare class MongoFire extends EventEmitter {
 }
 
 // ─── 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) ─────
 /**
- * Raw Mongoose plugin factory for direct schema.plugin() usage.
- * Equivalent to mongofire.plugin(name, opts) but requires `collection` in options.
+ * Starts the Express app after waiting for local MongoDB.
+ * Exits the process if the DB is unavailable.
  *
- * @example
- * import mongofirePlugin from 'mongofire/plugin';
- * userSchema.plugin(mongofirePlugin, { collection: 'users', ownerField: 'userId' });
+ * ```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.
  *
- * @example
- * // Or use the factory helper (matches instance.plugin() return shape):
- * import { factory } from 'mongofire/plugin';
- * userSchema.plugin(factory('users', { ownerField: 'userId' }));
+ * ```ts
+ * import { plugin } from './mongofire.js';
+ * UserSchema.plugin(plugin('users'));
+ * StudentSchema.plugin(plugin('students', { 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;
-}
+export declare function plugin(
+  collectionName: string,
+  options?: PluginOptions
+): (schema: import('mongoose').Schema) => void;
 
 // ─── Default export ───────────────────────────────────────────────────────────
-
-/** The default MongoFire singleton instance. */
-declare const mongofire: MongoFire & { MongoFire: typeof MongoFire };
+declare const mongofire: MongoFire & { MongoFire: typeof MongoFire; startApp: typeof startApp; plugin: typeof plugin; };
 export default mongofire;

package/index.cjs

@@ -1,4 +1,18 @@
 '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');
+// index.cjs — MongoFire entry point
+//
+// Resolution order:
+//   1. ./dist/src/index.cjs  — built production bundle (created by `npm run build`)
+//   2. ./src/index.cjs       — live source (fallback for local dev / npm link)
+//
+// ⚠️  If you see errors referencing dist/src/index.cjs after updating the
+//     source, run `npm run build` (or delete the dist/ folder) to clear the
+//     stale build.  The dist/ folder is NOT included in the git repo and must
+//     be regenerated after every source change.
+let _mod;
+try {
+  _mod = require('./dist/src/index.cjs');
+} catch (_) {
+  _mod = require('./src/index.cjs');
+}
+module.exports = _mod;