@vidyano-labs/virtual-service 0.2.0 → 0.3.0

package/README.md

@@ -396,6 +396,115 @@ service.registerPersistentObject({
 - Return nothing (or undefined) if validation passes
 - Cannot override built-in rules
 
+### Translating Validation Messages
+
+Provide custom translations for validation error messages to support multiple languages:
+
+```typescript
+import { VirtualService } from "@vidyano-labs/virtual-service";
+
+// Define your translations
+const translations: Record<string, string> = {
+    "Required": "Dit veld is verplicht",
+    "NotEmpty": "Dit veld mag niet leeg zijn",
+    "IsEmail": "E-mailformaat is ongeldig",
+    "MaxLength": "Maximale lengte is {0} tekens",
+    "MinLength": "Minimale lengte is {0} tekens",
+    "MaxValue": "Maximale waarde is {0}",
+    "MinValue": "Minimale waarde is {0}"
+};
+
+// Create service and register translation function
+const service = new VirtualService();
+service.registerMessageTranslator((key: string, ...params: any[]) => {
+    const template = translations[key] || key;
+    // Use String.format from @vidyano/core for {0}, {1} placeholders
+    return String.format(template, ...params);
+});
+
+service.registerPersistentObject({
+    type: "Person",
+    attributes: [
+        {
+            name: "Email",
+            type: "String",
+            rules: "Required; MaxLength(100); IsEmail"
+        }
+    ]
+});
+
+await service.initialize();
+
+const person = await service.getPersistentObject(null, "Person", null, true);
+await person.save();
+
+// Error message is now translated
+console.log(person.getAttribute("Email").validationError);
+// "Dit veld is verplicht"
+```
+
+**Translation function signature:**
+```typescript
+type TranslateFunction = (key: string, ...params: any[]) => string;
+```
+
+**Parameters:**
+- `key` - The validation rule name (e.g., "Required", "MaxLength")
+- `params` - Positional parameters for the message (e.g., max length value)
+
+**How it works:**
+1. Built-in validators call `translate(key, ...params)` instead of using hardcoded messages
+2. Your translate function receives the rule name and any parameters
+3. Return the translated message with parameters interpolated
+4. If no translate function is provided, default English messages are used
+
+**Custom rules can also use translation:**
+
+```typescript
+const service = new VirtualService();
+service.registerMessageTranslator((key: string, ...params: any[]) => {
+    const translations: Record<string, string> = {
+        "MinimumAge": "L'âge minimum est {0}",
+        "MatchesPassword": "Les mots de passe ne correspondent pas"
+    };
+    const template = translations[key] || key;
+    return String.format(template, ...params);
+});
+
+// Custom rule using translation
+service.registerBusinessRule("MinimumAge", (value: any, context: RuleValidationContext, minAge: number) => {
+    if (!value)
+        return;
+
+    const age = Number(value);
+    if (age < minAge)
+        throw new Error(context.translate("MinimumAge", minAge));
+});
+
+// Custom rule can still throw direct errors (backward compatible)
+service.registerBusinessRule("IsPhoneNumber", (value: any, _context: RuleValidationContext) => {
+    if (!value)
+        return;
+
+    const phoneRegex = /^\+?[\d\s-()]+$/;
+    if (!phoneRegex.test(String(value)))
+        throw new Error("Invalid phone number format");  // Not translated
+});
+```
+
+**Built-in rule keys:**
+- `Required` - Field is required (no params)
+- `NotEmpty` - Field cannot be empty (no params)
+- `IsEmail` - Invalid email format (no params)
+- `IsUrl` - Invalid URL format (no params)
+- `MaxLength` - Maximum length exceeded (param: max length)
+- `MinLength` - Minimum length not met (param: min length)
+- `MaxValue` - Maximum value exceeded (param: max value)
+- `MinValue` - Minimum value not met (param: min value)
+- `IsBase64` - Invalid base64 string (no params)
+- `IsRegex` - Invalid regex pattern (no params)
+- `IsWord` - Invalid word characters (no params)
+
 ## Queries
 
 ### Basic Query Registration
@@ -1091,6 +1200,7 @@ test("search and sort query results", async () => {
 | `registerAction(config)` | Register a custom action |
 | `registerBusinessRule(name, validator)` | Register a validation rule |
 | `registerPersistentObjectActions(type, Class)` | Register lifecycle handlers |
+| `registerMessageTranslator(translateFn)` | Register message translator for system messages |
 | `initialize()` | Finalize registrations |
 
 ### VirtualPersistentObjectActions
@@ -1131,7 +1241,9 @@ import type {
     ActionArgs,
     ActionContext,
     RuleValidatorFn,
-    RuleValidationContext
+    RuleValidationContext,
+    TranslateFunction,
+    TranslateFunction
 } from "@vidyano-labs/virtual-service";
 ```
 

package/index.d.ts

@@ -233,6 +233,17 @@ type ActionContext = {
      */
     setNotification: (message: string, type: Dto.NotificationType, duration?: number) => void;
 };
+/**
+ * Translation function for system messages
+ * @param key - The message key (e.g., "Required", "MaxLength")
+ * @param params - Positional parameters for the message
+ * @returns Translated message with parameters interpolated
+ *
+ * Example:
+ * translate("MaxLength", 50) => "Maximum length is 50 characters"
+ * translate("MinValue", 18) => "Minimum value is 18"
+ */
+type TranslateFunction = (key: string, ...params: any[]) => string;
 /**
  * Context provided to business rule validators for accessing the persistent object
  */
@@ -245,6 +256,10 @@ type RuleValidationContext = {
      * The attribute being validated (wrapped with helper methods)
      */
     attribute: VirtualPersistentObjectAttribute;
+    /**
+     * Translation function for system messages
+     */
+    translate: TranslateFunction;
 };
 /**
  * PersistentObject configuration - converted to PersistentObjectDto
@@ -460,6 +475,10 @@ declare class VirtualPersistentObjectActions {
 declare class VirtualServiceHooks extends ServiceHooks {
     #private;
     constructor();
+    /**
+     * Sets the translation function for system messages
+     */
+    setTranslate(translate: TranslateFunction): void;
     /**
      * Intercepts fetch requests and routes them to virtual handlers
      */
@@ -512,7 +531,7 @@ declare class VirtualService extends Service {
     #private;
     /**
      * Creates a new VirtualService instance.
-     * @param hooks - Optional custom VirtualServiceHooks. If not provided, a default instance is created.
+     * @param hooks - Optional custom hooks instance.
      */
     constructor(hooks?: VirtualServiceHooks);
     /**
@@ -562,7 +581,14 @@ declare class VirtualService extends Service {
      * @throws Error if called after initialize().
      */
     registerPersistentObjectActions(type: string, ActionsClass: typeof VirtualPersistentObjectActions): void;
+    /**
+     * Registers a message translator for translating system messages.
+     * Must be called before initialize().
+     * @param translate - The translation function.
+     * @throws Error if called after initialize().
+     */
+    registerMessageTranslator(translate: TranslateFunction): void;
 }
 
 export { VirtualPersistentObjectActions, VirtualService, VirtualServiceHooks };
-export type { ActionArgs, ActionConfig, ActionContext, ActionHandler, RuleValidationContext, RuleValidatorFn, VirtualPersistentObject, VirtualPersistentObjectAttribute, VirtualPersistentObjectAttributeConfig, VirtualPersistentObjectConfig, VirtualQueryConfig, VirtualQueryExecuteResult };
+export type { ActionArgs, ActionConfig, ActionContext, ActionHandler, RuleValidationContext, RuleValidatorFn, TranslateFunction, VirtualPersistentObject, VirtualPersistentObjectAttribute, VirtualPersistentObjectAttributeConfig, VirtualPersistentObjectConfig, VirtualQueryConfig, VirtualQueryExecuteResult };

package/index.js

@@ -1228,7 +1228,9 @@ class VirtualPersistentObjectActionsRegistry {
 class BusinessRuleValidator {
     #builtInRules = new Map();
     #customRules = new Map();
+    #translate;
     constructor() {
+        this.#translate = this.#defaultTranslate;
         // Register all built-in rules
         this.#builtInRules.set("IsBase64", this.#validateIsBase64.bind(this));
         this.#builtInRules.set("IsEmail", this.#validateIsEmail.bind(this));
@@ -1242,6 +1244,32 @@ class BusinessRuleValidator {
         this.#builtInRules.set("NotEmpty", this.#validateNotEmpty.bind(this));
         this.#builtInRules.set("Required", this.#validateRequired.bind(this));
     }
+    /**
+     * Sets the translation function
+     */
+    setTranslate(translate) {
+        this.#translate = translate;
+    }
+    /**
+     * Default English translations - used when no translate function provided
+     */
+    #defaultTranslate(key, ...params) {
+        const defaults = {
+            "Required": () => "This field is required",
+            "NotEmpty": () => "This field cannot be empty",
+            "IsEmail": () => "Email format is invalid",
+            "IsUrl": () => "Value must be a valid URL",
+            "MaxLength": (max) => `Maximum length is ${max} characters`,
+            "MinLength": (min) => `Minimum length is ${min} characters`,
+            "MaxValue": (max) => `Maximum value is ${max}`,
+            "MinValue": (min) => `Minimum value is ${min}`,
+            "IsBase64": () => "Value must be a valid base64 string",
+            "IsRegex": () => "Value must be a valid regular expression",
+            "IsWord": () => "Value must contain only word characters"
+        };
+        const translator = defaults[key];
+        return translator ? translator(...params) : key;
+    }
     /**
      * Register a custom business rule
      * @throws Error if attempting to override a built-in rule
@@ -1272,7 +1300,8 @@ class BusinessRuleValidator {
         // Create validation context
         const context = {
             persistentObject: wrappedPo,
-            attribute: wrappedAttr
+            attribute: wrappedAttr,
+            translate: this.#translate
         };
         // Get the converted value (e.g., boolean from "True"/"False", number from string)
         const convertedValue = this.#getConvertedValue(attr);
@@ -1345,87 +1374,87 @@ class BusinessRuleValidator {
         return fromServiceValue(attr.value, attr.type);
     }
     // Built-in validators - throw errors instead of returning strings
-    #validateIsBase64(value, context) {
+    #validateIsBase64(value, _context) {
         if (value == null || value === "")
             return;
         const base64Regex = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
         if (!base64Regex.test(String(value)))
-            throw new Error("Value must be a valid base64 string");
+            throw new Error(this.#translate("IsBase64"));
     }
-    #validateIsEmail(value, context) {
+    #validateIsEmail(value, _context) {
         if (value == null || value === "")
             return;
         // Only allow ASCII characters in email addresses
         const emailRegex = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
         if (!emailRegex.test(String(value)))
-            throw new Error("Email format is invalid");
+            throw new Error(this.#translate("IsEmail"));
     }
-    #validateIsRegex(value, context) {
+    #validateIsRegex(value, _context) {
         if (value == null || value === "")
             return;
         try {
             new RegExp(String(value));
         }
         catch {
-            throw new Error("Value must be a valid regular expression");
+            throw new Error(this.#translate("IsRegex"));
         }
     }
-    #validateIsUrl(value, context) {
+    #validateIsUrl(value, _context) {
         if (value == null || value === "")
             return;
         try {
             new URL(String(value));
         }
         catch {
-            throw new Error("Value must be a valid URL");
+            throw new Error(this.#translate("IsUrl"));
         }
     }
-    #validateIsWord(value, context) {
+    #validateIsWord(value, _context) {
         if (value == null || value === "")
             return;
         const wordRegex = /^\w+$/;
         if (!wordRegex.test(String(value)))
-            throw new Error("Value must contain only word characters");
+            throw new Error(this.#translate("IsWord"));
     }
-    #validateMaxLength(value, context, maxLength) {
+    #validateMaxLength(value, _context, maxLength) {
         if (value == null || value === "")
             return;
         const length = String(value).length;
         if (length > maxLength)
-            throw new Error(`Maximum length is ${maxLength} characters`);
+            throw new Error(this.#translate("MaxLength", maxLength));
     }
-    #validateMaxValue(value, context, maximum) {
+    #validateMaxValue(value, _context, maximum) {
         if (value == null || value === "")
             return;
         const num = Number(value);
         if (isNaN(num))
             throw new Error("Value must be a number");
         if (num > maximum)
-            throw new Error(`Maximum value is ${maximum}`);
+            throw new Error(this.#translate("MaxValue", maximum));
     }
-    #validateMinLength(value, context, minLength) {
+    #validateMinLength(value, _context, minLength) {
         if (value == null || value === "")
             return;
         const length = String(value).length;
         if (length < minLength)
-            throw new Error(`Minimum length is ${minLength} characters`);
+            throw new Error(this.#translate("MinLength", minLength));
     }
-    #validateMinValue(value, context, minimum) {
+    #validateMinValue(value, _context, minimum) {
         if (value == null || value === "")
             return;
         const num = Number(value);
         if (isNaN(num))
             throw new Error("Value must be a number");
         if (num < minimum)
-            throw new Error(`Minimum value is ${minimum}`);
+            throw new Error(this.#translate("MinValue", minimum));
     }
-    #validateRequired(value, context) {
+    #validateRequired(value, _context) {
         if (value == null)
-            throw new Error("This field is required");
+            throw new Error(this.#translate("Required"));
     }
-    #validateNotEmpty(value, context) {
+    #validateNotEmpty(value, _context) {
         if (value == null || value === "" || (typeof value === "string" && value.trim() === ""))
-            throw new Error("This field cannot be empty");
+            throw new Error(this.#translate("NotEmpty"));
     }
 }
 
@@ -1461,6 +1490,12 @@ class VirtualServiceHooks extends ServiceHooks {
         this.#actionDefinitions.set("Save", { name: "Save", displayName: "Save", isPinned: false });
         this.#actionDefinitions.set("SelectReference", { name: "SelectReference", displayName: "Select", isPinned: false });
     }
+    /**
+     * Sets the translation function for system messages
+     */
+    setTranslate(translate) {
+        this.#validator.setTranslate(translate);
+    }
     /**
      * Intercepts fetch requests and routes them to virtual handlers
      */
@@ -1969,7 +2004,7 @@ class VirtualService extends Service {
     #isInitialized = false;
     /**
      * Creates a new VirtualService instance.
-     * @param hooks - Optional custom VirtualServiceHooks. If not provided, a default instance is created.
+     * @param hooks - Optional custom hooks instance.
      */
     constructor(hooks) {
         super("http://virtual.local", hooks ?? new VirtualServiceHooks(), true);
@@ -2036,6 +2071,16 @@ class VirtualService extends Service {
         this.#ensureNotInitialized();
         this.virtualHooks.registerPersistentObjectActions(type, ActionsClass);
     }
+    /**
+     * Registers a message translator for translating system messages.
+     * Must be called before initialize().
+     * @param translate - The translation function.
+     * @throws Error if called after initialize().
+     */
+    registerMessageTranslator(translate) {
+        this.#ensureNotInitialized();
+        this.virtualHooks.setTranslate(translate);
+    }
     /**
      * Throws an error if the service has already been initialized.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vidyano-labs/virtual-service",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Virtual service implementation for testing Vidyano applications",
   "type": "module",
   "main": "index.js",
@@ -20,5 +20,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHash": "a8a427169445d844bc42c226c93da215441e6242"
+  "gitHash": "db4cd7380e2b729aedf28a81ab348823aa338c4b"
 }