@xeplr/actions 1.1.14 → 1.1.15

package/README.md

@@ -184,13 +184,16 @@ await actions.uploader.upload({
   columns,                // optional [{ name, type }] — declared; skips inference
   batchSize: 5000, firstBatchScanRows: 1000,
   metaStore, mtId1, mtId2, mtId3, mtId4, details,
-  errorTable, batchDir, keepBatchFiles, onProgress
+  errorTable, batchDir, keepBatchFiles, onProgress,
+  signal                  // optional AbortSignal: stop on request
 })
 // → { movementId, tables: { main, errors }, columns, totalRows, totalBatches, completed, dropped, aborted, durationMs }
 ```
 
 `onProgress({ rowsRead, batches, rowsWritten, phase? })` fires after each batch is read, with `rowsWritten` from the write queue's own count, so a caller can show both and see whether writing keeps up. After the read, while the queue drains, it fires again each time the written count moves (`phase: 'writing'`), never on a bare timer, so a stuck write goes quiet.
 
+`signal` (an `AbortSignal`, passed to db-move as `system.signal`) stops a running movement: the writes still queued are dropped at once (in-flight ones settle), the read stops at the next batch, and it ends with an error whose `code` is `'STOPPED'` (the runner keeps `error.code`), neither a failure nor a success. What it wrote stays, under its `movementId`, for the caller to roll back or keep.
+
 Rows are spooled to NDJSON files on disk between source and database. From the first batch it creates, if missing: the target table, `<targetTable>_import_errors` (`movement_id`, `row_num`, `error_description`, `underlying_sql`, `raw_row`, `recorded_at`), a `__xeplr_movement_id__` column, and a unique index on `primaryKeys`. Server dialects also add `__xeplr_id__`; DuckDB does not.
 
 Logical types and what each driver creates:
@@ -312,7 +315,7 @@ node --test test/uploader/reconcile.test.js
 
 | needs nothing | needs a database |
 |---|---|
-| `test/procedure-call.test.js`, `test/streaming/spool.test.js`, `test/uploader/reconcile.test.js`, `test/write-progress.test.js`, `test/formats/csv-gnarly.test.js`, `test/drivers/mysql.test.js`, `test/drivers/mssql.test.js`, `test/drivers/query-columns.test.js`, `test/builtins/email.test.js` (loads the package root, so `@xeplr/db` must be resolvable) | Postgres at `localhost:5435` (`PG_PASSWORD`, default `postgres`; database `xeplr_actions_test`): `test/drivers/postgres.test.js`, `test/builtins/db-push.test.js`, `test/builtins/file-upload.test.js`, `test/uploader/upload.test.js`; plus `@xeplr/db` for `test/uploader/meta-store-knex.test.js` |
+| `test/procedure-call.test.js`, `test/streaming/spool.test.js`, `test/uploader/reconcile.test.js`, `test/write-progress.test.js`, `test/stop-movement.test.js`, `test/formats/csv-gnarly.test.js`, `test/drivers/mysql.test.js`, `test/drivers/mssql.test.js`, `test/drivers/query-columns.test.js`, `test/builtins/email.test.js` (loads the package root, so `@xeplr/db` must be resolvable) | Postgres at `localhost:5435` (`PG_PASSWORD`, default `postgres`; database `xeplr_actions_test`): `test/drivers/postgres.test.js`, `test/builtins/db-push.test.js`, `test/builtins/file-upload.test.js`, `test/uploader/upload.test.js`; plus `@xeplr/db` for `test/uploader/meta-store-knex.test.js` |
 | `test/drivers/duckdb.test.js`, `test/drivers/duckdb-values.test.js` (needs `@duckdb/node-api`) | MySQL `localhost:3306` (`MYSQL_HOST/PORT/USER/PASSWORD`): `test/drivers/mysql-integration.test.js` |
 | | SQL Server `localhost:1433` (`MSSQL_HOST/PORT/USER/PASSWORD`): `test/drivers/mssql-integration.test.js` |
 | | Postgres + MySQL + SQL Server (`PG_*`, `MYSQL_*`, `MSSQL_*`): `test/builtins/db-replication.test.js` |

package/lib/builtins/db/move.js

@@ -304,7 +304,9 @@ module.exports = {
         // Passed through from the caller's `system`, not from `input` — a
         // progress reporter is a function, and an action's input is data that
         // has to survive being stored in a job row.
-        onProgress:     system.onProgress || null
+        onProgress:     system.onProgress || null,
+        // An AbortSignal from the caller: stop reading, drop the queued writes.
+        signal:         system.signal || null
       });
 
       // Every count upload() has, not just the headline one — "read" and

package/lib/runner.js

@@ -109,6 +109,8 @@ function finish(start, status, output, err) {
     if (err.stack) e.stack = err.stack;
     if (err.details) e.details = err.details;
     if (err.actionName) e.actionName = err.actionName;
+    // Kept, so a caller can tell a movement STOPPED on request from one that failed.
+    if (err.code) e.code = err.code;
   }
   return { status: status, output: output, error: e, durationMs: Date.now() - start };
 }

package/lib/uploader/index.js

@@ -77,6 +77,14 @@ async function upload(opts) {
   var spoolResult = null;
   var runDir = null;
 
+  // STOPPING ON REQUEST (opts.signal, an AbortSignal). The writes still queued
+  // are dropped the moment it fires — in-flight ones settle — and the read
+  // stops at the next batch. What was written stays, identified by
+  // movementId, for the caller to roll back or keep.
+  if (opts.signal && opts.signal.aborted) throw stoppedError();
+  var onStop = opts.signal ? function() { opts.queue.abort(opts.movementId, 'stopped'); } : null;
+  if (onStop) opts.signal.addEventListener('abort', onStop, { once: true });
+
   try {
     var summary = await spool(opts.source, {
       runId:        opts.movementId,
@@ -131,6 +139,7 @@ async function upload(opts) {
         // in turn awaits spool's next batch — the whole pipeline throttles
         // correctly, but disk (not memory) is the buffer.
         onBatch: async function(rows, meta) {
+          if (opts.signal && opts.signal.aborted) throw stoppedError();
           if (!columns) throw new Error('uploader: onBatch before beforeAll — spool contract violated');
           for (var off = 0; off < rows.length; off += effectiveBatchSize) {
             var chunk = rows.slice(off, off + effectiveBatchSize);
@@ -207,6 +216,8 @@ async function upload(opts) {
     } finally {
       if (drainWatch) drainWatch.stop();
     }
+    // Stopped while the queue drained: not a finished movement.
+    if (opts.signal && opts.signal.aborted) throw stoppedError();
 
     var stats = opts.queue.stats(opts.movementId) || {};
     var status = stats.aborted ? 'aborted' : 'completed';
@@ -236,9 +247,17 @@ async function upload(opts) {
       try { await fsp.rm(runDir, { recursive: true, force: true }); } catch (_) {}
     }
     if (!poolIsExternal && pool) await driver.close(pool);
+    if (onStop) opts.signal.removeEventListener('abort', onStop);
   }
 }
 
+/** The error a stopped movement ends with: code 'STOPPED', so a caller can tell it from a failure. */
+function stoppedError() {
+  var err = new Error('Stopped by request');
+  err.code = 'STOPPED';
+  return err;
+}
+
 // Rollback a movement — drop from main + error tables, clear meta row.
 // Graceful queue abort first (in-flight SQLs allowed to settle).
 //
@@ -406,6 +425,7 @@ var { inferColumnType } = require('./infer');
 module.exports = {
   upload:          upload,
   watchWrites:     watchWrites,
+  stoppedError:    stoppedError,
   rollback:        rollback,
   inferColumns:    inferColumns,
   inferColumnType: inferColumnType,

package/package.json

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