@xeplr/actions 1.1.18 → 1.1.20

package/README.md

@@ -107,6 +107,8 @@ Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a modu
 | key | action name | does |
 |---|---|---|
 | `dataOperation` | `data-operation` | From a list of rows, make the list the next step needs — keep some rows, pick and rename columns, compute new ones, sort, optionally render. See [Data operation](#data-operation). |
+| `exportTable` | `export-table` | Rows to a **CSV, Excel (.xlsx) or PDF** file. See [Export](#export). |
+| `exportPages` | `export-pages` | Pages of placed blocks (text, tables, images, shapes) to a PDF — a dashboard as it looked. See [Export](#export). |
 | `dbFetch` | `db-fetch` | Stream rows from a table (`mode: 'table'`) or SQL (`mode: 'query'`, `params`). Default `streaming_mode: true` → NDJSON file `{ filePath, format: 'jsonl', bytes, rows }`; `false` → `{ rows, rowCount }`. |
 | `dbPush` | `db-push` | Write `rows` or an NDJSON `filePath` into `targetTable` through the uploader. `primaryKeys` → upsert. |
 | `dbMove` | `db-move` | One window of rows from a source table, query or procedure into a target table in one streamed pass. See [db-move](#db-move). |
@@ -220,6 +222,48 @@ should not take the other eight hundred and ninety-nine with it.
 **No aggregation.** `group by status, count` changes what a row *is*; that is
 a different shape and, when it is wanted, a different step.
 
+## Export
+
+`export-table` writes rows that arrive **already presented**: which columns, in what order, under what heading, and for each cell its raw value and the text a reader saw. The action knows nothing of reports or pivots; the caller decides all that (in xeplr-bi, `report-engine`'s `presentTable` does). Each format takes what it needs:
+
+| format | writes | from |
+|---|---|---|
+| `csv` | RFC 4180; a UTF-8 byte-order mark so Excel reads `₹` and accents; a text cell starting with `= + - @` gets a leading `'` (no formula injection; numbers untouched) | `values` |
+| `xlsx` | numbers and dates as **real typed cells carrying the column's Excel number format** (`"₹"#,##0.00`, `0.0%`, `mmm yyyy`, `#,##0.0,,"M"`), so the sheet looks like the screen and still sums; an optional title and subtitle; a bold, frozen header with an autofilter; bold subtotals and a tinted total row; column widths from the first 200 rows. Excel's 1,048,576-row limit is respected (`truncated`) | `values` |
+| `pdf` | each cell exactly as displayed, numbers right-aligned by `align`, header repeated on every page, landscape past 6 columns, "Page x of y", bold or tinted total rows. Capped at 5,000 rows (`maxRows`) with a closing note | `display` |
+
+```js
+await runAction(builtins.exportTable, {
+  format: 'xlsx',
+  document: {
+    title: 'Sales by region', subtitle: 'Date: Current financial year',
+    columns: [
+      { header: 'Region' },
+      { header: 'Month', kind: 'date', numFmt: 'mmm yyyy' },
+      { header: 'Revenue', kind: 'number', numFmt: '"₹"#,##0.00', align: 'right' }
+    ]
+  },
+  rows: [{ values: ['North', '2024-01-01', 1234.5], display: ['North', 'Jan 2024', '₹1,234.50'], kind: 'detail' }]
+  // or rowsFile: an NDJSON file, one row per line — streamed, never held
+})
+// → { filePath, fileName, contentType, bytes, rows, truncated }
+```
+
+- **Streaming.** CSV and Excel stream rows to disk, from `rows` or from `rowsFile` (NDJSON, one row per line, as `streaming.spool` writes it); 200,000 rows to xlsx take about 2 s in flat memory. Our own xlsx writer runs on `fflate`. `exceljs` was rejected: it pulls a `uuid` with a published advisory and has had no release since December 2024.
+- **Fonts.** pdfkit's built-in fonts cannot draw `₹` or non-Latin text; a missing glyph draws as nothing. The PDF embeds **DejaVu Sans Condensed** (the `dejavu-fonts-ttf` peer). Pass `document.font` / `boldFont` (TTF/OTF paths) for scripts it lacks. Only the glyphs used are embedded.
+- **Output** goes to `outputPath`, or to a new directory under `XEPLR_ACTIONS_TMP_DIR` with a file named after the title. A failed export leaves no half-written file.
+
+`export-pages` lays out `pages: [{ blocks }]`, each block positioned by **fractions** of the page's content box (A4 landscape by default):
+- `text` (`text`, `size`, `bold`, `color`, `align`)
+- `table` (`title`, `columns`, `rows`; drawn inside its box, and rows that don't fit are counted as "+N more rows")
+- `image` (`src` must be a **PNG or JPEG data URL**: no fetching, no SVG, no markup)
+- `rect` (`fill`, `stroke`, `radius`)
+- `line`
+
+What it is given is assumed to come from a browser, so it is bounded: 50 pages, 200 blocks a page, 8 MB per image, 500 table rows, and 5,000 characters of text. An image that will not decode draws a note in its box instead of failing the whole file.
+
+Peers (optional, needed only by the format used): `fflate` for xlsx; `pdfkit` and `dejavu-fonts-ttf` for pdf. `writers` (`getWriter`, `INFO`, `SUPPORTED`) is exported for code that wants a writer without the action.
+
 ## Uploader
 
 `uploader.upload(opts)` is what `db-push`, `db-move` and `file-upload` use:
@@ -256,9 +300,20 @@ Logical types and what each driver creates:
 | number | NUMERIC | DECIMAL(38,10) | DECIMAL(38,10) | DOUBLE |
 | boolean | BOOLEAN | TINYINT(1) | BIT | BOOLEAN |
 | date | DATE | DATE | DATE | DATE |
-| datetime | TIMESTAMPTZ | DATETIME(6) | DATETIME2 | TIMESTAMPTZ |
+| datetime (an instant) | TIMESTAMPTZ | DATETIME(6), in UTC | DATETIME2, in UTC | TIMESTAMPTZ |
+| localdatetime (no zone) | TIMESTAMP | DATETIME(6) | DATETIME2 | TIMESTAMP |
 | object / array | JSONB | JSON | NVARCHAR(MAX) | JSON |
 
+**Dates and times follow three rules, on every driver** (`lib/drivers/db/dateValues.js`, the one copy):
+
+1. **A `date` is copied as the same day.** MySQL/Postgres/SQL Server `DATE` → `date`.
+2. **A date-time with a zone is copied as the same instant**, stored in UTC. MySQL `TIMESTAMP`, Postgres `timestamptz`, SQL Server `datetimeoffset`, DuckDB `TIMESTAMPTZ` → `datetime`.
+3. **A date-time without a zone is copied as its digits**, `10:00` stays `10:00`, and stays zoneless. MySQL `DATETIME`, Postgres `timestamp`, SQL Server `datetime`/`datetime2`/`smalldatetime`, DuckDB `TIMESTAMP` → `localdatetime`. Which zone it was recorded in is declared where it is used (a cube's source zone), never guessed here.
+
+**Nothing reads the machine's time zone.** The MySQL session is pinned to UTC (`SET time_zone = '+00:00'` on every connection), SQL Server to `useUTC: true` (after the caller's options), Postgres returns `date` and `timestamp` as text, and DuckDB opens with `TimeZone = 'UTC'`. Every JS `Date` is read with `getUTC*`, and a string with no zone is read as UTC, never handed to `new Date()`. `test/dates-across-zones.test.js` moves a real table from each of the three databases into DuckDB with the process in India time and in New York time, and the two must store the same values.
+
+**An existing target column that is zoned but receives a zoneless source column is retyped once** to zoneless, keeping its digits (Postgres and DuckDB; `buildRetypeToLocalDateTimeSql`). Tables created before this rule held those values as instants.
+
 Inference (`inferColumns`): any array → `array`; any object → `object`; all `Date` or ISO-date strings → `datetime`; all booleans → `boolean`; all numbers → `number`; anything else, or all null → `string`.
 
 ### Staged loads
@@ -377,7 +432,7 @@ await driver.query(pool, userSql, params)          // reads only
 | Movement logs carry identifiers, counts, SQL and the error text — never parameter values or row contents; a failed batch shows one row's primary key, not its data. | Logs are copied into tickets and chats. |
 | DuckDB opens **read-only unless the call says `access: 'rw'`**; no environment variable can grant write. A file already open read-only in the process refuses a write. Opening waits on the lock (`openTimeoutMs`, default 60 s). | One read-write process locks every other process out, even readers. Write access belongs at the call site that writes. |
 | **Every DuckDB value comes out plain**, from `query` and `fetchStream` alike: a number, text, boolean, `Date`, array or object, never a BigInt or a DuckDB wrapper object. DECIMAL is a number; DATE and TIMESTAMP are `Date`s; a whole number too big to hold exactly (beyond ±9,007,199,254,740,991) is **text**, never rounded; lists, structs and maps are arrays and objects; TIME, INTERVAL, UUID and any other type are text. `fetchStream` has DuckDB do the conversion inside its engine by wrapping the query (about +3% on a million rows); a query with nothing to convert runs as given. | A streamed read used to hand DECIMAL and TIMESTAMP back as wrapper objects with a BigInt inside, and the first `JSON.stringify` downstream failed with "Do not know how to serialize a BigInt". Text for huge numbers is what the Postgres, MySQL and SQL Server drivers already return. |
-| **A DuckDB timestamp without a zone is read as UTC**; one with a zone keeps its exact instant. | Data is kept in UTC; the viewer's time zone is applied when rendering, never in the driver. |
+| **DuckDB works in UTC** (`TimeZone = 'UTC'` on every instance). A timestamp without a zone is read with its digits in the `Date`'s UTC fields; one with a zone keeps its exact instant. | Left to the machine's zone, `date_trunc('month', …)` of 1 Aug 00:00 UTC on a server in India was 31 Jul 18:30, so August was labelled July, and a filter "to 31 Aug" ended at 30 Aug 18:30. |
 | `meta-store-knex` requires `service` and `applicationId`, and scopes every statement by `applicationId`. | `import_meta` is shared by every app; unattributed rows, or a rollback decided from another app's row, are worse than refusing. |
 | Mail filenames are sanitised (`[^\w.-]` → `_`, all-dot names → `attachment`, max 180 chars) and prefixed with a random id. | Attachment names come from the sender and could escape the output directory; common names collide. |
 | The system mail sender refuses `text`, `bcc`, `from`, `replyTo` rather than dropping them. | A silently lost bcc is a compliance problem found a year later. |

package/index.js

@@ -41,6 +41,8 @@ module.exports = {
   streaming:     streaming,
   drivers:       { db: dbDrivers, file: fileDrivers },
   formats:       formats,
+  // { getWriter(type), INFO, SUPPORTED } — csv / xlsx / pdf writers behind export-table.
+  writers:       require('./lib/formats/writers'),
 
   // xeplr_configs — shared control-plane DB (import/movement metadata).
   // One call per app: attachConfig({ service }); await xcfg.ready(). See

package/lib/builtins/export/pages.js

@@ -0,0 +1,92 @@
+// export-pages — placed blocks to a PDF: a dashboard as it looked.
+//
+// Each page is a list of blocks positioned by FRACTIONS of the page's content
+// box (x, w across; y, h down), so a layout drawn on any screen keeps its
+// proportions on paper. A block is text, a small table, an image (a PNG or
+// JPEG data URL — a chart is captured as one), a rectangle or a line. See
+// lib/formats/writers/pdf.js renderPages for each block's fields.
+//
+// Bounded on purpose: what arrives here was posted by a browser, so the page,
+// block and image counts and sizes are capped and an image must be a data URL
+// of a raster type — no fetching, no markup.
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+var pdf = require('../../formats/writers/pdf');
+var { checkFormatRequires } = require('../../formats');
+
+var LIMITS = { pages: 50, blocksPerPage: 200, imageBytes: 8 * 1024 * 1024, tableRows: 500, text: 5000 };
+var TYPES = ['text', 'table', 'image', 'rect', 'line'];
+
+function fail(message) {
+  var err = new Error(message);
+  err.status = 400;
+  return err;
+}
+
+function fraction(n) { return typeof n === 'number' && isFinite(n) && n >= -0.01 && n <= 50; }
+
+/** Throws (400) naming the first block that is not one this action draws. */
+function validate(spec) {
+  var pages = spec.pages;
+  if (!Array.isArray(pages) || !pages.length) throw fail('pages must list at least one page');
+  if (pages.length > LIMITS.pages) throw fail('At most ' + LIMITS.pages + ' pages');
+  pages.forEach(function(page, p) {
+    var blocks = (page && page.blocks) || [];
+    if (!Array.isArray(blocks)) throw fail('pages[' + p + '].blocks must be a list');
+    if (blocks.length > LIMITS.blocksPerPage) throw fail('At most ' + LIMITS.blocksPerPage + ' blocks on a page');
+    blocks.forEach(function(b, i) {
+      var where = 'pages[' + p + '].blocks[' + i + ']';
+      if (!b || TYPES.indexOf(b.type) === -1) throw fail(where + ': type must be one of ' + TYPES.join(', '));
+      if (![b.x, b.y, b.w, b.h].every(fraction)) throw fail(where + ': x, y, w and h are fractions of the page');
+      if (b.type === 'image') {
+        var src = String(b.src || '');
+        if (!/^data:image\/(png|jpe?g);base64,[A-Za-z0-9+/=]+$/.test(src)) throw fail(where + ': src must be a PNG or JPEG data URL');
+        if (src.length * 0.75 > LIMITS.imageBytes) throw fail(where + ': image is larger than ' + (LIMITS.imageBytes >> 20) + ' MB');
+      }
+      if (b.type === 'table') {
+        if (!Array.isArray(b.columns) || !Array.isArray(b.rows)) throw fail(where + ': a table needs columns and rows');
+        if (b.rows.length > LIMITS.tableRows) b.rows = b.rows.slice(0, LIMITS.tableRows);
+      }
+      if (b.type === 'text' && String(b.text == null ? '' : b.text).length > LIMITS.text) b.text = String(b.text).slice(0, LIMITS.text);
+    });
+  });
+}
+
+module.exports = {
+  name: 'export-pages',
+  description: 'Lay out pages of placed blocks (text, tables, images, shapes) as a PDF — a dashboard as it looked.',
+  requires: [],
+  LIMITS: LIMITS,
+
+  inputSchema: [
+    { name: 'pages', type: 'array', required: true, order: 1,
+      description: '[{ blocks: [{ type: text|table|image|rect|line, x, y, w, h, … }] }], positions as fractions of the page.' },
+    { name: 'title', type: 'string', order: 2 },
+    { name: 'footer', type: 'string', order: 3 },
+    { name: 'landscape', type: 'boolean', order: 4, description: 'Default true.' },
+    { name: 'outputPath', type: 'string', order: 5 }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' },
+    { name: 'contentType', type: 'string' }, { name: 'bytes', type: 'number' }, { name: 'pages', type: 'number' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    checkFormatRequires('export-pages', 'pdf', pdf);
+    validate(input);
+    var name = (String(input.title || 'dashboard').replace(/[\\/:*?"<>|\u0000-\u001F]+/g, ' ').trim().slice(0, 80) || 'dashboard') + '.pdf';
+    var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+    fs.mkdirSync(dir, { recursive: true });
+    var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(dir, 'export-')), name);
+    var done = await pdf.renderPages(filePath, {
+      pages: input.pages, title: input.title, footer: input.footer, landscape: input.landscape !== false
+    });
+    return {
+      filePath: filePath, fileName: path.basename(filePath), contentType: 'application/pdf',
+      bytes: fs.statSync(filePath).size, pages: done.pages
+    };
+  }
+};

package/lib/builtins/export/table.js

@@ -0,0 +1,116 @@
+// export-table — rows to a CSV, Excel or PDF file.
+//
+// The rows arrive already DECIDED: which columns, in what order, under what
+// heading, and for each cell both its raw value and the text a reader saw.
+// This action does not know what a report or a pivot is; whoever calls it
+// worked that out (in BI, report-engine's presentTable). Each format takes
+// what it needs from a row:
+//
+//   csv   the raw values, unformatted — a file for another program
+//   xlsx  the raw values as TYPED cells carrying each column's number format,
+//         so the sheet looks like the screen and still sums
+//   pdf   the display text, exactly as shown
+//
+// Rows come inline (`rows`) or from an NDJSON file (`rowsFile`, one row per
+// line — what streaming/spool writes), so a large result never has to be one
+// array in memory. CSV and Excel stream; a PDF holds its rows (capped, 5,000 by
+// default) because a page is laid out from them.
+
+var fs = require('fs');
+var os = require('os');
+var path = require('path');
+var readline = require('readline');
+var writers = require('../../formats/writers');
+var { checkFormatRequires } = require('../../formats');
+
+function tmpDir() {
+  var dir = process.env.XEPLR_ACTIONS_TMP_DIR || path.join(os.tmpdir(), 'xeplr-actions');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** A file name from a title: what a person would recognise in their downloads. */
+function fileNameFor(title, extension) {
+  var base = String(title || 'export').replace(/[\\/:*?"<>|\u0000-\u001F]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80) || 'export';
+  return base + '.' + extension;
+}
+
+async function* rowsFrom(input) {
+  if (Array.isArray(input.rows)) { for (var i = 0; i < input.rows.length; i++) yield input.rows[i]; return; }
+  var lines = readline.createInterface({ input: fs.createReadStream(input.rowsFile), crlfDelay: Infinity });
+  for await (var line of lines) if (line.trim()) yield JSON.parse(line);
+}
+
+module.exports = {
+  name: 'export-table',
+  description: 'Write rows to a CSV, Excel (.xlsx) or PDF file. Excel cells stay numbers with their number format; ' +
+               'a PDF shows each cell as it was displayed.',
+  requires: [],
+
+  inputSchema: [
+    { name: 'format', type: 'string', required: true, order: 1, enum: writers.SUPPORTED,
+      description: 'csv, xlsx or pdf.' },
+    { name: 'document', type: 'object', required: true, order: 2,
+      description: '{ title?, subtitle?, footer?, columns: [{ header, kind?: number|date|text, numFmt?, align?, width? }] }. ' +
+                   'numFmt is an Excel number format ("#,##0.00", "0.0%", "mmm yyyy").' },
+    { name: 'rows', type: 'array', order: 3,
+      description: 'Rows: { values: [], display?: [], kind?: detail|subtotal|total }. Or give rowsFile.' },
+    { name: 'rowsFile', type: 'string', order: 4,
+      description: 'An NDJSON file with one row per line, instead of rows.' },
+    { name: 'outputPath', type: 'string', order: 5,
+      description: 'Where to write. Default: a new file in XEPLR_ACTIONS_TMP_DIR named after the title.' },
+    { name: 'maxRows', type: 'number', order: 6,
+      description: 'PDF only: rows to draw before stopping with a note (default 5,000).' }
+  ],
+  outputSchema: [
+    { name: 'filePath', type: 'string' }, { name: 'fileName', type: 'string' },
+    { name: 'contentType', type: 'string' }, { name: 'bytes', type: 'number' },
+    { name: 'rows', type: 'number' }, { name: 'truncated', type: 'boolean' }
+  ],
+
+  execute: async function(ctx) {
+    var input = ctx.input || {};
+    var format = String(input.format || '').toLowerCase();
+    var writer = writers.getWriter(format);
+    checkFormatRequires('export-table', format, writer);
+    var doc = Object.assign({}, input.document || {});
+    if (!Array.isArray(doc.columns) || !doc.columns.length) {
+      var bad = new Error('document.columns must list at least one column');
+      bad.status = 400;
+      throw bad;
+    }
+    if (!Array.isArray(input.rows) && !input.rowsFile) {
+      var none = new Error('Give rows, or a rowsFile');
+      none.status = 400;
+      throw none;
+    }
+    if (format === 'pdf' && input.maxRows) doc.maxRows = input.maxRows;
+
+    var info = writers.INFO[format];
+    var fileName = fileNameFor(doc.title, info.extension);
+    var filePath = input.outputPath || path.join(fs.mkdtempSync(path.join(tmpDir(), 'export-')), fileName);
+    var open = writer.open(filePath, doc);
+    var signal = ctx.signal;
+    try {
+      for await (var row of rowsFrom(input)) {
+        if (signal && signal.aborted) throw new Error('Stopped by request');
+        var more = await open.writeRow(row);
+        // Excel's own limit: the rest are only counted. A PDF keeps counting
+        // too, so its closing note can say how many were left out.
+        if (more === false && format === 'xlsx') { /* keep reading to count */ }
+      }
+      var done = await open.close();
+      return {
+        filePath: filePath,
+        fileName: path.basename(filePath),
+        contentType: info.contentType,
+        bytes: fs.statSync(filePath).size,
+        rows: done.rows,
+        truncated: done.truncated
+      };
+    } catch (err) {
+      try { fs.rmSync(filePath, { force: true }); } catch (e) { /* nothing to clean */ }
+      throw err;
+    }
+  }
+};

package/lib/builtins/index.js

@@ -61,5 +61,12 @@ module.exports = {
   emailMove:                require('./email/move'),
   emailDelete:              require('./email/delete'),
   emailDownloadEmail:       require('./email/download-email'),
-  emailDownloadAttachments: require('./email/download-attachments')
+  emailDownloadAttachments: require('./email/download-attachments'),
+
+  // Export — rows to CSV / Excel / PDF, and placed blocks to a PDF. The rows
+  // arrive already presented (columns, headings, raw values and display
+  // text); see export/table.js. Peers: fflate (xlsx), pdfkit and
+  // dejavu-fonts-ttf (pdf) — optional, required only by the format used.
+  exportTable:              require('./export/table'),
+  exportPages:              require('./export/pages')
 };

package/lib/drivers/db/dateValues.js

@@ -0,0 +1,106 @@
+// Dates and times as they move between databases — the ONE copy every driver
+// uses, so no driver can quietly read a value in this machine's zone.
+//
+// Three logical types, and three rules:
+//
+//   date           a calendar day. Copied as the same day, always.
+//   datetime       an INSTANT (MySQL TIMESTAMP, Postgres timestamptz, SQL Server
+//                  datetimeoffset, DuckDB TIMESTAMPTZ). Copied as the same
+//                  instant, in UTC.
+//   localdatetime  a wall-clock reading with NO zone (MySQL DATETIME, Postgres
+//                  timestamp, SQL Server datetime/datetime2, DuckDB TIMESTAMP).
+//                  Copied digit for digit — 10:00 stays 10:00. What zone it was
+//                  recorded in is declared later, where it is used (a cube's
+//                  source timezone), never guessed here.
+//
+// NOTHING HERE READS THE MACHINE'S ZONE. Every Date is read with getUTC*, and a
+// string without a zone is read as UTC rather than handed to `new Date()`,
+// which would read it in local time. The drivers deliver values on the same
+// terms: the MySQL session is pinned to UTC, the SQL Server driver to useUTC,
+// Postgres returns its zoneless types as text, and DuckDB works in UTC. So a
+// value here means the same thing on a server in India and one in New York —
+// the tests run under both zones to keep it that way.
+
+function pad(n, width) { return String(n).padStart(width || 2, '0'); }
+
+function utcDate(d) {
+  return d.getUTCFullYear() + '-' + pad(d.getUTCMonth() + 1) + '-' + pad(d.getUTCDate());
+}
+
+function utcClock(d) {
+  return pad(d.getUTCHours()) + ':' + pad(d.getUTCMinutes()) + ':' + pad(d.getUTCSeconds()) + '.' + pad(d.getUTCMilliseconds(), 3);
+}
+
+// '2025-08-01', '2025-08-01 10:00', '2025-08-01T10:00:00.123456', optionally with
+// 'Z' or an offset. Captures the parts as written.
+var STAMP = /^(\d{4}-\d{2}-\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?)?\s*(Z|[+-]\d{2}(?::?\d{2})?)?$/i;
+
+/**
+ * A calendar day as YYYY-MM-DD. A Date is read in UTC — every driver delivers a
+ * date as midnight UTC of that day, or as text.
+ */
+function toDateOnly(v) {
+  if (v === null || v === undefined) return v;
+  if (v instanceof Date) return isNaN(v.getTime()) ? null : utcDate(v);
+  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v).trim());
+  return m ? m[1] : v;
+}
+
+/**
+ * A zoneless wall-clock time as 'YYYY-MM-DD HH:MM:SS.mmm', the digits it had.
+ * A Date carries those digits in its UTC fields (that is how the drivers hand
+ * one over); a string keeps its own digits, and any zone on it is dropped —
+ * the column has none to keep.
+ */
+function toLocalDateTime(v) {
+  if (v === null || v === undefined) return v;
+  if (v instanceof Date) return isNaN(v.getTime()) ? null : utcDate(v) + ' ' + utcClock(v);
+  var m = STAMP.exec(String(v).trim());
+  if (!m) return v;
+  var ms = m[5] ? (m[5] + '00').slice(0, 3) : '000';
+  return m[1] + ' ' + (m[2] || '00') + ':' + (m[3] || '00') + ':' + (m[4] || '00') + '.' + ms;
+}
+
+/**
+ * An instant as a Date. A string that names its zone is read in it; one that
+ * does not is read as UTC (a MySQL TIMESTAMP from a UTC session), never in this
+ * machine's zone. Unreadable → null.
+ */
+function toInstant(v) {
+  if (v === null || v === undefined) return null;
+  if (v instanceof Date) return isNaN(v.getTime()) ? null : v;
+  var m = STAMP.exec(String(v).trim());
+  if (!m) return null;
+  var iso = m[1] + 'T' + (m[2] || '00') + ':' + (m[3] || '00') + ':' + (m[4] || '00') +
+    (m[5] ? '.' + (m[5] + '00').slice(0, 3) : '') + (m[6] ? normalizeZone(m[6]) : 'Z');
+  var d = new Date(iso);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+function normalizeZone(z) {
+  if (/^z$/i.test(z)) return 'Z';
+  var m = /^([+-])(\d{2}):?(\d{2})?$/.exec(z);
+  return m ? m[1] + m[2] + ':' + (m[3] || '00') : 'Z';
+}
+
+/** An instant as ISO 8601 in UTC ('…Z'), or the value unchanged when unreadable. */
+function toInstantIso(v) {
+  if (v === null || v === undefined) return v;
+  var d = toInstant(v);
+  return d ? d.toISOString() : v;
+}
+
+/** An instant as 'YYYY-MM-DD HH:MM:SS.mmm' in UTC — for a column with no zone of its own (MySQL, SQL Server). */
+function toInstantUtcClock(v) {
+  if (v === null || v === undefined) return v;
+  var d = toInstant(v);
+  return d ? utcDate(d) + ' ' + utcClock(d) : v;
+}
+
+module.exports = {
+  toDateOnly: toDateOnly,
+  toLocalDateTime: toLocalDateTime,
+  toInstant: toInstant,
+  toInstantIso: toInstantIso,
+  toInstantUtcClock: toInstantUtcClock
+};

package/lib/drivers/db/duckdb.js

@@ -81,7 +81,8 @@ var TYPE_MAP = {
   number:   'DOUBLE',
   boolean:  'BOOLEAN',
   date:     'DATE',
-  datetime: 'TIMESTAMPTZ',
+  datetime: 'TIMESTAMPTZ',     // an instant
+  localdatetime: 'TIMESTAMP',  // no zone; its digits as they were (dateValues.js)
   object:   'JSON',
   array:    'JSON'
 };
@@ -94,8 +95,10 @@ var DUCK_TO_LOGICAL = {
   'HUGEINT': 'number',  'UTINYINT': 'number', 'USMALLINT': 'number', 'UINTEGER': 'number',
   'UBIGINT': 'number',  'FLOAT': 'number',    'DOUBLE': 'number',  'DECIMAL': 'number',
   'DATE': 'date',
-  'TIMESTAMP': 'datetime', 'TIMESTAMP WITH TIME ZONE': 'datetime',
-  'TIMESTAMP_S': 'datetime', 'TIMESTAMP_MS': 'datetime', 'TIMESTAMP_NS': 'datetime',
+  // A TIMESTAMP has no zone — a wall-clock reading, copied as its digits. Only
+  // the one WITH a zone is an instant.
+  'TIMESTAMP': 'localdatetime', 'TIMESTAMP WITH TIME ZONE': 'datetime',
+  'TIMESTAMP_S': 'localdatetime', 'TIMESTAMP_MS': 'localdatetime', 'TIMESTAMP_NS': 'localdatetime',
   'TIME': 'datetime',   'TIME WITH TIME ZONE': 'datetime', 'INTERVAL': 'string',
   'JSON': 'object',     'STRUCT': 'object',   'MAP': 'object',
   'LIST': 'array'
@@ -234,7 +237,15 @@ async function connect(config) {
     return existing.pool;
   }
 
-  var options = access === 'ro' ? { access_mode: 'READ_ONLY' } : {};
+  // THE SESSION ZONE IS UTC, ALWAYS. DuckDB otherwise takes the machine's
+  // zone, and every date operation on a TIMESTAMPTZ — date_trunc, comparing
+  // with a plain date, a cast to DATE — happens in it. On a server in India
+  // the month of 1 Aug 00:00 UTC came back as 31 Jul 18:30, a board asked for
+  // August labelled its total "Jul-2025", and a filter "to 31 Aug" ended at
+  // 30 Aug 18:30. Data here is kept in UTC (and a cube stores its days already
+  // cut in its own reporting zone), so UTC is the zone that changes nothing.
+  // Set on the instance, so every connection to the file inherits it.
+  var options = Object.assign({ TimeZone: 'UTC' }, access === 'ro' ? { access_mode: 'READ_ONLY' } : {});
   // Waits rather than failing — see openWithWait. This is what makes the
   // file's own lock the mutex and removes any need to designate a writer.
   var instance = await openWithWait(api, key, options, access,
@@ -516,19 +527,8 @@ function buildInsertSql(tableName, rows, columns, movementId, primaryKeys) {
   return { sql: sql, params: params };
 }
 
-// A calendar date as YYYY-MM-DD with no timezone conversion — see the note in
-// postgres.js; the bug it avoids is identical here.
-function toDateOnly(v) {
-  if (v === null || v === undefined) return v;
-  if (v instanceof Date) {
-    if (isNaN(v.getTime())) return null;
-    return v.getFullYear() + '-' +
-      String(v.getMonth() + 1).padStart(2, '0') + '-' +
-      String(v.getDate()).padStart(2, '0');
-  }
-  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
-  return m ? m[1] : v;
-}
+// Dates and times: one shared rule for every driver (dateValues.js).
+var dateValues = require('./dateValues');
 
 // Coerce a JS value to the effective column type. Same contract as the other
 // drivers: a value that cannot fit passes through unchanged so DuckDB rejects
@@ -567,11 +567,13 @@ function coerceValue(v, type) {
       return v;
 
     case 'date':
-      return toDateOnly(v);
+      return dateValues.toDateOnly(v);
 
     case 'datetime':
-      if (v instanceof Date) return v.toISOString();
-      return v;
+      return dateValues.toInstantIso(v);
+
+    case 'localdatetime':
+      return dateValues.toLocalDateTime(v);
 
     case 'object':
     case 'array':
@@ -955,7 +957,17 @@ async function committedMovement(pool, movementId) {
   return r.rows[0] || null;
 }
 
+/**
+ * A zoned date-time column that holds zoneless values, retyped to zoneless with
+ * the same digits (read in UTC — how they were written). See the uploader's
+ * bootstrap for when this runs.
+ */
+function buildRetypeToLocalDateTimeSql(tableName, column) {
+  return 'ALTER TABLE ' + quoteIdent(tableName) + ' ALTER COLUMN ' + quoteIdent(column) + ' SET DATA TYPE TIMESTAMP';
+}
+
 module.exports = {
+  buildRetypeToLocalDateTimeSql: buildRetypeToLocalDateTimeSql,
   requires: ['@duckdb/node-api'],
 
   connect: connect,

package/lib/drivers/db/mssql.js

@@ -22,8 +22,9 @@
 //   number  → DECIMAL(38,10)   (38 is SQL Server's max precision; > 10
 //                               fractional digits are rounded)
 //   boolean → BIT
-//   date    → DATETIME2        (user rule: always datetime, stored UTC)
-//   datetime→ DATETIME2
+//   date          → DATE       (the same day — dateValues.js)
+//   datetime      → DATETIME2  (an instant, written in UTC)
+//   localdatetime → DATETIME2  (no zone; its digits as they were)
 //   object  → NVARCHAR(MAX)    (SQL Server has no native JSON type)
 //   array   → NVARCHAR(MAX)
 
@@ -33,6 +34,7 @@ var TYPE_MAP = {
   boolean:  'BIT',
   date:     'DATE',
   datetime: 'DATETIME2',
+  localdatetime: 'DATETIME2',
   object:   'NVARCHAR(MAX)',
   array:    'NVARCHAR(MAX)'
 };
@@ -45,30 +47,16 @@ var NATIVE_TO_LOGICAL = {
   decimal: 'number', numeric: 'number', float: 'number', real: 'number',
   money: 'number', smallmoney: 'number',
   bit: 'boolean',
-  datetime: 'datetime', datetime2: 'datetime', smalldatetime: 'datetime',
+  // No zone: copied as their digits (dateValues.js). datetimeoffset is an
+  // instant.
+  datetime: 'localdatetime', datetime2: 'localdatetime', smalldatetime: 'localdatetime',
   // 'date' maps to its OWN logical type — see reconcile.js.
   date: 'date', time: 'datetime', datetimeoffset: 'datetime'
 };
 
 
-// A calendar date, as YYYY-MM-DD, with NO timezone conversion.
-//
-// toISOString() would convert to UTC first, which is exactly the bug: a Date
-// holding 2026-01-05 local becomes 2026-01-04 in UTC anywhere east of
-// Greenwich. The local getters are the right ones here precisely because a
-// business date has no instant to convert.
-function toDateOnly(v) {
-  if (v === null || v === undefined) return v;
-  if (v instanceof Date) {
-    if (isNaN(v.getTime())) return null;
-    return v.getFullYear() + '-' +
-      String(v.getMonth() + 1).padStart(2, '0') + '-' +
-      String(v.getDate()).padStart(2, '0');
-  }
-  // Already a date string — take the date part and leave the rest alone.
-  var m = /^(\d{4}-\d{2}-\d{2})/.exec(String(v));
-  return m ? m[1] : v;
-}
+// Dates and times: one shared rule for every driver (dateValues.js).
+var dateValues = require('./dateValues');
 
 var INTERNAL_ID_COL       = '__xeplr_id__';
 var INTERNAL_MOVEMENT_COL = '__xeplr_movement_id__';
@@ -92,7 +80,12 @@ async function connect(config) {
       // batch and has no session-level read-only mode, so SQL the caller did
       // not write needs a login that can only read (db_datareader). See README.
       config.readOnly ? { readOnlyIntent: true } : {},
-      config.options || {}
+      config.options || {},
+      // PINNED, after the caller's options: a zoneless datetime/date comes
+      // back with its digits in the Date's UTC fields, whatever zone this
+      // process is in. It was the library's default, which a default change
+      // or a caller's `useUTC: false` would have silently undone.
+      { useUTC: true }
     )
   });
   await pool.connect();
@@ -265,7 +258,7 @@ function coerceValue(v, type) {
 
   switch (type) {
     case 'string':
-      if (v instanceof Date)     return toMssqlDatetime(v);
+      if (v instanceof Date)     return dateValues.toInstantUtcClock(v);
       if (Array.isArray(v))      return JSON.stringify(v);
       if (typeof v === 'object') return JSON.stringify(v);
       return String(v);
@@ -289,10 +282,13 @@ function coerceValue(v, type) {
       return v;                    // let SQL Server reject
 
     case 'date':
-      return toDateOnly(v);
+      return dateValues.toDateOnly(v);
 
     case 'datetime':
-      return toMssqlDatetime(v);
+      return dateValues.toInstantUtcClock(v);
+
+    case 'localdatetime':
+      return dateValues.toLocalDateTime(v);
 
     case 'object':
     case 'array':
@@ -304,13 +300,6 @@ function coerceValue(v, type) {
   }
 }
 
-// 'YYYY-MM-DD HH:MM:SS.mmm' in UTC — DATETIME2 parses this unambiguously.
-// Unparseable input passes through so SQL Server rejects it (→ error table).
-function toMssqlDatetime(v) {
-  var d = (v instanceof Date) ? v : new Date(v);
-  if (isNaN(d.getTime())) return v;
-  return d.toISOString().slice(0, 23).replace('T', ' ');
-}
 
 async function getTableSchema(pool, tableName, schema) {
   var r = await query(pool,