IoC Arise

A command-line tool that automatically generates type-safe IoC (Inversion of Control) containers for TypeScript projects using the ioc-arise runtime library. It analyzes your classes, detects dependencies, and generates the necessary registration code.

Table of Contents

• Features
• Installation
• Usage
• Configuration File
  • Config File Location
  • Priority Order
• Examples
  • Basic Example
• Usage in Your Code
• Development
• Limitations
• Contributing

Features

• 🔍 Automatic Detection: Finds classes to be registered
• 🧠 Dependency Analysis: Parses constructor dependencies from TypeScript code
• 🛡️ Type Safety: Uses the type-safe ioc-arise runtime library
• 🚫 No Decorators: Pure static analysis, no runtime decorators required
• ⚠️ Circular Dependency Detection: Warns about dependency cycles

Installation

First, install the runtime library and the CLI:

# Install runtime library
npm install ioc-arise

# Install CLI globally
npm install -g @notjustcoders/ioc-arise

# Or use with npx
npx @notjustcoders/ioc-arise --help

Usage

# Basic usage
ioc-arise generate

# With custom source and output
ioc-arise generate --source src --output src/container.gen.ts

Configuration File

You can create an ioc.config.json file in the same directory as your source code to set default options. CLI arguments will override config file settings.

{
  "source": "src",
  "output": "container.gen.ts",
  "interface": "I[A-Z].*",
  "exclude": [
    "**/*.test.ts",
    "**/*.spec.ts",
    "**/node_modules/**"
  ],
  "checkCycles": false,
  "verbose": true
}

Config File Location

The config file should be placed in the same directory as your source code. For example, if your source directory is src, place ioc.config.json in the src directory.

Priority Order

1. CLI arguments (highest priority)
2. Config file settings
3. Default values (lowest priority)

Examples

Basic Example

Directory structure:

minimal-todo/
├── entities/Todo.ts
├── repositories/
│   ├── ITodoRepository.ts
│   └── InMemoryTodoRepository.ts
├── services/
│   ├── ITodoService.ts
│   └── TodoService.ts
├── ioc.config.json
└── container.gen.ts (generated)

Generated container (container.gen.ts):

/**
 * This file is auto-generated by ioc-arise.
 * Do not modify this file manually.
 */
import { Container, Lifecycle } from '@notjustcoders/di-container';
import { InMemoryTodoRepository } from './repositories/InMemoryTodoRepository';
import { TodoService } from './services/TodoService';

export const container = new Container();

container.register(InMemoryTodoRepository, {
  useClass: InMemoryTodoRepository,
  lifecycle: Lifecycle.Singleton,
});

container.register(TodoService, {
  useClass: TodoService,
  dependencies: [InMemoryTodoRepository],
  lifecycle: Lifecycle.Transient,
});

Usage in Your Code

import { container } from './container.gen';
import { TodoService } from './services/TodoService';

// Resolve dependencies
const todoService = container.resolve(TodoService);
const todos = await todoService.getAllTodos();

Development

# Run in development mode
pnpm run dev

# Build for production
pnpm run build

Limitations

• Constructor parameters must be typed with classes that are also analyzed
• Circular dependencies are detected and warned about
• Only analyzes TypeScript files (.ts extension)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.