@objectstack/service-analytics 9.8.0 → 9.9.0

package/dist/index.d.cts

@@ -381,6 +381,8 @@ interface AnalyticsServicePluginOptions {
             alias: string;
         }>;
         filter?: Record<string, unknown>;
+        /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
+        timezone?: string;
     }) => Promise<Record<string, unknown>[]>;
     /**
      * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). The

package/dist/index.d.ts

@@ -381,6 +381,8 @@ interface AnalyticsServicePluginOptions {
             alias: string;
         }>;
         filter?: Record<string, unknown>;
+        /** Reference timezone (IANA) for date bucketing — ADR-0053 Phase 2. */
+        timezone?: string;
     }) => Promise<Record<string, unknown>[]>;
     /**
      * ADR-0021 D-C — context-aware per-object read scope (tenant + RLS). The

package/dist/index.js

@@ -636,7 +636,11 @@ var ObjectQLStrategy = class {
       // 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
+      filter: Object.keys(filter).length > 0 ? filter : void 0,
+      // ADR-0053 Phase 2 (D2): forward the reference tz so date buckets resolve
+      // on that zone's calendar days. A non-UTC zone makes the engine bucket
+      // in-memory (uniform across drivers); UTC/unset keeps the DB fast path.
+      timezone: query.timezone
     });
     const mappedRows = rows.map((row) => {
       const mapped = {};
@@ -1035,7 +1039,8 @@ var DatasetExecutor = class {
         measures: unfiltered,
         dimensions,
         where: baseFilter,
-        selection
+        selection,
+        contextTimezone: context?.timezone
       }), context);
     } else {
       result = { rows: [], fields: [] };
@@ -1046,7 +1051,8 @@ var DatasetExecutor = class {
         measures: [m],
         dimensions,
         where: mFilter,
-        selection
+        selection,
+        contextTimezone: context?.timezone
       }), context);
       result.rows = mergeByDimensions(result.rows, sub.rows, dimensions, [m]);
       result.fields.push({ name: m, type: "number" });
@@ -1070,7 +1076,9 @@ var DatasetExecutor = class {
       cube: compiled.cube.name,
       measures: opts.measures,
       dimensions: opts.dimensions,
-      timezone: opts.selection.timezone ?? "UTC"
+      // Precedence: explicit selection tz → request's reference tz
+      // (ExecutionContext.timezone, ADR-0053 Phase 2) → UTC.
+      timezone: opts.selection.timezone ?? opts.contextTimezone ?? "UTC"
     };
     if (opts.where) q.where = opts.where;
     const selTimeDims = opts.selection.timeDimensions ?? [];
@@ -1108,7 +1116,7 @@ var DatasetExecutor = class {
       dimensions,
       where: baseFilter,
       timeDimensions: shiftedTd,
-      timezone: selection.timezone ?? "UTC"
+      timezone: selection.timezone ?? context?.timezone ?? "UTC"
     }, context);
     return sub.rows.map((row) => {
       const out = {};
@@ -1221,6 +1229,7 @@ function pickDisplayField(fields) {
 }
 
 // src/preview-evaluator.ts
+import { calendarPartsInTzOrUtc } from "@objectstack/core";
 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;
@@ -1268,23 +1277,23 @@ function matchesWhere(row, where) {
   }
   return true;
 }
-function bucketDate(value, granularity) {
+function bucketDate(value, granularity, timezone) {
   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");
+  const { year: y, month, day: dayNum } = calendarPartsInTzOrUtc(d, timezone);
+  const m = `${month}`.padStart(2, "0");
+  const day = `${dayNum}`.padStart(2, "0");
   switch (granularity) {
     case "year":
       return `${y}`;
     case "quarter":
-      return `${y}-Q${Math.floor(d.getUTCMonth() / 3) + 1}`;
+      return `${y}-Q${Math.floor((month - 1) / 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);
+      const monday = new Date(Date.UTC(y, month - 1, dayNum));
+      const dow = (monday.getUTCDay() + 6) % 7;
+      monday.setUTCDate(monday.getUTCDate() - dow);
       return monday.toISOString().slice(0, 10);
     }
     case "day":
@@ -1329,6 +1338,7 @@ function evaluateAnalyticsQueryOverRows(query, cube, rows) {
     });
   }
   const dimensions = query.dimensions ?? [];
+  const timezone = query.timezone;
   const granByDim = new Map(timeDims.filter((t) => t.granularity).map((t) => [t.dimension, t.granularity]));
   const keyOf = (r) => {
     const values = {};
@@ -1337,7 +1347,7 @@ function evaluateAnalyticsQueryOverRows(query, cube, rows) {
       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;
+      values[name] = gran ? bucketDate(raw, gran, timezone) : raw ?? null;
     }
     return { key: JSON.stringify(values), values };
   };
@@ -1818,7 +1828,7 @@ var AnalyticsServicePlugin = class {
           '[Analytics] No "data" service registered yet at init; will retry per-query. Register ObjectQLPlugin or pass executeAggregate.'
         );
       }
-      executeAggregate = async (objectName, { groupBy, aggregations, filter }) => {
+      executeAggregate = async (objectName, { groupBy, aggregations, filter, timezone }) => {
         const engine = tryGetDataEngine();
         if (!engine) {
           throw new Error(
@@ -1832,7 +1842,10 @@ var AnalyticsServicePlugin = class {
             function: a.method,
             field: a.field,
             alias: a.alias
-          }))
+          })),
+          // ADR-0053 Phase 2: thread the reference tz so date buckets resolve on
+          // that zone's calendar days (engine buckets in-memory when non-UTC).
+          timezone
         });
         return rows;
       };