Dependency injection

@fluixi/start/di provides an Angular-style injector, useful for sharing services, clients and config without prop-drilling, with per-request isolation on the server.

import { injectionToken, provide, inject } from '@fluixi/start/di';

const ApiClientToken = injectionToken<ApiClient>('ApiClient');

// Provide it, e.g. at the app root:
provide([
  { provide: ApiClientToken, useFactory: () => new ApiClient(env.API_URL) },
]);

// Inject it anywhere in the owner tree:
const api = inject(ApiClientToken);

provide takes an array of providers, so one call registers a whole set, and returns the injector it created.

Tokens

A token is an identity, not a value, two tokens with the same name are still distinct, and the type parameter is what makes inject return the right type.

const Config = injectionToken<AppConfig>('Config');
const Now = injectionToken<() => Date>('Now', { factory: () => () => new Date() });

A token with a factory has a default, so inject(Now) works with nothing provided, useful for things that almost always have one sensible implementation and occasionally need swapping in a test.

Provider forms

provide([
  { provide: Config, useValue: { apiUrl: '/api' } },              // a ready value
  { provide: Clock, useClass: SystemClock },                      // constructed once
  { provide: Api, useFactory: (c) => new Api(c.apiUrl), deps: [Config] },
  { provide: LegacyApi, useExisting: Api },                       // an alias
]);

deps lists the tokens to resolve and pass, in order, to useFactory or the useClass constructor. Everything is built lazily on first inject and then cached, so a service nobody injects is never constructed.

A circular dependency is detected and reported rather than overflowing the stack.

Scope

Injectors follow the reactive owner tree, so a provide inside a component shadows an outer one for that subtree and disappears with it:

createRoot(() => {
  provide([{ provide: T, useValue: 'child' }]);
  inject(T);   // "child"
});
inject(T);     // back to the outer value

provideRoot registers on the root injector instead, which is what an app-wide service usually wants. runInInjectionContext(injector, fn) runs fn against a specific injector, needed when you have to inject from a callback that has left the owner tree.

Per-request roots

On the server the root injector is created per request, so two concurrent requests never share instances. A request-scoped service, a database connection, the current user's session, stays isolated without any work on your part. On the client there is one root for the life of the page.

This is the reason to prefer DI over a module-level singleton in an SSR app: a module global is shared by every request the process handles, and leaking one user's session into another's render is the kind of bug that only appears under concurrency.

Cleanup

A provider can implement onDestroy, called when its injector is disposed, at the end of the request on the server, or when the owning root is disposed on the client.

Next: Internationalization.