registerSingleton<T> method

void registerSingleton<T>(T instance, { String? moduleId, bool allowOverwrite = false, })

Registers a dependency as a Singleton (Immediate).

If the type is already registered and allowOverwrite is false, it will throw DependencyAlreadyRegisteredException.

instance The object instance to store. moduleId Optional ID of the module that owns this registration. allowOverwrite Set to true to replace existing dependencies (useful for testing/mocking).

Implementation

void registerSingleton<T>(
  T instance, {
  String? moduleId,
  bool allowOverwrite = false,
}) {
  // Prevent accidental overwrites
  if (_registrations.containsKey(T) && !allowOverwrite) {
    AirLogger.warning(
      'Dependency already registered',
      context: {
        'type': T.toString(),
        'existingOwner': _registrationOwners[T],
        'newOwner': moduleId,
      },
    );
    AirAudit().log(
      type: AuditType.securityViolation,
      action: 'dependency_overwrite_blocked',
      moduleId: moduleId ?? 'unknown',
      context: {
        'type': T.toString(),
        'existingOwner': _registrationOwners[T],
      },
      severity: AuditSeverity.medium,
      success: false,
    );
    throw DependencyAlreadyRegisteredException(T);
  }

  _registrations[T] = _SingletonDependency<T>(instance);
  _registrationOwners[T] = moduleId;

  AirLogger.debug(
    'Registered Singleton',
    context: {'type': T.toString(), 'module': moduleId},
  );
}