@objectstack/service-analytics 9.9.1 → 9.10.0

package/dist/index.d.cts

@@ -212,6 +212,15 @@ interface AnalyticsServiceConfig {
      * config hook is a fallback for legacy hand-authored cubes.
      */
     getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
+    /**
+     * Coerce a filter comparand to a temporal column's storage form so a
+     * relative-date / ISO-string value compares correctly on the active driver
+     * (SQLite `Field.datetime` → epoch ms; `Field.date` / native timestamp →
+     * unchanged). Threaded into the StrategyContext and consulted by
+     * `NativeSQLStrategy` when binding filter values. See the contract docs on
+     * `StrategyContext.coerceTemporalFilterValue` for the full rationale.
+     */
+    coerceTemporalFilterValue?: (objectName: string, fieldName: string, value: unknown) => unknown;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -561,6 +570,31 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     private resolveDimensionSql;
     private resolveMeasureSql;
     private resolveFieldSql;
+    /**
+     * Resolve the (object, column) a filter member binds against, so its
+     * comparand can be coerced to that column's on-disk storage form.
+     *
+     * Mirrors `resolveFieldSql`'s `sql` resolution but yields the *logical*
+     * target rather than the qualified SQL:
+     *   - A dotted column (`account.region`, emitted for a relation traversal)
+     *     belongs to the JOINED object — resolve the alias → target table via the
+     *     cube's `joins` map (alias `account` → object `crm_account` when
+     *     namespaced) and take the tail as the column.
+     *   - Otherwise the column lives on the cube's BASE table. Use the dimension's
+     *     resolved `sql` (the real column, which may differ from the member name,
+     *     e.g. dimension `assessed` → column `assessed_at`) rather than the member.
+     */
+    private resolveStorageTarget;
+    /**
+     * Apply the storage-form coercion for a single comparand. Prefers the
+     * driver-backed `coerceTemporalFilterValue` hook (single source of truth for
+     * the date/datetime storage convention — see StrategyContext); when the hook
+     * is absent, or returns the value unchanged (the field is not a temporal
+     * column, or the dialect stores it as a native timestamp), falls back to the
+     * generic boolean/number recovery so non-temporal typed columns still bind
+     * correctly.
+     */
+    private coerceTemporal;
     private buildFilterClause;
     private extractObjectName;
     private buildFieldMeta;

package/dist/index.d.ts

@@ -212,6 +212,15 @@ interface AnalyticsServiceConfig {
      * config hook is a fallback for legacy hand-authored cubes.
      */
     getAllowedRelationships?: (cubeName: string) => Set<string> | undefined;
+    /**
+     * Coerce a filter comparand to a temporal column's storage form so a
+     * relative-date / ISO-string value compares correctly on the active driver
+     * (SQLite `Field.datetime` → epoch ms; `Field.date` / native timestamp →
+     * unchanged). Threaded into the StrategyContext and consulted by
+     * `NativeSQLStrategy` when binding filter values. See the contract docs on
+     * `StrategyContext.coerceTemporalFilterValue` for the full rationale.
+     */
+    coerceTemporalFilterValue?: (objectName: string, fieldName: string, value: unknown) => unknown;
     /**
      * ADR-0021 — optional object-graph resolver used when compiling datasets:
      * `(baseObject, relationshipName) => relatedObjectName | undefined`. When
@@ -561,6 +570,31 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     private resolveDimensionSql;
     private resolveMeasureSql;
     private resolveFieldSql;
+    /**
+     * Resolve the (object, column) a filter member binds against, so its
+     * comparand can be coerced to that column's on-disk storage form.
+     *
+     * Mirrors `resolveFieldSql`'s `sql` resolution but yields the *logical*
+     * target rather than the qualified SQL:
+     *   - A dotted column (`account.region`, emitted for a relation traversal)
+     *     belongs to the JOINED object — resolve the alias → target table via the
+     *     cube's `joins` map (alias `account` → object `crm_account` when
+     *     namespaced) and take the tail as the column.
+     *   - Otherwise the column lives on the cube's BASE table. Use the dimension's
+     *     resolved `sql` (the real column, which may differ from the member name,
+     *     e.g. dimension `assessed` → column `assessed_at`) rather than the member.
+     */
+    private resolveStorageTarget;
+    /**
+     * Apply the storage-form coercion for a single comparand. Prefers the
+     * driver-backed `coerceTemporalFilterValue` hook (single source of truth for
+     * the date/datetime storage convention — see StrategyContext); when the hook
+     * is absent, or returns the value unchanged (the field is not a temporal
+     * column, or the dialect stores it as a native timestamp), falls back to the
+     * generic boolean/number recovery so non-temporal typed columns still bind
+     * correctly.
+     */
+    private coerceTemporal;
     private buildFilterClause;
     private extractObjectName;
     private buildFieldMeta;

package/dist/index.js

@@ -319,6 +319,7 @@ var NativeSQLStrategy = class {
   }
   canHandle(query, ctx) {
     if (!query.cube) return false;
+    if (query.timeDimensions?.some((td) => !!td.granularity)) return false;
     const caps = ctx.queryCapabilities(query.cube);
     return caps.nativeSql && typeof ctx.executeRawSql === "function";
   }
@@ -358,7 +359,8 @@ var NativeSQLStrategy = class {
     if (normalizedFilters.length > 0) {
       for (const filter of normalizedFilters) {
         const colExpr = this.resolveFieldSql(cube, filter.member, tableName, joins);
-        const clause = this.buildFilterClause(colExpr, filter.operator, filter.values, params);
+        const target = this.resolveStorageTarget(cube, filter.member, tableName);
+        const clause = this.buildFilterClause(colExpr, filter.operator, filter.values, params, ctx, target);
         if (clause) whereClauses.push(clause);
       }
     }
@@ -368,7 +370,11 @@ var NativeSQLStrategy = class {
         if (td.dateRange) {
           const range = Array.isArray(td.dateRange) ? td.dateRange : [td.dateRange, td.dateRange];
           if (range.length === 2) {
-            params.push(range[0], range[1]);
+            const td2 = this.resolveStorageTarget(cube, td.dimension, tableName);
+            params.push(
+              this.coerceTemporal(ctx, td2, range[0]),
+              this.coerceTemporal(ctx, td2, range[1])
+            );
             whereClauses.push(`${colExpr} BETWEEN $${params.length - 1} AND $${params.length}`);
           }
         }
@@ -532,7 +538,48 @@ var NativeSQLStrategy = class {
     const fieldName = member.includes(".") ? member.split(".")[1] : member;
     return fieldName;
   }
-  buildFilterClause(col, operator, values, params) {
+  /**
+   * Resolve the (object, column) a filter member binds against, so its
+   * comparand can be coerced to that column's on-disk storage form.
+   *
+   * Mirrors `resolveFieldSql`'s `sql` resolution but yields the *logical*
+   * target rather than the qualified SQL:
+   *   - A dotted column (`account.region`, emitted for a relation traversal)
+   *     belongs to the JOINED object — resolve the alias → target table via the
+   *     cube's `joins` map (alias `account` → object `crm_account` when
+   *     namespaced) and take the tail as the column.
+   *   - Otherwise the column lives on the cube's BASE table. Use the dimension's
+   *     resolved `sql` (the real column, which may differ from the member name,
+   *     e.g. dimension `assessed` → column `assessed_at`) rather than the member.
+   */
+  resolveStorageTarget(cube, member, baseTable) {
+    const dim = this.lookupMember(cube, member, "dimension");
+    const measure = dim ? void 0 : this.lookupMember(cube, member, "measure");
+    const rawSql = dim?.sql ?? measure?.sql ?? (member.includes(".") ? member.split(".").slice(1).join(".") : member);
+    if (rawSql.includes(".")) {
+      const [alias, ...rest] = rawSql.split(".");
+      const object = cube.joins?.[alias]?.name ?? alias;
+      return { object, field: rest.join(".") };
+    }
+    return { object: baseTable, field: rawSql };
+  }
+  /**
+   * Apply the storage-form coercion for a single comparand. Prefers the
+   * driver-backed `coerceTemporalFilterValue` hook (single source of truth for
+   * the date/datetime storage convention — see StrategyContext); when the hook
+   * is absent, or returns the value unchanged (the field is not a temporal
+   * column, or the dialect stores it as a native timestamp), falls back to the
+   * generic boolean/number recovery so non-temporal typed columns still bind
+   * correctly.
+   */
+  coerceTemporal(ctx, target, value) {
+    if (typeof ctx.coerceTemporalFilterValue === "function") {
+      const coerced = ctx.coerceTemporalFilterValue(target.object, target.field, value);
+      if (coerced !== value) return coerced;
+    }
+    return coerceFilterValueForSql(value);
+  }
+  buildFilterClause(col, operator, values, params, ctx, target) {
     const opMap = {
       equals: "=",
       notEquals: "!=",
@@ -548,7 +595,7 @@ var NativeSQLStrategy = class {
     if (operator === "in" || operator === "notIn") {
       if (!values || values.length === 0) return null;
       const placeholders = values.map((v) => {
-        params.push(coerceFilterValueForSql(v));
+        params.push(this.coerceTemporal(ctx, target, v));
         return `$${params.length}`;
       }).join(", ");
       return `${col} ${operator === "in" ? "IN" : "NOT IN"} (${placeholders})`;
@@ -558,7 +605,7 @@ var NativeSQLStrategy = class {
     if (operator === "contains" || operator === "notContains") {
       params.push(`%${values[0]}%`);
     } else {
-      params.push(coerceFilterValueForSql(values[0]));
+      params.push(this.coerceTemporal(ctx, target, values[0]));
     }
     return `${col} ${sqlOp} $${params.length}`;
   }
@@ -1428,7 +1475,8 @@ var AnalyticsService = class {
       fallbackService: config.fallbackService,
       // Prefer a compiled dataset's declared relationships (D-C join allowlist);
       // fall back to any explicitly-configured provider for legacy cubes.
-      getAllowedRelationships: (cubeName) => this.datasetRegistry.get(cubeName)?.allowedRelationships ?? config.getAllowedRelationships?.(cubeName)
+      getAllowedRelationships: (cubeName) => this.datasetRegistry.get(cubeName)?.allowedRelationships ?? config.getAllowedRelationships?.(cubeName),
+      coerceTemporalFilterValue: config.coerceTemporalFilterValue
     };
     const builtIn = [
       new NativeSQLStrategy(),
@@ -1973,6 +2021,17 @@ var AnalyticsServicePlugin = class {
       }
       return pending ? rows : null;
     };
+    const coerceTemporalFilterValue = (objectName, fieldName, value) => {
+      try {
+        const svc = ctx.getService("data");
+        const driver = svc?.getDriverForObject?.(objectName);
+        if (driver && typeof driver.temporalFilterValue === "function") {
+          return driver.temporalFilterValue(objectName, fieldName, value);
+        }
+      } catch {
+      }
+      return value;
+    };
     const config = {
       cubes: this.options.cubes,
       logger: ctx.logger,
@@ -1982,6 +2041,7 @@ var AnalyticsServicePlugin = class {
       fallbackService,
       getReadScope,
       getAllowedRelationships: this.options.getAllowedRelationships,
+      coerceTemporalFilterValue,
       relationshipResolver,
       labelResolver,
       draftRowsResolver