@gajae-code/utils 0.11.6 → 0.11.8

package/dist/types/env.d.ts

@@ -66,3 +66,7 @@ export declare function isBunTestRuntime(): boolean;
  */
 export declare function isCompiledBinary(): boolean;
 export declare function $flag(name: string, def?: boolean): boolean;
+/** Resolve the first flag among keys that has a set value (GJC-first, PI fallback). Matches $flag semantics per key. */
+export declare function $pickflag(...keys: string[]): boolean;
+/** Resolve the first positive integer among keys, else defaultValue (GJC-first). Set-but-invalid keys are skipped. */
+export declare function $pickenvpos(keys: string[], defaultValue: number): number;

package/dist/types/stream.d.ts

@@ -17,7 +17,11 @@ export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?
  * ```
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
-export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T>;
+export interface SseReadOptions {
+    maxEventBytes?: number;
+    maxTotalBytes?: number;
+}
+export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver, options?: SseReadOptions): AsyncGenerator<T>;
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *
@@ -53,7 +57,7 @@ export interface ServerSentEvent {
  * }
  * ```
  */
-export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<ServerSentEvent>;
+export declare function readSseEvents(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, options?: SseReadOptions): AsyncGenerator<ServerSentEvent>;
 /**
  * Parse a complete JSONL string, skipping malformed lines instead of throwing.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.11.6",
+	"version": "0.11.8",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.11.6",
+		"@gajae-code/natives": "0.11.8",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/env.ts

@@ -279,3 +279,23 @@ export function $flag(name: string, def: boolean = false): boolean {
 	// would silently read as false while only `FOO=TRUE`/`FOO=1` worked.
 	return TRUTHY[value.toUpperCase()] === true;
 }
+
+/** Resolve the first flag among keys that has a set value (GJC-first, PI fallback). Matches $flag semantics per key. */
+export function $pickflag(...keys: string[]): boolean {
+	for (const key of keys) {
+		const value = $env[key]?.trim();
+		if (value) return TRUTHY[value.toUpperCase()] === true;
+	}
+	return false;
+}
+
+/** Resolve the first positive integer among keys, else defaultValue (GJC-first). Set-but-invalid keys are skipped. */
+export function $pickenvpos(keys: string[], defaultValue: number): number {
+	for (const key of keys) {
+		const raw = $env[key]?.trim();
+		if (!raw) continue;
+		const parsed = Number.parseInt(raw, 10);
+		if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+	}
+	return defaultValue;
+}

package/src/format.ts

@@ -9,7 +9,9 @@ const DAY = 24 * HOUR;
  */
 export function formatDuration(ms: number): string {
 	if (ms < SEC) return `${ms}ms`;
-	if (ms < MIN) return `${(ms / SEC).toFixed(1)}s`;
+	// Truncate below 60.0s instead of rounding up into the next unit (the minute
+	// branch below), mirroring roundBelow/formatByteUnit: e.g. 59_999ms -> "59.9s".
+	if (ms < MIN) return `${(roundBelow(ms / 100, 600) / 10).toFixed(1)}s`;
 	if (ms < HOUR) {
 		const mins = Math.floor(ms / MIN);
 		const secs = Math.floor((ms % MIN) / SEC);
@@ -59,13 +61,21 @@ export function formatBytes(bytes: number): string {
 	if (bytes < 1024) return `${bytes}B`;
 	if (bytes < 1024 * 1024) return `${formatByteUnit(bytes, 1024)}KB`;
 	if (bytes < 1024 * 1024 * 1024) return `${formatByteUnit(bytes, 1024 * 1024)}MB`;
-	return `${formatByteUnit(bytes, 1024 * 1024 * 1024)}GB`;
+	// The GB branch is terminal (no larger unit), so it must not clamp below the
+	// next-unit boundary the way KB/MB do; clamping here reports every value >=
+	// 1 TiB as "1023.9GB" (e.g. 2 TiB -> "1023.9GB" instead of "2048.0GB").
+	return `${formatByteUnit(bytes, 1024 * 1024 * 1024, false)}GB`;
 }
 
-/** Format bytes to 1 decimal without rounding up into the next byte unit. */
-function formatByteUnit(bytes: number, unit: number): string {
-	const tenths = Math.min(Math.round((bytes / unit) * 10), 1024 * 10 - 1);
-	return (tenths / 10).toFixed(1);
+/**
+ * Format bytes to 1 decimal. Intermediate units (KB/MB) clamp just below the
+ * next-unit boundary so a value like 1023.95 KB never rounds up to "1024.0KB";
+ * the terminal GB unit passes `clampToNextUnit: false` because it has no next
+ * unit to protect against.
+ */
+function formatByteUnit(bytes: number, unit: number, clampToNextUnit = true): string {
+	const tenths = Math.round((bytes / unit) * 10);
+	return ((clampToNextUnit ? Math.min(tenths, 1024 * 10 - 1) : tenths) / 10).toFixed(1);
 }
 
 /**

package/src/frontmatter.ts

@@ -124,18 +124,30 @@ export function parseFrontmatter(
 	const loc = location ?? source;
 	const frontmatter: Record<string, unknown> = { ...fallback };
 
-	const normalized = normalize ? stripHtmlComments(content.replace(/\r\n?/g, "\n")) : content;
-	if (!normalized.startsWith("---")) {
+	// Normalize away a leading UTF-8 BOM and CRLF line endings before matching so
+	// a BOM-prefixed but otherwise valid document is still recognized as
+	// frontmatter (BOM-prefixed Markdown is common on Windows-authored files).
+	const normalized = normalize ? stripHtmlComments(content.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n")) : content;
+	// A frontmatter block opens with a line that is exactly `---` (trailing
+	// spaces/tabs allowed). A bare `----` banner or a `--- text` heading is not
+	// an opener, so a document without frontmatter keeps its body intact rather
+	// than having content silently consumed by the fixed-offset slicing below.
+	const open = normalized.match(/^---[ \t]*(?:\n|$)/);
+	if (!open) {
 		return { frontmatter, body: normalized };
 	}
 
-	const endIndex = normalized.indexOf("\n---", 3);
-	if (endIndex === -1) {
+	// The block closes at the next line that is exactly `---`. Searching from the
+	// end of the opening `---` (offset 3, not the whole opener) keeps an empty
+	// block (`---\n---`) matching as empty frontmatter.
+	const afterOpen = normalized.slice(3);
+	const close = afterOpen.match(/\n---[ \t]*(?:\n|$)/);
+	if (!close || close.index === undefined) {
 		return { frontmatter, body: normalized };
 	}
 
-	const metadata = normalized.slice(4, endIndex);
-	const body = normalized.slice(endIndex + 4).trim();
+	const metadata = afterOpen.slice(open[0].length - 3, close.index);
+	const body = afterOpen.slice(close.index + close[0].length).trim();
 
 	try {
 		// Replace tabs with spaces for YAML compatibility, use failsafe mode for robustness

package/src/logger.ts

@@ -410,7 +410,10 @@ function printModuleLoadSummary(loads: Span[], depth: number, lines: string[]):
 	}
 	const wall = unionEnd > unionStart ? unionEnd - unionStart : 0;
 	lines.push(`${childIndent}(modules): ${loads.length} loaded, wall ${fmtMs(wall)}, sum ${fmtMs(totalSelf)}`);
-	const showAll = process.env.PI_TIMING === "full";
+	// Resolve GJC-first with PI fallback inline (no ./env import) so this
+	// foundational logger stays off the env module's dependency graph, which the
+	// tab-worker native-free runtime contract (issue-2598-repro) walks.
+	const showAll = (process.env.GJC_TIMING?.trim() || process.env.PI_TIMING?.trim()) === "full";
 	const sorted = [...loads].sort((a, b) => durationOf(b) - durationOf(a));
 	const visible = showAll ? sorted : sorted.slice(0, MODULE_LOAD_VERBOSE_TOP);
 	for (const span of visible) {

package/src/stream.ts

@@ -125,16 +125,22 @@ class ConcatSink {
 		this.#length = 0;
 	}
 
-	*appendAndFlushLines(chunk: Uint8Array) {
+	*appendAndFlushLines(chunk: Uint8Array, maxLineBytes?: () => number) {
 		let pos = 0;
 		while (pos < chunk.length) {
 			const nl = chunk.indexOf(LF, pos);
 			if (nl === -1) {
+				if (maxLineBytes && this.#length + chunk.length - pos > maxLineBytes()) {
+					throw new Error("SSE event exceeds size limit");
+				}
 				this.append(chunk.subarray(pos));
 				return;
 			}
 			const suffix = chunk.subarray(pos, nl);
 			pos = nl + 1;
+			if (maxLineBytes && this.#length + suffix.length + 1 > maxLineBytes()) {
+				throw new Error("SSE event exceeds size limit");
+			}
 			if (this.isEmpty) {
 				yield suffix;
 			} else {
@@ -201,6 +207,11 @@ class ConcatSink {
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
 
+export interface SseReadOptions {
+	maxEventBytes?: number;
+	maxTotalBytes?: number;
+}
+
 function notifySseEventObserver(observer: SseEventObserver | undefined, event: ServerSentEvent): void {
 	if (!observer) return;
 	try {
@@ -214,8 +225,9 @@ export async function* readSseJson<T>(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
 	onEvent?: SseEventObserver,
+	options?: SseReadOptions,
 ): AsyncGenerator<T> {
-	for await (const sse of readSseEvents(stream, signal)) {
+	for await (const sse of readSseEvents(stream, signal, options)) {
 		notifySseEventObserver(onEvent, sse);
 		const data = sse.data;
 		if (data === "" || data === "[DONE]") {
@@ -336,14 +348,26 @@ function pushSseLine(line: Uint8Array, state: SseEventState): ServerSentEvent |
 export async function* readSseEvents(
 	stream: ReadableStream<Uint8Array>,
 	signal?: AbortSignal,
+	options?: SseReadOptions,
 ): AsyncGenerator<ServerSentEvent> {
 	const lineBuffer = new ConcatSink();
 	const state: SseEventState = { event: null, data: null, raw: [] };
 	const source = createAbortableStream(stream, signal);
+	let eventBytes = 0;
+	let totalBytes = 0;
 	try {
 		for await (const chunk of source) {
-			for (const line of lineBuffer.appendAndFlushLines(chunk)) {
+			totalBytes += chunk.length;
+			if (options?.maxTotalBytes !== undefined && totalBytes > options.maxTotalBytes) {
+				throw new Error("SSE stream exceeds size limit");
+			}
+			for (const line of lineBuffer.appendAndFlushLines(
+				chunk,
+				() => (options?.maxEventBytes ?? Infinity) - eventBytes,
+			)) {
+				eventBytes += line.length + 1;
 				const event = pushSseLine(line, state);
+				if (line.length === 0 || (line.length === 1 && line[0] === 0x0d)) eventBytes = 0;
 				if (event) yield event;
 			}
 		}