@objectstack/service-analytics 9.0.0 → 9.0.1

package/dist/index.d.cts

@@ -228,6 +228,16 @@ interface AnalyticsServiceConfig {
      * 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.
@@ -259,6 +269,8 @@ declare class AnalyticsService implements IAnalyticsService {
     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);
@@ -284,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>;
     /**
@@ -298,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.
      */
@@ -326,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;
 }

package/dist/index.d.ts

@@ -228,6 +228,16 @@ interface AnalyticsServiceConfig {
      * 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.
@@ -259,6 +269,8 @@ declare class AnalyticsService implements IAnalyticsService {
     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);
@@ -284,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>;
     /**
@@ -298,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.
      */
@@ -326,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;
 }

package/dist/index.js

@@ -1193,6 +1193,160 @@ function pickDisplayField(fields) {
   return void 0;
 }
 
+// src/preview-evaluator.ts
+function compare(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+}
+function matchOp(value, op, expected) {
+  switch (op) {
+    case "$eq":
+      return value === expected || String(value) === String(expected);
+    case "$ne":
+      return !(value === expected || String(value) === String(expected));
+    case "$gt":
+      return value != null && compare(value, expected) > 0;
+    case "$gte":
+      return value != null && compare(value, expected) >= 0;
+    case "$lt":
+      return value != null && compare(value, expected) < 0;
+    case "$lte":
+      return value != null && compare(value, expected) <= 0;
+    case "$in":
+      return Array.isArray(expected) && expected.some((e) => value === e || String(value) === String(e));
+    case "$nin":
+      return Array.isArray(expected) && !expected.some((e) => value === e || String(value) === String(e));
+    case "$contains":
+      return String(value ?? "").toLowerCase().includes(String(expected ?? "").toLowerCase());
+    default:
+      return true;
+  }
+}
+function matchesWhere(row, where) {
+  if (!where) return true;
+  for (const [key, cond] of Object.entries(where)) {
+    if (key === "$and") {
+      if (!cond.every((c) => matchesWhere(row, c))) return false;
+    } else if (key === "$or") {
+      if (!cond.some((c) => matchesWhere(row, c))) return false;
+    } else if (key === "$not") {
+      if (matchesWhere(row, cond)) return false;
+    } else if (cond !== null && typeof cond === "object" && !Array.isArray(cond)) {
+      for (const [op, expected] of Object.entries(cond)) {
+        if (!matchOp(row[key], op, expected)) return false;
+      }
+    } else if (!(row[key] === cond || String(row[key]) === String(cond))) {
+      return false;
+    }
+  }
+  return true;
+}
+function bucketDate(value, granularity) {
+  const d = new Date(String(value));
+  if (Number.isNaN(d.getTime())) return null;
+  const y = d.getUTCFullYear();
+  const m = `${d.getUTCMonth() + 1}`.padStart(2, "0");
+  const day = `${d.getUTCDate()}`.padStart(2, "0");
+  switch (granularity) {
+    case "year":
+      return `${y}`;
+    case "quarter":
+      return `${y}-Q${Math.floor(d.getUTCMonth() / 3) + 1}`;
+    case "month":
+      return `${y}-${m}`;
+    case "week": {
+      const monday = new Date(d);
+      const dow = (d.getUTCDay() + 6) % 7;
+      monday.setUTCDate(d.getUTCDate() - dow);
+      return monday.toISOString().slice(0, 10);
+    }
+    case "day":
+    default:
+      return `${y}-${m}-${day}`;
+  }
+}
+function aggregate(rows, metricType, field) {
+  if (metricType === "count" || field === "*") {
+    if (metricType === "countDistinct") {
+      return new Set(rows.map((r) => r[field]).filter((v) => v != null)).size;
+    }
+    return rows.length;
+  }
+  const nums = rows.map((r) => Number(r[field])).filter((n) => Number.isFinite(n));
+  switch (metricType) {
+    case "countDistinct":
+      return new Set(rows.map((r) => r[field]).filter((v) => v != null)).size;
+    case "sum":
+      return nums.reduce((a, b) => a + b, 0);
+    case "avg":
+      return nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : 0;
+    case "min":
+      return nums.length ? Math.min(...nums) : 0;
+    case "max":
+      return nums.length ? Math.max(...nums) : 0;
+    default:
+      return nums.length ? nums.reduce((a, b) => a + b, 0) : rows.length;
+  }
+}
+function evaluateAnalyticsQueryOverRows(query, cube, rows) {
+  let filtered = rows.filter((r) => matchesWhere(r, query.where));
+  const timeDims = query.timeDimensions ?? [];
+  for (const td of timeDims) {
+    const dim = cube.dimensions?.[td.dimension];
+    const field = String(dim?.sql ?? td.dimension);
+    if (!td.dateRange) continue;
+    const [start, end] = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
+    filtered = filtered.filter((r) => {
+      const v = String(r[field] ?? "");
+      return v >= String(start) && v <= `${end}~`;
+    });
+  }
+  const dimensions = query.dimensions ?? [];
+  const granByDim = new Map(timeDims.filter((t) => t.granularity).map((t) => [t.dimension, t.granularity]));
+  const keyOf = (r) => {
+    const values = {};
+    for (const name of dimensions) {
+      const dim = cube.dimensions?.[name];
+      const field = String(dim?.sql ?? name);
+      const raw = r[field];
+      const gran = granByDim.get(name) ?? (dim?.type === "time" && dim.granularities?.length === 1 ? String(dim.granularities[0]) : void 0);
+      values[name] = gran ? bucketDate(raw, gran) : raw ?? null;
+    }
+    return { key: JSON.stringify(values), values };
+  };
+  const groups = /* @__PURE__ */ new Map();
+  for (const r of filtered) {
+    const { key, values } = keyOf(r);
+    const g = groups.get(key) ?? { values, rows: [] };
+    g.rows.push(r);
+    groups.set(key, g);
+  }
+  if (dimensions.length === 0 && groups.size === 0) {
+    groups.set("{}", { values: {}, rows: [] });
+  }
+  const out = [];
+  for (const g of groups.values()) {
+    const row = { ...g.values };
+    for (const m of query.measures) {
+      const metric = cube.measures?.[m];
+      row[m] = aggregate(g.rows, String(metric?.type ?? "count"), String(metric?.sql ?? "*"));
+    }
+    out.push(row);
+  }
+  for (const [col, dir] of Object.entries(query.order ?? {}).reverse()) {
+    out.sort((a, b) => (dir === "desc" ? -1 : 1) * compare(a[col], b[col]));
+  }
+  const offset = query.offset ?? 0;
+  const limited = out.slice(offset, query.limit != null ? offset + query.limit : void 0);
+  return {
+    rows: limited,
+    fields: [
+      ...dimensions.map((d) => ({ name: d, type: "string" })),
+      ...query.measures.map((m) => ({ name: m, type: "number" }))
+    ]
+  };
+}
+
 // src/analytics-service.ts
 var DEFAULT_CAPABILITIES = {
   nativeSql: false,
@@ -1211,6 +1365,7 @@ var AnalyticsService = class {
     this.readScopeProvider = config.getReadScope;
     this.relationshipResolver = config.relationshipResolver;
     this.labelResolver = config.labelResolver;
+    this.draftRowsResolver = config.draftRowsResolver;
     if (config.datasets) {
       for (const ds of config.datasets) {
         try {
@@ -1304,6 +1459,14 @@ var AnalyticsService = class {
   }
   /**
    * 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.
    */
   async query(query, context) {
     if (!query.cube) {
@@ -1311,9 +1474,23 @@ var AnalyticsService = class {
     }
     this.ensureCube(query);
     const ctx = await this.callCtx(query, context);
-    const strategy = this.resolveStrategy(query, ctx);
-    this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
-    return strategy.execute(query, ctx);
+    let skip;
+    for (; ; ) {
+      const strategy = this.resolveStrategy(query, ctx, skip);
+      this.logger.debug(`[Analytics] Query on cube "${query.cube}" \u2192 ${strategy.name}`);
+      try {
+        return await strategy.execute(query, ctx);
+      } catch (e) {
+        if (e?.code === "RAW_SQL_UNSUPPORTED") {
+          this.logger.warn(
+            `[Analytics] ${strategy.name} cannot run on this driver (raw SQL unsupported) \u2014 falling back to the next strategy.`
+          );
+          (skip ?? (skip = /* @__PURE__ */ new Set())).add(strategy);
+          continue;
+        }
+        throw e;
+      }
+    }
   }
   /**
    * Compile a `dataset` (ADR-0021) and register its Cube + join allowlist so it
@@ -1332,9 +1509,25 @@ var AnalyticsService = class {
    * runs the selection through the `DatasetExecutor` with the request context so
    * tenant/RLS scoping (D-C) is applied. See {@link IAnalyticsService.queryDataset}.
    */
-  async queryDataset(dataset, selection, context) {
+  async queryDataset(dataset, selection, context, options) {
     const compiled = this.registerDataset(dataset);
     this.logger.debug(`[Analytics] queryDataset "${dataset.name}" (object=${dataset.object}, include=${(dataset.include ?? []).join(",") || "\u2014"})`);
+    if (options?.previewDrafts && this.draftRowsResolver) {
+      let seedRows = null;
+      try {
+        seedRows = await this.draftRowsResolver(dataset.object, context);
+      } catch (e) {
+        this.logger.warn(`[Analytics] draft preview resolver failed for "${dataset.object}" \u2014 falling back to live data: ${String(e?.message ?? e)}`);
+      }
+      if (seedRows) {
+        this.logger.debug(`[Analytics] queryDataset "${dataset.name}" \u2192 preview over ${seedRows.length} drafted seed row(s)`);
+        const previewService = {
+          query: async (q) => evaluateAnalyticsQueryOverRows(q, compiled.cube, seedRows)
+        };
+        const previewResult = await new DatasetExecutor(previewService).execute(compiled, selection, context);
+        return previewResult;
+      }
+    }
     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 }));
@@ -1479,16 +1672,19 @@ var AnalyticsService = class {
     };
   }
   /**
-   * 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).
    */
-  resolveStrategy(query, ctx) {
+  resolveStrategy(query, ctx, skip) {
     for (const strategy of this.strategies) {
+      if (skip?.has(strategy)) continue;
       if (strategy.canHandle(query, ctx)) {
         return strategy;
       }
     }
     throw new Error(
-      `[Analytics] No strategy can handle query for cube "${query.cube}". Checked: ${this.strategies.map((s) => s.name).join(", ")}. Ensure a compatible driver is configured or a fallback service is registered.`
+      `[Analytics] No strategy can handle query for cube "${query.cube}". Checked: ${this.strategies.map((s) => s.name).join(", ")}${skip?.size ? ` (skipped at runtime: ${[...skip].map((s) => s.name).join(", ")})` : ""}. Ensure a compatible driver is configured or a fallback service is registered.`
     );
   }
 };
@@ -1610,8 +1806,15 @@ var AnalyticsServicePlugin = class {
         }
         const knexSql = sql.replace(/\$(\d+)/g, "?");
         const result = await engine.execute(knexSql, { args: params });
+        if (result === null || result === void 0) {
+          const err = new Error(
+            `[Analytics] The "data" engine's driver returned null for raw SQL \u2014 this driver does not support SQL execution. The query will fall back to an aggregate-based strategy when one is available.`
+          );
+          err.code = "RAW_SQL_UNSUPPORTED";
+          throw err;
+        }
         if (Array.isArray(result)) return result;
-        if (result && typeof result === "object" && "rows" in result) {
+        if (typeof result === "object" && "rows" in result) {
           return result.rows;
         }
         return [];
@@ -1680,6 +1883,31 @@ var AnalyticsServicePlugin = class {
         return map;
       }
     };
+    const draftRowsResolver = async (objectName) => {
+      let protocol;
+      try {
+        protocol = ctx.getService("protocol");
+      } catch {
+        return null;
+      }
+      if (!protocol?.getMetaItems || !protocol.getMetaItem) return null;
+      const res = await protocol.getMetaItems({ type: "seed", previewDrafts: true }).catch(() => null);
+      const list = Array.isArray(res) ? res : res && typeof res === "object" && Array.isArray(res.items) ? res.items : [];
+      const rows = [];
+      let pending = false;
+      for (const entry of list) {
+        const body = entry?.item ?? entry;
+        if (!body?.name || body.object !== objectName) continue;
+        const draft = await protocol.getMetaItem({ type: "seed", name: body.name, state: "draft" }).catch(() => null);
+        const draftBody = draft?.item;
+        if (!draftBody) continue;
+        pending = true;
+        for (const r of Array.isArray(draftBody.records) ? draftBody.records : []) {
+          if (r && typeof r === "object") rows.push(r);
+        }
+      }
+      return pending ? rows : null;
+    };
     const config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
@@ -1690,7 +1918,8 @@ var AnalyticsServicePlugin = class {
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
       relationshipResolver,
-      labelResolver
+      labelResolver,
+      draftRowsResolver
     };
     if (autoBridgedReadScope) {
       ctx.logger.info('[Analytics] Auto-bridged getReadScope \u2192 "security" service (getReadFilter)');