feat: add debounceSignal

Author: sp90

libs/ngxtension/debounce-signal/README.md

@@ -0,0 +1,3 @@
+# ngxtension/debounce-signal
+
+Secondary entry point of `ngxtension`. It can be used by importing from `ngxtension/debounce-signal`.

libs/ngxtension/debounce-signal/ng-package.json

@@ -0,0 +1,5 @@
+{
+	"lib": {
+		"entryFile": "src/index.ts"
+	}
+}

libs/ngxtension/debounce-signal/project.json

@@ -0,0 +1,20 @@
+{
+	"name": "ngxtension/debounce-signal",
+	"$schema": "../../../node_modules/nx/schemas/project-schema.json",
+	"projectType": "library",
+	"sourceRoot": "libs/ngxtension/debounce-signal/src",
+	"targets": {
+		"test": {
+			"executor": "@nx/jest:jest",
+			"outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
+			"options": {
+				"jestConfig": "libs/ngxtension/jest.config.ts",
+				"testPathPattern": ["debounce-signal"]
+			}
+		},
+		"lint": {
+			"executor": "@nx/eslint:lint",
+			"outputs": ["{options.outputFile}"]
+		}
+	}
+}

libs/ngxtension/debounce-signal/src/debounce-signal.spec.ts

@@ -0,0 +1,159 @@
+import { TestBed } from '@angular/core/testing';
+import { debounceSignal } from './debounce-signal';
+
+describe(debounceSignal.name, () => {
+	describe('data types', () => {
+		beforeEach(() => {
+			jest.useFakeTimers(); // Enable fake timers BEFORE any code using timers runs
+		});
+
+		afterEach(() => {
+			jest.useRealTimers(); // Restore real timers AFTER each test
+			jest.clearAllMocks();
+		});
+
+		it('number', () => {
+			TestBed.runInInjectionContext(() => {
+				const s = debounceSignal(1, 300);
+
+				expect(s()).toEqual(1);
+				s.set(2);
+				expect(s()).toEqual(1); // Still the initial value
+
+				// Advance the clock by the debounce time + 1ms
+				jest.advanceTimersByTime(301);
+				expect(s()).toEqual(2); // Now the debounced value
+			});
+		});
+
+		it('multiple changes number', () => {
+			TestBed.runInInjectionContext(() => {
+				const s = debounceSignal(1, 300);
+
+				expect(s()).toEqual(1);
+				s.set(2);
+				s.set(3);
+				s.set(4);
+				expect(s()).toEqual(1); // Still the initial value
+
+				// Advance the clock by the debounce time + 1ms
+				jest.advanceTimersByTime(301);
+				expect(s()).toEqual(4); // Now the debounced value
+			});
+		});
+
+		it('string', () => {
+			TestBed.runInInjectionContext(() => {
+				const s = debounceSignal('1', 300);
+
+				expect(s()).toEqual('1');
+				s.set('2');
+				expect(s()).toEqual('1');
+
+				jest.advanceTimersByTime(301);
+				expect(s()).toEqual('2');
+			});
+		});
+
+		it('multiple changes string', () => {
+			TestBed.runInInjectionContext(() => {
+				const s = debounceSignal('1', 300);
+
+				expect(s()).toEqual('1');
+				s.set('2');
+				s.set('3');
+				s.set('4');
+				expect(s()).toEqual('1');
+
+				jest.advanceTimersByTime(301);
+				expect(s()).toEqual('4');
+			});
+		});
+
+		it('should handle immediate updates followed by debounced updates', () => {
+			TestBed.runInInjectionContext(() => {
+				const s = debounceSignal(1, 300);
+				expect(s()).toBe(1);
+
+				s.set(2);
+				expect(s()).toBe(1);
+
+				jest.advanceTimersByTime(150);
+				s.set(3);
+				expect(s()).toBe(1);
+
+				jest.advanceTimersByTime(151);
+				expect(s()).toBe(1);
+
+				jest.advanceTimersByTime(150);
+				expect(s()).toBe(3);
+			});
+		});
+
+		it('object', () => {
+			TestBed.runInInjectionContext(() => {
+				const initialObject = { a: 1, b: { c: 2 } };
+				const s = debounceSignal(initialObject, 300);
+
+				expect(s()).toEqual(initialObject);
+
+				const updatedObject = { a: 2, b: { c: 3 } };
+				s.set(updatedObject);
+				expect(s()).toEqual(initialObject);
+
+				jest.advanceTimersByTime(301);
+				expect(s()).toEqual(updatedObject);
+			});
+		});
+
+		it('array', () => {
+			TestBed.runInInjectionContext(() => {
+				const initialArray = [1, 2, 3];
+				const s = debounceSignal(initialArray, 300);
+
+				expect(s()).toEqual(initialArray);
+
+				const updatedArray = [4, 5, 6];
+				s.set(updatedArray);
+				expect(s()).toEqual(initialArray);
+
+				jest.advanceTimersByTime(301);
+				expect(s()).toEqual(updatedArray);
+			});
+		});
+
+		it('nested object property', () => {
+			TestBed.runInInjectionContext(() => {
+				const initialObject = { a: 1, b: { c: 2 } };
+				const s = debounceSignal(initialObject, 300);
+
+				expect(s().b.c).toEqual(2);
+
+				s.update((val) => ({ ...val, b: { ...val.b, c: 3 } }));
+
+				expect(s().b.c).toEqual(2);
+
+				jest.advanceTimersByTime(301);
+				expect(s().b.c).toEqual(3);
+			});
+		});
+
+		it('multiple changes to nested object property', () => {
+			TestBed.runInInjectionContext(() => {
+				const initialObject = { a: 1, b: { c: 2 } };
+				const s = debounceSignal(initialObject, 300);
+
+				expect(s().b.c).toEqual(2);
+
+				s.update((val) => ({ ...val, b: { ...val.b, c: 3 } }));
+				s.update((val) => ({ ...val, b: { ...val.b, c: 4 } }));
+				s.update((val) => ({ ...val, b: { ...val.b, c: 5 } }));
+
+				expect(s().b.c).toEqual(2);
+
+				jest.advanceTimersByTime(301);
+				expect(s().b.c).toEqual(5);
+			});
+		});
+	});
+});

libs/ngxtension/debounce-signal/src/debounce-signal.ts

@@ -0,0 +1,37 @@
+import { CreateSignalOptions, WritableSignal } from '@angular/core';
+import {
+	SIGNAL,
+	SignalGetter,
+	signalSetFn,
+	signalUpdateFn,
+} from '@angular/core/primitives/signals';
+import { createSignal } from 'ngxtension/create-signal';
+
+export function debounceSignal<T>(
+	initialValue: T,
+	time: number,
+	options?: CreateSignalOptions<T>,
+): WritableSignal<T> {
+	const signalFn = createSignal(initialValue) as SignalGetter<T> &
+		WritableSignal<T>;
+	const node = signalFn[SIGNAL];
+	if (options?.equal) {
+		node.equal = options.equal;
+	}
+
+	let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+	signalFn.set = (newValue: T) => {
+		clearTimeout(timeoutId);
+
+		timeoutId = setTimeout(() => signalSetFn(node, newValue), time);
+	};
+
+	signalFn.update = (updateFn: (value: T) => T) => {
+		clearTimeout(timeoutId);
+
+		timeoutId = setTimeout(() => signalUpdateFn(node, updateFn), time);
+	};
+
+	return signalFn;
+}

libs/ngxtension/debounce-signal/src/index.ts

@@ -0,0 +1 @@
+export * from './debounce-signal';