@cognite/signal-utils 1.0.0

package/README.md

@@ -0,0 +1,204 @@
+# Signals
+
+> [!WARNING]
+> This package is developed and published for Cognite's internal use. It is made publicly available on npm as a
+> side effect of our internal tooling, but no support, stability, or continued availability is guaranteed for
+> external users. Cognite makes no warranty regarding this package and accepts no liability for any security
+> vulnerabilities, defects, or issues arising from its use, by internal or external consumers.
+
+This is a library for dealing with signals. A signal contains a value, and you can be notified of changes to the value. Signal is not a new concept and has been in the frontend space for some time. There is even [a proposal](https://github.com/tc39/proposal-signals) to make signals part of the language. Several frontend frameworks use signals in some shape or form. This library is a thin wrapper on top of [Preact Signals](https://github.com/preactjs/signals). We want to control the signals interface, and we hope that we can change the underlying implementation in the future with a native solution.
+
+## API
+
+### `signal(value?)`
+
+```ts
+import { signal } from '@cognite/signal-utils';
+
+// Create a signal with an initial value
+const mySignal = signal(42); // Will have the type Signal<number>
+console.log(mySignal()); // 42
+mySignal(43);
+console.log(mySignal()); // 43
+
+// Create a signal without an initial value
+const mySignal = signal<string>(); // Will have the type Signal<string | undefined>
+console.log(mySignal()); // undefined
+mySignal('hello');
+console.log(mySignal()); // 'hello'
+```
+
+#### `signal.peek()`
+
+```ts
+import { signal } from '@cognite/signal-utils';
+
+// Peek the value without creating a dependency
+const mySignal = signal(42);
+mySignal.peek(); // 42
+```
+
+### `computed(fn)`
+
+```ts
+import { signal, computed } from '@cognite/signal-utils';
+
+const myNumber = signal(42);
+const double = computed(() => myNumber() * 2);
+double() // 84
+myNumber(43);
+double() // 86
+```
+
+### `effect(fn)`
+
+```ts
+import { signal, effect } from '@cognite/signal-utils';
+
+const mySignal = signal(42);
+effect(() => {
+ console.log(mySignal());
+});
+// 42 is logged
+mySignal(43);
+// 43 is logged
+
+// Cleanup
+effect(() => {
+  addEventListener('click', handler);
+  return () => { removeEventListener('click', handler); };
+});
+```
+
+
+### `batch(fn)`
+
+```ts
+import { signal, computed, batch, effect } from '@cognite/signal-utils';
+
+const givenName = signal('Jane');
+const familyName = signal('Doe');
+const fullName = computed(() => givenName() + ' ' + familyName());
+
+effect(() => console.log(fullName()));
+// "Jane Doe" logged
+
+// Combines both signal writes into one atomic update.
+batch(() => {
+  givenName('Foo');
+  familyName('Bar');
+});
+// "Foo Bar" logged
+```
+
+### `untracked(fn)`
+
+```ts
+import { signal, effect, untracked } from '@cognite/signal-utils';
+
+const signalA = signal('A');
+const signalB = signal('B');
+
+function someFunction() {
+  console.log(signalB());
+}
+
+effect(() => {
+  console.log(signalA());
+  untracked(someFunction);
+})
+// A & B is logged
+
+signalA('A2');
+// A2 & B is logged
+
+signalB('B2');
+// Nothing is logged as we didn't take a dependency on signalB
+```
+
+### `arraySignal(value=[])`
+
+```ts
+import { arraySignal } from '@cognite/signal-utils';
+
+const myArraySignal = arraySignal([1, 2, 3]);
+
+// Getter
+const currentArray = myArraySignal();
+
+// Setter
+myArraySignal([4, 5, 6]);
+
+// Push new values
+myArraySignal.push(7, 8);
+
+// Insert value at specific index
+myArraySignal.insertAt(1, 9);
+
+// Remove specific value
+myArraySignal.remove(2);
+
+// Remove value at specific index
+myArraySignal.removeAt(0);
+
+// Swap values at two indices
+myArraySignal.swap(0, 1);
+
+// Clear the array
+myArraySignal.clear();
+
+// Peek the current value without taking a dependency
+const peekedArray = myArraySignal.peek();
+```
+
+### `debouncedComputed(fn, [delayInMs], [immediate=false])`
+
+```ts
+import { signal, debouncedComputed } from '@cognite/signal-utils';
+
+const mySignal = signal(42);
+
+// `double` is a read-only signal (computed) which updates at a maximum frequency of once every 250 ms.
+const double = debouncedComputed(() => mySignal() * 2, 250);
+
+double(); // 84
+
+mySignal(12);
+double(); // 84
+
+await sleep(250);
+double(); // 24
+```
+
+### `fragmentSignal(key, defaultValue?, serialize?, deserialize?)`
+
+```ts
+import { fragmentSignal } from '@cognite/signal-utils/extensions';
+
+// Create a signal that syncs with the URL hash fragment
+const pageSignal = fragmentSignal('page', 1);
+
+// Read the current value (from URL if present, otherwise default)
+pageSignal(); // 1
+
+// Update the value (also updates URL to #page=2)
+pageSignal(2);
+
+// Clean up when done
+pageSignal.dispose();
+```
+
+## API (React)
+
+### `useSignalValue(signal)`
+
+```ts
+import { signal } from '@cognite/signal-utils';
+import { useSignalValue } from '@cognite/signal-utils/react';
+
+const mySignal = signal(42);
+
+// React hook to read the signal value and keep it up-to-date.
+// This works for any ReadonlySignal, including signal, computed, arraySignal.
+const value = useSignalValue(mySignal); // 42
+```

package/dist/core/array-signal.d.ts

@@ -0,0 +1,61 @@
+import { ReadonlySignal, Signal } from './signal';
+declare const arraySignalSymbol: unique symbol;
+export type ReadonlyArraySignal<T> = ReadonlySignal<readonly T[]>;
+export type ArraySignal<T> = Signal<readonly T[]> & {
+    push(...values: T[]): void;
+    insertAt(index: number, value: T): void;
+    remove(value: T): void;
+    removeAt(index: number): void;
+    swap(i: number, j: number): void;
+    clear(): void;
+    [arraySignalSymbol]: boolean;
+};
+/**
+ * Creates an `ArraySignal` which is a reactive signal for an array of values.
+ *
+ * @template T - The type of elements in the array.
+ * @param {readonly T[]} [value=[]] - The initial value of the array.
+ * @returns {ArraySignal<T>} A reactive signal for the array.
+ *
+ * @example
+ * ```ts
+ * const myArraySignal = arraySignal([1, 2, 3]);
+ *
+ * // Getter
+ * const currentArray = myArraySignal();
+ *
+ * // Setter
+ * myArraySignal([4, 5, 6]);
+ *
+ * // Push new values
+ * myArraySignal.push(7, 8);
+ *
+ * // Insert value at specific index
+ * myArraySignal.insertAt(1, 9);
+ *
+ * // Remove specific value
+ * myArraySignal.remove(2);
+ *
+ * // Remove value at specific index
+ * myArraySignal.removeAt(0);
+ *
+ * // Swap values at two indices
+ * myArraySignal.swap(0, 1);
+ *
+ * // Clear the array
+ * myArraySignal.clear();
+ *
+ * // Peek the current value without taking a dependency
+ * const peekedArray = myArraySignal.peek();
+ * ```
+ */
+export declare function arraySignal<T>(value?: readonly T[]): ArraySignal<T>;
+/**
+ * Checks if the given value is an ArraySignal.
+ *
+ * @template T - The type of elements in the array signal.
+ * @param value - The value to check.
+ * @returns A boolean indicating whether the value is an ArraySignal.
+ */
+export declare function isArraySignal<T>(value: unknown): value is ArraySignal<T>;
+export {};

package/dist/core/array-signal.js

@@ -0,0 +1,36 @@
+import { insertAt as e, remove as t, removeAt as n, swap as r } from "../utils/arrays.js";
+import { signal as i } from "./signal.js";
+//#region libs/shared/signal-utils/src/core/array-signal.ts
+var a = Symbol("ArraySignal");
+function o(o = []) {
+	let s = i([...o]);
+	function c(e) {
+		if (arguments.length === 1) {
+			s([...e]);
+			return;
+		}
+		return s();
+	}
+	return c[a] = !0, c.push = (...e) => {
+		s([...s.peek(), ...e]);
+	}, c.insertAt = (t, n) => {
+		let r = [...s.peek()];
+		e(r, t, n), s(r);
+	}, c.remove = (e) => {
+		let n = [...s.peek()];
+		t(n, e), s(n);
+	}, c.removeAt = (e) => {
+		let t = [...s.peek()];
+		n(t, e), s(t);
+	}, c.swap = (e, t) => {
+		let n = [...s.peek()];
+		r(n, e, t), s(n);
+	}, c.clear = () => {
+		s([]);
+	}, c.peek = () => s.peek(), c.subscribe = (e) => s.subscribe(e), c;
+}
+function s(e) {
+	return typeof e == "function" && a in e;
+}
+//#endregion
+export { o as arraySignal, s as isArraySignal };

package/dist/core/batch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Executes a function within a batch, ensuring that signal updates are batched together (atomic operation).
+ *
+ * @param fn - The function to be executed within the batch.
+ *
+ * @example
+ * ```ts
+ * const givenName = signal('Jane');
+ * const familyName = signal('Doe');
+ * const fullName = computed(() => givenName() + ' ' + familyName());
+ *
+ * effect(() => console.log(fullName()));
+ * // "Jane Doe" logged
+ *
+ * // Combines both signal writes into one atomic update.
+ * batch(() => {
+ *   givenName('Foo');
+ *   familyName('Bar');
+ * });
+ * // "Foo Bar" logged
+ * ```
+ */
+export declare function batch(fn: VoidFunction): void;

package/dist/core/batch.js

@@ -0,0 +1,7 @@
+import { batch as e } from "@preact/signals-core";
+//#region libs/shared/signal-utils/src/core/batch.ts
+function t(t) {
+	e(t);
+}
+//#endregion
+export { t as batch };

package/dist/core/computed.d.ts

@@ -0,0 +1,19 @@
+import { ReadonlySignal } from './signal';
+/**
+ * Creates a computed signal that derives its value from the provided function.
+ *
+ * @template T - The type of the value returned by the computed function.
+ * @param {() => T} fn - A function that returns the value for the computed signal.
+ * @returns {ReadonlySignal<T>} A readonly signal that provides the computed value.
+ *
+ * @example
+ * ```ts
+ * const myNumber = signal(42);
+ * const double = computed(() => myNumber() * 2);
+ * double() // 84
+ *
+ * myNumber(43);
+ * double() // 86
+ * ```
+ */
+export declare function computed<T>(fn: () => T): ReadonlySignal<T>;

package/dist/core/computed.js

@@ -0,0 +1,11 @@
+import { computed as e } from "@preact/signals-core";
+//#region libs/shared/signal-utils/src/core/computed.ts
+function t(t) {
+	let n = e(t);
+	function r() {
+		return n.value;
+	}
+	return r.peek = () => n.peek(), r.subscribe = (e) => n.subscribe(e), r;
+}
+//#endregion
+export { t as computed };

package/dist/core/effect.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Calls the provided function, first initially, and when a signal dependency changes.
+ *
+ * The provided function can optionally return a cleanup function that will run only once.
+ * It will run when the effect is disposed or right before the next invocation of provided function.
+ *
+ * @param fn
+ * @returns A method to dispose the effect.
+ *
+ * @example
+ * ```ts
+ * const mySignal = signal(42);
+ * effect(() => {
+ *  console.log(mySignal());
+ * });
+ * // 42 is logged
+ *
+ * mySignal(43);
+ * // 43 is logged
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Cleanup
+ * effect(() => {
+ *   addEventListener('click', handler);
+ *   return () => { removeEventListener('click', handler); };
+ * });
+ * ```
+ */
+export declare function effect(fn: EffectFn): Dispose;
+type Dispose = VoidFunction;
+type EffectFn = () => void | Dispose;
+export {};

package/dist/core/effect.js

@@ -0,0 +1,7 @@
+import { effect as e } from "@preact/signals-core";
+//#region libs/shared/signal-utils/src/core/effect.ts
+function t(t) {
+	return e(t);
+}
+//#endregion
+export { t as effect };

package/dist/core/signal.d.ts

@@ -0,0 +1,88 @@
+declare const signalSymbol: unique symbol;
+/**
+ * Represents a readonly signal that can be used to get the current value.
+ *
+ * @template T - The type of the signal value.
+ */
+export type ReadonlySignal<T> = {
+    (): T;
+    /**
+     * Let you peek the signal value without taking dependency on the signal.
+     * Peeking is useful in scenarios where you want to read the value, but not update on value changes.
+     *
+     * @returns The current signal value.
+     */
+    peek(): T;
+    /**
+     * Subscribes to value changes. The provided function will be called once initially with the current value.
+     * @param fn The provided function will be invoked with a single argument, the newest signal value.
+     * @returns A function to unsubscribe.
+     */
+    subscribe: (fn: Subscriber<T>) => Unsubscribe;
+};
+export type Subscriber<T> = (value: T) => void;
+export type Unsubscribe = VoidFunction;
+/**
+ * Represents a signal that can be used to get and set the current value.
+ *
+ * @template T - The type of the signal value.
+ */
+export type Signal<T> = ReadonlySignal<T> & {
+    (value: T): void;
+    [signalSymbol]?: boolean;
+};
+/**
+ * Creates a new signal with an optional initial value.
+ *
+ * A signal is a reactive primitive that holds a value and can be used to track changes to that value.
+ * The signal can be read by calling it as a function, and it can be updated by calling it with a new value.
+ * The `peek` method can be used to read the current value without taking dependency on it.
+ *
+ * @template T - The type of the signal value.
+ * @param {T} [value] - The initial value of the signal.
+ * @returns {Signal<T | undefined> | Signal<T>} - The created signal.
+ *
+ * @example
+ * ```ts
+ * // Create a signal with an initial value
+ * const mySignal = signal(42); // Will have the type Signal<number>
+ * console.log(mySignal()); // 42
+ * mySignal(43);
+ * console.log(mySignal()); // 43
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Create a signal without an initial value
+ * const mySignal = signal<string>(); // Will have the type Signal<string | undefined>
+ * console.log(mySignal()); // undefined
+ * mySignal('hello');
+ * console.log(mySignal()); // 'hello'
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Peek the value without creating a dependency
+ * const mySignal = signal(42);
+ * mySignal.peek(); // 42
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Subscribe to value changes
+ * const mySignal = signal(42);
+ * mySignal.subscribe(console.log); // Logs 42
+ * mySignal(43); // Logs 43
+ * ```
+ */
+export declare function signal<T>(): Signal<T | undefined>;
+export declare function signal<T>(value: T): Signal<T>;
+/**
+ * Checks if the given value is a Signal.
+ *
+ * @template T - The value type of the signal.
+ * @param value - The value to check.
+ * @returns A boolean indicating whether the value is a Signal.
+ */
+export declare function isSignal<T>(value: unknown): value is Signal<T>;
+export {};

package/dist/core/signal.js

@@ -0,0 +1,19 @@
+import { signal as e } from "@preact/signals-core";
+//#region libs/shared/signal-utils/src/core/signal.ts
+var t = Symbol("signal");
+function n(n) {
+	let r = e(n);
+	function i(e) {
+		if (arguments.length === 1) {
+			r.value = e;
+			return;
+		}
+		return r.value;
+	}
+	return i[t] = !0, i.peek = () => r.peek(), i.subscribe = (e) => r.subscribe(e), i;
+}
+function r(e) {
+	return typeof e == "function" && t in e;
+}
+//#endregion
+export { r as isSignal, n as signal };

package/dist/core/untracked.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Calls the provided function, without taking dependency on any signals called within it.
+ * @param fn
+ * @returns The value returned from `fn`.
+ *
+ * @example
+ * ```ts
+ * const signalA = signal('A');
+ * const signalB = signal('B');
+ *
+ * function someFunction() {
+ *   console.log(signalB());
+ * }
+ *
+ * effect(() => {
+ *   console.log(signalA());
+ *   untracked(someFunction);
+ * })
+ * // A & B is logged
+ *
+ * signalA('A2');
+ * // A2 & B is logged
+ *
+ * signalB('B2');
+ * // Nothing is logged as we didn't take a dependency on signalB
+ * ```
+ */
+export declare function untracked<T>(fn: () => T): T;

package/dist/core/untracked.js

@@ -0,0 +1,7 @@
+import { untracked as e } from "@preact/signals-core";
+//#region libs/shared/signal-utils/src/core/untracked.ts
+function t(t) {
+	return e(t);
+}
+//#endregion
+export { t as untracked };

package/dist/extensions/fragmentSignal.d.ts

@@ -0,0 +1,89 @@
+import { Signal } from '../core/signal';
+export type FragmentSignal<T> = Signal<T> & {
+    dispose: () => void;
+};
+/**
+ * Creates a signal that synchronizes its value with the URL hash fragment.
+ *
+ * This function creates a reactive signal that automatically reads from and writes to
+ * the URL hash fragment (the part after `#`). When the signal value changes, the URL
+ * hash is updated. When the URL hash changes (e.g., via browser navigation), the
+ * signal value is updated accordingly.
+ *
+ * @template T - The type of the value stored in the signal
+ *
+ * @param key - The parameter name to use in the URL hash fragment
+ * @param defaultValue - The default value to use when the URL parameter is not present
+ * @param serialize - Optional function to serialize the value to a string. Defaults to `JSON.stringify`
+ * @param deserialize - Optional function to deserialize a string to a value. Defaults to `JSON.parse`
+ *
+ * @returns A signal that synchronizes with the URL hash fragment, including a `dispose()` method to clean up event listeners
+ *
+ * @example
+ * ```ts
+ * // Basic usage with a default value
+ * const pageSignal = fragmentSignal('page', 1);
+ *
+ * // Read the current value
+ * console.log(pageSignal()); // 1 (or value from URL if present)
+ *
+ * // Update the value (also updates URL to #page=2)
+ * pageSignal(2);
+ *
+ * // Clear the value (removes from URL and resets to default)
+ * pageSignal(null);
+ *
+ * // Clean up when done
+ * pageSignal.dispose();
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Usage without default value (signal will be undefined if not in URL)
+ * const optionalSignal = fragmentSignal<string>('filter');
+ *
+ * console.log(optionalSignal()); // undefined (if not in URL)
+ * optionalSignal('active'); // Sets URL to #filter=active
+ * optionalSignal(undefined); // Removes from URL
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom serialization for complex objects
+ * interface Filter {
+ *   category: string;
+ *   priceRange: [number, number];
+ * }
+ *
+ * const filterSignal = fragmentSignal<Filter>(
+ *   'filter',
+ *   { category: 'all', priceRange: [0, 100] },
+ *   (filter) => btoa(JSON.stringify(filter)), // Base64 encode
+ *   (str) => JSON.parse(atob(str)) // Base64 decode
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multiple fragment signals can coexist
+ * const searchSignal = fragmentSignal('q', '');
+ * const sortSignal = fragmentSignal('sort', 'name');
+ *
+ * searchSignal('react');
+ * sortSignal('date');
+ * // URL becomes: #q=react&sort=date
+ * ```
+ *
+ * @remarks
+ * - The signal automatically listens to `hashchange` events and updates accordingly
+ * - Setting the signal to `null` or `undefined` resets the parameter to the default value.
+ *   If it is initialized without a default value, then it will remove the hash key from the URL.
+ * - The URL hash uses `URLSearchParams` format for encoding multiple parameters
+ * - The signal persists across page reloads as long as the URL hash remains
+ * - Call `dispose()` on the returned signal to remove the `hashchange` event listener when no longer needed
+ * - Two overloads are available:
+ *   1. With default value: `fragmentSignal(key, defaultValue, serialize?, deserialize?)` - returns `Signal<T>`
+ *   2. Without default value: `fragmentSignal(key, serialize?, deserialize?)` - returns `Signal<T | undefined>`
+ */
+export declare function fragmentSignal<T extends NonNullable<unknown>>(key: string, defaultValue: T, serialize?: (value: T) => string, deserialize?: (hashString: string) => T): FragmentSignal<T>;
+export declare function fragmentSignal<T>(key: string, serialize?: (value: T) => string, deserialize?: (hashString: string) => T): FragmentSignal<T | undefined | null>;

package/dist/extensions/fragmentSignal.js

@@ -0,0 +1,21 @@
+import { signal as e } from "../core/signal.js";
+//#region libs/shared/signal-utils/src/extensions/fragmentSignal.ts
+function t(t, n, r = JSON.stringify, i = JSON.parse) {
+	let a = u().get(t), o = a === null ? n : i(a), s = e(o), c = new AbortController();
+	window.addEventListener("hashchange", () => {
+		let e = u().get(t), r = e === null ? n : i(e);
+		s(r);
+	}, { signal: c.signal });
+	let l = new Proxy(s, { apply: function(e, n, i) {
+		if (i.length === 0) return Reflect.apply(e, n, i);
+		let a = u(), o = i[0];
+		return o == null ? a.delete(t) : a.set(t, r(o)), window.location.hash = a.toString(), o;
+	} });
+	return Object.assign(l, { dispose: () => c.abort() });
+	function u() {
+		let e = window.location.hash.substring(1);
+		return new URLSearchParams(e);
+	}
+}
+//#endregion
+export { t as fragmentSignal };

package/dist/extensions.d.ts

@@ -0,0 +1 @@
+export { fragmentSignal, type FragmentSignal, } from './extensions/fragmentSignal';

package/dist/extensions.js

@@ -0,0 +1,2 @@
+import { fragmentSignal as e } from "./extensions/fragmentSignal.js";
+export { e as fragmentSignal };

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { arraySignal, isArraySignal } from './core/array-signal';
+export { batch } from './core/batch';
+export { computed } from './core/computed';
+export { debouncedComputed } from './misc/debounced-computed';
+export { effect } from './core/effect';
+export { signal, isSignal } from './core/signal';
+export { untracked } from './core/untracked';
+export type { ArraySignal, ReadonlyArraySignal } from './core/array-signal';
+export type { DebouncedComputed } from './misc/debounced-computed';
+export type { Signal, ReadonlySignal } from './core/signal';

package/dist/index.js

@@ -0,0 +1,8 @@
+import { isSignal as e, signal as t } from "./core/signal.js";
+import { arraySignal as n, isArraySignal as r } from "./core/array-signal.js";
+import { batch as i } from "./core/batch.js";
+import { computed as a } from "./core/computed.js";
+import { effect as o } from "./core/effect.js";
+import { debouncedComputed as s } from "./misc/debounced-computed.js";
+import { untracked as c } from "./core/untracked.js";
+export { n as arraySignal, i as batch, a as computed, s as debouncedComputed, o as effect, r as isArraySignal, e as isSignal, t as signal, c as untracked };

package/dist/misc/debounced-computed.d.ts

@@ -0,0 +1,25 @@
+import { ReadonlySignal } from '../core/signal';
+/**
+ * Represents a debounced computed value.
+ *
+ * @template T - The type of the computed value.
+ *
+ * @property {ReadonlySignal<T>} value - The debounced computed value.
+ * @property {VoidFunction} dispose - A function to dispose updates to the computed value.
+ */
+export type DebouncedComputed<T> = {
+    value: ReadonlySignal<T>;
+    dispose: VoidFunction;
+};
+/**
+ * Creates a debounced computed value based on the provided function.
+ * The value will be set immediately, and debounce thereafter. This means the computed value will be updated at a maximum
+ * frequency of once every `delayInMs` milliseconds.
+ *
+ * @template T - The type of the computed value.
+ * @param {() => T} func - The function that returns the computed value.
+ * @param {number} [delayInMs] - The minimum amount of time that must pass between between each value update. If not provided, a default delay will be used.
+ * @param {boolean} [immediate=false] - If true, the function will be called at the start of the wait period, rather than the end.
+ * @returns {DebouncedComputed<T>} An object containing the debounced computed value and a dispose function.
+ */
+export declare function debouncedComputed<T>(func: () => T, delayInMs?: number, immediate?: boolean): DebouncedComputed<T>;

package/dist/misc/debounced-computed.js

@@ -0,0 +1,17 @@
+import { signal as e } from "../core/signal.js";
+import { computed as t } from "../core/computed.js";
+import { effect as n } from "../core/effect.js";
+import { debounce as r } from "../utils/debounce.js";
+//#region libs/shared/signal-utils/src/misc/debounced-computed.ts
+function i(i, a, o = !1) {
+	let s = !1, c = e(void 0), l = r(c, a, o), u = t(i), d = n(() => {
+		let e = u();
+		s ? l(e) : (c(e), s = !0);
+	});
+	return {
+		value: t(() => c()),
+		dispose: d
+	};
+}
+//#endregion
+export { i as debouncedComputed };

package/dist/react/use-signal-value.d.ts

@@ -0,0 +1,9 @@
+import { ReadonlySignal } from '../core/signal';
+/**
+ * A custom hook that returns the signal's value and keeps the value up-to-date.
+ *
+ * @template T - The type of the value held by the signal.
+ * @param {ReadonlySignal<T>} signal - The signal.
+ * @returns {T} - The current value of the signal.
+ */
+export declare function useSignalValue<T>(signal: ReadonlySignal<T>): T;

package/dist/react/use-signal-value.js

@@ -0,0 +1,7 @@
+import { useSyncExternalStore as e } from "react";
+//#region libs/shared/signal-utils/src/react/use-signal-value.ts
+function t(t) {
+	return e(t.subscribe, t.peek);
+}
+//#endregion
+export { t as useSignalValue };

package/dist/react.d.ts

@@ -0,0 +1 @@
+export { useSignalValue } from './react/use-signal-value';

package/dist/react.js

@@ -0,0 +1,2 @@
+import { useSignalValue as e } from "./react/use-signal-value.js";
+export { e as useSignalValue };

package/dist/utils/arrays.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Inserts an element at a specific index in the array.
+ *
+ * @param array
+ * @param index
+ * @param item
+ */
+export declare function insertAt<T>(array: T[], index: number, item: T): void;
+/**
+ * Removes an element from the array.
+ *
+ * @param array
+ * @param item
+ */
+export declare function remove<T>(array: T[], item: T): void;
+/**
+ * Removes an element at the index from the array.
+ *
+ * @param array
+ * @param item
+ */
+export declare function removeAt(array: unknown[], index: number): void;
+/**
+ * Swaps two elements in the array on index `i` and `j`.
+ *
+ * @param array
+ * @param i
+ * @param j
+ */
+export declare function swap(array: unknown[], i: number, j: number): void;

package/dist/utils/arrays.js

@@ -0,0 +1,17 @@
+//#region libs/shared/signal-utils/src/utils/arrays.ts
+function e(e, t, n) {
+	e.splice(t, 0, n);
+}
+function t(e, t) {
+	let r = e.indexOf(t);
+	r !== -1 && n(e, r);
+}
+function n(e, t) {
+	e.splice(t, 1);
+}
+function r(e, t, n) {
+	if (t < 0 || n < 0 || t >= e.length || n >= e.length) throw Error("Index out of bounds");
+	[e[t], e[n]] = [e[n], e[t]];
+}
+//#endregion
+export { e as insertAt, t as remove, n as removeAt, r as swap };

package/dist/utils/debounce.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Wraps a function in a debounce function that will only execute
+ * the provided function at a maximum frequency of once every `delayInMs` milliseconds.
+ *
+ * @param callback The function to debounce.
+ * @param delayInMs The minimum amount of time that must pass between calls to the function.
+ * @param immediate If true, the function will be called at the start of the wait period, rather than the end.
+ * @returns
+ */
+export declare function debounce<T extends (...args: any[]) => void>(callback: T, delayInMs?: number, immediate?: boolean): <U>(this: U, ...args: Parameters<typeof callback>) => void;

package/dist/utils/debounce.js

@@ -0,0 +1,12 @@
+//#region libs/shared/signal-utils/src/utils/debounce.ts
+function e(e, t = 250, n = !1) {
+	let r = null;
+	return function(...i) {
+		let a = () => {
+			r = null, n || e.apply(this, i);
+		}, o = n && r === null;
+		r !== null && clearTimeout(r), r = setTimeout(a, t), o && e.apply(this, i);
+	};
+}
+//#endregion
+export { e as debounce };

package/dist/utils/repeat.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Repeats the execution of a given function a specified number of times.
+ *
+ * @param fn - The function to be executed repeatedly. It should not take any arguments and should not return any value.
+ * @param times - The number of times to execute the function.
+ */
+export declare function repeat(fn: VoidFunction, times: number): void;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@cognite/signal-utils",
+  "version": "1.0.0",
+  "description": "A thin, framework-agnostic wrapper around Preact Signals for reactive state management.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json",
+    "./react": {
+      "import": "./dist/react.js",
+      "types": "./dist/react.d.ts"
+    },
+    "./extensions": {
+      "import": "./dist/extensions.js",
+      "types": "./dist/extensions.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@preact/signals-core": "^1.8.0"
+  },
+  "devDependencies": {
+    "@nx/eslint-plugin": "22.7.8",
+    "@testing-library/react": "16.0.1",
+    "@types/react": "18.3.14",
+    "@vitejs/plugin-react": "^5.2.0",
+    "react": "^18.3.1",
+    "vite": "8.2.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  }
+}