@simplysm/solid 13.0.34 → 13.0.36

package/src/providers/ServiceClientContext.ts

@@ -1,15 +1,28 @@
 import { createContext, useContext } from "solid-js";
 import type { ServiceClient, ServiceConnectionConfig } from "@simplysm/service-client";
 
+/**
+ * WebSocket 서비스 클라이언트 Context 값
+ */
 export interface ServiceClientContextValue {
+  /** WebSocket 연결 열기 (key로 다중 연결 관리) */
   connect: (key: string, options?: Partial<ServiceConnectionConfig>) => Promise<void>;
+  /** 연결 닫기 */
   close: (key: string) => Promise<void>;
+  /** 연결된 클라이언트 인스턴스 가져오기 (연결되지 않은 key면 에러 발생) */
   get: (key: string) => ServiceClient;
+  /** 연결 상태 확인 */
   isConnected: (key: string) => boolean;
 }
 
+/** WebSocket 서비스 클라이언트 Context */
 export const ServiceClientContext = createContext<ServiceClientContextValue>();
 
+/**
+ * WebSocket 서비스 클라이언트에 접근하는 훅
+ *
+ * @throws ServiceClientProvider가 없으면 에러 발생
+ */
 export function useServiceClient(): ServiceClientContextValue {
   const context = useContext(ServiceClientContext);
   if (!context) {

package/src/providers/ServiceClientProvider.tsx

@@ -8,6 +8,27 @@ import { ServiceClientContext, type ServiceClientContextValue } from "./ServiceC
 import { useConfig } from "./ConfigContext";
 import { useNotification } from "../components/feedback/notification/NotificationContext";
 
+/**
+ * WebSocket 서비스 클라이언트 Provider
+ *
+ * @remarks
+ * - ConfigProvider와 NotificationProvider 내부에서 사용해야 함
+ * - key 기반 다중 연결 관리
+ * - 요청/응답 진행률을 NotificationProvider 알림으로 표시
+ * - host, port, ssl 미지정 시 window.location에서 자동 추론
+ * - cleanup 시 모든 연결 자동 종료
+ *
+ * @example
+ * ```tsx
+ * <ConfigProvider clientName="my-app">
+ *   <NotificationProvider>
+ *     <ServiceClientProvider>
+ *       <App />
+ *     </ServiceClientProvider>
+ *   </NotificationProvider>
+ * </ConfigProvider>
+ * ```
+ */
 export const ServiceClientProvider: ParentComponent = (props) => {
   const config = useConfig();
   const notification = useNotification();

package/src/providers/SyncStorageContext.tsx

@@ -1,4 +1,10 @@
-import { createContext, useContext, type ParentComponent } from "solid-js";
+import {
+  type Accessor,
+  createContext,
+  createSignal,
+  useContext,
+  type ParentComponent,
+} from "solid-js";
 
 /**
  * 커스텀 동기화 저장소 어댑터 인터페이스
@@ -13,40 +19,72 @@ export interface StorageAdapter {
   removeItem(key: string): void | Promise<void>;
 }
 
+/**
+ * 기본 localStorage 기반 어댑터
+ */
+const defaultStorageAdapter: StorageAdapter = {
+  getItem: (key) => localStorage.getItem(key),
+  setItem: (key, value) => localStorage.setItem(key, value),
+  removeItem: (key) => localStorage.removeItem(key),
+};
+
+/**
+ * 동기화 저장소 Context 값
+ *
+ * @remarks
+ * - `adapter`: 현재 설정된 StorageAdapter (signal). 기본값은 localStorage 기반 어댑터
+ * - `configure`: decorator 함수를 받아 기존 adapter를 감싸서 새 adapter를 설정하는 함수
+ */
+export interface SyncStorageContextValue {
+  adapter: Accessor<StorageAdapter>;
+  configure: (fn: (origin: StorageAdapter) => StorageAdapter) => void;
+}
+
 /**
  * 동기화 저장소 Context
  *
  * @remarks
  * Provider가 없으면 `undefined` (useSyncConfig에서 localStorage로 fallback)
  */
-export const SyncStorageContext = createContext<StorageAdapter | undefined>(undefined);
+export const SyncStorageContext = createContext<SyncStorageContextValue>();
 
 /**
  * 동기화 저장소 Context에 접근하는 훅
  *
- * @returns StorageAdapter 또는 undefined (Provider가 없으면)
+ * @returns SyncStorageContextValue 또는 undefined (Provider가 없으면)
  */
-export function useSyncStorage(): StorageAdapter | undefined {
+export function useSyncStorage(): SyncStorageContextValue | undefined {
   return useContext(SyncStorageContext);
 }
 
 /**
  * 동기화 저장소 Provider
  *
+ * @remarks
+ * - prop 없이 사용. 기본적으로 localStorage 기반 어댑터가 설정됨
+ * - `configure()`로 decorator 함수를 전달하여 기존 adapter를 감싸거나 교체 가능
+ *
  * @example
  * ```tsx
- * <SyncStorageProvider storage={myStorageAdapter}>
- *   <ThemeProvider>
- *     <App />
- *   </ThemeProvider>
+ * <SyncStorageProvider>
+ *   <App />
  * </SyncStorageProvider>
+ *
+ * // 자식 컴포넌트에서 decorator 패턴으로 adapter 커스터마이징:
+ * useSyncStorage()!.configure((origin) => ({
+ *   getItem: (key) => myCustomGetItem(key),
+ *   setItem: origin.setItem,
+ *   removeItem: origin.removeItem,
+ * }));
  * ```
  */
-export const SyncStorageProvider: ParentComponent<{ storage: StorageAdapter }> = (props) => {
-  return (
-    // eslint-disable-next-line solid/reactivity -- storage는 초기 설정값으로 변경되지 않음
-    <SyncStorageContext.Provider value={props.storage}>
-      {props.children}
-    </SyncStorageContext.Provider>
-  );
+export const SyncStorageProvider: ParentComponent = (props) => {
+  const [adapter, setAdapter] = createSignal<StorageAdapter>(defaultStorageAdapter);
+
+  const value: SyncStorageContextValue = {
+    adapter,
+    configure: (fn: (origin: StorageAdapter) => StorageAdapter) => setAdapter((prev) => fn(prev)),
+  };
+
+  return <SyncStorageContext.Provider value={value}>{props.children}</SyncStorageContext.Provider>;
 };

package/src/providers/shared-data/SharedDataChangeEvent.ts

@@ -1,5 +1,13 @@
 import { defineEvent } from "@simplysm/service-common";
 
+/**
+ * SharedData 변경 이벤트 정의
+ *
+ * @remarks
+ * 서버-클라이언트 간 공유 데이터 변경을 알리는 이벤트.
+ * - 이벤트 정보: `{ name: string; filter: unknown }` — 데이터 이름과 필터
+ * - 이벤트 데이터: `(string | number)[] | undefined` — 변경된 항목의 key 배열 (undefined면 전체 갱신)
+ */
 export const SharedDataChangeEvent = defineEvent<
   { name: string; filter: unknown },
   (string | number)[] | undefined

package/src/providers/shared-data/SharedDataContext.ts

@@ -1,36 +1,77 @@
 import { type Accessor, createContext, useContext } from "solid-js";
 
+/**
+ * 공유 데이터 정의
+ *
+ * @remarks
+ * SharedDataProvider에 전달하여 서버 데이터 구독을 설정한다.
+ */
 export interface SharedDataDefinition<TData> {
+  /** 서비스 연결 key (useServiceClient의 connect key와 동일) */
   serviceKey: string;
+  /** 데이터 조회 함수 (changeKeys가 있으면 해당 항목만 부분 갱신) */
   fetch: (changeKeys?: Array<string | number>) => Promise<TData[]>;
+  /** 항목의 고유 key 추출 함수 */
   getKey: (item: TData) => string | number;
+  /** 정렬 기준 배열 (여러 기준 적용 가능) */
   orderBy: [(item: TData) => unknown, "asc" | "desc"][];
+  /** 서버 이벤트 필터 (같은 name의 이벤트 중 filter가 일치하는 것만 수신) */
   filter?: unknown;
 }
 
+/**
+ * 공유 데이터 접근자
+ *
+ * @remarks
+ * 각 데이터 key에 대한 반응형 접근 및 변경 알림을 제공한다.
+ */
 export interface SharedDataAccessor<TData> {
+  /** 반응형 항목 배열 */
   items: Accessor<TData[]>;
+  /** key로 단일 항목 조회 */
   get: (key: string | number | undefined) => TData | undefined;
+  /** 서버에 변경 이벤트 전파 (모든 구독자에게 refetch 트리거) */
   emit: (changeKeys?: Array<string | number>) => Promise<void>;
 }
 
+/**
+ * 공유 데이터 Context 값
+ *
+ * @remarks
+ * - configure 호출 전: wait, busy, configure만 접근 가능. 데이터 접근 시 throw
+ * - configure 호출 후: 각 데이터 key별 SharedDataAccessor와 전체 상태 관리 메서드 포함
+ */
 export type SharedDataValue<TSharedData extends Record<string, unknown>> = {
   [K in keyof TSharedData]: SharedDataAccessor<TSharedData[K]>;
 } & {
+  /** 모든 초기 fetch 완료까지 대기 */
   wait: () => Promise<void>;
+  /** fetch 진행 중 여부 */
   busy: Accessor<boolean>;
+  /** definitions를 설정하여 데이터 구독 시작 (decorator 패턴) */
+  configure: (
+    fn: (origin: {
+      [K in keyof TSharedData]: SharedDataDefinition<TSharedData[K]>;
+    }) => {
+      [K in keyof TSharedData]: SharedDataDefinition<TSharedData[K]>;
+    },
+  ) => void;
 };
 
+/** 공유 데이터 Context */
 export const SharedDataContext = createContext<SharedDataValue<Record<string, unknown>>>();
 
+/**
+ * 공유 데이터에 접근하는 훅
+ *
+ * @throws SharedDataProvider가 없으면 에러 발생
+ */
 export function useSharedData<
   TSharedData extends Record<string, unknown> = Record<string, unknown>,
 >(): SharedDataValue<TSharedData> {
   const context = useContext(SharedDataContext);
   if (!context) {
-    throw new Error(
-      "useSharedData는 SharedDataProvider 내부에서만 사용할 수 있습니다. SharedDataProvider는 ServiceClientProvider 아래에 위치해야 합니다",
-    );
+    throw new Error("useSharedData는 SharedDataProvider 내부에서만 사용할 수 있습니다");
   }
   return context as unknown as SharedDataValue<TSharedData>;
 }

package/src/providers/shared-data/SharedDataProvider.tsx

@@ -11,14 +11,41 @@ import { useServiceClient } from "../ServiceClientContext";
 import { useNotification } from "../../components/feedback/notification/NotificationContext";
 import { useLogger } from "../../hooks/useLogger";
 
-export function SharedDataProvider<TSharedData extends Record<string, unknown>>(props: {
-  definitions: { [K in keyof TSharedData]: SharedDataDefinition<TSharedData[K]> };
-  children: JSX.Element;
-}): JSX.Element {
+/**
+ * 공유 데이터 Provider
+ *
+ * @remarks
+ * - ServiceClientProvider와 NotificationProvider 내부에서 사용해야 함
+ * - LoggerProvider가 있으면 fetch 실패를 로거에도 기록
+ * - configure() 호출 전: wait, busy, configure만 접근 가능. 데이터 접근 시 throw
+ * - configure() 호출 후: definitions의 각 key마다 서버 이벤트 리스너를 등록하여 실시간 동기화
+ * - 동시 fetch 호출 시 version counter로 데이터 역전 방지
+ * - fetch 실패 시 사용자에게 danger 알림 표시
+ * - cleanup 시 모든 이벤트 리스너 자동 해제
+ *
+ * @example
+ * ```tsx
+ * <SharedDataProvider>
+ *   <App />
+ * </SharedDataProvider>
+ *
+ * // 자식 컴포넌트에서 나중에 설정:
+ * useSharedData().configure(() => ({
+ *   users: {
+ *     serviceKey: "main",
+ *     fetch: async (changeKeys) => fetchUsers(changeKeys),
+ *     getKey: (item) => item.id,
+ *     orderBy: [[(item) => item.name, "asc"]],
+ *   },
+ * }));
+ * ```
+ */
+export function SharedDataProvider(props: { children: JSX.Element }): JSX.Element {
   const serviceClient = useServiceClient();
   const notification = useNotification();
   const logger = useLogger();
 
+  let configured = false;
   const [busyCount, setBusyCount] = createSignal(0);
   const busy: Accessor<boolean> = () => busyCount() > 0;
 
@@ -26,6 +53,8 @@ export function SharedDataProvider<TSharedData extends Record<string, unknown>>(
   const memoMap = new Map<string, Accessor<Map<string | number, unknown>>>();
   const listenerKeyMap = new Map<string, string>();
   const versionMap = new Map<string, number>();
+  const accessors: Record<string, SharedDataAccessor<unknown>> = {};
+  let currentDefinitions: Record<string, SharedDataDefinition<unknown>> | undefined;
 
   function ordering<TT>(data: TT[], orderByList: [(item: TT) => unknown, "asc" | "desc"][]): TT[] {
     let result = [...data];
@@ -86,70 +115,95 @@ export function SharedDataProvider<TSharedData extends Record<string, unknown>>(
     await waitUntil(() => busyCount() <= 0);
   }
 
-  const accessors: Record<string, SharedDataAccessor<unknown>> = {};
-
-  // eslint-disable-next-line solid/reactivity -- definitions는 초기 설정용으로 마운트 시 1회만 읽음
-  for (const [name, def] of Object.entries(props.definitions) as [
-    string,
-    SharedDataDefinition<unknown>,
-  ][]) {
-    const [items, setItems] = createSignal<unknown[]>([]);
-    // eslint-disable-next-line solid/reactivity -- signal 참조를 Map에 저장하는 것은 반응성 접근이 아님
-    signalMap.set(name, [items, setItems]);
-
-    const itemMap = createMemo(() => {
-      const map = new Map<string | number, unknown>();
-      for (const item of items()) {
-        map.set(def.getKey(item as never), item);
-      }
-      return map;
-    });
-    // eslint-disable-next-line solid/reactivity -- memo 참조를 Map에 저장하는 것은 반응성 접근이 아님
-    memoMap.set(name, itemMap);
-
-    const client = serviceClient.get(def.serviceKey);
-    void client
-      .addEventListener(SharedDataChangeEvent, { name, filter: def.filter }, async (changeKeys) => {
-        await loadData(name, def, changeKeys);
-      })
-      .then((key) => {
-        listenerKeyMap.set(name, key);
+  function configure(
+    fn: (
+      origin: Record<string, SharedDataDefinition<unknown>>,
+    ) => Record<string, SharedDataDefinition<unknown>>,
+  ): void {
+    if (configured) {
+      throw new Error("SharedDataProvider: configure()는 1회만 호출할 수 있습니다");
+    }
+    configured = true;
+
+    const definitions = fn({});
+    currentDefinitions = definitions;
+
+    for (const [name, def] of Object.entries(definitions)) {
+      const [items, setItems] = createSignal<unknown[]>([]);
+      // eslint-disable-next-line solid/reactivity -- signal 참조를 Map에 저장하는 것은 반응성 접근이 아님
+      signalMap.set(name, [items, setItems]);
+
+      const itemMap = createMemo(() => {
+        const map = new Map<string | number, unknown>();
+        for (const item of items()) {
+          map.set(def.getKey(item as never), item);
+        }
+        return map;
       });
+      // eslint-disable-next-line solid/reactivity -- memo 참조를 Map에 저장하는 것은 반응성 접근이 아님
+      memoMap.set(name, itemMap);
 
-    void loadData(name, def);
-
-    accessors[name] = {
-      items,
-      get: (key: string | number | undefined) => {
-        if (key === undefined) return undefined;
-        return itemMap().get(key);
-      },
-      emit: async (changeKeys?: Array<string | number>) => {
-        await client.emitToServer(
+      const client = serviceClient.get(def.serviceKey);
+      void client
+        .addEventListener(
           SharedDataChangeEvent,
-          (info) => info.name === name && objEqual(info.filter, def.filter),
-          changeKeys,
-        );
-      },
-    };
+          { name, filter: def.filter },
+          async (changeKeys) => {
+            await loadData(name, def, changeKeys);
+          },
+        )
+        .then((key) => {
+          listenerKeyMap.set(name, key);
+        });
+
+      void loadData(name, def);
+
+      accessors[name] = {
+        items,
+        get: (key: string | number | undefined) => {
+          if (key === undefined) return undefined;
+          return itemMap().get(key);
+        },
+        emit: async (changeKeys?: Array<string | number>) => {
+          await client.emitToServer(
+            SharedDataChangeEvent,
+            (info) => info.name === name && objEqual(info.filter, def.filter),
+            changeKeys,
+          );
+        },
+      };
+    }
   }
 
   onCleanup(() => {
-    for (const [name] of Object.entries(props.definitions)) {
+    if (!currentDefinitions) return;
+    for (const [name] of Object.entries(currentDefinitions)) {
       const listenerKey = listenerKeyMap.get(name);
       if (listenerKey != null) {
-        const def = (props.definitions as Record<string, SharedDataDefinition<unknown>>)[name];
+        const def = currentDefinitions[name];
         const client = serviceClient.get(def.serviceKey);
         void client.removeEventListener(listenerKey);
       }
     }
   });
 
-  const contextValue = {
-    ...accessors,
-    wait,
-    busy,
-  } as SharedDataValue<Record<string, unknown>>;
+  const KNOWN_KEYS = new Set(["wait", "busy", "configure"]);
+
+  // Proxy: configure 전 데이터 접근 시 throw
+  const contextValue = new Proxy(
+    { wait, busy, configure } as SharedDataValue<Record<string, unknown>>,
+    {
+      get(target, prop: string) {
+        if (KNOWN_KEYS.has(prop)) {
+          return target[prop];
+        }
+        if (!configured) {
+          throw new Error("SharedDataProvider: configure()를 먼저 호출해야 합니다");
+        }
+        return accessors[prop];
+      },
+    },
+  );
 
   return (
     <SharedDataContext.Provider value={contextValue}>{props.children}</SharedDataContext.Provider>