@vidyano-labs/virtual-service 0.1.1 → 0.3.0

package/README.md

@@ -336,8 +336,10 @@ console.log(contact.getAttribute("Email").validationError);
 Register your own validation rules for domain-specific requirements:
 
 ```typescript
+import type { RuleValidationContext } from "@vidyano-labs/virtual-service";
+
 // Register a custom rule (before registerPersistentObject)
-service.registerBusinessRule("IsPhoneNumber", (value: any) => {
+service.registerBusinessRule("IsPhoneNumber", (value: any, context: RuleValidationContext) => {
     if (value == null || value === "") return;
     const phoneRegex = /^\+?[\d\s-()]+$/;
     if (!phoneRegex.test(String(value)))
@@ -357,12 +359,152 @@ service.registerPersistentObject({
 });
 ```
 
+**Validation context:**
+The `RuleValidationContext` parameter provides access to:
+- `context.persistentObject` - The persistent object being validated (wrapped with helper methods)
+- `context.attribute` - The attribute being validated (wrapped with helper methods)
+
+This allows cross-field validation:
+
+```typescript
+// Validate password confirmation matches password
+service.registerBusinessRule("MatchesPassword", (value: any, context: RuleValidationContext) => {
+    if (!value) return;
+
+    const passwordValue = context.persistentObject.getAttributeValue("Password");
+    if (value !== passwordValue)
+        throw new Error("Passwords do not match");
+});
+
+service.registerPersistentObject({
+    type: "User",
+    attributes: [
+        { name: "Password", type: "String" },
+        {
+            name: "ConfirmPassword",
+            type: "String",
+            rules: "MatchesPassword"
+        }
+    ]
+});
+```
+
 **Custom rule requirements:**
 - Must be registered before `registerPersistentObject()`
+- Receives two parameters: `value` (the attribute value) and `context` (validation context)
 - Throw an `Error` with a message if validation fails
 - 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
@@ -1058,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
@@ -1097,7 +1240,10 @@ import type {
     ActionHandler,
     ActionArgs,
     ActionContext,
-    RuleValidatorFn
+    RuleValidatorFn,
+    RuleValidationContext,
+    TranslateFunction,
+    TranslateFunction
 } from "@vidyano-labs/virtual-service";
 ```
 

package/index.d.ts

@@ -77,10 +77,6 @@ type VirtualPersistentObjectAttributeConfig = {
      * Initial value for the attribute.
      */
     value?: any;
-    /**
-     * Indicates whether this attribute is required. Defaults to false.
-     */
-    isRequired?: boolean;
     /**
      * Indicates whether the value of this attribute can be changed. Defaults to false.
      */
@@ -237,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
  */
@@ -249,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
@@ -464,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
      */
@@ -516,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);
     /**
@@ -566,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

@@ -215,15 +215,15 @@ class VirtualPersistentObjectRegistry {
         for (const attr of po.attributes) {
             // Clear previous validation errors
             attr.validationError = undefined;
-            // Find the attribute config to get rules and isRequired
+            // Find the attribute config to get rules
             const attrConfig = config.attributes.find(a => a.name === attr.name);
             if (!attrConfig)
                 continue;
-            // Create a DTO with the rules and isRequired from config
+            // Always use server config for rules and isRequired (never trust client values)
             const attrWithRules = {
                 ...attr,
                 rules: attrConfig.rules,
-                isRequired: attrConfig.isRequired || false
+                isRequired: hasRequiredRule(attrConfig.rules)
             };
             // Validate the attribute
             const error = this.#validator.validateAttribute(attrWithRules, po);
@@ -345,17 +345,36 @@ async function buildPersistentObjectDto(config, queryRegistry, objectId, isNew)
         queries
     };
 }
+/**
+ * Checks if rules string contains NotEmpty or Required
+ */
+function hasRequiredRule(rules) {
+    if (!rules)
+        return false;
+    // Parse the rules string (semicolon-separated)
+    const ruleNames = rules
+        .split(";")
+        .map(rule => rule.trim())
+        .map(rule => {
+        // Extract just the rule name (before any parentheses)
+        const match = rule.match(/^(\w+)/);
+        return match ? match[1] : "";
+    });
+    return ruleNames.includes("NotEmpty") || ruleNames.includes("Required");
+}
 /**
  * Builds a PersistentObjectAttributeDto from configuration
  */
 async function buildAttributeDto(config, index, queryRegistry) {
+    // Automatically set isRequired if rules contain NotEmpty or Required
+    const isRequired = hasRequiredRule(config.rules);
     const baseDto = {
         id: config.id || crypto.randomUUID(),
         name: config.name,
         type: config.type || "String",
         label: config.label || config.name,
         value: config.value,
-        isRequired: config.isRequired || false,
+        isRequired,
         isReadOnly: config.isReadOnly || false,
         rules: config.rules,
         visibility: config.visibility || "Always",
@@ -1209,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));
@@ -1221,7 +1242,33 @@ class BusinessRuleValidator {
         this.#builtInRules.set("MinLength", this.#validateMinLength.bind(this));
         this.#builtInRules.set("MinValue", this.#validateMinValue.bind(this));
         this.#builtInRules.set("NotEmpty", this.#validateNotEmpty.bind(this));
-        this.#builtInRules.set("Required", this.#validateNotEmpty.bind(this)); // Required is same as NotEmpty
+        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
@@ -1253,20 +1300,14 @@ 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);
-        // Check isRequired first
-        if (attr.isRequired) {
-            try {
-                this.#validateNotEmpty(convertedValue, context);
-            }
-            catch (error) {
-                return error instanceof Error ? error.message : String(error);
-            }
-        }
         // Parse and validate rules string
+        // Note: isRequired is auto-set from rules for UI purposes only (e.g., showing asterisks)
+        // All validation logic is handled by the rules themselves
         if (!attr.rules)
             return null;
         const rules = this.parseRules(attr.rules);
@@ -1333,83 +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));
     }
-    #validateNotEmpty(value, context) {
+    #validateRequired(value, _context) {
+        if (value == null)
+            throw new Error(this.#translate("Required"));
+    }
+    #validateNotEmpty(value, _context) {
         if (value == null || value === "" || (typeof value === "string" && value.trim() === ""))
-            throw new Error("This field is required");
+            throw new Error(this.#translate("NotEmpty"));
     }
 }
 
@@ -1445,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
      */
@@ -1953,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);
@@ -2020,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.1.1",
+  "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": "c69d76d2dd9e0289838ca50f1cc89a81fa9a89c3"
+  "gitHash": "db4cd7380e2b729aedf28a81ab348823aa338c4b"
 }