eng: add query v1.3 (#504)

Author: tshedor

MIGRATING.md

@@ -1,51 +1,234 @@
 include: package:lints/recommended.yaml
 
-# Additional information about this file can be found at
-# https://dart.dev/guides/language/analysis-options
-
 linter:
   rules:
+    # This list is derived from the list of all available lints located at
+    # https://github.com/dart-lang/linter/blob/master/example/all.yaml
     - always_declare_return_types
+    # - always_put_control_body_on_new_line
+    # - always_put_required_named_parameters_first
+    # - always_specify_types
     - always_use_package_imports
+    - annotate_overrides
+    # - avoid_annotating_with_dynamic
     - avoid_bool_literals_in_conditional_expressions
+    # - avoid_catches_without_on_clauses
+    # - avoid_catching_errors
+    - avoid_classes_with_only_static_members
+    - avoid_double_and_int_checks
+    # - avoid_dynamic_calls
+    - avoid_empty_else
+    # - avoid_equals_and_hash_code_on_mutable_classes
     - avoid_escaping_inner_quotes
+    - avoid_field_initializers_in_const_classes
+    # - avoid_final_parameters
+    - avoid_function_literals_in_foreach_calls
+    - avoid_implementing_value_types
+    - avoid_init_to_null
+    - avoid_js_rounded_ints
+    - avoid_multiple_declarations_per_line
+    - avoid_null_checks_in_equality_operators
+    # - avoid_positional_boolean_parameters
+    - avoid_print
+    - avoid_private_typedef_functions
+    - avoid_redundant_argument_values
+    - avoid_relative_lib_imports
+    - avoid_renaming_method_parameters
+    - avoid_return_types_on_setters
+    - avoid_returning_null_for_void
+    - avoid_returning_this
+    - avoid_setters_without_getters
+    - avoid_shadowing_type_parameters
+    - avoid_single_cascade_in_expression_statements
+    - avoid_slow_async_io
+    - avoid_type_to_string
+    - avoid_types_as_parameter_names
+    # - avoid_types_on_closure_parameters
+    - avoid_unnecessary_containers
+    - avoid_unused_constructor_parameters
     - avoid_void_async
+    - avoid_web_libraries_in_flutter
+    - await_only_futures
     - camel_case_extensions
     - camel_case_types
+    - cancel_subscriptions
+    - cascade_invocations
+    - cast_nullable_to_non_nullable
+    # - close_sinks
+    - collection_methods_unrelated_type
+    - combinators_ordering
+    - comment_references
+    - conditional_uri_does_not_exist
+    - constant_identifier_names
+    - control_flow_in_finally
     - curly_braces_in_flow_control_structures
+    - dangling_library_doc_comments
+    - depend_on_referenced_packages
+    - deprecated_consistency
+    - deprecated_member_use_from_same_package
+    # - diagnostic_describe_all_properties
     - directives_ordering
     - discarded_futures
+    - do_not_use_environment
+    - empty_catches
+    - empty_constructor_bodies
+    - empty_statements
     - eol_at_end_of_file
+    - exhaustive_cases
     - file_names
+    - flutter_style_todos
+    - hash_and_equals
+    - implementation_imports
+    - implicit_call_tearoffs
+    - implicit_reopen
     - invalid_case_patterns
+    - join_return_with_assignment
+    # - leading_newlines_in_multiline_strings
+    - library_annotations
+    - library_names
+    - library_prefixes
+    - library_private_types_in_public_api
+    # - lines_longer_than_80_chars
+    - literal_only_boolean_expressions
     - matching_super_parameters
+    - missing_whitespace_between_adjacent_strings
+    - no_adjacent_strings_in_list
+    - no_default_cases
+    - no_duplicate_case_values
+    - no_leading_underscores_for_library_prefixes
+    - no_leading_underscores_for_local_identifiers
     - no_literal_bool_comparisons
+    - no_logic_in_create_state
+    - no_runtimeType_toString
+    - no_self_assignments
+    - no_wildcard_variable_uses
+    - non_constant_identifier_names
+    - noop_primitive_operations
+    - null_check_on_nullable_type_parameter
+    - null_closures
+    - omit_local_variable_types
+    - one_member_abstracts
+    - only_throw_errors
+    - overridden_fields
+    - package_api_docs
+    - package_names
+    - package_prefixed_library_names
+    - parameter_assignments
+    - prefer_adjacent_string_concatenation
+    - prefer_asserts_in_initializer_lists
+    - prefer_asserts_with_message
+    - prefer_collection_literals
+    - prefer_conditional_assignment
+    - prefer_const_constructors
+    - prefer_const_constructors_in_immutables
+    - prefer_const_declarations
+    - prefer_const_literals_to_create_immutables
+    - prefer_constructors_over_static_methods
+    - prefer_contains
+    # - prefer_double_quotes
+    # - prefer_expression_function_bodies
+    - prefer_final_fields
+    - prefer_final_in_for_each
     - prefer_final_locals
+    # - prefer_final_parameters
+    - prefer_for_elements_to_map_fromIterable
+    - prefer_foreach
+    - prefer_function_declarations_over_variables
+    - prefer_generic_function_type_aliases
+    - prefer_if_elements_to_conditional_expressions
+    - prefer_if_null_operators
+    - prefer_initializing_formals
+    - prefer_inlined_adds
+    - prefer_int_literals
+    - prefer_interpolation_to_compose_strings
     - prefer_is_empty
     - prefer_is_not_empty
+    - prefer_is_not_operator
+    - prefer_iterable_whereType
+    - prefer_mixin
+    - prefer_null_aware_method_calls
+    - prefer_null_aware_operators
+    # - prefer_relative_imports
     - prefer_single_quotes
+    - prefer_spread_collections
+    - prefer_typing_uninitialized_variables
+    - prefer_void_to_null
+    - provide_deprecation_message
+    - public_member_api_docs
+    - recursive_getters
     - require_trailing_commas
+    - secure_pubspec_urls
+    - sized_box_for_whitespace
+    - sized_box_shrink_expand
+    - slash_for_doc_comments
+    - sort_child_properties_last
+    # - sort_constructors_first
+    - sort_pub_dependencies
+    - sort_unnamed_constructors_first
+    - test_types_in_equals
+    - throw_in_finally
+    - tighten_type_of_initializing_formals
+    - type_annotate_public_apis
+    - type_init_formals
     - type_literal_in_constant_pattern
     - unawaited_futures
+    # - unnecessary_await_in_return
+    - unnecessary_brace_in_string_interps
+    - unnecessary_breaks
+    - unnecessary_const
+    - unnecessary_constructor_name
+    # - unnecessary_final
+    - unnecessary_getters_setters
     - unnecessary_lambdas
+    - unnecessary_late
+    - unnecessary_library_directive
+    - unnecessary_new
+    - unnecessary_null_aware_assignments
+    - unnecessary_null_aware_operator_on_extension_on_nullable
+    - unnecessary_null_checks
+    - unnecessary_null_in_if_null_operators
+    - unnecessary_nullable_for_final_variable_declarations
+    - unnecessary_overrides
     - unnecessary_parenthesis
     - unnecessary_raw_strings
     - unnecessary_statements
+    - unnecessary_string_escapes
+    - unnecessary_string_interpolations
+    - unnecessary_this
     - unnecessary_to_list_in_spreads
+    # - unreachable_from_main
+    - unrelated_type_equality_checks
+    - unsafe_html
+    - use_build_context_synchronously
+    - use_colored_box
+    - use_decorated_box
+    - use_enums
+    - use_full_hex_values_for_flutter_colors
+    - use_function_type_syntax_for_parameters
     - use_if_null_to_convert_nulls_to_bools
+    - use_is_even_rather_than_modulo
+    - use_key_in_widget_constructors
+    - use_late_for_private_fields_and_variables
+    - use_named_constants
     - use_raw_strings
+    - use_rethrow_when_possible
+    - use_setters_to_change_properties
+    - use_string_buffers
+    - use_string_in_part_of_directives
     - use_super_parameters
+    - use_test_throws_matchers
     - use_to_and_as_if_applicable
-    - unnecessary_breaks
+    - valid_regexps
+    - void_checks
 
 analyzer:
-  exclude: 
+  exclude:
     - example/
     - "**/example/"
     - example_rest
     - example_graphql
     - "**/*.g.dart"
-    
+
   errors:
     # override custom
     always_use_package_imports: error

analysis_options.yaml

@@ -31,18 +31,25 @@ Underscore prefixing of type declarations ensure that 1) they will likely not co
 
 Every public instance method should support a named argument of `{Query query}`. `Query` is the glue between an application and an abstracted provider or repository. It is accessed by both the repository and the provider, but as the last mile, the provider should interpret the `Query` at its barest level.
 
-### `providerArgs:`
+### `limit:`
 
-`providerArgs` describe how to interact with a provider's source.
+The ceiling for how many results a provider should return from the source.
+
+```
+Query(limit: 10)
+```
+
+### `offset:`
+
+The starting index for a provider's search for results.
 
-```dart
-providerArgs: {
-  // limit describes how many results the provider requires from the source
-  'limit': 10,
-},
 ```
+Query(offset: 10)
+```
+
+### `forProviders:`
 
-As `providerArgs` can vary from provider to provider and IDE suggestions are unavailable to a string-key map, `providerArgs` should be clearly and accessibly documented within every new provider.
+Available arguments can vary from provider to provider; this allows implementations to query exclusive statements from a specific source.
 
 ### `where:`
 

docs/data/providers.md

@@ -19,7 +19,7 @@ query MyOperation($vars: MyInputClass!) {
 }
 ```
 
-?> `providerArgs['operation'].variables` will **never** be wrapped by `variablesNamespace`
+?> `GraphqlProviderQuery#.variables` will **never** be wrapped by `variablesNamespace`
 
 ## `where:`
 

docs/graphql/query.md

@@ -4,12 +4,12 @@
 
 The following map exactly to their SQLite keywords. The values will be inserted into a SQLite statement **without being prepared**.
 
-* `collate`
-* `having`
-* `groupBy`
-* `limit`
-* `offset`
-* `orderBy`
+- `collate`
+- `having`
+- `groupBy`
+- `limit`
+- `offset`
+- `orderBy`
 
 As the values are directly inserted, use the field name:
 
@@ -20,7 +20,7 @@ final String lastName;
 
 Query(
   where: [Where.exact('lastName', 'Mustermann')],
-  providerArgs: {'orderBy': 'lastName ASC'},
+  orderBy: [OrderBy('lastName', ascending: true)]
 )
 ```
 

docs/sqlite/query.md

@@ -1,16 +1,12 @@
 # `Query` Configuration
 
-## `providerArgs:`
+## `limit`
 
-| Name                       | Type      | Description                                                                                                                                           |
-| -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `'limit'`                  | `int`     | Forwards to Supabase's `limit` [param](https://supabase.com/docs/reference/dart/limit) in Brick's `#get` action                                       |
-| `'limitByReferencedTable'` | `String?` | Forwards to Supabase's `referencedTable` [property](https://supabase.com/docs/reference/dart/limit)                                                   |
-| `'offset'`                 | `int`     | Start from a specific offset, inclusive.                                                                                                              |
-| `'orderBy'`                | `String`  | Use field names not column names and always specify direction.For example, given a `final DateTime createdAt;` field: `{'orderBy': 'createdAt ASC'}`. |
-| `'orderByReferencedTable'` | `String?` | Forwards to Supabase's `referencedTable` [property](https://supabase.com/docs/reference/dart/order)                                                   |
+Forwards to Supabase's `limit` [param](https://supabase.com/docs/reference/dart/limit) in Brick's `#get` action
 
-?> The `ReferencedTable` naming convention is awkward but necessary to not collide with other providers (like `SqliteProvider`) that also use `orderBy` and `limit`. While a `foreign_table.foreign_column` syntax is more Supabase-like, it is not supported in `orderBy` and `limit`.
+## `offset`
+
+Start from a specific offset, inclusive.
 
 ## `where:`
 

docs/supabase/query.md

@@ -1,6 +1,8 @@
 // GENERATED CODE EDIT WITH CAUTION
 // THIS FILE **WILL NOT** BE REGENERATED
 // This file should be version controlled and can be manually edited.
+// ignore_for_file: public_member_api_docs, constant_identifier_names
+
 part of 'schema.g.dart';
 
 // While migrations are intelligently created, the difference between some commands, such as
@@ -21,8 +23,6 @@ const List<MigrationCommand> _migration_20240920063917_up = [
     'Pizza',
     'Customer',
     foreignKeyColumn: 'customer_Customer_brick_id',
-    onDeleteCascade: false,
-    onDeleteSetDefault: false,
   ),
 ];
 

example_supabase/lib/brick/db/20240920063917.migration.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 import 'package:brick_offline_first_with_supabase/brick_offline_first_with_supabase.dart';
 import 'package:brick_sqlite/brick_sqlite.dart';
 

example_supabase/lib/brick/models/customer.model.dart

@@ -1,10 +1,12 @@
+// ignore_for_file: public_member_api_docs
+
 import 'package:brick_offline_first_with_supabase/brick_offline_first_with_supabase.dart';
 import 'package:brick_sqlite/brick_sqlite.dart';
 import 'package:brick_supabase/brick_supabase.dart';
 import 'package:pizza_shoppe/brick/models/customer.model.dart';
 
 @ConnectOfflineFirstWithSupabase(
-  supabaseConfig: SupabaseSerializable(),
+  supabaseConfig: SupabaseSerializable.defaults,
 )
 class Pizza extends OfflineFirstWithSupabaseModel {
   /// Read more about `@Sqlite`: https://github.com/GetDutchie/brick/tree/main/packages/brick_sqlite#fields

example_supabase/lib/brick/models/pizza.model.dart

@@ -1,3 +1,5 @@
+// ignore_for_file: public_member_api_docs
+
 import 'package:brick_offline_first_with_supabase/brick_offline_first_with_supabase.dart';
 import 'package:brick_sqlite/brick_sqlite.dart';
 import 'package:brick_sqlite/memory_cache_provider.dart';
@@ -10,6 +12,8 @@ import 'package:supabase_flutter/supabase_flutter.dart';
 class Repository extends OfflineFirstWithSupabaseRepository {
   static late Repository? _singleton;
 
+  factory Repository() => _singleton!;
+
   Repository._({
     required super.supabaseProvider,
     required super.sqliteProvider,
@@ -18,8 +22,6 @@ class Repository extends OfflineFirstWithSupabaseRepository {
     super.memoryCacheProvider,
   });
 
-  factory Repository() => _singleton!;
-
   static Future<void> initializeSupabaseAndConfigure({
     required String supabaseUrl,
     required String supabaseAnonKey,