@objectstack/service-analytics 8.0.1 → 9.0.1

package/dist/index.d.cts

@@ -83,6 +83,73 @@ interface CompiledDataset {
 type RelationshipResolver = (baseObject: string, relationshipName: string) => string | undefined;
 declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolver): CompiledDataset;
 
+/**
+ * Dimension display-label resolution (ADR-0021).
+ *
+ * Analytics groups by the raw stored value of a dimension field. For two field
+ * kinds that value is NOT human-readable:
+ *
+ *  - **select** — grouped by the stored option `value` (e.g. `backlog`), but the
+ *    user-facing text is the option `label` (e.g. `Backlog`).
+ *  - **lookup / master_detail** — grouped by the foreign-key `id` (e.g.
+ *    `8eqtuKI4G9IhUsPS`), but the user-facing text is the related record's
+ *    display field (its name/title).
+ *
+ * `resolveDimensionLabels` post-processes the result rows IN PLACE, replacing the
+ * raw value at `row[dimension.name]` with its display label when one is found.
+ * Unresolved values are left untouched so an orphaned id still renders as itself
+ * rather than blanking out. Date / number / plain-string dimensions are no-ops.
+ *
+ * The resolution LOGIC lives here (and is unit-tested); the low-level capabilities
+ * — 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;
+    /** Lookup / master_detail target object name. */
+    reference?: string;
+    /** Select options — the value→label source. */
+    options?: Array<{
+        value: unknown;
+        label?: string;
+    }>;
+}
+/** Capabilities the resolver needs from the runtime (injected by the plugin). */
+interface DimensionLabelDeps {
+    /** Return the field map for an object, or `undefined` if unknown. */
+    getObjectFields(objectName: string): Record<string, FieldMetaLite> | undefined;
+    /**
+     * 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.
+     */
+    fetchRecordLabels(targetObject: string, ids: unknown[]): Promise<Map<unknown, string>>;
+}
+/** Date-dimension granularity (mirrors the dataset `dateGranularity` enum). */
+type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * Replace raw dimension values with display labels, in place.
+ *
+ * @param baseObject - the dataset's base object (where the dimension fields live)
+ * @param dims - selected dimensions as `{ name, field, type?, dateGranularity? }`
+ *   (row key = `name`)
+ * @param rows - result rows, mutated in place
+ * @param deps - injected runtime capabilities
+ */
+declare function resolveDimensionLabels(baseObject: string, dims: Array<{
+    name: string;
+    field: string;
+    type?: string;
+    dateGranularity?: DateGranularity | string;
+}>, rows: Record<string, unknown>[], deps: DimensionLabelDeps): 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.
+ * Returns `undefined` when nothing suitable exists.
+ */
+declare function pickDisplayField(fields: Record<string, FieldMetaLite> | undefined): string | undefined;
+
 /**
  * Configuration for AnalyticsService.
  */
@@ -153,6 +220,24 @@ interface AnalyticsServiceConfig {
     relationshipResolver?: RelationshipResolver;
     /** Pre-defined datasets to compile + register at construction (ADR-0021). */
     datasets?: Dataset[];
+    /**
+     * ADR-0021 — resolve raw dimension values to human display labels. When
+     * provided, `queryDataset` post-processes result rows so a `select` dimension
+     * shows its option label (not the stored value) and a `lookup`/`master_detail`
+     * dimension shows the related record's display name (not the FK id). Injected
+     * by the plugin from the `data` engine; omit to keep raw values.
+     */
+    labelResolver?: DimensionLabelDeps;
+    /**
+     * ADR-0037 Phase 3 — draft data preview. Resolve the PENDING `seed` draft
+     * rows for an object (returns null when the object has no pending seed).
+     * When provided and `queryDataset` is called with `previewDrafts`, the
+     * selection is evaluated over these rows in memory instead of the engine —
+     * the Live Canvas charts real numbers from the drafted sample data, and
+     * because publish materializes the SAME seed, the numbers are continuous
+     * across the publish boundary. Reads only; never touches physical tables.
+     */
+    draftRowsResolver?: (objectName: string, context?: ExecutionContext) => Promise<Record<string, unknown>[] | null>;
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -182,6 +267,10 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly datasetRegistry;
     /** Optional object-graph resolver used when compiling datasets. */
     private readonly relationshipResolver?;
+    /** Optional dimension display-label resolver (select options / lookup names). */
+    private readonly labelResolver?;
+    /** ADR-0037 P3: pending-seed row resolver for draft data preview. */
+    private readonly draftRowsResolver?;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -207,6 +296,14 @@ declare class AnalyticsService implements IAnalyticsService {
     private resolveReadScopes;
     /**
      * Execute an analytical query by delegating to the first capable strategy.
+     *
+     * A strategy can discover only AT EXECUTION TIME that the underlying driver
+     * cannot serve it — the canonical case is NativeSQLStrategy on an in-memory
+     * driver, whose `execute()` returns null for raw SQL (the auto-bridge throws
+     * `RAW_SQL_UNSUPPORTED`). That is a capability miss, not a query error: fall
+     * back to the next capable strategy (e.g. ObjectQLStrategy over the
+     * aggregate bridge) instead of failing — or worse, fabricating empty rows.
+     * Any other error propagates untouched.
      */
     query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
@@ -221,7 +318,9 @@ declare class AnalyticsService implements IAnalyticsService {
      * 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>;
+    queryDataset(dataset: Dataset, selection: DatasetSelection, context?: ExecutionContext, options?: {
+        previewDrafts?: boolean;
+    }): Promise<AnalyticsResult>;
     /**
      * Get cube metadata for discovery.
      */
@@ -249,7 +348,9 @@ declare class AnalyticsService implements IAnalyticsService {
     /** Build a minimal Cube from the fields referenced by an AnalyticsQuery. */
     private inferCubeFromQuery;
     /**
-     * Walk the strategy chain and return the first strategy that can handle the query.
+     * Walk the strategy chain and return the first strategy that can handle the
+     * query. `skip` excludes strategies that already proved incapable at
+     * execution time (see {@link query}'s RAW_SQL_UNSUPPORTED fallback).
      */
     private resolveStrategy;
 }
@@ -495,4 +596,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-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 };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };

package/dist/index.d.ts

@@ -83,6 +83,73 @@ interface CompiledDataset {
 type RelationshipResolver = (baseObject: string, relationshipName: string) => string | undefined;
 declare function compileDataset(dataset: Dataset, resolver?: RelationshipResolver): CompiledDataset;
 
+/**
+ * Dimension display-label resolution (ADR-0021).
+ *
+ * Analytics groups by the raw stored value of a dimension field. For two field
+ * kinds that value is NOT human-readable:
+ *
+ *  - **select** — grouped by the stored option `value` (e.g. `backlog`), but the
+ *    user-facing text is the option `label` (e.g. `Backlog`).
+ *  - **lookup / master_detail** — grouped by the foreign-key `id` (e.g.
+ *    `8eqtuKI4G9IhUsPS`), but the user-facing text is the related record's
+ *    display field (its name/title).
+ *
+ * `resolveDimensionLabels` post-processes the result rows IN PLACE, replacing the
+ * raw value at `row[dimension.name]` with its display label when one is found.
+ * Unresolved values are left untouched so an orphaned id still renders as itself
+ * rather than blanking out. Date / number / plain-string dimensions are no-ops.
+ *
+ * The resolution LOGIC lives here (and is unit-tested); the low-level capabilities
+ * — 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;
+    /** Lookup / master_detail target object name. */
+    reference?: string;
+    /** Select options — the value→label source. */
+    options?: Array<{
+        value: unknown;
+        label?: string;
+    }>;
+}
+/** Capabilities the resolver needs from the runtime (injected by the plugin). */
+interface DimensionLabelDeps {
+    /** Return the field map for an object, or `undefined` if unknown. */
+    getObjectFields(objectName: string): Record<string, FieldMetaLite> | undefined;
+    /**
+     * 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.
+     */
+    fetchRecordLabels(targetObject: string, ids: unknown[]): Promise<Map<unknown, string>>;
+}
+/** Date-dimension granularity (mirrors the dataset `dateGranularity` enum). */
+type DateGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
+/**
+ * Replace raw dimension values with display labels, in place.
+ *
+ * @param baseObject - the dataset's base object (where the dimension fields live)
+ * @param dims - selected dimensions as `{ name, field, type?, dateGranularity? }`
+ *   (row key = `name`)
+ * @param rows - result rows, mutated in place
+ * @param deps - injected runtime capabilities
+ */
+declare function resolveDimensionLabels(baseObject: string, dims: Array<{
+    name: string;
+    field: string;
+    type?: string;
+    dateGranularity?: DateGranularity | string;
+}>, rows: Record<string, unknown>[], deps: DimensionLabelDeps): 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.
+ * Returns `undefined` when nothing suitable exists.
+ */
+declare function pickDisplayField(fields: Record<string, FieldMetaLite> | undefined): string | undefined;
+
 /**
  * Configuration for AnalyticsService.
  */
@@ -153,6 +220,24 @@ interface AnalyticsServiceConfig {
     relationshipResolver?: RelationshipResolver;
     /** Pre-defined datasets to compile + register at construction (ADR-0021). */
     datasets?: Dataset[];
+    /**
+     * ADR-0021 — resolve raw dimension values to human display labels. When
+     * provided, `queryDataset` post-processes result rows so a `select` dimension
+     * shows its option label (not the stored value) and a `lookup`/`master_detail`
+     * dimension shows the related record's display name (not the FK id). Injected
+     * by the plugin from the `data` engine; omit to keep raw values.
+     */
+    labelResolver?: DimensionLabelDeps;
+    /**
+     * ADR-0037 Phase 3 — draft data preview. Resolve the PENDING `seed` draft
+     * rows for an object (returns null when the object has no pending seed).
+     * When provided and `queryDataset` is called with `previewDrafts`, the
+     * selection is evaluated over these rows in memory instead of the engine —
+     * the Live Canvas charts real numbers from the drafted sample data, and
+     * because publish materializes the SAME seed, the numbers are continuous
+     * across the publish boundary. Reads only; never touches physical tables.
+     */
+    draftRowsResolver?: (objectName: string, context?: ExecutionContext) => Promise<Record<string, unknown>[] | null>;
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -182,6 +267,10 @@ declare class AnalyticsService implements IAnalyticsService {
     private readonly datasetRegistry;
     /** Optional object-graph resolver used when compiling datasets. */
     private readonly relationshipResolver?;
+    /** Optional dimension display-label resolver (select options / lookup names). */
+    private readonly labelResolver?;
+    /** ADR-0037 P3: pending-seed row resolver for draft data preview. */
+    private readonly draftRowsResolver?;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -207,6 +296,14 @@ declare class AnalyticsService implements IAnalyticsService {
     private resolveReadScopes;
     /**
      * Execute an analytical query by delegating to the first capable strategy.
+     *
+     * A strategy can discover only AT EXECUTION TIME that the underlying driver
+     * cannot serve it — the canonical case is NativeSQLStrategy on an in-memory
+     * driver, whose `execute()` returns null for raw SQL (the auto-bridge throws
+     * `RAW_SQL_UNSUPPORTED`). That is a capability miss, not a query error: fall
+     * back to the next capable strategy (e.g. ObjectQLStrategy over the
+     * aggregate bridge) instead of failing — or worse, fabricating empty rows.
+     * Any other error propagates untouched.
      */
     query(query: AnalyticsQuery, context?: ExecutionContext): Promise<AnalyticsResult>;
     /**
@@ -221,7 +318,9 @@ declare class AnalyticsService implements IAnalyticsService {
      * 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>;
+    queryDataset(dataset: Dataset, selection: DatasetSelection, context?: ExecutionContext, options?: {
+        previewDrafts?: boolean;
+    }): Promise<AnalyticsResult>;
     /**
      * Get cube metadata for discovery.
      */
@@ -249,7 +348,9 @@ declare class AnalyticsService implements IAnalyticsService {
     /** Build a minimal Cube from the fields referenced by an AnalyticsQuery. */
     private inferCubeFromQuery;
     /**
-     * Walk the strategy chain and return the first strategy that can handle the query.
+     * Walk the strategy chain and return the first strategy that can handle the
+     * query. `skip` excludes strategies that already proved incapable at
+     * execution time (see {@link query}'s RAW_SQL_UNSUPPORTED fallback).
      */
     private resolveStrategy;
 }
@@ -495,4 +596,4 @@ declare class ObjectQLStrategy implements AnalyticsStrategy {
     private buildFieldMeta;
 }
 
-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 };
+export { AnalyticsService, type AnalyticsServiceConfig, AnalyticsServicePlugin, type AnalyticsServicePluginOptions, type CompareTo, type CompiledDataset, CubeRegistry, DatasetExecutor, type DerivedMeasureSpec, type DimensionLabelDeps, type FieldMetaLite, NativeSQLStrategy, ObjectQLStrategy, type RelationshipResolver, combineFilters, compileDataset, compileScopedFilterToSql, evaluateDerivedMeasures, mergeByDimensions, pickDisplayField, resolveDimensionLabels, shiftRange };