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

package/dist/index.d.cts

@@ -119,6 +119,7 @@ declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolve
  * — reading an object's field map and fetching id→label pairs — are injected via
  * {@link DimensionLabelDeps} so this module stays free of any engine dependency.
  */
+
 /** The minimal field shape this resolver needs. */
 interface FieldMetaLite {
     type?: string;
@@ -138,9 +139,90 @@ interface DimensionLabelDeps {
      * Fetch a map of `id → display label` for the given ids of a target object.
      * The implementation chooses the target's display field. Returning an empty
      * map (e.g. no display field, no data access) leaves the ids unresolved.
+     *
+     * `scope` (ADR-0021 D-C, #3602) is the TARGET object's own read scope — the
+     * RLS/tenant `FilterCondition` the implementation must AND into the label
+     * lookup so this never reveals a related record the target object's RLS would
+     * hide. The label lookup is a per-record read (`group by id`) dressed as an
+     * aggregate; without the scope it leaks display names whenever the referenced
+     * object is more restricted than the base object whose rows carry the id.
+     * `undefined` means "no scope for this object" (global table / unrestricted
+     * caller) — the same contract as the read-scope provider.
+     *
+     * `context` is the request's ExecutionContext — the SECOND belt on the same
+     * read (#3602). `scope` is the analytics layer's own predicate; forwarding the
+     * context lets the ENGINE's middleware chain scope this per-record read
+     * itself, so it stays scoped even if a caller ever reaches this hook without
+     * a resolved `scope`. Implementations bridging to an ObjectQL engine MUST
+     * forward it; a bridge with nowhere to put it may ignore it.
+     */
+    fetchRecordLabels(targetObject: string, ids: unknown[], scope?: Record<string, unknown>, context?: ExecutionContext): Promise<Map<unknown, string>>;
+}
+/**
+ * Resolve the TARGET object's read scope for a label lookup (#3602). Returns the
+ * object's RLS/tenant `FilterCondition`, `null`/`undefined` when the object is
+ * unscoped, or a rejected promise when the scope cannot be resolved — in which
+ * case the resolver fails CLOSED (skips that dimension's labels) rather than
+ * fetching unscoped names.
+ */
+type LabelScopeResolver = (targetObject: string) => Promise<Record<string, unknown> | null | undefined> | Record<string, unknown> | null | undefined;
+/**
+ * Sort-key label resolution for `DatasetSelection.order` (#3680).
+ *
+ * The executor sorts the assembled grid BEFORE `queryDataset` rewrites stored
+ * dimension values into display labels, so an order key naming a `select` or
+ * `lookup`/`master_detail` dimension used to sort by the stored value / FK id —
+ * an order that presents as arbitrary once the labels render. This hook hands
+ * the executor JUST the value→label mapping for such a dimension so it can sort
+ * by what the user will actually read, while the rows keep their raw values
+ * (drill metadata depends on them) and ordering + windowing stay one adjacent
+ * step. The executor stays engine-free: it sees this interface, never the
+ * engine behind it.
+ */
+interface OrderLabelResolver {
+    /**
+     * Whether the dimension's stored value differs from the label it renders as
+     * (`select` options, `lookup`/`master_detail` FK ids). Synchronous — the
+     * executor consults it when deciding whether the window may be pushed into
+     * SQL, before any query runs.
+     */
+    isLabelBearing(dimension: string): boolean;
+    /**
+     * Map the given raw stored values of one dimension to display labels.
+     * Values missing from the map sort by their raw form — the same thing the
+     * user will see rendered for them.
      */
-    fetchRecordLabels(targetObject: string, ids: unknown[]): Promise<Map<unknown, string>>;
+    resolveLabels(dimension: string, values: unknown[]): Promise<Map<unknown, string> | undefined>;
 }
+/**
+ * Build the executor's {@link OrderLabelResolver} from the dataset's dimension
+ * list and the injected label capabilities. Mirrors the classification in
+ * {@link resolveDimensionLabels}: a dimension is label-bearing when its field
+ * carries select `options` or is a lookup/master_detail with a `reference`.
+ *
+ * - `select` resolves from field metadata — no query at all.
+ * - `lookup`/`master_detail` costs ONE batched id→name read over the distinct
+ *   grouped values, scoped to the REFERENCED object's own RLS (#3602). Fail
+ *   closed: an unresolvable scope degrades to sorting by the stored id rather
+ *   than fetching unscoped — consistent with the display pass, which renders
+ *   the raw id in that case too.
+ */
+declare function createOrderLabelResolver(baseObject: string, dims: Array<{
+    name: string;
+    field: string;
+}>, deps: DimensionLabelDeps, resolveScope?: LabelScopeResolver, context?: ExecutionContext): OrderLabelResolver;
+/**
+ * Wrap a {@link DimensionLabelDeps} so repeated `fetchRecordLabels` calls
+ * within ONE request fetch each id at most once. A selection that sorts by a
+ * lookup dimension resolves labels twice — once PRE-window for the sort keys
+ * (#3680, over the full grid's ids), once post-window for display (a subset of
+ * the same ids) — so with this cache the display pass costs no extra query.
+ *
+ * Per-request only: entries are keyed by target object alone, which is safe
+ * because an object's read scope is constant within one request. Never share
+ * an instance across requests.
+ */
+declare function withLabelFetchCache(deps: DimensionLabelDeps): DimensionLabelDeps;
 /** Date-dimension granularity (mirrors the dataset `dateGranularity` enum). */
 type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
 /**
@@ -151,13 +233,22 @@ type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
  *   (row key = `name`)
  * @param rows - result rows, mutated in place
  * @param deps - injected runtime capabilities
+ * @param resolveScope - (ADR-0021 D-C, #3602) resolves the referenced object's
+ *   own read scope for a lookup/master_detail dimension's label fetch. When it
+ *   throws, that dimension's labels are SKIPPED (fail-closed — the raw id renders
+ *   instead) rather than fetched unscoped. Omit when no read-scope provider is
+ *   configured (labels then fetch unscoped, as before — no security in play).
+ * @param context - the request's ExecutionContext, forwarded to
+ *   {@link DimensionLabelDeps.fetchRecordLabels} so the engine's own middleware
+ *   scopes the per-record label read too — the second belt beside `resolveScope`
+ *   (#3602)
  */
 declare function resolveDimensionLabels(baseObject: string, dims: Array<{
     name: string;
     field: string;
     type?: string;
     dateGranularity?: DateGranularity | string;
-}>, rows: Record<string, unknown>[], deps: DimensionLabelDeps): Promise<void>;
+}>, rows: Record<string, unknown>[], deps: DimensionLabelDeps, resolveScope?: LabelScopeResolver, context?: ExecutionContext): Promise<void>;
 /**
  * Pick the display field for an object from its field map, by convention:
  * an explicit `name`/`title`/`label` field, else the first text-like field.
@@ -195,6 +286,15 @@ interface AnalyticsServiceConfig {
             alias: string;
         }>;
         filter?: Record<string, unknown>;
+        /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
+        timezone?: string;
+        /**
+         * ADR-0021 D-C (#3602) — the request's ExecutionContext. Bridges MUST
+         * forward it to `engine.aggregate` so engine-side RLS applies; see
+         * `StrategyContext.executeAggregate` for why this is a second belt rather
+         * than a replacement for `getReadScope`.
+         */
+        context?: ExecutionContext;
     }) => Promise<Record<string, unknown>[]>;
     /**
      * Fallback IAnalyticsService (e.g. MemoryAnalyticsService).
@@ -244,6 +344,24 @@ interface AnalyticsServiceConfig {
      * `StrategyContext.isExternalObject`.
      */
     isExternalObject?: (objectName: string) => boolean;
+    /**
+     * [#3867] Is `name` a registered object in this kernel's schema registry?
+     *
+     * Consulted by {@link AnalyticsService.ensureCube} on the auto-inference
+     * path only. When no Cube is registered under the queried name, the service
+     * infers a minimal one whose `sql` IS that name — the intended "metric over
+     * an object" path (an `object-metric` KPI widget queries `crm_account`
+     * without anyone authoring a Cube). Without this hook that inference accepts
+     * ANY string, so an arbitrary physical table name reached the driver: the
+     * analytics-side twin of the data-path gap closed in #3770.
+     *
+     * Optional, and absence means "skip the check" — same tiering as #3770's
+     * `assertObjectRegistered`: with no registry to consult the question cannot
+     * be answered, and failing closed would break every embedding that runs
+     * analytics without a data engine. The production bridge in `plugin.ts`
+     * always wires it.
+     */
+    isRegisteredObject?: (name: string) => boolean;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -315,6 +433,10 @@ declare class AnalyticsService implements IAnalyticsService {
     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?;
+    /** [#3867] One-shot flag for the {@link assertInferableCube} stand-down warning. */
+    private warnedNoObjectRegistry;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -389,6 +511,20 @@ declare class AnalyticsService implements IAnalyticsService {
      *   strategies pick the right aggregation function and field.
      */
     private ensureCube;
+    /**
+     * [#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.
+     *
+     * Rejects with `status: 404` / `code: 'CUBE_NOT_FOUND'` so the HTTP boundary
+     * answers "no such cube" instead of letting the name reach the driver as a
+     * table and surfacing whatever the driver says about it. The message names
+     * both ways the request could be made valid, because from here the two are
+     * genuinely indistinguishable: register a Cube, or register the object.
+     *
+     * Skips when `isRegisteredObject` was not supplied — see the config field's
+     * doc for why that tier is a deliberate stand-down and not a hole.
+     */
+    private assertInferableCube;
     /** Build a minimal Cube from the fields referenced by an AnalyticsQuery. */
     private inferCubeFromQuery;
     /**
@@ -427,6 +563,12 @@ interface AnalyticsServicePluginOptions {
         filter?: Record<string, unknown>;
         /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
         timezone?: string;
+        /**
+         * ADR-0021 D-C (#3602) — the request's ExecutionContext. A custom bridge
+         * MUST forward it to its engine so engine-side RLS applies; dropping it is
+         * what made the built-in bridge fall open in #3597.
+         */
+        context?: ExecutionContext;
     }) => Promise<Record<string, unknown>[]>;
     /**
      * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). The
@@ -488,25 +630,6 @@ declare class AnalyticsServicePlugin implements Plugin {
 
 /** @deprecated use DatasetCompareTo from @objectstack/spec/contracts */
 type CompareTo = DatasetCompareTo;
-/**
- * Dataset executor (ADR-0021 WS2).
- *
- * Turns a compiled dataset + a presentation's selection (dimensions, measures,
- * runtime filter, compareTo) into one or more `AnalyticsQuery`s against the Cube
- * runtime, then post-processes the results:
- *   - resolves the base measures a selection needs (including derived deps),
- *   - applies measure-scoped filters via supplementary grouped queries,
- *   - evaluates derived measures (ratio/sum/difference/product) row-by-row (Q1),
- *   - shifts the query for `compareTo` (previousPeriod / previousYear) and
- *     attaches `<measure>__compare` columns,
- *   - computes server-side totals (`selection.totals.groupings`, #1753) by
- *     re-running the selection per dimension subset, so matrix subtotals and
- *     the grand total use each measure's true aggregate.
- *
- * RLS/tenant scoping is NOT handled here — it is enforced inside the strategy
- * via the StrategyContext read-scope hook (D-C). This layer is pure query
- * shaping + arithmetic.
- */
 /** AND two optional FilterConditions into one (MongoDB-style). */
 declare function combineFilters(a?: FilterCondition, b?: FilterCondition): FilterCondition | undefined;
 /**
@@ -518,7 +641,16 @@ declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derive
 declare function shiftRange(range: [string, string], kind: CompareTo['kind']): [string, string];
 declare class DatasetExecutor {
     private readonly service;
-    constructor(service: IAnalyticsService);
+    private readonly orderLabels?;
+    /**
+     * @param service - The analytics service the executor issues its queries to.
+     * @param orderLabels - Optional sort-key label hook (#3680). When provided,
+     *   an order key naming a label-bearing (`select`/`lookup`) dimension sorts
+     *   by its display label instead of the stored value. Omit to sort by stored
+     *   values everywhere (e.g. the draft-preview path, whose seed rows already
+     *   carry display names).
+     */
+    constructor(service: IAnalyticsService, orderLabels?: OrderLabelResolver | undefined);
     /**
      * Execute a dataset selection and return the shaped rows (+ field metadata).
      *
@@ -526,7 +658,7 @@ declare class DatasetExecutor {
      *   underlying `IAnalyticsService.query` so the tenant/RLS read scope is
      *   applied per request (ADR-0021 D-C).
      */
-    execute(compiled: CompiledDataset, selection: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
+    execute(compiledInput: CompiledDataset, selectionInput: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     private executeSelection;
     private buildQuery;
     private runCompare;
@@ -652,10 +784,83 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     readonly priority = 20;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
     execute(query: AnalyticsQuery, ctx: StrategyContext): Promise<AnalyticsResult>;
+    /**
+     * Render a REPRESENTATIVE SQL string for an ObjectQL aggregate query.
+     *
+     * This path executes through `engine.aggregate()`, not raw SQL, so the string
+     * is documentation rather than the literal statement — but it must be an
+     * honest account of what the query does, because dataset responses echo it
+     * and authors read it to verify their widget options landed (#3588). It
+     * therefore renders date bucketing (`date_trunc`), the WHERE predicate,
+     * ordering, and the row window.
+     *
+     * Filter VALUES are rendered as `$n` placeholders and returned in `params`,
+     * never inlined: the echoed statement travels to the browser, and a filter
+     * comparand can carry tenant data.
+     */
     generateSql(query: AnalyticsQuery, ctx: StrategyContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
+    /**
+     * ADR-0021 D-C (#3597) — AND the object's read scope (tenant + RLS) into the
+     * filter handed to `engine.aggregate`.
+     *
+     * This path used to drop the scope entirely, and the engine could not make up
+     * for it: the aggregate bridge passes no `ExecutionContext`, so the security
+     * middleware's principal-less fall-open skipped its own RLS injection. Both
+     * belts were off at once — an authenticated caller received aggregates
+     * computed over EVERY tenant's rows.
+     *
+     * Composed with `$and`, never by key merge: the query's own filter and the
+     * scope can name the SAME field (e.g. a dashboard filtering `organization_id`),
+     * and a spread would let caller input silently overwrite the security
+     * predicate. `$and` makes that structurally impossible.
+     */
+    private withReadScope;
+    /** Is `field` a resolved cross-object (relationship-traversal) reference? */
+    private isCrossObjectField;
+    /**
+     * Plan how to serve cross-object references on this join-less path (#3654).
+     *
+     * `engine.aggregate()` cannot join. A cross-object DIMENSION within a
+     * supported envelope is served by an FK-expand (`executeCrossObject`): group
+     * the base aggregate on the lookup FK, resolve the FK to the related attribute
+     * with a SCOPED read, re-bucket in memory. Returns `null` for a base-only
+     * query (direct path), a plan for an in-envelope cross-object query.
+     *
+     * THROWS for anything outside the envelope — a cross-object MEASURE or FILTER
+     * (needs a real join to evaluate), 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.
+     *
+     * Detection is on RESOLVED field names, so a dotted dimension the cube
+     * flattens to a real column is treated as base, not cross-object.
+     */
+    private planCrossObject;
+    /**
+     * Serve a cross-object-dimension query by FK-expand (#3654). The pure
+     * re-bucketing step lives in `cross-object-rebucket.ts`.
+     */
+    private executeCrossObject;
+    /**
+     * Resolve `fkValues` (ids of `refObject`) to their `attr` values, applying the
+     * referenced object's OWN read scope (#3654 / #3602). Reuses the aggregate
+     * bridge — `group by (id, attr)` is one row per record. Ids the scope hides
+     * are simply absent from the map (⇒ RESTRICTED bucket downstream).
+     */
+    private resolveFkAttr;
+    /**
+     * Render one normalized filter as a display SQL predicate for `generateSql`.
+     *
+     * Mirrors `NativeSQLStrategy.buildFilterClause`'s operator vocabulary so the
+     * two previews read alike, but binds through `coerceFilterValueForObjectQL`:
+     * the comparand shown is the one THIS path actually hands the engine (a real
+     * boolean, not SQL's 1/0). Returns null for an operator/value combination
+     * that carries no predicate, matching `execute()`, which drops it too.
+     */
+    private buildFilterClauseSql;
     /**
      * Resolve a member ref to a `{ sql, type? }` definition.
      *
@@ -671,9 +876,65 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private lookupMember;
     private resolveFieldName;
     private resolveMeasureAggregation;
+    /**
+     * AND one more operand onto `filter[field]`, merging operator objects rather
+     * than overwriting them. Returns a standalone conjunct when the two cannot
+     * share one entry, or `null` when the merge absorbed the operand.
+     *
+     * Every predicate this strategy contributes goes through here — the caller's
+     * `where` and the time-dimension `dateRange` alike. Two operands on one field
+     * are the normal case (`{$gte}` from a `where` plus `{$gte,$lte}` from a
+     * window on `close_date`), and a plain assignment would keep only the last:
+     * that is how a range used to lose a bound.
+     *
+     * Spreading is sound only while the operands name DIFFERENT operators. Where
+     * they collide — two `$gte` bounds on one field, which a window makes routine
+     * and which a `where` can already produce on its own through `$and` — the
+     * spread keeps whichever came last and WIDENS the query. Same for a bare
+     * equality meeting an operator object: neither can absorb the other. Those
+     * are handed back for the caller to AND in separately, so the engine
+     * intersects them instead of the strategy picking a winner.
+     */
+    private mergeFilterOperand;
+    /**
+     * Lower `timeDimensions[].dateRange` into resolved-field bounds (#3650).
+     *
+     * `dateRange` states a WINDOW on a time dimension; it is a SIBLING of `where`,
+     * never folded into it. `normalizeAnalyticsFilters` reads only `where`, so
+     * this path used to drop the window on the floor — no error, just every row
+     * ever recorded. Nor is that a corner case: `NativeSQLStrategy.canHandle`
+     * declines any query carrying a `granularity`, so a date-bucketed trend lands
+     * 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.
+     *
+     * 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
+     * STORAGE coercion happens here, deliberately: `NativeSQLStrategy` needs
+     * `coerceTemporal` because it binds into raw SQL and had to learn that a
+     * SQLite `Field.datetime` is an INTEGER epoch (#2034); this path goes through
+     * `engine.aggregate()`, where the driver's own CRUD filter coercion applies —
+     * the very coercion that already makes a `where` bound on that same column
+     * work today.
+     *
+     * A bare-string `dateRange` degenerates to the single point `[s, s]`, matching
+     * `NativeSQLStrategy`. Relative phrases ("Last 7 days") are NOT resolved here;
+     * neither SQL path resolves them, and inventing a second interpretation on the
+     * driver-independent path is how the two would drift apart again.
+     *
+     * An oddly-sized array (the schema types `dateRange` as a plain `string[]`)
+     * takes its first two entries, a one-entry array degenerating to a point.
+     * `NativeSQLStrategy` drops such a window entirely — but "drop the window"
+     * means "plot all of history", which is the very failure this fixes, so the
+     * fallback here errs toward the narrower query instead.
+     */
+    private dateRangeBounds;
     private convertFilter;
     private extractObjectName;
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, type RelationshipTarget, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };
+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 };