Skip to content

v1.1 - Added Async and Dispose support

Choose a tag to compare

@tzuleger tzuleger released this 23 Jan 13:18
· 6 commits to master since this release
dba8409

Fluxject v1.1

This version highlights two exciting new features that assist with your dependency management.

  • Asynchronous Service Support
    • Singleton and Scoped services can now be registered with a Promise as the return type, and [prepare()] and/or [createScope()] will automatically resolve these promises.
    • Transient services remain the same, where the return type when de-referencing a Transient service will still return a Promise
  • Service Disposal Support
    • Singleton and Scoped services can now include the [Symbol.dispose] or [Symbol.asyncDispose] to implicitly manage cleanup of the registered services.

This version also includes better documentation and better unit tests, to ensure that the latest version behaves as intended.

Asynchronous support

Services can be registered where the return type of the service is a Promise, and calling [prepare()] would now return a Promise if there was any services registered as asynchronous.

All Singleton services will be resolved as expected after [prepare()] is awaited. Transient services will always return the original return type, so they must still be awaited. Scoped services will have the same behavior as Singleton services, but the [createScope()] function must be awaited instead of [prepare()].

Example registering asynchronous services:

import { Container } from "fluxject";
const container = Container.create()
  .register(m => m.singleton({
     singleton1: () => ({ test: () => 'singleton1: sync' }),
     singleton2: async () => ({ test: () => 'singleton2: async' })
   }))
   .register(m => m.transient({
     transient1: () => ({ test: () => 'transient1: sync' }),
     transient2: async () => ({ test: () => 'transient2: async' })
   })
   .register(m => m.scoped({
     scoped1: () => ({ test: () => 'scoped1: sync' }),
     scoped2: async () => ({ test: () => 'scoped2: async' })
   });
   
const hostServiceProvider = await container.prepare();
console.log(hostServiceProvider.singleton1.test()); // prints "singleton1: sync"
console.log(hostServiceProvider.singleton2.test()); // prints "singleton2: async"
console.log(hostServiceProvider.transient1.test()); // prints "transient1: sync"
console.log((await hostServiceProvider.transient2).test()); // prints "transient2: async"

const scopedServiceProvider = await hostServiceProvider.createScope();
console.log(scopedServiceProvider.scoped1.test()); // prints "scoped1: sync"
console.log(scopedServiceProvider.scoped2.test()); // prints "scoped2: async"

Disposal support

Registered Singleton and Scoped services can now include the pre-defined ESNext [Symbol.dispose] or [Symbol.asyncDispose] symbols for functions to handle the disposal of that specific service. If the service is intended to be disposed of, the function [dispose()] can be called on the respective service provider (HostServiceProvider or ScopedServiceProvider) to appropriately call these functions.

This functionality is type-safe in the way that if there is no [Symbol.asyncDispose] symbol defined on ANY registered Singleton or Scoped services, then the return type of [dispose()] will just be void. Inversely, if at least one Singleton service is defined with [Symbol.asyncDispose], then the <HostServiceProvider>.dispose() function will return a Promise<void>.

The same goes for Scoped services, where the <ScopedServiceProvider>.dispose() function will return void if [Symbol.asyncDispose] is not defined on any Scoped services and Promise<void> if there is at least one service with a defined [Symbol.asyncDispose] function.

Example adding disposal for registered services:

import { Container } from "fluxject";

let disposedSingleton = false;
let disposedTransient = false;
let disposedScoped = false;
const container = Container.create()
  .register(m => m.singleton({ testSingleton: () => ({ [Symbol.dispose]: () => disposedSingleton = true })
  .register(m => m.transient({ testTransient: () => ({ [Symbol.dispose]: () => {
    console.log("disposing [testTransient]");
    disposedTransient = true;
  }})
  .register(m => m.scoped({ testScoped: () => ({ [Symbol.asyncDispose]: async () => disposedScoped = true });

const hostServiceProvider = container.prepare();
const scopedServiceProvider = hostServiceProvider.createScope();

assert(disposedSingleton === false);
assert(disposedTransient === false);
assert(disposedScoped === false);

hostServiceProvider.dispose();

assert(disposedSingleton === true);
assert(disposedTransient === false); // transients cannot be implicitly disposed of.
assert(disposedScoped === false);

// must be awaited, as the [Symbol.asyncDispose] symbol appears on at least one Scoped service
await scopedServiceProvider.dispose();

assert(disposedSingleton === true);
assert(disposedTransient === false);
assert(disposedScoped === true);

For TypeScript users, you should be able to use the using keyword with Transient services. (This has not been tested, so please submit any issues if this does not work as intended)

Example referencing the above code block:

function test() {
  console.log("Retrieving [testTransient] from host service provider");
  using myTransientService = hostServiceProvider.testTransient;
  console.log("Received [testTransient] from host service provider");
}

test();
console.log(disposedTransient);
// prints:
//   Retrieving [testTransient] from host service provider
//   Received [testTransient] from host service provider
//   Disposing [testTransient]
//   true

Or for JavaScript users:

function test() {
  let myTransientService;
  try {
    console.log("Retrieving [testTransient] from host service provider");
    myTransientService = hostServiceProvider.testTransient;
    console.log("Received [testTransient] from host service provider");
  }
  finally {
    if(myTransientService) {
      myTransientService[Symbol.dispose]();
    }
  }

}

test();
console.log(disposedTransient);
// prints:
//   Retrieving [testTransient] from host service provider
//   Received [testTransient] from host service provider
//   Disposing [testTransient]
//   true

Final Remarks

This update is exciting, as it takes Fluxject to a new level of IoC where services can be implicitly managed on a more granular level.