@xo-cash/utils 0.0.7 → 0.0.8-development.16556484698

package/dist/index.mjs

@@ -265,6 +265,21 @@ var ExternallyAbortedExponentialBackoffInternalSignalAbortedError = class extend
 //#endregion
 //#region source/misc.ts
 /**
+* Recursively freezes an object by iterating over all properties and freezing them.
+* @param obj - The object to freeze.
+* @returns The frozen object.
+*/
+const deepFreeze = (value) => {
+	if (value !== null && (typeof value === "object" || typeof value === "function")) {
+		for (const key of Reflect.ownKeys(value)) {
+			const descriptor = Reflect.getOwnPropertyDescriptor(value, key);
+			if (descriptor && "value" in descriptor) deepFreeze(descriptor.value);
+		}
+		Object.freeze(value);
+	}
+	return value;
+};
+/**
 * Validate the value is within the bounds, returning true if it is within the bounds, false otherwise
 *
 * @param value - The value to validate
@@ -277,6 +292,14 @@ const isWithinBounds = (value, min, max) => {
 	if (value < min || value > max) return false;
 	return true;
 };
+/**
+* Converts a non-error to an error
+* @param error - The error to convert
+* @returns The error
+*/
+const normalizeError = (error) => {
+	return error instanceof Error ? error : /* @__PURE__ */ new Error(`${error}`);
+};
 
 //#endregion
 //#region source/exponential-backoff/exponential-backoff.ts
@@ -728,6 +751,26 @@ const SSE_TRAILING_NEWLINE_REGEX = /\n$/;
 * buffered partial lines between streamed chunks before the next parse call.
 */
 const NEW_LINE = "\n";
+/**
+* Default exponential backoff options for the SSE session.
+*/
+const SSE_SESSION_EXPONENTIAL_BACKOFF_DEFAULTS = {
+	baseDelay: 250,
+	maxDelay: 1e4,
+	maxAttempts: 0,
+	growthRate: 1.3,
+	jitter: .3
+};
+/**
+* Default attempt reconnect flag for the SSE session.
+* @default true
+*/
+const SSE_SESSION_ATTEMPT_RECONNECT_DEFAULT = true;
+/**
+* Default persistent flag for the SSE session.
+* @default false
+*/
+const SSE_SESSION_PERSISTENT_DEFAULT = false;
 
 //#endregion
 //#region source/sse-session/sse-event-parser.ts
@@ -880,6 +923,447 @@ var SSEEventParser = class {
 	}
 };
 
+//#endregion
+//#region source/sse-session/errors.ts
+/**
+* Error thrown when a response body is null
+*/
+var ResponseBodyNullError = class extends Error {
+	constructor() {
+		super("Response body is null");
+		this.name = "ResponseBodyNullError";
+	}
+};
+/**
+* Error thrown when an HTTP error occurs
+*/
+var HTTPError = class extends Error {
+	constructor(status, message) {
+		super(`HTTP error! Status: ${status} - ${message}`);
+		this.name = "HTTPError";
+	}
+};
+/**
+* Error thrown when a plugin's unsubscribe function is not a function
+*/
+var SSESessionUnsubscribePluginNotAFunctionError = class extends Error {
+	constructor(pluginName) {
+		super(`${pluginName}'s unsubscribe function is not a function`);
+		this.name = "SSESessionUnsubscribePluginNotAFunctionError";
+	}
+};
+
+//#endregion
+//#region source/sse-session/sse-session.ts
+/**
+* A fetch-based Server-Sent Events (SSE) client with reconnect and optional
+* browser tab visibility handling.
+*
+* Each session maintains one HTTP streaming connection at a time. Incoming
+* bytes are parsed into {@link SSEvent} objects and delivered through two
+* surfaces:
+*
+* - **Events** — `"connected"`, `"message"`, `"disconnected"`, `"error"`,
+*   and `"closed"` on the session itself (extends {@link EventEmitter}).
+* - **Messages** — {@link messages}, an async iterable for `for await...of`
+*   consumers.
+*
+* Typical usage:
+*
+* ```ts
+* const session = await SSESession.create("/events");
+*
+* session.on("message", (event) => console.log(event.data));
+*
+* for await (const event of session.messages) {
+*   handle(event);
+* }
+* ```
+*
+* ## Lifecycle
+*
+* - {@link connect} opens (or reopens) the transport. It resolves once the
+*   HTTP stream is established; reading continues in the background.
+* - {@link disconnect} stops the in-flight fetch without ending the session.
+*   Used internally for tab visibility. The {@link messages} iterator stays
+*   open so an existing consumer resumes when the tab becomes visible again.
+* - {@link close} aborts the transport, closes {@link messages}, and emits
+*   `"closed"`.
+*
+* Automatic reconnect is controlled by {@link SSESessionOptions.persistent}
+* (server closed the stream) and
+* {@link SSESessionOptions.attemptReconnect} (transport error).
+*
+* ## Connection supersession
+*
+* Each {@link connect} will create a new controller if one does not exist. Otherwise,
+* it will return immediately.
+*/
+var SSESession = class SSESession extends EventEmitter {
+	/**
+	* Creates a session and waits until the first connection is established.
+	*
+	* @param url - The SSE endpoint URL.
+	* @param options - Configuration merged with instance defaults.
+	* @returns A connected session.
+	* @throws When the initial connection cannot be established.
+	*/
+	static async create(url, options = {}) {
+		const session = new SSESession(url, options);
+		await session.connect();
+		return session;
+	}
+	/**
+	* Enables SSE resume semantics by sending `Last-Event-ID` on reconnect.
+	*
+	* Listens for incoming `"message"` events and remembers the most recent
+	* {@link SSEvent.id}. On every subsequent connect or reconnect, the session's
+	* {@link onRequest} hook is wrapped so that header is attached when an id is
+	* known, allowing the server to replay only events the client has not yet
+	* received.
+	*
+	* The existing {@link onRequest} callback is preserved and runs after the
+	* header is applied, so auth or other header mutations continue to work.
+	*
+	* Since this relies on listening to the `"message"` event, this should ideally
+	* be called before "{@link connect} is called so no messages (and no ids) are missed.
+	*
+	* ```ts
+	* const session = new SSESession(url);
+	* SSESession.addLastEventIdReconnect(session);
+	* await session.connect();
+	* // Reconnects send Last-Event-ID once an event with an id is received.
+	* ```
+	*
+	* @param session - The session to instrument.
+	* @returns The same session, for chaining.
+	*/
+	static addLastEventIdReconnect(session) {
+		if (session.plugins.has(SSESession.addLastEventIdReconnect)) {
+			const removeListener = session.plugins.get(SSESession.addLastEventIdReconnect);
+			if (typeof removeListener !== "function") throw new SSESessionUnsubscribePluginNotAFunctionError("addLastEventIdReconnect");
+			return {
+				session,
+				removeListener
+			};
+		}
+		let lastEventId;
+		const messageListener = (event) => {
+			lastEventId = event.id ?? lastEventId;
+		};
+		session.on("message", messageListener);
+		const originalOnRequest = session.options.onRequest;
+		let enabled = true;
+		session.options.onRequest = async (request) => {
+			if (lastEventId && enabled) request.headers = {
+				...request.headers,
+				"Last-Event-ID": lastEventId
+			};
+			return originalOnRequest(request);
+		};
+		const removeListener = () => {
+			enabled = false;
+			session.off("message", messageListener);
+			if (session.plugins.get(SSESession.addLastEventIdReconnect) === removeListener) session.plugins.delete(SSESession.addLastEventIdReconnect);
+		};
+		session.plugins.set(SSESession.addLastEventIdReconnect, removeListener);
+		return {
+			session,
+			removeListener
+		};
+	}
+	/**
+	* Pauses and resumes a session based on browser tab visibility.
+	*
+	* Uses the Page Visibility API (`document.visibilitychange`):
+	*
+	* - **hidden** — {@link disconnect} stops the active fetch. {@link messages}
+	*   stays open; `"disconnected"` fires but `"closed"` does not.
+	* - **visible** — {@link connect} re-establishes the stream if needed.
+	*
+	* This controller will not re-connect if the session was disconnected by something else.
+	*
+	* No-op in non-browser environments where `document` is undefined.
+	*
+	* @param session - The session to manage.
+	*/
+	static addBrowserVisibilityHandler(session) {
+		if (typeof document === "undefined") return { session };
+		if (session.plugins.has(SSESession.addBrowserVisibilityHandler)) {
+			const removeListener = session.plugins.get(SSESession.addBrowserVisibilityHandler);
+			if (typeof removeListener !== "function") throw new SSESessionUnsubscribePluginNotAFunctionError("addBrowserVisibilityHandler");
+			return {
+				session,
+				removeListener
+			};
+		}
+		const reconnectOnVisible = async () => {
+			if (document.visibilityState === "visible") {
+				document.removeEventListener("visibilitychange", reconnectOnVisible);
+				await session.connect();
+			}
+		};
+		const disableOnExternalDisconnect = ({ source }) => {
+			if (source !== SSESession.addBrowserVisibilityHandler) document.removeEventListener("visibilitychange", reconnectOnVisible);
+		};
+		const handleVisibilityChange = async () => {
+			if (!session.active) return;
+			if (document.visibilityState === "hidden") {
+				document.addEventListener("visibilitychange", reconnectOnVisible);
+				session.disconnect({ source: SSESession.addBrowserVisibilityHandler });
+			}
+		};
+		document.addEventListener("visibilitychange", handleVisibilityChange);
+		session.on("beforeDisconnect", disableOnExternalDisconnect);
+		const removeListener = () => {
+			document.removeEventListener("visibilitychange", handleVisibilityChange);
+			document.removeEventListener("visibilitychange", reconnectOnVisible);
+			session.off("beforeDisconnect", disableOnExternalDisconnect);
+			if (session.plugins.get(SSESession.addBrowserVisibilityHandler) === removeListener) session.plugins.delete(SSESession.addBrowserVisibilityHandler);
+		};
+		session.plugins.set(SSESession.addBrowserVisibilityHandler, removeListener);
+		return {
+			session,
+			removeListener
+		};
+	}
+	/** SSE endpoint URL for this session. */
+	#url;
+	/**
+	* Per-instance configuration.
+	*
+	* Defaults live on the instance field (not a shared static) so each session
+	* gets its own {@link SSEEventParser} and {@link ExponentialBackoff}.
+	*/
+	options = {
+		fetch: (...args) => fetch(...args),
+		method: "GET",
+		headers: {
+			Accept: "text/event-stream",
+			"Cache-Control": "no-cache"
+		},
+		body: new FormData(),
+		onRequest: (request) => Promise.resolve(request),
+		retry: new ExponentialBackoff({ ...SSE_SESSION_EXPONENTIAL_BACKOFF_DEFAULTS }),
+		attemptReconnect: SSE_SESSION_ATTEMPT_RECONNECT_DEFAULT,
+		persistent: SSE_SESSION_PERSISTENT_DEFAULT,
+		eventParser: new SSEEventParser()
+	};
+	/**
+	* Registered plugins for the session.
+	* This can be used to prevent duplicate plugins from being added to the session.
+	* The value for a plugin is arbitrary, for example a function that removes the plugin.
+	*/
+	plugins = /* @__PURE__ */ new Map();
+	/** AbortController for the currently active fetch, if any. */
+	#connectionController = null;
+	/** The server's requested retry interval in milliseconds (per SSE spec) if any */
+	#retryInterval = null;
+	/**
+	* Asynchronous stream of parsed SSE events for the active connection.
+	*
+	* Stays open across {@link disconnect} and automatic reconnects so an existing
+	* `for await` consumer keeps receiving events after visibility resumes.
+	*
+	* Closes when:
+	* - the server ends the stream and {@link SSESessionOptions.persistent}
+	*   is false,
+	* - {@link close} is called, or
+	* - a transport error occurs with
+	*   {@link SSESessionOptions.attemptReconnect} disabled.
+	*
+	* A later {@link connect} replaces this with a new iterator when the
+	* previous one was closed. Consumers should read from `session.messages`
+	* rather than caching a reference across terminal disconnects.
+	*/
+	messages = new AsyncPushIterator();
+	constructor(url, options = {}) {
+		super();
+		const { onConnected, onDisconnected, onError, ...restOptions } = options;
+		this.#url = url;
+		this.options = {
+			...this.options,
+			...restOptions,
+			headers: {
+				...this.options.headers,
+				...options.headers
+			}
+		};
+		if (onConnected) this.on("connected", onConnected);
+		if (onDisconnected) this.on("disconnected", onDisconnected);
+		if (onError) this.on("error", onError);
+	}
+	/**
+	* Returns true if the session is active by checking if the controller is not null.
+	*/
+	get active() {
+		return this.#connectionController !== null;
+	}
+	/**
+	* Connects or reconnects to the SSE endpoint.
+	*
+	* Resolves once the HTTP stream is established and `"connected"` has been
+	* emitted. Body reading continues asynchronously in the background via the
+	* internal `#readStream` method.
+	*
+	* @throws When the fetch retry policy exhausts attempts or the connection
+	*   is superseded before the reader is handed off (in the latter case the
+	*   promise resolves without throwing).
+	*/
+	async connect() {
+		if (this.#connectionController) return;
+		this.#resetEventParser();
+		this.#ensureMessageStreamOpen();
+		const connectionController = new AbortController();
+		this.#connectionController = connectionController;
+		const { method, headers, body } = this.options;
+		const fetchOptions = {
+			method,
+			headers: headers || {},
+			signal: connectionController.signal,
+			cache: "no-store"
+		};
+		if (method === "POST") fetchOptions.body = body || null;
+		let reader;
+		try {
+			reader = await this.options.retry.run(() => this.#createReader(fetchOptions), { signal: connectionController.signal });
+		} catch (error) {
+			if (this.#connectionController !== connectionController) return;
+			this.#connectionController = null;
+			const normalizedError = normalizeError(error);
+			this.emit("disconnected", {
+				reason: "error",
+				error: normalizedError
+			});
+			this.emit("error", normalizedError);
+			this.#closeMessageStream();
+			throw error;
+		}
+		if (this.#connectionController !== connectionController) {
+			await reader.cancel();
+			return;
+		}
+		this.emit("connected", void 0);
+		this.#readStream(reader, connectionController).catch((error) => {
+			this.emit("error", error);
+		});
+	}
+	/**
+	* Disconnects only the currently active transport.
+	*
+	* `beforeDisconnect` is emitted on every invocation, even when no
+	* transport is currently active. This allows observers to react to
+	* an explicit disconnect operation.
+	*
+	* @param context - Context describing the operation initiator.
+	* @emits `beforeDisconnect` with the supplied operation context.
+	* @emits `disconnected` with reason `"disconnect"` when an active
+	* transport is actually disconnected.
+	*/
+	disconnect(context = {}) {
+		this.emit("beforeDisconnect", context);
+		if (this.#connectionController) {
+			const connectionController = this.#connectionController;
+			this.#connectionController = null;
+			connectionController.abort();
+			this.emit("disconnected", {
+				reason: "disconnect",
+				source: context.source
+			});
+		}
+		this.#resetEventParser();
+	}
+	/**
+	* Terminates the session and disables attached visibility handling until
+	* the same instance is manually {@link connect connected} again.
+	*
+	* Closes {@link messages} and emits `"closed"`.
+	*/
+	close() {
+		this.disconnect();
+		this.#closeMessageStream();
+		this.emit("closed", void 0);
+	}
+	/**
+	* Performs the HTTP request and returns a reader for the response body.
+	*
+	* {@link SSESessionOptions.onRequest} may mutate headers (for example auth
+	* tokens or `Last-Event-ID`) before the fetch runs.
+	*/
+	async #createReader(fetchOptions) {
+		const requestOptions = await this.options.onRequest(fetchOptions);
+		const response = await this.options.fetch(this.#url, requestOptions);
+		if (!response.ok) {
+			const responseCode = response.status;
+			const error = new HTTPError(responseCode, await response.text());
+			this.emit("error", error);
+			throw error;
+		}
+		if (!response.body) {
+			const error = new ResponseBodyNullError();
+			this.emit("error", error);
+			throw error;
+		}
+		return response.body.getReader();
+	}
+	/**
+	* Reads bytes from an established stream until it ends, errors, or is
+	* superseded by a newer connection.
+	*/
+	async #readStream(reader, connectionController) {
+		try {
+			while (this.#connectionController === connectionController) {
+				const { done, value } = await reader.read();
+				if (this.#connectionController !== connectionController) return;
+				if (done) {
+					this.#connectionController = null;
+					this.emit("disconnected", { reason: "remote" });
+					if (this.options.persistent) await this.connect();
+					else this.#closeMessageStream();
+					return;
+				}
+				if (!value) continue;
+				for (const event of this.options.eventParser.parseEvents(value)) {
+					if (event.retry) this.#retryInterval = event.retry;
+					this.emit("message", event);
+					this.messages.push(event);
+				}
+			}
+		} catch (error) {
+			if (connectionController !== this.#connectionController) return;
+			this.#connectionController = null;
+			const normalizedError = normalizeError(error);
+			this.emit("disconnected", {
+				reason: "error",
+				error: normalizedError
+			});
+			if (connectionController.signal.aborted) return;
+			this.emit("error", normalizedError);
+			if (this.options.attemptReconnect) {
+				if (this.#retryInterval) await new Promise((resolve) => setTimeout(resolve, this.#retryInterval));
+				await this.connect();
+			} else this.#closeMessageStream();
+		}
+	}
+	/** Clears partial SSE frames left over from an abandoned transport. */
+	#resetEventParser() {
+		this.options.eventParser.reset();
+	}
+	/**
+	* Creates a new {@link messages} iterator when the previous one was closed
+	* by a terminal disconnect or server stream end.
+	*/
+	#ensureMessageStreamOpen() {
+		if (!this.messages.closed) return;
+		this.messages = new AsyncPushIterator();
+	}
+	/** Ends the message iteration loop for the current connection span. */
+	#closeMessageStream() {
+		if (this.messages.closed) return;
+		this.messages.close();
+	}
+};
+
 //#endregion
 //#region source/template/errors.ts
 /**
@@ -2521,5 +3005,5 @@ const compileCashAssemblyString = (parameters) => {
 };
 
 //#endregion
-export { AsyncPushIterator, CashAssemblyBlockCommentUnclosedError, CashAssemblyCompilationFailedError, CashAssemblyEvaluationUnclosedError, CashAssemblyIdentifierCollisionError, CashAssemblyNumberNotSafeIntegerError, CashAssemblyPrimitiveMethodMissingError, CashAssemblyPrimitiveVariableMissingError, CashAssemblyQuotedLiteralUnclosedError, CashAssemblyRequiredVariableMissingError, CashAssemblyUnsupportedValueTypeError, CashAssemblyVariableTypeMismatchError, CashAssemblyVmNumberDecodeError, EventEmitter, ExponentialBackoff, ExponentialBackoffExternallyAbortable, ExponentialBackoffMaxRetriesHitError, ExponentialBackoffNonIntegerError, ExponentialBackoffNumberNotFiniteError, ExponentialBackoffNumberOutOfBoundsError, ExponentialBackoffNumberTooSmallError, ExponentialBackoffStoppedRetriesError, ExternallyAbortedExponentialBackoffExternalSignalAbortedError, ExternallyAbortedExponentialBackoffInternalSignalAbortedError, SSEEventParser, TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, WaitForTimeoutError, bchVmVersionSchema, buildErrorDescription, collectVariablesUsingParseScript, compileCashAssemblyString, extendedJsonReplacer, extendedJsonReviver, extractCashAssemblyEvaluations, fromExtendedJson, generateTemplateIdentifier, isCashAssemblyExpression, parseTemplate, satoshisSchema, scriptToScriptHash, serializeTemplate, toExtendedJson, uint8ArraySchema, xoTemplateActionIntentSchema, xoTemplateActionRequirementsSchema, xoTemplateActionRoleRequirementsSchema, xoTemplateActionRoleSchema, xoTemplateActionSchema, xoTemplateAssetAmountsSchema, xoTemplateConstantSchema, xoTemplateDataSchema, xoTemplateDefaultsSchema, xoTemplateIconSchema, xoTemplateImportDefaultValueSchema, xoTemplateInputSchema, xoTemplateIntentSchema, xoTemplateLockingScriptIntentSchema, xoTemplateLockingScriptRoleSchema, xoTemplateLockingScriptSchema, xoTemplateLockingTypeSchema, xoTemplateNftCapabilitySchema, xoTemplateNonFungibleTokenDetailsSchema, xoTemplateOutputIntentSchema, xoTemplateOutputSchema, xoTemplatePrimitiveTypeSchema, xoTemplateResourceSchema, xoTemplateRoleSlotSchema, xoTemplateRoleSlotsRequirementsSchema, xoTemplateSchema, xoTemplateStateSchema, xoTemplateTokenSchema, xoTemplateTransactionInputSchema, xoTemplateTransactionOutputSchema, xoTemplateTransactionRoleDataSchema, xoTemplateTransactionSchema, xoTemplateVariableSchema, xoTemplateViewPropertiesSchema };
+export { AsyncPushIterator, CashAssemblyBlockCommentUnclosedError, CashAssemblyCompilationFailedError, CashAssemblyEvaluationUnclosedError, CashAssemblyIdentifierCollisionError, CashAssemblyNumberNotSafeIntegerError, CashAssemblyPrimitiveMethodMissingError, CashAssemblyPrimitiveVariableMissingError, CashAssemblyQuotedLiteralUnclosedError, CashAssemblyRequiredVariableMissingError, CashAssemblyUnsupportedValueTypeError, CashAssemblyVariableTypeMismatchError, CashAssemblyVmNumberDecodeError, EventEmitter, ExponentialBackoff, ExponentialBackoffExternallyAbortable, ExponentialBackoffMaxRetriesHitError, ExponentialBackoffNonIntegerError, ExponentialBackoffNumberNotFiniteError, ExponentialBackoffNumberOutOfBoundsError, ExponentialBackoffNumberTooSmallError, ExponentialBackoffStoppedRetriesError, ExternallyAbortedExponentialBackoffExternalSignalAbortedError, ExternallyAbortedExponentialBackoffInternalSignalAbortedError, SSEEventParser, SSESession, TemplateInvalidError, TemplateJsonMalformedError, TemplateSerializationFailedError, VIEW_PROPERTIES_DESCRIPTION_MAX_LENGTH, VIEW_PROPERTIES_ICON_MAX_LENGTH, VIEW_PROPERTIES_NAME_MAX_LENGTH, WaitForTimeoutError, bchVmVersionSchema, buildErrorDescription, collectVariablesUsingParseScript, compileCashAssemblyString, deepFreeze, extendedJsonReplacer, extendedJsonReviver, extractCashAssemblyEvaluations, fromExtendedJson, generateTemplateIdentifier, isCashAssemblyExpression, isWithinBounds, normalizeError, parseTemplate, satoshisSchema, scriptToScriptHash, serializeTemplate, toExtendedJson, uint8ArraySchema, xoTemplateActionIntentSchema, xoTemplateActionRequirementsSchema, xoTemplateActionRoleRequirementsSchema, xoTemplateActionRoleSchema, xoTemplateActionSchema, xoTemplateAssetAmountsSchema, xoTemplateConstantSchema, xoTemplateDataSchema, xoTemplateDefaultsSchema, xoTemplateIconSchema, xoTemplateImportDefaultValueSchema, xoTemplateInputSchema, xoTemplateIntentSchema, xoTemplateLockingScriptIntentSchema, xoTemplateLockingScriptRoleSchema, xoTemplateLockingScriptSchema, xoTemplateLockingTypeSchema, xoTemplateNftCapabilitySchema, xoTemplateNonFungibleTokenDetailsSchema, xoTemplateOutputIntentSchema, xoTemplateOutputSchema, xoTemplatePrimitiveTypeSchema, xoTemplateResourceSchema, xoTemplateRoleSlotSchema, xoTemplateRoleSlotsRequirementsSchema, xoTemplateSchema, xoTemplateStateSchema, xoTemplateTokenSchema, xoTemplateTransactionInputSchema, xoTemplateTransactionOutputSchema, xoTemplateTransactionRoleDataSchema, xoTemplateTransactionSchema, xoTemplateVariableSchema, xoTemplateViewPropertiesSchema };
 //# sourceMappingURL=index.mjs.map