@tlockney/cdp-kernel 0.9.0 → 0.11.0

package/runtime/display.d.mts

@@ -1,7 +1,10 @@
 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 { CommApi, Widget, WidgetOptions };
+export type { Sql, SqlColumn, SqlFragment, SqlResult };
+export type { CommApi, Host, HostCallOptions, HostError, HostErrorCode, HostNotebooks, HostOptions, HostSelf, NotebookEntry, NotebookHit, NotebookSearch, Widget, WidgetOptions };
 
 /**
  * The symbol a class implements to choose how its instances appear. At
@@ -23,6 +26,33 @@ export interface DisplayHost {
   readFile: (path: string) => Uint8Array;
   send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void;
   input: (prompt: string, password: boolean) => string | null;
+  /** The run's parameters as JSON text, or `undefined` when there are none. */
+  params?: () => string | undefined;
+}
+
+/** The MIME type of a named result: `{ name, value }`. */
+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`. */
@@ -283,6 +313,174 @@ export interface JupyterNamespace {
    * @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
+   * counter="2nd Ave"`. They arrive as a JSON object in the kernel's
+   * `GANYMEDE_PARAMS` environment variable. Take defaults with
+   * destructuring, so the notebook also runs on its own.
+   *
+   * @throws {TypeError} `GANYMEDE_PARAMS` is set but isn't a JSON object.
+   * @availability Node, Deno, Bun, workerd and celld read the kernel's
+   *   environment; the browser target takes `params` from its options.
+   * @example
+   * ```ts
+   * const { counter = "Fremont", days = 30 } = jupyter.params as { counter?: string; days?: number };
+   * `${counter}, last ${days} days`;
+   * ```
+   * @see jupyter-api.md#parameters-and-named-results
+   */
+  readonly params: { readonly [name: string]: JsonValue };
+  /**
+   * Publish a value under a name, as an output that a run's caller reads
+   * by name instead of parsing outputs: `ganymede execute --results`, or
+   * another notebook. The output has the MIME type
+   * `application/vnd.ganymede.result+json` holding `{ name, value }`, and
+   * a `text/plain` line `name = value` for frontends that don't know the
+   * type. When a name is published twice, readers take the last one.
+   *
+   * @param name The result's name.
+   * @param value Any value `JSON.stringify` accepts; it is stored as JSON,
+   *   so a `Date` becomes its ISO string.
+   * @throws {TypeError} `name` is empty, or `value` isn't JSON (a
+   *   function, `undefined`, a `BigInt` or a cycle).
+   * @example
+   * ```ts
+   * const counts = [3120, 2890, 2410];
+   * jupyter.result("weekday_drop", (counts[2] - counts[0]) / counts[0]);
+   * jupyter.result("counts", counts);
+   * ```
+   * @see jupyter-api.md#parameters-and-named-results
+   */
+  result(name: string, value: unknown): 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;
+  /**
+   * The Ganymede server running this kernel, through its host API: read,
+   * search and (when granted) run other notebooks under its root. The
+   * server opens a comm to the kernel when it starts; this resolves to
+   * `null` when none answers, as under plain Jupyter.
+   *
+   * Each call returns a promise and takes `{ signal }`, by default
+   * `jupyter.signal`, so an interrupt cancels it. A failed call rejects
+   * with a `HostError` whose `code` says why: `denied` for a notebook or
+   * method this notebook isn't granted. Branch on `code`: `HostError`
+   * isn't a global, so `instanceof` isn't available.
+   *
+   * @param options `timeout`: how long to wait for a server, in ms.
+   * @throws {HostError} `cancelled` when an interrupt ends the wait.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * if (host) {
+   *   const { hits } = await host.notebooks.search({ query: "weekday drop", dir: "journal" });
+   *   hits.map((h) => `${h.path}: ${h.excerpt}`);
+   * }
+   * ```
+   * @see jupyter-api.md#other-notebooks-jupyter-host
+   */
+  host(options?: HostOptions): Promise<Host | null>;
 }
 
 export interface Jupyter {

package/runtime/display.mjs

@@ -4,18 +4,26 @@
 //
 // 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, tableBundle, tableSource } from "./table.mjs";
 
 export const $display = Symbol.for("Jupyter.display");
 
@@ -242,66 +250,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;
 }
@@ -343,8 +291,20 @@ function isMediaBundle(obj) {
  *   readFile: (path: string) => Uint8Array,
  *   send: (msgType: string, content: object, metadata: object, buffers: Uint8Array[]) => void,
  *   input: (prompt: string, password: boolean) => string | null,
+ *   params?: () => string | undefined,
  * }} host
  */
+/** The MIME type of a named result (cdp-kernel#456): `{ name, value }`. */
+export const RESULT_MIME = "application/vnd.ganymede.result+json";
+
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null) {
+    for (const v of Object.values(value)) deepFreeze(v);
+    Object.freeze(value);
+  }
+  return value;
+}
+
 export function createJupyter(host) {
   async function format(obj) {
     return await formatNow(obj);
@@ -364,7 +324,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 };
@@ -396,6 +357,13 @@ 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);
   }
@@ -439,6 +407,61 @@ export function createJupyter(host) {
     return answer === "" ? defaultValue : answer;
   }
 
+  // jupyter.params (cdp-kernel#456): the run's parameters, which the host
+  // (ganymede execute -p) passes as JSON in GANYMEDE_PARAMS. Parsed on first
+  // read, so a bad value fails the cell that reads it, not the kernel.
+  let params;
+  function readParams() {
+    if (params !== undefined) return params;
+    const text = host.params?.();
+    if (text === undefined || text === "") return (params = Object.freeze({}));
+    let value;
+    try {
+      value = JSON.parse(text);
+    } catch (err) {
+      throw new TypeError(`GANYMEDE_PARAMS is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      throw new TypeError("GANYMEDE_PARAMS must be a JSON object, such as {\"counter\": \"Fremont\"}");
+    }
+    return (params = deepFreeze(value));
+  }
+
+  // jupyter.result (cdp-kernel#456): a named value as an output of
+  // Ganymede's result type, which a run's caller reads without parsing
+  // outputs. JSON only, so every reader sees the same value.
+  function result(name, value) {
+    if (typeof name !== "string" || name === "") throw new TypeError("jupyter.result: name must be a non-empty string");
+    let text;
+    try {
+      text = JSON.stringify(value);
+    } catch (err) {
+      throw new TypeError(`jupyter.result: ${name} is not JSON: ${err instanceof Error ? err.message : err}`);
+    }
+    if (text === undefined) throw new TypeError(`jupyter.result: ${name} is not JSON (${typeof value})`);
+    const json = JSON.parse(text);
+    broadcast("display_data", {
+      data: { [RESULT_MIME]: { name, value: json }, "text/plain": `${name} = ${text}` },
+      metadata: {},
+      transient: {},
+    });
+  }
+
+  // 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));
 
   // jupyter.signal (#418): aborted when the kernel is interrupted, so cell
@@ -462,6 +485,11 @@ export function createJupyter(host) {
     for (const controller of handlers.keys()) controller.abort(reason);
     handlers.clear();
   }
+  // jupyter.host() (#461): Ganymede's host API. Registers its comm target
+  // now, so the comm the server opens at kernel start finds it. A call
+  // without a signal watches the jupyter.signal of whatever started it.
+  const hostApi = createHost(comms.api, () => current.signal);
+
   async function commDispatch(msgType, content, metadata, buffers, ownSignal = false) {
     // A handler during a cell shares the cell's signal, and is tracked
     // apart from it: it can outlive the cell.
@@ -484,6 +512,13 @@ export function createJupyter(host) {
       },
       broadcast,
       display,
+      get params() {
+        return readParams();
+      },
+      result,
+      table,
+      sql,
+      chart,
       format,
       md: taggedTemplate("text/markdown"),
       html: taggedTemplate("text/html"),
@@ -491,6 +526,7 @@ export function createJupyter(host) {
       image,
       $display,
       comm: comms.api,
+      host: hostApi.host,
       widget: createWidgetFactory(comms.api, $display),
     },
     broadcastResult,