ngx-signal-plus 2.4.2 → 2.5.0

package/README.md

@@ -2,11 +2,10 @@
 
 [![Angular 16-21](https://img.shields.io/badge/Angular-16--21-dd0031)](https://angular.dev/)
 [![npm version](https://img.shields.io/npm/v/ngx-signal-plus.svg)](https://www.npmjs.com/package/ngx-signal-plus)
-![Coverage](https://img.shields.io/badge/coverage-89.14%25-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-90.44%25-brightgreen)
 
 Bring validation, persistence, undo/redo, and reactive queries to Angular Signals on Angular 16+.
 
-- Interactive playground: https://stackblitz.com/github/milad-hub/ngx-signal-plus
 - Full API docs: https://github.com/milad-hub/ngx-signal-plus/blob/main/projects/signal-plus/docs/API.md
 - Repository README (contributors): https://github.com/milad-hub/ngx-signal-plus/blob/main/README.md
 
@@ -78,6 +77,11 @@ export class CounterComponent {
 - Schema validation: `spSchema`, `spSchemaValidator`
 - Middleware: `spUseMiddleware`, `spRemoveMiddleware`, `spLoggerMiddleware`, `spAnalyticsMiddleware`
 
+## Foundations Updates
+
+- `spComputed()` now exposes a read-only surface via `ReadonlySignalPlus<T>`.
+- `SignalPlus<T>` now includes `errors: Signal<string[]>` for consistent validation error access.
+
 ## Comparisons
 
 ### ngx-signal-plus vs Angular native signals
@@ -103,6 +107,7 @@ export class CounterComponent {
 - Akita is a store-centric architecture built around RxJS stores/queries.
 - ngx-signal-plus is signal-first and utility-first, designed for composable local/global signal state without store boilerplate.
 - Akita is no longer actively evolving like modern signal-first tools: the npm package is old (8.0.1, last published years ago), and the GitHub repository is archived.
+
 ## Documentation
 
 - API documentation: https://github.com/milad-hub/ngx-signal-plus/blob/main/projects/signal-plus/docs/API.md

package/fesm2022/ngx-signal-plus.mjs

@@ -461,18 +461,7 @@ class SignalBuilder {
     build() {
         // Get transform function
         const transform = this.options.transform || ((value) => value);
-        // Helper to conditionally clone only complex objects
-        const conditionalClone = (value) => {
-            const type = typeof value;
-            if (type === 'string' ||
-                type === 'number' ||
-                type === 'boolean' ||
-                value === null ||
-                value === undefined) {
-                return value;
-            }
-            return structuredClone(value);
-        };
+        const conditionalClone = (value) => this.cloneIfNeeded(value);
         // Create signal with initial value (untransformed)
         const writable = signal(structuredClone(this.options.initialValue), ...(ngDevMode ? [{ debugName: "writable" }] : []));
         let previousValue = structuredClone(this.options.initialValue);
@@ -489,31 +478,8 @@ class SignalBuilder {
         let currentValidationAbortController = null;
         const isValidatingSignal = signal(false, ...(ngDevMode ? [{ debugName: "isValidatingSignal" }] : []));
         const asyncErrorsSignal = signal([], ...(ngDevMode ? [{ debugName: "asyncErrorsSignal" }] : []));
-        /**
-         * Helper function to enforce history size limit
-         * @param histArray The history array to enforce size on
-         * @returns The history array with size limit applied
-         */
-        const enforceHistorySize = (histArray) => {
-            if (this.options.historySize &&
-                histArray.length > this.options.historySize) {
-                return histArray.slice(-this.options.historySize);
-            }
-            return histArray;
-        };
-        /**
-         * Helper function to enforce redo stack size limit
-         * @param redoArray The redo stack array to enforce size on
-         * @returns The redo stack array with size limit applied
-         */
-        const enforceRedoStackSize = (redoArray) => {
-            // Use the same size limit as history for consistency
-            if (this.options.historySize &&
-                redoArray.length > this.options.historySize) {
-                return redoArray.slice(-this.options.historySize);
-            }
-            return redoArray;
-        };
+        const enforceHistorySize = (histArray) => this.limitByHistorySize(histArray, this.options.historySize);
+        const enforceRedoStackSize = (redoArray) => this.limitByHistorySize(redoArray, this.options.historySize);
         /**
          * Helper function to run async validation with debouncing and cancellation
          * @param value The value to validate
@@ -592,42 +558,7 @@ class SignalBuilder {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         data, 
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        fallbackData) => {
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            const safeStringify = (obj) => {
-                const seen = new WeakSet();
-                return JSON.stringify(obj, (key, value) => {
-                    if (value !== null && typeof value === 'object') {
-                        if (seen.has(value)) {
-                            return '[Circular Reference]';
-                        }
-                        seen.add(value);
-                    }
-                    return value;
-                });
-            };
-            try {
-                return JSON.stringify(data);
-            }
-            catch (error) {
-                if (error instanceof TypeError && error.message.includes('circular')) {
-                    return safeStringify(data);
-                }
-                if (fallbackData !== undefined) {
-                    try {
-                        return JSON.stringify(fallbackData);
-                    }
-                    catch (fallbackError) {
-                        if (fallbackError instanceof TypeError &&
-                            fallbackError.message.includes('circular')) {
-                            return safeStringify(fallbackData);
-                        }
-                        throw fallbackError;
-                    }
-                }
-                throw error;
-            }
-        };
+        fallbackData) => this.serializeWithCircularCheck(data, fallbackData);
         // Initialize history with initial value
         if (this.options.enableHistory) {
             history.set([conditionalClone(initialValue)]);
@@ -730,6 +661,7 @@ class SignalBuilder {
                 this.handleError(error);
             });
         };
+        const getValidationErrors = (value) => this.collectValidationErrors(this.options.validators, value);
         const subscribe = (callback) => {
             const subId = nextSubId++;
             subscribers.set(subId, callback);
@@ -775,23 +707,11 @@ class SignalBuilder {
                 }
                 // Then validate the transformed value
                 if (!skipValidation) {
-                    const validators = this.options.validators;
-                    if (validators.length > 0) {
-                        // Check validators in sequence and stop on first failure
-                        for (const validator of validators) {
-                            try {
-                                const result = validator(transformedValue);
-                                if (!result) {
-                                    const error = new Error('Validation failed');
-                                    this.handleError(error);
-                                    throw error;
-                                }
-                            }
-                            catch (error) {
-                                this.handleError(error);
-                                throw error;
-                            }
-                        }
+                    const validationErrors = getValidationErrors(transformedValue);
+                    if (validationErrors.length > 0) {
+                        const error = new Error(validationErrors[0]);
+                        this.handleError(error);
+                        throw error;
                     }
                 }
                 // Check if value is distinct
@@ -990,42 +910,11 @@ class SignalBuilder {
                 }
             },
             validate: () => {
-                try {
-                    const validators = this.options
-                        .validators;
-                    return validators.every((validator) => {
-                        try {
-                            return validator(writable());
-                        }
-                        catch (error) {
-                            this.handleError(error);
-                            return false;
-                        }
-                    });
-                }
-                catch (error) {
-                    this.handleError(error);
-                    return false;
-                }
+                return getValidationErrors(writable()).length === 0;
             },
+            errors: computed(() => getValidationErrors(writable())),
             isValid: computed(() => {
-                try {
-                    const validators = this.options
-                        .validators;
-                    return validators.every((validator) => {
-                        try {
-                            return validator(writable());
-                        }
-                        catch (error) {
-                            this.handleError(error);
-                            return false;
-                        }
-                    });
-                }
-                catch (error) {
-                    this.handleError(error);
-                    return false;
-                }
+                return getValidationErrors(writable()).length === 0;
             }),
             isValidating: computed(() => isValidatingSignal()),
             asyncErrors: computed(() => asyncErrorsSignal()),
@@ -1310,6 +1199,92 @@ class SignalBuilder {
         };
         return signalInstance;
     }
+    cloneIfNeeded(value) {
+        const type = typeof value;
+        if (type === 'string' ||
+            type === 'number' ||
+            type === 'boolean' ||
+            value === null ||
+            value === undefined) {
+            return value;
+        }
+        return structuredClone(value);
+    }
+    limitByHistorySize(values, historySize) {
+        if (historySize && values.length > historySize) {
+            return values.slice(-historySize);
+        }
+        return values;
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    serializeWithCircularCheck(data, fallbackData) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const safeStringify = (obj) => {
+            const seen = new WeakSet();
+            return JSON.stringify(obj, (key, value) => {
+                if (value !== null && typeof value === 'object') {
+                    if (seen.has(value)) {
+                        return '[Circular Reference]';
+                    }
+                    seen.add(value);
+                }
+                return value;
+            });
+        };
+        try {
+            return JSON.stringify(data);
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message.includes('circular')) {
+                return safeStringify(data);
+            }
+            if (fallbackData !== undefined) {
+                try {
+                    return JSON.stringify(fallbackData);
+                }
+                catch (fallbackError) {
+                    if (fallbackError instanceof TypeError &&
+                        fallbackError.message.includes('circular')) {
+                        return safeStringify(fallbackData);
+                    }
+                    throw fallbackError;
+                }
+            }
+            throw error;
+        }
+    }
+    collectValidationErrors(validators, value) {
+        try {
+            if (!validators || validators.length === 0) {
+                return [];
+            }
+            const errors = [];
+            for (const validator of validators) {
+                try {
+                    const result = validator(value);
+                    if (result === true) {
+                        continue;
+                    }
+                    if (typeof result === 'string') {
+                        errors.push(result);
+                        continue;
+                    }
+                    errors.push('Validation failed');
+                    break;
+                }
+                catch (error) {
+                    this.handleError(error);
+                    errors.push(error instanceof Error ? error.message : 'Validation failed');
+                    break;
+                }
+            }
+            return errors;
+        }
+        catch (error) {
+            this.handleError(error);
+            return ['Validation failed'];
+        }
+    }
     /**
      * Internal method to handle errors through registered error handlers.
      * @param error The error to handle
@@ -3970,8 +3945,8 @@ function spCollection(options) {
 /**
  * Creates an enhanced computed signal that supports persistence, history, and validation.
  *
- * Unlike Angular's built-in `computed()`, `spComputed` returns a `SignalPlus`-like object
- * that allows features like persistence, history tracking, and validation for derived values.
+ * Unlike Angular's built-in `computed()`, `spComputed` returns a read-only SignalPlus shape
+ * that allows persistence, history tracking, and validation for derived values.
  *
  * @template T - The type of the computed value
  * @param fn - A function that computes the value from source signals
@@ -4001,7 +3976,6 @@ function spComputed(fn, options = {}) {
     const internalSignal = signal(initialValue, ...(ngDevMode ? [{ debugName: "internalSignal" }] : []));
     const historySignal = signal([initialValue], ...(ngDevMode ? [{ debugName: "historySignal" }] : []));
     const redoStackSignal = signal([], ...(ngDevMode ? [{ debugName: "redoStackSignal" }] : []));
-    const errorsSignal = signal([], ...(ngDevMode ? [{ debugName: "errorsSignal" }] : []));
     let previousValue = initialValue;
     const storedInitialValue = initialValue;
     if (persist && isBrowser()) {
@@ -4028,10 +4002,6 @@ function spComputed(fn, options = {}) {
                 const newHistory = [...currentHistory, newValue].slice(-historySize);
                 historySignal.set(newHistory);
                 redoStackSignal.set([]);
-                if (validate) {
-                    const isValid = validate(newValue);
-                    errorsSignal.set(isValid ? [] : ['Validation failed']);
-                }
                 if (persist && isBrowser()) {
                     safeLocalStorageSet(persist, JSON.stringify(newValue));
                 }
@@ -4066,17 +4036,18 @@ function spComputed(fn, options = {}) {
             safeLocalStorageSet(persist, JSON.stringify(valueToRedo));
         }
     };
-    const processValue = (value) => {
-        const transformedValue = applyTransform(value);
-        previousValue = internalSignal();
-        internalSignal.set(transformedValue);
-        historySignal.update((h) => [...h, transformedValue].slice(-historySize));
-        redoStackSignal.set([]);
+    const getValidationErrors = (value) => {
+        if (!validate) {
+            return [];
+        }
+        const result = validate(value);
+        if (result === true) {
+            return [];
+        }
+        return typeof result === 'string' ? [result] : ['Validation failed'];
     };
     const isValidSignal = computed(() => {
-        if (!validate)
-            return true;
-        return validate(internalSignal());
+        return getValidationErrors(internalSignal()).length === 0;
     }, ...(ngDevMode ? [{ debugName: "isValidSignal" }] : []));
     const isDirtySignal = computed(() => {
         return (JSON.stringify(internalSignal()) !== JSON.stringify(storedInitialValue));
@@ -4096,27 +4067,11 @@ function spComputed(fn, options = {}) {
         },
         signal: computed(() => internalSignal()),
         writable: internalSignal,
-        set: processValue,
-        setValue: processValue,
-        update: (updateFn) => {
-            const newValue = applyTransform(updateFn(internalSignal()));
-            previousValue = internalSignal();
-            internalSignal.set(newValue);
-            historySignal.update((h) => [...h, newValue].slice(-historySize));
-            redoStackSignal.set([]);
-        },
-        reset: () => {
-            previousValue = internalSignal();
-            internalSignal.set(storedInitialValue);
-            historySignal.set([storedInitialValue]);
-            redoStackSignal.set([]);
-        },
         validate: () => {
-            if (!validate)
-                return true;
-            return validate(internalSignal());
+            return getValidationErrors(internalSignal()).length === 0;
         },
         isValid: isValidSignal,
+        errors: computed(() => getValidationErrors(internalSignal())),
         isValidating: computed(() => false),
         asyncErrors: computed(() => []),
         isDirty: isDirtySignal,
@@ -4130,9 +4085,6 @@ function spComputed(fn, options = {}) {
             }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
             return () => effectRef.destroy();
         },
-        pipe: () => {
-            throw new Error('pipe is not supported for spComputed');
-        },
         destroy: () => {
             historySignal.set([]);
             redoStackSignal.set([]);