flongo 1.0.0

package/README.md

@@ -0,0 +1,261 @@
+# Flongo 🔥🍃
+
+**Firestore-like fluent query API for MongoDB**
+
+Flongo brings the intuitive, chainable query syntax of Firestore to MongoDB, making database operations more readable and developer-friendly.
+
+## Installation
+
+```bash
+npm install flongo
+```
+
+## Quick Start
+
+```typescript
+import { initializeFlongo, FlongoCollection, FlongoQuery } from 'flongo';
+
+// Initialize MongoDB connection
+initializeFlongo({
+  connectionString: 'mongodb://localhost:27017',
+  dbName: 'myapp'
+});
+
+// Define your data interface
+interface User {
+  name: string;
+  email: string;
+  age: number;
+  tags: string[];
+}
+
+// Create a collection
+const users = new FlongoCollection<User>('users');
+
+// Query with fluent API
+const adults = await users.getAll(
+  new FlongoQuery()
+    .where('age').gtEq(18)
+    .and('tags').arrContainsAny(['developer', 'designer'])
+    .orderBy('name')
+);
+```
+
+## Features
+
+- 🔗 **Chainable queries** - Firestore-like fluent API
+- 🚀 **TypeScript support** - Full type safety and IntelliSense
+- 📊 **Rich query operations** - Comparisons, arrays, geospatial, text search
+- 🎛️ **Configurable** - Optional event logging, custom error handling
+- 🧪 **Battle-tested** - Extracted from production codebase
+- 📦 **Zero config** - Works with existing MongoDB setup
+
+## API Reference
+
+### Basic Queries
+
+```typescript
+const query = new FlongoQuery();
+
+// Equality
+query.where('status').eq('active')
+
+// Comparisons
+query.where('age').gt(21).and('age').lt(65)
+query.where('score').gtEq(80).and('score').ltEq(100)
+query.where('status').neq('deleted')
+
+// Arrays
+query.where('tags').arrContains('featured')
+query.where('categories').arrContainsAny(['tech', 'design'])
+query.where('skills').arrContainsAll(['js', 'react'])
+query.where('id').in(['user1', 'user2', 'user3'])
+query.where('role').notIn(['admin', 'banned'])
+
+// Text search
+query.where('name').startsWith('John')
+query.where('email').endsWith('@gmail.com')
+query.where('bio').strContains('developer')
+
+// Ranges
+query.inRange('price', 100, 500)
+```
+
+### Advanced Queries
+
+```typescript
+// OR queries
+const activeOrFeatured = new FlongoQuery()
+  .where('status').eq('active')
+  .or(
+    new FlongoQuery().where('featured').eq(true)
+  );
+
+// Geospatial queries
+query.where('location').geoWithin({
+  ne: { latitude: 40.7829, longitude: -73.9441 },
+  sw: { latitude: 40.7489, longitude: -73.9441 }
+});
+
+// Radius search
+query.inRadius('location', { latitude: 40.7589, longitude: -73.9851 }, 1000);
+
+// Sorting and pagination
+const results = await collection.getAll(
+  query.orderBy('createdAt', SortDirection.Descending),
+  { offset: 0, count: 20 }
+);
+```
+
+### Collection Operations
+
+```typescript
+const collection = new FlongoCollection<User>('users');
+
+// Create
+const user = await collection.create({
+  name: 'John Doe',
+  email: 'john@example.com',
+  age: 30,
+  tags: ['developer']
+});
+
+// Read
+const user = await collection.get('user123');
+const users = await collection.getAll(query);
+const first = await collection.getFirst(query);
+const count = await collection.count(query);
+const exists = await collection.exists(query);
+
+// Update
+await collection.update('user123', { age: 31 });
+await collection.updateAll({ status: 'verified' }, query);
+await collection.increment('user123', 'loginCount', 1);
+await collection.append('user123', 'tags', ['admin']);
+
+// Delete
+await collection.delete('user123');
+await collection.batchDelete(['user1', 'user2']);
+
+// Batch operations
+await collection.batchCreate([user1, user2, user3]);
+```
+
+### Configuration
+
+```typescript
+// Disable event logging
+const collection = new FlongoCollection<User>('users', {
+  enableEventLogging: false
+});
+
+// Custom events collection
+const collection = new FlongoCollection<User>('users', {
+  enableEventLogging: true,
+  eventsCollectionName: 'audit_logs'
+});
+```
+
+## Examples
+
+### E-commerce Product Search
+
+```typescript
+interface Product {
+  name: string;
+  price: number;
+  category: string;
+  tags: string[];
+  inStock: boolean;
+  rating: number;
+}
+
+const products = new FlongoCollection<Product>('products');
+
+// Find affordable, well-rated tech products in stock
+const results = await products.getAll(
+  new FlongoQuery()
+    .where('category').eq('electronics')
+    .and('price').ltEq(500)
+    .and('rating').gtEq(4.0)
+    .and('inStock').eq(true)
+    .and('tags').arrContainsAny(['laptop', 'phone', 'tablet'])
+    .orderBy('rating', SortDirection.Descending)
+);
+```
+
+### User Management
+
+```typescript
+interface User {
+  email: string;
+  role: string;
+  lastLogin: number;
+  preferences: string[];
+  location?: Coordinates;
+}
+
+const users = new FlongoCollection<User>('users');
+
+// Find active users who haven't logged in recently
+const staleUsers = await users.getAll(
+  new FlongoQuery()
+    .where('role').neq('admin')
+    .and('lastLogin').lt(Date.now() - 30 * 24 * 60 * 60 * 1000) // 30 days ago
+    .orderBy('lastLogin', SortDirection.Ascending)
+);
+
+// Find users interested in specific topics near a location
+const nearbyDevs = await users.getAll(
+  new FlongoQuery()
+    .where('preferences').arrContainsAny(['javascript', 'react', 'node'])
+    .and('location').inRadius(
+      'location',
+      { latitude: 37.7749, longitude: -122.4194 }, // San Francisco
+      10000 // 10km radius
+    )
+);
+```
+
+## Error Handling
+
+```typescript
+import { Error404, Error400 } from 'flongo';
+
+try {
+  const user = await users.get('nonexistent-id');
+} catch (error) {
+  if (error instanceof Error404) {
+    console.log('User not found');
+  }
+}
+```
+
+## Migration from Firestore
+
+Flongo's API closely mirrors Firestore, making migration straightforward:
+
+```typescript
+// Firestore
+const snapshot = await db.collection('users')
+  .where('age', '>=', 18)
+  .where('tags', 'array-contains-any', ['developer', 'designer'])
+  .orderBy('name')
+  .get();
+
+// Flongo
+const users = await collection.getAll(
+  new FlongoQuery()
+    .where('age').gtEq(18)
+    .and('tags').arrContainsAny(['developer', 'designer'])
+    .orderBy('name')
+);
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class Error404 extends Error {
+    constructor(message?: string);
+}
+export declare class Error400 extends Error {
+    constructor(message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,19 @@
+"use strict";
+// Simple error classes for flongo
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Error400 = exports.Error404 = void 0;
+class Error404 extends Error {
+    constructor(message = "Not found") {
+        super(message);
+        this.name = "Error404";
+    }
+}
+exports.Error404 = Error404;
+class Error400 extends Error {
+    constructor(message = "Bad request") {
+        super(message);
+        this.name = "Error400";
+    }
+}
+exports.Error400 = Error400;
+//# sourceMappingURL=errors.js.map

package/dist/flongo.d.ts

@@ -0,0 +1,9 @@
+import { Db, MongoClient } from "mongodb";
+export declare let flongoClient: MongoClient;
+export declare let flongoDb: Db;
+export interface FlongoConfig {
+    connectionString: string;
+    dbName: string;
+}
+export declare function initializeFlongo(config: FlongoConfig): void;
+//# sourceMappingURL=flongo.d.ts.map

package/dist/flongo.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flongoDb = exports.flongoClient = void 0;
+exports.initializeFlongo = initializeFlongo;
+const mongodb_1 = require("mongodb");
+function initializeFlongo(config) {
+    exports.flongoClient = new mongodb_1.MongoClient(config.connectionString);
+    exports.flongoDb = exports.flongoClient.db(config.dbName);
+}
+//# sourceMappingURL=flongo.js.map

package/dist/flongoCollection.d.ts

@@ -0,0 +1,192 @@
+import { FlongoQuery } from "./flongoQuery";
+import { Entity, Event, EventName, Pagination, Repository } from "./types";
+/**
+ * Configuration options for FlongoCollection instances
+ */
+export interface FlongoCollectionOptions {
+    /** Whether to enable automatic event logging for CRUD operations */
+    enableEventLogging?: boolean;
+    /** Name of the collection to store events in (defaults to "events") */
+    eventsCollectionName?: string;
+}
+/**
+ * FlongoCollection provides a high-level interface for MongoDB collection operations
+ * with automatic entity management, event logging, and fluent query support.
+ *
+ * This class abstracts MongoDB collection operations and provides:
+ * - Automatic _id conversion between ObjectId and string
+ * - Timestamps management (createdAt, updatedAt)
+ * - Optional event logging for audit trails
+ * - Integration with FlongoQuery for fluent querying
+ * - Type-safe operations with TypeScript generics
+ *
+ * Example usage:
+ * ```typescript
+ * interface User {
+ *   name: string;
+ *   email: string;
+ *   age: number;
+ * }
+ *
+ * const users = new FlongoCollection<User>('users');
+ *
+ * // Create a user
+ * const user = await users.create({ name: 'John', email: 'john@example.com', age: 30 });
+ *
+ * // Query users
+ * const adults = await users.getAll(
+ *   new FlongoQuery().where('age').gtEq(18)
+ * );
+ * ```
+ */
+export declare class FlongoCollection<T> {
+    /** The underlying MongoDB collection */
+    private collection;
+    /** Events collection for audit logging (null if logging disabled) */
+    private events;
+    /** Collection name for event logging */
+    private name;
+    /** Configuration options */
+    private options;
+    /**
+     * Creates a new FlongoCollection instance
+     * @param collectionName - Name of the MongoDB collection
+     * @param options - Configuration options for the collection
+     */
+    constructor(collectionName: Repository, options?: FlongoCollectionOptions);
+    /**
+     * Retrieves a single document by its ID
+     * @param id - Document ID (string that will be converted to ObjectId)
+     * @returns Promise resolving to the document with Entity metadata
+     * @throws Error404 if document is not found
+     */
+    get(id: string): Promise<Entity & T>;
+    /**
+     * Converts MongoDB document to Entity format
+     * Converts ObjectId _id to string and ensures proper typing
+     * @private
+     * @param obj - Raw MongoDB document
+     * @returns Document with string _id and Entity typing
+     */
+    private toEntity;
+    /**
+     * Retrieves multiple documents based on query and pagination
+     * @param query - Optional FlongoQuery for filtering
+     * @param pagination - Optional pagination settings
+     * @returns Promise resolving to array of documents
+     */
+    getAll(query?: FlongoQuery, pagination?: Pagination): Promise<(Entity & T)[]>;
+    /**
+     * Retrieves a subset of documents with required query and pagination
+     * Similar to getAll but requires both query and pagination parameters
+     * @param query - FlongoQuery for filtering (required)
+     * @param pagination - Pagination settings (required)
+     * @returns Promise resolving to array of documents
+     */
+    getSome(query: FlongoQuery, pagination: Pagination): Promise<(Entity & T)[]>;
+    /**
+     * Retrieves the first document matching the query
+     * @param query - FlongoQuery for filtering
+     * @returns Promise resolving to the first matching document
+     */
+    getFirst(query: FlongoQuery): Promise<Entity & T>;
+    /**
+     * Counts documents matching the query
+     * @param query - Optional FlongoQuery for filtering
+     * @returns Promise resolving to the count of matching documents
+     */
+    count(query?: FlongoQuery): Promise<number>;
+    /**
+     * Checks if any documents match the query
+     * @param query - FlongoQuery for filtering
+     * @returns Promise resolving to true if any documents match, false otherwise
+     */
+    exists(query: FlongoQuery): Promise<boolean>;
+    /**
+     * Deletes a single document by ID
+     * Logs the deletion event with backup data before deleting
+     * @param id - Document ID to delete
+     * @param clientId - ID of the client performing the deletion (for audit trail)
+     */
+    delete(id: string, clientId: string): Promise<void>;
+    /**
+     * Deletes multiple documents by their IDs
+     * Logs batch deletion event with backup data before deleting
+     * @param ids - Array of document IDs to delete
+     * @param clientId - ID of the client performing the deletion
+     */
+    batchDelete(ids: string[], clientId: string): Promise<void>;
+    /**
+     * Creates a new document in the collection
+     * Automatically adds timestamps and logs the creation event
+     * @param attributes - Document data (without Entity metadata)
+     * @param clientId - Optional client ID for audit trail
+     * @returns Promise resolving to the created document with Entity metadata
+     */
+    create(attributes: T, clientId?: string): Promise<Entity & T>;
+    /**
+     * Creates multiple documents in a single batch operation
+     * More efficient than individual creates for large datasets
+     * @param attributes - Array of document data
+     * @param clientId - Optional client ID for audit trail
+     */
+    batchCreate(attributes: T[], clientId?: string): Promise<void>;
+    /**
+     * Updates multiple documents matching the query
+     * @param attributes - Fields to update
+     * @param query - Optional FlongoQuery to filter documents (updates all if not provided)
+     * @param clientId - Optional client ID for audit trail
+     */
+    updateAll(attributes: any, query?: FlongoQuery, clientId?: string): Promise<void>;
+    /**
+     * Updates a single document by ID
+     * @param id - Document ID to update
+     * @param attributes - Fields to update
+     * @param clientId - Optional client ID for audit trail
+     */
+    update(id: string, attributes: any, clientId?: string): Promise<void>;
+    /**
+     * Updates the first document matching the query
+     * @param attributes - Fields to update
+     * @param query - Optional FlongoQuery to filter documents
+     * @param clientId - Optional client ID for audit trail
+     * @returns Promise resolving to the updated document
+     */
+    updateFirst(attributes: any, query?: FlongoQuery, clientId?: string): Promise<Entity & T>;
+    /**
+     * Atomically increments a numeric field
+     * @param id - Document ID
+     * @param key - Field name to increment
+     * @param amt - Amount to increment by (defaults to 1)
+     */
+    increment(id: string, key: string, amt?: number): Promise<void>;
+    /**
+     * Atomically decrements a numeric field
+     * @param id - Document ID
+     * @param key - Field name to decrement
+     * @param amt - Amount to decrement by (defaults to 1)
+     */
+    decrement(id: string, key: string, amt?: number): Promise<void>;
+    /**
+     * Atomically appends items to an array field
+     * @param id - Document ID
+     * @param key - Array field name
+     * @param items - Items to append to the array
+     */
+    append(id: string, key: string, items: any[]): Promise<void>;
+    /**
+     * Atomically removes items from an array field
+     * @param id - Document ID
+     * @param key - Array field name
+     * @param items - Items to remove from the array
+     */
+    arrRemove(id: string, key: string, items: any[]): Promise<void>;
+    /**
+     * Logs an event to the events collection for audit trails
+     * Events are only logged if event logging is enabled in options
+     * @param event - Event object with name and metadata
+     * @returns Promise resolving to the event ID (or null if logging disabled)
+     */
+    logEvent<T extends EventName>(event: Event<T>): Promise<string | null>;
+}
+//# sourceMappingURL=flongoCollection.d.ts.map