DuckDB OPFS Todo List App

A fully-functional todo list application that demonstrates DuckDB WASM OPFS (Origin Private File System) persistence using a pure functional programming approach.

Features

• ✅ Interactive Todo Items - Add, check off, and manage todo items
• ✅ Persistent Checkboxes - Todo completion state survives page refresh
• ✅ OPFS Persistence - All data persists between browser sessions
• ✅ Strike-through Completed Items - Visual feedback for completed todos
• ✅ Smart Clear Options - Clear only completed items or clear all
• ✅ Real-time Status Display - Shows OPFS vs in-memory mode
• ✅ Debug Console - Real-time operation logs for troubleshooting
• ✅ 100% Functional Code - No classes anywhere, pure functional design
• ✅ Comprehensive TypeDoc Documentation - Every function documented
• ✅ AI-Friendly Code Structure - Designed for easy understanding

Quick Start

npm install
npm run dev

Open https://localhost:5173/ in your browser.

🌐 Live Demo: https://markwylde.com/duckdb-opfs-todo-list/

Test Plan

1. Add Todo Items: Enter text and click "Add Todo" or press Enter
2. Check/Uncheck Items: Click checkboxes to mark items as completed (see strike-through effect)
3. Test Persistence: Refresh the page → all todos and their completion status should persist
4. Clear Completed: Use "Clear Completed" to remove only finished items
5. Clear All: Use "Clear All Todos" to remove everything
6. Status Verification: Check if status shows "OPFS Persistent" or "In-Memory"

Expected Behavior

• OPFS Supported: Status shows "OPFS Persistent", todos and checkmarks survive page refresh
• OPFS Not Supported: Status shows "In-Memory", todos lost on refresh
• Visual Feedback: Completed items show strike-through text and subtle background change
• Interactive Checkboxes: Clicking checkboxes immediately toggles completion state
• Debug Info: Console logs show all database operations and OPFS detection

Architecture & Code Quality

Functional Programming Approach

• No classes anywhere - pure functional design
• Immutable data patterns - state is managed functionally
• Pure functions - predictable, testable code
• Clear separation of concerns - each function has a single responsibility

Documentation Excellence

• Comprehensive TypeDoc comments - every function documented
• Usage examples - code examples for all major functions
• AI-friendly structure - designed for easy understanding by future developers and AIs
• Error handling patterns - consistent error handling throughout

Code Organization

src/database.ts    # Functional database operations
├── Type definitions (TodoItem, DatabaseState, DatabaseOptions)
├── OPFS detection utilities
├── Database initialization functions  
├── Todo CRUD operations (add, get, toggle, clear)
└── Database lifecycle management

src/main.ts        # Functional UI implementation
├── DOM utilities and type-safe element access
├── Debug logging system
├── UI status updates
├── Todo rendering with interactive checkboxes
├── Event handling (add, toggle, clear)
└── Application lifecycle

Technical Details

• DuckDB WASM: v1.29.1-dev269.0 with OPFS support
• Database Path: opfs://test.db (falls back to :memory:)
• Bundle: EH (Exception Handling) variant for broader browser compatibility
• HTTPS: Automatic SSL certificates via vite-plugin-mkcert
• HTTPS Required: DuckDB WASM requires HTTPS for OPFS functionality
• TypeScript: Full type safety with detailed interfaces
• Functional Paradigm: Zero classes, pure functions only

Files Structure

├── package.json              # Dependencies and scripts
├── vite.config.js            # Vite config with HTTPS and COOP/COEP headers  
├── copy-wasm.sh              # Script to copy WASM files to public/
├── index.html                # Main HTML structure
├── src/
│   ├── main.ts              # Functional UI implementation (700+ lines)
│   │   ├── DOM utilities    # Type-safe element access
│   │   ├── Debug logging    # Real-time operation feedback
│   │   ├── UI updates       # Status and todo count management
│   │   ├── Todo rendering   # Interactive checkboxes and strike-through
│   │   ├── User actions     # Add/toggle/clear todo handlers
│   │   └── App lifecycle    # Initialization and cleanup
│   ├── database.ts          # Functional database operations (500+ lines)
│   │   ├── OPFS detection   # Browser capability checking
│   │   ├── DB initialization# Connection and schema setup
│   │   ├── Todo operations  # CRUD with completion state and auto-flush
│   │   └── Lifecycle mgmt   # Proper cleanup and persistence
│   └── style.css            # Application styling
└── public/                  # DuckDB WASM files (copied by script)
    ├── duckdb-eh.wasm
    └── duckdb-browser-eh.worker.js

Database Schema

CREATE TABLE todos (
  id INTEGER PRIMARY KEY,
  content TEXT NOT NULL,
  completed BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE SEQUENCE todos_id_seq START 1;

For Developers & AIs

This codebase demonstrates:

1. How to implement DuckDB WASM OPFS persistence correctly
2. Functional programming patterns in TypeScript
3. Interactive UI with persistent state management
4. Comprehensive error handling strategies
5. Type-safe DOM manipulation with event handling
6. Proper database lifecycle management
7. Security best practices (XSS prevention, input validation)

Key Functions to Study

• initializeDatabase() - Shows OPFS setup with fallback
• addTodoItem() - Demonstrates parameterized queries + CHECKPOINT
• toggleTodoItem() - Shows UPDATE operations with state changes
• isOpfsSupported() - Browser capability detection
• renderTodos() - Interactive DOM generation with event binding
• handleToggleTodo() - Real-time UI updates with database sync
• setupEventListeners() - Functional event binding

This todo list app definitively demonstrates DuckDB WASM OPFS persistence with interactive state management, serving as a complete reference implementation for functional database applications with rich user interactions.