@remember-web/sse 0.1.0-alpha.1

package/src/createSseClient.test.ts

@@ -0,0 +1,82 @@
+// @vitest-environment node
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SseClient } from './core/SseClient';
+import type { SseClientOptions } from './core/types';
+import { createSseClient } from './createSseClient';
+import { WorkerSseClient } from './worker/WorkerSseClient';
+
+const createOptions = (
+  overrides?: Partial<SseClientOptions>
+): SseClientOptions & { warnings: string[] } => {
+  const warnings: string[] = [];
+  return {
+    baseUrl: 'https://sse.example.com',
+    getAuthToken: () => 'token-1',
+    logger: { warn: (message) => warnings.push(message), error: () => {} },
+    warnings,
+    ...overrides,
+  };
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('createSseClient — 구현 선택', () => {
+  it('sharedWorker 팩토리를 제공하고 브라우저가 SharedWorker를 지원하면 탭 간 공유 클라이언트를 만듭니다', () => {
+    vi.stubGlobal('SharedWorker', class {});
+    const options = createOptions({
+      sharedWorker: () => ({}) as SharedWorker,
+    });
+
+    const client = createSseClient(options);
+
+    expect(client).toBeInstanceOf(WorkerSseClient);
+    expect(options.warnings).toHaveLength(0);
+  });
+
+  it('sharedWorker 팩토리가 없으면 탭별 직접 연결 클라이언트를 만듭니다', () => {
+    const client = createSseClient(createOptions());
+
+    expect(client).toBeInstanceOf(SseClient);
+  });
+
+  it('sharedWorker를 제공해도 브라우저가 SharedWorker를 지원하지 않으면 직접 연결로 대체하고 logger.warn으로 알립니다', () => {
+    vi.stubGlobal('document', {});
+    const options = createOptions({
+      sharedWorker: () => ({}) as SharedWorker,
+    });
+
+    const client = createSseClient(options);
+
+    expect(client).toBeInstanceOf(SseClient);
+    expect(options.warnings).toHaveLength(1);
+    expect(options.warnings[0]).toContain('SharedWorker');
+  });
+
+  it('SSR·워커 스코프(document 없음)에서는 직접 연결로 대체하되 경고하지 않습니다', () => {
+    const options = createOptions({
+      sharedWorker: () => ({}) as SharedWorker,
+    });
+
+    const client = createSseClient(options);
+
+    expect(client).toBeInstanceOf(SseClient);
+    expect(options.warnings).toHaveLength(0);
+  });
+
+  it('워커 경로에 eventSource를 함께 주면 적용되지 않는다고 logger.warn으로 알립니다', () => {
+    vi.stubGlobal('SharedWorker', class {});
+    const options = createOptions({
+      sharedWorker: () => ({}) as SharedWorker,
+      eventSource: class {} as unknown as typeof EventSource,
+    });
+
+    const client = createSseClient(options);
+
+    expect(client).toBeInstanceOf(WorkerSseClient);
+    expect(options.warnings).toHaveLength(1);
+    expect(options.warnings[0]).toContain('eventSource');
+  });
+});

package/src/createSseClient.ts

@@ -0,0 +1,34 @@
+import { SseClient } from './core/SseClient';
+import type {
+  SseClientLike,
+  SseClientOptions,
+  SseEventMap,
+} from './core/types';
+import { WorkerSseClient } from './worker/WorkerSseClient';
+
+/**
+ * @description 환경에 맞는 SseClientLike 구현을 선택합니다 — sharedWorker 팩토리를 제공하면
+ * 탭 간 연결 공유(WorkerSseClient), 미제공이거나 브라우저가 SharedWorker를 지원하지 않으면
+ * 탭별 직접 연결(SseClient)입니다. 생성 시점에는 능력 검사만 하므로 SSR·워커 스코프에서도 안전합니다.
+ */
+export const createSseClient = <M extends object = SseEventMap>(
+  options: SseClientOptions
+): SseClientLike<M> => {
+  if (options.sharedWorker !== undefined) {
+    if (options.eventSource !== undefined) {
+      options.logger?.warn(
+        'sse: 워커 경로에서는 eventSource 주입이 적용되지 않습니다 — 스트림은 워커 스코프에서 만들어집니다'
+      );
+    }
+    if (typeof SharedWorker !== 'undefined') {
+      return new WorkerSseClient<M>(options);
+    }
+    // document는 브라우저 메인 스레드에만 있습니다 — SSR·워커 스코프의 무의미한 경고를 함께 거릅니다
+    if (typeof document !== 'undefined') {
+      options.logger?.warn(
+        'sse: 이 브라우저는 SharedWorker를 지원하지 않습니다 — 탭별 직접 연결로 대체합니다'
+      );
+    }
+  }
+  return new SseClient<M>(options);
+};

package/src/index.ts

@@ -0,0 +1,21 @@
+// 클라이언트 생성은 createSseClient 단일 진입입니다 — 구현 클래스를 직접 노출하면 주입점(sharedWorker 선택)을 우회하게 됩니다
+export { createSseClient } from './createSseClient';
+export type { BackoffOptions } from './core/backoff';
+export { wire } from './core/wire';
+export type { WireHandlers } from './core/wire';
+export type {
+  FatalCause,
+  FatalPayload,
+  GoawayAction,
+  GoawayPayload,
+  GoawayReason,
+  PayloadOf,
+  SseClientLike,
+  SseClientOptions,
+  SseEventHandler,
+  SseEventMap,
+  SseEventName,
+  SseLogger,
+  SseStatus,
+  Unsubscribe,
+} from './core/types';

package/src/react/SseProvider.test.tsx

@@ -0,0 +1,129 @@
+import { render } from '@testing-library/react';
+import { StrictMode } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSseContext } from './createSseContext';
+
+import { SseClient } from '../core/SseClient';
+
+const { SseProvider } = createSseContext();
+
+const options = {
+  baseUrl: 'https://sse.example.com',
+  getAuthToken: () => 'token',
+};
+
+function trackLifecycleCalls() {
+  const calls: string[] = [];
+  const instances: unknown[] = [];
+  vi.spyOn(SseClient.prototype, 'connect').mockImplementation(
+    function (this: unknown) {
+      calls.push('connect');
+      instances.push(this);
+    }
+  );
+  vi.spyOn(SseClient.prototype, 'disconnect').mockImplementation(
+    function (this: unknown) {
+      calls.push('disconnect');
+      instances.push(this);
+    }
+  );
+  return { calls, instances };
+}
+
+describe('SseProvider 연결 수명주기', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('StrictMode 이중 마운트에서 같은 인스턴스로 connect → disconnect → connect가 수행됩니다', () => {
+    const { calls, instances } = trackLifecycleCalls();
+    const { unmount } = render(
+      <StrictMode>
+        <SseProvider {...options}>{null}</SseProvider>
+      </StrictMode>
+    );
+    expect(calls).toEqual(['connect', 'disconnect', 'connect']);
+    expect(new Set(instances).size).toBe(1);
+    unmount();
+    expect(calls).toEqual(['connect', 'disconnect', 'connect', 'disconnect']);
+  });
+
+  it('enabled=false로 마운트하면 연결한 적 없는 클라이언트에 disconnect가 나가지 않습니다', () => {
+    const { calls } = trackLifecycleCalls();
+    const { unmount } = render(
+      <StrictMode>
+        <SseProvider {...options} enabled={false}>
+          {null}
+        </SseProvider>
+      </StrictMode>
+    );
+    unmount();
+    expect(calls).toEqual([]);
+  });
+
+  it('enabled를 끄면 이전 effect의 cleanup이 한 번만 해제합니다', () => {
+    const { calls } = trackLifecycleCalls();
+    const { rerender } = render(<SseProvider {...options}>{null}</SseProvider>);
+    rerender(
+      <SseProvider {...options} enabled={false}>
+        {null}
+      </SseProvider>
+    );
+    expect(calls).toEqual(['connect', 'disconnect']);
+  });
+
+  it('enabled를 다시 켜면 재연결하고, 그 연결은 언마운트 때 해제됩니다', () => {
+    const { calls } = trackLifecycleCalls();
+    const { rerender, unmount } = render(
+      <SseProvider {...options} enabled={false}>
+        {null}
+      </SseProvider>
+    );
+    rerender(<SseProvider {...options}>{null}</SseProvider>);
+    expect(calls).toEqual(['connect']);
+    unmount();
+    expect(calls).toEqual(['connect', 'disconnect']);
+  });
+});
+
+// 이 배선이 없으면 휴면으로 접힌 연결이 깨어나도 서지 못해, 방치한 탭의 수신이 새로고침 전까지 죽어 있습니다
+describe('SseProvider 자동 재개', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('탭이 다시 보이면 connect를 다시 부릅니다', () => {
+    const { calls } = trackLifecycleCalls();
+    render(<SseProvider {...options}>{null}</SseProvider>);
+    expect(calls).toEqual(['connect']);
+
+    document.dispatchEvent(new Event('visibilitychange'));
+
+    expect(calls).toEqual(['connect', 'connect']);
+  });
+
+  it('언마운트한 뒤에는 탭이 다시 보여도 connect가 나가지 않습니다', () => {
+    const { calls } = trackLifecycleCalls();
+    const { unmount } = render(<SseProvider {...options}>{null}</SseProvider>);
+    unmount();
+    const before = [...calls];
+
+    document.dispatchEvent(new Event('visibilitychange'));
+
+    expect(calls).toEqual(before);
+  });
+
+  it('enabled=false면 자동 재개도 배선되지 않습니다', () => {
+    const { calls } = trackLifecycleCalls();
+    render(
+      <SseProvider {...options} enabled={false}>
+        {null}
+      </SseProvider>
+    );
+
+    document.dispatchEvent(new Event('visibilitychange'));
+
+    expect(calls).toEqual([]);
+  });
+});

package/src/react/createSseContext.test.ts

@@ -0,0 +1,47 @@
+// @vitest-environment node
+import { describe, expectTypeOf, it } from 'vitest';
+
+import { createSseContext } from './createSseContext';
+
+import type { FatalPayload } from '../core/types';
+
+// 이 파일의 검증 대상은 타입 추론입니다 — 훅 호출 없이 인스턴스화 표현식으로만 확인하므로 Provider가 필요 없습니다
+// 게이트는 tsc(type-check)입니다 — vitest run은 타입 단언을 검증하지 않습니다
+interface TestEventMap {
+  'demo.created': { id: string };
+}
+
+describe('createSseContext 타입 추론', () => {
+  const hooks = createSseContext<TestEventMap>();
+
+  it('맵에 있는 이벤트명이면 페이로드가 맵에서 추론됩니다', () => {
+    expectTypeOf(hooks.useSseEvent<'demo.created'>)
+      .parameter(1)
+      .toEqualTypeOf<(payload: { id: string }) => void>();
+  });
+
+  it('맵에 없는 이벤트명은 unknown 페이로드로 허용됩니다', () => {
+    expectTypeOf(hooks.useSseEvent<'not.in.map'>)
+      .parameter(1)
+      .toEqualTypeOf<(payload: unknown) => void>();
+  });
+
+  it('SDK 예약 이벤트 resync의 페이로드는 void입니다', () => {
+    expectTypeOf(hooks.useSseEvent<'resync'>)
+      .parameter(1)
+      .toEqualTypeOf<(payload: void) => void>();
+  });
+
+  it('SDK 예약 이벤트 fatal의 페이로드는 멈춘 사유를 담습니다', () => {
+    expectTypeOf(hooks.useSseEvent<'fatal'>)
+      .parameter(1)
+      .toEqualTypeOf<(payload: FatalPayload) => void>();
+  });
+
+  it('맵과 다른 페이로드 타입의 핸들러는 컴파일에서 거부됩니다', () => {
+    type DemoHandler = Parameters<typeof hooks.useSseEvent<'demo.created'>>[1];
+    // @ts-expect-error 'demo.created'의 페이로드는 { id: string }입니다
+    const wrong: DemoHandler = (e: { wrong: number }) => e.wrong;
+    expectTypeOf(wrong).toBeFunction();
+  });
+});

package/src/react/createSseContext.tsx

@@ -0,0 +1,140 @@
+import type { ReactNode } from 'react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useInsertionEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+
+import type {
+  PayloadOf,
+  SseClientLike,
+  SseClientOptions,
+  SseEventHandler,
+  SseEventMap,
+  SseEventName,
+  SseStatus,
+} from '../core/types';
+import { createSseClient } from '../createSseClient';
+
+// useEffectEvent(React 19.2+)와 같은 목적의 latest-ref 패턴 — insertion effect는 커밋된 렌더에서만 실행되고 paint 전에 동기 반영됩니다
+const useLatestRef = <T,>(value: T) => {
+  const ref = useRef(value);
+  useInsertionEffect(() => {
+    ref.current = value;
+  });
+  return ref;
+};
+
+/**
+ * @description 연결 옵션은 마운트 시점 값으로 고정됩니다 — 이후 prop 변경은 무시됩니다.
+ * 단 `getAuthToken`은 마지막 커밋된 렌더의 함수를 호출하므로 인라인 클로저를 넘겨도 안전합니다.
+ */
+export interface SseProviderProps extends SseClientOptions {
+  /** @description false면 연결하지 않고, 연결 중이면 해제합니다 (로그아웃 등) */
+  enabled?: boolean;
+  children: ReactNode;
+}
+
+/**
+ * @description 앱의 이벤트 맵으로 Provider와 훅을 한 번에 생성합니다 — 호출부는 이벤트명만으로 페이로드가 추론됩니다.
+ * 컨텍스트를 팩토리 안에서 만들어 Provider와 훅이 타입으로 결합되며,
+ * 호출마다 제네릭을 명시하는 방식은 TS의 부분 타입 인자 추론 부재로 페이로드가 unknown이 되어 팩토리로 고정합니다.
+ * 컴포넌트 밖 모듈 스코프에서 한 번만 호출하세요 — 렌더 중 호출하면 컨텍스트가 매번 재생성됩니다.
+ *
+ * @example
+ * // 앱당 1회, 모듈 스코프
+ * export const { SseProvider, useSseEvent, useSseStatus } =
+ *   createSseContext<AppEventMap>();
+ *
+ * // 호출부 — 이벤트명만으로 페이로드가 추론됩니다
+ * useSseEvent('demo.created', (event) => showToast(event.id));
+ */
+export function createSseContext<M extends object = SseEventMap>() {
+  const SseClientContext = createContext<SseClientLike<M> | null>(null);
+
+  const SseProvider = ({
+    enabled = true,
+    children,
+    ...options
+  }: Readonly<SseProviderProps>) => {
+    const getAuthTokenRef = useLatestRef(options.getAuthToken);
+
+    const [client] = useState(() =>
+      createSseClient<M>({
+        ...options,
+        getAuthToken: () => getAuthTokenRef.current(),
+      })
+    );
+
+    useEffect(() => {
+      if (!enabled) {
+        return;
+      }
+      client.connect();
+      // 휴면으로 접힌 연결은 깨어난 탭의 connect만이 다시 세웁니다 — 소비처가 몰라도 복구되게 여기서 붙입니다
+      const detachAutoResume = client.attachAutoResume();
+      return () => {
+        detachAutoResume();
+        client.disconnect();
+      };
+    }, [client, enabled]);
+
+    return (
+      <SseClientContext.Provider value={client}>
+        {children}
+      </SseClientContext.Provider>
+    );
+  };
+
+  const useSseClient = (): SseClientLike<M> => {
+    const client = useContext(SseClientContext);
+    if (!client) {
+      throw new Error('SSE 훅은 SseProvider 안에서만 호출할 수 있습니다');
+    }
+    return client;
+  };
+
+  /**
+   * @description 이벤트 구독 훅 — 마운트 동안 구독하고 언마운트에 해제하며, 핸들러는 항상 최신 렌더의 클로저를 봅니다.
+   * @param type 이벤트 이름. 도메인 이벤트 외 예약 4종 —
+   * - `fatal`(SDK의 포기 선언 — 재시도 없이 멈춤, SDK 합성) ·
+   * - `stalled`(재시도가 계속되는 진행형 통지, SDK 합성) ·
+   * - `goaway`(서버의 예고된 끊음 — `action: 'close'`만 안내 대상, 서버 발신) ·
+   * - `resync`(재수립 후 놓친 구간을 REST로 재조회하라는 신호, SDK 합성). 상세는 `WithLifecycle` 문서 참조.
+   * @param handler 이벤트 페이로드를 받는 콜백 — 발화 순간의 구독자에게만 배달되므로 수명주기 핸들러는 앱 루트에 두세요
+   */
+  const useSseEvent = <K extends SseEventName<M>>(
+    type: K,
+    handler: SseEventHandler<PayloadOf<M, K>>
+  ): void => {
+    const client = useSseClient();
+    const handlerRef = useLatestRef(handler);
+
+    useEffect(
+      () => client.on(type, (payload) => handlerRef.current(payload)),
+      // handlerRef는 useRef 정체성이라 재구독을 유발하지 않지만, exhaustive-deps가 커스텀 훅 반환을 안정으로 볼 수 없어 명시합니다
+      [client, type, handlerRef]
+    );
+  };
+
+  const useSseStatus = (): SseStatus => {
+    const client = useSseClient();
+    const subscribe = useCallback(
+      (onStoreChange: () => void) => client.onStatus(onStoreChange),
+      [client]
+    );
+    return useSyncExternalStore(
+      subscribe,
+      () => client.status,
+      // 서버/hydration 첫 렌더는 connect() 이전이라 항상 클라이언트 초기 상태입니다
+      () => client.status
+    );
+  };
+
+  return { SseProvider, useSseClient, useSseEvent, useSseStatus };
+}

package/src/react/index.ts

@@ -0,0 +1,2 @@
+export { createSseContext } from './createSseContext';
+export type { SseProviderProps } from './createSseContext';

package/src/react/useSseEvent.test.tsx

@@ -0,0 +1,71 @@
+import { render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSseContext } from './createSseContext';
+
+import { SseClient } from '../core/SseClient';
+
+interface TestEventMap {
+  'demo.created': { id: string };
+}
+
+const { SseProvider, useSseEvent } = createSseContext<TestEventMap>();
+
+const options = {
+  baseUrl: 'https://sse.example.com',
+  getAuthToken: () => 'token',
+};
+
+function EventProbe({ onCreated }: { onCreated: (e: { id: string }) => void }) {
+  useSseEvent('demo.created', onCreated);
+  return null;
+}
+
+describe('useSseEvent', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('리렌더 시 재구독 없이, 이벤트가 오면 최신 핸들러가 호출됩니다', () => {
+    let captured: ((payload: unknown) => void) | undefined;
+    const on = vi
+      .spyOn(SseClient.prototype, 'on')
+      .mockImplementation((_type, handler) => {
+        captured = handler as (payload: unknown) => void;
+        return () => {};
+      });
+    const staleHandler = vi.fn();
+    const latestHandler = vi.fn();
+    const { rerender } = render(
+      <SseProvider {...options}>
+        <EventProbe onCreated={staleHandler} />
+      </SseProvider>
+    );
+    rerender(
+      <SseProvider {...options}>
+        <EventProbe onCreated={latestHandler} />
+      </SseProvider>
+    );
+
+    captured?.({ id: 'a' });
+
+    expect(on).toHaveBeenCalledTimes(1);
+    expect(staleHandler).not.toHaveBeenCalled();
+    expect(latestHandler).toHaveBeenCalledWith({ id: 'a' });
+  });
+
+  it('언마운트하면 구독이 해제됩니다', () => {
+    const unsubscribe = vi.fn();
+    vi.spyOn(SseClient.prototype, 'on').mockImplementation(() => unsubscribe);
+    const { unmount } = render(
+      <SseProvider {...options}>
+        <EventProbe onCreated={() => {}} />
+      </SseProvider>
+    );
+    expect(unsubscribe).not.toHaveBeenCalled();
+
+    unmount();
+
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+  });
+});

package/src/react/useSseStatus.test.tsx

@@ -0,0 +1,40 @@
+import { render } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { createSseContext } from './createSseContext';
+
+import { SseClient } from '../core/SseClient';
+
+const { SseProvider, useSseStatus } = createSseContext();
+
+const options = {
+  baseUrl: 'https://sse.example.com',
+  getAuthToken: () => 'token',
+};
+
+function StatusProbe() {
+  useSseStatus();
+  return null;
+}
+
+describe('useSseStatus', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('리렌더 시 재구독하지 않습니다', () => {
+    const onStatus = vi.spyOn(SseClient.prototype, 'onStatus');
+    const { rerender, unmount } = render(
+      <SseProvider {...options}>
+        <StatusProbe />
+      </SseProvider>
+    );
+    rerender(
+      <SseProvider {...options}>
+        <StatusProbe />
+      </SseProvider>
+    );
+    expect(onStatus).toHaveBeenCalledTimes(1);
+    unmount();
+  });
+});