feat(explicitEffect): addition of defer parameter; this parameter all…

docs/src/content/docs/utilities/Signals/explicit-effect.md

@@ -65,17 +65,29 @@ explicitEffect(
 
 ## Cleanup
 
-An optional second argument can be provided to `explicitEffect` that will be called when the effect is cleaned up.
+An optional second argument can be provided to the `explicitEffect` function that will be called when the effect is cleaned up.
 
 ```ts
 const count = signal(0);
-explicitEffect([this.count], ([count], cleanup) => {
+explicitEffect([count], ([count], cleanup) => {
 	console.log(`count updated ${count}`);
 	cleanup(() => console.log('cleanup'));
 });
+```
+
+## Defer
+
+In addition to the regular `effect` options, you can also pass a `defer` value as part of the third object argument of `explicitEffect`. This allows the computation not to execute immediately and only run on first deps change.
+
+```ts
+const count = signal(0);
+explicitEffect(
+	[count],
+	([count]) => {
+		console.log(`count updated ${count}`);
+	},
+	{ defer: true },
+);
 
-// count updated 0
-// count.set(1);
-// cleanup
-// count updated 1
+count.set(1); // this set will trigger the effect function call, not the initial value
 ```

libs/ngxtension/explicit-effect/src/explicit-effect.spec.ts

@@ -106,4 +106,27 @@ describe(explicitEffect.name, () => {
 			});
 		});
 	});
+
+	it('should skip the first run of the effect callback', () => {
+		const log: string[] = [];
+		const count = signal(0);
+		const state = signal('idle');
+
+		TestBed.runInInjectionContext(() => {
+			explicitEffect(
+				[count, state],
+				([count, state]) => {
+					log.push(`count updated ${count}, ${state}`);
+				},
+				{ defer: true },
+			);
+			expect(log.length).toBe(0);
+			TestBed.flushEffects();
+			expect(log.length).toBe(0);
+
+			count.set(1);
+			TestBed.flushEffects();
+			expect(log.length).toBe(1);
+		});
+	});
 });

libs/ngxtension/explicit-effect/src/explicit-effect.ts

@@ -13,6 +13,16 @@ type ExplicitEffectValues<T> = {
 	[K in keyof T]: () => T[K];
 };
 
+/**
+ * Extend the regular set of effect options
+ */
+declare interface CreateExplicitEffectOptions extends CreateEffectOptions {
+	/**
+	 * Option that allows the computation not to execute immediately, but only run on first change.
+	 */
+	defer?: boolean;
+}
+
 /**
  * This explicit effect function will take the dependencies and the function to run when the dependencies change.
  *
@@ -34,18 +44,24 @@ type ExplicitEffectValues<T> = {
  *
  * @param deps - The dependencies that the effect will run on
  * @param fn - The function to run when the dependencies change
- * @param options - The options for the effect
+ * @param options - The options for the effect with the addition of defer (it allows the computation to run on first change, not immediately)
  */
 export function explicitEffect<
 	Input extends readonly unknown[],
 	Params = Input,
 >(
 	deps: readonly [...ExplicitEffectValues<Input>],
 	fn: (deps: Params, onCleanup: EffectCleanupRegisterFn) => void,
-	options?: CreateEffectOptions | undefined,
+	options?: CreateExplicitEffectOptions | undefined,
 ): EffectRef {
+	let defer = options && options.defer;
 	return effect((onCleanup) => {
 		const depValues = deps.map((s) => s());
-		untracked(() => fn(depValues as any, onCleanup));
+		untracked(() => {
+			if (!defer) {
+				fn(depValues as any, onCleanup);
+			}
+			defer = false;
+		});
 	}, options);
 }