v0.1.10 - Improved DSL for Fields, Redaction, Logging, and Accounts API simplification!

This release contains some new nice-to-have goodies and simplifications in several APIs. This may have some breaking changes for you if you use Accounts APIs. Don't worry it's not much! Just read the Migration guide section at the bottom of this page ❤️

New nice-to-have goodies! 😋 😋 😋

1. #147 Redacted APIs and Entities 🍧
   • Howto page: howto-redact-apis-and-entities.md
2. #144 Logging support 🍪
   • Howto page: howto-log-api-input-output.md

API improvements 🍬

1. #152 Simplified API for attaching local RawContacts to an Account (breaking change)
2. #153 Simplified API for querying for Accounts (breaking change)
3. #150 Improved syntactic Kotlin sugar (DSL) for constructing Where clauses using Fields 🍰🍰
   • This is a minor improvement but very cool nonetheless! Essentially, you don't need to import or write the Fields in where, include, and orderBy functions anymore if you choose not to. There is a separate function now that takes in a function that has Fields as the receiver. More details in #150
   • Howto page: howto-query-contacts-advanced.md#an-advanced-query

Please keep in mind that releases below the semantic version v1.0.0 may contain breaking changes!!! Anything below the semantic version v1.0.0 are implicitly experimental/non-stable. Backwards compatibility and deprecations will not be exercised until after v1.0.0 (the first true production release version) in order to keep the library clean and easy to change. TLDR; I'm not really following semantic versioning major.minor.patch for any releases below v1.0.0. 😅

Upgrades

1. #164 Set target and compile SDK version from 30 to 31.

Internal refactors

Just thought you should know about these in case you experience regression when updating to this version. These should not affect you at all. But just in case, you know about these 🎺

1. #148 Lazily evaluating WHERE clause.
2. #154 Standardized interface for all CRUD APIs accessible via Contacts instance.

Note for #154. You can actually use the CrudApiListenerRegistry as an advanced feature if you want. I don't recommend it though, which is why I am not announcing it as a new feature. I also did not write a howto page for it. The library is currently using this mechanism for logging but you may find some advanced use for it. If you do, let me know how you end up using it! We may find some other use for it than attaching our logger.

New Contributors!!!

• @alorma made their first contribution in #145
  • The initial implementation of our logger is nice and sweet! Thank you and welcome to the will-be-legendary Android library 🔥
• @jayasuryat made their first contribution in #163
  • This genius from Reddit reduced 500 lines of code down to 2 lines 🤯 🤯🤯 Truly amazing! This library is lucky to have him as a contributor 🔥 🔥 🔥

Full Changelog

0.1.9...0.1.10

Want to discuss this release?

Head on over to the v0.1.10 Release Checklist and leave a comment!

Migration guide (from v0.1.9 to v0.1.10)

This should cover everything that could affect you. Let me know if I missed anything! If you don't care to look at the before-and-after, then go straight into the howto pages. I also made sure to update all documentation in code

I. Simplified API for attaching local RawContacts to an Account

Previously, in order to attach a set of local RawContacts to an Account, you would do...

val isSuccessful: Boolean = Contacts(context)
        .accounts()
        .updateRawContactsAssociations()
        .associateAccountWithLocalRawContacts(account, rawContacts)

This really deviated from the API design of using commit as the terminal operator and everything prior as argument specifications. So, I decided to simplify it and also follow the design of the other update APIs!

Now, to do the same thing as the above example...

val result: Result = Contacts(context)
        .accounts()
        .updateLocalRawContactsAccount()
        .addToAccount(account)
        .localRawContacts(rawContacts)
        .commit()

val isSuccessful = result. isSuccessful

This is more future-proof and just looks nicer 😄

I have not written the howto page for this but the documentation in code should be enough for now. The issue for the howto page is #1. Leave a comment there if you want to push me to write it sooner 🤣

II. Simplified API for querying for Accounts

Previously, in order to query for android.accounts.Account...

Contacts(context).accounts().query().apply {
    val allAccounts : List<Account> = allAccounts(context)
    val googleAccounts : List<Account> = accountsWithType(context, "com.google")
    val accountsForRawContacts: Result = accountsFor(rawContacts)
}

The problem was similar to the previous refactor. This API derails from the design of the other APIs! This was the last one that had to be fixed to come up with a standard for all APIs in the library... So I cleaned it up!!! 🔥

Now...

Contacts(context).accounts().query().apply {
    val allAccounts : List<Account> = find()
    val googleAccounts : List<Account> = withTypes("com.google").find()
    val accountsForRawContacts: Result = associatedWith(rawContacts).find()
}

This also enables you to use withTypes and associatedWith together in different combinations, giving you more flexibility and control!

I updated the howto page for this, howto-query-accounts.md, so you can take a look at it for usage guides if the in-code documentation is not good enough for you 😁