@lightdash/cli 3.163.1 → 3.164.0

package/dist/vendor/template/skill.md

@@ -608,6 +608,8 @@ function RevenueTable() {
 
 ### Formatting
 
+**Trust Lightdash's values for date/time display — never re-convert them.** Date and timestamp values arrive as the correct wall-clock reading with a `Z` suffix (e.g. a March 1st date is `'2025-03-01T00:00:00Z'`). Rendering them through anything timezone-aware — `new Date(value).toLocaleDateString()`, `Intl.DateTimeFormat`, `date-fns-tz`, or manual offset math — shifts them into the viewer's local timezone, so a viewer behind UTC sees Feb 28 where Lightdash shows Mar 1. Always display dates via `format(row, fieldName)` or the `@/lib/format` helpers below (they render the server's wall-clock components as-is); when formatting manually, format the date's own Y/M/D components, never a locale/timezone conversion of them.
+
 Every Lightdash row carries two views of each value:
 
 - `row[fieldName]` — the **raw** value. Numbers are real numbers; **dates and timestamps are full ISO strings** (e.g. `'2025-03-01T00:00:00Z'`) regardless of the truncation grain. Pass these to charts as data, not as axis labels.
@@ -636,17 +638,15 @@ import { formatField, formatDate, formatNumber, getColumn } from '@/lib/format';
 - number — server-formatted (currency / % / suffix preserved via the SDK `format()` you pass in)
 - timestamp without grain — `Jun 16, 2025 14:00`
 
-**Override** by passing `opts.pattern` to `formatDate`, or by formatting yourself with `date-fns`/`Intl.NumberFormat`:
+**Override** by passing `opts.pattern` to `formatDate` — this keeps the server's wall-clock reading while changing the pattern:
 
 ```tsx
-import { format as formatDateFns, parseISO } from 'date-fns';
-
 formatDate(row.order_date_month, getColumn(columns, 'order_date_month'), 'axis', { pattern: 'MMM yyyy' });
-
-// Or fully manual:
-formatDateFns(parseISO(row.order_date as string), 'EEEE, MMM d');
+formatDate(row.order_date, undefined, 'cell', { pattern: 'EEEE, MMM d' });
 ```
 
+Avoid `parseISO`/`new Date` + `format` from `date-fns` for display: the `Z` suffix makes them shift the value into the viewer's timezone, moving midnight dates to the previous day for viewers behind UTC.
+
 #### Chart axes
 
 **Every `<XAxis>` and `<YAxis>` in the app must have a `tickFormatter`.** No exceptions — including year axes that "look like they'd be fine" (`order_date_year` is still a full ISO timestamp at the data layer; Recharts will render `2025-01-01T00:00:00Z`, not `2025`).
@@ -1379,6 +1379,7 @@ The action-menu example above shows typical `drillDown()` usage. For the full AP
 | Skipping `tickFormatter` on a year axis because "year is just a number" | Year dimensions (`*_year`) are still full ISO timestamps at the data layer, so the axis renders `2025-01-01T00:00:00Z` | Apply the same `formatDate(...)` `tickFormatter` to year axes — `formatDate` will collapse to `2025` for year-grain columns |
 | Using `format(row, 'order_date')` for a date column in a table cell | Renders `2025-03-17` (zero-padded tabular) — readable but ugly in dashboards | `formatField(row, col, format, 'cell')` from `@/lib/format` — renders `Mar 17, 2025` while still routing currency/% metrics through the server format |
 | Treating `row.order_date_month` as a `Date` or short string | It's a full ISO timestamp string (`2025-03-01T00:00:00Z`) for every grain | Pass through `formatDate` / `formatField`, or `parseISO` it before doing date math |
+| Displaying dates via `toLocaleDateString()`, `Intl.DateTimeFormat`, or `parseISO` + `format` | The `Z` suffix makes these convert to the viewer's timezone — viewers behind UTC see the previous day (e.g. Feb 28 instead of Mar 1) | Render through `format(row, field)` or `@/lib/format` helpers; they display the server's wall-clock value as-is |
 | Wrong `.parameters()` key scope | Value silently ignored — query returns the default | Project-level → bare name (`{ region }`); model-level → `model.param` (`{ 'orders.region' }`), matching the `${lightdash.parameters.…}` reference |
 | Inventing a parameter not declared in the YAML | Backend ignores unknown params; nothing changes | Only pass parameters that exist in a model's `meta.parameters` or `lightdash.config.yml`. Use `.filters()` for row restriction instead |
 | Applying `.parameters()` at module scope for a UI-driven value | Value never updates when the control changes | Apply `.parameters()` in a `useMemo` keyed on the state value; keep the base query at module scope |

package/dist/vendor/template/src/lib/format.ts

@@ -1,5 +1,5 @@
-import { format as formatDateFns, parseISO } from 'date-fns';
 import type { Column, FormatFunction, Row } from '@lightdash/query-sdk';
+import { format as formatDateFns, parseISO } from 'date-fns';
 
 export type FormatVariant = 'cell' | 'axis';
 
@@ -21,6 +21,93 @@ function inferGranularity(name: string): DateGranularity | undefined {
     return undefined;
 }
 
+// Lightdash returns dates/timestamps as the project's wall-clock reading with
+// a `Z` suffix (e.g. a March 1st date arrives as '2025-03-01T00:00:00Z').
+// Parsing that with `parseISO`/`new Date` and formatting locally shifts it
+// into the viewer's timezone — a UTC-7 viewer would see "Feb 28". Render the
+// wall-clock components exactly as the server sent them instead.
+const ISO_WALL_CLOCK_RE =
+    /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?)?/;
+
+/**
+ * A Date whose local-time getters return UTC components, so date-fns `format`
+ * renders the stored wall-clock reading in every viewer timezone. A plain
+ * `new Date(y, m, d, h, …)` is not enough: the constructor interprets the
+ * components in the viewer's timezone and normalizes local times that don't
+ * exist there (a DST spring-forward gap turns 02:30 into 03:30). date-fns
+ * clones inputs via their own constructor, so the subclass survives `format`.
+ * Same mechanism as @date-fns/utc's UTCDate, without the dependency.
+ */
+class WallClockDate extends Date {
+    getFullYear() {
+        return this.getUTCFullYear();
+    }
+
+    getMonth() {
+        return this.getUTCMonth();
+    }
+
+    getDate() {
+        return this.getUTCDate();
+    }
+
+    getDay() {
+        return this.getUTCDay();
+    }
+
+    getHours() {
+        return this.getUTCHours();
+    }
+
+    getMinutes() {
+        return this.getUTCMinutes();
+    }
+
+    getSeconds() {
+        return this.getUTCSeconds();
+    }
+
+    getMilliseconds() {
+        return this.getUTCMilliseconds();
+    }
+
+    getTimezoneOffset() {
+        return 0;
+    }
+
+    // Setters must match the getters: date-fns week tokens (II, ww, RRRR)
+    // compute via startOfWeek, which mutates clones with setDate/setHours.
+    // Inheriting the local setters would mix UTC reads with local writes and
+    // land on the wrong ISO week in non-UTC viewer timezones.
+    setFullYear(...args: Parameters<Date['setFullYear']>) {
+        return this.setUTCFullYear(...args);
+    }
+
+    setMonth(...args: Parameters<Date['setMonth']>) {
+        return this.setUTCMonth(...args);
+    }
+
+    setDate(day: number) {
+        return this.setUTCDate(day);
+    }
+
+    setHours(...args: Parameters<Date['setHours']>) {
+        return this.setUTCHours(...args);
+    }
+
+    setMinutes(...args: Parameters<Date['setMinutes']>) {
+        return this.setUTCMinutes(...args);
+    }
+
+    setSeconds(...args: Parameters<Date['setSeconds']>) {
+        return this.setUTCSeconds(...args);
+    }
+
+    setMilliseconds(ms: number) {
+        return this.setUTCMilliseconds(ms);
+    }
+}
+
 function toDate(value: unknown): Date | null {
     if (value === null || value === undefined || value === '') return null;
     if (value instanceof Date)
@@ -30,6 +117,23 @@ function toDate(value: unknown): Date | null {
         return Number.isNaN(d.getTime()) ? null : d;
     }
     if (typeof value === 'string') {
+        const wallClock = ISO_WALL_CLOCK_RE.exec(value);
+        if (wallClock) {
+            const [, year, month, day, hours, minutes, seconds, millis] =
+                wallClock;
+            const d = new WallClockDate(
+                Date.UTC(
+                    Number(year),
+                    Number(month) - 1,
+                    Number(day),
+                    Number(hours ?? 0),
+                    Number(minutes ?? 0),
+                    Number(seconds ?? 0),
+                    Number(millis?.padEnd(3, '0') ?? 0),
+                ),
+            );
+            return Number.isNaN(d.getTime()) ? null : d;
+        }
         const d = parseISO(value);
         return Number.isNaN(d.getTime()) ? null : d;
     }
@@ -135,9 +239,6 @@ export function formatField(
     }
 }
 
-export function getColumn(
-    columns: Column[],
-    name: string,
-): Column | undefined {
+export function getColumn(columns: Column[], name: string): Column | undefined {
     return columns.find((c) => c.name === name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "3.163.1",
+  "version": "3.164.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "3.163.1",
-    "@lightdash/warehouses": "3.163.1",
+    "@lightdash/common": "3.164.0",
+    "@lightdash/warehouses": "3.164.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",
@@ -61,6 +61,7 @@
     "@vercel/ncc": "0.38.4",
     "@yao-pkg/pkg": "6.24.0",
     "copyfiles": "2.4.1",
+    "date-fns": "3.6.0",
     "oxlint": "1.75.0",
     "oxlint-tsgolint": "7.0.2001",
     "tsx": "4.19.4",