@objectstack/driver-memory 2.0.7 → 3.0.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/driver-memory@2.0.7 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     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
+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 10233ms
-DTS dist/index.d.mts 6.37 KB
-DTS dist/index.d.ts  6.37 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,17 @@
 # @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

package/dist/index.d.mts

@@ -1,5 +1,6 @@
-import { QueryInput, DriverOptions } from '@objectstack/spec/data';
+import { QueryInput, DriverOptions, Cube, AnalyticsQuery } from '@objectstack/spec/data';
 import { DriverInterface, Logger } from '@objectstack/core';
+import { IAnalyticsService, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
 
 /**
  * Configuration options for the InMemory driver.
@@ -165,10 +166,75 @@ declare class InMemoryDriver implements DriverInterface {
     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, type InMemoryDriverConfig, _default as default };
+export { InMemoryDriver, type InMemoryDriverConfig, type MemoryAnalyticsConfig, MemoryAnalyticsService, _default as default };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-import { QueryInput, DriverOptions } from '@objectstack/spec/data';
+import { QueryInput, DriverOptions, Cube, AnalyticsQuery } from '@objectstack/spec/data';
 import { DriverInterface, Logger } from '@objectstack/core';
+import { IAnalyticsService, AnalyticsResult, CubeMeta } from '@objectstack/spec/contracts';
 
 /**
  * Configuration options for the InMemory driver.
@@ -165,10 +166,75 @@ declare class InMemoryDriver implements DriverInterface {
     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, type InMemoryDriverConfig, _default as default };
+export { InMemoryDriver, type InMemoryDriverConfig, type MemoryAnalyticsConfig, MemoryAnalyticsService, _default as default };

package/dist/index.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   InMemoryDriver: () => InMemoryDriver,
+  MemoryAnalyticsService: () => MemoryAnalyticsService,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -703,6 +704,399 @@ var InMemoryDriver = class {
   }
 };
 
+// src/memory-analytics.ts
+var import_core2 = require("@objectstack/core");
+var MemoryAnalyticsService = class {
+  constructor(config) {
+    this.driver = config.driver;
+    this.cubes = new Map(config.cubes.map((c) => [c.name, c]));
+    this.logger = config.logger || (0, import_core2.createLogger)({ level: "info", format: "pretty" });
+    this.logger.debug("MemoryAnalyticsService initialized", { cubeCount: this.cubes.size });
+  }
+  /**
+   * Execute an analytical query using the memory driver's aggregation pipeline
+   */
+  async query(query) {
+    this.logger.debug("Executing analytics query", { cube: query.cube, measures: query.measures });
+    if (!query.cube) {
+      throw new Error("Cube name is required");
+    }
+    const cube = this.cubes.get(query.cube);
+    if (!cube) {
+      throw new Error(`Cube not found: ${query.cube}`);
+    }
+    const pipeline = [];
+    if (query.filters && query.filters.length > 0) {
+      const matchStage = {};
+      for (const filter of query.filters) {
+        const mongoOp = this.convertOperatorToMongo(filter.operator);
+        const fieldPath = this.resolveFieldPath(cube, filter.member);
+        if (filter.values && filter.values.length > 0) {
+          if (mongoOp === "$in") {
+            matchStage[fieldPath] = { $in: filter.values };
+          } else if (mongoOp === "$nin") {
+            matchStage[fieldPath] = { $nin: filter.values };
+          } else {
+            matchStage[fieldPath] = { [mongoOp]: filter.values[0] };
+          }
+        } else if (mongoOp === "$exists") {
+          matchStage[fieldPath] = { $exists: filter.operator === "set" };
+        }
+      }
+      if (Object.keys(matchStage).length > 0) {
+        pipeline.push({ $match: matchStage });
+      }
+    }
+    if (query.timeDimensions && query.timeDimensions.length > 0) {
+      for (const timeDim of query.timeDimensions) {
+        const fieldPath = this.resolveFieldPath(cube, timeDim.dimension);
+        if (timeDim.dateRange) {
+          const range = Array.isArray(timeDim.dateRange) ? timeDim.dateRange : this.parseDateRangeString(timeDim.dateRange);
+          if (range.length === 2) {
+            pipeline.push({
+              $match: {
+                [fieldPath]: {
+                  $gte: new Date(range[0]),
+                  $lte: new Date(range[1])
+                }
+              }
+            });
+          }
+        }
+      }
+    }
+    const groupStage = { _id: {} };
+    if (query.dimensions && query.dimensions.length > 0) {
+      for (const dim of query.dimensions) {
+        const fieldPath = this.resolveFieldPath(cube, dim);
+        const dimName = this.getShortName(dim);
+        groupStage._id[dimName] = `$${fieldPath}`;
+      }
+    } else {
+      groupStage._id = null;
+    }
+    if (query.measures && query.measures.length > 0) {
+      for (const measure of query.measures) {
+        const measureDef = this.resolveMeasure(cube, measure);
+        const measureName = this.getShortName(measure);
+        if (measureDef) {
+          const aggregator = this.buildAggregator(measureDef);
+          groupStage[measureName] = aggregator;
+        }
+      }
+    }
+    pipeline.push({ $group: groupStage });
+    const projectStage = { _id: 0 };
+    if (query.dimensions && query.dimensions.length > 0) {
+      for (const dim of query.dimensions) {
+        const dimName = this.getShortName(dim);
+        projectStage[dimName] = `$_id.${dimName}`;
+      }
+    }
+    if (query.measures && query.measures.length > 0) {
+      for (const measure of query.measures) {
+        const measureName = this.getShortName(measure);
+        projectStage[measureName] = `$${measureName}`;
+      }
+    }
+    pipeline.push({ $project: projectStage });
+    if (query.order && Object.keys(query.order).length > 0) {
+      const sortStage = {};
+      for (const [field, direction] of Object.entries(query.order)) {
+        const shortName = this.getShortName(field);
+        sortStage[shortName] = direction === "asc" ? 1 : -1;
+      }
+      pipeline.push({ $sort: sortStage });
+    }
+    if (query.offset) {
+      pipeline.push({ $skip: query.offset });
+    }
+    if (query.limit) {
+      pipeline.push({ $limit: query.limit });
+    }
+    const tableName = this.extractTableName(cube.sql);
+    const rawRows = await this.driver.aggregate(tableName, pipeline);
+    const rows = rawRows.map((row) => {
+      const renamedRow = {};
+      if (query.dimensions) {
+        for (const dim of query.dimensions) {
+          const shortName = this.getShortName(dim);
+          if (shortName in row) {
+            renamedRow[dim] = row[shortName];
+          }
+        }
+      }
+      if (query.measures) {
+        for (const measure of query.measures) {
+          const shortName = this.getShortName(measure);
+          if (shortName in row) {
+            renamedRow[measure] = row[shortName];
+          }
+        }
+      }
+      return renamedRow;
+    });
+    const fields = [];
+    if (query.dimensions) {
+      for (const dim of query.dimensions) {
+        const dimension = this.resolveDimension(cube, dim);
+        fields.push({
+          name: dim,
+          type: dimension?.type || "string"
+        });
+      }
+    }
+    if (query.measures) {
+      for (const measure of query.measures) {
+        const measureDef = this.resolveMeasure(cube, measure);
+        fields.push({
+          name: measure,
+          type: this.measureTypeToFieldType(measureDef?.type || "count")
+        });
+      }
+    }
+    this.logger.debug("Analytics query completed", { rowCount: rows.length });
+    return {
+      rows,
+      fields,
+      sql: this.generateSqlFromPipeline(tableName, pipeline)
+      // For debugging
+    };
+  }
+  /**
+   * Get available cube metadata for discovery
+   */
+  async getMeta(cubeName) {
+    const cubes = cubeName ? [this.cubes.get(cubeName)].filter(Boolean) : Array.from(this.cubes.values());
+    return cubes.map((cube) => ({
+      name: cube.name,
+      title: cube.title,
+      measures: Object.entries(cube.measures).map(([key, measure]) => ({
+        name: `${cube.name}.${key}`,
+        type: measure.type,
+        title: measure.label
+      })),
+      dimensions: Object.entries(cube.dimensions).map(([key, dimension]) => ({
+        name: `${cube.name}.${key}`,
+        type: dimension.type,
+        title: dimension.label
+      }))
+    }));
+  }
+  /**
+   * Generate SQL representation for debugging/transparency
+   */
+  async generateSql(query) {
+    if (!query.cube) {
+      throw new Error("Cube name is required");
+    }
+    const cube = this.cubes.get(query.cube);
+    if (!cube) {
+      throw new Error(`Cube not found: ${query.cube}`);
+    }
+    const tableName = this.extractTableName(cube.sql);
+    const selectClauses = [];
+    const groupByClauses = [];
+    if (query.dimensions && query.dimensions.length > 0) {
+      for (const dim of query.dimensions) {
+        const fieldPath = this.resolveFieldPath(cube, dim);
+        selectClauses.push(`${fieldPath} AS "${dim}"`);
+        groupByClauses.push(fieldPath);
+      }
+    }
+    if (query.measures && query.measures.length > 0) {
+      for (const measure of query.measures) {
+        const measureDef = this.resolveMeasure(cube, measure);
+        if (measureDef) {
+          const aggSql = this.measureToSql(measureDef);
+          selectClauses.push(`${aggSql} AS "${measure}"`);
+        }
+      }
+    }
+    const whereClauses = [];
+    if (query.filters && query.filters.length > 0) {
+      for (const filter of query.filters) {
+        const fieldPath = this.resolveFieldPath(cube, filter.member);
+        const sqlOp = this.operatorToSql(filter.operator);
+        if (filter.values && filter.values.length > 0) {
+          whereClauses.push(`${fieldPath} ${sqlOp} '${filter.values[0]}'`);
+        }
+      }
+    }
+    let sql = `SELECT ${selectClauses.join(", ")} FROM ${tableName}`;
+    if (whereClauses.length > 0) {
+      sql += ` WHERE ${whereClauses.join(" AND ")}`;
+    }
+    if (groupByClauses.length > 0) {
+      sql += ` GROUP BY ${groupByClauses.join(", ")}`;
+    }
+    if (query.order) {
+      const orderClauses = Object.entries(query.order).map(
+        ([field, dir]) => `"${field}" ${dir.toUpperCase()}`
+      );
+      sql += ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+    if (query.limit) {
+      sql += ` LIMIT ${query.limit}`;
+    }
+    if (query.offset) {
+      sql += ` OFFSET ${query.offset}`;
+    }
+    return { sql, params: [] };
+  }
+  // ===================================
+  // Helper Methods
+  // ===================================
+  resolveFieldPath(cube, member) {
+    const parts = member.split(".");
+    const fieldName = parts.length > 1 ? parts[1] : parts[0];
+    const dimension = cube.dimensions[fieldName];
+    if (dimension) {
+      return dimension.sql.replace(/^\$/, "");
+    }
+    const measure = cube.measures[fieldName];
+    if (measure) {
+      return measure.sql.replace(/^\$/, "");
+    }
+    return fieldName;
+  }
+  resolveMeasure(cube, measureName) {
+    const parts = measureName.split(".");
+    const fieldName = parts.length > 1 ? parts[1] : parts[0];
+    return cube.measures[fieldName];
+  }
+  resolveDimension(cube, dimensionName) {
+    const parts = dimensionName.split(".");
+    const fieldName = parts.length > 1 ? parts[1] : parts[0];
+    return cube.dimensions[fieldName];
+  }
+  getShortName(fullName) {
+    const parts = fullName.split(".");
+    return parts.length > 1 ? parts[1] : parts[0];
+  }
+  buildAggregator(measure) {
+    const fieldPath = measure.sql.replace(/^\$/, "");
+    switch (measure.type) {
+      case "count":
+        return { $sum: 1 };
+      case "sum":
+        return { $sum: `$${fieldPath}` };
+      case "avg":
+        return { $avg: `$${fieldPath}` };
+      case "min":
+        return { $min: `$${fieldPath}` };
+      case "max":
+        return { $max: `$${fieldPath}` };
+      case "count_distinct":
+        return { $addToSet: `$${fieldPath}` };
+      // Will need post-processing for count
+      default:
+        return { $sum: 1 };
+    }
+  }
+  measureTypeToFieldType(measureType) {
+    switch (measureType) {
+      case "count":
+      case "sum":
+      case "count_distinct":
+        return "number";
+      case "avg":
+      case "min":
+      case "max":
+        return "number";
+      case "string":
+        return "string";
+      case "boolean":
+        return "boolean";
+      default:
+        return "number";
+    }
+  }
+  convertOperatorToMongo(operator) {
+    const opMap = {
+      "equals": "$eq",
+      "notEquals": "$ne",
+      "contains": "$regex",
+      "notContains": "$not",
+      "gt": "$gt",
+      "gte": "$gte",
+      "lt": "$lt",
+      "lte": "$lte",
+      "set": "$exists",
+      "notSet": "$exists",
+      "inDateRange": "$gte"
+      // Will need special handling
+    };
+    return opMap[operator] || "$eq";
+  }
+  operatorToSql(operator) {
+    const opMap = {
+      "equals": "=",
+      "notEquals": "!=",
+      "contains": "LIKE",
+      "notContains": "NOT LIKE",
+      "gt": ">",
+      "gte": ">=",
+      "lt": "<",
+      "lte": "<="
+    };
+    return opMap[operator] || "=";
+  }
+  measureToSql(measure) {
+    const fieldPath = measure.sql.replace(/^\$/, "");
+    switch (measure.type) {
+      case "count":
+        return "COUNT(*)";
+      case "sum":
+        return `SUM(${fieldPath})`;
+      case "avg":
+        return `AVG(${fieldPath})`;
+      case "min":
+        return `MIN(${fieldPath})`;
+      case "max":
+        return `MAX(${fieldPath})`;
+      case "count_distinct":
+        return `COUNT(DISTINCT ${fieldPath})`;
+      default:
+        return "COUNT(*)";
+    }
+  }
+  extractTableName(sql) {
+    return sql.trim();
+  }
+  parseDateRangeString(range) {
+    const now = /* @__PURE__ */ new Date();
+    const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+    if (range === "today") {
+      return [today.toISOString(), new Date(today.getTime() + 864e5).toISOString()];
+    } else if (range.startsWith("last ")) {
+      const parts = range.split(" ");
+      const num = parseInt(parts[1]);
+      const unit = parts[2];
+      const start = new Date(today);
+      if (unit.startsWith("day")) {
+        start.setDate(start.getDate() - num);
+      } else if (unit.startsWith("week")) {
+        start.setDate(start.getDate() - num * 7);
+      } else if (unit.startsWith("month")) {
+        start.setMonth(start.getMonth() - num);
+      } else if (unit.startsWith("year")) {
+        start.setFullYear(start.getFullYear() - num);
+      }
+      return [start.toISOString(), now.toISOString()];
+    }
+    return [range, range];
+  }
+  generateSqlFromPipeline(table, pipeline) {
+    const stages = pipeline.map((stage, idx) => {
+      const op = Object.keys(stage)[0];
+      return `/* Stage ${idx + 1}: ${op} */ ${JSON.stringify(stage[op])}`;
+    }).join("\n");
+    return `-- MongoDB Aggregation Pipeline on table: ${table}
+${stages}`;
+  }
+};
+
 // src/index.ts
 var index_default = {
   id: "com.objectstack.driver.memory",
@@ -721,6 +1115,7 @@ var index_default = {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  InMemoryDriver
+  InMemoryDriver,
+  MemoryAnalyticsService
 });
 //# sourceMappingURL=index.js.map