flongo 1.0.0

package/dist/flongoQuery.js

@@ -0,0 +1,448 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logic = exports.FlongoQueryBuilder = exports.FlongoQuery = void 0;
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const types_1 = require("./types");
+Object.defineProperty(exports, "Logic", { enumerable: true, get: function () { return types_1.Logic; } });
+const geofire_common_1 = require("geofire-common");
+const mongodb_1 = require("mongodb");
+/**
+ * FlongoQuery provides a fluent, chainable interface for building MongoDB queries
+ * similar to Firestore's query API. It allows developers to construct complex queries
+ * using method chaining rather than building MongoDB filter objects manually.
+ *
+ * Example usage:
+ * ```typescript
+ * const query = new FlongoQuery()
+ *   .where('age').gtEq(18)
+ *   .and('status').eq('active')
+ *   .and('tags').arrContainsAny(['developer', 'designer'])
+ *   .orderBy('createdAt', SortDirection.Descending);
+ * ```
+ */
+class FlongoQuery {
+    constructor() {
+        /** Array of field expressions (where conditions) */
+        this.expressions = [];
+        /** Array of range queries (currently unused but reserved for future features) */
+        this.ranges = [];
+        /** Array of queries to be combined with OR logic */
+        this.orQueries = [];
+        /** Array of queries to be combined with AND logic */
+        this.andQueries = [];
+    }
+    /**
+     * Gets the most recently added expression for method chaining
+     * @private
+     * @returns The last expression in the expressions array
+     */
+    exp() {
+        return this.expressions[this.expressions.length - 1];
+    }
+    /**
+     * Sets the operator and value for the most recent expression
+     * If value is null or undefined, removes the last expression (allows for conditional chaining)
+     * @private
+     * @param op - MongoDB operator (e.g., '$eq', '$gt', '$in')
+     * @param val - Value to compare against
+     * @returns This query instance for chaining
+     */
+    set(op, val) {
+        if (val === null || val === undefined) {
+            // Remove the expression if no value is provided
+            // This allows conditional chaining like .where('field').eq(maybeUndefinedValue)
+            this.expressions.pop();
+            return this;
+        }
+        this.exp().op = op;
+        this.exp().val = val;
+        return this;
+    }
+    /**
+     * Helper method to handle empty/invalid values by removing the last expression
+     * @private
+     * @returns This query instance for chaining
+     */
+    handleEmptyValue() {
+        this.expressions.pop();
+        return this;
+    }
+    /**
+     * Sets a range query on a field (currently unused but reserved for future features)
+     * @param key - Field name to query
+     * @param start - Start value of the range
+     * @param end - End value of the range
+     * @param orderField - Field to order by for range queries
+     */
+    setRange(key, start, end, orderField) {
+        this.orderBy(orderField);
+        this.ranges.push({ key: key, start: start, end: end });
+    }
+    /**
+     * Starts a new where clause for the specified field
+     * @param key - Field name to query
+     * @returns This query instance for chaining
+     */
+    where(key) {
+        this.expressions.push(new types_1.ColExpression(key));
+        return this;
+    }
+    /**
+     * Alias for where() - adds another field constraint with AND logic
+     * @param key - Field name to query
+     * @returns This query instance for chaining
+     */
+    and(key) {
+        this.where(key);
+        return this;
+    }
+    // ===========================================
+    // COMPARISON OPERATORS
+    // ===========================================
+    /**
+     * Adds equality constraint to the current field
+     * @param val - Value to match exactly
+     * @returns This query instance for chaining
+     */
+    eq(val) {
+        return this.set("$eq", val);
+    }
+    /**
+     * Adds not-equal constraint to the current field
+     * @param val - Value to exclude
+     * @returns This query instance for chaining
+     */
+    neq(val) {
+        return this.set("$ne", val);
+    }
+    /**
+     * Adds less-than constraint to the current field
+     * @param val - Upper bound (exclusive)
+     * @returns This query instance for chaining
+     */
+    lt(val) {
+        return this.set("$lt", val);
+    }
+    /**
+     * Adds less-than-or-equal constraint to the current field
+     * @param val - Upper bound (inclusive)
+     * @returns This query instance for chaining
+     */
+    ltEq(val) {
+        return this.set("$lte", val);
+    }
+    /**
+     * Adds greater-than constraint to the current field
+     * @param val - Lower bound (exclusive)
+     * @returns This query instance for chaining
+     */
+    gt(val) {
+        return this.set("$gt", val);
+    }
+    /**
+     * Adds greater-than-or-equal constraint to the current field
+     * @param val - Lower bound (inclusive)
+     * @returns This query instance for chaining
+     */
+    gtEq(val) {
+        return this.set("$gte", val);
+    }
+    // ===========================================
+    // ARRAY OPERATORS
+    // ===========================================
+    /**
+     * Checks if array field contains the specified value
+     * @param val - Value that must be present in the array
+     * @returns This query instance for chaining
+     */
+    arrContains(val) {
+        return this.set(undefined, val);
+    }
+    /**
+     * Checks if array field contains all of the specified values
+     * @param val - Array of values that must all be present
+     * @returns This query instance for chaining
+     */
+    arrContainsAll(val) {
+        return this.set("$all", val);
+    }
+    /**
+     * Checks if array field contains any of the specified values
+     * If empty array is provided, removes the expression
+     * @param val - Array of values, any of which may be present
+     * @returns This query instance for chaining
+     */
+    arrContainsAny(val) {
+        return val?.length ? this.set("$in", val) : this.handleEmptyValue();
+    }
+    // ===========================================
+    // STRING OPERATORS
+    // ===========================================
+    /**
+     * Adds case-insensitive string starts-with constraint
+     * @param val - String prefix to match
+     * @returns This query instance for chaining
+     */
+    startsWith(val) {
+        return this.set("$regex", "^" + val);
+    }
+    /**
+     * Adds case-insensitive string ends-with constraint
+     * @param val - String suffix to match
+     * @returns This query instance for chaining
+     */
+    endsWith(val) {
+        return this.set("$regex", val + "$");
+    }
+    /**
+     * Adds case-insensitive string contains constraint
+     * @param val - Substring to search for
+     * @returns This query instance for chaining
+     */
+    strContains(val) {
+        return this.set("$regex", val);
+    }
+    /**
+     * Helper method to apply comparison operators with null/empty checks
+     * @private
+     * @param op - MongoDB operator
+     * @param val - Array of values
+     * @returns This query instance for chaining
+     */
+    applyComparisonOperator(op, val) {
+        if (val) {
+            this.set(op, val);
+        }
+        else {
+            // Remove expression if no values provided
+            this.expressions.pop();
+        }
+        return this;
+    }
+    /**
+     * Checks if field value is in the provided array
+     * @param val - Array of possible values
+     * @returns This query instance for chaining
+     */
+    in(val) {
+        return val?.length ? this.applyComparisonOperator("$in", val) : this.handleEmptyValue();
+    }
+    /**
+     * Checks if field value is NOT in the provided array
+     * @param val - Array of values to exclude
+     * @returns This query instance for chaining
+     */
+    notIn(val) {
+        return val?.length ? this.applyComparisonOperator("$nin", val) : this.handleEmptyValue();
+    }
+    /**
+     * Convenience method for range queries (field >= min AND field <= max)
+     * @param key - Field name
+     * @param min - Minimum value (inclusive)
+     * @param max - Maximum value (inclusive)
+     * @returns This query instance for chaining
+     */
+    inRange(key, min, max) {
+        return this.where(key).gtEq(min).and(key).ltEq(max);
+    }
+    // ===========================================
+    // GEOSPATIAL OPERATORS
+    // ===========================================
+    /**
+     * Performs geospatial radius search using geohash bounds
+     * This method uses the geofire-common library to generate geohash query bounds
+     * and creates OR queries for each bound to efficiently search within a radius
+     * @param key - Field containing geohash data
+     * @param center - Center point coordinates
+     * @param radius - Search radius in meters
+     * @returns This query instance for chaining
+     */
+    inRadius(key, center, radius) {
+        // Generate geohash bounds for the given center and radius
+        const geoBounds = (0, geofire_common_1.geohashQueryBounds)([center.latitude, center.longitude], radius);
+        // Order by geohash field for optimal query performance
+        this.orderBy(key, types_1.SortDirection.Ascending);
+        // Create OR queries for each geohash bound range
+        for (const b of geoBounds) {
+            this.or(new FlongoQuery().inRange(key, b[0], b[1]));
+        }
+        return this;
+    }
+    /**
+     * Performs geospatial query within rectangular bounds
+     * Creates a GeoJSON polygon from the provided bounds
+     * @param bounds - Rectangular bounds with northeast and southwest corners
+     * @returns This query instance for chaining
+     */
+    geoWithin(bounds) {
+        if (bounds) {
+            // Create GeoJSON polygon from bounds
+            // MongoDB requires coordinates in [longitude, latitude] format
+            // Polygon must be closed (first and last coordinates identical)
+            this.set("$geoWithin", {
+                $geometry: {
+                    type: "Polygon",
+                    coordinates: [
+                        [
+                            [bounds.ne.longitude, bounds.ne.latitude], // Top-right
+                            [bounds.ne.longitude, bounds.sw.latitude], // Bottom-right
+                            [bounds.sw.longitude, bounds.sw.latitude], // Bottom-left
+                            [bounds.sw.longitude, bounds.ne.latitude], // Top-left
+                            [bounds.ne.longitude, bounds.ne.latitude] // Close polygon
+                        ]
+                    ]
+                }
+            });
+        }
+        else {
+            // Remove expression if no bounds provided
+            this.expressions.pop();
+        }
+        return this;
+    }
+    // ===========================================
+    // SORTING
+    // ===========================================
+    /**
+     * Sets the field and direction for sorting results
+     * @param field - Field name to sort by
+     * @param direction - Sort direction (ascending or descending)
+     * @returns This query instance for chaining
+     */
+    orderBy(field, direction) {
+        this.orderField = field;
+        this.orderDirection = direction;
+        return this;
+    }
+    // ===========================================
+    // LOGICAL OPERATORS
+    // ===========================================
+    /**
+     * Adds a sub-query with AND logic
+     * @param query - Sub-query to combine with AND logic
+     * @returns This query instance for chaining
+     */
+    andQuery(query) {
+        this.andQueries.push(query);
+        return this;
+    }
+    /**
+     * Adds a sub-query with OR logic
+     * @param query - Sub-query to combine with OR logic
+     * @returns This query instance for chaining
+     */
+    or(query) {
+        this.orQueries.push(query);
+        return this;
+    }
+    // ===========================================
+    // QUERY BUILDING
+    // ===========================================
+    /**
+     * Builds the final MongoDB filter object from all expressions and sub-queries
+     * This method converts the fluent query structure into a MongoDB-compatible filter
+     * @returns MongoDB filter object
+     */
+    build() {
+        let mongodbQuery = {};
+        try {
+            // Process main expressions
+            if (this.expressions) {
+                for (const expression of this.expressions) {
+                    // Special handling for _id field - convert strings to ObjectIds
+                    if (expression.key === "_id") {
+                        if (Array.isArray(expression.val)) {
+                            // Multiple IDs: {_id: {$in: [ObjectId(...), ObjectId(...)]}}
+                            mongodbQuery = {
+                                _id: {
+                                    [expression.op ?? "$in"]: expression.val.map((element) => new mongodb_1.ObjectId(element))
+                                }
+                            };
+                        }
+                        else {
+                            // Single ID: {_id: ObjectId(...)}
+                            mongodbQuery = { _id: new mongodb_1.ObjectId(expression.val) };
+                        }
+                        break; // _id queries are typically exclusive
+                    }
+                    // Build query object for non-_id fields
+                    const fieldValue = expression.op
+                        ? expression.op === "$regex"
+                            ? { [expression.op]: expression.val, ["$options"]: "i" } // Case-insensitive regex
+                            : { [expression.op]: expression.val }
+                        : expression.val; // Direct value assignment for simple equality
+                    // Merge operators for the same field (e.g., range queries)
+                    if (mongodbQuery[expression.key] &&
+                        typeof mongodbQuery[expression.key] === "object" &&
+                        typeof fieldValue === "object") {
+                        mongodbQuery[expression.key] = { ...mongodbQuery[expression.key], ...fieldValue };
+                    }
+                    else {
+                        mongodbQuery[expression.key] = fieldValue;
+                    }
+                }
+            }
+            // Add OR sub-queries
+            if (this.orQueries.length > 0) {
+                mongodbQuery["$or"] = [];
+                for (const query of this.orQueries) {
+                    mongodbQuery["$or"].push(query.build());
+                }
+            }
+            // Add AND sub-queries
+            if (this.andQueries.length > 0) {
+                mongodbQuery["$and"] = [];
+                for (const query of this.andQueries) {
+                    mongodbQuery["$and"].push(query.build());
+                }
+            }
+        }
+        catch (err) {
+            console.log("Failed building query: ", err);
+            throw err;
+        }
+        // Note: Range queries are currently commented out but reserved for future use
+        // if (query.ranges) {
+        //   query.ranges.forEach((range) => {
+        //     mongodbQuery[range.key as keyof Filter<T>] = {
+        //       $gte: range.start,
+        //       $lt: range.end
+        //     };
+        //   });
+        // }
+        return mongodbQuery;
+    }
+    /**
+     * Builds MongoDB FindOptions for pagination and sorting
+     * @param pagination - Optional pagination settings
+     * @returns MongoDB FindOptions object
+     */
+    buildOptions(pagination) {
+        const mongodbOptions = {};
+        // Add pagination if provided
+        if (pagination) {
+            mongodbOptions.skip = pagination.offset;
+            mongodbOptions.limit = pagination.count;
+        }
+        // Add sorting if specified
+        if (this.orderField && this.orderDirection) {
+            mongodbOptions.sort = {
+                [this.orderField]: this.orderDirection === types_1.SortDirection.Ascending ? 1 : -1
+            };
+        }
+        return mongodbOptions;
+    }
+}
+exports.FlongoQuery = FlongoQuery;
+/**
+ * FlongoQueryBuilder provides a builder pattern wrapper around FlongoQuery
+ * This can be useful for more complex query construction scenarios
+ */
+class FlongoQueryBuilder {
+    constructor() {
+        /** The underlying query instance */
+        this.q = new FlongoQuery();
+    }
+}
+exports.FlongoQueryBuilder = FlongoQueryBuilder;
+//# sourceMappingURL=flongoQuery.js.map

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { FlongoCollection, FlongoCollectionOptions } from "./flongoCollection";
+export { FlongoQuery, FlongoQueryBuilder } from "./flongoQuery";
+export { initializeFlongo, FlongoConfig, flongoClient, flongoDb } from "./flongo";
+export { Error404, Error400 } from "./errors";
+export { Entity, DbRecord, Pagination, Coordinates, Bounds, Event, EventName, EventRecord, Logic, SortDirection, ColRange, ColExpression, ICollectionQuery, ICollection, Repository } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+// Main exports for flongo package
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColExpression = exports.ColRange = exports.SortDirection = exports.Logic = exports.EventName = exports.Error400 = exports.Error404 = exports.flongoDb = exports.flongoClient = exports.initializeFlongo = exports.FlongoQueryBuilder = exports.FlongoQuery = exports.FlongoCollection = void 0;
+var flongoCollection_1 = require("./flongoCollection");
+Object.defineProperty(exports, "FlongoCollection", { enumerable: true, get: function () { return flongoCollection_1.FlongoCollection; } });
+var flongoQuery_1 = require("./flongoQuery");
+Object.defineProperty(exports, "FlongoQuery", { enumerable: true, get: function () { return flongoQuery_1.FlongoQuery; } });
+Object.defineProperty(exports, "FlongoQueryBuilder", { enumerable: true, get: function () { return flongoQuery_1.FlongoQueryBuilder; } });
+var flongo_1 = require("./flongo");
+Object.defineProperty(exports, "initializeFlongo", { enumerable: true, get: function () { return flongo_1.initializeFlongo; } });
+Object.defineProperty(exports, "flongoClient", { enumerable: true, get: function () { return flongo_1.flongoClient; } });
+Object.defineProperty(exports, "flongoDb", { enumerable: true, get: function () { return flongo_1.flongoDb; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "Error404", { enumerable: true, get: function () { return errors_1.Error404; } });
+Object.defineProperty(exports, "Error400", { enumerable: true, get: function () { return errors_1.Error400; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "EventName", { enumerable: true, get: function () { return types_1.EventName; } });
+Object.defineProperty(exports, "Logic", { enumerable: true, get: function () { return types_1.Logic; } });
+Object.defineProperty(exports, "SortDirection", { enumerable: true, get: function () { return types_1.SortDirection; } });
+Object.defineProperty(exports, "ColRange", { enumerable: true, get: function () { return types_1.ColRange; } });
+Object.defineProperty(exports, "ColExpression", { enumerable: true, get: function () { return types_1.ColExpression; } });
+//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+export interface Entity {
+    _id: string;
+    createdAt: number;
+    updatedAt: number;
+    createdBy?: string;
+    updatedBy?: string;
+}
+export type DbRecord<T> = Entity & T;
+export interface Pagination {
+    offset: number;
+    count: number;
+}
+export interface Coordinates {
+    latitude: number;
+    longitude: number;
+    geohash?: string;
+    geoJSON?: GeoJson;
+}
+export interface GeoJson {
+    type: string;
+    coordinates: number[];
+}
+export interface Bounds {
+    ne: Coordinates;
+    sw: Coordinates;
+    center?: Coordinates;
+}
+export declare enum EventName {
+    CreateEntity = "create_entity",
+    BatchCreateEntities = "batch_create_entities",
+    UpdateEntity = "update_entity",
+    BatchUpdateEntities = "batch_update_entities",
+    DeleteEntity = "delete_entity",
+    BatchDeleteEntities = "batch_delete_entities"
+}
+export type Event<T extends EventName = any> = {
+    name: T;
+    identity?: string;
+    value: any;
+};
+export type EventRecord<T extends EventName = any> = DbRecord<Event<T>>;
+export declare enum Logic {
+    and = "and",
+    or = "or"
+}
+export declare enum SortDirection {
+    Ascending = "asc",
+    Descending = "desc"
+}
+export declare class ColRange {
+    key: string;
+    start: string;
+    end: string;
+}
+export declare class ColExpression {
+    op?: string | undefined;
+    key: string;
+    val: any;
+    constructor(key: string);
+}
+export type ICollectionQuery = {
+    expressions: ColExpression[];
+    ranges: ColRange[];
+    orderField?: string;
+    orderDirection?: SortDirection;
+    orQueries: ICollectionQuery[];
+    andQueries: ICollectionQuery[];
+};
+export type ICollection<T> = {
+    getAll: (query?: ICollectionQuery, pagination?: Pagination) => Promise<(Entity & T)[]>;
+    getSome: (query: ICollectionQuery, pagination: Pagination) => Promise<(Entity & T)[]>;
+    getFirst: (query: ICollectionQuery, pagination?: Pagination) => Promise<Entity & T>;
+    get: (id: string) => Promise<Entity & T>;
+    count: (query?: ICollectionQuery) => Promise<number>;
+    delete: (id: string, clientId?: string) => Promise<void>;
+    batchDelete: (ids: string[], clientId?: string) => Promise<void>;
+    exists: (query: ICollectionQuery) => Promise<boolean>;
+    create: (attributes: T, clientId?: string) => Promise<Entity & T>;
+    batchCreate: (attributes: T[], clientId?: string) => Promise<void>;
+    updateAll: (attributes: any, filters?: any, clientId?: string) => Promise<void>;
+    update: (id: string, attributes: any, clientId?: string) => Promise<void>;
+    increment: (id: string, key: string, amt?: number) => Promise<void>;
+    decrement: (id: string, key: string, amt?: number) => Promise<void>;
+    append: (id: string, key: string, items: any[]) => Promise<void>;
+    arrRemove: (id: string, key: string, items: any[]) => Promise<void>;
+    updateFirst: (attributes: any, filters?: any, clientId?: string) => Promise<Entity & T>;
+};
+export type Repository = string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,49 @@
+"use strict";
+// Core types for flongo - extracted from @staysco/models
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ColExpression = exports.ColRange = exports.SortDirection = exports.Logic = exports.EventName = void 0;
+// Event system types - making these generic for flongo
+var EventName;
+(function (EventName) {
+    EventName["CreateEntity"] = "create_entity";
+    EventName["BatchCreateEntities"] = "batch_create_entities";
+    EventName["UpdateEntity"] = "update_entity";
+    EventName["BatchUpdateEntities"] = "batch_update_entities";
+    EventName["DeleteEntity"] = "delete_entity";
+    EventName["BatchDeleteEntities"] = "batch_delete_entities";
+})(EventName || (exports.EventName = EventName = {}));
+// Enums for common operations
+var Logic;
+(function (Logic) {
+    Logic["and"] = "and";
+    Logic["or"] = "or";
+})(Logic || (exports.Logic = Logic = {}));
+var SortDirection;
+(function (SortDirection) {
+    SortDirection["Ascending"] = "asc";
+    SortDirection["Descending"] = "desc";
+})(SortDirection || (exports.SortDirection = SortDirection = {}));
+// Collection operations
+class ColRange {
+    constructor() {
+        this.key = "";
+        this.start = "";
+        this.end = "";
+    }
+}
+exports.ColRange = ColRange;
+class ColExpression {
+    constructor(key) {
+        this.op = "==";
+        this.key = "";
+        this.val = "";
+        if (this.key === "_id") {
+            this.key = String(key);
+        }
+        else {
+            this.key = key;
+        }
+    }
+}
+exports.ColExpression = ColExpression;
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "flongo",
+  "version": "1.0.0",
+  "description": "Firestore-like fluent query API for MongoDB",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "dev": "tsc --watch",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "lint": "echo 'Linting not configured yet'",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test",
+    "semantic-release": "semantic-release"
+  },
+  "keywords": [
+    "mongodb",
+    "firestore",
+    "query",
+    "fluent",
+    "database",
+    "nosql"
+  ],
+  "author": "Nick Schrock",
+  "license": "MIT",
+  "dependencies": {
+    "mongodb": "^6.0.0",
+    "geofire-common": "^6.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "@types/node": "^20.0.0",
+    "semantic-release": "^22.0.0",
+    "@semantic-release/changelog": "^6.0.0",
+    "@semantic-release/git": "^10.0.0"
+  },
+  "peerDependencies": {
+    "mongodb": ">=5.0.0"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nickrunner/flongo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nickrunner/flongo/issues"
+  },
+  "homepage": "https://github.com/nickrunner/flongo#readme"
+}