@objectstack/service-analytics 8.0.0 → 9.0.0

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,88 @@ 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/analytics-service.ts
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
@@ -1139,6 +1249,7 @@ var AnalyticsService = class {
     }
     this.readScopeProvider = config.getReadScope;
     this.relationshipResolver = config.relationshipResolver;
+    this.labelResolver = config.labelResolver;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -1176,13 +1287,60 @@ var AnalyticsService = class {
    * current request's ExecutionContext (ADR-0021 D-C). The strategy then sees a
    * `getReadScope(objectName)` that already knows the active tenant.
    */
-  callCtx(context) {
+  async callCtx(query, context) {
     if (!this.readScopeProvider) return this.baseCtx;
+    const scopes = await this.resolveReadScopes(query, context);
     return {
       ...this.baseCtx,
-      getReadScope: (objectName) => this.readScopeProvider(objectName, context)
+      getReadScope: (objectName) => scopes.get(objectName) ?? null
     };
   }
+  /**
+   * Resolve the read scope (tenant + RLS `FilterCondition`) for the base object
+   * AND every joined object of the query's cube, keyed by object name. This is
+   * the async pre-pass that lets the synchronous strategy enforce scoping even
+   * when the provider (security `getReadFilter`) resolves asynchronously.
+   *
+   * The object set is `cube.sql` (base) plus every `cube.joins[*].name` — a
+   * SUPERSET of what the strategy actually scans (the strategy only joins along
+   * declared relationships), so no scanned object is ever left unscoped.
+   *
+   * Fail-closed: if the provider throws for an object, the whole query is
+   * rejected rather than emitting SQL with that object unscoped.
+   */
+  async resolveReadScopes(query, context) {
+    const map = /* @__PURE__ */ new Map();
+    const provider = this.readScopeProvider;
+    if (!provider || !query.cube) return map;
+    const cube = this.cubeRegistry.get(query.cube);
+    if (!cube) return map;
+    const objects = /* @__PURE__ */ new Set();
+    if (typeof cube.sql === "string" && cube.sql.trim()) {
+      objects.add(cube.sql.trim());
+    }
+    const joins = cube.joins;
+    if (joins) {
+      for (const [alias, j] of Object.entries(joins)) {
+        objects.add(j?.name ?? alias);
+      }
+    }
+    for (const object of objects) {
+      let filter;
+      try {
+        filter = await provider(object, context);
+      } catch (e) {
+        this.logger.error?.(
+          `[Analytics] read-scope resolution failed for object "${object}" \u2014 rejecting query (fail-closed, ADR-0021 D-C)`,
+          e instanceof Error ? e : new Error(String(e))
+        );
+        throw new Error(
+          `[Analytics] read-scope resolution failed for "${object}"; query denied (fail-closed).`
+        );
+      }
+      if (filter != null) map.set(object, filter);
+    }
+    return map;
+  }
   /**
    * Execute an analytical query by delegating to the first capable strategy.
    */
@@ -1191,7 +1349,7 @@ var AnalyticsService = class {
       throw new Error("Cube name is required in analytics query");
     }
     this.ensureCube(query);
-    const ctx = this.callCtx(context);
+    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);
@@ -1216,7 +1374,27 @@ var AnalyticsService = class {
   async queryDataset(dataset, selection, context) {
     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);
+    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.
@@ -1246,7 +1424,7 @@ var AnalyticsService = class {
       throw new Error("Cube name is required for SQL generation");
     }
     this.ensureCube(query);
-    const ctx = this.callCtx(context);
+    const ctx = await this.callCtx(query, context);
     const strategy = this.resolveStrategy(query, ctx);
     this.logger.debug(`[Analytics] generateSql on cube "${query.cube}" \u2192 ${strategy.name}`);
     return strategy.generateSql(query, ctx);
@@ -1516,6 +1694,31 @@ 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 config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
@@ -1525,7 +1728,8 @@ var AnalyticsServicePlugin = class {
       fallbackService,
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
-      relationshipResolver
+      relationshipResolver,
+      labelResolver
     };
     if (autoBridgedReadScope) {
       ctx.logger.info('[Analytics] Auto-bridged getReadScope \u2192 "security" service (getReadFilter)');
@@ -1577,6 +1781,8 @@ var AnalyticsServicePlugin = class {
   compileScopedFilterToSql,
   evaluateDerivedMeasures,
   mergeByDimensions,
+  pickDisplayField,
+  resolveDimensionLabels,
   shiftRange
 });
 //# sourceMappingURL=index.cjs.map