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

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { IAnalyticsService, Logger, DriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, DatasetSelection, CubeMeta, DatasetCompareTo, StrategyContext } from '@objectstack/spec/contracts';
-export { AnalyticsStrategy, DatasetSelection, DriverCapabilities, StrategyContext } from '@objectstack/spec/contracts';
+import { IAnalyticsService, Logger, AnalyticsDriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, DatasetSelection, CubeMeta, DatasetCompareTo, StrategyContext } from '@objectstack/spec/contracts';
+export { AnalyticsDriverCapabilities, AnalyticsStrategy, DatasetSelection, StrategyContext } from '@objectstack/spec/contracts';
 import { Cube, FilterCondition } from '@objectstack/spec/data';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 import { Dataset } from '@objectstack/spec/ui';
@@ -268,7 +268,7 @@ interface AnalyticsServiceConfig {
      * Probe driver capabilities for the object that backs a cube.
      * The service calls this function to decide which strategy can handle a query.
      */
-    queryCapabilities?: (cubeName: string) => DriverCapabilities;
+    queryCapabilities?: (cubeName: string) => AnalyticsDriverCapabilities;
     /**
      * Execute raw SQL on the driver for a given object.
      * Required for NativeSQLStrategy.
@@ -336,6 +336,14 @@ interface AnalyticsServiceConfig {
      * `StrategyContext.coerceTemporalFilterValue` for the full rationale.
      */
     coerceTemporalFilterValue?: (objectName: string, fieldName: string, value: unknown) => unknown;
+    /**
+     * Normalise the COLUMN side of the same comparison to that storage form — the
+     * other half of the fix, needed because a SQLite `Field.datetime` holds both an
+     * INTEGER epoch (a `Date` write) and ISO TEXT (a REST/JSON write, a `NOW()`
+     * default) at once, so coercing only the comparand matches one of them and
+     * misses the other (#3912). See `StrategyContext.coerceTemporalFilterColumn`.
+     */
+    coerceTemporalFilterColumn?: (objectName: string, fieldName: string, columnSql: string) => string;
     /**
      * ADR-0062 D6 — report whether an object is federated (external datasource).
      * Threaded into the StrategyContext so `NativeSQLStrategy` declines external
@@ -362,6 +370,26 @@ interface AnalyticsServiceConfig {
      * always wires it.
      */
     isRegisteredObject?: (name: string) => boolean;
+    /**
+     * [#4437] The FIELD NAMES `objectName` declares, or `undefined` when nothing
+     * authoritative can answer.
+     *
+     * Consulted by {@link AnalyticsService.ensureCube} to validate the SOURCE
+     * FIELD a measure resolves to BEFORE any SQL is built. `inferMeasure` maps a
+     * suffix convention onto a field name (`ghost_sum` → `SUM(ghost)`) and used
+     * to accept any spelling, so a typo'd measure reached the driver as a column
+     * and came back as an opaque `500 SQLITE_ERROR` — a driver error class on the
+     * wire for a caller-shaped mistake (ADR-0112). The DATA route already refuses
+     * the same mistake with a `400 INVALID_FIELD` naming the field (#4315/#4254);
+     * this hook is what lets the ANALYTICS route give the same answer.
+     *
+     * Same tiering as {@link isRegisteredObject}: absence means "skip the check"
+     * (registry-less hosts, engine doubles, external datasources whose columns
+     * are not mirrored locally). The production bridge in `plugin.ts` wires it
+     * from the same schema registry the data path's gate reads, so "which fields
+     * exist" has ONE answer across `/data` and `/analytics`.
+     */
+    getObjectFieldNames?: (objectName: string) => readonly string[] | undefined;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -369,15 +397,23 @@ interface AnalyticsServiceConfig {
      */
     relationshipResolver?: RelationshipResolver;
     /**
-     * ADR-0053 currency chain — resolve a measure's SOURCE FIELD currency
-     * metadata so a monetary measure that omits an explicit `currency` falls back
-     * to the field's declared currency, then the tenant default (`ctx.currency`).
-     * Returns the source field's `type` and (fixed-mode) `defaultCurrency`;
-     * `undefined` for an unknown field. Non-`currency` fields never get a code.
+     * Resolve the metadata of a dimension's or measure's SOURCE FIELD on the
+     * dataset's base object — the one seam through which display semantics that
+     * live on the field reach the result columns. `undefined` for an unknown
+     * field. Feeds three chains:
+     *
+     * - ADR-0053 currency: a monetary measure that omits an explicit `currency`
+     *   falls back to the field's declared currency, then the tenant default
+     *   (`ctx.currency`). Non-`currency` fields never get a code.
+     * - Percent scale (objectui#3136): a measure over a `percent` field inherits
+     *   that field's storage scale via `percentScaleOf`, so a renderer scales by
+     *   declared metadata instead of guessing from the value.
+     * - Date bucketing: a date vs datetime dimension drills by the right bound.
      */
-    measureCurrency?: (object: string, field: string) => {
+    sourceFieldMeta?: (object: string, field: string) => {
         type?: string;
         defaultCurrency?: string;
+        max?: number;
     } | undefined;
     /** Pre-defined datasets to compile + register at construction (ADR-0021). */
     datasets?: Dataset[];
@@ -428,13 +464,15 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly datasetRegistry;
     /** Optional object-graph resolver used when compiling datasets. */
     private readonly relationshipResolver?;
-    private readonly measureCurrency?;
+    private readonly sourceFieldMeta?;
     /** Optional dimension display-label resolver (select options / lookup names). */
     private readonly labelResolver?;
     /** ADR-0037 P3: pending-seed row resolver for draft data preview. */
     private readonly draftRowsResolver?;
     /** [#3867] Schema-registry probe gating cube auto-inference. */
     private readonly isRegisteredObject?;
+    /** [#4437] Field-name probe gating measure source-field resolution. */
+    private readonly getObjectFieldNames?;
     /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
     private warnedNoObjectRegistry;
     readonly cubeRegistry: CubeRegistry;
@@ -511,6 +549,35 @@ declare class AnalyticsService implements IAnalyticsService {
      *   strategies pick the right aggregation function and field.
      */
     private ensureCube;
+    /**
+     * [#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.
+     */
+    private assertMeasureFields;
     /**
      * [#3867] Gate on the cube auto-inference path: a name with no registered
      * Cube may only be inferred into one if it is a registered object.
@@ -545,7 +612,7 @@ interface AnalyticsServicePluginOptions {
      * Probe driver capabilities for a given cube.
      * When omitted, defaults to in-memory only.
      */
-    queryCapabilities?: (cubeName: string) => DriverCapabilities;
+    queryCapabilities?: (cubeName: string) => AnalyticsDriverCapabilities;
     /**
      * Execute raw SQL on a driver. Enables NativeSQLStrategy.
      */
@@ -617,9 +684,22 @@ interface AnalyticsServicePluginOptions {
  */
 declare class AnalyticsServicePlugin implements Plugin {
     name: string;
+    /**
+     * Services init() registers on every path (ADR-0116, #4131) — lets the
+     * kernel name this plugin when a consumer requires one before it inits.
+     */
+    providesServices: string[];
     version: string;
     type: "standard";
     dependencies: string[];
+    /**
+     * 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`).
+     */
+    optionalDependencies: string[];
     private service?;
     private readonly options;
     constructor(options?: AnalyticsServicePluginOptions);
@@ -637,6 +717,50 @@ declare function combineFilters(a?: FilterCondition, b?: FilterCondition): Filte
  * Division by zero (and missing operands) yields `null` rather than Infinity/NaN.
  */
 declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derived: DerivedMeasureSpec[]): Record<string, unknown>[];
+/**
+ * Fill the EMPTY-GROUP value into every measure column the assembled grid
+ * LISTS but no query REPORTED — by aggregate kind (#4708, objectui#3136).
+ *
+ * The grid is assembled from several results: the primary query, one
+ * supplementary query per measure-scoped filter, and (for `compareTo`) a
+ * shifted pass. {@link mergeByDimensions} writes a measure's column only onto
+ * rows its source result returned, and a `GROUP BY` over a filtered row set
+ * emits NO group at all for a dimension value the filter excludes entirely.
+ * The column therefore comes back **absent**, not `0` — and absent renders as
+ * "no data for this row", which for a count is the opposite of what the row
+ * means. A derived ratio over it goes null as well ({@link computeDerived}
+ * treats a missing operand as unknowable), so the blank spreads.
+ *
+ * The bias runs the worst possible way: the rows that blank are the ones whose
+ * numerator the filter excluded — the WORST-performing rows. A `lead_source`
+ * that won nothing renders as "no data" while one that won everything renders
+ * fine.
+ *
+ * **Filled strictly by aggregate kind**, never wholesale. `count` /
+ * `count_distinct` over an excluded group is unambiguously `0` ("how many rows
+ * matched" has an exact answer when the answer is none), and `sum` over the
+ * empty set is its identity `0`. `avg` / `min` / `max` are genuinely null —
+ * there is nothing to average — and flattening those to `0` would trade this
+ * lie for the opposite one, reporting a measurement nobody made. The
+ * kind→identity mapping is `emptyGroupValueFor` in `@objectstack/spec/data`,
+ * shared with the authoring-side coherence checks so the two cannot drift.
+ *
+ * **Only rows that already exist are touched** — no group is invented. A
+ * dimension value no query reported at all has genuinely no data and stays out
+ * of the grid; this fills the cell, never the row.
+ *
+ * Deliberately NOT a `?? 0` in the widget or a `coalesce` in the measure: a
+ * consumer-side patch must be repeated by every author of every ratio widget
+ * forever, and forgetting it is silent. Only the executor knows which aggregate
+ * produced the gap, so only the executor can tell `0` from unknown.
+ *
+ * Mutates `rows` in place (they are already this pipeline's own copies) and
+ * returns them for chaining.
+ *
+ * @param columnAggregates - Grid column → the aggregate that produced it.
+ *   Includes `<measure>__compare` columns, which merge through the same seam.
+ */
+declare function fillEmptyGroups(rows: Record<string, unknown>[], columnAggregates: Record<string, string | undefined>): Record<string, unknown>[];
 /** Compute the comparison window for a [start,end] range. */
 declare function shiftRange(range: [string, string], kind: CompareTo['kind']): [string, string];
 declare class DatasetExecutor {
@@ -660,6 +784,48 @@ declare class DatasetExecutor {
      */
     execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
+    /**
+     * 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.
+     */
+    private runMeasurePass;
+    /**
+     * The selected dimensions the compiled cube types as `time`, in selection
+     * order (#3916) — the axis {@link resolveOrdering} defaults to ascending.
+     *
+     * Membership is decided by the DIMENSION's declared type, not by whether the
+     * selection happens to bucket it: a `date` dimension left ungranulated groups
+     * raw timestamps, and those want chronological order every bit as much as
+     * month buckets do. (Both sort correctly — `compareValues` compares Dates and
+     * ISO strings chronologically, and bucket keys are minted sort-stable.)
+     */
+    private timeDimensionsOf;
     private buildQuery;
     private runCompare;
 }
@@ -681,6 +847,12 @@ declare function compileScopedFilterToSql(filter: FilterCondition, alias: string
  * Pushes the analytics query down to the database as a native SQL statement.
  * This is the most efficient path and is preferred whenever the backing driver
  * supports raw SQL execution (e.g. Postgres, MySQL, SQLite).
+ *
+ * `resolveMeasureSql` used to answer `COUNT(*)` to three different questions it
+ * could not otherwise answer — an undeclared measure, a custom-SQL-expression
+ * metric type, and an unrecognised type. All three returned a plausible number
+ * for a query that asked for something else. They now emit the expression or
+ * throw; see that method. #4157.
  */
 declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
@@ -767,6 +939,34 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
      * correctly.
      */
     private coerceTemporal;
+    /**
+     * The column side of {@link coerceTemporal}: normalise the reference so it
+     * reads in the storage form the comparand was coerced into.
+     *
+     * A SQLite `Field.datetime` column carries an INTEGER epoch (a `Date` write)
+     * and ISO TEXT (a REST/JSON write, a `NOW()` default — including the platform's
+     * own `created_at`) at the SAME time, so coercing the value alone fixes one half
+     * and empties the other. That is #3912: a `dateRange: last_30_days` on
+     * `created_date` read 0 with 29 rows in range. Every other column and dialect
+     * gets its reference back verbatim.
+     */
+    private temporalColumn;
+    /**
+     * Compile a normalized filter node into a boolean SQL expression, recursing
+     * through the combinators. `null` = no constraint.
+     *
+     * Leaves go through {@link buildFilterClause} exactly as they did when this
+     * was a flat loop, so the storage-form coercion and the calendar-day
+     * upper-bound rule (#3777) apply at every depth — including inside an `$or`,
+     * where a second, combinator-aware implementation would have been free to
+     * drift from the first.
+     *
+     * Parenthesisation is explicit rather than left to SQL's precedence: `AND`
+     * does bind tighter than `OR`, so `a AND b OR c` happens to be right, but
+     * being right by construction is what keeps a future edit from making it
+     * wrong.
+     */
+    private compileFilterNode;
     private buildFilterClause;
     private extractObjectName;
     private buildFieldMeta;
@@ -895,6 +1095,26 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * are handed back for the caller to AND in separately, so the engine
      * intersects them instead of the strategy picking a winner.
      */
+    /**
+     * Fold a normalized filter node into the engine filter being built.
+     *
+     * AND-ed LEAVES merge per field through {@link mergeFilterOperand}, exactly
+     * as the flat loop this replaced did — so a query without combinators still
+     * produces byte-identical engine input. Anything structural (`$or`, `$not`,
+     * a nested `$and` that cannot merge) becomes its own conjunct, which the
+     * caller ANDs in. The engine speaks these combinators natively
+     * (`FilterCondition` declares them and every driver compiles them), so this
+     * path hands them over rather than lowering them.
+     */
+    private applyFilterNode;
+    /** A node as a standalone `FilterCondition` the engine can consume. */
+    private filterNodeToCondition;
+    /**
+     * Render a normalized filter node as the display SQL `/analytics/sql`
+     * echoes. Values still bind as `$n` placeholders — the echo travels to the
+     * browser, so a comparand is never inlined.
+     */
+    private renderFilterNodeSql;
     private mergeFilterOperand;
     /**
      * Lower `timeDimensions[].dateRange` into resolved-field bounds (#3650).
@@ -907,9 +1127,13 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * HERE on every driver — and "bucketed trend" is precisely the shape that also
      * carries a range ("last 12 months", "this quarter").
      *
-     * Bounds are inclusive on both ends — the same `$gte`/`$lte` pair
-     * `NativeSQLStrategy` binds as `BETWEEN` and the memory driver builds as a
-     * `$match`, so one dashboard reads the same on every driver.
+     * Bounds are inclusive on both ends — logically "from day X through day Y".
+     * The `$lte` end is left as the bare calendar day on purpose: the driver's
+     * filter compiler owns the calendar-day → instant translation, compiling a
+     * bare-day `$lte` on a `datetime` column into the half-open `< nextDay`
+     * (#3777) while a `date` column keeps the plain `<=`. `NativeSQLStrategy`
+     * performs the same half-open translation itself because it binds into raw
+     * SQL, so one dashboard reads the same on every driver.
      *
      * Comparands are coerced by the SAME helper the `where` path uses, so an
      * epoch-ms bound recovers as a number and an ISO string stays a string. No
@@ -934,7 +1158,26 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private dateRangeBounds;
     private convertFilter;
     private extractObjectName;
+    /**
+     * The dimensions this query PROJECTS, in the order the result carries them:
+     * every `dimensions` entry, then every granular `timeDimensions` entry that
+     * is not already one of them.
+     *
+     * `timeDimensions` is not merely a filter carrier. An entry with a
+     * `granularity` is GROUPED BY — see the `td.granularity` sites that build
+     * groupBy here, in `generateSql` and in the cross-object path — so its
+     * bucket is a COLUMN of the result; an entry without one only contributes a
+     * `dateRange` predicate and must NOT be projected.
+     *
+     * Grouping, row mapping and {@link buildFieldMeta} have to agree on exactly
+     * that set. When they did not, a bucketed query returned rows carrying only
+     * the measures and a `fields` list that never mentioned the bucket — a trend
+     * chart got N values and no x-axis (#4033) — even though the SQL had
+     * selected `date_trunc(…) AS "<dim>"` all along. One definition, every
+     * consumer.
+     */
+    private projectedDimensions;
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type OrderLabelResolver, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, createOrderLabelResolver, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange, withLabelFetchCache };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type OrderLabelResolver, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, createOrderLabelResolver, evaluateDerivedMeasures, fillEmptyGroups, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange, withLabelFetchCache };