@uwrl/qc-utils 0.0.20 → 0.0.22

package/dist/utils/plotting/script.d.ts

@@ -0,0 +1,67 @@
+/**
+ * QC History Script — save / load.
+ *
+ * See `docs/HISTORY_SCRIPT.md` for the full design rationale. The
+ * short version:
+ *
+ *   - **Save:** walk `record.history`, strip runtime-only fields
+ *     (`isLoading`, `duration`, `executionMode`, `selected`), keep
+ *     `method`, `args`, and the optional `status` flag. Wrap with
+ *     a `version`, `createdAt`, and the wall-clock `window` the
+ *     consumer was working in.
+ *
+ *   - **Load:** reset `history` + `redoStack`, `record.reload()`,
+ *     then `record.dispatch(operations.map(o => [o.method, ...o.args]))`.
+ *     Per-op failures are caught (the dispatch's own `catch` already
+ *     marks the entry `status: "failed"`); we tally them in the
+ *     returned `ApplyScriptReport` for the consumer to surface.
+ *
+ *   - **No per-method serialization rules.** Args round-trip
+ *     verbatim. Selection-coupled ops (DELETE_POINTS, INTERPOLATE,
+ *     SHIFT_DATETIMES, DRIFT_CORRECTION, CHANGE_VALUES,
+ *     ASSIGN_*_BULK) read their target indices off
+ *     `history[length - 2].selected` at runtime — replay walks the
+ *     ops in order so the SELECTION is in the right slot when the
+ *     consumer fires.
+ */
+import { ApplyScriptReport, QcScript, QcScriptWindow } from "../../types";
+import { ObservationRecord } from "./observation-record";
+/** The schema version this loader / serializer understands. */
+export declare const QC_SCRIPT_VERSION: "1";
+/**
+ * Serialize an `ObservationRecord`'s history into a `QcScript`.
+ *
+ * @param record  The record whose `.history` to serialize.
+ * @param window  Wall-clock bounds the consumer was working in. The
+ *   loader on the other end will fetch this range into the target
+ *   record before replaying.
+ */
+export declare function serializeHistory(record: ObservationRecord, window: QcScriptWindow): QcScript;
+/**
+ * Parse and validate a JSON-decoded payload as a `QcScript`. Throws
+ * on schema violations — callers should wrap in try/catch and
+ * surface the message to the user. Validation is deliberately
+ * minimal: structural shape, version, and per-op method recognition.
+ * Arg shape per method is the dispatcher's job.
+ */
+export declare function parseScript(json: unknown): QcScript;
+/**
+ * Apply a parsed `QcScript` to a freshly-prepared `ObservationRecord`.
+ *
+ * Caller's responsibility BEFORE this runs:
+ *   1. Pick the target datastream (no id matching is enforced — see
+ *      the design doc's "Stay reusable" goal).
+ *   2. Fetch the script's `window` into the record's raw data.
+ *
+ * What `applyScript` does:
+ *   1. Resets `history` + `redoStack` in-place (preserves the array
+ *      reference so the consumer's reactive ref stays bound).
+ *   2. `await record.reload()` to restore from raw.
+ *   3. Dispatches operations one at a time so per-op failures can be
+ *      caught and reported. Failures don't abort the remainder.
+ *
+ * Returns an `ApplyScriptReport` summarising the outcome. Per-op
+ * `HistoryItem.status` is also written by the dispatch path itself,
+ * so the UI can read failures directly off the history entries.
+ */
+export declare function applyScript(record: ObservationRecord, script: QcScript): Promise<ApplyScriptReport>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwrl/qc-utils",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Quality Control Utilities",
   "homepage": "https://github.com/hydroserver2/qc-utils#readme",
   "bugs": {
@@ -26,7 +26,8 @@
   ],
   "type": "module",
   "scripts": {
-    "build": "npm run clean:dist && vite build --mode prod && vue-tsc --declaration --emitDeclarationOnly",
+    "build": "vite build --mode prod && vue-tsc --declaration --emitDeclarationOnly",
+    "build:clean": "npm run clean:dist && npm run build",
     "pub": "npm publish --access public",
     "clean:dist": "rimraf dist",
     "clean:coverage": "rimraf coverage",