MIGRATING.md

Migrating Between Major Versions

Migrating from Brick 1 to Brick 2

Brick 2 focuses on Brick problems encountered at scale. While the primary refactor was the abstraction of domain-specific code from generalized domains, this major release also includes a new GraphQL domain, resolution of community pain points, and a few neat tricks.

Breaking Changes

• Brick no longer expects lib/app; it now expects lib/brick.

  mv -r lib/app lib/brick

• Models are no longer discovered in lib/app/models; they are now discovered via *.model.dart. They can live in any directory within lib and have any prefix. (#38)

  for FILENAME in lib/brick/models/*; do mv $FILENAME "${FILENAME/dart/model.dart}"; done

• brick_offline_first is now, fundamentally, brick_offline_first_with_rest. brick_offline_first now serves as an abstract bedrock for offline domains.

  sed -i '' 's/brick_offline_first:/brick_offline_first_with_rest:/g' pubspec.yaml
  for FILE in $(find "lib" -type f -name "*.dart"); do sed -i '' 's/package:brick_offline_first/package:brick_offline_first_with_rest/g' $FILE; done

• brick_offline_first_abstract is now brick_offline_first_with_rest_abstract

  sed -i '' 's/brick_offline_first_abstract:/brick_offline_first_with_rest_abstract:/g' pubspec.yaml
  for FILE in $(find "lib" -type f -name "*.dart"); do sed -i '' 's/package:brick_offline_first_abstract/package:brick_offline_first_with_rest_abstract/g' $FILE; done

• rest properties have been removed from OfflineFirstException. Use OfflineFirstWithRestException instead from brick_offline_first_with_rest.
• OfflineFirstRepository#get(requireRemote: and OfflineFirstRepository#getBatched(requireRemote: has been removed. Instead, use policy: OfflineFirstGetPolicy.alwaysHydrate
• OfflineFirstRepository#get(hydrateUnexisting: has been removed. Instead, use policy: OfflineFirstGetPolicy.awaitRemoteWhenNoneExist (this is the default).
• OfflineFirstRepository#get(alwaysHydrate: has been removed. Instead, use policy: OfflineFirstGetPolicy.alwaysHydrate.

Fun Changes

• Utilize OfflineFirstDeletePolicy, OfflineFirstGetPolicy, and OfflineFirstUpsertPolicy to override default behavior. Specific policies will throw an exception when the remote responds with an error (and throw that error) or skip the queue. Existing default behavior is maintained.
• OfflineFirstRepository#delete now supports requiring a successful remote with OfflineFirstDeletePolicy.requireRemote. If the app is offline, normally handled exceptions (ClientException and SocketException) are rethrown. (#182)
• OfflineFirstRepository#upsert now supports requiring a successful remote with OfflineFirstUpsertPolicy.requireRemote. If the app is offline, normally handled exceptions (ClientException and SocketException) are rethrown.

New Packages

• brick_graphql. The GraphqlProvider interfaces with a GraphQL backend. It uses gql's Link system to integrate with other community-supported functionality. That, and all your variables are autogenerated on every request.
• brick_graphql_generators. The perfect companion to brick_graphql, this thin layer around brick_rest_generators battle-tested core compiles adapters for the GraphQL domain.
• brick_json_generators. The experienced core separated from brick_rest_generators permits more code reuse and package creation for JSON-serving remote providers.
• brick_offline_first_build. Abstracted from the experienced core of brick_offline_first_with_rest_build, these helper generators and utils simplify adding offline capabilites to a domain.
• brick_offline_first_with_graphql. Utilize the GraphQL provider with SQLite and Memory cache. This is a near mirror of brick_offline_first_with_rest, save for a few exceptions. First, the OfflineQueueLink must be inserted in the appropriate position in your client's Link chain. Second, OfflineFirstWithGraphqlRepository#subscribe permits streaming updates, including notifications after local providers are updated.
• brick_offline_first_with_graphql_abstract. Annotations for the GraphQL domain without including Flutter.
• brick_offline_first_with_graphql_build. The culmination of brick_graphql_generators and brick_offline_first_build.

Migrating to Brick 1 (Null Safety)

Breaking Changes

• Because required is now a reserved Dart keyword, required in WherePhrase, WhereCondition, And, Or, and Where has been renamed to isRequired.
• Field types in models Set<Future<OfflineFirstModel>>, List<Future<OfflineFirstModel>>, and Future<OfflineFirstModel> are no longer supported. Instead, use Set<OfflineFirstModel>, List<OfflineFirstModel>, and OfflineFirstModel (the adapters will await each).
• StubOfflineFirstWithRest is functionally changed. SQLiteFFI has satisfied much of the original stubbing required for this class, and http's testing.dart library is sufficient to not require Mockito. Therefore, verify calls will no longer be effective in testing on the client. Instead, pass StubOfflineFirstWithRest.client to your RestProvider#client with the response values. StubOfflineFirstWithRestModel has been removed. Please review Offline First Testing for implementation examples.

Improvements

• brick_offline_first: Priority for the next job to process from the queue - when processing requests in serial - has changed from '$HTTP_JOBS_CREATED_AT_COLUMN ASC, $HTTP_JOBS_ATTEMPTS_COLUMN DESC, $HTTP_JOBS_UPDATED_AT ASC' to '$HTTP_JOBS_CREATED_AT_COLUMN ASC'; this uses the job column introduced in 0.0.7 (26 May 2020) and will not affect any implementations using 0.0.7 or higher.
• brick_offline_first: RequestSqliteCache no longer queries cached requests based on headers; requests are rediscovered based on their encoding, URL, request method, and body. Rehydrated (reattempted) requests will be hydrated with headers from the original request.
• Every package is null safe. There is one outstanding dependency - build_config - that needs to be migrated, so the generators are not technically "null safe". However, these are dev dependencies and build_config isn't imported into Dart code, so upgrading it will be changing numbers.