@jkershaw/mangodb 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-12-27
+
+### Added
+- Initial release
+- MongoDB-compatible API for file-based storage
+- Query operators: 31/32 supported (all except `$where`)
+- Update operators: 20/20 (100% coverage)
+- Aggregation stages: 29/34 supported
+- Expression operators: 121/127 supported
+- Index types: single, compound, text, TTL, partial, 2d, 2dsphere, hashed, wildcard
+- Geospatial queries with GeoJSON support
+- Text search with weighted indexes
+- Trigonometry expression operators (15 operators)
+- `$jsonSchema` query operator
+- `$merge` aggregation stage
+- Comprehensive documentation

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 J Kershaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,112 @@
+# MangoDB 🥭
+
+A file-based MongoDB drop-in replacement for TypeScript/Node.js.
+
+**SQLite is to SQL as MangoDB is to MongoDB.**
+
+MangoDB stores your data as simple JSON files on disk while exposing the same API as the official MongoDB driver. Write your application once, develop locally without any database setup, then deploy to real MongoDB by changing a single environment variable.
+
+## Why MangoDB?
+
+Working with MongoDB during development often means running local instances, configuring Docker containers, or connecting to cloud databases just to run your tests. MangoDB removes that friction entirely - your data lives in plain JSON files that you can inspect, version control, or simply delete between test runs.
+
+The best part: when you're ready for production, your code doesn't change. Just point to a real MongoDB instance and everything works.
+
+## Installation
+
+```bash
+npm install @jkershaw/mangodb
+```
+
+Requires Node.js >= 22.0.0
+
+## Quick Start
+
+```typescript
+import { MangoClient } from '@jkershaw/mangodb';
+
+const client = new MangoClient('./data');
+await client.connect();
+
+const db = client.db('myapp');
+const users = db.collection('users');
+
+// Same API as MongoDB driver
+await users.insertOne({ name: 'Alice', email: 'alice@example.com' });
+const user = await users.findOne({ name: 'Alice' });
+
+await client.close();
+```
+
+## Switching to MongoDB
+
+The API is identical. Only initialization differs:
+
+```typescript
+import { MongoClient } from 'mongodb';
+import { MangoClient } from '@jkershaw/mangodb';
+
+// Environment-based switching
+const client = process.env.MONGODB_URI
+  ? new MongoClient(process.env.MONGODB_URI)
+  : new MangoClient('./data');
+
+await client.connect();
+// ... rest of your code works unchanged
+```
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Compatibility](./docs/COMPATIBILITY.md) | What's supported, what's not |
+| [Migration](./docs/MIGRATION.md) | Switching between MangoDB and MongoDB |
+| [Testing](./docs/TESTING.md) | Test patterns and best practices |
+| [Edge Cases](./docs/EDGE-CASES.md) | Behavioral quirks and gotchas |
+| [Examples](./docs/EXAMPLES.md) | Framework integration examples |
+| [API Reference](./docs/API.md) | Quick reference for all operations |
+| [Troubleshooting](./docs/TROUBLESHOOTING.md) | Common issues and solutions |
+| [Initial Prompt](./docs/INITIAL-PROMPT.md) | The original AI prompt that started this project |
+
+## Feature Coverage
+
+| Category | Coverage |
+|----------|----------|
+| Query Operators | 31/32 (97%) |
+| Update Operators | 20/20 (100%) |
+| Aggregation Stages | 29/34 (85%) |
+| Expression Operators | 121/127 (95%) |
+| Index Types | 9/9 (100%) |
+
+See [COMPATIBILITY.md](./docs/COMPATIBILITY.md) for details.
+
+## When to Use MangoDB
+
+**Ideal for:**
+- Local development without MongoDB setup
+- Unit and integration testing
+- CI/CD pipelines (no database service needed)
+- Prototyping and learning
+- Small datasets (< 10,000 documents)
+
+**Not recommended for:**
+- Production deployments
+- Large datasets
+- Multi-process access
+- Applications requiring transactions
+
+## Running Tests
+
+```bash
+# Run against MangoDB
+npm test
+
+# Run against MongoDB (requires MongoDB instance)
+MONGODB_URI=mongodb://localhost:27017 npm test
+```
+
+Both modes should pass for full compatibility.
+
+## License
+
+MIT

package/dist/aggregation/accumulators.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Accumulator classes for $group stage.
+ */
+import type { Document } from '../types.ts';
+export interface Accumulator {
+    accumulate(doc: Document): void;
+    getResult(): unknown;
+}
+export declare function createAccumulator(op: string, expr: unknown): Accumulator;
+//# sourceMappingURL=accumulators.d.ts.map

package/dist/aggregation/accumulators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accumulators.d.ts","sourceRoot":"","sources":["../../src/aggregation/accumulators.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC;IAChC,SAAS,IAAI,OAAO,CAAC;CACtB;AA8QD,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,WAAW,CA6BxE"}

package/dist/aggregation/accumulators.js

@@ -0,0 +1,251 @@
+import { compareValuesForSort } from "../utils.js";
+import { valuesEqual } from "../document-utils.js";
+import { evaluateExpression } from "./expression.js";
+class SumAccumulator {
+    sum = 0;
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (typeof value === 'number') {
+            this.sum += value;
+        }
+    }
+    getResult() {
+        return this.sum;
+    }
+}
+class AvgAccumulator {
+    sum = 0;
+    count = 0;
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (typeof value === 'number') {
+            this.sum += value;
+            this.count++;
+        }
+    }
+    getResult() {
+        return this.count > 0 ? this.sum / this.count : null;
+    }
+}
+class MinAccumulator {
+    min = undefined;
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (value !== null && value !== undefined) {
+            if (this.min === undefined || compareValuesForSort(value, this.min, 1) < 0) {
+                this.min = value;
+            }
+        }
+    }
+    getResult() {
+        return this.min === undefined ? null : this.min;
+    }
+}
+class MaxAccumulator {
+    max = undefined;
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (value !== null && value !== undefined) {
+            if (this.max === undefined || compareValuesForSort(value, this.max, 1) > 0) {
+                this.max = value;
+            }
+        }
+    }
+    getResult() {
+        return this.max === undefined ? null : this.max;
+    }
+}
+class FirstAccumulator {
+    first = undefined;
+    hasValue = false;
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        if (!this.hasValue) {
+            this.first = evaluateExpression(this.expr, doc);
+            this.hasValue = true;
+        }
+    }
+    getResult() {
+        return this.first;
+    }
+}
+class LastAccumulator {
+    last = undefined;
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        this.last = evaluateExpression(this.expr, doc);
+    }
+    getResult() {
+        return this.last;
+    }
+}
+class PushAccumulator {
+    values = [];
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        this.values.push(value);
+    }
+    getResult() {
+        return this.values;
+    }
+}
+class AddToSetAccumulator {
+    values = [];
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (!this.values.some((v) => valuesEqual(v, value))) {
+            this.values.push(value);
+        }
+    }
+    getResult() {
+        return this.values;
+    }
+}
+/**
+ * $count accumulator - counts the number of documents in a group.
+ * Note: This is the accumulator form, not the $count stage.
+ */
+class CountAccumulator {
+    count = 0;
+    accumulate(_doc) {
+        this.count++;
+    }
+    getResult() {
+        return this.count;
+    }
+}
+/**
+ * $mergeObjects accumulator - merges documents into a single document.
+ */
+class MergeObjectsAccumulator {
+    result = {};
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (value !== null &&
+            value !== undefined &&
+            typeof value === 'object' &&
+            !Array.isArray(value)) {
+            Object.assign(this.result, value);
+        }
+    }
+    getResult() {
+        return this.result;
+    }
+}
+/**
+ * $stdDevPop accumulator - calculates the population standard deviation.
+ */
+class StdDevPopAccumulator {
+    values = [];
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (typeof value === 'number' && !isNaN(value)) {
+            this.values.push(value);
+        }
+    }
+    getResult() {
+        if (this.values.length === 0) {
+            return null;
+        }
+        const n = this.values.length;
+        const mean = this.values.reduce((a, b) => a + b, 0) / n;
+        const squaredDiffs = this.values.map((v) => Math.pow(v - mean, 2));
+        const variance = squaredDiffs.reduce((a, b) => a + b, 0) / n;
+        return Math.sqrt(variance);
+    }
+}
+/**
+ * $stdDevSamp accumulator - calculates the sample standard deviation.
+ */
+class StdDevSampAccumulator {
+    values = [];
+    expr;
+    constructor(expr) {
+        this.expr = expr;
+    }
+    accumulate(doc) {
+        const value = evaluateExpression(this.expr, doc);
+        if (typeof value === 'number' && !isNaN(value)) {
+            this.values.push(value);
+        }
+    }
+    getResult() {
+        if (this.values.length < 2) {
+            return null;
+        }
+        const n = this.values.length;
+        const mean = this.values.reduce((a, b) => a + b, 0) / n;
+        const squaredDiffs = this.values.map((v) => Math.pow(v - mean, 2));
+        const variance = squaredDiffs.reduce((a, b) => a + b, 0) / (n - 1);
+        return Math.sqrt(variance);
+    }
+}
+export function createAccumulator(op, expr) {
+    switch (op) {
+        case '$sum':
+            return new SumAccumulator(expr);
+        case '$avg':
+            return new AvgAccumulator(expr);
+        case '$min':
+            return new MinAccumulator(expr);
+        case '$max':
+            return new MaxAccumulator(expr);
+        case '$first':
+            return new FirstAccumulator(expr);
+        case '$last':
+            return new LastAccumulator(expr);
+        case '$push':
+            return new PushAccumulator(expr);
+        case '$addToSet':
+            return new AddToSetAccumulator(expr);
+        case '$count':
+            return new CountAccumulator();
+        case '$mergeObjects':
+            return new MergeObjectsAccumulator(expr);
+        case '$stdDevPop':
+            return new StdDevPopAccumulator(expr);
+        case '$stdDevSamp':
+            return new StdDevSampAccumulator(expr);
+        default:
+            throw new Error(`unknown group operator '${op}'`);
+    }
+}
+//# sourceMappingURL=accumulators.js.map

package/dist/aggregation/accumulators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"accumulators.js","sourceRoot":"","sources":["../../src/aggregation/accumulators.ts"],"names":[],"mappings":"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"}

package/dist/aggregation/cursor.d.ts

@@ -0,0 +1,116 @@
+import type { Document, PipelineStage } from '../types.ts';
+import type { AggregationDbContext } from './types.ts';
+/**
+ * AggregationCursor represents a cursor over aggregation pipeline results.
+ */
+export declare class AggregationCursor<T extends Document = Document> {
+    private readonly source;
+    private readonly pipeline;
+    private readonly dbContext?;
+    private pipelineNow?;
+    constructor(source: () => Promise<T[]>, pipeline: PipelineStage[], dbContext?: AggregationDbContext);
+    /**
+     * Get system variables for a document.
+     * Uses shared $$NOW date for consistency across pipeline.
+     */
+    private getSystemVars;
+    toArray(): Promise<Document[]>;
+    private executeStage;
+    private execMatch;
+    private execProject;
+    /**
+     * $redact - field-level access control with recursive traversal.
+     */
+    private execRedact;
+    /**
+     * $documents - injects literal documents into the pipeline.
+     * Must be the first stage.
+     */
+    private execDocuments;
+    /**
+     * $unset - removes specified fields from documents.
+     * Alias for $project with field exclusion.
+     */
+    private execUnset;
+    private isLiteralExpression;
+    private projectDocument;
+    private execSort;
+    private execLimit;
+    private execSkip;
+    private execCount;
+    private execUnwind;
+    private execGroup;
+    private execLookup;
+    /**
+     * MongoDB system variables that should not be substituted.
+     */
+    private static readonly SYSTEM_VARIABLES;
+    /**
+     * Recursively substitute $$varName references with actual values.
+     * Supports dotted paths like $$varName.field.subfield.
+     */
+    private substituteLetVars;
+    /**
+     * $graphLookup - recursive lookup for graph traversal.
+     */
+    private execGraphLookup;
+    /**
+     * $densify - fills gaps in numeric or date sequences.
+     */
+    private execDensify;
+    /**
+     * $fill - fills null/missing values with various strategies.
+     */
+    private execFill;
+    /**
+     * $setWindowFields - window functions for analytics.
+     */
+    private execSetWindowFields;
+    /**
+     * Get documents within the specified window bounds.
+     */
+    private getWindowDocuments;
+    /**
+     * Apply a window operator to the current document.
+     */
+    private applyWindowOperator;
+    private execAddFields;
+    private execReplaceRoot;
+    private execOut;
+    /**
+     * $merge - Writes documents to a collection, with options for handling matches.
+     */
+    private execMerge;
+    /**
+     * $sortByCount - Groups by expression and counts, sorted by count descending.
+     * Equivalent to: { $group: { _id: <expression>, count: { $sum: 1 } } }, { $sort: { count: -1 } }
+     */
+    private execSortByCount;
+    /**
+     * $sample - Randomly selects the specified number of documents.
+     */
+    private execSample;
+    /**
+     * $facet - Processes multiple aggregation pipelines within a single stage.
+     * Returns a single document where each field contains the array of results from its pipeline.
+     */
+    private execFacet;
+    /**
+     * $bucket - Categorizes documents into groups (buckets) based on boundaries.
+     */
+    private execBucket;
+    /**
+     * $bucketAuto - Automatically creates bucket boundaries.
+     */
+    private execBucketAuto;
+    /**
+     * $unionWith - Combines documents from two collections.
+     */
+    private execUnionWith;
+    /**
+     * Execute $geoNear stage.
+     * Returns documents sorted by distance from the specified point.
+     */
+    private execGeoNear;
+}
+//# sourceMappingURL=cursor.d.ts.map

package/dist/aggregation/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/aggregation/cursor.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,QAAQ,EAER,aAAa,EAId,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AA+BvD;;GAEG;AACH,qBAAa,iBAAiB,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ;IAC1D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAuB;IAClD,OAAO,CAAC,WAAW,CAAC,CAAO;gBAGzB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,EAC1B,QAAQ,EAAE,aAAa,EAAE,EACzB,SAAS,CAAC,EAAE,oBAAoB;IAOlC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAIf,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YAqDtB,YAAY;IAiJ1B,OAAO,CAAC,SAAS;IAIjB,OAAO,CAAC,WAAW;IAyCnB;;OAEG;IACH,OAAO,CAAC,UAAU;IA6BlB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAqBrB;;;OAGG;IACH,OAAO,CAAC,SAAS;IAqCjB,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,eAAe;IAyEvB,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,SAAS;IAgBjB,OAAO,CAAC,QAAQ;IAUhB,OAAO,CAAC,SAAS;IAkBjB,OAAO,CAAC,UAAU;IAqElB,OAAO,CAAC,SAAS;YA+CH,UAAU;IA2FxB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CASrC;IAEH;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IA6CzB;;OAEG;YACW,eAAe;IA8H7B;;OAEG;IACH,OAAO,CAAC,WAAW;IA0InB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAyGhB;;OAEG;IACH,OAAO,CAAC,mBAAmB;IA2F3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiF1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAqiB3B,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,eAAe;YAsBT,OAAO;IAgBrB;;OAEG;YACW,SAAS;IAkGvB;;;OAGG;IACH,OAAO,CAAC,eAAe;IAqBvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAwClB;;;OAGG;YACW,SAAS;IAgCvB;;OAEG;IACH,OAAO,CAAC,UAAU;IAuJlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAoHtB;;OAEG;YACW,aAAa;IA4B3B;;;OAGG;YACW,WAAW;CAqF1B"}