universal-api-layer 0.7.0

package/dist/websocket/index.js

@@ -0,0 +1,529 @@
+import {
+  abortable,
+  validateResponse
+} from "../chunk-DXYWZQW5.js";
+import {
+  ApiError
+} from "../chunk-YTM3FV65.js";
+
+// src/websocket/index.ts
+var retryCodes = /* @__PURE__ */ new Set([1001, 1005, 1006, 1011, 1012, 1013, 1014]);
+var encoder = new TextEncoder();
+function configuration(message) {
+  throw new ApiError(message, 0, {}, void 0, "configuration");
+}
+function limit(value, name, minimum = 1) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > 2147483647)
+    configuration(`${name} is outside its supported integer range`);
+  return value;
+}
+function socketUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return configuration("An absolute ws(s) URL is required");
+  }
+  if (!["ws:", "wss:"].includes(url.protocol) || url.username || url.password || value.includes("#") || value.includes("\\"))
+    configuration("Invalid WebSocket URL");
+  return url;
+}
+function byteSize(value) {
+  if (typeof value === "string") return encoder.encode(value).byteLength;
+  if (value instanceof Blob) return value.size;
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value))
+    return value.byteLength;
+  return configuration("Unsupported WebSocket message data");
+}
+function validateClose(code, reason) {
+  if (code !== 1e3 && (!Number.isInteger(code) || code < 3e3 || code > 4999))
+    configuration("Close code must be 1000 or between 3000 and 4999");
+  if (typeof reason !== "string" || encoder.encode(reason).length > 123)
+    configuration("Close reason must be at most 123 UTF-8 bytes");
+}
+function createSocketClient(config) {
+  const options = { ...config };
+  const format = options.format ?? "json";
+  if (format !== "json" && format !== "raw")
+    configuration("Socket format must be json or raw");
+  const connectTimeout = limit(
+    options.connectTimeoutMs ?? 1e4,
+    "connectTimeoutMs"
+  );
+  const messageLimit = limit(
+    options.maxMessageSize ?? 1048576,
+    "maxMessageSize"
+  );
+  const pendingLimit = limit(
+    options.maxPendingMessages ?? 64,
+    "maxPendingMessages"
+  );
+  const bufferedLimit = limit(
+    options.maxBufferedAmount ?? 1048576,
+    "maxBufferedAmount"
+  );
+  const reconnect = options.reconnect === false ? void 0 : {
+    maxAttempts: 5,
+    baseDelayMs: 500,
+    maxDelayMs: 3e4,
+    jitter: true,
+    ...options.reconnect
+  };
+  if (reconnect) {
+    limit(reconnect.maxAttempts, "maxAttempts", 0);
+    limit(reconnect.baseDelayMs, "baseDelayMs");
+    limit(reconnect.maxDelayMs, "maxDelayMs");
+    if (reconnect.baseDelayMs > reconnect.maxDelayMs || typeof reconnect.jitter !== "boolean")
+      configuration("Invalid reconnect settings");
+  }
+  const requiresAuth = options.requiresAuth ?? Boolean(options.sessionClient);
+  if (requiresAuth && !options.sessionClient)
+    configuration("requiresAuth requires a sessionClient");
+  if (typeof options.url !== "string" && typeof options.url !== "function")
+    configuration("Socket url must be a string or provider");
+  const origins = new Set(
+    (options.allowedOrigins ?? []).map((value) => {
+      const url = socketUrl(value);
+      if (url.pathname !== "/" || url.search)
+        configuration("allowedOrigins must contain exact ws(s) origins");
+      return url.origin;
+    })
+  );
+  if (typeof options.url === "string") {
+    const origin = socketUrl(options.url).origin;
+    if (options.allowedOrigins === void 0) origins.add(origin);
+    if (!origins.has(origin)) configuration("WebSocket origin is not allowed");
+  } else if (!origins.size)
+    configuration("URL providers require allowedOrigins");
+  const protocols = [...options.protocols ?? []];
+  if (new Set(protocols).size !== protocols.length || protocols.some(
+    (value) => typeof value !== "string" || !/^[!#$%&'*+\-.^_`|~\da-z]+$/i.test(value)
+  ))
+    configuration("Invalid WebSocket subprotocols");
+  let snapshot = Object.freeze({
+    status: "idle",
+    reconnectAttempt: 0,
+    error: null,
+    close: null
+  });
+  const stateListeners = /* @__PURE__ */ new Set();
+  const messageListeners = /* @__PURE__ */ new Set();
+  const errorListeners = /* @__PURE__ */ new Set();
+  let wanted = false, disposed = false, generation = 0, attempts = 0, pending = 0;
+  let socket;
+  let controller;
+  let timeout, retry;
+  let detach, unsubscribeSession;
+  let revision;
+  let chain = Promise.resolve();
+  function listenerError(cause) {
+    const error = new ApiError(
+      "WebSocket listener failed",
+      0,
+      {},
+      void 0,
+      "callback",
+      cause
+    );
+    for (const listener of [...errorListeners]) {
+      try {
+        listener(error);
+      } catch {
+      }
+    }
+  }
+  function update(value) {
+    snapshot = Object.freeze({
+      ...snapshot,
+      ...value,
+      reconnectAttempt: attempts
+    });
+    for (const listener of [...stateListeners]) {
+      try {
+        listener();
+      } catch (cause) {
+        listenerError(cause);
+      }
+    }
+  }
+  function report(error) {
+    update({ error });
+    for (const listener of [...errorListeners]) {
+      try {
+        listener(error);
+      } catch {
+      }
+    }
+  }
+  function sessionValid() {
+    const state = options.sessionClient?.getSessionSnapshot();
+    return (!state || state.revision === revision) && (!requiresAuth || Boolean(state?.userId));
+  }
+  const current = (id) => wanted && !disposed && id === generation && sessionValid();
+  function release(code = 1e3, reason = "") {
+    generation++;
+    clearTimeout(timeout);
+    clearTimeout(retry);
+    timeout = retry = void 0;
+    detach?.();
+    detach = void 0;
+    controller?.abort(
+      new ApiError(
+        "WebSocket attempt cancelled",
+        0,
+        {},
+        void 0,
+        "cancelled"
+      )
+    );
+    controller = void 0;
+    const previous = socket;
+    socket = void 0;
+    pending = 0;
+    chain = Promise.resolve();
+    if (previous && previous.readyState < 2) {
+      try {
+        previous.close(code, reason);
+      } catch {
+      }
+    }
+  }
+  function stop(code = 1e3, reason = "", state = {}) {
+    wanted = false;
+    release(code, reason);
+    if (!state.keepSession) {
+      unsubscribeSession?.();
+      unsubscribeSession = void 0;
+    }
+    update({
+      status: state.status ?? "closed",
+      ...state.close === void 0 ? {} : { close: state.close },
+      ...state.clearError ? { error: null } : {}
+    });
+  }
+  function failed(error, canRetry, close = null) {
+    const id = generation;
+    report(error);
+    if (!current(id)) return;
+    release();
+    if (canRetry && reconnect && attempts < reconnect.maxAttempts) {
+      const delay = Math.min(
+        reconnect.maxDelayMs,
+        reconnect.baseDelayMs * 2 ** Math.min(attempts, 30)
+      );
+      attempts++;
+      const nextGeneration = generation;
+      update({ status: "reconnecting", close });
+      if (!current(nextGeneration)) return;
+      retry = setTimeout(
+        () => {
+          retry = void 0;
+          if (current(nextGeneration)) void attempt();
+        },
+        reconnect.jitter ? Math.floor(delay * (0.5 + Math.random() * 0.5)) : delay
+      );
+    } else {
+      wanted = false;
+      update({ status: "closed", close });
+    }
+  }
+  async function attempt() {
+    release();
+    const id = generation;
+    if (!current(id)) return;
+    controller = new AbortController();
+    const signal = controller.signal;
+    timeout = setTimeout(() => {
+      if (current(id))
+        failed(
+          new ApiError(
+            "WebSocket connection timed out",
+            0,
+            {},
+            void 0,
+            "timeout"
+          ),
+          true
+        );
+    }, connectTimeout);
+    update({ status: attempts ? "reconnecting" : "connecting", close: null });
+    try {
+      const value = typeof options.url === "string" ? options.url : await abortable(
+        () => options.url(signal),
+        signal
+      );
+      if (!current(id)) return;
+      const url = socketUrl(value);
+      if (!origins.has(url.origin))
+        configuration("WebSocket origin is not allowed");
+      const factory = options.webSocketFactory ?? ((target, protocols2) => {
+        if (typeof globalThis.WebSocket !== "function")
+          configuration("WebSocket is unavailable; provide webSocketFactory");
+        return new globalThis.WebSocket(target, protocols2);
+      });
+      const transport = factory(url.href, [...protocols]);
+      if (!current(id)) {
+        transport.close(1e3);
+        return;
+      }
+      socket = transport;
+      transport.binaryType = "arraybuffer";
+      const onOpen = () => {
+        if (!current(id)) return;
+        clearTimeout(timeout);
+        timeout = void 0;
+        update({ status: "open", error: null, close: null });
+      };
+      const onError = () => {
+        if (current(id))
+          report(
+            new ApiError(
+              "WebSocket transport error",
+              0,
+              {},
+              void 0,
+              "network"
+            )
+          );
+      };
+      const onClose = (event) => {
+        if (!current(id)) return;
+        const close = Object.freeze({
+          code: event.code,
+          reason: event.reason,
+          wasClean: event.wasClean
+        });
+        if (event.code === 1e3) {
+          stop(1e3, "", { close, keepSession: true });
+        } else
+          failed(
+            new ApiError(
+              "WebSocket connection closed",
+              0,
+              {},
+              void 0,
+              "network"
+            ),
+            retryCodes.has(event.code),
+            close
+          );
+      };
+      const onMessage = (event) => {
+        if (!current(id) || snapshot.status !== "open") return;
+        const data = event.data;
+        if (!(typeof data === "string" || data instanceof ArrayBuffer || data instanceof Blob)) {
+          report(
+            new ApiError(
+              "Unsupported incoming WebSocket data",
+              0,
+              {},
+              void 0,
+              "parse"
+            )
+          );
+          return;
+        }
+        if (byteSize(data) > messageLimit || pending >= pendingLimit) {
+          report(
+            new ApiError(
+              "WebSocket incoming message limit exceeded",
+              0,
+              {},
+              void 0,
+              "backpressure"
+            )
+          );
+          if (current(id)) stop(1e3, "Message limit exceeded");
+          return;
+        }
+        pending++;
+        chain = chain.then(async () => {
+          if (!current(id)) return;
+          let parsed = data;
+          if (format === "json") {
+            if (typeof data !== "string")
+              throw new ApiError(
+                "Expected a JSON text WebSocket message",
+                0,
+                {},
+                void 0,
+                "parse"
+              );
+            try {
+              parsed = JSON.parse(data);
+            } catch {
+              throw new ApiError(
+                "Invalid JSON WebSocket message",
+                0,
+                {},
+                void 0,
+                "parse"
+              );
+            }
+          }
+          const result = options.schema ? await abortable(
+            () => validateResponse(options.schema, parsed, 0),
+            signal
+          ) : parsed;
+          for (const listener of [...messageListeners]) {
+            if (!current(id)) break;
+            try {
+              listener(result);
+            } catch (cause) {
+              listenerError(cause);
+            }
+          }
+        }).catch((cause) => {
+          if (current(id))
+            report(
+              cause instanceof ApiError ? cause : new ApiError(
+                "WebSocket message processing failed",
+                0,
+                {},
+                void 0,
+                "parse",
+                cause
+              )
+            );
+        }).finally(() => {
+          if (current(id)) pending--;
+        });
+      };
+      transport.addEventListener("open", onOpen);
+      transport.addEventListener("error", onError);
+      transport.addEventListener("message", onMessage);
+      transport.addEventListener("close", onClose);
+      detach = () => {
+        transport.removeEventListener("open", onOpen);
+        transport.removeEventListener("error", onError);
+        transport.removeEventListener("message", onMessage);
+        transport.removeEventListener("close", onClose);
+      };
+    } catch (cause) {
+      if (current(id))
+        failed(
+          cause instanceof ApiError ? cause : new ApiError(
+            "WebSocket connection setup failed",
+            0,
+            {},
+            void 0,
+            "network"
+          ),
+          !(cause instanceof ApiError) || cause.code === "network"
+        );
+    }
+  }
+  function send(data) {
+    if (!wanted || !sessionValid() || !socket || socket.readyState !== 1 || snapshot.status !== "open")
+      throw new ApiError(
+        "WebSocket is not open; message was not queued",
+        0,
+        {},
+        void 0,
+        "network"
+      );
+    if (socket.bufferedAmount + byteSize(data) > bufferedLimit)
+      throw new ApiError(
+        "WebSocket outgoing buffer limit exceeded",
+        0,
+        {},
+        void 0,
+        "backpressure"
+      );
+    try {
+      socket.send(data);
+    } catch (cause) {
+      throw new ApiError(
+        "WebSocket send failed; delivery is unknown",
+        0,
+        {},
+        void 0,
+        "network",
+        cause
+      );
+    }
+  }
+  return Object.freeze({
+    connect() {
+      if (disposed) configuration("Socket client is disposed");
+      if (wanted) return;
+      if (requiresAuth && !options.sessionClient?.getSessionSnapshot().userId)
+        throw new ApiError(
+          "An authenticated session is required",
+          401,
+          {},
+          void 0,
+          "auth"
+        );
+      revision = options.sessionClient?.getSessionSnapshot().revision;
+      wanted = true;
+      attempts = 0;
+      unsubscribeSession?.();
+      unsubscribeSession = options.sessionClient?.subscribeSession(() => {
+        if (!sessionValid())
+          stop(1e3, "Session changed", { close: null, clearError: true });
+      });
+      update({ error: null, close: null });
+      if (wanted) void attempt();
+    },
+    disconnect(code = 1e3, reason = "") {
+      validateClose(code, reason);
+      if (!disposed) stop(code, reason);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stop(1e3, "Disposed", {
+        status: "disposed",
+        close: null,
+        clearError: true
+      });
+      stateListeners.clear();
+      messageListeners.clear();
+      errorListeners.clear();
+    },
+    send,
+    sendJson(value) {
+      let data;
+      try {
+        data = JSON.stringify(value);
+      } catch (cause) {
+        throw new ApiError(
+          "Message is not JSON serializable",
+          0,
+          {},
+          void 0,
+          "configuration",
+          cause
+        );
+      }
+      if (data === void 0) configuration("Message is not JSON serializable");
+      send(data);
+    },
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      if (disposed) configuration("Socket client is disposed");
+      stateListeners.add(listener);
+      return () => {
+        stateListeners.delete(listener);
+      };
+    },
+    onMessage(listener) {
+      if (disposed) configuration("Socket client is disposed");
+      messageListeners.add(listener);
+      return () => {
+        messageListeners.delete(listener);
+      };
+    },
+    onError(listener) {
+      if (disposed) configuration("Socket client is disposed");
+      errorListeners.add(listener);
+      return () => {
+        errorListeners.delete(listener);
+      };
+    }
+  });
+}
+export {
+  createSocketClient
+};

package/dist/websocket/react.d.ts

@@ -0,0 +1,8 @@
+import { SocketClient, SocketSnapshot } from './index.js';
+import '../client-ByBlZaRg.js';
+
+/** Subscribes only; the application owns connect/disconnect and may share a client. */
+declare function useSocketState<T>(client: SocketClient<T>): SocketSnapshot;
+declare function useSocketMessage<T>(client: SocketClient<T>, listener: (message: T) => void): void;
+
+export { useSocketMessage, useSocketState };

package/dist/websocket/react.js

@@ -0,0 +1,23 @@
+// src/websocket/react.ts
+import { useEffect, useRef, useSyncExternalStore } from "react";
+function useSocketState(client) {
+  return useSyncExternalStore(
+    client.subscribe,
+    client.getSnapshot,
+    client.getSnapshot
+  );
+}
+function useSocketMessage(client, listener) {
+  const latest = useRef(listener);
+  useEffect(() => {
+    latest.current = listener;
+  });
+  useEffect(
+    () => client.onMessage((message) => latest.current(message)),
+    [client]
+  );
+}
+export {
+  useSocketMessage,
+  useSocketState
+};

package/dist/websocket/vue.d.ts

@@ -0,0 +1,9 @@
+import { Ref } from 'vue';
+import { SocketClient, SocketSnapshot } from './index.js';
+import '../client-ByBlZaRg.js';
+
+/** Subscribes only; the application owns connect/disconnect and may share a client. */
+declare function useSocketState<T>(client: SocketClient<T>): Readonly<Ref<SocketSnapshot>>;
+declare function useSocketMessage<T>(client: SocketClient<T>, listener: (message: T) => void): void;
+
+export { useSocketMessage, useSocketState };

package/dist/websocket/vue.js

@@ -0,0 +1,39 @@
+import {
+  ApiError
+} from "../chunk-YTM3FV65.js";
+
+// src/websocket/vue.ts
+import {
+  getCurrentScope,
+  onScopeDispose,
+  shallowReadonly,
+  shallowRef
+} from "vue";
+function assertScope() {
+  if (!getCurrentScope())
+    throw new ApiError(
+      "Socket composables require an active Vue effect scope",
+      0,
+      {},
+      void 0,
+      "configuration"
+    );
+}
+function useSocketState(client) {
+  assertScope();
+  const state = shallowRef(client.getSnapshot());
+  onScopeDispose(
+    client.subscribe(() => {
+      state.value = client.getSnapshot();
+    })
+  );
+  return shallowReadonly(state);
+}
+function useSocketMessage(client, listener) {
+  assertScope();
+  onScopeDispose(client.onMessage(listener));
+}
+export {
+  useSocketMessage,
+  useSocketState
+};