@objectstack/service-analytics 4.0.5 → 4.1.1

package/dist/index.js

@@ -116,6 +116,92 @@ var CubeRegistry = class {
   }
 };
 
+// src/strategies/filter-normalizer.ts
+var MONGO_TO_CUBE_OP = {
+  $eq: "equals",
+  $ne: "notEquals",
+  $gt: "gt",
+  $gte: "gte",
+  $lt: "lt",
+  $lte: "lte",
+  $in: "in",
+  $nin: "notIn",
+  $contains: "contains",
+  $notContains: "notContains",
+  $exists: "set"
+};
+function stringifyForCube(v) {
+  if (v == null) return "";
+  if (typeof v === "boolean") return v ? "1" : "0";
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === "object") return JSON.stringify(v);
+  return String(v);
+}
+function flattenCondition(cond, out) {
+  for (const [key, raw] of Object.entries(cond)) {
+    if (raw === void 0) continue;
+    if (key === "$and" && Array.isArray(raw)) {
+      for (const sub of raw) {
+        if (sub && typeof sub === "object") {
+          flattenCondition(sub, out);
+        }
+      }
+      continue;
+    }
+    if (key === "$or" || key === "$not") continue;
+    if (raw === null) {
+      out.push({ member: key, operator: "notSet", values: [] });
+      continue;
+    }
+    if (typeof raw === "object" && !Array.isArray(raw) && !(raw instanceof Date)) {
+      const wrapper = raw;
+      const opKeys = Object.keys(wrapper).filter((k) => k.startsWith("$"));
+      if (opKeys.length > 0) {
+        for (const opKey of opKeys) {
+          const cubeOp = MONGO_TO_CUBE_OP[opKey];
+          if (!cubeOp) continue;
+          const v = wrapper[opKey];
+          const values = Array.isArray(v) ? v.map(stringifyForCube) : [stringifyForCube(v)];
+          out.push({ member: key, operator: cubeOp, values });
+        }
+        continue;
+      }
+      for (const [nestedKey, nestedVal] of Object.entries(wrapper)) {
+        flattenCondition({ [`${key}.${nestedKey}`]: nestedVal }, out);
+      }
+      continue;
+    }
+    if (Array.isArray(raw)) {
+      out.push({ member: key, operator: "in", values: raw.map(stringifyForCube) });
+    } else {
+      out.push({ member: key, operator: "equals", values: [stringifyForCube(raw)] });
+    }
+  }
+}
+function normalizeAnalyticsFilters(query) {
+  if (!query || typeof query !== "object") return [];
+  const out = [];
+  const where = query.where;
+  if (where && typeof where === "object" && !Array.isArray(where)) {
+    flattenCondition(where, out);
+  }
+  return out;
+}
+function coerceFilterValueForSql(s) {
+  if (s === "true") return 1;
+  if (s === "false") return 0;
+  if (s === "null") return null;
+  if (/^-?\d+$/.test(s)) {
+    const n = Number(s);
+    if (Number.isFinite(n)) return n;
+  }
+  if (/^-?\d+\.\d+$/.test(s)) {
+    const n = Number(s);
+    if (Number.isFinite(n)) return n;
+  }
+  return s;
+}
+
 // src/strategies/native-sql-strategy.ts
 var NativeSQLStrategy = class {
   constructor() {
@@ -143,30 +229,33 @@ var NativeSQLStrategy = class {
     const params = [];
     const selectClauses = [];
     const groupByClauses = [];
+    const tableName = this.extractObjectName(cube);
+    const joins = /* @__PURE__ */ new Map();
     if (query.dimensions && query.dimensions.length > 0) {
       for (const dim of query.dimensions) {
-        const colExpr = this.resolveDimensionSql(cube, dim);
+        const colExpr = this.resolveDimensionSql(cube, dim, tableName, joins);
         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);
+        const aggExpr = this.resolveMeasureSql(cube, measure, tableName, joins);
         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 normalizedFilters = normalizeAnalyticsFilters(query);
+    if (normalizedFilters.length > 0) {
+      for (const filter of normalizedFilters) {
+        const colExpr = this.resolveFieldSql(cube, filter.member, tableName, joins);
         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);
+        const colExpr = this.resolveFieldSql(cube, td.dimension, tableName, joins);
         if (td.dateRange) {
           const range = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
           if (range.length === 2) {
@@ -176,8 +265,10 @@ var NativeSQLStrategy = class {
         }
       }
     }
-    const tableName = this.extractObjectName(cube);
     let sql = `SELECT ${selectClauses.join(", ")} FROM "${tableName}"`;
+    if (joins.size > 0) {
+      sql += " " + Array.from(joins.values()).join(" ");
+    }
     if (whereClauses.length > 0) {
       sql += ` WHERE ${whereClauses.join(" AND ")}`;
     }
@@ -197,16 +288,77 @@ var NativeSQLStrategy = class {
     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;
+  /**
+   * Resolve a dimension/measure/filter SQL expression that may reference a
+   * related table via dot notation (e.g. `account.industry`).
+   *
+   * When the resolved `sql` contains a dot, treat the prefix as a lookup
+   * field on the cube's table and synthesise a `LEFT JOIN` against the
+   * related table. The convention (matching the auto-cube generator and
+   * ObjectStack object schemas) is:
+   *
+   *   <parentTable>.<lookupField> = <lookupField>.id
+   *
+   * i.e. the lookup field name on the parent table equals the related
+   * table name. This holds for all `Field.lookup({ object: '...' })`
+   * declarations where the field is named after its target object.
+   *
+   * Returns the qualified SQL reference (e.g. `"account"."industry"`).
+   * Pure column references (no dot) are returned as-is.
+   */
+  qualifyAndRegisterJoin(rawSql, parentTable, joins) {
+    if (!rawSql.includes(".")) return rawSql;
+    const [alias, ...rest] = rawSql.split(".");
+    if (!alias || rest.length === 0) return rawSql;
+    const column = rest.join(".");
+    if (!joins.has(alias)) {
+      joins.set(
+        alias,
+        `LEFT JOIN "${alias}" ON "${parentTable}"."${alias}" = "${alias}"."id"`
+      );
+    }
+    return `"${alias}"."${column}"`;
   }
-  resolveMeasureSql(cube, member) {
-    const fieldName = member.includes(".") ? member.split(".")[1] : member;
-    const measure = cube.measures[fieldName];
+  /**
+   * Resolve a member reference (dimension, measure, or filter field) to its
+   * cube definition.
+   *
+   * Accepts three naming conventions:
+   *   1. `<cube>.<field>` — the canonical analytics qualifier (stripped to `<field>`).
+   *   2. `<lookup>.<field>` — a relation traversal (e.g. `account.industry`).
+   *      First tried as the literal key, then as the underscore-flattened
+   *      key (`account_industry`), and finally returned as a synthetic
+   *      definition whose `sql` is the dotted reference so the JOIN
+   *      machinery can pick it up.
+   *   3. `<field>` — a bare field name on the cube's table.
+   */
+  lookupMember(cube, member, kind) {
+    const bag = kind === "dimension" ? cube.dimensions : cube.measures;
+    if (bag[member]) return bag[member];
+    if (member.includes(".")) {
+      const [first, ...rest] = member.split(".");
+      const tail = rest.join(".");
+      if (first === cube.name && bag[tail]) return bag[tail];
+      if (bag[tail]) return bag[tail];
+      const flat = member.replace(/\./g, "_");
+      if (bag[flat]) return bag[flat];
+      if (kind === "dimension") {
+        return { sql: member, type: "string" };
+      }
+    } else if (bag[member]) {
+      return bag[member];
+    }
+    return void 0;
+  }
+  resolveDimensionSql(cube, member, parentTable, joins) {
+    const dim = this.lookupMember(cube, member, "dimension");
+    const raw = dim ? dim.sql : member.includes(".") ? member.split(".")[1] : member;
+    return this.qualifyAndRegisterJoin(raw, parentTable, joins);
+  }
+  resolveMeasureSql(cube, member, parentTable, joins) {
+    const measure = this.lookupMember(cube, member, "measure");
     if (!measure) return `COUNT(*)`;
-    const col = measure.sql;
+    const col = measure.sql === "*" ? "*" : this.qualifyAndRegisterJoin(measure.sql, parentTable, joins);
     switch (measure.type) {
       case "count":
         return "COUNT(*)";
@@ -224,12 +376,12 @@ var NativeSQLStrategy = class {
         return `COUNT(*)`;
     }
   }
-  resolveFieldSql(cube, member) {
+  resolveFieldSql(cube, member, parentTable, joins) {
+    const dim = this.lookupMember(cube, member, "dimension");
+    if (dim) return this.qualifyAndRegisterJoin(dim.sql, parentTable, joins);
+    const measure = this.lookupMember(cube, member, "measure");
+    if (measure) return this.qualifyAndRegisterJoin(measure.sql, parentTable, joins);
     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) {
@@ -248,7 +400,7 @@ var NativeSQLStrategy = class {
     if (operator === "in" || operator === "notIn") {
       if (!values || values.length === 0) return null;
       const placeholders = values.map((v) => {
-        params.push(v);
+        params.push(coerceFilterValueForSql(v));
         return `$${params.length}`;
       }).join(", ");
       return `${col} ${operator === "in" ? "IN" : "NOT IN"} (${placeholders})`;
@@ -258,7 +410,7 @@ var NativeSQLStrategy = class {
     if (operator === "contains" || operator === "notContains") {
       params.push(`%${values[0]}%`);
     } else {
-      params.push(values[0]);
+      params.push(coerceFilterValueForSql(values[0]));
     }
     return `${col} ${sqlOp} $${params.length}`;
   }
@@ -269,8 +421,7 @@ var NativeSQLStrategy = class {
     const fields = [];
     if (query.dimensions) {
       for (const dim of query.dimensions) {
-        const fieldName = dim.includes(".") ? dim.split(".")[1] : dim;
-        const d = cube.dimensions[fieldName];
+        const d = this.lookupMember(cube, dim, "dimension");
         fields.push({ name: dim, type: d?.type || "string" });
       }
     }
@@ -311,8 +462,9 @@ var ObjectQLStrategy = class {
       }
     }
     const filter = {};
-    if (query.filters && query.filters.length > 0) {
-      for (const f of query.filters) {
+    const normalizedFilters = normalizeAnalyticsFilters(query);
+    if (normalizedFilters.length > 0) {
+      for (const f of normalizedFilters) {
         const fieldName = this.resolveFieldName(cube, f.member, "any");
         filter[fieldName] = this.convertFilter(f.operator, f.values);
       }
@@ -369,27 +521,54 @@ var ObjectQLStrategy = class {
     return { sql, params: [] };
   }
   // ── Helpers ──────────────────────────────────────────────────────
+  /**
+   * Resolve a member ref to a `{ sql, type? }` definition.
+   *
+   * Mirrors `NativeSQLStrategy.lookupMember` so the two strategies
+   * accept the same naming conventions:
+   *   1. `<cube>.<field>`           — canonical analytics qualifier.
+   *   2. `<lookup>.<field>`         — relation traversal (e.g. `account.industry`).
+   *      Tries literal key, then underscore-flattened key, then falls
+   *      back to a synthetic dim whose `sql` is the dotted path so the
+   *      ObjectQL aggregate engine can traverse it via the lookup field.
+   *   3. `<field>`                  — bare column on the cube's table.
+   */
+  lookupMember(cube, member, kind) {
+    const bag = kind === "dimension" ? cube.dimensions : cube.measures;
+    if (bag[member]) return bag[member];
+    if (member.includes(".")) {
+      const [first, ...rest] = member.split(".");
+      const tail = rest.join(".");
+      if (first === cube.name && bag[tail]) return bag[tail];
+      if (bag[tail]) return bag[tail];
+      const flat = member.replace(/\./g, "_");
+      if (bag[flat]) return bag[flat];
+      if (kind === "dimension") return { sql: member, type: "string" };
+    } else if (bag[member]) {
+      return bag[member];
+    }
+    return void 0;
+  }
   resolveFieldName(cube, member, kind) {
-    const fieldName = member.includes(".") ? member.split(".")[1] : member;
     if (kind === "dimension" || kind === "any") {
-      const dim = cube.dimensions[fieldName];
+      const dim = this.lookupMember(cube, member, "dimension");
       if (dim) return dim.sql.replace(/^\$/, "");
     }
     if (kind === "measure" || kind === "any") {
-      const measure = cube.measures[fieldName];
+      const measure = this.lookupMember(cube, member, "measure");
       if (measure) return measure.sql.replace(/^\$/, "");
     }
-    return fieldName;
+    return member.includes(".") ? member.split(".")[1] : member;
   }
   resolveMeasureAggregation(cube, measureName) {
-    const fieldName = measureName.includes(".") ? measureName.split(".")[1] : measureName;
-    const direct = cube.measures[fieldName];
+    const direct = this.lookupMember(cube, measureName, "measure");
     if (direct) {
       return {
         field: direct.sql.replace(/^\$/, ""),
         method: direct.type === "count_distinct" ? "count_distinct" : direct.type
       };
     }
+    const fieldName = measureName.includes(".") ? measureName.split(".")[1] : measureName;
     const aggTypes = ["count", "sum", "avg", "min", "max", "count_distinct"];
     for (const type of aggTypes) {
       const suffix = `_${type}`;
@@ -410,27 +589,29 @@ var ObjectQLStrategy = class {
     if (operator === "set") return { $ne: null };
     if (operator === "notSet") return null;
     if (!values || values.length === 0) return void 0;
+    const v0 = coerceFilterValueForSql(values[0]);
+    const all = values.map(coerceFilterValueForSql);
     switch (operator) {
       case "equals":
-        return values[0];
+        return v0;
       case "notEquals":
-        return { $ne: values[0] };
+        return { $ne: v0 };
       case "gt":
-        return { $gt: values[0] };
+        return { $gt: v0 };
       case "gte":
-        return { $gte: values[0] };
+        return { $gte: v0 };
       case "lt":
-        return { $lt: values[0] };
+        return { $lt: v0 };
       case "lte":
-        return { $lte: values[0] };
+        return { $lte: v0 };
       case "contains":
         return { $regex: values[0] };
       case "in":
-        return { $in: values };
+        return { $in: all };
       case "notIn":
-        return { $nin: values };
+        return { $nin: all };
       default:
-        return values[0];
+        return v0;
     }
   }
   extractObjectName(cube) {
@@ -440,8 +621,7 @@ var ObjectQLStrategy = class {
     const fields = [];
     if (query.dimensions) {
       for (const dim of query.dimensions) {
-        const fieldName = dim.includes(".") ? dim.split(".")[1] : dim;
-        const d = cube.dimensions[fieldName];
+        const d = this.lookupMember(cube, dim, "dimension");
         fields.push({ name: dim, type: d?.type || "string" });
       }
     }
@@ -494,11 +674,10 @@ var AnalyticsService = class {
     if (!query.cube) {
       throw new Error("Cube name is required in analytics query");
     }
-    const normalized = this.normalizeQuery(query);
-    this.ensureCube(normalized);
-    const strategy = this.resolveStrategy(normalized);
-    this.logger.debug(`[Analytics] Query on cube "${normalized.cube}" \u2192 ${strategy.name}`);
-    return strategy.execute(normalized, this.strategyCtx);
+    this.ensureCube(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.
@@ -527,49 +706,12 @@ var AnalyticsService = class {
     if (!query.cube) {
       throw new Error("Cube name is required for SQL generation");
     }
-    const normalized = this.normalizeQuery(query);
-    this.ensureCube(normalized);
-    const strategy = this.resolveStrategy(normalized);
-    this.logger.debug(`[Analytics] generateSql on cube "${normalized.cube}" \u2192 ${strategy.name}`);
-    return strategy.generateSql(normalized, this.strategyCtx);
+    this.ensureCube(query);
+    const strategy = this.resolveStrategy(query);
+    this.logger.debug(`[Analytics] generateSql on cube "${query.cube}" \u2192 ${strategy.name}`);
+    return strategy.generateSql(query, this.strategyCtx);
   }
   // ── Internal ─────────────────────────────────────────────────────
-  /**
-   * Normalise a query into a canonical shape that strategies can rely on:
-   *
-   * 1. **Filters as object** — Some clients (e.g. dashboard widget translators)
-   *    send `filters` as a Mongo-style object `{ stage: { $nin: [...] } }`
-   *    instead of the schema's `Array<{ member, operator, values }>`. We
-   *    translate the object form into the array form so existing strategies
-   *    work unchanged.
-   * 2. Other shapes are returned as-is.
-   */
-  normalizeQuery(query) {
-    const filters = query.filters;
-    if (!filters || Array.isArray(filters)) return query;
-    if (typeof filters !== "object") return query;
-    const arr = [];
-    for (const [member, raw] of Object.entries(filters)) {
-      if (raw && typeof raw === "object" && !Array.isArray(raw) && !(raw instanceof Date)) {
-        for (const [op, val] of Object.entries(raw)) {
-          const mapped = mongoOperatorToFilter(op, val);
-          if (!mapped) continue;
-          if (mapped.multi) {
-            arr.push({ member, operator: mapped.operator, values: mapped.values });
-          } else if (mapped.values.length === 0) {
-            arr.push({ member, operator: mapped.operator, values: [] });
-          } else {
-            for (const v of mapped.values) arr.push({ member, operator: mapped.operator, values: [v] });
-          }
-        }
-      } else if (Array.isArray(raw)) {
-        arr.push({ member, operator: "in", values: raw.map(String) });
-      } else {
-        arr.push({ member, operator: "equals", values: [String(raw)] });
-      }
-    }
-    return { ...query, filters: arr };
-  }
   /**
    * Ensure a cube exists for the given query and that it knows about every
    * measure referenced by the query.
@@ -629,10 +771,13 @@ var AnalyticsService = class {
       if (dimensions[key]) continue;
       dimensions[key] = { name: key, label: key, type: "string", sql: key };
     }
-    for (const f of query.filters || []) {
-      const key = stripPrefix(f.member);
-      if (dimensions[key] || measures[key]) continue;
-      dimensions[key] = { name: key, label: key, type: "string", sql: key };
+    if (query.where && typeof query.where === "object" && !Array.isArray(query.where)) {
+      for (const key of Object.keys(query.where)) {
+        if (key.startsWith("$")) continue;
+        const stripped = stripPrefix(key);
+        if (dimensions[stripped] || measures[stripped]) continue;
+        dimensions[stripped] = { name: stripped, label: stripped, type: "string", sql: stripped };
+      }
     }
     for (const td of query.timeDimensions || []) {
       const key = stripPrefix(td.dimension);
@@ -688,33 +833,6 @@ function inferMeasure(key) {
   }
   return { name: key, label: key, type: "sum", sql: key };
 }
-function mongoOperatorToFilter(op, val) {
-  const toStrArr = (v) => v == null ? [] : Array.isArray(v) ? v.map(String) : [String(v)];
-  switch (op) {
-    case "$eq":
-      return { operator: "equals", values: toStrArr(val) };
-    case "$ne":
-      return { operator: "notEquals", values: toStrArr(val) };
-    case "$gt":
-      return { operator: "gt", values: toStrArr(val) };
-    case "$gte":
-      return { operator: "gte", values: toStrArr(val) };
-    case "$lt":
-      return { operator: "lt", values: toStrArr(val) };
-    case "$lte":
-      return { operator: "lte", values: toStrArr(val) };
-    case "$in":
-      return { operator: "in", values: toStrArr(val), multi: true };
-    case "$nin":
-      return { operator: "notIn", values: toStrArr(val), multi: true };
-    case "$regex":
-      return { operator: "contains", values: toStrArr(val) };
-    case "$exists":
-      return val ? { operator: "set", values: [] } : { operator: "notSet", values: [] };
-    default:
-      return null;
-  }
-}
 var FallbackDelegateStrategy = class {
   constructor() {
     this.name = "FallbackDelegateStrategy";
@@ -793,8 +911,36 @@ var AnalyticsServicePlugin = class {
       };
       autoBridged = true;
     }
+    let executeRawSql = this.options.executeRawSql;
+    let autoBridgedRawSql = false;
+    if (!executeRawSql) {
+      const tryGetExecutor = () => {
+        try {
+          const svc = ctx.getService("data");
+          return svc && typeof svc.execute === "function" ? svc : void 0;
+        } catch {
+          return void 0;
+        }
+      };
+      executeRawSql = async (_objectName, sql, params) => {
+        const engine = tryGetExecutor();
+        if (!engine || !engine.execute) {
+          throw new Error(
+            '[Analytics] Cannot execute raw SQL: no IDataEngine ("data") service with execute() is registered.'
+          );
+        }
+        const knexSql = sql.replace(/\$(\d+)/g, "?");
+        const result = await engine.execute(knexSql, { args: params });
+        if (Array.isArray(result)) return result;
+        if (result && typeof result === "object" && "rows" in result) {
+          return result.rows;
+        }
+        return [];
+      };
+      autoBridgedRawSql = true;
+    }
     const queryCapabilities = this.options.queryCapabilities ?? (() => ({
-      nativeSql: !!this.options.executeRawSql,
+      nativeSql: !!executeRawSql,
       objectqlAggregate: !!executeAggregate,
       inMemory: false
     }));
@@ -802,13 +948,16 @@ var AnalyticsServicePlugin = class {
       cubes: this.options.cubes,
       logger: ctx.logger,
       queryCapabilities,
-      executeRawSql: this.options.executeRawSql,
+      executeRawSql,
       executeAggregate,
       fallbackService
     };
     if (autoBridged) {
       ctx.logger.info('[Analytics] Auto-bridged executeAggregate \u2192 "data" service (IDataEngine)');
     }
+    if (autoBridgedRawSql) {
+      ctx.logger.info('[Analytics] Auto-bridged executeRawSql \u2192 "data" service (IDataEngine.execute)');
+    }
     this.service = new AnalyticsService(config);
     if (fallbackService) {
       ctx.replaceService("analytics", this.service);