injectkit 1.0.0

package/dist/interfaces.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Represents a constructor function that can be instantiated with the `new` operator.
+ * @template T The type of instance that this constructor creates.
+ */
+export interface Constructor<T> extends Function {
+    new (...args: any[]): T;
+}
+/**
+ * Represents an abstract class or interface that cannot be directly instantiated.
+ * @template T The type of the prototype.
+ */
+export interface Abstract<T> extends Function {
+    prototype: T;
+}
+/**
+ * A type identifier used to resolve dependencies in the container.
+ * Can be either a concrete constructor or an abstract class/interface.
+ * @template T The type being identified.
+ */
+export type Identifier<T> = Constructor<T> | Abstract<T>;
+/**
+ * Represents an instance of type T that is also an object.
+ * @template T The type of the instance.
+ */
+export type Instance<T> = T & object;
+/**
+ * Extracts the element type from an array type.
+ * @template T The array type to extract the element type from.
+ * @example
+ * ArrayType<Array<string>> // string
+ * ArrayType<string[]> // string
+ */
+export type ArrayType<T> = T extends Array<infer I> ? I : never;
+/**
+ * Extracts the key and value types from a map type.
+ * @template T The map type to extract the key and value types from.
+ * @example
+ * MapType<Map<string, number>> // [string, number]
+ * MapType<Map<symbol, AbstractService>> // [symbol, AbstractService]
+ */
+export type MapType<T> = T extends Map<infer I, infer O> ? [I, O] : never;
+/**
+ * Dependency injection container that manages the creation and lifetime of registered services.
+ */
+export declare abstract class Container {
+    /**
+     * Retrieves an instance of the specified type from the container.
+     * For singleton and scoped lifetimes, returns cached instances when available.
+     * For transient lifetimes, creates a new instance each time.
+     * @template T The type of instance to retrieve.
+     * @param id The identifier (constructor or abstract class) for the type to resolve.
+     * @returns An instance of type T.
+     */
+    abstract get<T>(id: Identifier<T>): T;
+    /**
+     * Creates a new scoped container that inherits all registrations from this container.
+     * Scoped containers allow for per-scope instance management, where scoped services
+     * are shared within a scope but isolated between different scopes.
+     * @returns A new scoped container instance with this container as its parent.
+     */
+    abstract createScopedContainer(): ScopedContainer;
+}
+/**
+ * Scoped container that extends the base container with the ability to override registrations.
+ */
+export type ScopedContainer = Container & {
+    /**
+     * Overrides the registration for the specified identifier with a new instance.
+     * @template T The type of the instance to override.
+     * @param id The identifier of the registration to override.
+     * @param instance The instance to use for the registration.
+     */
+    override<T>(id: Identifier<T>, instance: Instance<T>): void;
+};
+/**
+ * Factory function that creates an instance of type T using the provided container.
+ * @template T The type of instance the factory creates.
+ * @param container The container to use for resolving dependencies.
+ * @returns An instance of type T.
+ */
+export type Factory<T> = (container: Container) => T;
+/**
+ * Defines the lifetime management strategy for a registered service.
+ * - 'singleton': One instance shared across the entire container
+ * - 'transient': A new instance created every time it's requested
+ * - 'scoped': One instance per scoped container
+ */
+export type Lifetime = 'singleton' | 'transient' | 'scoped';
+/**
+ * Fluent interface for configuring registration lifetime.
+ * Allows chaining of configuration methods to set the lifetime of a registration.
+ * @template T The type being registered.
+ */
+export interface RegistrationLifeTime {
+    /**
+     * Sets the lifetime to singleton (one instance shared across the container).
+     */
+    asSingleton(): void;
+    /**
+     * Sets the lifetime to transient (new instance created each time).
+     */
+    asTransient(): void;
+    /**
+     * Sets the lifetime to scoped (one instance per scoped container).
+     */
+    asScoped(): void;
+}
+/**
+ * Fluent interface for configuring array-based registrations.
+ * Allows chaining of push() calls to add multiple implementations to an array.
+ * @template T The element type of the array being registered.
+ */
+export interface RegistrationArray<T> {
+    /**
+     * Adds an implementation identifier to the array collection.
+     * The resolved instance will be pushed to the array when the service is created.
+     * @param id The identifier of the implementation to add.
+     * @returns Registration array options for method chaining.
+     */
+    push(id: Identifier<T>): RegistrationArray<T>;
+}
+/**
+ * Fluent interface for configuring map-based registrations.
+ * Allows chaining of set() calls to add multiple implementations to a map.
+ * @template K The key type of the map being registered.
+ * @template V The value type of the map being registered.
+ */
+export interface RegistrationMap<K, V> {
+    /**
+     * Adds an implementation identifier to the map collection.
+     * The resolved instance will be stored in the map with the provided key when the service is created.
+     * @param key The key of the implementation to add.
+     * @param id The identifier of the implementation to add.
+     * @returns Registration map options for method chaining.
+     */
+    set(key: K, id: Identifier<V>): RegistrationMap<K, V>;
+}
+/**
+ * Fluent interface for specifying how a service should be created.
+ * Provides methods to register a service using a class, factory, or instance.
+ * @template T The type being registered.
+ */
+export interface RegistrationType<T> {
+    /**
+     * Registers a service using a constructor class.
+     * @param constructor The constructor function to use for creating instances.
+     * @returns Registration options for further configuration.
+     */
+    useClass(constructor: Constructor<T>): RegistrationLifeTime;
+    /**
+     * Registers a service using a factory function.
+     * @param factory The factory function that creates instances.
+     * @returns Registration options for further configuration.
+     */
+    useFactory(factory: Factory<T>): RegistrationLifeTime;
+    /**
+     * Registers a service using an existing instance.
+     * @param instance The instance to register (will be used as a singleton).
+     */
+    useInstance(instance: Instance<T>): void;
+    /**
+     * Registers a service as an array type, allowing multiple implementations to be collected.
+     * Use this when you need to register a service that extends Array and collect multiple implementations.
+     * The array will be populated with instances resolved from the identifiers added via push().
+     * @template U The array element type extracted from T.
+     * @param constructor The constructor function for the array type (must extend Array).
+     * @returns Registration array options for chaining push() calls to add implementations.
+     */
+    useArray<U extends ArrayType<T>>(constructor: Constructor<T>): RegistrationArray<U>;
+    /**
+     * Registers a service as a map type, allowing multiple implementations to be collected.
+     * Use this when you need to register a service that extends Map and collect multiple implementations.
+     * The map will be populated with instances resolved from the identifiers added via set().
+     * @template U The map element type extracted from T.
+     * @param constructor The constructor function for the map type (must extend Map).
+     * @returns Registration map options for chaining set() calls to add implementations.
+     */
+    useMap<U extends MapType<T>>(constructor: Constructor<T>): RegistrationMap<U[0], U[1]>;
+}
+/**
+ * Service registry that manages service registrations before building a container.
+ * Allows registration, removal, and checking of services, and provides a method to build a container
+ * with all registered services.
+ */
+export interface Registry {
+    /**
+     * Registers a service with the registry.
+     * @template T The type of the service to register.
+     * @param id The identifier (constructor or abstract class) for the type to register.
+     * @returns The registration type for configuring how the service should be created.
+     */
+    register<T>(id: Identifier<T>): RegistrationType<T>;
+    /**
+     * Removes a service registration from the registry.
+     * @template T The type of the service to remove.
+     * @param id The identifier (constructor or abstract class) for the type to remove.
+     */
+    remove<T>(id: Identifier<T>): void;
+    /**
+     * Checks if a service is registered with the registry.
+     * @template T The type of the service to check.
+     * @param id The identifier (constructor or abstract class) for the type to check.
+     * @returns True if the service is registered, false otherwise.
+     */
+    isRegistered<T>(id: Identifier<T>): boolean;
+    /**
+     * Builds a container from the registry.
+     * @returns A container instance.
+     */
+    build(): Container;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/dist/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../src/interfaces.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,CAAE,SAAQ,QAAQ;IAE9C,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,QAAQ;IAC3C,SAAS,EAAE,CAAC,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC;AAE1E;;GAEG;AACH,8BAAsB,SAAS;IAC7B;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC;IAErC;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,IAAI,eAAe;CAClD;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAC7D,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,KAAK,CAAC,CAAC;AAErD;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC;IAClC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;CAC/C;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,EAAE,CAAC;IACnC;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;IAE5D;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;IAEtD;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAEpF;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CACxF;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAEpD;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAEnC;;;;;OAKG;IACH,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC;IAE5C;;;OAGG;IACH,KAAK,IAAI,SAAS,CAAC;CACpB"}

package/dist/internal.d.ts

@@ -0,0 +1,31 @@
+import { Constructor, Factory, Identifier, Instance, Lifetime } from './interfaces.js';
+/**
+ * Internal representation of a service registration in the container.
+ * Contains all the information needed to resolve and create instances of the service.
+ * @template T The type being registered.
+ * @internal
+ */
+export type Registration<T> = {
+    /** Optional constructor function for class-based registration. */
+    constructor?: Constructor<T>;
+    /** Optional factory function for factory-based registration. */
+    factory?: Factory<T>;
+    /** Optional instance for instance-based registration. */
+    instance?: Instance<T>;
+    /** The lifetime management strategy for this registration. */
+    lifetime: Lifetime;
+    /**
+     * Array of all dependencies required by this registration.
+     * This is the union of ctorDependencies and collectionDependencies.
+     */
+    dependencies: Identifier<unknown>[];
+    /** Array of dependencies required by the constructor (extracted via reflection). */
+    ctorDependencies: Identifier<unknown>[];
+    /**
+     * Optional collection of dependencies for array or map registration.
+     * For arrays: Array of identifiers that will be resolved and pushed to the array.
+     * For maps: Map of key-value pairs where values are identifiers that will be resolved and stored.
+     */
+    collectionDependencies?: Array<Identifier<unknown>> | Map<unknown, Identifier<unknown>>;
+};
+//# sourceMappingURL=internal.d.ts.map

package/dist/internal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAEvF;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAC5B,kEAAkE;IAClE,WAAW,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAC7B,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,EAAE,QAAQ,CAAC;IACnB;;;OAGG;IACH,YAAY,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACpC,oFAAoF;IACpF,gBAAgB,EAAE,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;IACxC;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;CACzF,CAAC"}

package/dist/registry.d.ts

@@ -0,0 +1,56 @@
+import 'reflect-metadata';
+import { Identifier, RegistrationType, Container, Registry } from './interfaces.js';
+/**
+ * Registry implementation for managing service registrations.
+ * Allows registration of services with various creation strategies (class, factory, instance)
+ * and lifetime management (singleton, transient, scoped).
+ * Validates registrations for missing dependencies, circular dependencies, and tag conflicts
+ * before building the container.
+ */
+export declare class InjectKitRegistry implements Registry {
+    /** Internal map storing all service registrations by their identifier. */
+    private readonly registrations;
+    /**
+     * Registers a service with the registry.
+     * @template T The type of the service to register.
+     * @param id The identifier (constructor or abstract class) for the type to register.
+     * @returns The registration type for configuring how the service should be created.
+     * @throws {Error} If a registration for the given identifier already exists.
+     */
+    register<T>(id: Identifier<T>): RegistrationType<T>;
+    /**
+     * Removes a service registration from the registry.
+     * @template T The type of the service to remove.
+     * @param id The identifier (constructor or abstract class) for the type to remove.
+     * @throws {Error} If the registration for the given identifier is not found.
+     */
+    remove<T>(id: Identifier<T>): void;
+    /**
+     * Checks if a service is registered with the registry.
+     * @template T The type of the service to check.
+     * @param id The identifier (constructor or abstract class) for the type to check.
+     * @returns True if the service is registered, false otherwise.
+     */
+    isRegistered<T>(id: Identifier<T>): boolean;
+    /**
+     * Verifies that all dependencies for registered services are also registered.
+     * @param registrations Map of all registrations to verify.
+     * @throws {Error} If any service has dependencies that are not registered.
+     */
+    private static verifyRegistrations;
+    /**
+     * Verifies that there are no circular dependencies in the registration graph.
+     * Uses depth-first search to detect cycles in the dependency graph.
+     * @param registrations Map of all registrations to verify.
+     * @throws {Error} If a circular dependency is detected.
+     */
+    private static verifyNoCircularDependencies;
+    /**
+     * Builds a container from all registered services.
+     * Performs validation checks for missing dependencies and circular dependencies.
+     * @returns A configured container instance ready to resolve services.
+     * @throws {Error} If validation fails (missing dependencies, circular dependencies).
+     */
+    build(): Container;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAGL,UAAU,EAGV,gBAAgB,EAChB,SAAS,EAGT,QAAQ,EAKT,MAAM,iBAAiB,CAAC;AAIzB;;;;;;GAMG;AACH,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuE;IAErG;;;;;;OAMG;IACI,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAU1D;;;;;OAKG;IACI,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI;IAMzC;;;;;OAKG;IACI,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,OAAO;IAIlD;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAgBlC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,4BAA4B;IAyB3C;;;;;OAKG;IACI,KAAK,IAAI,SAAS;CAyB1B"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "injectkit",
+  "version": "1.0.0",
+  "description": "Lightweight, type-safe dependency injection container for TypeScript with constructor injection, factory functions, and lifetime management.",
+  "author": {
+    "name": "Marooned Software",
+    "url": "https://github.com/MaroonedSoftware/injectkit"
+  },
+  "bugs": {
+    "url": "https://github.com/MaroonedSoftware/injectkit/issues"
+  },
+  "homepage": "https://github.com/MaroonedSoftware/injectkit#readme",
+  "keywords": [
+    "dependency injection",
+    "inversion of control",
+    "service locator",
+    "dependency",
+    "injection",
+    "service",
+    "container",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MaroonedSoftware/injectkit.git"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "files": [
+    "dist/**"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "reflect-metadata": "^0.2.2"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^9.39.2",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-only-warn": "^1.1.0",
+    "globals": "^16.5.0",
+    "prettier": "^3.7.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --sourcemap --dts && tsc --emitDeclarationOnly --declaration",
+    "build:ci": "eslint --max-warnings=0 && pnpm run build",
+    "changeset": "changeset && changeset version",
+    "lint": "eslint --fix",
+    "format": "prettier --write . ",
+    "test": "vitest run",
+    "test:ci": "vitest run --coverage "
+  }
+}