@coldsmirk/inkstone-sql 0.13.0

package/dist/index.d.ts

@@ -0,0 +1,380 @@
+import { C as CatalogTable, S as CatalogFunction, _ as readCall, a as createSqlAssist, b as runnableStatement, c as SqlSource, d as CallRead, f as IdentifierRead, g as TableRef, h as StatementRead, i as SqlSignatureHelp, l as createSqlSchema, m as StatementContext, n as SqlCompletionCandidate, o as SqlCatalog, p as Runnable, r as SqlHoverCard, s as SqlSchema, t as SqlAssist, u as qualifiedName, v as readIdentifier, w as SqlKind, x as CatalogColumn, y as readStatement } from "./assist-gLTZKSD3.js";
+
+//#region src/functions.d.ts
+/**
+ * The function vocabulary this bench speaks: the curated floor this project wrote
+ * down, and whatever the data source in front of the operator reports about itself — its own
+ * routines from every kind, its built-ins from the kinds whose catalogs describe them.
+ *
+ * Completion, hover and signature help all read it here, so a name cannot mean one thing in the
+ * pane and another under the mouse.
+ */
+/**
+ * One function, however the bench came to know it.
+ */
+interface BenchFunction {
+  name: string;
+  /**
+   * The call as it is written — what signature help parses.
+   */
+  signature: string;
+  /**
+   * One line about it: this project's own for a curated name, the database's own description for
+   * anything else, and empty where neither exists.
+   */
+  summary: string;
+  /**
+   * The return type as the catalog spells it, shown beside the call on the hover card; empty
+   * where the catalog reports none — the curated floor included, whose signatures carry the
+   * return in their own prose where it matters.
+   */
+  returns: string;
+  /**
+   * The owner or package a call must qualify with; empty for a built-in, and for a routine the
+   * connected schema already resolves.
+   */
+  qualifier: string;
+  /**
+   * Where it came from. It decides how the pane ranks it and what a hover says about it: a
+   * routine is the estate's own, a curated name is bench vocabulary, and the rest is the
+   * vendor's own long tail.
+   */
+  origin: "routine" | "curated" | "builtin";
+}
+interface SqlFunctions {
+  /**
+   * Every function the bench can offer, in rank order. Falls back to the curated floor alone
+   * when the catalog refuses — a vocabulary is not worth a failed keystroke.
+   */
+  all: () => Promise<BenchFunction[]>;
+  /**
+   * One function by name, however the operator cased it.
+   */
+  find: (name: string) => Promise<BenchFunction | null>;
+}
+declare function createSqlFunctions(kind: SqlKind, schema: SqlSchema): SqlFunctions;
+//#endregion
+//#region src/completion.d.ts
+/**
+ * Completion for one system's data source, over the schema the tree already reads.
+ */
+declare function createSqlCompletion(kind: SqlKind, schema: SqlSchema, functions: SqlFunctions): SqlAssist["complete"];
+//#endregion
+//#region src/dialect.d.ts
+/**
+ * One function the bench knows how to talk about: the call as the operator writes it, and one
+ * line saying what it does. The signature is the whole parameter contract — signature help reads
+ * the parameters straight out of its parens, so a `…` tail is what marks a variadic call.
+ *
+ * The summaries are English, the register the script editor's API docs already use: they read as
+ * reference documentation beside each vendor's own, which is where an operator checks them next.
+ */
+interface SqlFunction {
+  name: string;
+  signature: string;
+  summary: string;
+}
+/**
+ * One kind's completion vocabulary. Curated bench vocabulary, not the reference
+ * manual: the words an integration engineer writes at this console, weighted toward reading — a
+ * keyword or function missing here costs one suggestion, so the lists stay honest rather than
+ * exhaustive. Everything is lowercase, the casing the bench itself writes (the tree's
+ * `select * from`, the editor placeholder); completion re-cases it to follow the operator's hand.
+ */
+interface SqlDialect {
+  keywords: string[];
+  functions: SqlFunction[];
+}
+declare const SQL_DIALECTS: Record<SqlKind, SqlDialect>;
+/**
+ * One kind's function by name, however the operator cased it. Hover and signature help both ask.
+ */
+/**
+ * A signature's parameters as `[start, end)` offsets into the signature itself — offsets rather
+ * than substrings so a call that repeats a parameter name still marks the right one. Everything
+ * between the first `(` and the last `)`, split on the commas at that depth.
+ */
+declare function signatureParameters(signature: string): Array<[number, number]>;
+//#endregion
+//#region src/format.d.ts
+declare function createSqlFormat(kind: SqlKind): SqlAssist["format"];
+//#endregion
+//#region src/hover.d.ts
+declare function createSqlHover(kind: SqlKind, schema: SqlSchema, functions: SqlFunctions): SqlAssist["hover"];
+//#endregion
+//#region src/joins.d.ts
+/**
+ * What two tables' own naming says about how they join. A named-shape heuristic read
+ * against the catalog's key flags: the catalog says a column *is* a foreign key, never whom it
+ * points at — that is a non-goal — so the name is what is left to read. A miss costs one
+ * suggestion, never a statement, which is what lets the guessing be this plain.
+ */
+interface JoinGuess {
+  /**
+   * The condition as the operator would write it, aliases and all.
+   */
+  text: string;
+  /**
+   * Which reading found it, shown beside the suggestion so the operator can weigh it. A code —
+   * the consuming app owns the wording and the language.
+   */
+  why: JoinReason;
+}
+/**
+ * How a join guess was found: a column whose own name points into the other table's key
+ * (`order_id` → `orders.id`, `contract_code` → `contract.code`), or one name both tables spell
+ * where exactly one side keys it.
+ */
+type JoinReason = "named-foreign-key" | "shared-key";
+/**
+ * The equalities worth offering when `target` is joined onto tables the statement already reads.
+ * The named foreign key leads, in both directions; the plainer shared-key reading follows.
+ */
+declare function joinGuesses(kind: SqlKind, target: SqlSource, others: SqlSource[]): JoinGuess[];
+//#endregion
+//#region src/markers.d.ts
+/**
+ * Placeholder detection for what a run asks the operator for.
+ *
+ * This is **not** validation and must never become it: the engine-side scanner (the polyglot
+ * sidecar's `internal/scan`) is the authority on what binds, it is lexical and per-dialect, and a second
+ * implementation here would drift from it the first time a dialect gained a quoting form. All
+ * this decides is whether the run has values to ask for, which form the parameter dialog
+ * offers, and — where the statement is one the scanner refuses outright — the refusal, as a
+ * code, so the editor can say so before the round trip does.
+ *
+ * **Callers pass the statement's blanked form** (`Runnable.blanked`), never its raw text. A
+ * disagreement with the engine's scanner is not cosmetic in either direction — it answers both
+ * "statement binds no parameters, request provides 1" and "statement binds 2, request provides
+ * 1" with a hard refusal — and quoted prose is where a raw scan disagrees first: `select '?'`
+ * has no placeholder in it. Blanking is the reader's job because the reader already owns what is
+ * prose and what is SQL for this page, and it takes that decision under the data source's own
+ * lexical profile (`noise.ts`), mode for mode with the scanner — MySQL's `#` comments and
+ * backslash escapes, Postgres's `$tag$` bodies, Oracle's `q'…'`, every kind's quoted names — so
+ * what reaches this file is exactly the text the engine would mint markers from.
+ */
+/**
+ * The binding form a statement's markers suggest.
+ */
+type MarkerForm = "none" | "positional" | "named";
+/**
+ * A statement the engine's scanner refuses outright, mirrored here so the editor can say so
+ * without the round trip. A code, not a sentence — the consuming app owns the wording:
+ *
+ * - `"mixed-forms"` — the statement writes both `?` and `:name`; the scanner binds neither.
+ * - `"question-escape-unsupported"` — `??` on a kind whose native form is itself `?` (MySQL,
+ * 达梦): the escape has no rendering that survives, and neither dialect has a `?` operator to
+ * escape in the first place.
+ * - `"native-marker-collision"` — a marker hand-written in the kind's own bind form (`$1`,
+ * `:1`, `@p1`) beside a `?`/`:name` the scanner would mint: both would bind the same slot.
+ */
+type MarkerRefusal = "mixed-forms" | "question-escape-unsupported" | "native-marker-collision";
+/**
+ * What a statement appears to bind. `?` (but not `??`, the escape) suggests positional; `:name`
+ * (but not `::`, Postgres's cast) suggests named. A statement that writes both is counted
+ * whole — the named grid is the one that shows what it found — with the fault on record in
+ * `refusal`.
+ */
+interface StatementMarkers {
+  form: MarkerForm;
+  /**
+   * The distinct `:name` markers, in first-appearance order.
+   */
+  names: string[];
+  /**
+   * How many `?` markers appeared.
+   */
+  count: number;
+  /**
+   * The first refusal the engine's scanner would raise for this statement, in its own document
+   * order — or `null` where it binds cleanly. `names` and `count` still describe the whole
+   * text, so a dialog can show what it found beside the fault.
+   */
+  refusal: MarkerRefusal | null;
+}
+declare function statementMarkers(statement: string, kind: SqlKind): StatementMarkers;
+//#endregion
+//#region src/noise.d.ts
+/**
+ * A run the reader must not look inside. `sealed` says the closing delimiter was found: a caret
+ * right after a sealed run is back in the statement, while a caret at the end of an unterminated
+ * string or a line comment is still inside it.
+ */
+interface NoiseSpan {
+  start: number;
+  end: number;
+  sealed: boolean;
+  /**
+   * The run is a quoted *name* rather than a literal or a comment — text the tokenizer must take
+   * whole, but text it is looking for, so it survives in [BlankedSql.withNames].
+   */
+  name: boolean;
+}
+interface BlankedSql {
+  /**
+   * Every string and comment overwritten by spaces, character for character, with quoted names
+   * left standing — what the tokenizer reads, since names are what it is after.
+   */
+  withNames: string;
+  /**
+   * The same, with quoted names blanked as well: everything the engine's scanner skips whole. A
+   * placeholder scan reads this, and so does every structural read (`;` splitting, emptiness), so
+   * a `?` or a `;` inside a name means here exactly what it means to the engine — nothing.
+   */
+  blanked: string;
+  spans: NoiseSpan[];
+}
+/**
+ * The statement with its noise blanked out, char for char, so every offset survives — in the two
+ * renderings the reader needs (see [BlankedSql]). One pass, mirroring the sidecar scanner's own
+ * loop over its mutually exclusive lexical modes.
+ */
+declare function blankNoise(text: string, kind: SqlKind): BlankedSql;
+/**
+ * Whether the caret sits inside a string or a comment, where the bench has nothing to say. A
+ * quoted name is not one: it is a name the operator is writing, and the reader is about names.
+ */
+declare function insideNoise(spans: NoiseSpan[], cursor: number): boolean;
+//#endregion
+//#region src/origin.d.ts
+/**
+ * Where a statement's result columns verifiably come from: the tree's own single-table
+ * `select * from <table>` skeleton, with at most a filtering tail (`where` / `order` /
+ * `limit`-class). Joins, column lists, aliases and subqueries all answer `null` — for those the
+ * result grid shows bare column names, because a comment that might belong to a different
+ * column is worse than none.
+ */
+interface StatementOrigin {
+  /**
+   * Empty when the statement names the table unqualified — the connected schema-or-user.
+   */
+  schema: string;
+  table: string;
+}
+declare function statementOrigin(statement: string): StatementOrigin | null;
+//#endregion
+//#region src/params.d.ts
+/**
+ * What a bound parameter is, and what it becomes on the wire.
+ *
+ * The unified-placeholder endpoint takes scalars — text, number, boolean, null — and refuses
+ * arrays and objects, so those four are the whole of what a row can be. Declaring one is not the
+ * guessing an editing surface must never do: it is the decision a statement's author already
+ * makes when they write `[42]` rather than `["42"]`, and NULL cannot be entered at all without it.
+ *
+ * A refusal is a code, never a sentence: the host owns the wording (and the language) of what it
+ * tells the operator, so this module reports *what* could not bind and leaves *how to say it*
+ * to the surface that asked.
+ */
+/**
+ * The scalar set the endpoint accepts, as one type.
+ */
+type SqlScalar = string | number | boolean | null;
+type ParamType = "text" | "number" | "boolean" | "null";
+/**
+ * One row of a params grid. `text` is what the operator typed, kept exactly as typed — changing
+ * a row's type never rewrites it, because reinterpreting `0042` as `42` behind their back would
+ * bind a value they did not write.
+ */
+interface ParamValue {
+  readonly type: ParamType;
+  readonly text: string;
+}
+/**
+ * A row's opening state, and what an untouched row stays: text, so a statement run without ever
+ * opening the type column behaves exactly as it did before the column existed. Frozen, because
+ * it is also the *shared default* a missing row falls back to — one consumer writing through it
+ * would rewrite every untouched row on the page.
+ */
+declare const TEXT_PARAM: ParamValue;
+/**
+ * Whether a statement asks for values and the operator has entered none of them. This is the
+ * host's cue to ask rather than to send: binding a row of empty strings is never what was meant,
+ * and the rows live behind a dialog, so nothing on the page would have said otherwise.
+ *
+ * A statement that binds nothing is never untouched — there is nothing to touch.
+ */
+declare function untouched(rows: Record<string, ParamValue>): boolean;
+/**
+ * Why one row could not bind.
+ *
+ * - `empty` — a number row holding nothing.
+ * - `not-a-boolean` — a boolean row holding anything but `true` / `false`.
+ * - `not-a-number` — text a person would not call a number (`0x10`, `Infinity`, `1,000`).
+ * - `not-finite` — a number the double could not carry.
+ * - `unsafe-integer` — an integer past ±(2^53 − 1); binding it as text carries it faithfully.
+ */
+type BindRefusal = "empty" | "not-a-boolean" | "not-a-number" | "not-finite" | "unsafe-integer";
+/**
+ * What one row binds as, or why it cannot. A refusal names the row's own trouble; the caller adds
+ * which row it was.
+ */
+type Bound = {
+  ok: true;
+  value: SqlScalar;
+} | {
+  ok: false;
+  refusal: BindRefusal;
+};
+declare function boundValue(param: ParamValue): Bound;
+/**
+ * Every row bound, in the shape the marker form chose: positional values keep slot order, named
+ * values keep their keys. `undefined` is a statement that binds nothing.
+ *
+ * A row its type cannot carry stops the whole run and is named — sending the rest would run the
+ * statement against arguments the operator did not write. The refusal carries the row's form and
+ * key (`"2"` for the second positional slot, `"when"` for `:when`) so the host can point at it.
+ */
+type BoundParams = {
+  ok: true;
+  params: SqlScalar[] | Record<string, SqlScalar> | undefined;
+} | {
+  ok: false;
+  form: "positional" | "named";
+  key: string;
+  refusal: BindRefusal;
+};
+declare function boundParams(markers: StatementMarkers, rows: Record<string, ParamValue>): BoundParams;
+//#endregion
+//#region src/signature.d.ts
+/**
+ * The signature of the call the caret is inside, over the vocabulary this bench
+ * speaks — the curated floor and whatever the data source reports about itself, so the estate's
+ * own routines raise their parameters exactly as the vendor's do. The argument is counted at the
+ * caret's own paren depth, so a call nested in another's arguments still marks its own.
+ */
+declare function createSqlSignature(kind: SqlKind, functions: SqlFunctions): SqlAssist["signature"];
+//#endregion
+//#region src/spelling.d.ts
+/**
+ * One catalog name as the statement must spell it.
+ */
+declare function spellIdentifier(kind: SqlKind, name: string): string;
+/**
+ * A routine name as a call must spell it. Reservation does not delimit here: a reserved word in
+ * call position is legal in every kind — `json_table(...)`, `left(...)` are the vendors' own
+ * builtins — and delimiting one would un-call it; only a lexically irregular name needs the
+ * delimiter.
+ */
+declare function spellCallable(kind: SqlKind, name: string): string;
+/**
+ * The qualifier a generated expression writes before a source's columns: the alias exactly as
+ * the operator wrote it — re-spelling the unquoted form would be lossy — or, where the ref has
+ * no alias, the catalog's table name in the kind's own spelling.
+ */
+declare function spellQualifier(kind: SqlKind, source: {
+  aliasWritten: string;
+  table: {
+    name: string;
+  };
+}): string;
+/**
+ * A table's qualified name as the statement must spell it. Kinds whose catalog reports no schema
+ * (or whose objects sit in the session's own) get the bare name.
+ */
+declare function spellQualifiedName(kind: SqlKind, table: {
+  schema: string;
+  name: string;
+}): string;
+//#endregion
+export { type BenchFunction, type BindRefusal, type BlankedSql, type Bound, type BoundParams, type CallRead, type CatalogColumn, type CatalogFunction, type CatalogTable, type IdentifierRead, type JoinGuess, type JoinReason, type MarkerForm, type MarkerRefusal, type NoiseSpan, type ParamType, type ParamValue, type Runnable, SQL_DIALECTS, type SqlAssist, type SqlCatalog, type SqlCompletionCandidate, type SqlDialect, type SqlFunction, type SqlFunctions, type SqlHoverCard, type SqlKind, type SqlScalar, type SqlSchema, type SqlSignatureHelp, type SqlSource, type StatementContext, type StatementMarkers, type StatementOrigin, type StatementRead, TEXT_PARAM, type TableRef, blankNoise, boundParams, boundValue, createSqlAssist, createSqlCompletion, createSqlFormat, createSqlFunctions, createSqlHover, createSqlSchema, createSqlSignature, insideNoise, joinGuesses, qualifiedName, readCall, readIdentifier, readStatement, runnableStatement, signatureParameters, spellCallable, spellIdentifier, spellQualifiedName, spellQualifier, statementMarkers, statementOrigin, untouched };