@objectstack/service-analytics 8.0.1 → 9.0.1

package/dist/index.cjs

@@ -31,6 +31,8 @@ __export(index_exports, {
   compileScopedFilterToSql: () => compileScopedFilterToSql,
   evaluateDerivedMeasures: () => evaluateDerivedMeasures,
   mergeByDimensions: () => mergeByDimensions,
+  pickDisplayField: () => pickDisplayField,
+  resolveDimensionLabels: () => resolveDimensionLabels,
   shiftRange: () => shiftRange
 });
 module.exports = __toCommonJS(index_exports);
@@ -633,12 +635,22 @@ var ObjectQLStrategy = class {
   async execute(query, ctx) {
     const cube = ctx.getCube(query.cube);
     const objectName = this.extractObjectName(cube);
+    const granByDim = /* @__PURE__ */ new Map();
+    for (const td of query.timeDimensions ?? []) {
+      if (td.granularity) granByDim.set(td.dimension, td.granularity);
+    }
     const groupBy = [];
     if (query.dimensions && query.dimensions.length > 0) {
       for (const dim of query.dimensions) {
-        groupBy.push(this.resolveFieldName(cube, dim, "dimension"));
+        const field = this.resolveFieldName(cube, dim, "dimension");
+        const gran = granByDim.get(dim);
+        groupBy.push(gran ? { field, dateGranularity: gran } : field);
+        granByDim.delete(dim);
       }
     }
+    for (const [dim, gran] of granByDim) {
+      groupBy.push({ field: this.resolveFieldName(cube, dim, "dimension"), dateGranularity: gran });
+    }
     const aggregations = [];
     if (query.measures && query.measures.length > 0) {
       for (const measure of query.measures) {
@@ -651,10 +663,16 @@ var ObjectQLStrategy = class {
     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);
+        const converted = this.convertFilter(f.operator, f.values);
+        const existing = filter[fieldName];
+        const mergeable = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+        filter[fieldName] = mergeable(existing) && mergeable(converted) ? { ...existing, ...converted } : converted;
       }
     }
     const rows = await ctx.executeAggregate(objectName, {
+      // Structured groupBy items ({field, dateGranularity}) pass through the
+      // executeAggregate bridge to engine.aggregate, which buckets them. The
+      // contract types groupBy as string[]; the cast carries the richer shape.
       groupBy: groupBy.length > 0 ? groupBy : void 0,
       aggregations: aggregations.length > 0 ? aggregations : void 0,
       filter: Object.keys(filter).length > 0 ? filter : void 0
@@ -1067,7 +1085,17 @@ var DatasetExecutor = class {
       timezone: opts.selection.timezone ?? "UTC"
     };
     if (opts.where) q.where = opts.where;
-    if (opts.selection.timeDimensions) q.timeDimensions = opts.selection.timeDimensions;
+    const selTimeDims = opts.selection.timeDimensions ?? [];
+    const selDims = new Set(selTimeDims.map((t) => t.dimension));
+    const explicitTimeDims = [];
+    for (const name of opts.dimensions) {
+      const cd = compiled.cube.dimensions[name];
+      if (cd?.type === "time" && cd.granularities?.length === 1 && !selDims.has(name)) {
+        explicitTimeDims.push({ dimension: name, granularity: String(cd.granularities[0]) });
+      }
+    }
+    const mergedTimeDims = [...selTimeDims, ...explicitTimeDims];
+    if (mergedTimeDims.length > 0) q.timeDimensions = mergedTimeDims;
     if (opts.selection.order) q.order = opts.selection.order;
     if (opts.selection.limit != null) q.limit = opts.selection.limit;
     if (opts.selection.offset != null) q.offset = opts.selection.offset;
@@ -1122,6 +1150,242 @@ function mergeByDimensions(base, extra, dimensions, valueColumns) {
   return base;
 }
 
+// src/dimension-labels.ts
+var LOOKUP_TYPES = /* @__PURE__ */ new Set(["lookup", "master_detail"]);
+var pad = (n) => String(n).padStart(2, "0");
+function formatDateBucket(value, granularity) {
+  if (value == null || value instanceof Date === false) {
+    if (typeof value !== "number" && typeof value !== "string") return value;
+  }
+  let d;
+  if (value instanceof Date) d = value;
+  else if (typeof value === "number") d = new Date(value);
+  else {
+    const s = String(value).trim();
+    d = /^\d+$/.test(s) ? new Date(Number(s) < 1e12 ? Number(s) * 1e3 : Number(s)) : new Date(s);
+  }
+  if (Number.isNaN(d.getTime())) return value;
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth();
+  switch (granularity) {
+    case "year":
+      return String(y);
+    case "quarter":
+      return `${y}-Q${Math.floor(m / 3) + 1}`;
+    case "month":
+      return `${y}-${pad(m + 1)}`;
+    case "week":
+    case "day":
+    default:
+      return `${y}-${pad(m + 1)}-${pad(d.getUTCDate())}`;
+  }
+}
+async function resolveDimensionLabels(baseObject, dims, rows, deps) {
+  if (!rows.length || !dims.length) return;
+  const fields = deps.getObjectFields(baseObject);
+  if (!fields) return;
+  for (const dim of dims) {
+    const meta = fields[dim.field];
+    if (dim.type === "date" || meta && meta.type === "date") {
+      for (const row of rows) {
+        const formatted = formatDateBucket(row[dim.name], dim.dateGranularity);
+        if (formatted != null) row[dim.name] = formatted;
+      }
+      continue;
+    }
+    if (!meta) continue;
+    if (Array.isArray(meta.options) && meta.options.length > 0) {
+      const labelByValue = /* @__PURE__ */ new Map();
+      for (const opt of meta.options) {
+        if (opt && opt.label != null) labelByValue.set(opt.value, String(opt.label));
+      }
+      if (labelByValue.size === 0) continue;
+      for (const row of rows) {
+        const raw = row[dim.name];
+        const label = labelByValue.get(raw);
+        if (label != null) row[dim.name] = label;
+      }
+      continue;
+    }
+    if (meta.type && LOOKUP_TYPES.has(meta.type) && meta.reference) {
+      const ids = Array.from(
+        new Set(rows.map((r) => r[dim.name]).filter((v) => v != null))
+      );
+      if (ids.length === 0) continue;
+      const labelById = await deps.fetchRecordLabels(meta.reference, ids);
+      if (!labelById || labelById.size === 0) continue;
+      for (const row of rows) {
+        const label = labelById.get(row[dim.name]);
+        if (label != null) row[dim.name] = label;
+      }
+    }
+  }
+}
+function pickDisplayField(fields) {
+  if (!fields) return void 0;
+  for (const preferred of ["name", "title", "label"]) {
+    if (fields[preferred]) return preferred;
+  }
+  for (const [name, meta] of Object.entries(fields)) {
+    if (meta.type === "text" || meta.type === "string") return name;
+  }
+  return void 0;
+}
+
+// src/preview-evaluator.ts
+function compare(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+}
+function matchOp(value, op, expected) {
+  switch (op) {
+    case "$eq":
+      return value === expected || String(value) === String(expected);
+    case "$ne":
+      return !(value === expected || String(value) === String(expected));
+    case "$gt":
+      return value != null && compare(value, expected) > 0;
+    case "$gte":
+      return value != null && compare(value, expected) >= 0;
+    case "$lt":
+      return value != null && compare(value, expected) < 0;
+    case "$lte":
+      return value != null && compare(value, expected) <= 0;
+    case "$in":
+      return Array.isArray(expected) && expected.some((e) => value === e || String(value) === String(e));
+    case "$nin":
+      return Array.isArray(expected) && !expected.some((e) => value === e || String(value) === String(e));
+    case "$contains":
+      return String(value ?? "").toLowerCase().includes(String(expected ?? "").toLowerCase());
+    default:
+      return true;
+  }
+}
+function matchesWhere(row, where) {
+  if (!where) return true;
+  for (const [key, cond] of Object.entries(where)) {
+    if (key === "$and") {
+      if (!cond.every((c) => matchesWhere(row, c))) return false;
+    } else if (key === "$or") {
+      if (!cond.some((c) => matchesWhere(row, c))) return false;
+    } else if (key === "$not") {
+      if (matchesWhere(row, cond)) return false;
+    } else if (cond !== null && typeof cond === "object" && !Array.isArray(cond)) {
+      for (const [op, expected] of Object.entries(cond)) {
+        if (!matchOp(row[key], op, expected)) return false;
+      }
+    } else if (!(row[key] === cond || String(row[key]) === String(cond))) {
+      return false;
+    }
+  }
+  return true;
+}
+function bucketDate(value, granularity) {
+  const d = new Date(String(value));
+  if (Number.isNaN(d.getTime())) return null;
+  const y = d.getUTCFullYear();
+  const m = `${d.getUTCMonth() + 1}`.padStart(2, "0");
+  const day = `${d.getUTCDate()}`.padStart(2, "0");
+  switch (granularity) {
+    case "year":
+      return `${y}`;
+    case "quarter":
+      return `${y}-Q${Math.floor(d.getUTCMonth() / 3) + 1}`;
+    case "month":
+      return `${y}-${m}`;
+    case "week": {
+      const monday = new Date(d);
+      const dow = (d.getUTCDay() + 6) % 7;
+      monday.setUTCDate(d.getUTCDate() - dow);
+      return monday.toISOString().slice(0, 10);
+    }
+    case "day":
+    default:
+      return `${y}-${m}-${day}`;
+  }
+}
+function aggregate(rows, metricType, field) {
+  if (metricType === "count" || field === "*") {
+    if (metricType === "countDistinct") {
+      return new Set(rows.map((r) => r[field]).filter((v) => v != null)).size;
+    }
+    return rows.length;
+  }
+  const nums = rows.map((r) => Number(r[field])).filter((n) => Number.isFinite(n));
+  switch (metricType) {
+    case "countDistinct":
+      return new Set(rows.map((r) => r[field]).filter((v) => v != null)).size;
+    case "sum":
+      return nums.reduce((a, b) => a + b, 0);
+    case "avg":
+      return nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : 0;
+    case "min":
+      return nums.length ? Math.min(...nums) : 0;
+    case "max":
+      return nums.length ? Math.max(...nums) : 0;
+    default:
+      return nums.length ? nums.reduce((a, b) => a + b, 0) : rows.length;
+  }
+}
+function evaluateAnalyticsQueryOverRows(query, cube, rows) {
+  let filtered = rows.filter((r) => matchesWhere(r, query.where));
+  const timeDims = query.timeDimensions ?? [];
+  for (const td of timeDims) {
+    const dim = cube.dimensions?.[td.dimension];
+    const field = String(dim?.sql ?? td.dimension);
+    if (!td.dateRange) continue;
+    const [start, end] = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
+    filtered = filtered.filter((r) => {
+      const v = String(r[field] ?? "");
+      return v >= String(start) && v <= `${end}~`;
+    });
+  }
+  const dimensions = query.dimensions ?? [];
+  const granByDim = new Map(timeDims.filter((t) => t.granularity).map((t) => [t.dimension, t.granularity]));
+  const keyOf = (r) => {
+    const values = {};
+    for (const name of dimensions) {
+      const dim = cube.dimensions?.[name];
+      const field = String(dim?.sql ?? name);
+      const raw = r[field];
+      const gran = granByDim.get(name) ?? (dim?.type === "time" && dim.granularities?.length === 1 ? String(dim.granularities[0]) : void 0);
+      values[name] = gran ? bucketDate(raw, gran) : raw ?? null;
+    }
+    return { key: JSON.stringify(values), values };
+  };
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of filtered) {
+    const { key, values } = keyOf(r);
+    const g = groups.get(key) ?? { values, rows: [] };
+    g.rows.push(r);
+    groups.set(key, g);
+  }
+  if (dimensions.length === 0 && groups.size === 0) {
+    groups.set("{}", { values: {}, rows: [] });
+  }
+  const out = [];
+  for (const g of groups.values()) {
+    const row = { ...g.values };
+    for (const m of query.measures) {
+      const metric = cube.measures?.[m];
+      row[m] = aggregate(g.rows, String(metric?.type ?? "count"), String(metric?.sql ?? "*"));
+    }
+    out.push(row);
+  }
+  for (const [col, dir] of Object.entries(query.order ?? {}).reverse()) {
+    out.sort((a, b) => (dir === "desc" ? -1 : 1) * compare(a[col], b[col]));
+  }
+  const offset = query.offset ?? 0;
+  const limited = out.slice(offset, query.limit != null ? offset + query.limit : void 0);
+  return {
+    rows: limited,
+    fields: [
+      ...dimensions.map((d) => ({ name: d, type: "string" })),
+      ...query.measures.map((m) => ({ name: m, type: "number" }))
+    ]
+  };
+}
+
 // src/analytics-service.ts
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
@@ -1139,6 +1403,8 @@ var AnalyticsService = class {
     }
     this.readScopeProvider = config.getReadScope;
     this.relationshipResolver = config.relationshipResolver;
+    this.labelResolver = config.labelResolver;
+    this.draftRowsResolver = config.draftRowsResolver;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -1232,6 +1498,14 @@ var AnalyticsService = class {
   }
   /**
    * Execute an analytical query by delegating to the first capable strategy.
+   *
+   * A strategy can discover only AT EXECUTION TIME that the underlying driver
+   * cannot serve it — the canonical case is NativeSQLStrategy on an in-memory
+   * driver, whose `execute()` returns null for raw SQL (the auto-bridge throws
+   * `RAW_SQL_UNSUPPORTED`). That is a capability miss, not a query error: fall
+   * back to the next capable strategy (e.g. ObjectQLStrategy over the
+   * aggregate bridge) instead of failing — or worse, fabricating empty rows.
+   * Any other error propagates untouched.
    */
   async query(query, context) {
     if (!query.cube) {
@@ -1239,9 +1513,23 @@ var AnalyticsService = class {
     }
     this.ensureCube(query);
     const ctx = await this.callCtx(query, context);
-    const strategy = this.resolveStrategy(query, ctx);
-    this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
-    return strategy.execute(query, ctx);
+    let skip;
+    for (; ; ) {
+      const strategy = this.resolveStrategy(query, ctx, skip);
+      this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
+      try {
+        return await strategy.execute(query, ctx);
+      } catch (e) {
+        if (e?.code === "RAW_SQL_UNSUPPORTED") {
+          this.logger.warn(
+            `[Analytics] ${strategy.name} cannot run on this driver (raw SQL unsupported) \u2014 falling back to the next strategy.`
+          );
+          (skip ?? (skip = /* @__PURE__ */ new Set())).add(strategy);
+          continue;
+        }
+        throw e;
+      }
+    }
   }
   /**
    * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
@@ -1260,10 +1548,46 @@ var AnalyticsService = class {
    * runs the selection through the `DatasetExecutor` with the request context so
    * tenant/RLS scoping (D-C) is applied. See {@link IAnalyticsService.queryDataset}.
    */
-  async queryDataset(dataset, selection, context) {
+  async queryDataset(dataset, selection, context, options) {
     const compiled = this.registerDataset(dataset);
     this.logger.debug(`[Analytics] queryDataset "${dataset.name}" (object=${dataset.object}, include=${(dataset.include ?? []).join(",") || "\u2014"})`);
-    return new DatasetExecutor(this).execute(compiled, selection, context);
+    if (options?.previewDrafts && this.draftRowsResolver) {
+      let seedRows = null;
+      try {
+        seedRows = await this.draftRowsResolver(dataset.object, context);
+      } catch (e) {
+        this.logger.warn(`[Analytics] draft preview resolver failed for "${dataset.object}" \u2014 falling back to live data: ${String(e?.message ?? e)}`);
+      }
+      if (seedRows) {
+        this.logger.debug(`[Analytics] queryDataset "${dataset.name}" \u2192 preview over ${seedRows.length} drafted seed row(s)`);
+        const previewService = {
+          query: async (q) => evaluateAnalyticsQueryOverRows(q, compiled.cube, seedRows)
+        };
+        const previewResult = await new DatasetExecutor(previewService).execute(compiled, selection, context);
+        return previewResult;
+      }
+    }
+    const result = await new DatasetExecutor(this).execute(compiled, selection, context);
+    if (this.labelResolver && selection.dimensions?.length) {
+      const dims = selection.dimensions.map((name) => dataset.dimensions?.find((d) => d.name === name)).filter((d) => !!d?.field).map((d) => ({ name: d.name, field: d.field, type: d.type, dateGranularity: d.dateGranularity }));
+      if (dims.length) {
+        try {
+          await resolveDimensionLabels(dataset.object, dims, result.rows, this.labelResolver);
+        } catch (e) {
+          this.logger?.warn?.(`[Analytics] dimension label resolution failed for "${dataset.name}": ${String(e?.message ?? e)}`);
+        }
+      }
+    }
+    if (result.fields?.length && dataset.measures?.length) {
+      const measureByName = new Map(dataset.measures.map((m) => [m.name, m]));
+      for (const f of result.fields) {
+        const m = measureByName.get(f.name) ?? measureByName.get(f.name.replace(/__compare$/, ""));
+        if (!m) continue;
+        if (f.label == null && typeof m.label === "string") f.label = m.label;
+        if (f.format == null && m.format) f.format = m.format;
+      }
+    }
+    return result;
   }
   /**
    * Get cube metadata for discovery.
@@ -1387,16 +1711,19 @@ var AnalyticsService = class {
     };
   }
   /**
-   * Walk the strategy chain and return the first strategy that can handle the query.
+   * Walk the strategy chain and return the first strategy that can handle the
+   * query. `skip` excludes strategies that already proved incapable at
+   * execution time (see {@link query}'s RAW_SQL_UNSUPPORTED fallback).
    */
-  resolveStrategy(query, ctx) {
+  resolveStrategy(query, ctx, skip) {
     for (const strategy of this.strategies) {
+      if (skip?.has(strategy)) continue;
       if (strategy.canHandle(query, ctx)) {
         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.`
+      `[Analytics] No strategy can handle query for cube "${query.cube}". Checked: ${this.strategies.map((s) => s.name).join(", ")}${skip?.size ? ` (skipped at runtime: ${[...skip].map((s) => s.name).join(", ")})` : ""}. Ensure a compatible driver is configured or a fallback service is registered.`
     );
   }
 };
@@ -1518,8 +1845,15 @@ var AnalyticsServicePlugin = class {
         }
         const knexSql = sql.replace(/\$(\d+)/g, "?");
         const result = await engine.execute(knexSql, { args: params });
+        if (result === null || result === void 0) {
+          const err = new Error(
+            `[Analytics] The "data" engine's driver returned null for raw SQL \u2014 this driver does not support SQL execution. The query will fall back to an aggregate-based strategy when one is available.`
+          );
+          err.code = "RAW_SQL_UNSUPPORTED";
+          throw err;
+        }
         if (Array.isArray(result)) return result;
-        if (result && typeof result === "object" && "rows" in result) {
+        if (typeof result === "object" && "rows" in result) {
           return result.rows;
         }
         return [];
@@ -1563,6 +1897,56 @@ var AnalyticsServicePlugin = class {
       }
       return engine ? void 0 : relationshipName;
     };
+    const dataEngine = () => {
+      try {
+        const svc = ctx.getService("data");
+        return svc && typeof svc.getObject === "function" ? svc : void 0;
+      } catch {
+        return void 0;
+      }
+    };
+    const labelResolver = {
+      getObjectFields: (objectName) => dataEngine()?.getObject?.(objectName)?.fields,
+      fetchRecordLabels: async (targetObject, ids) => {
+        const map = /* @__PURE__ */ new Map();
+        const displayField = pickDisplayField(dataEngine()?.getObject?.(targetObject)?.fields);
+        if (!displayField || !executeAggregate || ids.length === 0) return map;
+        const rows = await executeAggregate(targetObject, {
+          groupBy: ["id", displayField],
+          aggregations: [{ field: "id", method: "count", alias: "_c" }],
+          filter: { id: { $in: ids } }
+        });
+        for (const r of rows) {
+          if (r.id != null && r[displayField] != null) map.set(r.id, String(r[displayField]));
+        }
+        return map;
+      }
+    };
+    const draftRowsResolver = async (objectName) => {
+      let protocol;
+      try {
+        protocol = ctx.getService("protocol");
+      } catch {
+        return null;
+      }
+      if (!protocol?.getMetaItems || !protocol.getMetaItem) return null;
+      const res = await protocol.getMetaItems({ type: "seed", previewDrafts: true }).catch(() => null);
+      const list = Array.isArray(res) ? res : res && typeof res === "object" && Array.isArray(res.items) ? res.items : [];
+      const rows = [];
+      let pending = false;
+      for (const entry of list) {
+        const body = entry?.item ?? entry;
+        if (!body?.name || body.object !== objectName) continue;
+        const draft = await protocol.getMetaItem({ type: "seed", name: body.name, state: "draft" }).catch(() => null);
+        const draftBody = draft?.item;
+        if (!draftBody) continue;
+        pending = true;
+        for (const r of Array.isArray(draftBody.records) ? draftBody.records : []) {
+          if (r && typeof r === "object") rows.push(r);
+        }
+      }
+      return pending ? rows : null;
+    };
     const config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
@@ -1572,7 +1956,9 @@ var AnalyticsServicePlugin = class {
       fallbackService,
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
-      relationshipResolver
+      relationshipResolver,
+      labelResolver,
+      draftRowsResolver
     };
     if (autoBridgedReadScope) {
       ctx.logger.info('[Analytics] Auto-bridged getReadScope \u2192 "security" service (getReadFilter)');
@@ -1624,6 +2010,8 @@ var AnalyticsServicePlugin = class {
   compileScopedFilterToSql,
   evaluateDerivedMeasures,
   mergeByDimensions,
+  pickDisplayField,
+  resolveDimensionLabels,
   shiftRange
 });
 //# sourceMappingURL=index.cjs.map