ngx-signal-plus 2.2.0 → 2.4.1

package/README.md

@@ -382,6 +382,32 @@ const darkMode = spPresets.toggle({
 });
 ```
 
+### Schema Validation (Zod/Yup/Joi)
+
+Use any schema validation library with signals:
+
+```typescript
+import { sp, spSchema, spSchemaValidator } from "ngx-signal-plus";
+import { z } from "zod";
+
+const userSchema = z.object({
+  name: z.string().min(1),
+  email: z.string().email(),
+  age: z.number().min(18),
+});
+
+// Basic boolean validation with SignalBuilder
+const user = sp({ name: "", email: "", age: 0 }).validate(spSchema(userSchema)).build();
+
+// Advanced: Get detailed error messages
+const validator = spSchemaValidator(userSchema);
+const result = validator.validateWithErrors({ name: "", email: "invalid", age: 10 });
+// result: { valid: false, errors: ["name: String must contain at least 1 character(s)", "email: Invalid email", "age: Number must be greater than or equal to 18"] }
+
+// Use with SignalBuilder for boolean validation
+const validatedSignal = sp({ name: "", email: "", age: 0 }).validate(validator.validate).build();
+```
+
 ### Middleware/Plugin System
 
 Intercept signal operations for logging, analytics, and error tracking:
@@ -533,7 +559,7 @@ What happens during SSR:
 | **Async State Management**  | `spAsync` - Manage asynchronous operations with loading, error, retry, and caching                                                             |
 | **Collection Management**   | `spCollection` - Manage arrays of entities with ID-based CRUD, queries, transforms, and history                                                |
 | **Transactions & Batching** | `spTransaction`, `spBatch`, `spIsTransactionActive`, `spIsInTransaction`, `spIsInBatch`, `spGetModifiedSignals`                                |
-| **Utilities**               | `spValidators`, `spPresets`                                                                                                                    |
+| **Utilities**               | `spValidators`, `spPresets`, `spSchema`, `spSchemaValidator`                                                                                   |
 | **Middleware/Plugins**      | `spUseMiddleware`, `spRemoveMiddleware`, `spLoggerMiddleware`, `spAnalyticsMiddleware`                                                         |
 | **State Management**        | `spHistoryManager`, `spStorageManager`                                                                                                         |
 | **Components**              | `spSignalPlusComponent`, `spSignalPlusService`, `spSignalBuilder`                                                                              |

package/fesm2022/ngx-signal-plus.mjs

@@ -1342,6 +1342,106 @@ class SignalBuilder {
     }
 }
 
+var SpErrorCode;
+(function (SpErrorCode) {
+    SpErrorCode["INIT_001"] = "INIT_001";
+    SpErrorCode["VAL_001"] = "VAL_001";
+    SpErrorCode["VAL_002"] = "VAL_002";
+    SpErrorCode["TRX_001"] = "TRX_001";
+    SpErrorCode["TRX_002"] = "TRX_002";
+    SpErrorCode["STOR_001"] = "STOR_001";
+    SpErrorCode["STOR_002"] = "STOR_002";
+    SpErrorCode["HIST_001"] = "HIST_001";
+    SpErrorCode["HIST_002"] = "HIST_002";
+})(SpErrorCode || (SpErrorCode = {}));
+
+const SP_ERRORS = {
+    [SpErrorCode.INIT_001]: {
+        code: SpErrorCode.INIT_001,
+        message: 'Initial value cannot be undefined',
+        suggestion: 'Provide a defined initial value when creating a signal',
+    },
+    [SpErrorCode.VAL_001]: {
+        code: SpErrorCode.VAL_001,
+        message: 'Validation failed',
+        suggestion: 'Check the value against the validator requirements',
+    },
+    [SpErrorCode.VAL_002]: {
+        code: SpErrorCode.VAL_002,
+        message: 'Invalid email format',
+        suggestion: 'Ensure the email includes "@" and a valid domain (e.g., user@example.com)',
+    },
+    [SpErrorCode.TRX_001]: {
+        code: SpErrorCode.TRX_001,
+        message: 'Nested transactions are not allowed',
+        suggestion: 'Complete the current transaction before starting a new one',
+    },
+    [SpErrorCode.TRX_002]: {
+        code: SpErrorCode.TRX_002,
+        message: 'Transaction rollback failed',
+        suggestion: 'Check that all signals in the transaction support rollback',
+    },
+    [SpErrorCode.STOR_001]: {
+        code: SpErrorCode.STOR_001,
+        message: 'Failed to save to storage',
+        suggestion: 'Check storage quota and browser permissions',
+    },
+    [SpErrorCode.STOR_002]: {
+        code: SpErrorCode.STOR_002,
+        message: 'Failed to load from storage',
+        suggestion: 'Verify the storage key exists and data is valid JSON',
+    },
+    [SpErrorCode.HIST_001]: {
+        code: SpErrorCode.HIST_001,
+        message: 'Cannot undo - no history available',
+        suggestion: 'Ensure history is enabled and changes have been made',
+    },
+    [SpErrorCode.HIST_002]: {
+        code: SpErrorCode.HIST_002,
+        message: 'Cannot redo - no future states available',
+        suggestion: 'Redo is only available after an undo operation',
+    },
+};
+class SpError extends Error {
+    code;
+    context;
+    suggestion;
+    constructor(code, context, customMessage) {
+        const errorInfo = SP_ERRORS[code];
+        const message = customMessage || errorInfo.message;
+        const formattedMessage = formatSpError(code, message, context, errorInfo.suggestion);
+        super(formattedMessage);
+        this.name = 'SpError';
+        this.code = code;
+        this.context = context;
+        this.suggestion = errorInfo.suggestion;
+    }
+}
+function formatSpError(code, message, context, suggestion) {
+    let result = `[SP-${code}] ${message}`;
+    if (context) {
+        if (context.signalName) {
+            result += `\n  Signal: '${context.signalName}'`;
+        }
+        if (context.validatorName) {
+            result += `\n  Validator: ${context.validatorName}`;
+        }
+        if (context.currentValue !== undefined) {
+            result += `\n  Current value: ${JSON.stringify(context.currentValue)}`;
+        }
+        if (context.expectedValue) {
+            result += `\n  Expected: ${context.expectedValue}`;
+        }
+    }
+    if (suggestion) {
+        result += `\n  Suggestion: ${suggestion}`;
+    }
+    return result;
+}
+function spCreateError(code, context, customMessage) {
+    return new SpError(code, context, customMessage);
+}
+
 /**
  * @fileoverview Utility functions for creating enhanced signals
  * @description
@@ -1415,7 +1515,7 @@ class SignalBuilder {
  */
 function sp(initialValue) {
     if (initialValue === undefined) {
-        throw new Error('Initial value cannot be undefined');
+        throw spCreateError(SpErrorCode.INIT_001);
     }
     return new SignalBuilder(initialValue);
 }
@@ -4423,6 +4523,88 @@ function spAnalyticsMiddleware(tracker) {
     };
 }
 
+function extractErrorMessages(error) {
+    if (!error) {
+        return [];
+    }
+    if ('issues' in error && Array.isArray(error.issues)) {
+        return error.issues.map((issue) => {
+            const path = issue.path?.join('.') || '';
+            return path ? `${path}: ${issue.message}` : issue.message;
+        });
+    }
+    if ('errors' in error && Array.isArray(error.errors)) {
+        return error.errors.map((e) => {
+            const path = e.path?.join('.') || '';
+            return path ? `${path}: ${e.message}` : e.message;
+        });
+    }
+    if (error.message) {
+        return [error.message];
+    }
+    return ['Validation failed'];
+}
+function spSchema(schema) {
+    return (value) => {
+        if ('safeParse' in schema) {
+            return schema.safeParse(value).success;
+        }
+        try {
+            schema.parse(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+}
+function spSchemaWithErrors(schema) {
+    return (value) => {
+        const result = schema.safeParse(value);
+        if (result.success) {
+            return { valid: true, errors: [] };
+        }
+        return {
+            valid: false,
+            errors: extractErrorMessages(result.error),
+        };
+    };
+}
+function spSchemaValidator(schema) {
+    const validate = (value) => {
+        if ('safeParse' in schema) {
+            return schema.safeParse(value).success;
+        }
+        try {
+            schema.parse(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    const validateWithErrors = (value) => {
+        if ('safeParse' in schema) {
+            const result = schema.safeParse(value);
+            if (result.success) {
+                return { valid: true, errors: [] };
+            }
+            return { valid: false, errors: extractErrorMessages(result.error) };
+        }
+        try {
+            schema.parse(value);
+            return { valid: true, errors: [] };
+        }
+        catch (error) {
+            if (error && typeof error === 'object') {
+                return { valid: false, errors: extractErrorMessages(error) };
+            }
+            return { valid: false, errors: ['Validation failed'] };
+        }
+    };
+    return { validate, validateWithErrors };
+}
+
 /**
  * @fileoverview Transaction and batching utilities for ngx-signal-plus
  * @description Provides functionality for atomic operations and batched updates
@@ -4672,7 +4854,7 @@ function spTransaction(fn) {
     const txState = state.transaction;
     // Prevent nested transactions
     if (txState.active) {
-        throw new Error('Nested transactions are not allowed');
+        throw spCreateError(SpErrorCode.TRX_001);
     }
     // Initialize transaction state
     const transactionStartTime = new Date();
@@ -5809,5 +5991,5 @@ function createQuery(queryKey, queryFn, options) {
  * Generated bundle index. Do not edit.
  */
 
-export { QueryClient, createMutation, createQuery, enhance, getGlobalQueryClient, setGlobalQueryClient, sp, spAnalyticsMiddleware, spAsync, spBatch, spClearMiddleware, spCollection, combineLatest as spCombineLatest, spComputed, spCounter, debounceTime as spDebounceTime, delay$1 as spDelay, distinctUntilChanged as spDistinctUntilChanged, filter as spFilter, spForm, spFormGroup, spGetMiddlewareCount, spGetModifiedSignals, HistoryManager as spHistoryManager, spIsInBatch, spIsInTransaction, spIsTransactionActive, spLoggerMiddleware, map as spMap, merge as spMerge, spMutation, presets as spPresets, spQuery, spRemoveMiddleware, SignalBuilder as spSignalBuilder, SignalPlusComponent as spSignalPlusComponent, SignalPlusService as spSignalPlusService, skip as spSkip, StorageManager as spStorageManager, take as spTake, throttleTime as spThrottleTime, spToggle, spTransaction, spUseMiddleware, validators as spValidators };
+export { QueryClient, SP_ERRORS, SpError, createMutation, createQuery, enhance, formatSpError, getGlobalQueryClient, setGlobalQueryClient, sp, spAnalyticsMiddleware, spAsync, spBatch, spClearMiddleware, spCollection, combineLatest as spCombineLatest, spComputed, spCounter, spCreateError, debounceTime as spDebounceTime, delay$1 as spDelay, distinctUntilChanged as spDistinctUntilChanged, filter as spFilter, spForm, spFormGroup, spGetMiddlewareCount, spGetModifiedSignals, HistoryManager as spHistoryManager, spIsInBatch, spIsInTransaction, spIsTransactionActive, spLoggerMiddleware, map as spMap, merge as spMerge, spMutation, presets as spPresets, spQuery, spRemoveMiddleware, spSchema, spSchemaValidator, spSchemaWithErrors, SignalBuilder as spSignalBuilder, SignalPlusComponent as spSignalPlusComponent, SignalPlusService as spSignalPlusService, skip as spSkip, StorageManager as spStorageManager, take as spTake, throttleTime as spThrottleTime, spToggle, spTransaction, spUseMiddleware, validators as spValidators };
 //# sourceMappingURL=ngx-signal-plus.mjs.map