@cp949/iframecall 0.1.0

package/dist/host.js

@@ -0,0 +1,618 @@
+import {
+  createIframeCallError,
+  createIframeCallErrorResponse,
+  createIframeCallNotify,
+  createIframeCallRequest,
+  createIframeCallSuccessResponse,
+  createIframeWindowTransport,
+  isSerializedIframeCallError,
+  parseIframeCallMessage,
+  serializeIframeCallError
+} from "./chunk-UYZXYOI6.js";
+
+// src/host/consoleDebugLogger.ts
+function consoleDebugLogger(options = {}) {
+  const prefix = options.prefix ?? "[iframecall:host]";
+  const head = prefix.length > 0 ? `${prefix} ` : "";
+  return (event) => {
+    switch (event.type) {
+      case "commandSentToIframe":
+        console.debug(`${head}${event.type} ${event.command}`, event.args);
+        return;
+      case "commandResultReceivedFromIframe":
+        console.debug(`${head}${event.type} ${event.command}`, event.value);
+        return;
+      case "commandErrorReceivedFromIframe":
+        console.debug(`${head}${event.type} ${event.command}`, event.error);
+        return;
+      case "notificationReceivedFromIframe":
+        console.debug(`${head}${event.type} ${event.event}`, event.payload);
+        return;
+      case "readyReceived":
+        console.debug(`${head}${event.type}`, event.payload);
+        return;
+      case "terminatedReceived":
+        console.debug(`${head}${event.type} ${event.reason}`, event.error);
+        return;
+    }
+  };
+}
+
+// src/host/controllerLifecycle.ts
+function createControllerLifecycle(options) {
+  const { readyTimeoutMs, onTerminate } = options;
+  let readyFlag = false;
+  let terminatedError = null;
+  let cleanupDone = false;
+  let onCleanup = null;
+  let resolveReady;
+  let rejectReady;
+  const ready = new Promise((resolve, reject) => {
+    resolveReady = resolve;
+    rejectReady = reject;
+  });
+  ready.catch(() => {
+  });
+  let resolveTerminated;
+  const terminated = new Promise(
+    (resolve) => {
+      resolveTerminated = resolve;
+    }
+  );
+  const readyTimeoutId = readyTimeoutMs === 0 || readyTimeoutMs === Number.POSITIVE_INFINITY ? null : setTimeout(() => {
+    terminate(
+      createIframeCallError("timeout", "Iframe ready timed out.", {
+        details: { timeoutMs: readyTimeoutMs }
+      })
+    );
+  }, readyTimeoutMs);
+  function clearReadyTimeout() {
+    if (readyTimeoutId !== null) {
+      clearTimeout(readyTimeoutId);
+    }
+  }
+  function markReady() {
+    if (terminatedError !== null || readyFlag) {
+      return;
+    }
+    readyFlag = true;
+    clearReadyTimeout();
+    resolveReady();
+  }
+  function terminate(error) {
+    if (terminatedError !== null) {
+      return;
+    }
+    terminatedError = error;
+    clearReadyTimeout();
+    rejectReady(error);
+    resolveTerminated(error);
+    onTerminate(error);
+    cleanup();
+  }
+  function cleanup() {
+    if (cleanupDone) {
+      return;
+    }
+    cleanupDone = true;
+    onCleanup?.();
+  }
+  return {
+    ready,
+    terminated,
+    isReady: () => readyFlag,
+    isTerminated: () => terminatedError !== null,
+    getTerminatedError: () => terminatedError,
+    markReady,
+    terminate,
+    setOnCleanup(fn) {
+      onCleanup = fn;
+    },
+    cleanup
+  };
+}
+
+// src/host/notifyHandlerRegistry.ts
+function createNotifyHandlerRegistry() {
+  const handlers = /* @__PURE__ */ new Map();
+  return {
+    register(event, handler) {
+      const set = handlers.get(event) ?? /* @__PURE__ */ new Set();
+      set.add(handler);
+      handlers.set(event, set);
+      return () => {
+        set.delete(handler);
+        if (set.size === 0) {
+          handlers.delete(event);
+        }
+      };
+    },
+    dispatch(event, payload) {
+      const set = handlers.get(event);
+      if (set === void 0) {
+        return;
+      }
+      for (const handler of set) {
+        handler(payload);
+      }
+    },
+    clear() {
+      handlers.clear();
+    }
+  };
+}
+
+// src/host/pendingCallRegistry.ts
+function createPendingCallRegistry(transport, targetOrigin) {
+  const pending = /* @__PURE__ */ new Map();
+  function clearCallTimeout(call) {
+    if (call.timeoutId !== null) {
+      clearTimeout(call.timeoutId);
+    }
+  }
+  return {
+    add(id, call) {
+      pending.set(id, call);
+    },
+    delete(id) {
+      pending.delete(id);
+    },
+    settle(id, response) {
+      const call = pending.get(id);
+      if (call === void 0) {
+        return;
+      }
+      pending.delete(id);
+      clearCallTimeout(call);
+      if (response.ok) {
+        call.resolve(response.value);
+        return;
+      }
+      call.reject(response.error);
+    },
+    post(id, cmd, args, transfer) {
+      try {
+        transport.post(
+          createIframeCallRequest(id, cmd, args),
+          targetOrigin,
+          transfer
+        );
+      } catch (error) {
+        const call = pending.get(id);
+        pending.delete(id);
+        if (call !== void 0) {
+          clearCallTimeout(call);
+          call.reject(
+            createIframeCallError(
+              "invalid_args",
+              "Failed to post command request.",
+              {
+                command: cmd,
+                details: error
+              }
+            )
+          );
+        }
+      }
+    },
+    rejectAll(buildError) {
+      for (const [, call] of pending) {
+        clearCallTimeout(call);
+        call.reject(buildError(call.command));
+      }
+      pending.clear();
+    },
+    getCommand(id) {
+      return pending.get(id)?.command;
+    }
+  };
+}
+
+// src/host/readyQueue.ts
+function createReadyQueue() {
+  const queued = /* @__PURE__ */ new Map();
+  function clearCallTimeout(call) {
+    if (call.timeoutId !== null) {
+      clearTimeout(call.timeoutId);
+    }
+  }
+  return {
+    size() {
+      return queued.size;
+    },
+    add(id, call) {
+      queued.set(id, call);
+    },
+    delete(id) {
+      queued.delete(id);
+    },
+    flush(forward) {
+      for (const [id, call] of queued) {
+        queued.delete(id);
+        forward(id, call);
+      }
+    },
+    rejectAll(buildError) {
+      for (const [, call] of queued) {
+        clearCallTimeout(call);
+        call.reject(buildError(call.command));
+      }
+      queued.clear();
+    }
+  };
+}
+
+// src/host/controller.ts
+function createIframeCallController(options) {
+  const targetOrigin = requireTargetOrigin(options.targetOrigin);
+  const allowedOrigins = new Set(options.allowedOrigins ?? [targetOrigin]);
+  const transport = options.transport ?? createIframeWindowTransport(options.iframe);
+  const generateId = options.generateId ?? crypto.randomUUID.bind(crypto);
+  const defaultTimeoutMs = options.defaultTimeoutMs ?? 3e4;
+  const readyTimeoutMs = options.readyTimeoutMs ?? defaultTimeoutMs;
+  const readyPolicy = options.readyPolicy ?? "queue";
+  const readyQueueLimit = options.readyQueueLimit ?? Number.POSITIVE_INFINITY;
+  const pending = createPendingCallRegistry(transport, targetOrigin);
+  const queue = createReadyQueue();
+  const notifyRegistry = createNotifyHandlerRegistry();
+  const debugSubscribers = /* @__PURE__ */ new Set();
+  function emitDebug(event) {
+    for (const handler of debugSubscribers) {
+      try {
+        handler(event);
+      } catch (error) {
+        options.logger?.warn("iframecall debug subscriber threw.", error);
+      }
+    }
+  }
+  const lifecycle = createControllerLifecycle({
+    readyTimeoutMs,
+    onTerminate(error) {
+      const buildLifecycleError = (command) => createCallLifecycleError(error, command);
+      pending.rejectAll(buildLifecycleError);
+      queue.rejectAll(buildLifecycleError);
+    }
+  });
+  const unsubscribeTransport = transport.subscribe(
+    createTransportRouter({
+      lifecycle,
+      allowedOrigins,
+      transport,
+      pending,
+      queue,
+      notifyRegistry,
+      logger: options.logger,
+      emitDebug
+    })
+  );
+  lifecycle.setOnCleanup(() => {
+    unsubscribeTransport();
+    notifyRegistry.clear();
+  });
+  const controller = {
+    ready: lifecycle.ready,
+    terminated: lifecycle.terminated,
+    call(cmd, args, callOptions) {
+      const terminatedError = lifecycle.getTerminatedError();
+      if (terminatedError !== null) {
+        return Promise.reject(terminatedError);
+      }
+      if (!lifecycle.isReady() && readyPolicy === "reject") {
+        return Promise.reject(
+          createIframeCallError("not_ready", "Iframe is not ready.", {
+            command: cmd
+          })
+        );
+      }
+      const id = generateId();
+      const timeoutMs = callOptions?.timeoutMs ?? defaultTimeoutMs;
+      return new Promise((resolve, reject) => {
+        const timeoutId = timeoutMs === 0 || timeoutMs === Number.POSITIVE_INFINITY ? null : setTimeout(() => {
+          pending.delete(id);
+          queue.delete(id);
+          reject(
+            createIframeCallError("timeout", "Command timed out.", {
+              command: cmd,
+              details: { timeoutMs }
+            })
+          );
+        }, timeoutMs);
+        const call = {
+          command: cmd,
+          timeoutId,
+          resolve,
+          reject
+        };
+        if (!lifecycle.isReady()) {
+          if (queue.size() >= readyQueueLimit) {
+            if (timeoutId !== null) {
+              clearTimeout(timeoutId);
+            }
+            reject(
+              createIframeCallError(
+                "queue_overflow",
+                "Ready queue overflow.",
+                {
+                  command: cmd,
+                  details: { readyQueueLimit }
+                }
+              )
+            );
+            return;
+          }
+          queue.add(id, {
+            ...call,
+            args,
+            transfer: callOptions?.transfer
+          });
+          return;
+        }
+        emitDebug({ type: "commandSentToIframe", command: cmd, args });
+        pending.add(id, call);
+        pending.post(id, cmd, args, callOptions?.transfer);
+      });
+    },
+    onNotificationFromIframe(event, handler) {
+      return notifyRegistry.register(
+        event,
+        handler
+      );
+    },
+    debug: {
+      subscribe(handler) {
+        debugSubscribers.add(handler);
+        return () => {
+          debugSubscribers.delete(handler);
+        };
+      }
+    },
+    async dispose(reason = "host_requested") {
+      if (lifecycle.isTerminated()) {
+        lifecycle.cleanup();
+        return;
+      }
+      const lifecycleError = createIframeCallError(
+        "terminated",
+        "Controller disposed.",
+        {
+          details: { reason }
+        }
+      );
+      try {
+        transport.post(
+          createIframeCallRequest(generateId(), "host:dispose", [{ reason }]),
+          targetOrigin
+        );
+      } catch (error) {
+        options.logger?.warn("iframecall dispose message failed.", error);
+      } finally {
+        lifecycle.terminate(lifecycleError);
+        lifecycle.cleanup();
+      }
+    }
+  };
+  return controller;
+}
+function createTransportRouter(deps) {
+  const {
+    lifecycle,
+    allowedOrigins,
+    transport,
+    pending,
+    queue,
+    notifyRegistry,
+    logger,
+    emitDebug
+  } = deps;
+  return (event) => {
+    if (lifecycle.isTerminated()) return;
+    if (!allowedOrigins.has(event.origin)) return;
+    if (transport.expectedSource !== void 0 && event.source !== transport.expectedSource) {
+      return;
+    }
+    const parsed = parseIframeCallMessage(event.data);
+    if (parsed?.type === "response") {
+      const responseMessage = parsed.message;
+      const command = pending.getCommand(responseMessage.id);
+      pending.settle(responseMessage.id, responseMessage);
+      if (command !== void 0) {
+        if (responseMessage.ok) {
+          emitDebug({
+            type: "commandResultReceivedFromIframe",
+            command,
+            value: responseMessage.value
+          });
+        } else {
+          emitDebug({
+            type: "commandErrorReceivedFromIframe",
+            command,
+            error: responseMessage.error
+          });
+        }
+      }
+      return;
+    }
+    if (parsed?.type !== "notify") return;
+    const { event: notifyEvent, payload } = parsed.message;
+    if (notifyEvent === "ready") {
+      handleReadyNotify(payload, lifecycle, queue, pending, logger, emitDebug);
+      return;
+    }
+    if (notifyEvent === "terminated") {
+      const terminatedPayload = isRecord(payload) ? payload : {};
+      const reason = typeof terminatedPayload.reason === "string" ? terminatedPayload.reason : "unknown";
+      const cause = getTerminatedCause(payload);
+      emitDebug({
+        type: "terminatedReceived",
+        reason,
+        error: cause ?? null
+      });
+      lifecycle.terminate(
+        createIframeCallError("terminated", "Iframe terminated.", {
+          cause,
+          details: payload
+        })
+      );
+      return;
+    }
+    notifyRegistry.dispatch(notifyEvent, payload);
+    emitDebug({
+      type: "notificationReceivedFromIframe",
+      event: notifyEvent,
+      payload
+    });
+  };
+}
+function handleReadyNotify(payload, lifecycle, queue, pending, logger, emitDebug) {
+  if (lifecycle.isReady()) {
+    logger?.warn("iframecall duplicate ready ignored.", payload);
+    return;
+  }
+  if (!isSupportedReadyPayload(payload)) {
+    lifecycle.terminate(
+      createIframeCallError(
+        "version_mismatch",
+        "Unsupported iframecall protocol version.",
+        { details: payload }
+      )
+    );
+    return;
+  }
+  emitDebug({ type: "readyReceived", payload });
+  lifecycle.markReady();
+  queue.flush((id, call) => {
+    emitDebug({
+      type: "commandSentToIframe",
+      command: call.command,
+      args: call.args
+    });
+    pending.add(id, call);
+    pending.post(id, call.command, call.args, call.transfer);
+  });
+}
+function createCallLifecycleError(error, command) {
+  if (error.code !== "timeout" || error.command !== void 0) {
+    return error;
+  }
+  return {
+    ...error,
+    command
+  };
+}
+function getTerminatedCause(payload) {
+  if (!isRecord(payload) || !isSerializedIframeCallError(payload.error)) {
+    return void 0;
+  }
+  return payload.error;
+}
+function isSupportedReadyPayload(payload) {
+  return isRecord(payload) && payload.protocolVersion === 1;
+}
+function requireTargetOrigin(targetOrigin) {
+  if (targetOrigin.length === 0 || targetOrigin === "*" || targetOrigin === "null") {
+    throw createIframeCallError(
+      "invalid_origin",
+      "targetOrigin must be explicit."
+    );
+  }
+  return targetOrigin;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+
+// src/host/useIframeCallController.tsx
+import { useCallback, useEffect, useRef, useState } from "react";
+function useIframeCallController(options) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const iframeElRef = useRef(null);
+  const [iframeAttached, setIframeAttached] = useState(false);
+  const [controller, setController] = useState(null);
+  const [status, setStatus] = useState("pending");
+  const [terminationError, setTerminationError] = useState(null);
+  const [readyError, setReadyError] = useState(null);
+  const iframeRef = useCallback((node) => {
+    iframeElRef.current = node;
+    setIframeAttached(node !== null);
+  }, []);
+  useEffect(() => {
+    if (!iframeAttached) return;
+    const iframeEl = iframeElRef.current;
+    if (iframeEl === null) return;
+    const opts = optionsRef.current;
+    const next = createIframeCallController({
+      iframe: iframeEl,
+      targetOrigin: opts.targetOrigin,
+      allowedOrigins: opts.allowedOrigins,
+      defaultTimeoutMs: opts.defaultTimeoutMs,
+      generateId: opts.generateId,
+      logger: opts.logger,
+      readyPolicy: opts.readyPolicy,
+      readyQueueLimit: opts.readyQueueLimit,
+      readyTimeoutMs: opts.readyTimeoutMs,
+      transport: opts.transport
+    });
+    let cancelled = false;
+    setController(
+      next
+    );
+    setStatus("pending");
+    setTerminationError(null);
+    setReadyError(null);
+    next.ready.then(
+      () => {
+        if (cancelled) return;
+        setStatus("ready");
+      },
+      (error) => {
+        if (cancelled) return;
+        setReadyError(error);
+        setStatus((prev) => prev === "terminated" ? prev : "failed");
+      }
+    );
+    next.terminated.then((reason) => {
+      if (cancelled) return;
+      setTerminationError(reason);
+      setStatus("terminated");
+    });
+    let unsubscribeDebug = null;
+    const debugLog = opts.debugLog;
+    if (debugLog) {
+      const prefix = typeof debugLog === "object" && debugLog !== null ? debugLog.prefix : void 0;
+      const handler = consoleDebugLogger(
+        prefix !== void 0 ? { prefix } : void 0
+      );
+      unsubscribeDebug = next.debug.subscribe(handler);
+    }
+    return () => {
+      cancelled = true;
+      if (unsubscribeDebug !== null) {
+        unsubscribeDebug();
+      }
+      void next.dispose("host-unmount");
+      setController(null);
+    };
+  }, [iframeAttached]);
+  return {
+    iframeRef,
+    controller,
+    status,
+    terminationError,
+    readyError
+  };
+}
+export {
+  consoleDebugLogger,
+  createIframeCallController,
+  createIframeCallError,
+  createIframeCallErrorResponse,
+  createIframeCallNotify,
+  createIframeCallRequest,
+  createIframeCallSuccessResponse,
+  createIframeWindowTransport,
+  isSerializedIframeCallError,
+  parseIframeCallMessage,
+  serializeIframeCallError,
+  useIframeCallController
+};

package/dist/iframe.d.ts

@@ -0,0 +1,67 @@
+import { x as IframeDebugEvent, C as CommandMap, y as IframeCallRunnerOptions, z as IframeCallRunnerHandle, A as CommandsConstructor, B as IframeCallRunnerClassOptions, D as IframeHelper } from './messages-Cg4n93bf.js';
+export { b as CommandArgs, c as CommandHandler, d as CommandResult, e as CommandRunner, E as DomainNotificationKey, f as IframeCallCallOptions, g as IframeCallLogger, h as IframeCallNotify, i as IframeCallRequest, j as IframeCallResponse, k as IframeCallTransferable, l as IframeCallTransport, m as IframeCallTransportEvent, N as NotifyHandler, P as ParsedIframeCallMessage, R as ReadyPolicy, n as ReservedNotificationName, S as SerializedIframeCallError, o as createIframeCallError, p as createIframeCallErrorResponse, q as createIframeCallNotify, r as createIframeCallRequest, s as createIframeCallSuccessResponse, F as createParentWindowTransport, u as isSerializedIframeCallError, v as parseIframeCallMessage, w as serializeIframeCallError } from './messages-Cg4n93bf.js';
+
+/** consoleDebugLogger 옵션. prefix를 명시하지 않으면 [iframecall:iframe]가 기본값이다. */
+type ConsoleDebugLoggerOptions = {
+    readonly prefix?: string;
+};
+/**
+ * iframe runner의 iframeHelper.debug.subscribe에 그대로 넘길 수 있는 console.debug 출력 함수.
+ * event type별로 핵심 식별자(command/event)를 첫 인자에 포함하고,
+ * raw payload(args/value/error/payload)를 두 번째 인자로 전달한다.
+ */
+declare function consoleDebugLogger(options?: ConsoleDebugLoggerOptions): (event: IframeDebugEvent) => void;
+
+/**
+ * iframecall iframe runner를 생성한다.
+ * `{ Commands }` class 옵션을 받아 dispatch lookup을 만들고,
+ * 도메인 코드가 host로 notify를 보낼 수 있는 helper를 함께 노출한다.
+ * 두 번째 generic은 host로 보낼 notify event/payload 타입 추론에 사용한다.
+ */
+declare function createIframeCallRunner<TCommands extends CommandMap<TCommands>, TNotificationsToHost = Record<string, unknown>>(options: IframeCallRunnerOptions<TCommands, TNotificationsToHost>): IframeCallRunnerHandle<TCommands, TNotificationsToHost>;
+
+/** debugLog 옵션. true면 자동 구독, prefix override 가능. false/undefined면 미구독. */
+type UseIframeCallRunnerDebugLog = boolean | {
+    readonly prefix?: string;
+};
+/**
+ * useIframeCallRunner에 전달하는 옵션.
+ * IframeCallRunnerClassOptions의 transport, logger, onHostDispose도 그대로 전달할 수 있다.
+ */
+type UseIframeCallRunnerOptions<TCommands, TNotificationsToHost = Record<string, unknown>> = {
+    /** postMessage targetOrigin. 빈 문자열이나 "*"은 runner 내부에서 거부된다. */
+    readonly targetOrigin: string;
+    /** 허용할 origin 목록. 생략하면 targetOrigin 하나만 허용한다. */
+    readonly allowedOrigins?: readonly string[];
+    /** runner가 new해서 iframeHelper를 주입할 Commands class. */
+    readonly Commands: CommandsConstructor<TCommands, TNotificationsToHost>;
+    /** true 또는 { prefix }이면 mount 시 consoleDebugLogger를 자동 구독한다. */
+    readonly debugLog?: UseIframeCallRunnerDebugLog;
+} & Pick<IframeCallRunnerClassOptions<TCommands, TNotificationsToHost>, "logger" | "onHostDispose" | "transport">;
+/**
+ * useIframeCallRunner가 반환하는 handle.
+ * mount 전에는 모든 값이 undefined / false이며, mount 후 runner가 생성되면 채워진다.
+ */
+type UseIframeCallRunnerResult<TCommands, TNotificationsToHost = Record<string, unknown>> = {
+    /** runner가 생성한 Commands 인스턴스. mount 전 undefined. */
+    readonly commands: TCommands | undefined;
+    /** Commands constructor에 주입된 iframeHelper. mount 전 undefined. */
+    readonly iframeHelper: IframeHelper<TNotificationsToHost> | undefined;
+    /** runner handle 전체. mount 전 undefined. */
+    readonly runner: IframeCallRunnerHandle<TCommands, TNotificationsToHost> | undefined;
+    /** runner가 활성화되어 있으면 true. mount 전 false. */
+    readonly isActive: boolean;
+};
+/**
+ * IframeCallRunner를 React lifecycle에 묶는 hook.
+ * mount 시 runner를 한 번만 생성하고, unmount 시 dispose한다.
+ * re-render로 인한 runner 재생성을 방지하기 위해 handle을 ref에 보관한다.
+ * unmount cleanup은 transport/runner dispose만 수행하고 isActive 전환은 하지 않는다.
+ * StrictMode의 mount→unmount→re-mount 사이클에서도 inactive 상태가 외부에 노출되지 않도록 보장한다.
+ *
+ * TCommands는 Commands class가 구현하는 command interface여야 한다.
+ * class 자체가 아니라 command method만 포함하는 타입을 전달해야 CommandMap constraint를 만족한다.
+ */
+declare function useIframeCallRunner<TCommands extends CommandMap<TCommands>, TNotificationsToHost = Record<string, unknown>>(options: UseIframeCallRunnerOptions<TCommands, TNotificationsToHost>): UseIframeCallRunnerResult<TCommands, TNotificationsToHost>;
+
+export { CommandMap, CommandsConstructor, IframeCallRunnerClassOptions, IframeCallRunnerHandle, IframeCallRunnerOptions, IframeDebugEvent, IframeHelper, type UseIframeCallRunnerDebugLog, type UseIframeCallRunnerOptions, type UseIframeCallRunnerResult, consoleDebugLogger, createIframeCallRunner, useIframeCallRunner };