@xeplr/actions 2.1.0 → 2.2.0

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`.

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/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.0",
   "description": "Named-action registry with typed inputs and safe invocation — plus built-in actions for HTTP, DB, files, email, spawn",
   "main": "index.js",
   "scripts": {