@coldsmirk/inkstone-mongodb 0.22.0

package/README.md

@@ -0,0 +1,51 @@
+# @coldsmirk/inkstone-mongodb
+
+MongoDB command editing intelligence for Monaco: a command document in the shell's own spelling (`{ find: "orders", filter: { status: "open" }, limit: 20 }` — keys bare or quoted, `ObjectId("…")`, `ISODate("…")`, `/regex/i`), the database commands and their fields, the query, update and aggregation operators by where the caret stands, collection and database completion, the document read as the engine reads it, markers, and a drop-in React `<MongodbEditor>`.
+
+Part of [inkstone](https://github.com/coldsmirk/inkstone). Built for the [**polyglot**](https://github.com/coldsmirk/polyglot) sidecar's MongoDB engine, which takes one command document — the command as its first key, `$db` naming the database — and parses it with the driver's own `BsonDocument.parse`.
+
+## Entries
+
+- **`@coldsmirk/inkstone-mongodb`** — the framework-free core: the document reader, the command table, the operator vocabularies, the assist, the markers. Zero editor dependencies.
+- **`@coldsmirk/inkstone-mongodb/monaco`** — `defineMongodbLanguage(monaco)` (the `mongodb` id with its Monarch grammar, once per monaco module), `registerMongodbLanguage(monaco, modelPath, hooks)` (completion and hover for one model), `setMongodbMarkers`. Peer: `monaco-editor`.
+- **`@coldsmirk/inkstone-mongodb/react`** — `<MongodbEditor>`: a controlled command editor built on `@coldsmirk/inkstone-react`'s `<MonacoEditor>`, with a run key (Ctrl/Cmd-Enter handing over the live caret), caret tracking, an insert handle for collection trees, and the markers refreshed on every change. Peers: `monaco-editor`, `react`.
+
+## The shape
+
+```ts
+import { createMongodbAssist, documentMarkers, runnableDocument } from "@coldsmirk/inkstone-mongodb";
+
+// The catalog is YOURS to fetch — and it MUST be a cache-backed read (the tree's own list),
+// never a fresh fetch: completion reads it on every keystroke in a value.
+const assist = createMongodbAssist({ collections: () => cachedCollections() });   // CatalogCollection[]
+
+// What one run should send: the selection where there is one, else the whole document.
+const runnable = runnableDocument(text, from, to);
+
+if (runnable.kind === "one") {
+  send(runnable.text);
+}
+
+// A code per fault — the host owns the wording.
+for (const marker of documentMarkers(text)) {
+  console.log(marker.code, marker.severity, marker.from, marker.to);
+}
+```
+
+Completion offers the commands at the document's first key and the named command's fields after it, `$db` beside them; the collections as the command's value and the databases as `$db`'s; the query operators under a filter and the comparison operators under a field of one; the update operators under an update; the pipeline stages inside a pipeline and each stage's keys under it. Hover describes the command under its key.
+
+## The mirror invariant
+
+`readDocument` reads the text as the driver's `BsonDocument.parse` does — one object, keys bare or quoted, strings in either quote, the shell's constructors with or without `new`, regular-expression literals, `undefined`, `MinKey` and `MaxKey`, no comments and no trailing commas — and refuses what the engine refuses, as a code (`"not-a-document"` with the offset it stopped at, `"no-command"` for a document holding nothing but `$db`). A change to the engine's parsing requires a matching release of this package; `document.test.ts` carries the cases.
+
+## The vocabulary
+
+The command table and the operator lists are curated in `commands.ts` — the commands a bench reaches for with their fields, and the operators the query language, the update language and the aggregation pipeline take, by context. They are a hint of the language's shape, never its authority: a key the table does not know is still sent, and the server's answer is what counts.
+
+## Install
+
+```bash
+pnpm add @coldsmirk/inkstone-mongodb monaco-editor
+```
+
+Every peer is optional, because the root entry needs none of them: `/monaco` needs `monaco-editor`, and `/react` additionally needs `react` (>= 19) and `@coldsmirk/inkstone-react`. Never import `monaco-editor` statically — take the module from `onMount` / `ensureMonacoHost()`; type-only imports erase and are fine.

package/dist/document-CVB9YunA.js

@@ -0,0 +1,408 @@
+//#region src/document.ts
+const CONSTRUCTORS = [
+	"ObjectId",
+	"ISODate",
+	"Date",
+	"NumberLong",
+	"NumberInt",
+	"NumberDecimal",
+	"Timestamp",
+	"BinData",
+	"UUID",
+	"HexData",
+	"RegExp",
+	"DBRef",
+	"DBPointer",
+	"MinKey",
+	"MaxKey"
+];
+const CONSTRUCTOR_SET = new Set(CONSTRUCTORS);
+const LITERALS = [
+	"true",
+	"false",
+	"null",
+	"undefined",
+	"Infinity",
+	"NaN",
+	"MinKey",
+	"MaxKey"
+];
+const LITERAL_SET = new Set(LITERALS);
+const IDENTIFIER = /[A-Za-z_$][\w$]*/uy;
+const NUMBER = /-?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?|-?Infinity|NaN/uy;
+const ESCAPES = {
+	n: "\n",
+	r: "\r",
+	t: "	",
+	b: "\b",
+	f: "\f",
+	"\"": "\"",
+	"'": "'",
+	"\\": "\\",
+	"/": "/"
+};
+var Fault = class extends Error {
+	at;
+	constructor(at) {
+		super("not a document");
+		this.at = at;
+	}
+};
+var Reader = class {
+	text;
+	i = 0;
+	constructor(text) {
+		this.text = text;
+	}
+	blanks() {
+		while (this.i < this.text.length && /\s/u.test(this.text[this.i])) this.i++;
+	}
+	expect(character) {
+		if (this.text[this.i] !== character) throw new Fault(this.i);
+		this.i++;
+	}
+	key() {
+		const c = this.text[this.i];
+		if (c === "\"" || c === "'") return this.string();
+		IDENTIFIER.lastIndex = this.i;
+		const match = IDENTIFIER.exec(this.text);
+		if (match === null) throw new Fault(this.i);
+		this.i += match[0].length;
+		return match[0];
+	}
+	string() {
+		const quote = this.text[this.i];
+		let out = "";
+		this.i++;
+		while (true) {
+			if (this.i >= this.text.length) throw new Fault(this.i);
+			const c = this.text[this.i];
+			if (c === quote) {
+				this.i++;
+				return out;
+			}
+			if (c === "\\") {
+				const escaped = this.text[this.i + 1];
+				if (escaped === "u") {
+					const hex = this.text.slice(this.i + 2, this.i + 6);
+					if (!/^[0-9a-f]{4}$/iu.test(hex)) throw new Fault(this.i);
+					out += String.fromCodePoint(Number.parseInt(hex, 16));
+					this.i += 6;
+					continue;
+				}
+				const resolved = escaped === void 0 ? void 0 : ESCAPES[escaped];
+				if (resolved === void 0) throw new Fault(this.i);
+				out += resolved;
+				this.i += 2;
+				continue;
+			}
+			out += c;
+			this.i++;
+		}
+	}
+	value() {
+		const c = this.text[this.i];
+		if (c === void 0) throw new Fault(this.i);
+		if (c === "{") {
+			this.container("}", true);
+			return null;
+		}
+		if (c === "[") {
+			this.container("]", false);
+			return null;
+		}
+		if (c === "\"" || c === "'") return this.string();
+		if (c === "/") {
+			this.regex();
+			return null;
+		}
+		NUMBER.lastIndex = this.i;
+		const number = NUMBER.exec(this.text);
+		if (number !== null) {
+			this.i += number[0].length;
+			return null;
+		}
+		const start = this.i;
+		IDENTIFIER.lastIndex = start;
+		const word = IDENTIFIER.exec(this.text);
+		if (word === null) throw new Fault(start);
+		this.i += word[0].length;
+		if (word[0] === "new") {
+			this.blanks();
+			IDENTIFIER.lastIndex = this.i;
+			const constructed = IDENTIFIER.exec(this.text);
+			if (constructed === null || !CONSTRUCTOR_SET.has(constructed[0])) throw new Fault(this.i);
+			this.i += constructed[0].length;
+			this.call();
+			return null;
+		}
+		this.blanks();
+		if (this.text[this.i] === "(") {
+			if (!CONSTRUCTOR_SET.has(word[0])) throw new Fault(this.i);
+			this.call();
+			return null;
+		}
+		if (!LITERAL_SET.has(word[0])) throw new Fault(start);
+		return null;
+	}
+	container(close, keyed) {
+		this.i++;
+		this.blanks();
+		if (this.text[this.i] === close) {
+			this.i++;
+			return;
+		}
+		while (true) {
+			if (keyed) {
+				this.key();
+				this.blanks();
+				this.expect(":");
+				this.blanks();
+			}
+			this.value();
+			this.blanks();
+			if (this.text[this.i] === ",") {
+				this.i++;
+				this.blanks();
+				continue;
+			}
+			this.expect(close);
+			return;
+		}
+	}
+	call() {
+		this.expect("(");
+		this.blanks();
+		if (this.text[this.i] === ")") {
+			this.i++;
+			return;
+		}
+		while (true) {
+			this.value();
+			this.blanks();
+			if (this.text[this.i] === ",") {
+				this.i++;
+				this.blanks();
+				continue;
+			}
+			this.expect(")");
+			return;
+		}
+	}
+	regex() {
+		this.i++;
+		while (true) {
+			const c = this.text[this.i];
+			if (c === void 0 || c === "\n") throw new Fault(this.i);
+			if (c === "\\") {
+				this.i += 2;
+				continue;
+			}
+			this.i++;
+			if (c === "/") break;
+		}
+		while (this.i < this.text.length && /[a-z]/u.test(this.text[this.i])) this.i++;
+	}
+	document() {
+		this.blanks();
+		if (this.text[this.i] !== "{") throw new Fault(this.i);
+		const keys = [];
+		const spans = [];
+		let database = null;
+		this.i++;
+		this.blanks();
+		if (this.text[this.i] === "}") this.i++;
+		else while (true) {
+			const from = this.i;
+			const key = this.key();
+			keys.push(key);
+			spans.push({
+				from,
+				to: this.i
+			});
+			this.blanks();
+			this.expect(":");
+			this.blanks();
+			const value = this.value();
+			if (key === "$db" && typeof value === "string") database = value;
+			this.blanks();
+			if (this.text[this.i] === ",") {
+				this.i++;
+				this.blanks();
+				continue;
+			}
+			this.expect("}");
+			break;
+		}
+		this.blanks();
+		if (this.i < this.text.length) throw new Fault(this.i);
+		return {
+			keys,
+			spans,
+			database
+		};
+	}
+};
+function readDocument(text) {
+	if (text.trim() === "") return {
+		keys: [],
+		command: null,
+		database: null,
+		commandSpan: null,
+		refusal: "empty",
+		at: -1
+	};
+	try {
+		const { keys, spans, database } = new Reader(text).document();
+		const index = keys.findIndex((key) => key !== "$db");
+		return {
+			keys,
+			command: index === -1 ? null : keys[index],
+			database,
+			commandSpan: index === -1 ? null : spans[index],
+			refusal: index === -1 ? "no-command" : null,
+			at: -1
+		};
+	} catch (error) {
+		if (error instanceof Fault) return {
+			keys: [],
+			command: null,
+			database: null,
+			commandSpan: null,
+			refusal: "not-a-document",
+			at: error.at
+		};
+		throw error;
+	}
+}
+function runnableDocument(text, from, to) {
+	const [start, end] = from < to ? [from, to] : [0, text.length];
+	const span = text.slice(start, end);
+	const first = start + (span.length - span.trimStart().length);
+	const last = end - (span.length - span.trimEnd().length);
+	return first >= last ? { kind: "none" } : {
+		kind: "one",
+		text: text.slice(first, last),
+		from: first,
+		to: last
+	};
+}
+function pathOf(frames) {
+	const path = [];
+	const enclosing = frames.slice(0, -1);
+	for (const frame of enclosing) if (!frame.transparent && frame.key !== null) path.push(frame.key);
+	return path;
+}
+function atKey(frame) {
+	return frame !== void 0 && !frame.transparent && frame.expectingKey;
+}
+function valueKey(frame) {
+	return frame !== void 0 && !frame.transparent && !frame.valueStarted ? frame.key : null;
+}
+function keyContext(frames, top, typed, quoted) {
+	return {
+		kind: "key",
+		path: pathOf(frames),
+		siblings: top.seen,
+		typed,
+		quoted
+	};
+}
+function valueContext(frames, key, typed, quoted) {
+	return {
+		kind: "value",
+		path: pathOf(frames),
+		key,
+		typed,
+		quoted
+	};
+}
+function closingQuote(text, from, quote) {
+	let i = from;
+	while (i < text.length) {
+		if (text[i] === "\\") {
+			i += 2;
+			continue;
+		}
+		if (text[i] === quote) return i;
+		i++;
+	}
+	return -1;
+}
+function structure(frames, top, c, pending) {
+	if (c === "{" || c === "[" || c === "(") {
+		if (top !== void 0) top.valueStarted = true;
+		frames.push({
+			transparent: c !== "{",
+			key: null,
+			expectingKey: c === "{",
+			valueStarted: false,
+			seen: []
+		});
+		return;
+	}
+	if (c === "}" || c === "]" || c === ")") {
+		frames.pop();
+		return;
+	}
+	if (top === void 0) return;
+	if (!top.transparent && c === ":") {
+		top.key = pending;
+		top.expectingKey = false;
+		top.valueStarted = false;
+		top.seen.push(pending);
+		return;
+	}
+	if (!top.transparent && c === ",") {
+		top.key = null;
+		top.expectingKey = true;
+		top.valueStarted = false;
+		return;
+	}
+	if (!/\s/u.test(c)) top.valueStarted = true;
+}
+function caretContext(text, offset) {
+	const body = text.slice(0, offset);
+	const frames = [];
+	let pending = "";
+	let i = 0;
+	while (i < body.length) {
+		const c = body[i];
+		const top = frames.at(-1);
+		if (c === "\"" || c === "'") {
+			const end = closingQuote(body, i + 1, c);
+			if (end === -1) {
+				const typed = body.slice(i + 1);
+				if (top !== void 0 && atKey(top)) return keyContext(frames, top, typed, true);
+				const key = valueKey(top);
+				return key === null ? { kind: "none" } : valueContext(frames, key, typed, true);
+			}
+			if (atKey(top)) pending = body.slice(i + 1, end);
+			else if (top !== void 0) top.valueStarted = true;
+			i = end + 1;
+			continue;
+		}
+		IDENTIFIER.lastIndex = i;
+		const word = /[A-Za-z_$]/u.test(c) ? IDENTIFIER.exec(body) : null;
+		if (word !== null) {
+			const typed = word[0];
+			i += typed.length;
+			if (i >= body.length) {
+				if (top !== void 0 && atKey(top)) return keyContext(frames, top, typed, false);
+				const key = valueKey(top);
+				return key === null ? { kind: "none" } : valueContext(frames, key, typed, false);
+			}
+			if (atKey(top)) pending = typed;
+			else if (top !== void 0) top.valueStarted = true;
+			continue;
+		}
+		structure(frames, top, c, pending);
+		i++;
+	}
+	const top = frames.at(-1);
+	if (top !== void 0 && atKey(top)) return keyContext(frames, top, "", false);
+	const key = valueKey(top);
+	return key === null ? { kind: "none" } : valueContext(frames, key, "", false);
+}
+//#endregion
+export { runnableDocument as a, readDocument as i, LITERALS as n, caretContext as r, CONSTRUCTORS as t };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { C as PUSH_MODIFIERS, D as keysAt, E as UPDATE_OPERATORS, S as MongoCommand, T as STAGES, _ as MongodbHoverCard, a as CaretContext, b as FIELD_OPERATORS, c as LITERALS, d as readDocument, f as runnableDocument, g as MongodbCompletionCandidate, h as MongodbCatalog, i as CONSTRUCTORS, l as RunnableDocument, m as MongodbAssist, n as MongodbMarkerCode, o as DocumentRead, p as CatalogCollection, r as documentMarkers, s as DocumentRefusal, t as MongodbMarker, u as caretContext, v as createMongodbAssist, w as QUERY_OPERATORS, x as MONGO_COMMANDS, y as EXPRESSION_OPERATORS } from "./markers-CQOm7diu.js";
+export { CONSTRUCTORS, type CaretContext, type CatalogCollection, type DocumentRead, type DocumentRefusal, EXPRESSION_OPERATORS, FIELD_OPERATORS, LITERALS, MONGO_COMMANDS, type MongoCommand, type MongodbAssist, type MongodbCatalog, type MongodbCompletionCandidate, type MongodbHoverCard, type MongodbMarker, type MongodbMarkerCode, PUSH_MODIFIERS, QUERY_OPERATORS, type RunnableDocument, STAGES, UPDATE_OPERATORS, caretContext, createMongodbAssist, documentMarkers, keysAt, readDocument, runnableDocument };

package/dist/index.js

@@ -0,0 +1,90 @@
+import { a as PUSH_MODIFIERS, c as UPDATE_OPERATORS, i as MONGO_COMMANDS, l as keysAt, n as EXPRESSION_OPERATORS, o as QUERY_OPERATORS, r as FIELD_OPERATORS, s as STAGES, t as documentMarkers } from "./markers-Bdvbut2O.js";
+import { a as runnableDocument, i as readDocument, n as LITERALS, r as caretContext, t as CONSTRUCTORS } from "./document-CVB9YunA.js";
+//#region src/assist.ts
+const NO_CATALOG = { collections: () => [] };
+function documentationOf(command) {
+	return command.fields.length === 0 ? command.summary : `${command.summary}\n\nFields: ${command.fields.join(", ")}`;
+}
+function wordAt(text, offset) {
+	let from = offset;
+	let to = offset;
+	while (from > 0 && /[\w$]/u.test(text[from - 1])) from--;
+	while (to < text.length && /[\w$]/u.test(text[to])) to++;
+	return from === to ? null : {
+		word: text.slice(from, to),
+		from,
+		to
+	};
+}
+function createMongodbAssist(catalog = NO_CATALOG, commands = MONGO_COMMANDS) {
+	const byName = new Map(commands.map((command) => [command.name, command]));
+	return {
+		complete: (text, offset) => {
+			const context = caretContext(text, offset);
+			if (context.kind === "key") {
+				const named = context.path.length === 0 ? context.siblings.find((key) => key !== "$db") : void 0;
+				const commanding = context.path.length === 0 && (named === void 0 || !byName.has(named));
+				const staged = context.path.at(-1) === "pipeline";
+				return keysAt(context.path, context.siblings, commands).map((key) => {
+					const command = commanding && key !== "$db" ? byName.get(key) : void 0;
+					const kind = command === void 0 ? key.startsWith("$") && key !== "$db" ? staged ? "stage" : "operator" : "field" : "command";
+					return {
+						label: key,
+						kind,
+						insertText: context.quoted ? key : `"${key}": $0`,
+						...!context.quoted && { snippet: true },
+						replace: context.typed.length,
+						...named !== void 0 && !commanding && { detail: named },
+						...command !== void 0 && { documentation: documentationOf(command) },
+						sortGroup: kind === "command" || kind === "field" ? 0 : 1
+					};
+				});
+			}
+			if (context.kind !== "value" || context.path.length > 0) return [];
+			const listed = catalog.collections();
+			const quote = (name) => context.quoted ? name : `"${name}"`;
+			if (context.key === "$db") return [...new Set(listed.map((collection) => collection.database))].map((database) => {
+				return {
+					label: database,
+					kind: "database",
+					insertText: quote(database),
+					replace: context.typed.length,
+					sortGroup: 0
+				};
+			});
+			const command = byName.get(context.key);
+			if (command === void 0 || !command.collection) return [];
+			const databases = new Set(listed.map((collection) => collection.database));
+			const seen = /* @__PURE__ */ new Set();
+			const candidates = [];
+			for (const collection of listed) {
+				if (seen.has(collection.name)) continue;
+				seen.add(collection.name);
+				candidates.push({
+					label: collection.name,
+					kind: "collection",
+					insertText: quote(collection.name),
+					replace: context.typed.length,
+					...databases.size > 1 && { detail: collection.database },
+					sortGroup: 0
+				});
+			}
+			return candidates;
+		},
+		hover: (text, offset) => {
+			const at = wordAt(text, offset);
+			if (at === null) return null;
+			const command = byName.get(at.word);
+			if (command === void 0) return null;
+			const context = caretContext(text, at.from);
+			if (context.kind !== "key" || context.path.length > 0) return null;
+			return {
+				from: at.from,
+				to: at.to,
+				markdown: [`**${command.name}**`, documentationOf(command)]
+			};
+		}
+	};
+}
+//#endregion
+export { CONSTRUCTORS, EXPRESSION_OPERATORS, FIELD_OPERATORS, LITERALS, MONGO_COMMANDS, PUSH_MODIFIERS, QUERY_OPERATORS, STAGES, UPDATE_OPERATORS, caretContext, createMongodbAssist, documentMarkers, keysAt, readDocument, runnableDocument };