@vidyano-labs/virtual-service 0.1.0

package/index.d.ts

@@ -0,0 +1,559 @@
+import { Dto, ServiceHooks, Service, Application } from '@vidyano/core';
+
+/**
+ * Simplified attribute configuration - converted to PersistentObjectAttributeDto
+ */
+type VirtualPersistentObjectAttributeConfig = {
+    /**
+     * Optional fixed id for this attribute. If not provided, a random UUID is generated.
+     */
+    id?: string;
+    /**
+     * The unique name of the attribute.
+     */
+    name: string;
+    /**
+     * The type of the data. Defaults to "String".
+     */
+    type?: string;
+    /**
+     * The label of the attribute. Defaults to name.
+     */
+    label?: string;
+    /**
+     * 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.
+     */
+    isReadOnly?: boolean;
+    /**
+     * A semicolon separated list of business rules that should be checked when saving this attribute.
+     * @example "NotEmpty; MaxLength(40)"
+     */
+    rules?: string;
+    /**
+     * The visibility of this attribute.
+     */
+    visibility?: Dto.PersistentObjectAttributeVisibility;
+    /**
+     * The name of the group to which this attribute belongs. Defaults to "".
+     */
+    group?: string;
+    /**
+     * The name of the tab to which this attribute belongs. Defaults to "".
+     */
+    tab?: string;
+    /**
+     * Gets whether the persistent object is refreshed when this attribute is changed. Defaults to false.
+     */
+    triggersRefresh?: boolean;
+    /**
+     * A list of predefined options to choose the attribute value from.
+     */
+    options?: string[];
+    /**
+     * Type hints for this attribute.
+     */
+    typeHints?: Record<string, string>;
+    /**
+     * The column that should be used when displaying this attribute.
+     */
+    column?: number;
+    /**
+     * The column span that should be used when displaying this attribute. Defaults to 4.
+     */
+    columnSpan?: number;
+    /**
+     * The position of this attribute when displayed.
+     */
+    offset?: number;
+    /**
+     * Indicates whether this attribute can be used to sort the query. Defaults to true for most types.
+     */
+    canSort?: boolean;
+    /**
+     * For Reference attributes: the name of the registered query to use as a lookup.
+     */
+    lookup?: string;
+    /**
+     * For Reference attributes: the attribute name to use for displaying the reference value. Defaults to the first attribute.
+     */
+    displayAttribute?: string;
+    /**
+     * For Reference attributes: whether the user can add a new reference. Defaults to false.
+     */
+    canAddNewReference?: boolean;
+    /**
+     * For Reference attributes: whether to use a fixed list of possible references. Defaults to false.
+     */
+    selectInPlace?: boolean;
+};
+/**
+ * Unified action handler arguments (matches C# CustomAction pattern)
+ */
+type ActionArgs = {
+    /**
+     * The parent PersistentObject (like args.Parent in C#)
+     * For PersistentObject actions: the PersistentObject itself
+     * For Query actions: the parent PO that owns the query, or null for top-level queries
+     */
+    parent: Dto.PersistentObjectDto | null;
+    /**
+     * The query context (like args.Query in C#) - present if action invoked from query
+     */
+    query?: Dto.QueryDto;
+    /**
+     * Selected items (like args.SelectedItems in C#) - present if query action with selections
+     */
+    selectedItems?: Dto.QueryResultItemDto[];
+    /**
+     * Additional parameters (like args.Parameters in C#)
+     */
+    parameters?: Record<string, any>;
+    /**
+     * Helper context for modifying attributes and setting notifications
+     */
+    context: ActionContext;
+};
+/**
+ * Unified action handler (matches C# CustomAction Execute signature)
+ * Return the PersistentObject to refresh UI, or null to complete silently
+ */
+type ActionHandler = (args: ActionArgs) => Promise<Dto.PersistentObjectDto | null> | Dto.PersistentObjectDto | null;
+/**
+ * Action configuration
+ */
+type ActionConfig = {
+    /**
+     * The name of the action.
+     */
+    name: string;
+    /**
+     * The display name for the action. Defaults to name.
+     */
+    displayName?: string;
+    /**
+     * Indicates whether the action is pinned. Defaults to false.
+     */
+    isPinned?: boolean;
+    /**
+     * Custom action logic handler.
+     */
+    handler: ActionHandler;
+};
+/**
+ * Context provides safe API to modify the persistent object during actions
+ */
+type ActionContext = {
+    /**
+     * Gets an attribute by name.
+     */
+    getAttribute: (name: string) => Dto.PersistentObjectAttributeDto | undefined;
+    /**
+     * Gets the value of an attribute by name.
+     */
+    getAttributeValue: (name: string) => any;
+    /**
+     * Sets the value of an attribute by name.
+     */
+    setAttributeValue: (name: string, value: any) => void;
+    /**
+     * Gets the converted value of an attribute DTO (e.g., Boolean as boolean, Int32 as number).
+     */
+    getConvertedValue: (attr: Dto.PersistentObjectAttributeDto) => any;
+    /**
+     * Sets the value on an attribute DTO with automatic type conversion.
+     */
+    setConvertedValue: (attr: Dto.PersistentObjectAttributeDto, value: any) => void;
+    /**
+     * Sets a validation error for an attribute.
+     */
+    setValidationError: (name: string, error: string) => void;
+    /**
+     * Clears the validation error for an attribute.
+     */
+    clearValidationError: (name: string) => void;
+    /**
+     * Sets a notification message.
+     */
+    setNotification: (message: string, type: Dto.NotificationType, duration?: number) => void;
+};
+/**
+ * PersistentObject configuration - converted to PersistentObjectDto
+ */
+type VirtualPersistentObjectConfig = {
+    /**
+     * The type of the persistent object.
+     */
+    type: string;
+    /**
+     * For singleton objects, the id.
+     */
+    id?: string;
+    /**
+     * The attributes of this persistent object.
+     */
+    attributes: VirtualPersistentObjectAttributeConfig[];
+    /**
+     * The actions allowed for this persistent object (reference by name).
+     */
+    actions?: string[];
+    /**
+     * Query names to attach as detail queries (reference by name).
+     */
+    queries?: string[];
+    /**
+     * The tab information for the persistent object.
+     */
+    tabs?: Record<string, Partial<Dto.PersistentObjectTabDto>>;
+    /**
+     * A set of extra options that influence the state of the persistent object.
+     */
+    stateBehavior?: Dto.PersistentObjectStateBehavior;
+    /**
+     * The label of the persistent object.
+     */
+    label?: string;
+};
+/**
+ * Result returned from onExecuteQuery
+ */
+type VirtualQueryExecuteResult = {
+    /**
+     * The items to display (already filtered, sorted, and paginated by your implementation)
+     */
+    items: Record<string, any>[];
+    /**
+     * Total number of items matching the query (before pagination)
+     */
+    totalItems: number;
+};
+/**
+ * Query configuration - converted to QueryDto
+ */
+type VirtualQueryConfig = {
+    /**
+     * Query name (e.g., "People")
+     */
+    name: string;
+    /**
+     * Display label (defaults to name)
+     */
+    label?: string;
+    /**
+     * Type name of already-registered PersistentObject (REQUIRED)
+     * MUST reference an already-registered PersistentObject by type name
+     */
+    persistentObject: string;
+    /**
+     * Default data for the query. When executeQuery is not overridden in the
+     * VirtualPersistentObjectActions class, this data will be used.
+     * Text search, sorting, and pagination are applied automatically.
+     */
+    data?: Record<string, any>[];
+    /**
+     * Query-level actions (reference by name, e.g., "New", "Export")
+     */
+    actions?: string[];
+    /**
+     * Item-level actions (reference by name, e.g., "Edit", "Delete")
+     */
+    itemActions?: string[];
+    /**
+     * Enable text search (default: true)
+     */
+    allowTextSearch?: boolean;
+    /**
+     * Disable bulk edit (default: false)
+     */
+    disableBulkEdit?: boolean;
+    /**
+     * Auto-execute on load (default: true). If false, getQuery returns empty result
+     */
+    autoQuery?: boolean;
+    /**
+     * Page size (default: 20)
+     */
+    pageSize?: number;
+};
+
+/**
+ * Rule validator function that throws an error if invalid, or returns nothing if valid
+ */
+type RuleValidatorFn = (value: any, ...params: any[]) => void;
+
+/**
+ * VirtualPersistentObjectAttribute combines a PersistentObjectAttributeDto with helper methods
+ * This allows clean syntax like attr.getValue() and attr.setValue() while keeping the underlying DTO unchanged
+ */
+type VirtualPersistentObjectAttribute = Dto.PersistentObjectAttributeDto & {
+    /**
+     * Gets the converted value of this attribute (e.g., Boolean as boolean, Int32 as number)
+     */
+    getValue(): any;
+    /**
+     * Sets the value of this attribute with automatic type conversion
+     */
+    setValue(value: any): void;
+    /**
+     * Sets a validation error on this attribute
+     */
+    setValidationError(error: string): void;
+    /**
+     * Clears the validation error on this attribute
+     */
+    clearValidationError(): void;
+};
+/**
+ * VirtualPersistentObject combines a PersistentObjectDto with helper methods
+ * This allows clean syntax like obj.setAttributeValue() while keeping the underlying DTO unchanged
+ */
+type VirtualPersistentObject = Dto.PersistentObjectDto & {
+    /**
+     * Gets an attribute by name, wrapped with getValue/setValue methods
+     */
+    getAttribute(name: string): VirtualPersistentObjectAttribute | undefined;
+    /**
+     * Gets the value of an attribute by name
+     */
+    getAttributeValue(name: string): any;
+    /**
+     * Sets the value of an attribute by name
+     */
+    setAttributeValue(name: string, value: any): void;
+    /**
+     * Sets a validation error for an attribute
+     */
+    setValidationError(name: string, error: string): void;
+    /**
+     * Clears a validation error for an attribute
+     */
+    clearValidationError(name: string): void;
+    /**
+     * Sets a notification message on the persistent object
+     */
+    setNotification(message: string, type: Dto.NotificationType, duration?: number): void;
+};
+
+/**
+ * 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.
+ */
+declare 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: VirtualPersistentObject): void;
+    /**
+     * 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
+     */
+    onLoad(obj: VirtualPersistentObject, parent: VirtualPersistentObject | null): Promise<VirtualPersistentObject>;
+    /**
+     * 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
+     */
+    onNew(obj: VirtualPersistentObject, parent: VirtualPersistentObject | null, query: Dto.QueryDto | null, parameters: Record<string, string> | null): Promise<VirtualPersistentObject>;
+    /**
+     * 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
+     */
+    onRefresh(obj: VirtualPersistentObject, attribute: VirtualPersistentObjectAttribute | undefined): Promise<VirtualPersistentObject>;
+    /**
+     * 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
+     */
+    onSave(obj: VirtualPersistentObject): Promise<VirtualPersistentObject>;
+    /**
+     * 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
+     */
+    protected saveNew(obj: VirtualPersistentObject): Promise<VirtualPersistentObject>;
+    /**
+     * 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
+     */
+    protected saveExisting(obj: VirtualPersistentObject): Promise<VirtualPersistentObject>;
+    /**
+     * 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
+     */
+    onSelectReference(_parent: VirtualPersistentObject, referenceAttribute: Dto.PersistentObjectAttributeDto, _query: Dto.QueryDto, selectedItem: Dto.QueryResultItemDto | null): Promise<void>;
+    /**
+     * 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
+     */
+    onDelete(parent: VirtualPersistentObject | null, query: Dto.QueryDto, selectedItems: Dto.QueryResultItemDto[]): Promise<void>;
+    /**
+     * 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: Dto.QueryDto, parent: VirtualPersistentObject | null): void;
+    /**
+     * 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
+     */
+    onExecuteQuery(query: Dto.QueryDto, parent: VirtualPersistentObject | null, data: Record<string, any>[]): Promise<VirtualQueryExecuteResult>;
+    /**
+     * 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)
+     */
+    getEntities(_query: Dto.QueryDto, _parent: VirtualPersistentObject | null, data: Record<string, any>[]): Promise<Record<string, any>[]>;
+}
+
+/**
+ * Virtual implementation of ServiceHooks for testing without a backend
+ */
+declare class VirtualServiceHooks extends ServiceHooks {
+    #private;
+    constructor();
+    /**
+     * Intercepts fetch requests and routes them to virtual handlers
+     */
+    onFetch(request: Request): Promise<Response>;
+    /**
+     * Registers a PersistentObject configuration
+     */
+    registerPersistentObject(config: VirtualPersistentObjectConfig): void;
+    /**
+     * Registers a Query configuration
+     */
+    registerQuery(config: VirtualQueryConfig): void;
+    /**
+     * Registers a custom action that can be used on PersistentObjects and Queries
+     * @param config - The action configuration with handler
+     */
+    registerAction(config: ActionConfig): void;
+    /**
+     * Registers a custom business rule for validation
+     * @param name - The rule name (cannot override built-in rules)
+     * @param validator - The validation function
+     */
+    registerBusinessRule(name: string, validator: RuleValidatorFn): void;
+    /**
+     * Registers a VirtualPersistentObjectActions class for a specific type
+     * @param type - The PersistentObject type name
+     * @param ActionsClass - The VirtualPersistentObjectActions class constructor
+     */
+    registerPersistentObjectActions(type: string, ActionsClass: typeof VirtualPersistentObjectActions): void;
+}
+
+/**
+ * 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");
+ * ```
+ */
+declare class VirtualService extends Service {
+    #private;
+    /**
+     * Creates a new VirtualService instance.
+     * @param hooks - Optional custom VirtualServiceHooks. If not provided, a default instance is created.
+     */
+    constructor(hooks?: VirtualServiceHooks);
+    /**
+     * Gets the VirtualServiceHooks instance.
+     */
+    get virtualHooks(): VirtualServiceHooks;
+    /**
+     * Initializes the service and finalizes all registrations.
+     * After this method is called, no more registrations are allowed.
+     */
+    initialize(skipDefaultCredentialLogin?: boolean): Promise<Application>;
+    initialize(oneTimeSignInToken: string): Promise<Application>;
+    /**
+     * Registers a PersistentObject configuration.
+     * Must be called before initialize().
+     * @param config - The PersistentObject configuration.
+     * @throws Error if called after initialize().
+     */
+    registerPersistentObject(config: VirtualPersistentObjectConfig): void;
+    /**
+     * Registers a Query configuration.
+     * Must be called before initialize().
+     * @param config - The Query configuration.
+     * @throws Error if called after initialize().
+     */
+    registerQuery(config: VirtualQueryConfig): void;
+    /**
+     * 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: ActionConfig): void;
+    /**
+     * 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: string, validator: RuleValidatorFn): void;
+    /**
+     * 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: string, ActionsClass: typeof VirtualPersistentObjectActions): void;
+}
+
+export { VirtualPersistentObjectActions, VirtualService, VirtualServiceHooks };
+export type { ActionArgs, ActionConfig, ActionContext, ActionHandler, RuleValidatorFn, VirtualPersistentObject, VirtualPersistentObjectAttribute, VirtualPersistentObjectAttributeConfig, VirtualPersistentObjectConfig, VirtualQueryConfig, VirtualQueryExecuteResult };