Skip to content

3.0.0 🚀

Compare
Choose a tag to compare
@github-actions github-actions released this 26 May 13:35
· 234 commits to master since this release
001a2a0

🧨 Breaking changes

🚨 Behavior change - the number of subscribers that onSubscribe receives has been changed from previous to current. I.e. onSubscribe will now get a number bigger by one. Please manually check each usage of onSubscribe in the project right after you update. 🚨

  • Compile-time error: JobManager is now a generic class, which means expression val jobs = manageJobs() requires a type argument now. To fix, simply provide the return type expicitly:
    val jobs: JobManager<Jobs> = manageJobs()
    
  • Removed deprecated android-compose artifact. You can now just use compose which is multiplatform.
  • Merged android-view and android artifacts - please remove android-view
  • Store will now check if it has been launched before it is subscribed to. This will result in an exception if not. Opt-out of this behavior using allowIdleSubscriptions = true. This check will not be run when debuggable = false
  • Verify each method of store plugin builder is only called once. The plugin builder will now throw if you attempt to invoke a given callback multiple times. For example, onStart { } ; onStart { } will now throw

🚀 New Features

  • Compose and lifecycle support is now multiplatform! With androidx.lifecycle being multiplatform, the library automatically uses system lifecycle to subscribe to the store.
    • However, if you are using a navigation library with a custom lifecycle support, such as Decompose, you can pass the lifecycle as a composition local (using the essenty integration) or manually as a function parameter.
  • Remote Debugging! A new module family debugger-* allows to debug your stores remotely, with a dedicated app provided for Linux, MacOS, Windows.
  • Essenty Integration! Two new modules: essenty and essenty-compose provide integration with Decompose and Essenty libraries, including lifecycle, retained instances and saved state. Essenty setup explained in docs
  • Wasm and JS support for all modules. saveStatePlugin will persist the state to local storage on browser targets by default
  • New flag atomicStateUpdates in store builders allows disabling serialization / atomicity of state transactions if that is not needed, improving performance. true by default
  • Stores now have StoreLogger parameter which
    • can be overridden and decorated
    • is available in the store's code and plugins
    • fully multiplatform and automatic
      You can set or remove the store logger using the configure block. If a value is not set, then if debuggable is true, a platform logger will be used, and if false, no-op logger will.
  • Added a new "queue" property for Undo/Redo to observe changes to the queue
  • Implemented a new multiplatform sample app for Wasm, Android, Desktop and iOS to showcase main features, integration with decompose, DI setup and lifecycle setup.
  • savedStatePlugin now provides logging information
  • serializeState plugin now has a default Json instance provided. Using it is recommended if your json instance is not lenient enough to ignore schema changes.
  • Library performance was optimized to reduce object allocation, lambda creation and function indirection. With k2, lambdas which are extensively used in the library should become more performant. Also optimizations were made to the subscription lifecycle handling to make it faster & more reliable.
  • Implemented a new Lazy Plugin DSL where plugin will now have access to the store configuration that installs it and that will be built at the store creation time, not at the property instantiation time.
    • This Lazy DSL replaces the old lazyPlugin function.
    • Convert an existing plugin into a lazy one to get access to the config by calling LazyPlugin { config -> }
    • Create a lazy plugin using lazyPlugin builder function and use the config property
    • StoreConfiguration is now also available from PipelineContext, so you can invoke logging calls and determine if the store is debuggable

🐞 Bug fixes

  • Fixed file name for serializeState function using store name instead of actual name
  • Fix Savers handling cancellation exceptions
  • Added a missing overload of Time Travel that would create and return the object for the user
  • Store will now not print logs when the state has not changed (stayed the same)
  • Fixed race with concurrent subscriptions to the store where job was relaunched too many times
  • Fixed store builder allowing to install 0 plugins
  • Synchronize disallowRestart plugin operations
  • Ensured subscription events are always sent and processed. This should fix rare bugs where the number of subscribers was quickly conflated to the same value sometimes.
  • Fixed issues where store configuration was accessible and changeable from plugins and from callbacks. This will now not compile instead of silently failing.
  • Disallowed nested plugin callback invocation e.g. onStart { onStart { } }

📚 Docs

  • Project Icon, banner, and star history
  • Documentation on prebuilt plugins
  • Docs on lazy plugins
  • Docs for store configuration parameters
  • Docs on remote debugger setup
  • Expanded FAQ
  • Docs for essenty integration

⭐️ Deprecations

  • Deprecated parentStorePlugin in favor of a simple store.collect suspending function. It's much more flexible and allows to merge the incoming state with other data sources
  • Deprecated platformLoggingPlugin, nativeLoggingPlugin, consoleLoggingPlugin, logcatLoggingPlugin as a default loggingPlugin now uses store logger by default
  • Deprecated parameters of savedStatePlugin which were accepting a file and a directory, because on wasm targets local storage is used. A new overload that takes a path is now used.
  • New configure { } block DSL replaced the old store configuration properties. You can no longer access store configuration in the store builder. This change was made to ensure users do not access store configuration before it's actually created, because while the store is being built, the configuration may change. This will also prevent users from changing the store configuration inside the plugins, which makes no sense as the configuration is not valid anymore.
  • Many default parameters were removed from multiple plugins because those parameters are now obtained from the Store configuration using Lazy Plugin DSL. This includes logger, debugger, save state and some other plugins. Only non-mandatory parameters were removed. You can safely remove them as well.

Changes since 2.5.0-alpha12

Features

  • un-deprecate overloads of subscribe where the lifecycle is not provided explicitly
  • deprecate useState and rename to updateStateImmediate with auto-replace
  • change the return value of onSubscribe to return the new subscriber count
  • Kotlin 2.0, compose 1.6.10
  • allow overriding name and logger for the logging plugin
  • update docs for v3.0

Bug fixes

  • Bring back stateProvider under a deprecation message to reduce migration complexity
  • Bring back removed logging plugin as it was removed too early
  • Bring back removed nameByType temporarily to reduce migration complexity