@coldsmirk/inkstone-mongodb 0.22.0

package/dist/markers-CQOm7diu.d.ts

@@ -0,0 +1,218 @@
+//#region src/commands.d.ts
+/**
+ * The vocabulary the assist offers: the database commands a bench reaches for with the fields
+ * each takes, and the operators a key position takes by where it stands — a filter's, an
+ * update's, a pipeline's stages and their keys. Curated from the MongoDB manual, not
+ * exhaustive; the server's answer is the authority.
+ */
+/**
+ * One database command as the document names it in its first key.
+ */
+interface MongoCommand {
+  name: string;
+  summary: string;
+  /**
+   * The command's other top-level keys.
+   */
+  fields: string[];
+  /**
+   * Whether the command's own value names a collection (`{ find: "orders" }`), rather than
+   * being `1` or a name of another kind.
+   */
+  collection: boolean;
+}
+declare const MONGO_COMMANDS: readonly MongoCommand[];
+declare const QUERY_OPERATORS: string[];
+declare const FIELD_OPERATORS: string[];
+declare const UPDATE_OPERATORS: string[];
+declare const PUSH_MODIFIERS: string[];
+declare const STAGES: string[];
+declare const EXPRESSION_OPERATORS: string[];
+/**
+ * The keys to offer at a key position, by the keys enclosing the caret and — at the top level
+ * — the keys already there, the first of which names the command. Empty where the names are
+ * the reader's own (a field, a variable, a facet).
+ */
+declare function keysAt(path: readonly string[], siblings: readonly string[], commands?: readonly MongoCommand[]): string[];
+//#endregion
+//#region src/assist.d.ts
+/**
+ * One collection as the catalog lists it, under its database.
+ */
+interface CatalogCollection {
+  database: string;
+  name: string;
+}
+/**
+ * The catalog is the host's 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.
+ */
+interface MongodbCatalog {
+  collections: () => readonly CatalogCollection[];
+}
+/**
+ * One suggestion: a command, one of its fields, an operator, a pipeline stage, a collection
+ * or a database.
+ */
+interface MongodbCompletionCandidate {
+  label: string;
+  kind: "command" | "field" | "operator" | "stage" | "collection" | "database";
+  insertText: string;
+  /**
+   * `insertText` is a snippet (`$0` marks the caret) rather than plain text.
+   */
+  snippet?: boolean;
+  /**
+   * How many characters before the caret the insert replaces — the key or the name typed so
+   * far, bare or inside its quote.
+   */
+  replace: number;
+  detail?: string;
+  documentation?: string;
+  sortGroup: number;
+}
+interface MongodbHoverCard {
+  from: number;
+  to: number;
+  markdown: string[];
+}
+interface MongodbAssist {
+  complete: (text: string, offset: number) => MongodbCompletionCandidate[];
+  hover: (text: string, offset: number) => MongodbHoverCard | null;
+}
+/**
+ * Completion for keys and for the values that name a collection or a database, hover for the
+ * command under its key — all reading the document through `document.ts`.
+ */
+declare function createMongodbAssist(catalog?: MongodbCatalog, commands?: readonly MongoCommand[]): MongodbAssist;
+//#endregion
+//#region src/document.d.ts
+/**
+ * A MongoDB command is one document in the shell's own spelling — the command as its first
+ * key, `$db` naming the database — read here as the polyglot sidecar's MongoDB engine reads it
+ * with the driver's `BsonDocument.parse`: keys quoted or bare, strings in double or single
+ * quotes, the shell's constructors (`ObjectId("…")`, `ISODate("…")`, `NumberLong(…)`, `new
+ * Date(…)` …), regular-expression literals, `undefined`, `MinKey` and `MaxKey`, no comments and
+ * no trailing commas. A text this reader refuses is a text the engine refuses, for the same
+ * reason.
+ */
+/**
+ * Why a text is not a command — a code, never a sentence; the host owns the wording:
+ * `"not-a-document"` where it does not parse as one document, `"no-command"` where the document
+ * holds nothing but `$db`.
+ */
+type DocumentRefusal = "empty" | "not-a-document" | "no-command";
+interface DocumentRead {
+  /**
+   * The top-level keys in order, `$db` among them.
+   */
+  keys: string[];
+  /**
+   * The first key that is not `$db` — the command; null where there is none.
+   */
+  command: string | null;
+  /**
+   * `$db`'s value where it is a string.
+   */
+  database: string | null;
+  /**
+   * The command key's `[from, to)` in the text, quotes included; null where there is none.
+   */
+  commandSpan: {
+    from: number;
+    to: number;
+  } | null;
+  refusal: DocumentRefusal | null;
+  /**
+   * Where a `not-a-document` fault is, as an offset into the text; -1 otherwise.
+   */
+  at: number;
+}
+/**
+ * The constructors the shell's spelling allows in a value, `new` before any of them.
+ */
+declare const CONSTRUCTORS: readonly ["ObjectId", "ISODate", "Date", "NumberLong", "NumberInt", "NumberDecimal", "Timestamp", "BinData", "UUID", "HexData", "RegExp", "DBRef", "DBPointer", "MinKey", "MaxKey"];
+/**
+ * The bare words a value may be.
+ */
+declare const LITERALS: readonly ["true", "false", "null", "undefined", "Infinity", "NaN", "MinKey", "MaxKey"];
+/**
+ * The command a text holds, read as the engine reads it.
+ */
+declare function readDocument(text: string): DocumentRead;
+/**
+ * What one run should send: the selection where there is one, else the whole text — a command
+ * is one document; `none` where either is blank.
+ */
+type RunnableDocument = {
+  kind: "one";
+  text: string;
+  from: number;
+  to: number;
+} | {
+  kind: "none";
+};
+declare function runnableDocument(text: string, from: number, to: number): RunnableDocument;
+/**
+ * Where the caret stands, for completion: at a key of an object, at the value of a key, or
+ * nowhere the assist has anything to say.
+ */
+type CaretContext = {
+  kind: "key";
+  /**
+   * The keys of the objects enclosing the caret, outermost first, arrays and constructor
+   * calls passed through: `["filter", "age"]` inside the age's own object.
+   */
+  path: string[];
+  /**
+   * The keys already bound in the object the caret is a key of, in order.
+   */
+  siblings: string[];
+  /**
+   * The key's characters typed before the caret.
+   */
+  typed: string;
+  /**
+   * Whether the caret is inside an opened quote.
+   */
+  quoted: boolean;
+} | {
+  kind: "value";
+  path: string[];
+  /**
+   * The key whose value the caret is at.
+   */
+  key: string;
+  typed: string;
+  quoted: boolean;
+} | {
+  kind: "none";
+};
+/**
+ * A light scan of the text before the caret — not a parse, since a document being typed is
+ * rarely one — for the position the caret is at.
+ */
+declare function caretContext(text: string, offset: number): CaretContext;
+//#endregion
+//#region src/markers.d.ts
+/**
+ * What a marker says — a code, never a sentence; the host owns the wording:
+ *
+ * - `"not-a-document"` — the text is not one document in the shell's spelling; the engine
+ * refuses it (`error`), marked from where the reading stopped to the end of that line;
+ * - `"no-command"` — a document with nothing but `$db` in it; the engine refuses it (`error`);
+ * - `"unknown-command"` — a first key the table does not know (`hint`: the server may).
+ */
+type MongodbMarkerCode = Exclude<DocumentRefusal, "empty"> | "unknown-command";
+interface MongodbMarker {
+  from: number;
+  to: number;
+  code: MongodbMarkerCode;
+  severity: "error" | "hint";
+}
+/**
+ * The markers of the text as one command document; none for a blank text.
+ */
+declare function documentMarkers(text: string, commands?: readonly MongoCommand[]): MongodbMarker[];
+//#endregion
+export { PUSH_MODIFIERS as C, keysAt as D, UPDATE_OPERATORS as E, MongoCommand as S, STAGES as T, MongodbHoverCard as _, CaretContext as a, FIELD_OPERATORS as b, LITERALS as c, readDocument as d, runnableDocument as f, MongodbCompletionCandidate as g, MongodbCatalog as h, CONSTRUCTORS as i, RunnableDocument as l, MongodbAssist as m, MongodbMarkerCode as n, DocumentRead as o, CatalogCollection as p, documentMarkers as r, DocumentRefusal as s, MongodbMarker as t, caretContext as u, createMongodbAssist as v, QUERY_OPERATORS as w, MONGO_COMMANDS as x, EXPRESSION_OPERATORS as y };

package/dist/monaco.d.ts

@@ -0,0 +1,40 @@
+import { m as MongodbAssist, t as MongodbMarker } from "./markers-CQOm7diu.js";
+import * as monacoEditor from "monaco-editor";
+import { IDisposable, editor } from "monaco-editor";
+//#region src/monaco.d.ts
+/**
+ * The monaco module itself, as `onMount` hands it over.
+ */
+type MonacoModule = typeof monacoEditor;
+/**
+ * The language id the editor registers a command document under.
+ */
+declare const MONGODB_LANGUAGE_ID = "mongodb";
+/**
+ * Register the language — the id, its Monarch grammar and its bracket configuration — once per
+ * monaco module. Call it before the first model of the language is created (`beforeMount`).
+ */
+declare function defineMongodbLanguage(monaco: MonacoModule, languageId?: string): void;
+interface MongodbLanguageHooks {
+  /**
+   * The assist as it stands right now — read per request rather than captured, so the host
+   * can swap it without touching Monaco's registry; null answers nothing.
+   */
+  assist: () => MongodbAssist | null;
+}
+/**
+ * Register completion and hover for one model. The disposables are the caller's to hold:
+ * Monaco's registry outlives any editor.
+ */
+declare function registerMongodbLanguage(monaco: MonacoModule, modelPath: string, hooks: MongodbLanguageHooks, languageId?: string): IDisposable[];
+/**
+ * The owner Monaco files this package's markers under.
+ */
+declare const MONGODB_MARKER_OWNER = "inkstone-mongodb";
+/**
+ * Put `markers` on the model as Monaco's own, replacing this package's last set; the words
+ * beside each code are the host's, handed in per code.
+ */
+declare function setMongodbMarkers(monaco: MonacoModule, model: editor.ITextModel, markers: readonly MongodbMarker[], wording: (marker: MongodbMarker) => string): void;
+//#endregion
+export { MONGODB_LANGUAGE_ID, MONGODB_MARKER_OWNER, MonacoModule, MongodbLanguageHooks, defineMongodbLanguage, registerMongodbLanguage, setMongodbMarkers };

package/dist/monaco.js

@@ -0,0 +1,170 @@
+import { n as LITERALS, t as CONSTRUCTORS } from "./document-CVB9YunA.js";
+//#region src/monaco.ts
+const MONGODB_LANGUAGE_ID = "mongodb";
+const LANGUAGES_KEY = Symbol.for("coldsmirk.inkstone.mongodb.languages");
+function definedLanguages(monaco) {
+	const holder = globalThis;
+	const registry = holder[LANGUAGES_KEY] ?? /* @__PURE__ */ new WeakMap();
+	holder[LANGUAGES_KEY] = registry;
+	const existing = registry.get(monaco);
+	if (existing) return existing;
+	const created = /* @__PURE__ */ new Set();
+	registry.set(monaco, created);
+	return created;
+}
+function grammar() {
+	const calls = CONSTRUCTORS.filter((name) => name !== "MinKey" && name !== "MaxKey").join("|");
+	return {
+		unicode: true,
+		tokenizer: { root: [
+			[/\$[\w$]*(?=\s*:)/u, "keyword"],
+			[/"\$(?:[^"\\]|\\.)*"(?=\s*:)/u, "keyword"],
+			[/'\$(?:[^'\\]|\\.)*'(?=\s*:)/u, "keyword"],
+			[/"(?:[^"\\]|\\.)*"(?=\s*:)/u, "support.type.property-name.json"],
+			[/'(?:[^'\\]|\\.)*'(?=\s*:)/u, "support.type.property-name.json"],
+			[/[A-Za-z_$][\w$]*(?=\s*:)/u, "support.type.property-name.json"],
+			[/"(?:[^"\\]|\\.)*"/u, "string"],
+			[/'(?:[^'\\]|\\.)*'/u, "string"],
+			[/\/(?:[^/\\\n]|\\.)+\/[a-z]*/u, "string.regexp"],
+			[/-?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?/iu, "constant.numeric"],
+			[/\bnew\b/u, "keyword"],
+			[new RegExp(String.raw`\b(?:${calls})\b(?=\s*\()`, "u"), "support.function"],
+			[new RegExp(String.raw`\b(?:${LITERALS.join("|")})\b`, "u"), "constant.language"],
+			[/[{}[\]()]/u, "delimiter.bracket"],
+			[/[,:]/u, "delimiter"],
+			[/\s+/u, "white"],
+			[/[^\s"'{}[\]():,]+/u, "variable"]
+		] }
+	};
+}
+function defineMongodbLanguage(monaco, languageId = MONGODB_LANGUAGE_ID) {
+	const defined = definedLanguages(monaco);
+	if (defined.has(languageId)) return;
+	defined.add(languageId);
+	monaco.languages.register({ id: languageId });
+	monaco.languages.setLanguageConfiguration(languageId, {
+		brackets: [
+			["{", "}"],
+			["[", "]"],
+			["(", ")"]
+		],
+		autoClosingPairs: [
+			{
+				open: "{",
+				close: "}"
+			},
+			{
+				open: "[",
+				close: "]"
+			},
+			{
+				open: "(",
+				close: ")"
+			},
+			{
+				open: "\"",
+				close: "\"",
+				notIn: ["string"]
+			},
+			{
+				open: "'",
+				close: "'",
+				notIn: ["string"]
+			}
+		],
+		surroundingPairs: [
+			{
+				open: "{",
+				close: "}"
+			},
+			{
+				open: "[",
+				close: "]"
+			},
+			{
+				open: "(",
+				close: ")"
+			},
+			{
+				open: "\"",
+				close: "\""
+			},
+			{
+				open: "'",
+				close: "'"
+			}
+		],
+		wordPattern: /[\w$]+/u
+	});
+	monaco.languages.setMonarchTokensProvider(languageId, grammar());
+}
+function itemKinds(monaco) {
+	const kinds = monaco.languages.CompletionItemKind;
+	return {
+		command: kinds.Function,
+		field: kinds.Field,
+		operator: kinds.Keyword,
+		stage: kinds.Method,
+		collection: kinds.Struct,
+		database: kinds.Module
+	};
+}
+function registerMongodbLanguage(monaco, modelPath, hooks, languageId = MONGODB_LANGUAGE_ID) {
+	const kinds = itemKinds(monaco);
+	const path = monaco.Uri.parse(modelPath).toString();
+	const answering = (model) => model.uri.toString() === path ? hooks.assist() : null;
+	return [monaco.languages.registerCompletionItemProvider(languageId, {
+		triggerCharacters: [
+			"\"",
+			"'",
+			"$"
+		],
+		provideCompletionItems: (model, position) => {
+			const assist = answering(model);
+			if (assist === null) return { suggestions: [] };
+			return { suggestions: assist.complete(model.getValue(), model.getOffsetAt(position)).map((candidate, index) => {
+				return {
+					label: candidate.label,
+					kind: kinds[candidate.kind],
+					insertText: candidate.insertText,
+					insertTextRules: candidate.snippet ? monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet : void 0,
+					detail: candidate.detail,
+					documentation: candidate.documentation,
+					range: new monaco.Range(position.lineNumber, Math.max(1, position.column - candidate.replace), position.lineNumber, position.column),
+					sortText: `${String(candidate.sortGroup)}:${String(index).padStart(4, "0")}`
+				};
+			}) };
+		}
+	}), monaco.languages.registerHoverProvider(languageId, { provideHover: (model, position) => {
+		const assist = answering(model);
+		if (assist === null) return null;
+		const card = assist.hover(model.getValue(), model.getOffsetAt(position));
+		if (card === null) return null;
+		const from = model.getPositionAt(card.from);
+		const to = model.getPositionAt(card.to);
+		return {
+			range: new monaco.Range(from.lineNumber, from.column, to.lineNumber, to.column),
+			contents: card.markdown.map((value) => {
+				return { value };
+			})
+		};
+	} })];
+}
+const MONGODB_MARKER_OWNER = "inkstone-mongodb";
+function setMongodbMarkers(monaco, model, markers, wording) {
+	const severities = monaco.MarkerSeverity;
+	monaco.editor.setModelMarkers(model, MONGODB_MARKER_OWNER, markers.map((marker) => {
+		const from = model.getPositionAt(marker.from);
+		const to = model.getPositionAt(marker.to);
+		return {
+			severity: marker.severity === "error" ? severities.Error : severities.Hint,
+			message: wording(marker),
+			startLineNumber: from.lineNumber,
+			startColumn: from.column,
+			endLineNumber: to.lineNumber,
+			endColumn: to.column
+		};
+	}));
+}
+//#endregion
+export { MONGODB_LANGUAGE_ID, MONGODB_MARKER_OWNER, defineMongodbLanguage, registerMongodbLanguage, setMongodbMarkers };

package/dist/react.d.ts

@@ -0,0 +1,93 @@
+import { m as MongodbAssist, t as MongodbMarker } from "./markers-CQOm7diu.js";
+import { MonacoModule } from "./monaco.js";
+import { ReactNode } from "react";
+import { editor } from "monaco-editor";
+//#region src/react.d.ts
+/**
+ * What a host reaches into the editor for: inserting at the caret — a collection tree is an
+ * input device — and the focus.
+ */
+interface MongodbEditorHandle {
+  insert: (text: string) => void;
+  focus: () => void;
+}
+/**
+ * Where the operator is in the document, in offsets — what `runnableDocument` reads to decide
+ * what a run sends. `from` and `to` are the selection's bounds and equal where nothing is
+ * selected; the text rides with them because the two must belong to the same instant.
+ */
+interface MongodbCaret {
+  text: string;
+  from: number;
+  to: number;
+}
+interface MongodbEditorProps {
+  value: string;
+  onChange: (value: string) => void;
+  /**
+   * Render with the dark theme; the component never reads the OS `prefers-color-scheme`.
+   *
+   * @default false
+   */
+  dark?: boolean;
+  /**
+   * Editor height in px, or `"fill"` to consume the parent's resolved height (the parent must be
+   * a `min-height: 0` flex item).
+   */
+  height?: number | "fill";
+  fontSize?: number;
+  /**
+   * UI locale for Monaco's chrome — page-global and locked by the first editor to mount.
+   */
+  locale?: "en" | "zh-cn";
+  placeholder?: string;
+  /**
+   * The editor's accessible name, set on Monaco's own input surface.
+   */
+  ariaLabel: string;
+  /**
+   * The Monaco language id the model registers under; the grammar is defined under it.
+   *
+   * @default "mongodb"
+   */
+  languageId?: string;
+  loading?: ReactNode;
+  failure?: ReactNode;
+  /**
+   * Ctrl/Cmd-Enter — the run key, handed the editor's live caret; the host reads the document
+   * to send off it with `runnableDocument`.
+   */
+  onRun?: (caret: MongodbCaret) => void;
+  /**
+   * The label the run action shows in Monaco's own chrome.
+   *
+   * @default "Run command"
+   */
+  runActionLabel?: string;
+  /**
+   * The caret moved, or the text under it changed.
+   */
+  onCaret?: (caret: MongodbCaret) => void;
+  onReady?: (handle: MongodbEditorHandle) => void;
+  /**
+   * Runs after this component's own mount wiring, with the live editor and the monaco module.
+   */
+  onMount?: (instance: editor.IStandaloneCodeEditor, monaco: MonacoModule) => void;
+  /**
+   * What completion and hover answer from; neither without it.
+   */
+  assist?: MongodbAssist;
+  /**
+   * The words each marker shows, per code (`documentMarkers`) — the host's language. No
+   * markers are drawn without it.
+   */
+  markerWording?: (marker: MongodbMarker) => string;
+}
+/**
+ * The command editing surface: Monaco under the `mongodb` grammar, one command document in the
+ * shell's spelling, the run key handing the caret over, completion and hover wired through
+ * `registerMongodbLanguage`, and the markers refreshed on every change.
+ */
+declare function MongodbEditor({ value, onChange, dark, height, fontSize, locale, placeholder, ariaLabel, languageId, loading, failure, onRun, runActionLabel, onCaret, onReady, onMount, assist, markerWording }: MongodbEditorProps): import("react").JSX.Element;
+//#endregion
+export { MongodbCaret, MongodbEditor, MongodbEditorHandle, MongodbEditorProps };

package/dist/react.js

@@ -0,0 +1,104 @@
+import { t as documentMarkers } from "./markers-Bdvbut2O.js";
+import { MONGODB_LANGUAGE_ID, defineMongodbLanguage, registerMongodbLanguage, setMongodbMarkers } from "./monaco.js";
+import { MonacoEditor } from "@coldsmirk/inkstone-react/monaco";
+import { useEffect, useInsertionEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react.tsx
+const EDITOR_ID_KEY = Symbol.for("coldsmirk.inkstone.mongodb.editorId");
+function nextEditorId() {
+	const holder = globalThis;
+	const id = holder[EDITOR_ID_KEY] ?? 0;
+	holder[EDITOR_ID_KEY] = id + 1;
+	return id;
+}
+function useLatest(value) {
+	const ref = useRef(value);
+	useInsertionEffect(() => {
+		ref.current = value;
+	});
+	return ref;
+}
+function caretOf(instance) {
+	const model = instance.getModel();
+	const selection = instance.getSelection();
+	if (model === null || selection === null) return {
+		text: "",
+		from: 0,
+		to: 0
+	};
+	return {
+		text: model.getValue(),
+		from: model.getOffsetAt(selection.getStartPosition()),
+		to: model.getOffsetAt(selection.getEndPosition())
+	};
+}
+function MongodbEditor({ value, onChange, dark = false, height = 200, fontSize, locale, placeholder, ariaLabel, languageId = MONGODB_LANGUAGE_ID, loading, failure, onRun, runActionLabel = "Run command", onCaret, onReady, onMount, assist, markerWording }) {
+	const [modelPath] = useState(() => `file:///inkstone-mongodb/${String(nextEditorId())}.mongodb`);
+	const bindings = useRef([]);
+	const assistRef = useLatest(assist ?? null);
+	const runRef = useLatest(onRun);
+	const caretChangedRef = useLatest(onCaret);
+	const readyRef = useLatest(onReady);
+	const mountRef = useLatest(onMount);
+	const wordingRef = useLatest(markerWording);
+	useEffect(() => () => {
+		for (const binding of bindings.current) binding.dispose();
+		bindings.current = [];
+	}, []);
+	const fill = height === "fill";
+	return /* @__PURE__ */ jsx("div", {
+		style: fill ? {
+			height: "100%",
+			minHeight: 0
+		} : { height },
+		children: /* @__PURE__ */ jsx(MonacoEditor, {
+			showLineNumbers: true,
+			dark,
+			failure,
+			fontSize,
+			height: fill ? "100%" : height,
+			language: languageId,
+			loading,
+			locale,
+			options: { ariaLabel },
+			path: modelPath,
+			placeholder,
+			value,
+			beforeMount: (monaco) => {
+				defineMongodbLanguage(monaco, languageId);
+			},
+			onChange,
+			onMount: (live, monaco) => {
+				const mark = () => {
+					const model = live.getModel();
+					const wording = wordingRef.current;
+					if (model !== null && wording !== void 0) setMongodbMarkers(monaco, model, documentMarkers(model.getValue()), wording);
+				};
+				bindings.current.push(live.onDidChangeCursorSelection(() => caretChangedRef.current?.(caretOf(live))), live.onDidChangeModelContent(mark), live.addAction({
+					id: "inkstone-mongodb.run",
+					label: runActionLabel,
+					keybindings: [monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter],
+					run: (current) => runRef.current?.(caretOf(current))
+				}), ...registerMongodbLanguage(monaco, modelPath, { assist: () => assistRef.current }, languageId));
+				mark();
+				readyRef.current?.({
+					insert: (text) => {
+						const selection = live.getSelection();
+						if (selection) live.executeEdits("inkstone-mongodb-insert", [{
+							range: selection,
+							text,
+							forceMoveMarkers: true
+						}]);
+						live.focus();
+					},
+					focus: () => {
+						live.focus();
+					}
+				});
+				mountRef.current?.(live, monaco);
+			}
+		})
+	});
+}
+//#endregion
+export { MongodbEditor };