@objectstack/driver-memory 2.0.6 → 3.0.0

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@3.0.0 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     36.64 KB
+ESM dist/index.mjs.map 77.34 KB
+ESM ⚡️ Build success in 93ms
+CJS dist/index.js     37.79 KB
+CJS dist/index.js.map 77.38 KB
+CJS ⚡️ Build success in 98ms
 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 10279ms
+DTS dist/index.d.mts 8.39 KB
+DTS dist/index.d.ts  8.39 KB

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @objectstack/driver-memory
 
+## 3.0.0
+
+### Major Changes
+
+- Release v3.0.0 — unified version bump for all ObjectStack packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - @objectstack/spec@3.0.0
+  - @objectstack/core@3.0.0
+
+## 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,34 @@
-import { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import { DriverInterface } from '@objectstack/core';
+import { QueryInput, DriverOptions, Cube, AnalyticsQuery } from '@objectstack/spec/data';
+import { DriverInterface, Logger } from '@objectstack/core';
+import { IAnalyticsService, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
 
 /**
- * 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 minimal reference implementation of the ObjectStack Driver Protocol.
- * This driver stores data in a simple JavaScript object (Heap).
+ * A production-ready implementation of the ObjectStack Driver Protocol
+ * powered by Mingo — a MongoDB-compatible query and aggregation engine.
+ *
+ * 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 +36,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,22 +91,150 @@ 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;
 }
 
+/**
+ * Configuration for MemoryAnalyticsService
+ */
+interface MemoryAnalyticsConfig {
+    /** The data driver instance to use for queries */
+    driver: InMemoryDriver;
+    /** Cube definitions for the semantic layer */
+    cubes: Cube[];
+    /** Optional logger */
+    logger?: Logger;
+}
+/**
+ * Memory-Based Analytics Service
+ *
+ * Implements IAnalyticsService using InMemoryDriver's aggregation capabilities.
+ * Provides a semantic layer (Cubes, Metrics, Dimensions) on top of in-memory data.
+ *
+ * Features:
+ * - Cube-based semantic modeling
+ * - Measure calculations (count, sum, avg, min, max, count_distinct)
+ * - Dimension grouping
+ * - Filter support
+ * - Time dimension handling
+ * - SQL generation (for debugging/transparency)
+ *
+ * This implementation is suitable for:
+ * - Development and testing
+ * - Local-first analytics
+ * - Small to medium datasets
+ * - Prototyping BI applications
+ */
+declare class MemoryAnalyticsService implements IAnalyticsService {
+    private driver;
+    private cubes;
+    private logger;
+    constructor(config: MemoryAnalyticsConfig);
+    /**
+     * Execute an analytical query using the memory driver's aggregation pipeline
+     */
+    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+    /**
+     * Get available cube metadata for discovery
+     */
+    getMeta(cubeName?: string): Promise<CubeMeta[]>;
+    /**
+     * Generate SQL representation for debugging/transparency
+     */
+    generateSql(query: AnalyticsQuery): Promise<{
+        sql: string;
+        params: unknown[];
+    }>;
+    private resolveFieldPath;
+    private resolveMeasure;
+    private resolveDimension;
+    private getShortName;
+    private buildAggregator;
+    private measureTypeToFieldType;
+    private convertOperatorToMongo;
+    private operatorToSql;
+    private measureToSql;
+    private extractTableName;
+    private parseDateRangeString;
+    private generateSqlFromPipeline;
+}
+
 declare const _default: {
     id: string;
     version: string;
     onEnable: (context: any) => Promise<void>;
 };
 
-export { InMemoryDriver, _default as default };
+export { InMemoryDriver, type InMemoryDriverConfig, type MemoryAnalyticsConfig, MemoryAnalyticsService, _default as default };

package/dist/index.d.ts

@@ -1,11 +1,34 @@
-import { QueryInput, DriverOptions } from '@objectstack/spec/data';
-import { DriverInterface } from '@objectstack/core';
+import { QueryInput, DriverOptions, Cube, AnalyticsQuery } from '@objectstack/spec/data';
+import { DriverInterface, Logger } from '@objectstack/core';
+import { IAnalyticsService, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
 
 /**
- * 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 minimal reference implementation of the ObjectStack Driver Protocol.
- * This driver stores data in a simple JavaScript object (Heap).
+ * A production-ready implementation of the ObjectStack Driver Protocol
+ * powered by Mingo — a MongoDB-compatible query and aggregation engine.
+ *
+ * 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 +36,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,22 +91,150 @@ 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;
 }
 
+/**
+ * Configuration for MemoryAnalyticsService
+ */
+interface MemoryAnalyticsConfig {
+    /** The data driver instance to use for queries */
+    driver: InMemoryDriver;
+    /** Cube definitions for the semantic layer */
+    cubes: Cube[];
+    /** Optional logger */
+    logger?: Logger;
+}
+/**
+ * Memory-Based Analytics Service
+ *
+ * Implements IAnalyticsService using InMemoryDriver's aggregation capabilities.
+ * Provides a semantic layer (Cubes, Metrics, Dimensions) on top of in-memory data.
+ *
+ * Features:
+ * - Cube-based semantic modeling
+ * - Measure calculations (count, sum, avg, min, max, count_distinct)
+ * - Dimension grouping
+ * - Filter support
+ * - Time dimension handling
+ * - SQL generation (for debugging/transparency)
+ *
+ * This implementation is suitable for:
+ * - Development and testing
+ * - Local-first analytics
+ * - Small to medium datasets
+ * - Prototyping BI applications
+ */
+declare class MemoryAnalyticsService implements IAnalyticsService {
+    private driver;
+    private cubes;
+    private logger;
+    constructor(config: MemoryAnalyticsConfig);
+    /**
+     * Execute an analytical query using the memory driver's aggregation pipeline
+     */
+    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+    /**
+     * Get available cube metadata for discovery
+     */
+    getMeta(cubeName?: string): Promise<CubeMeta[]>;
+    /**
+     * Generate SQL representation for debugging/transparency
+     */
+    generateSql(query: AnalyticsQuery): Promise<{
+        sql: string;
+        params: unknown[];
+    }>;
+    private resolveFieldPath;
+    private resolveMeasure;
+    private resolveDimension;
+    private getShortName;
+    private buildAggregator;
+    private measureTypeToFieldType;
+    private convertOperatorToMongo;
+    private operatorToSql;
+    private measureToSql;
+    private extractTableName;
+    private parseDateRangeString;
+    private generateSqlFromPipeline;
+}
+
 declare const _default: {
     id: string;
     version: string;
     onEnable: (context: any) => Promise<void>;
 };
 
-export { InMemoryDriver, _default as default };
+export { InMemoryDriver, type InMemoryDriverConfig, type MemoryAnalyticsConfig, MemoryAnalyticsService, _default as default };