@objectstack/service-analytics 3.2.9

package/dist/index.js

@@ -0,0 +1,600 @@
+// src/analytics-service.ts
+import { createLogger } from "@objectstack/core";
+
+// src/cube-registry.ts
+var CubeRegistry = class {
+  constructor() {
+    this.cubes = /* @__PURE__ */ new Map();
+  }
+  /** Register a single cube definition. Overwrites if name already exists. */
+  register(cube) {
+    this.cubes.set(cube.name, cube);
+  }
+  /** Register multiple cube definitions at once. */
+  registerAll(cubes) {
+    for (const cube of cubes) {
+      this.register(cube);
+    }
+  }
+  /** Get a cube definition by name. */
+  get(name) {
+    return this.cubes.get(name);
+  }
+  /** Check if a cube is registered. */
+  has(name) {
+    return this.cubes.has(name);
+  }
+  /** Return all registered cubes. */
+  getAll() {
+    return Array.from(this.cubes.values());
+  }
+  /** Return all cube names. */
+  names() {
+    return Array.from(this.cubes.keys());
+  }
+  /** Number of registered cubes. */
+  get size() {
+    return this.cubes.size;
+  }
+  /** Remove all cubes. */
+  clear() {
+    this.cubes.clear();
+  }
+  /**
+   * Auto-generate a cube definition from an object schema.
+   *
+   * Heuristic rules:
+   * - `number` fields → `sum`, `avg`, `min`, `max` measures
+   * - `boolean` fields → `count` measure (count where true)
+   * - All non-computed fields → dimensions
+   * - `date`/`datetime` fields → time dimensions with standard granularities
+   * - A default `count` measure is always added
+   *
+   * @param objectName - The snake_case object name (used as table/cube name)
+   * @param fields - Array of field descriptors `{ name, type, label? }`
+   */
+  inferFromObject(objectName, fields) {
+    const measures = {
+      count: {
+        name: "count",
+        label: "Count",
+        type: "count",
+        sql: "*"
+      }
+    };
+    const dimensions = {};
+    for (const field of fields) {
+      const label = field.label || field.name;
+      const dimType = this.fieldTypeToDimensionType(field.type);
+      dimensions[field.name] = {
+        name: field.name,
+        label,
+        type: dimType,
+        sql: field.name,
+        ...dimType === "time" ? { granularities: ["day", "week", "month", "quarter", "year"] } : {}
+      };
+      if (field.type === "number" || field.type === "currency" || field.type === "percent") {
+        measures[`${field.name}_sum`] = {
+          name: `${field.name}_sum`,
+          label: `${label} (Sum)`,
+          type: "sum",
+          sql: field.name
+        };
+        measures[`${field.name}_avg`] = {
+          name: `${field.name}_avg`,
+          label: `${label} (Avg)`,
+          type: "avg",
+          sql: field.name
+        };
+      }
+    }
+    const cube = {
+      name: objectName,
+      title: objectName,
+      sql: objectName,
+      measures,
+      dimensions,
+      public: false
+    };
+    this.register(cube);
+    return cube;
+  }
+  fieldTypeToDimensionType(fieldType) {
+    switch (fieldType) {
+      case "number":
+      case "currency":
+      case "percent":
+        return "number";
+      case "boolean":
+        return "boolean";
+      case "date":
+      case "datetime":
+        return "time";
+      default:
+        return "string";
+    }
+  }
+};
+
+// src/strategies/native-sql-strategy.ts
+var NativeSQLStrategy = class {
+  constructor() {
+    this.name = "NativeSQLStrategy";
+    this.priority = 10;
+  }
+  canHandle(query, ctx) {
+    if (!query.cube) return false;
+    const caps = ctx.queryCapabilities(query.cube);
+    return caps.nativeSql && typeof ctx.executeRawSql === "function";
+  }
+  async execute(query, ctx) {
+    const { sql, params } = await this.generateSql(query, ctx);
+    const cube = ctx.getCube(query.cube);
+    const objectName = this.extractObjectName(cube);
+    const rows = await ctx.executeRawSql(objectName, sql, params);
+    const fields = this.buildFieldMeta(query, cube);
+    return { rows, fields, sql };
+  }
+  async generateSql(query, ctx) {
+    const cube = ctx.getCube(query.cube);
+    if (!cube) {
+      throw new Error(`Cube not found: ${query.cube}`);
+    }
+    const params = [];
+    const selectClauses = [];
+    const groupByClauses = [];
+    if (query.dimensions && query.dimensions.length > 0) {
+      for (const dim of query.dimensions) {
+        const colExpr = this.resolveDimensionSql(cube, dim);
+        selectClauses.push(`${colExpr} AS "${dim}"`);
+        groupByClauses.push(colExpr);
+      }
+    }
+    if (query.measures && query.measures.length > 0) {
+      for (const measure of query.measures) {
+        const aggExpr = this.resolveMeasureSql(cube, measure);
+        selectClauses.push(`${aggExpr} AS "${measure}"`);
+      }
+    }
+    const whereClauses = [];
+    if (query.filters && query.filters.length > 0) {
+      for (const filter of query.filters) {
+        const colExpr = this.resolveFieldSql(cube, filter.member);
+        const clause = this.buildFilterClause(colExpr, filter.operator, filter.values, params);
+        if (clause) whereClauses.push(clause);
+      }
+    }
+    if (query.timeDimensions && query.timeDimensions.length > 0) {
+      for (const td of query.timeDimensions) {
+        const colExpr = this.resolveFieldSql(cube, td.dimension);
+        if (td.dateRange) {
+          const range = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
+          if (range.length === 2) {
+            params.push(range[0], range[1]);
+            whereClauses.push(`${colExpr} BETWEEN $${params.length - 1} AND $${params.length}`);
+          }
+        }
+      }
+    }
+    const tableName = this.extractObjectName(cube);
+    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 && Object.keys(query.order).length > 0) {
+      const orderClauses = Object.entries(query.order).map(([f, d]) => `"${f}" ${d.toUpperCase()}`);
+      sql += ` ORDER BY ${orderClauses.join(", ")}`;
+    }
+    if (query.limit != null) {
+      sql += ` LIMIT ${query.limit}`;
+    }
+    if (query.offset != null) {
+      sql += ` OFFSET ${query.offset}`;
+    }
+    return { sql, params };
+  }
+  // ── Helpers ──────────────────────────────────────────────────────
+  resolveDimensionSql(cube, member) {
+    const fieldName = member.includes(".") ? member.split(".")[1] : member;
+    const dim = cube.dimensions[fieldName];
+    return dim ? dim.sql : fieldName;
+  }
+  resolveMeasureSql(cube, member) {
+    const fieldName = member.includes(".") ? member.split(".")[1] : member;
+    const measure = cube.measures[fieldName];
+    if (!measure) return `COUNT(*)`;
+    const col = measure.sql;
+    switch (measure.type) {
+      case "count":
+        return "COUNT(*)";
+      case "sum":
+        return `SUM(${col})`;
+      case "avg":
+        return `AVG(${col})`;
+      case "min":
+        return `MIN(${col})`;
+      case "max":
+        return `MAX(${col})`;
+      case "count_distinct":
+        return `COUNT(DISTINCT ${col})`;
+      default:
+        return `COUNT(*)`;
+    }
+  }
+  resolveFieldSql(cube, member) {
+    const fieldName = member.includes(".") ? member.split(".")[1] : member;
+    const dim = cube.dimensions[fieldName];
+    if (dim) return dim.sql;
+    const measure = cube.measures[fieldName];
+    if (measure) return measure.sql;
+    return fieldName;
+  }
+  buildFilterClause(col, operator, values, params) {
+    const opMap = {
+      equals: "=",
+      notEquals: "!=",
+      gt: ">",
+      gte: ">=",
+      lt: "<",
+      lte: "<=",
+      contains: "LIKE",
+      notContains: "NOT LIKE"
+    };
+    if (operator === "set") return `${col} IS NOT NULL`;
+    if (operator === "notSet") return `${col} IS NULL`;
+    const sqlOp = opMap[operator];
+    if (!sqlOp || !values || values.length === 0) return null;
+    if (operator === "contains" || operator === "notContains") {
+      params.push(`%${values[0]}%`);
+    } else {
+      params.push(values[0]);
+    }
+    return `${col} ${sqlOp} $${params.length}`;
+  }
+  extractObjectName(cube) {
+    return cube.sql.trim();
+  }
+  buildFieldMeta(query, cube) {
+    const fields = [];
+    if (query.dimensions) {
+      for (const dim of query.dimensions) {
+        const fieldName = dim.includes(".") ? dim.split(".")[1] : dim;
+        const d = cube.dimensions[fieldName];
+        fields.push({ name: dim, type: d?.type || "string" });
+      }
+    }
+    if (query.measures) {
+      for (const m of query.measures) {
+        fields.push({ name: m, type: "number" });
+      }
+    }
+    return fields;
+  }
+};
+
+// src/strategies/objectql-strategy.ts
+var ObjectQLStrategy = class {
+  constructor() {
+    this.name = "ObjectQLStrategy";
+    this.priority = 20;
+  }
+  canHandle(query, ctx) {
+    if (!query.cube) return false;
+    const caps = ctx.queryCapabilities(query.cube);
+    return caps.objectqlAggregate && typeof ctx.executeAggregate === "function";
+  }
+  async execute(query, ctx) {
+    const cube = ctx.getCube(query.cube);
+    const objectName = this.extractObjectName(cube);
+    const groupBy = [];
+    if (query.dimensions && query.dimensions.length > 0) {
+      for (const dim of query.dimensions) {
+        groupBy.push(this.resolveFieldName(cube, dim, "dimension"));
+      }
+    }
+    const aggregations = [];
+    if (query.measures && query.measures.length > 0) {
+      for (const measure of query.measures) {
+        const { field, method } = this.resolveMeasureAggregation(cube, measure);
+        aggregations.push({ field, method, alias: measure });
+      }
+    }
+    const filter = {};
+    if (query.filters && query.filters.length > 0) {
+      for (const f of query.filters) {
+        const fieldName = this.resolveFieldName(cube, f.member, "any");
+        filter[fieldName] = this.convertFilter(f.operator, f.values);
+      }
+    }
+    const rows = await ctx.executeAggregate(objectName, {
+      groupBy: groupBy.length > 0 ? groupBy : void 0,
+      aggregations: aggregations.length > 0 ? aggregations : void 0,
+      filter: Object.keys(filter).length > 0 ? filter : void 0
+    });
+    const mappedRows = rows.map((row) => {
+      const mapped = {};
+      if (query.dimensions) {
+        for (const dim of query.dimensions) {
+          const shortName = this.resolveFieldName(cube, dim, "dimension");
+          if (shortName in row) mapped[dim] = row[shortName];
+        }
+      }
+      if (query.measures) {
+        for (const m of query.measures) {
+          if (m in row) mapped[m] = row[m];
+        }
+      }
+      return mapped;
+    });
+    const fields = this.buildFieldMeta(query, cube);
+    return { rows: mappedRows, fields };
+  }
+  async generateSql(query, ctx) {
+    const cube = ctx.getCube(query.cube);
+    if (!cube) {
+      throw new Error(`Cube not found: ${query.cube}`);
+    }
+    const selectParts = [];
+    const groupByParts = [];
+    if (query.dimensions) {
+      for (const dim of query.dimensions) {
+        const col = this.resolveFieldName(cube, dim, "dimension");
+        selectParts.push(`${col} AS "${dim}"`);
+        groupByParts.push(col);
+      }
+    }
+    if (query.measures) {
+      for (const m of query.measures) {
+        const { field, method } = this.resolveMeasureAggregation(cube, m);
+        const aggSql = method === "count" ? "COUNT(*)" : `${method.toUpperCase()}(${field})`;
+        selectParts.push(`${aggSql} AS "${m}"`);
+      }
+    }
+    const tableName = this.extractObjectName(cube);
+    let sql = `SELECT ${selectParts.join(", ")} FROM "${tableName}"`;
+    if (groupByParts.length > 0) {
+      sql += ` GROUP BY ${groupByParts.join(", ")}`;
+    }
+    return { sql, params: [] };
+  }
+  // ── Helpers ──────────────────────────────────────────────────────
+  resolveFieldName(cube, member, kind) {
+    const fieldName = member.includes(".") ? member.split(".")[1] : member;
+    if (kind === "dimension" || kind === "any") {
+      const dim = cube.dimensions[fieldName];
+      if (dim) return dim.sql.replace(/^\$/, "");
+    }
+    if (kind === "measure" || kind === "any") {
+      const measure = cube.measures[fieldName];
+      if (measure) return measure.sql.replace(/^\$/, "");
+    }
+    return fieldName;
+  }
+  resolveMeasureAggregation(cube, measureName) {
+    const fieldName = measureName.includes(".") ? measureName.split(".")[1] : measureName;
+    const measure = cube.measures[fieldName];
+    if (!measure) return { field: "*", method: "count" };
+    return {
+      field: measure.sql.replace(/^\$/, ""),
+      method: measure.type === "count_distinct" ? "count_distinct" : measure.type
+    };
+  }
+  convertFilter(operator, values) {
+    if (operator === "set") return { $ne: null };
+    if (operator === "notSet") return null;
+    if (!values || values.length === 0) return void 0;
+    switch (operator) {
+      case "equals":
+        return values[0];
+      case "notEquals":
+        return { $ne: values[0] };
+      case "gt":
+        return { $gt: values[0] };
+      case "gte":
+        return { $gte: values[0] };
+      case "lt":
+        return { $lt: values[0] };
+      case "lte":
+        return { $lte: values[0] };
+      case "contains":
+        return { $regex: values[0] };
+      default:
+        return values[0];
+    }
+  }
+  extractObjectName(cube) {
+    return cube.sql.trim();
+  }
+  buildFieldMeta(query, cube) {
+    const fields = [];
+    if (query.dimensions) {
+      for (const dim of query.dimensions) {
+        const fieldName = dim.includes(".") ? dim.split(".")[1] : dim;
+        const d = cube.dimensions[fieldName];
+        fields.push({ name: dim, type: d?.type || "string" });
+      }
+    }
+    if (query.measures) {
+      for (const m of query.measures) {
+        fields.push({ name: m, type: "number" });
+      }
+    }
+    return fields;
+  }
+};
+
+// src/analytics-service.ts
+var DEFAULT_CAPABILITIES = {
+  nativeSql: false,
+  objectqlAggregate: false,
+  inMemory: true
+};
+var AnalyticsService = class {
+  constructor(config = {}) {
+    this.logger = config.logger || createLogger({ level: "info", format: "pretty" });
+    this.cubeRegistry = new CubeRegistry();
+    if (config.cubes) {
+      this.cubeRegistry.registerAll(config.cubes);
+    }
+    this.strategyCtx = {
+      getCube: (name) => this.cubeRegistry.get(name),
+      queryCapabilities: config.queryCapabilities || (() => DEFAULT_CAPABILITIES),
+      executeRawSql: config.executeRawSql,
+      executeAggregate: config.executeAggregate,
+      fallbackService: config.fallbackService
+    };
+    const builtIn = [
+      new NativeSQLStrategy(),
+      new ObjectQLStrategy()
+    ];
+    if (config.fallbackService) {
+      builtIn.push(new FallbackDelegateStrategy());
+    }
+    const custom = config.strategies || [];
+    this.strategies = [...builtIn, ...custom].sort((a, b) => a.priority - b.priority);
+    this.logger.info(
+      `[Analytics] Initialized with ${this.cubeRegistry.size} cubes, ${this.strategies.length} strategies: ${this.strategies.map((s) => s.name).join(" \u2192 ")}`
+    );
+  }
+  /**
+   * Execute an analytical query by delegating to the first capable strategy.
+   */
+  async query(query) {
+    if (!query.cube) {
+      throw new Error("Cube name is required in analytics query");
+    }
+    const strategy = this.resolveStrategy(query);
+    this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
+    return strategy.execute(query, this.strategyCtx);
+  }
+  /**
+   * Get cube metadata for discovery.
+   */
+  async getMeta(cubeName) {
+    const cubes = cubeName ? [this.cubeRegistry.get(cubeName)].filter(Boolean) : this.cubeRegistry.getAll();
+    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 for a query without executing it (dry-run).
+   */
+  async generateSql(query) {
+    if (!query.cube) {
+      throw new Error("Cube name is required for SQL generation");
+    }
+    const strategy = this.resolveStrategy(query);
+    this.logger.debug(`[Analytics] generateSql on cube "${query.cube}" \u2192 ${strategy.name}`);
+    return strategy.generateSql(query, this.strategyCtx);
+  }
+  // ── Internal ─────────────────────────────────────────────────────
+  /**
+   * Walk the strategy chain and return the first strategy that can handle the query.
+   */
+  resolveStrategy(query) {
+    for (const strategy of this.strategies) {
+      if (strategy.canHandle(query, this.strategyCtx)) {
+        return strategy;
+      }
+    }
+    throw new Error(
+      `[Analytics] No strategy can handle query for cube "${query.cube}". Checked: ${this.strategies.map((s) => s.name).join(", ")}. Ensure a compatible driver is configured or a fallback service is registered.`
+    );
+  }
+};
+var FallbackDelegateStrategy = class {
+  constructor() {
+    this.name = "FallbackDelegateStrategy";
+    this.priority = 30;
+  }
+  canHandle(query, ctx) {
+    if (!query.cube) return false;
+    return !!ctx.fallbackService;
+  }
+  async execute(query, ctx) {
+    return ctx.fallbackService.query(query);
+  }
+  async generateSql(query, ctx) {
+    if (ctx.fallbackService?.generateSql) {
+      return ctx.fallbackService.generateSql(query);
+    }
+    return {
+      sql: `-- FallbackDelegateStrategy: SQL generation not supported for cube "${query.cube}"`,
+      params: []
+    };
+  }
+};
+
+// src/plugin.ts
+var AnalyticsServicePlugin = class {
+  constructor(options = {}) {
+    this.name = "com.objectstack.service-analytics";
+    this.version = "1.0.0";
+    this.type = "standard";
+    this.dependencies = [];
+    this.options = options;
+  }
+  async init(ctx) {
+    let fallbackService;
+    try {
+      const existing = ctx.getService("analytics");
+      if (existing && typeof existing.query === "function") {
+        fallbackService = existing;
+        ctx.logger.debug("[Analytics] Found existing analytics service, using as fallback");
+      }
+    } catch {
+    }
+    const config = {
+      cubes: this.options.cubes,
+      logger: ctx.logger,
+      queryCapabilities: this.options.queryCapabilities,
+      executeRawSql: this.options.executeRawSql,
+      executeAggregate: this.options.executeAggregate,
+      fallbackService
+    };
+    this.service = new AnalyticsService(config);
+    if (fallbackService) {
+      ctx.replaceService("analytics", this.service);
+    } else {
+      ctx.registerService("analytics", this.service);
+    }
+    if (this.options.debug) {
+      ctx.hook("analytics:beforeQuery", async (query) => {
+        ctx.logger.debug("[Analytics] Before query", { query });
+      });
+    }
+    ctx.logger.info("[Analytics] Service initialized");
+  }
+  async start(ctx) {
+    if (!this.service) return;
+    await ctx.trigger("analytics:ready", this.service);
+    ctx.logger.info(
+      `[Analytics] Service started with ${this.service.cubeRegistry.size} cubes: ${this.service.cubeRegistry.names().join(", ") || "(none)"}`
+    );
+  }
+  async destroy() {
+    this.service = void 0;
+  }
+};
+export {
+  AnalyticsService,
+  AnalyticsServicePlugin,
+  CubeRegistry,
+  NativeSQLStrategy,
+  ObjectQLStrategy
+};
+//# sourceMappingURL=index.js.map