@vizejs/composable 0.426.2 → 0.427.0

package/dist/use-serial.d.mts

@@ -0,0 +1,165 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-serial.d.ts
+/** USB identifiers used to filter `requestPort`. */
+interface SerialPortFilter {
+  /** USB vendor id. */
+  readonly usbVendorId?: number;
+  /** USB product id. */
+  readonly usbProductId?: number;
+  /** Bluetooth RFCOMM service class id. */
+  readonly bluetoothServiceClassId?: number | string;
+}
+/** Line settings passed to `SerialPort.open`. */
+interface SerialOpenOptions {
+  /** Baud rate, e.g. `9600` or `115200`. */
+  readonly baudRate: number;
+  /**
+   * Data bits per frame (7 or 8).
+   *
+   * @default 8
+   */
+  readonly dataBits?: number;
+  /**
+   * Stop bits (1 or 2).
+   *
+   * @default 1
+   */
+  readonly stopBits?: number;
+  /**
+   * Parity mode.
+   *
+   * @default "none"
+   */
+  readonly parity?: "none" | "even" | "odd";
+  /**
+   * Read/write buffer size in bytes.
+   *
+   * @default 255
+   */
+  readonly bufferSize?: number;
+  /**
+   * Flow control mode.
+   *
+   * @default "none"
+   */
+  readonly flowControl?: "none" | "hardware";
+}
+/** Minimal `SerialPort` used by {@link useSerial}. */
+interface SerialPortLike extends EventTarget {
+  /** Byte stream from the device while open; `null` otherwise or after a fatal error. */
+  readonly readable: ReadableStream<Uint8Array> | null;
+  /** Byte sink to the device while open. */
+  readonly writable: WritableStream<Uint8Array> | null;
+  /** Open the port. */
+  open(options: SerialOpenOptions): Promise<void>;
+  /** Close the port. */
+  close(): Promise<void>;
+}
+/** `navigator.serial`-like capability used by {@link useSerial}. */
+interface SerialHost extends EventTarget {
+  /** Ports the page already has access to. */
+  getPorts(): Promise<SerialPortLike[]>;
+  /** Prompt the user for a port. */
+  requestPort(options?: {
+    readonly filters?: readonly SerialPortFilter[];
+  }): Promise<SerialPortLike>;
+}
+/** How received bytes are delivered. */
+type SerialDecoding = "bytes" | "text";
+/** Chunk type delivered for a {@link SerialDecoding}. */
+type SerialChunk<Decoding extends SerialDecoding> = Decoding extends "text" ? string : Uint8Array;
+/** Options for {@link useSerial}. */
+interface UseSerialOptions<Decoding extends SerialDecoding = "bytes"> {
+  /**
+   * `navigator.serial`-like capability.
+   *
+   * @default window.navigator.serial when it exists
+   */
+  readonly host?: MaybeRefOrGetter<SerialHost | null | undefined>;
+  /**
+   * Deliver raw bytes or text decoded with `encoding` (streaming, so split
+   * multi-byte characters are joined).
+   *
+   * @default "bytes"
+   */
+  readonly decode?: Decoding;
+  /**
+   * Text encoding used when `decode` is `"text"`.
+   *
+   * @default "utf-8"
+   */
+  readonly encoding?: string;
+  /**
+   * Receives every chunk read from the open port.
+   *
+   * @default undefined
+   */
+  readonly onData?: (chunk: SerialChunk<Decoding>) => void;
+}
+/** Reactive state and actions returned by {@link useSerial}. */
+interface SerialControls {
+  /** Whether Web Serial is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Ports the page has access to, refreshed on `connect` / `disconnect`. */
+  readonly ports: Readonly<ShallowRef<readonly SerialPortLike[]>>;
+  /** Currently open port. */
+  readonly port: Readonly<ShallowRef<SerialPortLike | undefined>>;
+  /** Whether a port is open. */
+  readonly connected: Readonly<Ref<boolean>>;
+  /** Most recent failure (request, open, read, write). */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Prompt the user for a port (requires user activation).
+   *
+   * @returns The chosen port, or `undefined` when cancelled or failed.
+   */
+  readonly requestPort: (filters?: readonly SerialPortFilter[]) => Promise<SerialPortLike | undefined>;
+  /**
+   * Refresh `ports`.
+   *
+   * @returns The granted ports.
+   */
+  readonly getPorts: () => Promise<readonly SerialPortLike[]>;
+  /**
+   * Open `port` (closing any other open port) and start the read loop.
+   *
+   * @returns Whether the port opened.
+   */
+  readonly open: (port: SerialPortLike, options: SerialOpenOptions) => Promise<boolean>;
+  /**
+   * Write text (UTF-8 encoded) or bytes.
+   *
+   * @returns Whether the data was written.
+   */
+  readonly write: (data: string | Uint8Array) => Promise<boolean>;
+  /** Stop reading and close the open port. Idempotent. */
+  readonly close: () => Promise<void>;
+}
+/**
+ * Talk to serial devices with the Web Serial API.
+ *
+ * `requestPort()` prompts for a port, `open()` opens it and starts a read
+ * loop that feeds `onData` with bytes or decoded text, `write()` sends text
+ * or bytes. `ports` follows the host's `connect` / `disconnect` events and a
+ * port's own `disconnect` closes the session. Failures land in `error`. The
+ * read loop is cancelled and the port closed when the owning reactive scope
+ * stops; outside a scope call `close()`.
+ *
+ * Server rendering: `supported` and `connected` are false, nothing is read.
+ *
+ * @example
+ * ```ts
+ * const serial = useSerial({ decode: "text", onData: (text) => log(text) });
+ * const port = await serial.requestPort([{ usbVendorId: 0x2341 }]);
+ * if (port) await serial.open(port, { baudRate: 115200 });
+ * ```
+ *
+ * @param options Host, decoding, and data callback.
+ * @default options {}
+ * @throws `RangeError` tagged `VIZE_COMPOSE_SERIAL_INVALID_ENCODING` for an unknown `encoding`.
+ * @returns Serial state and actions.
+ */
+declare function useSerial<const Decoding extends SerialDecoding = "bytes">(options?: UseSerialOptions<Decoding>): SerialControls;
+//#endregion
+export { SerialChunk, SerialControls, SerialDecoding, SerialHost, SerialOpenOptions, SerialPortFilter, SerialPortLike, UseSerialOptions, useSerial };

package/dist/use-serial.mjs

@@ -0,0 +1,205 @@
+import { tryOnScopeDispose } from "./scope.mjs";
+import { computed, hasInjectionContext, readonly, ref, shallowReadonly, shallowRef, toValue, watch, watchPostEffect } from "vue";
+//#region src/use-serial.ts
+function browserSerialHost() {
+	if (typeof window === "undefined") return void 0;
+	const { navigator } = window;
+	const serial = "serial" in navigator ? navigator.serial : void 0;
+	return isSerialHost(serial) ? serial : void 0;
+}
+function isSerialHost(value) {
+	return typeof value === "object" && value !== null && "requestPort" in value;
+}
+/**
+* Talk to serial devices with the Web Serial API.
+*
+* `requestPort()` prompts for a port, `open()` opens it and starts a read
+* loop that feeds `onData` with bytes or decoded text, `write()` sends text
+* or bytes. `ports` follows the host's `connect` / `disconnect` events and a
+* port's own `disconnect` closes the session. Failures land in `error`. The
+* read loop is cancelled and the port closed when the owning reactive scope
+* stops; outside a scope call `close()`.
+*
+* Server rendering: `supported` and `connected` are false, nothing is read.
+*
+* @example
+* ```ts
+* const serial = useSerial({ decode: "text", onData: (text) => log(text) });
+* const port = await serial.requestPort([{ usbVendorId: 0x2341 }]);
+* if (port) await serial.open(port, { baudRate: 115200 });
+* ```
+*
+* @param options Host, decoding, and data callback.
+* @default options {}
+* @throws `RangeError` tagged `VIZE_COMPOSE_SERIAL_INVALID_ENCODING` for an unknown `encoding`.
+* @returns Serial state and actions.
+*/
+function useSerial(options = {}) {
+	const ports = shallowRef([]);
+	const port = shallowRef(void 0);
+	const connected = ref(false);
+	const error = shallowRef(void 0);
+	const encoding = options.encoding ?? "utf-8";
+	const text = options.decode === "text";
+	if (text) try {
+		new TextDecoder(encoding);
+	} catch {
+		throw new RangeError(`[VIZE_COMPOSE_SERIAL_INVALID_ENCODING] unsupported text encoding "${encoding}"`);
+	}
+	let session;
+	const hydrated = shallowRef(!hasInjectionContext());
+	if (!hydrated.value) watchPostEffect(() => {
+		hydrated.value = true;
+	});
+	const resolveHost = () => !hydrated.value ? void 0 : options.host === void 0 ? browserSerialHost() : toValue(options.host) ?? void 0;
+	const deliver = (chunk) => {
+		if (chunk.length > 0) options.onData?.(chunk);
+	};
+	const readLoop = async (target, current) => {
+		const decoder = text ? new TextDecoder(encoding) : void 0;
+		let stream = target.readable;
+		while (stream && current.active) {
+			const reader = stream.getReader();
+			current.reader = reader;
+			try {
+				for (;;) {
+					const { value, done } = await reader.read();
+					if (done) break;
+					deliver(decoder ? decoder.decode(value, { stream: true }) : value);
+				}
+			} catch (cause) {
+				if (current.active) error.value = cause;
+			} finally {
+				reader.releaseLock();
+				current.reader = void 0;
+			}
+			if (target.readable === stream) break;
+			stream = target.readable;
+		}
+		if (decoder) deliver(decoder.decode());
+	};
+	const onPortDisconnect = () => {
+		close();
+	};
+	async function close() {
+		const current = session;
+		const target = port.value;
+		session = void 0;
+		port.value = void 0;
+		connected.value = false;
+		if (!current || !target) return;
+		target.removeEventListener("disconnect", onPortDisconnect);
+		current.active = false;
+		let failure;
+		try {
+			await current.reader?.cancel();
+		} catch (cause) {
+			failure = cause;
+		}
+		try {
+			await current.done;
+		} catch (cause) {
+			failure ??= cause;
+		}
+		try {
+			await target.close();
+		} catch (cause) {
+			failure ??= cause;
+		}
+		if (failure !== void 0) error.value = failure;
+	}
+	const open = async (target, openOptions) => {
+		await close();
+		try {
+			await target.open(openOptions);
+		} catch (cause) {
+			error.value = cause;
+			return false;
+		}
+		const current = {
+			active: true,
+			reader: void 0,
+			done: Promise.resolve()
+		};
+		session = current;
+		port.value = target;
+		connected.value = true;
+		error.value = void 0;
+		target.addEventListener("disconnect", onPortDisconnect);
+		current.done = readLoop(target, current);
+		return true;
+	};
+	const write = async (data) => {
+		const writable = port.value?.writable;
+		if (!writable) return false;
+		const writer = writable.getWriter();
+		try {
+			await writer.write(typeof data === "string" ? new TextEncoder().encode(data) : data);
+			return true;
+		} catch (cause) {
+			error.value = cause;
+			return false;
+		} finally {
+			writer.releaseLock();
+		}
+	};
+	const getPorts = async () => {
+		const host = resolveHost();
+		if (!host) return [];
+		try {
+			ports.value = await host.getPorts();
+		} catch (cause) {
+			error.value = cause;
+		}
+		return ports.value;
+	};
+	const requestPort = async (filters) => {
+		const host = resolveHost();
+		if (!host) return void 0;
+		try {
+			const chosen = await host.requestPort(filters === void 0 ? {} : { filters });
+			error.value = void 0;
+			await getPorts();
+			return chosen;
+		} catch (cause) {
+			error.value = cause;
+			return;
+		}
+	};
+	const onHostChange = () => {
+		getPorts();
+	};
+	watch(resolveHost, (host, _previous, onCleanup) => {
+		if (!host) {
+			ports.value = [];
+			return;
+		}
+		host.addEventListener("connect", onHostChange);
+		host.addEventListener("disconnect", onHostChange);
+		onCleanup(() => {
+			host.removeEventListener("connect", onHostChange);
+			host.removeEventListener("disconnect", onHostChange);
+		});
+		getPorts();
+	}, {
+		immediate: true,
+		flush: "sync"
+	});
+	tryOnScopeDispose(() => {
+		close();
+	});
+	return {
+		supported: computed(() => resolveHost() !== void 0),
+		ports: shallowReadonly(ports),
+		port: shallowReadonly(port),
+		connected: readonly(connected),
+		error: readonly(error),
+		requestPort,
+		getPorts,
+		open,
+		write,
+		close
+	};
+}
+//#endregion
+export { useSerial };

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

@@ -0,0 +1,177 @@
+import { ComputedRef, MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+//#region src/use-service-worker.d.ts
+/** Lifecycle states of a service worker. */
+type ServiceWorkerStateName = "parsed" | "installing" | "installed" | "activating" | "activated" | "redundant";
+/** Minimal `ServiceWorker` consumed by {@link useServiceWorker}. */
+interface ServiceWorkerLike extends EventTarget {
+  /** Current lifecycle state; changes fire `statechange`. */
+  readonly state: ServiceWorkerStateName;
+  /** Post a message to the worker. */
+  postMessage(message: unknown): void;
+}
+/** Minimal `ServiceWorkerRegistration` consumed by {@link useServiceWorker}. */
+interface ServiceWorkerRegistrationLike extends EventTarget {
+  /** Worker being installed, if any; a new one fires `updatefound`. */
+  readonly installing: ServiceWorkerLike | null;
+  /** Installed worker waiting to take over, if any. */
+  readonly waiting: ServiceWorkerLike | null;
+  /** Active worker, if any. */
+  readonly active: ServiceWorkerLike | null;
+  /** Registration scope URL. */
+  readonly scope: string;
+  /** Check the server for an updated script. */
+  update(): Promise<unknown>;
+  /** Unregister; resolves whether the registration was removed. */
+  unregister(): Promise<boolean>;
+}
+/** Options forwarded to `ServiceWorkerContainer.register`. */
+interface ServiceWorkerRegisterOptions {
+  /**
+   * Registration scope.
+   *
+   * @default the script's directory
+   */
+  readonly scope?: string;
+  /**
+   * Script type.
+   *
+   * @default "classic"
+   */
+  readonly type?: "classic" | "module";
+  /**
+   * HTTP cache policy for update checks.
+   *
+   * @default "imports"
+   */
+  readonly updateViaCache?: "imports" | "all" | "none";
+}
+/** Minimal `ServiceWorkerContainer` (`navigator.serviceWorker`). */
+interface ServiceWorkerContainerLike extends EventTarget {
+  /** Worker controlling this page; changes fire `controllerchange`. */
+  readonly controller: ServiceWorkerLike | null;
+  /** Register a service worker script. */
+  register(scriptUrl: string | URL, options?: ServiceWorkerRegisterOptions): Promise<ServiceWorkerRegistrationLike>;
+}
+/** States of the registration's workers (`null` when absent). */
+interface ServiceWorkerStates {
+  /** State of the installing worker. */
+  readonly installing: ServiceWorkerStateName | null;
+  /** State of the waiting worker. */
+  readonly waiting: ServiceWorkerStateName | null;
+  /** State of the active worker. */
+  readonly active: ServiceWorkerStateName | null;
+}
+/** Options for {@link useServiceWorker}. */
+interface UseServiceWorkerOptions {
+  /**
+   * Service worker container for alternate runtimes and tests.
+   *
+   * @default window.navigator.serviceWorker when it exists
+   */
+  readonly container?: MaybeRefOrGetter<ServiceWorkerContainerLike | null | undefined>;
+  /**
+   * Registration scope.
+   *
+   * @default undefined (the script's directory)
+   */
+  readonly scope?: string;
+  /**
+   * Script type.
+   *
+   * @default "classic"
+   */
+  readonly type?: "classic" | "module";
+  /**
+   * HTTP cache policy for update checks.
+   *
+   * @default "imports"
+   */
+  readonly updateViaCache?: "imports" | "all" | "none";
+  /**
+   * Register as soon as the composable is created (browser only).
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+  /**
+   * Message posted to the waiting worker by `skipWaiting()`.
+   *
+   * @default { type: "SKIP_WAITING" }
+   */
+  readonly skipWaitingMessage?: unknown;
+  /**
+   * Called on `controllerchange` (for example to reload the page after a
+   * new worker took control).
+   *
+   * @default undefined
+   */
+  readonly onControllerChange?: (controller: ServiceWorkerLike | null) => void;
+}
+/** Reactive state and actions returned by {@link useServiceWorker}. */
+interface ServiceWorkerControls {
+  /** Whether the Service Worker API is available. */
+  readonly supported: ComputedRef<boolean>;
+  /** Current registration, or `null` before registering. */
+  readonly registration: Readonly<ShallowRef<ServiceWorkerRegistrationLike | null>>;
+  /** States of the installing, waiting and active workers. */
+  readonly state: Readonly<Ref<ServiceWorkerStates>>;
+  /** Whether a waiting worker is ready to replace the controlling one. */
+  readonly updateAvailable: ComputedRef<boolean>;
+  /** Most recent failure, cleared by the next successful action. */
+  readonly error: Readonly<ShallowRef<unknown>>;
+  /**
+   * Register (or re-register) the script.
+   *
+   * @returns The registration, or `null` when unsupported or on failure.
+   */
+  readonly register: () => Promise<ServiceWorkerRegistrationLike | null>;
+  /**
+   * Check the server for an updated script.
+   *
+   * @returns Whether the check ran without failing.
+   */
+  readonly update: () => Promise<boolean>;
+  /**
+   * Post the skip-waiting message to the waiting worker.
+   *
+   * @returns Whether a waiting worker received the message.
+   */
+  readonly skipWaiting: () => boolean;
+  /**
+   * Unregister the service worker.
+   *
+   * @returns Whether the registration was removed.
+   */
+  readonly unregister: () => Promise<boolean>;
+}
+/**
+ * Register a service worker and follow its update lifecycle.
+ *
+ * Tracks `updatefound` and each worker's `statechange` so `state` mirrors
+ * the installing, waiting and active workers. `updateAvailable` turns true
+ * once an installed worker waits while another one controls the page;
+ * `skipWaiting()` then posts the configured message to it, and
+ * `onControllerChange` runs once it takes control. Listeners are removed
+ * when the owning reactive scope stops; outside a scope they live as long as
+ * the registration.
+ *
+ * Server rendering: nothing is registered, `supported` is false and every
+ * state is `null`.
+ *
+ * @example
+ * ```ts
+ * const sw = useServiceWorker("/sw.js", {
+ *   onControllerChange: () => window.location.reload(),
+ * });
+ * const applyUpdate = () => sw.skipWaiting();
+ * ```
+ *
+ * @param scriptUrl Service worker script URL.
+ * @param options Container override, registration options and update hooks.
+ * @default options {}
+ * @returns Registration state and actions.
+ */
+declare function useServiceWorker(scriptUrl: MaybeRefOrGetter<string | URL>, options?: UseServiceWorkerOptions): ServiceWorkerControls;
+//#endregion
+export { ServiceWorkerContainerLike, ServiceWorkerControls, ServiceWorkerLike, ServiceWorkerRegisterOptions, ServiceWorkerRegistrationLike, ServiceWorkerStateName, ServiceWorkerStates, UseServiceWorkerOptions, useServiceWorker };