docs(rules): apply markdown standards and streamline rulesets
- Apply markdown.mdc formatting to all ruleset files (80-char line length, proper spacing) - Update timesafari.mdc to reflect completed migration (remove triple migration pattern references) - Clean up corrupted logging_standards.mdc and restore proper content - Streamline architectural_decision_record.mdc for better readability - Update all file dates to 2025-08-19 for consistency - Add proper document headers and metadata to all ruleset files - Remove duplicate content and improve file organization - Maintain alwaysApply settings and glob patterns appropriately Files affected: 15 ruleset files across app/, database/, development/, features/, workflow/ directories
This commit is contained in:
@@ -1,13 +1,23 @@
|
||||
---
|
||||
globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/services/AbsurdSqlDatabaseService.ts
|
||||
globs: **/db/databaseUtil.ts, **/interfaces/absurd-sql.d.ts, **/src/registerSQLWorker.js, **/
|
||||
services/AbsurdSqlDatabaseService.ts
|
||||
alwaysApply: false
|
||||
---
|
||||
# Absurd SQL - Cursor Development Guide
|
||||
|
||||
**Author**: Matthew Raymer
|
||||
**Date**: 2025-08-19
|
||||
**Status**: 🎯 **ACTIVE** - Database development guidelines
|
||||
|
||||
## 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.
|
||||
|
||||
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
|
||||
@@ -20,36 +30,45 @@ absurd-sql/
|
||||
## 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
|
||||
```
|
||||
@@ -60,17 +79,20 @@ PRAGMA page_size=8192; -- Optional, but recommended
|
||||
- `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
|
||||
@@ -78,18 +100,21 @@ PRAGMA page_size=8192; -- Optional, but recommended
|
||||
- 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
|
||||
@@ -98,6 +123,7 @@ PRAGMA page_size=8192; -- Optional, but recommended
|
||||
## Common Patterns
|
||||
|
||||
### Worker Initialization
|
||||
|
||||
```javascript
|
||||
// Main thread
|
||||
import { initBackend } from 'absurd-sql/dist/indexeddb-main-thread';
|
||||
@@ -109,6 +135,7 @@ function init() {
|
||||
```
|
||||
|
||||
### Database Setup
|
||||
|
||||
```javascript
|
||||
// Worker thread
|
||||
import initSqlJs from '@jlongster/sql.js';
|
||||
@@ -130,6 +157,7 @@ async function setupDatabase() {
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. SharedArrayBuffer not available
|
||||
- Check COOP/COEP headers
|
||||
- Verify browser support
|
||||
@@ -146,7 +174,20 @@ async function setupDatabase() {
|
||||
- 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/)
|
||||
- [SQL.js Documentation](https://github.com/sql-js/sql.js/)
|
||||
|
||||
---
|
||||
|
||||
**Status**: Active database development guidelines
|
||||
**Priority**: High
|
||||
**Estimated Effort**: Ongoing reference
|
||||
**Dependencies**: Absurd SQL, SQL.js, IndexedDB
|
||||
**Stakeholders**: Development team, Database team
|
||||
- [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/)
|
||||
|
||||
Reference in New Issue
Block a user