[EVOL]: add lazy evaluation utils

Author: helabenkhalfallah

benchmark-fp.ts

@@ -2,8 +2,11 @@ import { performance } from 'perf_hooks';
 
 import {
     CanApply,
+    LazyCall,
+    LazyStream,
     Ok,
     Option,
+    PageLazyStream,
     SyncEffect,
     compose,
     composeTransducers,
@@ -266,3 +269,60 @@ benchmarks.push(
 
 //  **Display Benchmark Results**
 console.table(benchmarks);
+
+// ** Benchmark for Lazy Evaluation **
+async function runBenchmarks() {
+    const benchmarks: BenchmarkResult[] = [];
+
+    // ** Benchmark LazyCall **
+    const lazyComputation = new LazyCall(() => {
+        for (let i = 0; i < 1e7; i++) {
+            // Do nothing
+        } // Simulated heavy computation
+        return 42;
+    });
+
+    benchmarks.push(benchmark(() => lazyComputation.get(), 'LazyCall', 'First Evaluation'));
+
+    benchmarks.push(benchmark(() => lazyComputation.get(), 'LazyCall', 'Cached Evaluation'));
+
+    // ** Benchmark LazyStream **
+    async function* asyncNumbers(start = 1) {
+        let num = start;
+        while (num <= 10000) {
+            yield num++;
+        }
+    }
+
+    const stream = LazyStream.from(() => asyncNumbers())
+        .map((x) => x * 2)
+        .filter((x) => x % 3 === 0)
+        .take(1000);
+
+    benchmarks.push(
+        await benchmark(() => stream.toArray(), 'LazyStream', 'Lazy Mapping + Filtering + Taking'),
+    );
+
+    // ** Benchmark PageLazyStream (Paginated API simulation) **
+    async function* paginatedNumbers() {
+        for (let i = 1; i <= 100; i++) {
+            await new Promise((resolve) => setTimeout(resolve, 10)); // Simulate API delay
+            yield Array.from({ length: 10 }, (_, j) => i * 10 + j);
+        }
+    }
+
+    const pageStream = PageLazyStream.from(() => paginatedNumbers())
+        .map((page) => page.map((x) => x * 2))
+        .filter((page) => page.some((x) => x % 5 === 0))
+        .take(5);
+
+    benchmarks.push(
+        await benchmark(() => pageStream.toArray(), 'PageLazyStream', 'Lazy Paginated Processing'),
+    );
+
+    // ** Display Benchmark Results **
+    console.table(benchmarks);
+}
+
+// Run benchmarks
+runBenchmarks();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsa-toolbox",
-  "version": "2.0.4",
+  "version": "2.1.0",
   "description": "A powerful toolkit for data structures and algorithms in TypeScript, designed for optimal performance and versatility. The toolkit provides implementations of various data structures and algorithms, with a focus on search and sort operations, caching, and probabilistic data structures.",
   "type": "module",
   "main": "dist/index.js",

src/functional/index.ts

@@ -12,3 +12,4 @@ export {
     takeTransducer,
 } from './transducers/Transducers.ts';
 export * from './monads/index.ts';
+export * from './lazy/index.ts';

src/functional/lazy/LazyCall-test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { LazyCall } from './LazyCall.ts';
+
+describe('LazyCall', () => {
+    it('should evaluate the computation only once', () => {
+        const spy = vi.fn(() => 42);
+        const lazy = new LazyCall(spy);
+
+        expect(spy).not.toHaveBeenCalled();
+
+        const result1 = lazy.get();
+        const result2 = lazy.get();
+
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(result1).toBe(42);
+        expect(result2).toBe(42);
+    });
+
+    it('should apply transformations using map lazily', () => {
+        const spy = vi.fn(() => 10);
+        const lazy = new LazyCall(spy);
+        const mapped = lazy.map((x) => x * 2);
+
+        expect(spy).not.toHaveBeenCalled(); // The computation should not run yet
+
+        const result = mapped.get();
+
+        expect(spy).toHaveBeenCalledTimes(1); // The original computation should run once
+        expect(result).toBe(20);
+    });
+
+    it('should apply flatMap and preserve laziness', () => {
+        const spy = vi.fn(() => 5);
+        const lazy = new LazyCall(spy);
+        const flatMapped = lazy.flatMap((x) => new LazyCall(() => x * 3));
+
+        expect(spy).not.toHaveBeenCalled(); // Should not compute yet
+
+        const result = flatMapped.get();
+
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(result).toBe(15);
+    });
+
+    it('should work with multiple transformations and only compute once', () => {
+        const spy = vi.fn(() => 3);
+        const lazy = new LazyCall(spy).map((x) => x + 2).map((x) => x * 10);
+
+        expect(spy).not.toHaveBeenCalled(); // No evaluation yet
+
+        const result = lazy.get();
+
+        expect(spy).toHaveBeenCalledTimes(1);
+        expect(result).toBe(50);
+    });
+
+    it('should allow chaining of flatMap with dependent computations', () => {
+        const lazy = new LazyCall(() => 5)
+            .flatMap((x) => new LazyCall(() => x * 2))
+            .flatMap((x) => new LazyCall(() => x + 3));
+
+        const result = lazy.get();
+
+        expect(result).toBe(13); // (5 * 2) + 3
+    });
+
+    it('should correctly handle side effects only once', () => {
+        let count = 0;
+        const lazy = new LazyCall(() => {
+            count++;
+            return count;
+        });
+
+        expect(count).toBe(0);
+
+        const first = lazy.get();
+        const second = lazy.get();
+
+        expect(first).toBe(1);
+        expect(second).toBe(1);
+        expect(count).toBe(1);
+    });
+});

src/functional/lazy/LazyCall.ts

@@ -0,0 +1,53 @@
+/**
+ * LazyCall Evaluation Wrapper.
+ *
+ * Allows delayed computation with functional transformations.
+ *
+ * @template T - The type of the computed value.
+ */
+export class LazyCall<T> {
+    private computed: T | undefined;
+    private isEvaluated = false;
+
+    /**
+     * Constructs a new LazyCall instance with a computation.
+     *
+     * @param {() => T} computation - The function to compute the value lazily.
+     */
+    constructor(private readonly computation: () => T) {}
+
+    /**
+     * Computes the value **only once** and caches the result.
+     *
+     * @returns {T} The computed value.
+     */
+    get(): T {
+        if (!this.isEvaluated) {
+            this.computed = this.computation(); // Compute and store the result
+            this.isEvaluated = true; // Mark as evaluated to prevent re-execution
+        }
+        return this.computed!;
+    }
+
+    /**
+     * Transforms the stored value **without evaluating** it immediately.
+     *
+     * @template U - The new transformed type.
+     * @param {(value: T) => U} fn - The transformation function.
+     * @returns {LazyCall<U>} A new lazy instance with the transformation applied.
+     */
+    map<U>(fn: (value: T) => U): LazyCall<U> {
+        return new LazyCall(() => fn(this.get()));
+    }
+
+    /**
+     * Chains computations that return another LazyCall instance.
+     *
+     * @template U - The transformed type.
+     * @param {(value: T) => LazyCall<U>} fn - The function returning a new LazyCall instance.
+     * @returns {LazyCall<U>} A new lazy instance.
+     */
+    flatMap<U>(fn: (value: T) => LazyCall<U>): LazyCall<U> {
+        return new LazyCall(() => fn(this.get()).get());
+    }
+}

src/functional/lazy/LazyCallProperty-test.ts

@@ -0,0 +1,116 @@
+import fc from 'fast-check';
+import { describe, expect, it, vi } from 'vitest';
+
+import { LazyCall } from './LazyCall.ts';
+
+describe('LazyCall - Property-Based Testing', () => {
+    it('should always return the same value for the same computation', () => {
+        fc.assert(
+            fc.property(fc.integer(), (num) => {
+                const lazy = new LazyCall(() => num);
+
+                expect(lazy.get()).toBe(num);
+                expect(lazy.get()).toBe(num); // Ensure memoization
+            }),
+        );
+    });
+
+    it('should only evaluate once regardless of how many times get() is called', () => {
+        fc.assert(
+            fc.property(fc.integer(), (num) => {
+                const spy = vi.fn(() => num);
+                const lazy = new LazyCall(spy);
+
+                lazy.get();
+                lazy.get();
+                lazy.get();
+
+                expect(spy).toHaveBeenCalledTimes(1);
+            }),
+        );
+    });
+
+    it('should correctly apply map transformations', () => {
+        fc.assert(
+            fc.property(fc.integer(), fc.func(fc.integer()), (num, transformFn) => {
+                const lazy = new LazyCall(() => num).map(transformFn);
+
+                expect(lazy.get()).toBe(transformFn(num));
+            }),
+        );
+    });
+
+    it('should correctly apply flatMap transformations', () => {
+        fc.assert(
+            fc.property(fc.integer(), fc.func(fc.integer()), (num, transformFn) => {
+                const lazy = new LazyCall(() => num).flatMap(
+                    (x) => new LazyCall(() => transformFn(x)),
+                );
+
+                expect(lazy.get()).toBe(transformFn(num));
+            }),
+        );
+    });
+
+    it('should preserve memoization after mapping', () => {
+        fc.assert(
+            fc.property(fc.integer(), fc.func(fc.integer()), (num, transformFn) => {
+                const spy = vi.fn(() => num);
+                const lazy = new LazyCall(spy).map(transformFn);
+
+                const result1 = lazy.get();
+                const result2 = lazy.get();
+
+                expect(spy).toHaveBeenCalledTimes(1);
+                expect(result1).toBe(result2);
+            }),
+        );
+    });
+
+    it('should preserve memoization after flatMapping', () => {
+        fc.assert(
+            fc.property(fc.integer(), fc.func(fc.integer()), (num, transformFn) => {
+                const spy = vi.fn(() => num);
+                const lazy = new LazyCall(spy).flatMap((x) => new LazyCall(() => transformFn(x)));
+
+                const result1 = lazy.get();
+                const result2 = lazy.get();
+
+                expect(spy).toHaveBeenCalledTimes(1);
+                expect(result1).toBe(result2);
+            }),
+        );
+    });
+
+    it('should chain multiple maps correctly', () => {
+        fc.assert(
+            fc.property(
+                fc.integer(),
+                fc.func(fc.integer()),
+                fc.func(fc.integer()),
+                (num, fn1, fn2) => {
+                    const lazy = new LazyCall(() => num).map(fn1).map(fn2);
+
+                    expect(lazy.get()).toBe(fn2(fn1(num)));
+                },
+            ),
+        );
+    });
+
+    it('should chain multiple flatMaps correctly', () => {
+        fc.assert(
+            fc.property(
+                fc.integer(),
+                fc.func(fc.integer()),
+                fc.func(fc.integer()),
+                (num, fn1, fn2) => {
+                    const lazy = new LazyCall(() => num)
+                        .flatMap((x) => new LazyCall(() => fn1(x)))
+                        .flatMap((x) => new LazyCall(() => fn2(x)));
+
+                    expect(lazy.get()).toBe(fn2(fn1(num)));
+                },
+            ),
+        );
+    });
+});