@half0wl/container 1.0.0

package/dist/index.cjs

@@ -0,0 +1,266 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BaseService: () => BaseService,
+  Container: () => Container,
+  Inject: () => Inject,
+  Service: () => Service,
+  getPropertyDescriptorFromChain: () => getPropertyDescriptorFromChain,
+  wrapWithTracing: () => wrapWithTracing
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/base.ts
+var BaseService = class {
+  /** The user-defined dependencies (everything except `registry`). */
+  deps;
+  /** The container instance, used internally by {@link Inject} to resolve other services. */
+  registry;
+  constructor(dependencies) {
+    const { registry, ...rest } = dependencies;
+    this.deps = rest;
+    this.registry = registry;
+  }
+};
+
+// src/decorators.ts
+var TRACED_MARKER = /* @__PURE__ */ Symbol("__service_traced__");
+function Service(options) {
+  return (target) => {
+    if (options?.trace) {
+      target[TRACED_MARKER] = true;
+    }
+    return target;
+  };
+}
+function Inject(factory) {
+  return (_target, propertyKey) => {
+    const cacheKey = /* @__PURE__ */ Symbol(`__inject_${String(propertyKey)}`);
+    Object.defineProperty(_target, propertyKey, {
+      get() {
+        const cached = this[cacheKey];
+        if (cached !== void 0) return cached;
+        const resolved = this.registry.get(factory());
+        this[cacheKey] = resolved;
+        return resolved;
+      },
+      enumerable: true,
+      configurable: true
+    });
+  };
+}
+
+// src/helpers.ts
+function getPropertyDescriptorFromChain(proto, key, stopAt) {
+  let current = proto;
+  while (current && current !== stopAt) {
+    const desc = Object.getOwnPropertyDescriptor(current, key);
+    if (desc) return desc;
+    current = Object.getPrototypeOf(current);
+  }
+  return void 0;
+}
+function wrapWithTracing(instance, trace, stopAt) {
+  const className = instance.constructor.name;
+  const seen = /* @__PURE__ */ new Set();
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== stopAt) {
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      if (key === "constructor" || seen.has(key)) continue;
+      seen.add(key);
+      const desc = Object.getOwnPropertyDescriptor(proto, key);
+      if (!desc || !desc.value || typeof desc.value !== "function") continue;
+      const original = desc.value;
+      const spanName = `${className}.${key}`;
+      instance[key] = function(...args) {
+        return trace(spanName, () => original.apply(this, args));
+      };
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+}
+
+// src/container.ts
+var Container = class _Container {
+  static globalInstance;
+  instances = /* @__PURE__ */ new Map();
+  deps;
+  config;
+  constructor(config = {}) {
+    this.config = config;
+    this.deps = config.deps;
+  }
+  /**
+   * Create a new container instance.
+   *
+   * Accepts either a plain deps object or a {@link ContainerConfig} with
+   * additional options like `trace`.
+   * When called with no arguments, the container defers resolution
+   * until {@link setDeps} is called.
+   *
+   * @typeParam TDeps - User-defined dependency interface
+   * @param depsOrConfig - Dependencies or full configuration object
+   * @returns A new isolated container instance
+   *
+   * @example
+   * ```ts
+   * // Simple — pass deps directly
+   * const container = Container.create<ContainerDeps>({ db, logger });
+   *
+   * // With config — pass options alongside deps
+   * const container = Container.create<ContainerDeps>({
+   *   deps: { db, logger },
+   *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
+   * });
+   *
+   * // Lazy — set deps later
+   * const container = Container.create<ContainerDeps>();
+   * container.setDeps({ db, logger });
+   * ```
+   */
+  static create(depsOrConfig) {
+    if (depsOrConfig && typeof depsOrConfig === "object" && ("deps" in depsOrConfig || "trace" in depsOrConfig)) {
+      return new _Container(depsOrConfig);
+    }
+    return new _Container({
+      deps: depsOrConfig
+    });
+  }
+  /**
+   * Get the global singleton container instance.
+   *
+   * Creates one on first call. Useful for module-level exports that
+   * need a container reference before deps are available.
+   *
+   * @typeParam TDeps - User-defined dependency interface
+   * @returns The global container instance
+   */
+  static getGlobalInstance() {
+    if (!_Container.globalInstance) {
+      _Container.globalInstance = new _Container();
+    }
+    return _Container.globalInstance;
+  }
+  /**
+   * Reset the global singleton container.
+   *
+   * Clears all cached instances and removes the global reference.
+   * Primarily used for test cleanup.
+   */
+  static resetGlobal() {
+    _Container.globalInstance?.clear();
+    _Container.globalInstance = void 0;
+  }
+  /**
+   * Set or replace the dependencies after container creation.
+   *
+   * Useful for lazy initialization patterns where the container
+   * is created before deps are available.
+   *
+   * @param deps - The user-defined dependencies
+   */
+  setDeps(deps) {
+    this.deps = deps;
+  }
+  /**
+   * Resolve a service by its class constructor.
+   *
+   * On first call, lazily constructs the service with `{ ...deps, registry: this }`
+   * and caches the singleton. Subsequent calls return the cached instance.
+   *
+   * If the service was decorated with `@Service({ trace: true })`, all its methods
+   * are automatically wrapped with the configured `trace` function.
+   *
+   * @typeParam T - The service type
+   * @param serviceClass - The class constructor to resolve
+   * @returns The singleton instance
+   * @throws If deps have not been set
+   * @throws If the service has tracing enabled but no `trace` function was configured
+   */
+  get(serviceClass) {
+    const existing = this.instances.get(serviceClass);
+    if (existing) return existing;
+    if (!this.deps) {
+      throw new Error(
+        "Container deps not set. Call setDeps() or pass deps to Container.create()."
+      );
+    }
+    const serviceDeps = {
+      ...this.deps,
+      registry: this
+    };
+    const instance = new serviceClass(serviceDeps);
+    if (serviceClass[TRACED_MARKER]) {
+      if (!this.config.trace) {
+        throw new Error(
+          `Service "${serviceClass.name}" has trace enabled but no trace function was provided. Pass { trace } to Container.create().`
+        );
+      }
+      wrapWithTracing(
+        instance,
+        this.config.trace,
+        BaseService.prototype
+      );
+    }
+    this.instances.set(serviceClass, instance);
+    return instance;
+  }
+  /**
+   * Register a pre-built instance for a service class.
+   *
+   * The registered instance is returned by {@link get} without constructing.
+   * Primarily used for injecting test mocks.
+   *
+   * @typeParam T - The service type
+   * @param serviceClass - The class constructor to associate with the instance
+   * @param instance - The pre-built instance to register
+   *
+   * @example
+   * ```ts
+   * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
+   * testContainer.register(UserService, mockUserService);
+   * const auth = testContainer.get(AuthService); // uses mockUserService via @Inject
+   * ```
+   */
+  register(serviceClass, instance) {
+    this.instances.set(serviceClass, instance);
+  }
+  /**
+   * Clear all cached service instances.
+   *
+   * After calling this, the next {@link get} call for any service
+   * will construct a fresh instance. Does not clear deps or config.
+   */
+  clear() {
+    this.instances.clear();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BaseService,
+  Container,
+  Inject,
+  Service,
+  getPropertyDescriptorFromChain,
+  wrapWithTracing
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/base.ts","../src/decorators.ts","../src/helpers.ts","../src/container.ts"],"sourcesContent":["export {\n  BaseService,\n  type Constructor,\n  type ContainerConfig,\n  type IContainer,\n  type ServiceDependencies,\n  type TraceFn,\n} from \"./base.js\";\nexport { Container } from \"./container.js\";\nexport { Inject, Service, type ServiceOptions } from \"./decorators.js\";\nexport { getPropertyDescriptorFromChain, wrapWithTracing } from \"./helpers.js\";\n","/** A class constructor type. */\n// biome-ignore lint/suspicious/noExplicitAny: Constructor must accept any args to be generic over all classes\nexport type Constructor<T = unknown> = new (...args: any[]) => T;\n\n/** A pluggable tracing function signature. */\nexport type TraceFn = (spanName: string, fn: () => unknown) => unknown;\n\n/**\n * Minimal interface representing a DI container.\n *\n * Services receive this as `this.registry` to resolve other services\n * without coupling to the full {@link Container} implementation.\n */\nexport interface IContainer {\n  /**\n   * Resolve a service by its class constructor.\n   *\n   * @typeParam T - The service type\n   * @param serviceClass - The class constructor to resolve\n   * @returns The singleton instance of the service\n   */\n  get<T>(serviceClass: Constructor<T>): T;\n}\n\n/**\n * The full set of dependencies passed to a service constructor.\n *\n * Combines the user-defined `TDeps` with the container's `registry`,\n * which is injected automatically by the container.\n *\n * @typeParam TDeps - User-defined dependency interface\n */\nexport type ServiceDependencies<TDeps> = TDeps & { registry: IContainer };\n\n/**\n * Configuration object for {@link Container.create}.\n *\n * @typeParam TDeps - User-defined dependency interface\n */\nexport interface ContainerConfig<TDeps> {\n  /** The user-defined dependencies to inject into services. */\n  deps?: TDeps;\n\n  /**\n   * Optional tracing function for services decorated with `@Service({ trace: true })`.\n   * When a traced service is resolved, all its methods are wrapped with this function.\n   *\n   * @param spanName - The span name in `ClassName.methodName` format\n   * @param fn - The original method to execute within the span\n   * @returns The return value of `fn`\n   *\n   * @example\n   * ```ts\n   * const container = Container.create<ContainerDeps>({\n   *   deps: { db, logger },\n   *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),\n   * });\n   * ```\n   */\n  trace?: TraceFn;\n}\n\n/**\n * Abstract base class that all container-managed services extend.\n *\n * Receives injected dependencies via its constructor and exposes them\n * as `this.deps` (user-defined) and `this.registry` (the container).\n *\n * @typeParam TDeps - User-defined dependency interface\n *\n * @example\n * ```ts\n * interface ContainerDeps {\n *   db: DatabaseClient;\n *   logger: Logger;\n * }\n *\n * @Service()\n * class UserService extends BaseService<ContainerDeps> {\n *   findById(id: string) {\n *     return this.deps.db.users.findUnique({ where: { id } });\n *   }\n * }\n * ```\n */\nexport abstract class BaseService<TDeps = unknown> {\n  /** The user-defined dependencies (everything except `registry`). */\n  protected readonly deps: TDeps;\n\n  /** The container instance, used internally by {@link Inject} to resolve other services. */\n  protected readonly registry: IContainer;\n\n  constructor(dependencies: ServiceDependencies<TDeps>) {\n    const { registry, ...rest } = dependencies as ServiceDependencies<TDeps>;\n    this.deps = rest as unknown as TDeps;\n    this.registry = registry;\n  }\n}\n","import type { Constructor, IContainer } from \"./base.js\";\n\n/** @internal Symbol used to mark classes decorated with `@Service({ trace: true })`. */\nexport const TRACED_MARKER = Symbol(\"__service_traced__\");\n\n/**\n * Options for the {@link Service} decorator.\n */\nexport interface ServiceOptions {\n  /**\n   * When `true`, all methods on this service are automatically wrapped\n   * with the container's `trace` function after construction.\n   *\n   * Requires a `trace` function in the {@link ContainerConfig}.\n   *\n   * @defaultValue `false`\n   */\n  trace?: boolean;\n}\n\n/**\n * Class decorator that marks a class as container-managed.\n *\n * When `trace` is enabled, the container will wrap all methods\n * with tracing spans using the configured trace function.\n *\n * Requires `experimentalDecorators: true` in tsconfig.json.\n *\n * @param options - Optional configuration for the service\n * @returns A class decorator\n *\n * @example\n * ```ts\n * @Service()\n * class UserService extends BaseService<ContainerDeps> {\n *   findById(id: string) {\n *     return this.deps.db.users.findUnique({ where: { id } });\n *   }\n * }\n *\n * @Service({ trace: true })\n * class TracedService extends BaseService<ContainerDeps> {\n *   // All methods auto-traced as \"TracedService.methodName\"\n *   process() { ... }\n * }\n * ```\n */\nexport function Service(options?: ServiceOptions): ClassDecorator {\n  return (target) => {\n    if (options?.trace) {\n      (target as unknown as Record<symbol, boolean>)[TRACED_MARKER] = true;\n    }\n    return target;\n  };\n}\n\ntype InjectTarget<T> = { registry: IContainer } & Record<symbol, T>;\n\n/**\n * Property decorator for declarative inter-service dependency injection.\n *\n * Defines a lazy getter that resolves the dependency from the same container\n * on first access and caches it per-instance. Uses a factory function\n * (`() => X` instead of `X` directly) to avoid circular import issues\n * between service files.\n *\n * Requires `experimentalDecorators: true` in tsconfig.json.\n *\n * @typeParam T - The injected service type\n * @param factory - A factory function returning the service class constructor.\n *                  Called lazily on first property access.\n * @returns A property decorator\n *\n * @example\n * ```ts\n * @Service()\n * class AuthService extends BaseService<ContainerDeps> {\n *   @Inject(() => UserService)\n *   declare readonly userService: UserService;\n *\n *   @Inject(() => TokenService)\n *   declare readonly tokenService: TokenService;\n *\n *   authenticate(token: string) {\n *     const payload = this.tokenService.verify(token);\n *     return this.userService.findById(payload.userId);\n *   }\n * }\n * ```\n */\nexport function Inject<T>(factory: () => Constructor<T>) {\n  return (_target: object, propertyKey: string | symbol): void => {\n    const cacheKey = Symbol(`__inject_${String(propertyKey)}`);\n\n    Object.defineProperty(_target, propertyKey, {\n      get(this: InjectTarget<T>) {\n        const cached = this[cacheKey];\n        if (cached !== undefined) return cached;\n        const resolved = this.registry.get(factory());\n        this[cacheKey] = resolved;\n        return resolved;\n      },\n      enumerable: true,\n      configurable: true,\n    });\n  };\n}\n","import type { TraceFn } from \"./base.js\";\n\n/**\n * Walk the prototype chain from `proto` up to (but not including) `stopAt`,\n * looking for a property descriptor with the given key.\n *\n * @param proto - The prototype to start searching from\n * @param key - The property name to look for\n * @param stopAt - The prototype to stop at (exclusive)\n * @returns The property descriptor if found, or `undefined`\n */\nexport function getPropertyDescriptorFromChain(\n  proto: object,\n  key: string,\n  stopAt: object,\n): PropertyDescriptor | undefined {\n  let current: object | null = proto;\n  while (current && current !== stopAt) {\n    const desc = Object.getOwnPropertyDescriptor(current, key);\n    if (desc) return desc;\n    current = Object.getPrototypeOf(current);\n  }\n  return undefined;\n}\n\n/**\n * Wrap all methods on an instance with a tracing function.\n *\n * Walks the prototype chain from the instance up to `stopAt`, wrapping\n * every method (functions with a `value` descriptor) with the `trace` callback.\n * Getters, setters, and the constructor are skipped. When a method exists on\n * multiple prototypes in the chain, the closest (most derived) version wins.\n *\n * Span names follow the `ClassName.methodName` format.\n *\n * @param instance - The object instance whose methods will be wrapped\n * @param trace - The tracing function that wraps each method call\n * @param stopAt - The prototype to stop walking at (typically `BaseService.prototype`)\n *\n * @example\n * ```ts\n * wrapWithTracing(instance, (spanName, fn) => {\n *   console.log(`>> ${spanName}`);\n *   const result = fn();\n *   console.log(`<< ${spanName}`);\n *   return result;\n * }, BaseService.prototype);\n * ```\n */\nexport function wrapWithTracing(\n  instance: object,\n  trace: TraceFn,\n  stopAt: object,\n): void {\n  const className = instance.constructor.name;\n  const seen = new Set<string>();\n  let proto: object | null = Object.getPrototypeOf(instance);\n\n  while (proto && proto !== stopAt) {\n    for (const key of Object.getOwnPropertyNames(proto)) {\n      if (key === \"constructor\" || seen.has(key)) continue;\n      seen.add(key);\n\n      const desc = Object.getOwnPropertyDescriptor(proto, key);\n      if (!desc || !desc.value || typeof desc.value !== \"function\") continue;\n\n      const original = desc.value as (...args: unknown[]) => unknown;\n      const spanName = `${className}.${key}`;\n\n      (instance as Record<string, unknown>)[key] = function (\n        this: unknown,\n        ...args: unknown[]\n      ) {\n        return trace(spanName, () => original.apply(this, args));\n      };\n    }\n    proto = Object.getPrototypeOf(proto);\n  }\n}\n","import {\n  BaseService,\n  type Constructor,\n  type ContainerConfig,\n  type IContainer,\n  type ServiceDependencies,\n} from \"./base.js\";\nimport { TRACED_MARKER } from \"./decorators.js\";\nimport { wrapWithTracing } from \"./helpers.js\";\n\n/**\n * A dependency injection container that lazily creates and caches singleton service instances.\n *\n * Supports both a global singleton (via {@link Container.getGlobalInstance}) and\n * isolated instances (via {@link Container.create}) for test environments.\n *\n * @typeParam TDeps - User-defined dependency interface\n *\n * @example\n * ```ts\n * // Production usage\n * const container = Container.create<ContainerDeps>({ db, logger });\n * const auth = container.get(AuthService);\n *\n * // Test usage (isolated)\n * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });\n * testContainer.register(UserService, mockUserService);\n * const auth = testContainer.get(AuthService);\n * ```\n */\nexport class Container<TDeps = unknown> implements IContainer {\n  private static globalInstance: Container<unknown> | undefined;\n\n  private instances = new Map<Constructor, unknown>();\n  private deps: TDeps | undefined;\n  private config: ContainerConfig<TDeps>;\n\n  private constructor(config: ContainerConfig<TDeps> = {}) {\n    this.config = config;\n    this.deps = config.deps;\n  }\n\n  /**\n   * Create a new container instance.\n   *\n   * Accepts either a plain deps object or a {@link ContainerConfig} with\n   * additional options like `trace`.\n   * When called with no arguments, the container defers resolution\n   * until {@link setDeps} is called.\n   *\n   * @typeParam TDeps - User-defined dependency interface\n   * @param depsOrConfig - Dependencies or full configuration object\n   * @returns A new isolated container instance\n   *\n   * @example\n   * ```ts\n   * // Simple — pass deps directly\n   * const container = Container.create<ContainerDeps>({ db, logger });\n   *\n   * // With config — pass options alongside deps\n   * const container = Container.create<ContainerDeps>({\n   *   deps: { db, logger },\n   *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),\n   * });\n   *\n   * // Lazy — set deps later\n   * const container = Container.create<ContainerDeps>();\n   * container.setDeps({ db, logger });\n   * ```\n   */\n  static create<TDeps>(\n    depsOrConfig?: TDeps | ContainerConfig<TDeps>,\n  ): Container<TDeps> {\n    if (\n      depsOrConfig &&\n      typeof depsOrConfig === \"object\" &&\n      (\"deps\" in depsOrConfig || \"trace\" in depsOrConfig)\n    ) {\n      return new Container<TDeps>(depsOrConfig as ContainerConfig<TDeps>);\n    }\n    return new Container<TDeps>({\n      deps: depsOrConfig as TDeps | undefined,\n    });\n  }\n\n  /**\n   * Get the global singleton container instance.\n   *\n   * Creates one on first call. Useful for module-level exports that\n   * need a container reference before deps are available.\n   *\n   * @typeParam TDeps - User-defined dependency interface\n   * @returns The global container instance\n   */\n  static getGlobalInstance<TDeps>(): Container<TDeps> {\n    if (!Container.globalInstance) {\n      Container.globalInstance = new Container<TDeps>();\n    }\n    return Container.globalInstance as Container<TDeps>;\n  }\n\n  /**\n   * Reset the global singleton container.\n   *\n   * Clears all cached instances and removes the global reference.\n   * Primarily used for test cleanup.\n   */\n  static resetGlobal(): void {\n    Container.globalInstance?.clear();\n    Container.globalInstance = undefined;\n  }\n\n  /**\n   * Set or replace the dependencies after container creation.\n   *\n   * Useful for lazy initialization patterns where the container\n   * is created before deps are available.\n   *\n   * @param deps - The user-defined dependencies\n   */\n  setDeps(deps: TDeps): void {\n    this.deps = deps;\n  }\n\n  /**\n   * Resolve a service by its class constructor.\n   *\n   * On first call, lazily constructs the service with `{ ...deps, registry: this }`\n   * and caches the singleton. Subsequent calls return the cached instance.\n   *\n   * If the service was decorated with `@Service({ trace: true })`, all its methods\n   * are automatically wrapped with the configured `trace` function.\n   *\n   * @typeParam T - The service type\n   * @param serviceClass - The class constructor to resolve\n   * @returns The singleton instance\n   * @throws If deps have not been set\n   * @throws If the service has tracing enabled but no `trace` function was configured\n   */\n  get<T>(serviceClass: Constructor<T>): T {\n    const existing = this.instances.get(serviceClass);\n    if (existing) return existing as T;\n\n    if (!this.deps) {\n      throw new Error(\n        \"Container deps not set. Call setDeps() or pass deps to Container.create().\",\n      );\n    }\n\n    const serviceDeps: ServiceDependencies<TDeps> = {\n      ...this.deps,\n      registry: this,\n    };\n\n    const instance = new serviceClass(serviceDeps);\n\n    // Apply tracing if @Service({ trace: true }) was used\n    if ((serviceClass as unknown as Record<symbol, unknown>)[TRACED_MARKER]) {\n      if (!this.config.trace) {\n        throw new Error(\n          `Service \"${serviceClass.name}\" has trace enabled but no trace function was provided. Pass { trace } to Container.create().`,\n        );\n      }\n      wrapWithTracing(\n        instance as object,\n        this.config.trace,\n        BaseService.prototype,\n      );\n    }\n\n    this.instances.set(serviceClass, instance);\n    return instance;\n  }\n\n  /**\n   * Register a pre-built instance for a service class.\n   *\n   * The registered instance is returned by {@link get} without constructing.\n   * Primarily used for injecting test mocks.\n   *\n   * @typeParam T - The service type\n   * @param serviceClass - The class constructor to associate with the instance\n   * @param instance - The pre-built instance to register\n   *\n   * @example\n   * ```ts\n   * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });\n   * testContainer.register(UserService, mockUserService);\n   * const auth = testContainer.get(AuthService); // uses mockUserService via @Inject\n   * ```\n   */\n  register<T>(serviceClass: Constructor<T>, instance: T): void {\n    this.instances.set(serviceClass, instance);\n  }\n\n  /**\n   * Clear all cached service instances.\n   *\n   * After calling this, the next {@link get} call for any service\n   * will construct a fresh instance. Does not clear deps or config.\n   */\n  clear(): void {\n    this.instances.clear();\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,325 @@
+/** A class constructor type. */
+type Constructor<T = unknown> = new (...args: any[]) => T;
+/** A pluggable tracing function signature. */
+type TraceFn = (spanName: string, fn: () => unknown) => unknown;
+/**
+ * Minimal interface representing a DI container.
+ *
+ * Services receive this as `this.registry` to resolve other services
+ * without coupling to the full {@link Container} implementation.
+ */
+interface IContainer {
+    /**
+     * Resolve a service by its class constructor.
+     *
+     * @typeParam T - The service type
+     * @param serviceClass - The class constructor to resolve
+     * @returns The singleton instance of the service
+     */
+    get<T>(serviceClass: Constructor<T>): T;
+}
+/**
+ * The full set of dependencies passed to a service constructor.
+ *
+ * Combines the user-defined `TDeps` with the container's `registry`,
+ * which is injected automatically by the container.
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ */
+type ServiceDependencies<TDeps> = TDeps & {
+    registry: IContainer;
+};
+/**
+ * Configuration object for {@link Container.create}.
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ */
+interface ContainerConfig<TDeps> {
+    /** The user-defined dependencies to inject into services. */
+    deps?: TDeps;
+    /**
+     * Optional tracing function for services decorated with `@Service({ trace: true })`.
+     * When a traced service is resolved, all its methods are wrapped with this function.
+     *
+     * @param spanName - The span name in `ClassName.methodName` format
+     * @param fn - The original method to execute within the span
+     * @returns The return value of `fn`
+     *
+     * @example
+     * ```ts
+     * const container = Container.create<ContainerDeps>({
+     *   deps: { db, logger },
+     *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
+     * });
+     * ```
+     */
+    trace?: TraceFn;
+}
+/**
+ * Abstract base class that all container-managed services extend.
+ *
+ * Receives injected dependencies via its constructor and exposes them
+ * as `this.deps` (user-defined) and `this.registry` (the container).
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ *
+ * @example
+ * ```ts
+ * interface ContainerDeps {
+ *   db: DatabaseClient;
+ *   logger: Logger;
+ * }
+ *
+ * @Service()
+ * class UserService extends BaseService<ContainerDeps> {
+ *   findById(id: string) {
+ *     return this.deps.db.users.findUnique({ where: { id } });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseService<TDeps = unknown> {
+    /** The user-defined dependencies (everything except `registry`). */
+    protected readonly deps: TDeps;
+    /** The container instance, used internally by {@link Inject} to resolve other services. */
+    protected readonly registry: IContainer;
+    constructor(dependencies: ServiceDependencies<TDeps>);
+}
+
+/**
+ * A dependency injection container that lazily creates and caches singleton service instances.
+ *
+ * Supports both a global singleton (via {@link Container.getGlobalInstance}) and
+ * isolated instances (via {@link Container.create}) for test environments.
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ *
+ * @example
+ * ```ts
+ * // Production usage
+ * const container = Container.create<ContainerDeps>({ db, logger });
+ * const auth = container.get(AuthService);
+ *
+ * // Test usage (isolated)
+ * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
+ * testContainer.register(UserService, mockUserService);
+ * const auth = testContainer.get(AuthService);
+ * ```
+ */
+declare class Container<TDeps = unknown> implements IContainer {
+    private static globalInstance;
+    private instances;
+    private deps;
+    private config;
+    private constructor();
+    /**
+     * Create a new container instance.
+     *
+     * Accepts either a plain deps object or a {@link ContainerConfig} with
+     * additional options like `trace`.
+     * When called with no arguments, the container defers resolution
+     * until {@link setDeps} is called.
+     *
+     * @typeParam TDeps - User-defined dependency interface
+     * @param depsOrConfig - Dependencies or full configuration object
+     * @returns A new isolated container instance
+     *
+     * @example
+     * ```ts
+     * // Simple — pass deps directly
+     * const container = Container.create<ContainerDeps>({ db, logger });
+     *
+     * // With config — pass options alongside deps
+     * const container = Container.create<ContainerDeps>({
+     *   deps: { db, logger },
+     *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
+     * });
+     *
+     * // Lazy — set deps later
+     * const container = Container.create<ContainerDeps>();
+     * container.setDeps({ db, logger });
+     * ```
+     */
+    static create<TDeps>(depsOrConfig?: TDeps | ContainerConfig<TDeps>): Container<TDeps>;
+    /**
+     * Get the global singleton container instance.
+     *
+     * Creates one on first call. Useful for module-level exports that
+     * need a container reference before deps are available.
+     *
+     * @typeParam TDeps - User-defined dependency interface
+     * @returns The global container instance
+     */
+    static getGlobalInstance<TDeps>(): Container<TDeps>;
+    /**
+     * Reset the global singleton container.
+     *
+     * Clears all cached instances and removes the global reference.
+     * Primarily used for test cleanup.
+     */
+    static resetGlobal(): void;
+    /**
+     * Set or replace the dependencies after container creation.
+     *
+     * Useful for lazy initialization patterns where the container
+     * is created before deps are available.
+     *
+     * @param deps - The user-defined dependencies
+     */
+    setDeps(deps: TDeps): void;
+    /**
+     * Resolve a service by its class constructor.
+     *
+     * On first call, lazily constructs the service with `{ ...deps, registry: this }`
+     * and caches the singleton. Subsequent calls return the cached instance.
+     *
+     * If the service was decorated with `@Service({ trace: true })`, all its methods
+     * are automatically wrapped with the configured `trace` function.
+     *
+     * @typeParam T - The service type
+     * @param serviceClass - The class constructor to resolve
+     * @returns The singleton instance
+     * @throws If deps have not been set
+     * @throws If the service has tracing enabled but no `trace` function was configured
+     */
+    get<T>(serviceClass: Constructor<T>): T;
+    /**
+     * Register a pre-built instance for a service class.
+     *
+     * The registered instance is returned by {@link get} without constructing.
+     * Primarily used for injecting test mocks.
+     *
+     * @typeParam T - The service type
+     * @param serviceClass - The class constructor to associate with the instance
+     * @param instance - The pre-built instance to register
+     *
+     * @example
+     * ```ts
+     * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
+     * testContainer.register(UserService, mockUserService);
+     * const auth = testContainer.get(AuthService); // uses mockUserService via @Inject
+     * ```
+     */
+    register<T>(serviceClass: Constructor<T>, instance: T): void;
+    /**
+     * Clear all cached service instances.
+     *
+     * After calling this, the next {@link get} call for any service
+     * will construct a fresh instance. Does not clear deps or config.
+     */
+    clear(): void;
+}
+
+/**
+ * Options for the {@link Service} decorator.
+ */
+interface ServiceOptions {
+    /**
+     * When `true`, all methods on this service are automatically wrapped
+     * with the container's `trace` function after construction.
+     *
+     * Requires a `trace` function in the {@link ContainerConfig}.
+     *
+     * @defaultValue `false`
+     */
+    trace?: boolean;
+}
+/**
+ * Class decorator that marks a class as container-managed.
+ *
+ * When `trace` is enabled, the container will wrap all methods
+ * with tracing spans using the configured trace function.
+ *
+ * Requires `experimentalDecorators: true` in tsconfig.json.
+ *
+ * @param options - Optional configuration for the service
+ * @returns A class decorator
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class UserService extends BaseService<ContainerDeps> {
+ *   findById(id: string) {
+ *     return this.deps.db.users.findUnique({ where: { id } });
+ *   }
+ * }
+ *
+ * @Service({ trace: true })
+ * class TracedService extends BaseService<ContainerDeps> {
+ *   // All methods auto-traced as "TracedService.methodName"
+ *   process() { ... }
+ * }
+ * ```
+ */
+declare function Service(options?: ServiceOptions): ClassDecorator;
+/**
+ * Property decorator for declarative inter-service dependency injection.
+ *
+ * Defines a lazy getter that resolves the dependency from the same container
+ * on first access and caches it per-instance. Uses a factory function
+ * (`() => X` instead of `X` directly) to avoid circular import issues
+ * between service files.
+ *
+ * Requires `experimentalDecorators: true` in tsconfig.json.
+ *
+ * @typeParam T - The injected service type
+ * @param factory - A factory function returning the service class constructor.
+ *                  Called lazily on first property access.
+ * @returns A property decorator
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class AuthService extends BaseService<ContainerDeps> {
+ *   @Inject(() => UserService)
+ *   declare readonly userService: UserService;
+ *
+ *   @Inject(() => TokenService)
+ *   declare readonly tokenService: TokenService;
+ *
+ *   authenticate(token: string) {
+ *     const payload = this.tokenService.verify(token);
+ *     return this.userService.findById(payload.userId);
+ *   }
+ * }
+ * ```
+ */
+declare function Inject<T>(factory: () => Constructor<T>): (_target: object, propertyKey: string | symbol) => void;
+
+/**
+ * Walk the prototype chain from `proto` up to (but not including) `stopAt`,
+ * looking for a property descriptor with the given key.
+ *
+ * @param proto - The prototype to start searching from
+ * @param key - The property name to look for
+ * @param stopAt - The prototype to stop at (exclusive)
+ * @returns The property descriptor if found, or `undefined`
+ */
+declare function getPropertyDescriptorFromChain(proto: object, key: string, stopAt: object): PropertyDescriptor | undefined;
+/**
+ * Wrap all methods on an instance with a tracing function.
+ *
+ * Walks the prototype chain from the instance up to `stopAt`, wrapping
+ * every method (functions with a `value` descriptor) with the `trace` callback.
+ * Getters, setters, and the constructor are skipped. When a method exists on
+ * multiple prototypes in the chain, the closest (most derived) version wins.
+ *
+ * Span names follow the `ClassName.methodName` format.
+ *
+ * @param instance - The object instance whose methods will be wrapped
+ * @param trace - The tracing function that wraps each method call
+ * @param stopAt - The prototype to stop walking at (typically `BaseService.prototype`)
+ *
+ * @example
+ * ```ts
+ * wrapWithTracing(instance, (spanName, fn) => {
+ *   console.log(`>> ${spanName}`);
+ *   const result = fn();
+ *   console.log(`<< ${spanName}`);
+ *   return result;
+ * }, BaseService.prototype);
+ * ```
+ */
+declare function wrapWithTracing(instance: object, trace: TraceFn, stopAt: object): void;
+
+export { BaseService, type Constructor, Container, type ContainerConfig, type IContainer, Inject, Service, type ServiceDependencies, type ServiceOptions, type TraceFn, getPropertyDescriptorFromChain, wrapWithTracing };

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+/** A class constructor type. */
+type Constructor<T = unknown> = new (...args: any[]) => T;
+/** A pluggable tracing function signature. */
+type TraceFn = (spanName: string, fn: () => unknown) => unknown;
+/**
+ * Minimal interface representing a DI container.
+ *
+ * Services receive this as `this.registry` to resolve other services
+ * without coupling to the full {@link Container} implementation.
+ */
+interface IContainer {
+    /**
+     * Resolve a service by its class constructor.
+     *
+     * @typeParam T - The service type
+     * @param serviceClass - The class constructor to resolve
+     * @returns The singleton instance of the service
+     */
+    get<T>(serviceClass: Constructor<T>): T;
+}
+/**
+ * The full set of dependencies passed to a service constructor.
+ *
+ * Combines the user-defined `TDeps` with the container's `registry`,
+ * which is injected automatically by the container.
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ */
+type ServiceDependencies<TDeps> = TDeps & {
+    registry: IContainer;
+};
+/**
+ * Configuration object for {@link Container.create}.
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ */
+interface ContainerConfig<TDeps> {
+    /** The user-defined dependencies to inject into services. */
+    deps?: TDeps;
+    /**
+     * Optional tracing function for services decorated with `@Service({ trace: true })`.
+     * When a traced service is resolved, all its methods are wrapped with this function.
+     *
+     * @param spanName - The span name in `ClassName.methodName` format
+     * @param fn - The original method to execute within the span
+     * @returns The return value of `fn`
+     *
+     * @example
+     * ```ts
+     * const container = Container.create<ContainerDeps>({
+     *   deps: { db, logger },
+     *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
+     * });
+     * ```
+     */
+    trace?: TraceFn;
+}
+/**
+ * Abstract base class that all container-managed services extend.
+ *
+ * Receives injected dependencies via its constructor and exposes them
+ * as `this.deps` (user-defined) and `this.registry` (the container).
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ *
+ * @example
+ * ```ts
+ * interface ContainerDeps {
+ *   db: DatabaseClient;
+ *   logger: Logger;
+ * }
+ *
+ * @Service()
+ * class UserService extends BaseService<ContainerDeps> {
+ *   findById(id: string) {
+ *     return this.deps.db.users.findUnique({ where: { id } });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class BaseService<TDeps = unknown> {
+    /** The user-defined dependencies (everything except `registry`). */
+    protected readonly deps: TDeps;
+    /** The container instance, used internally by {@link Inject} to resolve other services. */
+    protected readonly registry: IContainer;
+    constructor(dependencies: ServiceDependencies<TDeps>);
+}
+
+/**
+ * A dependency injection container that lazily creates and caches singleton service instances.
+ *
+ * Supports both a global singleton (via {@link Container.getGlobalInstance}) and
+ * isolated instances (via {@link Container.create}) for test environments.
+ *
+ * @typeParam TDeps - User-defined dependency interface
+ *
+ * @example
+ * ```ts
+ * // Production usage
+ * const container = Container.create<ContainerDeps>({ db, logger });
+ * const auth = container.get(AuthService);
+ *
+ * // Test usage (isolated)
+ * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
+ * testContainer.register(UserService, mockUserService);
+ * const auth = testContainer.get(AuthService);
+ * ```
+ */
+declare class Container<TDeps = unknown> implements IContainer {
+    private static globalInstance;
+    private instances;
+    private deps;
+    private config;
+    private constructor();
+    /**
+     * Create a new container instance.
+     *
+     * Accepts either a plain deps object or a {@link ContainerConfig} with
+     * additional options like `trace`.
+     * When called with no arguments, the container defers resolution
+     * until {@link setDeps} is called.
+     *
+     * @typeParam TDeps - User-defined dependency interface
+     * @param depsOrConfig - Dependencies or full configuration object
+     * @returns A new isolated container instance
+     *
+     * @example
+     * ```ts
+     * // Simple — pass deps directly
+     * const container = Container.create<ContainerDeps>({ db, logger });
+     *
+     * // With config — pass options alongside deps
+     * const container = Container.create<ContainerDeps>({
+     *   deps: { db, logger },
+     *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
+     * });
+     *
+     * // Lazy — set deps later
+     * const container = Container.create<ContainerDeps>();
+     * container.setDeps({ db, logger });
+     * ```
+     */
+    static create<TDeps>(depsOrConfig?: TDeps | ContainerConfig<TDeps>): Container<TDeps>;
+    /**
+     * Get the global singleton container instance.
+     *
+     * Creates one on first call. Useful for module-level exports that
+     * need a container reference before deps are available.
+     *
+     * @typeParam TDeps - User-defined dependency interface
+     * @returns The global container instance
+     */
+    static getGlobalInstance<TDeps>(): Container<TDeps>;
+    /**
+     * Reset the global singleton container.
+     *
+     * Clears all cached instances and removes the global reference.
+     * Primarily used for test cleanup.
+     */
+    static resetGlobal(): void;
+    /**
+     * Set or replace the dependencies after container creation.
+     *
+     * Useful for lazy initialization patterns where the container
+     * is created before deps are available.
+     *
+     * @param deps - The user-defined dependencies
+     */
+    setDeps(deps: TDeps): void;
+    /**
+     * Resolve a service by its class constructor.
+     *
+     * On first call, lazily constructs the service with `{ ...deps, registry: this }`
+     * and caches the singleton. Subsequent calls return the cached instance.
+     *
+     * If the service was decorated with `@Service({ trace: true })`, all its methods
+     * are automatically wrapped with the configured `trace` function.
+     *
+     * @typeParam T - The service type
+     * @param serviceClass - The class constructor to resolve
+     * @returns The singleton instance
+     * @throws If deps have not been set
+     * @throws If the service has tracing enabled but no `trace` function was configured
+     */
+    get<T>(serviceClass: Constructor<T>): T;
+    /**
+     * Register a pre-built instance for a service class.
+     *
+     * The registered instance is returned by {@link get} without constructing.
+     * Primarily used for injecting test mocks.
+     *
+     * @typeParam T - The service type
+     * @param serviceClass - The class constructor to associate with the instance
+     * @param instance - The pre-built instance to register
+     *
+     * @example
+     * ```ts
+     * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
+     * testContainer.register(UserService, mockUserService);
+     * const auth = testContainer.get(AuthService); // uses mockUserService via @Inject
+     * ```
+     */
+    register<T>(serviceClass: Constructor<T>, instance: T): void;
+    /**
+     * Clear all cached service instances.
+     *
+     * After calling this, the next {@link get} call for any service
+     * will construct a fresh instance. Does not clear deps or config.
+     */
+    clear(): void;
+}
+
+/**
+ * Options for the {@link Service} decorator.
+ */
+interface ServiceOptions {
+    /**
+     * When `true`, all methods on this service are automatically wrapped
+     * with the container's `trace` function after construction.
+     *
+     * Requires a `trace` function in the {@link ContainerConfig}.
+     *
+     * @defaultValue `false`
+     */
+    trace?: boolean;
+}
+/**
+ * Class decorator that marks a class as container-managed.
+ *
+ * When `trace` is enabled, the container will wrap all methods
+ * with tracing spans using the configured trace function.
+ *
+ * Requires `experimentalDecorators: true` in tsconfig.json.
+ *
+ * @param options - Optional configuration for the service
+ * @returns A class decorator
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class UserService extends BaseService<ContainerDeps> {
+ *   findById(id: string) {
+ *     return this.deps.db.users.findUnique({ where: { id } });
+ *   }
+ * }
+ *
+ * @Service({ trace: true })
+ * class TracedService extends BaseService<ContainerDeps> {
+ *   // All methods auto-traced as "TracedService.methodName"
+ *   process() { ... }
+ * }
+ * ```
+ */
+declare function Service(options?: ServiceOptions): ClassDecorator;
+/**
+ * Property decorator for declarative inter-service dependency injection.
+ *
+ * Defines a lazy getter that resolves the dependency from the same container
+ * on first access and caches it per-instance. Uses a factory function
+ * (`() => X` instead of `X` directly) to avoid circular import issues
+ * between service files.
+ *
+ * Requires `experimentalDecorators: true` in tsconfig.json.
+ *
+ * @typeParam T - The injected service type
+ * @param factory - A factory function returning the service class constructor.
+ *                  Called lazily on first property access.
+ * @returns A property decorator
+ *
+ * @example
+ * ```ts
+ * @Service()
+ * class AuthService extends BaseService<ContainerDeps> {
+ *   @Inject(() => UserService)
+ *   declare readonly userService: UserService;
+ *
+ *   @Inject(() => TokenService)
+ *   declare readonly tokenService: TokenService;
+ *
+ *   authenticate(token: string) {
+ *     const payload = this.tokenService.verify(token);
+ *     return this.userService.findById(payload.userId);
+ *   }
+ * }
+ * ```
+ */
+declare function Inject<T>(factory: () => Constructor<T>): (_target: object, propertyKey: string | symbol) => void;
+
+/**
+ * Walk the prototype chain from `proto` up to (but not including) `stopAt`,
+ * looking for a property descriptor with the given key.
+ *
+ * @param proto - The prototype to start searching from
+ * @param key - The property name to look for
+ * @param stopAt - The prototype to stop at (exclusive)
+ * @returns The property descriptor if found, or `undefined`
+ */
+declare function getPropertyDescriptorFromChain(proto: object, key: string, stopAt: object): PropertyDescriptor | undefined;
+/**
+ * Wrap all methods on an instance with a tracing function.
+ *
+ * Walks the prototype chain from the instance up to `stopAt`, wrapping
+ * every method (functions with a `value` descriptor) with the `trace` callback.
+ * Getters, setters, and the constructor are skipped. When a method exists on
+ * multiple prototypes in the chain, the closest (most derived) version wins.
+ *
+ * Span names follow the `ClassName.methodName` format.
+ *
+ * @param instance - The object instance whose methods will be wrapped
+ * @param trace - The tracing function that wraps each method call
+ * @param stopAt - The prototype to stop walking at (typically `BaseService.prototype`)
+ *
+ * @example
+ * ```ts
+ * wrapWithTracing(instance, (spanName, fn) => {
+ *   console.log(`>> ${spanName}`);
+ *   const result = fn();
+ *   console.log(`<< ${spanName}`);
+ *   return result;
+ * }, BaseService.prototype);
+ * ```
+ */
+declare function wrapWithTracing(instance: object, trace: TraceFn, stopAt: object): void;
+
+export { BaseService, type Constructor, Container, type ContainerConfig, type IContainer, Inject, Service, type ServiceDependencies, type ServiceOptions, type TraceFn, getPropertyDescriptorFromChain, wrapWithTracing };

package/dist/index.js

@@ -0,0 +1,234 @@
+// src/base.ts
+var BaseService = class {
+  /** The user-defined dependencies (everything except `registry`). */
+  deps;
+  /** The container instance, used internally by {@link Inject} to resolve other services. */
+  registry;
+  constructor(dependencies) {
+    const { registry, ...rest } = dependencies;
+    this.deps = rest;
+    this.registry = registry;
+  }
+};
+
+// src/decorators.ts
+var TRACED_MARKER = /* @__PURE__ */ Symbol("__service_traced__");
+function Service(options) {
+  return (target) => {
+    if (options?.trace) {
+      target[TRACED_MARKER] = true;
+    }
+    return target;
+  };
+}
+function Inject(factory) {
+  return (_target, propertyKey) => {
+    const cacheKey = /* @__PURE__ */ Symbol(`__inject_${String(propertyKey)}`);
+    Object.defineProperty(_target, propertyKey, {
+      get() {
+        const cached = this[cacheKey];
+        if (cached !== void 0) return cached;
+        const resolved = this.registry.get(factory());
+        this[cacheKey] = resolved;
+        return resolved;
+      },
+      enumerable: true,
+      configurable: true
+    });
+  };
+}
+
+// src/helpers.ts
+function getPropertyDescriptorFromChain(proto, key, stopAt) {
+  let current = proto;
+  while (current && current !== stopAt) {
+    const desc = Object.getOwnPropertyDescriptor(current, key);
+    if (desc) return desc;
+    current = Object.getPrototypeOf(current);
+  }
+  return void 0;
+}
+function wrapWithTracing(instance, trace, stopAt) {
+  const className = instance.constructor.name;
+  const seen = /* @__PURE__ */ new Set();
+  let proto = Object.getPrototypeOf(instance);
+  while (proto && proto !== stopAt) {
+    for (const key of Object.getOwnPropertyNames(proto)) {
+      if (key === "constructor" || seen.has(key)) continue;
+      seen.add(key);
+      const desc = Object.getOwnPropertyDescriptor(proto, key);
+      if (!desc || !desc.value || typeof desc.value !== "function") continue;
+      const original = desc.value;
+      const spanName = `${className}.${key}`;
+      instance[key] = function(...args) {
+        return trace(spanName, () => original.apply(this, args));
+      };
+    }
+    proto = Object.getPrototypeOf(proto);
+  }
+}
+
+// src/container.ts
+var Container = class _Container {
+  static globalInstance;
+  instances = /* @__PURE__ */ new Map();
+  deps;
+  config;
+  constructor(config = {}) {
+    this.config = config;
+    this.deps = config.deps;
+  }
+  /**
+   * Create a new container instance.
+   *
+   * Accepts either a plain deps object or a {@link ContainerConfig} with
+   * additional options like `trace`.
+   * When called with no arguments, the container defers resolution
+   * until {@link setDeps} is called.
+   *
+   * @typeParam TDeps - User-defined dependency interface
+   * @param depsOrConfig - Dependencies or full configuration object
+   * @returns A new isolated container instance
+   *
+   * @example
+   * ```ts
+   * // Simple — pass deps directly
+   * const container = Container.create<ContainerDeps>({ db, logger });
+   *
+   * // With config — pass options alongside deps
+   * const container = Container.create<ContainerDeps>({
+   *   deps: { db, logger },
+   *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),
+   * });
+   *
+   * // Lazy — set deps later
+   * const container = Container.create<ContainerDeps>();
+   * container.setDeps({ db, logger });
+   * ```
+   */
+  static create(depsOrConfig) {
+    if (depsOrConfig && typeof depsOrConfig === "object" && ("deps" in depsOrConfig || "trace" in depsOrConfig)) {
+      return new _Container(depsOrConfig);
+    }
+    return new _Container({
+      deps: depsOrConfig
+    });
+  }
+  /**
+   * Get the global singleton container instance.
+   *
+   * Creates one on first call. Useful for module-level exports that
+   * need a container reference before deps are available.
+   *
+   * @typeParam TDeps - User-defined dependency interface
+   * @returns The global container instance
+   */
+  static getGlobalInstance() {
+    if (!_Container.globalInstance) {
+      _Container.globalInstance = new _Container();
+    }
+    return _Container.globalInstance;
+  }
+  /**
+   * Reset the global singleton container.
+   *
+   * Clears all cached instances and removes the global reference.
+   * Primarily used for test cleanup.
+   */
+  static resetGlobal() {
+    _Container.globalInstance?.clear();
+    _Container.globalInstance = void 0;
+  }
+  /**
+   * Set or replace the dependencies after container creation.
+   *
+   * Useful for lazy initialization patterns where the container
+   * is created before deps are available.
+   *
+   * @param deps - The user-defined dependencies
+   */
+  setDeps(deps) {
+    this.deps = deps;
+  }
+  /**
+   * Resolve a service by its class constructor.
+   *
+   * On first call, lazily constructs the service with `{ ...deps, registry: this }`
+   * and caches the singleton. Subsequent calls return the cached instance.
+   *
+   * If the service was decorated with `@Service({ trace: true })`, all its methods
+   * are automatically wrapped with the configured `trace` function.
+   *
+   * @typeParam T - The service type
+   * @param serviceClass - The class constructor to resolve
+   * @returns The singleton instance
+   * @throws If deps have not been set
+   * @throws If the service has tracing enabled but no `trace` function was configured
+   */
+  get(serviceClass) {
+    const existing = this.instances.get(serviceClass);
+    if (existing) return existing;
+    if (!this.deps) {
+      throw new Error(
+        "Container deps not set. Call setDeps() or pass deps to Container.create()."
+      );
+    }
+    const serviceDeps = {
+      ...this.deps,
+      registry: this
+    };
+    const instance = new serviceClass(serviceDeps);
+    if (serviceClass[TRACED_MARKER]) {
+      if (!this.config.trace) {
+        throw new Error(
+          `Service "${serviceClass.name}" has trace enabled but no trace function was provided. Pass { trace } to Container.create().`
+        );
+      }
+      wrapWithTracing(
+        instance,
+        this.config.trace,
+        BaseService.prototype
+      );
+    }
+    this.instances.set(serviceClass, instance);
+    return instance;
+  }
+  /**
+   * Register a pre-built instance for a service class.
+   *
+   * The registered instance is returned by {@link get} without constructing.
+   * Primarily used for injecting test mocks.
+   *
+   * @typeParam T - The service type
+   * @param serviceClass - The class constructor to associate with the instance
+   * @param instance - The pre-built instance to register
+   *
+   * @example
+   * ```ts
+   * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });
+   * testContainer.register(UserService, mockUserService);
+   * const auth = testContainer.get(AuthService); // uses mockUserService via @Inject
+   * ```
+   */
+  register(serviceClass, instance) {
+    this.instances.set(serviceClass, instance);
+  }
+  /**
+   * Clear all cached service instances.
+   *
+   * After calling this, the next {@link get} call for any service
+   * will construct a fresh instance. Does not clear deps or config.
+   */
+  clear() {
+    this.instances.clear();
+  }
+};
+export {
+  BaseService,
+  Container,
+  Inject,
+  Service,
+  getPropertyDescriptorFromChain,
+  wrapWithTracing
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base.ts","../src/decorators.ts","../src/helpers.ts","../src/container.ts"],"sourcesContent":["/** A class constructor type. */\n// biome-ignore lint/suspicious/noExplicitAny: Constructor must accept any args to be generic over all classes\nexport type Constructor<T = unknown> = new (...args: any[]) => T;\n\n/** A pluggable tracing function signature. */\nexport type TraceFn = (spanName: string, fn: () => unknown) => unknown;\n\n/**\n * Minimal interface representing a DI container.\n *\n * Services receive this as `this.registry` to resolve other services\n * without coupling to the full {@link Container} implementation.\n */\nexport interface IContainer {\n  /**\n   * Resolve a service by its class constructor.\n   *\n   * @typeParam T - The service type\n   * @param serviceClass - The class constructor to resolve\n   * @returns The singleton instance of the service\n   */\n  get<T>(serviceClass: Constructor<T>): T;\n}\n\n/**\n * The full set of dependencies passed to a service constructor.\n *\n * Combines the user-defined `TDeps` with the container's `registry`,\n * which is injected automatically by the container.\n *\n * @typeParam TDeps - User-defined dependency interface\n */\nexport type ServiceDependencies<TDeps> = TDeps & { registry: IContainer };\n\n/**\n * Configuration object for {@link Container.create}.\n *\n * @typeParam TDeps - User-defined dependency interface\n */\nexport interface ContainerConfig<TDeps> {\n  /** The user-defined dependencies to inject into services. */\n  deps?: TDeps;\n\n  /**\n   * Optional tracing function for services decorated with `@Service({ trace: true })`.\n   * When a traced service is resolved, all its methods are wrapped with this function.\n   *\n   * @param spanName - The span name in `ClassName.methodName` format\n   * @param fn - The original method to execute within the span\n   * @returns The return value of `fn`\n   *\n   * @example\n   * ```ts\n   * const container = Container.create<ContainerDeps>({\n   *   deps: { db, logger },\n   *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),\n   * });\n   * ```\n   */\n  trace?: TraceFn;\n}\n\n/**\n * Abstract base class that all container-managed services extend.\n *\n * Receives injected dependencies via its constructor and exposes them\n * as `this.deps` (user-defined) and `this.registry` (the container).\n *\n * @typeParam TDeps - User-defined dependency interface\n *\n * @example\n * ```ts\n * interface ContainerDeps {\n *   db: DatabaseClient;\n *   logger: Logger;\n * }\n *\n * @Service()\n * class UserService extends BaseService<ContainerDeps> {\n *   findById(id: string) {\n *     return this.deps.db.users.findUnique({ where: { id } });\n *   }\n * }\n * ```\n */\nexport abstract class BaseService<TDeps = unknown> {\n  /** The user-defined dependencies (everything except `registry`). */\n  protected readonly deps: TDeps;\n\n  /** The container instance, used internally by {@link Inject} to resolve other services. */\n  protected readonly registry: IContainer;\n\n  constructor(dependencies: ServiceDependencies<TDeps>) {\n    const { registry, ...rest } = dependencies as ServiceDependencies<TDeps>;\n    this.deps = rest as unknown as TDeps;\n    this.registry = registry;\n  }\n}\n","import type { Constructor, IContainer } from \"./base.js\";\n\n/** @internal Symbol used to mark classes decorated with `@Service({ trace: true })`. */\nexport const TRACED_MARKER = Symbol(\"__service_traced__\");\n\n/**\n * Options for the {@link Service} decorator.\n */\nexport interface ServiceOptions {\n  /**\n   * When `true`, all methods on this service are automatically wrapped\n   * with the container's `trace` function after construction.\n   *\n   * Requires a `trace` function in the {@link ContainerConfig}.\n   *\n   * @defaultValue `false`\n   */\n  trace?: boolean;\n}\n\n/**\n * Class decorator that marks a class as container-managed.\n *\n * When `trace` is enabled, the container will wrap all methods\n * with tracing spans using the configured trace function.\n *\n * Requires `experimentalDecorators: true` in tsconfig.json.\n *\n * @param options - Optional configuration for the service\n * @returns A class decorator\n *\n * @example\n * ```ts\n * @Service()\n * class UserService extends BaseService<ContainerDeps> {\n *   findById(id: string) {\n *     return this.deps.db.users.findUnique({ where: { id } });\n *   }\n * }\n *\n * @Service({ trace: true })\n * class TracedService extends BaseService<ContainerDeps> {\n *   // All methods auto-traced as \"TracedService.methodName\"\n *   process() { ... }\n * }\n * ```\n */\nexport function Service(options?: ServiceOptions): ClassDecorator {\n  return (target) => {\n    if (options?.trace) {\n      (target as unknown as Record<symbol, boolean>)[TRACED_MARKER] = true;\n    }\n    return target;\n  };\n}\n\ntype InjectTarget<T> = { registry: IContainer } & Record<symbol, T>;\n\n/**\n * Property decorator for declarative inter-service dependency injection.\n *\n * Defines a lazy getter that resolves the dependency from the same container\n * on first access and caches it per-instance. Uses a factory function\n * (`() => X` instead of `X` directly) to avoid circular import issues\n * between service files.\n *\n * Requires `experimentalDecorators: true` in tsconfig.json.\n *\n * @typeParam T - The injected service type\n * @param factory - A factory function returning the service class constructor.\n *                  Called lazily on first property access.\n * @returns A property decorator\n *\n * @example\n * ```ts\n * @Service()\n * class AuthService extends BaseService<ContainerDeps> {\n *   @Inject(() => UserService)\n *   declare readonly userService: UserService;\n *\n *   @Inject(() => TokenService)\n *   declare readonly tokenService: TokenService;\n *\n *   authenticate(token: string) {\n *     const payload = this.tokenService.verify(token);\n *     return this.userService.findById(payload.userId);\n *   }\n * }\n * ```\n */\nexport function Inject<T>(factory: () => Constructor<T>) {\n  return (_target: object, propertyKey: string | symbol): void => {\n    const cacheKey = Symbol(`__inject_${String(propertyKey)}`);\n\n    Object.defineProperty(_target, propertyKey, {\n      get(this: InjectTarget<T>) {\n        const cached = this[cacheKey];\n        if (cached !== undefined) return cached;\n        const resolved = this.registry.get(factory());\n        this[cacheKey] = resolved;\n        return resolved;\n      },\n      enumerable: true,\n      configurable: true,\n    });\n  };\n}\n","import type { TraceFn } from \"./base.js\";\n\n/**\n * Walk the prototype chain from `proto` up to (but not including) `stopAt`,\n * looking for a property descriptor with the given key.\n *\n * @param proto - The prototype to start searching from\n * @param key - The property name to look for\n * @param stopAt - The prototype to stop at (exclusive)\n * @returns The property descriptor if found, or `undefined`\n */\nexport function getPropertyDescriptorFromChain(\n  proto: object,\n  key: string,\n  stopAt: object,\n): PropertyDescriptor | undefined {\n  let current: object | null = proto;\n  while (current && current !== stopAt) {\n    const desc = Object.getOwnPropertyDescriptor(current, key);\n    if (desc) return desc;\n    current = Object.getPrototypeOf(current);\n  }\n  return undefined;\n}\n\n/**\n * Wrap all methods on an instance with a tracing function.\n *\n * Walks the prototype chain from the instance up to `stopAt`, wrapping\n * every method (functions with a `value` descriptor) with the `trace` callback.\n * Getters, setters, and the constructor are skipped. When a method exists on\n * multiple prototypes in the chain, the closest (most derived) version wins.\n *\n * Span names follow the `ClassName.methodName` format.\n *\n * @param instance - The object instance whose methods will be wrapped\n * @param trace - The tracing function that wraps each method call\n * @param stopAt - The prototype to stop walking at (typically `BaseService.prototype`)\n *\n * @example\n * ```ts\n * wrapWithTracing(instance, (spanName, fn) => {\n *   console.log(`>> ${spanName}`);\n *   const result = fn();\n *   console.log(`<< ${spanName}`);\n *   return result;\n * }, BaseService.prototype);\n * ```\n */\nexport function wrapWithTracing(\n  instance: object,\n  trace: TraceFn,\n  stopAt: object,\n): void {\n  const className = instance.constructor.name;\n  const seen = new Set<string>();\n  let proto: object | null = Object.getPrototypeOf(instance);\n\n  while (proto && proto !== stopAt) {\n    for (const key of Object.getOwnPropertyNames(proto)) {\n      if (key === \"constructor\" || seen.has(key)) continue;\n      seen.add(key);\n\n      const desc = Object.getOwnPropertyDescriptor(proto, key);\n      if (!desc || !desc.value || typeof desc.value !== \"function\") continue;\n\n      const original = desc.value as (...args: unknown[]) => unknown;\n      const spanName = `${className}.${key}`;\n\n      (instance as Record<string, unknown>)[key] = function (\n        this: unknown,\n        ...args: unknown[]\n      ) {\n        return trace(spanName, () => original.apply(this, args));\n      };\n    }\n    proto = Object.getPrototypeOf(proto);\n  }\n}\n","import {\n  BaseService,\n  type Constructor,\n  type ContainerConfig,\n  type IContainer,\n  type ServiceDependencies,\n} from \"./base.js\";\nimport { TRACED_MARKER } from \"./decorators.js\";\nimport { wrapWithTracing } from \"./helpers.js\";\n\n/**\n * A dependency injection container that lazily creates and caches singleton service instances.\n *\n * Supports both a global singleton (via {@link Container.getGlobalInstance}) and\n * isolated instances (via {@link Container.create}) for test environments.\n *\n * @typeParam TDeps - User-defined dependency interface\n *\n * @example\n * ```ts\n * // Production usage\n * const container = Container.create<ContainerDeps>({ db, logger });\n * const auth = container.get(AuthService);\n *\n * // Test usage (isolated)\n * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });\n * testContainer.register(UserService, mockUserService);\n * const auth = testContainer.get(AuthService);\n * ```\n */\nexport class Container<TDeps = unknown> implements IContainer {\n  private static globalInstance: Container<unknown> | undefined;\n\n  private instances = new Map<Constructor, unknown>();\n  private deps: TDeps | undefined;\n  private config: ContainerConfig<TDeps>;\n\n  private constructor(config: ContainerConfig<TDeps> = {}) {\n    this.config = config;\n    this.deps = config.deps;\n  }\n\n  /**\n   * Create a new container instance.\n   *\n   * Accepts either a plain deps object or a {@link ContainerConfig} with\n   * additional options like `trace`.\n   * When called with no arguments, the container defers resolution\n   * until {@link setDeps} is called.\n   *\n   * @typeParam TDeps - User-defined dependency interface\n   * @param depsOrConfig - Dependencies or full configuration object\n   * @returns A new isolated container instance\n   *\n   * @example\n   * ```ts\n   * // Simple — pass deps directly\n   * const container = Container.create<ContainerDeps>({ db, logger });\n   *\n   * // With config — pass options alongside deps\n   * const container = Container.create<ContainerDeps>({\n   *   deps: { db, logger },\n   *   trace: (spanName, fn) => tracer.startActiveSpan(spanName, () => fn()),\n   * });\n   *\n   * // Lazy — set deps later\n   * const container = Container.create<ContainerDeps>();\n   * container.setDeps({ db, logger });\n   * ```\n   */\n  static create<TDeps>(\n    depsOrConfig?: TDeps | ContainerConfig<TDeps>,\n  ): Container<TDeps> {\n    if (\n      depsOrConfig &&\n      typeof depsOrConfig === \"object\" &&\n      (\"deps\" in depsOrConfig || \"trace\" in depsOrConfig)\n    ) {\n      return new Container<TDeps>(depsOrConfig as ContainerConfig<TDeps>);\n    }\n    return new Container<TDeps>({\n      deps: depsOrConfig as TDeps | undefined,\n    });\n  }\n\n  /**\n   * Get the global singleton container instance.\n   *\n   * Creates one on first call. Useful for module-level exports that\n   * need a container reference before deps are available.\n   *\n   * @typeParam TDeps - User-defined dependency interface\n   * @returns The global container instance\n   */\n  static getGlobalInstance<TDeps>(): Container<TDeps> {\n    if (!Container.globalInstance) {\n      Container.globalInstance = new Container<TDeps>();\n    }\n    return Container.globalInstance as Container<TDeps>;\n  }\n\n  /**\n   * Reset the global singleton container.\n   *\n   * Clears all cached instances and removes the global reference.\n   * Primarily used for test cleanup.\n   */\n  static resetGlobal(): void {\n    Container.globalInstance?.clear();\n    Container.globalInstance = undefined;\n  }\n\n  /**\n   * Set or replace the dependencies after container creation.\n   *\n   * Useful for lazy initialization patterns where the container\n   * is created before deps are available.\n   *\n   * @param deps - The user-defined dependencies\n   */\n  setDeps(deps: TDeps): void {\n    this.deps = deps;\n  }\n\n  /**\n   * Resolve a service by its class constructor.\n   *\n   * On first call, lazily constructs the service with `{ ...deps, registry: this }`\n   * and caches the singleton. Subsequent calls return the cached instance.\n   *\n   * If the service was decorated with `@Service({ trace: true })`, all its methods\n   * are automatically wrapped with the configured `trace` function.\n   *\n   * @typeParam T - The service type\n   * @param serviceClass - The class constructor to resolve\n   * @returns The singleton instance\n   * @throws If deps have not been set\n   * @throws If the service has tracing enabled but no `trace` function was configured\n   */\n  get<T>(serviceClass: Constructor<T>): T {\n    const existing = this.instances.get(serviceClass);\n    if (existing) return existing as T;\n\n    if (!this.deps) {\n      throw new Error(\n        \"Container deps not set. Call setDeps() or pass deps to Container.create().\",\n      );\n    }\n\n    const serviceDeps: ServiceDependencies<TDeps> = {\n      ...this.deps,\n      registry: this,\n    };\n\n    const instance = new serviceClass(serviceDeps);\n\n    // Apply tracing if @Service({ trace: true }) was used\n    if ((serviceClass as unknown as Record<symbol, unknown>)[TRACED_MARKER]) {\n      if (!this.config.trace) {\n        throw new Error(\n          `Service \"${serviceClass.name}\" has trace enabled but no trace function was provided. Pass { trace } to Container.create().`,\n        );\n      }\n      wrapWithTracing(\n        instance as object,\n        this.config.trace,\n        BaseService.prototype,\n      );\n    }\n\n    this.instances.set(serviceClass, instance);\n    return instance;\n  }\n\n  /**\n   * Register a pre-built instance for a service class.\n   *\n   * The registered instance is returned by {@link get} without constructing.\n   * Primarily used for injecting test mocks.\n   *\n   * @typeParam T - The service type\n   * @param serviceClass - The class constructor to associate with the instance\n   * @param instance - The pre-built instance to register\n   *\n   * @example\n   * ```ts\n   * const testContainer = Container.create<ContainerDeps>({ db: mockDb, logger: mockLogger });\n   * testContainer.register(UserService, mockUserService);\n   * const auth = testContainer.get(AuthService); // uses mockUserService via @Inject\n   * ```\n   */\n  register<T>(serviceClass: Constructor<T>, instance: T): void {\n    this.instances.set(serviceClass, instance);\n  }\n\n  /**\n   * Clear all cached service instances.\n   *\n   * After calling this, the next {@link get} call for any service\n   * will construct a fresh instance. Does not clear deps or config.\n   */\n  clear(): void {\n    this.instances.clear();\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@half0wl/container",
+  "version": "1.0.0",
+  "description": "Lightweight decorator-based dependency injection container for TypeScript services",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.check.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "dependency-injection",
+    "di",
+    "container",
+    "typescript",
+    "decorators",
+    "singleton"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  }
+}