@xeplr/actions 1.1.23 → 1.2.0

package/README.md

@@ -87,7 +87,7 @@ var moved = await actions.runAction(actions.builtins.dbMove, {
 |---|---|
 | `name` | Required. |
 | `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` — hints for a form; validation treats every field the same. |
+| `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) 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. |
 | `requires` | Module names checked with `require.resolve` at `register()`. |
 | `execute({ input, system, metaStore })` | Returns (or resolves to) the output. |
@@ -159,7 +159,7 @@ For `mode: 'table'` the source's declared column types (`getTableSchema`) are pa
 | `mysql` | `CALL name(?, ?)` — positional; names are ignored (and logged as such) |
 | `postgres` | `SELECT * FROM fn(param => …)` when `returnsRows` (default `true`), `CALL proc(param => …)` when `false` |
 
-`params` is `[{ name, value }]` or bare values; values are always bound. `''` becomes `null`, integer- and decimal-looking strings become numbers, and an object value is an error naming the parameter. A schema-qualified name (`dbo.usp_x`) is quoted per part. `window: { from, to, fromParam, toParam }` appends the two bounds as parameters after `params` (null edges passed as `NULL`); a window without `fromParam`/`toParam` is refused. `maxRows` fails the run when more rows come back. If `system.log` is supplied it gets the statement, parameter count and window bounds — not the other parameter values.
+`params` is `[{ name, value }]` or bare values; values are always bound. `''` becomes `null`, integer- and decimal-looking strings become numbers, and an object value is an error naming the parameter. A schema-qualified name (`dbo.usp_x`) is quoted per part. `window: { from, to, fromParam, toParam }` appends the two bounds as parameters after `params` (null edges passed as `NULL`); a window without `fromParam`/`toParam` is refused. From a job, the usual way to pass dates is as ordinary parameters bound to the run's window, `{ "name": "startDate", "value": "{window.from}" }` (`@xeplr/jobs` fills them in); `params` carries `control: 'parameters'` and `window` is `hidden`, so a form shows rows instead of JSON. `maxRows` fails the run when more rows come back. If `system.log` is supplied it gets the statement, parameter count and window bounds — not the other parameter values.
 
 ### Email
 
@@ -348,6 +348,10 @@ On Postgres, MySQL and SQL Server the staging table is shaped like the target (`
 
 **Before loading: the file against the table.** `uploader.compareToTable({ driver, connection, targetTable, columns })` → `{ exists, matched, extra, missing: [{ name, required }] }`, matched by exact name, the framework's columns left out. `extra` (in the file, not the table) means the import will be refused; `missing` columns are left empty, and `required` ones (no empty value, no default) mean every row will be refused. `formats.columnsOf(format, filePath, { sheet? })` gives a file's columns from its first row. Every driver's `getTableSchema` now says `nullable` and `hasDefault` (an identity or auto-increment counts as a default).
 
+### The uploader's own tables
+
+Beside the tables it loads, the uploader makes three of its own: `<table>_import_errors` (refused rows), `<table>__xeplr_staging` (a staged load in progress) and, in a DuckDB file, `__xeplr_loads` (its ledger). `isInternalTable(name)` (also accepts a listing row `{ name }`) says whether a table is one of these, so an app listing a database's tables for people to pick from can leave them out. They still exist and are read where they belong.
+
 ### A written DuckDB file keeps no index
 
 DuckDB 1.5.4–1.5.6 has a bug ([duckdb/duckdb#26106](https://github.com/duckdb/duckdb/issues/26106), open upstream): when a process dies with rows still only in the WAL, the next open replays them into the table and the next checkpoint drops them from every index on it. The first `DELETE` that reaches one fails with *"Failed to delete all rows from index"*, which is **FATAL**: the whole file is unusable until the process restarts. Any index, unique or not. A table with no index is unaffected.

package/index.js

@@ -37,6 +37,8 @@ module.exports = {
   // their own — e.g. a UI wizard showing inferred columns from a CSV sample
   // before actually committing to an import).
   uploader:      uploader,
+  // The uploader's own tables (_import_errors, __xeplr_staging, __xeplr_loads), to leave out of table pickers.
+  isInternalTable: require('./lib/drivers/db/internalTables').isInternalTable,
   inferColumns:  uploader.inferColumns,
   streaming:     streaming,
   drivers:       { db: dbDrivers, file: fileDrivers },

package/lib/builtins/db/procedure.js

@@ -89,13 +89,19 @@ module.exports = {
     // Half-open, from <= x < to. The next run starts at exactly this run's
     // `to`, so a procedure treating `to` as inclusive double-counts the
     // boundary row every time.
-    { name: 'window',      type: 'object', order: 6, group: 'Incremental',
+    // `hidden`: a form leaves it out unless a job already holds one. A job's
+    // dates now reach a procedure as ordinary parameters bound to the run's
+    // window — see `params` — which needs no names typed into JSON here.
+    { name: 'window',      type: 'object', order: 6, group: 'Incremental', hidden: true,
       description: '{ from, to, fromParam, toParam } — the period this run covers, passed as the ' +
                    'named parameters fromParam/toParam. Filled automatically for a job with ' +
                    'incrementalMode "period"; name the two parameters and leave from/to empty. ' +
                    'A window without fromParam/toParam is refused rather than silently dropped.' },
 
-    { name: 'params',      type: 'array', order: 7,
+    // `control: 'parameters'`: a form shows these as rows — a name and where
+    // its value comes from (a fixed value, or the start / end of the run's
+    // window, which a job binds as "{window.from}" / "{window.to}").
+    { name: 'params',      type: 'array', order: 7, control: 'parameters', label: 'Parameters',
       description: 'Parameters, as [{ name, value }] or bare values. Named entries are matched by ' +
                    'name on postgres and mssql; MySQL has no named-argument syntax, so there they ' +
                    'are positional and must be in the order the procedure declares them.' },

package/lib/drivers/db/internalTables.js

@@ -0,0 +1,31 @@
+// THE TABLES THE UPLOADER MAKES FOR ITSELF, beside the tables it loads:
+//
+//   <table>_import_errors    rows the database refused (errorRows.js)
+//   <table>__xeplr_staging   a staged load's rows until they move in (staging.js, duckdb.js)
+//   __xeplr_loads            a DuckDB file's ledger of staged loads (duckdb.js)
+//
+// They are the uploader's bookkeeping, not data anybody models: an app that
+// lists a database's tables for people to pick from (a dataset builder, a
+// cube's source picker) leaves them out with isInternalTable(). They still
+// exist and are read where they belong (an import's dropped rows).
+
+var ERRORS_SUFFIX = '_import_errors';
+var STAGING_SUFFIX = require('./staging').SUFFIX;
+var LOADS_LEDGER = '__xeplr_loads';
+
+function endsWith(s, suffix) {
+  return s.length > suffix.length && s.slice(-suffix.length) === suffix;
+}
+
+/** Whether a table is one the uploader made for itself. Case as the database reports it. */
+function isInternalTable(name) {
+  var s = String(name == null ? '' : (typeof name === 'object' ? name.name || name.table || '' : name));
+  return endsWith(s, ERRORS_SUFFIX) || endsWith(s, STAGING_SUFFIX) || s === LOADS_LEDGER;
+}
+
+module.exports = {
+  isInternalTable: isInternalTable,
+  ERRORS_SUFFIX: ERRORS_SUFFIX,
+  STAGING_SUFFIX: STAGING_SUFFIX,
+  LOADS_LEDGER: LOADS_LEDGER
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/actions",
-  "version": "1.1.23",
+  "version": "1.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",
   "files": [