@objectstack/driver-memory 2.0.6 → 2.0.7

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/driver-memory@2.0.6 build /home/runner/work/spec/spec/packages/plugins/driver-memory
+> @objectstack/driver-memory@2.0.7 build /home/runner/work/spec/spec/packages/plugins/driver-memory
 > tsup --config ../../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-ESM dist/index.mjs     16.81 KB
-ESM dist/index.mjs.map 35.73 KB
-ESM ⚡️ Build success in 68ms
-CJS dist/index.js     17.84 KB
-CJS dist/index.js.map 35.78 KB
-CJS ⚡️ Build success in 68ms
+ESM dist/index.mjs     24.12 KB
+ESM dist/index.mjs.map 51.46 KB
+ESM ⚡️ Build success in 86ms
+CJS dist/index.js     25.22 KB
+CJS dist/index.js.map 51.50 KB
+CJS ⚡️ Build success in 89ms
 DTS Build start
-DTS ⚡️ Build success in 9696ms
-DTS dist/index.d.mts 3.24 KB
-DTS dist/index.d.ts  3.24 KB
+DTS ⚡️ Build success in 10233ms
+DTS dist/index.d.mts 6.37 KB
+DTS dist/index.d.ts  6.37 KB

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @objectstack/driver-memory
 
+## 2.0.7
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@2.0.7
+  - @objectstack/core@2.0.7
+
 ## 2.0.6
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,11 +1,33 @@
 import { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import { DriverInterface } from '@objectstack/core';
+import { DriverInterface, Logger } from '@objectstack/core';
 
 /**
- * Example: In-Memory Driver
+ * Configuration options for the InMemory driver.
+ * Aligned with @objectstack/spec MemoryConfigSchema.
+ */
+interface InMemoryDriverConfig {
+    /** Optional: Initial data to populate the store */
+    initialData?: Record<string, Record<string, unknown>[]>;
+    /** Optional: Enable strict mode (throw on missing records) */
+    strictMode?: boolean;
+    /** Optional: Logger instance */
+    logger?: Logger;
+}
+/**
+ * In-Memory Driver for ObjectStack
+ *
+ * A production-ready implementation of the ObjectStack Driver Protocol
+ * powered by Mingo — a MongoDB-compatible query and aggregation engine.
  *
- * A minimal reference implementation of the ObjectStack Driver Protocol.
- * This driver stores data in a simple JavaScript object (Heap).
+ * Features:
+ * - MongoDB-compatible query engine (Mingo) for filtering, projection, aggregation
+ * - Full CRUD and bulk operations
+ * - Aggregation pipeline support ($match, $group, $sort, $project, $unwind, etc.)
+ * - Snapshot-based transactions (begin/commit/rollback)
+ * - Field projection and distinct values
+ * - Strict mode and initial data loading
+ *
+ * Reference: objectql/packages/drivers/memory
  */
 declare class InMemoryDriver implements DriverInterface {
     name: string;
@@ -13,7 +35,9 @@ declare class InMemoryDriver implements DriverInterface {
     version: string;
     private config;
     private logger;
-    constructor(config?: any);
+    private idCounters;
+    private transactions;
+    constructor(config?: InMemoryDriverConfig);
     install(ctx: any): void;
     supports: {
         transactions: boolean;
@@ -66,14 +90,77 @@ declare class InMemoryDriver implements DriverInterface {
         data: Record<string, any>;
     }[], options?: DriverOptions): Promise<any[]>;
     bulkDelete(object: string, ids: (string | number)[], options?: DriverOptions): Promise<void>;
-    syncSchema(object: string, schema: any, options?: DriverOptions): Promise<void>;
-    dropTable(object: string, options?: DriverOptions): Promise<void>;
-    beginTransaction(): Promise<void>;
-    commit(): Promise<void>;
-    rollback(): Promise<void>;
+    beginTransaction(): Promise<{
+        id: string;
+    }>;
+    commit(txHandle?: unknown): Promise<void>;
+    rollback(txHandle?: unknown): Promise<void>;
+    /**
+     * Remove all data from the store.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get total number of records across all tables.
+     */
+    getSize(): number;
+    /**
+     * Get distinct values for a field, optionally filtered.
+     */
+    distinct(object: string, field: string, query?: QueryInput): Promise<any[]>;
+    /**
+     * Execute a MongoDB-style aggregation pipeline using Mingo.
+     *
+     * Supports all standard MongoDB pipeline stages:
+     * - $match, $group, $sort, $project, $unwind, $limit, $skip
+     * - $addFields, $replaceRoot, $lookup (limited), $count
+     * - Accumulator operators: $sum, $avg, $min, $max, $first, $last, $push, $addToSet
+     *
+     * @example
+     * // Group by status and count
+     * const results = await driver.aggregate('orders', [
+     *   { $match: { status: 'completed' } },
+     *   { $group: { _id: '$customer', totalAmount: { $sum: '$amount' } } }
+     * ]);
+     *
+     * @example
+     * // Calculate average with filter
+     * const results = await driver.aggregate('products', [
+     *   { $match: { category: 'electronics' } },
+     *   { $group: { _id: null, avgPrice: { $avg: '$price' } } }
+     * ]);
+     */
+    aggregate(object: string, pipeline: Record<string, any>[], options?: DriverOptions): Promise<any[]>;
+    /**
+     * Convert ObjectQL filter format to MongoDB query format for Mingo.
+     *
+     * Supports:
+     * 1. AST Comparison Node: { type: 'comparison', field, operator, value }
+     * 2. AST Logical Node: { type: 'logical', operator: 'and'|'or', conditions: [...] }
+     * 3. Legacy Array Format: [['field', 'op', value], 'and', ['field2', 'op', value2]]
+     * 4. MongoDB Format: { field: value } or { field: { $eq: value } } (passthrough)
+     */
+    private convertToMongoQuery;
+    /**
+     * Convert a single ObjectQL condition to MongoDB operator format.
+     */
+    private convertConditionToMongo;
+    /**
+     * Escape special regex characters for safe literal matching.
+     */
+    private escapeRegex;
     private performAggregation;
     private computeAggregate;
     private setValueByPath;
+    syncSchema(object: string, schema: any, options?: DriverOptions): Promise<void>;
+    dropTable(object: string, options?: DriverOptions): Promise<void>;
+    /**
+     * Apply manual sorting (Mingo sort has CJS build issues).
+     */
+    private applySort;
+    /**
+     * Project specific fields from a record.
+     */
+    private projectFields;
     private getTable;
     private generateId;
 }
@@ -84,4 +171,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { InMemoryDriver, _default as default };
+export { InMemoryDriver, type InMemoryDriverConfig, _default as default };

package/dist/index.d.ts

@@ -1,11 +1,33 @@
 import { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import { DriverInterface } from '@objectstack/core';
+import { DriverInterface, Logger } from '@objectstack/core';
 
 /**
- * Example: In-Memory Driver
+ * Configuration options for the InMemory driver.
+ * Aligned with @objectstack/spec MemoryConfigSchema.
+ */
+interface InMemoryDriverConfig {
+    /** Optional: Initial data to populate the store */
+    initialData?: Record<string, Record<string, unknown>[]>;
+    /** Optional: Enable strict mode (throw on missing records) */
+    strictMode?: boolean;
+    /** Optional: Logger instance */
+    logger?: Logger;
+}
+/**
+ * In-Memory Driver for ObjectStack
+ *
+ * A production-ready implementation of the ObjectStack Driver Protocol
+ * powered by Mingo — a MongoDB-compatible query and aggregation engine.
  *
- * A minimal reference implementation of the ObjectStack Driver Protocol.
- * This driver stores data in a simple JavaScript object (Heap).
+ * Features:
+ * - MongoDB-compatible query engine (Mingo) for filtering, projection, aggregation
+ * - Full CRUD and bulk operations
+ * - Aggregation pipeline support ($match, $group, $sort, $project, $unwind, etc.)
+ * - Snapshot-based transactions (begin/commit/rollback)
+ * - Field projection and distinct values
+ * - Strict mode and initial data loading
+ *
+ * Reference: objectql/packages/drivers/memory
  */
 declare class InMemoryDriver implements DriverInterface {
     name: string;
@@ -13,7 +35,9 @@ declare class InMemoryDriver implements DriverInterface {
     version: string;
     private config;
     private logger;
-    constructor(config?: any);
+    private idCounters;
+    private transactions;
+    constructor(config?: InMemoryDriverConfig);
     install(ctx: any): void;
     supports: {
         transactions: boolean;
@@ -66,14 +90,77 @@ declare class InMemoryDriver implements DriverInterface {
         data: Record<string, any>;
     }[], options?: DriverOptions): Promise<any[]>;
     bulkDelete(object: string, ids: (string | number)[], options?: DriverOptions): Promise<void>;
-    syncSchema(object: string, schema: any, options?: DriverOptions): Promise<void>;
-    dropTable(object: string, options?: DriverOptions): Promise<void>;
-    beginTransaction(): Promise<void>;
-    commit(): Promise<void>;
-    rollback(): Promise<void>;
+    beginTransaction(): Promise<{
+        id: string;
+    }>;
+    commit(txHandle?: unknown): Promise<void>;
+    rollback(txHandle?: unknown): Promise<void>;
+    /**
+     * Remove all data from the store.
+     */
+    clear(): Promise<void>;
+    /**
+     * Get total number of records across all tables.
+     */
+    getSize(): number;
+    /**
+     * Get distinct values for a field, optionally filtered.
+     */
+    distinct(object: string, field: string, query?: QueryInput): Promise<any[]>;
+    /**
+     * Execute a MongoDB-style aggregation pipeline using Mingo.
+     *
+     * Supports all standard MongoDB pipeline stages:
+     * - $match, $group, $sort, $project, $unwind, $limit, $skip
+     * - $addFields, $replaceRoot, $lookup (limited), $count
+     * - Accumulator operators: $sum, $avg, $min, $max, $first, $last, $push, $addToSet
+     *
+     * @example
+     * // Group by status and count
+     * const results = await driver.aggregate('orders', [
+     *   { $match: { status: 'completed' } },
+     *   { $group: { _id: '$customer', totalAmount: { $sum: '$amount' } } }
+     * ]);
+     *
+     * @example
+     * // Calculate average with filter
+     * const results = await driver.aggregate('products', [
+     *   { $match: { category: 'electronics' } },
+     *   { $group: { _id: null, avgPrice: { $avg: '$price' } } }
+     * ]);
+     */
+    aggregate(object: string, pipeline: Record<string, any>[], options?: DriverOptions): Promise<any[]>;
+    /**
+     * Convert ObjectQL filter format to MongoDB query format for Mingo.
+     *
+     * Supports:
+     * 1. AST Comparison Node: { type: 'comparison', field, operator, value }
+     * 2. AST Logical Node: { type: 'logical', operator: 'and'|'or', conditions: [...] }
+     * 3. Legacy Array Format: [['field', 'op', value], 'and', ['field2', 'op', value2]]
+     * 4. MongoDB Format: { field: value } or { field: { $eq: value } } (passthrough)
+     */
+    private convertToMongoQuery;
+    /**
+     * Convert a single ObjectQL condition to MongoDB operator format.
+     */
+    private convertConditionToMongo;
+    /**
+     * Escape special regex characters for safe literal matching.
+     */
+    private escapeRegex;
     private performAggregation;
     private computeAggregate;
     private setValueByPath;
+    syncSchema(object: string, schema: any, options?: DriverOptions): Promise<void>;
+    dropTable(object: string, options?: DriverOptions): Promise<void>;
+    /**
+     * Apply manual sorting (Mingo sort has CJS build issues).
+     */
+    private applySort;
+    /**
+     * Project specific fields from a record.
+     */
+    private projectFields;
     private getTable;
     private generateId;
 }
@@ -84,4 +171,4 @@ declare const _default: {
     onEnable: (context: any) => Promise<void>;
 };
 
-export { InMemoryDriver, _default as default };
+export { InMemoryDriver, type InMemoryDriverConfig, _default as default };