Merge pull request #2 from isoos/update

Updated query API methods to always return non-null values.

Author: isoos

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.3.0-null-safety.1
+
+- Updated public API to always return non-nullable results.
+- **BREAKING CHANGE**: unknown mapped table name is no longer `null`, it is empty string (`''`).
+
 ## 2.3.0-null-safety.0
 
 - Migrate to null safety. (Thanks to [j4qfrost](https://github.com/j4qfrost), [#153](https://github.com/stablekernel/postgresql-dart/pull/153)).

lib/src/connection.dart

@@ -390,10 +390,6 @@ class _OidCache {
       resolveOids: false,
     );
 
-    if (orderedTableNames == null) {
-      return;
-    }
-
     final iterator = oids.iterator;
     orderedTableNames.forEach((tableName) {
       iterator.moveNext();
@@ -416,7 +412,7 @@ abstract class _PostgreSQLExecutionContextMixin
   int get queueSize => _queue.length;
 
   @override
-  Future<PostgreSQLResult?> query(
+  Future<PostgreSQLResult> query(
     String fmtString, {
     Map<String, dynamic>? substitutionValues,
     bool allowReuse = true,
@@ -429,7 +425,7 @@ abstract class _PostgreSQLExecutionContextMixin
         timeoutInSeconds: timeoutInSeconds,
       );
 
-  Future<PostgreSQLResult?> _query(
+  Future<PostgreSQLResult> _query(
     String fmtString, {
     Map<String, dynamic>? substitutionValues,
     required bool allowReuse,
@@ -458,18 +454,16 @@ abstract class _PostgreSQLExecutionContextMixin
     }
     final metaData = _PostgreSQLResultMetaData(columnDescriptions!);
 
-    return queryResult != null
-        ? _PostgreSQLResult(
-            queryResult.affectedRowCount,
-            metaData,
-            queryResult.value!
-                .map((columns) => _PostgreSQLResultRow(metaData, columns))
-                .toList())
-        : null;
+    return _PostgreSQLResult(
+        queryResult.affectedRowCount,
+        metaData,
+        queryResult.value!
+            .map((columns) => _PostgreSQLResultRow(metaData, columns))
+            .toList());
   }
 
   @override
-  Future<List<Map<String?, Map<String, dynamic>>>> mappedResultsQuery(
+  Future<List<Map<String, Map<String, dynamic>>>> mappedResultsQuery(
       String fmtString,
       {Map<String, dynamic> substitutionValues = const {},
       bool allowReuse = false,
@@ -481,14 +475,11 @@ abstract class _PostgreSQLExecutionContextMixin
       timeoutInSeconds: timeoutInSeconds,
     );
 
-    if (rs == null) {
-      return Future.value();
-    }
     return rs.map((row) => row.toTableColumnMap()).toList();
   }
 
   @override
-  Future<int?> execute(String fmtString,
+  Future<int> execute(String fmtString,
       {Map<String, dynamic> substitutionValues = const {},
       int? timeoutInSeconds}) async {
     timeoutInSeconds ??= _connection.queryTimeoutInSeconds;
@@ -502,13 +493,13 @@ abstract class _PostgreSQLExecutionContextMixin
         onlyReturnAffectedRowCount: true);
 
     final result = await _enqueue(query, timeoutInSeconds: timeoutInSeconds);
-    return result != null ? result.affectedRowCount : null;
+    return result.affectedRowCount;
   }
 
   @override
-  void cancelTransaction({String reason});
+  void cancelTransaction({String? reason});
 
-  Future<QueryResult<T>?> _enqueue<T>(Query<T> query,
+  Future<QueryResult<T>> _enqueue<T>(Query<T> query,
       {int timeoutInSeconds = 30}) async {
     if (_queue.add(query)) {
       _connection._transitionToState(_connection._connectionState.awake());
@@ -518,7 +509,7 @@ abstract class _PostgreSQLExecutionContextMixin
             await query.future.timeout(Duration(seconds: timeoutInSeconds));
         _connection._cache.add(query);
         _queue.remove(query);
-        return result;
+        return result!;
       } catch (e, st) {
         _queue.remove(query);
         await _onQueryError(query, e, st);
@@ -529,20 +520,20 @@ abstract class _PostgreSQLExecutionContextMixin
       // the caller behaves correctly in this condition. otherwise,
       // the caller would complete synchronously. This future
       // will always complete as a cancellation error.
-      return Future(() async => query.future);
+      return Future(() async => (await query.future)!);
     }
   }
 
   Future _onQueryError(Query query, dynamic error, [StackTrace? trace]) async {}
 }
 
 class _PostgreSQLResultMetaData {
-  final List<ColumnDescription?> columnDescriptions;
+  final List<ColumnDescription> columnDescriptions;
   late List<String?> _tableNames;
 
   _PostgreSQLResultMetaData(this.columnDescriptions) {
     _tableNames =
-        columnDescriptions.map((column) => column!.tableName).toSet().toList();
+        columnDescriptions.map((column) => column.tableName).toSet().toList();
   }
 
   List<String?> get tableNames {
@@ -561,7 +552,7 @@ class _PostgreSQLResult extends UnmodifiableListView<PostgreSQLResultRow>
       : super(rows);
 
   @override
-  List<ColumnDescription?> get columnDescriptions =>
+  List<ColumnDescription> get columnDescriptions =>
       _metaData.columnDescriptions;
 }
 
@@ -572,18 +563,18 @@ class _PostgreSQLResultRow extends UnmodifiableListView
   _PostgreSQLResultRow(this._metaData, List columns) : super(columns);
 
   @override
-  List<ColumnDescription?> get columnDescriptions =>
+  List<ColumnDescription> get columnDescriptions =>
       _metaData.columnDescriptions;
 
   @override
-  Map<String?, Map<String, dynamic>> toTableColumnMap() {
-    final rowMap = <String?, Map<String, dynamic>>{};
+  Map<String, Map<String, dynamic>> toTableColumnMap() {
+    final rowMap = <String, Map<String, dynamic>>{};
     _metaData.tableNames.forEach((tableName) {
-      rowMap[tableName] = <String, dynamic>{};
+      rowMap[tableName ?? ''] = <String, dynamic>{};
     });
     for (var i = 0; i < _metaData.columnDescriptions.length; i++) {
       final col = _metaData.columnDescriptions[i];
-      rowMap[col!.tableName]![col.columnName] = this[i];
+      rowMap[col.tableName]![col.columnName] = this[i];
     }
     return rowMap;
   }
@@ -593,7 +584,7 @@ class _PostgreSQLResultRow extends UnmodifiableListView
     final rowMap = <String, dynamic>{};
     for (var i = 0; i < _metaData.columnDescriptions.length; i++) {
       final col = _metaData.columnDescriptions[i];
-      rowMap[col!.columnName] = this[i];
+      rowMap[col.columnName] = this[i];
     }
     return rowMap;
   }

lib/src/execution_context.dart

@@ -29,7 +29,7 @@ abstract class PostgreSQLExecutionContext {
   /// By default, instances of this class will reuse queries. This allows significantly more efficient transport to and from the database. You do not have to do
   /// anything to opt in to this behavior, this connection will track the necessary information required to reuse queries without intervention. (The [fmtString] is
   /// the unique identifier to look up reuse information.) You can disable reuse by passing false for [allowReuse].
-  Future<PostgreSQLResult?> query(String fmtString,
+  Future<PostgreSQLResult> query(String fmtString,
       {Map<String, dynamic> substitutionValues,
       bool allowReuse,
       int? timeoutInSeconds});
@@ -41,14 +41,14 @@ abstract class PostgreSQLExecutionContext {
   /// This method returns the number of rows affected and no additional information. This method uses the least efficient and less secure command
   /// for executing queries in the PostgreSQL protocol; [query] is preferred for queries that will be executed more than once, will contain user input,
   /// or return rows.
-  Future<int?> execute(String fmtString,
+  Future<int> execute(String fmtString,
       {Map<String, dynamic> substitutionValues, int? timeoutInSeconds});
 
   /// Cancels a transaction on this context.
   ///
   /// If this context is an instance of [PostgreSQLConnection], this method has no effect. If the context is a transaction context (passed as the argument
   /// to [PostgreSQLConnection.transaction]), this will rollback the transaction.
-  void cancelTransaction({String reason});
+  void cancelTransaction({String? reason});
 
   /// Executes a query on this connection and returns each row as a [Map].
   ///
@@ -80,7 +80,7 @@ abstract class PostgreSQLExecutionContext {
   ///           "company: {"name": "stable|kernel"}
   ///         }
   ///       ]
-  Future<List<Map<String?, Map<String, dynamic>>>> mappedResultsQuery(
+  Future<List<Map<String, Map<String, dynamic>>>> mappedResultsQuery(
       String fmtString,
       {Map<String, dynamic> substitutionValues,
       bool allowReuse,
@@ -93,18 +93,18 @@ abstract class ColumnDescription {
   String get columnName;
 
   /// The resolved name of the referenced table.
-  String? get tableName;
+  String get tableName;
 }
 
 /// A single row of a query result.
 ///
 /// Column values can be accessed through the `[]` operator.
 abstract class PostgreSQLResultRow implements List {
-  List<ColumnDescription?> get columnDescriptions;
+  List<ColumnDescription> get columnDescriptions;
 
   /// Returns a two-level map that on the first level contains the resolved
   /// table name, and on the second level the column name (or its alias).
-  Map<String?, Map<String, dynamic>> toTableColumnMap();
+  Map<String, Map<String, dynamic>> toTableColumnMap();
 
   /// Returns a single-level map that maps the column name (or its alias) to the
   /// value returned on that position.
@@ -117,5 +117,5 @@ abstract class PostgreSQLResultRow implements List {
 abstract class PostgreSQLResult implements List<PostgreSQLResultRow> {
   /// How many rows did this query affect?
   int get affectedRowCount;
-  List<ColumnDescription?> get columnDescriptions;
+  List<ColumnDescription> get columnDescriptions;
 }

lib/src/query.dart

@@ -244,7 +244,7 @@ class FieldDescription implements ColumnDescription {
   final int formatCode;
 
   @override
-  final String? tableName;
+  final String tableName;
 
   FieldDescription._(
     this.converter,
@@ -281,7 +281,7 @@ class FieldDescription implements ColumnDescription {
     return FieldDescription._(
       converter, fieldName, tableID, columnID, typeID,
       dataTypeSize, typeModifier, formatCode,
-      null, // tableName
+      '', // tableName
     );
   }
 

pubspec.yaml

@@ -1,13 +1,13 @@
 name: postgres
 description: PostgreSQL database driver. Supports statement reuse and binary protocol.
-version: 2.3.0-null-safety.0
+version: 2.3.0-null-safety.1
 homepage: https://github.com/isoos/postgresql-dart
 
 environment:
   sdk: '>=2.12.0 <3.0.0'
 
 dependencies:
-  buffer: ^1.0.6
+  buffer: ^1.1.0
   crypto: ^3.0.0
   collection: ^1.15.0-nullsafety.4
 

test/connection_test.dart

@@ -105,10 +105,11 @@ void main() {
           username: 'darttrust');
       await conn.open();
 
+      final rs = await conn.query('select 1');
       final errors = [];
       final catcher = (e) {
         errors.add(e);
-        return null;
+        return rs;
       };
       final futures = [
         conn.query('select 1', allowReuse: false).catchError(catcher),
@@ -131,11 +132,12 @@ void main() {
       conn = PostgreSQLConnection('localhost', 5432, 'dart_test',
           username: 'darttrust', useSSL: true);
       await conn.open();
+      final rs = await conn.query('select 1');
 
       final errors = [];
       final catcher = (e) {
         errors.add(e);
-        return null;
+        return rs;
       };
       final futures = [
         conn.query('select 1', allowReuse: false).catchError(catcher),

test/decode_test.dart

@@ -40,7 +40,7 @@ void main() {
   test('Fetch em', () async {
     final res = await connection.query('select * from t');
 
-    final row1 = res![0];
+    final row1 = res[0];
     final row2 = res[1];
     final row3 = res[2];
 

test/encoding_test.dart

@@ -393,7 +393,7 @@ Future expectInverse(dynamic value, PostgreSQLDataType dataType) async {
   final result = await conn.query(
       'INSERT INTO t (v) VALUES (${PostgreSQLFormat.id('v', type: dataType)}) RETURNING v',
       substitutionValues: {'v': value});
-  expect(result!.first.first, equals(value));
+  expect(result.first.first, equals(value));
 
   final encoder = PostgresBinaryEncoder(dataType);
   final encodedValue = encoder.convert(value);

test/map_return_test.dart

@@ -125,7 +125,7 @@ void main() {
     final result = await connection.mappedResultsQuery('SELECT 1');
     expect(result, [
       {
-        null: {'?column?': 1}
+        '': {'?column?': 1}
       }
     ]);
   });

test/query_reuse_test.dart

@@ -547,23 +547,24 @@ void main() {
     test(
         'Send two queries that will be the same prepared statement async, first one fails on bind',
         () async {
+      final rs = await connection.query('SELECT 1');
       await connection.query(
           'insert into u (i1, i2) values (@i1:int4, @i2:int4) returning i1, i2',
           substitutionValues: {'i1': 1, 'i2': 2},
           allowReuse: false);
 
       final string = 'select i1, i2 from u where i1 = @i:int4';
       // ignore: unawaited_futures
-      connection
-          .query(string, substitutionValues: {'i': 'foo'}).catchError((e) {});
+      connection.query(string,
+          substitutionValues: {'i': 'foo'}).catchError((e) => rs);
 
       final results =
           await connection.query(string, substitutionValues: {'i': 1});
 
       expect(results, [
         [1, 2]
       ]);
-      expect(getQueryCache(connection).length, 1);
+      expect(getQueryCache(connection).length, 2); // 1: SELECT 1
       expect(hasCachedQueryNamed(connection, string), true);
     });
   });

test/query_test.dart

@@ -38,9 +38,9 @@ void main() {
       expect(result, [expectedRow]);
 
       result = await connection.query('select t from t');
-      expect(result!.columnDescriptions, hasLength(1));
-      expect(result.columnDescriptions.single!.tableName, 't');
-      expect(result.columnDescriptions.single!.columnName, 't');
+      expect(result.columnDescriptions, hasLength(1));
+      expect(result.columnDescriptions.single.tableName, 't');
+      expect(result.columnDescriptions.single.columnName, 't');
       expect(result, [expectedRow]);
     });
 
@@ -154,11 +154,11 @@ void main() {
         {'a': 'b'},
         '01234567-89ab-cdef-0123-0123456789ab'
       ];
-      expect(result!.columnDescriptions, hasLength(14));
-      expect(result.columnDescriptions.first!.tableName, 't');
-      expect(result.columnDescriptions.first!.columnName, 'i');
-      expect(result.columnDescriptions.last!.tableName, 't');
-      expect(result.columnDescriptions.last!.columnName, 'u');
+      expect(result.columnDescriptions, hasLength(14));
+      expect(result.columnDescriptions.first.tableName, 't');
+      expect(result.columnDescriptions.first.columnName, 'i');
+      expect(result.columnDescriptions.last.tableName, 't');
+      expect(result.columnDescriptions.last.columnName, 'u');
       expect(result, [expectedRow]);
       result = await connection.query(
           'select i,s, bi, bs, bl, si, t, f, d, dt, ts, tsz, j, u from t');
@@ -363,13 +363,13 @@ void main() {
         () async {
       final rs1 = await connection
           .query('SELECT *  FROM (VALUES (\'user@domain.com\')) t1 (col1)');
-      expect(rs1!.first.toColumnMap(), {'col1': 'user@domain.com'});
+      expect(rs1.first.toColumnMap(), {'col1': 'user@domain.com'});
 
       final rs2 = await connection.query(
         'SELECT *  FROM (VALUES (\'user@domain.com\')) t1 (col1) WHERE col1 > @u1',
         substitutionValues: {'u1': 'hello@domain.com'},
       );
-      expect(rs2!.first.toColumnMap(), {'col1': 'user@domain.com'});
+      expect(rs2.first.toColumnMap(), {'col1': 'user@domain.com'});
     });
 
     test('Wrong type for parameter in substitution values fails', () async {