@vampgg/utils 1.0.0-beta.1

package/dist/create-event-iterator.d.mts

@@ -0,0 +1,39 @@
+import { AsyncQueue, AsyncQueueOptions } from "./async-queue.mjs";
+
+//#region src/create-event-iterator.d.ts
+type Context<T> = {
+  emit: (value: T) => void; /** Terminate the stream as a clean completion. */
+  cancel: () => void; /** Terminate the stream with an error thrown into the consumer's `for await`. */
+  error: (e: unknown) => void;
+};
+type CleanupFn = () => void | Promise<void>;
+type Subscriber<T> = (context: Context<T>) => void | CleanupFn | Promise<CleanupFn | void>;
+/**
+ * Wrap an {@link AsyncQueue} in a hand-rolled async iterator that delegates
+ * `next`/`return`/`throw` directly to the queue.
+ *
+ * This deliberately does NOT use an `async function*` wrapper. An async
+ * generator serializes `next`/`return`/`throw` through an internal request
+ * queue, so a `return()` issued while a `next()` is still parked (the common
+ * "consume in the background, then call `return()` to stop" pattern) is queued
+ * *behind* that pending `next()`. The pending `next()` only settles once the
+ * queue is closed — which is exactly what the queued `return()` would do — so
+ * the two deadlock and the stream hangs forever. A plain object iterator has no
+ * such serialization: `return()` runs immediately, `queue.return()` resolves the
+ * parked `next()`, and the consumer's `for await` ends cleanly.
+ *
+ * `start` is invoked lazily on the first pull (matching the lazy semantics of
+ * the previous `async function*` body, whose code did not run until the first
+ * `next()`), and is awaited by `return()`/`throw()` so a subscription that has
+ * begun establishing always has its cleanup captured before dispose runs.
+ */
+declare function queueIterator<T>(queue: AsyncQueue<T>, start: () => Promise<void>): AsyncGenerator<T>;
+/**
+ * Bridge a callback-style event source into an async iterator backed by a
+ * bounded {@link AsyncQueue}. The subscriber receives `{ emit, cancel, error }`
+ * and may return a cleanup function, which runs exactly once when the stream
+ * terminates (close / error / consumer `break` / consumer `return()` / throw).
+ */
+declare function createEventIterator<T>(subscriber: Subscriber<T>, options?: AsyncQueueOptions): AsyncGenerator<T>;
+//#endregion
+export { CleanupFn, Context, Subscriber, createEventIterator, queueIterator };

package/dist/create-event-iterator.mjs

@@ -0,0 +1,67 @@
+import { AsyncQueue } from "./async-queue.mjs";
+//#region src/create-event-iterator.ts
+/**
+* Wrap an {@link AsyncQueue} in a hand-rolled async iterator that delegates
+* `next`/`return`/`throw` directly to the queue.
+*
+* This deliberately does NOT use an `async function*` wrapper. An async
+* generator serializes `next`/`return`/`throw` through an internal request
+* queue, so a `return()` issued while a `next()` is still parked (the common
+* "consume in the background, then call `return()` to stop" pattern) is queued
+* *behind* that pending `next()`. The pending `next()` only settles once the
+* queue is closed — which is exactly what the queued `return()` would do — so
+* the two deadlock and the stream hangs forever. A plain object iterator has no
+* such serialization: `return()` runs immediately, `queue.return()` resolves the
+* parked `next()`, and the consumer's `for await` ends cleanly.
+*
+* `start` is invoked lazily on the first pull (matching the lazy semantics of
+* the previous `async function*` body, whose code did not run until the first
+* `next()`), and is awaited by `return()`/`throw()` so a subscription that has
+* begun establishing always has its cleanup captured before dispose runs.
+*/
+function queueIterator(queue, start) {
+	let started;
+	const ensureStarted = () => {
+		started ??= start();
+		return started;
+	};
+	return {
+		async next() {
+			await ensureStarted();
+			return queue.next();
+		},
+		async return(value) {
+			if (started !== void 0) await started.catch(() => {});
+			return queue.return(value);
+		},
+		async throw(e) {
+			if (started !== void 0) await started.catch(() => {});
+			return queue.throw(e);
+		},
+		[Symbol.asyncIterator]() {
+			return this;
+		}
+	};
+}
+/**
+* Bridge a callback-style event source into an async iterator backed by a
+* bounded {@link AsyncQueue}. The subscriber receives `{ emit, cancel, error }`
+* and may return a cleanup function, which runs exactly once when the stream
+* terminates (close / error / consumer `break` / consumer `return()` / throw).
+*/
+function createEventIterator(subscriber, options) {
+	let unsubscribe;
+	const queue = new AsyncQueue(options, () => unsubscribe?.());
+	const context = {
+		emit: (value) => {
+			queue.push(value);
+		},
+		cancel: () => queue.close(),
+		error: (e) => queue.fail(e)
+	};
+	return queueIterator(queue, async () => {
+		unsubscribe = await subscriber(context);
+	});
+}
+//#endregion
+export { createEventIterator, queueIterator };

package/dist/debug-logger.d.mts

@@ -0,0 +1,43 @@
+import { ContextLogger } from "./context-logger.mjs";
+import { ConsoleLogger, TempoLogLevel, TempoLogger } from "@tempojs/common";
+
+//#region src/debug-logger.d.ts
+declare class DebugLogger extends ContextLogger implements ConsoleLogger {
+  bindings: Record<string, unknown>;
+  private debuggers;
+  sourceName: string;
+  logLevel: TempoLogLevel;
+  protected readonly children: Set<TempoLogger>;
+  constructor(sourceName: string, logLevel?: TempoLogLevel, parent?: TempoLogger, bindings?: Record<string, unknown>);
+  correlate<TLogger extends TempoLogger>(sourceName: string, correlationId: string, asOrphan?: boolean, bindings?: Record<string, unknown>): TLogger;
+  clone<TLogger extends TempoLogger>(sourceName: string, asOrphan?: boolean, bindings?: Record<string, unknown>): TLogger;
+  write(level: TempoLogLevel, message: string, data?: Record<string, unknown>, error?: Error): void;
+  /**
+   * @inheritDoc
+   */
+  trace(message: string, data?: Record<string, unknown>, error?: Error): void;
+  /**
+   * @inheritDoc
+   */
+  debug(message: string, data?: Record<string, unknown>, error?: Error): void;
+  /**
+   * @inheritDoc
+   */
+  info(message: string, data?: Record<string, unknown>, error?: Error): void;
+  /**
+   * @inheritDoc
+   */
+  warn(message: string, data?: Record<string, unknown>, error?: Error): void;
+  /**
+   * @inheritDoc
+   */
+  error(message: string, data?: Record<string, unknown>, error?: Error): void;
+  /**
+   * @inheritDoc
+   */
+  critical(message: string, data?: Record<string, unknown>, error?: Error): void;
+  setLogLevel(level: TempoLogLevel): void;
+  formatErrorMessage(error: Error, indentLevel?: number): string;
+}
+//#endregion
+export { DebugLogger };

package/dist/debug-logger.mjs

@@ -0,0 +1,122 @@
+import { ContextLogger } from "./context-logger.mjs";
+import { TempoLogLevel } from "@tempojs/common";
+import debug from "debug";
+//#region src/debug-logger.ts
+var DebugLogger = class DebugLogger extends ContextLogger {
+	bindings = {};
+	debuggers;
+	sourceName;
+	logLevel;
+	children = /* @__PURE__ */ new Set();
+	constructor(sourceName, logLevel = TempoLogLevel.Info, parent, bindings = {}) {
+		super(sourceName, logLevel, parent, bindings);
+		this.sourceName = sourceName;
+		this.logLevel = logLevel;
+		this.debuggers = {
+			trace: debug(`${sourceName}:trace`),
+			debug: debug(`${sourceName}:debug`),
+			info: debug(`${sourceName}:info`),
+			warn: debug(`${sourceName}:warn`),
+			error: debug(`${sourceName}:error`),
+			critical: debug(`${sourceName}:critical`)
+		};
+	}
+	correlate(sourceName, correlationId, asOrphan, bindings) {
+		return this.clone(sourceName, asOrphan, {
+			...bindings,
+			correlationId
+		});
+	}
+	clone(sourceName, asOrphan, bindings) {
+		const logger = new DebugLogger(asOrphan ? sourceName : `${this.sourceName}:${sourceName}`, this.logLevel, asOrphan !== true ? this : void 0, {
+			...this.bindings,
+			...bindings
+		});
+		if (asOrphan !== true) this.children.add(logger);
+		return logger;
+	}
+	write(level, message, data = {}, error) {
+		if (level < this.logLevel) return;
+		let logError = "";
+		if (error) {
+			logError = `\n${this.formatErrorMessage(error)}`;
+			data.error = logError;
+		}
+		const fullMessage = `${message}${` ${JSON.stringify({
+			...this.bindings,
+			...data
+		}, null, 2)}`}`;
+		switch (level) {
+			case TempoLogLevel.Trace:
+				this.debuggers.trace(fullMessage);
+				break;
+			case TempoLogLevel.Debug:
+				this.debuggers.debug(fullMessage);
+				break;
+			case TempoLogLevel.Info:
+				this.debuggers.info(fullMessage);
+				break;
+			case TempoLogLevel.Warn:
+				this.debuggers.warn(fullMessage);
+				break;
+			case TempoLogLevel.Error:
+				this.debuggers.error(fullMessage);
+				break;
+			case TempoLogLevel.Critical:
+				this.debuggers.critical(fullMessage);
+				break;
+		}
+	}
+	/**
+	* @inheritDoc
+	*/
+	trace(message, data, error) {
+		this.write(TempoLogLevel.Trace, message, data, error);
+	}
+	/**
+	* @inheritDoc
+	*/
+	debug(message, data, error) {
+		this.write(TempoLogLevel.Debug, message, data, error);
+	}
+	/**
+	* @inheritDoc
+	*/
+	info(message, data, error) {
+		this.write(TempoLogLevel.Info, message, data, error);
+	}
+	/**
+	* @inheritDoc
+	*/
+	warn(message, data, error) {
+		this.write(TempoLogLevel.Warn, message, data, error);
+	}
+	/**
+	* @inheritDoc
+	*/
+	error(message, data, error) {
+		this.write(TempoLogLevel.Error, message, data, error);
+	}
+	/**
+	* @inheritDoc
+	*/
+	critical(message, data, error) {
+		this.write(TempoLogLevel.Critical, message, data, error);
+	}
+	setLogLevel(level) {
+		this.logLevel = level;
+	}
+	formatErrorMessage(error, indentLevel = 0) {
+		const indent = "  ".repeat(indentLevel);
+		const message = error.message || "Unknown error";
+		const indentedStack = (error.stack || "Stack unavailable").split("\n").map((line) => `${indent}${line}`).join("\n");
+		let cause = "";
+		if ("cause" in error) cause = error?.cause instanceof Error ? this.formatErrorMessage(error.cause, indentLevel + 1) : "";
+		return `
+${indent}Error message: ${message}
+${indentedStack}
+${indent}${cause ? `Cause: ${cause}` : ""}`.trimEnd();
+	}
+};
+//#endregion
+export { DebugLogger };

package/dist/error.d.mts

@@ -0,0 +1,27 @@
+import { Error } from "./bebop.mjs";
+import { TempoError } from "@tempojs/common";
+
+//#region src/error.d.ts
+declare class SystemError<Tag extends string> extends TempoError {
+  readonly _tag: Tag;
+  readonly cause: Error;
+  constructor(tag: Tag, error?: Partial<Omit<Error, "tag">>);
+  static generic(err: unknown, tag?: ErrorTags, opts?: Partial<Omit<Error, "tag">>): SystemError<ErrorTags>;
+}
+declare enum ErrorTags {
+  PgOutage = "PgOutage",
+  RedisOutage = "RedisOutage",
+  Unknown = "Unknown",
+  NeedPermissions = "NeedPermissions",
+  Validation = "Validation",
+  Authorization = "Authorization",
+  GameStateGeneration = "GameStateGeneration",
+  InvalidPrompt = "InvalidPrompt",
+  UnknownAIProvider = "UnknownAIProvider",
+  FailedToStart = "FailedToStart",
+  Unimplemented = "Unimplemented",
+  IncompatibleVersion = "IncompatibleVersion",
+  PingUnacceptable = "PingUnacceptable"
+}
+//#endregion
+export { ErrorTags, SystemError };

package/dist/error.mjs

@@ -0,0 +1,49 @@
+import { TempoError, TempoStatusCode } from "@tempojs/common";
+import defaults from "lodash-es/defaults";
+//#region src/error.ts
+var SystemError = class SystemError extends TempoError {
+	_tag;
+	cause;
+	constructor(tag, error) {
+		const err = defaults({ ...error }, {
+			code: TempoStatusCode.UNKNOWN,
+			stack: "",
+			msg: "Unknown error occured",
+			details: /* @__PURE__ */ new Map()
+		});
+		const cause = {
+			...err,
+			tag
+		};
+		super(err.code, err.msg, cause);
+		this._tag = tag;
+		this.cause = cause;
+	}
+	static generic(err, tag, opts) {
+		return new SystemError(tag || "Unknown", {
+			msg: err instanceof Error ? err.message : "Unknown error occured",
+			code: err instanceof TempoError ? err.status : TempoStatusCode.INTERNAL,
+			details: err instanceof Error ? err.cause instanceof Map ? err.cause : /* @__PURE__ */ new Map() : new Map([["cause", JSON.stringify(err?.cause || "")]]),
+			stack: err?.stack || "",
+			...opts
+		});
+	}
+};
+let ErrorTags = /* @__PURE__ */ function(ErrorTags) {
+	ErrorTags["PgOutage"] = "PgOutage";
+	ErrorTags["RedisOutage"] = "RedisOutage";
+	ErrorTags["Unknown"] = "Unknown";
+	ErrorTags["NeedPermissions"] = "NeedPermissions";
+	ErrorTags["Validation"] = "Validation";
+	ErrorTags["Authorization"] = "Authorization";
+	ErrorTags["GameStateGeneration"] = "GameStateGeneration";
+	ErrorTags["InvalidPrompt"] = "InvalidPrompt";
+	ErrorTags["UnknownAIProvider"] = "UnknownAIProvider";
+	ErrorTags["FailedToStart"] = "FailedToStart";
+	ErrorTags["Unimplemented"] = "Unimplemented";
+	ErrorTags["IncompatibleVersion"] = "IncompatibleVersion";
+	ErrorTags["PingUnacceptable"] = "PingUnacceptable";
+	return ErrorTags;
+}({});
+//#endregion
+export { ErrorTags, SystemError };

package/dist/extension-channel.d.mts

@@ -0,0 +1,96 @@
+import { Message } from "./bebop.mjs";
+import { BebopRecord } from "bebop";
+import { BebopContentType, Credential, Deadline, TempoError } from "@tempojs/common";
+import { BaseChannel, CallOptions, ClientContext, MethodInfo, RetryPolicy, TempoChannelOptions } from "@tempojs/client";
+
+//#region src/extension-channel.d.ts
+/**
+ * Represents a Tempo channel for communication with a remote server.
+ */
+declare class TempoExtensionChannel extends BaseChannel {
+  static readonly defaultMaxRetryAttempts: number;
+  static readonly defaultMaxReceiveMessageSize: number;
+  static readonly defaultMaxSendMessageSize: number;
+  static readonly defaultContentType: BebopContentType;
+  private readonly events;
+  private readonly userAgent;
+  readonly pending: Map<string, (e: unknown) => void>;
+  private closed;
+  private readonly onMessage;
+  /**
+   * Constructs a new TempoChannel instance.
+   *
+   * @param {URL} target - The target URL for the channel.
+   * @param {TempoWSChannelOptions} options - The configuration options for the channel.
+   * @protected
+   */
+  constructor(options?: TempoChannelOptions);
+  /**
+   * Tear down the channel: remove the runtime message listener, reject every
+   * in-flight call, and clear all event listeners. Idempotent.
+   */
+  close(reason?: TempoError): void;
+  removeCredential(): Promise<void>;
+  getCredential(): Promise<Credential | undefined>;
+  /**
+   * Executes a function with retries according to the provided retry policy.
+   * The function will be retried if it fails with a TempoError and its status code is included in the retryableStatusCodes of the retry policy.
+   * If a deadline is provided, the deadline for each attempt will be managed by the provided deadline, but the deadline will not be reset upon each retry.
+   *
+   * @template T - The type of the result returned by the function.
+   * @param {((retryAttempt: number) => Promise<T>)} func - A function that returns a Promise with a result. The function will receive a number indicating the current retry attempt.
+   * @param {RetryPolicy} retryPolicy - An object defining the retry policy, including maxAttempts, initialBackoff, maxBackoff, backoffMultiplier, and retryableStatusCodes.
+   * @param {Deadline} [deadline] - An optional deadline object that manages the timeout for each attempt.
+   * @param {AbortController} [abortController] - An optional AbortController instance to cancel the function execution.
+   * @returns {Promise<T>} - A Promise that resolves with the result of the function if it completes within the deadline and retry policy constraints.
+   * @throws {Error} - If the function execution fails and the error does not match the retry policy, or if the maximum number of attempts is reached without a successful result.
+   */
+  executeWithRetry<T>(func: (retryAttempt: number) => Promise<T>, retryPolicy: RetryPolicy, deadline?: Deadline, abortController?: AbortController): Promise<T>;
+  private fetchUnary;
+  private fetchClientStream;
+  private fetchServerStream;
+  private fetchDuplexStream;
+  /**
+   * Creates a `RequestInit` object for a given payload, context, method and optional call options.
+   * This object can be used to make an HTTP request using the Fetch API.
+   *
+   * @private
+   * @param {Uint8Array} payload - The payload to be sent in the request.
+   * @param {ClientContext} context - The context of the client making the request.
+   * @param {MethodInfo<BebopRecord, BebopRecord>} method - Information about the method being called.
+   * @param {CallOptions | undefined} options - Optional configuration for the call.
+   * @returns {Promise<RequestInit>} A Promise resolving to the created `RequestInit` object.
+   * @throws {TempoError} Throws an error if there's a problem while getting the credential header.
+   */
+  private createRequest;
+  /**
+   * Processes the headers of the response from the server, validating their integrity and correctness.
+   * Also sets the incoming metadata from the response headers to the provided context.
+   *
+   * @private
+   * @param {Response} response - The response received from the server.
+   * @param {ClientContext} context - The context of the client making the request.
+   * @param {MethodType} methodType - The type of method being called.
+   * @throws {TempoError} Throws an error if any validation checks fail or if there's a problem parsing or storing credentials.
+   */
+  private processResponseHeaders;
+  /**
+   * {@inheritDoc BaseChannel.startUnary}
+   */
+  startUnary<TRequest extends BebopRecord, TResponse extends BebopRecord>(request: TRequest, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<TResponse>;
+  /**
+   * {@inheritDoc BaseChannel.startClientStream}
+   */
+  startClientStream<TRequest extends BebopRecord, TResponse extends BebopRecord>(generator: () => AsyncGenerator<TRequest, void, undefined>, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<TResponse>;
+  /**
+   * {@inheritDoc BaseChannel.startServerStream}
+   */
+  startServerStream<TRequest extends BebopRecord, TResponse extends BebopRecord>(request: TRequest, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<AsyncGenerator<TResponse, void, undefined>>;
+  /**
+   * {@inheritDoc BaseChannel.startDuplexStream}
+   */
+  startDuplexStream<TRequest extends BebopRecord, TResponse extends BebopRecord>(generator: () => AsyncGenerator<TRequest, void, undefined>, context: ClientContext, method: MethodInfo<TRequest, TResponse>, options?: CallOptions): Promise<AsyncGenerator<TResponse, void, undefined>>;
+  protected sendMessage(message: Message): Promise<unknown>;
+}
+//#endregion
+export { TempoExtensionChannel };