duckdb-terminal 0.1.0

package/README.md

@@ -0,0 +1,505 @@
+# DuckDB Terminal
+
+A browser-based SQL Terminal for [DuckDB](https://duckdb.org/) powered by [Ghostty](https://ghostty.org/) terminal emulator.
+
+## Features
+
+- **Full SQL REPL** - Execute SQL queries with multi-line support
+- **Command History** - Navigate previous commands with arrow keys (persisted in IndexedDB)
+- **Auto-Complete** - Tab completion for SQL keywords, table names, and functions
+- **Multiple Output Modes** - Table, CSV, TSV, or JSON output formats
+- **Clipboard Support** - Copy query results to clipboard in any output format
+- **Result Pagination** - Navigate large result sets page by page
+- **Syntax Highlighting** - Color-coded SQL keywords, strings, and numbers
+- **Clickable URLs** - Automatically detect and make URLs clickable in results
+- **File Loading** - Load CSV, Parquet, and JSON files via drag-and-drop or file picker
+- **Dark/Light Themes** - Switchable themes with custom theme support
+- **Customizable Prompts** - Configure primary and continuation prompts
+- **Dot Commands** - Terminal commands like `.help`, `.tables`, `.schema`
+- **Query Timing** - Optional execution time display
+- **Persistent Storage** - Optional OPFS storage for data persistence
+
+## Installation
+
+```bash
+npm install duckdb-terminal
+```
+
+## Quick Start
+
+### As a Library
+
+```typescript
+import { createTerminal } from 'duckdb-terminal';
+
+const Terminal = await createTerminal({
+  container: '#terminal',
+  theme: 'dark',
+});
+```
+
+### As a Standalone App
+
+```bash
+git clone https://github.com/tobilg/duckdb-terminal.git
+cd duckdb-terminal
+npm install
+npm run dev
+```
+
+Open http://localhost:5173 in your browser.
+
+## Configuration
+
+```typescript
+interface TerminalConfig {
+  // Container element or CSS selector
+  container: HTMLElement | string;
+
+  // Font family (default: 'Fira Code', 'Cascadia Code', etc.)
+  fontFamily?: string;
+
+  // Font size in pixels (default: 14)
+  fontSize?: number;
+
+  // Theme: 'dark' | 'light' | Theme (default: 'dark')
+  theme?: 'dark' | 'light' | Theme;
+
+  // Storage: 'memory' | 'opfs' (default: 'memory')
+  storage?: 'memory' | 'opfs';
+
+  // Database path for OPFS storage
+  databasePath?: string;
+
+  // Show welcome message (default: true)
+  // When enabled, displays loading progress during DuckDB initialization
+  welcomeMessage?: boolean;
+
+  // Primary prompt string (default: '🦆 ')
+  prompt?: string;
+
+  // Continuation prompt for multi-line SQL (default: '  > ')
+  continuationPrompt?: string;
+
+  // Enable clickable URL detection (default: true)
+  linkDetection?: boolean;
+
+  // Scrollback buffer size in bytes (default: 10485760 = 10MB)
+  scrollback?: number;
+}
+```
+
+## Terminal Commands
+
+| Command | Description |
+|---------|-------------|
+| `.help` | Show available commands |
+| `.clear` | Clear the terminal |
+| `.tables` | List all tables |
+| `.schema <table>` | Show table schema |
+| `.timer on\|off` | Toggle query timing |
+| `.mode table\|csv\|tsv\|json` | Set output format |
+| `.copy` | Copy last query results to clipboard |
+| `.pagesize <n>` | Set pagination size (0 to disable) |
+| `.theme dark\|light` | Switch color theme (clears screen) |
+| `.highlight on\|off` | Toggle syntax highlighting |
+| `.links on\|off` | Toggle clickable URL detection |
+| `.files [list\|add\|remove]` | Manage loaded files (list, add, or remove) |
+| `.open` | Open file picker to load data files |
+| `.prompt [primary [cont]]` | Get or set the command prompt |
+| `.examples` | Show example queries |
+| `.reset` | Reset database and all settings to defaults |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Execute command/SQL |
+| `Tab` | Auto-complete |
+| `↑` / `↓` | Navigate history |
+| `←` / `→` | Move cursor |
+| `Ctrl+A` | Move to start of line |
+| `Ctrl+E` | Move to end of line |
+| `Ctrl+K` | Clear to end of line |
+| `Ctrl+U` | Clear entire line |
+| `Ctrl+C` | Cancel current input |
+
+## Example Usage
+
+```sql
+-- Create a table
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  name VARCHAR,
+  email VARCHAR
+);
+
+-- Insert data
+INSERT INTO users VALUES
+  (1, 'Alice', 'alice@example.com'),
+  (2, 'Bob', 'bob@example.com');
+
+-- Query data
+SELECT * FROM users WHERE name LIKE 'A%';
+
+-- Use built-in functions
+SELECT range(10), current_timestamp;
+```
+
+## Querying and Copying Results
+
+The terminal supports four output formats and provides an easy way to copy query results to your clipboard.
+
+### Output Formats
+
+Use the `.mode` command to switch between output formats:
+
+```sql
+-- Table format (default) - human-readable ASCII table
+.mode table
+SELECT * FROM users;
++----+-------+-------------------+
+| id | name  | email             |
++----+-------+-------------------+
+| 1  | Alice | alice@example.com |
+| 2  | Bob   | bob@example.com   |
++----+-------+-------------------+
+
+-- CSV format - comma-separated values
+.mode csv
+SELECT * FROM users;
+id,name,email
+1,Alice,alice@example.com
+2,Bob,bob@example.com
+
+-- TSV format - tab-separated values
+.mode tsv
+SELECT * FROM users;
+id	name	email
+1	Alice	alice@example.com
+2	Bob	bob@example.com
+
+-- JSON format - array of objects
+.mode json
+SELECT * FROM users;
+[
+  {"id": 1, "name": "Alice", "email": "alice@example.com"},
+  {"id": 2, "name": "Bob", "email": "bob@example.com"}
+]
+```
+
+### Copying Results
+
+After running a query, use `.copy` to copy the results to your clipboard in the current output format:
+
+```sql
+-- Run your query
+SELECT * FROM users WHERE active = true;
+
+-- Copy results to clipboard (uses current .mode format)
+.copy
+```
+
+The copied content respects your current output mode, so you can:
+1. Use `.mode csv` or `.mode tsv` then `.copy` to paste into a spreadsheet
+2. Use `.mode json` then `.copy` to paste into a JSON file or API tool
+3. Use `.mode table` then `.copy` to paste formatted output into documentation
+
+### Pagination for Large Results
+
+For large result sets, enable pagination with `.pagesize`:
+
+```sql
+-- Enable pagination (50 rows per page)
+.pagesize 50
+
+-- Run a query with many results
+SELECT * FROM large_table;
+
+-- Navigate pages:
+-- n or Enter - next page
+-- p - previous page
+-- 1-9 - jump to page number
+-- q - quit pagination
+```
+
+Set `.pagesize 0` to disable pagination and show all results at once.
+
+**Note:** Queries that already contain `LIMIT` or `OFFSET` clauses bypass pagination, giving you full control over result size.
+
+## Custom Themes
+
+You can create custom themes by providing a `Theme` object instead of `'dark'` or `'light'`:
+
+```typescript
+import { createTerminal, type Theme, type ThemeColors } from 'duckdb-terminal';
+
+// Define custom colors
+const myColors: ThemeColors = {
+  background: '#1a1b26',    // Terminal background
+  foreground: '#a9b1d6',    // Default text color
+  cursor: '#c0caf5',        // Cursor color
+  selection: '#33467c',     // Selection highlight
+  // Standard ANSI colors
+  black: '#15161e',
+  red: '#f7768e',
+  green: '#9ece6a',
+  yellow: '#e0af68',
+  blue: '#7aa2f7',
+  magenta: '#bb9af7',
+  cyan: '#7dcfff',
+  white: '#a9b1d6',
+  // Bright variants
+  brightBlack: '#414868',
+  brightRed: '#f7768e',
+  brightGreen: '#9ece6a',
+  brightYellow: '#e0af68',
+  brightBlue: '#7aa2f7',
+  brightMagenta: '#bb9af7',
+  brightCyan: '#7dcfff',
+  brightWhite: '#c0caf5',
+};
+
+// Create theme object
+const tokyoNight: Theme = {
+  name: 'tokyo-night',
+  colors: myColors,
+};
+
+// Use custom theme
+const Terminal = await createTerminal({
+  container: '#terminal',
+  theme: tokyoNight,
+});
+
+// You can also change theme at runtime
+Terminal.setTheme(tokyoNight);
+```
+
+### ThemeColors Reference
+
+| Property | Description | ANSI Code |
+|----------|-------------|-----------|
+| `background` | Terminal background color | - |
+| `foreground` | Default text color | - |
+| `cursor` | Cursor color | - |
+| `selection` | Text selection highlight | - |
+| `black` | ANSI black | `\x1b[30m` |
+| `red` | ANSI red | `\x1b[31m` |
+| `green` | ANSI green | `\x1b[32m` |
+| `yellow` | ANSI yellow | `\x1b[33m` |
+| `blue` | ANSI blue | `\x1b[34m` |
+| `magenta` | ANSI magenta | `\x1b[35m` |
+| `cyan` | ANSI cyan | `\x1b[36m` |
+| `white` | ANSI white | `\x1b[37m` |
+| `brightBlack` | Bright black (gray) | `\x1b[90m` |
+| `brightRed` | Bright red | `\x1b[91m` |
+| `brightGreen` | Bright green | `\x1b[92m` |
+| `brightYellow` | Bright yellow | `\x1b[93m` |
+| `brightBlue` | Bright blue | `\x1b[94m` |
+| `brightMagenta` | Bright magenta | `\x1b[95m` |
+| `brightCyan` | Bright cyan | `\x1b[96m` |
+| `brightWhite` | Bright white | `\x1b[97m` |
+
+### Built-in Themes
+
+The library exports two built-in themes that you can use directly or extend:
+
+```typescript
+import { darkTheme, lightTheme } from 'duckdb-terminal';
+
+// Use directly
+const Terminal = await createTerminal({
+  container: '#terminal',
+  theme: darkTheme,
+});
+
+// Or extend
+const myTheme: Theme = {
+  name: 'my-dark',
+  colors: {
+    ...darkTheme.colors,
+    background: '#000000',  // Override specific colors
+    cursor: '#ff0000',
+  },
+};
+```
+
+## API
+
+### createTerminal(config)
+
+Creates and starts a DuckDB Terminal instance.
+
+```typescript
+import { createTerminal } from 'duckdb-terminal';
+
+const Terminal = await createTerminal({
+  container: document.getElementById('terminal'),
+  theme: 'dark',
+});
+
+// Write to terminal
+Terminal.write('Hello, World!');
+Terminal.writeln('With newline');
+
+// Execute SQL programmatically
+const result = await Terminal.executeSQL('SELECT 1+1 as answer');
+console.log(result); // { columns: ['answer'], rows: [[2]], rowCount: 1, duration: 5 }
+
+// Change theme
+Terminal.setTheme('light');
+
+// Clear terminal
+Terminal.clear();
+
+// Clean up when done (removes event listeners, closes database)
+Terminal.destroy();
+```
+
+### Events
+
+The Terminal emits events that you can subscribe to for monitoring and integrating with your application:
+
+```typescript
+import { createTerminal, type TerminalEvents } from 'duckdb-terminal';
+
+const Terminal = await createTerminal({
+  container: '#terminal',
+  theme: 'dark',
+});
+
+// Subscribe to events
+Terminal.on('ready', () => {
+  console.log('Terminal is ready!');
+});
+
+Terminal.on('queryStart', ({ sql }) => {
+  console.log('Executing:', sql);
+});
+
+Terminal.on('queryEnd', ({ sql, result, error, duration }) => {
+  if (error) {
+    console.error('Query failed:', error);
+  } else {
+    console.log(`Query completed in ${duration}ms, ${result?.rowCount} rows`);
+  }
+});
+
+Terminal.on('stateChange', ({ state, previous }) => {
+  console.log(`State changed: ${previous} -> ${state}`);
+});
+
+Terminal.on('themeChange', ({ theme, previous }) => {
+  console.log(`Theme changed to: ${theme.name}`);
+});
+
+Terminal.on('fileLoaded', ({ filename, size, type }) => {
+  console.log(`Loaded file: ${filename} (${size} bytes)`);
+});
+
+Terminal.on('commandExecute', ({ command, args }) => {
+  console.log(`Command: ${command}`, args);
+});
+
+Terminal.on('error', ({ message, source }) => {
+  console.error(`Error from ${source}: ${message}`);
+});
+
+// Unsubscribe using the returned function
+const unsubscribe = Terminal.on('queryEnd', handler);
+unsubscribe(); // Stop listening
+
+// Or use off() directly
+Terminal.off('queryEnd', handler);
+```
+
+#### Available Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `ready` | `{}` | Terminal is fully initialized |
+| `queryStart` | `{ sql }` | SQL query execution started |
+| `queryEnd` | `{ sql, result, error?, duration }` | SQL query completed or failed |
+| `stateChange` | `{ state, previous }` | Terminal state changed (idle, collecting, executing, paginating) |
+| `themeChange` | `{ theme, previous }` | Theme was changed |
+| `fileLoaded` | `{ filename, size, type }` | File was loaded via drag-drop or picker |
+| `commandExecute` | `{ command, args }` | Dot command was executed |
+| `error` | `{ message, source }` | An error occurred |
+
+### Advanced Usage
+
+```typescript
+import {
+  Terminal,
+  Database,
+  TerminalAdapter,
+  formatTable,
+  formatCSV,
+  formatJSON
+} from 'duckdb-terminal';
+
+// Use Database directly
+const db = new Database({ storage: 'memory' });
+await db.init();
+const result = await db.executeQuery('SELECT 42');
+
+// Use formatters
+console.log(formatTable(result.columns, result.rows));
+console.log(formatCSV(result.columns, result.rows));
+console.log(formatJSON(result.columns, result.rows));
+
+// Get completions
+const suggestions = await db.getCompletions('SEL', 3);
+```
+
+## Browser Requirements
+
+- Modern browser with WebAssembly support
+- SharedArrayBuffer (requires COOP/COEP headers)
+
+For development, Vite automatically sets the required headers. For production, configure your server:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+## Building
+
+```bash
+# Development
+npm run dev
+
+# Production build
+npm run build
+
+# Run tests
+npm test
+
+# Type checking
+npm run typecheck
+```
+
+## Bundle Outputs
+
+| File | Format | Usage |
+|------|--------|-------|
+| `dist/duckdb-terminal.js` | ESM | Modern bundlers |
+| `dist/duckdb-terminal.umd.cjs` | UMD | Script tags, legacy |
+| `dist/*.d.ts` | TypeScript | Type definitions |
+
+## Dependencies
+
+- [@duckdb/duckdb-wasm](https://www.npmjs.com/package/@duckdb/duckdb-wasm) - DuckDB WebAssembly build
+- [ghostty-web](https://www.npmjs.com/package/ghostty-web) - Ghostty terminal emulator for web
+
+## License
+
+MIT
+
+## Credits
+
+- [DuckDB](https://duckdb.org/) - The in-process analytical database
+- [Ghostty](https://ghostty.org/) - Fast, native terminal emulator
+- [ghostty-web](https://github.com/coder/ghostty-web) - Web port by Coder