@xeplr/actions 2.1.0 → 2.2.1

package/README.md

@@ -64,10 +64,12 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 |---|---|
 | `register(def)` / `register(name, def)` | Add an action. Throws without `name` or `execute`, or with a `requires` module that is not installed (`ActionMissingDependencyError`). Re-registering a name replaces it. |
 | `get(name)` / `has(name)` | Look one up. |
-| `list()` | `[{ name, description, inputSchema, outputSchema, requires, event }]` — serializable, for an actions endpoint. `event` is `null` for an ordinary action. |
+| `list()` | `[{ name, description, inputSchema, outputSchema, requires, event, preview, example }]` — serializable, for an actions endpoint. `event` is `null` for an ordinary action; `preview` is `true` when the action can be previewed (the function itself never leaves the process). |
 | `clear()` | Empty the registry. |
 | `runAction({ name, input, system?, timeoutMs? })` | Run a registered action. Never throws. |
 | `runAction(nameOrDef, input, { system, timeoutMs, metaStore }?)` | Same, by name or with an action module directly. |
+| `previewAction({ name, input, system? })` / `previewAction(nameOrDef, input, opts?)` | What the step **would** hand on, without running it — see [Previews](#previews-what-a-step-would-hand-on). Never calls `execute`. Never throws. |
+| `PREVIEW_ROWS` | `5`: how many rows or items a preview reads. |
 | `ActionNotRegisteredError` | Returned (in `error`) for an unknown name. |
 | `ActionMissingDependencyError` | Thrown by `register()` for a missing `requires` module. |
 | `TransientError` | For an action to signal "retry me". Nothing in this package (or `@xeplr/jobs`) acts on it yet. |
@@ -89,6 +91,8 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 | `description` | Text for pickers. |
 | `inputSchema` | `[{ name, type, required, default, description, order, ... }]`, validated by `@xeplr/schema-handler` `applySchema`. Built-ins also use `group`, `showWhen`, `system`, `options`, `optionsFrom`, `dependsOn`, `label`, `hidden` (left out of a form unless a value is already set), `suggestFrom` / `suggestWith` (a host option source that suggests values, asked with the named sibling inputs; `db-procedure`'s parameters ask `procedureParams` with the connection, database and procedure) and `control` (`'parameters'`: `[{ name, value }]` shown as rows, a value fixed or bound to the run's window: `{window.from}` / `{window.to}`, see `@xeplr/jobs`) — hints for a form; validation treats every field the same. |
 | `outputSchema` | Optional documentation of the return value. |
+| `preview({ input, system })` | Optional. Resolves to `{ output, rows? }`: what `execute` would return, read **without a side effect** — at most `PREVIEW_ROWS` rows or items, never a write, a send, a move or a delete. Only for an action that can read safely. |
+| `example` | Optional. For an action that writes or sends: its output with example values, so a designer can show the shape without running it. |
 | `requires` | Module names checked with `require.resolve` at `register()`. |
 | `execute({ input, system, metaStore })` | Returns (or resolves to) the output. |
 | `event` | Optional. Makes this a **screen function** rather than a step: the event it is written for — `beforeLoad`, `beforeSave`, `afterSave`, `beforeDelete`, `onError` (run by `@xeplr/factory` around a screen's records) or `decide` (run by `@xeplr/workflow-engine` to choose a flow's next step). A screen names one per event and pickers offer only the functions for that event. It is called with the event's context — `execute(ctx)`, not `{ input, system }` — and never as a workflow step. |
@@ -101,6 +105,26 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 
 An unknown action, invalid input, a thrown or rejected `execute`, and a timeout (`timeoutMs`, message `Action timed out after Nms`) all come back as `status: 'failed'`. A timeout does not cancel the running work.
 
+### Previews: what a step would hand on
+
+A workflow designer shows a step's output before anything has run, so later steps can pick from it. Typing an example by hand was the only way, even where the output can simply be read. `previewAction` reads it instead, and **only ever calls an action's `preview`, never its `execute`**:
+
+```js
+{ status: 'success' | 'example' | 'failed', output, rows, error, durationMs }
+```
+
+- `success`: `output` is what the step would hand on (its shape, sample values); `rows` the first few rows or items when it reads some.
+- `example`: the action has no preview (it writes or sends); `output` is its declared `example`, or `null`. **Nothing ran.**
+- `failed`: the input is incomplete or the read failed; `error` says which.
+
+The input is checked exactly as a run checks it.
+
+| previewed (reads, up to 5) | example only (writes or sends; never run) |
+|---|---|
+| `db-fetch` (through the run's own cursor, then stops; nothing spooled), `db-list-tables` / `-views` / `-procedures` / `-columns`, `file-list`, `file-read`, `data-operation` (the run itself: it only computes), `email-read` (the mailbox opened **read-only**, IMAP `EXAMINE`, so nothing is marked read) | `file-move`, `file-delete`, `email-send`, `email-move`, `email-delete`, `email-download-email`, `email-download-attachments`, `export-table`, `export-pages`, `db-procedure` (a procedure may write) |
+
+Neither: `db-push`, `db-move`, `http-request` (an outside system, which may change something), `spawn-program`, `file-upload`; a designer asks for an example by hand. `test/previews.test.js` checks it on a real folder, file and Postgres: five rows read and no file spooled, the real count kept, a deleting step's file still there.
+
 ## Built-in actions
 
 Register the ones you want (`register(actions.builtins.dbFetch)`) or pass a module straight to `runAction`. `@xeplr/jobs` registers all implemented ones except `spawnProgram` and `dbMove`.
@@ -558,6 +582,32 @@ await driver.query(pool, userSql, params)          // reads only
 
 **Values are bound, never written into SQL.** On MySQL, `stringifyObjects` is always on, so an object or array passed as a value is compared as text instead of being expanded into `key = value` pairs. **Procedure parameter names** are written into the call (`@region = @p0`, `region => $1`) and must be plain names — letters, digits and `_`.
 
+## Stopping a query — the stop reaches the database
+
+A query nobody is waiting for must not keep running. Every driver's `query` and `fetchStream` take a stop signal and a time limit:
+
+```js
+const stop = new AbortController()
+await driver.query(pool, sql, params, { signal: stop.signal, timeoutMs: 120000 })
+for await (const row of driver.fetchStream(pool, { sql, params, signal: stop.signal, timeoutMs: 120000 })) { … }
+stop.abort(new Error('Nobody is waiting for this'))   // cancels it IN THE DATABASE
+```
+
+- **A stop cancels the query in the database, not just our read.** A `GROUP BY` or `ORDER BY` is worked out in full before the first row comes back, so a stop that only ended our read loop left the database working, holding its CPU and a connection, until it finished.
+- **The two errors:** `code: 'QUERY_STOPPED'`, whose message is the signal's reason; and `code: 'QUERY_TIMEOUT'`, "The database stopped this query after 2 minutes, its time limit…".
+- **A signal that has already fired:** the query is never sent.
+- **Neither option given:** the query runs exactly as before.
+
+| Driver | How it is stopped | Time limit |
+|---|---|---|
+| postgres | `pg_cancel_backend(<the query's backend>)`, sent on a connection of its own, so a pool whose connections are all busy (often with the very queries being stopped) cannot block it. The stopped query's connection is destroyed, not reused | `statement_timeout`, enforced by Postgres even if this process dies. For `fetchStream` it applies to each FETCH. On a writable connection it is set for the query and reset after, without adding a transaction |
+| duckdb | `interrupt()` on the query's own connection. A query still waiting for a free connection is let go before it runs | a timer that interrupts the same way |
+| mssql | `request.cancel()`, an attention on the query's own connection | a timer that cancels the same way (SQL Server has no per-statement limit) |
+| mysql | `KILL QUERY <thread id>`, sent on a connection of its own. The stopped query's connection is destroyed | a timer that kills the same way (`max_execution_time` covers SELECTs only, and MariaDB names it differently) |
+| mongo | not yet | — |
+
+The tests prove that the database itself let go: Postgres by `pg_stat_activity`, SQL Server by `sys.dm_exec_requests`, MySQL by the processlist, and DuckDB by its one connection answering at once (`test/drivers/stop.*.test.js`). The SQL Server and MySQL ones run when `MSSQL_*` and `MYSQL_*` are set.
+
 ## Rules the code enforces, and why
 
 | rule | why |

package/index.js

@@ -21,6 +21,10 @@ module.exports = {
   //   runAction({ name, input, system?, timeoutMs? })
   //   runAction(nameOrAction, input, opts?)
   runAction:     runner.runAction,
+  // What a step would hand on, read without a side effect (an action's
+  // `preview`), or its declared example. Never runs `execute`.
+  previewAction: runner.previewAction,
+  PREVIEW_ROWS:  runner.PREVIEW_ROWS,
 
   // Saved connections: an id in the definition, the login only in the call.
   // Shared by @xeplr/jobs and @xeplr/workflow-engine. See lib/connections.js.

package/lib/builtins/data-operation.js

@@ -114,6 +114,13 @@ module.exports = {
   // The same call every action gets from runAction: { input, system }. It
   // once took (input, context) — the runner's object landed in `input`,
   // `from` was undefined, and every workflow step returned no rows.
+  // Works only on the rows it is given — no database, no file, no send — so
+  // its preview is the run, over the sample rows the step before hands on.
+  preview: async function(call) {
+    var out = await module.exports.execute(call);
+    return { output: out, rows: (out && out.rows || []).slice(0, require('../runner').PREVIEW_ROWS) };
+  },
+
   execute: async function(call) {
     var input = (call && call.input) || {};
     var system = (call && call.system) || {};

package/lib/builtins/db/fetch.js

@@ -79,6 +79,31 @@ module.exports = {
       description: 'Rows pulled per cursor round-trip / stream highWaterMark.' }
   ],
 
+  // THE FIRST ROWS, through the same statement and cursor a run uses, then
+  // stop: nothing is spooled. The output is what a run hands on, with the
+  // file it would write named but not written.
+  preview: async function(ctx) {
+    var input = ctx.input || {};
+    var driver = dbDrivers.getDriver(input.dbType);
+    dbDrivers.checkDriverRequires('db-fetch', input.dbType, driver);
+    var built = buildFetchSql(driver, input);
+    var pool = await driver.connect(input.connection);
+    var rows = [];
+    try {
+      var stream = driver.fetchStream(pool, { sql: built.sql, params: built.params, batchSize: require('../../runner').PREVIEW_ROWS });
+      for await (var row of stream) {
+        rows.push(row);
+        if (rows.length >= require('../../runner').PREVIEW_ROWS) break;
+      }
+    } finally {
+      await driver.close(pool);
+    }
+    var output = input.streaming_mode === false
+      ? { rows: rows, rowCount: rows.length, streaming: false }
+      : { filePath: '(a file in this company\'s tmp/, written when it runs)', format: 'jsonl', bytes: 0, rows: rows.length, streaming: true };
+    return { output: output, rows: rows };
+  },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var system = ctx.system || {};

package/lib/builtins/db/list-columns.js

@@ -20,6 +20,9 @@ module.exports = {
       description: 'Schema the table lives in (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
   ],
 
+  // Only reads the database's own catalogue, so the preview is the run.
+  preview: async function(ctx) { return { output: await module.exports.execute(ctx) }; },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var driver = dbDrivers.getDriver(input.dbType);

package/lib/builtins/db/list-procedures.js

@@ -17,6 +17,9 @@ module.exports = {
       description: 'Schema to list (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
   ],
 
+  // Only reads the database's own catalogue, so the preview is the run.
+  preview: async function(ctx) { return { output: await module.exports.execute(ctx) }; },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var driver = dbDrivers.getDriver(input.dbType);

package/lib/builtins/db/list-tables.js

@@ -19,6 +19,9 @@ module.exports = {
       description: 'Schema to list (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
   ],
 
+  // Only reads the database's own catalogue, so the preview is the run.
+  preview: async function(ctx) { return { output: await module.exports.execute(ctx) }; },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var driver = dbDrivers.getDriver(input.dbType);

package/lib/builtins/db/list-views.js

@@ -16,6 +16,9 @@ module.exports = {
       description: 'Schema to list (postgres/mssql — default public/all; mysql ignores this in favor of connection.database)' }
   ],
 
+  // Only reads the database's own catalogue, so the preview is the run.
+  preview: async function(ctx) { return { output: await module.exports.execute(ctx) }; },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var driver = dbDrivers.getDriver(input.dbType);

package/lib/builtins/db/procedure.js

@@ -32,6 +32,8 @@ var { buildProcedureCall } = require('../../drivers/db/procedure');
 
 module.exports = {
   name: 'db-procedure',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { rows: [{ id: 1, status: 'done' }], rowCount: 1, procedure: 'close_period', sql: 'CALL close_period(?)' },
   description: 'Call a stored procedure with parameters. Returns its rows when it produces any — ' +
                'no target table, no movement. For a procedure whose rows you want written to a ' +
                'table, use db-move with mode="procedure".',

package/lib/builtins/email/delete.js

@@ -13,6 +13,8 @@ var emailConfig = require('../../drivers/email/config');
 
 module.exports = {
   name: 'email-delete',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { deleted: true, messageId: '4182', folder: 'INBOX' },
   description: 'Permanently delete a message (flags \\Deleted and expunges — NOT a move to Trash). ' +
                'The message id is folder-scoped, so input.folder must name the folder it is in.',
   requires: [],

package/lib/builtins/email/download-attachments.js

@@ -17,6 +17,8 @@ var fileNames = require('../../fileNames');
 
 module.exports = {
   name: 'email-download-attachments',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { count: 1, saved: [{ filename: 'invoice.pdf', path: 'mail/invoice.pdf', size: 91022, contentType: 'application/pdf' }], path: 'mail/invoice.pdf', existing: [], subject: 'Invoice 450103', messageId: '4182' },
   description: 'Save a message\'s attachments to disk, optionally filtered by extension or ' +
                'filename substring, named as you say. Returns { count, saved[], path, skipped, existing[] }.',
   requires: [],

package/lib/builtins/email/download-email.js

@@ -15,6 +15,8 @@ var fileNames = require('../../fileNames');
 
 module.exports = {
   name: 'email-download-email',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { count: 1, saved: [{ filename: 'Invoice 450103.eml', path: 'mail/Invoice 450103.eml', size: 48213, contentType: 'message/rfc822' }], path: 'mail/Invoice 450103.eml', existing: [], subject: 'Invoice 450103', messageId: '4182' },
   description: 'Save an entire message to disk as a .eml (RFC-822) file, streamed. ' +
                'Returns { count, saved[], path } like email-download-attachments.',
   requires: [],

package/lib/builtins/email/move.js

@@ -14,6 +14,8 @@ var emailConfig = require('../../drivers/email/config');
 
 module.exports = {
   name: 'email-move',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { moved: true, messageId: '4182', fromFolder: 'INBOX', toFolder: 'Processed' },
   description: 'Move a message to another mailbox folder. The message id is folder-scoped, ' +
                'so input.folder must name the folder the message is currently in.',
   requires: [],

package/lib/builtins/email/read.js

@@ -59,6 +59,14 @@ module.exports = {
       description: 'true → spool messages to an NDJSON file (output.filePath). false → inline output.messages.' }
   ],
 
+  // The first messages, with the mailbox opened READ-ONLY (IMAP EXAMINE), so
+  // a preview never marks anything read — whatever a full download does.
+  preview: async function(ctx) {
+    var input = Object.assign({}, ctx.input, { limit: require('../../runner').PREVIEW_ROWS, readOnly: true, streaming_mode: false });
+    var out = await module.exports.execute({ input: input, system: ctx.system });
+    return { output: out, rows: out.messages };
+  },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var system = ctx.system || {};

package/lib/builtins/export/pages.js

@@ -66,6 +66,8 @@ function validate(spec) {
 
 module.exports = {
   name: 'export-pages',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { filePath: 'exports/board.pdf', fileName: 'board.pdf', contentType: 'application/pdf', bytes: 220514, pages: 3 },
   description: 'Lay out pages of placed blocks (text, tables, images, shapes) as a PDF — a dashboard as it looked.',
   requires: [],
   LIMITS: LIMITS,

package/lib/builtins/export/table.js

@@ -57,6 +57,8 @@ function columnsOf(rows) {
 
 module.exports = {
   name: 'export-table',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { filePath: 'exports/sales.xlsx', fileName: 'sales.xlsx', contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', bytes: 18432, rows: 1420, truncated: false, skipped: false },
   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: [],

package/lib/builtins/file/delete.js

@@ -11,6 +11,8 @@ var dataDir = require('../../dataDir');
 
 module.exports = {
   name: 'file-delete',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { path: 'bank/inbox/sept.csv', deleted: true, skipped: false },
   description: 'Delete one file, permanently (file-move to a "processed" folder is the reversible one). Returns { path, deleted, skipped }.',
   requires: [],
   inputSchema: [

package/lib/builtins/file/list.js

@@ -36,6 +36,12 @@ module.exports = {
     { name: 'count', type: 'number', description: 'How many, so the next step can branch on none.' }
   ],
 
+  // Listing only reads the folder; the preview is the run, its first files.
+  preview: async function(ctx) {
+    var out = await module.exports.execute(ctx);
+    return { output: { files: out.files.slice(0, require('../../runner').PREVIEW_ROWS), count: out.count }, rows: out.files.slice(0, require('../../runner').PREVIEW_ROWS) };
+  },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var dir = dataDir.resolve(input.folder, 'The folder');

package/lib/builtins/file/move.js

@@ -12,6 +12,8 @@ var fileNames = require('../../fileNames');
 
 module.exports = {
   name: 'file-move',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { path: 'bank/processed/sept.csv', name: 'sept.csv', moved: true, skipped: false },
   description: 'Move or copy a file into a folder, or to a new name. Returns { path, name, moved, skipped }.',
   requires: [],
   inputSchema: [

package/lib/builtins/file/read.js

@@ -38,6 +38,12 @@ module.exports = {
     { name: 'truncated', type: 'boolean' }
   ],
 
+  // The file's first rows: reading never changes it.
+  preview: async function(ctx) {
+    var out = await module.exports.execute({ input: Object.assign({}, ctx.input, { maxRows: require('../../runner').PREVIEW_ROWS }), system: ctx.system });
+    return { output: out, rows: out.rows };
+  },
+
   execute: async function(ctx) {
     var input = ctx.input || {};
     var file = dataDir.resolve(input.path, 'The file');

package/lib/builtins/send-email.js

@@ -48,6 +48,8 @@ var emailConfig = require('../drivers/email/config');
 
 module.exports = {
   name: 'email-send',
+  // What it hands on, with example values: it writes, so it is never previewed.
+  example: { sent: true, messageId: '<4182@mail.acme.com>', accepted: ['asha@acme.com'], rejected: [], response: '250 OK' },
   description: 'Send an email over SMTP. Attachments accept { filename, path } descriptors, ' +
                'so email-download-attachments output can be forwarded directly.',
   requires: [],   // nodemailer checked at runtime

package/lib/drivers/db/duckdb.js

@@ -349,6 +349,33 @@ async function acquire(entry) {
   return new Promise(function(resolve) { entry.waiters.push(resolve); });
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// DuckDB runs in this process, so a stop is conn.interrupt() on the query's
+// own connection, and the time limit is a timer that does the same. A query
+// still waiting for a free connection is let go of before it ever runs.
+var stop = require('./stop');
+
+/** acquire(), unless the stop comes first; a connection that arrives too late goes straight back. */
+function acquireUnlessStopped(entry, signal) {
+  if (!signal) return acquire(entry);
+  stop.throwIfStopped(signal);
+  return new Promise(function(resolve, reject) {
+    var gaveUp = false;
+    function onAbort() { gaveUp = true; reject(stop.stoppedError(signal)); }
+    signal.addEventListener('abort', onAbort, { once: true });
+    acquire(entry).then(function(conn) {
+      signal.removeEventListener('abort', onAbort);
+      if (gaveUp) release(entry, conn);
+      else resolve(conn);
+    }, function(err) { signal.removeEventListener('abort', onAbort); reject(err); });
+  });
+}
+
+/** Watch one connection's query: interrupt it on a stop or past the limit. */
+function watchConn(conn, opts) {
+  return stop.watch(opts && opts.signal, opts && opts.timeoutMs, function() { conn.interrupt(); });
+}
+
 function release(entry, conn) {
   var waiter = entry.waiters.shift();
   if (waiter) waiter(conn);
@@ -421,10 +448,11 @@ function plainDeep(v) {
  * The result's OWN return type is what distinguishes the two cases, so that is
  * what this reads. CHANGED_ROWS is DML; QUERY_RESULT is a select.
  */
-async function query(pool, sql, params) {
+async function query(pool, sql, params, opts) {
   var entry = entryOf(pool);
   refuseIndex(entry, sql);
-  var conn = await acquire(entry);
+  var conn = await acquireUnlessStopped(entry, opts && opts.signal);
+  var w = watchConn(conn, opts);
   try {
     var api = require('@duckdb/node-api');
     var reader = await conn.runAndReadAll(sql, params && params.length ? params : undefined);
@@ -441,8 +469,10 @@ async function query(pool, sql, params) {
     });
     return { rows: rows, rowCount: rows.length, columns: columns };
   } catch (err) {
+    if (w.why()) throw w.why();
     throw explainLockError(err, entry.key, entry.access, 0);
   } finally {
+    w.done();
     release(entry, conn);
   }
 }
@@ -756,7 +786,8 @@ async function plainValuesPlan(conn, sql) {
  */
 async function* fetchStream(pool, opts) {
   var entry = entryOf(pool);
-  var conn = await acquire(entry);
+  var conn = await acquireUnlessStopped(entry, opts.signal);
+  var w = watchConn(conn, opts);
   try {
     var plan = await plainValuesPlan(conn, opts.sql);
     var result = await conn.stream(plan.sql, (opts.params && opts.params.length) ? opts.params : undefined);
@@ -764,6 +795,7 @@ async function* fetchStream(pool, opts) {
     var dates = plan.dateColumns;
     var jsons = plan.jsonColumns;
     while (true) {
+      if (w.why()) throw w.why();
       var chunk = await result.fetchChunk();
       if (!chunk || chunk.rowCount === 0) break;
       var rows = chunk.getRowObjects(names);
@@ -783,8 +815,10 @@ async function* fetchStream(pool, opts) {
       }
     }
   } catch (err) {
+    if (w.why()) throw w.why();
     throw explainLockError(err, entry.key, entry.access, 0);
   } finally {
+    w.done();
     release(entry, conn);
   }
 }

package/lib/drivers/db/mssql.js

@@ -96,17 +96,34 @@ async function close(pool) {
   if (pool) await pool.close();
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// A stop is request.cancel(): an ATTENTION sent on the query's own
+// connection, which SQL Server answers by abandoning the batch. SQL Server
+// has no per-statement time limit of its own, so the limit is a timer here
+// that cancels the same way.
+var stop = require('./stop');
+
 // Bind params as @p0..@pN and normalize `{ recordset, rowsAffected }` to
 // Postgres shape. NOTE: mssql infers the SQL type from each JS value; a null
 // with no sibling non-null value in the batch falls back to NVARCHAR, which is
 // fine for our INSERTs since the column type is already declared.
-async function query(pool, sql, params) {
+async function query(pool, sql, params, opts) {
+  opts = opts || {};
+  stop.throwIfStopped(opts.signal);
   var request = pool.request();
   params = params || [];
   for (var i = 0; i < params.length; i++) {
     request.input('p' + i, params[i]);
   }
-  var r = await request.query(sql);
+  var w = stop.watch(opts.signal, opts.timeoutMs, function() { request.cancel(); });
+  var r;
+  try {
+    r = await request.query(sql);
+  } catch (err) {
+    throw w.why() || err;
+  } finally {
+    w.done();
+  }
   var rows = r.recordset || [];
   var rowCount = Array.isArray(r.rowsAffected)
     ? r.rowsAffected.reduce(function(a, b) { return a + b; }, 0)
@@ -382,8 +399,9 @@ async function ensureUpsertIndex(pool, tableName, primaryKeys) {
 // with real backpressure: pause the request once `batchSize` rows are buffered,
 // resume after the consumer drains them.
 //
-//   opts: { sql, params?, batchSize? }  →  async iterable<row>
+//   opts: { sql, params?, batchSize?, signal?, timeoutMs? }  →  async iterable<row>
 async function* fetchStream(pool, opts) {
+  stop.throwIfStopped(opts.signal);
   var high = Math.max(1, parseInt(opts.batchSize || 1000, 10));
   var request = pool.request();
   var params = opts.params || [];
@@ -406,12 +424,21 @@ async function* fetchStream(pool, opts) {
   request.on('error', function(err) { error = err; signal(); });
   request.on('done',  function()    { done = true;  signal(); });
 
+  // A stop cancels the request and wakes the consumer, which may be waiting
+  // for a first row the server is still working out.
+  var w = stop.watch(opts.signal, opts.timeoutMs, function() {
+    try { request.cancel(); } catch (_) {}
+    error = error || w.why();
+    signal();
+  });
+
   // Fire the query — with stream=true this drives the events above. We don't
   // await the returned promise; the events are the source of truth.
   request.query(opts.sql).catch(function(err) { error = error || err; signal(); });
 
   try {
     while (true) {
+      if (w.why()) throw w.why();
       if (buffer.length) {
         var batch = buffer;
         buffer = [];
@@ -419,11 +446,12 @@ async function* fetchStream(pool, opts) {
         for (var j = 0; j < batch.length; j++) yield batch[j];
         continue;
       }
-      if (error) throw error;
+      if (error) throw w.why() || error;
       if (done) return;
       await new Promise(function(res) { wake = res; });
     }
   } finally {
+    w.done();
     // If the consumer breaks out early, stop the underlying request.
     if (!done && !error) { try { request.cancel(); } catch (_) {} }
   }

package/lib/drivers/db/mysql.js

@@ -106,13 +106,67 @@ async function close(pool) {
   if (pool) await pool.end();
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// A stop is KILL QUERY <the connection's thread id>, sent on a connection of
+// its own: the pool's may all be busy with the very queries being stopped.
+// The time limit is a timer here that kills the same way — MySQL's own
+// max_execution_time covers SELECTs only, and MariaDB spells it differently.
+var stop = require('./stop');
+
+/** Kill whatever thread `threadId` is running, from a connection of its own. */
+async function killQuery(pool, threadId) {
+  var mysql = require('mysql2/promise');
+  var c = pool.pool.config.connectionConfig;
+  var conn = await mysql.createConnection({ host: c.host, port: c.port, user: c.user, password: c.password, connectTimeout: 5000 });
+  try {
+    await conn.query('KILL QUERY ' + Number(threadId));
+  } finally {
+    await conn.end().catch(function() {});
+  }
+}
+
+/** Watch one checked-out connection's query; `killed` is the pending kill. */
+function watchConn(pool, conn, opts) {
+  var state = { killed: null };
+  state.w = stop.watch(opts.signal, opts.timeoutMs, function() {
+    state.killed = killQuery(pool, conn.connection.threadId).catch(function() { /* it finished first, or the server is gone */ });
+  });
+  return state;
+}
+
+/** Give the connection back — destroyed when a query on it was stopped. */
+async function giveBack(state, conn) {
+  state.w.done();
+  if (state.killed) await state.killed;
+  if (state.w.why()) conn.destroy();
+  else conn.release();
+}
+
 // Normalize mysql2's `[rows|ResultSetHeader, fields]` to Postgres shape.
 //
 // The second element is the field list, which mysql2 returns even for a
 // SELECT that matched nothing — so `columns` describes the result's shape
 // when there is not a single row to infer it from.
-async function query(pool, sql, params) {
-  var res = await pool.query(sql, params || []);
+async function query(pool, sql, params, opts) {
+  opts = opts || {};
+  stop.throwIfStopped(opts.signal);
+  var res;
+  if (opts.signal || stop.limitOf(opts.timeoutMs)) {
+    var conn = await pool.getConnection();
+    var state = watchConn(pool, conn, opts);
+    try {
+      res = await conn.query(sql, params || []);
+      // A killed statement can still come back normally (SLEEP() answers 1
+      // when killed): stopped is stopped, whatever it returned.
+      if (state.w.why()) throw state.w.why();
+    } catch (err) {
+      throw state.w.why() || err;
+    } finally {
+      await giveBack(state, conn);
+    }
+  } else {
+    res = await pool.query(sql, params || []);
+  }
   var out = res[0];
   var fields = res[1];
 
@@ -412,10 +466,12 @@ function upsertIndexName(tableName) {
 // `for await` over it applies backpressure (highWaterMark bounds the rows
 // buffered in the driver before it pauses reading from the socket).
 //
-//   opts: { sql, params?, batchSize? }  →  async iterable<row>
+//   opts: { sql, params?, batchSize?, signal?, timeoutMs? }  →  async iterable<row>
 async function* fetchStream(pool, opts) {
+  stop.throwIfStopped(opts.signal);
   var batchSize = Math.max(1, parseInt(opts.batchSize || 1000, 10));
   var conn = await pool.getConnection();
+  var state = watchConn(pool, conn, opts);
   try {
     // .stream() lives on the core (non-promise) connection under .connection.
     var core = conn.connection;
@@ -423,9 +479,15 @@ async function* fetchStream(pool, opts) {
       ? { sql: opts.sql, values: opts.params }
       : opts.sql;
     var stream = core.query(q).stream({ highWaterMark: batchSize });
-    for await (var row of stream) yield row;
+    for await (var row of stream) {
+      if (state.w.why()) throw state.w.why();
+      yield row;
+    }
+    if (state.w.why()) throw state.w.why();
+  } catch (err) {
+    throw state.w.why() || err;
   } finally {
-    conn.release();
+    await giveBack(state, conn);
   }
 }
 

package/lib/drivers/db/postgres.js

@@ -8,7 +8,7 @@
 //
 //   requires:                 ['pg']
 //   async connect(config)                       → pool
-//   async query(pool, sql, params?)             → { rows, rowCount, ... }
+//   async query(pool, sql, params?, { signal?, timeoutMs }?)  → { rows, rowCount, ... }
 //   async close(pool)                           → void
 //
 //   buildCreateTableSql(tableName, columns, primaryKeys?)  → string
@@ -82,6 +82,56 @@ async function close(pool) {
   if (pool) await pool.end();
 }
 
+// ── STOPPING A QUERY (stop.js) ─────────────────────────────────────────────
+// A stop is pg_cancel_backend(<its backend's pid>), sent on a connection of
+// its own: the pool's may all be busy — quite possibly with the very queries
+// being stopped — and a cancel that waits for a free one never arrives. The
+// time limit is statement_timeout, so Postgres enforces it even if this
+// process dies; our own timer, a little later, is only the backstop.
+var stop = require('./stop');
+var QUERY_CANCELED = '57014';
+var BACKSTOP_MS = 2000;
+
+/** Cancel whatever `pid` is running, from a connection of its own. */
+async function cancelBackend(pool, pid) {
+  var pg = require('pg');
+  var o = pool.options || {};
+  var c = new pg.Client({ host: o.host, port: o.port, user: o.user, password: o.password, database: o.database, connectionTimeoutMillis: 5000 });
+  try {
+    await c.connect();
+    await c.query('SELECT pg_cancel_backend($1)', [pid]);
+  } finally {
+    await c.end().catch(function() {});
+  }
+}
+
+/**
+ * Watch one checked-out client's query for `opts` (signal, timeoutMs).
+ * `cancelled` is the pending cancel, awaited before the client goes back.
+ */
+function watchClient(pool, client, opts) {
+  var limit = stop.limitOf(opts.timeoutMs);
+  var state = { cancelled: null, limit: limit };
+  state.w = stop.watch(opts.signal, limit ? limit + BACKSTOP_MS : 0, function() {
+    state.cancelled = cancelBackend(pool, client.processID).catch(function() { /* it finished first, or the server is gone */ });
+  });
+  return state;
+}
+
+/** The error to reject with: ours when we stopped it, the time limit when Postgres did. */
+function stopReason(state, err) {
+  if (state.w.why()) return state.w.why();
+  if (err && err.code === QUERY_CANCELED && state.limit) return stop.timeoutError(state.limit);
+  return err;
+}
+
+/** Give the client back — destroyed when a query on it was stopped, so no half-cancelled state is reused. */
+async function giveBack(state, client) {
+  state.w.done();
+  if (state.cancelled) await state.cancelled;
+  client.release(state.w.why() ? true : undefined);
+}
+
 // `columns` is the query's OUTPUT COLUMNS, which the server describes whether
 // or not any row matched. Callers that need the shape of a result — a report
 // listing its columns, say — must not have to infer it from the first row,
@@ -90,16 +140,33 @@ async function close(pool) {
 // Attached to pg's own Result rather than wrapping it: callers already treat
 // this as the canonical shape the other drivers normalize TO, so replacing
 // the object risks dropping a property something else reads.
-async function query(pool, sql, params) {
+async function query(pool, sql, params, opts) {
+  opts = opts || {};
+  stop.throwIfStopped(opts.signal);
   var result;
-  if (pool.__xeplrReadOnly) {
+  var limit = stop.limitOf(opts.timeoutMs);
+  if (pool.__xeplrReadOnly || opts.signal || limit) {
+    var readOnly = Boolean(pool.__xeplrReadOnly);
     var client = await pool.connect();
+    var state = watchClient(pool, client, opts);
     try {
-      await client.query('BEGIN TRANSACTION READ ONLY');
-      result = await client.query({ text: sql, values: params || [], queryMode: 'extended' });
+      // Read-only: inside its own transaction, the limit with it (LOCAL).
+      // Otherwise the statement runs as it always did — no transaction added,
+      // which some statements refuse — and the limit is on the session until
+      // it is reset below.
+      if (readOnly) await client.query('BEGIN TRANSACTION READ ONLY');
+      if (limit) await client.query((readOnly ? 'SET LOCAL' : 'SET') + ' statement_timeout = ' + limit);
+      result = await client.query(readOnly ? { text: sql, values: params || [], queryMode: 'extended' } : sql, readOnly ? undefined : (params || []));
+    } catch (err) {
+      throw stopReason(state, err);
     } finally {
-      try { await client.query('ROLLBACK'); } catch (_) { /* the connection is released either way */ }
-      client.release();
+      if (!state.w.why()) {
+        try {
+          if (readOnly) await client.query('ROLLBACK');
+          else if (limit) await client.query('RESET statement_timeout');
+        } catch (_) { /* the connection is released either way */ }
+      }
+      await giveBack(state, client);
     }
   } else {
     result = await pool.query(sql, params || []);
@@ -342,14 +409,23 @@ async function listProcedures(pool, schema) {
 // rows at a time. The async generator naturally applies backpressure: the next
 // FETCH only fires when the consumer asks for more.
 //
-//   opts: { sql, params?, batchSize? }  →  async iterable<row>
+//   opts: { sql, params?, batchSize?, signal?, timeoutMs? }  →  async iterable<row>
+//
+// A GROUP BY or ORDER BY is worked out in full by the FIRST FETCH, which can
+// take minutes — so a stop must cancel that FETCH in Postgres, not wait for
+// it to come back. timeoutMs is per statement (each FETCH), as Postgres
+// counts it.
 async function* fetchStream(pool, opts) {
+  stop.throwIfStopped(opts.signal);
   var batchSize = Math.max(1, parseInt(opts.batchSize || 1000, 10));
+  var limit = stop.limitOf(opts.timeoutMs);
   var client = await pool.connect();
+  var state = watchClient(pool, client, opts);
   var declared = false;
   try {
     var readOnly = Boolean(pool.__xeplrReadOnly);
     await client.query(readOnly ? 'BEGIN TRANSACTION READ ONLY' : 'BEGIN');
+    if (limit) await client.query('SET LOCAL statement_timeout = ' + limit);
     // Extended protocol when read-only: one statement, so the caller's SQL
     // cannot close the cursor declaration and carry on with its own.
     await client.query(readOnly
@@ -357,14 +433,19 @@ async function* fetchStream(pool, opts) {
       : 'DECLARE __xeplr_fetch_cur NO SCROLL CURSOR FOR ' + opts.sql, readOnly ? undefined : (opts.params || []));
     declared = true;
     while (true) {
+      if (state.w.why()) throw state.w.why();
       var res = await client.query('FETCH FORWARD ' + batchSize + ' FROM __xeplr_fetch_cur');
       if (res.rows.length === 0) break;
       for (var i = 0; i < res.rows.length; i++) yield res.rows[i];
     }
+  } catch (err) {
+    throw stopReason(state, err);
   } finally {
-    try { if (declared) await client.query('CLOSE __xeplr_fetch_cur'); } catch (_) {}
-    try { await client.query(pool.__xeplrReadOnly ? 'ROLLBACK' : 'COMMIT'); } catch (_) {}
-    client.release();
+    if (!state.w.why()) {
+      try { if (declared) await client.query('CLOSE __xeplr_fetch_cur'); } catch (_) {}
+      try { await client.query(pool.__xeplrReadOnly ? 'ROLLBACK' : 'COMMIT'); } catch (_) {}
+    }
+    await giveBack(state, client);
   }
 }
 

package/lib/drivers/db/stop.js

@@ -0,0 +1,89 @@
+// STOPPING A QUERY — the part every driver shares.
+//
+// A query nobody is waiting for must not run (see CLAUDE.md, "No query runs
+// that nobody needs"). Every driver's query() and fetchStream() take
+//
+//   signal      an AbortSignal: when it fires, the query is CANCELLED IN THE
+//               DATABASE (each driver's own way), not just abandoned here —
+//               a GROUP BY the database is still working on would otherwise
+//               keep its CPU and its connection until it finished
+//   timeoutMs   a time limit; past it the query is cancelled the same way
+//
+// and reject with one of two errors a caller can tell apart:
+//
+//   code QUERY_STOPPED   the signal fired; the message is its reason's
+//   code QUERY_TIMEOUT   the time limit passed
+//
+// Neither is given: the query runs as it always did.
+
+/** The error a stopped query rejects with. */
+function stoppedError(signal) {
+  var reason = signal && signal.reason;
+  // abort() with no reason gives a generic AbortError: say it in our words.
+  var said = reason && reason.name !== 'AbortError' && reason.message;
+  var err = new Error(said || 'The query was stopped');
+  err.code = 'QUERY_STOPPED';
+  return err;
+}
+
+/** "45 seconds", "2 minutes" — how long a limit is, as a person says it. */
+function durationText(ms) {
+  var secs = Math.max(1, Math.round(ms / 1000));
+  if (secs < 60) return secs + ' second' + (secs === 1 ? '' : 's');
+  var mins = Math.round(secs / 60);
+  return mins + ' minute' + (mins === 1 ? '' : 's');
+}
+
+/** The error a query past its time limit rejects with. */
+function timeoutError(timeoutMs) {
+  var err = new Error('The database stopped this query after ' + durationText(timeoutMs) +
+    ', its time limit. Narrow it with a filter or a shorter date range, then run it again.');
+  err.code = 'QUERY_TIMEOUT';
+  return err;
+}
+
+/** A positive whole number of milliseconds, or 0 for no limit. */
+function limitOf(timeoutMs) {
+  var n = Math.floor(Number(timeoutMs));
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Watch one query: call `cancel()` once — when `signal` fires or `timeoutMs`
+ * passes, whichever is first — and remember why. `why()` is the error to
+ * reject with after the database has given up the query (null: not stopped).
+ * `done()` stops watching; call it in a finally.
+ */
+function watch(signal, timeoutMs, cancel) {
+  var limit = limitOf(timeoutMs);
+  var reason = null;
+  var timer = null;
+  function fire(err) {
+    if (reason) return;
+    reason = err;
+    try { cancel(); } catch (_) { /* the driver's cancel reports its own failures */ }
+  }
+  function onAbort() { fire(stoppedError(signal)); }
+  if (signal) {
+    if (signal.aborted) onAbort();
+    else signal.addEventListener('abort', onAbort, { once: true });
+  }
+  if (limit && !reason) {
+    timer = setTimeout(function() { fire(timeoutError(limit)); }, limit);
+    if (timer.unref) timer.unref();
+  }
+  return {
+    why: function() { return reason; },
+    done: function() {
+      if (timer) clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+    }
+  };
+}
+
+/** Throw now when the signal has already fired: never start a query nobody wants. */
+function throwIfStopped(signal) {
+  if (signal && signal.aborted) throw stoppedError(signal);
+}
+
+module.exports = { watch: watch, throwIfStopped: throwIfStopped, stoppedError: stoppedError, timeoutError: timeoutError, limitOf: limitOf, durationText: durationText };

package/lib/drivers/email/imap.js

@@ -95,7 +95,7 @@ function buildClientConfig(action, connection) {
 // through this so the release/logout pair can never be forgotten in one of
 // them. `logout()` is best-effort in its own catch: a failure there must not
 // mask the real error from the work, and must not fail an op that succeeded.
-async function withMailbox(action, connection, folder, fn) {
+async function withMailbox(action, connection, folder, fn, readOnly) {
   // Config FIRST, deps second. Validating the connection needs no peer dep, so
   // a misconfigured connection reports the missing field even on a host that
   // hasn't installed imapflow — otherwise the dep error masks the real one.
@@ -105,7 +105,9 @@ async function withMailbox(action, connection, folder, fn) {
 
   await client.connect();
   try {
-    var lock = await client.getMailboxLock(folder || 'INBOX');
+    // Read-only (IMAP EXAMINE) for a preview: nothing it fetches can mark a
+    // message read, whatever the server does on a full download.
+    var lock = await client.getMailboxLock(folder || 'INBOX', readOnly ? { readOnly: true } : undefined);
     try {
       return await fn(client);
     } finally {
@@ -257,7 +259,7 @@ async function read(connection, input) {
       });
     }
     return out;
-  });
+  }, input.readOnly === true);
 }
 
 /** Move one message to another folder. Returns the shape the action wraps. */

package/lib/registry.js

@@ -9,6 +9,15 @@
 //     outputSchema : array?     — optional; documents what the action returns
 //     requires     : string[]?  — peer-dep module names checked at register time
 //     execute      : function   — async ({ input, system }) => output
+//     preview      : function?  — async ({ input, system }) => { output, rows? }:
+//                                 what execute WOULD hand on, read without a
+//                                 side effect — a few rows, never a write, a
+//                                 send, a move or a delete. A designer shows it
+//                                 before anything has run (runner.previewAction).
+//     example      : object?    — for an action that cannot be previewed
+//                                 safely (it writes or sends): its output with
+//                                 example values, so a designer still shows
+//                                 the shape.
 //     event        : string?    — a SCREEN FUNCTION, not a step: the event it
 //                                 is written for ('beforeSave', 'decide', …).
 //                                 Called with that event's own context instead
@@ -61,6 +70,8 @@ function register(nameOrDef, def) {
     outputSchema: action.outputSchema || null,
     requires:     Array.isArray(action.requires) ? action.requires.slice() : [],
     event:        action.event || null,
+    preview:      typeof action.preview === 'function' ? action.preview : null,
+    example:      action.example && typeof action.example === 'object' ? action.example : null,
     execute:      action.execute
   });
 }
@@ -78,7 +89,11 @@ function list() {
       inputSchema: def.inputSchema,
       outputSchema: def.outputSchema,
       requires: def.requires,
-      event: def.event
+      event: def.event,
+      // Whether a designer can ask for a preview — the function itself never
+      // leaves the process.
+      preview: Boolean(def.preview),
+      example: def.example
     });
   });
   return out;

package/lib/runner.js

@@ -43,6 +43,40 @@ async function runAction(first, second, third) {
   }
 }
 
+/**
+ * WHAT A STEP WOULD HAND ON, without running it. Calls the action's `preview`
+ * — never `execute` — with the input checked exactly as a run checks it.
+ *
+ * Returns { status, output, rows, error, durationMs }:
+ *   status 'success'  output is what execute would return (its shape and
+ *                     sample values); rows, when the action reads rows, the
+ *                     first few of them.
+ *   status 'example'  the action cannot be previewed safely; output is its
+ *                     declared example (or null).
+ *   status 'failed'   the input is incomplete or the read failed — error says.
+ * Never throws.
+ */
+async function previewAction(first, second, third) {
+  var start = Date.now();
+  var opts = normalizeArgs(first, second, third);
+  var def = opts.action || get(opts.name);
+  if (!def) return Object.assign(finish(start, 'failed', null, new ActionNotRegisteredError(opts.name)), { rows: null });
+  if (typeof def.preview !== 'function') {
+    return Object.assign(finish(start, 'example', def.example || null, null), { rows: null });
+  }
+  try {
+    var input = applySchema(def.inputSchema, coerceScalars(def.inputSchema, opts.input || {}), 'input');
+    var seen = await def.preview({ input: input, system: opts.system || {}, metaStore: opts.metaStore });
+    seen = seen || {};
+    return Object.assign(finish(start, 'success', seen.output === undefined ? null : seen.output, null), { rows: seen.rows || null });
+  } catch (err) {
+    return Object.assign(finish(start, 'failed', null, err), { rows: null });
+  }
+}
+
+/** How many rows a preview reads: enough to see, never the data. */
+var PREVIEW_ROWS = 5;
+
 /**
  * ONE VALUE WHERE A LIST WAS DECLARED MEANS A LIST OF ONE.
  *
@@ -125,4 +159,4 @@ function withTimeout(promise, ms) {
   });
 }
 
-module.exports = { runAction: runAction };
+module.exports = { runAction: runAction, previewAction: previewAction, PREVIEW_ROWS: PREVIEW_ROWS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {