@objectstack/service-analytics 7.9.0 → 8.0.0

package/dist/index.d.cts

@@ -1,6 +1,8 @@
-import { IAnalyticsService, Logger, DriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, CubeMeta, StrategyContext } from '@objectstack/spec/contracts';
-export { AnalyticsStrategy, DriverCapabilities, StrategyContext } from '@objectstack/spec/contracts';
-import { Cube } from '@objectstack/spec/data';
+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 { Cube, FilterCondition } from '@objectstack/spec/data';
+import { ExecutionContext } from '@objectstack/spec/kernel';
+import { Dataset } from '@objectstack/spec/ui';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -52,6 +54,35 @@ declare class CubeRegistry {
     private fieldTypeToDimensionType;
 }
 
+interface DerivedMeasureSpec {
+    name: string;
+    op: 'ratio' | 'sum' | 'difference' | 'product';
+    of: string[];
+}
+interface CompiledDataset {
+    /** The Cube the dataset compiles to (consumed by the strategy chain). */
+    cube: Cube;
+    /**
+     * Relationship names declared in `include`. The join allowlist (D-C):
+     * the NativeSQLStrategy rejects any join alias not in this set.
+     */
+    allowedRelationships: Set<string>;
+    /** Derived measures, computed post-aggregation by the executor (Q1). */
+    derived: DerivedMeasureSpec[];
+    /** Definition-level filter (the dataset's intrinsic scope). */
+    filter?: FilterCondition;
+    /** Per-measure scoped filters, keyed by measure name (applied by executor). */
+    measureFilters: Record<string, FilterCondition>;
+}
+/**
+ * Resolves a relationship name on a base object to the related object/table
+ * name, using the runtime's object graph. Optional: when omitted the compiler
+ * trusts the declared `include` names (the NativeSQLStrategy convention assumes
+ * the relationship name equals the related table name).
+ */
+type RelationshipResolver = (baseObject: string, relationshipName: string) => string | undefined;
+declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolver): CompiledDataset;
+
 /**
  * Configuration for AnalyticsService.
  */
@@ -93,6 +124,30 @@ interface AnalyticsServiceConfig {
      * They are merged with the built-in strategies and sorted by priority.
      */
     strategies?: AnalyticsStrategy[];
+    /**
+     * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). Supplied
+     * by the runtime that owns the sharing middleware; receives the current
+     * request's ExecutionContext and returns the RLS `FilterCondition` for the
+     * object (exactly what `RLSCompiler` emits). The service binds the active
+     * context per query and the strategy compiles the filter into alias-qualified
+     * SQL injected into every base and joined table.
+     */
+    getReadScope?: (objectName: string, context?: ExecutionContext) => FilterCondition | null | undefined;
+    /**
+     * ADR-0021 D-C — join allowlist per cube (the dataset's declared `include`).
+     * Joins outside this set are rejected by the strategy. Compiled datasets
+     * (via `queryDataset`/`registerDataset`) supply this automatically; this
+     * config hook is a fallback for legacy hand-authored cubes.
+     */
+    getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
+    /**
+     * ADR-0021 — optional object-graph resolver used when compiling datasets:
+     * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
+     * provided, `queryDataset` validates that every declared `include` exists.
+     */
+    relationshipResolver?: RelationshipResolver;
+    /** Pre-defined datasets to compile + register at construction (ADR-0021). */
+    datasets?: Dataset[];
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -114,14 +169,40 @@ interface AnalyticsServiceConfig {
  */
 declare class AnalyticsService implements IAnalyticsService {
     private readonly strategies;
-    private readonly strategyCtx;
+    /** Context-independent part of the StrategyContext (no per-request scope). */
+    private readonly baseCtx;
+    /** Context-aware read-scope provider (bound to the request's context per call). */
+    private readonly readScopeProvider?;
+    /** Compiled datasets by name — feeds the join allowlist (D-C) and queryDataset. */
+    private readonly datasetRegistry;
+    /** Optional object-graph resolver used when compiling datasets. */
+    private readonly relationshipResolver?;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
+    /**
+     * Build a per-call StrategyContext that binds the read-scope provider to the
+     * current request's ExecutionContext (ADR-0021 D-C). The strategy then sees a
+     * `getReadScope(objectName)` that already knows the active tenant.
+     */
+    private callCtx;
     /**
      * Execute an analytical query by delegating to the first capable strategy.
      */
-    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+    query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    /**
+     * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
+     * can be queried by name. Idempotent (re-registering overwrites). Returns the
+     * compiled dataset.
+     */
+    registerDataset(dataset: Dataset): CompiledDataset;
+    /**
+     * Execute a semantic-layer dataset (ADR-0021). Compiles the dataset (saved or
+     * inline draft — Studio preview), registers its Cube + join allowlist, then
+     * runs the selection through the `DatasetExecutor` with the request context so
+     * tenant/RLS scoping (D-C) is applied. See {@link IAnalyticsService.queryDataset}.
+     */
+    queryDataset(dataset: Dataset, selection: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
      * Get cube metadata for discovery.
      */
@@ -129,7 +210,7 @@ declare class AnalyticsService implements IAnalyticsService {
     /**
      * Generate SQL for a query without executing it (dry-run).
      */
-    generateSql(query: AnalyticsQuery): Promise<{
+    generateSql(query: AnalyticsQuery, context?: ExecutionContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
@@ -181,6 +262,20 @@ interface AnalyticsServicePluginOptions {
         }>;
         filter?: Record<string, unknown>;
     }) => Promise<Record<string, unknown>[]>;
+    /**
+     * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). The
+     * runtime supplies this from its sharing middleware so the analytics raw-SQL
+     * path cannot bypass tenant isolation. Receives the request's ExecutionContext
+     * and returns the RLS `FilterCondition` for the object (what `RLSCompiler`
+     * emits). When omitted, the plugin auto-bridges to a registered `'security'`
+     * service exposing `getReadFilter(object, context)` if one is present.
+     */
+    getReadScope?: (objectName: string, context?: ExecutionContext) => FilterCondition | null | undefined;
+    /**
+     * ADR-0021 D-C — join allowlist per cube (the dataset's declared `include`).
+     * Typically wired from the dataset registry's compiled `allowedRelationships`.
+     */
+    getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
     /** Enable debug logging. */
     debug?: boolean;
 }
@@ -225,6 +320,59 @@ declare class AnalyticsServicePlugin implements Plugin {
     destroy(): Promise<void>;
 }
 
+/** @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.
+ *
+ * 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;
+/**
+ * Evaluate derived measures on each aggregated row, mutating a shallow copy.
+ * Division by zero (and missing operands) yields `null` rather than Infinity/NaN.
+ */
+declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derived: DerivedMeasureSpec[]): 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 {
+    private readonly service;
+    constructor(service: IAnalyticsService);
+    /**
+     * Execute a dataset selection and return the shaped rows (+ field metadata).
+     *
+     * @param context - The request's ExecutionContext, threaded into every
+     *   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>;
+    private buildQuery;
+    private runCompare;
+}
+/**
+ * Left-merge `extra` rows onto `base` rows by their dimension-key tuple,
+ * copying the listed value columns. Rows in `extra` with no base match are
+ * appended (outer-ish merge so comparison-only buckets still surface).
+ */
+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): {
+    sql: string;
+    params: unknown[];
+};
+
 /**
  * NativeSQLStrategy — Priority 1
  *
@@ -241,6 +389,16 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
         sql: string;
         params: unknown[];
     }>;
+    /**
+     * ADR-0021 D-C — inject an object's read scope (tenant + RLS predicate) into
+     * the WHERE clause. The scope is a canonical `FilterCondition` (what the
+     * RLSCompiler emits); `compileScopedFilterToSql` turns it into alias-qualified,
+     * parameterized SQL (fail-closed — it throws rather than drop a predicate).
+     * The `?` placeholders are then renumbered into the strategy's `$N` scheme.
+     * No-op when the runtime provides no scope hook (the caller is then
+     * responsible for isolation — see contract note).
+     */
+    private applyReadScope;
     /**
      * Resolve a dimension/measure/filter SQL expression that may reference a
      * related table via dot notation (e.g. `account.industry`).
@@ -318,4 +476,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, CubeRegistry, NativeSQLStrategy, ObjectQLStrategy };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, shiftRange };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { IAnalyticsService, Logger, DriverCapabilities, AnalyticsStrategy, AnalyticsQuery, AnalyticsResult, CubeMeta, StrategyContext } from '@objectstack/spec/contracts';
-export { AnalyticsStrategy, DriverCapabilities, StrategyContext } from '@objectstack/spec/contracts';
-import { Cube } from '@objectstack/spec/data';
+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 { Cube, FilterCondition } from '@objectstack/spec/data';
+import { ExecutionContext } from '@objectstack/spec/kernel';
+import { Dataset } from '@objectstack/spec/ui';
 import { Plugin, PluginContext } from '@objectstack/core';
 
 /**
@@ -52,6 +54,35 @@ declare class CubeRegistry {
     private fieldTypeToDimensionType;
 }
 
+interface DerivedMeasureSpec {
+    name: string;
+    op: 'ratio' | 'sum' | 'difference' | 'product';
+    of: string[];
+}
+interface CompiledDataset {
+    /** The Cube the dataset compiles to (consumed by the strategy chain). */
+    cube: Cube;
+    /**
+     * Relationship names declared in `include`. The join allowlist (D-C):
+     * the NativeSQLStrategy rejects any join alias not in this set.
+     */
+    allowedRelationships: Set<string>;
+    /** Derived measures, computed post-aggregation by the executor (Q1). */
+    derived: DerivedMeasureSpec[];
+    /** Definition-level filter (the dataset's intrinsic scope). */
+    filter?: FilterCondition;
+    /** Per-measure scoped filters, keyed by measure name (applied by executor). */
+    measureFilters: Record<string, FilterCondition>;
+}
+/**
+ * Resolves a relationship name on a base object to the related object/table
+ * name, using the runtime's object graph. Optional: when omitted the compiler
+ * trusts the declared `include` names (the NativeSQLStrategy convention assumes
+ * the relationship name equals the related table name).
+ */
+type RelationshipResolver = (baseObject: string, relationshipName: string) => string | undefined;
+declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolver): CompiledDataset;
+
 /**
  * Configuration for AnalyticsService.
  */
@@ -93,6 +124,30 @@ interface AnalyticsServiceConfig {
      * They are merged with the built-in strategies and sorted by priority.
      */
     strategies?: AnalyticsStrategy[];
+    /**
+     * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). Supplied
+     * by the runtime that owns the sharing middleware; receives the current
+     * request's ExecutionContext and returns the RLS `FilterCondition` for the
+     * object (exactly what `RLSCompiler` emits). The service binds the active
+     * context per query and the strategy compiles the filter into alias-qualified
+     * SQL injected into every base and joined table.
+     */
+    getReadScope?: (objectName: string, context?: ExecutionContext) => FilterCondition | null | undefined;
+    /**
+     * ADR-0021 D-C — join allowlist per cube (the dataset's declared `include`).
+     * Joins outside this set are rejected by the strategy. Compiled datasets
+     * (via `queryDataset`/`registerDataset`) supply this automatically; this
+     * config hook is a fallback for legacy hand-authored cubes.
+     */
+    getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
+    /**
+     * ADR-0021 — optional object-graph resolver used when compiling datasets:
+     * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
+     * provided, `queryDataset` validates that every declared `include` exists.
+     */
+    relationshipResolver?: RelationshipResolver;
+    /** Pre-defined datasets to compile + register at construction (ADR-0021). */
+    datasets?: Dataset[];
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -114,14 +169,40 @@ interface AnalyticsServiceConfig {
  */
 declare class AnalyticsService implements IAnalyticsService {
     private readonly strategies;
-    private readonly strategyCtx;
+    /** Context-independent part of the StrategyContext (no per-request scope). */
+    private readonly baseCtx;
+    /** Context-aware read-scope provider (bound to the request's context per call). */
+    private readonly readScopeProvider?;
+    /** Compiled datasets by name — feeds the join allowlist (D-C) and queryDataset. */
+    private readonly datasetRegistry;
+    /** Optional object-graph resolver used when compiling datasets. */
+    private readonly relationshipResolver?;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
+    /**
+     * Build a per-call StrategyContext that binds the read-scope provider to the
+     * current request's ExecutionContext (ADR-0021 D-C). The strategy then sees a
+     * `getReadScope(objectName)` that already knows the active tenant.
+     */
+    private callCtx;
     /**
      * Execute an analytical query by delegating to the first capable strategy.
      */
-    query(query: AnalyticsQuery): Promise<AnalyticsResult>;
+    query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
+    /**
+     * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
+     * can be queried by name. Idempotent (re-registering overwrites). Returns the
+     * compiled dataset.
+     */
+    registerDataset(dataset: Dataset): CompiledDataset;
+    /**
+     * Execute a semantic-layer dataset (ADR-0021). Compiles the dataset (saved or
+     * inline draft — Studio preview), registers its Cube + join allowlist, then
+     * runs the selection through the `DatasetExecutor` with the request context so
+     * tenant/RLS scoping (D-C) is applied. See {@link IAnalyticsService.queryDataset}.
+     */
+    queryDataset(dataset: Dataset, selection: DatasetSelection, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
      * Get cube metadata for discovery.
      */
@@ -129,7 +210,7 @@ declare class AnalyticsService implements IAnalyticsService {
     /**
      * Generate SQL for a query without executing it (dry-run).
      */
-    generateSql(query: AnalyticsQuery): Promise<{
+    generateSql(query: AnalyticsQuery, context?: ExecutionContext): Promise<{
         sql: string;
         params: unknown[];
     }>;
@@ -181,6 +262,20 @@ interface AnalyticsServicePluginOptions {
         }>;
         filter?: Record<string, unknown>;
     }) => Promise<Record<string, unknown>[]>;
+    /**
+     * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). The
+     * runtime supplies this from its sharing middleware so the analytics raw-SQL
+     * path cannot bypass tenant isolation. Receives the request's ExecutionContext
+     * and returns the RLS `FilterCondition` for the object (what `RLSCompiler`
+     * emits). When omitted, the plugin auto-bridges to a registered `'security'`
+     * service exposing `getReadFilter(object, context)` if one is present.
+     */
+    getReadScope?: (objectName: string, context?: ExecutionContext) => FilterCondition | null | undefined;
+    /**
+     * ADR-0021 D-C — join allowlist per cube (the dataset's declared `include`).
+     * Typically wired from the dataset registry's compiled `allowedRelationships`.
+     */
+    getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
     /** Enable debug logging. */
     debug?: boolean;
 }
@@ -225,6 +320,59 @@ declare class AnalyticsServicePlugin implements Plugin {
     destroy(): Promise<void>;
 }
 
+/** @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.
+ *
+ * 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;
+/**
+ * Evaluate derived measures on each aggregated row, mutating a shallow copy.
+ * Division by zero (and missing operands) yields `null` rather than Infinity/NaN.
+ */
+declare function evaluateDerivedMeasures(rows: Record<string, unknown>[], derived: DerivedMeasureSpec[]): 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 {
+    private readonly service;
+    constructor(service: IAnalyticsService);
+    /**
+     * Execute a dataset selection and return the shaped rows (+ field metadata).
+     *
+     * @param context - The request's ExecutionContext, threaded into every
+     *   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>;
+    private buildQuery;
+    private runCompare;
+}
+/**
+ * Left-merge `extra` rows onto `base` rows by their dimension-key tuple,
+ * copying the listed value columns. Rows in `extra` with no base match are
+ * appended (outer-ish merge so comparison-only buckets still surface).
+ */
+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): {
+    sql: string;
+    params: unknown[];
+};
+
 /**
  * NativeSQLStrategy — Priority 1
  *
@@ -241,6 +389,16 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
         sql: string;
         params: unknown[];
     }>;
+    /**
+     * ADR-0021 D-C — inject an object's read scope (tenant + RLS predicate) into
+     * the WHERE clause. The scope is a canonical `FilterCondition` (what the
+     * RLSCompiler emits); `compileScopedFilterToSql` turns it into alias-qualified,
+     * parameterized SQL (fail-closed — it throws rather than drop a predicate).
+     * The `?` placeholders are then renumbered into the strategy's `$N` scheme.
+     * No-op when the runtime provides no scope hook (the caller is then
+     * responsible for isolation — see contract note).
+     */
+    private applyReadScope;
     /**
      * Resolve a dimension/measure/filter SQL expression that may reference a
      * related table via dot notation (e.g. `account.industry`).
@@ -318,4 +476,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, CubeRegistry, NativeSQLStrategy, ObjectQLStrategy };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, shiftRange };