@stonecrop/stonecrop 0.12.7 → 0.13.0

package/dist/field-triggers.js

@@ -0,0 +1,575 @@
+import { useOperationLogStore } from './stores/operation-log';
+/**
+ * Field trigger execution engine integrated with Registry
+ * Singleton pattern following Registry implementation
+ * @public
+ */
+export class FieldTriggerEngine {
+    /**
+     * The root FieldTriggerEngine instance
+     */
+    static _root;
+    options;
+    doctypeActions = new Map(); // doctype -> action/field -> functions
+    doctypeTransitions = new Map(); // doctype -> transition -> functions
+    fieldRollbackConfig = new Map(); // doctype -> field -> rollback enabled
+    globalActions = new Map(); // action name -> function
+    globalTransitionActions = new Map(); // transition action name -> function
+    /**
+     * Creates a new FieldTriggerEngine instance (singleton pattern)
+     * @param options - Configuration options for the field trigger engine
+     */
+    constructor(options = {}) {
+        if (FieldTriggerEngine._root) {
+            return FieldTriggerEngine._root;
+        }
+        FieldTriggerEngine._root = this;
+        this.options = {
+            defaultTimeout: options.defaultTimeout ?? 5000,
+            debug: options.debug ?? false,
+            enableRollback: options.enableRollback ?? true,
+            errorHandler: options.errorHandler,
+        };
+    }
+    /**
+     * Register a global action function
+     * @param name - The name of the action
+     * @param fn - The action function
+     */
+    registerAction(name, fn) {
+        this.globalActions.set(name, fn);
+    }
+    /**
+     * Look up a registered action function by name.
+     * Returns `undefined` if the action has not been registered.
+     * @param name - The action name
+     */
+    getAction(name) {
+        return this.globalActions.get(name);
+    }
+    /**
+     * Register a global XState transition action function
+     * @param name - The name of the transition action
+     * @param fn - The transition action function
+     */
+    registerTransitionAction(name, fn) {
+        this.globalTransitionActions.set(name, fn);
+    }
+    /**
+     * Configure rollback behavior for a specific field trigger
+     * @param doctype - The doctype name
+     * @param fieldname - The field name
+     * @param enableRollback - Whether to enable rollback
+     */
+    setFieldRollback(doctype, fieldname, enableRollback) {
+        if (!this.fieldRollbackConfig.has(doctype)) {
+            this.fieldRollbackConfig.set(doctype, new Map());
+        }
+        this.fieldRollbackConfig.get(doctype).set(fieldname, enableRollback);
+    }
+    /**
+     * Get rollback configuration for a specific field trigger
+     */
+    getFieldRollback(doctype, fieldname) {
+        return this.fieldRollbackConfig.get(doctype)?.get(fieldname);
+    }
+    /**
+     * Register actions from a doctype - both regular actions and field triggers
+     * Separates XState transitions (uppercase) from field triggers (lowercase)
+     * @param doctype - The doctype name
+     * @param actions - The actions to register (supports Immutable Map, Map, or plain object)
+     */
+    registerDoctypeActions(doctype, actions) {
+        if (!actions)
+            return;
+        const actionMap = new Map();
+        const transitionMap = new Map();
+        // Convert from different Map types to regular Map
+        // Check for Immutable.js Map first (has entrySeq method)
+        const immutableActions = actions;
+        if (typeof immutableActions.entrySeq === 'function') {
+            // Immutable Map
+            immutableActions.entrySeq().forEach(([key, value]) => {
+                this.categorizeAction(key, value, actionMap, transitionMap);
+            });
+        }
+        else if (actions instanceof Map) {
+            // Regular Map
+            for (const [key, value] of actions) {
+                this.categorizeAction(key, value, actionMap, transitionMap);
+            }
+        }
+        else if (actions && typeof actions === 'object') {
+            // Plain object
+            Object.entries(actions).forEach(([key, value]) => {
+                this.categorizeAction(key, value, actionMap, transitionMap);
+            });
+        }
+        // Always set the maps, even if empty
+        this.doctypeActions.set(doctype, actionMap);
+        this.doctypeTransitions.set(doctype, transitionMap);
+    }
+    /**
+     * Categorize an action as either a field trigger or XState transition
+     * Uses uppercase convention: UPPERCASE = transition, lowercase/mixed = field trigger
+     */
+    categorizeAction(key, value, actionMap, transitionMap) {
+        // Check if the key is all uppercase (XState transition convention)
+        if (this.isTransitionKey(key)) {
+            transitionMap.set(key, value);
+        }
+        else {
+            actionMap.set(key, value);
+        }
+    }
+    /**
+     * Determine if a key represents an XState transition
+     * Transitions are identified by being all uppercase
+     */
+    isTransitionKey(key) {
+        // Must be all uppercase letters/numbers/underscores
+        return /^[A-Z0-9_]+$/.test(key) && key.length > 0;
+    }
+    /**
+     * Execute field triggers for a changed field
+     * @param context - The field change context
+     * @param options - Execution options (timeout and enableRollback)
+     */
+    async executeFieldTriggers(context, options = {}) {
+        const { doctype, fieldname } = context;
+        const triggers = this.findFieldTriggers(doctype, fieldname);
+        if (triggers.length === 0) {
+            return {
+                path: context.path,
+                actionResults: [],
+                totalExecutionTime: 0,
+                allSucceeded: true,
+                stoppedOnError: false,
+                rolledBack: false,
+            };
+        }
+        const startTime = performance.now();
+        const actionResults = [];
+        let stoppedOnError = false;
+        let rolledBack = false;
+        let snapshot = undefined;
+        // Determine if rollback is enabled (priority: execution option > field config > global setting)
+        const fieldRollbackConfig = this.getFieldRollback(doctype, fieldname);
+        const rollbackEnabled = options.enableRollback ?? fieldRollbackConfig ?? this.options.enableRollback;
+        // Capture snapshot before executing actions if rollback is enabled
+        if (rollbackEnabled && context.store) {
+            snapshot = this.captureSnapshot(context);
+        }
+        // Execute actions sequentially
+        for (const actionName of triggers) {
+            try {
+                const actionResult = await this.executeAction(actionName, context, options.timeout);
+                actionResults.push(actionResult);
+                if (!actionResult.success) {
+                    stoppedOnError = true;
+                    break;
+                }
+            }
+            catch (error) {
+                const actionError = error instanceof Error ? error : new Error(String(error));
+                const errorResult = {
+                    success: false,
+                    error: actionError,
+                    executionTime: 0,
+                    action: actionName,
+                };
+                actionResults.push(errorResult);
+                stoppedOnError = true;
+                break;
+            }
+        }
+        // Perform rollback if enabled, errors occurred, and we have a snapshot
+        if (rollbackEnabled && stoppedOnError && snapshot && context.store) {
+            try {
+                this.restoreSnapshot(context, snapshot);
+                rolledBack = true;
+            }
+            catch (rollbackError) {
+                // eslint-disable-next-line no-console
+                console.error('[FieldTriggers] Rollback failed:', rollbackError);
+            }
+        }
+        const totalExecutionTime = performance.now() - startTime;
+        // Call global error handler if configured and errors occurred
+        const failedResults = actionResults.filter(r => !r.success && r.error != null);
+        if (failedResults.length > 0 && this.options.errorHandler) {
+            for (const failedResult of failedResults) {
+                try {
+                    if (failedResult.error) {
+                        this.options.errorHandler(failedResult.error, context, failedResult.action);
+                    }
+                }
+                catch (handlerError) {
+                    // eslint-disable-next-line no-console
+                    console.error('[FieldTriggers] Error in global error handler:', handlerError);
+                }
+            }
+        }
+        const result = {
+            path: context.path,
+            actionResults,
+            totalExecutionTime,
+            allSucceeded: actionResults.every(r => r.success),
+            stoppedOnError,
+            rolledBack,
+            snapshot: this.options.debug && rollbackEnabled ? snapshot : undefined, // Only include snapshot in debug mode if rollback is enabled
+        };
+        return result;
+    }
+    /**
+     * Execute XState transition actions
+     * Similar to field triggers but specifically for FSM state transitions
+     * @param context - The transition change context
+     * @param options - Execution options (timeout)
+     */
+    async executeTransitionActions(context, options = {}) {
+        const { doctype, transition } = context;
+        const transitionActions = this.findTransitionActions(doctype, transition);
+        if (transitionActions.length === 0) {
+            return [];
+        }
+        const results = [];
+        // Execute transition actions sequentially
+        for (const actionName of transitionActions) {
+            try {
+                const actionResult = await this.executeTransitionAction(actionName, context, options.timeout);
+                results.push(actionResult);
+                if (!actionResult.success) {
+                    // Stop on first error for transitions
+                    break;
+                }
+            }
+            catch (error) {
+                const actionError = error instanceof Error ? error : new Error(String(error));
+                const errorResult = {
+                    success: false,
+                    error: actionError,
+                    executionTime: 0,
+                    action: actionName,
+                    transition,
+                };
+                results.push(errorResult);
+                break;
+            }
+        }
+        // Call global error handler if configured and errors occurred
+        const failedResults = results.filter(r => !r.success);
+        if (failedResults.length > 0 && this.options.errorHandler) {
+            for (const failedResult of failedResults) {
+                try {
+                    // Call with FieldChangeContext (base context type)
+                    if (failedResult.error) {
+                        this.options.errorHandler(failedResult.error, context, failedResult.action);
+                    }
+                }
+                catch (handlerError) {
+                    // eslint-disable-next-line no-console
+                    console.error('[FieldTriggers] Error in global error handler:', handlerError);
+                }
+            }
+        }
+        return results;
+    }
+    /**
+     * Find transition actions for a specific doctype and transition
+     */
+    findTransitionActions(doctype, transition) {
+        const doctypeTransitions = this.doctypeTransitions.get(doctype);
+        if (!doctypeTransitions)
+            return [];
+        return doctypeTransitions.get(transition) || [];
+    }
+    /**
+     * Execute a single transition action by name
+     */
+    async executeTransitionAction(actionName, context, timeout) {
+        const startTime = performance.now();
+        const actionTimeout = timeout ?? this.options.defaultTimeout;
+        try {
+            // Look up action in transition-specific registry first, then fall back to global
+            let actionFn = this.globalTransitionActions.get(actionName);
+            // If not found in transition registry, try regular action registry
+            // This allows sharing actions between field triggers and transitions
+            if (!actionFn) {
+                const regularActionFn = this.globalActions.get(actionName);
+                if (regularActionFn) {
+                    // Wrap regular action to accept TransitionChangeContext
+                    actionFn = regularActionFn;
+                }
+            }
+            if (!actionFn) {
+                throw new Error(`Transition action "${actionName}" not found in registry`);
+            }
+            await this.executeWithTimeout(actionFn, context, actionTimeout);
+            const executionTime = performance.now() - startTime;
+            return {
+                success: true,
+                executionTime,
+                action: actionName,
+                transition: context.transition,
+            };
+        }
+        catch (error) {
+            const executionTime = performance.now() - startTime;
+            const actionError = error instanceof Error ? error : new Error(String(error));
+            return {
+                success: false,
+                error: actionError,
+                executionTime,
+                action: actionName,
+                transition: context.transition,
+            };
+        }
+    }
+    /**
+     * Find field triggers for a specific doctype and field
+     * Field triggers are identified by keys that look like field paths (contain dots or match field names)
+     */
+    findFieldTriggers(doctype, fieldname) {
+        const doctypeActions = this.doctypeActions.get(doctype);
+        if (!doctypeActions)
+            return [];
+        const triggers = [];
+        for (const [key, actionNames] of doctypeActions) {
+            // Check if this key is a field trigger pattern
+            if (this.isFieldTriggerKey(key, fieldname)) {
+                triggers.push(...actionNames);
+            }
+        }
+        return triggers;
+    }
+    /**
+     * Determine if an action key represents a field trigger
+     * Field triggers can be:
+     * - Exact field name match: "emailAddress"
+     * - Wildcard patterns: "emailAddress.*", "*.is_primary"
+     * - Nested field paths: "address.street", "contact.email"
+     */
+    isFieldTriggerKey(key, fieldname) {
+        // Exact match
+        if (key === fieldname)
+            return true;
+        // Contains dots - likely a field path pattern
+        if (key.includes('.')) {
+            return this.matchFieldPattern(key, fieldname);
+        }
+        // Contains wildcards
+        if (key.includes('*')) {
+            return this.matchFieldPattern(key, fieldname);
+        }
+        return false;
+    }
+    /**
+     * Match a field pattern against a field name
+     * Supports wildcards (*) for dynamic segments
+     */
+    matchFieldPattern(pattern, fieldname) {
+        const patternParts = pattern.split('.');
+        const fieldParts = fieldname.split('.');
+        if (patternParts.length !== fieldParts.length) {
+            return false;
+        }
+        for (let i = 0; i < patternParts.length; i++) {
+            const patternPart = patternParts[i];
+            const fieldPart = fieldParts[i];
+            if (patternPart === '*') {
+                // Wildcard matches any segment
+                continue;
+            }
+            else if (patternPart !== fieldPart) {
+                // Exact match required
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Execute a single action by name
+     */
+    async executeAction(actionName, context, timeout) {
+        const startTime = performance.now();
+        const actionTimeout = timeout ?? this.options.defaultTimeout;
+        try {
+            // Look up action in global registry
+            const actionFn = this.globalActions.get(actionName);
+            if (!actionFn) {
+                throw new Error(`Action "${actionName}" not found in registry`);
+            }
+            await this.executeWithTimeout(actionFn, context, actionTimeout);
+            const executionTime = performance.now() - startTime;
+            return {
+                success: true,
+                executionTime,
+                action: actionName,
+            };
+        }
+        catch (error) {
+            const executionTime = performance.now() - startTime;
+            const actionError = error instanceof Error ? error : new Error(String(error));
+            return {
+                success: false,
+                error: actionError,
+                executionTime,
+                action: actionName,
+            };
+        }
+    }
+    /**
+     * Execute a function with timeout
+     */
+    async executeWithTimeout(fn, context, timeout) {
+        return new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                reject(new Error(`Action timeout after ${timeout}ms`));
+            }, timeout);
+            Promise.resolve(fn(context))
+                .then(result => {
+                clearTimeout(timeoutId);
+                resolve(result);
+            })
+                .catch(error => {
+                clearTimeout(timeoutId);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
+    /**
+     * Capture a snapshot of the record state before executing actions
+     * This creates a deep copy of the record data for potential rollback
+     */
+    captureSnapshot(context) {
+        if (!context.store || !context.doctype || !context.recordId) {
+            return undefined;
+        }
+        try {
+            // Get the record path (doctype.recordId)
+            const recordPath = `${context.doctype}.${context.recordId}`;
+            // Get the current record data
+            const recordData = context.store.get(recordPath);
+            if (!recordData || typeof recordData !== 'object') {
+                return undefined;
+            }
+            // Create a deep copy to avoid reference issues
+            return JSON.parse(JSON.stringify(recordData));
+        }
+        catch (error) {
+            if (this.options.debug) {
+                // eslint-disable-next-line no-console
+                console.warn('[FieldTriggers] Failed to capture snapshot:', error);
+            }
+            return undefined;
+        }
+    }
+    /**
+     * Restore a previously captured snapshot
+     * This reverts the record to its state before actions were executed
+     */
+    restoreSnapshot(context, snapshot) {
+        if (!context.store || !context.doctype || !context.recordId || !snapshot) {
+            return;
+        }
+        try {
+            // Get the record path (doctype.recordId)
+            const recordPath = `${context.doctype}.${context.recordId}`;
+            // Restore the entire record from snapshot
+            context.store.set(recordPath, snapshot);
+            if (this.options.debug) {
+                // eslint-disable-next-line no-console
+                console.log(`[FieldTriggers] Rolled back ${recordPath} to previous state`);
+            }
+        }
+        catch (error) {
+            // eslint-disable-next-line no-console
+            console.error('[FieldTriggers] Failed to restore snapshot:', error);
+            throw error;
+        }
+    }
+}
+/**
+ * Get or create the global field trigger engine singleton
+ * @param options - Optional configuration for the field trigger engine
+ * @public
+ */
+export function getGlobalTriggerEngine(options) {
+    return new FieldTriggerEngine(options);
+}
+/**
+ * Register a global action function that can be used in field triggers
+ * @param name - The name of the action to register
+ * @param fn - The action function to execute when the trigger fires
+ * @public
+ */
+export function registerGlobalAction(name, fn) {
+    const engine = getGlobalTriggerEngine();
+    engine.registerAction(name, fn);
+}
+/**
+ * Register a global XState transition action function
+ * @param name - The name of the transition action to register
+ * @param fn - The transition action function to execute
+ * @public
+ */
+export function registerTransitionAction(name, fn) {
+    const engine = getGlobalTriggerEngine();
+    engine.registerTransitionAction(name, fn);
+}
+/**
+ * Configure rollback behavior for a specific field trigger
+ * @param doctype - The doctype name
+ * @param fieldname - The field name
+ * @param enableRollback - Whether to enable automatic rollback for this field
+ * @public
+ */
+export function setFieldRollback(doctype, fieldname, enableRollback) {
+    const engine = getGlobalTriggerEngine();
+    engine.setFieldRollback(doctype, fieldname, enableRollback);
+}
+/**
+ * Manually trigger an XState transition for a specific doctype/record
+ * This can be called directly when you need to execute transition actions programmatically
+ * @param doctype - The doctype name
+ * @param transition - The XState transition name to trigger
+ * @param options - Optional configuration for the transition
+ * @public
+ */
+export async function triggerTransition(doctype, transition, options) {
+    const engine = getGlobalTriggerEngine();
+    const context = {
+        path: options?.path || (options?.recordId ? `${doctype}.${options.recordId}` : doctype),
+        fieldname: '',
+        beforeValue: undefined,
+        afterValue: undefined,
+        operation: 'set',
+        doctype,
+        recordId: options?.recordId,
+        timestamp: new Date(),
+        transition,
+        currentState: options?.currentState,
+        targetState: options?.targetState,
+        fsmContext: options?.fsmContext,
+    };
+    return await engine.executeTransitionActions(context);
+}
+/**
+ * Mark a specific operation as irreversible.
+ * Used to prevent undo of critical operations like publishing or deletion.
+ * @param operationId - The ID of the operation to mark as irreversible
+ * @param reason - Human-readable reason why the operation cannot be undone
+ * @public
+ */
+export function markOperationIrreversible(operationId, reason) {
+    if (!operationId)
+        return;
+    try {
+        const store = useOperationLogStore();
+        store.markIrreversible(operationId, reason);
+    }
+    catch {
+        // Operation log is optional
+    }
+}

package/dist/index.js

@@ -0,0 +1,27 @@
+import { useLazyLink } from './composables/lazy-link';
+import { useStonecrop } from './composables/stonecrop';
+import { useOperationLog, useUndoRedoShortcuts, withBatch } from './composables/operation-log';
+import Doctype from './doctype';
+import { FieldTriggerEngine, getGlobalTriggerEngine, markOperationIrreversible, registerGlobalAction, registerTransitionAction, setFieldRollback, triggerTransition, } from './field-triggers';
+import plugin from './plugins';
+import Registry from './registry';
+import { Stonecrop, getStonecrop } from './stonecrop';
+import { HST, createHST } from './stores/hst';
+import { useOperationLogStore } from './stores/operation-log';
+import { SchemaValidator, createValidator, validateSchema } from './schema-validator';
+import { ValidationSeverity } from './types/schema-validator';
+// Export enum as value (enums need runtime export, not just type)
+export { ValidationSeverity };
+export { Doctype, Registry, Stonecrop, useLazyLink, useStonecrop, 
+// HST exports for advanced usage
+HST, createHST, 
+// Field trigger system exports
+FieldTriggerEngine, getGlobalTriggerEngine, registerGlobalAction, registerTransitionAction, setFieldRollback, triggerTransition, markOperationIrreversible, 
+// Schema validator exports
+SchemaValidator, createValidator, validateSchema, 
+// Operation log exports
+useOperationLog, useOperationLogStore, useUndoRedoShortcuts, withBatch, 
+// Utility functions
+getStonecrop, };
+// Default export is the Vue plugin
+export default plugin;