@tlockney/cdp-kernel 0.10.0 → 0.12.0

package/runtime/display.d.mts

@@ -1,7 +1,9 @@
 import type { CommApi, Comms } from "./comm.d.mts";
 import type { Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch } from "./host.d.mts";
 import type { Widget, WidgetOptions } from "./widget.d.mts";
+import type { Sql, SqlColumn, SqlFragment, SqlResult } from "./sql.d.mts";
 
+export type { Sql, SqlColumn, SqlFragment, SqlResult };
 export type { CommApi, Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch, Widget, WidgetOptions };
 
 /**
@@ -34,6 +36,25 @@ export const RESULT_MIME: "application/vnd.ganymede.result+json";
 /** A JSON value, as `JSON.parse` returns it. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 
+/** Options for `jupyter.table`. */
+export interface TableOptions {
+  /** Rows to embed: default 1,000, at most 10,000, and never past 1 MB of JSON. */
+  limit?: number;
+  /** The columns to show, in order. Names an array of arrays' columns. */
+  columns?: string[];
+  /** A caption for the table. */
+  title?: string;
+}
+
+/** Options for `jupyter.chart` with a Vega-Lite or Vega spec. */
+export interface ChartOptions {
+  /**
+   * Also keep the spec under its Vega MIME type, for a frontend that
+   * draws Vega itself. Default `false`: the SVG and a text summary only.
+   */
+  spec?: boolean;
+}
+
 /** Options for `jupyter.display`. */
 export interface DisplayOptions {
   /**
@@ -62,33 +83,6 @@ export interface Displayable {
  * as `Deno.jupyter` in `deno jupyter`.
  */
 export interface JupyterNamespace {
-  /**
-   * Send a raw Jupyter message on the kernel's output channel (IOPub), as a
-   * reply to the running cell. The other helpers are built on it. It does
-   * not check the message: a wrong field is ignored or mishandled by the
-   * frontend.
-   *
-   * @param msgType An IOPub message type, such as `"clear_output"` or
-   *   `"display_data"`.
-   * @param content The message content, as the messaging spec defines it
-   *   for `msgType`.
-   * @param options `metadata` for the message, and binary `buffers`.
-   * @example
-   * ```ts
-   * // Count down in place: clear_output with wait avoids a flicker.
-   * for (const n of [3, 2, 1]) {
-   *   jupyter.broadcast("clear_output", { wait: true });
-   *   await jupyter.display(jupyter.md`Launching in **${n}**…`);
-   *   await new Promise((resolve) => setTimeout(resolve, 1000));
-   * }
-   * ```
-   * @see jupyter-api.md#raw-messages-with-broadcast
-   */
-  broadcast(
-    msgType: string,
-    content: object,
-    options?: { metadata?: object; buffers?: Uint8Array[] },
-  ): void;
   /**
    * Show a value now, in the middle of a cell, or replace one shown
    * earlier. The value can be anything a cell could end with: a template
@@ -121,22 +115,6 @@ export interface JupyterNamespace {
    * @see jupyter-api.md#showing-output-with-display
    */
   display(obj: unknown, options?: DisplayOptions): Promise<void>;
-  /**
-   * The MIME bundle that displaying a value would send, without showing
-   * anything. For plain values `text/plain` holds terminal color codes,
-   * as the notebook shows them.
-   *
-   * @param obj The value to format.
-   * @returns The bundle, for example `{ "text/plain": "\x1b[33m42\x1b[39m" }`
-   *   for `42`.
-   * @example
-   * ```ts
-   * const bundle = await jupyter.format(jupyter.md`# Weekly report`);
-   * bundle["text/markdown"]; // "# Weekly report"
-   * ```
-   * @see jupyter-api.md#getting-a-bundle-with-format
-   */
-  format(obj: unknown): Promise<MediaBundle>;
   /**
    * A tagged template that renders as Markdown. Interpolated values are
    * inserted as is, without escaping.
@@ -228,6 +206,175 @@ export interface JupyterNamespace {
    * @see jupyter-api.md#custom-display-for-your-own-classes
    */
   $display: typeof $display;
+  /**
+   * The MIME bundle that displaying a value would send, without showing
+   * anything. For plain values `text/plain` holds terminal color codes,
+   * as the notebook shows them.
+   *
+   * @param obj The value to format.
+   * @returns The bundle, for example `{ "text/plain": "\x1b[33m42\x1b[39m" }`
+   *   for `42`.
+   * @example
+   * ```ts
+   * const bundle = await jupyter.format(jupyter.md`# Weekly report`);
+   * bundle["text/markdown"]; // "# Weekly report"
+   * ```
+   * @see jupyter-api.md#getting-a-bundle-with-format
+   */
+  format(obj: unknown): Promise<MediaBundle>;
+  /**
+   * Send a raw Jupyter message on the kernel's output channel (IOPub), as a
+   * reply to the running cell. The other helpers are built on it. It does
+   * not check the message: a wrong field is ignored or mishandled by the
+   * frontend.
+   *
+   * @param msgType An IOPub message type, such as `"clear_output"` or
+   *   `"display_data"`.
+   * @param content The message content, as the messaging spec defines it
+   *   for `msgType`.
+   * @param options `metadata` for the message, and binary `buffers`.
+   * @example
+   * ```ts
+   * // Count down in place: clear_output with wait avoids a flicker.
+   * for (const n of [3, 2, 1]) {
+   *   jupyter.broadcast("clear_output", { wait: true });
+   *   await jupyter.display(jupyter.md`Launching in **${n}**…`);
+   *   await new Promise((resolve) => setTimeout(resolve, 1000));
+   * }
+   * ```
+   * @see jupyter-api.md#raw-messages-with-broadcast
+   */
+  broadcast(
+    msgType: string,
+    content: object,
+    options?: { metadata?: object; buffers?: Uint8Array[] },
+  ): void;
+  /**
+   * Show rows and columns as a table. The output has Ganymede's table
+   * type, `application/vnd.dataresource+json` (Table Schema fields, up to
+   * `limit` rows as JSON, and the total row count), which the Ganymede
+   * apps show with sorting and paging; a plain HTML table of the first
+   * and last rows for JupyterLab and VS Code; and a text summary of each
+   * column's type and range for agents and consoles.
+   *
+   * An Arrow table, a Polars DataFrame or a DuckDB result also shows this
+   * way when it is a cell's value; pass one here to set `limit`,
+   * `columns` or `title`.
+   *
+   * @param value An array of row objects, an array of arrays (name them
+   *   with `columns`), an Arrow table (apache-arrow, duckdb-wasm), a
+   *   Polars DataFrame, or a `@duckdb/node-api` result.
+   * @param options `limit`: rows to embed, default 1,000, at most 10,000,
+   *   and never more than 1 MB of JSON. `columns`: which columns, in order.
+   *   `title`: a caption.
+   * @throws {TypeError} `value` isn't one of those, or `limit` isn't a
+   *   whole number.
+   * @example
+   * ```ts
+   * const moons = [
+   *   { moon: "Io", radius_km: 1821.6, discovered: new Date("1610-01-08") },
+   *   { moon: "Europa", radius_km: 1560.8, discovered: new Date("1610-01-08") },
+   *   { moon: "Ganymede", radius_km: 2634.1, discovered: new Date("1610-01-07") },
+   * ];
+   * jupyter.table(moons, { title: "Galilean moons" });
+   * ```
+   * @see jupyter-api.md#tables
+   */
+  table(value: unknown, options?: TableOptions): Displayable;
+  /**
+   * Run SQL on an in-memory [DuckDB](https://duckdb.org) database, as a
+   * tagged template: each `${value}` becomes a bound parameter, never
+   * query text, so values can't change the query. Resolves to a
+   * `SqlResult`, which shows as a table and has `columns` and `rows`.
+   *
+   * The database opens on the first query and lasts until the kernel
+   * restarts or `jupyter.sql.close()`. DuckDB reads CSV, Parquet and JSON
+   * files by path or URL; `jupyter.sql.load` makes a table from rows the
+   * notebook already has. An interrupt stops a running query.
+   *
+   * @throws {TypeError} Called as a function rather than a tag.
+   * @availability Node, Deno and Bun use `@duckdb/node-api`; the browser
+   *   target (the Ganymede apps) uses duckdb-wasm from a CDN. Not on
+   *   workerd or celld.
+   * @example
+   * ```ts
+   * const min = 2000;
+   * await jupyter.sql`
+   *   select moon, radius_km
+   *   from (values ('Io', 1821.6), ('Ganymede', 2634.1), ('Callisto', 2410.3)) as m(moon, radius_km)
+   *   where radius_km > ${min}
+   *   order by radius_km desc`;
+   * ```
+   * @see jupyter-api.md#sql-with-duckdb
+   */
+  readonly sql: Sql;
+  /**
+   * Draw a chart in the kernel as one SVG, with its title and legend
+   * inside, plus a text summary for readers that can't see it. The SVG
+   * shows the same in the Ganymede apps, JupyterLab, VS Code and a
+   * published page. Text and axes are drawn in `currentColor`: the
+   * notebook's text color in the Ganymede apps, black in JupyterLab.
+   *
+   * Pass a [Vega-Lite](https://vega.github.io/vega-lite/) or Vega spec
+   * (or a vega-lite-api chart), or the
+   * [Observable Plot](https://observablehq.com/plot/) module and the
+   * options you would give `Plot.plot`. Plot's `title`, `subtitle`,
+   * `caption` and the color legend (`legend: true`, `"swatches"` or
+   * `"ramp"`) are drawn into the SVG; other scales' legends are left
+   * out. An SVG element shows as it is.
+   *
+   * vega and vega-lite (version 6), and linkedom for Plot where there is
+   * no DOM, load through the cell's import on first use. A chart past
+   * 2 MB of SVG logs a warning: aggregate or sample first.
+   *
+   * @param chart A Vega-Lite or Vega spec, the Plot module, or an SVG
+   *   element.
+   * @param options With a spec, `ChartOptions`; with Plot, Plot's options.
+   * @throws {TypeError} `chart` is none of those, or Plot comes without
+   *   options.
+   * @example
+   * ```ts
+   * jupyter.chart({
+   *   title: "Galilean moons",
+   *   data: { values: [
+   *     { moon: "Io", radius_km: 1821.6 },
+   *     { moon: "Europa", radius_km: 1560.8 },
+   *     { moon: "Ganymede", radius_km: 2634.1 },
+   *     { moon: "Callisto", radius_km: 2410.3 },
+   *   ] },
+   *   mark: "bar",
+   *   encoding: {
+   *     x: { field: "moon", sort: "-y" },
+   *     y: { field: "radius_km", type: "quantitative" },
+   *   },
+   * });
+   * ```
+   * @see jupyter-api.md#charts
+   */
+  chart(chart: object, options?: ChartOptions | Record<string, unknown>): Displayable;
+  /**
+   * An `AbortSignal` that an interrupt aborts, so code waiting on something
+   * only it can end can stop and clean up. Each cell gets its own, as does
+   * a comm handler that starts while no cell runs. Read it once when the
+   * work starts: a later read gets the signal of whatever started last.
+   * The abort reason is a `DOMException` named `AbortError`.
+   *
+   * @example
+   * ```ts
+   * const response = await fetch("https://example.com/large.csv", { signal: jupyter.signal });
+   * ```
+   * @example
+   * ```ts
+   * const signal = jupyter.signal;
+   * const ask = jupyter.comm.open("my.app", { question: "ready?" });
+   * const answer = await new Promise((resolve, reject) => {
+   *   ask.onMsg((m) => resolve(m.data));
+   *   signal.addEventListener("abort", () => { ask.close(); reject(signal.reason); }, { once: true });
+   * });
+   * ```
+   * @see jupyter-api.md#stopping-on-interrupt-jupyter-signal
+   */
+  readonly signal: AbortSignal;
   /**
    * Jupyter comms: message channels to the frontend outside cell
    * execution. Its methods are in the widgets and comms reference.
@@ -236,13 +383,14 @@ export interface JupyterNamespace {
    */
   comm: CommApi;
   /**
-   * Create an anywidget-compatible widget model. Display it (or end the
+   * Create an [anywidget](https://anywidget.dev)-compatible [widget
+   * model](widgets-reference.md#widget-model). Display it (or end the
    * cell with it) to show a view.
    *
    * @param options The view module, its CSS, and the initial state.
    * @returns The model, synced with every view of it.
    * @throws {TypeError} `options.esm` is not a string.
-   * @availability The frontend needs the anywidget extension.
+   * @availability The frontend needs the [anywidget](https://anywidget.dev) extension.
    * @example
    * ```ts
    * const counter = jupyter.widget({
@@ -269,29 +417,6 @@ export interface JupyterNamespace {
    * @see widgets.md#a-first-widget-a-counter
    */
   widget(options: WidgetOptions): Widget;
-  /**
-   * An `AbortSignal` that an interrupt aborts, so code waiting on something
-   * only it can end can stop and clean up. Each cell gets its own, as does
-   * a comm handler that starts while no cell runs. Read it once when the
-   * work starts: a later read gets the signal of whatever started last.
-   * The abort reason is a `DOMException` named `AbortError`.
-   *
-   * @example
-   * ```ts
-   * const response = await fetch("https://example.com/large.csv", { signal: jupyter.signal });
-   * ```
-   * @example
-   * ```ts
-   * const signal = jupyter.signal;
-   * const ask = jupyter.comm.open("my.app", { question: "ready?" });
-   * const answer = await new Promise((resolve, reject) => {
-   *   ask.onMsg((m) => resolve(m.data));
-   *   signal.addEventListener("abort", () => { ask.close(); reject(signal.reason); }, { once: true });
-   * });
-   * ```
-   * @see jupyter-api.md#stopping-on-interrupt-jupyter-signal
-   */
-  readonly signal: AbortSignal;
   /**
    * The parameters of this run: a frozen object, empty unless whoever
    * started the kernel passed some, such as `ganymede execute -p

package/runtime/display.mjs

@@ -4,19 +4,27 @@
 //
 // Ported from Deno's cli/js/40_jupyter.js (v2.9.6), which is
 // Copyright 2018-2026 the Deno authors, MIT license. The formatting rules
-// (display symbol, canvas, Vega, Polars-style DataFrames, JPEG/PNG bytes,
-// HTML/SVG elements) are unchanged; the Deno internals it used are injected:
+// (display symbol, canvas, Vega, JPEG/PNG bytes, HTML/SVG elements) are
+// unchanged; Polars-style DataFrames show through table.mjs instead (#475),
+// as do Arrow tables and DuckDB results. The Deno internals it used are
+// injected:
 //   Deno[Deno.internal].inspectArgs -> host.inspect
 //   op_base64_encode_from_buffer    -> host.base64
 //   Deno.readFileSync               -> host.readFile
 //   op_jupyter_broadcast            -> host.send
 // WebGPU texture/buffer display depends on Deno's wgpu bindings and is
-// omitted. Comms and widgets (jupyter.comm, jupyter.widget) are additions
-// Deno doesn't have; see comm.mjs and widget.mjs.
+// omitted. Comms, widgets, tables, SQL and charts (jupyter.comm,
+// jupyter.widget, jupyter.table, jupyter.sql, jupyter.chart) are additions
+// Deno doesn't have; see comm.mjs, widget.mjs, table.mjs, sql.mjs and
+// chart.mjs.
 
 import { createComms } from "./comm.mjs";
 import { createHost } from "./host.mjs";
 import { createWidgetFactory } from "./widget.mjs";
+import { createSql } from "./sql.mjs";
+import { createChart } from "./chart.mjs";
+import { isTableLike, pageTable, tableBundle, tableSource } from "./table.mjs";
+import { createTablePager } from "./table-paging.mjs";
 
 export const $display = Symbol.for("Jupyter.display");
 
@@ -243,66 +251,6 @@ function summarizeChart(spec) {
   }
 }
 
-function isDataFrameLike(obj) {
-  return obj !== null && typeof obj === "object" &&
-    obj.schema !== undefined && typeof obj.schema === "object" &&
-    typeof obj.head === "function" && typeof obj.toRecords === "function";
-}
-
-function mapPolarsTypeToJSONSchema(colType) {
-  const typeMapping = {
-    Null: "null",
-    Bool: "boolean",
-    Int8: "integer",
-    Int16: "integer",
-    Int32: "integer",
-    Int64: "integer",
-    UInt8: "integer",
-    UInt16: "integer",
-    UInt32: "integer",
-    UInt64: "integer",
-    Float32: "number",
-    Float64: "number",
-    Date: "string",
-    Datetime: "string",
-    Utf8: "string",
-    Categorical: "string",
-    List: "array",
-    Struct: "object",
-  };
-  // Polars DataTypes only expose their name through toJSON().
-  const dataType = typeof colType?.toJSON === "function" ? colType.toJSON()["DataType"] : undefined;
-  return typeMapping[dataType] || "string";
-}
-
-function extractDataFrame(df) {
-  const fields = [];
-  for (const [name, colType] of Object.entries(df.schema)) {
-    fields.push({ name, type: mapPolarsTypeToJSONSchema(colType) });
-  }
-  const data = df.head(50).toRecords();
-  let html = "<table><thead><tr>";
-  for (const field of fields) html += `<th>${escapeHTML(String(field.name))}</th>`;
-  html += "</tr></thead><tbody>";
-  for (const row of df.head(10).toRecords()) {
-    html += "<tr>";
-    for (const field of fields) html += `<td>${escapeHTML(String(row[field.name]))}</td>`;
-    html += "</tr>";
-  }
-  html += "</tbody></table>";
-  // Polars has `height`; the row count is left out when there isn't one.
-  const size = [];
-  if (Number.isInteger(df.height)) size.push(`${df.height} ${df.height === 1 ? "row" : "rows"}`);
-  size.push(`${fields.length} ${fields.length === 1 ? "column" : "columns"}`);
-  const columns = fields.slice(0, 20).map((field) => `${clip(String(field.name), 40)} (${field.type})`);
-  if (fields.length > 20) columns.push(`… ${fields.length - 20} more`);
-  return {
-    "application/vnd.dataresource+json": { data, schema: { fields } },
-    "text/html": html,
-    "text/plain": `DataFrame (${size.join(", ")})${columns.length ? `: ${columns.join(", ")}` : ""}`,
-  };
-}
-
 function isCanvasLike(obj) {
   return obj !== null && typeof obj === "object" && "toDataURL" in obj;
 }
@@ -377,7 +325,8 @@ export function createJupyter(host) {
       const vega = extractVega(obj);
       if (vega) return vega;
     }
-    if (isDataFrameLike(obj)) return extractDataFrame(obj);
+    // Arrow tables, Polars DataFrames and DuckDB results (#475).
+    if (isTableLike(obj)) return tableBundle(tableSource(obj));
     if (isJpg(obj)) return { "image/jpeg": host.base64(obj) };
     if (isPng(obj)) return { "image/png": host.base64(obj) };
     if (isSVGElementLike(obj)) return { "image/svg+xml": obj.outerHTML };
@@ -409,14 +358,25 @@ export function createJupyter(host) {
     );
   }
 
+  // jupyter.table (#475): rows and columns as Ganymede's table output,
+  // built now so a bad value fails the call, not the display.
+  function table(value, options = {}) {
+    const bundle = tableBundle(tableSource(value, options), options);
+    return { [$display]: () => bundle };
+  }
+
   function broadcast(msgType, content, { metadata = {}, buffers = [] } = {}) {
     host.send(msgType, content, metadata, buffers);
   }
 
+  // Set below, once the comms are: a table cut by the cap is kept for
+  // paging when it is sent as an output, not when it is formatted.
+  let pager;
+
   async function display(obj, options = { raw: false, update: false }) {
     const bundle = options.raw && isMediaBundle(obj) ? obj : await format(obj);
     broadcast(options.update ? "update_display_data" : "display_data", {
-      data: bundle,
+      data: pageTable(bundle, pager, options.display_id),
       metadata: {},
       transient: options.display_id ? { display_id: options.display_id } : {},
     });
@@ -427,7 +387,7 @@ export function createJupyter(host) {
     try {
       broadcast("execute_result", {
         execution_count: executionCount,
-        data: await format(result),
+        data: pageTable(await format(result), pager),
         metadata: {},
         // nbclient crashes on a null `transient`; Deno learned this too.
         transient: {},
@@ -492,7 +452,24 @@ export function createJupyter(host) {
     });
   }
 
+  // The cell's own import, so npm: resolution and the browser target's CDN
+  // apply to the packages jupyter.sql and jupyter.chart load.
+  const cellImport = (what) => (specifier) => {
+    const load = globalThis.__cdpk?.import;
+    if (typeof load !== "function") return Promise.reject(new Error(`${what}: no module loader in this runtime`));
+    return load(specifier);
+  };
+
+  // jupyter.sql (#477): DuckDB, loaded on the first query; an interrupt
+  // (jupyter.signal) interrupts the query.
+  const sql = createSql({ importModule: cellImport("jupyter.sql"), signal: () => current.signal });
+
+  // jupyter.chart (#479): vega, vega-lite or linkedom, loaded on first use.
+  const chart = createChart({ importModule: cellImport("jupyter.chart"), summarizeSpec: summarizeChart });
+
   const comms = createComms((msgType, content, metadata, buffers) => host.send(msgType, content, metadata, buffers));
+  // Tables cut by the cap page through the kernel over a comm (ganymede#747).
+  pager = createTablePager(comms.api);
 
   // jupyter.signal (#418): aborted when the kernel is interrupted, so cell
   // code can stop waiting on what the interrupt can't reach, such as a comm
@@ -546,6 +523,9 @@ export function createJupyter(host) {
         return readParams();
       },
       result,
+      table,
+      sql,
+      chart,
       format,
       md: taggedTemplate("text/markdown"),
       html: taggedTemplate("text/html"),

package/runtime/host.d.mts

@@ -103,7 +103,7 @@ export interface Host {
   call(method: string, params?: HostParams, options?: HostCallOptions): Promise<any>;
   /** Other notebooks under the server's root, as far as this notebook's grant reaches. */
   readonly notebooks: HostNotebooks;
-  /** This notebook's own cells. Not on a server yet: they reject `unavailable`. */
+  /** This notebook's own cells. Ganymede 0.8.0 or later; an older server rejects `unavailable`. */
   readonly self: HostSelf;
 }
 
@@ -160,7 +160,8 @@ export interface HostNotebooks {
     options?: HostCallOptions,
   ): Promise<NotebookSearch>;
   /**
-   * A notebook's named results. Not on a server yet: rejects `unavailable`.
+   * A notebook's named results. Ganymede 0.8.0 or later; an older server
+   * rejects `unavailable`.
    *
    * @param params `path`: the notebook.
    * @param options `signal` cancels the call.
@@ -172,8 +173,9 @@ export interface HostNotebooks {
    */
   results(params: { path: string }, options?: HostCallOptions): Promise<any>;
   /**
-   * Run a notebook with parameters and return its results. Not on a
-   * server yet: rejects `unavailable`.
+   * Run a notebook with parameters and return its results, in a fresh
+   * kernel, when this notebook's grant names it. Ganymede 0.8.0 or later;
+   * an older server rejects `unavailable`.
    *
    * @param params `path`: the notebook; `params`: its parameters.
    * @param options `signal` cancels the run.
@@ -186,7 +188,7 @@ export interface HostNotebooks {
   run(params: { path: string; params?: HostParams }, options?: HostCallOptions): Promise<any>;
 }
 
-/** `host.self`: this notebook's own cells. Not on a server yet: each rejects `unavailable`. */
+/** `host.self`: this notebook's own cells. Ganymede 0.8.0 or later; an older server rejects each with `unavailable`. */
 export interface HostSelf {
   /**
    * Add a cell to this notebook.

package/runtime/sql.d.mts

@@ -0,0 +1,147 @@
+import type { Displayable } from "./display.d.mts";
+
+export const NODE_API: string;
+export const DUCKDB_WASM: string;
+
+/** One column of a query's result. */
+export interface SqlColumn {
+  name: string;
+  /** DuckDB's type name (`BIGINT`, `VARCHAR`, `DATE`), or Arrow's in the browser. */
+  type: string;
+}
+
+/**
+ * A query's result. It shows as a table (the same output as
+ * `jupyter.table`) when it is a cell's value or passed to
+ * `jupyter.display`.
+ */
+export interface SqlResult extends Displayable {
+  /** The result's columns, in order. */
+  readonly columns: SqlColumn[];
+  /**
+   * The rows as plain objects keyed by column name. Integers that fit a
+   * JavaScript number are numbers, larger ones `bigint`; `DATE` and
+   * `TIMESTAMP` values are `Date`s.
+   */
+  readonly rows: Record<string, unknown>[];
+}
+
+export const SqlResult: new (columns: SqlColumn[], rows: Record<string, unknown>[]) => SqlResult & {
+  toTableSource(names?: string[]): import("./table.d.mts").TableSource;
+};
+
+/** Text that `jupyter.sql` puts into the query as written: see `sql.raw`. */
+export interface SqlFragment {
+  readonly __sqlRaw: never;
+}
+
+/**
+ * `jupyter.sql`: a tagged template that runs SQL on the kernel's DuckDB.
+ * Each `${value}` becomes a bound parameter.
+ */
+export interface Sql {
+  /**
+   * Run the query, with each `${value}` as a bound parameter.
+   *
+   * @example
+   * ```ts
+   * await jupyter.sql`select ${"Ganymede"} as moon`;
+   * ```
+   */
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<SqlResult>;
+  /**
+   * Run SQL from a string, with values for its `?` parameters. For a
+   * query built at run time; prefer the tag otherwise.
+   *
+   * @param text The SQL.
+   * @param params Values for its `?` placeholders, in order.
+   * @example
+   * ```ts
+   * const op = ">";
+   * await jupyter.sql.query(`select 2 ${op} ? as answer`, [1]);
+   * ```
+   */
+  query(text: string, params?: unknown[]): Promise<SqlResult>;
+  /**
+   * Text the tag puts into the query as written, rather than as a
+   * parameter: a table name or a file path built in code. Never pass it
+   * text from outside the notebook.
+   *
+   * @param text SQL text.
+   * @example
+   * ```ts
+   * const table = "moons";
+   * await jupyter.sql`select count(*) as n from ${jupyter.sql.raw(table)}`;
+   * ```
+   */
+  raw(text: string): SqlFragment;
+  /**
+   * Create (or replace) table `name` from a file DuckDB can read (CSV,
+   * Parquet or JSON, by path or URL), from an array of row objects, or
+   * from an Arrow table or Polars DataFrame. Rows go in as one JSON
+   * parameter, typed from the values: integers as `BIGINT`, numbers as
+   * `DOUBLE`, `Date`s as `TIMESTAMP`, arrays and objects as `JSON`.
+   *
+   * @param name The table's name.
+   * @param source A path or URL, rows, an Arrow table or a DataFrame.
+   * @throws {TypeError} `name` is empty, or the rows have no columns.
+   * @example
+   * ```ts
+   * await jupyter.sql.load("moons", [
+   *   { moon: "Io", radius_km: 1821.6 },
+   *   { moon: "Ganymede", radius_km: 2634.1 },
+   * ]);
+   * await jupyter.sql`select moon from moons order by radius_km desc`;
+   * ```
+   */
+  load(name: string, source: unknown): Promise<void>;
+  /**
+   * Close the database and free its memory. The next query opens a new,
+   * empty one.
+   *
+   * @example
+   * ```ts
+   * await jupyter.sql.close();
+   * ```
+   */
+  close(): Promise<void>;
+  /**
+   * The DuckDB connection itself, for what the tag doesn't cover: a
+   * `@duckdb/node-api` `DuckDBConnection` on Node, Deno and Bun, a
+   * duckdb-wasm `AsyncDuckDBConnection` in the browser.
+   *
+   * @example
+   * ```ts
+   * const conn = await jupyter.sql.connection();
+   * ```
+   */
+  connection(): Promise<unknown>;
+}
+
+export function decimalValue(words: ArrayLike<number> | number | bigint, scale: number): number;
+export function toParam(value: unknown): unknown;
+/** A parameter as a SQL literal. */
+export function sqlLiteral(value: unknown): string;
+/** The query with each `?` placeholder (outside strings, quoted names and comments) replaced by its parameter as a literal. */
+export function inlineParams(text: string, params: unknown[]): string;
+/** A DuckDB TIME as `HH:MM:SS[.fraction]`, from its count in the declared type's unit (microseconds by default). */
+export function timeText(value: number | bigint, declared?: string): string;
+/** Column names made unique: a repeated `id` becomes `id_1`, `id_2`, and so on. */
+export function uniqueNames(names: readonly string[]): string[];
+export function compose(strings: readonly string[], values: unknown[]): { text: string; params: unknown[] };
+export function quoteIdent(name: string): string;
+export function quoteString(text: string): string;
+export function rowsAsJson(source: unknown): { structure: string | null; json: string };
+
+export interface SqlEngine {
+  query: (text: string, params: unknown[]) => Promise<SqlResult>;
+  interrupt?: () => void;
+  close: () => Promise<void>;
+  connection: unknown;
+}
+
+export function createSql(options: {
+  importModule: (specifier: string) => Promise<any>;
+  signal?: () => AbortSignal | undefined;
+  openEngine?: () => Promise<SqlEngine>;
+}): Sql;