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

package/dist/index.d.cts

@@ -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
@@ -617,6 +625,11 @@ 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[];
@@ -660,6 +673,17 @@ declare class DatasetExecutor {
      */
     execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
+    /**
+     * 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 +705,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 +797,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 +953,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 +985,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,6 +1016,25 @@ 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;
 }
 

package/dist/index.d.ts

@@ -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
@@ -617,6 +625,11 @@ 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[];
@@ -660,6 +673,17 @@ declare class DatasetExecutor {
      */
     execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
+    /**
+     * 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 +705,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 +797,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 +953,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 +985,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,6 +1016,25 @@ 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;
 }