@objectstack/service-analytics 8.0.1 → 9.0.0

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,14 @@ 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;
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -182,6 +257,8 @@ 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?;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -495,4 +572,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,14 @@ 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;
 }
 /**
  * AnalyticsService — Multi-driver analytics orchestrator.
@@ -182,6 +257,8 @@ 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?;
     readonly cubeRegistry: CubeRegistry;
     private readonly logger;
     constructor(config?: AnalyticsServiceConfig);
@@ -495,4 +572,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.js

@@ -596,12 +596,22 @@ var ObjectQLStrategy = class {
   async execute(query, ctx) {
     const cube = ctx.getCube(query.cube);
     const objectName = this.extractObjectName(cube);
+    const granByDim = /* @__PURE__ */ new Map();
+    for (const td of query.timeDimensions ?? []) {
+      if (td.granularity) granByDim.set(td.dimension, td.granularity);
+    }
     const groupBy = [];
     if (query.dimensions && query.dimensions.length > 0) {
       for (const dim of query.dimensions) {
-        groupBy.push(this.resolveFieldName(cube, dim, "dimension"));
+        const field = this.resolveFieldName(cube, dim, "dimension");
+        const gran = granByDim.get(dim);
+        groupBy.push(gran ? { field, dateGranularity: gran } : field);
+        granByDim.delete(dim);
       }
     }
+    for (const [dim, gran] of granByDim) {
+      groupBy.push({ field: this.resolveFieldName(cube, dim, "dimension"), dateGranularity: gran });
+    }
     const aggregations = [];
     if (query.measures && query.measures.length > 0) {
       for (const measure of query.measures) {
@@ -614,10 +624,16 @@ var ObjectQLStrategy = class {
     if (normalizedFilters.length > 0) {
       for (const f of normalizedFilters) {
         const fieldName = this.resolveFieldName(cube, f.member, "any");
-        filter[fieldName] = this.convertFilter(f.operator, f.values);
+        const converted = this.convertFilter(f.operator, f.values);
+        const existing = filter[fieldName];
+        const mergeable = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+        filter[fieldName] = mergeable(existing) && mergeable(converted) ? { ...existing, ...converted } : converted;
       }
     }
     const rows = await ctx.executeAggregate(objectName, {
+      // Structured groupBy items ({field, dateGranularity}) pass through the
+      // executeAggregate bridge to engine.aggregate, which buckets them. The
+      // contract types groupBy as string[]; the cast carries the richer shape.
       groupBy: groupBy.length > 0 ? groupBy : void 0,
       aggregations: aggregations.length > 0 ? aggregations : void 0,
       filter: Object.keys(filter).length > 0 ? filter : void 0
@@ -1030,7 +1046,17 @@ var DatasetExecutor = class {
       timezone: opts.selection.timezone ?? "UTC"
     };
     if (opts.where) q.where = opts.where;
-    if (opts.selection.timeDimensions) q.timeDimensions = opts.selection.timeDimensions;
+    const selTimeDims = opts.selection.timeDimensions ?? [];
+    const selDims = new Set(selTimeDims.map((t) => t.dimension));
+    const explicitTimeDims = [];
+    for (const name of opts.dimensions) {
+      const cd = compiled.cube.dimensions[name];
+      if (cd?.type === "time" && cd.granularities?.length === 1 && !selDims.has(name)) {
+        explicitTimeDims.push({ dimension: name, granularity: String(cd.granularities[0]) });
+      }
+    }
+    const mergedTimeDims = [...selTimeDims, ...explicitTimeDims];
+    if (mergedTimeDims.length > 0) q.timeDimensions = mergedTimeDims;
     if (opts.selection.order) q.order = opts.selection.order;
     if (opts.selection.limit != null) q.limit = opts.selection.limit;
     if (opts.selection.offset != null) q.offset = opts.selection.offset;
@@ -1085,6 +1111,88 @@ function mergeByDimensions(base, extra, dimensions, valueColumns) {
   return base;
 }
 
+// src/dimension-labels.ts
+var LOOKUP_TYPES = /* @__PURE__ */ new Set(["lookup", "master_detail"]);
+var pad = (n) => String(n).padStart(2, "0");
+function formatDateBucket(value, granularity) {
+  if (value == null || value instanceof Date === false) {
+    if (typeof value !== "number" && typeof value !== "string") return value;
+  }
+  let d;
+  if (value instanceof Date) d = value;
+  else if (typeof value === "number") d = new Date(value);
+  else {
+    const s = String(value).trim();
+    d = /^\d+$/.test(s) ? new Date(Number(s) < 1e12 ? Number(s) * 1e3 : Number(s)) : new Date(s);
+  }
+  if (Number.isNaN(d.getTime())) return value;
+  const y = d.getUTCFullYear();
+  const m = d.getUTCMonth();
+  switch (granularity) {
+    case "year":
+      return String(y);
+    case "quarter":
+      return `${y}-Q${Math.floor(m / 3) + 1}`;
+    case "month":
+      return `${y}-${pad(m + 1)}`;
+    case "week":
+    case "day":
+    default:
+      return `${y}-${pad(m + 1)}-${pad(d.getUTCDate())}`;
+  }
+}
+async function resolveDimensionLabels(baseObject, dims, rows, deps) {
+  if (!rows.length || !dims.length) return;
+  const fields = deps.getObjectFields(baseObject);
+  if (!fields) return;
+  for (const dim of dims) {
+    const meta = fields[dim.field];
+    if (dim.type === "date" || meta && meta.type === "date") {
+      for (const row of rows) {
+        const formatted = formatDateBucket(row[dim.name], dim.dateGranularity);
+        if (formatted != null) row[dim.name] = formatted;
+      }
+      continue;
+    }
+    if (!meta) continue;
+    if (Array.isArray(meta.options) && meta.options.length > 0) {
+      const labelByValue = /* @__PURE__ */ new Map();
+      for (const opt of meta.options) {
+        if (opt && opt.label != null) labelByValue.set(opt.value, String(opt.label));
+      }
+      if (labelByValue.size === 0) continue;
+      for (const row of rows) {
+        const raw = row[dim.name];
+        const label = labelByValue.get(raw);
+        if (label != null) row[dim.name] = label;
+      }
+      continue;
+    }
+    if (meta.type && LOOKUP_TYPES.has(meta.type) && meta.reference) {
+      const ids = Array.from(
+        new Set(rows.map((r) => r[dim.name]).filter((v) => v != null))
+      );
+      if (ids.length === 0) continue;
+      const labelById = await deps.fetchRecordLabels(meta.reference, ids);
+      if (!labelById || labelById.size === 0) continue;
+      for (const row of rows) {
+        const label = labelById.get(row[dim.name]);
+        if (label != null) row[dim.name] = label;
+      }
+    }
+  }
+}
+function pickDisplayField(fields) {
+  if (!fields) return void 0;
+  for (const preferred of ["name", "title", "label"]) {
+    if (fields[preferred]) return preferred;
+  }
+  for (const [name, meta] of Object.entries(fields)) {
+    if (meta.type === "text" || meta.type === "string") return name;
+  }
+  return void 0;
+}
+
 // src/analytics-service.ts
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
@@ -1102,6 +1210,7 @@ var AnalyticsService = class {
     }
     this.readScopeProvider = config.getReadScope;
     this.relationshipResolver = config.relationshipResolver;
+    this.labelResolver = config.labelResolver;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -1226,7 +1335,27 @@ var AnalyticsService = class {
   async queryDataset(dataset, selection, context) {
     const compiled = this.registerDataset(dataset);
     this.logger.debug(`[Analytics] queryDataset "${dataset.name}" (object=${dataset.object}, include=${(dataset.include ?? []).join(",") || "\u2014"})`);
-    return new DatasetExecutor(this).execute(compiled, selection, context);
+    const result = await new DatasetExecutor(this).execute(compiled, selection, context);
+    if (this.labelResolver && selection.dimensions?.length) {
+      const dims = selection.dimensions.map((name) => dataset.dimensions?.find((d) => d.name === name)).filter((d) => !!d?.field).map((d) => ({ name: d.name, field: d.field, type: d.type, dateGranularity: d.dateGranularity }));
+      if (dims.length) {
+        try {
+          await resolveDimensionLabels(dataset.object, dims, result.rows, this.labelResolver);
+        } catch (e) {
+          this.logger?.warn?.(`[Analytics] dimension label resolution failed for "${dataset.name}": ${String(e?.message ?? e)}`);
+        }
+      }
+    }
+    if (result.fields?.length && dataset.measures?.length) {
+      const measureByName = new Map(dataset.measures.map((m) => [m.name, m]));
+      for (const f of result.fields) {
+        const m = measureByName.get(f.name) ?? measureByName.get(f.name.replace(/__compare$/, ""));
+        if (!m) continue;
+        if (f.label == null && typeof m.label === "string") f.label = m.label;
+        if (f.format == null && m.format) f.format = m.format;
+      }
+    }
+    return result;
   }
   /**
    * Get cube metadata for discovery.
@@ -1526,6 +1655,31 @@ var AnalyticsServicePlugin = class {
       }
       return engine ? void 0 : relationshipName;
     };
+    const dataEngine = () => {
+      try {
+        const svc = ctx.getService("data");
+        return svc && typeof svc.getObject === "function" ? svc : void 0;
+      } catch {
+        return void 0;
+      }
+    };
+    const labelResolver = {
+      getObjectFields: (objectName) => dataEngine()?.getObject?.(objectName)?.fields,
+      fetchRecordLabels: async (targetObject, ids) => {
+        const map = /* @__PURE__ */ new Map();
+        const displayField = pickDisplayField(dataEngine()?.getObject?.(targetObject)?.fields);
+        if (!displayField || !executeAggregate || ids.length === 0) return map;
+        const rows = await executeAggregate(targetObject, {
+          groupBy: ["id", displayField],
+          aggregations: [{ field: "id", method: "count", alias: "_c" }],
+          filter: { id: { $in: ids } }
+        });
+        for (const r of rows) {
+          if (r.id != null && r[displayField] != null) map.set(r.id, String(r[displayField]));
+        }
+        return map;
+      }
+    };
     const config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
@@ -1535,7 +1689,8 @@ var AnalyticsServicePlugin = class {
       fallbackService,
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
-      relationshipResolver
+      relationshipResolver,
+      labelResolver
     };
     if (autoBridgedReadScope) {
       ctx.logger.info('[Analytics] Auto-bridged getReadScope \u2192 "security" service (getReadFilter)');
@@ -1586,6 +1741,8 @@ export {
   compileScopedFilterToSql,
   evaluateDerivedMeasures,
   mergeByDimensions,
+  pickDisplayField,
+  resolveDimensionLabels,
   shiftRange
 };
 //# sourceMappingURL=index.js.map