crowd-funder-for-time-pwa/.cursor/rules/absurd-sql.mdc

---
description: 
globs: 
alwaysApply: true
---
# Absurd SQL - Cursor Development Guide

## Project Overview
Absurd SQL is a backend implementation for sql.js that enables persistent SQLite databases in the browser by using IndexedDB as a block storage system. This guide provides rules and best practices for developing with this project in Cursor.

## Project Structure
```
absurd-sql/
├── src/               # Source code
├── dist/             # Built files
├── package.json      # Dependencies and scripts
├── rollup.config.js  # Build configuration
└── jest.config.js    # Test configuration
```

## Development Rules

### 1. Worker Thread Requirements
- All SQL operations MUST be performed in a worker thread
- Main thread should only handle worker initialization and communication
- Never block the main thread with database operations

### 2. Code Organization
- Keep worker code in separate files (e.g., `*.worker.js`)
- Use ES modules for imports/exports
- Follow the project's existing module structure

### 3. Required Headers
When developing locally or deploying, ensure these headers are set:
```
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

### 4. Browser Compatibility
- Primary target: Modern browsers with SharedArrayBuffer support
- Fallback mode: Safari (with limitations)
- Always test in both modes

### 5. Database Configuration
Recommended database settings:
```sql
PRAGMA journal_mode=MEMORY;
PRAGMA page_size=8192;  -- Optional, but recommended
```

### 6. Development Workflow
1. Install dependencies:
   ```bash
   yarn add @jlongster/sql.js absurd-sql
   ```

2. Development commands:
   - `yarn build` - Build the project
   - `yarn jest` - Run tests
   - `yarn serve` - Start development server

### 7. Testing Guidelines
- Write tests for both SharedArrayBuffer and fallback modes
- Use Jest for testing
- Include performance benchmarks for critical operations

### 8. Performance Considerations
- Use bulk operations when possible
- Monitor read/write performance
- Consider using transactions for multiple operations
- Avoid unnecessary database connections

### 9. Error Handling
- Implement proper error handling for:
  - Worker initialization failures
  - Database connection issues
  - Concurrent access conflicts (in fallback mode)
  - Storage quota exceeded scenarios

### 10. Security Best Practices
- Never expose database operations directly to the client
- Validate all SQL queries
- Implement proper access controls
- Handle sensitive data appropriately

### 11. Code Style
- Follow ESLint configuration
- Use async/await for asynchronous operations
- Document complex database operations
- Include comments for non-obvious optimizations

### 12. Debugging
- Use `jest-debug` for debugging tests
- Monitor IndexedDB usage in browser dev tools
- Check worker communication in console
- Use performance monitoring tools

## Common Patterns

### Worker Initialization
```javascript
// Main thread
import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';

function init() {
  let worker = new Worker(new URL('./index.worker.js', import.meta.url));
  initBackend(worker);
}
```

### Database Setup
```javascript
// Worker thread
import initSqlJs from '@jlongster/sql.js';
import { SQLiteFS } from 'absurd-sql';
import IndexedDBBackend from 'absurd-sql/dist/indexeddb-backend';

async function setupDatabase() {
  let SQL = await initSqlJs({ locateFile: file => file });
  let sqlFS = new SQLiteFS(SQL.FS, new IndexedDBBackend());
  SQL.register_for_idb(sqlFS);
  
  SQL.FS.mkdir('/sql');
  SQL.FS.mount(sqlFS, {}, '/sql');
  
  return new SQL.Database('/sql/db.sqlite', { filename: true });
}
```

## Troubleshooting

### Common Issues
1. SharedArrayBuffer not available
   - Check COOP/COEP headers
   - Verify browser support
   - Test fallback mode

2. Worker initialization failures
   - Check file paths
   - Verify module imports
   - Check browser console for errors

3. Performance issues
   - Monitor IndexedDB usage
   - Check for unnecessary operations
   - Verify transaction usage

## Resources
- [Project Demo](https://priceless-keller-d097e5.netlify.app/)
- [Example Project](https://github.com/jlongster/absurd-example-project)
- [Blog Post](https://jlongster.com/future-sql-web)
- [SQL.js Documentation](https://github.com/sql-js/sql.js/)