@context-action/core 0.3.1 → 0.4.0

package/dist/index.js

@@ -39,24 +39,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 * @param context - Pipeline execution context containing handlers and state
 * @param createController - Factory function for creating pipeline controllers
 * 
-* @throws {Error} When a blocking handler fails or validation errors occur
+* @throws {Error} When a blocking handler fails
 * 
-* @example
-* ```typescript
-* // This is called internally by ActionRegister.dispatch()
-* // when executionMode is 'sequential'
-* 
-* // Handlers execute in this order (by priority):
-* // 1. Priority 100: Validation handler
-* // 2. Priority 50: Business logic handler  
-* // 3. Priority 10: Logging handler
-* 
-* await executeSequential(context, (registration, index) => ({
-*   abort: (reason) => { context.aborted = true; context.abortReason = reason },
-*   modifyPayload: (modifier) => { context.payload = modifier(context.payload) },
-*   // ... other controller methods
-* }))
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns
 * 
 * @public
 */
@@ -67,16 +52,6 @@ async function executeSequential(context, createController) {
 		if (context.aborted || context.terminated) break;
 		const registration = context.handlers[i];
 		context.currentIndex = i;
-		/** Check condition if provided */
-		if (registration.config.condition && !registration.config.condition()) {
-			i++;
-			continue;
-		}
-		/** Check validation if provided */
-		if (registration.config.validation && !registration.config.validation(context.payload)) {
-			i++;
-			continue;
-		}
 		const controller = createController(registration, i);
 		try {
 			if (context.aborted) break;
@@ -133,46 +108,13 @@ async function executeSequential(context, createController) {
 * 
 * @throws {Error} When any blocking handler fails
 * 
-* @example
-* ```typescript
-* // This is called internally by ActionRegister.dispatch()
-* // when executionMode is 'parallel'
-* 
-* // All handlers execute simultaneously:
-* // - Analytics handler (non-blocking)
-* // - Validation handler (blocking)
-* // - Update handler (blocking)
-* // - Notification handler (non-blocking)
-* 
-* await executeParallel(context, (registration, index) => ({
-*   abort: (reason) => { context.aborted = true },
-*   setResult: (result) => { context.results.push(result) },
-*   // ... other controller methods
-* }))
-* ```
-* 
-* @example Use Case
-* ```typescript
-* // Perfect for independent operations
-* register.setActionExecutionMode('logEvent', 'parallel')
-* 
-* // These can all run simultaneously:
-* register.register('logEvent', analyticsHandler, { blocking: false })
-* register.register('logEvent', metricsHandler, { blocking: false })
-* register.register('logEvent', auditHandler, { blocking: true })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#parallel-execution
 * 
 * @public
 */
 async function executeParallel(context, createController) {
-	/** Filter handlers that should run */
-	const runnableHandlers = context.handlers.filter((registration, _index) => {
-		/** Check condition */
-		if (registration.config.condition && !registration.config.condition()) return false;
-		/** Check validation */
-		if (registration.config.validation && !registration.config.validation(context.payload)) return false;
-		return true;
-	});
+	/** All handlers are runnable */
+	const runnableHandlers = context.handlers;
 	/** Create promises for all handlers */
 	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
 		const controller = createController(registration, _index);
@@ -238,52 +180,13 @@ async function executeParallel(context, createController) {
 * 
 * @throws {Error} When the winning handler fails and is blocking
 * 
-* @example
-* ```typescript
-* // This is called internally by ActionRegister.dispatch()
-* // when executionMode is 'race'
-* 
-* // Multiple data sources racing for fastest response:
-* // - Database handler (might be slow)
-* // - Cache handler (usually fast)
-* // - API handler (variable speed)
-* // 
-* // Whichever completes first wins
-* 
-* await executeRace(context, (registration, index) => ({
-*   return: (result) => { 
-*     context.terminated = true
-*     context.terminationResult = result 
-*   },
-*   // ... other controller methods
-* }))
-* ```
-* 
-* @example Use Case
-* ```typescript
-* // Race between multiple data sources
-* register.setActionExecutionMode('fetchUserData', 'race')
-* 
-* // These handlers race for fastest response:
-* register.register('fetchUserData', cacheHandler)     // Usually fastest
-* register.register('fetchUserData', databaseHandler)  // Reliable fallback
-* register.register('fetchUserData', apiHandler)       // External source
-* 
-* // First to complete wins, others are ignored
-* const result = await register.dispatchWithResult('fetchUserData', { id: '123' })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/dispatch-patterns#race-execution
 * 
 * @public
 */
 async function executeRace(context, createController) {
-	/** Filter handlers that should run */
-	const runnableHandlers = context.handlers.filter((registration, _index) => {
-		/** Check condition */
-		if (registration.config.condition && !registration.config.condition()) return false;
-		/** Check validation */
-		if (registration.config.validation && !registration.config.validation(context.payload)) return false;
-		return true;
-	});
+	/** All handlers are runnable */
+	const runnableHandlers = context.handlers;
 	if (runnableHandlers.length === 0) return;
 	/** Create promises for all handlers */
 	const handlerPromises = runnableHandlers.map(async (registration, _index) => {
@@ -392,33 +295,9 @@ var import_defineProperty$2 = /* @__PURE__ */ __toESM(require_defineProperty(),
 * debouncing and throttling mechanisms. Debouncing waits for a pause in calls
 * before executing, while throttling limits execution frequency.
 * 
-* @example Debouncing Search Input
-* ```typescript
-* const guard = new ActionGuard()
-* 
-* // Wait 300ms after user stops typing before searching
-* register.register('searchUsers', async (payload, controller) => {
-*   const query = payload.query
-*   if (query.length < 2) return
-*   
-*   const results = await userService.search(query)
-*   controller.setResult(results)
-* }, {
-*   debounce: 300,  // Built into ActionRegister via ActionGuard
-*   tags: ['search', 'user-input']
-* })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 * 
-* @example Throttling High-Frequency Events
-* ```typescript
-* // Limit scroll position updates to once per 100ms
-* register.register('updateScrollPosition', (payload, controller) => {
-*   scrollState.setValue(payload.position)
-* }, {
-*   throttle: 100,  // Built into ActionRegister via ActionGuard
-*   tags: ['scroll', 'performance']
-* })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 * 
 * @example Manual Usage (Advanced)
 * ```typescript
@@ -588,7 +467,7 @@ var ActionGuard = class {
 	clearAll() {
 		/** Iterate through all guard states and clear their timers */
 		/** This prevents memory leaks when clearing the entire guard system */
-		for (const [, state] of this.guards) {
+		this.guards.forEach((state) => {
 			/** Clear any active debounce timers */
 			if (state.debounceTimer) {
 				clearTimeout(state.debounceTimer);
@@ -596,7 +475,7 @@ var ActionGuard = class {
 			}
 			/** Clear any active throttle timers */
 			if (state.throttleTimer) clearTimeout(state.throttleTimer);
-		}
+		});
 		/** Remove all guard states from memory */
 		this.guards.clear();
 	}
@@ -747,74 +626,9 @@ var import_defineProperty = /* @__PURE__ */ __toESM(require_defineProperty(), 1)
 * 
 * @template TActionMap - Action payload mapping interface extending ActionPayloadMap
 * 
-* @example Basic Usage
-* ```typescript
-* interface AppActions extends ActionPayloadMap {
-*   updateUser: { id: string; name: string; email: string }
-*   deleteUser: { id: string }
-*   resetUser: void
-* }
-* 
-* const register = new ActionRegister<AppActions>({
-*   name: 'AppRegister',
-*   registry: { debug: true, maxHandlers: 10 }
-* })
-* 
-* // Register handler with priority
-* register.register('updateUser', async (payload, controller) => {
-*   await userService.update(payload.id, payload)
-*   controller.setResult({ success: true, userId: payload.id })
-* }, { priority: 10, tags: ['user', 'crud'] })
-* 
-* // Dispatch action
-* await register.dispatch('updateUser', { 
-*   id: '123', 
-*   name: 'John Doe', 
-*   email: 'john@example.com' 
-* })
-* ```
-* 
-* @example With Multiple Handlers
-* ```typescript
-* // High priority validation handler
-* register.register('updateUser', async (payload, controller) => {
-*   if (!payload.email.includes('@')) {
-*     controller.abort('Invalid email format')
-*     return
-*   }
-* }, { priority: 100, category: 'validation' })
-* 
-* // Lower priority update handler
-* register.register('updateUser', async (payload, controller) => {
-*   const user = await userService.update(payload.id, payload)
-*   controller.setResult(user)
-* }, { priority: 50, category: 'business-logic' })
-* ```
-* 
-* @example Advanced Configuration
-* ```typescript
-* const register = new ActionRegister<AppActions>({
-*   name: 'AdvancedRegister',
-*   registry: {
-*     debug: true,
-*     maxHandlers: 20,
-*     defaultExecutionMode: 'parallel',
-*     autoCleanup: true
-*   }
-* })
-* 
-* // Handler with debouncing and tags
-* register.register('searchUsers', async (payload, controller) => {
-*   const results = await userService.search(payload.query)
-*   controller.setResult(results)
-* }, {
-*   priority: 10,
-*   debounce: 300,
-*   tags: ['search', 'user'],
-*   category: 'query',
-*   once: false
-* })
-* ```
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
+* @see https://mineclover.github.io/context-action/en/guide/patterns/action/register-delegation
 * 
 * @public
 */
@@ -854,29 +668,7 @@ var ActionRegister = class {
 	* 
 	* @throws {Error} When maximum handlers limit is reached
 	* 
-	* @example Basic Registration
-	* ```typescript
-	* const unregister = register.register('updateUser', async (payload, controller) => {
-	*   await userService.update(payload.id, payload)
-	* })
-	* 
-	* // Later remove the handler
-	* unregister()
-	* ```
-	* 
-	* @example With Priority and Configuration
-	* ```typescript
-	* register.register('validateUser', async (payload, controller) => {
-	*   if (!payload.email) {
-	*     controller.abort('Email is required')
-	*   }
-	* }, {
-	*   priority: 100,
-	*   tags: ['validation'],
-	*   category: 'security',
-	*   once: false
-	* })
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -896,92 +688,8 @@ var ActionRegister = class {
 				id: handlerId,
 				blocking: config.blocking ?? false,
 				once: config.once ?? false,
-				condition: config.condition || (() => true),
-				debounce: config.debounce ?? void 0,
-				throttle: config.throttle ?? void 0,
-				validation: config.validation ?? void 0,
-				middleware: config.middleware ?? false,
-				tags: config.tags ?? [],
-				category: config.category ?? void 0,
-				description: config.description ?? void 0,
-				version: config.version ?? void 0,
-				returnType: config.returnType ?? "value",
-				timeout: config.timeout ?? void 0,
-				retries: config.retries ?? 0,
-				dependencies: config.dependencies ?? [],
-				conflicts: config.conflicts ?? [],
-				environment: config.environment ?? void 0,
-				feature: config.feature ?? void 0,
-				metrics: config.metrics ?? {
-					collectTiming: false,
-					collectErrors: false,
-					customMetrics: {}
-				},
-				metadata: config.metadata ?? {}
-			},
-			id: handlerId
-		};
-		if (!this.pipelines.has(action)) this.pipelines.set(action, []);
-		const pipeline = this.pipelines.get(action);
-		const existingIndex = pipeline.findIndex((reg) => reg.id === handlerId);
-		if (existingIndex !== -1) return () => {};
-		if (this.registryConfig?.maxHandlers && pipeline.length >= this.registryConfig.maxHandlers) throw new Error(`Maximum number of handlers (${this.registryConfig.maxHandlers}) reached for action '${String(action)}' in registry '${this.name}'`);
-		pipeline.push(registration);
-		pipeline.sort((a, b) => b.config.priority - a.config.priority);
-		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Handler registered: ${String(action)}`, {
-			handlerId,
-			priority: config.priority,
-			tags: config.tags,
-			category: config.category,
-			totalHandlers: pipeline.length,
-			registry: this.name
-		});
-		return () => {
-			const index = pipeline.findIndex((reg) => reg.id === handlerId && reg === registration);
-			if (index !== -1) {
-				pipeline.splice(index, 1);
-				if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Handler unregistered: ${String(action)}`, {
-					handlerId,
-					remainingHandlers: pipeline.length,
-					registry: this.name
-				});
-			}
-		};
-	}
-	/**
-	* 🆕 실제 등록 작업 수행 (큐에서 호출됨)
-	* @deprecated Currently unused - reserved for future queue-based registration
-	*/
-	_performRegistration(action, handler, config, handlerId) {
-		const registration = {
-			handler,
-			config: {
-				priority: config.priority ?? 0,
-				id: handlerId,
-				blocking: config.blocking ?? false,
-				once: config.once ?? false,
-				condition: config.condition || (() => true),
 				debounce: config.debounce ?? void 0,
-				throttle: config.throttle ?? void 0,
-				validation: config.validation ?? void 0,
-				middleware: config.middleware ?? false,
-				tags: config.tags ?? [],
-				category: config.category ?? void 0,
-				description: config.description ?? void 0,
-				version: config.version ?? void 0,
-				returnType: config.returnType ?? "value",
-				timeout: config.timeout ?? void 0,
-				retries: config.retries ?? 0,
-				dependencies: config.dependencies ?? [],
-				conflicts: config.conflicts ?? [],
-				environment: config.environment ?? void 0,
-				feature: config.feature ?? void 0,
-				metrics: config.metrics ?? {
-					collectTiming: false,
-					collectErrors: false,
-					customMetrics: {}
-				},
-				metadata: config.metadata ?? {}
+				throttle: config.throttle ?? void 0
 			},
 			id: handlerId
 		};
@@ -995,8 +703,6 @@ var ActionRegister = class {
 		if (this.registryConfig?.debug && process.env.NODE_ENV === "development") console.log(`🎯 Handler registered: ${String(action)}`, {
 			handlerId,
 			priority: config.priority,
-			tags: config.tags,
-			category: config.category,
 			totalHandlers: pipeline.length,
 			registry: this.name
 		});
@@ -1023,34 +729,7 @@ var ActionRegister = class {
 	* 
 	* @throws {Error} When action dispatching fails
 	* 
-	* @example Basic Dispatch
-	* ```typescript
-	* await register.dispatch('updateUser', {
-	*   id: '123',
-	*   name: 'John Doe',
-	*   email: 'john@example.com'
-	* })
-	* ```
-	* 
-	* @example With Options
-	* ```typescript
-	* await register.dispatch('updateUser', payload, {
-	*   executionMode: 'parallel',
-	*   timeout: 5000,
-	*   filter: {
-	*     tags: ['validation', 'business-logic'],
-	*     excludeCategory: 'analytics'
-	*   }
-	* })
-	* ```
-	* 
-	* @example With Throttling
-	* ```typescript
-	* await register.dispatch('searchUsers', { query: 'john' }, {
-	*   throttle: 300,
-	*   debounce: 100
-	* })
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1172,31 +851,7 @@ var ActionRegister = class {
 	* 
 	* @returns Promise resolving to comprehensive execution results
 	* 
-	* @example Basic Result Collection
-	* ```typescript
-	* const result = await register.dispatchWithResult('updateUser', payload)
-	* 
-	* if (result.success) {
-	*   console.log(`Executed ${result.execution.handlersExecuted} handlers`)
-	*   console.log(`Duration: ${result.execution.duration}ms`)
-	* }
-	* ```
-	* 
-	* @example Advanced Result Processing
-	* ```typescript
-	* const result = await register.dispatchWithResult('processOrder', order, {
-	*   result: {
-	*     collect: true,
-	*     strategy: 'merge',
-	*     maxResults: 5,
-	*     merger: (results) => results.reduce((acc, curr) => ({ ...acc, ...curr }), {})
-	*   }
-	* })
-	* 
-	* if (result.terminated) {
-	*   console.log('Handler returned early:', result.result)
-	* }
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1377,21 +1032,9 @@ var ActionRegister = class {
 		if (!filterOptions) return handlers;
 		return handlers.filter((registration) => {
 			const config = registration.config;
-			if (filterOptions.tags && filterOptions.tags.length > 0) {
-				const hasMatchingTag = filterOptions.tags.some((tag) => config.tags.includes(tag));
-				if (!hasMatchingTag) return false;
-			}
-			if (filterOptions.category && config.category !== filterOptions.category) return false;
 			if (filterOptions.handlerIds && filterOptions.handlerIds.length > 0) {
 				if (!filterOptions.handlerIds.includes(config.id)) return false;
 			}
-			if (filterOptions.environment && config.environment !== filterOptions.environment) return false;
-			if (filterOptions.feature && config.feature !== filterOptions.feature) return false;
-			if (filterOptions.excludeTags && filterOptions.excludeTags.length > 0) {
-				const hasExcludedTag = filterOptions.excludeTags.some((tag) => config.tags.includes(tag));
-				if (hasExcludedTag) return false;
-			}
-			if (filterOptions.excludeCategory && config.category === filterOptions.excludeCategory) return false;
 			if (filterOptions.excludeHandlerIds && filterOptions.excludeHandlerIds.length > 0) {
 				if (filterOptions.excludeHandlerIds.includes(config.id)) return false;
 			}
@@ -1509,13 +1152,7 @@ var ActionRegister = class {
 	* 
 	* @returns Number of registered handlers
 	* 
-	* @example
-	* ```typescript
-	* register.register('updateUser', handler1)
-	* register.register('updateUser', handler2)
-	* 
-	* console.log(register.getHandlerCount('updateUser')) // 2
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1530,12 +1167,7 @@ var ActionRegister = class {
 	* 
 	* @returns True if action has handlers, false otherwise
 	* 
-	* @example
-	* ```typescript
-	* if (register.hasHandlers('updateUser')) {
-	*   await register.dispatch('updateUser', userData)
-	* }
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1547,11 +1179,7 @@ var ActionRegister = class {
 	* 
 	* @returns Array of all registered action types
 	* 
-	* @example
-	* ```typescript
-	* const actions = register.getRegisteredActions()
-	* console.log('Registered actions:', actions) // ['updateUser', 'deleteUser', 'resetUser']
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1563,11 +1191,7 @@ var ActionRegister = class {
 	* 
 	* @param action - The action type to clear handlers for
 	* 
-	* @example
-	* ```typescript
-	* register.clearAction('updateUser')
-	* console.log(register.hasHandlers('updateUser')) // false
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1577,11 +1201,7 @@ var ActionRegister = class {
 	/**
 	* Remove all handlers for all actions
 	* 
-	* @example
-	* ```typescript
-	* register.clearAll()
-	* console.log(register.getRegisteredActions().length) // 0
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1593,11 +1213,7 @@ var ActionRegister = class {
 	* 
 	* @returns The register name
 	* 
-	* @example
-	* ```typescript
-	* const register = new ActionRegister({ name: 'UserRegister' })
-	* console.log(register.getName()) // 'UserRegister'
-	* ```
+	* @see https://mineclover.github.io/context-action/en/guide/patterns/action/basic-usage
 	* 
 	* @public
 	*/
@@ -1636,13 +1252,7 @@ var ActionRegister = class {
 		});
 		const handlersByPriority = Array.from(priorityMap.entries()).sort(([a], [b]) => b - a).map(([priority, handlers]) => ({
 			priority,
-			handlers: handlers.map((h) => ({
-				id: h.config.id,
-				tags: h.config.tags,
-				category: h.config.category,
-				description: h.config.description,
-				version: h.config.version
-			}))
+			handlers: handlers.map((h) => ({ id: h.config.id }))
 		}));
 		const stats = this.executionStats.get(action);
 		const executionStats = stats ? {
@@ -1668,34 +1278,6 @@ var ActionRegister = class {
 		return Array.from(this.pipelines.keys()).map((action) => this.getActionStats(action)).filter((stats) => stats !== null);
 	}
 	/**
-	* Get handlers by tag across all actions
-	* 
-	* @param tag Tag to filter handlers by
-	* @returns Map of actions to handlers with the specified tag
-	*/
-	getHandlersByTag(tag) {
-		const result = /* @__PURE__ */ new Map();
-		for (const [action, pipeline] of this.pipelines.entries()) {
-			const matchingHandlers = pipeline.filter((handler) => handler.config.tags.includes(tag));
-			if (matchingHandlers.length > 0) result.set(action, matchingHandlers);
-		}
-		return result;
-	}
-	/**
-	* Get handlers by category across all actions
-	* 
-	* @param category Category to filter handlers by
-	* @returns Map of actions to handlers with the specified category
-	*/
-	getHandlersByCategory(category) {
-		const result = /* @__PURE__ */ new Map();
-		for (const [action, pipeline] of this.pipelines.entries()) {
-			const matchingHandlers = pipeline.filter((handler) => handler.config.category === category);
-			if (matchingHandlers.length > 0) result.set(action, matchingHandlers);
-		}
-		return result;
-	}
-	/**
 	* Set execution mode for a specific action
 	* 
 	* @param action Action name