Injecute

https://github.com/masyaka/injecute
Admin
Injecute is a lightweight, extendable, and typesafe dependency injection container written in...
Tokens:246,115
Snippets:1,518
Trust Score:7.5
License:MIT
Update:2 hours ago
Show doc for...
Tokens:
Raw
### injecute DI container setup with startable lifecycle

Source: https://github.com/masyaka/injecute/blob/main/docs/index.md

Shows a complete DI container setup: registering singletons, extending with a module, and starting a lifecycle-managed server. Uses startLifecycle to start the server and stop it on SIGTERM. Demonstrates forking the container for tests with isolated scope and replace option.

```ts
import {
  DIContainer,
  startable,
  startLifecycle,
  type ServiceRegistry,
} from 'injecute';

// a module asks only for what it needs and registers its part of the app
const addUsers = (c: ServiceRegistry<{ db: Database }>) =>
  c.addSingleton('users', UserRepository, ['db']);

const app = new DIContainer()
  .addInstance('dbUrl', 'postgres://localhost/app')
  .addSingleton('db', Database, ['dbUrl'])
  .extend(addUsers)
  .extend(
    startable('server', HttpServer, ['users'], {
      start: (server) => server.listen(3000),
      stop: (server) => server.close(),
    }),
  );

app.get('users'); // UserRepository, typed

// start the server; on shutdown, close it, then dispose the container
const running = await startLifecycle(app);
process.once('SIGTERM', () => running.stop());

// in a test: replace the database for the whole graph, without touching `app`
await using test = app
  .fork({ isolated: true })
  .addInstance('db', fakeDb, { replace: true });
```

--------------------------------

### Install injecute with npm, pnpm, bun, or deno

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/getting-started.md

Install injecute as an ES module for Node.js ≥ 22.12, Deno, Bun, and browsers. No runtime dependencies. Choose the command for your package manager.

```sh
npm install injecute
```

```sh
pnpm add injecute
```

```sh
bun add injecute
```

```sh
deno add npm:injecute
```

--------------------------------

### Setup: install dependencies and run checks

Source: https://github.com/masyaka/injecute/blob/main/CONTRIBUTING.md

Run after cloning the repository. Requires Node.js ≥ 22.12; CI also runs on Node 24 and 26. Deno and Bun are only needed for smoke tests.

```sh
npm ci
npm run check   # format, lint, typecheck, tests, build: what CI runs
```

--------------------------------

### Create your first container with DIContainer

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/getting-started.md

Register an instance, a singleton class, and a singleton class with dependencies. Resolve 'users' as UserRepository with full type inference.

```typescript
import { DIContainer } from 'injecute';

class Database {
  constructor(readonly url: string) {}
  query(sql: string): string[] {
    return [`${this.url}: ${sql}`];
  }
}

class UserRepository {
  constructor(private readonly db: Database) {}
  findAll(): string[] {
    return this.db.query('select * from users');
  }
}

const app = new DIContainer()
  .addInstance('dbUrl', 'postgres://localhost/app')
  .addSingleton('db', Database, ['dbUrl'])
  .addSingleton('users', UserRepository, ['db']);

const users = app.get('users'); // typed as UserRepository
users.findAll();
```

--------------------------------

### Config-driven wiring example (JSON)

Source: https://github.com/masyaka/injecute/blob/main/ROADMAP.md

Example configuration for choosing implementations from JSON/YAML. Maps service names to implementation keys.

```json
{
  "logger": "winstonLogger",
  "notificationService": "slackNotificationService"
}
```

--------------------------------

### preload usage examples

Source: https://github.com/masyaka/injecute

Shows three ways to call preload: with no keys to resolve everything, with an array of specific keys, or with a predicate function to filter keys. The predicate example filters keys starting with 'Billing.'.

```ts
await preload(app); // everything
await preload(app, ['db', 'cache']);
await preload(app, (key) => String(key).startsWith('Billing.'));
```

--------------------------------

### startLifecycle(app, options)

Source: https://github.com/masyaka/injecute/blob/main/skills/injecute/SKILL.md

Starts the lifecycle of the application: runs init, start, and ready stages in order. Returns a running object with a stop method.

```APIDOC
## startLifecycle(app, options)

### Description
Starts the lifecycle of the application: runs init, start, and ready stages in order. Returns a running object with a stop method.

### Method
startLifecycle

### Parameters
- **app** (container) - Required - The application container.
- **options** (object) - Optional - Options: `lifecycle` (custom stages), `signal`, `onError`, `onHook`.

### Returns
A running object with a `stop()` method.

### Example
```ts
import { startLifecycle } from 'injecute';

const running = await startLifecycle(app);
process.once('SIGTERM', () => running.stop().catch((e) => logger.error(e)));
```
```

--------------------------------

### Create and start platform SDK

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/sdk.md

Shows how a consumer creates a platform SDK instance with createPlatform, starts it, and checks a feature flag. The SDK is built on a hidden container and exposes a plain object with lazy services.

```typescript
import { createPlatform } from 'platform-sdk';

await using platform = createPlatform({ service: 'checkout', apiUrl, token });
await platform.start();
platform.flags.isEnabled('one-click');
```

--------------------------------

### injecute DIContainer composition root example

Source: https://github.com/masyaka/injecute/blob/main/skills/injecute/SKILL.md

Builds a dependency injection container in one chain, registering instances, singletons, and transients. Uses optional dependencies and resolves a service with get().

```ts
import {
  DIContainer,
  optional,
  type ServiceProvider,
  type ServiceRegistry,
} from 'injecute';

class Database {
  constructor(readonly url: string) {}
}
class UserRepository {
  constructor(private readonly db: Database) {}
}

// The composition root: build the container in one chain, so its type has every service.
const app = new DIContainer()
  .addInstance('dbUrl', process.env.DATABASE_URL ?? 'postgres://localhost/app') // a ready value
  .addSingleton('db', Database, ['dbUrl']) // created once (new Database(dbUrl)), then cached
  .addTransient('requestId', () => crypto.randomUUID()) // created on every resolution
  .addSingleton('users', UserRepository, ['db'])
  .addSingleton('mailer', (transport) => createMailer(transport), [
    optional('transport'),
  ]);

const users = app.get('users'); // UserRepository
```

--------------------------------

### get usage example

Source: https://github.com/masyaka/injecute

Example of using `get` to resolve services asynchronously. The second call uses `{ optional: true }` to allow `undefined` when the service is not registered.

```TypeScript
const db = await app.get('db');
const cache = await app.get('cache', { optional: true }); // Cache | undefined
```

--------------------------------

### Start docs site with playground

Source: https://github.com/masyaka/injecute/blob/main/CONTRIBUTING.md

Launches the documentation site including the interactive playground.

```sh
npm run docs:dev
```

--------------------------------

### DIContainer usage example

Source: https://github.com/masyaka/injecute

Shows how to instantiate DIContainer, register services with addInstance and addSingleton, and resolve a service with get. The example demonstrates type inference for the service map.

```typescript
import { DIContainer } from 'injecute';

const app = new DIContainer()
  .addInstance('dbUrl', 'postgres://localhost/app')
  .addSingleton('users', UserRepository, ['dbUrl']); // typed

const users = app.get('users'); // UserRepository
```

--------------------------------

### Install injecute with npm, pnpm, bun, or deno

Source: https://github.com/masyaka/injecute/blob/main/README.md

Install the injecute package using your preferred package manager. The npm command includes alternatives for pnpm and bun, and the deno command uses the npm: prefix.

```sh
npm install injecute          # or: pnpm add injecute · bun add injecute
```

```sh
deno add npm:injecute
```

--------------------------------

### Example Plugin Implementations

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/sdk.md

Shows how to write plugins: recordRequests decorates the transport, viaGateway replaces it, analytics contributes to telemetrySink, and createInstrumentedPlatform assembles them.

```typescript
/** Decorates the transport: records every request, then sends it. */
export const recordRequests =
  (log: string[]): PlatformPlugin =>
  (c) =>
    c.addSingleton(
      'transport',
      (inner): Transport => ({
        send: (method, path, body) => {
          log.push(`${method} ${path}`);
          return inner.send(method, path, body);
        },
      }),
      { dependencies: ['transport'], replace: true }, // `inner` is the previous transport
    );

/** Replaces the transport: everything goes through the company's gateway. */
export const viaGateway =
  (gateway: Transport): PlatformPlugin =>
  (c) =>
    c.addInstance('transport', gateway, { replace: true });

/** Contributes to an extension point: telemetry also goes to the consumer's analytics. */
export const analytics =
  (received: TelemetryEvent[]): PlatformPlugin =>
  (c) =>
    c.addSingleton(telemetrySink('analytics'), (): TelemetrySink => ({
      send: async (events) => {
        received.push(...events);
      },
    }));

export const createInstrumentedPlatform = (
  requests: string[],
  received: TelemetryEvent[],
) =>
  createPlatform({
    service: 'checkout',
    apiUrl: 'https://platform.internal',
    token: process.env.PLATFORM_TOKEN ?? '',
    plugins: [recordRequests(requests), analytics(received)],
  });
```

--------------------------------

### injecute container setup

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/nestjs.md

Creates an injecute DIContainer with a singleton 'db' and extends with addOrders, then seals it.

```ts
// container.ts
export const app = new DIContainer()
  .addSingleton('db', () => new Database(process.env.DATABASE_URL!), {
    dispose: (db) => db.close(),
  })
  .extend(addOrders)
  .seal();
```

--------------------------------

### Create and start the SDK in a consumer without a container

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/sdk.md

Use this in an entry point when the consumer does not use injecute. The SDK is created with createPlatform, started to load flags and start telemetry flush, and automatically stopped at the end of the async function, flushing telemetry and clearing timers.

```typescript
export async function main() {
  await using platform = createPlatform({
    service: 'checkout',
    apiUrl: 'https://platform.internal',
    token: process.env.PLATFORM_TOKEN ?? '',
  });
  await platform.start(); // loads the flags, starts the telemetry flush

  new Checkout(platform.flags, platform.telemetry).run();
} // stopped here: telemetry is flushed, timers are cleared
```

--------------------------------

### Install dependencies with npm ci

Source: https://github.com/masyaka/injecute/blob/main/AGENTS.md

Installs project dependencies. Use this command to set up the environment.

```bash
npm ci
```

--------------------------------

### Entry point connecting core and server (main.ts)

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/app-structure.md

Creates the core, starts the lifecycle, and starts the HTTP server. On SIGTERM, it closes the server before stopping the lifecycle, ensuring connections are released in order.

```TypeScript
// main.ts
const core = createCore();
const running = await startLifecycle(core);
const server = createHttpApp(core).listen(core.get('config').port);

process.once('SIGTERM', () =>
  server.close(() => running.stop().catch((error) => console.error(error))),
);
```

--------------------------------

### createCore container setup

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/ui-frameworks.md

Creates a DIContainer with config, api, and OrdersStore services. Returns a new container per call; do not create at module top level.

```TypeScript
// src/core/container.ts: no UI framework imports
import {
  DIContainer,
  type ContainerServices,
  type ServiceRegistry,
} from 'injecute';
import { ApiClient } from './api';
import { OrdersStore } from './orders/orders-store';

export interface Config {
  apiUrl: string;
}

const addOrders = (c: ServiceRegistry<{ api: ApiClient }>) =>
  c.addSingleton('store', OrdersStore, ['api']);

export const createCore = (config: Config) =>
  new DIContainer()
    .addInstance('config', config)
    .addSingleton('api', (config) => new ApiClient(config.apiUrl), ['config'])
    .namespace('Orders', addOrders)
    .seal();

export type Core = ReturnType<typeof createCore>;
export type CoreServices = ContainerServices<Core>;
```

--------------------------------

### Build an SDK with createPlatform and toPlatform

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/recipes.md

Build an SDK's services in a container of its own (new per call) and expose an object typed by the SDK's interface. Nothing runs until a service is used or start() is called. The stop() logic handles failed starts and disposes the container.

```typescript
/** The services the SDK object exposes, and what it needs to start and stop. */
type Core = ServiceProvider<{
  api: ApiClient;
  'Flags.flags': FeatureFlags;
  'Telemetry.telemetry': Telemetry;
}> & { dispose(): Promise<void> };

/** Creates the SDK. Nothing runs until a service is used or `start()` is called. */
export function createPlatform(options: PlatformOptions): Platform {
  return toPlatform(createCore(options));
}

function toPlatform(core: Core): Platform {
  let running: Promise<RunningLifecycle> | undefined;
  let stopped: Promise<void> | undefined;
  const stop = () =>
    (stopped ??= (async () => {
      // a failed start already undid its hooks and disposed the container
      const run = await running?.catch(() => undefined);
      await (run ? run.stop() : running ? undefined : core.dispose());
    })());
  return {
    get api() {
      return core.get('api');
    },
    get flags() {
      return core.get('Flags.flags');
    },
    get telemetry() {
      return core.get('Telemetry.telemetry');
    },
    async start() {
      running ??= startLifecycle(core);
      await running;
    },
    stop,
    [Symbol.asyncDispose]: stop,
  };
}
```

--------------------------------

### Create App and Run Lifecycle with startLifecycle

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/startup-shutdown.md

Defines a DIContainer with instances, extensions, and namespaces, then starts the lifecycle. Logs started hooks and a route response, then stops the app. In Node.js, handle SIGTERM to stop gracefully.

```typescript
export const createApp = () =>
  new DIContainer()
    .addInstance('port', 8080)
    .extend(addPlatform)
    .namespace('Orders', addOrders)
    .namespace('Payments', addPayments)
    .seal();

export async function main(): Promise<void> {
  const app = createApp();
  // init → start → ready; in Node.js: process.once('SIGTERM', () => running.stop().catch(console.error))
  const running = await startLifecycle(app);
  log.push(`started: ${running.hooks.join(', ')}`);
  log.push(app.get('router').routes.get('/orders')!());

  await running.stop(); // undo ready → start → init, then app.dispose()
}
```

--------------------------------

### App setup with service files

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/custom-registration.md

Declares service types from the files' own types and applies the module. The container checks that required services exist, but not that every declared key has a file.

```typescript
// Taken from the files' own types: a changed factory changes the service type here.
type Services = {
  clock: ServiceOf<typeof import('./services/clock.ts')>;
  greeter: ServiceOf<typeof import('./services/greeter.ts')>;
};

const files = await loadServiceFiles(new URL('./services/', import.meta.url));

const app = new DIContainer()
  .addInstance('config', { greeting: 'Hello' })
  .extend(addServiceFiles<Services, { config: { greeting: string } }>(files));

app.get('greeter').greet('Ada'); // "Hello, Ada (1970-01-01T00:00:00.000Z)"
```

--------------------------------

### Register the SDK as a service in an injecute app

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/sdk.md

Use this when the consumer uses injecute. The SDK is registered as a singleton service, and its parts (flags, telemetry) are exposed as app keys so services depend on small interfaces. The init hook starts the SDK before app start hooks, and dispose stops it after dependent services.

```typescript
// In an app that uses injecute itself, the SDK is one service. Register the parts your code uses as
// keys of your app, so your services don't depend on the whole SDK.
export const createApp = () =>
  new DIContainer()
    .addInstance('config', { platformToken: process.env.PLATFORM_TOKEN ?? '' })
    .addSingleton(
      'platform',
      (config) =>
        createPlatform({
          service: 'checkout',
          apiUrl: 'https://platform.internal',
          token: config.platformToken,
        }),
      { dependencies: ['config'], dispose: (platform) => platform.stop() },
    )
    .addSingleton('flags', (platform) => platform.flags, ['platform'])
    .addSingleton('telemetry', (platform) => platform.telemetry, ['platform'])
    .addSingleton('checkout', Checkout, ['flags', 'telemetry'])
    // started with the app; stopped by dispose, after everything that depends on it
    .addSingleton(lifecycle.init('platform'), (platform) => platform.start(), [
      'platform',
    ]);
```

--------------------------------

### Lifecycle hooks with lifecycle.init, startable, and startLifecycle

Source: https://github.com/masyaka/injecute/blob/main/skills/injecute/SKILL.md

Registers a singleton service, a lifecycle.init subscription hook, and a startable consumer. startLifecycle runs init → start → ready; running.stop() undoes ready → start → init and disposes. The init hook returns the unsubscribe function.

```ts
import { lifecycle, startable, startLifecycle } from 'injecute';

const addOrders = (c: ServiceRegistry<{ bus: EventBus }>) =>
  c
    .addSingleton('service', OrderService)
    .addSingleton(
      lifecycle.init('subscriptions'),
      (bus, service) => bus.on('paid', (e) => service.onPaid(e)),
      ['bus', 'service'],
    ) // returns the unsubscribe
    .extend(
      startable('consumer', OrderConsumer, ['bus'], {
        start: (consumer) => consumer.start(),
        stop: (consumer) => consumer.stop(),
      }),
    );

const running = await startLifecycle(app); // init → start → ready
process.once('SIGTERM', () => running.stop().catch((e) => logger.error(e))); // undo ready → start → init, then dispose; rejects if something failed
```

--------------------------------

### TaggedKey usage example

Source: https://github.com/masyaka/injecute

Shows how to create a tagged key and register a service with type checking against the tag's type.

```ts
const route = createTag('route').of<Route>();
const key: 'orders:route' & TaggedKey<Route, 'orders:route'> = route('orders');
app.addSingleton(key, () => ({ path: '/orders' })); // checked against Route
```

--------------------------------

### createProxyAccessor usage example

Source: https://github.com/masyaka/injecute

Exposes selected services under custom names and resolves them on property access.

```ts
const sdk = createProxyAccessor(app, {
  keys: ['invoices', ['createInvoiceHandler', 'createInvoice']],
});
sdk.invoices;      // resolves 'invoices'
sdk.createInvoice; // resolves 'createInvoiceHandler'
```

--------------------------------

### lifecycle

Source: https://github.com/masyaka/injecute

The default lifecycle stages for an Injecute container: init, start, and ready. Use these stages to define hooks that run when the container starts and stops.

```APIDOC
## `lifecycle`

### Description
The default lifecycle stages for an Injecute container: `init`, `start`, and `ready`. Use these stages to define hooks that run when the container starts and stops.

### Source
`src/utils/lifecycle.ts`

### Type
`Lifecycle<'init' | 'start' | 'ready'>`

### Stages
- `init` — wire contributions, migrate, warm up
- `start` — begin accepting work: listen, start consumers
- `ready` — announce

Stopping undoes them in reverse.

### Example
```ts
const addPayments = (c: ServiceRegistry<{ bus: Bus }>) =>
  c
    .addSingleton('consumer', PaymentConsumer, ['bus'])
    .addSingleton(lifecycle.start('consumer'), (consumer) => {
      consumer.start();
      return () => consumer.stop();
    }, ['consumer']);
```
```

--------------------------------

### Dependency not provided by any file

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/custom-registration.md

This example shows a dependencies array that includes 'mailer', but there is no services/mailer.ts file. The error message indicates that the extension requires a service that is not registered.

```ts
export const dependencies = ['config', 'clock', 'mailer']; // there is no services/mailer.ts
```

```text
app.ts: Argument of type '(registry: ServiceRegistry<Requires>) => …' is not assignable to parameter
  of type '{ 'injecute: extension requires services that are not registered': "mailer"; }'.
```

--------------------------------

### namespace usage example

Source: https://github.com/masyaka/injecute

Shows how to register a namespace and access its services via the prefix and the namespace provider.

```ts
app.namespace('Billing', (billing) =>
  billing.addSingleton('invoices', InvoiceRepository, ['db']),
);
app.get('Billing.invoices');
app.get('Billing'); // ServiceProvider<{ invoices: InvoiceRepository }>
```

--------------------------------

### collect usage example

Source: https://github.com/masyaka/injecute

Shows how to use collect to gather all services registered under a tag, e.g., commands, and inject them as an array.

```ts
const command = createTag('command').of<Command>();

app
  .addSingleton(command('migrate'), MigrateCommand, ['db'])
  .addSingleton(command('seed'), SeedCommand, ['db'])
  .addSingleton('cli', (commands) => new Cli(commands), [collect(command)]); // Command[]
```

--------------------------------

### HTTP module: register routes and start server

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/fastify.md

Defines an extension point for route plugins and starts the Fastify server in a lifecycle hook. Registers a factory for the server to avoid thenable issues, and uses preValidation hook to run handlers in a request context. The server is a hook, so running.stop() closes it before dispose().

```TypeScript
// http.ts
import Fastify, { type FastifyPluginAsync } from 'fastify';
import { collect, createTag, lifecycle, type ServiceRegistry } from 'injecute';
import { storage } from './context.ts';

/** A Fastify plugin a module registers under a prefix. */
export interface Routes {
  readonly prefix: string;
  readonly plugin: FastifyPluginAsync;
}
/** The extension point: every module's routes. */
export const routes = createTag('routes').of<Routes>();

export const addHttp = (c: ServiceRegistry<{ port: number }>) =>
  c
    // a factory, not the instance: a Fastify instance is thenable
    .addSingleton(
      'createServer',
      (contributions) => () => {
        const server = Fastify({ logger: true });
        // preValidation runs after the body is parsed: the handlers run in this context
        server.addHook('preValidation', (request, _reply, done) => {
          storage.run(
            {
              traceId: request.id,
              tenantId: request.headers['x-tenant-id'] as string | undefined,
            },
            done,
          );
        });
        for (const { prefix, plugin } of contributions)
          server.register(plugin, { prefix });
        return server;
      },
      [collect(routes)],
    )
    .addSingleton(
      lifecycle.start('server'),
      async (createServer, port) => {
        const server = createServer();
        await server.listen({ port, host: '0.0.0.0' });
        return () => server.close(); // stops accepting requests, waits for open ones, runs onClose hooks
      },
      ['createServer', 'port'],
    );
```

--------------------------------

### Import map for injecute

Source: https://github.com/masyaka/injecute/blob/main/tests/browser/import-map.html

Defines an import map that maps the 'injecute' module to '/lib/index.js'.

```html
<script type="importmap">
{
  "imports": {
    "injecute": "/lib/index.js"
  }
}
</script>
```

--------------------------------

### getRegistration usage example

Source: https://github.com/masyaka/injecute

Shows how to inspect a registration's metadata, e.g., kind and dependencies.

```ts
const info = app.getRegistration('db');
// info.kind === 'singleton', info.dependencies: DependencyInfo[]
```

--------------------------------

### Resolving async services at startup

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/async.md

get() of a deferred service returns a promise; await it where you use it, or resolve the async services once at startup.

```ts
const [db, cache] = await Promise.all([app.get('db'), app.get('cache')]);
```

--------------------------------

### ownKeys usage example

Source: https://github.com/masyaka/injecute

Shows how to get the container's own keys, e.g., ['dbUrl', 'db', 'users'].

```ts
const own = app.ownKeys; // e.g. ['dbUrl', 'db', 'users']
```

--------------------------------

### get(key)

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/async.md

Resolves a service by key. Returns a promise that resolves to the service instance. Rejects if the key is missing.

```APIDOC
## get(key)

### Description
Resolves a service by key. Returns a promise that resolves to the service instance. Rejects if the key is missing.

### Method
Async method

### Endpoint
`get(key)`

### Parameters
- **key** (string) - Required - The service key to resolve.

### Response
Returns a `Promise` that resolves to the service instance.

### Example
```typescript
const users = await app.get('users'); // UserRepository
```
```

--------------------------------

### createResolver usage example

Source: https://github.com/masyaka/injecute

Creates a resolver for the 'db' service and later calls it to get the service instance.

```typescript
const connect = app.createResolver('db');

// later, inside a module or worker:
const db = connect();
```

--------------------------------

### keys usage example

Source: https://github.com/masyaka/injecute

Iterates over all visible keys and logs each one as a string.

```ts
for (const key of app.keys) {
  console.log(String(key));
}
```

--------------------------------

### Start application lifecycle with SIGTERM handling

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/fastify.md

Starts the application lifecycle and listens for SIGTERM to stop gracefully. The stop method is called on the running instance, and errors are logged to the console. For a complete entry point with grace period and second signal, see the referenced guide.

```typescript
// main.ts
import { startLifecycle } from 'injecute';
import { createApp } from './app.ts';

const running = await startLifecycle(createApp());
process.once('SIGTERM', () =>
  running.stop().catch((error) => console.error(error)),
);
```

--------------------------------

### Project structure with wiring files and composition root

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/app-structure.md

Shows the recommended file layout: plain service classes, per-module wiring files (e.g., orders.container.ts), a composition root (container.ts), and an entry point (main.ts).

```text
src/
  orders/
    orders-service.ts     plain classes: no injecute imports
    orders-repository.ts
    orders.container.ts   addOrders: registrations only
  billing/
    billing.container.ts
  container.ts            the composition root: createApp()
  main.ts                 the entry point: start, signals
```

--------------------------------

### Solid entry point creating core and providing it

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/ui-frameworks.md

Solid entry point that creates the core with an API URL from the environment and provides it to the app via ServicesProvider.

```tsx
// src/index.tsx
import { render } from 'solid-js/web';
import { createCore } from './core/container';
import { App } from './ui/App';
import { ServicesProvider } from './ui/services';

const core = createCore({ apiUrl: import.meta.env.VITE_API_URL });

render(
  () => (
    <ServicesProvider value={core}>
      <App />
    </ServicesProvider>
  ),
  document.getElementById('root')!,
);
```

--------------------------------

### Typo in dependency key is a compile error

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/getting-started.md

A typo in a dependency key is reported on the key. The error message suggests the correct key 'address'.

```ts
app.addSingleton('server', createServer, ['adress']);
// Type '"adress"' is not assignable to type 'Dependency<…>'. Did you mean '"address"'?
```

--------------------------------

### addAlias usage example

Source: https://github.com/masyaka/injecute

Shows how to use addAlias to conditionally alias a key and to replace an alias in a fork.

```ts
app.addAlias('logger', config.production ? 'jsonLogger' : 'prettyLogger');
app.fork().addAlias('logger', 'prettyLogger', { replace: true }); // in this fork only
```

--------------------------------

### Infer factory parameters and results with addSingleton

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/getting-started.md

Factory parameters and results are inferred from registrations. The 'address' factory receives 'port' as a number and returns a string.

```ts
import { DIContainer } from 'injecute';

const app = new DIContainer()
  .addInstance('port', 8080)
  // port: number
  .addSingleton('address', (port) => `http://localhost:${port}`, ['port']);

const address = app.get('address'); // string
//    ^?
```

--------------------------------

### React entry point creating core and providing it

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/ui-frameworks.md

React entry point that creates the core with an API URL from the environment and provides it to the app via ServicesProvider.

```tsx
// src/main.tsx
import { createRoot } from 'react-dom/client';
import { createCore } from './core/container';
import { App } from './ui/app';
import { ServicesProvider } from './ui/services';

const core = createCore({ apiUrl: import.meta.env.VITE_API_URL });

createRoot(document.getElementById('root')!).render(
  <ServicesProvider value={core}>
    <App />
  </ServicesProvider>,
);
```

--------------------------------

### Lifecycle usage example

Source: https://github.com/masyaka/injecute

Creates lifecycle stages, registers a hook with addSingleton, and starts the lifecycle. The hook factory may return a function that undoes it.

```ts
export const stages = createLifecycle(['migrate', 'init', 'start', 'ready'] as const);

c.addSingleton(stages.migrate('schema'), (db) => migrate(db), ['db']);

const running = await startLifecycle(app, { lifecycle: stages });
```

--------------------------------

### Using startable to register a service

Source: https://github.com/masyaka/injecute

Example of using startable to register a service with lifecycle hooks. The hook is registered as lifecycle.start('consumer') → key 'consumer:start'.

```typescript
const addPayments = (c: ServiceRegistry<{ bus: Bus }>) =>
  c.extend(
    startable('consumer', PaymentConsumer, ['bus'], {
      start: (consumer) => consumer.start(),
      stop: (consumer) => consumer.stop(),
    }),
  );

app.extend(addPayments);
// the hook is registered as lifecycle.start('consumer') → key 'consumer:start'
```

--------------------------------

### Applying generated wiring with DIContainer

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/custom-registration.md

Shows how to use the generated addServices module with DIContainer, adding a config instance and extending with the generated wiring. The example then retrieves the greeter service and calls greet, producing the shown output.

```typescript
import { DIContainer } from 'injecute';
import { addServices } from './services.generated.ts';

const app = new DIContainer()
  .addInstance('config', { greeting: 'Hello' })
  .extend(addServices);

app.get('greeter').greet('Ada'); // "Hello, Ada (1970-01-01T00:00:00.000Z)"

```

--------------------------------

### Vue entry point creating core and providing it

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/ui-frameworks.md

Vue entry point that creates the core with an API URL from the environment and provides it to the app via a services key.

```ts
// src/main.ts
import { createApp } from 'vue';
import { createCore } from './core/container';
import App from './ui/App.vue';
import { servicesKey } from './ui/services';

const core = createCore({ apiUrl: import.meta.env.VITE_API_URL });

createApp(App).provide(servicesKey, core).mount('#app');
```

--------------------------------

### DIContainer usage with import map

Source: https://github.com/masyaka/injecute/blob/main/tests/browser/import-map.html

Imports DIContainer from 'injecute', creates a container, adds a singleton 'answer' with value 42, and displays 'ok' if get('answer') returns 42, otherwise 'wrong'.

```javascript
import { DIContainer } from 'injecute';
const container = new DIContainer().addSingleton('answer', () => 42, []);
document.getElementById('out').textContent = container.get('answer') === 42 ? 'ok' : 'wrong';
```

--------------------------------

### preload()

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/async.md

Creates every service now, so wiring errors surface at boot. Returns a promise that settles once all services are created.

```APIDOC
## preload()

### Description
Creates every service now, so wiring errors surface at boot. Returns a promise that settles once all services are created.

### Method
Async method

### Endpoint
`preload()`

### Parameters
None

### Response
Returns a `Promise` that resolves when all services are created.

### Example
```typescript
await preload(withReports); // creates every service now, so wiring errors surface at boot
```
```

--------------------------------

### Register private services with symbol keys in a namespace

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/containers.md

Symbol keys are not added to the container's keys and are not accessible outside the namespace. The example shows a private cache used by a public service; get() with the symbol fails at runtime with INJECUTE_NOT_REGISTERED.

```typescript
const cache = Symbol('cache'); // not exported: only this module has the key

const addCatalog = (c: ServiceRegistry<{ db: Database }>) =>
  c
    .addSingleton(cache, () => new Map<string, string>())
    .addSingleton('products', (db, prices) => ({ db, prices }), ['db', cache]);

const shop = new DIContainer()
  .addInstance('dbUrl', 'postgres://prod')
  .addSingleton('db', Database, ['dbUrl'])
  .namespace('Catalog', addCatalog);

shop.get('Catalog.products'); // resolves, with the private cache
shop.keys; // ['dbUrl', 'db', 'Catalog', 'Catalog.products']: no cache
// shop.get(cache); // type error, and INJECUTE_NOT_REGISTERED at runtime
```

--------------------------------

### Create core container with QueryClient (src/core/container.ts)

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/ui-frameworks.md

Sets up the DI container with a QueryClient singleton, configured with retry from config and disposed via clear(). The core owns the QueryClient, one per app/test/server request.

```ts
// src/core/container.ts
import { QueryClient } from '@tanstack/query-core';

export interface Config {
  apiUrl: string;
  retry?: boolean;
}

export const createCore = (config: Config) =>
  new DIContainer()
    .addInstance('config', config)
    .addSingleton('api', (config) => new ApiClient(config.apiUrl), ['config'])
    .addSingleton(
      'queryClient',
      (config) =>
        new QueryClient({
          defaultOptions: { queries: { retry: config.retry ?? 3 } },
        }),
      { dependencies: ['config'], dispose: (client) => client.clear() },
    )
    .namespace('Orders', addOrders)
    .seal();
```

--------------------------------

### Guard middleware: prevent request-scoped resolution from root container

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/middleware-events.md

Middleware that throws when a request-scoped key is resolved from the root container. It checks if the key starts with 'request.' and the container is the root, then throws an error. The example shows a fork resolving 'request.user' successfully, while the root would throw.

```typescript
// Request-scoped services must never be resolved from the root container.
const root = new DIContainer()
  .addSingleton('config', () => ({ region: 'eu' }))
  .use((key, next, { container }) => {
    if (
      typeof key === 'string' &&
      key.startsWith('request.') &&
      container === root
    ) {
      throw new Error(
        `"${key}" is request-scoped: resolve it from a request fork`,
      );
    }
    return next();
  });

const request = root.fork().addInstance('request.user', { id: 42 });
request.get('request.user'); // ok
// root.get('request.user' as never) would throw
```

--------------------------------

### call usage example

Source: https://github.com/masyaka/injecute

Example of using `call` to invoke a function service with arguments.

```TypeScript
await app.call('greet', ['Ada']);
```

--------------------------------

### Add singleton with lifecycle start hook

Source: https://github.com/masyaka/injecute

Registers a singleton and attaches a start hook that starts and stops the consumer. The hook returns a cleanup function to stop the consumer.

```ts
const addPayments = (c: ServiceRegistry<{ bus: Bus }>) =>
  c
    .addSingleton('consumer', PaymentConsumer, ['bus'])
    .addSingleton(lifecycle.start('consumer'), (consumer) => {
      consumer.start();
      return () => consumer.stop();
    }, ['consumer']);
```

--------------------------------

### startLifecycle()

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/async.md

Runs lifecycle hooks at startup. Awaits each hook, including in an async container.

```APIDOC
## startLifecycle()

### Description
Runs lifecycle hooks at startup. Awaits each hook, including in an async container.

### Method
Async method

### Endpoint
`startLifecycle()`

### Parameters
None

### Response
Returns a `Promise` that resolves when all lifecycle hooks complete.
```

--------------------------------

### Using createDecorators: declare, decorate, and inject

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/custom-registration.md

Shows the full workflow: declare Services and Requires types, create a decorator set, decorate classes to register them, and apply the decorators as a module with extend() on a container. The example is one file with createDecorators() at the top, and is available in the playground.

```typescript
// The services the decorated classes provide, and what they need from the container.
type Services = { clock: Clock; greeter: Greeter };
type Requires = { config: Config };

const services = createDecorators<Services, Requires>();

@services.singleton('clock')
class Clock {
  now() {
    return new Date(0);
  }
}

@services.singleton('greeter', ['config', 'clock'])
class Greeter {
  constructor(
    private config: Config,
    private clock: Clock,
  ) {}

  greet(name: string) {
    return `${this.config.greeting}, ${name} (${this.clock.now().toISOString()})`;
  }
}

const app = new DIContainer()
  .addInstance('config', { greeting: 'Hello' })
  .extend(services); // DIContainer<{ config: Config } & Services>

app.get('greeter').greet('Ada'); // "Hello, Ada (1970-01-01T00:00:00.000Z)"
```

--------------------------------

### Check wiring at startup with preload

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/recipes.md

Resolves every service at boot so configuration errors surface immediately. Stops at the first failure; for tests, use `checkWiring()` to get all issues at once.

```ts
import { preload } from 'injecute';

await preload(app); // resolves every service now, so configuration errors surface at boot
```

--------------------------------

### startSignal

Source: https://github.com/masyaka/injecute

A dependency that gives a lifecycle hook the start signal: the signal passed to startLifecycle(), which aborts when the start takes too long. Pass it on to the work the hook waits for (a connection, a request). Outside a start, and without a signal option, it never aborts.

```APIDOC
## startSignal

### Description
A dependency that gives a lifecycle hook the start signal: the `signal` passed to `startLifecycle()`, which aborts when the start takes too long. Pass it on to the work the hook waits for (a connection, a request). Outside a start, and without a `signal` option, it never aborts.

### Method
startSignal

### Endpoint
`src/utils/lifecycle.ts`

### Parameters
#### Function Signature
- `startSignal(): LifecycleSignal`

### Response
#### Success Response
- **LifecycleSignal** - `AbortSignal` when the environment has it, otherwise `AbortSignalLike`

### Request Example
```ts
app.addSingleton(
  lifecycle.init('config'),
  async (client, signal) => {
    await client.load({ signal }); // cancelled when the start times out
  },
  ['configClient', startSignal],
);

await startLifecycle(app, { signal: AbortSignal.timeout(30_000) });
```
```

--------------------------------

### Generated wiring output for clock and greeter services

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/custom-registration.md

Example output from generateWiring for the two service files mentioned. Shows the generated module with Requires interface and addServices function that registers clock and greeter with dependencies.

```typescript
// Generated from ../services/ by generate-wiring.ts. Don't edit: run the generator.
import type { ServiceRegistry } from 'injecute';
import * as clock from '../services/clock.ts';
import * as greeter from '../services/greeter.ts';

export interface Requires {
  config: Parameters<typeof greeter.default>[0];
}

export const addServices = (registry: ServiceRegistry<Requires>) =>
  registry
    .addSingleton('clock', clock.default)
    .addSingleton('greeter', greeter.default, ['config', 'clock']);

```

--------------------------------

### Install injecute Agent Skill for any agent

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/ai-agents.md

Install the injecute Agent Skill for any agent that supports skills using npx.

```sh
npx skills add Masyaka/injecute
```

--------------------------------

### preload(app)

Source: https://github.com/masyaka/injecute/blob/main/skills/injecute/SKILL.md

Preloads the async container to resolve all dependencies. Should be called at startup.

```APIDOC
## preload(app)

### Description
Preloads the async container to resolve all dependencies. Should be called at startup.

### Method
preload

### Parameters
- **app** (AsyncDIContainer) - Required - The async container.

### Returns
Promise<void>

### Example
```ts
import { preload } from 'injecute';

await preload(app);
```
```

--------------------------------

### injecute and bind usage example

Source: https://github.com/masyaka/injecute

Example of using `injecute` to resolve dependencies and call a factory, and `bind` to create a reusable function that resolves dependencies and calls a factory.

```TypeScript
const config = await app.injecute(async (dbUrl) => loadConfig(dbUrl), ['dbUrl']);
const sendReport = app.bind(['mailer', 'reports'], (mailer, reports) => mailer.send(reports.weekly()));
await sendReport();
```

--------------------------------

### Install injecute Agent Skill in Claude Code

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/ai-agents.md

Install the injecute Agent Skill from the plugin marketplace in Claude Code using these two commands.

```sh
/plugin marketplace add Masyaka/injecute
/plugin install injecute@injecute
```

--------------------------------

### Async factories in a DIContainer with defer()

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/async.md

A factory can return a promise; a singleton caches that promise so concurrent get() calls share one creation. If the promise rejects, the container drops it and the next get() tries again, wrapping the rejection in INJECUTE_RESOLUTION_FAILED. defer() wraps a factory so its promised arguments are awaited first, and get() of a deferred service returns a promise.

```typescript
const app = new DIContainer()
  .addSingleton('config', async (): Promise<Config> => ({
    dbUrl: 'postgres://localhost',
  }))
  // defer(): awaits the promised arguments, so the factory receives the resolved config
  .addSingleton(
    'db',
    defer((config: Config) => new Database(config.dbUrl)),
    ['config'],
  );

export async function connect(): Promise<Database> {
  return app.get('db'); // Promise<Database>
}
```

--------------------------------

### checkWiring and createProxyAccessor usage

Source: https://github.com/masyaka/injecute

Shows how to use checkWiring with resolve option and createProxyAccessor with keys and optional options.

```typescript
await checkWiring(createApp(), { resolve: true });
const sdk = createProxyAccessor(app, { keys: ['db', ['users', 'findUsers']], optional: false });
```

--------------------------------

### injecute usage example

Source: https://github.com/masyaka/injecute

Shows how to use `injecute` to run a function with resolved dependencies without registering it. The example resolves 'users' and 'logger' and passes them to `createHandler`.

```typescript
const handler = app.injecute((users, logger) => createHandler(users, logger), ['users', 'logger']);
```

--------------------------------

### GetOptions / HasOptions

Source: https://github.com/masyaka/injecute

Options for the `get` and `has` methods of the container. `GetOptions` controls whether `get` returns `undefined` for missing keys, and `HasOptions` controls whether `has` only checks the local container.

```APIDOC
## GetOptions / HasOptions

### Description
Options for the `get` and `has` methods of the container. `GetOptions` controls whether `get` returns `undefined` for missing keys, and `HasOptions` controls whether `has` only checks the local container.

### Options

#### GetOptions
- `optional?: boolean` - Optional - Return `undefined` instead of throwing for a missing key (default `false`)

#### HasOptions
- `local?: boolean` - Optional - Only look at this container, not its parents (default `false`)

### Example
```ts
app.get('cache', { optional: true }); // Cache | undefined
app.has('tx', { local: true });       // ignores the parent's registration
```
```

--------------------------------

### Singleton platform per process (lib/platform.ts)

Source: https://github.com/masyaka/injecute/blob/main/docs/frameworks/nextjs.md

Uses globalThis to keep one platform per server process, surviving hot reloads and multiple bundles. Changes to createPlatform() take effect on dev server restart.

```ts
// lib/platform.ts
import { createPlatform } from './services';

type Platform = ReturnType<typeof createPlatform>;
const shared = globalThis as typeof globalThis & { __platform?: Platform };

// Next.js evaluates this module again on every hot reload, and can bundle it more than once
// (instrumentation.ts and the routes): keep one platform per process.
export const platform = (shared.__platform ??= createPlatform());
```

--------------------------------

### Service file: greeter.ts with dependencies

Source: https://github.com/masyaka/injecute/blob/main/docs/guide/custom-registration.md

Declares dependencies as an array of service keys and exports a factory that receives them in order.

```typescript
import type createClock from './clock.ts';

// Keys of the services the factory receives, in order.
export const dependencies = ['config', 'clock'];

export default function createGreeter(
  config: { greeting: string },
  clock: ReturnType<typeof createClock>,
) {
  return {
    greet: (name: string) =>
      `${config.greeting}, ${name} (${clock.now().toISOString()})`,
  };
}
```
Tokens:
Raw