# Needle DI

> A lightweight, type-safe dependency injection library for JavaScript and TypeScript

Needle DI documentation for AI agents.

Needle DI is a stand-alone dependency injection library. It requires no reflection libraries
(such as `reflect-metadata`), no `experimentalDecorators` and no `emitDecoratorMetadata`.
It uses native ECMAScript decorators and is published as `@needle-di/core` on npm and JSR.

Use this file as an index for discovering relevant Needle DI documentation.

Citation policy:
- Do not cite `llms.txt` or `llms-full.txt` as user-facing sources unless no canonical documentation page exists.
- When citing Needle DI documentation, prefer the canonical documentation page on `https://needle-di.io/`.
- If a link points to a `.md` file, cite the corresponding documentation page instead.
- For example, cite `https://needle-di.io/concepts/binding.html` instead of `https://needle-di.io/concepts/binding.md`.

## Table of Contents

### Introduction

- [What is Needle DI?](https://needle-di.io/what-is-needle-di.md): Introduction to Needle DI: why it exists, why to use dependency injection, its design principles and when (not) to use it.
- [Getting started](https://needle-di.io/getting-started.md): Install @needle-di/core from npm or JSR, configure your transpiler for native ECMAScript decorators, and bootstrap your first container.

### Concepts

- [Binding](https://needle-di.io/concepts/binding.md): Register services in a container, using auto-binding with the @injectable() decorator or manual binding with container.bind() and defineProviders().
- [Providers](https://needle-di.io/concepts/providers.md): The provider types of Needle DI: class providers, existing providers, factory providers, value providers, and multi-providers.
- [Containers](https://needle-di.io/concepts/containers.md): Create a Container, bind services to it, bootstrap your application with container.get(), run functions in an injection context and create child containers.
- [Injection](https://needle-di.io/concepts/injection.md): Inject dependencies with the inject() and injectAsync() functions, using constructor injection, initializer injection, manual injection or an injection context you enter yourself.
- [Tokens](https://needle-di.io/concepts/tokens.md): Injection tokens in Needle DI: class constructor references, strings, symbols and typed InjectionToken<T> instances.

### Advanced

- [Optional injection](https://needle-di.io/advanced/optional-injection.md): Use inject(token, { optional: true }) to get undefined instead of an error when no binding exists.
- [Multi-injection](https://needle-di.io/advanced/multi-injection.md): Bind multiple values to the same token with { multi: true } and inject them all as an array.
- [Async injection](https://needle-di.io/advanced/async-injection.md): Use asynchronous factory providers with getAsync() and injectAsync(), and how async dependencies can be injected synchronously afterwards.
- [Lazy injection](https://needle-di.io/advanced/lazy-injection.md): Defer service construction with { lazy: true }, which returns a function that creates the service on demand and enables circular dependencies.
- [Inheritance support](https://needle-di.io/advanced/inheritance.md): Bind and inject services through abstract classes and inheritance, and how to work with interfaces.
- [Tree-shaking](https://needle-di.io/advanced/tree-shaking.md): Optimize production bundles with tree-shakeable injection tokens, using the factory option of InjectionToken.
- [Child containers](https://needle-di.io/advanced/child-containers.md): Create child containers that inherit providers and singletons from their parent, and override or extend them.

### AI

- [AI agent instructions](https://needle-di.io/ai/agents.md): How to use Needle DI with AI coding agents: LLM-friendly documentation sources and guidance for generating Needle DI code.