@objectstack/service-analytics 17.2.0 → 17.4.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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 { Cube, FilterCondition, AggregationFunction } from '@objectstack/spec/data';
 import { ExecutionContext } from '@objectstack/spec/kernel';
 import { Dataset } from '@objectstack/spec/ui';
 import { Plugin, PluginContext } from '@objectstack/core';
@@ -8,12 +8,26 @@ import { Plugin, PluginContext } from '@objectstack/core';
 /**
  * CubeRegistry — Central registry for analytics cube definitions.
  *
- * Cubes can be registered from two sources:
- * 1. **Manifest definitions** — Explicit cube definitions in `objectstack.config.ts`.
- * 2. **Object schema inference** — Auto-generated cubes from ObjectQL object schemas.
+ * The registry is the single source of truth for cube metadata discovery:
+ * `getMeta()` maps every registered cube's measure/dimension `label` onto the
+ * `CubeMeta` titles served by `GET /api/v1/analytics/meta`, and the strategy
+ * chain resolves a query's cube through it.
  *
- * The registry is the single source of truth for cube metadata discovery
- * (used by `getMeta()` and the strategy chain).
+ * Three sources write to it, all of them from `AnalyticsService`:
+ * 1. **Manifest definitions** — `AnalyticsServiceConfig.cubes` (`registerAll`),
+ *    i.e. explicit cube definitions authored in `objectstack.config.ts`.
+ * 2. **Compiled datasets** (ADR-0021) — `compileDataset()`'s Cube, registered
+ *    under the dataset's name by `queryDataset`.
+ * 3. **Ad-hoc query inference** — `ensureCube` / `inferCubeFromQuery` mints a
+ *    minimal Cube from the members an `AnalyticsQuery` references, once
+ *    `assertInferableCube` (#3867) has confirmed the name is a registered
+ *    object. It infers from the QUERY, never from the object's field schema.
+ *
+ * This list used to read "two sources: manifest definitions, and object schema
+ * inference". Neither half was right: sources 2 and 3 were missing, and object
+ * schema inference is `inferFromObject` below, which no path in this repository
+ * calls (#15019). It is described at the method rather than advertised here,
+ * because listing it would promise a source the platform does not deliver.
  */
 declare class CubeRegistry {
     private cubes;
@@ -34,14 +48,36 @@ declare class CubeRegistry {
     /** Remove all cubes. */
     clear(): void;
     /**
-     * Auto-generate a cube definition from an object schema.
-     *
-     * Heuristic rules:
-     * - `number` fields → `sum`, `avg`, `min`, `max` measures
-     * - `boolean` fields → `count` measure (count where true)
-     * - All non-computed fields → dimensions
-     * - `date`/`datetime` fields → time dimensions with standard granularities
-     * - A default `count` measure is always added
+     * Auto-generate a cube definition from an object's FIELD SCHEMA, and register
+     * it under `objectName`.
+     *
+     * ⚠️ Nothing in this repository calls this — the only in-tree caller is a unit
+     * test, and every cube the platform registers itself comes from one of the
+     * three sources named on the class above (#15019). That is not the same thing
+     * as unreachable: `CubeRegistry` is exported from the package entry and
+     * `AnalyticsService.cubeRegistry` is public, so a consumer of
+     * `@objectstack/service-analytics` can call it, and what it mints does reach
+     * the wire — `getMeta()` serves the labels below as `CubeMeta` titles. Whether
+     * this published method is removed or wired up as a real cube source is #15019.
+     *
+     * Heuristic rules, measured by driving the built package (the list this
+     * replaces claimed three behaviours the code does not have — `min`/`max`
+     * measures, a `count` measure for booleans, and a computed-field exclusion):
+     * - `number` / `currency` / `percent` fields → one `sum` and one `avg` measure
+     *   each, labelled with the field's label plus ` (Sum)` / ` (Avg)`. No `min`
+     *   or `max` measure is minted.
+     * - EVERY field becomes a dimension; there is no computed-field exclusion (the
+     *   `fields` parameter carries no flag one could exclude on).
+     * - `boolean` fields become a `boolean` DIMENSION and nothing else — no count
+     *   measure is minted for them.
+     * - `date` / `datetime` fields → `time` dimensions granulated
+     *   day/week/month/quarter/year.
+     * - A default `count` measure labelled `Count` is always added.
+     *
+     * Those three defaults (`Count`, and the two composites) are English literals
+     * with no i18n hook; #14492's ruling listed the `Count` one as a site to carry
+     * the `builtinAggregate` discriminator, and it was left alone because no
+     * in-repo path reaches it.
      *
      * @param objectName - The snake_case object name (used as table/cube name)
      * @param fields - Array of field descriptors `{ name, type, label? }`
@@ -328,10 +364,28 @@ interface AnalyticsServiceConfig {
      */
     executeAggregate?: (objectName: string, options: {
         groupBy?: string[];
+        /**
+         * The local mirror of `StrategyContext.executeAggregate`'s aggregation
+         * entries (`packages/spec/src/contracts/analytics-service.ts`), kept in
+         * lockstep with it member by member. The two that lockstep is load-bearing
+         * for:
+         *
+         * - `filter` (#10576, the #10413 phase-2 contract field) — a bridge that
+         *   reconstructs the aggregation entries (as `AnalyticsServicePlugin`'s
+         *   auto-bridge does, to rename `method` → the engine's `function`) MUST
+         *   forward this field or a measure-scoped filter `ObjectQLStrategy`
+         *   lowers never reaches storage.
+         * - `method` is the spec's OWN six-value `AggregationFunction`, not
+         *   `string`: #12776 narrowed the contract, #12940 brought this mirror
+         *   back into line. Widening it here again would not be a local matter —
+         *   a bridge author types their handler against THIS declaration, so what
+         *   they would get is a vocabulary the contract no longer has.
+         */
         aggregations?: Array<{
             field: string;
-            method: string;
+            method: AggregationFunction;
             alias: string;
+            filter?: Record<string, unknown>;
         }>;
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
@@ -502,6 +556,24 @@ interface AnalyticsServiceConfig {
         defaultCurrency?: string;
         max?: number;
     } | undefined;
+    /**
+     * [#15684] The SQL dialect of the datasource backing `object` — `'sqlite'`,
+     * `'postgres'`, `'mysql'`, or `undefined` when the host cannot answer.
+     *
+     * The three SQL compilers need it for ONE thing: the case-EXACT text family
+     * (`$contains` / `$notContains` / `$startsWith` / `$endsWith`, #4706 Q2 = A)
+     * has no construct that is case-exact and parses on every dialect. A plain
+     * `LIKE` is case-exact on Postgres alone — SQLite folds ASCII case
+     * unconditionally, so the query's own `where` AND the RLS read scope
+     * admitted rows the predicate excludes there (over-reach, #3948). The
+     * per-dialect table lives in `text-match-sql.ts`.
+     *
+     * Answered by the plugin from the driver that will EXECUTE the statement, so
+     * the driver stays the single source of truth for its own dialect. A host
+     * that wires nothing keeps the `LIKE` the compilers always emitted —
+     * "cannot answer, do not block".
+     */
+    sqlDialect?: (object: string) => string | undefined;
     /** Pre-defined datasets to compile + register at construction (ADR-0021). */
     datasets?: Dataset[];
     /**
@@ -619,6 +691,27 @@ declare class AnalyticsService implements IAnalyticsService {
      * `getReadScope(objectName)` that already knows the active tenant.
      */
     private callCtx;
+    /**
+     * [#12230] Copy-on-write expansion of filter placeholders across everything
+     * a DIRECT analytics query compares on: `where` and each time dimension's
+     * `dateRange` — the same positions `DatasetExecutor.resolveSelectionTokens`
+     * covers for the dashboard door, minus the dataset-only channels it alone
+     * carries (measure filters ride the dataset-scope getter below).
+     *
+     * The input is never mutated: a query object can be caller-owned metadata
+     * (a saved report definition, a flow node's config) reused across requests,
+     * and resolving in place would bake one request's user id into every later
+     * render. Returns the SAME object when nothing resolved.
+     */
+    private resolveQueryTokens;
+    /**
+     * [#12230] A per-request `getDatasetScope` whose answers have their filter
+     * placeholders resolved against THIS caller. See `callCtx` for why the
+     * registry's copy cannot be handed out raw. Token-free scopes pass through
+     * by reference — `resolveFilterTokens` returns its input unchanged when the
+     * tree holds no placeholder, so the common case allocates nothing.
+     */
+    private resolvedDatasetScopeGetter;
     /**
      * 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
@@ -644,7 +737,7 @@ declare class AnalyticsService implements IAnalyticsService {
      * aggregate bridge) instead of failing — or worse, fabricating empty rows.
      * Any other error propagates untouched.
      */
-    query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    query(queryInput: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
      * [#8286] Withhold the executed statement unless this host enabled the echo.
      *
@@ -679,6 +772,42 @@ declare class AnalyticsService implements IAnalyticsService {
     queryDataset(dataset: Dataset, selection: DatasetSelection, context?: ExecutionContext, options?: {
         previewDrafts?: boolean;
     }): Promise<AnalyticsResult>;
+    /**
+     * The dataset dimensions this selection GROUPED THE GRID BY, resolved against
+     * the dataset definition. Shared by drill metadata, row-value label
+     * resolution and — through {@link enrichResultColumns} — the dimension column
+     * headers, so all three answer "which dimensions" the same way.
+     */
+    private selectedDimensions;
+    /**
+     * ADR-0021 — describe the result's COLUMNS from the dataset's own authored
+     * definition: a measure's `label` / `format` / `currency` / `percentScale` /
+     * `builtinAggregate` and the `type` its aggregate really returns, then a
+     * dimension column's header `label`.
+     *
+     * **Every key here is read off the DATASET** (the authored measure or
+     * dimension) **and `sourceFieldMeta`** (the source object's declared field
+     * metadata). Not one is read off `result.rows`. That is what makes this one
+     * seam serve both paths that produce a dataset response — the live engine
+     * query and the ADR-0037 P3 draft-data preview — and it is why #16097 was a
+     * defect rather than a deliberate omission: the preview branch returns ~250
+     * lines before this ran, so a response over drafted seed rows carried none of
+     * these keys and a renderer fell back to humanizing the raw measure name and
+     * guessing a percent scale from magnitude — the exact failures #5537,
+     * objectui#3136 and #14492 each closed on the live path.
+     *
+     * Extracted rather than copied onto the second path, for the reason the
+     * `type` correction below already gives for living here at all: this is ONE
+     * rule holding both halves of the question, and a per-path copy would be two
+     * implementations of it, free to drift.
+     *
+     * ⛔ Not here, and deliberately: dimension VALUE label resolution
+     * ({@link resolveDimensionLabels}), which rewrites the grouped value in each
+     * ROW. That reads the rows, it is the one enrichment a seed-draft row set can
+     * make unnecessary, and the preview path skips it on purpose — see the note
+     * at that early return.
+     */
+    private enrichResultColumns;
     /**
      * Get cube metadata for discovery.
      */
@@ -686,7 +815,7 @@ declare class AnalyticsService implements IAnalyticsService {
     /**
      * Generate SQL for a query without executing it (dry-run).
      */
-    generateSql(query: AnalyticsQuery, context?: ExecutionContext): Promise<{
+    generateSql(queryInput: AnalyticsQuery, context?: ExecutionContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
@@ -922,10 +1051,28 @@ interface AnalyticsServicePluginOptions {
      */
     executeAggregate?: (objectName: string, options: {
         groupBy?: string[];
+        /**
+         * The CUSTOM bridge's view of the aggregation entries — an app author's
+         * own `executeAggregate`, as opposed to the auto-bridge below. Mirrors
+         * `StrategyContext.executeAggregate`
+         * (`packages/spec/src/contracts/analytics-service.ts`) and must stay in
+         * lockstep with it; the two members that lockstep is load-bearing for:
+         *
+         * - `filter` (#10576, the #10413 contract field) — a custom bridge MUST
+         *   forward it to the real engine the same way the auto-bridge does, or a
+         *   measure-scoped filter this plugin lowers onto the aggregation
+         *   silently never reaches storage.
+         * - `method` is the spec's OWN six-value `AggregationFunction`, not
+         *   `string`: #12776 narrowed the contract, #12940 brought this mirror
+         *   back into line. This is the declaration a custom-bridge author types
+         *   their handler against, so it is where the compile-time vocabulary
+         *   #12776 bought for strategy authors reaches them too.
+         */
         aggregations?: Array<{
             field: string;
-            method: string;
+            method: AggregationFunction;
             alias: string;
+            filter?: Record<string, unknown>;
         }>;
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
@@ -1164,7 +1311,37 @@ declare class DatasetExecutor {
  */
 declare function mergeByDimensions(base: Record<string, unknown>[], extra: Record<string, unknown>[], dimensions: string[], valueColumns: string[]): Record<string, unknown>[];
 
-declare function compileScopedFilterToSql(filter: FilterCondition, alias: string): {
+/**
+ * [#14079] What a caller can tell this compiler about the columns a read scope
+ * names, beyond the scope itself.
+ */
+interface ReadScopeCompileOptions {
+    /**
+     * Is `field` a column whose STORED value is never text — a declared numeric
+     * or boolean scalar (`NON_TEXT_STORED_VALUE_TYPES`, `@objectstack/spec`)?
+     * When it answers `true`, a text operator over that column compiles to the
+     * contract's constant (`1 = 0` for the positive operators, `1 = 1` for
+     * `$notContains`) instead of a `LIKE` that coerces on SQLite and is refused
+     * at query time on Postgres (SQLSTATE 42883). Absent, or answering `false`,
+     * keeps the `LIKE` — the answer for a text column and for a caller that
+     * cannot classify one (`non-text-column.ts` carries the argument).
+     */
+    nonTextColumn?: (field: string) => boolean;
+    /**
+     * [#15684] The SQL dialect that will EXECUTE this scope — `'sqlite'` /
+     * `'postgres'` / `'mysql'`. Anything else, including absent, is `'unknown'`
+     * and keeps the plain `LIKE` this compiler always emitted.
+     *
+     * The case-EXACT text family (#4706 Q2 = A) needs it: SQLite's `LIKE` folds
+     * ASCII case unconditionally, so a policy written `{ name: { $contains:
+     * 'acme' } }` ADMITTED `ACME Corp` there — rows the predicate excludes,
+     * which on a read scope is over-reach (#3948), not a loose filter. The
+     * per-dialect construct table lives in `text-match-sql.ts`; both of this
+     * compiler's consumers fill this in from the driver that owns the object.
+     */
+    dialect?: string;
+}
+declare function compileScopedFilterToSql(filter: FilterCondition, alias: string, options?: ReadScopeCompileOptions): {
     sql: string;
     params: unknown[];
 };
@@ -1465,7 +1642,7 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * the members inside were unreadable from the outside and the envelope check
      * could not reject what it could not see.
      *
-     * ## Two producers, one inventory (#10861)
+     * ## Three producers, one inventory (#10861, #11461)
      *
      * The caller's `where` is not the only thing that reaches `engine.aggregate`
      * as a predicate. Since PR #10758 the compiled dataset's own definition-level
@@ -1480,6 +1657,36 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * which driver will serve the dataset and would refuse a dataset that is
      * perfectly legal on a native-SQL deployment.
      *
+     * [#11461] #10413 phase 2 then added a THIRD producer with the same reach and
+     * none of the coverage: a compiled measure's own `filter`, lowered onto that
+     * measure's `aggregations[].filter` entry (#10576). This view enumerated two
+     * origins, so the third was invisible to the envelope check and the arm of
+     * `planCrossObject` that inspects `query.measures` reads only each measure's
+     * resolved FIELD, never its filter. Measured on the unfixed tree, one fixture,
+     * both doors:
+     *
+     * ```
+     * BEFORE  execute()     ACCEPTED -> aggregations: [{field:"*",method:"count",
+     *                                   alias:"west_count",
+     *                                   filter:{"account.region":"West"}}]
+     *                                -> rows [{stage:"won",total_count:3,west_count:0}]
+     *                                   (the truthful west_count is 2; total_count
+     *                                    is right, so the wrong number arrived in
+     *                                    the same response shape as the right one)
+     *         generateSql() ACCEPTED -> COUNT(CASE WHEN account.region = $1 THEN 1 END)
+     *                                   over a FROM with no join in it at all
+     * AFTER   both doors    REFUSED   INVALID_FIELD / 400, engine never reached
+     * ```
+     *
+     * The same maintainer ruling covers it — same hazard, same physical verdict,
+     * one more producer — so it folds in HERE for the #10861 reason and not into
+     * `dataset-compiler.ts`, which still cannot see which driver will serve the
+     * dataset. Only the REQUESTED measures are folded: both doors' aggregation
+     * loops read `measureFilters[m]` for `m of query.measures` and nothing else,
+     * so a filter declared on a measure this query never asks for reaches no
+     * engine, and refusing on it would reject a query for a member that was never
+     * going to be evaluated.
+     *
      * Structure is discarded on purpose — a member is cross-object or it is not,
      * and which branch of a disjunction it sits in cannot make
      * `engine.aggregate` able to join it. PROVENANCE is not discarded, because it
@@ -1489,9 +1696,12 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * `planCrossObject`. The value slot carries that and nothing else; it never
      * reaches a driver.
      *
-     * Dataset leaves are inserted FIRST so a member named by BOTH producers keeps
-     * the caller's provenance (last write wins on a duplicate key): if it is in
-     * the request too, the request is the actionable place to fix it.
+     * Insertion order is measure-filter, then dataset-filter, then `where`, and
+     * last write wins on a duplicate key. Two things follow, in that order of
+     * importance. A member named by the request too keeps the CALLER's provenance,
+     * because if it is in the request that is the actionable place to fix it. And
+     * every shape that was refused before #11461 keeps the exact message it had:
+     * the new origin can only ever win a key no older producer names.
      *
      * Time-dimension WINDOWS are deliberately absent (they live in
      * `dateRangeBounds`, not in `where`). They need no arm here: a cross-object
@@ -1513,18 +1723,20 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
      * (needs a real join to evaluate), a cross-object leaf in the DATASET's own
      * definition-level `filter` (#10861 — same join it does not have, arriving
-     * from the producer PR #10758 added), a MULTI-HOP dimension (`a.b.c`), or a
-     * non-recombinable measure (`avg`/`count_distinct`, whose sub-bucket values
-     * cannot be merged). A loud error beats the silent mis-bucket #3654 kills.
+     * from the producer PR #10758 added), a cross-object leaf in ONE MEASURE's own
+     * `filter` (#11461 — the same join again, arriving from the producer #10413
+     * phase 2 added), a MULTI-HOP dimension (`a.b.c`), or a non-recombinable
+     * measure (`avg`/`count_distinct`, whose sub-bucket values cannot be merged).
+     * A loud error beats the silent mis-bucket #3654 kills.
      * `generateSql()` calls this too, so the preview accepts/rejects the same set
      * — and since #10759 both callers derive `filter` from the one
      * {@link filterMemberView}, so that sentence is enforced by construction
      * instead of restated at two call sites.
      *
-     * [#5716] All five refusals below are `invalidMemberError` — `INVALID_FIELD` /
+     * [#5716] All six refusals below are `invalidMemberError` — `INVALID_FIELD` /
      * 400, naming the member — and the four that predate #10861 keep their
      * MESSAGES unchanged (they are good diagnostics, and #5923's tests read
-     * them). Each is decided by two facts and nothing else: a member that will
+     * them); so does #10861's own, which #11461 left untouched beside it. Each is decided by two facts and nothing else: a member that will
      * reach the engine's predicate, and whether that member resolves across a
      * join. Neither is an internal invariant — a cube where the member exists and
      * a driver that could serve it are both perfectly ordinary, which is exactly
@@ -1533,14 +1745,15 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * because the fix is always to change or drop ONE named member, and because
      * four of them fire on `/analytics/query` where no dataset exists.
      *
-     * [#10861] The fifth is the exception that proves the rule and is written to
-     * it: it can only fire where a dataset DOES exist, and it is the one refusal
-     * here whose member no request key named — so it carries `cube` and no
-     * `param`, and says in its own words which document to go and edit. It stays
+     * [#10861, #11461] The fifth and sixth are the exceptions that prove the rule
+     * and are written to it: they can only fire where a dataset DOES exist, and
+     * they are the two refusals here whose member no request key named — so each
+     * carries `cube` and no `param`, and says in its own words which document to
+     * go and edit, the sixth naming the MEASURE inside it as well. Both stay
      * `INVALID_FIELD` rather than becoming `DATASET_INVALID` because the verdict
-     * is the same physical one as its neighbour — this engine cannot join this
+     * is the same physical one as their neighbours — this engine cannot join this
      * member — and splitting the code by PROVENANCE would make a caller branch on
-     * two wire shapes for one capability limit.
+     * three wire shapes for one capability limit.
      *
      * Detection is on RESOLVED field names, so a dotted dimension the cube
      * flattens to a real column is treated as base, not cross-object.
@@ -1558,6 +1771,23 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      * are simply absent from the map (⇒ RESTRICTED bucket downstream).
      */
     private resolveFkAttr;
+    /**
+     * A measure's aggregate, restricted to the rows its own `filter` admits
+     * (#10413 phase 2) — the same six functions `generateSql`'s unconditional
+     * branch renders, wrapped in a `CASE WHEN`.
+     *
+     * Spelled `CASE WHEN` rather than SQL-standard `FILTER (WHERE …)`, mirroring
+     * `NativeSQLStrategy.CONDITIONAL_AGGREGATE_SQL`: this string is DOCUMENTATION
+     * of an execution that really goes through `engine.aggregate`'s per-driver
+     * `aggregations[].filter` lowering (#10576), not a statement this class runs
+     * itself, so there is no reason to pick a dialect-restricted spelling over
+     * the portable one the SQL-executing sibling already settled on.
+     *
+     * `count` over `*` counts a constant (`COUNT(CASE WHEN p THEN 1 END)`, since
+     * `COUNT(CASE WHEN p THEN * END)` is not valid SQL); over a real column it
+     * counts that column's non-null values among the admitted rows.
+     */
+    private conditionalAggregateSql;
     /**
      * Render one normalized filter as a display SQL predicate for `generateSql`.
      *
@@ -1592,6 +1822,17 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
      *   3. `<field>`                  — bare column on the cube's table.
      */
     private lookupMember;
+    /**
+     * [#14079] The (object, field) a filter member binds against — the echo's
+     * copy of `NativeSQLStrategy.resolveStorageTarget`, kept beside the
+     * `LIKE_SQL_OPS` table for the same reason that table is a copy: this file
+     * renders a description of the statement THAT compiler produces, and the
+     * declared-type test both apply is keyed by object and field. A dotted
+     * `sql` is a relationship path (ADR-0071): every segment but the last is a
+     * hop whose join alias is the dot-to-`__` spelling the dataset compiler keys
+     * `cube.joins` by, the last is the column.
+     */
+    private resolveStorageTarget;
     private resolveFieldName;
     private resolveMeasureAggregation;
     /**