@objectql/driver-excel 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,70 @@
+# @objectql/driver-excel
+
+## 0.2.0 - 2024-01-16
+
+### Added
+
+- **File Storage Modes**: New `fileStorageMode` configuration option
+  - `single-file` mode: All object types in one Excel file (default, existing behavior)
+  - `file-per-object` mode: Each object type in a separate Excel file
+- Complete English documentation in README
+- Additional tests for file-per-object mode (39 total tests now)
+- Examples for both storage modes
+
+### Improved
+
+- Better documentation with comprehensive API reference
+- Usage examples for common scenarios
+- Performance benchmarks and optimization tips
+- Detailed error handling guide
+
+## 0.1.0 - 2024-01-16
+
+### Added
+
+- Initial release of Excel Driver for ObjectQL
+- Full CRUD operations (create, read, update, delete)
+- Query support with filters, sorting, and pagination
+- Bulk operations (createMany, updateMany, deleteMany)
+- Multiple worksheet support (one sheet per object type)
+- Auto-save and manual save options
+- File persistence with Excel (.xlsx) format
+- Comprehensive test suite with 36 passing tests
+- Complete documentation and examples
+- TypeScript support with strict typing
+- Compatible with @objectql/types Driver interface
+
+### Security
+
+- **IMPORTANT**: Uses ExcelJS (v4.4.0) instead of xlsx library to avoid known security vulnerabilities
+- ExcelJS has no known CVEs and is actively maintained
+- Secure against ReDoS (Regular Expression Denial of Service) attacks
+- Protected from Prototype Pollution vulnerabilities
+
+### Features
+
+- ✅ Read from existing Excel files
+- ✅ Write data back to Excel files
+- ✅ Create new Excel files automatically
+- ✅ Support for multiple object types (worksheets)
+- ✅ Filter operators: =, !=, >, >=, <, <=, in, nin, contains, startswith, endswith, between
+- ✅ Logical operators: AND, OR
+- ✅ Sorting (ascending/descending)
+- ✅ Pagination (skip/limit)
+- ✅ Field projection
+- ✅ Count and distinct queries
+- ✅ Error handling with ObjectQLError
+- ✅ Strict mode support
+- ✅ Auto-generated IDs
+- ✅ Timestamps (created_at, updated_at)
+- ✅ Async/await API with factory pattern
+
+### Dependencies
+
+- exceljs@^4.4.0 - Secure Excel file read/write library (actively maintained, no known CVEs)
+- @objectql/types@workspace:* - Core ObjectQL types
+
+### API Changes
+
+- Constructor requires async initialization via `ExcelDriver.create()` factory method
+- All file I/O operations are properly async for better performance

package/EXAMPLE.md

@@ -0,0 +1,198 @@
+# Excel Driver - Simple Example
+
+This example demonstrates how to use the Excel Driver for ObjectQL.
+
+## Installation
+
+```bash
+pnpm add @objectql/driver-excel
+```
+
+## Basic Usage
+
+```typescript
+import { ExcelDriver } from '@objectql/driver-excel';
+
+// Initialize driver with Excel file
+const driver = new ExcelDriver({
+  filePath: './data/mydata.xlsx',
+  createIfMissing: true,
+  autoSave: true
+});
+
+// Create records
+const user1 = await driver.create('users', {
+  name: 'Alice Johnson',
+  email: 'alice@example.com',
+  role: 'admin',
+  age: 30
+});
+
+const user2 = await driver.create('users', {
+  name: 'Bob Smith',
+  email: 'bob@example.com',
+  role: 'user',
+  age: 25
+});
+
+// Query records
+const allUsers = await driver.find('users');
+console.log('All users:', allUsers);
+
+// Filter records
+const admins = await driver.find('users', {
+  filters: [['role', '=', 'admin']]
+});
+console.log('Admin users:', admins);
+
+// Sort and paginate
+const sortedUsers = await driver.find('users', {
+  sort: [['age', 'desc']],
+  limit: 10
+});
+console.log('Sorted users:', sortedUsers);
+
+// Update a record
+await driver.update('users', user1.id, {
+  email: 'alice.new@example.com'
+});
+
+// Delete a record
+await driver.delete('users', user2.id);
+
+// Count records
+const count = await driver.count('users', {});
+console.log('Total users:', count);
+
+// Clean up
+await driver.disconnect();
+```
+
+## Advanced Features
+
+### Multiple Object Types (Worksheets)
+
+```typescript
+// Create products
+await driver.create('products', {
+  name: 'Laptop',
+  price: 999.99,
+  category: 'Electronics'
+});
+
+// Create orders
+await driver.create('orders', {
+  userId: user1.id,
+  productId: 'product-123',
+  quantity: 2,
+  total: 1999.98
+});
+
+// Each object type is stored in its own worksheet
+const products = await driver.find('products');
+const orders = await driver.find('orders');
+```
+
+### Complex Filters
+
+```typescript
+// AND conditions
+const results = await driver.find('users', {
+  filters: [
+    ['age', '>', 18],
+    ['role', '=', 'admin']
+  ]
+});
+
+// OR conditions
+const results2 = await driver.find('users', {
+  filters: [
+    ['role', '=', 'admin'],
+    'or',
+    ['role', '=', 'moderator']
+  ]
+});
+
+// Contains search
+const searchResults = await driver.find('users', {
+  filters: [['name', 'contains', 'john']]
+});
+```
+
+### Bulk Operations
+
+```typescript
+// Create many
+await driver.createMany('users', [
+  { name: 'User 1', email: 'user1@example.com' },
+  { name: 'User 2', email: 'user2@example.com' },
+  { name: 'User 3', email: 'user3@example.com' }
+]);
+
+// Update many
+await driver.updateMany(
+  'users',
+  [['role', '=', 'user']],
+  { role: 'member' }
+);
+
+// Delete many
+await driver.deleteMany(
+  'users',
+  [['status', '=', 'inactive']]
+);
+```
+
+### Manual Save Control
+
+```typescript
+// Disable auto-save for batch operations
+const driver = new ExcelDriver({
+  filePath: './data/batch.xlsx',
+  autoSave: false
+});
+
+// Perform multiple operations
+for (let i = 0; i < 1000; i++) {
+  await driver.create('records', { index: i });
+}
+
+// Save once at the end
+await driver.save();
+```
+
+## Excel File Structure
+
+The Excel file will look like this:
+
+**Sheet: users**
+| id | name | email | role | age | created_at | updated_at |
+|----|------|-------|------|-----|------------|------------|
+| users-1234-1 | Alice Johnson | alice@example.com | admin | 30 | 2024-01-01T... | 2024-01-01T... |
+| users-1234-2 | Bob Smith | bob@example.com | user | 25 | 2024-01-02T... | 2024-01-02T... |
+
+**Sheet: products**
+| id | name | price | category | created_at | updated_at |
+|----|------|-------|----------|------------|------------|
+| products-1234-1 | Laptop | 999.99 | Electronics | 2024-01-01T... | 2024-01-01T... |
+
+## Use Cases
+
+1. **Data Import/Export**: Import existing Excel data or export application data to Excel
+2. **Prototyping**: Quick database for development without setting up a real database
+3. **Reports**: Generate Excel reports from application data
+4. **Data Migration**: Migrate data from Excel to other databases
+5. **Small Projects**: Simple storage for projects with limited data needs
+
+## Performance Considerations
+
+- Best for datasets < 10,000 records per sheet
+- All operations are in-memory (fast queries, but uses RAM)
+- Auto-save writes to disk on every change (disable for batch operations)
+- Not suitable for concurrent multi-process access
+
+## Next Steps
+
+- Explore the [full API documentation](../README.md)
+- Check out other drivers: [SQL](../../sql), [MongoDB](../../mongo), [Memory](../../memory)
+- Learn about [ObjectQL](../../../README.md)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ObjectQL Contributors (https://github.com/objectql)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.