durablews 1.0.1 → 2.0.0-alpha.1

package/dist/compat.cjs

@@ -0,0 +1,765 @@
+'use strict';
+
+// src/backoff.ts
+var RECONNECT_DEFAULTS = {
+  baseDelay: 500,
+  factor: 2,
+  maxDelay: 3e4,
+  jitter: true,
+  maxRetries: Number.POSITIVE_INFINITY,
+  shouldReconnect: () => true
+};
+function resolveReconnect(option) {
+  if (option === false) {
+    return null;
+  }
+  return { ...RECONNECT_DEFAULTS, ...option };
+}
+function computeDelay(attempt, options, random = Math.random) {
+  const exponential = Math.min(
+    options.maxDelay,
+    options.baseDelay * options.factor ** attempt
+  );
+  return options.jitter ? random() * exponential : exponential;
+}
+
+// src/codec.ts
+function safeJSONParse(data) {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}
+function isBinary(data) {
+  return data instanceof ArrayBuffer || ArrayBuffer.isView(data) || typeof Blob !== "undefined" && data instanceof Blob;
+}
+var jsonCodec = {
+  encode(data) {
+    if (typeof data === "string" || isBinary(data)) {
+      return data;
+    }
+    return JSON.stringify(data);
+  },
+  decode(data) {
+    return typeof data === "string" ? safeJSONParse(data) : data;
+  }
+};
+
+// src/fsm.ts
+var TRANSITIONS = {
+  idle: { CONNECT: "connecting" },
+  connecting: {
+    OPEN: "open",
+    CLOSE_REQUESTED: "closing",
+    CLOSED: "closed",
+    RETRY: "reconnecting"
+  },
+  open: {
+    CLOSE_REQUESTED: "closing",
+    CLOSED: "closed",
+    RETRY: "reconnecting"
+  },
+  closing: { CLOSED: "closed" },
+  // `reconnecting` = waiting out the backoff delay; no socket exists, so
+  // CLOSE_REQUESTED goes straight to `closed` (there is nothing to wait for)
+  // and OPEN/CLOSED cannot legally occur.
+  reconnecting: {
+    CONNECT: "connecting",
+    CLOSE_REQUESTED: "closed"
+  },
+  closed: { CONNECT: "connecting" }
+};
+function nextState(state, event) {
+  return TRANSITIONS[state][event] ?? null;
+}
+
+// src/heartbeat.ts
+var HEARTBEAT_TIMEOUT_CODE = 4408;
+function resolveHeartbeat(option) {
+  if (option === void 0) {
+    return null;
+  }
+  return {
+    interval: option.interval,
+    message: option.message ?? "ping",
+    timeout: option.timeout ?? option.interval
+  };
+}
+
+// src/helpers/event-bus.ts
+function defineEventBus() {
+  const listeners = /* @__PURE__ */ new Map();
+  function on(eventName, handler) {
+    const handlers = listeners.get(eventName) ?? [];
+    handlers.push(handler);
+    listeners.set(eventName, handlers);
+  }
+  function off(eventName, handler) {
+    const handlers = listeners.get(eventName);
+    if (!handlers) {
+      return;
+    }
+    listeners.set(
+      eventName,
+      handlers.filter((h) => h !== handler)
+    );
+  }
+  function once(eventName, handler) {
+    const onceHandler = (payload) => {
+      off(eventName, onceHandler);
+      handler(payload);
+    };
+    on(eventName, onceHandler);
+  }
+  function emit(eventName, payload) {
+    const handlers = listeners.get(eventName);
+    handlers?.forEach((fn) => {
+      fn(payload);
+    });
+  }
+  return { on, off, emit, once };
+}
+
+// src/pipeline.ts
+function runPipeline(middlewares, ctx, terminal) {
+  let invoked = -1;
+  function dispatch(i) {
+    if (i <= invoked) {
+      throw new Error("next() called multiple times");
+    }
+    invoked = i;
+    const middleware = middlewares[i];
+    if (!middleware) {
+      return terminal();
+    }
+    return middleware(ctx, () => dispatch(i + 1));
+  }
+  return dispatch(0);
+}
+
+// src/queue.ts
+var QUEUE_DEFAULTS = {
+  maxSize: 256
+};
+function resolveQueue(option) {
+  if (option === false) {
+    return null;
+  }
+  return { ...QUEUE_DEFAULTS, ...option };
+}
+
+// src/schema.ts
+var SchemaValidationError = class extends Error {
+  issues;
+  constructor(issues) {
+    super(
+      `Inbound message failed schema validation: ${issues.map((issue) => issue.message).join("; ")}`
+    );
+    this.name = "SchemaValidationError";
+    this.issues = issues;
+  }
+};
+
+// src/client.ts
+function client(config) {
+  const bus = defineEventBus();
+  const codec = config.codec ?? jsonCodec;
+  const reconnect = resolveReconnect(config.reconnect);
+  const queue = resolveQueue(config.queue);
+  const heartbeat = resolveHeartbeat(config.heartbeat);
+  const middlewares = [];
+  const outboundMiddlewares = [];
+  const queued = [];
+  let socket = null;
+  let state = "idle";
+  let lastError = null;
+  let lastInboundAt = 0;
+  let heartbeatTimer = null;
+  let heartbeatDeadline = null;
+  let outboundTail = null;
+  let requeueIndex = 0;
+  let closeRequested = false;
+  let retryAttempt = 0;
+  let retryTimer = null;
+  const subscribers = /* @__PURE__ */ new Set();
+  let snapshot = null;
+  let pending = null;
+  function notify() {
+    snapshot = null;
+    for (const listener of [...subscribers]) {
+      listener();
+    }
+  }
+  function transition(event) {
+    const next = nextState(state, event);
+    if (next === null || next === state) {
+      return null;
+    }
+    const previous = state;
+    state = next;
+    notify();
+    bus.emit("statechange", { previous, current: next });
+    return next;
+  }
+  function settleConnected() {
+    pending?.resolve();
+    pending = null;
+  }
+  function settleFailed(reason) {
+    pending?.reject(reason);
+    pending = null;
+  }
+  function clearRetryTimer() {
+    if (retryTimer !== null) {
+      clearTimeout(retryTimer);
+      retryTimer = null;
+    }
+  }
+  function stopHeartbeat() {
+    if (heartbeatTimer !== null) {
+      clearInterval(heartbeatTimer);
+      heartbeatTimer = null;
+    }
+    if (heartbeatDeadline !== null) {
+      clearTimeout(heartbeatDeadline);
+      heartbeatDeadline = null;
+    }
+  }
+  function startHeartbeat() {
+    if (heartbeat === null) {
+      return;
+    }
+    stopHeartbeat();
+    heartbeatTimer = setInterval(() => {
+      if (state !== "open" || !socket) {
+        return;
+      }
+      const pingSentAt = Date.now();
+      try {
+        socket.send(codec.encode(heartbeat.message));
+      } catch (error) {
+        bus.emit("error", toError(error));
+      }
+      if (heartbeatDeadline !== null) {
+        clearTimeout(heartbeatDeadline);
+      }
+      heartbeatDeadline = setTimeout(() => {
+        heartbeatDeadline = null;
+        if (state === "open" && socket && lastInboundAt < pingSentAt) {
+          const failure = new Error(
+            `Heartbeat timeout: no inbound traffic within ${heartbeat.timeout}ms of a ping`
+          );
+          lastError = failure;
+          notify();
+          bus.emit("error", failure);
+          socket.close(HEARTBEAT_TIMEOUT_CODE, "heartbeat timeout");
+        }
+      }, heartbeat.timeout);
+    }, heartbeat.interval);
+  }
+  function wire(transformed, original) {
+    if (socket && state === "open") {
+      socket.send(codec.encode(transformed));
+      return;
+    }
+    if (queue !== null && (state === "connecting" || state === "reconnecting")) {
+      if (queued.length >= queue.maxSize) {
+        bus.emit("drop", {
+          data: queued.shift(),
+          reason: "overflow"
+        });
+        if (requeueIndex > 0) {
+          requeueIndex -= 1;
+        }
+      }
+      queued.splice(requeueIndex, 0, original);
+      requeueIndex += 1;
+      notify();
+      return;
+    }
+    bus.emit("drop", { data: original, reason: "close" });
+  }
+  function runOutbound(data) {
+    const ctx = { data, client: api };
+    try {
+      const result = runPipeline(outboundMiddlewares, ctx, () => {
+        wire(ctx.data, data);
+      });
+      if (result instanceof Promise) {
+        return result.catch((error) => {
+          bus.emit("error", toError(error));
+        });
+      }
+    } catch (error) {
+      bus.emit("error", toError(error));
+    }
+  }
+  function transmit(data) {
+    if (outboundTail === null) {
+      const result = runOutbound(data);
+      if (result instanceof Promise) {
+        setOutboundTail(result);
+      }
+      return;
+    }
+    setOutboundTail(outboundTail.then(() => runOutbound(data)));
+  }
+  function setOutboundTail(run) {
+    const tail = run.then(() => {
+      if (outboundTail === tail) {
+        outboundTail = null;
+      }
+    });
+    outboundTail = tail;
+  }
+  function flushQueue() {
+    const hadQueued = queued.length > 0;
+    requeueIndex = 0;
+    while (queued.length > 0 && socket && state === "open") {
+      const data = queued.shift();
+      if (outboundMiddlewares.length === 0) {
+        try {
+          socket.send(codec.encode(data));
+        } catch (error) {
+          bus.emit("error", toError(error));
+        }
+      } else {
+        transmit(data);
+      }
+    }
+    if (hadQueued) {
+      notify();
+    }
+  }
+  function dropQueued() {
+    const hadQueued = queued.length > 0;
+    while (queued.length > 0) {
+      bus.emit("drop", { data: queued.shift(), reason: "close" });
+    }
+    if (hadQueued) {
+      notify();
+    }
+  }
+  function isRetryable(event) {
+    return reconnect !== null && !closeRequested && retryAttempt < reconnect.maxRetries && reconnect.shouldReconnect(event);
+  }
+  function openSocket() {
+    if (lastError !== null) {
+      lastError = null;
+      notify();
+    }
+    socket = config.protocols ? new WebSocket(config.url, config.protocols) : new WebSocket(config.url);
+    if (config.binaryType) {
+      socket.binaryType = config.binaryType;
+    }
+    socket.onopen = () => {
+      retryAttempt = 0;
+      transition("OPEN");
+      flushQueue();
+      startHeartbeat();
+      bus.emit("open");
+      settleConnected();
+    };
+    socket.onmessage = (event) => {
+      lastInboundAt = Date.now();
+      deliver(event.data);
+    };
+    socket.onerror = (event) => {
+      lastError = event;
+      notify();
+      bus.emit("error", event);
+    };
+    socket.onclose = (event) => {
+      const wasConnecting = state === "connecting";
+      socket = null;
+      stopHeartbeat();
+      requeueIndex = 0;
+      if (reconnect !== null && isRetryable(event)) {
+        retryAttempt += 1;
+        const delay = computeDelay(retryAttempt - 1, reconnect);
+        transition("RETRY");
+        bus.emit("close", event);
+        bus.emit("reconnecting", { attempt: retryAttempt, delay });
+        retryTimer = setTimeout(() => {
+          retryTimer = null;
+          if (transition("CONNECT") !== null) {
+            openSocket();
+          }
+        }, delay);
+        return;
+      }
+      transition("CLOSED");
+      dropQueued();
+      bus.emit("close", event);
+      if (wasConnecting || pending) {
+        settleFailed(
+          new Error(
+            retryAttempt > 0 ? `WebSocket reconnect gave up after ${retryAttempt} attempt(s) (code ${event.code})` : `WebSocket closed before opening (code ${event.code}${event.reason ? `: ${event.reason}` : ""})`
+          )
+        );
+      }
+    };
+  }
+  function deliver(raw) {
+    const decoded = codec.decode(raw);
+    if (config.schema === void 0) {
+      dispatchMessage(decoded);
+      return;
+    }
+    let result;
+    try {
+      result = config.schema["~standard"].validate(decoded);
+    } catch (error) {
+      bus.emit("error", toError(error));
+      return;
+    }
+    if (result instanceof Promise) {
+      result.then(handleValidated, (error) => {
+        bus.emit("error", toError(error));
+      });
+      return;
+    }
+    handleValidated(result);
+  }
+  function handleValidated(result) {
+    if (result.issues) {
+      bus.emit("error", new SchemaValidationError(result.issues));
+      return;
+    }
+    dispatchMessage(result.value);
+  }
+  function dispatchMessage(data) {
+    const ctx = { data, client: api };
+    const emit = () => {
+      bus.emit("message", ctx.data);
+    };
+    try {
+      const result = runPipeline(middlewares, ctx, emit);
+      if (result instanceof Promise) {
+        result.catch((error) => {
+          bus.emit("error", toError(error));
+        });
+      }
+    } catch (error) {
+      bus.emit("error", toError(error));
+    }
+  }
+  function ensurePending() {
+    if (pending) {
+      return pending.promise;
+    }
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    pending = { promise, resolve, reject };
+    return promise;
+  }
+  const api = {
+    get state() {
+      return state;
+    },
+    connect() {
+      if (state === "open") {
+        return Promise.resolve();
+      }
+      if (state === "connecting") {
+        return ensurePending();
+      }
+      if (state === "closing") {
+        return Promise.reject(
+          new Error(
+            "Cannot connect() while the connection is closing"
+          )
+        );
+      }
+      if (state === "reconnecting") {
+        clearRetryTimer();
+        const promise2 = ensurePending();
+        transition("CONNECT");
+        openSocket();
+        return promise2;
+      }
+      closeRequested = false;
+      retryAttempt = 0;
+      if (transition("CONNECT") === null) {
+        return Promise.reject(
+          new Error(`Cannot connect() from state "${state}"`)
+        );
+      }
+      const promise = ensurePending();
+      try {
+        openSocket();
+      } catch (error) {
+        transition("CLOSED");
+        socket = null;
+        settleFailed(toError(error));
+      }
+      return promise;
+    },
+    send(data) {
+      if (socket && state === "open") {
+        if (outboundMiddlewares.length === 0) {
+          socket.send(codec.encode(data));
+        } else {
+          transmit(data);
+        }
+        return;
+      }
+      if (queue !== null && (state === "connecting" || state === "reconnecting")) {
+        if (queued.length >= queue.maxSize) {
+          bus.emit("drop", {
+            data: queued.shift(),
+            reason: "overflow"
+          });
+        }
+        queued.push(data);
+        notify();
+        return;
+      }
+      throw new Error(
+        `Cannot send: connection is not open (state: "${state}")`
+      );
+    },
+    close(code, reason) {
+      closeRequested = true;
+      clearRetryTimer();
+      stopHeartbeat();
+      if (retryAttempt !== 0) {
+        retryAttempt = 0;
+        notify();
+      }
+      dropQueued();
+      if (state === "reconnecting") {
+        transition("CLOSE_REQUESTED");
+        settleFailed(
+          new Error("close() called before the connection opened")
+        );
+        return;
+      }
+      if (!socket) {
+        return;
+      }
+      transition("CLOSE_REQUESTED");
+      socket.close(code, reason);
+    },
+    on(event, handler) {
+      bus.on(event, handler);
+      return () => bus.off(event, handler);
+    },
+    use(middleware) {
+      if (typeof middleware === "function") {
+        middlewares.push(middleware);
+        return api;
+      }
+      if (middleware.inbound) {
+        middlewares.push(middleware.inbound);
+      }
+      if (middleware.outbound) {
+        outboundMiddlewares.push(middleware.outbound);
+      }
+      return api;
+    },
+    getState() {
+      if (snapshot === null) {
+        snapshot = Object.freeze({
+          state,
+          lastError,
+          retryAttempt,
+          queueLength: queued.length
+        });
+      }
+      return snapshot;
+    },
+    subscribe(listener) {
+      subscribers.add(listener);
+      return () => {
+        subscribers.delete(listener);
+      };
+    }
+  };
+  return api;
+}
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+
+// src/compat.ts
+var rawCodec = {
+  // The class's send() signature restricts inputs to WebSocket-sendable
+  // values, so the cast only widens what TypeScript already enforced there.
+  encode: (data) => data,
+  decode: (data) => data
+};
+var CloseEventCtor = typeof CloseEvent !== "undefined" ? CloseEvent : class extends Event {
+  code;
+  reason;
+  wasClean;
+  constructor(type, init = {}) {
+    super(type);
+    this.code = init.code ?? 0;
+    this.reason = init.reason ?? "";
+    this.wasClean = init.wasClean ?? false;
+  }
+};
+var DurableWebSocket = class _DurableWebSocket extends EventTarget {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSING = 2;
+  static CLOSED = 3;
+  CONNECTING = 0;
+  OPEN = 1;
+  CLOSING = 2;
+  CLOSED = 3;
+  /** The underlying durablews client — the escape hatch to the full API. */
+  client;
+  url;
+  /** Always `""` — see the known-deviations table in the docs. */
+  protocol = "";
+  /** Always `""` — see the known-deviations table in the docs. */
+  extensions = "";
+  /** Always `0` — see the known-deviations table in the docs. */
+  bufferedAmount = 0;
+  onopen = null;
+  onmessage = null;
+  onclose = null;
+  onerror = null;
+  #binaryType;
+  // Serializes Blob → ArrayBuffer conversions so message order survives the
+  // async hop when binaryType is reassigned after construction. While no
+  // conversion is pending, delivery is fully synchronous (native-faithful).
+  #deliveryChain = Promise.resolve();
+  #pendingDeliveries = 0;
+  constructor(url, protocols, options = {}) {
+    super();
+    this.url = String(url);
+    this.#binaryType = options.binaryType ?? "blob";
+    this.client = client({
+      ...options,
+      url,
+      protocols,
+      codec: rawCodec
+    });
+    this.client.on("open", () => {
+      const event = new Event("open");
+      this.dispatchEvent(event);
+      this.onopen?.call(this, event);
+    });
+    this.client.on("message", (data) => {
+      this.#deliverMessage(data);
+    });
+    this.client.on("close", (event) => {
+      const compatEvent = new CloseEventCtor("close", {
+        code: event.code,
+        reason: event.reason,
+        wasClean: event.wasClean
+      });
+      this.dispatchEvent(compatEvent);
+      this.onclose?.call(this, compatEvent);
+    });
+    this.client.on("error", () => {
+      const event = new Event("error");
+      this.dispatchEvent(event);
+      this.onerror?.call(this, event);
+    });
+    this.client.connect().catch(() => {
+    });
+  }
+  /**
+   * Maps the durable lifecycle onto the four native states. Deviation by
+   * design: during automatic reconnection this returns to `CONNECTING`,
+   * which a native (one-shot) socket can never do.
+   */
+  get readyState() {
+    switch (this.client.state) {
+      case "open":
+        return _DurableWebSocket.OPEN;
+      case "closing":
+        return _DurableWebSocket.CLOSING;
+      case "closed":
+        return _DurableWebSocket.CLOSED;
+      default:
+        return _DurableWebSocket.CONNECTING;
+    }
+  }
+  get binaryType() {
+    return this.#binaryType;
+  }
+  /**
+   * Honored at any time: when set to `"arraybuffer"` after construction,
+   * `Blob` frames are converted on delivery (order-preserving). Prefer
+   * passing `binaryType` in the constructor options, which configures the
+   * socket itself and avoids the conversion copy.
+   */
+  set binaryType(value) {
+    this.#binaryType = value;
+  }
+  /**
+   * Sends data, with durability semantics: while (re)connecting the message
+   * is queued and flushed on open (a native socket would throw). After
+   * `close()` it is silently discarded, matching native behavior.
+   */
+  send(data) {
+    if (this.client.state === "idle" || this.client.state === "closing" || this.client.state === "closed") {
+      return;
+    }
+    this.client.send(data);
+  }
+  close(code, reason) {
+    this.client.close(code, reason);
+  }
+  #deliverMessage(data) {
+    const dispatch = (value) => {
+      const event = new MessageEvent("message", { data: value });
+      this.dispatchEvent(event);
+      this.onmessage?.call(this, event);
+    };
+    if (this.#binaryType === "arraybuffer" && typeof Blob !== "undefined" && data instanceof Blob) {
+      this.#queueDelivery(async () => {
+        try {
+          dispatch(await blobToArrayBuffer(data));
+        } catch {
+          dispatch(data);
+        }
+      });
+      return;
+    }
+    if (this.#pendingDeliveries === 0) {
+      dispatch(data);
+      return;
+    }
+    this.#queueDelivery(() => {
+      dispatch(data);
+    });
+  }
+  #queueDelivery(deliver) {
+    this.#pendingDeliveries += 1;
+    this.#deliveryChain = this.#deliveryChain.then(deliver).catch(() => {
+    }).finally(() => {
+      this.#pendingDeliveries -= 1;
+    });
+  }
+};
+function blobToArrayBuffer(blob) {
+  if (typeof blob.arrayBuffer === "function") {
+    return blob.arrayBuffer();
+  }
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => {
+      resolve(reader.result);
+    };
+    reader.onerror = () => {
+      reject(reader.error ?? new Error("Blob read failed"));
+    };
+    reader.readAsArrayBuffer(blob);
+  });
+}
+
+exports.DurableWebSocket = DurableWebSocket;
+exports.WebSocket = DurableWebSocket;
+//# sourceMappingURL=compat.cjs.map
+//# sourceMappingURL=compat.cjs.map