fire2mongo 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,317 @@
+import { Db, Collection } from 'mongodb';
+
+interface ConnectionConfig {
+    uri: string;
+    dbName: string;
+}
+/**
+ * Initialize the MongoDB connection. Call once at app startup.
+ * Safe to call multiple times — returns cached instance after first call.
+ *
+ * @example
+ * await initMongoDB({ uri: process.env.MONGODB_URI!, dbName: process.env.MONGODB_DB! });
+ */
+declare function initMongoDB(config: ConnectionConfig): Promise<Db>;
+/**
+ * Get the cached Db instance.
+ * Throws if initMongoDB() has not been called.
+ */
+declare function getDb(): Db;
+/**
+ * Close the MongoDB connection. Useful for graceful shutdown or tests.
+ */
+declare function closeMongoDB(): Promise<void>;
+
+/**
+ * Register a single Firebase collection name → MongoDB collection name.
+ * If mongoCollection is omitted, uses the same name as firebaseName.
+ *
+ * @example
+ * registerCollection('users');
+ * registerCollection('items', { mongoCollection: 'inventory_items' });
+ */
+declare function registerCollection(firebaseName: string, options?: {
+    mongoCollection?: string;
+}): void;
+/**
+ * Register multiple collections at once.
+ * Key = Firebase collection name, Value = MongoDB collection name.
+ *
+ * @example
+ * registerCollections({
+ *   users:    'users',
+ *   products: 'inventory_items',
+ * });
+ */
+declare function registerCollections(map: Record<string, string>): void;
+/**
+ * Returns true if the collection is registered.
+ */
+declare function hasCollection(firebaseName: string): boolean;
+/**
+ * Resolves a Firebase collection name to a live MongoDB Collection.
+ * Throws with a helpful message if the collection is not registered.
+ */
+declare function getCollection(firebaseName: string): Collection;
+/**
+ * Clear all registered collections. Useful for tests.
+ */
+declare function clearRegistry(): void;
+
+/**
+ * TypeScript interfaces mirroring the Firebase Firestore public API
+ */
+interface DocumentReference<T = any> {
+    id: string;
+    path: string;
+    collection: string;
+    _parentPath?: string;
+}
+interface CollectionReference<T = any> {
+    id: string;
+    path: string;
+    _mongoCollection: string;
+    _parentPath?: string;
+}
+interface Query<T = any> {
+    _collectionRef: CollectionReference<T>;
+    _filters: QueryConstraint[];
+}
+interface DocumentSnapshot<T = any> {
+    id: string;
+    exists(): boolean;
+    data(): T | undefined;
+}
+interface QueryDocumentSnapshot<T = any> {
+    id: string;
+    exists(): boolean;
+    data(): T;
+}
+interface QuerySnapshot<T = any> {
+    docs: QueryDocumentSnapshot<T>[];
+    size: number;
+    empty: boolean;
+    forEach(callback: (doc: QueryDocumentSnapshot<T>) => void): void;
+}
+type WhereFilterOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in' | 'array-contains-any';
+type OrderByDirection = 'asc' | 'desc';
+interface QueryConstraint {
+    type: 'where' | 'orderBy' | 'limit' | 'offset' | 'and' | 'or';
+    field?: string;
+    operator?: WhereFilterOp;
+    value?: any;
+    direction?: OrderByDirection;
+    count?: number;
+    queries?: QueryConstraint[];
+}
+interface SetOptions {
+    merge?: boolean;
+    mergeFields?: string[];
+}
+type WithId<T> = T & {
+    id: string;
+};
+type WithOptionalId<T> = T & {
+    id?: string;
+};
+
+type DocumentData = {
+    [field: string]: any;
+};
+/**
+ * Get a document reference.
+ *
+ * @example
+ * doc(db, 'users', userId)
+ * doc(db, 'orders', orderId, 'items', itemId)  // subcollection
+ * doc(collectionRef)                             // auto-generate ID
+ */
+declare function doc<T = any>(dbOrCollection: any, collectionPath?: string, ...pathSegments: string[]): DocumentReference<T>;
+/**
+ * Get a collection reference.
+ *
+ * @example
+ * collection(db, 'users')
+ * collection(db, 'orders', orderId, 'items')  // subcollection → MongoDB: orders_items
+ */
+declare function collection<T = any>(_db: any, collectionPath: string, ...pathSegments: string[]): CollectionReference<T>;
+/**
+ * Get a single document by reference.
+ *
+ * @example
+ * const snap = await getDoc(doc(db, 'users', id));
+ * if (snap.exists()) { const user = snap.data(); }
+ */
+declare function getDoc<T = any>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+/**
+ * Get all documents matching a query or collection reference.
+ *
+ * @example
+ * const snap = await getDocs(query(collection(db, 'users'), where('active', '==', true)));
+ * snap.forEach(doc => console.log(doc.data()));
+ */
+declare function getDocs<T = any>(queryOrRef: Query<T> | CollectionReference<T>): Promise<QuerySnapshot<T>>;
+/**
+ * Create or overwrite a document.
+ * Pass `{ merge: true }` to do a partial update instead of overwrite.
+ *
+ * @example
+ * await setDoc(doc(db, 'users', id), userData);
+ * await setDoc(doc(db, 'users', id), { name: 'New' }, { merge: true });
+ */
+declare function setDoc<T = any>(reference: DocumentReference<T>, data: T, options?: SetOptions): Promise<void>;
+/**
+ * Add a new document with an auto-generated ID.
+ * Returns a DocumentReference for the new document.
+ *
+ * @example
+ * const ref = await addDoc(collection(db, 'orders'), orderData);
+ * console.log(ref.id);
+ */
+declare function addDoc<T = any>(reference: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
+/**
+ * Partially update a document. Only provided fields are changed.
+ *
+ * @example
+ * await updateDoc(doc(db, 'users', id), { status: 'ACTIVE' });
+ * await updateDoc(ref, { tags: arrayUnion('premium') });
+ */
+declare function updateDoc<T = any>(reference: DocumentReference<T>, data: Partial<T>): Promise<void>;
+/**
+ * Delete a document.
+ *
+ * @example
+ * await deleteDoc(doc(db, 'users', id));
+ */
+declare function deleteDoc<T = any>(reference: DocumentReference<T>): Promise<void>;
+/** Build a query from a collection reference and constraints. */
+declare function query<T = any>(collectionRef: CollectionReference<T>, ...constraints: QueryConstraint[]): Query<T>;
+/** Filter by field value. */
+declare function where(field: string, op: WhereFilterOp, value: any): QueryConstraint;
+/** Explicit AND grouping. */
+declare function and(...queries: QueryConstraint[]): QueryConstraint;
+/** OR grouping — translates to MongoDB $or. */
+declare function or(...queries: QueryConstraint[]): QueryConstraint;
+/** Sort results. */
+declare function orderBy(field: string, direction?: OrderByDirection): QueryConstraint;
+/** Limit number of results. */
+declare function limit(count: number): QueryConstraint;
+/** Skip the first n results. */
+declare function offset(count: number): QueryConstraint;
+interface WriteBatch {
+    set<T>(ref: DocumentReference<T>, data: T, options?: SetOptions): WriteBatch;
+    update<T>(ref: DocumentReference<T>, data: Partial<T>): WriteBatch;
+    delete<T>(ref: DocumentReference<T>): WriteBatch;
+    commit(): Promise<void>;
+}
+/**
+ * Batch multiple write operations. Not atomic — ops run in parallel.
+ *
+ * @example
+ * const batch = writeBatch(db);
+ * batch.set(ref1, data);
+ * batch.update(ref2, { status: 'DONE' });
+ * await batch.commit();
+ */
+declare function writeBatch(_db: any): WriteBatch;
+interface Transaction {
+    get<T>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+    set<T>(ref: DocumentReference<T>, data: T, options?: SetOptions): Transaction;
+    update<T>(ref: DocumentReference<T>, data: Partial<T>): Transaction;
+    delete<T>(ref: DocumentReference<T>): Transaction;
+}
+/**
+ * Best-effort transaction. Reads are immediate; writes are collected and run
+ * in parallel after the callback returns. Not true ACID — no rollback on failure.
+ *
+ * @example
+ * await runTransaction(db, async (tx) => {
+ *   const snap = await tx.get(ref);
+ *   tx.update(ref, { count: (snap.data()?.count ?? 0) + 1 });
+ * });
+ */
+declare function runTransaction<T>(_db: any, fn: (tx: Transaction) => Promise<T>): Promise<T>;
+/** Dummy db export for drop-in compatibility with firebase _db imports. */
+declare function getFirestore(): any;
+
+/**
+ * Firebase-compatible Timestamp class.
+ * Serializes as a JavaScript Date when stored in MongoDB.
+ */
+declare class Timestamp {
+    private readonly _seconds;
+    private readonly _nanoseconds;
+    constructor(_seconds: number, _nanoseconds: number);
+    get seconds(): number;
+    get nanoseconds(): number;
+    /** Current time */
+    static now(): Timestamp;
+    /** From a JavaScript Date */
+    static fromDate(date: Date): Timestamp;
+    /** From epoch milliseconds */
+    static fromMillis(ms: number): Timestamp;
+    /** Convert to JavaScript Date */
+    toDate(): Date;
+    /** Convert to epoch milliseconds */
+    toMillis(): number;
+    isEqual(other: Timestamp): boolean;
+    toString(): string;
+    /** MongoDB serialization — stored as Date */
+    toJSON(): Date;
+    valueOf(): Date;
+}
+
+/**
+ * Firebase-compatible FieldValue sentinel class.
+ * Used to express atomic array/increment operations in updateDoc / setDoc.
+ */
+declare class FieldValue {
+    readonly type: 'arrayUnion' | 'arrayRemove' | 'increment';
+    readonly elements: any[];
+    constructor(type: 'arrayUnion' | 'arrayRemove' | 'increment', elements: any[]);
+}
+/**
+ * Add elements to an array field (no duplicates).
+ * Translates to MongoDB $addToSet: { $each: [...] }
+ *
+ * @example
+ * await updateDoc(ref, { tags: arrayUnion('premium', 'verified') });
+ */
+declare function arrayUnion(...elements: any[]): FieldValue;
+/**
+ * Remove all instances of specified elements from an array field.
+ * Translates to MongoDB $pull: { $in: [...] }
+ *
+ * @example
+ * await updateDoc(ref, { tags: arrayRemove('trial') });
+ */
+declare function arrayRemove(...elements: any[]): FieldValue;
+/**
+ * Increment a numeric field by n.
+ * Translates to MongoDB $inc: { field: n }
+ *
+ * @example
+ * await updateDoc(ref, { viewCount: increment(1) });
+ */
+declare function increment(n: number): FieldValue;
+
+/**
+ * fire2mongo
+ *
+ * Drop-in TypeScript replacement for firebase/firestore backed by MongoDB.
+ * Swap one import line — no other code changes required.
+ *
+ * @example
+ * // Before (Firebase)
+ * import { doc, getDoc, setDoc, collection, getDocs, query, where } from 'firebase/firestore';
+ * import { db } from '@/lib/firebase';
+ *
+ * // After (MongoDB)
+ * import { doc, getDoc, setDoc, collection, getDocs, query, where } from 'fire2mongo';
+ * import { db } from 'fire2mongo';
+ */
+
+/** No-op db object — kept so existing `import { db } from 'firebase'` lines compile unchanged. */
+declare const db: {};
+
+export { type CollectionReference, type DocumentData, type DocumentReference, type DocumentSnapshot, FieldValue, type OrderByDirection, type Query, type QueryConstraint, type QueryDocumentSnapshot, type QuerySnapshot, type SetOptions, Timestamp, type Transaction, type WhereFilterOp, type WithId, type WithOptionalId, type WriteBatch, addDoc, and, arrayRemove, arrayUnion, clearRegistry, closeMongoDB, collection, db, deleteDoc, doc, getCollection, getDb, getDoc, getDocs, getFirestore, hasCollection, increment, initMongoDB, limit, offset, or, orderBy, query, registerCollection, registerCollections, runTransaction, setDoc, updateDoc, where, writeBatch };

package/dist/index.d.ts

@@ -0,0 +1,317 @@
+import { Db, Collection } from 'mongodb';
+
+interface ConnectionConfig {
+    uri: string;
+    dbName: string;
+}
+/**
+ * Initialize the MongoDB connection. Call once at app startup.
+ * Safe to call multiple times — returns cached instance after first call.
+ *
+ * @example
+ * await initMongoDB({ uri: process.env.MONGODB_URI!, dbName: process.env.MONGODB_DB! });
+ */
+declare function initMongoDB(config: ConnectionConfig): Promise<Db>;
+/**
+ * Get the cached Db instance.
+ * Throws if initMongoDB() has not been called.
+ */
+declare function getDb(): Db;
+/**
+ * Close the MongoDB connection. Useful for graceful shutdown or tests.
+ */
+declare function closeMongoDB(): Promise<void>;
+
+/**
+ * Register a single Firebase collection name → MongoDB collection name.
+ * If mongoCollection is omitted, uses the same name as firebaseName.
+ *
+ * @example
+ * registerCollection('users');
+ * registerCollection('items', { mongoCollection: 'inventory_items' });
+ */
+declare function registerCollection(firebaseName: string, options?: {
+    mongoCollection?: string;
+}): void;
+/**
+ * Register multiple collections at once.
+ * Key = Firebase collection name, Value = MongoDB collection name.
+ *
+ * @example
+ * registerCollections({
+ *   users:    'users',
+ *   products: 'inventory_items',
+ * });
+ */
+declare function registerCollections(map: Record<string, string>): void;
+/**
+ * Returns true if the collection is registered.
+ */
+declare function hasCollection(firebaseName: string): boolean;
+/**
+ * Resolves a Firebase collection name to a live MongoDB Collection.
+ * Throws with a helpful message if the collection is not registered.
+ */
+declare function getCollection(firebaseName: string): Collection;
+/**
+ * Clear all registered collections. Useful for tests.
+ */
+declare function clearRegistry(): void;
+
+/**
+ * TypeScript interfaces mirroring the Firebase Firestore public API
+ */
+interface DocumentReference<T = any> {
+    id: string;
+    path: string;
+    collection: string;
+    _parentPath?: string;
+}
+interface CollectionReference<T = any> {
+    id: string;
+    path: string;
+    _mongoCollection: string;
+    _parentPath?: string;
+}
+interface Query<T = any> {
+    _collectionRef: CollectionReference<T>;
+    _filters: QueryConstraint[];
+}
+interface DocumentSnapshot<T = any> {
+    id: string;
+    exists(): boolean;
+    data(): T | undefined;
+}
+interface QueryDocumentSnapshot<T = any> {
+    id: string;
+    exists(): boolean;
+    data(): T;
+}
+interface QuerySnapshot<T = any> {
+    docs: QueryDocumentSnapshot<T>[];
+    size: number;
+    empty: boolean;
+    forEach(callback: (doc: QueryDocumentSnapshot<T>) => void): void;
+}
+type WhereFilterOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in' | 'array-contains-any';
+type OrderByDirection = 'asc' | 'desc';
+interface QueryConstraint {
+    type: 'where' | 'orderBy' | 'limit' | 'offset' | 'and' | 'or';
+    field?: string;
+    operator?: WhereFilterOp;
+    value?: any;
+    direction?: OrderByDirection;
+    count?: number;
+    queries?: QueryConstraint[];
+}
+interface SetOptions {
+    merge?: boolean;
+    mergeFields?: string[];
+}
+type WithId<T> = T & {
+    id: string;
+};
+type WithOptionalId<T> = T & {
+    id?: string;
+};
+
+type DocumentData = {
+    [field: string]: any;
+};
+/**
+ * Get a document reference.
+ *
+ * @example
+ * doc(db, 'users', userId)
+ * doc(db, 'orders', orderId, 'items', itemId)  // subcollection
+ * doc(collectionRef)                             // auto-generate ID
+ */
+declare function doc<T = any>(dbOrCollection: any, collectionPath?: string, ...pathSegments: string[]): DocumentReference<T>;
+/**
+ * Get a collection reference.
+ *
+ * @example
+ * collection(db, 'users')
+ * collection(db, 'orders', orderId, 'items')  // subcollection → MongoDB: orders_items
+ */
+declare function collection<T = any>(_db: any, collectionPath: string, ...pathSegments: string[]): CollectionReference<T>;
+/**
+ * Get a single document by reference.
+ *
+ * @example
+ * const snap = await getDoc(doc(db, 'users', id));
+ * if (snap.exists()) { const user = snap.data(); }
+ */
+declare function getDoc<T = any>(reference: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+/**
+ * Get all documents matching a query or collection reference.
+ *
+ * @example
+ * const snap = await getDocs(query(collection(db, 'users'), where('active', '==', true)));
+ * snap.forEach(doc => console.log(doc.data()));
+ */
+declare function getDocs<T = any>(queryOrRef: Query<T> | CollectionReference<T>): Promise<QuerySnapshot<T>>;
+/**
+ * Create or overwrite a document.
+ * Pass `{ merge: true }` to do a partial update instead of overwrite.
+ *
+ * @example
+ * await setDoc(doc(db, 'users', id), userData);
+ * await setDoc(doc(db, 'users', id), { name: 'New' }, { merge: true });
+ */
+declare function setDoc<T = any>(reference: DocumentReference<T>, data: T, options?: SetOptions): Promise<void>;
+/**
+ * Add a new document with an auto-generated ID.
+ * Returns a DocumentReference for the new document.
+ *
+ * @example
+ * const ref = await addDoc(collection(db, 'orders'), orderData);
+ * console.log(ref.id);
+ */
+declare function addDoc<T = any>(reference: CollectionReference<T>, data: T): Promise<DocumentReference<T>>;
+/**
+ * Partially update a document. Only provided fields are changed.
+ *
+ * @example
+ * await updateDoc(doc(db, 'users', id), { status: 'ACTIVE' });
+ * await updateDoc(ref, { tags: arrayUnion('premium') });
+ */
+declare function updateDoc<T = any>(reference: DocumentReference<T>, data: Partial<T>): Promise<void>;
+/**
+ * Delete a document.
+ *
+ * @example
+ * await deleteDoc(doc(db, 'users', id));
+ */
+declare function deleteDoc<T = any>(reference: DocumentReference<T>): Promise<void>;
+/** Build a query from a collection reference and constraints. */
+declare function query<T = any>(collectionRef: CollectionReference<T>, ...constraints: QueryConstraint[]): Query<T>;
+/** Filter by field value. */
+declare function where(field: string, op: WhereFilterOp, value: any): QueryConstraint;
+/** Explicit AND grouping. */
+declare function and(...queries: QueryConstraint[]): QueryConstraint;
+/** OR grouping — translates to MongoDB $or. */
+declare function or(...queries: QueryConstraint[]): QueryConstraint;
+/** Sort results. */
+declare function orderBy(field: string, direction?: OrderByDirection): QueryConstraint;
+/** Limit number of results. */
+declare function limit(count: number): QueryConstraint;
+/** Skip the first n results. */
+declare function offset(count: number): QueryConstraint;
+interface WriteBatch {
+    set<T>(ref: DocumentReference<T>, data: T, options?: SetOptions): WriteBatch;
+    update<T>(ref: DocumentReference<T>, data: Partial<T>): WriteBatch;
+    delete<T>(ref: DocumentReference<T>): WriteBatch;
+    commit(): Promise<void>;
+}
+/**
+ * Batch multiple write operations. Not atomic — ops run in parallel.
+ *
+ * @example
+ * const batch = writeBatch(db);
+ * batch.set(ref1, data);
+ * batch.update(ref2, { status: 'DONE' });
+ * await batch.commit();
+ */
+declare function writeBatch(_db: any): WriteBatch;
+interface Transaction {
+    get<T>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+    set<T>(ref: DocumentReference<T>, data: T, options?: SetOptions): Transaction;
+    update<T>(ref: DocumentReference<T>, data: Partial<T>): Transaction;
+    delete<T>(ref: DocumentReference<T>): Transaction;
+}
+/**
+ * Best-effort transaction. Reads are immediate; writes are collected and run
+ * in parallel after the callback returns. Not true ACID — no rollback on failure.
+ *
+ * @example
+ * await runTransaction(db, async (tx) => {
+ *   const snap = await tx.get(ref);
+ *   tx.update(ref, { count: (snap.data()?.count ?? 0) + 1 });
+ * });
+ */
+declare function runTransaction<T>(_db: any, fn: (tx: Transaction) => Promise<T>): Promise<T>;
+/** Dummy db export for drop-in compatibility with firebase _db imports. */
+declare function getFirestore(): any;
+
+/**
+ * Firebase-compatible Timestamp class.
+ * Serializes as a JavaScript Date when stored in MongoDB.
+ */
+declare class Timestamp {
+    private readonly _seconds;
+    private readonly _nanoseconds;
+    constructor(_seconds: number, _nanoseconds: number);
+    get seconds(): number;
+    get nanoseconds(): number;
+    /** Current time */
+    static now(): Timestamp;
+    /** From a JavaScript Date */
+    static fromDate(date: Date): Timestamp;
+    /** From epoch milliseconds */
+    static fromMillis(ms: number): Timestamp;
+    /** Convert to JavaScript Date */
+    toDate(): Date;
+    /** Convert to epoch milliseconds */
+    toMillis(): number;
+    isEqual(other: Timestamp): boolean;
+    toString(): string;
+    /** MongoDB serialization — stored as Date */
+    toJSON(): Date;
+    valueOf(): Date;
+}
+
+/**
+ * Firebase-compatible FieldValue sentinel class.
+ * Used to express atomic array/increment operations in updateDoc / setDoc.
+ */
+declare class FieldValue {
+    readonly type: 'arrayUnion' | 'arrayRemove' | 'increment';
+    readonly elements: any[];
+    constructor(type: 'arrayUnion' | 'arrayRemove' | 'increment', elements: any[]);
+}
+/**
+ * Add elements to an array field (no duplicates).
+ * Translates to MongoDB $addToSet: { $each: [...] }
+ *
+ * @example
+ * await updateDoc(ref, { tags: arrayUnion('premium', 'verified') });
+ */
+declare function arrayUnion(...elements: any[]): FieldValue;
+/**
+ * Remove all instances of specified elements from an array field.
+ * Translates to MongoDB $pull: { $in: [...] }
+ *
+ * @example
+ * await updateDoc(ref, { tags: arrayRemove('trial') });
+ */
+declare function arrayRemove(...elements: any[]): FieldValue;
+/**
+ * Increment a numeric field by n.
+ * Translates to MongoDB $inc: { field: n }
+ *
+ * @example
+ * await updateDoc(ref, { viewCount: increment(1) });
+ */
+declare function increment(n: number): FieldValue;
+
+/**
+ * fire2mongo
+ *
+ * Drop-in TypeScript replacement for firebase/firestore backed by MongoDB.
+ * Swap one import line — no other code changes required.
+ *
+ * @example
+ * // Before (Firebase)
+ * import { doc, getDoc, setDoc, collection, getDocs, query, where } from 'firebase/firestore';
+ * import { db } from '@/lib/firebase';
+ *
+ * // After (MongoDB)
+ * import { doc, getDoc, setDoc, collection, getDocs, query, where } from 'fire2mongo';
+ * import { db } from 'fire2mongo';
+ */
+
+/** No-op db object — kept so existing `import { db } from 'firebase'` lines compile unchanged. */
+declare const db: {};
+
+export { type CollectionReference, type DocumentData, type DocumentReference, type DocumentSnapshot, FieldValue, type OrderByDirection, type Query, type QueryConstraint, type QueryDocumentSnapshot, type QuerySnapshot, type SetOptions, Timestamp, type Transaction, type WhereFilterOp, type WithId, type WithOptionalId, type WriteBatch, addDoc, and, arrayRemove, arrayUnion, clearRegistry, closeMongoDB, collection, db, deleteDoc, doc, getCollection, getDb, getDoc, getDocs, getFirestore, hasCollection, increment, initMongoDB, limit, offset, or, orderBy, query, registerCollection, registerCollections, runTransaction, setDoc, updateDoc, where, writeBatch };