@uwrl/qc-utils 0.0.15 → 0.0.18

package/dist/utils/plotting/operation-cores.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Pure, framework-free primitive kernels for each QC operation whose
+ * worker has a one-to-one inline equivalent. Shared by both the
+ * `?worker&inline` Vite workers and `ObservationRecord`'s non-worker
+ * fast paths so there's a single source of truth for each algorithm —
+ * if the worker's hot loop drifts from the main-thread loop we get
+ * silently wrong selections, which the calibration feature would make
+ * far easier to trigger.
+ *
+ * Keep these functions:
+ *   - allocation-frugal (no unnecessary intermediate arrays),
+ *   - free of module-level `self` / `postMessage` references (callable
+ *     in either context),
+ *   - deterministic given identical inputs (so worker output can be
+ *     diffed against inline output when debugging drift).
+ */
+/** Opcode encoding used by `valueThresholdCore` (matches the worker). */
+export declare const enum ThresholdOp {
+    LT = 0,
+    LTE = 1,
+    GT = 2,
+    GTE = 3,
+    E = 4
+}
+/**
+ * Scan `[start, end)` of `arrayY` and collect every index where the
+ * value matches ANY of the supplied comparator/threshold pairs. Short-
+ * circuits on first match per element (matches worker semantics).
+ */
+export declare function valueThresholdCore(arrayY: Float32Array | Float32Array<SharedArrayBuffer>, start: number, end: number, ops: number[], values: number[]): number[];
+/**
+ * First-difference filter: collect indexes in `[start, end)` where
+ * `Y[i] - Y[i-1]` satisfies the comparator. Comparator strings match
+ * the worker exactly (FilterOperation enum values).
+ */
+export declare function changeCore(arrayY: Float32Array | Float32Array<SharedArrayBuffer>, start: number, end: number, comparator: string, value: number): number[];
+/**
+ * Relative rate-of-change: `(Y[i] - Y[i-1]) / |Y[i-1]|`. Same
+ * comparator semantics as `changeCore`.
+ */
+export declare function rateOfChangeCore(arrayY: Float32Array | Float32Array<SharedArrayBuffer>, start: number, end: number, comparator: string, value: number): number[];
+/**
+ * Detect datetime gaps: returns a flat `[leftIdx, rightIdx, ...]`
+ * list for every pair whose datetime delta exceeds `threshold` ms.
+ * Scan covers `[start, endInclusive]`.
+ */
+export declare function findGapsCore(arrayX: Float64Array | Float64Array<SharedArrayBuffer>, start: number, endInclusive: number, threshold: number): number[];
+/**
+ * Emit maximal runs of equal Y values in `[start, end)` as flat
+ * `[startIndex, length, value, ...]` triplets. Downstream stitches
+ * adjacent chunk triplets before applying the min-run-length filter.
+ */
+export declare function persistenceCore(arrayY: Float32Array | Float32Array<SharedArrayBuffer>, start: number, end: number): number[];
+/**
+ * Copy `[start, end]` of `sourceX` / `sourceY` into `outX` / `outY`
+ * starting at `outStart`, inserting synthesized fill points after each
+ * gap whose left index falls in the read range. `gaps` is a list of
+ * `[leftIdx, rightIdx]` pairs, sorted by left index. `fillDelta` is
+ * the spacing between inserted points in the same unit as `sourceX`.
+ * When `interpolate` is true the filled Y values are linearly
+ * interpolated between the gap's endpoints; otherwise `fillValue` is
+ * written (used for "sentinel" -9999 fills).
+ *
+ * Shared by the `FillGapsWorker`'s per-segment write and the inline
+ * full-array path. Returns the number of elements written so callers
+ * can double-check contiguity against their pre-computed fill totals.
+ */
+export declare function fillGapsCore(sourceX: Float64Array | Float64Array<SharedArrayBuffer>, sourceY: Float32Array | Float32Array<SharedArrayBuffer>, gaps: ReadonlyArray<[number, number]>, outX: Float64Array | Float64Array<SharedArrayBuffer>, outY: Float32Array | Float32Array<SharedArrayBuffer>, start: number, end: number, outStart: number, fillDelta: number, interpolate: boolean, fillValue: number): number;
+/**
+ * Merge a slice `[origStart, origEnd)` of `sourceX` / `sourceY` with
+ * a pre-sorted list of `(x, y)` insertions into `outX` / `outY`
+ * starting at `outStart`. Originals win on datetime ties so the
+ * merged order matches `findLastLessOrEqual` semantics (insertion
+ * lands after equal-valued originals). Writes in order; caller is
+ * responsible for pre-allocating output buffers sized to
+ * `origEnd - origStart + insertions.length`.
+ *
+ * Shared by the `AddDataWorker`'s segment merge and the inline
+ * full-array path. Returns the number of elements written so callers
+ * can double-check contiguity.
+ */
+export declare function addDataPointsCore(sourceX: Float64Array | Float64Array<SharedArrayBuffer>, sourceY: Float32Array | Float32Array<SharedArrayBuffer>, insertions: ReadonlyArray<[number, number]>, outX: Float64Array | Float64Array<SharedArrayBuffer>, outY: Float32Array | Float32Array<SharedArrayBuffer>, origStart: number, origEnd: number, outStart: number): number;
+/**
+ * Copy `[readStart, readEnd]` of `sourceX` / `sourceY` into
+ * `outX` / `outY` starting at `outStart`, skipping any index that
+ * appears in `deleteIndices` (which must be sorted ascending and
+ * bounded to the read range). Shared by the worker's per-segment
+ * write path and the inline full-array path. Returns the number of
+ * elements written so callers can double-check contiguity.
+ */
+export declare function deleteDataPointsCore(sourceX: Float64Array | Float64Array<SharedArrayBuffer>, sourceY: Float32Array | Float32Array<SharedArrayBuffer>, deleteIndices: ArrayLike<number>, outX: Float64Array | Float64Array<SharedArrayBuffer>, outY: Float32Array | Float32Array<SharedArrayBuffer>, readStart: number, readEnd: number, outStart: number): number;
+/** Params for `shiftDatetimesCollection`; mirrors the worker payload. */
+export interface ShiftDatetimesParams {
+    amount: number;
+    isMonth: boolean;
+    isYear: boolean;
+    /** Precomputed scalar ms offset; unused when `isMonth || isYear`. */
+    deltaMs: number;
+}
+/**
+ * Compute shifted `(x, y)` pairs for each index in `indexes` without
+ * allocating a `SharedArrayBuffer`. Mirrors the shift worker's branches
+ * for month / year / scalar units. Returned in the same order as
+ * `indexes` so the caller can hand the collection straight to
+ * `_addDataPoints` after a `_deleteDataPoints(indexes)`.
+ */
+export declare function shiftDatetimesCollection(arrayX: Float64Array | Float64Array<SharedArrayBuffer>, arrayY: Float32Array | Float32Array<SharedArrayBuffer>, indexes: ArrayLike<number>, params: ShiftDatetimesParams): [number, number][];
+/** Prepared group shape shared by `_interpolate` and its worker. */
+export interface InterpolateGroup {
+    indexes: number[];
+    lowerIdx: number;
+    upperIdx: number;
+}
+/**
+ * Linear-interpolate Y-values at each group's `indexes` between the
+ * anchor points at `lowerIdx` / `upperIdx`. Writes in place. Matches
+ * the worker's degenerate-span semantics: if `lowerIdx === upperIdx`
+ * (group sits at a buffer edge with no valid anchor on one side) we
+ * paste the lone anchor value for every point in the group.
+ */
+export declare function interpolateCore(arrayX: Float64Array | Float64Array<SharedArrayBuffer>, arrayY: Float32Array | Float32Array<SharedArrayBuffer>, groups: InterpolateGroup[]): void;
+/**
+ * Apply linear drift correction over one or more `[start, end, value]`
+ * ranges in place on `arrayY`, using `arrayX` only to compute each
+ * range's time anchors. Per-point formula:
+ *
+ *     y_i += value * (x_i - startDatetime) / extent
+ *
+ * where `startDatetime = x[start]` and `extent = x[end] - x[start]`.
+ * Ranges with non-positive extent are skipped to match the worker's
+ * behaviour. The whole operation is O(total range length) — no
+ * chunking or spawning, suitable for the inline calibration path.
+ */
+export declare function driftCorrectionCore(arrayX: Float64Array | Float64Array<SharedArrayBuffer>, arrayY: Float32Array | Float32Array<SharedArrayBuffer>, ranges: [number, number, number][]): void;
+/**
+ * Apply an arithmetic operator to `arrayY` at each index in
+ * `indexes`. Operator strings match `Operator` enum values.
+ */
+export declare function changeValuesCore(arrayY: Float32Array | Float32Array<SharedArrayBuffer>, indexes: ArrayLike<number>, operator: string, value: number): void;

package/dist/utils/plotting/persistence.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/plotting/rate-of-change.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/plotting/shift-datetimes.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/utils/plotting/value-threshold.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,57 +1,62 @@
-{
-  "name": "@uwrl/qc-utils",
-  "version": "0.0.15",
-  "description": "Quality Control Utilities",
-  "homepage": "https://github.com/hydroserver2/qc-utils#readme",
-  "bugs": {
-    "url": "https://github.com/hydroserver2/qc-utils/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/hydroserver2/qc-utils.git"
-  },
-  "license": "ISC",
-  "author": "Maurier Ramirez",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "exports": {
-    ".": {
-      "require": "./dist/index.cjs",
-      "import": "./dist/index.js"
-    }
-  },
-  "types": "./dist/types.d.ts",
-  "files": [
-    "dist"
-  ],
-  "type": "module",
-  "scripts": {
-    "build": "npm run clean:dist && vite build --mode prod && vue-tsc --declaration --emitDeclarationOnly",
-    "pub": "npm publish --access public",
-    "clean:dist": "rimraf dist",
-    "clean:coverage": "rimraf coverage",
-    "preview": "vite preview",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "test": "npm run clean:coverage",
-    "up": "taze major -I",
-    "link": "npm link"
-  },
-  "dependencies": {
-    "rxjs": "^7.8.2",
-    "vite": "^7.0.4"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.14",
-    "eslint": "^9.27.0",
-    "eslint-plugin-cypress": "^5.0.0",
-    "eslint-plugin-prettier": "^5.4.1",
-    "rimraf": "^6.0.1",
-    "rollup-plugin-visualizer": "^6.0.3",
-    "stylelint": "^16.20.0",
-    "taze": "^19.1.0",
-    "typescript": "latest",
-    "vitest": "^3.2.4",
-    "vue-tsc": "^3.0.5"
-  }
+{
+  "name": "@uwrl/qc-utils",
+  "version": "0.0.18",
+  "description": "Quality Control Utilities",
+  "homepage": "https://github.com/hydroserver2/qc-utils#readme",
+  "bugs": {
+    "url": "https://github.com/hydroserver2/qc-utils/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hydroserver2/qc-utils.git"
+  },
+  "license": "ISC",
+  "author": "Maurier Ramirez",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/types.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "npm run clean:dist && vite build --mode prod && vue-tsc --declaration --emitDeclarationOnly",
+    "pub": "npm publish --access public",
+    "clean:dist": "rimraf dist",
+    "clean:coverage": "rimraf coverage",
+    "preview": "vite preview",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "up": "taze major -I",
+    "link": "npm link",
+    "dev": "vite build --watch --mode prod"
+  },
+  "dependencies": {
+    "rxjs": "^7.8.2",
+    "vite": "^8.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.0.0",
+    "eslint": "^10.0.0",
+    "eslint-plugin-cypress": "^6.0.0",
+    "eslint-plugin-prettier": "^5.4.1",
+    "happy-dom": "^20.9.0",
+    "rimraf": "^6.0.1",
+    "rollup-plugin-visualizer": "^7.0.0",
+    "stylelint": "^17.0.0",
+    "taze": "^19.1.0",
+    "typescript": "latest",
+    "typescript-eslint": "^8.58.2",
+    "vitest": "^4.0.1",
+    "vue-tsc": "^3.0.5"
+  }
 }

package/dist/types.d.ts

@@ -1,51 +0,0 @@
-export declare enum EnumEditOperations {
-    ADD_POINTS = "ADD_POINTS",
-    CHANGE_VALUES = "CHANGE_VALUES",
-    DELETE_POINTS = "DELETE_POINTS",
-    DRIFT_CORRECTION = "DRIFT_CORRECTION",
-    INTERPOLATE = "INTERPOLATE",
-    SHIFT_DATETIMES = "SHIFT_DATETIMES",
-    FILL_GAPS = "FILL_GAPS"
-}
-export declare enum EnumFilterOperations {
-    FIND_GAPS = "FIND_GAPS",
-    PERSISTENCE = "PERSISTENCE",
-    RATE_OF_CHANGE = "RATE_OF_CHANGE",
-    VALUE_THRESHOLD = "VALUE_THRESHOLD"
-}
-export type HistoryItem = {
-    method: EnumEditOperations;
-    icon: string;
-    isLoading: boolean;
-    args?: any[];
-    duration?: number;
-    status?: 'success' | 'failed';
-};
-export type EnumDictionary<T extends string | symbol | number, U> = {
-    [K in T]: U;
-};
-export declare enum FilterOperation {
-    LT = "Less than",
-    LTE = "Less than or equal to",
-    GT = "Greater than",
-    GTE = "Greater than or equal to",
-    E = "Equal",
-    START = "Start datetime",
-    END = "End datetime"
-}
-export declare const FilterOperationFn: EnumDictionary<FilterOperation, (value: number, toCompare: number) => boolean>;
-export declare enum Operator {
-    ADD = "ADD",
-    SUB = "SUB",
-    MULT = "MULT",
-    DIV = "DIV",
-    ASSIGN = "ASSIGN"
-}
-export declare enum RateOfChangeOperation {
-    LT = "Less than",
-    LTE = "Less than or equal to",
-    GT = "Greater than",
-    GTE = "Greater than or equal to",
-    E = "Equal"
-}
-export declare const RateOfChangeComparator: EnumDictionary<RateOfChangeOperation, (value: number, toCompare: number) => boolean>;

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

@@ -1,170 +0,0 @@
-import { EnumDictionary, EnumEditOperations, EnumFilterOperations, HistoryItem } from '../../types';
-export declare function subtractHours(timestamp: string, hours: number): string;
-/** Returns the index of the first value that is greater or equal to the target value */
-export declare const findFirstGreaterOrEqual: (array: number[] | Float64Array<SharedArrayBuffer>, target: number) => number;
-/** Returns the index of the last value that is lesser or equal to the target value */
-export declare const findLastLessOrEqual: (array: number[] | Float64Array<SharedArrayBuffer>, target: number) => number;
-export declare const measureEllapsedTime: (fn: () => any, message?: string) => Promise<{
-    response: any;
-    duration: number;
-}>;
-export declare enum TimeUnit {
-    SECOND = "s",
-    MINUTE = "m",
-    HOUR = "h",
-    DAY = "D",
-    WEEK = "W",
-    MONTH = "M",
-    YEAR = "Y"
-}
-export declare const timeUnitMultipliers: EnumDictionary<TimeUnit, number>;
-export declare const formatDate: (date: Date) => string;
-export declare const formatDuration: (duration: number) => string;
-export declare const shiftDatetime: (datetime: number, amount: number, unit: TimeUnit) => number;
-/**
- * This number should approximate the number of observations that a dataset could increase by during a session.
- * The lower this number, the less memory the entire app uses.
- * Note that when a dataset number of data points increases by more than `INCREASE_AMOUNT`,
- * the `_growBuffer()` method will allocate a new buffer, and the data will be copied into it.
- */
-export declare const INCREASE_AMOUNT: number;
-export declare class ObservationRecord {
-    /** The generated dataset to be used for plotting */
-    dataset: {
-        dimensions: string[];
-        source: {
-            x: Float64Array<SharedArrayBuffer>;
-            y: Float32Array<SharedArrayBuffer>;
-        };
-    };
-    history: HistoryItem[];
-    loadingTime: number | null;
-    isLoading: boolean;
-    rawData: {
-        datetimes: Float64Array<ArrayBuffer> | number[];
-        dataValues: Float32Array<ArrayBuffer> | number[];
-    };
-    constructor(dataArrays: {
-        datetimes: Float64Array<ArrayBuffer> | number[];
-        dataValues: Float32Array<ArrayBuffer> | number[];
-    });
-    loadData(dataArrays: {
-        datetimes: Float64Array<ArrayBuffer> | number[];
-        dataValues: Float32Array<ArrayBuffer> | number[];
-    }): Promise<void>;
-    get dataX(): Float64Array<SharedArrayBuffer>;
-    get dataY(): Float32Array<SharedArrayBuffer>;
-    /**
-     * Resizes the typed array
-     * @param length The total number of elements that the view will contain
-     */
-    private _resizeTo;
-    /**
-     * Buffer size is always in increments of `INCREASE_AMOUNT`.
-     * Grows the buffer by `INCREASE_AMOUNT` in bytes if the current data doesn't fit
-     * @param newLength The total number of elements that the view will contain
-     */
-    private _growBuffer;
-    /**
-     * Reloads the dataset with the raw data
-     */
-    reload(): Promise<void>;
-    /**
-     * @param index
-     * @returns
-     */
-    reloadHistory(index: number): Promise<void>;
-    /**
-     * Remove a history item
-     * @param index
-     */
-    removeHistoryItem(index: number): Promise<void>;
-    get beginTime(): Date | null;
-    get endTime(): Date | null;
-    /** Dispatch an operation and log its signature in hisotry */
-    dispatch(action: EnumEditOperations | [EnumEditOperations, ...any][], ...args: any): Promise<any[]>;
-    /** Filter operations do not transform the data and are not logged in history */
-    dispatchFilter(action: EnumFilterOperations | [EnumFilterOperations, ...any][], ...args: any): Promise<any>;
-    /**
-     * @param index An array containing the list of index of values to perform the operations on.
-     * @param operator The operator that will be applied
-     * @param value The value to use in the operation
-     * @returns The modified DataFrame
-     */
-    private _changeValues;
-    private _interpolate;
-    /** Interpolate existing values in the data source */
-    private _interpolateLinear;
-    /**
-     * Shifts the selected indexes by specified amount of units. Elements are reinserted according to their datetime.
-     * @param index The index of the elements to shift
-     * @param amount Number of {@link TimeUnit}
-     * @param unit {@link TimeUnit}
-     * @returns
-     */
-    private _shift;
-    private _fillGapsV2;
-    /**
-     * Find gaps and fill them with placeholder value
-     * @param gap Intervals to detect as gaps
-     * @param fill Interval used to fill the detected gaps
-     * @param interpolateValues If true, the new values will be linearly interpolated
-     * @returns
-     */
-    private _fillGaps;
-    /**
-     Deletes data points from a large array using worker threads.
-      1. The main thread divides the original array into equal parts to distribute work among workers.
-      2. For each segment, binary search locates the indexes to delete (deleteSegment), ensuring efficient lookups.
-      3. The cumulative deletions before each segment help compute the starting index (startTarget) for each worker's output, ensuring no overlap.
-      4. Each worker processes its segment linearly, skipping deletions and copying kept elements to their computed positions.
-      * @param deleteIndices
-     */
-    private _deleteDataPoints;
-    /**
-     *
-     * @param start The start index
-     * @param end The end index
-     * @param value The drift amount
-     */
-    private _driftCorrection;
-    /** Traverses the index array and returns groups of consecutive values.
-     * i.e.: `[0, 1, 3, 4, 6] => [[0, 1], [3, 4], [6]]`
-     * Assumes the input array is sorted.
-     * @param index: the index array (sorted)
-     */
-    private _getConsecutiveGroups;
-    /**
-     * Adds data points. Their insert index is determined using `findFirstGreaterOrEqual` in the x-axis.
-     * @param dataPoints
-     */
-    private _addDataPoints;
-    /**
-     * Filter by applying a set of logical operations
-     * @param appliedFilters
-     * @returns
-     */
-    private _valueThreshold;
-    /**
-     *
-     * @param comparator
-     * @param value
-     * @returns
-     */
-    private _rateOfChange;
-    /**
-     * Find gaps in the data
-     * @param value The time value
-     * @param unit The time unit (TimeUnit)
-     * @param range If specified, the gaps will be found only within the range
-     * @returns
-     */
-    private _findGaps;
-    /**
-     * Find points where the values are the same at least x times in a row
-     * @param times The number of times in a row that points can be equal
-     * @param range If specified, the points will be found only within the range
-     * @returns
-     */
-    private _persistence;
-}