@gravito/dark-matter 1.1.1 → 2.0.0

package/README.md

@@ -35,18 +35,30 @@ const users = await Mongo.collection('users')
 await Mongo.disconnect()
 ```
 
-## Features
-
-- 🚀 **Bun Native** - Optimized for Bun runtime
-- 🎯 **Laravel-style API** - Familiar fluent interface
-- 🔍 **Query Builder** - Type-safe query building
-- 📊 **Aggregation Pipeline** - Fluent aggregation API
-- 🔌 **Multi-connection** - Named connections support
-- 🛡️ **Transactions** - ACID transactions with convenient API
-- 🗑️ **Soft Deletes** - Built-in soft delete support with restore capability
-- 📦 **GridFS** - Handle large file uploads/downloads
-- ⚡ **Change Streams** - Real-time database event listening
-- ✅ **Schema Validation** - Type-safe Schema Builder API for MongoDB validation
+## ✨ Features
+
+- 🚀 **Bun Native Performance**: Optimized for the Bun runtime with zero-copy data handling.
+- 🌌 **Galaxy-Ready Persistence**: Native integration with PlanetCore for universal NoSQL data management.
+- 🎯 **Laravel-style API**: Familiar, fluent interface for MongoDB collections and aggregation pipelines.
+- 🛡️ **Distributed Document State**: ACID transactions and robust multi-connection management across the Galaxy.
+- 🗑️ **Soft Deletes**: Built-in logic for logical record deletion with restoration support.
+- 📦 **GridFS & Streams**: Specialized support for large-scale file storage and real-time change listening.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Dark Matter acts as the **MongoDB Gravity Core (NoSQL Persistence)**.
+
+- **Document Focus**: Provides an alternative gravity core for Satellites that require schema-less flexibility or massive-scale document storage.
+- **Micro-State Bridge**: Enables real-time reactive logic via MongoDB Change Streams, allowing one Satellite to react instantly to data changes in another.
+- **File Distribution**: Leverages GridFS to provide a distributed file storage layer that works alongside `@gravito/nebula`.
+
+```mermaid
+graph TD
+    S1[Satellite: Analytics] -- "Save" --> DM{Dark Matter}
+    S2[Satellite: Logs] -- "Query" --> DM
+    DM -->|Native Driver| MongoDB[(MongoDB Atlas)]
+    DM -.->|Watch| Realtime[Real-time Events]
+```
 
 ## API Reference
 

package/dist/index.cjs

@@ -1,4 +1,3 @@
-"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -30,6 +29,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DarkMatterError: () => DarkMatterError,
+  DarkMatterErrorCodes: () => DarkMatterErrorCodes,
   Mongo: () => Mongo,
   MongoAggregateBuilder: () => MongoAggregateBuilder,
   MongoClient: () => MongoClient,
@@ -42,6 +43,25 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors/DarkMatterError.ts
+var import_core = require("@gravito/core");
+var DarkMatterError = class extends import_core.InfrastructureException {
+  constructor(status, code, options = {}) {
+    super(status, code, options);
+    this.name = "DarkMatterError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/codes.ts
+var DarkMatterErrorCodes = {
+  CONNECTION_FAILED: "dark_matter.connection_failed",
+  NOT_CONNECTED: "dark_matter.not_connected",
+  CONNECTION_NOT_CONFIGURED: "dark_matter.connection_not_configured",
+  GRIDFS_NOT_INITIALIZED: "dark_matter.gridfs_not_initialized",
+  OPERATION_FAILED: "dark_matter.operation_failed"
+};
+
 // src/MongoQueryBuilder.ts
 var MongoQueryBuilder = class _MongoQueryBuilder {
   constructor(nativeCollection, collectionName, session) {
@@ -1146,26 +1166,38 @@ var MongoClient = class {
     if (this.config.socketTimeoutMS) {
       options.socketTimeoutMS = this.config.socketTimeoutMS;
     }
-    this.client = new this.mongodb.MongoClient(uri, options);
     let lastError = null;
     for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+      const client = new this.mongodb.MongoClient(uri, options);
+      this.client = client;
       try {
-        await this.client.connect();
+        await client.connect();
         const dbName = this.config.database ?? "test";
-        this.db = this.client.db(dbName);
+        this.db = client.db(dbName);
         this.connected = true;
         return;
       } catch (error) {
         lastError = error;
+        this.connected = false;
+        this.db = null;
+        try {
+          await client.close();
+        } catch {
+        }
+        if (this.client === client) {
+          this.client = null;
+        }
         if (attempt < config.maxRetries) {
           const delay = config.retryDelayMs * config.backoffMultiplier ** attempt;
           await new Promise((resolve) => setTimeout(resolve, delay));
         }
       }
     }
-    throw new Error(
-      `Failed to connect to MongoDB after ${config.maxRetries + 1} attempts: ${lastError?.message}`
-    );
+    throw new DarkMatterError(503, DarkMatterErrorCodes.CONNECTION_FAILED, {
+      message: `Failed to connect to MongoDB after ${config.maxRetries + 1} attempts: ${lastError?.message}`,
+      cause: lastError,
+      retryable: true
+    });
   }
   /**
    * Closes the connection to the MongoDB server.
@@ -1355,20 +1387,24 @@ var MongoClient = class {
       const mongodb = await import("mongodb");
       return mongodb;
     } catch {
-      throw new Error(
-        'MongoDB client requires the "mongodb" package. Please install it: bun add mongodb'
-      );
+      throw new DarkMatterError(500, DarkMatterErrorCodes.CONNECTION_FAILED, {
+        message: 'MongoDB client requires the "mongodb" package. Please install it: bun add mongodb'
+      });
     }
   }
   getClient() {
     if (!this.client) {
-      throw new Error("MongoDB client not connected. Call connect() first.");
+      throw new DarkMatterError(503, DarkMatterErrorCodes.NOT_CONNECTED, {
+        message: "MongoDB client not connected. Call connect() first."
+      });
     }
     return this.client;
   }
   getDatabase() {
     if (!this.db) {
-      throw new Error("MongoDB client not connected. Call connect() first.");
+      throw new DarkMatterError(503, DarkMatterErrorCodes.NOT_CONNECTED, {
+        message: "MongoDB client not connected. Call connect() first."
+      });
     }
     return this.db;
   }
@@ -1491,7 +1527,9 @@ var MongoManager = class {
     if (!this.connections.has(connectionName)) {
       const config = this.configs.get(connectionName);
       if (!config) {
-        throw new Error(`MongoDB connection "${connectionName}" not configured`);
+        throw new DarkMatterError(500, DarkMatterErrorCodes.CONNECTION_NOT_CONFIGURED, {
+          message: `MongoDB connection "${connectionName}" not configured`
+        });
       }
       this.connections.set(connectionName, new MongoClient(config));
     }
@@ -1995,7 +2033,10 @@ var MongoGridFS = class {
   }
   async ensureBucket() {
     if (!this.bucket) {
-      throw new Error("GridFS bucket not initialized. Please wait a moment after creation.");
+      throw new DarkMatterError(503, DarkMatterErrorCodes.GRIDFS_NOT_INITIALIZED, {
+        message: "GridFS bucket not initialized. Please wait a moment after creation.",
+        retryable: true
+      });
     }
   }
 };
@@ -2305,6 +2346,8 @@ function schema() {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DarkMatterError,
+  DarkMatterErrorCodes,
   Mongo,
   MongoAggregateBuilder,
   MongoClient,

package/dist/index.d.cts

@@ -1,3 +1,27 @@
+import { InfrastructureException, InfrastructureExceptionOptions } from '@gravito/core';
+
+/**
+ * Error codes for the dark-matter package.
+ * @public
+ */
+declare const DarkMatterErrorCodes: {
+    readonly CONNECTION_FAILED: "dark_matter.connection_failed";
+    readonly NOT_CONNECTED: "dark_matter.not_connected";
+    readonly CONNECTION_NOT_CONFIGURED: "dark_matter.connection_not_configured";
+    readonly GRIDFS_NOT_INITIALIZED: "dark_matter.gridfs_not_initialized";
+    readonly OPERATION_FAILED: "dark_matter.operation_failed";
+};
+type DarkMatterErrorCode = (typeof DarkMatterErrorCodes)[keyof typeof DarkMatterErrorCodes];
+
+/**
+ * Concrete error class for the dark-matter (MongoDB) package.
+ * Extends InfrastructureException to participate in the GravitoException hierarchy.
+ * @public
+ */
+declare class DarkMatterError extends InfrastructureException {
+    constructor(status: number, code: DarkMatterErrorCode, options?: InfrastructureExceptionOptions);
+}
+
 /**
  * @gravito/dark-matter - Type Definitions
  */
@@ -1035,7 +1059,7 @@ declare class MongoQueryBuilder<T = Document> implements MongoCollectionContract
     private limitCount;
     private skipCount;
     private softDeleteMode;
-    constructor(nativeCollection: MongoNativeCollection, collectionName: string, session?: unknown | undefined);
+    constructor(nativeCollection: MongoNativeCollection, collectionName: string, session?: unknown);
     /**
      * Adds a basic WHERE clause to the query.
      *
@@ -1953,4 +1977,4 @@ declare class MongoSchemaBuilder {
  */
 declare function schema(): MongoSchemaBuilder;
 
-export { type BulkWriteOperation, type BulkWriteResult, type DeleteResult, type Document$1 as Document, type FilterDocument, type FilterOperator, type GridFSFile, type GridFSUploadOptions, type GridFSUploadProgress, type InsertManyResult, type InsertResult, type LookupOptions, Mongo, MongoAggregateBuilder, type MongoAggregateContract, MongoClient, type MongoClientContract, type MongoCollectionContract, type MongoConfig, type MongoDatabaseContract, MongoGridFS, MongoManager, type MongoManagerConfig, MongoPoolMonitor, MongoQueryBuilder, MongoSchemaBuilder, type MongoSession, type PipelineStage, type PoolMetrics, type Projection, type RetryConfig, type SchemaValidationOptions, type SoftDeletableDocument, type SortDirection, type SortSpec, type TransactionOptions, type UpdateDocument, type UpdateResult, schema };
+export { type BulkWriteOperation, type BulkWriteResult, DarkMatterError, type DarkMatterErrorCode, DarkMatterErrorCodes, type DeleteResult, type Document$1 as Document, type FilterDocument, type FilterOperator, type GridFSFile, type GridFSUploadOptions, type GridFSUploadProgress, type InsertManyResult, type InsertResult, type LookupOptions, Mongo, MongoAggregateBuilder, type MongoAggregateContract, MongoClient, type MongoClientContract, type MongoCollectionContract, type MongoConfig, type MongoDatabaseContract, MongoGridFS, MongoManager, type MongoManagerConfig, MongoPoolMonitor, MongoQueryBuilder, MongoSchemaBuilder, type MongoSession, type PipelineStage, type PoolMetrics, type Projection, type RetryConfig, type SchemaValidationOptions, type SoftDeletableDocument, type SortDirection, type SortSpec, type TransactionOptions, type UpdateDocument, type UpdateResult, schema };

package/dist/index.d.ts

@@ -1,3 +1,27 @@
+import { InfrastructureException, InfrastructureExceptionOptions } from '@gravito/core';
+
+/**
+ * Error codes for the dark-matter package.
+ * @public
+ */
+declare const DarkMatterErrorCodes: {
+    readonly CONNECTION_FAILED: "dark_matter.connection_failed";
+    readonly NOT_CONNECTED: "dark_matter.not_connected";
+    readonly CONNECTION_NOT_CONFIGURED: "dark_matter.connection_not_configured";
+    readonly GRIDFS_NOT_INITIALIZED: "dark_matter.gridfs_not_initialized";
+    readonly OPERATION_FAILED: "dark_matter.operation_failed";
+};
+type DarkMatterErrorCode = (typeof DarkMatterErrorCodes)[keyof typeof DarkMatterErrorCodes];
+
+/**
+ * Concrete error class for the dark-matter (MongoDB) package.
+ * Extends InfrastructureException to participate in the GravitoException hierarchy.
+ * @public
+ */
+declare class DarkMatterError extends InfrastructureException {
+    constructor(status: number, code: DarkMatterErrorCode, options?: InfrastructureExceptionOptions);
+}
+
 /**
  * @gravito/dark-matter - Type Definitions
  */
@@ -1035,7 +1059,7 @@ declare class MongoQueryBuilder<T = Document> implements MongoCollectionContract
     private limitCount;
     private skipCount;
     private softDeleteMode;
-    constructor(nativeCollection: MongoNativeCollection, collectionName: string, session?: unknown | undefined);
+    constructor(nativeCollection: MongoNativeCollection, collectionName: string, session?: unknown);
     /**
      * Adds a basic WHERE clause to the query.
      *
@@ -1953,4 +1977,4 @@ declare class MongoSchemaBuilder {
  */
 declare function schema(): MongoSchemaBuilder;
 
-export { type BulkWriteOperation, type BulkWriteResult, type DeleteResult, type Document$1 as Document, type FilterDocument, type FilterOperator, type GridFSFile, type GridFSUploadOptions, type GridFSUploadProgress, type InsertManyResult, type InsertResult, type LookupOptions, Mongo, MongoAggregateBuilder, type MongoAggregateContract, MongoClient, type MongoClientContract, type MongoCollectionContract, type MongoConfig, type MongoDatabaseContract, MongoGridFS, MongoManager, type MongoManagerConfig, MongoPoolMonitor, MongoQueryBuilder, MongoSchemaBuilder, type MongoSession, type PipelineStage, type PoolMetrics, type Projection, type RetryConfig, type SchemaValidationOptions, type SoftDeletableDocument, type SortDirection, type SortSpec, type TransactionOptions, type UpdateDocument, type UpdateResult, schema };
+export { type BulkWriteOperation, type BulkWriteResult, DarkMatterError, type DarkMatterErrorCode, DarkMatterErrorCodes, type DeleteResult, type Document$1 as Document, type FilterDocument, type FilterOperator, type GridFSFile, type GridFSUploadOptions, type GridFSUploadProgress, type InsertManyResult, type InsertResult, type LookupOptions, Mongo, MongoAggregateBuilder, type MongoAggregateContract, MongoClient, type MongoClientContract, type MongoCollectionContract, type MongoConfig, type MongoDatabaseContract, MongoGridFS, MongoManager, type MongoManagerConfig, MongoPoolMonitor, MongoQueryBuilder, MongoSchemaBuilder, type MongoSession, type PipelineStage, type PoolMetrics, type Projection, type RetryConfig, type SchemaValidationOptions, type SoftDeletableDocument, type SortDirection, type SortSpec, type TransactionOptions, type UpdateDocument, type UpdateResult, schema };

package/dist/index.js

@@ -1,3 +1,22 @@
+// src/errors/DarkMatterError.ts
+import { InfrastructureException } from "@gravito/core";
+var DarkMatterError = class extends InfrastructureException {
+  constructor(status, code, options = {}) {
+    super(status, code, options);
+    this.name = "DarkMatterError";
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+
+// src/errors/codes.ts
+var DarkMatterErrorCodes = {
+  CONNECTION_FAILED: "dark_matter.connection_failed",
+  NOT_CONNECTED: "dark_matter.not_connected",
+  CONNECTION_NOT_CONFIGURED: "dark_matter.connection_not_configured",
+  GRIDFS_NOT_INITIALIZED: "dark_matter.gridfs_not_initialized",
+  OPERATION_FAILED: "dark_matter.operation_failed"
+};
+
 // src/MongoQueryBuilder.ts
 var MongoQueryBuilder = class _MongoQueryBuilder {
   constructor(nativeCollection, collectionName, session) {
@@ -1102,26 +1121,38 @@ var MongoClient = class {
     if (this.config.socketTimeoutMS) {
       options.socketTimeoutMS = this.config.socketTimeoutMS;
     }
-    this.client = new this.mongodb.MongoClient(uri, options);
     let lastError = null;
     for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+      const client = new this.mongodb.MongoClient(uri, options);
+      this.client = client;
       try {
-        await this.client.connect();
+        await client.connect();
         const dbName = this.config.database ?? "test";
-        this.db = this.client.db(dbName);
+        this.db = client.db(dbName);
         this.connected = true;
         return;
       } catch (error) {
         lastError = error;
+        this.connected = false;
+        this.db = null;
+        try {
+          await client.close();
+        } catch {
+        }
+        if (this.client === client) {
+          this.client = null;
+        }
         if (attempt < config.maxRetries) {
           const delay = config.retryDelayMs * config.backoffMultiplier ** attempt;
           await new Promise((resolve) => setTimeout(resolve, delay));
         }
       }
     }
-    throw new Error(
-      `Failed to connect to MongoDB after ${config.maxRetries + 1} attempts: ${lastError?.message}`
-    );
+    throw new DarkMatterError(503, DarkMatterErrorCodes.CONNECTION_FAILED, {
+      message: `Failed to connect to MongoDB after ${config.maxRetries + 1} attempts: ${lastError?.message}`,
+      cause: lastError,
+      retryable: true
+    });
   }
   /**
    * Closes the connection to the MongoDB server.
@@ -1311,20 +1342,24 @@ var MongoClient = class {
       const mongodb = await import("mongodb");
       return mongodb;
     } catch {
-      throw new Error(
-        'MongoDB client requires the "mongodb" package. Please install it: bun add mongodb'
-      );
+      throw new DarkMatterError(500, DarkMatterErrorCodes.CONNECTION_FAILED, {
+        message: 'MongoDB client requires the "mongodb" package. Please install it: bun add mongodb'
+      });
     }
   }
   getClient() {
     if (!this.client) {
-      throw new Error("MongoDB client not connected. Call connect() first.");
+      throw new DarkMatterError(503, DarkMatterErrorCodes.NOT_CONNECTED, {
+        message: "MongoDB client not connected. Call connect() first."
+      });
     }
     return this.client;
   }
   getDatabase() {
     if (!this.db) {
-      throw new Error("MongoDB client not connected. Call connect() first.");
+      throw new DarkMatterError(503, DarkMatterErrorCodes.NOT_CONNECTED, {
+        message: "MongoDB client not connected. Call connect() first."
+      });
     }
     return this.db;
   }
@@ -1447,7 +1482,9 @@ var MongoManager = class {
     if (!this.connections.has(connectionName)) {
       const config = this.configs.get(connectionName);
       if (!config) {
-        throw new Error(`MongoDB connection "${connectionName}" not configured`);
+        throw new DarkMatterError(500, DarkMatterErrorCodes.CONNECTION_NOT_CONFIGURED, {
+          message: `MongoDB connection "${connectionName}" not configured`
+        });
       }
       this.connections.set(connectionName, new MongoClient(config));
     }
@@ -1951,7 +1988,10 @@ var MongoGridFS = class {
   }
   async ensureBucket() {
     if (!this.bucket) {
-      throw new Error("GridFS bucket not initialized. Please wait a moment after creation.");
+      throw new DarkMatterError(503, DarkMatterErrorCodes.GRIDFS_NOT_INITIALIZED, {
+        message: "GridFS bucket not initialized. Please wait a moment after creation.",
+        retryable: true
+      });
     }
   }
 };
@@ -2260,6 +2300,8 @@ function schema() {
   return new MongoSchemaBuilder();
 }
 export {
+  DarkMatterError,
+  DarkMatterErrorCodes,
   Mongo,
   MongoAggregateBuilder,
   MongoClient,

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gravito/dark-matter",
-  "version": "1.1.1",
+  "sideEffects": false,
+  "version": "2.0.0",
   "description": "MongoDB client for Gravito - Bun native, Laravel-style API",
   "type": "module",
   "main": "./dist/index.js",
@@ -14,6 +15,7 @@
   },
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
     "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
@@ -26,7 +28,7 @@
     "bench:schema": "MONGODB_URI=mongodb://localhost:27017 bun test benchmarks/schema-validation.bench.ts",
     "bench:transactions": "MONGODB_URI=mongodb://localhost:27017 bun test benchmarks/transactions.bench.ts",
     "bench:change-streams": "MONGODB_URI=mongodb://localhost:27017 bun test benchmarks/change-streams.bench.ts",
-    "test:unit": "bun test tests/ --timeout=10000",
+    "test:unit": "bun test $(find tests -name '*.test.ts' ! -name '*.integration.test.ts' 2>/dev/null | tr '\\n' ' ') --timeout=10000",
     "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
   },
   "files": [