@ixfx/process 0.44.0 → 0.56.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-2024 Clint Heyer
+Copyright (c) 2021-2025 Clint Heyer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -88,3 +88,30 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+----
+
+Package: Kalman.js
+https://github.com/wouterbulten/kalmanjs
+
+MIT License
+
+Copyright (c) 2019 Wouter Bulten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/basic-DeFYZmGk.d.ts

@@ -0,0 +1,69 @@
+//#region src/types.d.ts
+type Process<TIn, TOut> = (value: TIn) => TOut;
+type ProcessFactory<TIn, TOut> = () => Process<TIn, TOut>;
+type Processors1<T1, T2> = [Process<T1, T2>];
+type Processors2<T1, T2, T3> = [Process<T1, T2>, Process<T2, T3>];
+type Processors3<T1, T2, T3, T4> = [Process<T1, T2>, Process<T2, T3>, Process<T3, T4>];
+type Processors4<T1, T2, T3, T4, T5> = [Process<T1, T2>, Process<T2, T3>, Process<T3, T4>, Process<T4, T5>];
+type Processors5<T1, T2, T3, T4, T5, T6> = [Process<T1, T2>, Process<T2, T3>, Process<T3, T4>, Process<T4, T5>, Process<T5, T6>];
+type Processors<T1, T2, T3, T4, T5, T6> = Processors1<T1, T2> | Processors2<T1, T2, T3> | Processors3<T1, T2, T3, T4> | Processors4<T1, T2, T3, T4, T5> | Processors5<T1, T2, T3, T4, T5, T6>;
+/**
+* A rank function that compares A and B.
+* Returns the highest value, 'a' or 'b'. 
+* Returns 'eq' if values are equal
+*/
+type RankFunction<T> = (a: T, b: T) => `a` | `b` | `eq`;
+type RankOptions = {
+  /**
+  * If set, only values with this JS type are included
+  */
+  includeType?: `string` | `number` | `object` | `boolean`;
+  /**
+  * If _true_, also emits values when they rank equal with current highest.
+  * _false_ by default
+  */
+  emitEqualRanked?: boolean;
+  /**
+  * If _true_, emits the current highest value even if it hasn't changed.
+  * This means it will match the tempo of the incoming stream.
+  */
+  emitRepeatHighest?: boolean;
+};
+//#endregion
+//#region src/basic.d.ts
+/**
+* Outputs the current largest-seen value
+* @returns 
+*/
+declare const max: () => Process<number | number[], number>;
+/**
+* Outputs the current smallest-seen value
+* @returns
+*/
+declare const min: () => Process<number | number[], number>;
+/**
+* Returns a sum of values
+* @returns 
+*/
+declare const sum: () => Process<number | number[], number>;
+/**
+* Returns the current average of input values
+* @returns 
+*/
+declare const average: () => Process<number | number[], number>;
+/**
+* Returns the tally (ie number of) values
+* @param countArrayItems 
+* @returns 
+*/
+declare const tally: (countArrayItems: boolean) => Process<any, number>;
+/**
+* Returns the 'best' value seen so far as determined by a ranking function.
+* This is similar to min/max but usable for objects.
+* @param r 
+* @param options 
+* @returns 
+*/
+declare function rank<In>(r: RankFunction<In>, options?: Partial<RankOptions>): (value: In) => In | undefined;
+//#endregion
+export { sum as a, ProcessFactory as c, Processors2 as d, Processors3 as f, RankOptions as g, RankFunction as h, rank as i, Processors as l, Processors5 as m, max as n, tally as o, Processors4 as p, min as r, Process as s, average as t, Processors1 as u };

package/dist/basic.d.ts

@@ -0,0 +1,2 @@
+import { a as sum, i as rank, n as max, o as tally, r as min, s as Process, t as average } from "./basic-DeFYZmGk.js";
+export { Process, average, max, min, rank, sum, tally };

package/dist/basic.js

@@ -0,0 +1,112 @@
+//#region src/basic.ts
+/**
+* Outputs the current largest-seen value
+* @returns 
+*/
+const max = () => {
+	let max$1 = Number.MIN_SAFE_INTEGER;
+	const compute = (value) => {
+		const valueArray = Array.isArray(value) ? value : [value];
+		for (const subValue of valueArray) {
+			if (typeof subValue !== `number`) break;
+			max$1 = Math.max(subValue, max$1);
+		}
+		return max$1;
+	};
+	return compute;
+};
+/**
+* Outputs the current smallest-seen value
+* @returns
+*/
+const min = () => {
+	let min$1 = Number.MAX_SAFE_INTEGER;
+	const compute = (value) => {
+		const valueArray = Array.isArray(value) ? value : [value];
+		for (const subValue of valueArray) {
+			if (typeof subValue !== `number`) break;
+			min$1 = Math.min(subValue, min$1);
+		}
+		return min$1;
+	};
+	return compute;
+};
+/**
+* Returns a sum of values
+* @returns 
+*/
+const sum = () => {
+	let t = 0;
+	const compute = (value) => {
+		const valueArray = Array.isArray(value) ? value : [value];
+		for (const subValue of valueArray) {
+			if (typeof subValue !== `number`) continue;
+			t += subValue;
+		}
+		return t;
+	};
+	return compute;
+};
+/**
+* Returns the current average of input values
+* @returns 
+*/
+const average = () => {
+	let total = 0;
+	let tally$1 = 0;
+	const compute = (value) => {
+		const valueArray = Array.isArray(value) ? value : [value];
+		for (const subValue of valueArray) {
+			if (typeof subValue !== `number`) continue;
+			tally$1++;
+			total += subValue;
+		}
+		return total / tally$1;
+	};
+	return compute;
+};
+/**
+* Returns the tally (ie number of) values
+* @param countArrayItems 
+* @returns 
+*/
+const tally = (countArrayItems) => {
+	let t = 0;
+	const compute = (value) => {
+		if (countArrayItems) if (Array.isArray(value)) t += value.length;
+		else t++;
+		else t++;
+		return t;
+	};
+	return compute;
+};
+/**
+* Returns the 'best' value seen so far as determined by a ranking function.
+* This is similar to min/max but usable for objects.
+* @param r 
+* @param options 
+* @returns 
+*/
+function rank(r, options = {}) {
+	const includeType = options.includeType;
+	const emitEqualRanked = options.emitEqualRanked ?? false;
+	const emitRepeatHighest = options.emitRepeatHighest ?? false;
+	let best;
+	return (value) => {
+		if (includeType && typeof value !== includeType) return;
+		if (best === void 0) {
+			best = value;
+			return best;
+		} else {
+			const result = r(value, best);
+			if (result == `a`) {
+				best = value;
+				return best;
+			} else if (result === `eq` && emitEqualRanked) return best;
+			else if (emitRepeatHighest) return best;
+		}
+	};
+}
+
+//#endregion
+export { average, max, min, rank, sum, tally };

package/dist/index.d.ts

@@ -0,0 +1,97 @@
+import { a as sum, c as ProcessFactory, d as Processors2, f as Processors3, g as RankOptions, h as RankFunction, i as rank, l as Processors, m as Processors5, n as max, o as tally, p as Processors4, r as min, s as Process, t as average, u as Processors1 } from "./basic-DeFYZmGk.js";
+
+//#region src/cancel-error.d.ts
+declare class CancelError extends Error {
+  constructor(message: any);
+}
+//#endregion
+//#region src/flow.d.ts
+declare function flow<T1, T2>(...processors: [Process<T1, T2>]): (value: T1) => T2;
+declare function flow<T1, T2, T3>(...processors: [Process<T1, T2>, Process<T2, T3>]): (value: T1) => T3;
+declare function flow<T1, T2, T3, T4>(...processors: [Process<T1, T2>, Process<T2, T3>, Process<T3, T4>]): (value: T1) => T4;
+declare function flow<T1, T2, T3, T4, T5>(...processors: [Process<T1, T2>, Process<T2, T3>, Process<T3, T4>, Process<T4, T5>]): (value: T1) => T5;
+declare function flow<T1, T2, T3, T4, T5, T6>(...processors: [Process<T1, T2>, Process<T2, T3>, Process<T3, T4>, Process<T4, T5>, Process<T5, T6>]): (value: T1) => T6;
+//#endregion
+//#region src/if-undefined.d.ts
+/**
+* Calls a function if the input value is not undefined.
+* Return value from function is passed to next function in flow.
+* 
+* ```js
+* const flow = Process.flow(
+*  Process.max(),
+*  Process.seenLastToUndefined(),
+*  Process.ifNotUndefined(v => {
+*    console.log(`v:`, v);
+*  })
+* );
+* flow(100); // Prints 'v:100'
+* flow(90);  // Nothing happens max value has not changed
+* flow(110); // Prints 'v:110'
+* ```
+* @param fn 
+* @returns 
+*/
+declare function ifNotUndefined<TIn, TOut>(fn: (value: Exclude<TIn, undefined>) => TOut): (value: TIn) => TIn | TOut;
+/**
+* Cancels the remaining flow operations if _undefined_ is an input.
+* See also {@link ifUndefined} or {@link ifNotUndefined}.
+* 
+* ```js
+* const c3 = Process.flow(
+*  Basic.max(),
+*  Process.seenLastToUndefined(),
+*  Process.cancelIfUndefined(),
+*  (v => {
+*   console.log(v);
+*  })
+* );
+* c3(100); // Prints '100'
+* c3(90);  // Doesn't print anything since max does not change
+* c3(110); // Prints '110'
+* ```
+* @returns 
+*/
+declare function cancelIfUndefined<TIn>(): (value: TIn | undefined) => TIn;
+/**
+* Returns the output of `fn` if the input value is _undefined_.
+* See also: {@link ifNotUndefined} and {@link cancelIfUndefined}.
+* @param fn 
+* @returns 
+*/
+declare function ifUndefined<TIn, TOut>(fn: () => TOut): (value: TIn) => TOut | (TIn & ({} | null));
+//#endregion
+//#region src/seen.d.ts
+/**
+* If a value is same as the previous value, _undefined_ is emitted instead.
+* 
+* @param eq Equality function. If not specified, === semantics are used.
+* @returns 
+*/
+declare function seenLastToUndefined<TIn>(eq?: (a: TIn, b: TIn) => boolean): Process<TIn, TIn | undefined>;
+/**
+* If a value is same as any previously-seen value, _undefined_ is emitted instead.
+* 
+* It stores all previous values and compares against them for each new value. 
+* This would likely be not very efficient compared to {@link seenToUndefinedByKey} which uses a one-time computed
+* key and efficient storage of only the keys (using a Set).
+*  
+* @param eq Equality function. If not specified, === semantics are used.
+* @returns 
+*/
+declare function seenToUndefined<TIn>(eq?: (a: TIn, b: TIn) => boolean): Process<TIn, TIn | undefined>;
+/**
+* If a value is the same as any previously-seen value, _undefined_ is emitted instead.
+* 
+* This version uses a function to create a string key of the object, by default JSON.stringify.
+* Thus we don't need to store all previously seen objects, just their keys.
+* 
+* Alternatively, if a key function doesn't make sense for the value, use
+* {@link seenToUndefined}, which stores the values (less efficient).
+* 
+* @param toString 
+* @returns 
+*/
+declare function seenToUndefinedByKey<TIn>(toString?: (value: TIn) => string): Process<TIn, TIn | undefined>;
+//#endregion
+export { CancelError, Process, ProcessFactory, Processors, Processors1, Processors2, Processors3, Processors4, Processors5, RankFunction, RankOptions, average, cancelIfUndefined, flow, ifNotUndefined, ifUndefined, max, min, rank, seenLastToUndefined, seenToUndefined, seenToUndefinedByKey, sum, tally };

package/dist/index.js

@@ -0,0 +1,182 @@
+import { average, max, min, rank, sum, tally } from "./basic.js";
+
+//#region src/cancel-error.ts
+var CancelError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = `CancelError`;
+	}
+};
+
+//#endregion
+//#region src/flow.ts
+/**
+* Creates a flow of data processors (up to 5 are supported).
+* The flow is encapsulated in a function that accepts an input value an returns an output.
+* 
+* ```js
+* const p = flow(
+*  (value:string) => value.toUpperCase(), // Convert to uppercase
+*  (value:string) => value.at(0) === 'A') // If first letter is an A, return true
+* );
+* p('apple'); // True
+* ```
+* 
+* Each processing function is expected to take in one input value and return one value.
+* @param processors 
+* @returns 
+*/
+function flow(...processors) {
+	return (value) => {
+		let v = value;
+		for (const p of processors) try {
+			v = p(v);
+		} catch (err) {
+			if (err instanceof CancelError) break;
+			else throw err;
+		}
+		return v;
+	};
+}
+
+//#endregion
+//#region src/if-undefined.ts
+/**
+* Calls a function if the input value is not undefined.
+* Return value from function is passed to next function in flow.
+* 
+* ```js
+* const flow = Process.flow(
+*  Process.max(),
+*  Process.seenLastToUndefined(),
+*  Process.ifNotUndefined(v => {
+*    console.log(`v:`, v);
+*  })
+* );
+* flow(100); // Prints 'v:100'
+* flow(90);  // Nothing happens max value has not changed
+* flow(110); // Prints 'v:110'
+* ```
+* @param fn 
+* @returns 
+*/
+function ifNotUndefined(fn) {
+	return (value) => {
+		if (value === void 0) return value;
+		return fn(value);
+	};
+}
+/**
+* Cancels the remaining flow operations if _undefined_ is an input.
+* See also {@link ifUndefined} or {@link ifNotUndefined}.
+* 
+* ```js
+* const c3 = Process.flow(
+*  Basic.max(),
+*  Process.seenLastToUndefined(),
+*  Process.cancelIfUndefined(),
+*  (v => {
+*   console.log(v);
+*  })
+* );
+* c3(100); // Prints '100'
+* c3(90);  // Doesn't print anything since max does not change
+* c3(110); // Prints '110'
+* ```
+* @returns 
+*/
+function cancelIfUndefined() {
+	return (value) => {
+		if (value === void 0) throw new CancelError(`cancel`);
+		return value;
+	};
+}
+/**
+* Returns the output of `fn` if the input value is _undefined_.
+* See also: {@link ifNotUndefined} and {@link cancelIfUndefined}.
+* @param fn 
+* @returns 
+*/
+function ifUndefined(fn) {
+	return (value) => {
+		if (value === void 0) return fn();
+		else return value;
+	};
+}
+
+//#endregion
+//#region src/util.ts
+/**
+* Default comparer function is equiv to checking `a === b`.
+* Use {@link isEqualValueDefault} to compare by value, via comparing JSON string representation.
+*/
+const isEqualDefault = (a, b) => a === b;
+/**
+* A default converter to string that uses JSON.stringify if its an object, or the thing itself if it's a string
+*/
+const toStringDefault = (itemToMakeStringFor) => typeof itemToMakeStringFor === `string` ? itemToMakeStringFor : JSON.stringify(itemToMakeStringFor);
+
+//#endregion
+//#region src/seen.ts
+/**
+* If a value is same as the previous value, _undefined_ is emitted instead.
+* 
+* @param eq Equality function. If not specified, === semantics are used.
+* @returns 
+*/
+function seenLastToUndefined(eq) {
+	if (typeof eq === `undefined`) eq = isEqualDefault;
+	let lastValue;
+	return (value) => {
+		if (value !== lastValue) {
+			lastValue = value;
+			return value;
+		}
+	};
+}
+/**
+* If a value is same as any previously-seen value, _undefined_ is emitted instead.
+* 
+* It stores all previous values and compares against them for each new value. 
+* This would likely be not very efficient compared to {@link seenToUndefinedByKey} which uses a one-time computed
+* key and efficient storage of only the keys (using a Set).
+*  
+* @param eq Equality function. If not specified, === semantics are used.
+* @returns 
+*/
+function seenToUndefined(eq) {
+	const seen = [];
+	if (typeof eq === `undefined`) eq = isEqualDefault;
+	return (value) => {
+		if (value === void 0) return;
+		for (const s of seen) if (eq(s, value)) return;
+		seen.push(value);
+		return value;
+	};
+}
+/**
+* If a value is the same as any previously-seen value, _undefined_ is emitted instead.
+* 
+* This version uses a function to create a string key of the object, by default JSON.stringify.
+* Thus we don't need to store all previously seen objects, just their keys.
+* 
+* Alternatively, if a key function doesn't make sense for the value, use
+* {@link seenToUndefined}, which stores the values (less efficient).
+* 
+* @param toString 
+* @returns 
+*/
+function seenToUndefinedByKey(toString) {
+	const seen = /* @__PURE__ */ new Set();
+	if (typeof toString === `undefined`) toString = toStringDefault;
+	return (value) => {
+		if (value === void 0) return;
+		const key = toString(value);
+		if (seen.has(key)) return;
+		seen.add(key);
+		return value;
+	};
+}
+
+//#endregion
+export { CancelError, average, cancelIfUndefined, flow, ifNotUndefined, ifUndefined, max, min, rank, seenLastToUndefined, seenToUndefined, seenToUndefinedByKey, sum, tally };

package/package.json

@@ -1,27 +1,47 @@
 {
   "name": "@ixfx/process",
-  "version": "0.44.0",
+  "version": "0.56.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
   "files": [
-    "dist/",
-    "bundle/"
+    "dist"
   ],
-  "dependencies": {},
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "import": "./dist/src/index.js"
-    },
-    "./basic": {
-      "types": "./dist/src/basic.d.ts",
-      "import": "./dist/src/basic.js"
+    ".": "./dist/index.js",
+    "./basic": "./dist/basic.js",
+    "./package.json": "./package.json"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/*",
+        "./*"
+      ]
     }
   },
-  "scripts": {
-    "package-bundle": "tsdown",
-    "clean": "rm -rf dist && rm -rf bundle"
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "ixfx guards",
+  "keywords": [
+    "ixfx",
+    "interactivity",
+    "guards"
+  ],
+  "homepage": "https://ixfxfun.dev",
+  "bugs": {
+    "url": "https://github.com/@ixfxfun/ixfx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/@ixfxfun/ixfx.git",
+    "directory": "packages/guards"
+  },
+  "author": "Clint Heyer <clint@thestaticvoid.net>",
+  "engines": {
+    "node": ">=20.19.0"
   },
-  "main": "dist/src/index.js"
+  "scripts": {}
 }