isolate_manager

• Add cross-platform transferables support (fixes #56, thanks to @kartikey321).
• Add enableWasmTransferables parameter to automatically omit transferables on WASM targets for better performance.
• Update queueStrategy and workerConverter types for better null safety (fixes #54).
• Improve benchmark scripts.
• Update README.

• Improve the way to check if the isolate_manager_generator is installed.

• Hide the IsolateManagerCustomWorker class.
• Strip --add-generator flag before launching generator.

• Hide the IsolateManagerController.initialParams to avoid unexpected access. Because this attribute does nothing so I won't treat it as a breaking change.
• Update the docs that related to deprecated onInitial.

• Update IsolateManager docs for runFunction and runCustomFunction.
• Add enableWasmConverter parameter to IsolateManager.
• Update README.

• Improve README.

This major release incorporates numerous features, improvements, fixes, and breaking changes developed through the preceding release candidates. For a smooth transition, review the breaking changes section below. If you need information about deprecated methods before upgrading, please use v6.0.0-rc.24.

BREAKING CHANGES:

• JS Recompilation Required: All JS worker files MUST be recompiled using dart run isolate_manager:generate. This is necessary due to internal changes in data transfer mechanisms (introduced in rc.1) and worker naming conventions (introduced in rc.21).

• Generator Package: The generator functionality has been separated into the isolate_manager_generator package. This package MUST now be added to your dev_dependencies to use the dart run isolate_manager:generate command (separated in rc.10, made mandatory in rc.25).

• Deprecated Methods Removed: All methods previously marked as deprecated have been removed (introduced in rc.25). Please update your code to use their replacements.

• ImType Refactoring: ImType and its subclasses (ImList, ImMap) have been refactored to prevent nullable values being wrapped directly, ensuring type safety. Use non-nullable types within ImType.

• QueueStrategy Renaming: The QueueStrategy enums have been renamed for clarity:

  • QueueStrategyUnlimited → UnlimitedStrategy
  • QueueStrategyRemoveNewest → DropNewestStrategy
  • QueueStrategyRemoveOldest → DropOldestStrategy
  • QueueStrategyDiscardIncoming → RejectIncomingStrategy

• Exception Type Change: UnimplementedError thrown by ImType wrapper methods has been replaced with the more specific UnsupportedImTypeException.

• Shared Worker Naming: Shared workers now only accept the basename of the workerName (changed in rc.21).

New Features:

• IsolateManager.run: Added a method similar to Isolate.run that supports execution on both VM Isolates and Web Workers.
• IsolateManager.runFunction: Added a method that automatically applies the correct workerName when running a function, simplifying shared worker usage.
• IsolateManager.runCustomFunction: Added support for custom isolate execution logic with optional callbacks and debug logging.
• ImType System: Introduced ImType (replacing IsolateType) and its subclasses (ImList, ImMap) to enforce type safety for parameters and return values, especially for Web Worker generation.
• ImType Helper Methods: Added convenient methods to ImList (toIterable, toList, toDecodedIterable, toDecodedList) and ImMap (toMap, toDecodedMap). The toDecoded... methods replace previous toUnwrapped... methods.
• Custom Exception Transfer: Added the ability to register custom exception classes (extending IsolateException) that can be safely transferred between the main isolate and workers.
• ImType Debugging: Added toString() methods to ImType subclasses for easier debugging.
• [Experiment] Automatic Worker Mappings: Introduced an experimental flag (--worker-mappings-experiment=lib/main.dart) for the generator to automatically create workerMappings.

Improvements:

• Performance:

  • Improved data transfer performance between Web Workers and the main app by using Map instead of json.
  • Enhanced performance by using native dartify and jstify for web interoperability.
  • Improved performance by optimizing IsolateState detection.
  • Refactored multiple components for better performance.
  • Used assert for logging messages, improving release mode performance.

• Error Handling:

  • Generator (dart run isolate_manager:generate) now returns a non-zero exit code on errors, improving CI/CD integration.
  • Wrap methods now throw UnsupportedImTypeException for unsupported nullable types in ImType, ImList, ImMap.
  • Improved error handling when transferring exceptions from Workers back to the main isolate.
  • Improved worker function handling to avoid unnecessary wrapping when the worker is not available.

• API & Usage:

  • Uses wrap/unwrap methods (replacing encode/decode) for ImType data handling.
  • Introduced onInit callback for IsolateManagerFunction.customFunction, replacing the previous onInitial. The initialParameter argument for IsolateManager.createCustom is no longer used with onInit.
  • Renamed internal type CustomIsolateFunction to IsolateCustomFunction for clarity.
  • workerName for shared workers now uses the latest mapping value dynamically, avoiding the need to restart after updates.
  • Improved ImType equality and hash code implementations (replacing Equatable).
  • Added a converter helper for better int, Iterable<int>, Set<int>, List<int> handling when compiling to WASM.
  • ImType can now be declared as const.
  • Supported computing nullable functions with nullable parameters using IsolateManagerShared.

• Generator:

  • Improved generator logic for creating worker mappings.

• Code Quality:

  • Adopted very_good_analysis for stricter linting rules.
  • Refactored codebase to remove redundant streams.
  • Simplified internal code structures.
  • General code cleanup.

Fixes:

• Fixed an issue in the shared isolate manager where useWorker was true but no workerName was provided.
• Fixed an issue preventing subsequent task processing after an exception occurred.
• Correctly parse Dart native arguments during generation (Fixes #36).
• Fixed various typos in code and documentation.

Testing:

• WASM Support: Added support for running tests on WASM (dart test --platform=chrome --compiler dart2wasm) and updated CI workflows accordingly. Updated WASM benchmarks.

• Benchmarks: Rewrote and updated benchmarks, including results in the README.

• Test Infrastructure:

  • Added a local script (test/bin/run.sh) to generate workers and run all tests.
  • Switched code coverage calculation from flutter test to dart test for accurate VM and Chrome testing.
  • Reorganized test file structures and simplified test flow.

• General: Added and strengthened tests throughout the development cycle.

Dependencies:

• Requires isolate_manager_generator in dev_dependencies for code generation.
• Bumped web package dependency to ^1.0.0.

Documentation:

• Numerous improvements and updates to the README.

• Add isolate_manager_generator to dev dependencies in the example.

• BREAKING CHANGE:
  • The isolate_manager_generator MUST be added to dev_dependencies to use dart run isolate_manager:generate.
  • Remove all deprecated methods.
• Return non-zero exit code when errors occur during the dart run isolate_manager:generate execution for better error handling in CI/CD pipelines.

• Improve README.

• Rename the QueueStrategys:
  • QueueStrategyUnlimited → UnlimitedStrategy
  • QueueStrategyRemoveNewest → DropNewestStrategy
  • QueueStrategyRemoveOldest → DropOldestStrategy
  • QueueStrategyDiscardIncoming → RejectIncomingStrategy
• Cleanup code.
• Remove .vscode.

• Improve README.

• Update wrap methods to throw UnsupportedImTypeException when wrapping nullable types in ImType, ImList, and ImMap.
• Update tests.
• Improve README.

• The shared worker now only accept the basename of the workerName to compatible with the new generator (since v0.0.6).
• Reorganize test file structures.
• BREADKING CHANGE: Recompile test workers.
• Simplify test flow.

• Add, replace and deprecate the old methods:
  • ImMap.toUnwrappedMap -> ImMap.toDecodedMap
  • ImList.toUnwrappedIterable -> ImList.toDecodedIterable
  • ImList.toUnwrappedList -> ImList.toDecodedList
• Update tests.

• BREAKING CHANGE Replace UnimplementedError with UnsupportedImTypeException in ImType wrapper methods.
• Improve worker function handling to avoid unnecessary wrapping when the worker is not available.
• Add toString() method to ImType subclasses for improved debugging.
• Able to throw and catch UnsupportedImTypeException correctly across io, js and wasm.
• Able to register the custom exceptions (extends IsolateException) that can be safely transferred between isolates.
• Update benchmark for WASM and update the result.
• Improve README.

• Replace IsolateTypes with ImTypes and mark the old ones as deprecated.

• BREAKING CHANGE Refactor ImType to prevent nullable values.

• Replace encode with wrap and decode with unwrap in IsolateType handling across and mark the old ones as deprecated.

• Add some useful methods:

  • ImList: toIterable, toList, toDecodedIterable and toDecodedList.
  • ImMap: toMap and toDecodedMap.

• Improve error handling when sending exception from Worker to main.

• Improve the ImType equality and hash code implementations to replace Equatable.

• Add a converter helper to ensure proper type handling for int, Iterable<int>, Set<int> and List<int> when compiling to WASM.

• Update tests and README.

• Able to run tests on WASM via dart test --platform=chrome --compiler dart2wasm.

• Update the workflows to run test on WASM.

• Fixes an issue in the shared isolate manager that useWorker is true but there is no workerName provided.

• Add new onInit callback to replace onInitial and make it as deprecated.

• Mark initialParameter in the IsolateManager.createCustom as deprecated:

  Before:

  void customIsolateFunction(dynamic params) {
    IsolateManangerFunction.customFunction(
      params,
      onInitial: (controller, initialParams) {
        // Do something here with the `initialParams`.
      },
    );
  }
  
  final isolate = IsolateManager.createCustom<R, P>(
    customIsolateFunction,
    initialParams: 'initialParams',
  );
  

  Now:

  void customIsolateFunction(dynamic params) {
    IsolateManangerFunction.customFunction(
      params,
      onInit: (controller) {
        // Do something here with your own `initialParams` value.
      },
    );
  }
  
  final isolate = IsolateManager.createCustom<R, P>(
    customIsolateFunction,
  );
  

• Improve tests.

• Update README.

• Add runCustomFunction method to support custom isolate execution with optional callback and debug logging
• The workerName now gets the latest mapping value dynamically, avoid the need to recreate the IsolateManager after updates.
• Refactored the codebase to remove redundant streams.
• Rename CustomIsolateFunction to IsolateCustomFunction, update references and mark the old one as deprecated.
• Improve README.

• Refactored multiple components to improve performance.
• Rewrote benchmarks, regenerated JS worker for benchmarks, and updated benchmark results in README.
• Used assert to log messages, enhancing performance in release mode.
• Fixed several typos.

• Fix README typos.

• Add an IsolateManager.runFunction method that automatically applies the appropriate workerName when executing a function.

• Improve README.

• Add an IsolateManager.run method that follows Isolate.run but also supports Web Workers.
• Allow IsolateType to be declared as const.
• Refactor to simplify internal code.
• Strengthen tests.
• Improve the README.
• Improve the Benchmarks.

• Adjust the dependencies.

• Separate the generator into the isolate_manager_generator package.

• Fixed issue that causes subsequent tasks not to be processed after receiving an exception.

• Able to compute a nullable function with a nullable parameter use IsolateManagerShared.

• The IsolateType.encode is now accept the nullable values.

• Add IsolateType to use for function parameters and return types to ensure that type is supported when generating a Worker.
• Add test/bin/run.sh to generate and run all tests locally.
• Use native dartify and jstify to improve perfomances.

• Improve the generator to generate the worker mappings better.
• Update workflows to ensure backward compatibility.

• Correctly parse the dart native arguments (Fixes #36).
• [Experiment] Automatically generate the workerMappings by adding the --worker-mappings-experiment=lib/main.dart flag to the generator.
• The code coverage is now using dart test instead of flutter test so we can correctly test the code on both vm and chrome.
• Improve the performaces by improving the way to detect the IsolateState.
• Improve tests.

• Bump the web package to ^1.0.0.
• Bump the analyzer package to ^6.0.0.
• Update the benchmark result.

• BREAKING CHANGE All the JS files MUST BE recompiled by running dart run isolate_manager:generate.
• Improve the data transfer performances between the Worker and the main App by replacing the json with the Map when sending and receiving data.

Although all tests are passed, many things will be refactored before version 6.0.0 is fully released.

• Change the type of the Map from String to dynamic when converting by dartify.
• Add more tests for the Map.

• Able to create a Map function and use it as a Worker instead of using JSON.

• Set the max number of the queued computations.
• Control how a new computation is added and retrieved from the Queue.
• Compute a priority computation (promote a computation to the top of the Queue so it will be compute as soon as possible).

• Able to add options and flags directly into to Dart to Js Compiler.
• Able to print the debug logs for the dart to js compiler (only if the --debug flag is specified).