@context-action/core 0.0.1

package/LICENSE

@@ -0,0 +1,187 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (which shall not include communications that are marked or
+      otherwise designated in writing by the copyright owner as
+      "Not a Work").
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based upon (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and derivative works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control
+      systems, and issue tracking systems that are managed by, or on behalf
+      of, the Licensor for the purpose of discussing and improving the Work,
+      but excluding communication that is marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to use, reproduce, modify, distribute, prepare
+      Derivative Works of, and perform and display the Work and such
+      Derivative Works in all media and formats now known or hereafter
+      developed.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, trademark, patent,
+          attribution and other notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright notice as an addendum to the copyright
+      notice on the Work.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. You may choose to offer, and to
+      charge a fee for, warranty, support, indemnity or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may act only on Your own behalf and on
+      Your sole responsibility, not on behalf of any other Contributor, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any such warranty or
+      support.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2025 mineclover
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.ko.md

@@ -0,0 +1,328 @@
+# @context-action/core
+
+React 통합을 지원하는 타입 안전한 액션 파이프라인 관리 TypeScript 라이브러리입니다.
+
+## 주요 기능
+
+- 🔒 **타입 안전성**: 엄격한 타입 검사를 지원하는 완전한 TypeScript 지원
+- ⚡ **파이프라인 시스템**: 우선순위 제어를 통한 다중 핸들러 체이닝
+- 🎯 **Context 통합**: React Context와의 원활한 통합
+- 🔄 **비동기 지원**: 동기 및 비동기 작업 모두 처리
+- 🛡️ **에러 처리**: 내장된 에러 처리 및 중단 메커니즘
+- 📦 **경량화**: 제로 의존성으로 최소 번들 크기
+
+## 설치
+
+```bash
+npm install @context-action/core
+# 또는
+yarn add @context-action/core
+# 또는
+pnpm add @context-action/core
+```
+
+## 빠른 시작
+
+### 1. 액션 타입 정의
+
+```typescript
+import { ActionPayloadMap } from '@context-action/core';
+
+interface AppActions extends ActionPayloadMap {
+  increment: void;
+  decrement: void;
+  setCount: number;
+  reset: void;
+}
+```
+
+### 2. 액션 컨텍스트 생성
+
+```typescript
+import { createActionContext } from '@context-action/core';
+
+const { Provider, useAction, useActionHandler } = createActionContext<AppActions>();
+```
+
+### 3. React 컴포넌트에서 사용
+
+```typescript
+function Counter() {
+  const [count, setCount] = useState(0);
+  const action = useAction();
+
+  // 액션 핸들러 등록
+  useActionHandler('increment', () => {
+    setCount(prev => prev + 1);
+  }, { priority: 1 });
+
+  useActionHandler('setCount', (payload) => {
+    setCount(payload);
+  });
+
+  return (
+    <div>
+      <p>카운트: {count}</p>
+      <button onClick={() => action.dispatch('increment')}>+1</button>
+      <button onClick={() => action.dispatch('setCount', 10)}>10으로 설정</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Provider>
+      <Counter />
+    </Provider>
+  );
+}
+```
+
+## API 참조
+
+### `createActionContext<T>()`
+
+지정된 액션 타입 맵으로 새로운 액션 컨텍스트를 생성합니다.
+
+**반환값:**
+- `Provider`: React 컨텍스트 프로바이더 컴포넌트
+- `useAction()`: 액션 디스패처를 가져오는 훅
+- `useActionHandler()`: 액션 핸들러를 등록하는 훅
+- `useActionContext()`: 원시 컨텍스트에 접근하는 훅
+
+### `ActionRegister<T>`
+
+액션 파이프라인을 관리하는 핵심 클래스입니다.
+
+#### 메서드
+
+- `register(action, handler, config?)`: 액션 핸들러 등록
+- `dispatch(action, payload?)`: 파이프라인을 통해 액션 디스패치
+
+#### 핸들러 설정
+
+```typescript
+interface HandlerConfig {
+  priority?: number;    // 우선순위가 높은 핸들러가 먼저 실행 (기본값: 0)
+  id?: string;         // 핸들러의 고유 식별자
+  blocking?: boolean;  // 비동기 핸들러를 기다릴지 여부 (기본값: false)
+}
+```
+
+#### 파이프라인 컨트롤러
+
+각 핸들러는 컨트롤러 객체를 받습니다:
+
+```typescript
+interface PipelineController<T> {
+  next(): void;                           // 다음 핸들러로 진행
+  abort(reason?: string): void;           // 파이프라인 중단
+  modifyPayload(modifier: (payload: T) => T): void; // 후속 핸들러를 위한 페이로드 수정
+}
+```
+
+## 고급 사용법
+
+### 우선순위 기반 실행
+
+```typescript
+useActionHandler('saveData', () => {
+  console.log('검증');
+}, { priority: 10 }); // 첫 번째 실행
+
+useActionHandler('saveData', () => {
+  console.log('데이터베이스에 저장');
+}, { priority: 5 }); // 두 번째 실행
+
+useActionHandler('saveData', () => {
+  console.log('UI 업데이트');
+}, { priority: 1 }); // 마지막 실행
+```
+
+### 비동기 핸들러
+
+```typescript
+useActionHandler('fetchData', async (payload, controller) => {
+  try {
+    const data = await api.fetch(payload.url);
+    controller.modifyPayload(prev => ({ ...prev, data }));
+  } catch (error) {
+    controller.abort('데이터 가져오기 실패');
+  }
+}, { blocking: true }); // 이 핸들러가 완료될 때까지 대기
+```
+
+### 에러 처리
+
+```typescript
+useActionHandler('riskyOperation', (payload, controller) => {
+  if (!payload.isValid) {
+    controller.abort('유효하지 않은 페이로드');
+    return;
+  }
+  // 처리 계속...
+  controller.next();
+});
+```
+
+## 실제 사용 예제
+
+### 알림 시스템
+
+```typescript
+interface NotificationActions extends ActionPayloadMap {
+  showSuccess: { message: string };
+  showError: { message: string };
+  hideNotification: void;
+}
+
+const { Provider, useAction, useActionHandler } = createActionContext<NotificationActions>();
+
+function NotificationProvider({ children }: { children: ReactNode }) {
+  const [notification, setNotification] = useState<{
+    message: string;
+    type: 'success' | 'error';
+  } | null>(null);
+
+  useActionHandler('showSuccess', ({ message }) => {
+    setNotification({ message, type: 'success' });
+  });
+
+  useActionHandler('showError', ({ message }) => {
+    setNotification({ message, type: 'error' });
+  });
+
+  useActionHandler('hideNotification', () => {
+    setNotification(null);
+  });
+
+  return (
+    <Provider>
+      {children}
+      {notification && (
+        <div className={`notification ${notification.type}`}>
+          {notification.message}
+          <button onClick={() => useAction().dispatch('hideNotification')}>
+            ×
+          </button>
+        </div>
+      )}
+    </Provider>
+  );
+}
+```
+
+### 사용자 관리 시스템
+
+```typescript
+interface UserActions extends ActionPayloadMap {
+  loginUser: { email: string; password: string };
+  logoutUser: void;
+  updateProfile: { name: string; avatar?: File };
+}
+
+function UserManager() {
+  const [user, setUser] = useState<User | null>(null);
+  const [loading, setLoading] = useState(false);
+  const action = useAction();
+
+  // 로그인 검증
+  useActionHandler('loginUser', ({ email, password }, controller) => {
+    if (!email || !password) {
+      controller.abort('이메일과 비밀번호를 입력해주세요');
+      return;
+    }
+  }, { priority: 10 });
+
+  // 로그인 API 호출
+  useActionHandler('loginUser', async ({ email, password }, controller) => {
+    setLoading(true);
+    try {
+      const userData = await authAPI.login(email, password);
+      controller.modifyPayload(prev => ({ ...prev, userData }));
+    } catch (error) {
+      controller.abort('로그인 실패');
+    } finally {
+      setLoading(false);
+    }
+  }, { priority: 5, blocking: true });
+
+  // 사용자 상태 업데이트
+  useActionHandler('loginUser', (payload: any) => {
+    setUser(payload.userData);
+    localStorage.setItem('user', JSON.stringify(payload.userData));
+  }, { priority: 1 });
+
+  // 로그아웃
+  useActionHandler('logoutUser', () => {
+    setUser(null);
+    localStorage.removeItem('user');
+  });
+
+  return (
+    <div>
+      {user ? (
+        <div>
+          <p>환영합니다, {user.name}님!</p>
+          <button onClick={() => action.dispatch('logoutUser')}>
+            로그아웃
+          </button>
+        </div>
+      ) : (
+        <LoginForm onLogin={(email, password) => 
+          action.dispatch('loginUser', { email, password })
+        } />
+      )}
+    </div>
+  );
+}
+```
+
+## TypeScript 지원
+
+이 라이브러리는 TypeScript로 작성되었으며 완전한 타입 안전성을 제공합니다:
+
+```typescript
+// ✅ 타입 안전한 액션 디스패치
+action.dispatch('setCount', 42);        // 정상
+action.dispatch('setCount', 'invalid'); // ❌ 타입 에러
+
+// ✅ 타입 안전한 핸들러 등록
+useActionHandler('setCount', (count: number) => {
+  // count는 자동으로 number 타입으로 추론됩니다
+});
+```
+
+## 성능 고려사항
+
+- **경량화**: 라이브러리는 매우 작으며 제로 의존성을 가집니다
+- **메모화**: 불필요한 리렌더링을 방지하기 위해 적절한 메모화를 사용하세요
+- **핸들러 등록**: 가능한 한 컴포넌트 외부에서 핸들러를 정의하세요
+
+```typescript
+// ✅ 좋은 예
+const handleIncrement = useCallback(() => {
+  setCount(prev => prev + 1);
+}, []);
+
+useActionHandler('increment', handleIncrement);
+
+// ❌ 피해야 할 예 (매번 새로운 함수 생성)
+useActionHandler('increment', () => {
+  setCount(prev => prev + 1);
+});
+```
+
+## 기여하기
+
+기여를 환영합니다! Pull Request를 자유롭게 제출해 주세요.
+
+## 라이선스
+
+Apache-2.0 © [mineclover](https://github.com/mineclover)
+
+## 관련 링크
+
+- [English README](./README.md) - 영문 버전
+- [GitHub Repository](https://github.com/mineclover/context-action) - 소스 코드
+- [Issues](https://github.com/mineclover/context-action/issues) - 버그 리포트 및 기능 요청

package/README.md

@@ -0,0 +1,195 @@
+# @context-action/core
+
+A TypeScript library for type-safe action pipeline management with React integration.
+
+## Features
+
+- 🔒 **Type-safe**: Full TypeScript support with strict type checking
+- ⚡ **Pipeline System**: Chain multiple handlers with priority control
+- 🎯 **Context Integration**: Seamless React Context integration
+- 🔄 **Async Support**: Handle both sync and async operations
+- 🛡️ **Error Handling**: Built-in error handling and abort mechanisms
+- 📦 **Lightweight**: Minimal bundle size with zero dependencies
+
+## Installation
+
+```bash
+npm install @context-action/core
+# or
+yarn add @context-action/core
+# or
+pnpm add @context-action/core
+```
+
+## Quick Start
+
+### 1. Define your action types
+
+```typescript
+import { ActionPayloadMap } from '@context-action/core';
+
+interface AppActions extends ActionPayloadMap {
+  increment: void;
+  decrement: void;
+  setCount: number;
+  reset: void;
+}
+```
+
+### 2. Create action context
+
+```typescript
+import { createActionContext } from '@context-action/core';
+
+const { Provider, useAction, useActionHandler } = createActionContext<AppActions>();
+```
+
+### 3. Use in your React components
+
+```typescript
+function Counter() {
+  const [count, setCount] = useState(0);
+  const action = useAction();
+
+  // Register action handlers
+  useActionHandler('increment', () => {
+    setCount(prev => prev + 1);
+  }, { priority: 1 });
+
+  useActionHandler('setCount', (payload) => {
+    setCount(payload);
+  });
+
+  return (
+    <div>
+      <p>Count: {count}</p>
+      <button onClick={() => action.dispatch('increment')}>+1</button>
+      <button onClick={() => action.dispatch('setCount', 10)}>Set to 10</button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <Provider>
+      <Counter />
+    </Provider>
+  );
+}
+```
+
+## API Reference
+
+### `createActionContext<T>()`
+
+Creates a new action context with the specified action type map.
+
+**Returns:**
+- `Provider`: React context provider component
+- `useAction()`: Hook to get the action dispatcher
+- `useActionHandler()`: Hook to register action handlers
+- `useActionContext()`: Hook to access the raw context
+
+### `ActionRegister<T>`
+
+Core class for managing action pipelines.
+
+#### Methods
+
+- `register(action, handler, config?)`: Register an action handler
+- `dispatch(action, payload?)`: Dispatch an action through the pipeline
+
+#### Handler Configuration
+
+```typescript
+interface HandlerConfig {
+  priority?: number;    // Higher priority handlers run first (default: 0)
+  id?: string;         // Unique identifier for the handler
+  blocking?: boolean;  // Whether to wait for async handlers (default: false)
+}
+```
+
+#### Pipeline Controller
+
+Each handler receives a controller object:
+
+```typescript
+interface PipelineController<T> {
+  next(): void;                           // Continue to next handler
+  abort(reason?: string): void;           // Abort the pipeline
+  modifyPayload(modifier: (payload: T) => T): void; // Modify payload for subsequent handlers
+}
+```
+
+## Advanced Usage
+
+### Priority-based Execution
+
+```typescript
+useActionHandler('saveData', () => {
+  console.log('Validation');
+}, { priority: 10 }); // Runs first
+
+useActionHandler('saveData', () => {
+  console.log('Save to database');
+}, { priority: 5 }); // Runs second
+
+useActionHandler('saveData', () => {
+  console.log('Update UI');
+}, { priority: 1 }); // Runs last
+```
+
+### Async Handlers
+
+```typescript
+useActionHandler('fetchData', async (payload, controller) => {
+  try {
+    const data = await api.fetch(payload.url);
+    controller.modifyPayload(prev => ({ ...prev, data }));
+  } catch (error) {
+    controller.abort('Failed to fetch data');
+  }
+}, { blocking: true }); // Wait for this handler to complete
+```
+
+### Error Handling
+
+```typescript
+useActionHandler('riskyOperation', (payload, controller) => {
+  if (!payload.isValid) {
+    controller.abort('Invalid payload');
+    return;
+  }
+  // Continue processing...
+  controller.next();
+});
+```
+
+## TypeScript Support
+
+This library is written in TypeScript and provides full type safety:
+
+```typescript
+// ✅ Type-safe action dispatching
+action.dispatch('setCount', 42);        // OK
+action.dispatch('setCount', 'invalid'); // ❌ Type error
+
+// ✅ Type-safe handler registration
+useActionHandler('setCount', (count: number) => {
+  // count is automatically typed as number
+});
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+Apache-2.0 © [mineclover](https://github.com/mineclover)
+
+## Links
+
+- [한국어 README](./README.ko.md) - Korean version
+- [GitHub Repository](https://github.com/mineclover/context-action) - Source code
+- [Issues](https://github.com/mineclover/context-action/issues) - Bug reports and feature requests