@tlockney/cdp-kernel 0.9.0 → 0.11.0

package/runtime/host.d.mts

@@ -0,0 +1,248 @@
+import type { CommApi } from "./comm.d.mts";
+
+/** The target name of the comm a Ganymede server opens to the kernel. */
+export const HOST_TARGET: "ganymede.host.v1";
+
+/** Why a host call failed. The codes are ganymede-device's. */
+export type HostErrorCode = "unavailable" | "denied" | "cancelled" | "timeout" | "failed" | "disconnected";
+
+/**
+ * A failed host call. Branch on `code` (or `name === "HostError"`): the
+ * class isn't a global, so `instanceof` isn't available in a cell.
+ *
+ * A failed host call: `unavailable` (no such method), `denied` (not
+ * granted to this notebook), `cancelled` (its signal aborted), `timeout`,
+ * `failed` (the server couldn't do it), `disconnected` (the host comm
+ * closed, such as on a server restart).
+ */
+export class HostError extends Error {
+  readonly code: HostErrorCode;
+  constructor(code: HostErrorCode, message: string);
+  static from(err: unknown): HostError;
+}
+
+/** Options for a host call. */
+export interface HostCallOptions {
+  /** Aborting it cancels the call. Default `jupyter.signal`. */
+  signal?: AbortSignal;
+}
+
+/** Parameters and results are JSON; the host API's design note lists each method's. */
+export type HostParams = { [key: string]: unknown };
+
+/** An entry `notebooks.list` returns: a folder, or a notebook this notebook may read. */
+export interface NotebookEntry {
+  path: string;
+  type: "directory" | "notebook";
+  /** Its first heading, for a notebook that has one. */
+  title?: string | null;
+  /** Its kernelspec name. */
+  kernel?: string | null;
+  /** ISO 8601. */
+  modified: string;
+}
+
+/** A cell `notebooks.search` matched. */
+export interface NotebookHit {
+  path: string;
+  title: string | null;
+  /** The cell's position in the notebook. */
+  index: number;
+  id: string | null;
+  cell_type: "code" | "markdown" | "raw";
+  /** Where the first word matched. */
+  in: "source" | "output";
+  excerpt: string;
+}
+
+/** What `notebooks.search` returns. */
+export interface NotebookSearch {
+  hits: NotebookHit[];
+  /** Matching cells, beyond `limit` too. */
+  total: number;
+  truncated: boolean;
+}
+
+/** The Ganymede server that runs this kernel, from `jupyter.host()`. */
+export interface Host {
+  /** The host API's protocol version. */
+  readonly protocol: number;
+  /** The server's version. */
+  readonly server: string;
+  /** This notebook's path under the server's root, or null when the kernel has none. */
+  readonly notebook: string | null;
+  /** The methods this notebook may call. */
+  readonly methods: readonly string[];
+  /**
+   * Whether this notebook may call `method`.
+   *
+   * @param method The method, such as `"notebooks.run"`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * host?.has("notebooks.run"); // false unless the notebook is granted runs
+   * ```
+   */
+  has(method: string): boolean;
+  /**
+   * Call a method by name. The shortcuts under `notebooks` and `self` call
+   * this.
+   *
+   * @param method The method, such as `"notebooks.read"`.
+   * @param params Its parameters, a JSON object. Default `{}`.
+   * @param options `signal` cancels the call.
+   * @returns What the server answered, as JSON.
+   * @throws {HostError} The call failed; `code` says why.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook } = await host!.call("notebooks.read", { path: "journal/a.ipynb" });
+   * notebook.cells.length;
+   * ```
+   */
+  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. Ganymede 0.8.0 or later; an older server rejects `unavailable`. */
+  readonly self: HostSelf;
+}
+
+/** `host.notebooks`: other notebooks under the server's root. */
+export interface HostNotebooks {
+  /**
+   * The notebooks this notebook may read, and the folders, in a folder.
+   *
+   * @param params `dir`: the folder, relative to the root. Default the root.
+   * @param options `signal` cancels the call.
+   * @returns One entry per notebook or folder.
+   * @throws {HostError} `denied` when the grant doesn't reach `dir`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const entries = await host!.notebooks.list({ dir: "journal" });
+   * entries.filter((e) => e.type === "notebook").map((e) => e.title ?? e.path);
+   * ```
+   */
+  list(params?: { dir?: string }, options?: HostCallOptions): Promise<NotebookEntry[]>;
+  /**
+   * A notebook as nbformat JSON (from its open document when someone has
+   * it open), and each cell's source hash by cell id.
+   *
+   * @param params `path`: the notebook, relative to the root.
+   * @param options `signal` cancels the call.
+   * @returns The notebook and its hashes.
+   * @throws {HostError} `denied` when the grant doesn't reach `path`.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook } = await host!.notebooks.read({ path: "journal/a.ipynb" });
+   * notebook.cells.length;
+   * ```
+   */
+  read(params: { path: string }, options?: HostCallOptions): Promise<{ notebook: any; hashes: { [cellId: string]: string } }>;
+  /**
+   * Cells that hold every word of `query`, in the notebooks this notebook
+   * may read: in sources, and in outputs too with `outputs: true`.
+   *
+   * @param params `query`, and optionally `dir`, `outputs`, `cell_type`
+   *   (`code`, `markdown` or `raw`) and `limit` (default 20, at most 200).
+   * @param options `signal` cancels the call.
+   * @returns The matches, how many there are in all, and whether `limit` cut them.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { hits } = await host!.notebooks.search({ query: "weekday drop", dir: "journal" });
+   * hits.map((h) => `${h.path}: ${h.excerpt}`);
+   * ```
+   */
+  search(
+    params: { query: string; dir?: string; outputs?: boolean; cell_type?: "code" | "markdown" | "raw"; limit?: number },
+    options?: HostCallOptions,
+  ): Promise<NotebookSearch>;
+  /**
+   * 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.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const results = await host!.notebooks.results({ path: "journal/fremont.ipynb" });
+   * ```
+   */
+  results(params: { path: string }, options?: HostCallOptions): Promise<any>;
+  /**
+   * 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.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const run = await host!.notebooks.run({ path: "journal/fremont.ipynb", params: { counter: "2nd Ave" } });
+   * ```
+   */
+  run(params: { path: string; params?: HostParams }, options?: HostCallOptions): Promise<any>;
+}
+
+/** `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.
+   *
+   * @param params The cell, as the host API's design note describes.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * await host!.self.add({ cell_type: "markdown", source: "## Index" });
+   * ```
+   */
+  add(params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /**
+   * Change a cell's source, given the hash of the source it replaces.
+   *
+   * @param params The cell id, its new source and the old source's hash.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook, hashes } = await host!.notebooks.read({ path: host!.notebook! });
+   * const id = notebook.cells[0].id;
+   * await host!.self.edit({ id, source: "# New title", source_hash: hashes[id] });
+   * ```
+   */
+  edit(params?: HostParams, options?: HostCallOptions): Promise<any>;
+  /**
+   * Delete a cell, given its source's hash.
+   *
+   * @param params The cell id and its source's hash.
+   * @param options `signal` cancels the call.
+   * @example
+   * ```ts
+   * const host = await jupyter.host();
+   * const { notebook, hashes } = await host!.notebooks.read({ path: host!.notebook! });
+   * const id = notebook.cells.at(-1).id;
+   * await host!.self.delete({ id, source_hash: hashes[id] });
+   * ```
+   */
+  delete(params?: HostParams, options?: HostCallOptions): Promise<any>;
+}
+
+/** Options for `jupyter.host()`. */
+export interface HostOptions {
+  /**
+   * How long to wait for a server that hasn't opened the comm, in ms.
+   * Default 1000. Once a wait goes unanswered, later calls answer `null`
+   * at once.
+   */
+  timeout?: number;
+}
+
+export function createHost(
+  comms: CommApi,
+  defaultSignal?: () => AbortSignal | undefined,
+): { host(options?: HostOptions): Promise<Host | null> };

package/runtime/host.mjs

@@ -0,0 +1,215 @@
+// @ts-self-types="./host.d.mts"
+// jupyter.host() (#461): the client for a Ganymede server's host API, which
+// lets a cell read, search and (when granted) run other notebooks. The
+// server opens a comm to target `ganymede.host.v1` when the kernel starts,
+// with its `hello` as the open's data. Calls go out as comm messages
+// `{ id, method, params }`; the server replies `{ id, result }` or
+// `{ id, error: { code, message } }` on a kernel subshell, so a cell that
+// awaits a call gets its reply. The message format and error codes are
+// ganymede-device's, so the two clients behave alike.
+//
+// Design: https://github.com/tlockney/ganymede/blob/main/docs/host-api.md
+
+export const HOST_TARGET = "ganymede.host.v1";
+
+const CODES = new Set(["unavailable", "denied", "cancelled", "timeout", "failed", "disconnected"]);
+
+export class HostError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "HostError";
+    this.code = code;
+  }
+
+  /** An abort becomes `cancelled`, a timeout signal's abort `timeout`, anything else `failed`. */
+  static from(err) {
+    if (err instanceof HostError) return err;
+    const message = typeof err?.message === "string" ? err.message : String(err);
+    if (err?.name === "AbortError") return new HostError("cancelled", message);
+    if (err?.name === "TimeoutError") return new HostError("timeout", message);
+    if (typeof err?.code === "string" && CODES.has(err.code)) return new HostError(err.code, message);
+    return new HostError("failed", message);
+  }
+}
+
+/** Why an aborted signal ended a call: `timeout` for a timeout signal, else `cancelled`. */
+function abortError(reason) {
+  const message = typeof reason?.message === "string" ? reason.message : String(reason ?? "aborted");
+  return new HostError(reason?.name === "TimeoutError" ? "timeout" : "cancelled", message);
+}
+
+/** A server's `hello`, or null when `data` isn't one. */
+function helloOf(data) {
+  if (data === null || typeof data !== "object" || typeof data.protocol !== "number") return null;
+  return {
+    protocol: data.protocol,
+    server: typeof data.server === "string" ? data.server : "",
+    notebook: typeof data.notebook === "string" ? data.notebook : null,
+    methods: Array.isArray(data.methods) ? data.methods.filter((m) => typeof m === "string") : [],
+  };
+}
+
+/**
+ * @param {import("./comm.d.mts").CommApi} comms
+ * @param {() => AbortSignal | undefined} [defaultSignal] the signal a call
+ *   watches when it is given none: jupyter.signal.
+ */
+export function createHost(comms, defaultSignal = () => undefined) {
+  /** The open host comm: { comm, hello, host, pending }, or null. */
+  let link = null;
+  /** Whoever waits for a hello: called with the link's Host, or null once there is no link. */
+  const waiters = new Set();
+  /**
+   * A comm this runtime opened went unanswered: no server. Remembered, so
+   * each `jupyter.host()` after the first answers null at once, until a
+   * server opens the comm itself.
+   */
+  let noServer = false;
+  let nextId = 0;
+
+  function settle() {
+    const host = link?.host ?? null;
+    if (host === null && link !== null) return;
+    for (const waiter of [...waiters]) waiter(host);
+  }
+
+  /** `ours`: this runtime opened the comm, not the server. */
+  function adopt(comm, data, ours = false) {
+    // A new comm replaces the old one: the server opens one per kernel start.
+    const old = link;
+    const l = { comm, host: null, pending: new Map(), ours };
+    if (!ours) noServer = false;
+    link = l;
+    if (old !== null && !old.comm.closed) old.comm.close();
+    const hello = helloOf(data);
+    if (hello !== null) l.host = makeHost(l, hello);
+    comm.onMsg(({ data }) => {
+      if (data.hello !== undefined) {
+        const hello = helloOf(data.hello);
+        if (hello !== null) {
+          l.host = makeHost(l, hello);
+          if (link === l) settle();
+        }
+        return;
+      }
+      const call = l.pending.get(data.id);
+      if (call === undefined) return;
+      if (data.error !== undefined) {
+        const { code, message } = data.error ?? {};
+        call.reject(new HostError(CODES.has(code) ? code : "failed", typeof message === "string" ? message : String(code)));
+      } else {
+        call.resolve(data.result);
+      }
+    });
+    comm.onClose(({ data }) => {
+      for (const call of l.pending.values()) {
+        call.reject(new HostError("disconnected", typeof data?.error === "string" ? `host comm closed: ${data.error}` : "host comm closed"));
+      }
+      l.pending.clear();
+      if (link === l) {
+        link = null;
+        // The frontend closed the comm this runtime opened: no server.
+        if (l.ours && l.host === null) noServer = true;
+        settle();
+      }
+    });
+    if (l.host !== null) settle();
+  }
+
+  function makeHost(l, hello) {
+    const methods = Object.freeze([...hello.methods]);
+    function call(method, params = {}, { signal = defaultSignal() } = {}) {
+      if (signal?.aborted) return Promise.reject(abortError(signal.reason));
+      if (l.comm.closed) return Promise.reject(new HostError("disconnected", "host comm closed"));
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        const onAbort = () => {
+          l.pending.delete(id);
+          if (!l.comm.closed) l.comm.send({ id, cancel: true });
+          reject(abortError(signal.reason));
+        };
+        const done = () => signal?.removeEventListener("abort", onAbort);
+        const call = {
+          resolve: (value) => (l.pending.delete(id), done(), resolve(value)),
+          reject: (error) => (l.pending.delete(id), done(), reject(error)),
+        };
+        l.pending.set(id, call);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+          l.comm.send({ id, method, params });
+        } catch (err) {
+          // Params that can't be sent, such as a BigInt: the server never
+          // got the call.
+          call.reject(new HostError("failed", `cannot send ${method}: ${err instanceof Error ? err.message : err}`));
+        }
+      });
+    }
+    const bind = (method) => (params, options) => call(method, params, options);
+    return Object.freeze({
+      protocol: hello.protocol,
+      server: hello.server,
+      notebook: hello.notebook,
+      methods,
+      has: (method) => methods.includes(method),
+      call,
+      notebooks: Object.freeze({
+        list: bind("notebooks.list"),
+        read: bind("notebooks.read"),
+        search: bind("notebooks.search"),
+        results: bind("notebooks.results"),
+        run: bind("notebooks.run"),
+      }),
+      self: Object.freeze({
+        add: bind("self.add"),
+        edit: bind("self.edit"),
+        delete: bind("self.delete"),
+      }),
+    });
+  }
+
+  comms.registerTarget(HOST_TARGET, (comm, msg) => adopt(comm, msg.data));
+
+  async function host({ timeout = 1000 } = {}) {
+    if (link?.host) return link.host;
+    // The wait for a server watches jupyter.signal, so an interrupt ends it.
+    const signal = defaultSignal();
+    if (signal?.aborted) throw abortError(signal.reason);
+    if (noServer) return null;
+    // No comm from the server (one whose comm closed, as when a runtime
+    // restarts in the same kernel): open it from here. A Ganymede server
+    // answers `{ hello }`; anything else closes it or stays silent.
+    if (link === null) adopt(comms.open(HOST_TARGET), null, true);
+    const mine = link;
+    return new Promise((resolve, reject) => {
+      let timer;
+      const onAbort = () => {
+        done();
+        reject(abortError(signal.reason));
+      };
+      const done = () => {
+        waiters.delete(waiter);
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+      };
+      const waiter = (host) => {
+        done();
+        resolve(host);
+      };
+      waiters.add(waiter);
+      signal?.addEventListener("abort", onAbort, { once: true });
+      // Each caller waits its own timeout; the last to give up on a comm
+      // this runtime opened closes it.
+      timer = setTimeout(() => {
+        done();
+        if (waiters.size === 0 && link === mine && mine.host === null && mine.ours) {
+          link = null;
+          noServer = true;
+          mine.comm.close();
+        }
+        resolve(null);
+      }, timeout);
+    });
+  }
+
+  return { host };
+}

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;