From 0151728191020a5b95c42d674668418d904f9c99 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:13:39 -0300 Subject: [PATCH 01/40] Refactor conditions: ordering comparisons written once, shared helpers - condition: a private `_Ordering` enum (gt, gte, lt, lte; `mirrored`, `test`) behind the ordering methods of `ConditionParameter` and `Condition` (public methods kept as one-line delegates; the unused `keyType` documented), and a private `_KeyConditionOrdering` base of the four `KeyCondition{GreaterThan,...}` classes (constructors, `cast` and symbols kept). `encodeValue` moved into `KeyCondition`. - `ConditionParameter.matchesIn`: the parameters among the values are resolved once, not once per element. - `KeyConditionRegExp._literalRegExp` -> `_literalRegExpCache`, documented. - encoder: `isReservedWord` by a const set; `TypeInfo.from(valueType)` computed once; `EncodingContext.parameterValue`. - condition SQL: `_encodeIDComparison`, `_requireTableScheme`, `_writeEmptySetMatch`, `qualifiedColumnSQL`. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_condition.dart | 649 +++++++++-------------- lib/src/bones_api_condition_encoder.dart | 89 ++-- lib/src/bones_api_condition_sql.dart | 130 ++--- 3 files changed, 358 insertions(+), 510 deletions(-) diff --git a/lib/src/bones_api_condition.dart b/lib/src/bones_api_condition.dart index b012697c..d25d9a5d 100644 --- a/lib/src/bones_api_condition.dart +++ b/lib/src/bones_api_condition.dart @@ -270,27 +270,14 @@ class ConditionParameter extends ConditionElement { List? positionalParameters, Map? namedParameters, EntityHandler? entityHandler, - }) { - var myValue = getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ); - - var otherValue = value is ConditionParameter - ? value.getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ) - : value; - - return EntityHandler.graterThanValue( - myValue, - otherValue, - entityHandler: entityHandler, - ); - } + }) => _compareOrdering( + _Ordering.gt, + value, + parameters, + positionalParameters, + namedParameters, + entityHandler, + ); bool greaterThanOrEqual( Object? value, { @@ -298,27 +285,14 @@ class ConditionParameter extends ConditionElement { List? positionalParameters, Map? namedParameters, EntityHandler? entityHandler, - }) { - var myValue = getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ); - - var otherValue = value is ConditionParameter - ? value.getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ) - : value; - - return EntityHandler.graterThanOrEqualValue( - myValue, - otherValue, - entityHandler: entityHandler, - ); - } + }) => _compareOrdering( + _Ordering.gte, + value, + parameters, + positionalParameters, + namedParameters, + entityHandler, + ); bool lessThan( Object? value, { @@ -326,27 +300,14 @@ class ConditionParameter extends ConditionElement { List? positionalParameters, Map? namedParameters, EntityHandler? entityHandler, - }) { - var myValue = getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ); - - var otherValue = value is ConditionParameter - ? value.getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ) - : value; - - return EntityHandler.lessThanValue( - myValue, - otherValue, - entityHandler: entityHandler, - ); - } + }) => _compareOrdering( + _Ordering.lt, + value, + parameters, + positionalParameters, + namedParameters, + entityHandler, + ); bool lessThanOrEqual( Object? value, { @@ -354,7 +315,28 @@ class ConditionParameter extends ConditionElement { List? positionalParameters, Map? namedParameters, EntityHandler? entityHandler, - }) { + }) => _compareOrdering( + _Ordering.lte, + value, + parameters, + positionalParameters, + namedParameters, + entityHandler, + ); + + /// Compares this parameter's value (the left side) with [value] (the right + /// side, itself resolved if it's a [ConditionParameter]) by [ordering]. + /// + /// The shared body of [greaterThan], [greaterThanOrEqual], [lessThan] and + /// [lessThanOrEqual], which only differ by the [ordering]. + bool _compareOrdering( + _Ordering ordering, + Object? value, + Object? parameters, + List? positionalParameters, + Map? namedParameters, + EntityHandler? entityHandler, + ) { var myValue = getValue( parameters: parameters, positionalParameters: positionalParameters, @@ -369,11 +351,7 @@ class ConditionParameter extends ConditionElement { ) : value; - return EntityHandler.lessThanOrEqualValue( - myValue, - otherValue, - entityHandler: entityHandler, - ); + return ordering.test(myValue, otherValue, entityHandler); } bool matchesIn( @@ -391,18 +369,25 @@ class ConditionParameter extends ConditionElement { checkNotRegExpValue(myValue); - if (myValue is List) { - for (var v1 in myValue) { - checkNotRegExpValue(v1); - for (var v2 in values) { - var otherValue = v2 is ConditionParameter + // Resolve the parameters among [values] once, not once per element of + // `myValue` (`getValue` is pure, but it may convert the `parameters` + // object with `Json.toJson` on every call): + var otherValues = values + .map( + (v2) => v2 is ConditionParameter ? v2.getValue( parameters: parameters, positionalParameters: positionalParameters, namedParameters: namedParameters, ) - : v2; + : v2, + ) + .toList(); + if (myValue is List) { + for (var v1 in myValue) { + checkNotRegExpValue(v1); + for (var otherValue in otherValues) { var match = EntityHandler.equalsValuesBasic( v1, otherValue, @@ -414,15 +399,7 @@ class ConditionParameter extends ConditionElement { return false; } else { - for (var v2 in values) { - var otherValue = v2 is ConditionParameter - ? v2.getValue( - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ) - : v2; - + for (var otherValue in otherValues) { var match = EntityHandler.equalsValuesBasic( myValue, otherValue, @@ -472,6 +449,50 @@ class ConditionParameter extends ConditionElement { (contextPosition?.hashCode ?? 0); } +/// The four ordering comparisons of a condition (`>`, `>=`, `<`, `<=`). +/// +/// Written once here, instead of once per operator in [ConditionParameter], +/// [Condition] and the `KeyCondition` subclasses: used by +/// [ConditionParameter._compareOrdering], [Condition._orderingConditionValue] +/// and [_KeyConditionOrdering]. +enum _Ordering { + gt('>'), + gte('>='), + lt('<'), + lte('<='); + + /// The operator symbol, as encoded in a condition (see [Condition.encode]). + final String symbol; + + const _Ordering(this.symbol); + + /// The same comparison with its sides swapped: `a > b` is `b < a`. Used + /// when the [ConditionParameter] to resolve is the right side. + _Ordering get mirrored => switch (this) { + gt => lt, + gte => lte, + lt => gt, + lte => gte, + }; + + /// Compares [a] with [b] by the matching [EntityHandler] function. + bool test(Object? a, Object? b, EntityHandler? entityHandler) => + switch (this) { + gt => EntityHandler.graterThanValue(a, b, entityHandler: entityHandler), + gte => EntityHandler.graterThanOrEqualValue( + a, + b, + entityHandler: entityHandler, + ), + lt => EntityHandler.lessThanValue(a, b, entityHandler: entityHandler), + lte => EntityHandler.lessThanOrEqualValue( + a, + b, + entityHandler: entityHandler, + ), + }; +} + abstract class EntityMatcher { bool matchesEntity( O o, { @@ -558,6 +579,10 @@ abstract class Condition extends ConditionElement static bool _isToManyValues(Object? value1, Object? value2) => value1 is Iterable && value2 is! Iterable; + /// If [value1] `>` [value2] (see [_orderingConditionValue]). + /// + /// [keyType] is unused: kept for the API (and symmetry with + /// [equalsConditionValue]). bool greaterThanConditionValue( Object? value1, Object? value2, { @@ -566,47 +591,20 @@ abstract class Condition extends ConditionElement Map? namedParameters, TypeInfo? keyType, EntityHandler? keyEntityHandler, - }) { - if (_isToManyValues(value1, value2)) { - return (value1 as Iterable).any( - (v) => greaterThanConditionValue( - v, - value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyType, - keyEntityHandler: keyEntityHandler, - ), - ); - } - - if (value1 is ConditionParameter) { - return value1.greaterThan( - value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, - ); - } else if (value2 is ConditionParameter) { - return value2.lessThan( - value1, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, - ); - } else { - var match = EntityHandler.graterThanValue( - value1, - value2, - entityHandler: keyEntityHandler, - ); - return match; - } - } + }) => _orderingConditionValue( + _Ordering.gt, + value1, + value2, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, + ); + /// If [value1] `>=` [value2] (see [_orderingConditionValue]). + /// + /// [keyType] is unused: kept for the API (and symmetry with + /// [equalsConditionValue]). bool greaterThanOrEqualConditionValue( Object? value1, Object? value2, { @@ -615,47 +613,20 @@ abstract class Condition extends ConditionElement Map? namedParameters, TypeInfo? keyType, EntityHandler? keyEntityHandler, - }) { - if (_isToManyValues(value1, value2)) { - return (value1 as Iterable).any( - (v) => greaterThanOrEqualConditionValue( - v, - value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyType, - keyEntityHandler: keyEntityHandler, - ), - ); - } - - if (value1 is ConditionParameter) { - return value1.greaterThanOrEqual( - value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, - ); - } else if (value2 is ConditionParameter) { - return value2.lessThanOrEqual( - value1, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, - ); - } else { - var match = EntityHandler.graterThanOrEqualValue( - value1, - value2, - entityHandler: keyEntityHandler, - ); - return match; - } - } + }) => _orderingConditionValue( + _Ordering.gte, + value1, + value2, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, + ); + /// If [value1] `<` [value2] (see [_orderingConditionValue]). + /// + /// [keyType] is unused: kept for the API (and symmetry with + /// [equalsConditionValue]). bool lessThanConditionValue( Object? value1, Object? value2, { @@ -664,47 +635,20 @@ abstract class Condition extends ConditionElement Map? namedParameters, TypeInfo? keyType, EntityHandler? keyEntityHandler, - }) { - if (_isToManyValues(value1, value2)) { - return (value1 as Iterable).any( - (v) => lessThanConditionValue( - v, - value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyType, - keyEntityHandler: keyEntityHandler, - ), - ); - } - - if (value1 is ConditionParameter) { - return value1.lessThan( - value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, - ); - } else if (value2 is ConditionParameter) { - return value2.greaterThan( - value1, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, - ); - } else { - var match = EntityHandler.lessThanValue( - value1, - value2, - entityHandler: keyEntityHandler, - ); - return match; - } - } + }) => _orderingConditionValue( + _Ordering.lt, + value1, + value2, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, + ); + /// If [value1] `<=` [value2] (see [_orderingConditionValue]). + /// + /// [keyType] is unused: kept for the API (and symmetry with + /// [equalsConditionValue]). bool lessThanOrEqualConditionValue( Object? value1, Object? value2, { @@ -713,44 +657,69 @@ abstract class Condition extends ConditionElement Map? namedParameters, TypeInfo? keyType, EntityHandler? keyEntityHandler, - }) { + }) => _orderingConditionValue( + _Ordering.lte, + value1, + value2, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, + ); + + /// Compares [value1] (an entity's value) with [value2] by [ordering]: the + /// shared body of [greaterThanConditionValue], + /// [greaterThanOrEqualConditionValue], [lessThanConditionValue] and + /// [lessThanOrEqualConditionValue]. + /// + /// - The values of a to-many relationship: any of them (as a SQL join of + /// its rows). + /// - A [ConditionParameter] on the left is resolved and compared by + /// [ordering]; on the right, it's the left side of the [_Ordering.mirrored] + /// comparison (`a > ?` is `? < a`). + bool _orderingConditionValue( + _Ordering ordering, + Object? value1, + Object? value2, + Object? parameters, + List? positionalParameters, + Map? namedParameters, + EntityHandler? keyEntityHandler, + ) { if (_isToManyValues(value1, value2)) { return (value1 as Iterable).any( - (v) => lessThanOrEqualConditionValue( + (v) => _orderingConditionValue( + ordering, v, value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyType, - keyEntityHandler: keyEntityHandler, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, ), ); } if (value1 is ConditionParameter) { - return value1.lessThanOrEqual( + return value1._compareOrdering( + ordering, value2, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, ); } else if (value2 is ConditionParameter) { - return value2.greaterThanOrEqual( + return value2._compareOrdering( + ordering.mirrored, value1, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - entityHandler: keyEntityHandler, + parameters, + positionalParameters, + namedParameters, + keyEntityHandler, ); } else { - var match = EntityHandler.lessThanOrEqualValue( - value1, - value2, - entityHandler: keyEntityHandler, - ); - return match; + return ordering.test(value1, value2, keyEntityHandler); } } @@ -1488,6 +1457,9 @@ abstract class KeyCondition extends Condition { } } + /// The [value] encoded as in a condition string (see [encode]). + String get encodeValue => Condition.encodeConditionValue(value); + /// If `true` this is a negated operator (`!=`, `!~`), that also matches a /// `null` field. bool get isNegated => false; @@ -2149,8 +2121,6 @@ class KeyConditionEQ extends KeyCondition { ); } - String get encodeValue => Condition.encodeConditionValue(value); - @override String encode() => '$encodeKey == $encodeValue'; } @@ -2262,21 +2232,20 @@ class KeyConditionNotEQ extends KeyCondition { return notEquals(keyValue); } - String get encodeValue => Condition.encodeConditionValue(value); - @override String encode() => '$encodeKey != $encodeValue'; } -class KeyConditionGreaterThan extends KeyCondition { - KeyConditionGreaterThan(super.keys, dynamic super.value); +/// The base of the ordering key conditions ([KeyConditionGreaterThan], +/// [KeyConditionGreaterThanOrEqual], [KeyConditionLessThan] and +/// [KeyConditionLessThanOrEqual]), which only differ by their [_ordering]: +/// matching and encoding are written once here. Each public subclass keeps +/// its own constructor and [cast]. +abstract class _KeyConditionOrdering extends KeyCondition { + _KeyConditionOrdering(super.keys, super.value); - @override - KeyConditionGreaterThan cast() => - this is KeyConditionGreaterThan - ? this as KeyConditionGreaterThan - : KeyConditionGreaterThan(keys, value) - .._markResolved(resolved, _parent); + /// The comparison of this condition. + _Ordering get _ordering; @override bool matchesEntity( @@ -2288,12 +2257,14 @@ class KeyConditionGreaterThan extends KeyCondition { }) { var keyValue = getEntityKeyValue(o, entityHandler); - return greaterThanConditionValue( + return _orderingConditionValue( + _ordering, keyValue, value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, + parameters, + positionalParameters, + namedParameters, + null, ); } @@ -2307,189 +2278,75 @@ class KeyConditionGreaterThan extends KeyCondition { }) { var keyValue = getEntityMapKeyValue(o, entityHandler); - return greaterThanConditionValue( + return _orderingConditionValue( + _ordering, keyValue?.value, value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyValue?.type, - keyEntityHandler: keyValue?.entityHandler, + parameters, + positionalParameters, + namedParameters, + keyValue?.entityHandler, ); } - String get encodeValue => Condition.encodeConditionValue(value); - @override - String encode() => '$encodeKey > $encodeValue'; + String encode() => '$encodeKey ${_ordering.symbol} $encodeValue'; } -class KeyConditionGreaterThanOrEqual extends KeyCondition { - KeyConditionGreaterThanOrEqual(super.keys, dynamic super.value); +class KeyConditionGreaterThan extends _KeyConditionOrdering { + KeyConditionGreaterThan(super.keys, dynamic super.value); @override - KeyConditionGreaterThanOrEqual cast() => - this is KeyConditionGreaterThanOrEqual - ? this as KeyConditionGreaterThanOrEqual - : KeyConditionGreaterThanOrEqual(keys, value) - .._markResolved(resolved, _parent); + _Ordering get _ordering => _Ordering.gt; @override - bool matchesEntity( - O o, { - EntityHandler? entityHandler, - Object? parameters, - List? positionalParameters, - Map? namedParameters, - }) { - var keyValue = getEntityKeyValue(o, entityHandler); + KeyConditionGreaterThan cast() => + this is KeyConditionGreaterThan + ? this as KeyConditionGreaterThan + : KeyConditionGreaterThan(keys, value) + .._markResolved(resolved, _parent); +} - return greaterThanOrEqualConditionValue( - keyValue, - value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ); - } +class KeyConditionGreaterThanOrEqual extends _KeyConditionOrdering { + KeyConditionGreaterThanOrEqual(super.keys, dynamic super.value); @override - bool matchesEntityMap( - Map o, { - EntityHandler? entityHandler, - Object? parameters, - List? positionalParameters, - Map? namedParameters, - }) { - var keyValue = getEntityMapKeyValue(o, entityHandler); - - return greaterThanOrEqualConditionValue( - keyValue?.value, - value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyValue?.type, - keyEntityHandler: keyValue?.entityHandler, - ); - } - - String get encodeValue => Condition.encodeConditionValue(value); + _Ordering get _ordering => _Ordering.gte; @override - String encode() => '$encodeKey >= $encodeValue'; + KeyConditionGreaterThanOrEqual cast() => + this is KeyConditionGreaterThanOrEqual + ? this as KeyConditionGreaterThanOrEqual + : KeyConditionGreaterThanOrEqual(keys, value) + .._markResolved(resolved, _parent); } -class KeyConditionLessThan extends KeyCondition { +class KeyConditionLessThan extends _KeyConditionOrdering { KeyConditionLessThan(super.keys, dynamic super.value); + @override + _Ordering get _ordering => _Ordering.lt; + @override KeyConditionLessThan cast() => this is KeyConditionLessThan ? this as KeyConditionLessThan : KeyConditionLessThan(keys, value) .._markResolved(resolved, _parent); - - @override - bool matchesEntity( - O o, { - EntityHandler? entityHandler, - Object? parameters, - List? positionalParameters, - Map? namedParameters, - }) { - var keyValue = getEntityKeyValue(o, entityHandler); - - return lessThanConditionValue( - keyValue, - value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ); - } - - @override - bool matchesEntityMap( - Map o, { - EntityHandler? entityHandler, - Object? parameters, - List? positionalParameters, - Map? namedParameters, - }) { - var keyValue = getEntityMapKeyValue(o, entityHandler); - - return lessThanConditionValue( - keyValue?.value, - value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyValue?.type, - keyEntityHandler: keyValue?.entityHandler, - ); - } - - String get encodeValue => Condition.encodeConditionValue(value); - - @override - String encode() => '$encodeKey < $encodeValue'; } -class KeyConditionLessThanOrEqual extends KeyCondition { +class KeyConditionLessThanOrEqual extends _KeyConditionOrdering { KeyConditionLessThanOrEqual(super.keys, dynamic super.value); + @override + _Ordering get _ordering => _Ordering.lte; + @override KeyConditionLessThanOrEqual cast() => this is KeyConditionLessThanOrEqual ? this as KeyConditionLessThanOrEqual : KeyConditionLessThanOrEqual(keys, value) .._markResolved(resolved, _parent); - - @override - bool matchesEntity( - O o, { - EntityHandler? entityHandler, - Object? parameters, - List? positionalParameters, - Map? namedParameters, - }) { - var keyValue = getEntityKeyValue(o, entityHandler); - - return lessThanOrEqualConditionValue( - keyValue, - value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - ); - } - - @override - bool matchesEntityMap( - Map o, { - EntityHandler? entityHandler, - Object? parameters, - List? positionalParameters, - Map? namedParameters, - }) { - var keyValue = getEntityMapKeyValue(o, entityHandler); - - return lessThanOrEqualConditionValue( - keyValue?.value, - value, - parameters: parameters, - positionalParameters: positionalParameters, - namedParameters: namedParameters, - keyType: keyValue?.type, - keyEntityHandler: keyValue?.entityHandler, - ); - } - - String get encodeValue => Condition.encodeConditionValue(value); - - @override - String encode() => '$encodeKey <= $encodeValue'; } abstract class KeyConditionINBase extends KeyCondition> { @@ -2721,8 +2578,6 @@ abstract class KeyConditionINBase extends KeyCondition> { return inIDs(keyValue) != not; } - String get encodeValue => Condition.encodeConditionValue(value); - @override String encode() => '$encodeKey ${not ? '!' : '='}~ $encodeValue'; } @@ -2906,8 +2761,12 @@ class KeyConditionRegExp extends KeyCondition { } } - /// The [RegExp] of a literal pattern (without a parameter). - RegExp? _literalRegExp; + /// A cache of the [RegExp] of a literal [pattern] (without a parameter), + /// filled by [_resolveRegExp]. + /// + /// Why: a literal pattern never changes, and a condition is matched once + /// per entity (an in-memory select): compiled once, not once per entity. + RegExp? _literalRegExpCache; /// The [RegExp] of this condition, with its parameter's value, if any. /// @@ -2921,7 +2780,7 @@ class KeyConditionRegExp extends KeyCondition { ) { var pattern = this.pattern; if (pattern != null) { - return _literalRegExp ??= toDartRegExp( + return _literalRegExpCache ??= toDartRegExp( pattern, caseInsensitive: caseInsensitive, ); @@ -3066,6 +2925,8 @@ class KeyConditionRegExp extends KeyCondition { return s.toString(); } + /// A regexp is encoded as `/pattern/flags`, not as a JSON value. + @override String get encodeValue { var value = this.value; var body = value is String ? encodePatternLiteral(value) : value.toString(); diff --git a/lib/src/bones_api_condition_encoder.dart b/lib/src/bones_api_condition_encoder.dart index 89030052..6db422a9 100644 --- a/lib/src/bones_api_condition_encoder.dart +++ b/lib/src/bones_api_condition_encoder.dart @@ -1267,38 +1267,36 @@ class EncodingContext { return null; } - bool isValidAlias(String alias) { - if (isReservedWord(alias)) { - return false; - } - - return true; - } - - bool isReservedWord(String alias) { - return alias == 'as' || - alias == 'eq' || - alias == 'by' || - alias == 'null' || - alias == 'not' || - alias == 'def' || - alias == 'sum' || - alias == 'add' || - alias == 'from' || - alias == 'default' || - alias == 'alias' || - alias == 'equals' || - alias == 'count' || - alias == 'order' || - alias == 'table' || - alias == 'column' || - alias == 'select' || - alias == 'alter' || - alias == 'drop' || - alias == 'delete' || - alias == 'sql' || - alias == 'empty'; - } + bool isValidAlias(String alias) => !isReservedWord(alias); + + /// The words that can't be a generated table alias (see [isReservedWord]): + /// SQL keywords and function names an alias could collide with. + static const Set _reservedAliases = { + 'as', + 'eq', + 'by', + 'null', + 'not', + 'def', + 'sum', + 'add', + 'from', + 'default', + 'alias', + 'equals', + 'count', + 'order', + 'table', + 'column', + 'select', + 'alter', + 'drop', + 'delete', + 'sql', + 'empty', + }; + + bool isReservedWord(String alias) => _reservedAliases.contains(alias); String addEncodingParameter( String suggestedKey, @@ -1326,6 +1324,16 @@ class EncodingContext { throw StateError("Can't create encoding parameter: $suggestedKey = $value"); } + + /// The value of [parameter], resolved with all the parameters of this + /// context ([parameters], [positionalParameters], [namedParameters] and + /// [encodingParameters]). + Object? parameterValue(ConditionParameter parameter) => parameter.getValue( + parameters: parameters, + positionalParameters: positionalParameters, + namedParameters: namedParameters, + encodingParameters: encodingParameters, + ); } /// Base class to encode [Condition]. @@ -1732,12 +1740,7 @@ abstract class ConditionEncoder { Type? valueType, bool valueAsList, ) { - var paramValue = value.getValue( - parameters: context.parameters, - positionalParameters: context.positionalParameters, - namedParameters: context.namedParameters, - encodingParameters: context.encodingParameters, - ); + var paramValue = context.parameterValue(value); // Not a regexp pattern parameter (`/?/`), which `encodeKeyConditionRegExp` // resolves: a `RegExp` here would be compared as its text. @@ -1805,13 +1808,15 @@ abstract class ConditionEncoder { } FutureOr _resolveValueToTypeImpl(Object? value, Type valueType) { + // `late`: computed once, and only if needed (the early returns below + // don't need it). + late final valueTypeInfo = TypeInfo.from(valueType); + // A list as a single value (`== [x]` is `== x`), unless the field is a // list itself (a `List`, a `Uint8List`: compared as a whole): // first, so its element is resolved as a value (an enum by its name, an // entity by its ID), not the list as text. - if (value is Iterable && - value is! TypedData && - !TypeInfo.from(valueType).isIterable) { + if (value is Iterable && value is! TypedData && !valueTypeInfo.isIterable) { var list = value.toList(); if (list.isEmpty) return null; if (list.length == 1) value = list.first; @@ -1872,8 +1877,6 @@ abstract class ConditionEncoder { if (entityID != null) value = entityID; } - var valueTypeInfo = TypeInfo.from(valueType); - var valueParser = TypeParser.parserForTypeInfo(valueTypeInfo); if (valueParser != null) { if (value is Iterable && valueTypeInfo.isPrimitiveType) { diff --git a/lib/src/bones_api_condition_sql.dart b/lib/src/bones_api_condition_sql.dart index 1bbc614a..4cc96917 100644 --- a/lib/src/bones_api_condition_sql.dart +++ b/lib/src/bones_api_condition_sql.dart @@ -137,40 +137,42 @@ class ConditionSQLEncoder extends ConditionEncoder { FutureOr encodeIDCondition( ConditionID c, EncodingContext context, - ) { - var tableName = context.tableNameOrEntityName; - var tableAlias = context.resolveEntityAlias(tableName); + ) => _encodeIDComparison(context, c.idValue, isList: false); - // Never `null`: required by the constructor. - var tableSchemeRet = schemeProvider!.getTableScheme(tableName); + @override + FutureOr encodeIDConditionIN( + ConditionIdIN c, + EncodingContext context, + ) => _encodeIDComparison(context, c.idsValues, isList: true); - return tableSchemeRet.resolveMapped((tableScheme) { - if (tableScheme == null) { - var errorMsg = "Can't find `TableScheme` for entity/table: $tableName"; - _log.severe(errorMsg); - throw StateError(errorMsg); - } + /// The shared body of [encodeIDCondition] (`#ID == x`) and + /// [encodeIDConditionIN] (`#ID =~ [x, y]`, [isList]): resolves the ID + /// column of the [context]'s table and writes its comparison with + /// [idValue] (see [encodeIDValues]). + FutureOr _encodeIDComparison( + EncodingContext context, + Object? idValue, { + required bool isList, + }) { + var tableName = context.tableNameOrEntityName; + var tableAlias = context.resolveEntityAlias(tableName); + return _requireTableScheme(tableName).resolveMapped((tableScheme) { var idFieldName = tableScheme.idFieldName ?? 'id'; var idType = tableScheme.fieldsTypes[idFieldName] ?? int; - var idKey = context.addEncodingParameter(idFieldName, c.idValue); - var q = sqlElementQuote; + var idKey = context.addEncodingParameter(idFieldName, idValue); // The column, not `idKey` (renamed if a query parameter has its name): - var tableKey = '$q$tableAlias$q.$q$idFieldName$q'; + var tableKey = qualifiedColumnSQL(tableAlias, idFieldName); - return encodeIDValues(context, idType, idKey, tableKey, c.idValue, false); + return encodeIDValues(context, idType, idKey, tableKey, idValue, isList); }); } - @override - FutureOr encodeIDConditionIN( - ConditionIdIN c, - EncodingContext context, - ) { - var tableName = context.tableNameOrEntityName; - var tableAlias = context.resolveEntityAlias(tableName); - + /// The [TableScheme] of [tableName], or a [StateError] (logged) if there's + /// none. Used by the encoders that need the main table's scheme + /// ([_encodeIDComparison] and [keyFieldToSQL]). + FutureOr _requireTableScheme(String tableName) { // Never `null`: required by the constructor. var tableSchemeRet = schemeProvider!.getTableScheme(tableName); @@ -180,26 +182,18 @@ class ConditionSQLEncoder extends ConditionEncoder { _log.severe(errorMsg); throw StateError(errorMsg); } - - var idFieldName = tableScheme.idFieldName ?? 'id'; - var idType = tableScheme.fieldsTypes[idFieldName] ?? int; - - var idKey = context.addEncodingParameter(idFieldName, c.idsValues); - var q = sqlElementQuote; - // The column, not `idKey` (renamed if a query parameter has its name): - var tableKey = '$q$tableAlias$q.$q$idFieldName$q'; - - return encodeIDValues( - context, - idType, - idKey, - tableKey, - c.idsValues, - true, - ); + return tableScheme; }); } + /// A column qualified by its table alias, quoted with [sqlElementQuote]: + /// `"alias"."column"`. As `SQLDialect.qualifiedColumnSQL` (with the + /// dialect's quote). + String qualifiedColumnSQL(String tableAlias, String column) { + var q = sqlElementQuote; + return '$q$tableAlias$q.$q$column$q'; + } + /// Writes the comparison of the ID column ([tableKey]) with [idValue] (`=`) /// or with the [idValue] list (`IN`), as parameters (placeholders) rather /// than values written into the SQL: the statement text is the same for @@ -385,12 +379,7 @@ class ConditionSQLEncoder extends ConditionEncoder { var patternParameter = c.patternParameter; if (patternParameter != null) { - var paramValue = patternParameter.getValue( - parameters: context.parameters, - positionalParameters: context.positionalParameters, - namedParameters: context.namedParameters, - encodingParameters: context.encodingParameters, - ); + var paramValue = context.parameterValue(patternParameter); (pattern, caseInsensitive) = KeyConditionRegExp.resolvePatternValue( paramValue, @@ -486,14 +475,19 @@ class ConditionSQLEncoder extends ConditionEncoder { var values = c.value; if (values is! List || values.length != 1) return false; var p = values.first; - return p is ConditionParameter && - p.getValue( - parameters: context.parameters, - positionalParameters: context.positionalParameters, - namedParameters: context.namedParameters, - encodingParameters: context.encodingParameters, - ) == - null; + return p is ConditionParameter && context.parameterValue(p) == null; + } + + /// Writes the match of an empty set of values (`x =~ []`): `IN` matches + /// nothing (`FALSE`) and `NOT IN` everything (`TRUE`, also a `NULL`). + /// Used by [encodeConditionValuesWithOperator] for an empty list, and for a + /// relationship's list with only `null`s. + EncodingContext _writeEmptySetMatch( + EncodingContext context, + String operator, + ) { + context.write(operator == 'IN' ? ' FALSE ' : ' TRUE '); + return context; } /// If [c]'s key is a single relationship field of the main entity: its `IN` @@ -601,8 +595,7 @@ class ConditionSQLEncoder extends ConditionEncoder { // as a list with a `null`), except for a relationship // ([nullsAsAbsent], below). if (elements.isEmpty) { - context.write(operator == 'IN' ? ' FALSE ' : ' TRUE '); - return context; + return _writeEmptySetMatch(context, operator); } var nonNulls = elements @@ -620,8 +613,7 @@ class ConditionSQLEncoder extends ConditionEncoder { // A relationship's set of IDs ([_isRelationshipKey]): its `null`s // aren't IDs. Without any other, an empty set (as `[]`). if (nonNulls.isEmpty) { - context.write(operator == 'IN' ? ' FALSE ' : ' TRUE '); - return context; + return _writeEmptySetMatch(context, operator); } value = EncodingValueList( value.key, @@ -801,17 +793,7 @@ class ConditionSQLEncoder extends ConditionEncoder { var keys = c.keys; var key0 = keys.first as ConditionKeyField; - var tableSchemeRet = schemeProvider.getTableScheme(tableName); - - return tableSchemeRet.resolveMapped((tableScheme) { - if (tableScheme == null) { - var errorMsg = "Can't find `TableScheme` for entity/table: $tableName"; - _log.severe(errorMsg); - throw StateError(errorMsg); - } - - var q = sqlElementQuote; - + return _requireTableScheme(tableName).resolveMapped((tableScheme) { var fieldName = key0.name; var tableFieldName = tableScheme.resolveTableFieldName(fieldName); var tableFieldType = tableFieldName != null @@ -819,7 +801,10 @@ class ConditionSQLEncoder extends ConditionEncoder { : null; if (tableFieldType != null) { - return MapEntry(tableFieldType, '$q$tableAlias$q.$q$tableFieldName$q'); + return MapEntry( + tableFieldType, + qualifiedColumnSQL(tableAlias, tableFieldName!), + ); } var retFieldType = schemeProvider.getFieldType( @@ -874,7 +859,7 @@ class ConditionSQLEncoder extends ConditionEncoder { return MapEntry( relationshipTargetFieldType, - '$q$relationshipAlias$q.$q$relationshipTargetField$q', + qualifiedColumnSQL(relationshipAlias, relationshipTargetField), ); }); }); @@ -952,9 +937,8 @@ class ConditionSQLEncoder extends ConditionEncoder { final alias = context.resolveEntityAlias(targetTable); final type = scheme.fieldsTypes[fieldName]!; - final q = sqlElementQuote; - return MapEntry(type, '$q$alias$q.$q$fieldName$q'); + return MapEntry(type, qualifiedColumnSQL(alias, fieldName)); }); } From c213c07732cdc9ce364e311a783525e66fa13b8a Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:13:39 -0300 Subject: [PATCH 02/40] Refactor SQL builder: index/constraint names in one place, cache fields - `SQLGenerator.uniqueConstraintName`, `indexName`, `foreignKeyName` and `relationshipTableName` (byte-identical names), also used by the scheme check and the in-memory adapter's relationship table. - Locals `constrain*Name` -> `constraint*Name`. - `SQLDialect.qualifiedColumnSQL` (used by `orderBySQL`). - `CreateTableSQL`/`AlterTableSQL` table caches named `*Cache`, documented. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_entity_db_memory.dart | 5 +- lib/src/bones_api_entity_db_sql.dart | 2 +- lib/src/bones_api_sql_builder.dart | 147 +++++++++++++++++------- 3 files changed, 112 insertions(+), 42 deletions(-) diff --git a/lib/src/bones_api_entity_db_memory.dart b/lib/src/bones_api_entity_db_memory.dart index 22f9cd06..922b2fd0 100644 --- a/lib/src/bones_api_entity_db_memory.dart +++ b/lib/src/bones_api_entity_db_memory.dart @@ -1660,7 +1660,10 @@ class DBSQLMemoryAdapter extends DBSQLAdapter ?.type ?? int; - var relTable = '${sourceTable}__${sourceField}__rel'; + var relTable = SQLGenerator.relationshipTableName( + sourceTable, + sourceField, + ); var relSourceField = '${sourceTable}__$sourceFieldId'; var relTargetField = '${targetTable}__$targetField'; diff --git a/lib/src/bones_api_entity_db_sql.dart b/lib/src/bones_api_entity_db_sql.dart index d2f54cf7..c13f96de 100644 --- a/lib/src/bones_api_entity_db_sql.dart +++ b/lib/src/bones_api_entity_db_sql.dart @@ -4465,7 +4465,7 @@ class _DBTableCheck { var column = sqlGenerator.normalizeColumnName(f.name); return sqlGenerator.generateAddUniqueConstraintSQL( table, - '${table}__${column}__unique', + SQLGenerator.uniqueConstraintName(table, column), [column], comment: '${f.type.toString(withT: false)} ${f.name} UNIQUE', ); diff --git a/lib/src/bones_api_sql_builder.dart b/lib/src/bones_api_sql_builder.dart index 758d9c87..6f8c517a 100644 --- a/lib/src/bones_api_sql_builder.dart +++ b/lib/src/bones_api_sql_builder.dart @@ -201,6 +201,13 @@ class SQLDialect extends DBDialect { this.subqueryAsDerivedTable = false, }); + /// A [column] qualified by its [tableAlias], quoted with [elementQuote]: + /// `"alias"."column"`. + String qualifiedColumnSQL(String tableAlias, String column) { + var q = elementQuote; + return '$q$tableAlias$q.$q$column$q'; + } + /// Builds the ` ORDER BY . ASC|DESC` clause /// of this dialect. String orderBySQL( @@ -208,9 +215,8 @@ class SQLDialect extends DBDialect { String column, { OrderDirection? direction, }) { - var q = elementQuote; var keyword = OrderDirection.resolve(direction).sqlKeyword; - return ' ORDER BY $q$tableAlias$q.$q$column$q $keyword'; + return ' ORDER BY ${qualifiedColumnSQL(tableAlias, column)} $keyword'; } /// Builds the ` LIMIT OFFSET ` clause of this dialect. @@ -480,27 +486,39 @@ class CreateTableSQL extends TableSQL { this.entityRepository, }); - List? _referenceTables; + /// A cache of [referenceTables], filled on its first call. + /// + /// Why: it's called repeatedly while sorting the tables by their + /// dependencies, and it's derived from the [entries]. Reset by + /// [_disposeCache]. + List? _referenceTablesCache; @override - List get referenceTables => _referenceTables ??= { + List get referenceTables => _referenceTablesCache ??= { ...entries.expand((e) => e.referenceTables ?? []), }.toList(); - List? _relationshipsTables; + /// A cache of [relationshipsTables], filled on its first call. As + /// [_referenceTablesCache], derived from the [relationships]. Reset by + /// [_disposeCache]. + List? _relationshipsTablesCache; /// Returns the tables of the [relationships]. - List get relationshipsTables => _relationshipsTables ??= { - ...?relationships?.expand( - (e) => e.referenceTables.where((t) => t != table), - ), - }.toList(); + List get relationshipsTables => + _relationshipsTablesCache ??= { + ...?relationships?.expand( + (e) => e.referenceTables.where((t) => t != table), + ), + }.toList(); - List? _referenceAndRelationshipTables; + /// A cache of [referenceAndRelationshipTables] (the [dependentTables]), + /// filled on its first call. As [_referenceTablesCache]. Reset by + /// [_disposeCache]. + List? _referenceAndRelationshipTablesCache; /// Returns the tables in [referenceTables] and [relationshipsTables]. List get referenceAndRelationshipTables => - _referenceAndRelationshipTables ??= { + _referenceAndRelationshipTablesCache ??= { ...referenceTables, ...relationshipsTables, }.toList(); @@ -520,9 +538,9 @@ class CreateTableSQL extends TableSQL { entries.where((e) => e.type == 'CONSTRAINT').toList(); void _disposeCache() { - _referenceTables = null; - _relationshipsTables = null; - _referenceAndRelationshipTables = null; + _referenceTablesCache = null; + _relationshipsTablesCache = null; + _referenceAndRelationshipTablesCache = null; } /// Converts the [constraints] to [AlterTableSQL]. @@ -685,10 +703,14 @@ class AlterTableSQL extends TableSQL { super.parentTable, }); - List? _referenceTables; + /// A cache of [referenceTables], filled on its first call. + /// + /// Why: it's called repeatedly while sorting the tables by their + /// dependencies, and it's derived from the [entries]. + List? _referenceTablesCache; @override - List get referenceTables => _referenceTables ??= { + List get referenceTables => _referenceTablesCache ??= { ...entries.expand((e) => e.referenceTables ?? []).nonNulls, }.toList(); @@ -1429,6 +1451,36 @@ extension SQLBuilderListExtension on List { /// Base class for a `SQL` generator. abstract mixin class SQLGenerator { + /// The name of the `UNIQUE` constraint (or unique index, where a + /// constraint can't be added) of [column] of [table]: + /// `____unique`. Without a [column], of the whole [table] + /// (a relationship table's `UNIQUE (source, target)`): + /// `
__unique`. + /// + /// The single source of these names: the `CREATE TABLE`, the `ALTER TABLE` + /// that adds a missing one, and the scheme check that looks for it must + /// agree on it. + static String uniqueConstraintName(String table, [String? column]) => + column == null ? '${table}__unique' : '${table}__${column}__unique'; + + /// The name of the (non-unique) index of [column] of [table]: + /// `
____idx`. + static String indexName(String table, String column) => + '${table}__${column}__idx'; + + /// The name of the `FOREIGN KEY` constraint of [column] of [table]: + /// `
____fkey`. + static String foreignKeyName(String table, String column) => + '${table}__${column}__fkey'; + + /// The name of the relationship table of the to-many field [column] of + /// [table]: `
____rel`. + /// + /// Also used to find it in the in-memory adapter, which must match the + /// name of the SQL adapters' tables. + static String relationshipTableName(String table, String column) => + '${table}__${column}__rel'; + /// The generated SQL dialect. SQLDialect get dialect; @@ -1753,7 +1805,10 @@ abstract mixin class SQLGenerator { if (entityFieldAnnotations != null && entityFieldAnnotations.isNotEmpty) { if (entityFieldAnnotations.hasUnique && !alterTableAddConstraint) { - var uniqueIndexName = '${table}__${columnName}__unique'; + var uniqueIndexName = SQLGenerator.uniqueConstraintName( + table, + columnName, + ); indexes = [ CreateIndexSQL.columns( dialect, @@ -1765,11 +1820,14 @@ abstract mixin class SQLGenerator { ), ]; } else if (entityFieldAnnotations.hasUnique) { - var constrainUniqueName = '${table}__${columnName}__unique'; + var constraintUniqueName = SQLGenerator.uniqueConstraintName( + table, + columnName, + ); var uniqueEntry = SQLEntry( 'CONSTRAINT', - ' ADD CONSTRAINT $q$constrainUniqueName$q UNIQUE ($q$columnName$q)', + ' ADD CONSTRAINT $q$constraintUniqueName$q UNIQUE ($q$columnName$q)', columns: [ SQLColumn( table, @@ -1784,7 +1842,7 @@ abstract mixin class SQLGenerator { AlterTableSQL(dialect, table, [uniqueEntry]), ]; } else if (entityFieldAnnotations.hasIndexed) { - var indexName = '${table}__${columnName}__idx'; + var indexName = SQLGenerator.indexName(table, columnName); indexes = [CreateIndexSQL(dialect, table, columnName, indexName)]; } } @@ -1798,13 +1856,13 @@ abstract mixin class SQLGenerator { // (Without `ADD CONSTRAINT`: in the column, above.) if (alterTableAddConstraint) { - var constrainName = '${table}__${columnName}__fkey'; + var constraintName = SQLGenerator.foreignKeyName(table, columnName); constraints ??= []; var constraintEntry = SQLEntry( 'CONSTRAINT', - ' ADD CONSTRAINT $q$constrainName$q FOREIGN KEY ($q$columnName$q) REFERENCES $q$refTableName$q($q$refField$q)', + ' ADD CONSTRAINT $q$constraintName$q FOREIGN KEY ($q$columnName$q) REFERENCES $q$refTableName$q($q$refField$q)', comment: '$fieldName @ $refTableName.$refField', columns: [ SQLColumn( @@ -1820,7 +1878,7 @@ abstract mixin class SQLGenerator { } if (!dialect.foreignKeyCreatesImplicitIndex) { - var indexName = '${table}__${columnName}__idx'; + var indexName = SQLGenerator.indexName(table, columnName); indexes ??= []; indexes.add( @@ -1850,7 +1908,7 @@ abstract mixin class SQLGenerator { var columnName = normalizeColumnName(fieldName); // The same name as in the `CREATE TABLE`: - var constraintName = '${table}__${columnName}__unique'; + var constraintName = SQLGenerator.uniqueConstraintName(table, columnName); var comment = '${fieldType.toString(withT: false)} $fieldName UNIQUE'; @@ -2139,12 +2197,15 @@ abstract mixin class SQLGenerator { if (entityFieldAnnotations != null) { if (entityFieldAnnotations.hasUnique) { - var constrainUniqueName = '${table}__${columnName}__unique'; + var constraintUniqueName = SQLGenerator.uniqueConstraintName( + table, + columnName, + ); sqlEntries.add( SQLEntry( 'CONSTRAINT', - ' CONSTRAINT $q$constrainUniqueName$q UNIQUE ($q$columnName$q)', + ' CONSTRAINT $q$constraintUniqueName$q UNIQUE ($q$columnName$q)', columns: [ SQLColumn( table, @@ -2157,11 +2218,11 @@ abstract mixin class SQLGenerator { ); uniqueConstraints.add(( - name: constrainUniqueName, + name: constraintUniqueName, columns: [columnName], )); } else if (entityFieldAnnotations.hasIndexed) { - var indexName = '${table}__${columnName}__idx'; + var indexName = SQLGenerator.indexName(table, columnName); indexSQLs.add( CreateIndexSQL(dialect, table, columnName, indexName, q: q), ); @@ -2178,12 +2239,12 @@ abstract mixin class SQLGenerator { var refTableName = ref.key; var refField = ref.value.key.toLowerCase(); - var constrainName = '${table}__${columnName}__fkey'; + var constraintName = SQLGenerator.foreignKeyName(table, columnName); sqlEntries.add( SQLEntry( 'CONSTRAINT', - ' CONSTRAINT $q$constrainName$q FOREIGN KEY ($q$columnName$q) REFERENCES $q$refTableName$q($q$refField$q)', + ' CONSTRAINT $q$constraintName$q FOREIGN KEY ($q$columnName$q) REFERENCES $q$refTableName$q($q$refField$q)', comment: '$fieldName @ $refTableName.$refField', columns: [ SQLColumn( @@ -2197,7 +2258,7 @@ abstract mixin class SQLGenerator { ); if (!dialect.foreignKeyCreatesImplicitIndex) { - var indexName = '${table}__${columnName}__idx'; + var indexName = SQLGenerator.indexName(table, columnName); indexSQLs.add( CreateIndexSQL(dialect, table, columnName, indexName, q: q), ); @@ -2308,11 +2369,17 @@ abstract mixin class SQLGenerator { var dstFieldName = normalizeColumnName(relDstTable); - var relName = '${table}__${columnName}__rel'; + var relName = SQLGenerator.relationshipTableName(table, columnName); - var constrainUniqueName = '${relName}__unique'; - var constrainSrcName = '${relName}__${srcFieldName}__fkey'; - var constrainDstName = '${relName}__${dstFieldName}__fkey'; + var constraintUniqueName = SQLGenerator.uniqueConstraintName(relName); + var constraintSrcName = SQLGenerator.foreignKeyName( + relName, + srcFieldName, + ); + var constraintDstName = SQLGenerator.foreignKeyName( + relName, + dstFieldName, + ); var sqlRelEntries = [ SQLEntry( @@ -2344,7 +2411,7 @@ abstract mixin class SQLGenerator { ), SQLEntry( 'CONSTRAINT', - ' CONSTRAINT $q$constrainUniqueName$q UNIQUE ($q$srcFieldName$q, $q$dstFieldName$q)', + ' CONSTRAINT $q$constraintUniqueName$q UNIQUE ($q$srcFieldName$q, $q$dstFieldName$q)', columns: [ SQLColumn(relName, srcFieldName), SQLColumn(relName, dstFieldName), @@ -2352,7 +2419,7 @@ abstract mixin class SQLGenerator { ), SQLEntry( 'CONSTRAINT', - ' CONSTRAINT $q$constrainSrcName$q FOREIGN KEY ($q$srcFieldName$q) REFERENCES $q$table$q($q$idColumnName$q) ON DELETE CASCADE', + ' CONSTRAINT $q$constraintSrcName$q FOREIGN KEY ($q$srcFieldName$q) REFERENCES $q$table$q($q$idColumnName$q) ON DELETE CASCADE', comment: ' $srcFieldName @ $table.$idColumnName', columns: [ SQLColumn( @@ -2365,7 +2432,7 @@ abstract mixin class SQLGenerator { ), SQLEntry( 'CONSTRAINT', - ' CONSTRAINT $q$constrainDstName$q FOREIGN KEY ($q$dstFieldName$q) REFERENCES $q$relDstTable$q($q$relDstTableId$q) ON DELETE CASCADE', + ' CONSTRAINT $q$constraintDstName$q FOREIGN KEY ($q$dstFieldName$q) REFERENCES $q$relDstTable$q($q$relDstTableId$q) ON DELETE CASCADE', comment: ' $dstFieldName @ $relDstTable.$relDstTableId', columns: [ SQLColumn( @@ -2385,7 +2452,7 @@ abstract mixin class SQLGenerator { // the target column needs its own index (another one on the source // would just be updated on every write). if (!dialect.foreignKeyCreatesImplicitIndex) { - var indexName2 = '${relName}__${dstFieldName}__idx'; + var indexName2 = SQLGenerator.indexName(relName, dstFieldName); relIndexes.add( CreateIndexSQL(dialect, relName, dstFieldName, indexName2, q: q), From db1b1771c23f487f61d07b8944652968df3a5b2f Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:16:44 -0300 Subject: [PATCH 03/40] Refactor entity rules: shared merge/flatten/scan helpers, cache naming - EntityResolutionRules.merge: the tri-state flag merge -> _mergeFlag; the tolerant/intolerant mirror arms -> _mergeTypesDroppingConflict. - fetchTypes: four near-identical lambdas -> _typesWhere. - EntityAccessRules: _flattenGroup, _conditionMatches, _lastDefined; the block arm returns fieldRule directly. - EntityAccessRulesCached: cache fields named *Cache and documented. - EntityRulesResolver.contextProviders (cotextProviders kept, deprecated). Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_entity_rules.dart | 337 +++++++++++----------- test/bones_api_cov_entity_rules_test.dart | 5 +- 2 files changed, 175 insertions(+), 167 deletions(-) diff --git a/lib/src/bones_api_entity_rules.dart b/lib/src/bones_api_entity_rules.dart index ea2bde34..ce72beca 100644 --- a/lib/src/bones_api_entity_rules.dart +++ b/lib/src/bones_api_entity_rules.dart @@ -270,14 +270,9 @@ class EntityAccessRules extends EntityRules { final entityFields = this.entityFields; var fieldRule = entityFields != null && entityFields.isNotEmpty; - // If blocks a field it's not fully blocking a type: - if (fieldRule) { - return true; - } + // If blocks a field it's not fully blocking a type (allowed). // If there's NO field rule, the type is being blocked: - else { - return false; - } + return fieldRule; } case EntityAccessRuleType.mask: { @@ -291,17 +286,37 @@ class EntityAccessRules extends EntityRules { } } - final rules = this.rules; + return _lastDefined(rules, (r) => r.isAllowedEntityType(type)); + } + + /// Scans [rules] from the last to the first and returns the first + /// non-`null` [decision]: a later rule overrides an earlier one. Returns + /// `null` when no rule decides (or [rules] is `null`/empty). + /// + /// Used by [isAllowedEntityType], [isAllowedEntityTypeField] and + /// [isMaskedEntityTypeField] to delegate to the sub-rules. It's `static` + /// since [EntityAccessRules] is implemented by other classes. + static bool? _lastDefined( + List? rules, + bool? Function(EntityAccessRules rule) decision, + ) { if (rules == null || rules.isEmpty) return null; for (var r in rules.reversed) { - var allowed = r.isAllowedEntityType(type); - if (allowed != null) return allowed; + var decided = decision(r); + if (decided != null) return decided; } return null; } + /// Returns `true` if [condition] is absent (an unconditional rule) or + /// accepts [context]. Used by the field allow/block/mask checks. + static bool _conditionMatches( + EntityAccessRulesCondition? condition, + EntityAccessRulesContext? context, + ) => condition == null || condition(context); + bool hasRuleType(List ruleTypes) { if (ruleTypes.isEmpty) return false; @@ -341,7 +356,7 @@ class EntityAccessRules extends EntityRules { case EntityAccessRuleType.allow: { if (entityFields.anyIgnoreCase(field)) { - var allowed = condition == null || condition(context); + var allowed = _conditionMatches(condition, context); return allowed; } else { return null; @@ -350,7 +365,7 @@ class EntityAccessRules extends EntityRules { case EntityAccessRuleType.block: { if (entityFields.anyIgnoreCase(field)) { - var allowed = condition == null || condition(context); + var allowed = _conditionMatches(condition, context); var blocked = !allowed; return blocked; } else { @@ -368,15 +383,10 @@ class EntityAccessRules extends EntityRules { } } - final rules = this.rules; - if (rules == null || rules.isEmpty) return null; - - for (var r in rules.reversed) { - var allowed = r.isAllowedEntityTypeField(type, field, context: context); - if (allowed != null) return allowed; - } - - return null; + return _lastDefined( + rules, + (r) => r.isAllowedEntityTypeField(type, field, context: context), + ); } bool? isMaskedEntityTypeField( @@ -392,8 +402,7 @@ class EntityAccessRules extends EntityRules { if (entityType == type) { if (ruleType == EntityAccessRuleType.mask) { if (entityFields.anyIgnoreCase(field)) { - final condition = this.condition; - return (condition == null || condition(context)); + return _conditionMatches(condition, context); } else { return null; } @@ -402,15 +411,10 @@ class EntityAccessRules extends EntityRules { if (direct) return false; - final rules = this.rules; - if (rules == null || rules.isEmpty) return null; - - for (var r in rules.reversed) { - var masked = r.isMaskedEntityTypeField(type, field, context: context); - if (masked != null) return masked; - } - - return null; + return _lastDefined( + rules, + (r) => r.isMaskedEntityTypeField(type, field, context: context), + ); } V applyMask( @@ -575,12 +579,7 @@ class EntityAccessRules extends EntityRules { .where((r) => !r.isInnocuous) .map((r) => r.simplified()); - var rulesSimpleFlat = rulesSimple.expand((r) { - var rules = r.rules; - return rules != null && rules.isNotEmpty && r.entityType == null - ? rules - : [r]; - }).toList(); + var rulesSimpleFlat = rulesSimple.expand(_flattenGroup).toList(); if (entityType != null) { var r1 = copyWith(rules: []); @@ -607,25 +606,24 @@ class EntityAccessRules extends EntityRules { return other; } - var a = simplified(); - var b = other.simplified(); - - var rulesA = a.rules; - var rulesB = b.rules; - - var listA = rulesA != null && rulesA.isNotEmpty && a.entityType == null - ? rulesA - : [a]; - - var listB = rulesB != null && rulesB.isNotEmpty && b.entityType == null - ? rulesB - : [b]; - - var allRules = [...listA, ...listB]; + var allRules = [ + ..._flattenGroup(simplified()), + ..._flattenGroup(other.simplified()), + ]; return EntityAccessRules.group(allRules); } + /// Returns the sub-rules of [rule] when it's a pure group (sub-rules and + /// no [entityType]), otherwise `[rule]` itself. Used by [simplified] and + /// [merge] to avoid nesting groups inside groups. + static List _flattenGroup(EntityAccessRules rule) { + var rules = rule.rules; + return rules != null && rules.isNotEmpty && rule.entityType == null + ? rules + : [rule]; + } + static final _rulesListEquality = ListEquality(); @override @@ -777,10 +775,12 @@ class EntityAccessRulesCached implements EntityAccessRules { EntityAccessRulesCached(this.accessRules); - int? _totalRules; + /// Cache of [totalRules]: the rule tree is immutable, so the count is + /// computed (a full traversal) only once. + int? _totalRulesCache; @override - int totalRules() => _totalRules ??= accessRules.totalRules(); + int totalRules() => _totalRulesCache ??= accessRules.totalRules(); @override bool? get _innocuous => accessRules._innocuous; @@ -821,29 +821,33 @@ class EntityAccessRulesCached implements EntityAccessRules { @override bool get _simplified => accessRules._simplified; - final Map _hasRuleForEntityType = {}; + /// Cache of [hasRuleForEntityType] results by entity [Type]: called for + /// every object encoded to JSON, and each call walks the rule tree. + final Map _hasRuleForEntityTypeCache = {}; @override - bool hasRuleForEntityType(Type type) => _hasRuleForEntityType.putIfAbsent( - type, - () => accessRules.hasRuleForEntityType(type), - ); + bool hasRuleForEntityType(Type type) => _hasRuleForEntityTypeCache + .putIfAbsent(type, () => accessRules.hasRuleForEntityType(type)); - final Map<_CacheKey, bool> _hasRuleType = <_CacheKey, bool>{}; + /// Cache of [hasRuleType] results, keyed by the (element-wise compared) + /// list of rule types queried: each call walks the rule tree. + final Map<_CacheKey, bool> _hasRuleTypeCache = <_CacheKey, bool>{}; @override bool hasRuleType(List ruleTypes) { final cacheKey = _CacheKey(ruleTypes); - return _hasRuleType.putIfAbsent( + return _hasRuleTypeCache.putIfAbsent( cacheKey, () => accessRules.hasRuleType(ruleTypes), ); } - final Map _hasRuleForEntityTypeField = {}; + /// Cache of [hasRuleForEntityTypeField] results by entity [Type]: called + /// for every object encoded to JSON, and each call walks the rule tree. + final Map _hasRuleForEntityTypeFieldCache = {}; @override - bool hasRuleForEntityTypeField(Type type) => _hasRuleForEntityTypeField + bool hasRuleForEntityTypeField(Type type) => _hasRuleForEntityTypeFieldCache .putIfAbsent(type, () => accessRules.hasRuleForEntityTypeField(type)); @override @@ -1213,39 +1217,10 @@ class EntityResolutionRules extends EntityRules { Map? lazyTypes, bool mergeTolerant = false, }) { - var eagerTypesNotNull = eagerTypes?.entries.map((e) { - var eager = e.value; - return eager != null ? MapEntry(e.key, eager) : null; - }).nonNulls; - - var lazyTypesNotNull = lazyTypes?.entries.map((e) { - var lazy = e.value; - return lazy != null ? MapEntry(e.key, lazy) : null; - }).nonNulls; - - var fetchEager = eagerTypesNotNull?.map((e) { - var t = e.key; - var eager = e.value; - return eager ? t : null; - }); - - var fetchNotEager = eagerTypesNotNull?.map((e) { - var t = e.key; - var eager = e.value; - return !eager ? t : null; - }); - - var fetchLazy = lazyTypesNotNull?.map((e) { - var t = e.key; - var lazy = e.value; - return lazy ? t : null; - }); - - var fetchNotLazy = lazyTypesNotNull?.map((e) { - var t = e.key; - var lazy = e.value; - return !lazy ? t : null; - }); + var fetchEager = _typesWhere(eagerTypes, true); + var fetchNotEager = _typesWhere(eagerTypes, false); + var fetchLazy = _typesWhere(lazyTypes, true); + var fetchNotLazy = _typesWhere(lazyTypes, false); var eagerEntityTypes = [...?fetchEager, ...?fetchNotLazy].nonNulls .expand((e) => e is Iterable ? e : [e]) @@ -1282,6 +1257,15 @@ class EntityResolutionRules extends EntityRules { ); } + /// Returns the keys of [typesFlags] whose flag is [wanted], used by + /// [EntityResolutionRules.fetchTypes]. A `null` flag means "no rule" and + /// is never selected. A key can be a [Type] or an [Iterable] of [Type]s + /// (expanded by the caller). + static Iterable? _typesWhere( + Map? typesFlags, + bool wanted, + ) => typesFlags?.entries.where((e) => e.value == wanted).map((e) => e.key); + /// Returns `true` if this instance is equivalent to [innocuous] instance (no resolution rules to apply). @override bool get isInnocuous { @@ -1453,52 +1437,31 @@ class EntityResolutionRules extends EntityRules { var bothMergeTolerant = mergeTolerant && other.mergeTolerant; - var allowEntityFetch = _allowEntityFetch; - if (other._allowEntityFetch != null) { - if (allowEntityFetch == null) { - allowEntityFetch = other._allowEntityFetch; - } else if (allowEntityFetch != other._allowEntityFetch) { - if (bothMergeTolerant) { - allowEntityFetch = null; - } else if (mergeTolerant) { - allowEntityFetch = other._allowEntityFetch; - } else if (!other.mergeTolerant) { - throw MergeEntityRulesError(this, other, 'allowEntityFetch'); - } - } - } + var allowEntityFetch = _mergeFlag( + this, + other, + _allowEntityFetch, + other._allowEntityFetch, + 'allowEntityFetch', + ); var allowReadFile = this.allowReadFile || other.allowReadFile; - var allLazy = this.allLazy; - if (other.allLazy != null) { - if (allLazy == null) { - allLazy = other.allLazy; - } else if (allLazy != other.allLazy) { - if (bothMergeTolerant) { - allLazy = null; - } else if (mergeTolerant) { - allLazy = other.allLazy; - } else if (!other.mergeTolerant) { - throw MergeEntityRulesError(this, other, 'allLazy'); - } - } - } + var allLazy = _mergeFlag( + this, + other, + this.allLazy, + other.allLazy, + 'allLazy', + ); - var allEager = this.allEager; - if (other.allEager != null) { - if (allEager == null) { - allEager = other.allEager; - } else if (allEager != other.allEager) { - if (bothMergeTolerant) { - allEager = null; - } else if (mergeTolerant) { - allEager = other.allEager; - } else if (!other.mergeTolerant) { - throw MergeEntityRulesError(this, other, 'allEager'); - } - } - } + var allEager = _mergeFlag( + this, + other, + this.allEager, + other.allEager, + 'allEager', + ); var lazyEntityTypes = this.lazyEntityTypes .merge(other.lazyEntityTypes) @@ -1525,26 +1488,23 @@ class EntityResolutionRules extends EntityRules { if (bothMergeTolerant) { merge = merge.copyWith(conflictingEntityTypes: conflict); } else { - List? lazyEntityTypes; - List? eagerEntityTypes; - - if (mergeTolerant) { - lazyEntityTypes = this.lazyEntityTypes - .without(conflict) - .merge(other.lazyEntityTypes); - - eagerEntityTypes = this.eagerEntityTypes - .without(conflict) - .merge(other.eagerEntityTypes); - } else if (other.mergeTolerant) { - lazyEntityTypes = other.lazyEntityTypes - .without(conflict) - .merge(this.lazyEntityTypes); - - eagerEntityTypes = other.eagerEntityTypes - .without(conflict) - .merge(this.eagerEntityTypes); - } + // Exactly one side is tolerant: it yields the conflicting types to + // the intolerant side. + var (tolerant, intolerant) = mergeTolerant + ? (this, other) + : (other, this); + + var lazyEntityTypes = _mergeTypesDroppingConflict( + tolerant.lazyEntityTypes, + intolerant.lazyEntityTypes, + conflict, + ); + + var eagerEntityTypes = _mergeTypesDroppingConflict( + tolerant.eagerEntityTypes, + intolerant.eagerEntityTypes, + conflict, + ); merge = EntityResolutionRules( allowEntityFetch: allowEntityFetch, @@ -1563,6 +1523,46 @@ class EntityResolutionRules extends EntityRules { return merge; } + /// Merges one tri-state flag (`allowEntityFetch`, `allLazy`, `allEager`) + /// of [mine] and [theirs], used by [merge]: + /// - A `null` side yields to the other side. + /// - On a conflict: both [EntityResolutionRules.mergeTolerant] drop the + /// flag (`null`); a tolerant [mine] yields to [theirsValue]; an intolerant + /// [mine] facing an intolerant [theirs] throws a [MergeEntityRulesError] + /// naming [name]; otherwise [mineValue] is kept. + /// + /// It's `static` because [EntityResolutionRules] is implemented (not + /// extended) by other classes, which would otherwise have to forward it. + static bool? _mergeFlag( + EntityResolutionRules mine, + EntityResolutionRules theirs, + bool? mineValue, + bool? theirsValue, + String name, + ) { + if (theirsValue == null) return mineValue; + if (mineValue == null || mineValue == theirsValue) return theirsValue; + + if (mine.mergeTolerant && theirs.mergeTolerant) { + return null; + } else if (mine.mergeTolerant) { + return theirsValue; + } else if (!theirs.mergeTolerant) { + throw MergeEntityRulesError(mine, theirs, name); + } + + return mineValue; + } + + /// Merges [tolerantTypes] (without the [conflict] types) with + /// [intolerantTypes], used by [merge] when only one side is + /// [mergeTolerant]: the tolerant side gives up its conflicting types. + static List? _mergeTypesDroppingConflict( + List? tolerantTypes, + List? intolerantTypes, + List conflict, + ) => tolerantTypes.without(conflict).merge(intolerantTypes); + static final ListEquality _listEqualityType = ListEquality(); @override @@ -1870,23 +1870,28 @@ abstract class EntityRulesContextProvider { /// Mixin to resolve the [EntityResolutionRules] to apply. mixin EntityRulesResolver { - static final Set _cotextProviders = + static final Set _contextProviders = {}; static EntityRulesContextProvider? _singleContextProvider; static void _updateSingleContextProvider() => _singleContextProvider = - _cotextProviders.length == 1 ? _cotextProviders.first : null; + _contextProviders.length == 1 ? _contextProviders.first : null; /// Returns the current [EntityRulesContextProvider]s. + static List get contextProviders => + _contextProviders.toList(); + + /// Deprecated misspelling of [contextProviders]. + @Deprecated('Use `contextProviders`') static List get cotextProviders => - _cotextProviders.toList(); + contextProviders; /// Register an [EntityRulesContextProvider]. static bool registerContextProvider( EntityRulesContextProvider contextProvider, ) { - var added = _cotextProviders.add(contextProvider); + var added = _contextProviders.add(contextProvider); _updateSingleContextProvider(); return added; } @@ -1895,7 +1900,7 @@ mixin EntityRulesResolver { static bool unregisterContextProvider( EntityRulesContextProvider contextProvider, ) { - var removed = _cotextProviders.remove(contextProvider); + var removed = _contextProviders.remove(contextProvider); _updateSingleContextProvider(); return removed; } @@ -1908,7 +1913,7 @@ mixin EntityRulesResolver { var resolutionRules = singleContextProvider .getContextEntityResolutionRules(contextZone: Zone.current); return resolutionRules; - } else if (_cotextProviders.isEmpty) { + } else if (_contextProviders.isEmpty) { return null; } @@ -1916,7 +1921,7 @@ mixin EntityRulesResolver { EntityResolutionRules? contextRule; - for (var c in _cotextProviders) { + for (var c in _contextProviders) { var resolutionRules = c.getContextEntityResolutionRules( contextZone: zone, ); diff --git a/test/bones_api_cov_entity_rules_test.dart b/test/bones_api_cov_entity_rules_test.dart index 861d0656..83a4508d 100644 --- a/test/bones_api_cov_entity_rules_test.dart +++ b/test/bones_api_cov_entity_rules_test.dart @@ -689,6 +689,9 @@ void main() { expect(EntityRulesResolver.registerContextProvider(p3), isTrue); try { + expect(EntityRulesResolver.contextProviders.length, equals(3)); + // The deprecated misspelled alias still works: + // ignore: deprecated_member_use_from_same_package expect(EntityRulesResolver.cotextProviders.length, equals(3)); var context = resolver.getContextEntityResolutionRules()!; @@ -722,7 +725,7 @@ void main() { EntityRulesResolver.unregisterContextProvider(p3); } - expect(EntityRulesResolver.cotextProviders, isEmpty); + expect(EntityRulesResolver.contextProviders, isEmpty); }); test('resolved context provider', () { From 5068dab8b69f0670c636384c547b0a997a9be0ee Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:18:44 -0300 Subject: [PATCH 04/40] Refactor DB SQL adapter: table check helpers, relationship SQLs, JOINs - `_checkDBTableScheme` split into helpers named after its sections (`_findMissingReferenceConstraints`, `_findMissingRelationshipIndexes`, `_findMissingEnumConstraints`, `_dedupeMissingEntityIndexes`, `_findEntityIndexesNameConflicts`, `_tableCheckErrorLine`), with `_sameManagerEntityTypes` for the identical to-one/to-many blocks, a local `columnsOf`, and the "No scheme" message written once. - Relationship generators: `_requireTableScheme`, `_requireRelationship`; `_generateConstrainRelationshipSQL` takes the resolved relationship; `_selectRelationshipSQLText` and `_executeSelectRelationshipSQL` shared by the single/multiple relationship selects. - JOINs: `SQLDialect.qualifiedColumnSQL` and `_joinKeyword` (same SQL). - `SQL`: `_positionalCache` declared before the method that fills it; the lazy positional fields documented. - Typo locals (`colum`, `constrainSQL`). Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_entity_db_sql.dart | 911 ++++++++++++++------------- 1 file changed, 477 insertions(+), 434 deletions(-) diff --git a/lib/src/bones_api_entity_db_sql.dart b/lib/src/bones_api_entity_db_sql.dart index c13f96de..528e81a9 100644 --- a/lib/src/bones_api_entity_db_sql.dart +++ b/lib/src/bones_api_entity_db_sql.dart @@ -192,6 +192,14 @@ class SQL implements SQLWrapper { static final RegExp _defaultPlaceholderRegexp = RegExp(r'@(\w+)'); + // The lazily computed [sqlPositional], [parametersKeysByPosition] and + // [parametersValuesByPosition] (`null`: not computed yet), filled together + // by [_computeSQLPositional] on the first access of any of them: only an + // adapter with positional placeholders (`?`) needs them. They can also be + // given to the constructor (a [copy]). Not named `*Cache` because they're + // also private named constructor parameters (`sqlPositional:` ...), whose + // public names would change. + String? _sqlPositional; List? _parametersKeysByPosition; @@ -290,6 +298,17 @@ class SQL implements SQLWrapper { return _parametersValuesByPosition!; } + /// A cache of [sqlPositional] and [parametersKeysByPosition] by SQL text + /// (default placeholder only), filled by [_computeSQLPositional]. + /// + /// Why: the same statements repeat, and converting their placeholders is a + /// regexp replace per statement: only the values are resolved per + /// instance. Cleared when it reaches [_positionalCacheLimit] (e.g. SQLs + /// with inlined values, all different). + static final Map)> _positionalCache = {}; + + static const int _positionalCacheLimit = 2000; + void _computeSQLPositional() { var keys = []; var values = []; @@ -339,13 +358,6 @@ class SQL implements SQLWrapper { _parametersValuesByPosition ??= values; } - /// [sqlPositional] and [parametersKeysByPosition] by SQL text (default - /// placeholder only). Cleared when it reaches [_positionalCacheLimit] - /// (e.g. SQLs with inlined values, all different). - static final Map)> _positionalCache = {}; - - static const int _positionalCacheLimit = 2000; - @override String toString() { var s = StringBuffer(); @@ -1242,13 +1254,10 @@ abstract class DBSQLAdapter extends DBRelationalAdapter var repoType = repository.type; if (scheme == null) { - _log.severe( - 'No scheme for repository `${repository.name}` (`$repoType`) in this adapter> generateTables: $_generateTables @ $this', - ); - - return _DBTableCheck.error( - 'No scheme for repository `${repository.name}` (`$repoType`) in this adapter> generateTables: $_generateTables @ $this', - ); + var errorMsg = + 'No scheme for repository `${repository.name}` (`$repoType`) in this adapter> generateTables: $_generateTables @ $this'; + _log.severe(errorMsg); + return _DBTableCheck.error(errorMsg); } var schemeTableName = scheme.name; @@ -1389,108 +1398,16 @@ abstract class DBSQLAdapter extends DBRelationalAdapter if (capability.constraintSupport) { // REF CONSTRAINTS // - var fieldEntityTypes = entityHandler - .getFieldsEntityTypes() - .entries - .map((e) { - var entityType = e.value.entityType; - if (entityType == null) return null; - - var refRepository = repository.provider.getEntityRepositoryByType( - entityType, - ); - - if (refRepository == null || - !refRepository.isSameEntityManager(repository)) { - return null; - } - - return MapEntry(e.key, entityType); - }) - .nonNulls - .toMapFromEntries(); - - if (fieldEntityTypes.isNotEmpty) { - var fieldsReferencedTables = scheme.fieldsReferencedTables; - - var fieldsReferences = fieldsReferencedTables.entries - .map((e) { - var colum = e.key; - var field = schemeToRepoMap[colum] ?? colum; - - var entityType = fieldEntityTypes[field]; - if (entityType == null) return null; - - var refTable = e.value.targetTable; - return MapEntry(field, refTable); - }) - .nonNulls - .toMapFromEntries(); - - missingFieldReferenceConstraints = fieldEntityTypes.keys - .where((f) => !fieldsReferences.containsKey(f)) - .toSet(); - - if (!dialect.foreignKeyCreatesImplicitIndex) { - missingFieldReferenceIndexes = fieldsReferencedTables.entries - .where((e) => e.value.indexName == null) - .map((e) => e.key) - .toSet(); - } - } + (missingFieldReferenceConstraints, missingFieldReferenceIndexes) = + _findMissingReferenceConstraints(repository, scheme, schemeToRepoMap); // RELATIONSHIP CONSTRAINTS // - var fieldListEntityTypes = entityHandler - .getFieldsListEntityTypes() - .entries - .map((e) { - var entityType = e.value.entityType; - if (entityType == null) return null; - - var refRepository = repository.provider.getEntityRepositoryByType( - entityType, - ); - - if (refRepository == null || - !refRepository.isSameEntityManager(repository)) { - return null; - } - - return MapEntry(e.key, entityType); - }) - .nonNulls - .toMapFromEntries(); - - if (fieldListEntityTypes.isNotEmpty) { - if (!dialect.foreignKeyCreatesImplicitIndex) { - missingRelationshipFieldReferenceIndexes = collectionReferenceFields - .entries - .expand((e) { - var relFieldRef = e.value; - if (relFieldRef == null) { - return <(String, String, TypeInfo)>[]; - } - - return [ - if (relFieldRef.sourceRelationshipFieldIndex == null) - ( - relFieldRef.relationshipTable, - relFieldRef.sourceRelationshipField, - relFieldRef.sourceFieldEntityType, - ), - if (relFieldRef.targetRelationshipFieldIndex == null) - ( - relFieldRef.relationshipTable, - relFieldRef.targetRelationshipField, - relFieldRef.targetFieldEntityType, - ), - ]; - }) - .nonNulls - .toSet(); - } - } + missingRelationshipFieldReferenceIndexes = + _findMissingRelationshipIndexes( + repository, + collectionReferenceFields, + ); // UNIQUE CONSTRAINTS (unique indexes unknown) // @@ -1510,49 +1427,11 @@ abstract class DBSQLAdapter extends DBRelationalAdapter // ENUM CONSTRAINTS // - var enumConstraints = scheme.constraints - .whereType() - .toList(); - - var enumConstraintsFields = enumConstraints.toFields( - fieldMap: schemeToRepoMap, + (missingEnumConstraints, missingEnumValues) = _findMissingEnumConstraints( + entityHandler, + scheme, + schemeToRepoMap, ); - - var entityEnumFields = entityHandler.getFieldsEnumTypes().keys.toList(); - - missingEnumConstraints = entityEnumFields - .whereNotIn(enumConstraintsFields) - .toSet(); - - // A column's enum values are missing only if no `CHECK` over it has - // them all: with a duplicated `CHECK` (an old one never dropped), the - // current one has them, and the duplicate is warned - // (`findTableDuplicates`). - var columnsWithAllValues = {}; - var columnsMissingValues = >{}; - - for (var e in enumConstraints) { - var valuesNames = _columnEnumValues( - entityHandler, - e.field, - schemeToRepoMap, - ); - if (valuesNames == null) continue; - - var missingValues = valuesNames.whereNotIn(e.values).toList(); - - if (missingValues.isEmpty) { - columnsWithAllValues.add(e.field); - } else { - columnsMissingValues.putIfAbsent(e.field, () => missingValues); - } - } - - for (var e in columnsMissingValues.entries) { - if (!columnsWithAllValues.contains(e.key)) { - missingEnumValues[e.key] = e.value; - } - } } // The entity's indexes (`@EntityIndex`) without an index over their @@ -1579,51 +1458,17 @@ abstract class DBSQLAdapter extends DBRelationalAdapter (f) => missingColumns.contains(f) || missingReferenceColumns.contains(f), ); - // As in the `CREATE TABLE`, not one over the same columns as another - // missing one: a unique field's constraint (reported with the field), a - // unique `@EntityIndex` (also serving a non-unique one), or the same - // index twice. - var missingUniqueColumns = [ - for (var f in missingUniqueConstraints) [fieldColumn(f)], - ]; - var missingEntityIndexesKept = []; - for (var sql in [ - ...missingEntityIndexes.where((e) => e.unique), - ...missingEntityIndexes.where((e) => !e.unique), - ]) { - var columns = sql.columns; - if (missingUniqueColumns.any((c) => c.equals(columns))) continue; - if (missingEntityIndexesKept.any( - (e) => e.columns.equals(columns) && (e.unique || !sql.unique), - )) { - continue; - } - missingEntityIndexesKept.add(sql); - } - // In the declared order: - missingEntityIndexes = missingEntityIndexes - .where(missingEntityIndexesKept.contains) - .toList(); - - // A missing index whose name is in use by another index (other - // columns, or not unique): `CREATE INDEX IF NOT EXISTS` would do - // nothing; it must be dropped first. By index name, where it's in use - // (other tables: [findIndexesNamesInUse], in `_checkDBTablesImpl`). - var entityIndexesNameConflicts = { - for (var sql in missingEntityIndexes) - if (sql.indexName case var indexName?) - if (scheme.indexes?[indexName] case var columns?) - indexName: - 'over (${columns.join(', ')})' - '${sql.unique && !(scheme.uniqueIndexes?.contains(indexName) ?? false) ? ', not unique' : ''}', - }; + missingEntityIndexes = _dedupeMissingEntityIndexes( + missingEntityIndexes, + missingUniqueColumns: [ + for (var f in missingUniqueConstraints) [fieldColumn(f)], + ], + ); - if (entityIndexesNameConflicts.isNotEmpty) { - _log.severe( - "Table `$schemeTableName`: `@EntityIndex` names in use by other " - "indexes (drop them first): $entityIndexesNameConflicts", - ); - } + var entityIndexesNameConflicts = _findEntityIndexesNameConflicts( + scheme, + missingEntityIndexes, + ); if (missingColumns.isNotEmpty || missingReferenceColumns.isNotEmpty || @@ -1637,45 +1482,36 @@ abstract class DBSQLAdapter extends DBRelationalAdapter missingEntityIndexes.isNotEmpty) { _log.severe( "ERROR Checking table `$schemeTableName`> entityType: `$repoType`\n" - "${missingEntityIndexes.isNotEmpty ? '-- missingEntityIndexes: ${missingEntityIndexes.map((e) => e.indexName).toList()}\n' : ''}" - "${missingColumns.isNotEmpty ? '-- missingColumns: $missingColumns\n' : ''}" - "${missingReferenceColumns.isNotEmpty ? '-- missingReferenceColumns: $missingReferenceColumns\n' : ''}" - "${missingCollectionReferenceColumns.isNotEmpty ? '-- missingCollectionReferenceColumns: $missingCollectionReferenceColumns\n' : ''}" - "${missingFieldReferenceConstraints.isNotEmpty ? '-- missingFieldReferenceConstraints: $missingFieldReferenceConstraints\n' : ''}" - "${missingFieldReferenceIndexes.isNotEmpty ? '-- missingFieldReferenceIndexes: $missingFieldReferenceIndexes\n' : ''}" - "${missingRelationshipFieldReferenceIndexes.isNotEmpty ? '-- missingRelationshipFieldReferenceIndexes: $missingRelationshipFieldReferenceIndexes\n' : ''}" - "${missingUniqueConstraints.isNotEmpty ? '-- missingUniqueConstraints: $missingUniqueConstraints\n' : ''}" - "${missingEnumConstraints.isNotEmpty ? '-- missingEnumConstraints: $missingEnumConstraints\n' : ''}" - "${missingEnumValues.isNotEmpty ? '-- missingEnumValues: $missingEnumValues\n' : ''}", + "${_tableCheckErrorLine('missingEntityIndexes', missingEntityIndexes.map((e) => e.indexName).toList())}" + "${_tableCheckErrorLine('missingColumns', missingColumns)}" + "${_tableCheckErrorLine('missingReferenceColumns', missingReferenceColumns)}" + "${_tableCheckErrorLine('missingCollectionReferenceColumns', missingCollectionReferenceColumns)}" + "${_tableCheckErrorLine('missingFieldReferenceConstraints', missingFieldReferenceConstraints)}" + "${_tableCheckErrorLine('missingFieldReferenceIndexes', missingFieldReferenceIndexes)}" + "${_tableCheckErrorLine('missingRelationshipFieldReferenceIndexes', missingRelationshipFieldReferenceIndexes)}" + "${_tableCheckErrorLine('missingUniqueConstraints', missingUniqueConstraints)}" + "${_tableCheckErrorLine('missingEnumConstraints', missingEnumConstraints)}" + "${_tableCheckErrorLine('missingEnumValues', missingEnumValues)}", ); + // The columns of [fields], as reported by the [_DBTableCheck]: + List<_DBTableColumn> columnsOf(Iterable fields) => fields + .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) + .toList(); + return _DBTableCheck.missing( repository, scheme, - missingColumns - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), - missingReferenceColumns - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), - missingCollectionReferenceColumns - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), - missingFieldReferenceConstraints - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), - missingFieldReferenceIndexes - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), + columnsOf(missingColumns), + columnsOf(missingReferenceColumns), + columnsOf(missingCollectionReferenceColumns), + columnsOf(missingFieldReferenceConstraints), + columnsOf(missingFieldReferenceIndexes), missingRelationshipFieldReferenceIndexes .map((f) => _DBRelationshipTableColumn(f.$1, f.$2, f.$3, [])) .toList(), - missingUniqueConstraints - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), - missingEnumConstraints - .map((f) => _DBTableColumn.fromEntityHandler(entityHandler, f)) - .toList(), + columnsOf(missingUniqueConstraints), + columnsOf(missingEnumConstraints), missingEnumValues.entries .map( (e) => MapEntry( @@ -1694,6 +1530,252 @@ abstract class DBSQLAdapter extends DBRelationalAdapter return _DBTableCheck.ok(); } + /// A line of the table check's error log (see [_checkDBTableScheme]): + /// `--
` of the selected entities ([list]) of + /// [entityRepository], with links to the related entities, and to edit, + /// delete and insert. Used by [select]. + List _buildSelectTableHTML( + EntityRepository entityRepository, + List entityRepositoryProviders, + List list, + ) { + var content = []; + + var entityType = entityRepository.type; var entityHandler = entityRepository.entityHandler; @@ -534,10 +628,28 @@ class APIDBModule extends APIModule { content.add('
'); + return content; + } + + /// The HTML of the pagination of a select of [repoName] (when it has a + /// [limit]): the range of the selected entities ([list]) and the links to + /// the previous and next pages; and the link to this page as JSON. The + /// links keep the select's [query] and directives. Used by [select]. + List _buildPaginationHTML( + String repoName, + List list, { + required String query, + required bool eager, + required int? limit, + required int? offset, + required OrderDirection? orderDirection, + }) { + var content = []; + // The query `String` of a page (`OFFSET`) of this select: String pageQuery(int? pageOffset) => [ if (query.isNotEmpty) Uri.encodeQueryComponent(query), - if (eager!) 'EAGER=true', + if (eager) 'EAGER=true', if (orderDirection != null) 'ORDER=${orderDirection.name}', 'LIMIT=${limit ?? 0}', if (pageOffset != null && pageOffset > 0) 'OFFSET=$pageOffset', @@ -568,11 +680,7 @@ class APIDBModule extends APIModule { '
', ); - htmlDoc.content = content; - - var html = htmlDoc.build(); - - return APIResponse.ok(html, mimeType: 'html'); + return content; } static const _fieldsNamesOrder = [ From e228e15a2b8e154857a755db62a575698c109f29 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:21:26 -0300 Subject: [PATCH 09/40] Fix: response cache eviction with alternatives and expiry memory accounting - `_checkMaxMemorySize` sorted `_cachedResponses.values`, which holds a `List<_CachedResponse>` for an entry with compressed alternatives (not `Comparable`): a `TypeError` on eviction. It now sorts the entries (key + all alternatives), compared by their total usage and memory size (`_CachedResponse.compareEntries`, same order as `compareTo`). - `_expire` removed the entries (200 and its 304) from the map directly, so their memory size was never subtracted from `totalMemorySize`: now through `_remove`. Tests: eviction of JSON responses with gzip alternatives; total memory back to 0 after the cached entries expire. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_server_cache.dart | 92 ++++++++++++++++------- test/bones_api_cov_server_cache_test.dart | 62 +++++++++++++++ 2 files changed, 125 insertions(+), 29 deletions(-) diff --git a/lib/src/bones_api_server_cache.dart b/lib/src/bones_api_server_cache.dart index d50d730b..c9b783a3 100644 --- a/lib/src/bones_api_server_cache.dart +++ b/lib/src/bones_api_server_cache.dart @@ -194,11 +194,13 @@ class APIServerResponseCache { _log.info( () => "REMOVED $key > File modified: ${prev.file?.path ?? key.path}", ); - _cachedResponses.remove(key); + // Through `_remove`, so the memory size of the removed entries is + // subtracted from the total (it was leaked by a direct map removal): + _remove(key); if (key.statusCode == 200) { var key304 = _CachedResponseKey(304, key.path); - var prev304 = _cachedResponses.remove(key304); + var prev304 = _remove(key304); if (prev304 != null) { _log.info( () => @@ -251,7 +253,9 @@ class APIServerResponseCache { return true; } - void _remove(_CachedResponseKey key) { + /// Removes the entry of [key] (with all its alternatives), subtracting its + /// memory size from the total. Returns the removed value, if any. + Object? _remove(_CachedResponseKey key) { var prev = _cachedResponses.remove(key); if (prev != null) { @@ -263,6 +267,8 @@ class APIServerResponseCache { } } } + + return prev; } bool _checkMaxMemorySize() { @@ -270,28 +276,33 @@ class APIServerResponseCache { var targetMemory = maxMemorySize * 0.80; - var cachedResponses = _cachedResponses.values.toList(); - cachedResponses.sort(); + // Sorted per entry (key), not per value: a value with compressed + // alternatives is a `List<_CachedResponse>`, which isn't `Comparable` + // (sorting the raw values threw a `TypeError`). + var evictionCandidates = _cachedResponses.entries + .map((e) => (key: e.key, cachedEntries: e.value.asCachedEntries!)) + .toList(); + + evictionCandidates.sort( + (a, b) => + _CachedResponse.compareEntries(a.cachedEntries, b.cachedEntries), + ); var totalRemoved = 0; var totalMemoryRemoved = 0; - for (var entry in cachedResponses) { - var cachedEntries = entry.asCachedEntries; - - if (cachedEntries != null && cachedEntries.isNotEmpty) { - for (var cached in cachedEntries) { - ++totalRemoved; - totalMemoryRemoved += cached.memorySize; - } + for (var (:key, :cachedEntries) in evictionCandidates) { + for (var cached in cachedEntries) { + ++totalRemoved; + totalMemoryRemoved += cached.memorySize; + } - // All the alternatives of an entry share its key: `_remove` drops the - // whole entry (and its memory size) at once. - _remove(cachedEntries.first.key); + // `_remove` drops the whole entry (all its alternatives) and its + // memory size at once. + _remove(key); - if (_totalCachedResponsesMemorySize <= targetMemory) { - break; - } + if (_totalCachedResponsesMemorySize <= targetMemory) { + break; } } @@ -956,18 +967,41 @@ abstract class _CachedResponse bool validate(Request request); @override - int compareTo(_CachedResponse other) { - int cmp; - - { - var use1 = usageCount ~/ 1000; - var use2 = other.usageCount ~/ 1000; - cmp = use2.compareTo(use1); - } + int compareTo(_CachedResponse other) => _compareUsageAndMemory( + usageCount, + memorySize, + other.usageCount, + other.memorySize, + ); + + /// Compares two cache entries (a response and its compressed + /// alternatives) as [compareTo] compares two responses, using the totals + /// of each entry ([usageCount] and [memorySize] summed): the entry is + /// stored and evicted as a whole. Used to sort the eviction candidates in + /// `APIServerResponseCache._checkMaxMemorySize`. + static int compareEntries( + List<_CachedResponse> entries1, + List<_CachedResponse> entries2, + ) => _compareUsageAndMemory( + entries1.map((e) => e.usageCount).sum, + entries1.map((e) => e.memorySize).sum, + entries2.map((e) => e.usageCount).sum, + entries2.map((e) => e.memorySize).sum, + ); + + /// The order of [compareTo] and [compareEntries]: by usage (in buckets of + /// 1000) then by memory size (in buckets of 8 KB), both descending. + static int _compareUsageAndMemory( + int usage1, + int memory1, + int usage2, + int memory2, + ) { + var cmp = (usage2 ~/ 1000).compareTo(usage1 ~/ 1000); if (cmp == 0) { - var m1 = memorySize ~/ (1024 * 8); - var m2 = other.memorySize ~/ (1024 * 8); + var m1 = memory1 ~/ (1024 * 8); + var m2 = memory2 ~/ (1024 * 8); cmp = m2.compareTo(m1); } diff --git a/test/bones_api_cov_server_cache_test.dart b/test/bones_api_cov_server_cache_test.dart index a0908866..031ab532 100644 --- a/test/bones_api_cov_server_cache_test.dart +++ b/test/bones_api_cov_server_cache_test.dart @@ -1014,6 +1014,68 @@ void main() { expect(cache.toString(), contains('fileStatTimeout: 2 d')); }); + test('max memory size cleaning: entries with alternatives', () async { + // Entries with compressed alternatives are stored as a `List`: the + // eviction sorted the raw values and threw a `TypeError` on them. + var cache = APIServerResponseCache( + maxMemorySize: 1024 * 1024, + fileStatTimeout: Duration(days: 2), + ); + + var inner = _FakeStaticHandler(tmpDir); + for (var i = 0; i < 8; ++i) { + var content = List.generate(30000, (j) => 'f$i:${j * 7919}').join(','); + inner.overrides['t$i.json'] = (request) => Response.ok( + utf8.encode('[$content]'), + headers: {'content-type': 'application/json'}, + ); + } + + var handler = cache.middleware(inner.call); + + for (var i = 0; i < 8; ++i) { + var r = await handler(_get('t$i.json')); + expect(r.statusCode, equals(200)); + + // A compressed alternative of the same entry: + var rGz = await handler( + _get('t$i.json', headers: {'accept-encoding': 'gzip'}), + ); + expect(rGz.statusCode, equals(200)); + expect(rGz.headers['content-encoding'], equals('gzip')); + } + + expect(inner.calls, equals(8)); + expect(cache.totalMemorySize, lessThanOrEqualTo(1024 * 1024 * 1.5)); + expect(cache.cachedResponsesLength, lessThan(8)); + }); + + test('expired entries: memory size subtracted', () async { + var file = writeFile('e.txt', 'Hello E'); + + var cache = APIServerResponseCache(fileStatTimeout: Duration.zero); + var inner = _FakeStaticHandler(tmpDir); + var handler = cache.middleware(inner.call); + + var r1 = await handler(_get('e.txt')); + expect(await _readBody(r1), equals('Hello E')); + + // 200 + 304: + expect(cache.cachedResponsesLength, equals(2)); + expect(cache.totalMemorySize, greaterThan(0)); + + file.writeAsStringSync('Hello E - modified!'); + file.setLastModifiedSync(DateTime.now().add(Duration(seconds: 10))); + await Future.delayed(Duration(milliseconds: 5)); + + // A lookup of the modified file expires its 200 and 304 entries + // (without caching anything new): + expect(await cache.getCachedResponse(_get('e.txt')), isNull); + + expect(cache.cachedResponsesLength, equals(0)); + expect(cache.totalMemorySize, equals(0)); + }); + test('multi-value headers + previous server-timing', () async { var cache = APIServerResponseCache(); var inner = _FakeStaticHandler(tmpDir); From 0f5c2fe4f331235f46df641438a02a5146e2eccc Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:22:11 -0300 Subject: [PATCH 10/40] Fix: `\'` in a single-quoted condition string `characterEscapeValue2` used `characterEscape`, whose pattern excludes `'`, so `Condition.parse("name == 'a\\'b'")` failed (`"\'" expected`); the unused `jsonEscapeCharsString2` was meant for it. Now `characterEscape2`. Test in bones_api_condition_test.dart. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_condition_parser.dart | 9 ++++++++- test/bones_api_condition_test.dart | 9 +++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/lib/src/bones_api_condition_parser.dart b/lib/src/bones_api_condition_parser.dart index 27be55ff..2e33f91b 100644 --- a/lib/src/bones_api_condition_parser.dart +++ b/lib/src/bones_api_condition_parser.dart @@ -96,11 +96,18 @@ abstract class JsonGrammarLexer extends GrammarDefinition { Parser characterEscape() => char('\\') & pattern(jsonEscapeCharsString); + /// The escapes of a single-quoted string: also `\'` + /// ([jsonEscapeCharsString2]). + Parser characterEscape2() => + char('\\') & pattern(jsonEscapeCharsString2); + Parser characterEscapeValue() => characterEscape().map((each) => jsonEscapeChars[each[1]]!); + // With [characterEscape2]: [characterEscape] doesn't accept `\'`, so a + // single-quoted string with an escaped quote (`'a\'b'`) didn't parse. Parser characterEscapeValue2() => - characterEscape().map((each) => jsonEscapeChars2[each[1]]!); + characterEscape2().map((each) => jsonEscapeChars2[each[1]]!); Parser characterUnicode() => string('\\u') & pattern('0-9A-Fa-f').times(4); diff --git a/test/bones_api_condition_test.dart b/test/bones_api_condition_test.dart index 31dce907..06a29e01 100644 --- a/test/bones_api_condition_test.dart +++ b/test/bones_api_condition_test.dart @@ -65,6 +65,15 @@ void main() { group('ConditionParser', () { setUp(() {}); + test(r"escaped quote in a single-quoted string (\')", () { + var c = Condition.parse(r"name == 'a\'b'") as KeyConditionEQ; + expect(c.value, equals("a'b")); + + // The other escapes, as in a double-quoted string: + var c2 = Condition.parse(r'''name == 'a\"b\\c\nd' ''') as KeyConditionEQ; + expect(c2.value, equals('a"b\\c\nd')); + }); + test('key op value', () async { var conditionParser = ConditionParser(); From 4d78ba18ee6fba40eef10705e7c9fac1809a23f1 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:22:42 -0300 Subject: [PATCH 11/40] Fix: SQLDialect.toString lists all its fields It lacked a space after `name: $name,` and omitted `acceptsVarcharWithoutMaximumSize`, `intParameterTypeSuffix`, `maxIDsAsParameters`, `regExpSyntax` and `subqueryAsDerivedTable`. Tests in bones_api_cov_sql_builder_test.dart. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_sql_builder.dart | 9 ++++++-- test/bones_api_cov_sql_builder_test.dart | 29 ++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/lib/src/bones_api_sql_builder.dart b/lib/src/bones_api_sql_builder.dart index 6f8c517a..bd9eb5d2 100644 --- a/lib/src/bones_api_sql_builder.dart +++ b/lib/src/bones_api_sql_builder.dart @@ -258,7 +258,7 @@ class SQLDialect extends DBDialect { @override String toString() { return 'SQLDialect{' - 'name: $name,' + 'name: $name, ' 'elementQuote: $elementQuote, ' 'acceptsOutputSyntax: $acceptsOutputSyntax, ' 'acceptsReturningSyntax: $acceptsReturningSyntax, ' @@ -267,6 +267,7 @@ class SQLDialect extends DBDialect { 'acceptsInsertDefaultValues: $acceptsInsertDefaultValues, ' 'acceptsInsertIgnore: $acceptsInsertIgnore, ' 'acceptsInsertOnConflict: $acceptsInsertOnConflict, ' + 'acceptsVarcharWithoutMaximumSize: $acceptsVarcharWithoutMaximumSize, ' 'foreignKeyCreatesImplicitIndex: $foreignKeyCreatesImplicitIndex, ' 'createIndexIfNotExists: $createIndexIfNotExists, ' 'alterTableAddConstraint: $alterTableAddConstraint, ' @@ -274,7 +275,11 @@ class SQLDialect extends DBDialect { 'dropIndexOnTable: $dropIndexOnTable, ' 'offsetRequiresLimit: $offsetRequiresLimit, ' 'offsetMaxLimitValue: $offsetMaxLimitValue, ' - 'maxIdentifierLength: $maxIdentifierLength' + 'maxIdentifierLength: $maxIdentifierLength, ' + 'intParameterTypeSuffix: $intParameterTypeSuffix, ' + 'maxIDsAsParameters: $maxIDsAsParameters, ' + 'regExpSyntax: ${regExpSyntax.name}, ' + 'subqueryAsDerivedTable: $subqueryAsDerivedTable' '}'; } } diff --git a/test/bones_api_cov_sql_builder_test.dart b/test/bones_api_cov_sql_builder_test.dart index da2dccb6..1e780ee4 100644 --- a/test/bones_api_cov_sql_builder_test.dart +++ b/test/bones_api_cov_sql_builder_test.dart @@ -240,8 +240,33 @@ void main() { expect(d1, equals(d2)); expect(d1.hashCode, equals(d2.hashCode)); expect(d1, isNot(equals(d3))); - expect(d1.toString(), startsWith('SQLDialect{name: X,elementQuote: ", ')); - expect(d1.toString(), endsWith('maxIdentifierLength: null}')); + expect( + d1.toString(), + startsWith('SQLDialect{name: X, elementQuote: ", '), + ); + expect(d1.toString(), endsWith('subqueryAsDerivedTable: false}')); + }); + + test('SQLDialect: toString with all the fields', () { + const d = SQLDialect( + 'Z', + elementQuote: '`', + acceptsVarcharWithoutMaximumSize: true, + maxIdentifierLength: 64, + intParameterTypeSuffix: ':int8', + maxIDsAsParameters: 0, + regExpSyntax: SQLRegExpSyntax.dart, + subqueryAsDerivedTable: true, + ); + + var s = d.toString(); + expect(s, contains('name: Z, elementQuote: `, ')); + expect(s, contains('acceptsVarcharWithoutMaximumSize: true, ')); + expect(s, contains('maxIdentifierLength: 64, ')); + expect(s, contains('intParameterTypeSuffix: :int8, ')); + expect(s, contains('maxIDsAsParameters: 0, ')); + expect(s, contains('regExpSyntax: dart, ')); + expect(s, endsWith('subqueryAsDerivedTable: true}')); }); test('CreateTableSQL: constraints as ALTER TABLE', () { From 1d5cc08e6a5b252bb13236269c02fe5704fafacb Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:23:06 -0300 Subject: [PATCH 12/40] Refactor entity references and extensions: shared helpers, doc fixes - EntityReference.fromJson: _fromInstantiator for the two instantiator blocks; uses EntityInstantiatorHandler.resolveEntityMap (the private duplicate removed). - EntityReferenceBase: _toStringPrefix and _compareIDPresence shared by EntityReference and EntityReferenceList (the list-vs-list arm now tested); dead branch in _castListNullable removed. - TypeInfo extension: parseEntity/entityType merged branches; _castEntityHandler for the castCall of toEntityReference(List). - MapGetterExtension: _parseValue (getParsed/getMultiKeyParsed tail), one key loop, _scanKeyIgnoreCase shared by getIgnoreCase and matchKeyIgnoreCase; docs name defaultValue (not def), and getMultiKeyAsString parses as String. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_entity_reference.dart | 187 +++++++++--------- lib/src/bones_api_extension.dart | 150 +++++++------- test/bones_api_cov_entity_reference_test.dart | 25 +++ 3 files changed, 192 insertions(+), 170 deletions(-) diff --git a/lib/src/bones_api_entity_reference.dart b/lib/src/bones_api_entity_reference.dart index 975b46f1..22a5ccf8 100644 --- a/lib/src/bones_api_entity_reference.dart +++ b/lib/src/bones_api_entity_reference.dart @@ -461,6 +461,31 @@ abstract class EntityReferenceBase { @override String toString({bool withT = true}); + + /// The head of [toString]: ` className` (` ` only + /// [withT]), the type from the known [Type], else the type name, else `?`. + /// Shared by [EntityReference] and [EntityReferenceList]. + String _toStringPrefix(String className, bool withT) { + var typeStr = _type?.toString() ?? _typeName ?? '?'; + var prefix = '$className<$typeStr>'; + return withT ? ' $prefix' : prefix; + } + + /// The tail of `equalsEntityID`/`equalsEntitiesIDs` when comparing with + /// another reference: by ID(s) only when both sides have them + /// ([compareIDs]); `false` when only one side has them; `null` (unknown) + /// when neither has. + static bool? _compareIDPresence( + bool otherHasIDs, + bool thisHasIDs, + bool Function() compareIDs, + ) { + if (otherHasIDs) { + return thisHasIDs ? compareIDs() : false; + } else { + return thisHasIDs ? false : null; + } + } } /// Reference wrapper to an entity. @@ -638,30 +663,21 @@ class EntityReference extends EntityReferenceBase { ); if (entityHandler != null) { - var instantiator = EntityInstantiatorHandler( - entityHandler, + return _fromInstantiator( id, entity, - entityCache: entityCache, - entityHandlerProvider: entityHandlerProvider, + type, + typeName, + entityHandler, + entityProvider, + entityHandlerProvider, + entityFetcher, + entityCache, ); - - return EntityReference.fromEntityInstantiator( - id, - instantiator, - type: type, - typeName: typeName, - entityHandler: entityHandler, - entityProvider: entityProvider, - entityHandlerProvider: entityHandlerProvider, - entityFetcher: entityFetcher, - entityCache: entityCache, - checkGenericType: false, - )._autoCast(); } } - var entityMapCast = _resolveEntityMap(entity); + var entityMapCast = EntityInstantiatorHandler.resolveEntityMap(entity); return EntityReference.fromEntityMap( entityMapCast, @@ -709,26 +725,17 @@ class EntityReference extends EntityReferenceBase { if (entityHandler != null) { var id = entityHandler.getIDFromMap(json); if (id != null) { - var instantiator = EntityInstantiatorHandler( - entityHandler, + return _fromInstantiator( id, json, - entityCache: entityCache, - entityHandlerProvider: entityHandlerProvider, + type, + typeName, + entityHandler, + entityProvider, + entityHandlerProvider, + entityFetcher, + entityCache, ); - - return EntityReference.fromEntityInstantiator( - id, - instantiator, - type: type, - typeName: typeName, - entityHandler: entityHandler, - entityProvider: entityProvider, - entityHandlerProvider: entityHandlerProvider, - entityFetcher: entityFetcher, - entityCache: entityCache, - checkGenericType: false, - )._autoCast(); } } @@ -746,15 +753,42 @@ class EntityReference extends EntityReferenceBase { } } - static Map _resolveEntityMap(Object entity) { - var entityMap = entity is Map - ? entity - : TypeParser.parseMap(entity) ?? {}; + /// An [EntityReference] with [id] whose entity is instantiated (lazily) + /// from [entityMap] by an [EntityInstantiatorHandler] (which also caches + /// the instantiator in [entityCache]). Used by [EntityReference.fromJson] + /// when the entity handler and the ID are known: for an `EntityReference` + /// JSON with an `entity`, and for an entity JSON. + static EntityReference _fromInstantiator( + Object id, + Object entityMap, + Type? type, + String? typeName, + EntityHandler entityHandler, + EntityProvider? entityProvider, + EntityHandlerProvider? entityHandlerProvider, + EntityFetcher? entityFetcher, + EntityCache? entityCache, + ) { + var instantiator = EntityInstantiatorHandler( + entityHandler, + id, + entityMap, + entityCache: entityCache, + entityHandlerProvider: entityHandlerProvider, + ); - var entityMapCast = entityMap is Map - ? entityMap - : entityMap.map((key, value) => MapEntry('$key', value)); - return entityMapCast; + return EntityReference.fromEntityInstantiator( + id, + instantiator, + type: type, + typeName: typeName, + entityHandler: entityHandler, + entityProvider: entityProvider, + entityHandlerProvider: entityHandlerProvider, + entityFetcher: entityFetcher, + entityCache: entityCache, + checkGenericType: false, + )._autoCast(); } /// Creates an [EntityReference] from [o] trying to resolve it in the best way. @@ -1328,19 +1362,11 @@ class EntityReference extends EntityReferenceBase { return true; } - if (otherEntity.isIdSet) { - if (isIdSet) { - return id == otherEntity.id; - } else { - return false; - } - } else { - if (isIdSet) { - return false; - } else { - return null; - } - } + return EntityReferenceBase._compareIDPresence( + otherEntity.isIdSet, + isIdSet, + () => id == otherEntity.id, + ); } else if (otherEntity is T) { if (isEntitySet && identical(entity, otherEntity)) return true; @@ -1361,9 +1387,7 @@ class EntityReference extends EntityReferenceBase { @override String toString({bool withT = true}) { - var typeStr = _type?.toString() ?? _typeName ?? '?'; - var prefix = 'EntityReference<$typeStr>'; - if (withT) prefix = ' $prefix'; + var prefix = _toStringPrefix('EntityReference', withT); if (isNull) { return '$prefix{null}'; @@ -1928,14 +1952,11 @@ class EntityReferenceList extends EntityReferenceBase { static List? _castListNullable(List? l) { if (l == null) return null; + // (A `List` is also a `List`.) if (l is List) { return l; } - if (l is List) { - return l; - } - if (l.every((e) => e is E)) { return l.map((e) => e as E).toList(); } @@ -2568,19 +2589,11 @@ class EntityReferenceList extends EntityReferenceBase { return true; } - if (otherEntities.isIdSet) { - if (isIDsSet) { - return _idsEquality.equals(ids, [otherEntities.id]); - } else { - return false; - } - } else { - if (isIDsSet) { - return false; - } else { - return null; - } - } + return EntityReferenceBase._compareIDPresence( + otherEntities.isIdSet, + isIDsSet, + () => _idsEquality.equals(ids, [otherEntities.id]), + ); } else if (otherEntities is EntityReferenceList) { if (type != otherEntities.type) return false; @@ -2594,19 +2607,11 @@ class EntityReferenceList extends EntityReferenceBase { return true; } - if (otherEntities.isIDsSet) { - if (isIDsSet) { - return _idsEquality.equals(ids, otherEntities.ids); - } else { - return false; - } - } else { - if (isIDsSet) { - return false; - } else { - return null; - } - } + return EntityReferenceBase._compareIDPresence( + otherEntities.isIDsSet, + isIDsSet, + () => _idsEquality.equals(ids, otherEntities.ids), + ); } else if (otherEntities is T) { if (isEntitiesSet && _listIdenticalEquality.equals(entities, [otherEntities])) { @@ -2647,9 +2652,7 @@ class EntityReferenceList extends EntityReferenceBase { @override String toString({bool withT = true}) { - var typeStr = _type?.toString() ?? _typeName ?? '?'; - var prefix = 'EntityReferenceList<$typeStr>'; - if (withT) prefix = ' $prefix'; + var prefix = _toStringPrefix('EntityReferenceList', withT); if (isNull) { return '$prefix{null}'; diff --git a/lib/src/bones_api_extension.dart b/lib/src/bones_api_extension.dart index 0bf36f37..132f9603 100644 --- a/lib/src/bones_api_extension.dart +++ b/lib/src/bones_api_extension.dart @@ -241,27 +241,29 @@ extension MapGetterExtension on Map { return defaultValue; } - var keyStr = key.toString(); + var match = _scanKeyIgnoreCase(key); + if (match == null) return defaultValue; - for (var k in keys) { - if (equalsIgnoreAsciiCase(keyStr, k.toString())) { - var value = this[k]; - return value ?? defaultValue; - } - } - - return defaultValue; + return this[match.$1] ?? defaultValue; } /// Returns the existing key that matches [key] as case-insensitive. K? matchKeyIgnoreCase(K key) { if (containsKey(key)) return key; + return _scanKeyIgnoreCase(key)?.$1; + } + /// The first key (in [keys] order) whose `toString` equals [key]'s, + /// ignoring ASCII case, wrapped in a record (so a `null` key can be a + /// match), or `null` if none. The key scan of [getIgnoreCase] and + /// [matchKeyIgnoreCase] (each one checks the exact [key] its own way + /// first: by a non-null value, or by [containsKey]). + (K,)? _scanKeyIgnoreCase(K key) { var keyStr = key.toString(); for (var k in keys) { if (equalsIgnoreAsciiCase(keyStr, k.toString())) { - return k; + return (k,); } } @@ -276,7 +278,7 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [bool]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. bool? getAsBool(K key, {bool? defaultValue, bool ignoreCase = false}) => getParsed( key, @@ -287,7 +289,7 @@ extension MapGetterExtension on Map { /// Gets the value of the first matching [keys], parsing as [bool]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. bool? getMultiKeyAsBool( List keys, { bool? defaultValue, @@ -301,7 +303,7 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [int]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. int? getAsInt(K key, {int? defaultValue, bool ignoreCase = false}) => getParsed( key, @@ -312,7 +314,7 @@ extension MapGetterExtension on Map { /// Gets the value of the first matching [keys], parsing as [int]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. int? getMultiKeyAsInt( List keys, { int? defaultValue, @@ -326,7 +328,7 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [double]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. double? getAsDouble(K key, {double? defaultValue, bool ignoreCase = false}) => getParsed( key, @@ -337,7 +339,7 @@ extension MapGetterExtension on Map { /// Gets the value of the first matching [keys], parsing as [double]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. double? getMultiKeyAsDouble( List keys, { double? defaultValue, @@ -351,7 +353,7 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing to [num] type. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. num? getAsNum(K key, {num? defaultValue, bool ignoreCase = false}) => getParsed( key, @@ -362,7 +364,7 @@ extension MapGetterExtension on Map { /// Gets the value of the first matching [keys], parsing as [num]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. num? getMultiKeyAsNum( List keys, { num? defaultValue, @@ -376,7 +378,7 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [String]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. String? getAsString(K key, {String? defaultValue, bool ignoreCase = false}) => getParsed( key, @@ -385,9 +387,9 @@ extension MapGetterExtension on Map { ignoreCase: ignoreCase, ); - /// Gets the value of the first matching [keys], parsing as [num]. + /// Gets the value of the first matching [keys], parsing as [String]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. String? getMultiKeyAsString( List keys, { String? defaultValue, @@ -401,7 +403,8 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [List]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. + /// - [def] is the [TypeParser.parseList] default (for a value it can't parse). /// - [elementParser] is the parser to use for each element in the [List]. List? getAsList( K key, { @@ -418,7 +421,8 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [Map]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. + /// - [def] is the [TypeParser.parseMap] default (for a value it can't parse). /// - [keyParser] is the parser to use for each key in the [Map]. /// - [valueParser] is the parser to use for each value in the [Map]. Map? getAsMap( @@ -442,7 +446,8 @@ extension MapGetterExtension on Map { /// Gets a [key] value parsing as [Set]. /// - /// - [def] is the default value if the value is invalid. + /// - [defaultValue] is the default value if the value is absent or invalid. + /// - [def] is the [TypeParser.parseSet] default (for a value it can't parse). /// - [elementParser] is the parser to use for each element in the [Set]. Set? getAsSet( K key, { @@ -467,18 +472,7 @@ extension MapGetterExtension on Map { bool ignoreCase = false, }) { var value = ignoreCase ? getIgnoreCase(key) : this[key]; - - T? v; - - if (parser != null) { - v = parser(value); - } else if (value is T?) { - v = value; - } else { - throw ArgumentError("Can't parse key('$key') value as `$T`: $value"); - } - - return v ?? defaultValue; + return _parseValue(value, parser, defaultValue, () => '$key'); } /// Same as [getParsed] but accepts multiple [keys]. @@ -488,27 +482,35 @@ extension MapGetterExtension on Map { T? defaultValue, bool ignoreCase = false, }) { + // The value of the first key with a (non-null) value: V? value; - if (ignoreCase) { - for (var k in keys) { - value = getIgnoreCase(k); - if (value != null) break; - } - } else { - for (var k in keys) { - value = this[k]; - if (value != null) break; - } + for (var k in keys) { + value = ignoreCase ? getIgnoreCase(k) : this[k]; + if (value != null) break; } + return _parseValue(value, parser, defaultValue, () => keys.join("','")); + } + + /// Parses [value] with [parser] (or, without a parser, accepts it if it's + /// already a [T]), returning [defaultValue] when the result is `null`. + /// Throws an [ArgumentError] (naming [keyDescription]) if [value] can't be + /// a [T]. The shared tail of [getParsed] and [getMultiKeyParsed]. + static T? _parseValue( + Object? value, + TypeElementParser? parser, + T? defaultValue, + String Function() keyDescription, + ) { T? v; + if (parser != null) { v = parser(value); } else if (value is T?) { v = value; } else { throw ArgumentError( - "Can't parse key('${keys.join("','")}') value as `$T`: $value", + "Can't parse key('${keyDescription()}') value as `$T`: $value", ); } @@ -672,15 +674,10 @@ extension TypeInfoEntityExtension on TypeInfo { Type? get entityType { var type = this.type; - Type? entityType; - - if (type.isEntityReferenceBaseType) { - entityType = arguments0?.type; - } else if (isList) { - entityType = arguments0?.type; - } else { - entityType = type; - } + // A reference or a `List`: the element (argument #0) type. + var entityType = type.isEntityReferenceBaseType || isList + ? arguments0?.type + : type; return EntityHandler.isValidEntityType(entityType) ? entityType : null; } @@ -717,12 +714,8 @@ extension TypeInfoEntityExtension on TypeInfo { } E? parseEntity(Object? value) { - if (isEntityReferenceType) { - var entityType = arguments0; - if (entityType != null) { - return entityType.parse(value); - } - } else if (isEntityReferenceListType) { + // A reference: parsed as its entity type (argument #0), when known. + if (isEntityReferenceType || isEntityReferenceListType) { var entityType = arguments0; if (entityType != null) { return entityType.parse(value); @@ -830,19 +823,12 @@ extension TypeInfoEntityExtension on TypeInfo { } EntityReference castCall() { - EntityHandler? oEntityHandler; - if (entityHandler != null) { - oEntityHandler = entityHandler is EntityHandler - ? (entityHandler as EntityHandler) - : entityHandler.getEntityHandler(type: type); - } - return _toEntityReferenceImpl( o, id, type, typeName, - oEntityHandler, + _castEntityHandler(entityHandler, type), entityProvider, entityHandlerProvider, entityFetcher as EntityFetcher?, @@ -853,6 +839,21 @@ extension TypeInfoEntityExtension on TypeInfo { return callCasted(castCall) as EntityReference; } + /// [entityHandler] as an [EntityHandler] of [E] (the type argument + /// [callCasted] resolves): itself if it already is one, otherwise the + /// one it provides for [E] ([type]). Used by the `castCall`s of + /// [toEntityReference] and [toEntityReferenceList]. + static EntityHandler? _castEntityHandler( + EntityHandler? entityHandler, + Type? type, + ) { + if (entityHandler == null) return null; + + return entityHandler is EntityHandler + ? entityHandler + : entityHandler.getEntityHandler(type: type); + } + EntityReference _toEntityReferenceImpl( Object? o, Object? id, @@ -971,18 +972,11 @@ extension TypeInfoEntityExtension on TypeInfo { } EntityReferenceList castCall() { - EntityHandler? oEntityHandler; - if (entityHandler != null) { - oEntityHandler = entityHandler is EntityHandler - ? (entityHandler as EntityHandler) - : entityHandler.getEntityHandler(type: type); - } - return _toEntityReferenceListImpl( o, type, typeName, - oEntityHandler, + _castEntityHandler(entityHandler, type), entityProvider, entityHandlerProvider, entitiesFetcher as EntitiesFetcher?, diff --git a/test/bones_api_cov_entity_reference_test.dart b/test/bones_api_cov_entity_reference_test.dart index 1642d5d0..41cecc1e 100644 --- a/test/bones_api_cov_entity_reference_test.dart +++ b/test/bones_api_cov_entity_reference_test.dart @@ -984,6 +984,31 @@ void main() { isFalse, ); + // `EntityReferenceList` compared by IDs (a non-null list always has + // IDs: resolved from its entities, `null` for an entity without ID): + var lNullID1 = EntityReferenceList<_Thing>.fromEntities([ + _Thing(null, 'x'), + ]); + var lNullID2 = EntityReferenceList<_Thing>.fromEntities([ + _Thing(null, 'y'), + ]); + expect( + lIDs.equalsEntitiesIDs(EntityReferenceList<_Thing>.fromIDs([1])), + isTrue, + ); + expect( + lIDs.equalsEntitiesIDs(EntityReferenceList<_Thing>.fromIDs([2])), + isFalse, + ); + expect(lIDs.equalsEntitiesIDs(lNullID1), isFalse); + expect(lNullID1.equalsEntitiesIDs(lIDs), isFalse); + expect(lNullID1.equalsEntitiesIDs(lNullID2), isTrue); + expect(lIDs.equalsEntitiesIDs(lNull), isFalse); + expect( + lNull.equalsEntitiesIDs(EntityReferenceList<_Thing>.asNull()), + isTrue, + ); + // With `T`: expect(l.equalsEntitiesIDs(t1), isTrue); expect(l.equalsEntitiesIDs(t2), isNull); From e382ef3f48d678066edb13b5ce66a2cbbdca8b43 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:23:51 -0300 Subject: [PATCH 13/40] Fix: user home directory resolution; JSON-decode error log - `_getUserDirectory` fell back to `Directory('~/')`, a literal `~` directory (relative to the current one), not the home directory. The home is now resolved only from `HOME`/`USERPROFILE` (Windows first tries `USERPROFILE`, the others `HOME`, each with the other as fallback), in the new `APIServerConfig.resolveUserDirectory` (`@visibleForTesting`). The identical macOS and Linux branches are merged. - `_resolvePayloadFromString`: `catch (e, s)` shadowed the payload `s`, so the JSON-decode error log printed the stack trace in place of the payload: now `catch (e, stackTrace)`. Tests: `resolveUserDirectory` (incl. a literal `~` directory in the current directory being ignored); the decode error log shows the payload. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_server.dart | 47 ++++++----- test/bones_api_cov_server_config_test.dart | 97 ++++++++++++++++++++-- 2 files changed, 117 insertions(+), 27 deletions(-) diff --git a/lib/src/bones_api_server.dart b/lib/src/bones_api_server.dart index d643be84..f1148fe1 100644 --- a/lib/src/bones_api_server.dart +++ b/lib/src/bones_api_server.dart @@ -10,6 +10,7 @@ import 'package:brotli_fast/brotli_fast.dart' show BrotliErrorCode, BrotliException; import 'package:collection/collection.dart'; import 'package:logging/logging.dart' as logging; +import 'package:meta/meta.dart' show visibleForTesting; import 'package:mime/mime.dart'; import 'package:path/path.dart' as pack_path; import 'package:reflection_factory/reflection_factory.dart'; @@ -1053,30 +1054,37 @@ class APIServerConfig { return null; } - static Directory? _getUserDirectory() { - var envVars = Platform.environment; + static Directory? _getUserDirectory() => + resolveUserDirectory(Platform.environment, isWindows: Platform.isWindows); - String? home; - if (Platform.isMacOS) { - home = envVars['HOME']; - } else if (Platform.isLinux) { - home = envVars['HOME']; - } else if (Platform.isWindows) { - home = envVars['UserProfile']; - } + /// Resolves the user's home directory from the environment variables + /// [envVars]: `USERPROFILE` on Windows, else `HOME` (each with the other as + /// fallback). Returns `null` if not defined or not an existing directory. + /// + /// The shell's `~` is not used as a fallback: `Directory('~/')` is a + /// literal directory named `~` (relative to the current directory), not + /// the home directory. + @visibleForTesting + static Directory? resolveUserDirectory( + Map envVars, { + required bool isWindows, + }) { + // `Platform.environment` keys are case-insensitive on Windows, but a + // plain `Map` (tests) is not: try both spellings of `USERPROFILE`. + var userProfile = envVars['USERPROFILE'] ?? envVars['UserProfile']; + var home = envVars['HOME']; + + var candidates = isWindows ? [userProfile, home] : [home, userProfile]; - if (home != null) { - var dir = Directory(home); + for (var path in candidates) { + if (path == null || path.trim().isEmpty) continue; + + var dir = Directory(path); if (dir.existsSync()) { return dir.absolute; } } - var dir = Directory('~/'); - if (dir.existsSync()) { - return dir.absolute; - } - return null; } @@ -2147,11 +2155,12 @@ class APIServer extends _APIServerBase { if (s.isEmpty) return null; try { payload = json.decode(s); - } catch (e, s) { + } catch (e, stackTrace) { + // Not `s`: it would shadow the payload `s` logged below. _log.severe( "_resolvePayloadFromString> Error decoding JSON: <<$s>>", e, - s, + stackTrace, ); return null; } diff --git a/test/bones_api_cov_server_config_test.dart b/test/bones_api_cov_server_config_test.dart index 1877cb9c..f9c0ad36 100644 --- a/test/bones_api_cov_server_config_test.dart +++ b/test/bones_api_cov_server_config_test.dart @@ -6,6 +6,7 @@ import 'dart:typed_data'; import 'package:args_simple/args_simple.dart'; import 'package:bones_api/bones_api_server.dart'; import 'package:bones_api/src/bones_api_server_cache.dart'; +import 'package:logging/logging.dart' as logging; import 'package:path/path.dart' as pack_path; import 'package:shelf/shelf.dart'; import 'package:test/test.dart'; @@ -538,6 +539,64 @@ void main() { } }); + test('resolveUserDirectory', () { + var home = tmpDir.absolute.path; + var other = pack_path.join(home, 'other'); + Directory(other).createSync(); + + expect( + APIServerConfig.resolveUserDirectory({ + 'HOME': home, + }, isWindows: false)!.path, + equals(home), + ); + expect( + APIServerConfig.resolveUserDirectory({ + 'USERPROFILE': home, + 'HOME': other, + }, isWindows: true)!.path, + equals(home), + ); + expect( + APIServerConfig.resolveUserDirectory({ + 'UserProfile': home, + }, isWindows: true)!.path, + equals(home), + ); + // Fallback to the other variable: + expect( + APIServerConfig.resolveUserDirectory({ + 'USERPROFILE': home, + }, isWindows: false)!.path, + equals(home), + ); + + // Not defined, blank or not existing: `null`. Never a literal `~` + // directory (the shell's `~` is not expanded by `Directory`): + var cwd = Directory.current; + Directory.current = tmpDir; + try { + Directory('~').createSync(); + expect( + APIServerConfig.resolveUserDirectory({}, isWindows: false), + isNull, + ); + } finally { + Directory.current = cwd; + } + + expect( + APIServerConfig.resolveUserDirectory({'HOME': ' '}, isWindows: false), + isNull, + ); + expect( + APIServerConfig.resolveUserDirectory({ + 'HOME': pack_path.join(home, 'nope'), + }, isWindows: false), + isNull, + ); + }); + test('resolve* from APIConfig', () { var apiConfig = APIConfig({ 'server': { @@ -1356,15 +1415,37 @@ void main() { }), ); - var invalid = await toAPIRequest( - Request( - 'POST', - Uri.parse('http://localhost/a'), - headers: {'content-type': 'application/json'}, - body: '{invalid', - ), - ); + // The error log shows the invalid payload (the `catch` variable + // shadowed it, logging the stack trace in its place): + var records = []; + var sub = logging.Logger.root.onRecord.listen((r) { + if (r.message.contains('Error decoding JSON')) records.add(r); + }); + + var prevLevel = logging.Logger.root.level; + logging.Logger.root.level = logging.Level.ALL; + + APIRequest invalid; + try { + invalid = await toAPIRequest( + Request( + 'POST', + Uri.parse('http://localhost/a'), + headers: {'content-type': 'application/json'}, + body: '{invalid', + ), + ); + await Future.delayed(Duration(milliseconds: 10)); + } finally { + logging.Logger.root.level = prevLevel; + await sub.cancel(); + } + expect(invalid.payload, isNull); + expect(records, hasLength(1)); + expect(records.first.message, contains('<<{invalid>>')); + expect(records.first.error, isA()); + expect(records.first.stackTrace, isNotNull); var blank = await toAPIRequest( Request( From f1cc81a1d99704646daad38215ef2684aae782e1 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:23:51 -0300 Subject: [PATCH 14/40] Fix: `IdenticalSet` groups elements by `identityHashCode` It bucketed elements by `hashCode`: an element whose `hashCode` changed after being added was looked up in another group, so `contains`, `add` and `remove` missed it. An identity set now uses `identityHashCode`. Test: an element with a changing `hashCode`. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_utils.dart | 5 +++- test/bones_api_utils_collection_test.dart | 34 +++++++++++++++++++++++ 2 files changed, 38 insertions(+), 1 deletion(-) diff --git a/lib/src/bones_api_utils.dart b/lib/src/bones_api_utils.dart index 20d59e61..af55add9 100644 --- a/lib/src/bones_api_utils.dart +++ b/lib/src/bones_api_utils.dart @@ -435,7 +435,10 @@ class IdenticalSet { : _groups = List.filled(groups.clamp(2, 1000), null); List _getGroup(Object? o) { - var h = o.hashCode; + // `identityHashCode`, not `hashCode`: elements are matched by identity, + // and an element whose `hashCode` changes (a mutable object) would be + // looked up in another group (not found by `contains`/`remove`). + var h = identityHashCode(o); var gIdx = h % _groups.length; var g = _groups[gIdx] ??= []; return g; diff --git a/test/bones_api_utils_collection_test.dart b/test/bones_api_utils_collection_test.dart index 63db1731..6fef0adb 100644 --- a/test/bones_api_utils_collection_test.dart +++ b/test/bones_api_utils_collection_test.dart @@ -5,6 +5,20 @@ import 'package:test/test.dart'; import 'bones_api_test_entities.dart'; +/// An object whose [hashCode] can change (a mutable key). +class _MutableHash { + int hash; + + _MutableHash(this.hash); + + @override + bool operator ==(Object other) => + identical(this, other) || other is _MutableHash && hash == other.hash; + + @override + int get hashCode => hash; +} + void main() { group('Enum', () { test('enumFromName', () async { @@ -79,6 +93,26 @@ void main() { expect(s1.toList(), unorderedEquals(['b'])); }); + + test('element with a changing hashCode', () { + // Bucketed by `hashCode`, an element was looked up in another group + // after its `hashCode` changed: not found by `contains`/`remove`. + var s = IdenticalSet<_MutableHash>(groups: 7); + + var o = _MutableHash(1); + expect(s.add(o), isTrue); + + for (var h = 2; h <= 7; ++h) { + o.hash = h; + expect(s.contains(o), isTrue, reason: 'hash: $h'); + expect(s.add(o), isFalse, reason: 'hash: $h'); + } + + expect(s.length, equals(1)); + expect(s.remove(o), isTrue); + expect(s.isEmpty, isTrue); + expect(s.toList(), isEmpty); + }); }); group('isEqualsDeep', () { From c33b80f088a406ea4ffca54e99af9eef3bddf995 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:23:51 -0300 Subject: [PATCH 15/40] Fix: `getFieldsKeysInMap` normalizes each field It passed the caller's `fieldLC`/`fieldSimple` (the normalized forms of ONE field) to the lookup of every field, so all the fields after the first matched that same key. They are now computed per field; the two parameters are kept (public API) but ignored and `@Deprecated`. The `mapLC` and `mapSimple` indexes (per map) are still shared by all the fields. (No caller in the package passed them.) Test: two fields with `fieldLC`/`fieldSimple` and shared indexes. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_mixin.dart | 22 ++++++++++------------ test/bones_api_cov_pool_weaklist_test.dart | 21 +++++++++++++++++++++ 2 files changed, 31 insertions(+), 12 deletions(-) diff --git a/lib/src/bones_api_mixin.dart b/lib/src/bones_api_mixin.dart index aa786e98..132a0d9c 100644 --- a/lib/src/bones_api_mixin.dart +++ b/lib/src/bones_api_mixin.dart @@ -705,13 +705,18 @@ mixin FieldsFromMap { return MapEntry(field, value); } - /// Returns a [Map] of [field] keys from [map]. - /// - [field] is case insensitive. + /// Returns a [Map] of [fields] keys from [map]. + /// - The [fields] are case insensitive. + /// - [mapLC] and [mapSimple] (indexes of [map], see [getFieldKeyInMap]) + /// are shared by all the [fields]. + /// - [fieldLC] and [fieldSimple] are ignored: they are the normalized + /// forms of ONE field, computed per field (passing them used the same + /// normalized key for every field). Map getFieldsKeysInMap( List fields, Map map, { - String? fieldLC, - String? fieldSimple, + @Deprecated("Ignored: computed per field") String? fieldLC, + @Deprecated("Ignored: computed per field") String? fieldSimple, Map? mapLC, Map? mapSimple, }) { @@ -719,14 +724,7 @@ mixin FieldsFromMap { .map( (f) => MapEntry( f, - getFieldKeyInMap( - f, - map, - fieldLC: fieldLC, - fieldSimple: fieldSimple, - mapLC: mapLC, - mapSimple: mapSimple, - ), + getFieldKeyInMap(f, map, mapLC: mapLC, mapSimple: mapSimple), ), ) .toMapFromEntries(); diff --git a/test/bones_api_cov_pool_weaklist_test.dart b/test/bones_api_cov_pool_weaklist_test.dart index f3ae5b40..2a25e812 100644 --- a/test/bones_api_cov_pool_weaklist_test.dart +++ b/test/bones_api_cov_pool_weaklist_test.dart @@ -455,6 +455,27 @@ void main() { f.getFieldsKeysInMap(['id', 'email'], {'ID': 1}), equals({'id': 'ID', 'email': null}), ); + + // The normalized forms are computed per field: a `fieldLC` / + // `fieldSimple` (of one field) is not used for every field. The + // `mapLC`/`mapSimple` indexes are shared: + var mapLC = {}; + var mapSimple = {}; + expect( + f.getFieldsKeysInMap( + ['userId', 'emailAddress'], + {'USERID': 1, 'email_address': 'e'}, + // ignore: deprecated_member_use_from_same_package + fieldLC: 'userid', + // ignore: deprecated_member_use_from_same_package + fieldSimple: 'userid', + mapLC: mapLC, + mapSimple: mapSimple, + ), + equals({'userId': 'USERID', 'emailAddress': 'email_address'}), + ); + expect(mapLC, isNotEmpty); + expect(mapSimple, isNotEmpty); }); }); From 45bc448a50d58ca5eafd40cc6450cb519dc8d362 Mon Sep 17 00:00:00 2001 From: "Graciliano M. P." Date: Sun, 8 Nov 2026 05:23:53 -0300 Subject: [PATCH 16/40] Fix: APIDBModule.select escapes the entities values in its HTML The values (and IDs in links) were written into the HTML as is: a value with `<` or `&` broke the page and could inject markup or scripts. Now escaped with `HtmlEscape` (element text; attribute for the links). Test in bones_api_cov_db_module_test.dart. Co-Authored-By: Claude Opus 5.5 --- lib/src/bones_api_db_module.dart | 37 ++++++++++++++++++++------ test/bones_api_cov_db_module_test.dart | 30 +++++++++++++++++++++ 2 files changed, 59 insertions(+), 8 deletions(-) diff --git a/lib/src/bones_api_db_module.dart b/lib/src/bones_api_db_module.dart index 3d1f3393..dda0f8ec 100644 --- a/lib/src/bones_api_db_module.dart +++ b/lib/src/bones_api_db_module.dart @@ -1,3 +1,4 @@ +import 'dart:convert' show HtmlEscape, HtmlEscapeMode; import 'dart:typed_data'; import 'package:archive/archive.dart'; @@ -591,29 +592,36 @@ class APIDBModule extends APIModule { content.add(''); + // A related entity's ID (also a `String` one) is escaped as any + // value, in the link and its text: + String idLink(Object? id) => + '' + '${_escapeHTML(id)}'; + if (v2 is List) { - var ids = v2 - .map((e) => '$e') - .join(' , '); - content.add(ids); + content.add(v2.map(idLink).join(' , ')); } else { - content.add('$v2'); + content.add(idLink(v2)); } content.add(''); } else { - content.add('$v2'); + content.add('${_escapeHTML(v2)}'); } } var id = entityHandler.getID(o); if (id != null) { + var idAttr = _escapeHTMLAttribute(id); + content.add('   [ '); - content.add('edit'); + content.add('edit'); - content.add('  |  del'); + content.add( + '  |  del', + ); content.add(' ]  '); } @@ -631,6 +639,19 @@ class APIDBModule extends APIModule { return content; } + /// [value] (its `toString`) escaped as HTML text (`&`, `<`, `>`): an + /// entity's value (e.g. a name with `<`) would otherwise be read as HTML + /// (and could inject markup or scripts in the page). Used by + /// [_buildSelectTableHTML]. + static String _escapeHTML(Object? value) => + const HtmlEscape(HtmlEscapeMode.element).convert('$value'); + + /// [value] (its `toString`) escaped for an HTML attribute value between + /// `"` (as [_escapeHTML], also `"`): an entity's ID in a link. Used by + /// [_buildSelectTableHTML]. + static String _escapeHTMLAttribute(Object? value) => + const HtmlEscape(HtmlEscapeMode.attribute).convert('$value'); + /// The HTML of the pagination of a select of [repoName] (when it has a /// [limit]): the range of the selected entities ([list]) and the links to /// the previous and next pages; and the link to this page as JSON. The diff --git a/test/bones_api_cov_db_module_test.dart b/test/bones_api_cov_db_module_test.dart index daf7b93d..d97415e1 100644 --- a/test/bones_api_cov_db_module_test.dart +++ b/test/bones_api_cov_db_module_test.dart @@ -247,6 +247,36 @@ void main() { expect({...stores, ...closedStores}, equals({1, 2, 3})); }); + test('select (HTML) escapes the entities values', () async { + var repository = provider.getEntityRepository()!; + + var info = UserInfo(' & bold'); + var id = await repository.store(info); + + try { + var tables = (await get('/db/tables/json')).payload as Map; + var table = tables['UserInfo'] as String; + + var response = await get('/db/select/$table'); + expect(response.isOK, isTrue); + + var html = response.payload as String; + expect(html, isNot(contains('