@context-action/core 0.8.1 → 0.8.6

package/dist/index.js

@@ -314,27 +314,91 @@ var ActionGuard = class {
 		this.guards = /* @__PURE__ */ new Map();
 		this.maxIdleTime = 6e4;
 		this.cleanupIntervalMs = 3e4;
+		this.maxGuards = 1e3;
+		this.accessOrder = [];
 		if (autoCleanup) this.startAutoCleanup();
 	}
 	/**
 	* Start automatic cleanup of idle guard states
-	* 
+	*
 	* @internal
 	*/
 	startAutoCleanup() {
 		this.cleanupInterval = setInterval(() => {
-			const now = Date.now();
-			const keysToDelete = [];
-			this.guards.forEach((state, key) => {
+			this.performCleanup();
+		}, this.cleanupIntervalMs);
+	}
+	/**
+	* 🔧 Optimized cleanup with early exit and batched operations
+	*
+	* @internal
+	*/
+	performCleanup() {
+		const guardCount = this.guards.size;
+		if (guardCount === 0) return;
+		const now = Date.now();
+		const keysToDelete = [];
+		if (guardCount <= 10) this.guards.forEach((state, key) => {
+			const isIdle = now - state.lastExecuted > this.maxIdleTime;
+			const hasActiveTimers = state.debounceTimer || state.throttleTimer;
+			if (isIdle && !hasActiveTimers) keysToDelete.push(key);
+		});
+		else {
+			const entriesToCheck = Math.min(this.accessOrder.length, Math.ceil(guardCount / 4));
+			for (let i = 0; i < entriesToCheck; i++) {
+				const key = this.accessOrder[i];
+				if (!key) continue;
+				const state = this.guards.get(key);
+				if (!state) {
+					keysToDelete.push(key);
+					continue;
+				}
 				const isIdle = now - state.lastExecuted > this.maxIdleTime;
 				const hasActiveTimers = state.debounceTimer || state.throttleTimer;
 				if (isIdle && !hasActiveTimers) keysToDelete.push(key);
-			});
-			if (keysToDelete.length > 0) {
-				keysToDelete.forEach((key) => this.guards.delete(key));
-				if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION) console.debug(`[ActionGuard] Cleaned up ${keysToDelete.length} idle guards`);
 			}
-		}, this.cleanupIntervalMs);
+		}
+		if (keysToDelete.length > 0) {
+			keysToDelete.forEach((key) => {
+				this.guards.delete(key);
+				const accessIndex = this.accessOrder.indexOf(key);
+				if (accessIndex !== -1) this.accessOrder.splice(accessIndex, 1);
+			});
+			if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION) console.debug(`[ActionGuard] Cleaned up ${keysToDelete.length} idle guards`);
+		}
+	}
+	/**
+	* 🔧 Update access order for LRU tracking
+	*
+	* @internal
+	*/
+	updateAccessOrder(key) {
+		const existingIndex = this.accessOrder.indexOf(key);
+		if (existingIndex !== -1) this.accessOrder.splice(existingIndex, 1);
+		this.accessOrder.push(key);
+	}
+	/**
+	* 🔧 Evict oldest guards if max limit exceeded
+	*
+	* @internal
+	*/
+	evictIfNeeded() {
+		if (this.guards.size >= this.maxGuards) {
+			const evictCount = Math.ceil(this.maxGuards * .1);
+			this.accessOrder.slice(0, evictCount).forEach((key) => {
+				const state = this.guards.get(key);
+				if (state) {
+					if (state.debounceTimer) {
+						clearTimeout(state.debounceTimer);
+						if (state.debounceResolve) state.debounceResolve(false);
+					}
+					if (state.throttleTimer) clearTimeout(state.throttleTimer);
+				}
+				this.guards.delete(key);
+			});
+			this.accessOrder = this.accessOrder.slice(evictCount);
+			if (typeof process !== "undefined" && process.env?.DEBUG_CONTEXT_ACTION) console.debug(`[ActionGuard] Evicted ${evictCount} oldest guards due to limit`);
+		}
 	}
 	/**
 	* Apply debouncing to an action
@@ -359,6 +423,7 @@ var ActionGuard = class {
 	* @internal
 	*/
 	async debounce(actionKey, debounceMs) {
+		this.evictIfNeeded();
 		/** Get or create guard state for this action */
 		let state = this.guards.get(actionKey);
 		if (!state) {
@@ -373,6 +438,7 @@ var ActionGuard = class {
 			};
 			this.guards.set(actionKey, state);
 		}
+		this.updateAccessOrder(actionKey);
 		/** Clear any existing debounce timer to restart the delay period */
 		if (state.debounceTimer) {
 			clearTimeout(state.debounceTimer);
@@ -417,6 +483,7 @@ var ActionGuard = class {
 	* @internal
 	*/
 	throttle(actionKey, throttleMs) {
+		this.evictIfNeeded();
 		/** Get or create guard state for this action */
 		let state = this.guards.get(actionKey);
 		if (!state) {
@@ -431,6 +498,7 @@ var ActionGuard = class {
 			};
 			this.guards.set(actionKey, state);
 		}
+		this.updateAccessOrder(actionKey);
 		const now = Date.now();
 		const timeSinceLastExecution = now - state.lastExecuted;
 		/** Check if enough time has passed since last execution */
@@ -548,6 +616,7 @@ var ActionGuard = class {
 			this.cleanupInterval = void 0;
 		}
 		this.clearAll();
+		this.accessOrder = [];
 	}
 	/**
 	* 🆕 Get statistics about active guards
@@ -632,7 +701,11 @@ var OperationQueue = class {
 	* - 작업 완료 시 대기 중인 프로세스에게 자동 알림
 	*/
 	async processQueue() {
-		if (this.processingPromise) return this.processingPromise;
+		if (this.processingPromise) {
+			await this.processingPromise;
+			if (this.queue.length > 0 && !this.processingPromise) return this.processQueue();
+			return;
+		}
 		this.processingPromise = this._doProcess();
 		try {
 			await this.processingPromise;
@@ -744,6 +817,95 @@ var OperationQueue = class {
 	}
 };
 
+//#endregion
+//#region src/errors.ts
+/**
+* Action payload 검증 실패 에러
+*
+* dispatch 시 Zod 스키마 검증이 실패하면 발생합니다.
+* (validationMode가 'strict'일 때만 throw)
+*
+* @example
+* ```typescript
+* try {
+*   dispatch('updateUser', { id: '', name: 'John' });
+* } catch (error) {
+*   if (error instanceof ActionValidationError) {
+*     console.log('Action:', error.action);
+*     console.log('Issues:', error.issues);
+*     console.log('Formatted:', error.formattedErrors);
+*   }
+* }
+* ```
+*/
+var ActionValidationError = class ActionValidationError extends Error {
+	/**
+	* @param action - 검증 실패한 action 이름
+	* @param zodError - Zod 검증 에러 객체 (ZodError compatible)
+	*/
+	constructor(action, zodError) {
+		const message = `Action "${action}" payload validation failed: ${zodError && typeof zodError === "object" && "message" in zodError ? String(zodError.message) : "Validation failed"}`;
+		super(message);
+		this.name = "ActionValidationError";
+		this.action = action;
+		this.zodError = zodError;
+		Object.setPrototypeOf(this, ActionValidationError.prototype);
+	}
+	/**
+	* Zod 검증 이슈 목록
+	*/
+	get issues() {
+		if (this.zodError && typeof this.zodError === "object" && "issues" in this.zodError && Array.isArray(this.zodError.issues)) return this.zodError.issues;
+		return [];
+	}
+	/**
+	* 포맷된 에러 객체 (필드별 에러 메시지)
+	*/
+	get formattedErrors() {
+		if (this.zodError && typeof this.zodError === "object" && "format" in this.zodError && typeof this.zodError.format === "function") return this.zodError.format();
+		return {};
+	}
+	/**
+	* 플랫 에러 맵 (필드명 → 에러 메시지 배열)
+	*/
+	get flattenedErrors() {
+		if (this.zodError && typeof this.zodError === "object" && "flatten" in this.zodError && typeof this.zodError.flatten === "function") return this.zodError.flatten();
+		return {
+			fieldErrors: {},
+			formErrors: []
+		};
+	}
+	/**
+	* 첫 번째 에러 메시지
+	*/
+	get firstError() {
+		return this.issues[0]?.message;
+	}
+	/**
+	* 에러 발생 필드 경로 목록
+	*/
+	get errorPaths() {
+		return this.issues.map((issue) => issue.path.map((p) => String(p)).join("."));
+	}
+	/**
+	* JSON 직렬화
+	*/
+	toJSON() {
+		return {
+			name: this.name,
+			action: this.action,
+			message: this.message,
+			issues: this.issues
+		};
+	}
+};
+/**
+* ActionValidationError 타입 가드
+*/
+function isActionValidationError(error) {
+	return error instanceof ActionValidationError;
+}
+
 //#endregion
 //#region src/ActionRegister.ts
 /**
@@ -761,6 +923,35 @@ var OperationQueue = class {
 * 
 * @public
 */
+/**
+* Type guard to determine if an object is DispatchOptions
+* Extracted as utility function for reuse and performance
+* 
+* @param obj - Object to check
+* @returns True if object is DispatchOptions
+* @internal
+*/
+function isDispatchOptions(obj) {
+	if (!obj || typeof obj !== "object") return false;
+	if ("debounce" in obj && typeof obj.debounce === "number") return true;
+	if ("throttle" in obj && typeof obj.throttle === "number") return true;
+	if ("executionMode" in obj) return true;
+	if ("signal" in obj && obj.signal instanceof AbortSignal) return true;
+	if ("immediate" in obj && typeof obj.immediate === "boolean") return true;
+	if ("queuePriority" in obj && typeof obj.queuePriority === "number") return true;
+	if ("timeout" in obj && typeof obj.timeout === "number") return true;
+	if ("retryOnError" in obj && typeof obj.retryOnError === "object") return true;
+	if ("autoAbort" in obj && typeof obj.autoAbort === "object") return true;
+	if ("filter" in obj && typeof obj.filter === "object" && obj.filter !== null) {
+		const filter = obj.filter;
+		if ("handlerIds" in filter || "excludeHandlerIds" in filter || "priority" in filter || "custom" in filter) return true;
+	}
+	if ("result" in obj && typeof obj.result === "object" && obj.result !== null) {
+		const result = obj.result;
+		if ("strategy" in result || "merger" in result || "collect" in result || "maxResults" in result || "includeErrors" in result) return true;
+	}
+	return false;
+}
 var ActionRegister = class {
 	constructor(config = {}) {
 		this.pipelines = /* @__PURE__ */ new Map();
@@ -809,18 +1000,16 @@ var ActionRegister = class {
 	* @public
 	*/
 	get actions() {
-		return new Proxy({}, { get: (target, prop) => {
+		if (!this._actionsProxy) this._actionsProxy = new Proxy({}, { get: (_target, prop) => {
 			if (typeof prop === "string" && this.pipelines.has(prop)) {
 				const actionKey = prop;
 				return (payloadOrOptions, options) => {
-					const isDispatchOptions = (obj) => {
-						return obj && typeof obj === "object" && ("debounce" in obj || "throttle" in obj || "executionMode" in obj || "signal" in obj || "immediate" in obj || "filter" in obj || "result" in obj);
-					};
 					if (payloadOrOptions && isDispatchOptions(payloadOrOptions)) return this.dispatch(actionKey, void 0, payloadOrOptions);
 					else return this.dispatch(actionKey, payloadOrOptions, options);
 				};
 			}
 		} });
+		return this._actionsProxy;
 	}
 	/**
 	* Actions-based dispatching with result collection
@@ -846,18 +1035,16 @@ var ActionRegister = class {
 	* @returns Proxy object with action functions that return ExecutionResult
 	*/
 	get actionsWithResult() {
-		return new Proxy({}, { get: (target, prop) => {
+		if (!this._actionsWithResultProxy) this._actionsWithResultProxy = new Proxy({}, { get: (_target, prop) => {
 			if (typeof prop === "string" && this.pipelines.has(prop)) {
 				const actionKey = prop;
 				return (payloadOrOptions, options) => {
-					const isDispatchOptions = (obj) => {
-						return obj && typeof obj === "object" && ("debounce" in obj || "throttle" in obj || "executionMode" in obj || "signal" in obj || "immediate" in obj || "filter" in obj || "result" in obj);
-					};
 					if (payloadOrOptions && isDispatchOptions(payloadOrOptions)) return this.dispatchWithResult(actionKey, void 0, payloadOrOptions);
 					else return this.dispatchWithResult(actionKey, payloadOrOptions, options);
 				};
 			}
 		} });
+		return this._actionsWithResultProxy;
 	}
 	/**
 	* Register an action handler with optional configuration
@@ -1042,6 +1229,20 @@ var ActionRegister = class {
 			timestamp: (/* @__PURE__ */ new Date()).toISOString()
 		});
 		if (payload instanceof Event && true) console.warn(`Event object passed to action "${String(action)}"`, payload.type);
+		if (this.registryConfig?.schema && this.registryConfig?.validateOnDispatch !== false) {
+			const actionSchema = this.registryConfig.schema[action];
+			if (actionSchema) {
+				const result = actionSchema.safeParse(payload);
+				if (!result.success) {
+					const mode = this.registryConfig.validationMode ?? "strict";
+					if (mode === "strict") throw new ActionValidationError(action, result.error);
+					else if (mode === "warn") {
+						console.warn(`Action "${String(action)}" payload validation failed:`, result.error.message);
+						this.log(`Validation warning for action '${String(action)}'`, { issues: result.error.issues }, "warn");
+					}
+				}
+			}
+		}
 		const [effectiveSignal, autoAbortController, cleanup] = this.createAbortSignal(options);
 		if (options?.autoAbort?.onControllerCreated && autoAbortController) options.autoAbort.onControllerCreated(autoAbortController);
 		if (effectiveSignal?.aborted) {
@@ -1927,5 +2128,140 @@ function isReactActionError(error) {
 }
 
 //#endregion
-export { ActionGuard, ActionRegister, ReactActionError, ReactDevUtils, createActionHandler, executeParallel, executeRace, executeSequential, isReactActionError };
+//#region src/action-schema.ts
+/**
+* Zod 스키마를 JSON Schema로 변환 (Zod 4 네이티브 API)
+*
+* @param schema - Zod 스키마
+* @returns JSON Schema (draft-7)
+*/
+function zodToJsonSchema(schema, zodModule) {
+	return zodModule.toJSONSchema(schema, {
+		target: "draft-7",
+		metadata: zodModule.globalRegistry
+	});
+}
+/**
+* Zod 스키마 기반 Action 정의
+*
+* defineTool 패턴을 기반으로 context-action에 맞게 구현:
+* - Single Source of Truth: Zod 스키마로 타입 + 검증 + 메타데이터 통합
+* - 런타임 검증: validate(), safeParse()
+* - Tool Chain 호환: toMCP(), toOpenAI(), toAnthropic()
+*
+* @param options - Action 정의 옵션
+* @param zodModule - Zod 모듈 (peerDependency로 주입)
+* @returns UnifiedAction 인스턴스
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+* import { defineAction } from '@context-action/core';
+*
+* const updateUserAction = defineAction({
+*   name: 'updateUser',
+*   description: 'Update user profile',
+*   parameters: z.object({
+*     id: z.string().min(1).meta({ description: 'User ID' }),
+*     name: z.string().min(2).max(50).meta({ description: 'User name' }),
+*     email: z.string().email().optional(),
+*   }),
+* }, z);
+*
+* // 검증
+* const validated = updateUserAction.validate({ id: '123', name: 'John' });
+*
+* // Tool chain 변환
+* const mcpTool = updateUserAction.toMCP();
+* ```
+*/
+function defineAction(options, zodModule) {
+	const { name, description, parameters } = options;
+	const jsonSchema = zodToJsonSchema(parameters, zodModule);
+	return {
+		name,
+		description,
+		zodSchema: parameters,
+		jsonSchema,
+		validate: (payload) => {
+			return parameters.parse(payload);
+		},
+		safeParse: (payload) => {
+			return parameters.safeParse(payload);
+		},
+		toJSONSchema: () => jsonSchema,
+		toMCP: () => ({
+			name,
+			description,
+			inputSchema: jsonSchema
+		}),
+		toOpenAI: () => ({
+			type: "function",
+			function: {
+				name,
+				description,
+				parameters: {
+					type: "object",
+					properties: jsonSchema.properties ?? {},
+					required: jsonSchema.required
+				}
+			}
+		}),
+		toAnthropic: () => ({
+			name,
+			description,
+			input_schema: jsonSchema
+		})
+	};
+}
+/**
+* 다중 Action 스키마 생성
+*
+* 여러 defineAction을 묶어서 ActionSchemaMap 생성
+*
+* @param actions - UnifiedAction 맵
+* @returns ActionSchemaMap
+*
+* @example
+* ```typescript
+* const userActionSchema = createActionSchema({
+*   updateUser: defineAction({ ... }, z),
+*   deleteUser: defineAction({ ... }, z),
+* });
+*
+* type UserActions = InferActionPayloadMap<typeof userActionSchema>;
+* ```
+*/
+function createActionSchema(actions) {
+	return actions;
+}
+/**
+* Zod 모듈을 바인딩한 defineAction 팩토리 생성
+*
+* 매번 z 모듈을 전달하지 않아도 되도록 팩토리 패턴 제공
+*
+* @param zodModule - Zod 모듈
+* @returns defineAction 함수 (z 바인딩됨)
+*
+* @example
+* ```typescript
+* import { z } from 'zod';
+* import { createActionFactory } from '@context-action/core';
+*
+* const defineAction = createActionFactory(z);
+*
+* const updateUser = defineAction({
+*   name: 'updateUser',
+*   parameters: z.object({ id: z.string() }),
+* });
+* ```
+*/
+function createActionFactory(zodModule) {
+	return (options) => {
+		return defineAction(options, zodModule);
+	};
+}
+
+//#endregion
+export { ActionGuard, ActionRegister, ActionValidationError, ReactActionError, ReactDevUtils, createActionFactory, createActionHandler, createActionSchema, defineAction, executeParallel, executeRace, executeSequential, isActionValidationError, isReactActionError, zodToJsonSchema };
 //# sourceMappingURL=index.js.map