@monstermann/dsp 0.2.2 → 0.3.0

package/dist/Dsp/dispose.d.mts

@@ -0,0 +1,95 @@
+import { Dsp } from "./index.mjs";
+
+//#region src/Dsp/dispose.d.ts
+
+/**
+ * # Dispose
+ *
+ * ```ts
+ * function Dsp.dispose(disposer: Dsp): void;
+ * ```
+ *
+ * Takes a `Dsp` instance and disposes it, walking through all added values in reverse order (LIFO).
+ *
+ * Disposed `Dsp`s will dereference themselves from other `Dsp`s.
+ *
+ * Every added value is wrapped with a `try/catch` and errors are accumulated in an `AggregateError`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dspA = Dsp.create();
+ * Dsp.add(dspA, () => console.log(1));
+ * Dsp.add(dspA, () => console.log(2));
+ *
+ * Dsp.dispose(dspA); // Prints: 2, 1
+ * ```
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dspA = Dsp.create();
+ * const dspB = Dsp.create();
+ *
+ * Dsp.add(dspA, () => console.log(1));
+ * Dsp.add(dspA, () => console.log(2));
+ * Dsp.add(dspB, () => console.log(3));
+ * Dsp.add(dspB, () => console.log(4));
+ * Dsp.add(dspA, dspB);
+ *
+ * Dsp.dispose(dspA); // Prints: 4, 3, 2, 1
+ * ```
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dspA = Dsp.create();
+ * const dspB = Dsp.create();
+ *
+ * Dsp.add(dspA, () => console.log(1));
+ * Dsp.add(dspA, () => console.log(2));
+ * Dsp.add(dspB, () => console.log(3));
+ * Dsp.add(dspB, () => console.log(4));
+ * Dsp.add(dspA, dspB);
+ *
+ * Dsp.dispose(dspB); // Prints: 4, 3
+ * Dsp.dispose(dspA); // Prints: 2, 1
+ * ```
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dspA = Dsp.create();
+ *
+ * Dsp.add(dspA, () => console.log(1));
+ * Dsp.add(dspA, () => console.log(2));
+ * Dsp.add(dspA, () => {
+ *     throw new Error();
+ * });
+ *
+ * Dsp.dispose(dspA); // Prints: 2, 1, then rethrows above error
+ * ```
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dspA = Dsp.create();
+ *
+ * Dsp.add(dspA, () => console.log(1));
+ * Dsp.add(dspA, () => console.log(2));
+ * Dsp.add(dspA, () => {
+ *     throw new Error();
+ * });
+ * Dsp.add(dspA, () => {
+ *     throw new Error();
+ * });
+ *
+ * Dsp.dispose(dspA); // Prints: 2, 1, then throws AggregateError
+ * ```
+ *
+ */
+declare function dispose(target: Dsp): void;
+//#endregion
+export { dispose };

package/dist/Dsp/dispose.mjs

@@ -0,0 +1,131 @@
+import { symbol } from "./symbol.mjs";
+import { unlinkVal } from "./internals.mjs";
+
+//#region src/Dsp/dispose.ts
+/**
+* # Dispose
+*
+* ```ts
+* function Dsp.dispose(disposer: Dsp): void;
+* ```
+*
+* Takes a `Dsp` instance and disposes it, walking through all added values in reverse order (LIFO).
+*
+* Disposed `Dsp`s will dereference themselves from other `Dsp`s.
+*
+* Every added value is wrapped with a `try/catch` and errors are accumulated in an `AggregateError`.
+*
+* ## Example
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dspA = Dsp.create();
+* Dsp.add(dspA, () => console.log(1));
+* Dsp.add(dspA, () => console.log(2));
+*
+* Dsp.dispose(dspA); // Prints: 2, 1
+* ```
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dspA = Dsp.create();
+* const dspB = Dsp.create();
+*
+* Dsp.add(dspA, () => console.log(1));
+* Dsp.add(dspA, () => console.log(2));
+* Dsp.add(dspB, () => console.log(3));
+* Dsp.add(dspB, () => console.log(4));
+* Dsp.add(dspA, dspB);
+*
+* Dsp.dispose(dspA); // Prints: 4, 3, 2, 1
+* ```
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dspA = Dsp.create();
+* const dspB = Dsp.create();
+*
+* Dsp.add(dspA, () => console.log(1));
+* Dsp.add(dspA, () => console.log(2));
+* Dsp.add(dspB, () => console.log(3));
+* Dsp.add(dspB, () => console.log(4));
+* Dsp.add(dspA, dspB);
+*
+* Dsp.dispose(dspB); // Prints: 4, 3
+* Dsp.dispose(dspA); // Prints: 2, 1
+* ```
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dspA = Dsp.create();
+*
+* Dsp.add(dspA, () => console.log(1));
+* Dsp.add(dspA, () => console.log(2));
+* Dsp.add(dspA, () => {
+*     throw new Error();
+* });
+*
+* Dsp.dispose(dspA); // Prints: 2, 1, then rethrows above error
+* ```
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dspA = Dsp.create();
+*
+* Dsp.add(dspA, () => console.log(1));
+* Dsp.add(dspA, () => console.log(2));
+* Dsp.add(dspA, () => {
+*     throw new Error();
+* });
+* Dsp.add(dspA, () => {
+*     throw new Error();
+* });
+*
+* Dsp.dispose(dspA); // Prints: 2, 1, then throws AggregateError
+* ```
+*
+*/
+function dispose(target) {
+	let errors;
+	let stack = {
+		dsp: target,
+		prev: void 0
+	};
+	let dsp = target;
+	while (dsp) {
+		dsp[symbol] = true;
+		while (dsp.dsps) {
+			unlinkVal(dsp.dsps);
+			dsp.dsps = dsp.dsps.prevDsp;
+		}
+		while (dsp.vals) {
+			const val = dsp.vals.val;
+			dsp.vals = dsp.vals.prevVal;
+			if (symbol in val) {
+				stack = {
+					dsp: val,
+					prev: stack
+				};
+				dsp = val;
+			} else try {
+				val();
+			} catch (err) {
+				errors ??= [];
+				errors.push(err);
+			}
+		}
+		stack = stack?.prev;
+		dsp = stack?.dsp;
+	}
+	if (!errors) return;
+	if (errors.length === 1) throw errors[0];
+	throw new AggregateError(errors, "DisposeError");
+}
+
+//#endregion
+export { dispose };

package/dist/Dsp/find.d.mts

@@ -0,0 +1,44 @@
+import { Dsp, DspLink } from "./index.mjs";
+
+//#region src/Dsp/find.d.ts
+
+/**
+ * # find
+ *
+ * ```ts
+ * function Dsp.find(disposer: Dsp, value: (() => void) | Dsp): DspLink | undefined;
+ * ```
+ *
+ * `O(n)`
+ *
+ * Takes a `Dsp` instance and finds the last occurrence of `value`, the result can be passed to `unlink` to remove it.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dsp = Dsp.create();
+ *
+ * const cb1 = () => {};
+ * const cb2 = () => {};
+ *
+ * Dsp.add(dsp, cb1);
+ *
+ * Dsp.includes(dsp, cb1); // true
+ * Dsp.includes(dsp, cb2); // false
+ *
+ * const l1 = Dsp.find(dsp, cb1); // link
+ * const l2 = Dsp.find(dsp, cb2); // undefined
+ *
+ * Dsp.unlink(l1);
+ * Dsp.unlink(l2);
+ *
+ * Dsp.includes(dsp, cb1); // false
+ * Dsp.includes(dsp, cb2); // false
+ * ```
+ *
+ */
+declare function find(target: Dsp, value: (() => void) | Dsp): DspLink | undefined;
+//#endregion
+export { find };

package/dist/Dsp/find.mjs

@@ -0,0 +1,49 @@
+//#region src/Dsp/find.ts
+/**
+* # find
+*
+* ```ts
+* function Dsp.find(disposer: Dsp, value: (() => void) | Dsp): DspLink | undefined;
+* ```
+*
+* `O(n)`
+*
+* Takes a `Dsp` instance and finds the last occurrence of `value`, the result can be passed to `unlink` to remove it.
+*
+* ## Example
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dsp = Dsp.create();
+*
+* const cb1 = () => {};
+* const cb2 = () => {};
+*
+* Dsp.add(dsp, cb1);
+*
+* Dsp.includes(dsp, cb1); // true
+* Dsp.includes(dsp, cb2); // false
+*
+* const l1 = Dsp.find(dsp, cb1); // link
+* const l2 = Dsp.find(dsp, cb2); // undefined
+*
+* Dsp.unlink(l1);
+* Dsp.unlink(l2);
+*
+* Dsp.includes(dsp, cb1); // false
+* Dsp.includes(dsp, cb2); // false
+* ```
+*
+*/
+function find(target, value) {
+	let link = target.vals;
+	while (link) {
+		if (link.val === value) return link;
+		link = link.prevVal;
+	}
+	return link;
+}
+
+//#endregion
+export { find };

package/dist/Dsp/includes.d.mts

@@ -0,0 +1,36 @@
+import { Dsp } from "./index.mjs";
+
+//#region src/Dsp/includes.d.ts
+
+/**
+ * # dspIncludes
+ *
+ * ```ts
+ * function Dsp.includes(disposer: Dsp, value: (() => void) | Dsp): boolean;
+ * ```
+ *
+ * `O(n)`
+ *
+ * Returns a boolean indicating whether the provided `Dsp` instance includes `value`.
+ *
+ * By default `add` does not check for duplicates, you can use this or `find` if you need to make sure there are none.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dsp = Dsp.create();
+ * const cb = () => {};
+ *
+ * Dsp.includes(dsp, cb); // false
+ * const link = Dsp.add(dsp, cb);
+ * Dsp.includes(dsp, cb); // true
+ * Dsp.unlink(dsp, link);
+ * Dsp.includes(dsp, cb); // false
+ * ```
+ *
+ */
+declare function includes(target: Dsp, value: (() => void) | Dsp): boolean;
+//#endregion
+export { includes };

package/dist/Dsp/includes.mjs

@@ -0,0 +1,38 @@
+import { find } from "./find.mjs";
+
+//#region src/Dsp/includes.ts
+/**
+* # dspIncludes
+*
+* ```ts
+* function Dsp.includes(disposer: Dsp, value: (() => void) | Dsp): boolean;
+* ```
+*
+* `O(n)`
+*
+* Returns a boolean indicating whether the provided `Dsp` instance includes `value`.
+*
+* By default `add` does not check for duplicates, you can use this or `find` if you need to make sure there are none.
+*
+* ## Example
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dsp = Dsp.create();
+* const cb = () => {};
+*
+* Dsp.includes(dsp, cb); // false
+* const link = Dsp.add(dsp, cb);
+* Dsp.includes(dsp, cb); // true
+* Dsp.unlink(dsp, link);
+* Dsp.includes(dsp, cb); // false
+* ```
+*
+*/
+function includes(target, value) {
+	return !!find(target, value);
+}
+
+//#endregion
+export { includes };

package/dist/Dsp/{index.d.ts → index.d.mts}

@@ -1,13 +1,13 @@
-import { add } from "./add.js";
-import { create } from "./create.js";
-import { dispose } from "./dispose.js";
-import { find } from "./find.js";
-import { includes } from "./includes.js";
-import { isDisposed } from "./isDisposed.js";
-import { isDsp } from "./isDsp.js";
-import { remove } from "./remove.js";
-import { symbol } from "./symbol.js";
-import { unlink } from "./unlink.js";
+import { add } from "./add.mjs";
+import { create } from "./create.mjs";
+import { dispose } from "./dispose.mjs";
+import { find } from "./find.mjs";
+import { includes } from "./includes.mjs";
+import { isDisposed } from "./isDisposed.mjs";
+import { isDsp } from "./isDsp.mjs";
+import { remove } from "./remove.mjs";
+import { symbol } from "./symbol.mjs";
+import { unlink } from "./unlink.mjs";
 
 //#region src/Dsp/index.d.ts
 

package/dist/Dsp/index.mjs

@@ -0,0 +1,27 @@
+import { symbol } from "./symbol.mjs";
+import { dispose } from "./dispose.mjs";
+import { add } from "./add.mjs";
+import { create } from "./create.mjs";
+import { find } from "./find.mjs";
+import { includes } from "./includes.mjs";
+import { isDisposed } from "./isDisposed.mjs";
+import { isDsp } from "./isDsp.mjs";
+import { unlink } from "./unlink.mjs";
+import { remove } from "./remove.mjs";
+
+//#region src/Dsp/index.js
+const Dsp = {
+	add,
+	create,
+	dispose,
+	find,
+	includes,
+	isDisposed,
+	isDsp,
+	remove,
+	symbol,
+	unlink
+};
+
+//#endregion
+export { Dsp };

package/dist/Dsp/{internals.js → internals.mjs}

@@ -1,4 +1,4 @@
-import { symbol } from "./symbol.js";
+import { symbol } from "./symbol.mjs";
 
 //#region src/Dsp/internals.ts
 function createLink(disposer, val) {

package/dist/Dsp/isDisposed.d.mts

@@ -0,0 +1,28 @@
+import { Dsp } from "./index.mjs";
+
+//#region src/Dsp/isDisposed.d.ts
+
+/**
+ * # isDisposed
+ *
+ * ```ts
+ * function Dsp.isDisposed(disposer: Dsp): boolean;
+ * ```
+ *
+ * Returns a boolean indicating whether the provided `Dsp` instance has been disposed.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dsp = Dsp.create();
+ * Dsp.isDisposed(dsp); // false
+ * Dsp.dispose(dsp);
+ * Dsp.isDisposed(dsp); // true
+ * ```
+ *
+ */
+declare function isDisposed(target: Dsp): boolean;
+//#endregion
+export { isDisposed };

package/dist/Dsp/isDisposed.mjs

@@ -0,0 +1,30 @@
+import { symbol } from "./symbol.mjs";
+
+//#region src/Dsp/isDisposed.ts
+/**
+* # isDisposed
+*
+* ```ts
+* function Dsp.isDisposed(disposer: Dsp): boolean;
+* ```
+*
+* Returns a boolean indicating whether the provided `Dsp` instance has been disposed.
+*
+* ## Example
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dsp = Dsp.create();
+* Dsp.isDisposed(dsp); // false
+* Dsp.dispose(dsp);
+* Dsp.isDisposed(dsp); // true
+* ```
+*
+*/
+function isDisposed(target) {
+	return target[symbol];
+}
+
+//#endregion
+export { isDisposed };

package/dist/Dsp/isDsp.d.mts

@@ -0,0 +1,26 @@
+import { Dsp } from "./index.mjs";
+
+//#region src/Dsp/isDsp.d.ts
+
+/**
+ * # isDsp
+ *
+ * ```ts
+ * function Dsp.isDsp(value: unknown): value is Dsp;
+ * ```
+ *
+ * Checks whether the provided `value` is a `Dsp` instance.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dsp = Dsp.create();
+ * Dsp.isDsp(dsp); // true
+ * ```
+ *
+ */
+declare function isDsp(value: unknown): value is Dsp;
+//#endregion
+export { isDsp };

package/dist/Dsp/isDsp.mjs

@@ -0,0 +1,28 @@
+import { symbol } from "./symbol.mjs";
+
+//#region src/Dsp/isDsp.ts
+/**
+* # isDsp
+*
+* ```ts
+* function Dsp.isDsp(value: unknown): value is Dsp;
+* ```
+*
+* Checks whether the provided `value` is a `Dsp` instance.
+*
+* ## Example
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dsp = Dsp.create();
+* Dsp.isDsp(dsp); // true
+* ```
+*
+*/
+function isDsp(value) {
+	return value != null && typeof value === "object" && symbol in value;
+}
+
+//#endregion
+export { isDsp };

package/dist/Dsp/remove.d.mts

@@ -0,0 +1,34 @@
+import { Dsp } from "./index.mjs";
+
+//#region src/Dsp/remove.d.ts
+
+/**
+ * # remove
+ *
+ * ```ts
+ * function Dsp.remove(disposer: Dsp, value: (() => void) | Dsp): void;
+ * ```
+ *
+ * `O(n)`
+ *
+ * Takes a `Dsp` instance and removes the last occurrence of `value` from it.
+ *
+ * If you can, use `unlink` as it is `O(1)`.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const dsp = Dsp.create();
+ * const cb = () => {};
+ * const link = Dsp.add(dsp, cb);
+ * Dsp.includes(dsp, cb); // true
+ * Dsp.remove(dsp, cb);
+ * Dsp.includes(dsp, cb); // false
+ * ```
+ *
+ */
+declare function remove(disposer: Dsp, value: (() => void) | Dsp): void;
+//#endregion
+export { remove };

package/dist/Dsp/remove.mjs

@@ -0,0 +1,38 @@
+import { find } from "./find.mjs";
+import { unlink } from "./unlink.mjs";
+
+//#region src/Dsp/remove.ts
+/**
+* # remove
+*
+* ```ts
+* function Dsp.remove(disposer: Dsp, value: (() => void) | Dsp): void;
+* ```
+*
+* `O(n)`
+*
+* Takes a `Dsp` instance and removes the last occurrence of `value` from it.
+*
+* If you can, use `unlink` as it is `O(1)`.
+*
+* ## Example
+*
+* ```ts
+* import { Dsp } from "@monstermann/dsp";
+*
+* const dsp = Dsp.create();
+* const cb = () => {};
+* const link = Dsp.add(dsp, cb);
+* Dsp.includes(dsp, cb); // true
+* Dsp.remove(dsp, cb);
+* Dsp.includes(dsp, cb); // false
+* ```
+*
+*/
+function remove(disposer, value) {
+	const link = find(disposer, value);
+	if (link) unlink(link);
+}
+
+//#endregion
+export { remove };

package/dist/Dsp/unlink.d.mts

@@ -0,0 +1,34 @@
+import { DspLink } from "./index.mjs";
+
+//#region src/Dsp/unlink.d.ts
+
+/**
+ * # unlink
+ *
+ * ```ts
+ * function Dsp.unlink(link: DspLink | undefined): void;
+ * ```
+ *
+ * `O(1)`
+ *
+ * Takes a value constructed by `add` and destroys all references.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Dsp } from "@monstermann/dsp";
+ *
+ * const cb = () => {};
+ *
+ * const dsp = Dsp.create();
+ * const link = Dsp.add(dsp, cb);
+ *
+ * Dsp.includes(dsp, cb); // true
+ * Dsp.unlink(link);
+ * Dsp.includes(dsp, cb); // false
+ * ```
+ *
+ */
+declare function unlink(link: DspLink | undefined): void;
+//#endregion
+export { unlink };