@objectstack/service-analytics 17.0.0 → 17.1.0

package/dist/index.d.cts

@@ -1186,6 +1186,33 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#8690] Does the query's `where` compare a declared TIME dimension against
+     * a value no temporal storage rule can read? See the ruling at
+     * {@link canHandle}.
+     *
+     * The classification comes from the CUBE, the only metadata this package has:
+     * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+     * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+     * member lookup in this strategy uses, so "the member the gate classified"
+     * and "the member the compiler emits" cannot drift apart.
+     *
+     * A `time` dimension is read with the DATETIME rule — the permissive one of
+     * the three. That is the right direction because this is a routing decision,
+     * not a verdict: the engine door re-judges with the field's real declared
+     * type and has the final say, so under-classifying an exotic spelling merely
+     * leaves today's behaviour, while over-classifying would silently move a
+     * working dashboard off the fast path. The comparands this card measured
+     * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+     * so the decline fires for them whichever backing type the dimension has.
+     *
+     * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+     * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+     * lowering is not this gate's to answer — the filter is malformed either way
+     * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+     * message and envelope it has always had.
+     */
+    private carriesUninterpretableTemporalComparand;
     /**
      * [#7598] Does serving this query require the cross-field capability this
      * strategy declines? See the ruling recorded at {@link canHandle}.

package/dist/index.d.ts

@@ -1186,6 +1186,33 @@ declare class NativeSQLStrategy implements AnalyticsStrategy {
     readonly name = "NativeSQLStrategy";
     readonly priority = 10;
     canHandle(query: AnalyticsQuery, ctx: StrategyContext): boolean;
+    /**
+     * [#8690] Does the query's `where` compare a declared TIME dimension against
+     * a value no temporal storage rule can read? See the ruling at
+     * {@link canHandle}.
+     *
+     * The classification comes from the CUBE, the only metadata this package has:
+     * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+     * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+     * member lookup in this strategy uses, so "the member the gate classified"
+     * and "the member the compiler emits" cannot drift apart.
+     *
+     * A `time` dimension is read with the DATETIME rule — the permissive one of
+     * the three. That is the right direction because this is a routing decision,
+     * not a verdict: the engine door re-judges with the field's real declared
+     * type and has the final say, so under-classifying an exotic spelling merely
+     * leaves today's behaviour, while over-classifying would silently move a
+     * working dashboard off the fast path. The comparands this card measured
+     * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+     * so the decline fires for them whichever backing type the dimension has.
+     *
+     * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+     * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+     * lowering is not this gate's to answer — the filter is malformed either way
+     * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+     * message and envelope it has always had.
+     */
+    private carriesUninterpretableTemporalComparand;
     /**
      * [#7598] Does serving this query require the cross-field capability this
      * strategy declines? See the ruling recorded at {@link canHandle}.

package/dist/index.js

@@ -124,17 +124,19 @@ import { isFilterAST, parseFilterAST, VALID_AST_OPERATORS } from "@objectstack/s
 import { StandardErrorCode } from "@objectstack/spec/api";
 
 // src/comparand-shape.ts
+import {
+  isUninterpretableTemporalComparand
+} from "@objectstack/core";
+import {
+  isAcceptedFilterComparand,
+  ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE
+} from "@objectstack/spec/data";
 function isBindableComparand(value) {
-  if (value === null || value === void 0) return true;
-  const kind = typeof value;
-  if (kind === "string" || kind === "number" || kind === "bigint" || kind === "boolean") return true;
-  return value instanceof Date || ArrayBuffer.isView(value);
+  if (value === void 0) return true;
+  return isAcceptedFilterComparand(value) || ArrayBuffer.isView(value);
 }
 function isRenderableTextComparand(value) {
-  if (value === null || value === void 0) return true;
-  const kind = typeof value;
-  if (kind === "string" || kind === "number" || kind === "bigint" || kind === "boolean") return true;
-  return value instanceof Date;
+  return value === void 0 || isAcceptedFilterComparand(value);
 }
 function isFieldReference(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
@@ -170,6 +172,51 @@ function findIn(node, field) {
   }
   return null;
 }
+function findUninterpretableTemporalMember(filter, kindOf) {
+  return findUninterpretableIn(filter, "", kindOf);
+}
+function findUninterpretableIn(node, field, kindOf) {
+  if (!node || typeof node !== "object") return null;
+  if (Array.isArray(node)) {
+    for (const child of node) {
+      const hit = findUninterpretableIn(child, field, kindOf);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (node instanceof Date || ArrayBuffer.isView(node)) return null;
+  if (isFieldReference(node)) return null;
+  for (const [key, value] of Object.entries(node)) {
+    const scope = key.startsWith("$") ? field : key;
+    const kind = scope ? kindOf(scope) : null;
+    if (kind) {
+      const hit2 = judgeTemporalLiterals(value, scope, kind);
+      if (hit2) return hit2;
+      continue;
+    }
+    const hit = findUninterpretableIn(value, scope, kindOf);
+    if (hit) return hit;
+  }
+  return null;
+}
+function judgeTemporalLiterals(value, field, kind) {
+  if (Array.isArray(value)) {
+    for (const member of value) {
+      const hit = judgeTemporalLiterals(member, field, kind);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  if (value && typeof value === "object") {
+    if (value instanceof Date || ArrayBuffer.isView(value) || isFieldReference(value)) return null;
+    for (const nested of Object.values(value)) {
+      const hit = judgeTemporalLiterals(nested, field, kind);
+      if (hit) return hit;
+    }
+    return null;
+  }
+  return isUninterpretableTemporalComparand(kind, value) ? { field, kind, value } : null;
+}
 var TEXT_PATTERN_OPERATORS = /* @__PURE__ */ new Set([
   "$contains",
   "$notContains",
@@ -187,7 +234,7 @@ function shapePreview(value) {
   }
 }
 function unrenderableTextComparandMessage(op, field, value) {
-  return `"${op}" on "${field}" matches against the TEXT of a pattern, but its comparand is ${Array.isArray(value) ? "an array" : "an object"} (${shapePreview(value)}). filter.zod.ts declares it a string (StringOperatorSchema); a string, number, boolean, null or Date is accepted. Refusing rather than stringifying it: String({}) is "[object Object]", so the pattern that ran would be one nobody wrote \u2014 and a row storing that literal text matches it.`;
+  return `"${op}" on "${field}" matches against the TEXT of a pattern, but its comparand is ${Array.isArray(value) ? "an array" : "an object"} (${shapePreview(value)}). filter.zod.ts declares it a string (StringOperatorSchema); ${ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE} is accepted. Refusing rather than stringifying it: String({}) is "[object Object]", so the pattern that ran would be one nobody wrote \u2014 and a row storing that literal text matches it.`;
 }
 function fieldReferenceComparandMessage(op, field, ref, position) {
   return `"${op}" on "${field}"${position ? ` (${position})` : ""} compares against the field reference { "$field": "${ref}" }, which this compiler does not lower into a column-to-column comparison. Refusing rather than binding it: the reference object used to become the BOUND VALUE of the comparison, so the emitted predicate compared "${field}" against the reference itself \u2014 a value no row can hold \u2014 and a read scope built from it answered the wrong row set with nothing to read. \u26A0\uFE0F This is NOT the platform declining the rule. @objectstack/spec declares this shape (FieldReferenceSchema), @objectstack/formula resolves it per record in memory, driver-sql / driver-sqlite-wasm compile it to a same-table column comparison for the six scalar operators since #5222, and since the 2026-08-12 ruling on #7598 the analytics native-SQL strategy DECLINES such a query so it routes to the ObjectQL engine path and runs there \u2014 the driver enforcing declared-only enumeration, the tenant-isolation ban and the comparison class with metadata it owns. What refuses here is this SQL lowering, whose only remaining caller is the /analytics/sql display echo; it has no faithful rendering of the predicate the engine path actually runs, and half-rendering one would describe a query that returns different rows. Run the query itself (/analytics/query) to get its rows (#7598).`;
@@ -196,7 +243,7 @@ function fieldReferenceBetweenBoundMessage(op, field, ref, index) {
   return `"${op}" on "${field}" has the field reference { "$field": "${ref}" } at index ${index} of its [min, max] bounds. A range BOUND may not be a field reference on any backend: driver-sql and driver-sqlite-wasm refuse both endpoints (#5222), @objectstack/formula does not resolve a reference inside a list either \u2014 it orders the bounds against the raw reference object, which no value compares meaningfully to \u2014 and @objectstack/spec no longer declares the position at all (#7596 removed FieldReferenceSchema from the $between endpoint union, ADR-0049 declared = enforced). Refusing rather than lowering it: this compiler splits $between into its two bounds, so the reference would arrive at the driver under a "$gte" / "$lte" the author never wrote \u2014 a position the SQL drivers DO compile \u2014 and the range would quietly succeed here while the identical filter is refused everywhere else. Use a literal bound, or spell the comparison you meant as a scalar one ({ "${field}": { "$gte": { "$field": "${ref}" } } }), which IS served \u2014 on the ObjectQL engine path, where the driver enforces the #5222 rulings (#7598).`;
 }
 function unbindableListMemberMessage(op, field, value, index) {
-  return `"${op}" on "${field}" has a value at index ${index} of its list that cannot be bound as a SQL parameter: ${shapePreview(value)}. Every member of an $in/$nin/$between list is a comparand in its own right \u2014 use a string, number, boolean, null, Date or binary value. Refusing rather than binding it: the member can equal no stored value, so the list silently loses that entry (and a $nin loses the exclusion the caller wrote).`;
+  return `"${op}" on "${field}" has a value at index ${index} of its list that cannot be bound as a SQL parameter: ${shapePreview(value)}. Every member of an $in/$nin/$between list is a comparand in its own right \u2014 use ${ACCEPTED_FILTER_COMPARAND_TYPES_SENTENCE} (or a binary value). Refusing rather than binding it: the member can equal no stored value, so the list silently loses that entry (and a $nin loses the exclusion the caller wrote).`;
 }
 
 // src/strategies/filter-normalizer.ts
@@ -1009,9 +1056,51 @@ var NativeSQLStrategy = class {
       }
     }
     if (this.carriesCrossFieldComparison(query, ctx)) return false;
+    if (this.carriesUninterpretableTemporalComparand(query, ctx)) return false;
     const caps = ctx.queryCapabilities(query.cube);
     return caps.nativeSql && typeof ctx.executeRawSql === "function";
   }
+  /**
+   * [#8690] Does the query's `where` compare a declared TIME dimension against
+   * a value no temporal storage rule can read? See the ruling at
+   * {@link canHandle}.
+   *
+   * The classification comes from the CUBE, the only metadata this package has:
+   * a dimension declares `type: 'time'` (compiled from the dataset dimension's
+   * `type: 'date'`), and {@link lookupMember} is the same resolution every other
+   * member lookup in this strategy uses, so "the member the gate classified"
+   * and "the member the compiler emits" cannot drift apart.
+   *
+   * A `time` dimension is read with the DATETIME rule — the permissive one of
+   * the three. That is the right direction because this is a routing decision,
+   * not a verdict: the engine door re-judges with the field's real declared
+   * type and has the final say, so under-classifying an exotic spelling merely
+   * leaves today's behaviour, while over-classifying would silently move a
+   * working dashboard off the fast path. The comparands this card measured
+   * (`last_30_days`, `not-a-date-at-all`) are unreadable under all three rules,
+   * so the decline fires for them whichever backing type the dimension has.
+   *
+   * `lowerAnalyticsWhere` rather than `query.where` raw, so the authored ARRAY
+   * sugar is seen after `parseFilterAST` has lowered it; a THROW from that
+   * lowering is not this gate's to answer — the filter is malformed either way
+   * and `normalizeAnalyticsFilterTree` refuses it a moment later with the
+   * message and envelope it has always had.
+   */
+  carriesUninterpretableTemporalComparand(query, ctx) {
+    const cube = query.cube ? ctx.getCube(query.cube) : void 0;
+    if (!cube) return false;
+    let where = null;
+    try {
+      where = lowerAnalyticsWhere(query);
+    } catch {
+      return false;
+    }
+    if (!where) return false;
+    return findUninterpretableTemporalMember(
+      where,
+      (member) => this.lookupMember(cube, member, "dimension")?.type === "time" ? "datetime" : null
+    ) !== null;
+  }
   /**
    * [#7598] Does serving this query require the cross-field capability this
    * strategy declines? See the ruling recorded at {@link canHandle}.