@coldsmirk/inkstone-elasticsearch 0.22.0

package/README.md

@@ -0,0 +1,50 @@
+# @coldsmirk/inkstone-elasticsearch
+
+Elasticsearch request editing intelligence for Monaco: requests in Kibana's console spelling (`GET /orders/_search` on the first line, the body after), endpoint and index completion on the path, body keys by where the caret stands (the query DSL's clauses under `query`, a `bool`'s clauses, the aggregation types, a mapping's field options …), the request read as the engine reads it, markers, and a drop-in React `<ElasticsearchEditor>`.
+
+Part of [inkstone](https://github.com/coldsmirk/inkstone). Built for the [**polyglot**](https://github.com/coldsmirk/polyglot) sidecar's Elasticsearch engine, which takes one request in this very spelling.
+
+## Entries
+
+- **`@coldsmirk/inkstone-elasticsearch`** — the framework-free core: the request reader, the endpoint table, the body vocabulary, the assist, the markers. Zero editor dependencies.
+- **`@coldsmirk/inkstone-elasticsearch/monaco`** — `defineElasticsearchLanguage(monaco)` (the `elasticsearch` id with its Monarch grammar, once per monaco module), `registerElasticsearchLanguage(monaco, modelPath, hooks)` (completion and hover for one model), `setElasticsearchMarkers`. Peer: `monaco-editor`.
+- **`@coldsmirk/inkstone-elasticsearch/react`** — `<ElasticsearchEditor>`: a controlled request 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 index trees, and the markers refreshed on every change. Peers: `monaco-editor`, `react`.
+
+## The shape
+
+```ts
+import { createElasticsearchAssist, requestMarkers, runnableRequest } from "@coldsmirk/inkstone-elasticsearch";
+
+// 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 path.
+const assist = createElasticsearchAssist({ indices: () => cachedIndices() });   // CatalogIndex[]
+
+// What one run should send: the selection where there is one, else the request the caret is in
+// — a document may hold several, each starting at its request line.
+const runnable = runnableRequest(text, from, to);
+
+if (runnable.kind === "one") {
+  send(runnable.text);
+}
+
+// A code per fault — the host owns the wording.
+for (const marker of requestMarkers(text)) {
+  console.log(marker.code, marker.severity, marker.from, marker.to);
+}
+```
+
+## The mirror invariant
+
+`readRequest` reads a request exactly as the engine does before sending it: the text stripped, the first line split into a method and a path on its first blank, the method uppercased and one of `GET` / `POST` / `PUT` / `DELETE` / `HEAD` / `PATCH`, the path starting with `/`, the rest the body — newline-delimited under `_bulk` and `_msearch`, JSON otherwise. What it refuses, the engine refuses, as a code (`"no-request-line"`, `"unknown-method"`, `"path-without-slash"`). A change to the engine's reading requires a matching release of this package; `request.test.ts` carries the cases.
+
+## The vocabulary
+
+The endpoint table and the body keys are curated in `api.ts` — the paths a bench reaches for and the keys the query DSL, the aggregations and the mappings take, by context. They are a hint of the API'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-elasticsearch 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/index.d.ts

@@ -0,0 +1,34 @@
+import { _ as readRequest, a as ElasticsearchAssist, b as runnableRequest, c as ElasticsearchHoverCard, d as REQUEST_METHODS, f as RequestMethod, g as caretContext, h as RunnableRequest, i as CatalogIndex, l as createElasticsearchAssist, m as RequestRefusal, n as ElasticsearchMarkerCode, o as ElasticsearchCatalog, p as RequestRead, r as requestMarkers, s as ElasticsearchCompletionCandidate, t as ElasticsearchMarker, u as CaretContext, v as requestAt, x as takesLines, y as requestSpans } from "./markers-BctX905j.js";
+//#region src/api.d.ts
+/**
+ * The vocabulary the assist offers: the REST endpoints a bench reaches for, and the keys of a
+ * body by where the caret stands in it. Curated, not exhaustive — the console's own
+ * completion is a hint of the API's shape, and the server's answer is the authority.
+ */
+/**
+ * One endpoint: its path with `{index}`, `{id}` and `{name}` for the parts the reader fills
+ * in, the methods it takes, and one line on what it does.
+ */
+interface ApiEndpoint {
+  path: string;
+  methods: RequestMethod[];
+  summary: string;
+}
+declare const API_ENDPOINTS: readonly ApiEndpoint[];
+/**
+ * The endpoint a path names, `{…}` parts matching one segment each; null where none does.
+ * The query string is not part of the match.
+ */
+declare function endpointOf(path: string): ApiEndpoint | null;
+/**
+ * What the request is for, read off its path — which decides the top-level keys of its body.
+ */
+type BodyKind = "search" | "count" | "index" | "mapping" | "settings" | "document" | "update" | "update-by-query" | "reindex" | "aliases" | "analyze" | "sql" | "cluster-settings" | "template" | "explain" | "mget" | "other";
+declare function bodyKindOf(method: string, path: string): BodyKind;
+/**
+ * The keys to offer at a key position in the body, by the request the body belongs to and the
+ * keys enclosing the caret; empty where the names are the reader's own (a field, an aggregation).
+ */
+declare function bodyKeys(kind: BodyKind, path: readonly string[]): string[];
+//#endregion
+export { API_ENDPOINTS, type ApiEndpoint, type BodyKind, type CaretContext, type CatalogIndex, type ElasticsearchAssist, type ElasticsearchCatalog, type ElasticsearchCompletionCandidate, type ElasticsearchHoverCard, type ElasticsearchMarker, type ElasticsearchMarkerCode, REQUEST_METHODS, type RequestMethod, type RequestRead, type RequestRefusal, type RunnableRequest, bodyKeys, bodyKindOf, caretContext, createElasticsearchAssist, endpointOf, readRequest, requestAt, requestMarkers, requestSpans, runnableRequest, takesLines };

package/dist/index.js

@@ -0,0 +1,102 @@
+import { a as requestAt, c as takesLines, d as bodyKindOf, f as endpointOf, i as readRequest, l as API_ENDPOINTS, n as REQUEST_METHODS, o as requestSpans, r as caretContext, s as runnableRequest, t as requestMarkers, u as bodyKeys } from "./markers-DBJshw-Y.js";
+//#region src/assist.ts
+const NO_CATALOG = { indices: () => [] };
+function tailOf(endpoint, prefix) {
+	return endpoint.path.slice(prefix.length).replaceAll(/\/\{[^}]+\}/gu, "").replace(/^\//u, "");
+}
+function endpointCandidate(endpoint, label, replace) {
+	return {
+		label,
+		kind: "endpoint",
+		insertText: label,
+		replace,
+		detail: endpoint.methods.join(" | "),
+		documentation: endpoint.summary,
+		sortGroup: 1
+	};
+}
+function createElasticsearchAssist(catalog = NO_CATALOG) {
+	return {
+		complete: (text, offset) => {
+			const context = caretContext(text, offset);
+			switch (context.kind) {
+				case "method": return REQUEST_METHODS.map((method) => {
+					return {
+						label: method,
+						kind: "method",
+						insertText: `${method} `,
+						replace: context.typed.length,
+						sortGroup: 0
+					};
+				});
+				case "path": {
+					const replace = context.typed.length;
+					if (context.segments.length === 0) {
+						const indices = catalog.indices().map((index) => {
+							return {
+								label: index.name,
+								kind: index.alias ? "alias" : "index",
+								insertText: index.name,
+								replace,
+								sortGroup: 0
+							};
+						});
+						const roots = API_ENDPOINTS.filter((endpoint) => endpoint.path !== "/" && !endpoint.path.startsWith("/{index}")).map((endpoint) => endpointCandidate(endpoint, tailOf(endpoint, "/"), replace));
+						return [...indices, ...roots];
+					}
+					if (context.segments.length === 1 && !context.segments[0].startsWith("_")) {
+						const seen = /* @__PURE__ */ new Set();
+						const under = [];
+						for (const endpoint of API_ENDPOINTS) {
+							if (!endpoint.path.startsWith("/{index}/")) continue;
+							const label = tailOf(endpoint, "/{index}/");
+							if (!seen.has(label)) {
+								seen.add(label);
+								under.push(endpointCandidate(endpoint, label, replace));
+							}
+						}
+						return under;
+					}
+					return [];
+				}
+				case "body-key": {
+					const kind = bodyKindOf(context.request.method, context.request.path);
+					return bodyKeys(kind, context.path).map((key) => context.quoted ? {
+						label: key,
+						kind: "key",
+						insertText: key,
+						replace: context.typed.length,
+						sortGroup: 0
+					} : {
+						label: key,
+						kind: "key",
+						insertText: `"${key}": $0`,
+						snippet: true,
+						replace: 0,
+						sortGroup: 0
+					});
+				}
+				default: return [];
+			}
+		},
+		hover: (text, offset) => {
+			const span = requestAt(text, offset);
+			const request = readRequest(text.slice(span.from, span.to));
+			if (request.refusal !== null && request.refusal !== "unknown-method") return null;
+			const lineFrom = span.from + request.line.from;
+			const lineTo = span.from + request.line.to;
+			const line = text.slice(lineFrom, lineTo);
+			const pathAt = line.search(/\s/u) + (line.slice(line.search(/\s/u)).length - line.slice(line.search(/\s/u)).trimStart().length);
+			if (offset < lineFrom + pathAt || offset > lineTo) return null;
+			const endpoint = endpointOf(request.path);
+			if (endpoint === null) return null;
+			return {
+				from: lineFrom + pathAt,
+				to: lineTo,
+				markdown: [`\`${endpoint.methods.join(" | ")} ${endpoint.path}\``, endpoint.summary]
+			};
+		}
+	};
+}
+//#endregion
+export { API_ENDPOINTS, REQUEST_METHODS, bodyKeys, bodyKindOf, caretContext, createElasticsearchAssist, endpointOf, readRequest, requestAt, requestMarkers, requestSpans, runnableRequest, takesLines };

package/dist/markers-BctX905j.d.ts

@@ -0,0 +1,204 @@
+//#region src/request.d.ts
+/**
+ * An Elasticsearch command is one request in Kibana's console spelling — `METHOD /path` on
+ * the first line, the body on the lines after — read here exactly as the polyglot sidecar's
+ * Elasticsearch engine reads it before sending: the text stripped, the first line split into
+ * a method and a path on its first blank, the method uppercased and one of six, the path
+ * starting with `/`, the rest the body, sent as ndjson under `_bulk` and `_msearch` and as
+ * JSON otherwise. A request this reader refuses is a request the engine refuses, for the
+ * same reason.
+ */
+declare const REQUEST_METHODS: readonly ["GET", "POST", "PUT", "DELETE", "HEAD", "PATCH"];
+type RequestMethod = (typeof REQUEST_METHODS)[number];
+/**
+ * Why a request could not be read — a code, never a sentence; the host owns the wording.
+ */
+type RequestRefusal = "empty" | "no-request-line" | "unknown-method" | "path-without-slash";
+interface RequestRead {
+  /**
+   * The method, uppercased; empty where the first line has none.
+   */
+  method: string;
+  /**
+   * The path with its query string, as written.
+   */
+  path: string;
+  /**
+   * The body, stripped; empty where there is none.
+   */
+  body: string;
+  bodyKind: "none" | "json" | "ndjson";
+  /**
+   * The request line's `[from, to)` in the text handed in, leading blanks left out.
+   */
+  line: {
+    from: number;
+    to: number;
+  };
+  /**
+   * The body's `[from, to)`, or null where there is none.
+   */
+  bodySpan: {
+    from: number;
+    to: number;
+  } | null;
+  refusal: RequestRefusal | null;
+}
+/**
+ * Whether the path names an endpoint that takes newline-delimited JSON, as the engine decides
+ * the content type.
+ */
+declare function takesLines(path: string): boolean;
+/**
+ * One request, read as the engine reads it.
+ */
+declare function readRequest(text: string): RequestRead;
+/**
+ * The `[from, to)` of every request in the document — each from its request line to the line
+ * before the next request's, blanks at either end left out; a document with no request line
+ * is one request whole, and text before the first request line belongs to none.
+ */
+declare function requestSpans(text: string): Array<{
+  from: number;
+  to: number;
+}>;
+/**
+ * The `[from, to)` of the request the caret is in (`requestSpans`); the first where the caret
+ * stands before every request line.
+ */
+declare function requestAt(text: string, offset: number): {
+  from: number;
+  to: number;
+};
+/**
+ * What one run should send: the selection where there is one, else the request the caret is
+ * in; `none` where either is blank.
+ */
+type RunnableRequest = {
+  kind: "one";
+  text: string;
+  from: number;
+  to: number;
+} | {
+  kind: "none";
+};
+declare function runnableRequest(text: string, from: number, to: number): RunnableRequest;
+/**
+ * Where the caret stands, for completion: in the request line's method or path, at a key
+ * position in the body, or nowhere the assist has anything to say.
+ */
+type CaretContext = {
+  kind: "method";
+  /**
+   * The characters of the method typed before the caret.
+   */
+  typed: string;
+} | {
+  kind: "path";
+  /**
+   * The path's segments before the caret's own, the leading `/` dropped: `[]` in the first
+   * segment, `["orders"]` in the second.
+   */
+  segments: string[];
+  /**
+   * The caret's own segment as typed before the caret.
+   */
+  typed: string;
+} | {
+  kind: "body-key";
+  /**
+   * The keys of the objects enclosing the caret, outermost first, arrays passed through:
+   * `["query", "bool"]` inside the bool's own object.
+   */
+  path: string[];
+  /**
+   * The request the body belongs to, for the top-level vocabulary.
+   */
+  request: RequestRead;
+  /**
+   * The key's characters typed before the caret, inside an opened quote where one stands.
+   */
+  typed: string;
+  /**
+   * Whether the caret is inside an opened quote.
+   */
+  quoted: boolean;
+} | {
+  kind: "none";
+};
+declare function caretContext(text: string, offset: number): CaretContext;
+//#endregion
+//#region src/assist.d.ts
+/**
+ * One index or alias as the catalog lists it.
+ */
+interface CatalogIndex {
+  name: string;
+  alias: boolean;
+}
+/**
+ * The catalog is the host's to fetch — and it MUST be a cache-backed read (a query cache, a
+ * memo the tree's refresh invalidates), never a fresh fetch: completion reads it on every
+ * keystroke in a path, and the package deliberately holds no cache of its own.
+ */
+interface ElasticsearchCatalog {
+  indices: () => readonly CatalogIndex[];
+}
+/**
+ * One suggestion: a method, an endpoint's path, an index or alias, or a body key.
+ */
+interface ElasticsearchCompletionCandidate {
+  label: string;
+  kind: "method" | "endpoint" | "index" | "alias" | "key";
+  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 segment or the key typed
+   * so far, which the editor's own word rules do not see whole (a path segment holds `_` and
+   * `.`, a key stands inside quotes).
+   */
+  replace: number;
+  detail?: string;
+  documentation?: string;
+  sortGroup: number;
+}
+interface ElasticsearchHoverCard {
+  from: number;
+  to: number;
+  markdown: string[];
+}
+interface ElasticsearchAssist {
+  complete: (text: string, offset: number) => ElasticsearchCompletionCandidate[];
+  hover: (text: string, offset: number) => ElasticsearchHoverCard | null;
+}
+/**
+ * Completion for the request line and the body, hover for the endpoint on the request line —
+ * both reading the request through `request.ts`, as the engine reads it.
+ */
+declare function createElasticsearchAssist(catalog?: ElasticsearchCatalog): ElasticsearchAssist;
+//#endregion
+//#region src/markers.d.ts
+/**
+ * What a marker says — a code, never a sentence; the host owns the wording:
+ *
+ * - the request-line faults `readRequest` refuses, which the engine refuses too (`error`);
+ * - `"body-not-json"` — a body (or, under `_bulk` and `_msearch`, a line of it) that is not
+ * one JSON value; the server will refuse it (`warning`);
+ * - `"method-not-taken"` — a known endpoint under a method it does not list (`hint`).
+ */
+type ElasticsearchMarkerCode = Exclude<RequestRefusal, "empty"> | "body-not-json" | "method-not-taken";
+interface ElasticsearchMarker {
+  from: number;
+  to: number;
+  code: ElasticsearchMarkerCode;
+  severity: "error" | "warning" | "hint";
+}
+/**
+ * The markers of every request in the text.
+ */
+declare function requestMarkers(text: string): ElasticsearchMarker[];
+//#endregion
+export { readRequest as _, ElasticsearchAssist as a, runnableRequest as b, ElasticsearchHoverCard as c, REQUEST_METHODS as d, RequestMethod as f, caretContext as g, RunnableRequest as h, CatalogIndex as i, createElasticsearchAssist as l, RequestRefusal as m, ElasticsearchMarkerCode as n, ElasticsearchCatalog as o, RequestRead as p, requestMarkers as r, ElasticsearchCompletionCandidate as s, ElasticsearchMarker as t, CaretContext as u, requestAt as v, takesLines as x, requestSpans as y };