From 8aac0a78a77bd84a8d655ed9e7b17c0a5fb14464 Mon Sep 17 00:00:00 2001
From: phil <uniphil@gmail.com>
Date: Thu, 16 Apr 2026 15:04:17 -0400
Subject: [PATCH] nice errors

---
 playground/src/routes/+page.svelte |  43 +++++++---
 ref-impl-js/src/index.ts           | 124 +++++++++++++++++++++++++----
 2 files changed, 142 insertions(+), 25 deletions(-)

diff --git a/playground/src/routes/+page.svelte b/playground/src/routes/+page.svelte
index 27678c9..68f5b82 100644
--- a/playground/src/routes/+page.svelte
+++ b/playground/src/routes/+page.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { enumerate, match, type PathInfo } from 'recordpath';
+	import { enumerate, match, parse, RecordPathParseError, type PathInfo } from 'recordpath';
 
 	const SAMPLE = {
 		$type: 'app.bsky.feed.post',
@@ -66,11 +66,27 @@
 	let record = $derived(parseResult.record);
 	let jsonError = $derived(parseResult.error);
 	let paths: PathInfo[] = $derived(record ? enumerate(record) : []);
-	let matches: unknown[] = $derived(
-		record && pathInput.trim() ? match(record, pathInput.trim()) : []
-	);
+
+	let pathResult = $derived.by(() => {
+		const trimmed = pathInput.trim();
+		if (!trimmed || !record) {
+			return { matches: [] as unknown[], parseError: null as RecordPathParseError | null };
+		}
+		try {
+			parse(trimmed);
+			return { matches: match(record, trimmed), parseError: null };
+		} catch (e) {
+			if (e instanceof RecordPathParseError) {
+				return { matches: [], parseError: e };
+			}
+			return { matches: [], parseError: null };
+		}
+	});
+
+	let matches = $derived(pathResult.matches);
+	let parseError = $derived(pathResult.parseError);
 	let hasInput = $derived(pathInput.trim().length > 0);
-	let noMatch = $derived(hasInput && record !== null && matches.length === 0);
+	let noMatch = $derived(hasInput && record !== null && !parseError && matches.length === 0);
 
 	function selectPath(path: string) {
 		pathInput = path;
@@ -119,7 +135,7 @@
 	<!-- Main panels -->
 	<main class="grid flex-1 grid-cols-2 overflow-hidden">
 		<!-- Left: JSON editor -->
-		<div class="flex flex-col overflow-hidden border-r border-stone-200">
+		<div class="flex flex-col flex-2 overflow-hidden border-r border-stone-200">
 			<div
 				class="border-b border-stone-200 bg-white px-3 py-1.5 text-[0.6875rem] font-semibold tracking-wide text-stone-400 uppercase"
 			>
@@ -140,7 +156,7 @@
 		</div>
 
 		<!-- Right: paths + matches -->
-		<div class="flex flex-col overflow-hidden">
+		<div class="flex flex-col flex-1 overflow-hidden">
 			<!-- Path input -->
 			<div class="border-b border-stone-200 bg-white p-2">
 				<input
@@ -150,10 +166,19 @@
 					spellcheck="false"
 					autocomplete="off"
 					class="w-full rounded border-[1.5px] bg-white px-2.5 py-2 font-mono text-sm outline-none
-						{noMatch
+						{parseError
 						? 'border-red-400 shadow-[0_0_0_2px_theme(colors.red.100)]'
-						: 'border-stone-200 focus:border-blue-500 focus:shadow-[0_0_0_2px_theme(colors.blue.100)]'}"
+						: noMatch
+							? 'border-amber-400 shadow-[0_0_0_2px_theme(colors.amber.100)]'
+							: 'border-stone-200 focus:border-blue-500 focus:shadow-[0_0_0_2px_theme(colors.blue.100)]'}"
 				/>
+				{#if parseError}
+					<pre
+						class="mt-1.5 overflow-x-auto rounded bg-red-50 px-2.5 py-2 font-mono text-[0.8125rem]"
+					><span class="text-red-300">{pathInput.trim()}</span>
+<span class="text-red-500">{' '.repeat(parseError.position)}^ {parseError.message.split(' (position')[0]}</span>{#if parseError.suggestion}
+<span class="text-emerald-500">hint: {parseError.suggestionHint}:</span> <button class="cursor-pointer text-emerald-600 underline decoration-emerald-300 hover:decoration-emerald-500" onclick={() => { pathInput = parseError.suggestion ?? ''; }}>{parseError.suggestion}</button>{/if}</pre>
+				{/if}
 			</div>
 
 			<!-- Path list header -->
diff --git a/ref-impl-js/src/index.ts b/ref-impl-js/src/index.ts
index 0ce8118..8fe87d4 100644
--- a/ref-impl-js/src/index.ts
+++ b/ref-impl-js/src/index.ts
@@ -3,6 +3,33 @@
 
 const STRUCTURAL = new Set(['.', '[', ']', '{', '}', '!']);
 
+/** Represents a parse error in a RecordPath string */
+export class RecordPathParseError extends Error {
+	/** the input string that failed to parse */
+	readonly input: string;
+	/** character position where the error was detected */
+	readonly position: number;
+	/** a corrected version of the input, if one can be inferred */
+	readonly suggestion: string | null;
+	/** explanation of what the suggestion changes */
+	readonly suggestionHint: string | null;
+
+	constructor(
+		message: string,
+		input: string,
+		position: number,
+		suggestion?: string,
+		suggestionHint?: string
+	) {
+		super(`${message} (position ${position} in '${input}')`);
+		this.name = 'RecordPathParseError';
+		this.input = input;
+		this.position = position;
+		this.suggestion = suggestion ?? null;
+		this.suggestionHint = suggestionHint ?? null;
+	}
+}
+
 export interface Qualifier {
 	type: 'array' | 'arrayUnion' | 'scalarUnion';
 	nsid?: string;
@@ -27,38 +54,85 @@ export function escapeFieldName(key: string): string {
 	return out;
 }
 
-// Parse a RecordPath string into segments.
-// TODO: error returns?? (or throws)
 export function parse(str: string): Segment[] {
+	if (str === '') throw new RecordPathParseError('empty path', str, 0);
+
 	const segments: Segment[] = [];
 	let i = 0;
 
 	while (i < str.length) {
 		let key = '';
 
-		// TODO: does this permit misplaced unescaped close chars? `]` and `}`
-		// we should probably fail/reject those.
 		while (i < str.length && str[i] !== '.' && str[i] !== '[' && str[i] !== '{') {
-			if (str[i] === '!' && i + 1 < str.length) {
-				key += str[i + 1];
+			if (str[i] === '!') {
+				if (i + 1 >= str.length) {
+					throw new RecordPathParseError(
+						'escape at end of input',
+						str,
+						i,
+						str.slice(0, i) + '!!',
+						"escape the '!' as '!!'"
+					);
+				}
+				const next = str[i + 1];
+				if (!STRUCTURAL.has(next)) {
+					throw new RecordPathParseError(
+						`escape followed by non-escapable '${next}'`,
+						str,
+						i,
+						str.slice(0, i) + '!!' + str.slice(i + 1),
+						"escape the '!' as '!!'"
+					);
+				}
+				key += next;
 				i += 2;
+			} else if (str[i] === ']') {
+				throw new RecordPathParseError(
+					"unexpected ']' without opening '['",
+					str,
+					i,
+					str.slice(0, i) + '!]' + str.slice(i + 1),
+					"escape as '!]'"
+				);
+			} else if (str[i] === '}') {
+				throw new RecordPathParseError(
+					"unexpected '}' without opening '{'",
+					str,
+					i,
+					str.slice(0, i) + '!}' + str.slice(i + 1),
+					"escape as '!}'"
+				);
 			} else {
 				key += str[i];
 				i++;
 			}
 		}
 
+		if (key === '') {
+			throw new RecordPathParseError('empty segment', str, i);
+		}
+
 		const qualifiers: Qualifier[] = [];
 		while (i < str.length && (str[i] === '[' || str[i] === '{')) {
 			const open = str[i];
 			const close = open === '[' ? ']' : '}';
+			const openPos = i;
 			i++;
 			let content = '';
 			while (i < str.length && str[i] !== close) {
 				content += str[i];
 				i++;
 			}
-			if (i < str.length) i++;
+			if (i >= str.length) {
+				throw new RecordPathParseError(
+					`unclosed '${open}'`,
+					str,
+					openPos,
+					str + close,
+					`close with '${close}'`
+				);
+			}
+			i++; // skip close
 
 			if (open === '[') {
 				qualifiers.push(
@@ -70,7 +144,19 @@ export function parse(str: string): Segment[] {
 		}
 
 		segments.push({ key, qualifiers });
-		if (i < str.length && str[i] === '.') i++;
+
+		if (i < str.length && str[i] === '.') {
+			i++;
+			if (i >= str.length) {
+				throw new RecordPathParseError(
+						'trailing dot',
+						str,
+						i - 1,
+						str.slice(0, -1),
+						'remove the trailing dot'
+					);
+			}
+		}
 	}
 
 	return segments;
@@ -137,14 +223,13 @@ function applyQualifiers(
 // Enumerate all RecordPaths reachable from a record.
 export function enumerate(record: Record<string, unknown>): PathInfo[] {
 	const paths = new Map<string, PathInfo>();
-	enumObject(record, '', true, false, paths);
+	enumObject(record, '', false, paths);
 	return Array.from(paths.values());
 }
 
 function enumObject(
 	obj: Record<string, unknown>,
 	prefix: string,
-	isRoot: boolean,
 	isVector: boolean,
 	paths: Map<string, PathInfo>
 ) {
@@ -159,15 +244,15 @@ function enumObject(
 		} else if (Array.isArray(child)) {
 			paths.set(keyPath, { path: keyPath, type: vtype });
 			enumArray(child, keyPath, isVector, paths);
-		} else if ((child as Record<string, unknown>).$type && !isRoot) {
+		} else if ((child as Record<string, unknown>).$type) {
 			paths.set(keyPath, { path: keyPath, type: vtype });
 			const nsid = (child as Record<string, unknown>).$type as string;
 			const qualified = keyPath + '{' + nsid + '}';
 			paths.set(qualified, { path: qualified, type: vtype });
-			enumObject(child as Record<string, unknown>, qualified, false, isVector, paths);
+			enumObject(child as Record<string, unknown>, qualified, isVector, paths);
 		} else {
 			paths.set(keyPath, { path: keyPath, type: vtype });
-			enumObject(child as Record<string, unknown>, keyPath, false, isVector, paths);
+			enumObject(child as Record<string, unknown>, keyPath, isVector, paths);
 		}
 	}
 }
@@ -206,7 +291,7 @@ function enumArray(
 			const qp = prefix + '[' + nsid + ']';
 			paths.set(qp, { path: qp, type: 'vector' });
 			for (const el of elements) {
-				enumObject(el, qp, false, true, paths);
+				enumObject(el, qp, true, paths);
 			}
 		}
 		if (plain.length > 0) {
@@ -225,7 +310,7 @@ function enumPlainArray(arr: unknown[], prefix: string, paths: Map<string, PathI
 		} else if (Array.isArray(el)) {
 			enumArray(el, prefix, true, paths);
 		} else {
-			enumObject(el as Record<string, unknown>, prefix, false, true, paths);
+			enumObject(el as Record<string, unknown>, prefix, true, paths);
 		}
 	}
 }
@@ -235,5 +320,12 @@ function enumPlainArray(arr: unknown[], prefix: string, paths: Map<string, PathI
 // (or enumerate could be a generator?? that might be even nicer)
 
 export function isVector(pathStr: string): boolean {
-	return /\[/.test(pathStr);
+	for (let i = 0; i < pathStr.length; i++) {
+		if (pathStr[i] === '!' && i + 1 < pathStr.length) {
+			i++; // skip escaped character
+		} else if (pathStr[i] === '[') {
+			return true;
+		}
+	}
+	return false;
 }
-- 
2.51.2