@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-websocket.d.mts

@@ -0,0 +1,218 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { t as RetryDelayOptions } from "./retry-delay-DYsdq4SE.mjs";
+import { MaybeRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-websocket.d.ts
+/** Raw payload delivered by a WebSocket `message` event. */
+type WebSocketRawData = string | ArrayBuffer | Blob;
+/** Payload accepted by `WebSocket.send`. */
+type WebSocketSendData = string | Blob | BufferSource;
+/** Connection status exposed by {@link useWebSocket}. */
+type WebSocketStatus = "connecting" | "open" | "closing" | "closed";
+/** Minimal WebSocket instance used by {@link useWebSocket}. */
+interface WebSocketLike {
+  /** Transmit data over the open connection. */
+  readonly send: (data: WebSocketSendData) => void;
+  /** Start the closing handshake. */
+  readonly close: (code?: number, reason?: string) => void;
+  /** Subscribe to `open`, `message`, `error`, or `close`. */
+  addEventListener(type: "open" | "message" | "error" | "close", listener: EventListener): void;
+  /** Remove a listener registered with `addEventListener`. */
+  removeEventListener(type: "open" | "message" | "error" | "close", listener: EventListener): void;
+}
+/** Constructor creating {@link WebSocketLike} connections (e.g. `WebSocket`). */
+type WebSocketConstructorLike = new (url: string, protocols?: string | string[]) => WebSocketLike;
+/** Discriminated failure reported by {@link useWebSocket}. */
+type WebSocketFailure = {
+  /** The socket dispatched an `error` event. */readonly kind: "error"; /** The dispatched event. */
+  readonly event: Event;
+} | {
+  /** The constructor threw (invalid URL, blocked port, ...). */readonly kind: "connect"; /** Exact thrown value. */
+  readonly cause: unknown;
+} | {
+  /** `parse` threw for an incoming message. */readonly kind: "parse"; /** Exact thrown value. */
+  readonly cause: unknown;
+} | {
+  /** `validate` rejected a parsed message. */readonly kind: "invalid"; /** Rejected message. */
+  readonly data: unknown;
+} | {
+  /** Automatic reconnection gave up. */readonly kind: "reconnect-exhausted"; /** Reconnection attempts performed. */
+  readonly attempts: number;
+};
+/** Options for automatic reconnection. */
+interface WebSocketReconnectOptions extends RetryDelayOptions {
+  /**
+   * Maximum consecutive reconnection attempts.
+   *
+   * @default Infinity
+   */
+  readonly retries?: number;
+  /**
+   * Called once reconnection gives up.
+   *
+   * @default undefined
+   */
+  readonly onFailed?: () => void;
+}
+/** Options for the keep-alive heartbeat. */
+interface WebSocketHeartbeatOptions {
+  /**
+   * Raw ping payload.
+   *
+   * @default "ping"
+   */
+  readonly message?: WebSocketSendData;
+  /**
+   * Incoming payload treated as a pong and not exposed as data.
+   *
+   * @default the ping message when it is a string
+   */
+  readonly responseMessage?: string;
+  /**
+   * Delay between pings in milliseconds.
+   *
+   * @default 30000
+   */
+  readonly intervalMs?: number;
+  /**
+   * Close (and possibly reconnect) when no message arrives this long after a ping.
+   *
+   * @default 10000
+   */
+  readonly pongTimeoutMs?: number;
+}
+/**
+ * Options for {@link useWebSocket}.
+ *
+ * Callbacks that consume message types use method syntax so options typed
+ * for concrete messages remain assignable to the implementation signature.
+ */
+interface UseWebSocketOptions<Incoming, Outgoing> {
+  /**
+   * Sub-protocols requested from the server.
+   *
+   * @default undefined
+   */
+  readonly protocols?: string | string[];
+  /**
+   * WebSocket constructor (a plain value or ref; never a getter, because a
+   * constructor is itself a function). Supplying one also enables automatic
+   * connection outside a browser.
+   *
+   * @default window.WebSocket when a browser window exists
+   */
+  readonly host?: MaybeRef<WebSocketConstructorLike | null | undefined>;
+  /**
+   * Connect as soon as a URL is available (browser or explicit host only).
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Reconnect after unexpected closes with exponential backoff.
+   *
+   * @default false
+   */
+  readonly autoReconnect?: boolean | WebSocketReconnectOptions;
+  /**
+   * Send periodic pings and drop connections whose peer stops answering.
+   *
+   * @default false
+   */
+  readonly heartbeat?: boolean | WebSocketHeartbeatOptions;
+  /**
+   * Decode incoming payloads.
+   *
+   * @default the raw payload
+   */
+  readonly parse?: (raw: WebSocketRawData) => Incoming;
+  /**
+   * Encode outgoing messages.
+   *
+   * @default sends payloads as-is and JSON-encodes anything else
+   */
+  serialize?(message: Outgoing): WebSocketSendData;
+  /**
+   * Reject parsed messages that fail this check (`"invalid"` failure).
+   *
+   * @default accepts every message
+   */
+  validate?(message: Incoming): boolean;
+  /**
+   * Queue messages sent while connecting and flush them on open.
+   *
+   * @default true
+   */
+  readonly bufferWhileConnecting?: boolean;
+  /**
+   * Timer host for reconnection and heartbeat.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+  /**
+   * Observe every accepted incoming message.
+   *
+   * @default undefined
+   */
+  onMessage?(message: Incoming, event: Event): void;
+  /**
+   * Observe failures.
+   *
+   * @default undefined
+   */
+  readonly onError?: (failure: WebSocketFailure) => void;
+}
+/** Reactive state and controls returned by {@link useWebSocket}. */
+interface WebSocketControls<Incoming, Outgoing> {
+  /** Connection status. */
+  readonly status: Readonly<Ref<WebSocketStatus>>;
+  /** Latest accepted incoming message. */
+  readonly data: Readonly<ShallowRef<Incoming | undefined>>;
+  /** Latest failure, cleared when a connection opens. */
+  readonly error: Readonly<ShallowRef<WebSocketFailure | undefined>>;
+  /** Consecutive reconnection attempts since the last successful open. */
+  readonly reconnectAttempts: Readonly<Ref<number>>;
+  /** Current underlying socket, if any. */
+  readonly socket: Readonly<ShallowRef<WebSocketLike | undefined>>;
+  /**
+   * Send a message, or queue it while connecting.
+   *
+   * @returns Whether the message was sent or queued.
+   */
+  send(message: Outgoing): boolean;
+  /** Open (or reopen) the connection and re-enable reconnection. */
+  readonly open: () => void;
+  /** Close the connection and disable automatic reconnection. */
+  readonly close: (code?: number, reason?: string) => void;
+}
+/**
+ * Open a WebSocket with raw payloads.
+ *
+ * @param url Reactive URL; `null`/`undefined` keeps the socket closed.
+ * @param options Connection options.
+ * @returns Reactive state and controls.
+ */
+declare function useWebSocket(url: MaybeRefOrGetter<string | URL | null | undefined>, options?: UseWebSocketOptions<WebSocketRawData, WebSocketSendData>): WebSocketControls<WebSocketRawData, WebSocketSendData>;
+/**
+ * Open a WebSocket with typed messages. `parse` is required unless raw
+ * payloads fit `Incoming`; `serialize` is required unless `Outgoing` is
+ * already sendable.
+ *
+ * @param url Reactive URL; `null`/`undefined` keeps the socket closed.
+ * @param options Connection options with codecs.
+ * @returns Reactive state and controls.
+ */
+declare function useWebSocket<Incoming = WebSocketRawData, Outgoing = WebSocketSendData>(url: MaybeRefOrGetter<string | URL | null | undefined>, options: UseWebSocketOptions<Incoming, Outgoing> & WebSocketCodecRequirements<Incoming, Outgoing>): WebSocketControls<Incoming, Outgoing>;
+/**
+ * Codec options that become mandatory when the defaults cannot produce the
+ * message types: `parse` unless raw payloads fit `Incoming`, `serialize`
+ * unless `Outgoing` is already sendable.
+ */
+type WebSocketCodecRequirements<Incoming, Outgoing> = ([WebSocketRawData] extends [Incoming] ? unknown : {
+  readonly parse: (raw: WebSocketRawData) => Incoming;
+}) & ([Outgoing] extends [WebSocketSendData] ? unknown : {
+  readonly serialize: (message: Outgoing) => WebSocketSendData;
+});
+//#endregion
+export { UseWebSocketOptions, WebSocketCodecRequirements, WebSocketConstructorLike, WebSocketControls, WebSocketFailure, WebSocketHeartbeatOptions, WebSocketLike, WebSocketRawData, WebSocketReconnectOptions, WebSocketSendData, WebSocketStatus, useWebSocket };

package/dist/use-websocket.mjs

@@ -0,0 +1,257 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { calculateRetryDelay } from "./retry-delay.mjs";
+import { readonly, shallowRef, toValue, unref, watch } from "vue";
+//#region src/use-websocket.ts
+function browserWebSocket() {
+	return typeof window !== "undefined" && typeof window.WebSocket === "function" ? window.WebSocket : void 0;
+}
+function toSendData(value) {
+	if (typeof value === "string" || value instanceof ArrayBuffer) return value;
+	if (typeof Blob !== "undefined" && value instanceof Blob) return value;
+	if (ArrayBuffer.isView(value) && value.buffer instanceof ArrayBuffer) return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+function isRawData(value) {
+	return typeof value === "string" || value instanceof ArrayBuffer || typeof Blob !== "undefined" && value instanceof Blob;
+}
+function defaultScheduler() {
+	return {
+		setTimeout: (callback, delayMs) => {
+			const handle = globalThis.setTimeout(callback, delayMs);
+			return () => globalThis.clearTimeout(handle);
+		},
+		clearTimeout: (cancel) => {
+			if (typeof cancel === "function") cancel();
+		}
+	};
+}
+/**
+* Reactive WebSocket with typed messages, auto-reconnect, and heartbeat.
+*
+* Unexpected closes reconnect with exponential backoff when `autoReconnect`
+* is enabled; `close()` is always final until `open()` is called again.
+* Messages sent while connecting are queued. The connection and all timers
+* are released when the owning reactive scope stops; outside a scope the
+* caller owns `close()`. Server rendering never connects: automatic
+* connection requires a browser or an explicit `host`, and status stays
+* `"closed"`.
+*
+* @example
+* ```ts
+* const chat = useWebSocket<ChatEvent, ChatCommand>("wss://example.test/chat", {
+*   parse: (raw) => parseChatEvent(String(raw)),
+*   serialize: (command) => JSON.stringify(command),
+*   autoReconnect: { retries: 5 },
+*   heartbeat: true,
+* });
+* chat.send({ type: "join", room: "general" });
+* ```
+*
+* @param url Reactive URL; changing it reconnects.
+* @param options Codecs, reconnection, heartbeat, and host options.
+* @default options {}
+* @returns Reactive state and controls.
+*/
+function useWebSocket(url, options = {}) {
+	const status = shallowRef("closed");
+	const data = shallowRef(void 0);
+	const error = shallowRef(void 0);
+	const reconnectAttempts = shallowRef(0);
+	const socket = shallowRef(void 0);
+	const scheduler = options.scheduler ?? defaultScheduler();
+	const reconnect = options.autoReconnect === true ? {} : options.autoReconnect || void 0;
+	const heartbeat = options.heartbeat === true ? {} : options.heartbeat || void 0;
+	const pingMessage = heartbeat?.message ?? "ping";
+	const pongMessage = heartbeat?.responseMessage ?? (typeof pingMessage === "string" ? pingMessage : void 0);
+	const buffer = [];
+	let manuallyClosed = false;
+	let reconnectTimer;
+	let pingTimer;
+	let pongTimer;
+	let detach;
+	const resolveHost = () => options.host === void 0 ? browserWebSocket() : unref(options.host) ?? void 0;
+	const fail = (failure) => {
+		error.value = failure;
+		options.onError?.(failure);
+	};
+	const clearTimer = (handle) => {
+		if (handle !== void 0) scheduler.clearTimeout(handle);
+	};
+	const stopHeartbeat = () => {
+		pingTimer = clearTimer(pingTimer);
+		pongTimer = clearTimer(pongTimer);
+	};
+	const serialize = (message) => options.serialize ? options.serialize(message) : toSendData(message) ?? JSON.stringify(message);
+	const schedulePing = (target) => {
+		if (!heartbeat) return;
+		pingTimer = scheduler.setTimeout(() => {
+			pingTimer = void 0;
+			target.send(pingMessage);
+			pongTimer = clearTimer(pongTimer);
+			pongTimer = scheduler.setTimeout(() => {
+				pongTimer = void 0;
+				target.close();
+			}, heartbeat.pongTimeoutMs ?? 1e4);
+			schedulePing(target);
+		}, heartbeat.intervalMs ?? 3e4);
+	};
+	const teardown = () => {
+		stopHeartbeat();
+		detach?.();
+		detach = void 0;
+	};
+	const scheduleReconnect = () => {
+		if (!reconnect || manuallyClosed) return;
+		const retries = reconnect.retries ?? Number.POSITIVE_INFINITY;
+		if (reconnectAttempts.value >= retries) {
+			fail({
+				kind: "reconnect-exhausted",
+				attempts: reconnectAttempts.value
+			});
+			reconnect.onFailed?.();
+			return;
+		}
+		reconnectAttempts.value += 1;
+		const delay = calculateRetryDelay(reconnectAttempts.value, reconnect);
+		reconnectTimer = scheduler.setTimeout(() => {
+			reconnectTimer = void 0;
+			connect();
+		}, delay);
+	};
+	const connect = () => {
+		reconnectTimer = clearTimer(reconnectTimer);
+		const current = socket.value;
+		if (current) {
+			teardown();
+			current.close();
+			socket.value = void 0;
+		}
+		const target = toValue(url);
+		const Host = resolveHost();
+		if (target === null || target === void 0 || Host === void 0) {
+			status.value = "closed";
+			return;
+		}
+		let instance;
+		try {
+			instance = options.protocols === void 0 ? new Host(String(target)) : new Host(String(target), options.protocols);
+		} catch (cause) {
+			status.value = "closed";
+			fail({
+				kind: "connect",
+				cause
+			});
+			scheduleReconnect();
+			return;
+		}
+		socket.value = instance;
+		status.value = "connecting";
+		const onOpen = () => {
+			status.value = "open";
+			error.value = void 0;
+			reconnectAttempts.value = 0;
+			for (const queued of buffer.splice(0)) instance.send(queued);
+			schedulePing(instance);
+		};
+		const onMessage = (event) => {
+			pongTimer = clearTimer(pongTimer);
+			const raw = "data" in event ? event.data : void 0;
+			if (!isRawData(raw)) return;
+			if (heartbeat && pongMessage !== void 0 && raw === pongMessage) return;
+			let message;
+			try {
+				message = options.parse ? options.parse(raw) : raw;
+			} catch (cause) {
+				fail({
+					kind: "parse",
+					cause
+				});
+				return;
+			}
+			if (options.validate && !options.validate(message)) {
+				fail({
+					kind: "invalid",
+					data: message
+				});
+				return;
+			}
+			data.value = message;
+			options.onMessage?.(message, event);
+		};
+		const onError = (event) => fail({
+			kind: "error",
+			event
+		});
+		const onClose = () => {
+			teardown();
+			if (socket.value === instance) socket.value = void 0;
+			status.value = "closed";
+			scheduleReconnect();
+		};
+		instance.addEventListener("open", onOpen);
+		instance.addEventListener("message", onMessage);
+		instance.addEventListener("error", onError);
+		instance.addEventListener("close", onClose);
+		detach = () => {
+			instance.removeEventListener("open", onOpen);
+			instance.removeEventListener("message", onMessage);
+			instance.removeEventListener("error", onError);
+			instance.removeEventListener("close", onClose);
+		};
+	};
+	const open = () => {
+		manuallyClosed = false;
+		reconnectAttempts.value = 0;
+		connect();
+	};
+	const close = (code, reason) => {
+		manuallyClosed = true;
+		reconnectTimer = clearTimer(reconnectTimer);
+		buffer.length = 0;
+		const current = socket.value;
+		teardown();
+		socket.value = void 0;
+		if (!current) {
+			status.value = "closed";
+			return;
+		}
+		status.value = "closing";
+		current.close(code, reason);
+		status.value = "closed";
+	};
+	const send = (message) => {
+		const payload = serialize(message);
+		if (status.value === "open" && socket.value) {
+			socket.value.send(payload);
+			return true;
+		}
+		if (status.value === "connecting" && (options.bufferWhileConnecting ?? true)) {
+			buffer.push(payload);
+			return true;
+		}
+		return false;
+	};
+	if (options.host !== void 0 || typeof window !== "undefined") {
+		let initial = true;
+		tryOnScopeDispose(watch([() => toValue(url), resolveHost], ([target]) => {
+			const first = initial;
+			initial = false;
+			if (first && !(options.immediate ?? true)) return;
+			if (!first && socket.value === void 0 && reconnectTimer === void 0) return;
+			if (target === null || target === void 0) close();
+			else open();
+		}, { immediate: true }));
+	}
+	tryOnScopeDispose(() => close());
+	return {
+		status: readonly(status),
+		data,
+		error,
+		reconnectAttempts: readonly(reconnectAttempts),
+		socket,
+		send,
+		open,
+		close
+	};
+}
+//#endregion
+export { useWebSocket };

package/dist/use-worker-fn.d.mts

@@ -0,0 +1,119 @@
+import { t as TimeoutScheduler } from "./timeout-scheduler-CI8RVLZs.mjs";
+import { MaybeRefOrGetter, Ref } from "vue";
+
+//#region src/use-worker-fn.d.ts
+/** Lifecycle status of a {@link useWorkerFn} worker. */
+type WorkerFnStatus = "idle" | "running" | "success" | "error" | "timeout";
+/** Minimal dedicated worker used by {@link useWorkerFn}. */
+interface WorkerLike {
+  /** Send a structured-clonable message to the worker. */
+  postMessage(message: unknown): void;
+  /** Stop the worker immediately. */
+  terminate(): void;
+  /** Subscribe to `message`, `messageerror`, or `error`. */
+  addEventListener(type: "message" | "messageerror" | "error", listener: EventListener): void;
+  /** Remove a listener registered with `addEventListener`. */
+  removeEventListener(type: "message" | "messageerror" | "error", listener: EventListener): void;
+}
+/** Constructor creating {@link WorkerLike} instances from a script URL. */
+type WorkerConstructorLike = new (url: string) => WorkerLike;
+/** Capabilities needed to run a function in a Blob-URL worker. */
+interface WorkerFnHost {
+  /** Worker constructor (e.g. `Worker`). */
+  readonly Worker: WorkerConstructorLike;
+  /** Create a URL for the generated worker script (e.g. `URL.createObjectURL`). */
+  readonly createObjectURL: (script: Blob) => string;
+  /** Release a URL returned by `createObjectURL`. */
+  readonly revokeObjectURL: (url: string) => void;
+}
+/** Stable error codes used in {@link useWorkerFn} rejection messages. */
+type WorkerFnErrorCode = "VIZE_COMPOSE_WORKER_FN_UNSUPPORTED" | "VIZE_COMPOSE_WORKER_FN_BUSY" | "VIZE_COMPOSE_WORKER_FN_TIMEOUT" | "VIZE_COMPOSE_WORKER_FN_TERMINATED" | "VIZE_COMPOSE_WORKER_FN_FAILED";
+/** Options for {@link useWorkerFn}. */
+interface UseWorkerFnOptions {
+  /**
+   * Reject and terminate a run after this many milliseconds.
+   *
+   * @default undefined (no timeout)
+   */
+  readonly timeoutMs?: number;
+  /**
+   * Absolute script URLs loaded with `importScripts` before the function runs.
+   *
+   * @default []
+   */
+  readonly dependencies?: readonly string[];
+  /**
+   * Named standalone functions inlined into the worker so `fn` can call them.
+   *
+   * @default []
+   */
+  readonly localDependencies?: readonly ((...arguments_: never[]) => unknown)[];
+  /**
+   * Worker capabilities for alternate runtimes and tests.
+   *
+   * @default window.Worker and window.URL when a browser window exists
+   */
+  readonly host?: MaybeRefOrGetter<WorkerFnHost | null | undefined>;
+  /**
+   * Timer host for `timeoutMs`.
+   *
+   * @default globalThis timer functions
+   */
+  readonly scheduler?: TimeoutScheduler;
+}
+/** Reactive state and controls returned by {@link useWorkerFn}. */
+interface WorkerFnControls<Arguments extends readonly unknown[], Result> {
+  /** Lifecycle status of the latest run. */
+  readonly status: Readonly<Ref<WorkerFnStatus>>;
+  /** Whether worker capabilities are available. */
+  readonly supported: Readonly<Ref<boolean>>;
+  /**
+   * Run the function in a fresh worker. Arguments and result must be
+   * structured-clonable. Rejects with a tagged `Error` whose message starts
+   * with a {@link WorkerFnErrorCode}.
+   */
+  readonly run: (...arguments_: Arguments) => Promise<Awaited<Result>>;
+  /** Terminate the running worker, rejecting its pending run. */
+  readonly terminate: () => void;
+}
+/**
+ * Build the worker script for `fn`. Exposed for inspection and testing.
+ *
+ * The function source is embedded with `Function.prototype.toString`, so it
+ * must be self-contained: no closures over module variables, only its
+ * arguments, `localDependencies`, `dependencies`, and worker globals.
+ *
+ * @param fn Function to embed.
+ * @param options Imported scripts and inlined helper functions.
+ * @default options {}
+ * @returns JavaScript source for a dedicated worker.
+ */
+declare function createWorkerFnScript(fn: (...arguments_: never[]) => unknown, options?: Pick<UseWorkerFnOptions, "dependencies" | "localDependencies">): string;
+/**
+ * Run a CPU-heavy function in a dedicated Blob-URL worker, off the main thread.
+ *
+ * Each `run` spawns a fresh worker, posts the arguments, and resolves with the
+ * function's (awaited) result; the worker is terminated and its URL revoked
+ * once the run settles, times out, or is terminated. Concurrent runs reject
+ * with `VIZE_COMPOSE_WORKER_FN_BUSY`. The running worker is terminated when
+ * the owning reactive scope stops. Server rendering never spawns workers:
+ * `supported` is `false` and `run` rejects with
+ * `VIZE_COMPOSE_WORKER_FN_UNSUPPORTED`.
+ *
+ * @example
+ * ```ts
+ * const { run, status } = useWorkerFn((values: number[]) =>
+ *   [...values].sort((a, b) => a - b),
+ * );
+ * const sorted = await run(bigArray);
+ * ```
+ *
+ * @param fn Self-contained function; see {@link createWorkerFnScript}.
+ * @param options Timeout, dependencies, host, and scheduler.
+ * @default options {}
+ * @throws {RangeError} `[VIZE_COMPOSE_WORKER_FN_INVALID_TIMEOUT]` for an invalid timeout.
+ * @returns Reactive status and run controls.
+ */
+declare function useWorkerFn<Arguments extends readonly unknown[], Result>(fn: (...arguments_: Arguments) => Result, options?: UseWorkerFnOptions): WorkerFnControls<Arguments, Result>;
+//#endregion
+export { UseWorkerFnOptions, WorkerConstructorLike, WorkerFnControls, WorkerFnErrorCode, WorkerFnHost, WorkerFnStatus, WorkerLike, createWorkerFnScript, useWorkerFn };