Introduction 🚀

Clawject is TypeScript Dependency Injection framework that's here to make your coding life easier. Forget about injection tokens and a huge number of decorators on and in your business classes. Use typescript features like interfaces, generics, type hierarchies in a declarative and intuitive way and let Clawject do messy work for you!

Main Features

• Ahead of Time Dependency Injection based on TypeScript types, full type safety because no injection tokens are used.
• Can be used both in Node.js and in the browser.
• Declarative and intuitive API.
• Fast at runtime, all dependency-resolution work is done at compile time!
• IDEs support, all errors and warnings are shown right in your code editor window.
• Ahead of Time circular dependencies detection with a clear cycle path, forget about runtime loops and stack overflows!
• No need to refer to a dependency injection library in your business-oriented classes, leave them clean and framework independent!
• Injection scopes support and ability to create your own custom scopes.
• Supports both experimental and stable JavaScript decorators + no dependency on reflect-metadata library.
• Minimal runtime overhead.
• Clawject is not modifying your classes, not adding additional runtime fields, so it's safe to use it with any other library or framework.

Let's compare Clawject with other popular frameworks that implements Dependency Injection, note how class is using interfaces with generics to declare dependencies:

Clawject

interface IRepository<T> { /*...*/ }
class RepositoryImpl<T> implements IRepository<T> { /*...*/ }
class PrimitivesService {
  constructor(
    private stringRepository: IRepository<string>,
    private numberRepository: IRepository<number>,
    private booleanRepository: IRepository<boolean>,
  ) {}
}

@ClawjectApplication
class Application {
  stringRepository = Bean(RepositoryImpl<string>);
  numberRepository = Bean(RepositoryImpl<number>);
  booleanRepository = Bean(RepositoryImpl<boolean>);
  primitivesService Bean(PrimitivesService);
}

NestJS

interface IRepository<T> { /*...*/ }
@Injectable()
class RepositoryImpl<T> implements IRepository<T> { /*...*/ }
const InjectionTokens = {
  StringRepository: Symbol('StringRepository'),
  NumberRepository: Symbol('NumberRepository'),
  BooleanRepository: Symbol('BooleanRepository'),
}

@Injectable()
class PrimitivesService {
  constructor(
    @Inject(InjectionTokens.StringRepository)
    private stringRepository: IRepository<string>,
    @Inject(InjectionTokens.NumberRepository)
    private numberRepository: IRepository<number>,
    @Inject(InjectionTokens.BooleanRepository)
    private booleanRepository: IRepository<boolean>,
  ) {}
}

@Module({
  providers: [
    PrimitivesService,
    { provide: InjectionTokens.StringRepository, useClass: RepositoryImpl },
    { provide: InjectionTokens.NumberRepository, useClass: RepositoryImpl },
    { provide: InjectionTokens.BooleanRepository, useClass: RepositoryImpl },
  ],
})
class Application {}

Angular

interface IRepository<T> { /*...*/ }
@Injectable()
class RepositoryImpl<T> implements IRepository<T> { /*...*/ }
const InjectionTokens = {
  StringRepository: new InjectionToken<IRepository<string>>('StringRepository'),
  NumberRepository: new InjectionToken<IRepository<number>>('NumberRepository'),
  BooleanRepository: new InjectionToken<IRepository<boolean>>('BooleanRepository'),
}

@Injectable()
class PrimitivesService {
  constructor(
    @Inject(InjectionTokens.StringRepository)
    private stringRepository: IRepository<string>,
    @Inject(InjectionTokens.NumberRepository)
    private numberRepository: IRepository<number>,
    @Inject(InjectionTokens.BooleanRepository)
    private booleanRepository: IRepository<boolean>,
  ) {}
}

@NgModule({
  providers: [
    PrimitivesService,
    { provide: InjectionTokens.StringRepository, useClass: RepositoryImpl },
    { provide: InjectionTokens.NumberRepository, useClass: RepositoryImpl },
    { provide: InjectionTokens.BooleanRepository, useClass: RepositoryImpl },
  ],
})
class Application {}

TSyringe

interface IRepository<T> { /*...*/ }
@injectable()
class RepositoryImpl<T> implements IRepository<T> { /*...*/ }
const InjectionTokens = {
  StringRepository: Symbol('StringRepository'),
  NumberRepository: Symbol('NumberRepository'),
  BooleanRepository: Symbol('BooleanRepository'),
}

@injectable()
class PrimitivesService {
  constructor(
    @inject(InjectionTokens.StringRepository)
    private stringRepository: IRepository<string>,
    @inject(InjectionTokens.NumberRepository)
    private numberRepository: IRepository<number>,
    @inject(InjectionTokens.BooleanRepository)
    private booleanRepository: IRepository<boolean>,
  ) {}
}

container.register(InjectionTokens.StringRepository, { useClass: RepositoryImpl });
container.register(InjectionTokens.NumberRepository, { useClass: RepositoryImpl });
container.register(InjectionTokens.BooleanRepository, { useClass: RepositoryImpl });
container.register(PrimitivesService, { useClass: PrimitivesService });

When it comes to the more complex scenarios, like generic inside constructors - with Clawject, it's still easy and type-safe but with other frameworks, it's getting really messy and hard to maintain, see the comparison below:

Clawject

interface ICache<T> {}
class CacheImpl<T> implements ICache<T> {}
interface IRepository<T> { /*...*/ }
class RepositoryImpl<T> implements IRepository<T> {
  constructor(
    private cache: ICache<T>,
  ) {}
}
class PrimitivesService {
  constructor(
    private stringRepository: IRepository<string>,
    private numberRepository: IRepository<number>,
    private booleanRepository: IRepository<boolean>,
  ) {}
}

@ClawjectApplication
class Application {
  stringCache = Bean(CacheImpl<string>);
  numberCache = Bean(CacheImpl<number>);
  booleanCache = Bean(CacheImpl<boolean>);
  stringRepository = Bean(RepositoryImpl<string>);
  numberRepository = Bean(RepositoryImpl<number>);
  booleanRepository = Bean(RepositoryImpl<boolean>);
  primitivesService = Bean(PrimitivesService);
}

NestJS

interface ICache<T> {}
class CacheImpl<T> implements ICache<T> {}
interface IRepository<T> { /*...*/ }
class RepositoryImpl<T> implements IRepository<T> {
  constructor(
    private cache: ICache<T>,
  ) {}
}

const InjectionTokens = {
  StringCache: Symbol('StringCache'),
  NumberCache: Symbol('NumberCache'),
  BooleanCache: Symbol('BooleanCache'),
  StringRepository: Symbol('StringRepository'),
  NumberRepository: Symbol('NumberRepository'),
  BooleanRepository: Symbol('BooleanRepository'),
}

@Injectable()
class PrimitivesService {
  constructor(
    @Inject(InjectionTokens.StringRepository)
    private stringRepository: IRepository<string>,
    @Inject(InjectionTokens.NumberRepository)
    private numberRepository: IRepository<number>,
    @Inject(InjectionTokens.BooleanRepository)
    private booleanRepository: IRepository<boolean>,
  ) {}
}

@Module({
  providers: [
    PrimitivesService,
    { provide: InjectionTokens.StringCache, useClass: CacheImpl },
    { provide: InjectionTokens.NumberCache, useClass: CacheImpl },
    { provide: InjectionTokens.BooleanCache, useClass: CacheImpl },
    {
      provide: InjectionTokens.StringRepository,
      useFactory: (cache: ICache<string>) => new RepositoryImpl(cache),
      inject: [InjectionTokens.StringCache],
    },
    {
      provide: InjectionTokens.NumberRepository,
      useFactory: (cache: ICache<number>) => new RepositoryImpl(cache),
      inject: [InjectionTokens.NumberCache],
    },
    {
      provide: InjectionTokens.BooleanRepository,
      useFactory: (cache: ICache<boolean>) => new RepositoryImpl(cache),
      inject: [InjectionTokens.BooleanCache],
    },
  ]
})
export class Application {}

Angular

interface ICache<T> {}
class CacheImpl<T> implements ICache<T> {}
interface IRepository<T> { /*...*/ }
class RepositoryImpl<T> implements IRepository<T> {
  constructor(
    private cache: ICache<T>,
  ) {}
}

const InjectionTokens = {
  StringCache: new InjectionToken<ICache<string>>('StringCache'),
  NumberCache: new InjectionToken<ICache<number>>('NumberCache'),
  BooleanCache: new InjectionToken<ICache<boolean>>('BooleanCache'),
  StringRepository: new InjectionToken<IRepository<string>>('StringRepository'),
  NumberRepository: new InjectionToken<IRepository<number>>('NumberRepository'),
  BooleanRepository: new InjectionToken<IRepository<boolean>>('BooleanRepository'),
}

@Injectable()
class PrimitivesService {
  constructor(
    @Inject(InjectionTokens.StringRepository)
    private stringRepository: IRepository<string>,
    @Inject(InjectionTokens.NumberRepository)
    private numberRepository: IRepository<number>,
    @Inject(InjectionTokens.BooleanRepository)
    private booleanRepository: IRepository<boolean>,
  ) {}
}

@NgModule({
  providers: [
    PrimitivesService,
    { provide: InjectionTokens.StringCache, useClass: CacheImpl },
    { provide: InjectionTokens.NumberCache, useClass: CacheImpl },
    { provide: InjectionTokens.BooleanCache, useClass: CacheImpl },
    {
      provide: InjectionTokens.StringRepository,
      useFactory: (cache: ICache<string>) => new RepositoryImpl(cache),
      inject: [InjectionTokens.StringCache],
    },
    {
      provide: InjectionTokens.NumberRepository,
      useFactory: (cache: ICache<number>) => new RepositoryImpl(cache),
      inject: [InjectionTokens.NumberCache],
    },
    {
      provide: InjectionTokens.BooleanRepository,
      useFactory: (cache: ICache<boolean>) => new RepositoryImpl(cache),
      inject: [InjectionTokens.BooleanCache],
    },
  ]
})
export class Application {}

TSyringe

interface ICache<T> {}
class CacheImpl<T> implements ICache<T> {}
interface IRepository<T> { /*...*/ }
class RepositoryImpl<T> implements IRepository<T> {
  constructor(
    private cache: ICache<T>,
  ) {}
}

const InjectionTokens = {
  StringCache: Symbol('StringCache'),
  NumberCache: Symbol('NumberCache'),
  BooleanCache: Symbol('BooleanCache'),
  StringRepository: Symbol('StringRepository'),
  NumberRepository: Symbol('NumberRepository'),
  BooleanRepository: Symbol('BooleanRepository'),
}

@injectable()
class PrimitivesService {
  constructor(
    @inject(InjectionTokens.StringRepository)
    private stringRepository: IRepository<string>,
    @inject(InjectionTokens.NumberRepository)
    private numberRepository: IRepository<number>,
    @inject(InjectionTokens.BooleanRepository)
    private booleanRepository: IRepository<boolean>,
  ) {}
}

container.register(InjectionTokens.StringCache, { useClass: CacheImpl });
container.register(InjectionTokens.NumberCache, { useClass: CacheImpl });
container.register(InjectionTokens.BooleanCache, { useClass: CacheImpl });
container.register(
  InjectionTokens.StringRepository,
  { useFactory: (container) => new RepositoryImpl(container.resolve(InjectionTokens.StringCache)) },
);
container.register(
  InjectionTokens.NumberRepository,
  { useFactory: (container) => new RepositoryImpl(container.resolve(InjectionTokens.NumberCache)) },
);
container.register(
  InjectionTokens.BooleanRepository,
  { useFactory: (container) => new RepositoryImpl(container.resolve(InjectionTokens.BooleanCache)) },
);
container.register(PrimitivesService, { useClass: PrimitivesService });

As you can see - Clawject requires much less boilerplate code, not pollutes business classes and provides an intuitive, declarative and really type-safe API where you can't miss a thing. Let's clawject your codebase and make it more maintainable and easy to understand!

Inspiration

Clawject is inspired by Spring framework and NestJS