diff --git a/CHANGELOG.md b/CHANGELOG.md index cab39e1d..34ac5d26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,28 @@ +## 1.35.2 + +- `DBSQLMemoryAdapter`: single-field unique constraints + (`@EntityField.unique()`) are now enforced as by the SQL databases: + - On an `EntityReference` field: the entity's value (the `EntityReference` + object) was compared with the stored value (the referenced ID), so it + never conflicted. `EntityFieldInvalid.value` of such a violation is the + referenced ID. + - On a camelCase field (e.g. `externalCode`, stored as `external_code`): + the stored entry was read by the field name only, so it never + conflicted. **In-memory tests storing duplicates of such a field now + fail, as they would on PostgreSQL/MySQL/SQLite.** + - An `enum` field is compared by its stored name. + + The single-field and composite (`@EntityIndex(unique: true)`) constraints + are now checked together: the entity's values normalized once, in their + stored form, and a `null` value never conflicting. Values of the same + type are now the same only by `==` (no longer also by `toString()`). +- `SetEntityRepository`: a unique `EntityReference` field compares the + referenced ID, and a null reference never conflicts (two rows with a null + reference were a violation; a reference by entity and one by ID could + differ). +- Test: the unsendable-`Zone` isolate test accepts Dart 3.14's message + (`Class: Zone`, was `_CustomZone`). + ## 1.35.1 - Private fields that only memoize a public getter or method of the same diff --git a/lib/src/bones_api_base.dart b/lib/src/bones_api_base.dart index 3b306479..0180aa25 100644 --- a/lib/src/bones_api_base.dart +++ b/lib/src/bones_api_base.dart @@ -52,7 +52,7 @@ typedef APILogger = void Function( /// Bones API Library class. class BonesAPI { // ignore: constant_identifier_names - static const String VERSION = '1.35.1'; + static const String VERSION = '1.35.2'; static bool _boot = false; diff --git a/lib/src/bones_api_entity.dart b/lib/src/bones_api_entity.dart index 0541bf96..b839bdb1 100644 --- a/lib/src/bones_api_entity.dart +++ b/lib/src/bones_api_entity.dart @@ -8818,7 +8818,9 @@ abstract class IterableEntityRepository for (var e in uniques) { var field = e.key; - var value = getField(o, field); + var value = _uniqueComparableValue(getField(o, field)); + // As the SQL databases: a `null` value (or a null reference) never + // conflicts. if (value == null) continue; if (_containsOtherEntryWithFieldValue(o, field, value)) { @@ -8833,8 +8835,21 @@ abstract class IterableEntityRepository } } + /// The [value] of a unique field as compared by [checkEntityFields] and + /// [_containsOtherEntryWithFieldValue]: an `EntityReference` by its + /// referenced ID (or its entity, if not stored yet), and `null` for a null + /// reference (that, as `null`, never conflicts). `EntityReference.==` would + /// make two null references equal, and a reference set by entity differ + /// from one set by ID. + static Object? _uniqueComparableValue(Object? value) => switch (value) { + EntityReference() => value.isNull ? null : (value.id ?? value.entity), + EntityReferenceList() => value.isNull ? null : value, + _ => value, + }; + /// Whether an entry other than [o] (not the same instance, nor with the - /// same ID: a re-stored entity) has the [field] [value]. + /// same ID: a re-stored entity) has the [field] [value] (already as + /// [_uniqueComparableValue]). bool _containsOtherEntryWithFieldValue(O o, String field, Object value) { var id = entityHandler.getID(o); @@ -8842,7 +8857,7 @@ abstract class IterableEntityRepository if (identical(elem, o)) return false; if (id != null && entityHandler.getID(elem) == id) return false; - var elemValue = getField(elem, field); + var elemValue = _uniqueComparableValue(getField(elem, field)); return elemValue == value; }); } diff --git a/lib/src/bones_api_entity_db_memory.dart b/lib/src/bones_api_entity_db_memory.dart index b2819240..9b642b4b 100644 --- a/lib/src/bones_api_entity_db_memory.dart +++ b/lib/src/bones_api_entity_db_memory.dart @@ -401,60 +401,47 @@ class DBSQLMemoryAdapter extends DBSQLAdapter o, ); - var uniques = - fieldsEntityAnnotations?.entries - .where((e) => e.value.hasUnique) - .toList() ?? - []; + // The unique constraints, by their fields: the single-field ones + // (`@EntityField.unique()`) and the composite ones + // (`@EntityIndex(unique: true)`), checked the same way. + var uniquesFields = >[ + ...?fieldsEntityAnnotations?.entries + .where((e) => e.value.hasUnique) + .map((e) => [e.key]), + for (var entityIndex in entityHandler.getEntityIndexes()) + if (entityIndex.unique) entityIndex.fields, + ]; + if (uniquesFields.isEmpty) return; + + // The entity's values in their stored form (normalized as an entry: e.g. + // an `EntityReference` as its referenced ID, not the reference object), + // so they are comparable with the stored entries. Normalized once for + // all the constraints. + var values = _normalizeEntityJSON( + { + for (var f in uniquesFields.expand((fields) => fields)) + f: entityHandler.getField(o, f), + }, + entityName: entityName, + table: table, + ); - for (var e in uniques) { - var field = e.key; - var value = entityHandler.getField(o, field); - if (value == null) continue; + for (var fields in uniquesFields) { + // As the SQL databases: a `null` value never conflicts. + if (fields.any((f) => values[f] == null)) continue; - if (_containsEntryWithConflictFieldValue( + if (_containsEntryWithConflictFieldsValues( map, - entityHandler, entityId, - field, - value, + fields, + values, )) { + var single = fields.length == 1; throw EntityFieldInvalid( 'unique', - value, - fieldName: field, - entityType: entityHandler.type, - tableName: table, - ); - } - } - - // The composite unique constraints (`@EntityIndex(unique: true)`), as - // the SQL databases: a `null` value never conflicts. - for (var entityIndex in entityHandler.getEntityIndexes()) { - if (!entityIndex.unique) continue; - - var fields = entityIndex.fields; - - var values = _normalizeEntityJSON({ - for (var f in fields) f: entityHandler.getField(o, f), - }, table: table); - if (values.values.any((v) => v == null)) continue; - - var conflict = map.entries.any((e) { - if (entityId != null && entityId == e.key) return false; - var elem = e.value; - return fields.every( - (f) => _sameValue(_entryFieldValue(elem, f), values[f]), - ); - }); - - if (conflict) { - throw EntityFieldInvalid( - 'unique', - fields.map((f) => values[f]).toList(), + single ? values[fields.first] : fields.map((f) => values[f]).toList(), fieldName: fields.join(', '), - fieldsNames: fields, + fieldsNames: single ? null : fields, entityType: entityHandler.type, tableName: table, ); @@ -464,9 +451,15 @@ class DBSQLMemoryAdapter extends DBSQLAdapter /// Whether a stored value [a] and an entity's value [b] are the same, as /// stored (e.g. an `enum` by its name). + /// + /// The stored forms are compared only when the types differ (an entity's + /// `Enum` against its stored name): values of the same type are only the + /// same by `==` (two distinct values of a class without a distinctive + /// `toString` are not the same). static bool _sameValue(Object? a, Object? b) { if (a == b) return true; if (a == null || b == null) return false; + if (a.runtimeType == b.runtimeType) return false; return _storedForm(a) == _storedForm(b); } @@ -482,22 +475,24 @@ class DBSQLMemoryAdapter extends DBSQLAdapter ? entry[field] : entry[normalizeColumnName(field)]; - bool _containsEntryWithConflictFieldValue( + /// Whether a stored entry of [map], other than [entityId]'s own, has the + /// same [values] in all the [fields] (a unique constraint conflict). + /// + /// Used by [checkEntityFields] for each unique constraint (single-field or + /// composite), with the entity's [values] already in their stored form: + /// each entry's field is read by name or column ([_entryFieldValue]) and + /// compared with [_sameValue]. + bool _containsEntryWithConflictFieldsValues( Map> map, - EntityHandler entityHandler, Object? entityId, - String field, - value, + List fields, + Map values, ) => map.entries.any((e) { - if (entityId != null) { - var id = e.key; - if (entityId == id) return false; - } - + if (entityId != null && entityId == e.key) return false; var elem = e.value; - var elemValue = elem[field]; - var conflict = elemValue == value; - return conflict; + return fields.every( + (f) => _sameValue(_entryFieldValue(elem, f), values[f]), + ); }); @override diff --git a/pubspec.yaml b/pubspec.yaml index e634d10e..1084cb35 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: bones_api description: Bones_API - A powerful API backend framework for Dart. It comes with a built-in HTTP Server, route handler, entity handler, SQL translator, and DB adapters. -version: 1.35.1 +version: 1.35.2 homepage: https://github.com/Colossus-Services/bones_api environment: diff --git a/test/bones_api_cov_root_test.dart b/test/bones_api_cov_root_test.dart index cbfb08d1..d6538e60 100644 --- a/test/bones_api_cov_root_test.dart +++ b/test/bones_api_cov_root_test.dart @@ -605,11 +605,14 @@ void main() { await root.ensureInitialized(); var zoneField = root.currentAPIRequest; + // The unsendable object is a `Zone`. The SDK names its class in the + // message: `_CustomZone` (Dart < 3.14) or `Zone` (Dart 3.14), so only + // `Zone` is matched (as a class name, not just the word "zone"). Matcher unsendable() => throwsA( isA().having( (e) => e.toString(), 'message', - contains('_CustomZone'), + matches(RegExp(r'Class: _?\w*Zone\b|_CustomZone')), ), ); diff --git a/test/bones_api_entity_index_test.dart b/test/bones_api_entity_index_test.dart index 991c2175..14549a64 100644 --- a/test/bones_api_entity_index_test.dart +++ b/test/bones_api_entity_index_test.dart @@ -45,6 +45,198 @@ class _RoleTestProvider extends EntityRepositoryProvider { } } +/// A referenced entity, for the unique `EntityReference` field of +/// [_Withdrawal]. +class _Wallet extends Entity { + int? id; + String name; + + _Wallet({this.id, this.name = ''}); + + @override + String get idFieldName => 'id'; + + @override + List get fieldsNames => const ['id', 'name']; + + @override + V? getField(String key) => switch (key) { + 'id' => id as V?, + 'name' => name as V?, + _ => null, + }; + + @override + TypeInfo? getFieldType(String key) => switch (key) { + 'id' => TypeInfo.tInt, + 'name' => TypeInfo.tString, + _ => null, + }; + + @override + void setField(String key, V? value) { + switch (key) { + case 'id': + id = value as int?; + case 'name': + name = value as String; + } + } + + @override + Map toJson() => {'id': id, 'name': name}; +} + +final _walletHandler = GenericEntityHandler<_Wallet>( + instantiatorDefault: _Wallet.new, + sampleEntity: _Wallet(), +); + +/// An entity with single-field unique fields (`@EntityField.unique()`): an +/// `EntityReference` (`pendingWallet`), a `String` (`externalCode`) and an +/// `enum` (`kind`). All named in camelCase, so their columns +/// (`pending_wallet`, `external_code`) differ from the field names. +class _Withdrawal extends Entity { + int? id; + EntityReference<_Wallet> pendingWallet; + String? externalCode; + RoleType? kind; + int amount; + + _Withdrawal({ + this.id, + Object? pendingWallet, + this.externalCode, + this.kind, + this.amount = 0, + }) : pendingWallet = EntityReference<_Wallet>.from( + pendingWallet, + entityHandler: _walletHandler, + ); + + @override + String get idFieldName => 'id'; + + @override + List get fieldsNames => const [ + 'id', + 'pendingWallet', + 'externalCode', + 'kind', + 'amount', + ]; + + @override + V? getField(String key) => switch (key) { + 'id' => id as V?, + 'pendingWallet' => pendingWallet as V?, + 'externalCode' => externalCode as V?, + 'kind' => kind as V?, + 'amount' => amount as V?, + _ => null, + }; + + @override + TypeInfo? getFieldType(String key) => switch (key) { + 'id' || 'amount' => TypeInfo.tInt, + 'pendingWallet' => TypeInfo>.fromType( + EntityReference, + [TypeInfo<_Wallet>(_Wallet)], + ), + 'externalCode' => TypeInfo.tString, + 'kind' => TypeInfo(RoleType), + _ => null, + }; + + @override + List? getFieldEntityAnnotations(String key) => + switch (key) { + 'pendingWallet' || + 'externalCode' || + 'kind' => const [EntityField.unique()], + _ => null, + }; + + @override + void setField(String key, V? value) { + switch (key) { + case 'id': + id = value as int?; + case 'pendingWallet': + pendingWallet = EntityReference<_Wallet>.from( + value, + entityHandler: _walletHandler, + ); + case 'externalCode': + externalCode = value as String?; + case 'kind': + kind = value == null + ? null + : (value is RoleType ? value : RoleType.values.byName('$value')); + case 'amount': + amount = value as int; + } + } + + @override + Map toJson() => { + 'id': id, + 'pendingWallet': pendingWallet.toJson(), + 'externalCode': externalCode, + 'kind': kind?.name, + 'amount': amount, + }; +} + +final _withdrawalHandler = GenericEntityHandler<_Withdrawal>( + instantiatorDefault: _Withdrawal.new, + sampleEntity: _Withdrawal(), +); + +/// A provider with a [DBSQLMemoryAdapter] and the [_Wallet] and +/// [_Withdrawal] repositories. +class _WithdrawalTestProvider extends EntityRepositoryProvider { + late final DBSQLMemoryAdapter sqlAdapter; + + _WithdrawalTestProvider() { + sqlAdapter = DBSQLMemoryAdapter(parentRepositoryProvider: this); + DBSQLEntityRepository<_Wallet>(sqlAdapter, 'wallet', _walletHandler); + DBSQLEntityRepository<_Withdrawal>( + sqlAdapter, + 'withdrawal', + _withdrawalHandler, + ); + + addTearDown(() { + sqlAdapter.close(); + close(); + }); + } +} + +/// A provider with [SetEntityRepository]s for [_Wallet] and [_Withdrawal] +/// (the in-memory repository without an adapter). +class _WithdrawalSetTestProvider extends EntityRepositoryProvider { + _WithdrawalSetTestProvider() { + var wallets = SetEntityRepository<_Wallet>( + 'wallet', + _walletHandler, + provider: this, + )..ensureInitialized(); + var withdrawals = SetEntityRepository<_Withdrawal>( + 'withdrawal', + _withdrawalHandler, + provider: this, + )..ensureInitialized(); + + addTearDown(() { + wallets.close(); + withdrawals.close(); + close(); + }); + } +} + /// An entity with a hidden field (`secret`), for [GenericEntityHandler]. class _SecretEntity extends Entity { int? id; @@ -1249,6 +1441,146 @@ void main() { ); }); + for (var (repositoryKind, newProvider) + in <(String, EntityRepositoryProvider Function())>[ + ('DBSQLMemoryAdapter', _WithdrawalTestProvider.new), + ('SetEntityRepository', _WithdrawalSetTestProvider.new), + ]) { + test( + '$repositoryKind: unique camelCase `String` and `enum` fields (`@EntityField.unique()`)', + () async { + var provider = newProvider(); + var withdrawals = provider.getEntityRepositoryByType<_Withdrawal>( + _Withdrawal, + )!; + + Future storeError(_Withdrawal o) async { + try { + await withdrawals.store(o); + } on EntityFieldInvalid catch (e) { + return e; + } + return null; + } + + expect( + await withdrawals.store( + _Withdrawal(externalCode: 'A', kind: RoleType.admin), + ), + isNotNull, + ); + expect( + await withdrawals.store( + _Withdrawal(externalCode: 'B', kind: RoleType.guest), + ), + isNotNull, + ); + // `null` values never conflict: + expect(await withdrawals.store(_Withdrawal()), isNotNull); + expect(await withdrawals.store(_Withdrawal()), isNotNull); + + var codeError = await storeError(_Withdrawal(externalCode: 'A')); + expect(codeError?.reason, 'unique'); + expect(codeError?.fieldName, 'externalCode'); + expect(codeError?.value, 'A'); + + var kindError = await storeError(_Withdrawal(kind: RoleType.guest)); + expect(kindError?.reason, 'unique'); + expect(kindError?.fieldName, 'kind'); + + expect((await withdrawals.selectAll()).length, 4); + }, + ); + + test( + '$repositoryKind: a unique `EntityReference` field (`@EntityField.unique()`)', + () async { + var provider = newProvider(); + var wallets = provider.getEntityRepositoryByType<_Wallet>(_Wallet)!; + var withdrawals = provider.getEntityRepositoryByType<_Withdrawal>( + _Withdrawal, + )!; + + var w1 = _Wallet(name: 'w1'); + var w2 = _Wallet(name: 'w2'); + expect(await wallets.store(w1), isNotNull); + expect(await wallets.store(w2), isNotNull); + + Future storeError(_Withdrawal o) async { + try { + await withdrawals.store(o); + } on EntityFieldInvalid catch (e) { + return e; + } + return null; + } + + // Referenced by entity: + var d1 = _Withdrawal(pendingWallet: w1, amount: 10); + expect(await withdrawals.store(d1), isNotNull); + + // Another wallet: OK. + var d2 = _Withdrawal(pendingWallet: w2.id, amount: 20); + expect(await withdrawals.store(d2), isNotNull); + + // `null` references never conflict (as the SQL databases): + expect(await withdrawals.store(_Withdrawal(amount: 1)), isNotNull); + expect(await withdrawals.store(_Withdrawal(amount: 2)), isNotNull); + + // The same wallet, referenced by ID: a violation. + var error = await storeError(_Withdrawal(pendingWallet: w1.id)); + expect(error, isNotNull); + expect(error!.reason, 'unique'); + expect(error.fieldName, 'pendingWallet'); + expect(error.value, w1.id); + expect(error.tableName, 'withdrawal'); + + // The same wallet, referenced by entity: a violation. + expect( + (await storeError(_Withdrawal(pendingWallet: w2)))?.reason, + 'unique', + ); + + // Updating itself (the same wallet): OK. + d1.amount = 11; + expect(await withdrawals.store(d1), d1.id); + + // Updating into the other's wallet: a violation. + d2.pendingWallet = EntityReference<_Wallet>.from( + w1, + entityHandler: _walletHandler, + ); + expect((await storeError(d2))?.fieldName, 'pendingWallet'); + // Not stored: back to its wallet. + d2.pendingWallet = EntityReference<_Wallet>.from( + w2.id, + entityHandler: _walletHandler, + ); + + // A reference to a not stored wallet (no ID yet): never the same as + // a stored wallet's. + expect( + await storeError( + _Withdrawal(pendingWallet: _Wallet(name: 'new'), amount: 3), + ), + isNull, + ); + + expect( + (await withdrawals.selectAll()) + .where((e) => e.amount != 3) + .map((e) => '${e.pendingWallet.id}/${e.amount}') + .toList(), + unorderedEquals(['${w1.id}/11', '${w2.id}/20', 'null/1', 'null/2']), + ); + expect( + (await withdrawals.selectAll()).where((e) => e.amount == 3).length, + 1, + ); + }, + ); + } + test('SQLite: the columns of a composite constraint message', () { var (table, columns) = DBSQLiteAdapter.parseConstraintTableFields( 'UNIQUE constraint failed: sales_day.establishment, sales_day.day',