@tlockney/cdp-kernel 0.10.0 → 0.11.0

package/runtime/display.mjs

@@ -4,19 +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");
 
@@ -243,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;
 }
@@ -377,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 };
@@ -409,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);
   }
@@ -492,6 +447,21 @@ 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));
 
   // jupyter.signal (#418): aborted when the kernel is interrupted, so cell
@@ -546,6 +516,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;