@vidyano-labs/virtual-service 0.1.0

package/index.js

@@ -0,0 +1,2008 @@
+import { DataType, ServiceHooks, Service } from '@vidyano/core';
+
+/**
+ * Value conversion utilities for the virtual service.
+ * Wraps core DataType conversions to return JavaScript primitives instead of BigNumber.
+ *
+ * @example
+ * // Convert from service string to primitive
+ * fromServiceValue("100.50", "Decimal")    // => 100.5 (number)
+ * fromServiceValue("True", "Boolean")      // => true (boolean)
+ * fromServiceValue("15-01-2024 10:30:00", "DateTime")  // => Date object
+ *
+ * @example
+ * // Convert from primitive to service string
+ * toServiceValue(100.5, "Decimal")         // => "100.5"
+ * toServiceValue(true, "Boolean")          // => "True"
+ * toServiceValue(new Date(2024, 0, 15), "Date")  // => "15-01-2024 00:00:00"
+ */
+/**
+ * Converts a service string value to a primitive JavaScript type.
+ * Unlike DataType.fromServiceString, this returns number instead of BigNumber
+ * for numeric types (Decimal, Double, Int64, etc.).
+ */
+function fromServiceValue(value, type) {
+    const result = DataType.fromServiceString(value, type);
+    // Check for BigNumber (has toNumber method) and convert to number primitive
+    if (result && typeof result.toNumber === "function")
+        return result.toNumber();
+    return result;
+}
+/**
+ * Converts a primitive JavaScript value to a service string.
+ */
+function toServiceValue(value, type) {
+    return DataType.toServiceString(value, type);
+}
+
+/**
+ * Registry for managing PersistentObject configurations and instances
+ */
+class VirtualPersistentObjectRegistry {
+    #configs = new Map();
+    #actionHandlers;
+    #validator;
+    #queryRegistry;
+    #actionsRegistry;
+    constructor(validator, actionHandlers, queryRegistry, actionsRegistry) {
+        this.#validator = validator;
+        this.#actionHandlers = actionHandlers;
+        this.#queryRegistry = queryRegistry;
+        this.#actionsRegistry = actionsRegistry;
+    }
+    /**
+     * Registers a PersistentObject configuration
+     */
+    register(config) {
+        this.#configs.set(config.type, config);
+    }
+    /**
+     * Gets a registered PersistentObject configuration
+     */
+    getConfig(type) {
+        return this.#configs.get(type);
+    }
+    /**
+     * Gets or creates a PersistentObject DTO
+     */
+    async getPersistentObject(type, objectId, isNew, parent = null) {
+        const config = this.#configs.get(type);
+        if (!config)
+            throw new Error(`PersistentObject type "${type}" is not registered`);
+        // Create new instance
+        let po = await buildPersistentObjectDto(config, this.#queryRegistry, objectId, isNew);
+        // Auto-add actions based on overridden lifecycle methods
+        if (this.#actionsRegistry.isMethodOverridden(config.type, "onSave")) {
+            if (!po.actions.includes("Save"))
+                po.actions.push("Save");
+        }
+        // Call lifecycle hooks
+        const conversionContext = this.#createConversionContext();
+        // Always call onConstruct
+        this.#actionsRegistry.executeConstruct(po, conversionContext);
+        // Call onLoad only for existing objects
+        if (!isNew)
+            po = await this.#actionsRegistry.executeLoad(po, parent, conversionContext);
+        return po;
+    }
+    /**
+     * Creates a new PersistentObject with the New action lifecycle
+     * @param type - The PersistentObject type
+     * @param parent - The parent PersistentObject (or null)
+     * @param query - The Query from which New was invoked (or null)
+     * @param parameters - Additional parameters (or null)
+     * @returns The new PersistentObject DTO
+     */
+    async createNewPersistentObject(type, parent, query, parameters) {
+        const config = this.#configs.get(type);
+        if (!config)
+            throw new Error(`PersistentObject type "${type}" is not registered`);
+        // Create new instance with a generated ID
+        const objectId = crypto.randomUUID();
+        let po = await buildPersistentObjectDto(config, this.#queryRegistry, objectId, true);
+        // Auto-add actions based on overridden lifecycle methods
+        if (this.#actionsRegistry.isMethodOverridden(config.type, "onSave")) {
+            if (!po.actions.includes("Save"))
+                po.actions.push("Save");
+        }
+        // Call lifecycle hooks
+        const conversionContext = this.#createConversionContext();
+        // Always call onConstruct first
+        this.#actionsRegistry.executeConstruct(po, conversionContext);
+        // Then call onNew for new objects
+        po = await this.#actionsRegistry.executeNew(po, parent, query, parameters, conversionContext);
+        return po;
+    }
+    /**
+     * Executes an action on a PersistentObject
+     */
+    async executeAction(request) {
+        let parent = request.parent;
+        if (!parent)
+            throw new Error("ExecuteAction requires a parent PersistentObject");
+        const type = parent.type;
+        const actionName = request.action.split(".").pop();
+        // Handle refresh action
+        if (actionName === "Refresh")
+            return this.#handleRefresh(request);
+        // Validate before Save action
+        if (actionName === "Save") {
+            const config = this.#configs.get(type);
+            try {
+                const validationFailed = this.#validateAttributes(parent, config);
+                if (validationFailed) {
+                    return {
+                        result: parent
+                    };
+                }
+            }
+            catch (error) {
+                parent.notification = error instanceof Error ? error.message : String(error);
+                parent.notificationType = "Error";
+                return {
+                    result: parent
+                };
+            }
+            // Call onSave from actions registry
+            const conversionContext = this.#createConversionContext();
+            parent = await this.#actionsRegistry.executeSave(parent, conversionContext);
+            return {
+                result: parent
+            };
+        }
+        // Get custom action handler
+        const handler = this.#actionHandlers.get(actionName);
+        if (!handler)
+            throw new Error(`Action "${actionName}" is not registered`);
+        // Create action context
+        const context = this.#createActionContext(parent);
+        // Build unified action args for PersistentObject actions
+        const args = {
+            parent: parent,
+            query: undefined,
+            selectedItems: undefined,
+            parameters: request.parameters,
+            context: context
+        };
+        // Execute handler and get result
+        const result = await handler(args);
+        // Handle both old and new API formats for backwards compatibility
+        // Old API: handler returns { result: PersistentObjectDto }
+        // New API: handler returns PersistentObjectDto | null
+        let finalResult;
+        if (result && typeof result === "object" && "result" in result) {
+            // Old API format - extract the result property
+            finalResult = result.result || parent;
+        }
+        else {
+            // New API format - use directly
+            finalResult = result || parent;
+        }
+        // Return response with result
+        return {
+            result: finalResult
+        };
+    }
+    /**
+     * Handles the PersistentObject.Refresh action
+     */
+    async #handleRefresh(request) {
+        let parent = request.parent;
+        const type = parent.type;
+        const config = this.#configs.get(type);
+        if (!config)
+            throw new Error(`PersistentObject type "${type}" is not registered`);
+        // Get the attribute that triggered the refresh
+        const refreshedAttributeId = request.parameters?.RefreshedPersistentObjectAttributeId;
+        const triggeredAttribute = refreshedAttributeId
+            ? parent.attributes?.find(a => a.id === refreshedAttributeId)
+            : undefined;
+        // Call onRefresh from actions registry
+        const conversionContext = this.#createConversionContext();
+        parent = await this.#actionsRegistry.executeRefresh(parent, triggeredAttribute, conversionContext);
+        return {
+            result: parent
+        };
+    }
+    /**
+     * Validates all attributes on a PersistentObject
+     * @returns true if validation failed, false if all valid
+     */
+    #validateAttributes(po, config) {
+        if (!po.attributes || !config)
+            return false;
+        let hasErrors = false;
+        for (const attr of po.attributes) {
+            // Clear previous validation errors
+            attr.validationError = undefined;
+            // Find the attribute config to get rules and isRequired
+            const attrConfig = config.attributes.find(a => a.name === attr.name);
+            if (!attrConfig)
+                continue;
+            // Create a DTO with the rules and isRequired from config
+            const attrWithRules = {
+                ...attr,
+                rules: attrConfig.rules,
+                isRequired: attrConfig.isRequired || false
+            };
+            // Validate the attribute
+            const error = this.#validator.validateAttribute(attrWithRules);
+            if (error) {
+                attr.validationError = error;
+                hasErrors = true;
+            }
+        }
+        return hasErrors;
+    }
+    /**
+     * Creates an action context for custom action handlers
+     */
+    #createActionContext(po) {
+        return {
+            getAttribute: (name) => {
+                return po.attributes?.find(a => a.name === name);
+            },
+            getAttributeValue: (name) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (!attr)
+                    return undefined;
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setAttributeValue: (name, value) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (attr) {
+                    attr.value = toServiceValue(value, attr.type);
+                    attr.isValueChanged = true;
+                }
+            },
+            getConvertedValue: (attr) => {
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setConvertedValue: (attr, value) => {
+                attr.value = toServiceValue(value, attr.type);
+                attr.isValueChanged = true;
+            },
+            setValidationError: (name, error) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (attr)
+                    attr.validationError = error;
+            },
+            clearValidationError: (name) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (attr)
+                    attr.validationError = undefined;
+            },
+            setNotification: (message, type, duration) => {
+                po.notification = message;
+                po.notificationType = type;
+                po.notificationDuration = duration;
+            }
+        };
+    }
+    /**
+     * Creates a conversion context for type conversions
+     */
+    #createConversionContext() {
+        return {
+            getConvertedValue: (attr) => {
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setConvertedValue: (attr, value) => {
+                attr.value = toServiceValue(value, attr.type);
+                attr.isValueChanged = true;
+            }
+        };
+    }
+}
+/**
+ * Builds a PersistentObjectDto from configuration
+ */
+async function buildPersistentObjectDto(config, queryRegistry, objectId, isNew) {
+    const id = crypto.randomUUID();
+    const fullTypeName = `MockNamespace.${config.type}`;
+    // Build attributes using existing DTO type
+    const attributes = await Promise.all(config.attributes
+        .map((attr, index) => buildAttributeDto(attr, index, queryRegistry)));
+    // Build tabs using existing DTO type
+    const tabs = {};
+    if (config.tabs) {
+        Object.entries(config.tabs).forEach(([key, tab]) => {
+            tabs[key] = {
+                name: tab.name || key,
+                columnCount: tab.columnCount || 0,
+                id: tab.id,
+                layout: tab.layout
+            };
+        });
+    }
+    else {
+        // Default tab
+        tabs[""] = { name: "", columnCount: 0 };
+    }
+    // Build action names (reference by name)
+    const actions = config.actions || [];
+    // Build queries (detail queries)
+    const queries = [];
+    if (config.queries) {
+        for (const queryName of config.queries) {
+            const queryDto = await queryRegistry.getQuery(queryName);
+            queries.push(queryDto);
+        }
+    }
+    // Return proper PersistentObjectDto
+    return {
+        id,
+        objectId,
+        type: config.type,
+        fullTypeName,
+        label: config.label || config.type,
+        isNew,
+        isReadOnly: false,
+        stateBehavior: config.stateBehavior || "StayInEdit",
+        attributes,
+        actions,
+        tabs,
+        queries
+    };
+}
+/**
+ * Builds a PersistentObjectAttributeDto from configuration
+ */
+async function buildAttributeDto(config, index, queryRegistry) {
+    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,
+        isReadOnly: config.isReadOnly || false,
+        rules: config.rules,
+        visibility: config.visibility || "Always",
+        group: config.group || "",
+        tab: config.tab || "",
+        triggersRefresh: config.triggersRefresh || false,
+        options: config.options,
+        typeHints: config.typeHints,
+        column: config.column,
+        columnSpan: config.columnSpan || 4,
+        offset: config.offset ?? index
+    };
+    // Handle Reference attributes with lookup
+    if (config.lookup) {
+        if (!queryRegistry)
+            throw new Error(`Cannot build reference attribute "${config.name}" without queryRegistry`);
+        const lookupQuery = await queryRegistry.getQuery(config.lookup);
+        // Determine displayAttribute - use provided or first visible column from lookup query
+        let displayAttribute = config.displayAttribute;
+        if (!displayAttribute && lookupQuery.columns && lookupQuery.columns.length > 0) {
+            // Find first non-Id visible column, or use first column
+            const firstVisibleColumn = lookupQuery.columns.find(c => !c.isHidden && c.name !== "Id");
+            displayAttribute = firstVisibleColumn?.name || lookupQuery.columns[0].name;
+        }
+        if (!displayAttribute)
+            displayAttribute = "Id";
+        // Build reference attribute DTO
+        const refDto = {
+            ...baseDto,
+            type: "Reference",
+            lookup: lookupQuery,
+            objectId: config.value || null,
+            displayAttribute,
+            canAddNewReference: config.canAddNewReference ?? false,
+            selectInPlace: config.selectInPlace ?? false
+        };
+        return refDto;
+    }
+    return baseDto;
+}
+
+/**
+ * Registry for managing Query configurations
+ */
+class VirtualQueryRegistry {
+    #configs = new Map();
+    #actionsRegistry;
+    constructor(actionsRegistry) {
+        this.#actionsRegistry = actionsRegistry || null;
+    }
+    /**
+     * Checks if a query is registered
+     * @param name - The query name
+     */
+    hasQuery(name) {
+        return this.#configs.has(name);
+    }
+    /**
+     * Registers a Query configuration
+     */
+    register(config, persistentObjectConfig) {
+        // Validate required fields
+        if (!config.name || config.name.trim() === "")
+            throw new Error("Query configuration must have a 'name' property");
+        if (!config.persistentObject || config.persistentObject.trim() === "")
+            throw new Error("Query configuration must have a 'persistentObject' property");
+        // Derive columns from PersistentObject configuration
+        const columns = VirtualQueryRegistry.#deriveColumnsFromPersistentObject(persistentObjectConfig);
+        this.#configs.set(config.name, {
+            config,
+            columns,
+            persistentObjectConfig,
+            data: config.data || []
+        });
+    }
+    /**
+     * Derives query columns from PersistentObject attributes
+     */
+    static #deriveColumnsFromPersistentObject(poConfig) {
+        return poConfig.attributes.map((attr, index) => {
+            const offset = attr.offset ?? index;
+            return {
+                id: attr.name,
+                name: attr.name,
+                label: attr.label || this.#humanize(attr.name),
+                type: attr.type || "String",
+                offset,
+                isHidden: this.#mapVisibilityToIsHidden(attr.visibility),
+                isSensitive: false,
+                // Query capabilities - following plan specifications
+                canFilter: false, // Not supported in mock implementation
+                canSort: attr.canSort ?? true, // Defaults to true
+                canGroupBy: false, // Not supported in mock implementation
+                canListDistincts: false, // Not supported (no filtering)
+                // Filter arrays (empty for mock)
+                includes: [],
+                excludes: []
+                // Note: typeHints are not stored on columns, only on QueryResultItemValueDto
+            };
+        });
+    }
+    /**
+     * Maps attribute visibility to column isHidden property
+     */
+    static #mapVisibilityToIsHidden(visibility) {
+        if (!visibility || visibility === "Always" || visibility === "Read" || visibility === "Query")
+            return false;
+        if (visibility === "New" || visibility === "Never")
+            return true;
+        // Handle compound visibility values
+        if (visibility === "Read, Query" || visibility === "Query, New")
+            return false;
+        if (visibility === "Read, New")
+            return true;
+        return false;
+    }
+    /**
+     * Converts camelCase or PascalCase string to human-readable format
+     */
+    static #humanize(name) {
+        if (!name)
+            return name;
+        // Insert space before capital letters (except first) and between number/letter transitions
+        return name
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+            .replace(/([a-zA-Z])(\d)/g, '$1 $2')
+            .replace(/(\d)([a-zA-Z])/g, '$1 $2')
+            .trim();
+    }
+    /**
+     * Gets a QueryDto by name
+     * @param name - The query name
+     * @param parent - The parent PersistentObject (for detail queries) or null
+     */
+    async getQuery(name, parent) {
+        const entry = this.#configs.get(name);
+        if (!entry)
+            throw new Error(`Query '${name}' is not registered`);
+        const { config, columns, persistentObjectConfig } = entry;
+        // Build default actions
+        const actions = ["RefreshQuery"];
+        // Auto-add New if onNew is overridden for the PersistentObject type
+        if (this.#actionsRegistry?.isMethodOverridden(persistentObjectConfig.type, "onNew")) {
+            if (!actions.includes("New"))
+                actions.push("New");
+        }
+        // Auto-add Delete if onDelete is overridden for the PersistentObject type
+        if (this.#actionsRegistry?.isMethodOverridden(persistentObjectConfig.type, "onDelete")) {
+            if (!actions.includes("Delete"))
+                actions.push("Delete");
+        }
+        // Add custom query-level actions
+        if (config.actions) {
+            for (const actionName of config.actions)
+                if (!actions.includes(actionName))
+                    actions.push(actionName);
+        }
+        // Add custom item-level actions
+        if (config.itemActions) {
+            for (const actionName of config.itemActions)
+                if (!actions.includes(actionName))
+                    actions.push(actionName);
+        }
+        // Build the query DTO first (needed for onConstructQuery and executeQuery)
+        const queryDto = buildQueryDto(config, columns, actions, persistentObjectConfig);
+        // Call onConstructQuery lifecycle hook
+        if (this.#actionsRegistry)
+            this.#actionsRegistry.executeConstructQuery(queryDto, parent || null);
+        // Handle autoQuery flag - execute query to get initial results
+        if (config.autoQuery !== false && this.#actionsRegistry) {
+            const result = await this.executeQuery(queryDto, parent || null);
+            queryDto.result = result;
+        }
+        return queryDto;
+    }
+    /**
+     * Executes a query by delegating to the actions registry's onExecuteQuery
+     * @param query - The query DTO with textSearch, sortOptions, skip, top set
+     * @param parent - The parent PersistentObject (for detail queries) or null
+     */
+    async executeQuery(query, parent) {
+        if (!this.#actionsRegistry)
+            throw new Error("Actions registry is required for query execution");
+        const entry = this.#configs.get(query.name);
+        if (!entry)
+            throw new Error(`Query '${query.name}' is not registered`);
+        const { columns, data } = entry;
+        // Use registered columns (with isHidden) instead of request columns
+        const queryWithColumns = { ...query, columns };
+        // Delegate to actions registry to get items, passing default data from config
+        const result = await this.#actionsRegistry.executeQuery(queryWithColumns, parent, data);
+        // Convert data rows to QueryResultItemDto
+        const items = result.items.map(row => buildQueryResultItemDto(row, columns));
+        // Build and return QueryResultDto
+        return buildQueryResultDto(items, columns, result.totalItems, undefined, // No continuation - use skip/top instead
+        query.pageSize, query.skip, query.sortOptions);
+    }
+}
+/**
+ * Builds a QueryDto from configuration
+ */
+function buildQueryDto(config, columns, actions, persistentObjectConfig) {
+    // Build minimal PersistentObjectDto for the query
+    const persistentObject = {
+        type: persistentObjectConfig.type,
+        id: crypto.randomUUID(),
+        objectId: null,
+        label: persistentObjectConfig.type,
+        fullTypeName: `Mock.${persistentObjectConfig.type}`,
+        isNew: false,
+        isReadOnly: true,
+        attributes: [],
+        actions: [],
+        tabs: {},
+        queries: []
+    };
+    return {
+        id: crypto.randomUUID(),
+        name: config.name,
+        label: config.label || config.name,
+        columns,
+        actions,
+        allowTextSearch: config.allowTextSearch ?? true,
+        disableBulkEdit: config.disableBulkEdit ?? false,
+        autoQuery: config.autoQuery ?? true,
+        pageSize: config.pageSize || 20,
+        persistentObject,
+        sortOptions: "",
+        textSearch: "",
+        skip: 0,
+        top: config.pageSize || 20,
+        totalItems: -1,
+        canRead: true,
+        canReorder: false,
+        enableSelectAll: true
+    };
+}
+/**
+ * Builds a QueryResultDto from result data
+ */
+function buildQueryResultDto(items, columns, totalItems, continuation, pageSize, skip, sortOptions) {
+    return {
+        items,
+        columns,
+        totalItems,
+        continuation,
+        pageSize,
+        skip,
+        sortOptions: sortOptions || "",
+        charts: []
+    };
+}
+/**
+ * Builds a QueryResultItemDto from a data row
+ */
+function buildQueryResultItemDto(data, columns) {
+    // Extract or generate ID (check both lowercase "id" and capitalized "Id")
+    let id;
+    if (data["id"] != null && (typeof data["id"] === "string" || typeof data["id"] === "number"))
+        id = String(data["id"]);
+    else if (data["Id"] != null && (typeof data["Id"] === "string" || typeof data["Id"] === "number"))
+        id = String(data["Id"]);
+    else
+        id = crypto.randomUUID();
+    // Build values array
+    const values = columns.map(column => {
+        return buildQueryResultItemValueDto(column.name, data[column.name], column.type, data[column.name + "Id"], data[column.name + "$typeHints"]);
+    });
+    // Extract typeHints and tag from row if present
+    const typeHints = data.$typeHints;
+    const tag = data.$tag;
+    return {
+        id,
+        values,
+        typeHints,
+        tag
+    };
+}
+/**
+ * Builds a QueryResultItemValueDto from a single value
+ * Converts JavaScript primitives to service string format
+ */
+function buildQueryResultItemValueDto(key, rawValue, type, objectId, typeHints) {
+    // Convert to service string format using DataType.toServiceString
+    const value = rawValue == null
+        ? null
+        : DataType.toServiceString(rawValue, type);
+    return {
+        key,
+        value,
+        objectId,
+        typeHints
+    };
+}
+
+/**
+ * Base class for PersistentObject lifecycle methods
+ * Extend this class to override lifecycle hooks like onLoad, onSave, onRefresh, etc.
+ * All methods have default implementations, so you only need to override what you need.
+ */
+class VirtualPersistentObjectActions {
+    /**
+     * Called every time a PersistentObject DTO is created (both new and existing objects)
+     * Use this to set metadata on attributes that can only be known at runtime
+     * @param obj - The PersistentObject DTO being constructed
+     */
+    onConstruct(obj) {
+        // Default implementation: do nothing
+    }
+    /**
+     * Called when loading an existing PersistentObject by ID
+     * Use this to load entity data and populate attribute values
+     * @param obj - The constructed PersistentObject DTO (after onConstruct)
+     * @param parent - The parent PersistentObject if loaded in a master-detail context, null otherwise
+     * @returns The PersistentObject with loaded data
+     */
+    async onLoad(obj, parent) {
+        // Default implementation: return obj as-is
+        return obj;
+    }
+    /**
+     * Called when creating a new PersistentObject via the "New" action
+     * Use this to create a fresh entity instance with default values
+     * @param obj - The constructed PersistentObject DTO (after onConstruct)
+     * @param parent - The parent PersistentObject if creating from a detail query, null otherwise
+     * @param query - The Query from which the New action was invoked, null if not from a query
+     * @param parameters - Optional parameters including "MenuOption" if NewOptions exist
+     * @returns The PersistentObject with default values set
+     */
+    async onNew(obj, parent, query, parameters) {
+        // Default implementation: return obj as-is
+        return obj;
+    }
+    /**
+     * Called when an attribute with triggersRefresh: true is changed
+     * Use this to update other attributes based on the changed attribute
+     * @param obj - The PersistentObject DTO in edit mode
+     * @param attribute - The attribute that triggered the refresh (the one with triggersRefresh=true that was changed), wrapped with getValue/setValue
+     * @returns The PersistentObject with refreshed attributes
+     */
+    async onRefresh(obj, attribute) {
+        // Default implementation: return obj as-is
+        return obj;
+    }
+    /**
+     * Called when the Save action is executed
+     * Orchestrates the save process by calling saveNew or saveExisting based on obj.isNew
+     * @param obj - The PersistentObject DTO to save
+     * @returns The saved PersistentObject
+     */
+    async onSave(obj) {
+        // Default implementation: delegate to saveNew or saveExisting based on isNew flag
+        if (obj.isNew)
+            return await this.saveNew(obj);
+        else
+            return await this.saveExisting(obj);
+    }
+    /**
+     * Called by onSave when obj.isNew === true
+     * Use this to save a new entity to the data store
+     * @param obj - The new PersistentObject DTO to save
+     * @returns The saved PersistentObject
+     */
+    async saveNew(obj) {
+        // Default implementation: return obj as-is (no persistence in mock)
+        return obj;
+    }
+    /**
+     * Called by onSave when obj.isNew === false
+     * Use this to update an existing entity in the data store
+     * @param obj - The existing PersistentObject DTO to save
+     * @returns The saved PersistentObject
+     */
+    async saveExisting(obj) {
+        // Default implementation: return obj as-is (no persistence in mock)
+        return obj;
+    }
+    /**
+     * Called when a reference attribute is changed (via changeReference() on a PersistentObjectAttributeWithReference)
+     * The base implementation sets objectId, value, and isValueChanged on the reference attribute.
+     * Override this to add custom logic after the reference is set.
+     * @param parent - The PersistentObject that contains the reference attribute
+     * @param referenceAttribute - The reference attribute that was changed
+     * @param query - The query that was used to select the reference
+     * @param selectedItem - The QueryResultItem that was selected, or null if reference was cleared
+     */
+    async onSelectReference(_parent, referenceAttribute, _query, selectedItem) {
+        const refAttr = referenceAttribute;
+        if (selectedItem == null) {
+            // Clear the reference
+            refAttr.objectId = null;
+            refAttr.value = null;
+        }
+        else {
+            // Set the reference to the selected item
+            refAttr.objectId = selectedItem.id;
+            // Get the display value from the item using displayAttribute
+            const displayAttribute = refAttr.displayAttribute;
+            const displayValue = selectedItem.values?.find((v) => v.key === displayAttribute);
+            refAttr.value = displayValue?.value || selectedItem.id;
+        }
+        refAttr.isValueChanged = true;
+    }
+    /**
+     * Called when the Delete action is executed on selected items in a Query
+     * Use this to handle deletion of entities
+     * @param parent - The parent PersistentObject if deleting from a detail query, null for top-level queries
+     * @param query - The query from which items are being deleted
+     * @param selectedItems - The QueryResultItems that are selected for deletion
+     */
+    async onDelete(parent, query, selectedItems) {
+        // Default implementation: do nothing (no persistence in mock)
+    }
+    /**
+     * Called when a Query of this PersistentObject type is constructed
+     * Use this to set metadata on query columns that can only be known at runtime
+     * @param query - The Query DTO being constructed
+     * @param parent - The parent PersistentObject if this is a detail query, null for top-level queries
+     */
+    onConstructQuery(query, parent) {
+        // Default implementation: do nothing
+    }
+    /**
+     * Called when a Query is executed.
+     * The base implementation calls getEntities() and applies text search, sorting, and pagination.
+     * @param query - The Query DTO with textSearch, sortOptions, skip, top properties set
+     * @param parent - The parent PersistentObject if this is a detail query, null for top-level queries
+     * @param data - Default data from the query config (used if getEntities is not overridden)
+     * @returns The items matching the query criteria and the total count before pagination
+     */
+    async onExecuteQuery(query, parent, data) {
+        // Get all items from subclass or use provided data
+        let result = await this.getEntities(query, parent, data);
+        // Apply text search if provided
+        if (query.textSearch && query.textSearch.trim() !== "") {
+            const searchLower = query.textSearch.toLowerCase();
+            const stringColumns = query.columns?.filter(c => c.type === "String" && !c.isHidden) || [];
+            result = result.filter(row => {
+                for (const column of stringColumns) {
+                    const value = String(row[column.name] || "").toLowerCase();
+                    if (value.includes(searchLower))
+                        return true;
+                }
+                return false;
+            });
+        }
+        // Apply sorting if provided
+        if (query.sortOptions && query.sortOptions.trim() !== "") {
+            const sortParts = query.sortOptions.split(";").map(s => s.trim()).filter(Boolean);
+            const sortOptions = sortParts.map(part => {
+                const [name, dir] = part.split(/\s+/);
+                return { name, direction: dir?.toUpperCase() === "DESC" ? "DESC" : "ASC" };
+            });
+            result = [...result].sort((a, b) => {
+                for (const { name, direction } of sortOptions) {
+                    const aVal = a[name];
+                    const bVal = b[name];
+                    // Null handling
+                    if (aVal == null && bVal == null)
+                        continue;
+                    if (aVal == null)
+                        return direction === "ASC" ? -1 : 1;
+                    if (bVal == null)
+                        return direction === "ASC" ? 1 : -1;
+                    // Type-aware comparison
+                    let cmp = 0;
+                    if (typeof aVal === "boolean")
+                        cmp = aVal === bVal ? 0 : (aVal ? 1 : -1);
+                    else if (aVal instanceof Date && bVal instanceof Date)
+                        cmp = aVal.getTime() - bVal.getTime();
+                    else if (typeof aVal === "number" && typeof bVal === "number")
+                        cmp = aVal - bVal;
+                    else
+                        cmp = String(aVal).toLowerCase().localeCompare(String(bVal).toLowerCase());
+                    if (cmp !== 0)
+                        return direction === "ASC" ? cmp : -cmp;
+                }
+                return 0;
+            });
+        }
+        // Apply pagination
+        const skip = query.skip || 0;
+        const top = query.top || query.pageSize || 20;
+        const items = result.slice(skip, skip + top);
+        return {
+            items,
+            totalItems: result.length
+        };
+    }
+    /**
+     * Override this to provide the full list of items for a query.
+     * The base onExecuteQuery will handle text search, sorting, and pagination automatically.
+     * @param query - The Query DTO with textSearch, sortOptions properties set
+     * @param parent - The parent PersistentObject if this is a detail query, null for top-level queries
+     * @param data - Default data from the query config
+     * @returns All items matching the query criteria (before pagination)
+     */
+    async getEntities(_query, _parent, data) {
+        // Default implementation: return provided data (from query config)
+        return [...data];
+    }
+}
+
+/**
+ * Creates a VirtualPersistentObjectAttribute by wrapping an attribute DTO with a Proxy
+ * The Proxy intercepts property access to provide getValue/setValue methods
+ * @param attr - The PersistentObjectAttributeDto to wrap
+ * @param conversionContext - The conversion context for type conversions
+ * @returns A VirtualPersistentObjectAttribute that combines DTO properties with helper methods
+ */
+function createVirtualPersistentObjectAttribute(attr, conversionContext) {
+    const helpers = {
+        getValue() {
+            return conversionContext.getConvertedValue(attr);
+        },
+        setValue(value) {
+            conversionContext.setConvertedValue(attr, value);
+        },
+        setValidationError(error) {
+            attr.validationError = error;
+        },
+        clearValidationError() {
+            attr.validationError = undefined;
+        }
+    };
+    return new Proxy(attr, {
+        get(target, prop) {
+            if (prop in helpers)
+                return helpers[prop];
+            return target[prop];
+        },
+        set(target, prop, value) {
+            target[prop] = value;
+            return true;
+        }
+    });
+}
+/**
+ * Creates a VirtualPersistentObject by wrapping a DTO with a Proxy
+ * The Proxy intercepts property access to provide helper methods while keeping the underlying DTO unchanged
+ * @param dto - The PersistentObjectDto to wrap
+ * @param conversionContext - The conversion context for type conversions
+ * @returns A VirtualPersistentObject that combines DTO properties with helper methods
+ */
+function createVirtualPersistentObject(dto, conversionContext) {
+    // Helper methods - logic is inlined here, only using conversionContext for type conversion
+    const helpers = {
+        getAttribute(name) {
+            const attr = dto.attributes?.find(a => a.name === name);
+            if (!attr)
+                return undefined;
+            return createVirtualPersistentObjectAttribute(attr, conversionContext);
+        },
+        getAttributeValue(name) {
+            const attr = dto.attributes?.find(a => a.name === name);
+            if (!attr)
+                return undefined;
+            return conversionContext.getConvertedValue(attr);
+        },
+        setAttributeValue(name, value) {
+            const attr = dto.attributes?.find(a => a.name === name);
+            if (attr)
+                conversionContext.setConvertedValue(attr, value);
+        },
+        setValidationError(name, error) {
+            const attr = dto.attributes?.find(a => a.name === name);
+            if (attr)
+                attr.validationError = error;
+        },
+        clearValidationError(name) {
+            const attr = dto.attributes?.find(a => a.name === name);
+            if (attr)
+                attr.validationError = undefined;
+        },
+        setNotification(message, type, duration) {
+            dto.notification = message;
+            dto.notificationType = type;
+            dto.notificationDuration = duration;
+        }
+    };
+    // Create a Proxy that intercepts property access
+    return new Proxy(dto, {
+        get(target, prop) {
+            // If accessing a helper method, return it
+            if (prop in helpers)
+                return helpers[prop];
+            // Otherwise, return the DTO property
+            return target[prop];
+        },
+        set(target, prop, value) {
+            // Allow setting DTO properties directly
+            target[prop] = value;
+            return true;
+        }
+    });
+}
+/**
+ * Unwraps a VirtualPersistentObject to get the underlying DTO
+ * Since the Proxy wraps the DTO, we can safely cast it back
+ * @param wrapped - The VirtualPersistentObject to unwrap
+ * @returns The underlying PersistentObjectDto
+ */
+function unwrapVirtualPersistentObject(wrapped) {
+    // The wrapped object is a Proxy around the DTO
+    // We can return it as-is since the DTO is the target of the Proxy
+    return wrapped;
+}
+
+/**
+ * Registry for managing VirtualPersistentObjectActions classes
+ * Provides methods to register actions classes and execute lifecycle hooks
+ */
+class VirtualPersistentObjectActionsRegistry {
+    #actionsClasses = new Map();
+    #overrideInfo = new Map();
+    /**
+     * Registers a VirtualPersistentObjectActions class for a specific type
+     * @param type - The PersistentObject type name
+     * @param ActionsClass - The VirtualPersistentObjectActions class constructor
+     */
+    register(type, ActionsClass) {
+        this.#actionsClasses.set(type, ActionsClass);
+        // Detect overridden methods
+        const overriddenMethods = this.#detectOverriddenMethods(ActionsClass);
+        this.#overrideInfo.set(type, { overriddenMethods });
+    }
+    /**
+     * Detects which lifecycle methods are overridden in the given class
+     * @param ActionsClass - The VirtualPersistentObjectActions class constructor
+     * @returns Set of overridden method names
+     */
+    #detectOverriddenMethods(ActionsClass) {
+        const overridden = new Set();
+        const baseProto = VirtualPersistentObjectActions.prototype;
+        const classProto = ActionsClass.prototype;
+        const methodsToCheck = [
+            "onSave", "onNew", "onDelete", "onRefresh",
+            "onLoad", "onConstruct", "onConstructQuery", "onSelectReference", "onExecuteQuery", "getEntities"
+        ];
+        for (const methodName of methodsToCheck) {
+            if (classProto[methodName] !== baseProto[methodName])
+                overridden.add(methodName);
+        }
+        return overridden;
+    }
+    /**
+     * Checks if a specific lifecycle method is overridden for a type
+     * @param type - The PersistentObject type name
+     * @param methodName - The lifecycle method name
+     * @returns true if the method is overridden, false otherwise
+     */
+    isMethodOverridden(type, methodName) {
+        const info = this.#overrideInfo.get(type);
+        if (!info)
+            return false;
+        return info.overriddenMethods.has(methodName);
+    }
+    /**
+     * Checks if a type has registered actions
+     * @param type - The PersistentObject type name
+     * @returns true if the type has registered actions, false otherwise
+     */
+    has(type) {
+        return this.#actionsClasses.has(type);
+    }
+    /**
+     * Creates a new instance of the actions class for a type
+     * Returns a default VirtualPersistentObjectActions if no custom actions are registered
+     * @param type - The PersistentObject type name
+     * @returns A new instance of the VirtualPersistentObjectActions class
+     */
+    createInstance(type) {
+        const ActionsClass = this.#actionsClasses.get(type);
+        if (!ActionsClass)
+            return new VirtualPersistentObjectActions();
+        return new ActionsClass();
+    }
+    /**
+     * Executes onConstruct lifecycle hook
+     * @param dto - The PersistentObject DTO
+     * @param conversionContext - The conversion context for type conversions
+     */
+    executeConstruct(dto, conversionContext) {
+        const wrappedObj = createVirtualPersistentObject(dto, conversionContext);
+        const instance = this.createInstance(dto.type);
+        instance.onConstruct(wrappedObj);
+    }
+    /**
+     * Executes onLoad lifecycle hook
+     * @param dto - The PersistentObject DTO
+     * @param parent - The parent DTO (or null)
+     * @param conversionContext - The conversion context for type conversions
+     * @returns The updated DTO
+     */
+    async executeLoad(dto, parent, conversionContext) {
+        const wrappedObj = createVirtualPersistentObject(dto, conversionContext);
+        // Wrap parent if provided
+        let wrappedParent = null;
+        if (parent) {
+            const parentContext = this.#createConversionContext();
+            wrappedParent = createVirtualPersistentObject(parent, parentContext);
+        }
+        const instance = this.createInstance(dto.type);
+        const result = await instance.onLoad(wrappedObj, wrappedParent);
+        return unwrapVirtualPersistentObject(result);
+    }
+    /**
+     * Executes onNew lifecycle hook
+     * @param dto - The PersistentObject DTO
+     * @param parent - The parent DTO (or null)
+     * @param query - The query DTO (or null)
+     * @param parameters - The parameters (or null)
+     * @param conversionContext - The conversion context for type conversions
+     * @returns The updated DTO
+     */
+    async executeNew(dto, parent, query, parameters, conversionContext) {
+        const wrappedObj = createVirtualPersistentObject(dto, conversionContext);
+        // Wrap parent if provided
+        let wrappedParent = null;
+        if (parent) {
+            const parentContext = this.#createConversionContext();
+            wrappedParent = createVirtualPersistentObject(parent, parentContext);
+        }
+        const instance = this.createInstance(dto.type);
+        const result = await instance.onNew(wrappedObj, wrappedParent, query, parameters);
+        return unwrapVirtualPersistentObject(result);
+    }
+    /**
+     * Executes onRefresh lifecycle hook
+     * @param dto - The PersistentObject DTO
+     * @param attribute - The attribute that triggered the refresh (or undefined)
+     * @param conversionContext - The conversion context for type conversions
+     * @returns The updated DTO
+     */
+    async executeRefresh(dto, attribute, conversionContext) {
+        const wrappedObj = createVirtualPersistentObject(dto, conversionContext);
+        // Wrap attribute if provided
+        let wrappedAttribute;
+        if (attribute)
+            wrappedAttribute = createVirtualPersistentObjectAttribute(attribute, conversionContext);
+        const instance = this.createInstance(dto.type);
+        const result = await instance.onRefresh(wrappedObj, wrappedAttribute);
+        return unwrapVirtualPersistentObject(result);
+    }
+    /**
+     * Executes onSave lifecycle hook
+     * @param dto - The PersistentObject DTO
+     * @param conversionContext - The conversion context for type conversions
+     * @returns The updated DTO
+     */
+    async executeSave(dto, conversionContext) {
+        const wrappedObj = createVirtualPersistentObject(dto, conversionContext);
+        const instance = this.createInstance(dto.type);
+        const result = await instance.onSave(wrappedObj);
+        return unwrapVirtualPersistentObject(result);
+    }
+    /**
+     * Executes onSelectReference lifecycle hook
+     * @param parent - The parent DTO
+     * @param referenceAttribute - The reference attribute DTO
+     * @param query - The query DTO
+     * @param selectedItem - The selected item (or null)
+     * @param conversionContext - The conversion context for type conversions
+     */
+    async executeSelectReference(parent, referenceAttribute, query, selectedItem, conversionContext) {
+        const wrappedParent = createVirtualPersistentObject(parent, conversionContext);
+        const instance = this.createInstance(parent.type);
+        await instance.onSelectReference(wrappedParent, referenceAttribute, query, selectedItem);
+    }
+    /**
+     * Executes onDelete lifecycle hook
+     * @param parent - The parent DTO (or null)
+     * @param query - The query DTO
+     * @param selectedItems - The selected items
+     */
+    async executeDelete(parent, query, selectedItems) {
+        // Wrap parent if provided
+        let wrappedParent = null;
+        if (parent) {
+            const conversionContext = this.#createConversionContext();
+            wrappedParent = createVirtualPersistentObject(parent, conversionContext);
+        }
+        // Get type from query's persistentObject
+        const type = query.persistentObject?.type;
+        if (!type)
+            throw new Error("Query does not have a persistentObject type");
+        const instance = this.createInstance(type);
+        await instance.onDelete(wrappedParent, query, selectedItems);
+    }
+    /**
+     * Executes onConstructQuery lifecycle hook
+     * @param query - The query DTO
+     * @param parent - The parent DTO (or null)
+     */
+    executeConstructQuery(query, parent) {
+        // Wrap parent if provided
+        let wrappedParent = null;
+        if (parent) {
+            const conversionContext = this.#createConversionContext();
+            wrappedParent = createVirtualPersistentObject(parent, conversionContext);
+        }
+        // Get type from query's persistentObject
+        const type = query.persistentObject?.type;
+        if (!type)
+            throw new Error("Query does not have a persistentObject type");
+        const instance = this.createInstance(type);
+        instance.onConstructQuery(query, wrappedParent);
+    }
+    /**
+     * Executes onExecuteQuery lifecycle hook
+     * @param query - The query DTO with textSearch, sortOptions, skip, top set
+     * @param parent - The parent DTO (or null)
+     * @param data - Default data from the query config (used if getEntities is not overridden)
+     * @returns The query execution result with items and totalItems
+     */
+    async executeQuery(query, parent, data) {
+        // Wrap parent if provided
+        let wrappedParent = null;
+        if (parent) {
+            const conversionContext = this.#createConversionContext();
+            wrappedParent = createVirtualPersistentObject(parent, conversionContext);
+        }
+        // Get type from query's persistentObject
+        const type = query.persistentObject?.type;
+        if (!type)
+            throw new Error("Query does not have a persistentObject type");
+        const instance = this.createInstance(type);
+        return await instance.onExecuteQuery(query, wrappedParent, data);
+    }
+    /**
+     * Creates a conversion context for type conversions
+     * @returns A ConversionContext with type conversion methods
+     */
+    #createConversionContext() {
+        return {
+            getConvertedValue: (attr) => {
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setConvertedValue: (attr, value) => {
+                attr.value = toServiceValue(value, attr.type);
+                attr.isValueChanged = true;
+            }
+        };
+    }
+}
+
+/**
+ * Business rule validator that supports built-in and custom rules
+ */
+class BusinessRuleValidator {
+    #builtInRules = new Map();
+    #customRules = new Map();
+    constructor() {
+        // Register all built-in rules
+        this.#builtInRules.set("IsBase64", this.#validateIsBase64.bind(this));
+        this.#builtInRules.set("IsEmail", this.#validateIsEmail.bind(this));
+        this.#builtInRules.set("IsRegex", this.#validateIsRegex.bind(this));
+        this.#builtInRules.set("IsUrl", this.#validateIsUrl.bind(this));
+        this.#builtInRules.set("IsWord", this.#validateIsWord.bind(this));
+        this.#builtInRules.set("MaxLength", this.#validateMaxLength.bind(this));
+        this.#builtInRules.set("MaxValue", this.#validateMaxValue.bind(this));
+        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
+    }
+    /**
+     * Register a custom business rule
+     * @throws Error if attempting to override a built-in rule
+     */
+    registerCustomRule(name, validator) {
+        if (this.#builtInRules.has(name))
+            throw new Error(`Cannot override built-in rule: ${name}`);
+        this.#customRules.set(name, validator);
+    }
+    /**
+     * Validate an attribute against its rules
+     * @returns Error message if validation fails, null if valid
+     */
+    validateAttribute(attr) {
+        // Check isRequired first
+        if (attr.isRequired) {
+            try {
+                this.#validateNotEmpty(attr.value);
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : String(error);
+            }
+        }
+        // Parse and validate rules string
+        if (!attr.rules)
+            return null;
+        const rules = this.parseRules(attr.rules);
+        for (const rule of rules) {
+            const validator = this.#builtInRules.get(rule.name) || this.#customRules.get(rule.name);
+            if (!validator)
+                throw new Error(`Unknown business rule: ${rule.name}`);
+            try {
+                validator(attr.value, ...rule.params);
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : String(error);
+            }
+        }
+        return null;
+    }
+    /**
+     * Parse a rules string into individual rules with parameters
+     * Example: "NotEmpty; MaxLength(40); IsEmail" -> [
+     *   { name: "NotEmpty", params: [] },
+     *   { name: "MaxLength", params: [40] },
+     *   { name: "IsEmail", params: [] }
+     * ]
+     */
+    parseRules(rulesString) {
+        if (!rulesString?.trim())
+            return [];
+        return rulesString
+            .split(";")
+            .map(rule => rule.trim())
+            .filter(rule => rule.length > 0)
+            .map(rule => this.#parseRule(rule));
+    }
+    #parseRule(ruleString) {
+        const match = ruleString.match(/^(\w+)(?:\(([^)]*)\))?$/);
+        if (!match)
+            throw new Error(`Invalid rule format: ${ruleString}`);
+        const name = match[1];
+        const paramsString = match[2];
+        if (!paramsString) {
+            return { name, params: [] };
+        }
+        // Parse parameters (can be comma-separated)
+        const params = paramsString
+            .split(",")
+            .map(p => p.trim())
+            .map(p => {
+            // Try to parse as number
+            const num = Number(p);
+            if (p !== "" && !isNaN(num))
+                return num;
+            // Try to parse as boolean
+            if (p === "true")
+                return true;
+            if (p === "false")
+                return false;
+            // Otherwise return as string (remove quotes if present)
+            return p.replace(/^["']|["']$/g, "");
+        });
+        return { name, params };
+    }
+    // Built-in validators - throw errors instead of returning strings
+    #validateIsBase64(value) {
+        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");
+    }
+    #validateIsEmail(value) {
+        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");
+    }
+    #validateIsRegex(value) {
+        if (value == null || value === "")
+            return;
+        try {
+            new RegExp(String(value));
+        }
+        catch {
+            throw new Error("Value must be a valid regular expression");
+        }
+    }
+    #validateIsUrl(value) {
+        if (value == null || value === "")
+            return;
+        try {
+            new URL(String(value));
+        }
+        catch {
+            throw new Error("Value must be a valid URL");
+        }
+    }
+    #validateIsWord(value) {
+        if (value == null || value === "")
+            return;
+        const wordRegex = /^\w+$/;
+        if (!wordRegex.test(String(value)))
+            throw new Error("Value must contain only word characters");
+    }
+    #validateMaxLength(value, maxLength) {
+        if (value == null || value === "")
+            return;
+        const length = String(value).length;
+        if (length > maxLength)
+            throw new Error(`Maximum length is ${maxLength} characters`);
+    }
+    #validateMaxValue(value, 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}`);
+    }
+    #validateMinLength(value, minLength) {
+        if (value == null || value === "")
+            return;
+        const length = String(value).length;
+        if (length < minLength)
+            throw new Error(`Minimum length is ${minLength} characters`);
+    }
+    #validateMinValue(value, 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}`);
+    }
+    #validateNotEmpty(value) {
+        if (value == null || value === "" || (typeof value === "string" && value.trim() === ""))
+            throw new Error("This field is required");
+    }
+}
+
+/**
+ * Virtual implementation of ServiceHooks for testing without a backend
+ */
+class VirtualServiceHooks extends ServiceHooks {
+    #persistentObjectRegistry;
+    #queryRegistry;
+    #actionDefinitions = new Map();
+    #actionHandlers = new Map();
+    #validator;
+    #persistentObjectActionsRegistry;
+    #builtInActions = new Set(["New", "Delete", "SelectReference", "RefreshQuery", "Edit", "CancelEdit", "Save", "EndEdit"]);
+    constructor() {
+        super();
+        this.#validator = new BusinessRuleValidator();
+        this.#persistentObjectActionsRegistry = new VirtualPersistentObjectActionsRegistry();
+        this.#queryRegistry = new VirtualQueryRegistry(this.#persistentObjectActionsRegistry);
+        this.#persistentObjectRegistry = new VirtualPersistentObjectRegistry(this.#validator, this.#actionHandlers, this.#queryRegistry, this.#persistentObjectActionsRegistry);
+        // Register default action definitions (these are built-in actions without custom handlers)
+        this.#actionDefinitions.set("AddReference", { name: "AddReference", displayName: "Add", isPinned: false });
+        this.#actionDefinitions.set("BulkEdit", { name: "BulkEdit", displayName: "Edit", isPinned: false });
+        this.#actionDefinitions.set("CancelEdit", { name: "CancelEdit", displayName: "Cancel", isPinned: false });
+        this.#actionDefinitions.set("CancelSave", { name: "CancelSave", displayName: "Cancel", isPinned: false });
+        this.#actionDefinitions.set("Delete", { name: "Delete", displayName: "Delete", isPinned: false });
+        this.#actionDefinitions.set("Edit", { name: "Edit", displayName: "Edit", isPinned: false });
+        this.#actionDefinitions.set("EndEdit", { name: "EndEdit", displayName: "Save", isPinned: false });
+        this.#actionDefinitions.set("Filter", { name: "Filter", displayName: "", isPinned: false });
+        this.#actionDefinitions.set("New", { name: "New", displayName: "New", isPinned: false });
+        this.#actionDefinitions.set("RefreshQuery", { name: "RefreshQuery", displayName: "", isPinned: false });
+        this.#actionDefinitions.set("Remove", { name: "Remove", displayName: "Remove", isPinned: false });
+        this.#actionDefinitions.set("Save", { name: "Save", displayName: "Save", isPinned: false });
+        this.#actionDefinitions.set("SelectReference", { name: "SelectReference", displayName: "Select", isPinned: false });
+    }
+    /**
+     * Intercepts fetch requests and routes them to virtual handlers
+     */
+    async onFetch(request) {
+        const url = new URL(request.url);
+        const pathname = url.pathname;
+        const method = pathname.includes("GetClientData") ? "GetClientData" : pathname.split('/').pop();
+        const body = request.method === "POST" ? await request.clone().json() : null;
+        let result;
+        try {
+            // Route to appropriate handler based on service method
+            switch (method) {
+                case "GetClientData":
+                    result = this.#handleGetClientData();
+                    break;
+                case "GetApplication":
+                    result = this.#handleGetApplication();
+                    break;
+                case "GetQuery":
+                    result = await this.#handleGetQuery(body);
+                    break;
+                case "ExecuteQuery":
+                    result = await this.#handleExecuteQuery(body);
+                    break;
+                case "GetPersistentObject":
+                    result = await this.#handleGetPersistentObject(body);
+                    break;
+                case "ExecuteAction":
+                    result = await this.#handleExecuteAction(body);
+                    break;
+                default:
+                    throw new Error(`Virtual handler not implemented for method: ${method}`);
+            }
+            return new Response(JSON.stringify(result), {
+                headers: { "content-type": "application/json" }
+            });
+        }
+        catch (error) {
+            const errorResponse = {
+                exception: error instanceof Error ? error.message : String(error)
+            };
+            // Return 200 OK with exception in JSON body (like real service does)
+            return new Response(JSON.stringify(errorResponse), {
+                status: 200,
+                headers: { "content-type": "application/json" }
+            });
+        }
+    }
+    /**
+     * Registers a PersistentObject configuration
+     */
+    registerPersistentObject(config) {
+        // Validate configuration
+        if (!config.type)
+            throw new Error("VirtualPersistentObjectConfig.type is required");
+        if (!config.attributes || config.attributes.length === 0)
+            throw new Error("VirtualPersistentObjectConfig.attributes must have at least one attribute");
+        // Validate that referenced actions are registered (skip built-in actions)
+        if (config.actions) {
+            config.actions.forEach(actionName => {
+                if (!this.#builtInActions.has(actionName) && !this.#actionHandlers.has(actionName))
+                    throw new Error(`Action "${actionName}" is not registered. Call registerAction first.`);
+            });
+        }
+        // Validate that referenced queries are registered
+        if (config.queries) {
+            config.queries.forEach(queryName => {
+                if (!this.#queryRegistry.hasQuery(queryName))
+                    throw new Error(`Query "${queryName}" is not registered. Call registerQuery first.`);
+            });
+        }
+        // Validate that lookup queries for reference attributes are registered
+        if (config.attributes) {
+            config.attributes.forEach(attr => {
+                if (attr.lookup) {
+                    if (!this.#queryRegistry.hasQuery(attr.lookup))
+                        throw new Error(`Lookup query "${attr.lookup}" for attribute "${attr.name}" is not registered. Call registerQuery first.`);
+                }
+            });
+        }
+        // Register with registry
+        this.#persistentObjectRegistry.register(config);
+    }
+    /**
+     * Registers a Query configuration
+     */
+    registerQuery(config) {
+        // Validate configuration
+        if (!config.name)
+            throw new Error("VirtualQueryConfig.name is required");
+        if (!config.persistentObject)
+            throw new Error("VirtualQueryConfig.persistentObject is required");
+        // Verify PersistentObject is already registered
+        const persistentObjectConfig = this.#persistentObjectRegistry.getConfig(config.persistentObject);
+        if (!persistentObjectConfig)
+            throw new Error(`PersistentObject type '${config.persistentObject}' must be registered before creating a query. Call registerPersistentObject first.`);
+        // Validate that referenced actions are registered (skip built-in actions)
+        if (config.actions) {
+            config.actions.forEach(actionName => {
+                if (!this.#builtInActions.has(actionName) && !this.#actionHandlers.has(actionName))
+                    throw new Error(`Action "${actionName}" is not registered. Call registerAction first.`);
+            });
+        }
+        if (config.itemActions) {
+            config.itemActions.forEach(actionName => {
+                if (!this.#builtInActions.has(actionName) && !this.#actionHandlers.has(actionName))
+                    throw new Error(`Action "${actionName}" is not registered. Call registerAction first.`);
+            });
+        }
+        // Register with query registry
+        this.#queryRegistry.register(config, persistentObjectConfig);
+    }
+    /**
+     * Registers a custom action that can be used on PersistentObjects and Queries
+     * @param config - The action configuration with handler
+     */
+    registerAction(config) {
+        // Validate configuration
+        if (!config.name)
+            throw new Error("ActionConfig.name is required");
+        if (!config.handler)
+            throw new Error("ActionConfig.handler is required");
+        // Register action definition
+        this.#actionDefinitions.set(config.name, {
+            name: config.name,
+            displayName: config.displayName || config.name,
+            isPinned: config.isPinned || false
+        });
+        // Register action handler
+        this.#actionHandlers.set(config.name, config.handler);
+    }
+    /**
+     * Registers a custom business rule for validation
+     * @param name - The rule name (cannot override built-in rules)
+     * @param validator - The validation function
+     */
+    registerBusinessRule(name, validator) {
+        this.#validator.registerCustomRule(name, validator);
+    }
+    /**
+     * Registers a VirtualPersistentObjectActions class for a specific type
+     * @param type - The PersistentObject type name
+     * @param ActionsClass - The VirtualPersistentObjectActions class constructor
+     */
+    registerPersistentObjectActions(type, ActionsClass) {
+        this.#persistentObjectActionsRegistry.register(type, ActionsClass);
+    }
+    /**
+     * Handles GetClientData requests
+     */
+    #handleGetClientData() {
+        return {
+            defaultUser: "VirtualUser",
+            exception: null,
+            languages: {
+                "en": {
+                    name: "English",
+                    isDefault: true,
+                    messages: {
+                        "OK": "OK",
+                        "Cancel": "Cancel",
+                        "Save": "Save"
+                    }
+                }
+            },
+            providers: {
+                "Vidyano": {
+                    parameters: {
+                        label: "Vidyano",
+                        description: "Vidyano Provider",
+                        requestUri: null,
+                        signOutUri: null
+                    }
+                }
+            },
+            windowsAuthentication: false
+        };
+    }
+    /**
+     * Handles GetApplication requests
+     */
+    #handleGetApplication() {
+        // Build action definition items
+        const actionItems = Array.from(this.#actionDefinitions.values()).map(action => ({
+            id: crypto.randomUUID(),
+            values: [
+                { key: "Name", value: action.name },
+                { key: "DisplayName", value: action.displayName },
+                { key: "IsPinned", value: String(action.isPinned) }
+            ]
+        }));
+        // Create a minimal application PersistentObject with required attributes
+        const appPo = {
+            id: crypto.randomUUID(),
+            objectId: "Application",
+            type: "Application",
+            fullTypeName: "Vidyano.Application",
+            label: "Virtual Application",
+            isNew: false,
+            isReadOnly: true,
+            stateBehavior: "StayInEdit",
+            attributes: [
+                { name: "UserId", type: "String", value: "VirtualUserId", id: crypto.randomUUID(), offset: 0, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "FriendlyUserName", type: "String", value: "Virtual User", id: crypto.randomUUID(), offset: 1, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "FeedbackId", type: "String", value: null, id: crypto.randomUUID(), offset: 2, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "UserSettingsId", type: "String", value: null, id: crypto.randomUUID(), offset: 3, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "GlobalSearchId", type: "String", value: null, id: crypto.randomUUID(), offset: 4, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "AnalyticsKey", type: "String", value: null, id: crypto.randomUUID(), offset: 5, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "Routes", type: "String", value: JSON.stringify({ programUnits: {}, persistentObjects: {}, queries: {}, persistentObjectKeys: [], queryKeys: [] }), id: crypto.randomUUID(), offset: 6, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "UserSettings", type: "String", value: "{}", id: crypto.randomUUID(), offset: 7, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "CanProfile", type: "Boolean", value: "False", id: crypto.randomUUID(), offset: 8, label: "", visibility: "Always", toolTip: "", group: "", tab: "" },
+                { name: "ProgramUnits", type: "String", value: JSON.stringify({ hasManagement: false, units: [] }), id: crypto.randomUUID(), offset: 9, label: "", visibility: "Always", toolTip: "", group: "", tab: "" }
+            ],
+            actions: [],
+            tabs: {},
+            queries: [
+                // Empty Resources query
+                {
+                    id: crypto.randomUUID(),
+                    name: "Resources",
+                    label: "Resources",
+                    columns: [],
+                    persistentObject: {
+                        type: "Resource",
+                        id: crypto.randomUUID(),
+                        objectId: null,
+                        label: "Resource",
+                        isReadOnly: true,
+                        attributes: [],
+                        actions: [],
+                        tabs: {},
+                        queries: [],
+                        fullTypeName: "Vidyano.Resource"
+                    },
+                    result: {
+                        charts: [],
+                        columns: [],
+                        items: [],
+                        sortOptions: ""
+                    }
+                },
+                // Actions query with registered actions
+                {
+                    id: crypto.randomUUID(),
+                    name: "Actions",
+                    label: "Actions",
+                    columns: [
+                        { id: "Name", name: "Name", label: "Name", type: "String", offset: 0, canFilter: false, canGroupBy: false, canListDistincts: false, canSort: false, isHidden: false, includes: [], excludes: [] },
+                        { id: "DisplayName", name: "DisplayName", label: "Display Name", type: "String", offset: 1, canFilter: false, canGroupBy: false, canListDistincts: false, canSort: false, isHidden: false, includes: [], excludes: [] },
+                        { id: "IsPinned", name: "IsPinned", label: "Is Pinned", type: "Boolean", offset: 2, canFilter: false, canGroupBy: false, canListDistincts: false, canSort: false, isHidden: false, includes: [], excludes: [] }
+                    ],
+                    persistentObject: {
+                        type: "ActionDefinition",
+                        id: crypto.randomUUID(),
+                        objectId: null,
+                        label: "Action Definition",
+                        isReadOnly: true,
+                        attributes: [],
+                        actions: [],
+                        tabs: {},
+                        queries: [],
+                        fullTypeName: "Vidyano.ActionDefinition"
+                    },
+                    result: {
+                        charts: [],
+                        columns: [
+                            { id: "Name", name: "Name", label: "Name", type: "String", offset: 0, canFilter: false, canGroupBy: false, canListDistincts: false, canSort: false, isHidden: false, includes: [], excludes: [] },
+                            { id: "DisplayName", name: "DisplayName", label: "Display Name", type: "String", offset: 1, canFilter: false, canGroupBy: false, canListDistincts: false, canSort: false, isHidden: false, includes: [], excludes: [] },
+                            { id: "IsPinned", name: "IsPinned", label: "Is Pinned", type: "Boolean", offset: 2, canFilter: false, canGroupBy: false, canListDistincts: false, canSort: false, isHidden: false, includes: [], excludes: [] }
+                        ],
+                        items: actionItems,
+                        sortOptions: ""
+                    }
+                }
+            ]
+        };
+        return {
+            application: appPo,
+            userCultureInfo: "en-US",
+            userLanguage: "en",
+            userName: "VirtualUser",
+            hasSensitive: false
+        };
+    }
+    /**
+     * Handles GetQuery requests
+     */
+    async #handleGetQuery(request) {
+        const queryName = request.id;
+        const queryDto = await this.#queryRegistry.getQuery(queryName);
+        return {
+            query: queryDto
+        };
+    }
+    /**
+     * Handles ExecuteQuery requests
+     */
+    async #handleExecuteQuery(request) {
+        const query = request.query;
+        const result = await this.#queryRegistry.executeQuery(query, request.parent || null);
+        return {
+            result
+        };
+    }
+    /**
+     * Handles GetPersistentObject requests
+     */
+    async #handleGetPersistentObject(request) {
+        const type = request.persistentObjectTypeId;
+        const objectId = request.objectId || crypto.randomUUID();
+        const isNew = request.isNew || false;
+        const parent = request.parent || null;
+        const po = await this.#persistentObjectRegistry.getPersistentObject(type, objectId, isNew, parent);
+        return {
+            result: po
+        };
+    }
+    /**
+     * Handles ExecuteAction requests
+     */
+    async #handleExecuteAction(request) {
+        const actionName = request.action.split(".").pop();
+        // Check if this is a query action
+        const queryActionRequest = request;
+        if (queryActionRequest.query) {
+            // Query action - can have parent or not
+            const queryDto = await this.#queryRegistry.getQuery(queryActionRequest.query.name);
+            return await this.#executeQueryAction(request, queryDto, actionName);
+        }
+        // PersistentObject action - must have parent
+        return await this.#persistentObjectRegistry.executeAction(request);
+    }
+    /**
+     * Executes an action from a query context
+     */
+    async #executeQueryAction(request, query, actionName) {
+        // Note: query.persistentObject is the TEMPLATE/SCHEMA, not the parent!
+        const parent = request.parent;
+        // Handle built-in New action
+        if (actionName === "New") {
+            const type = query.persistentObject?.type;
+            if (!type)
+                throw new Error("Query does not have a persistentObject type");
+            // Create a new PersistentObject with the full lifecycle
+            const newPo = await this.#persistentObjectRegistry.createNewPersistentObject(type, parent, query, request.parameters || null);
+            return {
+                result: newPo
+            };
+        }
+        // Handle built-in SelectReference action
+        if (actionName === "SelectReference") {
+            if (!parent)
+                throw new Error("SelectReference requires a parent PersistentObject");
+            const attributeId = request.parameters?.PersistentObjectAttributeId;
+            if (!attributeId)
+                throw new Error("SelectReference requires PersistentObjectAttributeId parameter");
+            // Find the reference attribute
+            const refAttr = parent.attributes?.find(a => a.id === attributeId);
+            if (!refAttr)
+                throw new Error(`Attribute with id "${attributeId}" not found`);
+            // Get selected items from the request
+            const queryActionRequest = request;
+            const selectedItems = queryActionRequest.selectedItems || [];
+            const selectedItem = selectedItems.length > 0 ? selectedItems[0] : null;
+            // Call onSelectReference - base implementation sets objectId/value
+            const conversionContext = this.#createConversionContext();
+            await this.#persistentObjectActionsRegistry.executeSelectReference(parent, refAttr, query, selectedItem, conversionContext);
+            return {
+                result: parent
+            };
+        }
+        // Handle built-in Delete action
+        if (actionName === "Delete") {
+            const type = query.persistentObject?.type;
+            if (!type)
+                throw new Error("Query does not have a persistentObject type");
+            // Get selected items from the request
+            const queryActionRequest = request;
+            const selectedItems = queryActionRequest.selectedItems || [];
+            if (selectedItems.length === 0)
+                throw new Error("Delete requires at least one selected item");
+            // Call onDelete lifecycle hook
+            await this.#persistentObjectActionsRegistry.executeDelete(parent || null, query, selectedItems);
+            // Return parent or empty result
+            return {
+                result: parent || null
+            };
+        }
+        // Get action handler
+        const handler = this.#actionHandlers.get(actionName);
+        if (!handler)
+            throw new Error(`Action "${actionName}" is not registered`);
+        // Create action context - use parent if provided, otherwise fall back to query's template PO
+        const contextPo = parent || query.persistentObject;
+        const context = this.#createActionContext(contextPo);
+        // Build unified action args
+        const queryActionRequest = request;
+        const args = {
+            parent: parent ?? null,
+            query: query,
+            selectedItems: queryActionRequest.selectedItems,
+            parameters: request.parameters,
+            context: context
+        };
+        // Execute handler
+        const result = await handler(args);
+        // Handle result - use parent if available, otherwise use template
+        const finalResult = this.#normalizeActionResult(result, contextPo);
+        return {
+            result: finalResult
+        };
+    }
+    /**
+     * Creates an action context for attribute manipulation
+     */
+    #createActionContext(po) {
+        return {
+            getAttribute: (name) => {
+                return po.attributes?.find(a => a.name === name);
+            },
+            getAttributeValue: (name) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (!attr)
+                    return undefined;
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setAttributeValue: (name, value) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (attr) {
+                    attr.value = toServiceValue(value, attr.type);
+                    attr.isValueChanged = true;
+                }
+            },
+            getConvertedValue: (attr) => {
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setConvertedValue: (attr, value) => {
+                attr.value = toServiceValue(value, attr.type);
+                attr.isValueChanged = true;
+            },
+            setValidationError: (name, error) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (attr)
+                    attr.validationError = error;
+            },
+            clearValidationError: (name) => {
+                const attr = po.attributes?.find(a => a.name === name);
+                if (attr)
+                    attr.validationError = undefined;
+            },
+            setNotification: (message, type, duration) => {
+                po.notification = message;
+                po.notificationType = type;
+                po.notificationDuration = duration;
+            }
+        };
+    }
+    /**
+     * Creates a conversion context for type conversions
+     */
+    #createConversionContext() {
+        return {
+            getConvertedValue: (attr) => {
+                return fromServiceValue(attr.value, attr.type);
+            },
+            setConvertedValue: (attr, value) => {
+                attr.value = toServiceValue(value, attr.type);
+                attr.isValueChanged = true;
+            }
+        };
+    }
+    /**
+     * Normalizes action result (handles both old and new API formats)
+     */
+    #normalizeActionResult(result, defaultParent) {
+        // Handle both old and new API formats for backwards compatibility
+        // Old API: handler returns { result: PersistentObjectDto }
+        // New API: handler returns PersistentObjectDto | null
+        if (result && typeof result === "object" && "result" in result) {
+            // Old API format - extract the result property
+            return result.result || defaultParent;
+        }
+        // New API format - use directly
+        return result || defaultParent;
+    }
+}
+
+/**
+ * A virtual service for testing without a backend.
+ *
+ * Register PersistentObjects, Queries, Actions, and BusinessRules before calling initialize().
+ * Once initialize() is called, no more registrations are allowed.
+ *
+ * @example
+ * ```typescript
+ * const service = new VirtualService();
+ * service.registerPersistentObject({ type: "Person", attributes: [...] });
+ * service.registerQuery({ name: "AllPersons", persistentObject: "Person" });
+ * await service.initialize();
+ *
+ * // Now use the service
+ * const query = await service.getQuery("AllPersons");
+ * ```
+ */
+class VirtualService extends Service {
+    #isInitialized = false;
+    /**
+     * Creates a new VirtualService instance.
+     * @param hooks - Optional custom VirtualServiceHooks. If not provided, a default instance is created.
+     */
+    constructor(hooks) {
+        super("http://virtual.local", hooks ?? new VirtualServiceHooks(), true);
+    }
+    /**
+     * Gets the VirtualServiceHooks instance.
+     */
+    get virtualHooks() {
+        return this.hooks;
+    }
+    async initialize(arg) {
+        this.#isInitialized = true;
+        return super.initialize(arg);
+    }
+    /**
+     * Registers a PersistentObject configuration.
+     * Must be called before initialize().
+     * @param config - The PersistentObject configuration.
+     * @throws Error if called after initialize().
+     */
+    registerPersistentObject(config) {
+        this.#ensureNotInitialized();
+        this.virtualHooks.registerPersistentObject(config);
+    }
+    /**
+     * Registers a Query configuration.
+     * Must be called before initialize().
+     * @param config - The Query configuration.
+     * @throws Error if called after initialize().
+     */
+    registerQuery(config) {
+        this.#ensureNotInitialized();
+        this.virtualHooks.registerQuery(config);
+    }
+    /**
+     * Registers a custom action that can be used on PersistentObjects and Queries.
+     * Must be called before initialize().
+     * @param config - The action configuration with handler.
+     * @throws Error if called after initialize().
+     */
+    registerAction(config) {
+        this.#ensureNotInitialized();
+        this.virtualHooks.registerAction(config);
+    }
+    /**
+     * Registers a custom business rule for validation.
+     * Must be called before initialize().
+     * @param name - The rule name (cannot override built-in rules).
+     * @param validator - The validation function.
+     * @throws Error if called after initialize().
+     */
+    registerBusinessRule(name, validator) {
+        this.#ensureNotInitialized();
+        this.virtualHooks.registerBusinessRule(name, validator);
+    }
+    /**
+     * Registers a VirtualPersistentObjectActions class for a specific type.
+     * Must be called before initialize().
+     * @param type - The PersistentObject type name.
+     * @param ActionsClass - The VirtualPersistentObjectActions class constructor.
+     * @throws Error if called after initialize().
+     */
+    registerPersistentObjectActions(type, ActionsClass) {
+        this.#ensureNotInitialized();
+        this.virtualHooks.registerPersistentObjectActions(type, ActionsClass);
+    }
+    /**
+     * Throws an error if the service has already been initialized.
+     */
+    #ensureNotInitialized() {
+        if (this.#isInitialized)
+            throw new Error("Cannot register after initialize() has been called");
+    }
+}
+
+export { VirtualPersistentObjectActions, VirtualService, VirtualServiceHooks };