@objectstack/service-analytics 17.0.0-rc.1 → 17.0.0-rc.2

package/dist/index.js

@@ -1,4 +1,5 @@
 // src/analytics-service.ts
+import { percentScaleOf } from "@objectstack/spec/data";
 import { createLogger, bucketKeyToCalendarRange, zonedDateStartToUtcMs } from "@objectstack/core";
 
 // src/cube-registry.ts
@@ -1708,6 +1709,7 @@ function compileDataset(dataset, resolver) {
 }
 
 // src/dataset-executor.ts
+import { emptyGroupValueFor } from "@objectstack/spec/data";
 import { filterTokenContextFrom, resolveFilterTokens } from "@objectstack/core";
 function resolveSelectionTokens(compiled, selection, context) {
   const tokenCtx = filterTokenContextFrom(context, /* @__PURE__ */ new Date());
@@ -1729,6 +1731,12 @@ function combineFilters(a, b) {
   if (a && b) return { $and: [a, b] };
   return a ?? b;
 }
+function splitMeasuresByFilter(measures, measureFilters) {
+  const unfiltered = [];
+  const filtered = [];
+  for (const m of measures) (measureFilters[m] ? filtered : unfiltered).push(m);
+  return { unfiltered, filtered };
+}
 function evaluateDerivedMeasures(rows, derived) {
   if (derived.length === 0) return rows;
   return rows.map((row) => {
@@ -1739,6 +1747,14 @@ function evaluateDerivedMeasures(rows, derived) {
     return out;
   });
 }
+function fillEmptyGroups(rows, columnAggregates) {
+  for (const [column, aggregate2] of Object.entries(columnAggregates)) {
+    const empty = emptyGroupValueFor(aggregate2);
+    if (empty === void 0) continue;
+    for (const row of rows) if (row[column] == null) row[column] = empty;
+  }
+  return rows;
+}
 function num(v) {
   if (v == null) return null;
   const n = typeof v === "number" ? v : Number(v);
@@ -1917,11 +1933,7 @@ var DatasetExecutor = class {
     for (const d of selectedDerived) {
       for (const dep of d.of) baseMeasures.add(dep);
     }
-    const unfiltered = [];
-    const filtered = [];
-    for (const m of baseMeasures) {
-      (compiled.measureFilters[m] ? filtered : unfiltered).push(m);
-    }
+    const { unfiltered, filtered } = splitMeasuresByFilter(baseMeasures, compiled.measureFilters);
     const baseFilter = combineFilters(compiled.filter, selection.runtimeFilter);
     const dimensions = selection.dimensions ?? [];
     const order = resolveOrdering(selection, dimensions, this.timeDimensionsOf(compiled, dimensions));
@@ -1932,6 +1944,76 @@ var DatasetExecutor = class {
     const pushDownKeys = /* @__PURE__ */ new Set([...dimensions, ...unfiltered]);
     const canPushDownWindow = singleQuery && labelOrderKeys.length === 0 && Object.keys(order ?? {}).every((k) => pushDownKeys.has(k));
     const windowQuery = canPushDownWindow ? { order, limit: selection.limit, offset: selection.offset } : void 0;
+    const result = await this.runMeasurePass(compiled, selection, {
+      measures: [...baseMeasures],
+      dimensions,
+      baseFilter,
+      window: windowQuery,
+      context
+    });
+    if (selection.compareTo) {
+      const compareRows = await this.runCompare(compiled, selection, [...baseMeasures], dimensions, baseFilter, context);
+      result.rows = mergeByDimensions(
+        result.rows,
+        compareRows,
+        dimensions,
+        [...baseMeasures].map((m) => `${m}__compare`)
+      );
+      for (const m of baseMeasures) result.fields.push({ name: `${m}__compare`, type: "number" });
+    }
+    const fillColumns = {};
+    for (const m of baseMeasures) {
+      const aggregate2 = compiled.cube.measures?.[m]?.type;
+      fillColumns[m] = aggregate2;
+      if (selection.compareTo) fillColumns[`${m}__compare`] = aggregate2;
+    }
+    fillEmptyGroups(result.rows, fillColumns);
+    result.rows = evaluateDerivedMeasures(result.rows, selectedDerived);
+    for (const d of selectedDerived) result.fields.push({ name: d.name, type: "number" });
+    let sortKeys;
+    for (const key of labelOrderKeys) {
+      const values = [...new Set(result.rows.map((r) => r[key]).filter((v) => v != null))];
+      if (values.length === 0) continue;
+      const labels = await this.orderLabels.resolveLabels(key, values);
+      if (labels && labels.size > 0) (sortKeys ?? (sortKeys = {}))[key] = labels;
+    }
+    result.rows = applyOrdering(result.rows, order, sortKeys);
+    result.rows = applyWindow(result.rows, selection.limit, selection.offset);
+    return result;
+  }
+  /**
+   * Run ONE grouped pass over a set of base measures, honouring each measure's
+   * own scoped `filter`: the unfiltered measures in a single query, plus one
+   * supplementary query per filter-scoped measure, merged back by dimension key.
+   *
+   * **This is the executor's only implementation of "how a measure filter is
+   * applied", and every window goes through it** — the current period, each
+   * `totals` subset (which re-enters via `executeSelection`), and the
+   * `compareTo` window. Before #4820 the comparison window had its own,
+   * simpler answer: one shifted query over all base measures with only the
+   * base filter, so `compiled.measureFilters` was never read on that path.
+   * `won_count` counted won deals and `won_count__compare` counted every deal,
+   * under one label, in adjacent columns. Only measures carrying a filter were
+   * wrong — which is what made it survive: the unfiltered ones next to them
+   * compared correctly.
+   *
+   * The caller supplies the `selection` this pass queries under, which is how
+   * the comparison window differs at all: same measures, same dimensions, same
+   * filters — a `timeDimensions` shifted by {@link shiftRange}. Nothing else
+   * about the two passes may drift, because anything that does becomes a
+   * discrepancy between two columns the reader is invited to subtract.
+   *
+   * Cost: one extra query per filter-scoped measure when `compareTo` is set.
+   * The alternative — declaring the discrepancy in the response — is not one,
+   * since the two columns exist to be directly comparable.
+   *
+   * @param window - Ordering/window to push into the SQL. Only ever set for a
+   *   selection the caller proved is a single self-sufficient query; a pass
+   *   that fans out must return its whole grid for the merge.
+   */
+  async runMeasurePass(compiled, selection, opts) {
+    const { measures, dimensions, baseFilter, window, context } = opts;
+    const { unfiltered, filtered } = splitMeasuresByFilter(measures, compiled.measureFilters);
     let result;
     if (unfiltered.length > 0 || filtered.length === 0) {
       result = await this.service.query(this.buildQuery(compiled, {
@@ -1940,7 +2022,7 @@ var DatasetExecutor = class {
         where: baseFilter,
         selection,
         contextTimezone: context?.timezone,
-        window: windowQuery
+        window
       }), context);
     } else {
       result = { rows: [], fields: [] };
@@ -1957,27 +2039,6 @@ var DatasetExecutor = class {
       result.rows = mergeByDimensions(result.rows, sub.rows, dimensions, [m]);
       result.fields.push({ name: m, type: "number" });
     }
-    if (selection.compareTo) {
-      const compareRows = await this.runCompare(compiled, selection, [...baseMeasures], dimensions, baseFilter, context);
-      result.rows = mergeByDimensions(
-        result.rows,
-        compareRows,
-        dimensions,
-        [...baseMeasures].map((m) => `${m}__compare`)
-      );
-      for (const m of baseMeasures) result.fields.push({ name: `${m}__compare`, type: "number" });
-    }
-    result.rows = evaluateDerivedMeasures(result.rows, selectedDerived);
-    for (const d of selectedDerived) result.fields.push({ name: d.name, type: "number" });
-    let sortKeys;
-    for (const key of labelOrderKeys) {
-      const values = [...new Set(result.rows.map((r) => r[key]).filter((v) => v != null))];
-      if (values.length === 0) continue;
-      const labels = await this.orderLabels.resolveLabels(key, values);
-      if (labels && labels.size > 0) (sortKeys ?? (sortKeys = {}))[key] = labels;
-    }
-    result.rows = applyOrdering(result.rows, order, sortKeys);
-    result.rows = applyWindow(result.rows, selection.limit, selection.offset);
     return result;
   }
   /**
@@ -2042,13 +2103,11 @@ var DatasetExecutor = class {
     const shiftedTd = (selection.timeDimensions ?? []).map(
       (t) => t.dimension === cmp.dimension ? { ...t, dateRange: shifted } : t
     );
-    const sub = await this.service.query(this.buildQuery(compiled, {
-      measures,
-      dimensions,
-      where: baseFilter,
-      selection: { ...selection, timeDimensions: shiftedTd },
-      contextTimezone: context?.timezone
-    }), context);
+    const sub = await this.runMeasurePass(
+      compiled,
+      { ...selection, timeDimensions: shiftedTd },
+      { measures, dimensions, baseFilter, context }
+    );
     return sub.rows.map((row) => {
       const out = {};
       for (const dim of dimensions) out[dim] = row[dim];
@@ -2418,6 +2477,7 @@ function isMissingSourceError(err) {
   msg.includes("not registered") || // framework: object not in registry
   msg.includes("unknown object") || msg.includes("is not a registered object");
 }
+var BARE_IDENTIFIER = /^[a-z_][a-z0-9_]*$/i;
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
   objectqlAggregate: false,
@@ -2436,10 +2496,11 @@ var AnalyticsService = class {
     }
     this.readScopeProvider = config.getReadScope;
     this.relationshipResolver = config.relationshipResolver;
-    this.measureCurrency = config.measureCurrency;
+    this.sourceFieldMeta = config.sourceFieldMeta;
     this.labelResolver = config.labelResolver;
     this.draftRowsResolver = config.draftRowsResolver;
     this.isRegisteredObject = config.isRegisteredObject;
+    this.getObjectFieldNames = config.getObjectFieldNames;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -2657,7 +2718,7 @@ var AnalyticsService = class {
       if (!d.field || d.type !== "date") continue;
       const granularity = resolveDimensionGranularity(selection, d.name, d.dateGranularity);
       if (!granularity) continue;
-      const ftype = this.measureCurrency?.(dataset.object, d.field)?.type;
+      const ftype = this.sourceFieldMeta?.(dataset.object, d.field)?.type;
       if (ftype === "datetime") rangeDims.push({ d, granularity, instant: true });
       else if (ftype === "date") rangeDims.push({ d, granularity, instant: false });
       else if (rangeTz === "UTC") rangeDims.push({ d, granularity, instant: false });
@@ -2706,14 +2767,17 @@ var AnalyticsService = class {
         if (f.format == null && m.format) f.format = m.format;
         const fc = f;
         const mc = m;
+        const meta = m.field ? this.sourceFieldMeta?.(dataset.object, m.field) : void 0;
         if (fc.currency == null) {
-          const meta = m.field ? this.measureCurrency?.(dataset.object, m.field) : void 0;
           const monetary = !!mc.currency || meta?.type === "currency";
           if (monetary) {
             const resolved = mc.currency ?? meta?.defaultCurrency ?? context?.currency;
             if (resolved) fc.currency = resolved;
           }
         }
+        if (f.percentScale == null) {
+          f.percentScale = m.derived?.op === "ratio" ? "fraction" : percentScaleOf(meta);
+        }
       }
     }
     if (result.fields?.length && selectedDims.length) {
@@ -2779,6 +2843,7 @@ var AnalyticsService = class {
     if (!cube) {
       this.assertInferableCube(name);
       cube = this.inferCubeFromQuery(query);
+      this.assertMeasureFields(query, cube, Object.keys(cube.measures));
       this.cubeRegistry.register(cube);
       const isScalarMetric = (query.dimensions?.length ?? 0) === 0 && (query.timeDimensions?.length ?? 0) === 0;
       const message = `[Analytics] No cube registered for "${name}"; auto-inferred a minimal cube (sql="${name}", measures=${Object.keys(cube.measures).join(",") || "(none)"}, dimensions=${Object.keys(cube.dimensions).join(",") || "(none)"}). Define an explicit Cube in your stack for full control.`;
@@ -2798,10 +2863,82 @@ var AnalyticsService = class {
         ...cube,
         measures: { ...cube.measures, ...extraMeasures }
       };
+      this.assertMeasureFields(query, augmented, Object.keys(cube.measures));
       this.cubeRegistry.register(augmented);
       this.logger.debug(
         `[Analytics] Augmented cube "${name}" with inferred measures: ${Object.keys(extraMeasures).join(",")}`
       );
+    } else {
+      this.assertMeasureFields(query, cube, Object.keys(cube.measures));
+    }
+  }
+  /**
+   * [#4437] Reject a measure whose SOURCE FIELD the backing object does not
+   * have, BEFORE the strategy compiles it into SQL.
+   *
+   * `inferMeasure` maps a suffix convention onto a field name and has no way to
+   * know whether that field exists: `ghost_sum` happily became `SUM(ghost)`, the
+   * driver threw `no such column`, and the caller got
+   * `500 {"code":"SQLITE_ERROR","message":"Internal server error"}` — a driver
+   * error class on the wire, and nothing actionable, for what is a plain typo.
+   * The DATA route has refused the same mistake with a `400 INVALID_FIELD`
+   * naming the field since #4315/#4254; this is the analytics half of that
+   * answer, and it is deliberately the SAME envelope (`code`/`field`/`object`/
+   * `param`) so one mistake has one shape across both routes.
+   *
+   * What it checks, and what it deliberately does not:
+   *
+   * - Only when the cube's `sql` is a bare OBJECT NAME. An authored cube whose
+   *   `sql` is a real SQL expression has no field list to check against.
+   * - Only when {@link AnalyticsServiceConfig.getObjectFieldNames} answers.
+   *   Absent hook / unknown object → stand down (see the config field's doc).
+   * - Only measures whose source is a BARE COLUMN. `count(*)` has no source
+   *   field, and a dotted reference (`account.industry`) resolves through a
+   *   join whose target this check cannot see — both pass through untouched.
+   * - `id` / `created_at` / `updated_at` are admitted unconditionally, matching
+   *   the data path's `resolveQueryFields`: they are engine-assigned rather than
+   *   declared, and a gate stricter than the engine it guards would reject
+   *   queries that used to work.
+   */
+  assertMeasureFields(query, cube, declaredMeasures) {
+    const probe = this.getObjectFieldNames;
+    if (!probe) return;
+    const measures = query.measures ?? [];
+    if (measures.length === 0) return;
+    const object = typeof cube.sql === "string" ? cube.sql.trim() : "";
+    if (!object || !BARE_IDENTIFIER.test(object)) return;
+    const fieldNames = probe(object);
+    if (!fieldNames || fieldNames.length === 0) return;
+    const known = /* @__PURE__ */ new Set([...fieldNames, "id", "created_at", "updated_at"]);
+    const stripPrefix = (m) => m.includes(".") ? m.split(".").slice(1).join(".") : m;
+    const sourceFieldOf = (measure) => {
+      const metric = cube.measures[stripPrefix(measure)];
+      if (!metric) return null;
+      if (metric.type === "count" && (metric.sql === "*" || metric.sql == null)) return null;
+      const source = typeof metric.sql === "string" ? metric.sql.trim() : "";
+      if (!source || source === "*" || !BARE_IDENTIFIER.test(source)) return null;
+      return source;
+    };
+    const invalid = /* @__PURE__ */ new Set();
+    for (const measure of measures) {
+      const source = sourceFieldOf(measure);
+      if (source && !known.has(source)) invalid.add(stripPrefix(measure));
+    }
+    if (invalid.size === 0) return;
+    const usable = declaredMeasures.filter((m) => !invalid.has(m));
+    for (const measure of measures) {
+      const source = sourceFieldOf(measure);
+      if (!source || known.has(source)) continue;
+      const err = new Error(
+        `Measure '${measure}' on cube '${cube.name}' aggregates field '${source}', which object '${object}' does not have. Valid measures: ${usable.join(", ") || "(none)"}. Other measures are inferred from the object's OWN fields as '<field>_sum' / '_avg' / '_min' / '_max' / '_count_distinct', so check the spelling of '${source}' \u2014 known fields: ${[...fieldNames].sort().join(", ")}.`
+      );
+      err.code = "INVALID_FIELD";
+      err.status = 400;
+      err.field = source;
+      err.object = object;
+      err.param = "measures";
+      err.measure = measure;
+      throw err;
     }
   }
   /**
@@ -2955,6 +3092,14 @@ var AnalyticsServicePlugin = class {
     this.version = "1.0.0";
     this.type = "standard";
     this.dependencies = [];
+    /**
+     * init() probes the `data` engine ObjectQLPlugin provides for the
+     * auto-bridge — order-if-present so the probe verdict is deterministic
+     * (ADR-0116, #4471). Soft, not hard: without an engine the plugin
+     * degrades on purpose (per-query lazy resolution / explicit
+     * `executeAggregate`).
+     */
+    this.optionalDependencies = ["com.objectstack.engine.objectql"];
     this.options = options;
   }
   async init(ctx) {
@@ -3178,10 +3323,12 @@ var AnalyticsServicePlugin = class {
       coerceTemporalFilterColumn,
       relationshipResolver,
       labelResolver,
-      // ADR-0053 — source-field currency metadata for the measure currency chain.
-      measureCurrency: (object, field) => {
+      // Source-field metadata behind the display chains on result columns:
+      // ADR-0053 currency (`currencyConfig.defaultCurrency`) and percent scale
+      // (`max`, which is what marks whole-percent storage — objectui#3136).
+      sourceFieldMeta: (object, field) => {
         const f = dataEngine()?.getObject?.(object)?.fields?.[field];
-        return f ? { type: f.type, defaultCurrency: f.currencyConfig?.defaultCurrency } : void 0;
+        return f ? { type: f.type, max: f.max, defaultCurrency: f.currencyConfig?.defaultCurrency } : void 0;
       },
       // ADR-0062 D6 — a federated object carries an `external` block (ADR-0015).
       // Reported so NativeSQLStrategy declines it (its hand-compiled FROM would
@@ -3204,6 +3351,18 @@ var AnalyticsServicePlugin = class {
         if (!engine) return true;
         return engine.getObject?.(name) != null;
       },
+      // [#4437] Field names for the measure source-field gate. Read from the
+      // SAME schema registry `isRegisteredObject` above consults (and the data
+      // path's #4315 gate reads), so "which fields exist" has one answer across
+      // /data and /analytics. `undefined` — no engine, unknown object, or an
+      // object with no field map (an external datasource whose columns are not
+      // mirrored locally) — means "cannot answer", and the gate stands down.
+      getObjectFieldNames: (objectName) => {
+        const fields = dataEngine()?.getObject?.(objectName)?.fields;
+        if (!fields || typeof fields !== "object") return void 0;
+        const names = Object.keys(fields);
+        return names.length > 0 ? names : void 0;
+      },
       draftRowsResolver
     };
     if (autoBridgedReadScope && securityPresentAtInit) {
@@ -3259,6 +3418,7 @@ export {
   compileScopedFilterToSql,
   createOrderLabelResolver,
   evaluateDerivedMeasures,
+  fillEmptyGroups,
   mergeByDimensions,
   pickDisplayField,
   resolveDimensionLabels,