@oh-my-pi/pi-utils 18.10.4 → 18.11.1

package/dist/types/incoming-json.d.ts

@@ -48,6 +48,18 @@
  * await args.key("path").value<string>(); // "a.ts"
  * ```
  */
+/**
+ * @internal exported for tests — monotonic count of members re-lexed by
+ * selecting scans: one per object member or array element a scan walked over
+ * on the way to the member it was asked for.
+ *
+ * Cursor resumption (see {@link ContainerIndex}) is what keeps a full
+ * traversal linear in the document instead of quadratic, and losing it
+ * changes nothing about the pulled values — only how many members get
+ * re-lexed. Read the live binding before and after a traversal to measure
+ * exactly that.
+ */
+export declare let rescannedMembers: number;
 /** Location component in a pulled JSON path: an object member name or an array index. */
 export type PullPathSegment = string | number;
 /** JSON shape observed by a started pull. */

package/dist/types/mime.d.ts

@@ -26,5 +26,26 @@ export type ImageMetadata = {
     hasAlpha?: boolean;
 };
 export declare function parseImageMetadata(header: Uint8Array): ImageMetadata | null;
+/** Why base64 image data is unusable; `undefined` when it is canonical and non-empty. */
+export type Base64ImageDataFailure = "invalid base64 image data" | "empty image data";
+/**
+ * Non-empty decoded bytes on success, or a validation failure reason, never both.
+ * Check `reason` before using `bytes`; successful base64 decoding does not establish
+ * that the bytes represent a supported or decodable image.
+ */
+export type Base64ImageDecodeResult = {
+    bytes: Buffer;
+    reason?: never;
+} | {
+    bytes?: never;
+    reason: Base64ImageDataFailure;
+};
+/**
+ * Validate standard base64 image data without decoding it. Padding may be omitted, but
+ * present padding must be canonical, the trailing bits must be zero, and the data non-empty.
+ */
+export declare function base64ImageDataFailureReason(data: string): Base64ImageDataFailure | undefined;
+/** Decode standard base64 image data under the {@link base64ImageDataFailureReason} rules. */
+export declare function decodeBase64ImageData(data: string): Base64ImageDecodeResult;
 export declare function readImageMetadataSync(filePath: string, maxBytes?: number): ImageMetadata | null;
 export declare function readImageMetadata(filePath: string, maxBytes?: number): Promise<ImageMetadata | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.10.4",
+	"version": "18.11.1",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.10.4"
+		"@oh-my-pi/pi-natives": "18.11.1"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/incoming-json.ts

@@ -67,6 +67,19 @@ import { parseJsonWithRepair } from "./json-parse";
 /** Maximum container nesting before a scan reports the value as pending forever. */
 const MAX_DEPTH = 128;
 
+/**
+ * @internal exported for tests — monotonic count of members re-lexed by
+ * selecting scans: one per object member or array element a scan walked over
+ * on the way to the member it was asked for.
+ *
+ * Cursor resumption (see {@link ContainerIndex}) is what keeps a full
+ * traversal linear in the document instead of quadratic, and losing it
+ * changes nothing about the pulled values — only how many members get
+ * re-lexed. Read the live binding before and after a traversal to measure
+ * exactly that.
+ */
+export let rescannedMembers = 0;
+
 /** Location component in a pulled JSON path: an object member name or an array index. */
 export type PullPathSegment = string | number;
 
@@ -325,6 +338,7 @@ function selectKey(
 		lex.ws();
 		if (lex.atEnd) return PENDING;
 		if (key === wanted) return selectValue(lex, path, at, ended, depth + 1, slot);
+		rescannedMembers++;
 		const skipped = scanValue(lex, ended, depth + 1);
 		if (skipped.tag !== "located" || skipped.end === undefined) return PENDING;
 		lex.ws();
@@ -370,6 +384,7 @@ function selectIndex(
 		}
 		const slot = index.elements[element] ?? (index.tail ??= { offset: lex.pos });
 		if (element === wanted) return selectValue(lex, path, at, ended, depth + 1, slot);
+		rescannedMembers++;
 		const skipped = scanValue(lex, ended, depth + 1);
 		if (skipped.tag !== "located" || skipped.end === undefined) return PENDING;
 		if (element === index.elements.length) {

package/src/mime.ts

@@ -143,6 +143,50 @@ export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
 	);
 }
 
+/** Why base64 image data is unusable; `undefined` when it is canonical and non-empty. */
+export type Base64ImageDataFailure = "invalid base64 image data" | "empty image data";
+
+/**
+ * Non-empty decoded bytes on success, or a validation failure reason, never both.
+ * Check `reason` before using `bytes`; successful base64 decoding does not establish
+ * that the bytes represent a supported or decodable image.
+ */
+export type Base64ImageDecodeResult =
+	| { bytes: Buffer; reason?: never }
+	| { bytes?: never; reason: Base64ImageDataFailure };
+
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+
+/**
+ * Validate standard base64 image data without decoding it. Padding may be omitted, but
+ * present padding must be canonical, the trailing bits must be zero, and the data non-empty.
+ */
+export function base64ImageDataFailureReason(data: string): Base64ImageDataFailure | undefined {
+	if (data.length === 0) return "empty image data";
+
+	const match = /^([A-Za-z0-9+/]+)(={0,2})$/.exec(data);
+	if (!match) return "invalid base64 image data";
+	const encoded = match[1];
+	const paddingLength = match[2].length;
+	const remainder = encoded.length % 4;
+	if (remainder === 1 || (paddingLength === 1 && remainder !== 3) || (paddingLength === 2 && remainder !== 2)) {
+		return "invalid base64 image data";
+	}
+
+	const lastSextet = BASE64_ALPHABET.indexOf(encoded[encoded.length - 1]);
+	if ((remainder === 2 && (lastSextet & 0b1111) !== 0) || (remainder === 3 && (lastSextet & 0b11) !== 0)) {
+		return "invalid base64 image data";
+	}
+	return undefined;
+}
+
+/** Decode standard base64 image data under the {@link base64ImageDataFailureReason} rules. */
+export function decodeBase64ImageData(data: string): Base64ImageDecodeResult {
+	const reason = base64ImageDataFailureReason(data);
+	if (reason) return { reason };
+	return { bytes: Buffer.from(data, "base64") };
+}
+
 export function readImageMetadataSync(filePath: string, maxBytes = IMAGE_METADATA_HEADER_BYTES): ImageMetadata | null {
 	return peekFileSync(filePath, maxBytes, parseImageMetadata);
 }