@dex-ai/sdk 0.1.30

package/src/util.ts

@@ -0,0 +1,110 @@
+/** Small helpers used across the agent loop. */
+
+import type { StandardSchemaV1 } from "./index";
+
+/**
+ * Format an error with full stack trace for troubleshooting.
+ * Handles nested errors, non-Error throws, and provider metadata.
+ */
+export function formatError(err: unknown): string {
+	if (!(err instanceof Error)) {
+		return `Non-Error thrown: ${JSON.stringify(err)}`;
+	}
+
+	const parts: string[] = [];
+	parts.push(`${err.name}: ${err.message}`);
+
+	// Include stack trace
+	if (err.stack) {
+		// Strip the first line (it's the message, already shown)
+		const stackLines = err.stack.split("\n").slice(1);
+		if (stackLines.length > 0) {
+			parts.push(stackLines.slice(0, 15).join("\n"));
+			if (stackLines.length > 15) {
+				parts.push(`  ... ${stackLines.length - 15} more frames`);
+			}
+		}
+	}
+
+	// Provider-specific metadata (e.g. HTTP status, response body)
+	const meta = (err as any).status ?? (err as any).statusCode;
+	if (meta) parts.push(`  HTTP status: ${meta}`);
+	const code = (err as any).code;
+	if (code) parts.push(`  code: ${code}`);
+	const type = (err as any).type;
+	if (type) parts.push(`  type: ${type}`);
+
+	// Nested cause (Error.cause)
+	if ((err as any).cause) {
+		parts.push(`  caused by: ${formatError((err as any).cause)}`);
+	}
+
+	return parts.join("\n");
+}
+
+/** Validate a value against a Standard Schema. Returns either { value } or { issues }. */
+export async function validateWithSchema<I, O>(
+	schema: StandardSchemaV1<I, O>,
+	value: unknown,
+) {
+	const res = await schema["~standard"].validate(value);
+	return res;
+}
+
+/** Merge two optional AbortSignals into one AbortController.signal. */
+export function mergeSignals(
+	a?: AbortSignal,
+	b?: AbortSignal,
+): { signal: AbortSignal; dispose: () => void } {
+	const ctrl = new AbortController();
+	const relay = (reason: unknown) => ctrl.abort(reason);
+	const la = a && (() => relay(a!.reason));
+	const lb = b && (() => relay(b!.reason));
+	if (a?.aborted) ctrl.abort(a.reason);
+	else if (b?.aborted) ctrl.abort(b.reason);
+	if (la) a!.addEventListener("abort", la, { once: true });
+	if (lb) b!.addEventListener("abort", lb, { once: true });
+	const dispose = () => {
+		if (la) a!.removeEventListener("abort", la);
+		if (lb) b!.removeEventListener("abort", lb);
+	};
+	return { signal: ctrl.signal, dispose };
+}
+
+/** A queue-backed push channel that becomes an AsyncIterable. Used to fan out StreamParts to callers. */
+export class PushStream<T> implements AsyncIterable<T> {
+	private buffer: T[] = [];
+	private resolvers: Array<(r: IteratorResult<T>) => void> = [];
+	private closed = false;
+	private failure: unknown = null;
+
+	push(v: T) {
+		if (this.closed) return;
+		const r = this.resolvers.shift();
+		if (r) r({ value: v, done: false });
+		else this.buffer.push(v);
+	}
+	close() {
+		this.closed = true;
+		while (this.resolvers.length)
+			this.resolvers.shift()!({ value: undefined as any, done: true });
+	}
+	fail(err: unknown) {
+		this.failure = err;
+		this.close();
+	}
+	[Symbol.asyncIterator](): AsyncIterator<T> {
+		return {
+			next: () => {
+				if (this.buffer.length)
+					return Promise.resolve({ value: this.buffer.shift()!, done: false });
+				if (this.failure) return Promise.reject(this.failure);
+				if (this.closed)
+					return Promise.resolve({ value: undefined as any, done: true });
+				return new Promise<IteratorResult<T>>((resolve) =>
+					this.resolvers.push(resolve),
+				);
+			},
+		};
+	}
+}