Add support for unified save() method on DbRecord

Author: graknol

declarative_sqlite/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 1.2.0
+
+### Features
+- **Unified Save Method**: Enhanced `DbRecord.save()` to automatically handle both insert and update operations
+  - `save()` now intelligently detects whether a record is new (needs INSERT) or existing (needs UPDATE)
+  - Eliminates the need to manually choose between `insert()` and `save()` for updates
+  - Added `isNewRecord` property to check whether a record needs insertion
+  - Deprecated explicit `insert()` method in favor of unified `save()` approach
+  - After successful insert via `save()`, record data is automatically refreshed with all system columns
+  - Multiple consecutive `save()` calls work seamlessly on the same record
+
+### Developer Experience
+- Simplified CRUD workflow - just use `save()` for everything
+- Reduced cognitive load - no need to track insert vs update state manually
+- Better API consistency across create and update operations
+
+### Documentation
+- Updated data modeling guide with unified save examples
+- Enhanced CRUD operations documentation with recommended patterns
+- Added comprehensive example demonstrating unified save approach
+
 ## 1.1.0
 
 ### Features

declarative_sqlite/lib/src/db_record.dart

@@ -23,13 +23,19 @@ abstract class DbRecord {
 
   /// Map to track which fields have been modified since creation
   final Set<String> _modifiedFields = <String>{};
+  
+  /// Tracks whether this is a new record (needs insert) or existing (needs update)
+  /// True if record was created without a system_id (new record to be inserted)
+  /// False if record was loaded from database (existing record to be updated)
+  bool _isNewRecord;
 
   DbRecord(Map<String, Object?> data, this._tableName, this._database)
     : _data = Map<String, Object?>.from(data), 
     _tableDefinition = _database.schema.userTables.firstWhereOrNull(
         (table) => table.name == _tableName,
       ),
-      _updateTableName = _tableName;
+      _updateTableName = _tableName,
+      _isNewRecord = data['system_id'] == null;
 
   /// Gets the table name for this record
   String get tableName => _tableName;
@@ -61,6 +67,10 @@ abstract class DbRecord {
 
   /// Gets the set of fields that have been modified (read-only copy)
   Set<String> get modifiedFields => Set.unmodifiable(_modifiedFields);
+  
+  /// Returns true if this record needs to be inserted (new record)
+  /// Returns false if this record already exists and needs to be updated
+  bool get isNewRecord => _isNewRecord;
 
   /// Gets the system_id for this record
   String? get systemId => getRawValue('system_id') as String?;
@@ -285,21 +295,37 @@ abstract class DbRecord {
   void setFilesetField(String columnName, FilesetField? value) =>
       setValue(columnName, value);
 
-  /// Saves any modified fields back to the database
+  /// Saves the record to the database.
+  /// 
+  /// Automatically determines whether to insert (for new records) or update (for existing records).
+  /// - For new records (created without system_id): performs an INSERT
+  /// - For existing records (loaded from database): performs an UPDATE of modified fields only
+  /// 
   /// Throws StateError if the target table doesn't support CRUD operations
   Future<void> save() async {
     _checkCrudPermission('save');
 
+    if (_isNewRecord) {
+      // New record - perform insert
+      await _performInsert();
+    } else {
+      // Existing record - perform update of modified fields
+      await _performUpdate();
+    }
+  }
+  
+  /// Internal method to perform the actual update operation
+  Future<void> _performUpdate() async {
     if (_modifiedFields.isEmpty) return;
 
     final systemId = this.systemId;
     if (systemId == null) {
-      throw StateError('Cannot save record without system_id');
+      throw StateError('Cannot update record without system_id');
     }
 
     final systemVersion = this.systemVersion;
     if (systemVersion == null) {
-      throw StateError('Cannot save record without system_version');
+      throw StateError('Cannot update record without system_version');
     }
 
     // Build update map with only modified fields (excluding system columns)
@@ -323,19 +349,55 @@ abstract class DbRecord {
     // Clear modified fields after successful save
     _modifiedFields.clear();
   }
+  
+  /// Internal method to perform the actual insert operation
+  Future<void> _performInsert() async {
+    // Remove system columns - they'll be added by the database layer
+    final insertData = Map<String, Object?>.from(_data);
+    insertData.removeWhere((key, value) => key.startsWith('system_'));
+
+    final systemId = await _database.insert(_updateTableName ?? _tableName, insertData);
+    
+    // Reload the record from database to get all system columns
+    final results = await _database.queryTable(
+      _updateTableName ?? _tableName,
+      where: 'system_id = ?',
+      whereArgs: [systemId],
+    );
+    
+    if (results.isEmpty) {
+      throw StateError('Failed to reload record after insert');
+    }
+    
+    // Update the record's data with fresh data from database
+    _data.clear();
+    _data.addAll(results.first);
+    _isNewRecord = false;
+
+    // Clear modified fields since this is now persisted
+    _modifiedFields.clear();
+  }
 
   /// Creates a new record in the database with the current data
+  /// 
+  /// Note: Consider using `save()` instead, which automatically handles both insert and update.
+  /// 
   /// Throws StateError if the target table doesn't support CRUD operations
+  @Deprecated('Use save() instead, which automatically handles insert vs update')
   Future<void> insert() async {
     _checkCrudPermission('insert');
 
     // Remove system columns - they'll be added by the database layer
     final insertData = Map<String, Object?>.from(_data);
     insertData.removeWhere((key, value) => key.startsWith('system_'));
 
-    await _database.insert(_updateTableName ?? _tableName, insertData);
+    final systemId = await _database.insert(_updateTableName ?? _tableName, insertData);
+    
+    // Update the record's data with the new system_id and mark as no longer new
+    _data['system_id'] = systemId;
+    _isNewRecord = false;
 
-    // Clear modified fields since this is a new record
+    // Clear modified fields since this is now persisted
     _modifiedFields.clear();
   }
 
@@ -381,6 +443,9 @@ abstract class DbRecord {
     // Update the data map with fresh data
     _data.clear();
     _data.addAll(results.first);
+    
+    // Mark as existing record since we just loaded from database
+    _isNewRecord = false;
 
     // Clear modified fields since we have fresh data
     _modifiedFields.clear();

declarative_sqlite/pubspec.yaml

@@ -1,6 +1,6 @@
 name: declarative_sqlite
 description: A dart package for declaratively creating SQLite tables and automatically migrating them.
-version: 1.1.0
+version: 1.2.0
 repository: https://github.com/graknol/declarative_sqlite
 
 environment:

declarative_sqlite/test/unified_save_test.dart

@@ -0,0 +1,210 @@
+import 'package:declarative_sqlite/declarative_sqlite.dart';
+import 'package:declarative_sqlite/src/files/filesystem_file_repository.dart';
+import 'package:sqflite_common_ffi/sqflite_ffi.dart';
+import 'package:test/test.dart';
+
+void main() {
+  sqfliteFfiInit();
+  final databaseFactory = databaseFactoryFfi;
+
+  group('Unified save() method', () {
+    late DeclarativeDatabase database;
+
+    setUp(() async {
+      final schema = SchemaBuilder()
+          .table('users', (table) {
+            table.text('name').notNull('');
+            table.integer('age').notNull(0);
+            table.text('email').lww();
+            table.key(['system_id']).primary();
+          })
+          .build();
+
+      database = await DeclarativeDatabase.open(
+        ':memory:',
+        databaseFactory: databaseFactory,
+        schema: schema,
+        fileRepository: FilesystemFileRepository('temp_test'),
+      );
+    });
+
+    test('save() inserts a new record when created without system_id', () async {
+      // Create a new record without system_id
+      final record = GenericDbRecord({
+        'name': 'Alice',
+        'age': 30,
+        'email': 'alice@example.com',
+      }, 'users', database);
+
+      // Verify it's marked as new
+      expect(record.isNewRecord, isTrue);
+      expect(record.systemId, isNull);
+
+      // Save should perform an INSERT
+      await record.save();
+
+      // After save, should no longer be new and should have system_id
+      expect(record.isNewRecord, isFalse);
+      expect(record.systemId, isNotNull);
+
+      // Verify the record exists in database
+      final results = await database.queryTable('users');
+      expect(results.length, 1);
+      expect(results[0]['name'], 'Alice');
+      expect(results[0]['age'], 30);
+      expect(results[0]['email'], 'alice@example.com');
+    });
+
+    test('save() updates an existing record when loaded from database', () async {
+      // First insert a record directly
+      final systemId = await database.insert('users', {
+        'name': 'Bob',
+        'age': 25,
+        'email': 'bob@example.com',
+      });
+
+      // Load the record from database
+      final results = await database.queryTable('users', 
+        where: 'system_id = ?', 
+        whereArgs: [systemId]
+      );
+      final record = GenericDbRecord(results[0], 'users', database);
+
+      // Verify it's marked as existing
+      expect(record.isNewRecord, isFalse);
+      expect(record.systemId, systemId);
+
+      // Modify the record
+      record.setValue('email', 'bob.updated@example.com');
+
+      // Save should perform an UPDATE
+      await record.save();
+
+      // Verify the update
+      final updatedResults = await database.queryTable('users',
+        where: 'system_id = ?',
+        whereArgs: [systemId]
+      );
+      expect(updatedResults.length, 1);
+      expect(updatedResults[0]['name'], 'Bob'); // Unchanged
+      expect(updatedResults[0]['age'], 25); // Unchanged
+      expect(updatedResults[0]['email'], 'bob.updated@example.com'); // Updated
+    });
+
+    test('save() can be called multiple times on the same record', () async {
+      // Create new record
+      final record = GenericDbRecord({
+        'name': 'Charlie',
+        'age': 35,
+        'email': 'charlie@example.com',
+      }, 'users', database);
+
+      // First save - inserts
+      await record.save();
+      expect(record.isNewRecord, isFalse);
+      final systemId = record.systemId;
+      expect(systemId, isNotNull);
+
+      // Modify and save again - updates (using LWW column)
+      record.setValue('email', 'charlie.updated@example.com');
+      await record.save();
+
+      // Verify update worked
+      final results = await database.queryTable('users',
+        where: 'system_id = ?',
+        whereArgs: [systemId]
+      );
+      expect(results.length, 1);
+      expect(results[0]['email'], 'charlie.updated@example.com');
+
+      // Modify and save one more time - updates again
+      record.setValue('email', 'charlie.new@example.com');
+      await record.save();
+
+      // Verify second update worked
+      final results2 = await database.queryTable('users',
+        where: 'system_id = ?',
+        whereArgs: [systemId]
+      );
+      expect(results2.length, 1);
+      expect(results2[0]['email'], 'charlie.new@example.com');
+    });
+
+    test('save() handles empty modifications on existing record', () async {
+      // Insert and load a record
+      final systemId = await database.insert('users', {
+        'name': 'Diana',
+        'age': 28,
+        'email': 'diana@example.com',
+      });
+
+      final results = await database.queryTable('users',
+        where: 'system_id = ?',
+        whereArgs: [systemId]
+      );
+      final record = GenericDbRecord(results[0], 'users', database);
+
+      // Call save without modifications
+      await record.save();
+
+      // Should complete without error
+      expect(record.isNewRecord, isFalse);
+      expect(record.systemId, systemId);
+    });
+
+    test('reload() maintains correct isNewRecord state', () async {
+      // Insert a record
+      final systemId = await database.insert('users', {
+        'name': 'Eve',
+        'age': 32,
+        'email': 'eve@example.com',
+      });
+
+      // Load the record
+      final results = await database.queryTable('users',
+        where: 'system_id = ?',
+        whereArgs: [systemId]
+      );
+      final record = GenericDbRecord(results[0], 'users', database);
+
+      expect(record.isNewRecord, isFalse);
+
+      // Reload the record
+      await record.reload();
+
+      // Should still not be a new record
+      expect(record.isNewRecord, isFalse);
+      expect(record.systemId, systemId);
+    });
+
+    test('isNewRecord getter provides correct state', () async {
+      // New record
+      final newRecord = GenericDbRecord({
+        'name': 'Frank',
+        'age': 40,
+      }, 'users', database);
+      expect(newRecord.isNewRecord, isTrue);
+
+      // Existing record
+      final systemId = await database.insert('users', {
+        'name': 'Grace',
+        'age': 29,
+      });
+      final results = await database.queryTable('users',
+        where: 'system_id = ?',
+        whereArgs: [systemId]
+      );
+      final existingRecord = GenericDbRecord(results[0], 'users', database);
+      expect(existingRecord.isNewRecord, isFalse);
+    });
+  });
+}
+
+/// A generic DbRecord implementation for testing
+class GenericDbRecord extends DbRecord {
+  GenericDbRecord(
+    Map<String, Object?> data,
+    String tableName,
+    DeclarativeDatabase database,
+  ) : super(data, tableName, database);
+}