Skip to content

Commit d0cc550

Browse files
mceachenmceachen
committed
chore(docs): initial project analysis and lzz-migration steps
1 parent a55ea12 commit d0cc550

File tree

4 files changed

+399
-0
lines changed

4 files changed

+399
-0
lines changed

‎.claude/settings.local.json

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"permissions": {
3+
"allow": [
4+
"WebFetch(domain:www.lazycplusplus.com)",
5+
"Bash(grep:*)",
6+
"Bash(ls:*)",
7+
"Bash(find:*)",
8+
"Bash(lzz:*)"
9+
]
10+
},
11+
"enableAllProjectMcpServers": false
12+
}

‎CLAUDE.md

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**better-sqlite3** is a Node.js native addon providing synchronous SQLite database access. It's architected as a hybrid C++/JavaScript library where C++ handles direct SQLite operations and JavaScript provides the high-level API.
8+
9+
## Build & Development Commands
10+
11+
### Essential Commands
12+
- **Build**: `npm run build-release` (production build)
13+
- **Debug Build**: `npm run build-debug`
14+
- **Full Rebuild**: `npm run rebuild-release` (includes LZZ preprocessing)
15+
- **Test**: `npm test` (mocha with 5s timeout)
16+
- **Single Test**: `npx mocha test/[test-file].js`
17+
- **Benchmark**: `npm run benchmark`
18+
19+
### LZZ-Specific (Current Architecture)
20+
- **Generate C++**: `npm run lzz` (preprocesses .lzz files to .cpp/.hpp)
21+
- **Download SQLite**: `npm run download`
22+
23+
## Architecture
24+
25+
### Code Organization
26+
```
27+
lib/ # JavaScript API layer
28+
├── index.js # Main export (Database constructor)
29+
├── database.js # Database class with native binding
30+
└── methods/ # Method implementations
31+
32+
src/ # C++ source (LZZ-based)
33+
├── better_sqlite3.lzz # Main file (generates .cpp/.hpp)
34+
├── objects/ # Core classes (Database, Statement, etc.)
35+
└── util/ # Utilities and type conversion
36+
```
37+
38+
### Critical LZZ Pattern
39+
- **Never edit `.cpp` or `.hpp` files directly** - they are generated
40+
- Edit `.lzz` files only, then run `npm run lzz`
41+
- Uses `#insert` directive (literal inclusion, not C++ #include)
42+
- Single compilation unit architecture
43+
- Order dependency matters in .lzz files
44+
45+
### LZZ Migration Status
46+
This codebase is currently migrating away from LZZ (see `lzz-migration.md`). The current branch `no-lzz-20250428` contains migration work. Be aware that the build process may change during this transition.
47+
48+
## Native Addon Structure
49+
50+
### Data Flow
51+
```
52+
JavaScript API → C++ Native Methods → SQLite C API → Results → Type Conversion → JavaScript
53+
```
54+
55+
### Key Classes
56+
- `Database`: Main database connection and operations
57+
- `Statement`: Prepared SQL statements
58+
- `StatementIterator`: Row iteration
59+
- `Backup`: Database backup functionality
60+
61+
### Type Conversion
62+
The C++ layer handles conversion between SQLite types and V8/JavaScript types, including support for 64-bit integers, Buffers, and BigInts.
63+
64+
## Testing
65+
66+
Tests are organized by functionality in `test/`:
67+
- `00.setup.js`: Global test setup
68+
- `10-19.*`: Database-level operations
69+
- `20-29.*`: Statement operations
70+
- `30-39.*`: Advanced features (transactions, custom functions)
71+
- `40-50.*`: Special cases (BigInts, worker threads, unsafe mode)
72+
73+
## Development Workflow
74+
75+
1. **For C++ changes**: Edit `.lzz` files → `npm run lzz` → `npm run build-release` → `npm test`
76+
2. **For JavaScript changes**: Edit files in `lib/` → `npm test`
77+
3. **Performance testing**: Use `npm run benchmark` after changes
78+
79+
## Important Notes
80+
81+
- This is a **synchronous** SQLite library (no async/await)
82+
- Single-threaded SQLite access for performance
83+
- Uses Node.js N-API for forward compatibility
84+
- Embeds SQLite source in `deps/` directory
85+
- Supports Node.js 20.x, 22.x, 23.x, 24.x

‎TODO.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Migration from .lzz to Standard C++ Files
2+
3+
## Overview
4+
Migrate better-sqlite3 from using .lzz (Lazy C++) to standard .cpp/.hpp files. The current architecture uses #insert directives to create a single compilation unit, which requires a careful migration approach.
5+
6+
## Critical Understanding
7+
- **Current Build**: All .lzz files are processed as ONE unit through `src/better_sqlite3.lzz`
8+
- **#insert != #include**: The #insert directive literally inserts file contents during preprocessing
9+
- **Single .cpp Output**: Currently produces only `better_sqlite3.cpp` and `better_sqlite3.hpp`
10+
11+
## Migration Approach: Option A (Recommended - Low Risk)
12+
Preserve the single compilation unit architecture while removing lzz dependency.
13+
14+
### Phase 1: Preparation
15+
- [ ] Create a backup branch for safety
16+
- [ ] Document the current #insert order from `better_sqlite3.lzz`
17+
- [ ] Verify lzz is installed and working
18+
19+
### Phase 2: Generate Baseline
20+
- [ ] Run lzz WITHOUT #line directives:
21+
```bash
22+
lzz -hx hpp -sx cpp -k BETTER_SQLITE3 -d -e ./src/better_sqlite3.lzz
23+
```
24+
- [ ] Backup the generated files:
25+
```bash
26+
cp src/better_sqlite3.hpp src/better_sqlite3.hpp.generated
27+
cp src/better_sqlite3.cpp src/better_sqlite3.cpp.generated
28+
```
29+
- [ ] Verify the build still works with these generated files
30+
31+
### Phase 3: Split Generated Code
32+
- [ ] Create directory structure for split files:
33+
```bash
34+
mkdir -p src/util src/objects
35+
```
36+
- [ ] Manually extract code from generated files into individual .hpp files:
37+
- [ ] `src/util/macros.hpp` - Extract macro definitions
38+
- [ ] `src/util/query-macros.hpp` - Extract query macros
39+
- [ ] `src/util/constants.hpp` - Extract constants
40+
- [ ] `src/util/bind-map.hpp` - Extract BindMap class
41+
- [ ] `src/objects/database.hpp` - Extract Database class
42+
- [ ] `src/objects/statement.hpp` - Extract Statement class
43+
- [ ] `src/objects/statement-iterator.hpp` - Extract StatementIterator
44+
- [ ] `src/objects/backup.hpp` - Extract Backup class
45+
- [ ] `src/util/data-converter.hpp` - Extract data conversion utilities
46+
- [ ] `src/util/custom-function.hpp` - Extract custom function code
47+
- [ ] `src/util/custom-aggregate.hpp` - Extract custom aggregate code
48+
- [ ] `src/util/custom-table.hpp` - Extract custom table code
49+
- [ ] `src/util/data.hpp` - Extract data handling code
50+
- [ ] `src/util/binder.hpp` - Extract binder utilities
51+
52+
### Phase 4: Create New Main Files
53+
- [ ] Create new `src/better_sqlite3.hpp` that includes all headers in correct order:
54+
```cpp
55+
#pragma once
56+
#include <climits>
57+
#include <cstdio>
58+
// ... other system includes ...
59+
60+
#include "util/macros.hpp"
61+
#include "util/query-macros.hpp"
62+
#include "util/constants.hpp"
63+
#include "util/bind-map.hpp"
64+
// Forward declarations
65+
struct Addon;
66+
class Statement;
67+
class Backup;
68+
#include "objects/database.hpp"
69+
#include "objects/statement.hpp"
70+
#include "objects/statement-iterator.hpp"
71+
#include "objects/backup.hpp"
72+
#include "util/data-converter.hpp"
73+
#include "util/custom-function.hpp"
74+
#include "util/custom-aggregate.hpp"
75+
#include "util/custom-table.hpp"
76+
#include "util/data.hpp"
77+
#include "util/binder.hpp"
78+
// Addon struct definition
79+
```
80+
- [ ] Update `src/better_sqlite3.cpp` to use the new header structure
81+
82+
### Phase 5: Verify and Test
83+
- [ ] Build the project: `npm run build-release`
84+
- [ ] Run the test suite: `npm test`
85+
- [ ] Run benchmarks to ensure no performance regression
86+
- [ ] Check that all exports work correctly
87+
88+
### Phase 6: Update Build System
89+
- [ ] Update `package.json` to remove lzz script
90+
- [ ] Update documentation to remove lzz references
91+
- [ ] Update contribution guide
92+
93+
### Phase 7: Cleanup
94+
- [ ] Once all tests pass, remove .lzz files
95+
- [ ] Remove lzz from development dependencies
96+
- [ ] Create a PR with the changes
97+
98+
## Alternative: Option B (Future Enhancement)
99+
Convert to proper modular architecture with separate compilation units.
100+
101+
### Additional Steps for Option B:
102+
- [ ] Analyze dependencies between modules
103+
- [ ] Add proper .cpp files for each module
104+
- [ ] Update binding.gyp to include all .cpp files
105+
- [ ] Resolve circular dependencies
106+
- [ ] Enable parallel compilation
107+
108+
## Rollback Plan
109+
If issues arise:
110+
1. Git reset to backup branch
111+
2. Restore original .lzz files
112+
3. Rebuild with lzz
113+
114+
## Success Criteria
115+
- [ ] All tests pass
116+
- [ ] No performance regression
117+
- [ ] No lzz dependency
118+
- [ ] Clean build without warnings
119+
- [ ] Documentation updated

0 commit comments

Comments
 (0)