@objectstack/service-analytics 17.3.0 → 17.4.0

package/dist/index.d.cts

@@ -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? }`
@@ -520,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[];
     /**
@@ -718,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.
      */
@@ -1221,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[];
 };
@@ -1702,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;
     /**

package/dist/index.d.ts

@@ -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? }`
@@ -520,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[];
     /**
@@ -718,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.
      */
@@ -1221,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[];
 };
@@ -1702,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;
     /**