@interactive-inc/flume 0.6.0 → 0.9.0

package/dist/index.d.ts

@@ -1,15 +1,21 @@
-import { C as FlumeSourceStartContext, D as FlumeStatusHandler, E as FlumeStatusEvent, O as FlumeTimerHandle, S as FlumeSourceName, T as FlumeStatus, _ as FlumeSlackConnectionResponse, a as FlumeEventHandler, b as FlumeSlackSourceOptions, c as FlumeGitHubNotification, d as FlumeLogHandler, f as FlumeLogInput, g as FlumeRuntimeDeps, h as FlumeReconnectOptions, i as FlumeEvent, k as FlumeLogger, l as FlumeGitHubSourceOptions, m as FlumeReconnectConfig, n as FlumeDiscordEvent, o as FlumeGatewayMessage, p as FlumeLogLevel, r as FlumeDiscordSourceOptions, s as FlumeGitHubEvent, t as FlumeSource, u as FlumeLog, v as FlumeSlackEnvelope, w as FlumeSourceStatus, x as FlumeSourceLocalStatusHandler, y as FlumeSlackEvent } from "./flume-source-DuUFPhSe.js";
+import { A as FlumeStreamOverflow, C as FlumeSourceName, D as FlumeStreamHandler, E as FlumeStatus, F as FlumeTimerHandle, I as FlumeLogger, M as FlumeTimeMessage, N as FlumeTimeSourceOptions, O as FlumeStreamItem, P as FlumeTimeTick, S as FlumeSourceLocalStatusHandler, T as FlumeSourceStatus, _ as FlumeRuntimeDeps, a as FlumeEvent, b as FlumeSlackEvent, c as FlumeGitHubEvent, d as FlumeLog, f as FlumeLogHandler, g as FlumeReconnectOptions, h as FlumeReconnectConfig, i as FlumeErrorHandler, j as FlumeTimeEvent, k as FlumeStreamOptions, l as FlumeGitHubNotification, m as FlumeLogLevel, n as FlumeDiscordEvent, o as FlumeEventHandler, p as FlumeLogInput, r as FlumeDiscordSourceOptions, s as FlumeGatewayMessage, t as FlumeSource, u as FlumeGitHubSourceOptions, v as FlumeSlackConnectionResponse, w as FlumeSourceStartContext, x as FlumeSlackSourceOptions, y as FlumeSlackEnvelope } from "./flume-source.js";
+import { t as FlumeParseError } from "./parse-error.js";
 
 //#region lib/deps.d.ts
 /**
  * platform 既定の IO を束ねた `FlumeRuntimeDeps`。
  * `FlumeTimerHandle` は不透明型 (`unknown`) のため、setTimeout / clearTimeout の戻り値・引数を
- * platform 型と橋渡しする際に境界で `as unknown as` を使う (IO 境界の最終手段)
+ * platform 型と橋渡しする際に境界で `as unknown as` を使う (IO 境界の最終手段)。
+ *
+ * `WebSocket` を含む全 IO は呼び出しごとに `globalThis` から引く lazy lookup。
+ * モジュール初期化後に `globalThis.WebSocket` が差し替わる環境
+ * (テストの `beforeEach` パッチ、jsdom などのブラウザ環境エミュレータ) でも
+ * `createFlumeDefaultDeps()` が返した deps が常に最新の参照を見る。
  */
 declare function createFlumeDefaultDeps(): FlumeRuntimeDeps;
 //#endregion
 //#region lib/errors/connection-error.d.ts
-type Options$3 = {
+type Options$1 = {
   cause?: unknown;
   code?: number;
 };
@@ -19,107 +25,204 @@ type Options$3 = {
  */
 declare class FlumeConnectionError extends Error {
   readonly code: number | null;
-  constructor(message: string, options?: Options$3);
+  constructor(message: string, options?: Options$1);
 }
 //#endregion
 //#region lib/errors/http-error.d.ts
-type Props$2 = {
+type Props$4 = {
   message: string;
   status: number;
   cause?: unknown;
 };
 declare class FlumeHttpError extends Error {
   readonly status: number;
-  constructor(props: Props$2);
+  constructor(props: Props$4);
 }
 //#endregion
-//#region lib/errors/parse-error.d.ts
-type Options$2 = {
+//#region lib/errors/start-error.d.ts
+type Options = {
   cause?: unknown;
 };
-declare class FlumeParseError extends Error {
-  constructor(message: string, options?: Options$2);
+declare class FlumeStartError extends Error {
+  constructor(message: string, options?: Options);
 }
 //#endregion
-//#region lib/errors/start-error.d.ts
-type Options$1 = {
-  cause?: unknown;
+//#region lib/flume-stream.d.ts
+type Props$3 = {
+  buffer: number;
+  onOverflow: FlumeStreamOverflow;
+  onClose: () => void;
 };
-declare class FlumeStartError extends Error {
-  constructor(message: string, options?: Options$1);
+/**
+ * push (`FlumeStreamHub.publish`) を pull (`for await`) に変換する async iterator。
+ * consumer が待っていれば即 resolve、いなければ buffer に積み、溢れたら onOverflow に従う。
+ * `return()` (break / 例外) と hub.close() のどちらでも自然に done へ落ちる
+ */
+declare class FlumeStream implements AsyncIterableIterator<FlumeStreamItem> {
+  private readonly props;
+  private readonly items;
+  private readonly resolvers;
+  private closed;
+  constructor(props: Props$3);
+  push(item: FlumeStreamItem): void;
+  close(): void;
+  next(): Promise<IteratorResult<FlumeStreamItem>>;
+  return(): Promise<IteratorResult<FlumeStreamItem>>;
+  [Symbol.asyncIterator](): AsyncIterableIterator<FlumeStreamItem>;
 }
 //#endregion
-//#region lib/flume-stopped.d.ts
-type Props$1 = {
+//#region lib/flume-stream-hub.d.ts
+/**
+ * firehose (`onEvent` / `stream()`) の item を複数の pull consumer へ fan-out する内部ハブ。
+ * subscriber が居なければ publish は実質 no-op。Flume 停止時に close() で全 stream を終端する
+ */
+declare class FlumeStreamHub {
+  private readonly streams;
+  private closed;
+  publish(item: FlumeStreamItem): void;
+  subscribe(options?: FlumeStreamOptions): FlumeStream;
+  close(): void;
+}
+//#endregion
+//#region lib/flume-closed.d.ts
+type FlumeCloseError = {
+  source: string;
+  error: Error;
+};
+type Props$2 = {
   finalStatuses: ReadonlyArray<FlumeSourceStatus>;
+  closeErrors: ReadonlyArray<FlumeCloseError>;
 };
 /**
- * 停止済みの終端状態。最終ステータスのスナップショットのみ観測できる
+ * 停止済みの終端状態。最終ステータスと、停止時に source.disconnect が throw した
+ * エラー一覧を観測できる。`errors()` を読めば `onLog` を grep せずに「どの source が
+ * きれいに close したか / どれが失敗したか」を直接判定できる
  */
-declare class FlumeStopped {
+declare class FlumeClosed {
   private readonly props;
-  readonly kind: "stopped";
-  constructor(props: Props$1);
+  readonly kind: "closed";
+  constructor(props: Props$2);
   statuses(): ReadonlyArray<FlumeSourceStatus>;
+  /**
+   * `runClose` 中に `source.stop()` が rejected で settle した source の名前と
+   * 正規化済み Error の組。`onEvent` firehose の `flume.close.failed` log と 1:1 対応する。
+   * 全 source が clean close した場合は空配列。
+   */
+  errors(): ReadonlyArray<FlumeCloseError>;
 }
 //#endregion
 //#region lib/flume-running.d.ts
-type Props = {
+type Props$1 = {
   sources: ReadonlyArray<FlumeSource>;
   signal?: AbortSignal;
   log: FlumeLogger;
+  hub: FlumeStreamHub;
 };
 /**
- * 稼働中の Flume。stop() で FlumeStopped へ遷移する。signal が abort されると自動 stop。
+ * 稼働中の Flume。close() で FlumeClosed へ遷移する。signal が abort されると自動 close。
  * 全ての source 呼び出し・signal 操作・status 読み取りを `attempt` 経由で扱い、
- * `runStop` の最外殻 try/catch で想定外の throw も `FlumeStopped` の resolve に変換する
+ * `runClose` の最外殻 try/catch で想定外の throw も `FlumeClosed` の resolve に変換する
  */
 declare class FlumeRunning {
   private readonly props;
   readonly kind: "running";
-  private stopPromise;
+  private closePromise;
   private readonly onAbort;
-  constructor(props: Props);
-  stop(): Promise<FlumeStopped>;
+  constructor(props: Props$1);
+  close(): Promise<FlumeClosed>;
   statuses(): ReadonlyArray<FlumeSourceStatus>;
-  private runStop;
+  /**
+   * 統合 firehose を pull で受け取る async iterator。`for await (const item of running.stream())`。
+   * item は events + 全ログの union (`FlumeStreamItem`)。`item.kind` で判別する。
+   * close() / signal abort で iterator は自然に終了し、`break` すると hub から自動 unsubscribe する。
+   * consumer が遅れて buffer を超えたら `onOverflow` (既定 drop-oldest) に従う
+   */
+  stream(options?: FlumeStreamOptions): AsyncIterableIterator<FlumeStreamItem>;
+  /**
+   * Host が `Flume({ signal })` で渡した AbortSignal をそのまま公開する。
+   * 直接の controller を持っていない呼び出し元が `running.signal?.aborted`
+   * で abort 状態を確認できる
+   */
+  get signal(): AbortSignal | undefined;
+  private runClose;
   private snapshotStatuses;
   private sourceName;
 }
 //#endregion
 //#region lib/flume.d.ts
-type Options = {
-  onEvent?: FlumeEventHandler;
+type FlumeOptions = {
+  /** 統合する Source 群 (必須) */sources: ReadonlyArray<FlumeSource>;
+  /**
+   * 統合 firehose (push)。events と全レベルのログを `FlumeStreamItem` の union で受ける。
+   * 使う側が `item.kind` ("event" | "log") と `item.log.level` で filter する。
+   * pull 版は `FlumeRunning.stream()`
+   */
+  onEvent?: FlumeStreamHandler; /** error レベルのログだけ (Sentry など error 専用の送信先用途)。firehose の error 部分の便利フィルタ */
+  onError?: FlumeErrorHandler;
   signal?: AbortSignal;
-  onLog?: FlumeLogHandler;
-  onStatus?: FlumeStatusHandler;
   deps?: FlumeRuntimeDeps;
   reconnect?: FlumeReconnectOptions;
 };
 /**
- * 起動前の Flume。`start()` で `FlumeRunning` へ遷移する。
- * 第一引数は sources、第二引数は cross-cutting options (全て optional)。
- * `onEvent` を省略するとイベントは黙って捨てられる (接続観測専用モード)。
+ * 起動前の Flume。`open()` で `FlumeRunning` へ遷移する。
+ * コンストラクタは単一オブジェクト `{ sources, ...options }` を受け取る (`sources` のみ必須)。
+ * events も全ログも 1 本の firehose (`onEvent` push / `stream()` pull) に流れ、購読側が filter する。
  * いずれかの source 失敗時は既に成功した source を全て `stop()` してロールバックし
  * `FlumeStartError` を返す。
  * `source.start()` / `source.stop()` の sync throw も `Promise.resolve().then` 経由で
- * Promise rejection に正規化して `allSettled` で捕捉する (`start()` は決して reject しない)
+ * Promise rejection に正規化して `allSettled` で捕捉する (`open()` は決して reject しない)
  */
 declare class Flume {
-  private readonly sources;
   private readonly options;
   private consumed;
   private readonly log;
   private readonly deps;
-  private readonly onEvent;
-  constructor(sources: ReadonlyArray<FlumeSource>, options?: Options);
-  start(): Promise<FlumeRunning | FlumeStartError>;
-  private guardStart;
+  private readonly sources;
+  private readonly sourceEventHandler;
+  private readonly hub;
+  constructor(options: FlumeOptions);
+  /** source が受信したログを firehose へ流す handler。error は onError にも分岐する */
+  private buildLogHandler;
+  /**
+   * firehose の単一 sink: pull の hub と push の onEvent の両方へ item を配る。
+   * onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する) ため
+   * 例外をここで握り潰す
+   */
+  private emitItem;
+  open(): Promise<FlumeRunning | FlumeStartError>;
+  private guardOpen;
   private isSignalAborted;
   private sourceName;
   private safeStart;
-  private notifyStatus;
   private rollback;
 }
 //#endregion
-export { Flume, FlumeConnectionError, type FlumeDiscordEvent, type FlumeDiscordSourceOptions, type FlumeEvent, type FlumeEventHandler, type FlumeGatewayMessage, type FlumeGitHubEvent, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackEvent, type FlumeSlackSourceOptions, FlumeSource, type FlumeSourceLocalStatusHandler, type FlumeSourceName, type FlumeSourceStartContext, type FlumeSourceStatus, FlumeStartError, type FlumeStatus, type FlumeStatusEvent, type FlumeStatusHandler, FlumeStopped, type FlumeTimerHandle, createFlumeDefaultDeps };
+//#region lib/flume-confluence.d.ts
+type Props = {
+  /** 配下の全 Flume の firehose をここへ合流させる単一 sink */onEvent?: FlumeStreamHandler; /** error レベル log だけ (全 Flume 共通) */
+  onError?: FlumeErrorHandler;
+  deps?: FlumeRuntimeDeps;
+  reconnect?: FlumeReconnectOptions;
+};
+/**
+ * 複数の `Flume` を束ねて動的に増減させる上位レイヤー。各 Flume は immutable のまま、
+ * `add()` で新しいグループを起動し `remove()` で個別に停止する。全グループの firehose は
+ * `onEvent` 1 本に合流する。Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
+ *
+ * id はグループの管理ハンドル (add/remove 用)。合流ストリーム自体は id を持たず、
+ * item の中の source 名で発信元を判別する。throw しない流儀に従い `add()` は `Error | null` を返す
+ */
+declare class FlumeConfluence {
+  private readonly props;
+  private readonly running;
+  constructor(props?: Props);
+  /** sources を 1 グループとして起動。id 重複や起動失敗は `Error` で返す (throw しない) */
+  add(id: string, sources: ReadonlyArray<FlumeSource>): Promise<Error | null>;
+  /** 指定グループだけ close。他グループは無停止。未知の id は no-op */
+  remove(id: string): Promise<void>;
+  closeAll(): Promise<void>;
+  has(id: string): boolean;
+  ids(): ReadonlyArray<string>;
+}
+//#endregion
+export { Flume, type FlumeCloseError, FlumeClosed, FlumeConfluence, FlumeConnectionError, type FlumeDiscordEvent, type FlumeDiscordSourceOptions, type FlumeErrorHandler, type FlumeEvent, type FlumeEventHandler, type FlumeGatewayMessage, type FlumeGitHubEvent, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, type FlumeOptions, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackEvent, type FlumeSlackSourceOptions, FlumeSource, type FlumeSourceLocalStatusHandler, type FlumeSourceName, type FlumeSourceStartContext, type FlumeSourceStatus, FlumeStartError, type FlumeStatus, type FlumeStreamHandler, type FlumeStreamItem, type FlumeStreamOptions, type FlumeStreamOverflow, type FlumeTimeEvent, type FlumeTimeMessage, type FlumeTimeSourceOptions, type FlumeTimeTick, type FlumeTimerHandle, createFlumeDefaultDeps };