@ehfuse/forma/dist/src/core/FieldStore.d.ts

Advanced React state management library with individual field subscriptions - supports both forms and general state management with useFormaState

/**
 * FieldStore.ts
 *
 * Forma - 개별 필드 상태 관리 핵심 클래스 / Core class for individual field state management
 * 선택적 구독과 성능 최적화 지원 / Supports selective subscriptions and performance optimization
 *
 * @license MIT License
 * @copyright 2025 KIM YOUNG JIN (Kim Young Jin)
 * @author KIM YOUNG JIN (ehfuse@gmail.com)
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */
/**
 * 개별 필드 상태 관리 Store / Individual field state management store
 * 선택적 구독과 성능 최적화를 위한 핵심 클래스
 * Core class for selective subscriptions and performance optimization
 *
 * @template T 폼 데이터의 타입 / Form data type
 */
/**
 * Watch 콜백 타입 / Watch callback type
 */
type WatchCallback = (value: any, prevValue: any) => void;
export declare class FieldStore<T extends Record<string, any>> {
    private fields;
    private dotNotationListeners;
    private initialValues;
    private globalListeners;
    private watchers;
    constructor(initialValues: T);
    /**
     * 특정 필드 값 가져오기 / Get specific field value
     * Dot notation 지원 / Supports dot notation
     * @param fieldName 필드명 또는 dot notation 경로 또는 "*" (전체) / Field name or dot notation path or "*" (all)
     * @returns 필드 값 / Field value
     */
    getValue(fieldName: keyof T | string): any;
    /**
     * 특정 필드 구독 / Subscribe to specific field
     * Dot notation 지원 / Supports dot notation
     * @param fieldName 필드명 또는 dot notation 경로 또는 "*" (전체) / Field name or dot notation path or "*" (all)
     * @param listener 변경 시 호출될 콜백 / Callback to call on change
     * @returns 구독 해제 함수 / Unsubscribe function
     */
    subscribe(fieldName: keyof T | string, listener: () => void): () => void;
    /**
     * 전역 구독 / Global subscription
     * isModified 등을 위해 사용 / Used for isModified etc.
     * @param listener 변경 시 호출될 콜백 / Callback to call on change
     * @returns 구독 해제 함수 / Unsubscribe function
     */
    subscribeGlobal(listener: () => void): () => void;
    /**
     * 필드 값 설정 / Set field value
     * Dot notation 지원 / Supports dot notation
     * @param fieldName 필드명 또는 dot notation 경로 / Field name or dot notation path
     * @param value 설정할 값 / Value to set
     */
    setValue(fieldName: keyof T | string, value: any): void;
    /**
     * 모든 값 가져오기 / Get all values
     * @returns 모든 필드 값을 포함한 객체 / Object containing all field values
     */
    getValues(): T;
    /**
     * 모든 값 설정 / Set all values
     * @param newValues 설정할 값들 / Values to set
     */
    setValues(newValues: Partial<T>): void;
    /**
     * 초기값 재설정 / Reset initial values
     * @param newInitialValues 새로운 초기값 / New initial values
     */
    setInitialValues(newInitialValues: T): void;
    /**
     * 수정 여부 확인 / Check if modified
     * @returns 초기값에서 변경되었는지 여부 / Whether changed from initial values
     */
    isModified(): boolean;
    /**
     * 객체에 비어있지 않은 값이 있는지 확인 / Check if object has non-empty values
     */
    private hasNonEmptyValues;
    /**
     * 특정 필드가 존재하는지 확인 / Check if a specific field exists
     * @param path 필드 경로 (dot notation 지원) / Field path (supports dot notation)
     * @returns 필드 존재 여부 / Whether the field exists
     */
    hasField(path: string): boolean;
    /**
     * 특정 필드를 제거 / Remove a specific field
     * @param path 필드 경로 (dot notation 지원) / Field path (supports dot notation)
     */
    removeField(path: string): void;
    /**
     * 전역 상태 변경에 구독 / Subscribe to global state changes
     * @param callback 상태 변경 시 실행될 콜백 / Callback to execute on state change
     * @returns 구독 해제 함수 / Unsubscribe function
     */
    subscribeToAll(callback: (values: T) => void): () => void;
    /**
     * 특정 prefix를 가진 모든 필드 구독자들을 새로고침합니다
     * Refresh all field subscribers with specific prefix
     * @param prefix 새로고침할 필드 prefix (예: "address")
     */
    refreshFields(prefix: string): void;
    /**
     * Batch update multiple fields efficiently
     * 여러 필드를 효율적으로 일괄 업데이트
     * @param updates - 업데이트할 필드들의 키-값 쌍
     */
    setBatch(updates: Record<string, any>): void;
    /**
     * Set value without immediately notifying listeners (for batch operations)
     * 리스너 알림 없이 값 설정 (배치 작업용)
     */
    private setValueWithoutNotify;
    /**
     * 초기값으로 리셋 / Reset to initial values
     */
    reset(): void;
    /**
     * 필드 변경 감시 / Watch field changes
     * @param path 감시할 필드 경로 (dot notation 지원) / Field path to watch (supports dot notation)
     * @param callback 변경 시 실행할 콜백 / Callback to execute on change
     * @param options 옵션 / Options
     * @returns cleanup 함수 / Cleanup function
     */
    watch(path: string, callback: WatchCallback, options?: {
        immediate?: boolean;
    }): () => void;
    /**
     * Watcher 알림 실행 / Notify watchers
     * @param path 변경된 필드 경로 / Changed field path
     * @param value 새 값 / New value
     * @param prevValue 이전 값 / Previous value
     * @param prevParentValues 부모 경로들의 이전 값 맵 / Map of previous values for parent paths
     */
    private notifyWatchers;
    /**
     * 와일드카드 패턴 매칭 / Wildcard pattern matching
     * @param path 실제 경로 / Actual path (e.g., "todos.0.completed")
     * @param pattern 와일드카드 패턴 / Wildcard pattern (e.g., "todos.*.completed")
     * @returns 매칭 여부 / Whether path matches pattern
     */
    private matchesWildcard;
    /**
     * 특정 path에 watcher가 등록되어 있는지 확인 / Check if watcher is registered for specific path
     * @param path 확인할 경로 / Path to check
     * @returns watcher 등록 여부 / Whether watcher is registered
     */
    hasWatcher(path: string): boolean;
    /**
     * 등록된 모든 watcher path 목록 반환 (디버깅용) / Return all registered watcher paths (for debugging)
     * @returns watcher path 배열 / Array of watcher paths
     */
    getWatchedPaths(): string[];
    /**
     * 리소스 정리 / Clean up resources
     */
    destroy(): void;
}
export {};
//# sourceMappingURL=FieldStore.d.ts.map