Review and improve FileSystem driver: Add initialData support, utility methods, Chinese docs, and enhanced error handling

Co-authored-by: huangyiirene <[email protected]>

Author: Copilot

packages/drivers/fs/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to the @objectql/driver-fs package will be documented in this file.
 
+## [0.1.1] - 2024-01-16
+
+### Added
+- `initialData` configuration option to pre-populate data on initialization
+- `clear(objectName)` method to clear all data for a specific object
+- `clearAll()` method to clear all data from all objects
+- `invalidateCache(objectName)` method to force cache reload
+- `getCacheSize()` method to get the number of cached objects
+- Chinese documentation (README.zh-CN.md)
+- Better error handling for invalid JSON files
+- Support for empty JSON files
+
+### Improved
+- Enhanced JSON parse error messages with more detailed information
+- Better documentation with examples for all new features
+- Added 7 new test cases (total: 36 tests)
+- TypeScript configuration for proper workspace resolution
+
 ## [0.1.0] - 2024-01-16
 
 ### Added

packages/drivers/fs/README.md

@@ -2,6 +2,8 @@
 
 File System Driver for ObjectQL - JSON file-based persistent storage with one file per table.
 
+> **中文文档**: [README.zh-CN.md](./README.zh-CN.md)
+
 ## Features
 
 ✅ **Persistent Storage** - Data survives process restarts  
@@ -80,6 +82,9 @@ interface FileSystemDriverConfig {
 
     /** Enable strict mode (throw on missing objects) (default: false) */
     strictMode?: boolean;
+    
+    /** Initial data to populate the store (optional) */
+    initialData?: Record<string, any[]>;
 }
 ```
 
@@ -90,7 +95,12 @@ const driver = new FileSystemDriver({
     dataDir: './data',
     prettyPrint: true,      // Human-readable JSON
     enableBackup: true,     // Create .bak files
-    strictMode: false       // Graceful handling of missing records
+    strictMode: false,      // Graceful handling of missing records
+    initialData: {          // Pre-populate with initial data
+        users: [
+            { id: 'admin', name: 'Admin User', role: 'admin' }
+        ]
+    }
 });
 ```
 
@@ -297,6 +307,24 @@ await products.create({
 
 ### Loading Initial Data
 
+**Method 1: Provide in configuration**
+
+```typescript
+const driver = new FileSystemDriver({
+    dataDir: './data',
+    initialData: {
+        users: [
+            { id: 'admin-001', name: 'Admin User', role: 'admin' }
+        ],
+        settings: [
+            { key: 'theme', value: 'dark' }
+        ]
+    }
+});
+```
+
+**Method 2: Pre-create JSON files**
+
 You can pre-populate JSON files:
 
 ```json
@@ -329,6 +357,22 @@ const testDriver = new FileSystemDriver({
 });
 ```
 
+### Utility Methods
+
+```typescript
+// Clear all data for a specific object
+await driver.clear('users');
+
+// Clear all data for all objects
+await driver.clearAll();
+
+// Invalidate cache for an object
+driver.invalidateCache('users');
+
+// Get cache size
+const size = driver.getCacheSize();
+```
+
 ## Comparison with Other Drivers
 
 | Feature | FileSystem | Memory | SQL | MongoDB |