@prometheus-ai/utils 0.5.0

package/src/snowflake.ts

@@ -0,0 +1,136 @@
+// 16-bit hex lookup table (65536 entries) for fast conversion
+const HEX4 = Array.from({ length: 65536 }, (_, i) => i.toString(16).padStart(4, "0"));
+
+function randu32() {
+	return crypto.getRandomValues(new Uint32Array(1))[0];
+}
+
+const EPOCH = 1420070400000;
+const MAX_SEQ = 0x3fffff;
+
+// Snowflake as a hex string (16 chars, zero-padded).
+//
+// Since this is not distributed (no machine ID needed), we use an extended
+// 22-bit sequence instead of the standard 10-bit machine ID + 12-bit sequence.
+//
+type Snowflake = string & { readonly __brand: unique symbol };
+
+namespace Snowflake {
+	// Hex string validation pattern (16 lowercase hex chars).
+	//
+	export const PATTERN = /^[0-9a-f]{16}$/;
+
+	// Epoch timestamp.
+	//
+	export const EPOCH_TIMESTAMP = EPOCH;
+
+	// Maximum sequence number.
+	//
+	export const MAX_SEQUENCE = MAX_SEQ;
+
+	// Parses a hex string or bigint to bigint.
+	//
+	function toBigInt(value: Snowflake): bigint {
+		const hi = Number.parseInt(value.substring(0, 8), 16);
+		const lo = Number.parseInt(value.substring(8, 16), 16);
+		return (BigInt(hi) << 32n) | BigInt(lo);
+	}
+
+	// Formats a sequence and timestamp into a snowflake hex string.
+	//
+	export function formatParts(dt: number, seq: number): Snowflake {
+		// Split dt into hi/lo to avoid exceeding Number.MAX_SAFE_INTEGER.
+		// dt is ~39 bits; dt<<22 would be ~61 bits, so we split at bit 10:
+		//   lo32 = (dtLo << 22) | seq   (10+22 = 32 bits, no overlap)
+		//   hi32 = dtHi                 (~29 bits)
+		const dtLo = dt % 1024;
+		const hi = (dt - dtLo) / 1024; // dt >>> 10
+		const lo = ((dtLo << 22) | seq) >>> 0;
+		const hi1 = (hi >>> 16) & 0xffff;
+		const hi2 = hi & 0xffff;
+		const lo1 = (lo >>> 16) & 0xffff;
+		const lo2 = lo & 0xffff;
+		return `${HEX4[hi1]}${HEX4[hi2]}${HEX4[lo1]}${HEX4[lo2]}` as Snowflake;
+	}
+
+	// Snowflake generator type.
+	//
+	export class Source {
+		#seq = 0;
+		constructor(sequence: number = randu32() & MAX_SEQ) {
+			this.#seq = sequence & MAX_SEQ;
+		}
+
+		// Sequence number.
+		//
+		get sequence() {
+			return this.#seq & MAX_SEQ;
+		}
+		set sequence(v: number) {
+			this.#seq = v & MAX_SEQ;
+		}
+		reset() {
+			this.#seq = 0;
+		}
+
+		// Generates the next value as a hex string.
+		//
+		generate(timestamp: number): Snowflake {
+			const seq = (this.#seq + 1) & MAX_SEQ;
+			const dt = timestamp - EPOCH;
+			this.#seq = seq;
+			return formatParts(dt, seq);
+		}
+	}
+
+	// Gets the next snowflake given the timestamp.
+	//
+	const defaultSource = new Source();
+	export function next(timestamp = Date.now()): Snowflake {
+		return defaultSource.generate(timestamp);
+	}
+
+	// Validates a snowflake hex string.
+	//
+	export function valid(value: string): value is Snowflake {
+		return value.length === 16 && PATTERN.test(value);
+	}
+
+	// Returns the upper/lower boundaries for the given timestamp.
+	//
+	export function lowerbound(timelike: Date | number | Snowflake): Snowflake {
+		switch (typeof timelike) {
+			case "object": // Date
+				return formatParts(timelike.getTime() - EPOCH, 0);
+			case "number":
+				return formatParts(timelike - EPOCH, 0);
+			case "string": // Snowflake hex string
+				return timelike;
+		}
+	}
+	export function upperbound(timelike: Date | number | Snowflake): Snowflake {
+		switch (typeof timelike) {
+			case "object": // Date
+				return formatParts(timelike.getTime() - EPOCH, MAX_SEQ);
+			case "number":
+				return formatParts(timelike - EPOCH, MAX_SEQ);
+			case "string": // Snowflake hex string
+				return timelike;
+		}
+	}
+
+	// Returns the individual bits given the snowflake.
+	//
+	export function getSequence(value: Snowflake) {
+		return Number.parseInt(value.substring(8, 16), 16) & MAX_SEQ;
+	}
+	export function getTimestamp(value: Snowflake) {
+		const n = toBigInt(value) >> 22n;
+		return Number(n + BigInt(EPOCH));
+	}
+	export function getDate(value: Snowflake) {
+		return new Date(getTimestamp(value));
+	}
+}
+
+export { Snowflake };

package/src/stream.ts

@@ -0,0 +1,403 @@
+import { createAbortableStream } from "./abortable";
+
+const LF = 0x0a;
+type JsonlChunkResult = {
+	values: unknown[];
+	error: unknown;
+	read: number;
+	done: boolean;
+};
+
+function parseJsonlChunkCompat(input: Uint8Array, beg?: number, end?: number): JsonlChunkResult;
+function parseJsonlChunkCompat(input: string): JsonlChunkResult;
+function parseJsonlChunkCompat(input: Uint8Array | string, beg?: number, end?: number): JsonlChunkResult {
+	if (typeof input === "string") {
+		const { values, error, read, done } = Bun.JSONL.parseChunk(input);
+		return { values, error, read, done };
+	}
+	const start = beg ?? 0;
+	const stop = end ?? input.length;
+	const { values, error, read, done } = Bun.JSONL.parseChunk(input, start, stop);
+	return { values, error, read, done };
+}
+
+export async function* readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array> {
+	const buffer = new ConcatSink();
+	const source = createAbortableStream(stream, signal);
+	try {
+		for await (const chunk of source) {
+			for (const line of buffer.appendAndFlushLines(chunk)) {
+				yield line;
+			}
+		}
+		if (!buffer.isEmpty) {
+			const tail = buffer.flush();
+			if (tail) {
+				buffer.clear();
+				yield tail;
+			}
+		}
+	} catch (err) {
+		// Abort errors are expected — just stop the generator.
+		if (signal?.aborted) return;
+		throw err;
+	}
+}
+
+export async function* readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T> {
+	const buffer = new ConcatSink();
+	const source = createAbortableStream(stream, signal);
+	try {
+		for await (const chunk of source) {
+			yield* buffer.pullJSONL<T>(chunk, 0, chunk.length);
+		}
+		if (!buffer.isEmpty) {
+			const tail = buffer.flush();
+			if (tail) {
+				buffer.clear();
+				const { values, error, done } = parseJsonlChunkCompat(tail, 0, tail.length);
+				if (values.length > 0) {
+					yield* values as T[];
+				}
+				if (error) throw error;
+				if (!done) {
+					throw new Error("JSONL stream ended unexpectedly");
+				}
+			}
+		}
+	} catch (err) {
+		// Abort errors are expected — just stop the generator.
+		if (signal?.aborted) return;
+		throw err;
+	}
+}
+
+// =============================================================================
+// SSE (Server-Sent Events)
+// =============================================================================
+
+class ConcatSink {
+	#space?: Buffer;
+	#length = 0;
+
+	#ensureCapacity(size: number): Buffer {
+		const space = this.#space;
+		if (space && space.length >= size) return space;
+		const nextSize = space ? Math.max(size, space.length * 2) : size;
+		const next = Buffer.allocUnsafe(nextSize);
+		if (space && this.#length > 0) {
+			space.copy(next, 0, 0, this.#length);
+		}
+		this.#space = next;
+		return next;
+	}
+
+	append(chunk: Uint8Array) {
+		const n = chunk.length;
+		if (!n) return;
+		const offset = this.#length;
+		const space = this.#ensureCapacity(offset + n);
+		space.set(chunk, offset);
+		this.#length += n;
+	}
+
+	reset(chunk: Uint8Array) {
+		const n = chunk.length;
+		if (!n) {
+			this.#length = 0;
+			return;
+		}
+		const space = this.#ensureCapacity(n);
+		space.set(chunk, 0);
+		this.#length = n;
+	}
+
+	get isEmpty(): boolean {
+		return this.#length === 0;
+	}
+
+	flush(): Uint8Array | undefined {
+		if (!this.#length) return undefined;
+		return this.#space!.subarray(0, this.#length);
+	}
+
+	clear() {
+		this.#length = 0;
+	}
+
+	*appendAndFlushLines(chunk: Uint8Array) {
+		let pos = 0;
+		while (pos < chunk.length) {
+			const nl = chunk.indexOf(LF, pos);
+			if (nl === -1) {
+				this.append(chunk.subarray(pos));
+				return;
+			}
+			const suffix = chunk.subarray(pos, nl);
+			pos = nl + 1;
+			if (this.isEmpty) {
+				yield suffix;
+			} else {
+				this.append(suffix);
+				const payload = this.flush();
+				if (payload) {
+					yield payload;
+					this.clear();
+				}
+			}
+		}
+	}
+	*pullJSONL<T>(chunk: Uint8Array, beg: number, end: number) {
+		if (this.isEmpty) {
+			const { values, error, read, done } = parseJsonlChunkCompat(chunk, beg, end);
+			if (values.length > 0) {
+				yield* values as T[];
+			}
+			if (error) throw error;
+			if (done) return;
+			this.reset(chunk.subarray(read, end));
+			return;
+		}
+
+		const offset = this.#length;
+		const n = end - beg;
+		const total = offset + n;
+		const space = this.#ensureCapacity(total);
+		space.set(chunk.subarray(beg, end), offset);
+		this.#length = total;
+
+		const { values, error, read, done } = parseJsonlChunkCompat(space.subarray(0, total), 0, total);
+		if (values.length > 0) {
+			yield* values as T[];
+		}
+		if (error) throw error;
+		if (done) {
+			this.#length = 0;
+			return;
+		}
+		const rem = total - read;
+		if (rem < total) {
+			space.copyWithin(0, read, total);
+		}
+		this.#length = rem;
+	}
+}
+
+/**
+ * Stream parsed JSON objects from SSE `data:` lines.
+ *
+ * Thin wrapper over {@link readSseEvents}: yields one parsed JSON value per
+ * dispatched SSE event, skipping events with empty `data` and stopping at the
+ * OpenAI-style `[DONE]` sentinel. If your consumer doesn't care about `event:`
+ * names or doesn't need a custom parse step, use this; otherwise call
+ * `readSseEvents` directly.
+ *
+ * @example
+ * ```ts
+ * for await (const obj of readSseJson(response.body!)) {
+ *   console.log(obj);
+ * }
+ * ```
+ */
+export type SseEventObserver = (event: ServerSentEvent) => void;
+
+function notifySseEventObserver(observer: SseEventObserver | undefined, event: ServerSentEvent): void {
+	if (!observer) return;
+	try {
+		observer(event);
+	} catch {
+		// Diagnostic observers must never perturb provider stream consumption.
+	}
+}
+
+export async function* readSseJson<T>(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+	onEvent?: SseEventObserver,
+): AsyncGenerator<T> {
+	for await (const sse of readSseEvents(stream, signal)) {
+		notifySseEventObserver(onEvent, sse);
+		const data = sse.data;
+		if (data === "" || data === "[DONE]") {
+			if (data === "[DONE]") return;
+			continue;
+		}
+		yield JSON.parse(data) as T;
+	}
+}
+
+/**
+ * A single Server-Sent Event dispatched on a blank-line boundary.
+ *
+ * - `event` is the value of the most recent `event:` field, or `null` if none.
+ * - `data` is the concatenation (joined by `\n`) of every `data:` field in the
+ *   event, exactly as required by the SSE spec.
+ * - `raw` is the list of decoded non-empty lines that made up the event,
+ *   preserved for diagnostic context (error reporting, debugging). The
+ *   dispatching blank line is not included.
+ */
+export interface ServerSentEvent {
+	event: string | null;
+	data: string;
+	raw: string[];
+}
+
+interface SseEventState {
+	event: string | null;
+	// `data` accumulates across multiple `data:` lines per the SSE spec, joined
+	// by `\n`. We keep the running string here and append as lines arrive instead
+	// of buffering an array and joining at flush. `null` means "no data: field
+	// seen yet" (distinct from a `data:` field with an empty value).
+	data: string | null;
+	raw: string[];
+}
+
+// Single decoder reused for all line decodes. Safe because lines are split on
+// LF (0x0a) which is always a single-byte ASCII char in UTF-8 and never appears
+// inside a multi-byte sequence — so each line is itself a complete UTF-8 run.
+const SSE_LINE_DECODER = new TextDecoder("utf-8");
+
+function decodeSseLineBytes(line: Uint8Array, end: number): string {
+	return end === line.length ? SSE_LINE_DECODER.decode(line) : SSE_LINE_DECODER.decode(line.subarray(0, end));
+}
+
+function flushSseEvent(state: SseEventState): ServerSentEvent | null {
+	if (state.event === null && state.data === null) {
+		state.raw = [];
+		return null;
+	}
+	const event: ServerSentEvent = {
+		event: state.event,
+		data: state.data ?? "",
+		raw: state.raw,
+	};
+	state.event = null;
+	state.data = null;
+	state.raw = [];
+	return event;
+}
+
+function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent | null {
+	// `appendAndFlushLines` splits on LF only; strip a trailing CR so CRLF sources
+	// don't leak `\r` into field values.
+	let end = line.length;
+	if (end > 0 && line[end - 1] === 0x0d /* '\r' */) end--;
+	if (end === 0) return flushSseEvent(state);
+
+	// Comment line: keep in `raw` for diagnostic context, skip parsing.
+	if (line[0] === 0x3a /* ':' */) {
+		state.raw.push(decodeSseLineBytes(line, end));
+		return null;
+	}
+
+	const text = decodeSseLineBytes(line, end);
+	state.raw.push(text);
+
+	const colon = text.indexOf(":");
+	const fieldName = colon === -1 ? text : text.slice(0, colon);
+	let value = colon === -1 ? "" : text.slice(colon + 1);
+	if (value.charCodeAt(0) === 0x20 /* ' ' */) value = value.slice(1);
+
+	if (fieldName === "event") {
+		state.event = value;
+	} else if (fieldName === "data") {
+		if (state.data === null) {
+			state.data = value;
+		} else {
+			state.data += "\n";
+			state.data += value;
+		}
+	}
+	// `id` and `retry` are intentionally ignored — the providers we consume
+	// don't use them, and the underlying transport handles reconnects itself.
+	return null;
+}
+
+/**
+ * Stream raw Server-Sent Events from an HTTP response body.
+ *
+ * Yields one `ServerSentEvent` per blank-line dispatch. The consumer is
+ * responsible for parsing `data` (e.g. JSON, plain text, error envelope).
+ * Use `readSseJson` instead when every event is a single `data:` JSON object
+ * and you don't need access to the `event:` field.
+ *
+ * Internally backed by a Buffer-based line reader (`ConcatSink`) so chunk
+ * concatenation is O(n) and never triggers per-line string slicing of the
+ * accumulated buffer.
+ *
+ * @example
+ * ```ts
+ * for await (const sse of readSseEvents(response.body!)) {
+ *   if (sse.event === "ping") continue;
+ *   const obj = JSON.parse(sse.data);
+ * }
+ * ```
+ */
+export async function* readSseEvents(
+	stream: ReadableStream<Uint8Array>,
+	signal?: AbortSignal,
+): AsyncGenerator<ServerSentEvent> {
+	const lineBuffer = new ConcatSink();
+	const state: SseEventState = { event: null, data: null, raw: [] };
+	const source = createAbortableStream(stream, signal);
+	try {
+		for await (const chunk of source) {
+			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
+				const event = pushSseLine(line, state);
+				if (event) yield event;
+			}
+		}
+		// Treat any trailing partial line (no terminating LF) as a complete line.
+		if (!lineBuffer.isEmpty) {
+			const tail = lineBuffer.flush();
+			if (tail) {
+				lineBuffer.clear();
+				const event = pushSseLine(tail, state);
+				if (event) yield event;
+			}
+		}
+		// Real services don't always close on a blank line — flush any pending event.
+		const trailing = flushSseEvent(state);
+		if (trailing) yield trailing;
+	} catch (err) {
+		if (signal?.aborted) return;
+		throw err;
+	}
+}
+
+/**
+ * Parse a complete JSONL string, skipping malformed lines instead of throwing.
+ *
+ * Uses `Bun.JSONL.parseChunk` internally. On parse errors, the malformed
+ * region is skipped up to the next newline and parsing continues.
+ *
+ * @example
+ * ```ts
+ * const entries = parseJsonlLenient<MyType>(fileContents);
+ * ```
+ */
+export function parseJsonlLenient<T>(buffer: string): T[] {
+	let entries: T[] | undefined;
+
+	while (buffer.length > 0) {
+		const { values, error, read, done } = parseJsonlChunkCompat(buffer);
+		if (values.length > 0) {
+			const ext = values as T[];
+			if (!entries) {
+				entries = ext;
+			} else {
+				entries.push(...ext);
+			}
+		}
+		if (error) {
+			const nextNewline = buffer.indexOf("\n", read);
+			if (nextNewline === -1) break;
+			buffer = buffer.substring(nextNewline + 1);
+			continue;
+		}
+		if (read === 0) break;
+		buffer = buffer.substring(read);
+		if (done) break;
+	}
+	return entries ?? [];
+}