@remember-web/sse 0.1.0-alpha.1

package/dist/worker/sse.worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.worker.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@remember-web/sse",
+  "version": "0.1.0-alpha.1",
+  "description": "Remember Web SSE Client SDK",
+  "homepage": "https://dramancompany.github.io/rwp",
+  "author": "Remember",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dramancompany/rwp.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "rollup -c && rollup -c rollup.config.worker.mjs && yarn fix:dts-alias",
+    "fix:dts-alias": "yarn tsc-alias -p tsconfig.alias.json",
+    "type-check": "tsc -p ./tsconfig.cli.json",
+    "test": "vitest run",
+    "test:watch": "vitest watch"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "source": "./src/index.ts",
+  "main": "./dist/src/index.cjs.js",
+  "module": "./dist/src/index.esm.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.esm.js",
+      "require": "./dist/src/index.cjs.js"
+    },
+    "./react": {
+      "types": "./dist/src/react/index.d.ts",
+      "import": "./dist/src/react/index.esm.js",
+      "require": "./dist/src/react/index.cjs.js"
+    },
+    "./worker": "./dist/worker/sse.worker.js"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.4",
+    "@remember-web/shared": "^0.1.2"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.4",
+    "@babel/plugin-transform-runtime": "^7.24.3",
+    "@babel/preset-env": "^7.24.4",
+    "@babel/preset-react": "^7.24.1",
+    "@babel/preset-typescript": "^7.24.1",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^28.0.6",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^18.2.77",
+    "@types/react-dom": "^18.2.25",
+    "jsdom": "^26.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^4.44.1",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "rollup-plugin-preserve-directives": "^0.4.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "tsc-alias": "^1.8.8",
+    "tsconfig": "0.0.2",
+    "tslib": "^2.6.2",
+    "typescript": "^5.4.5",
+    "vite-tsconfig-paths": "^5.1.4",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "typescript": ">=5.4"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/src/core/BaseSseClient.test.ts

@@ -0,0 +1,142 @@
+// @vitest-environment jsdom — attachAutoResume가 document·window에 배선하는 유일한 표면이라 이 파일만 jsdom입니다.
+// 나머지 공유 표면(on·onStatus)은 SseClientLike.contract.test.ts가 두 구현으로 고정합니다
+import { describe, expect, it, vi } from 'vitest';
+
+import { createSseClient } from '../createSseClient';
+import {
+  createHarness,
+  FakeEventSource,
+  lastSource,
+  openConnection,
+  setupFakeTimers,
+} from '../testing';
+
+setupFakeTimers();
+
+const createClientSpy = () => {
+  let connects = 0;
+  const client = createSseClient({
+    baseUrl: 'https://sse.example.com',
+    getAuthToken: () => 'token-1',
+  });
+  // connect 자체를 재우고 호출만 셉니다 — 여기서 볼 것은 "언제 불리는가"뿐입니다
+  client.connect = () => {
+    connects += 1;
+  };
+
+  return { client, connects: () => connects };
+};
+
+const setVisibility = (state: DocumentVisibilityState): void => {
+  Object.defineProperty(document, 'visibilityState', {
+    value: state,
+    configurable: true,
+  });
+  document.dispatchEvent(new Event('visibilitychange'));
+};
+
+const showPage = (persisted: boolean): void => {
+  window.dispatchEvent(new PageTransitionEvent('pageshow', { persisted }));
+};
+
+describe('attachAutoResume — 탭 복귀 배선', () => {
+  it('탭이 다시 보이면 connect를 부릅니다 — 얼어붙은 사이 수거됐어도 돌아옵니다', () => {
+    const { client, connects } = createClientSpy();
+    client.attachAutoResume();
+
+    setVisibility('visible');
+
+    expect(connects()).toBe(1);
+  });
+
+  it('탭이 숨을 때는 부르지 않습니다', () => {
+    const { client, connects } = createClientSpy();
+    client.attachAutoResume();
+
+    setVisibility('hidden');
+
+    expect(connects()).toBe(0);
+  });
+
+  // bfcache는 SharedWorker 포트를 evict하므로 visibilitychange로는 알 수 없습니다
+  it('bfcache에서 돌아오면 connect를 부릅니다', () => {
+    const { client, connects } = createClientSpy();
+    client.attachAutoResume();
+
+    showPage(true);
+
+    expect(connects()).toBe(1);
+  });
+
+  it('bfcache가 아닌 첫 로드에는 부르지 않습니다 — connect는 소비처가 이미 불렀습니다', () => {
+    const { client, connects } = createClientSpy();
+    client.attachAutoResume();
+
+    showPage(false);
+
+    expect(connects()).toBe(0);
+  });
+
+  it('떼면 더 부르지 않습니다 — 클라이언트를 버릴 때 누수가 남지 않게', () => {
+    const { client, connects } = createClientSpy();
+    const detach = client.attachAutoResume();
+
+    detach();
+    setVisibility('visible');
+    showPage(true);
+
+    expect(connects()).toBe(0);
+  });
+});
+
+describe('attachAutoResume — 끊은 쪽의 의도 존중', () => {
+  it('disconnect한 뒤에는 탭이 돌아와도 되살리지 않습니다 — 끊은 건 소비처의 판단입니다', () => {
+    const { client, connects } = createClientSpy();
+    client.attachAutoResume();
+    client.disconnect();
+
+    setVisibility('visible');
+
+    expect(connects()).toBe(0);
+  });
+
+  it('서버가 goaway(action: close)로 끊은 뒤에는 탭이 돌아와도 되살리지 않습니다', async () => {
+    const { client } = createHarness();
+    await openConnection(client);
+    client.attachAutoResume();
+
+    lastSource().dispatch(
+      'goaway',
+      JSON.stringify({ reason: 'user_logout', action: 'close' })
+    );
+    expect(client.status).toBe('closed');
+
+    setVisibility('visible');
+    await vi.advanceTimersByTimeAsync(0);
+
+    // 자동 재개가 서버의 close를 뒤집으면 재연결 티켓과 새 소스가 생깁니다
+    expect(FakeEventSource.instances).toHaveLength(1);
+    expect(client.status).toBe('closed');
+  });
+
+  // fatal의 회복 계약은 disconnect 후 connect라 자동 재개가 대신할 수 없습니다 — 시도하면 탭 전환마다 warn만 쌓입니다
+  it('fatal 상태에서는 탭이 돌아와도 connect를 시도하지 않습니다', async () => {
+    const warnings: string[] = [];
+    const { client, failTicketsWith } = createHarness({
+      logger: { warn: (message) => warnings.push(message), error: () => {} },
+    });
+    failTicketsWith(401);
+    client.connect();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(client.status).toBe('fatal');
+    client.attachAutoResume();
+    const warningsBefore = warnings.length;
+
+    setVisibility('visible');
+    setVisibility('visible');
+    await vi.advanceTimersByTimeAsync(0);
+
+    expect(warnings).toHaveLength(warningsBefore);
+    expect(client.status).toBe('fatal');
+  });
+});

package/src/core/BaseSseClient.ts

@@ -0,0 +1,103 @@
+import type { Emitter } from './emitter';
+import { createEmitter } from './emitter';
+import { isUndeliverableEvent } from './eventNames';
+import type {
+  PayloadOf,
+  SseClientLike,
+  SseEventHandler,
+  SseEventMap,
+  SseEventName,
+  SseLogger,
+  SseStatus,
+  Unsubscribe,
+} from './types';
+
+/**
+ * @description 두 구현이 공유하는 구독 표면 — 구독 장부(emitter)를 소유하고 on·onStatus를 확정합니다.
+ * 연결을 어떻게 다루는지는 모릅니다: 구현마다 다른 것만 추상 멤버로 남깁니다.
+ * 같아야 할 것을 한 벌로 두기 위한 클래스입니다 — 두 구현이 각자 배선하다 갈린 이력이 있습니다.
+ */
+export abstract class BaseSseClient<
+  M extends object = SseEventMap,
+> implements SseClientLike<M> {
+  declare readonly __eventMap?: M;
+
+  protected readonly emitter: Emitter;
+
+  constructor(protected readonly logger?: SseLogger) {
+    this.emitter = createEmitter(logger);
+  }
+
+  on<K extends SseEventName<M>>(
+    type: K,
+    handler: SseEventHandler<PayloadOf<M, K>>
+  ): Unsubscribe {
+    if (isUndeliverableEvent(type)) {
+      this.logger?.warn(
+        `sse: '${type}'는 SDK가 소비하는 예약 이벤트라 구독이 배달되지 않습니다`
+      );
+    }
+    this.registerSubscription(type);
+    return this.emitter.on(type, handler as SseEventHandler<unknown>);
+  }
+
+  onStatus(listener: (status: SseStatus) => void): Unsubscribe {
+    return this.emitter.onStatus(listener);
+  }
+
+  /**
+   * @description 탭이 돌아올 때 connect()를 다시 부릅니다 — 전원이 얼어붙어 접힌 연결(휴면)은
+   * 깨어난 탭의 이 호출만이 다시 세울 수 있습니다. 연결이 살아 있으면 아무 일도 없습니다.
+   * bfcache 복귀는 visibilitychange가 아니라 pageshow로만 알 수 있어 둘 다 봅니다.
+   * SSR에는 붙일 곳이 없어 아무 일도 하지 않습니다.
+   *
+   * @returns 리스너를 떼는 함수 — 클라이언트를 버릴 때 함께 부르세요
+   */
+  attachAutoResume(): Unsubscribe {
+    if (typeof document === 'undefined' || typeof window === 'undefined') {
+      return () => {};
+    }
+
+    // 되살릴 대상은 idle입니다 — 전원 침묵으로 접힌 휴면이 이 상태입니다(workerConnection.close).
+    // closed(소비처 disconnect·서버 goaway close)는 끊은 의도를 되살리지 않고,
+    // fatal의 회복 계약은 disconnect 후 connect라 자동 재개가 대신할 수 없습니다
+    const notifyAlive = (): void => {
+      if (this.status === 'closed' || this.status === 'fatal') {
+        return;
+      }
+      this.connect();
+    };
+
+    const onVisible = (): void => {
+      if (document.visibilityState === 'visible') {
+        notifyAlive();
+      }
+    };
+
+    // persisted = bfcache 복귀, 직결 경로용 — Chrome은 SharedWorker 페이지를 bfcache에 넣지 않고,
+    // 넣는 브라우저라면 포트가 이미 죽어 이 connect가 닿지 않습니다(알려진 한계)
+    const onPageShow = (event: PageTransitionEvent): void => {
+      if (event.persisted) {
+        notifyAlive();
+      }
+    };
+
+    document.addEventListener('visibilitychange', onVisible);
+    window.addEventListener('pageshow', onPageShow);
+
+    return () => {
+      document.removeEventListener('visibilitychange', onVisible);
+      window.removeEventListener('pageshow', onPageShow);
+    };
+  }
+
+  /**
+   * @description 구독이 등록될 때 각 구현이 할 일 — 열린 소스에 리스너를 붙이거나, 워커에 알리거나.
+   * 연결 전 구독도 여기로 오므로, 아직 붙일 곳이 없으면 조용히 넘어가야 합니다.
+   */
+  protected abstract registerSubscription(type: string): void;
+
+  abstract get status(): SseStatus;
+  abstract connect(): void;
+  abstract disconnect(): void;
+}