Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Notebook DuckDB Package

Status: Implemented for the current package boundary. packages/notebook/duckdb owns shared DuckDB runtime contracts, app-table and vault-file registration contracts, catalog/preview types, and pure query/catalog helpers consumed by the notebook product plugin.

Purpose

@lapis-notes/notebook-duckdb separates reusable DuckDB-facing notebook contracts from the product plugin. The package owns runtime TypeScript interfaces, query row/result types, app-table and vault-file registration contracts, catalog/preview types, DuckDB type mapping, normalization into notebook table metadata, and small SQL/catalog helpers.

Current Scope

  • NotebookDuckDbRuntime and NotebookDuckDbRuntimeProvider contracts
  • NotebookDuckDbColumnDefinition table registration contract
  • DuckDbQueryRow and DuckDbQueryResult types
  • row normalization for scalar/object DuckDB results
  • query result normalization into notebook table columns, column metadata, row counts, query timing, and source SQL metadata
  • DuckDB type-name mapping for notebook table column categories
  • catalog and table-preview types for inspector/runtime surfaces
  • information-schema table-type normalization
  • DuckDB identifier quoting for generated service queries
  • createNotebookDuckDbCatalog(options) for building notebook catalog models from information-schema table/column rows and a host-provided row-count callback
  • pure catalog/preview SQL helpers, preview-limit normalization, row-count normalization, and createNotebookDuckDbTablePreview(options) for shaping table preview rows
  • NotebookAppTablesSnapshot, NotebookAppTableRegistrar, NOTEBOOK_APP_TABLE_COLUMNS, and registerNotebookAppTablesSnapshot(service, snapshot) for registering app-derived tables into any runtime-shaped registrar that can create JSON tables
  • resolveNotebookVaultPath(path, sourcePath?), NotebookVaultFileReader, NotebookVaultFileRegistrar, and registerNotebookVaultFile(service, reader, alias, path, sourcePath?) for resolving notebook-relative vault file references with the shared stdlib path-normalization rules and either registering host-read file buffers or handing the resolved path to a native runtime registrar
  • createDuckDbSchemaSql(schema) and createDuckDbJsonTableSql(options) for creating stable DuckDB SQL used by product runtimes when registering JSON-backed notebook tables

Boundary Rules

This package must stay independent of product-plugin runtime code. It must not import @lapis-notes/api, Svelte, worker entrypoints, vault adapters, app-table snapshot collectors, DuckDB-Wasm, or DuckDB asset URL imports. Browser/PWA asset URL resolution belongs to @lapis-notes/notebook-duckdb-assets; the product plugin owns app-table snapshot collection, actual vault file reads, native vault-path registration, concrete query execution, and the concrete DuckDB-Wasm service lifecycle. Sharing notebook-relative path normalization with @lapis-notes/notebook-stdlib is allowed so DuckDB registration and notebook file helpers keep one path contract.

Consumers

@lapis-notes/notebook consumes this package from the concrete DuckDB service, app-table registration adapter, vault-file adapter, inspector data surfaces, and notebook execution paths.