Class RefRegistry

Centralized registry that tracks all active ServiceRefs.

Provides ref counting, introspection, and leak detection via FinalizationRegistry. Each SynapseContext owns at most one RefRegistry (created lazily on first acquireRef()).

Since

1.2.0

Implements

Disposable

Index

Constructors

Accessors

isDisposed stats

Methods

acquire checkLeaks dispose invalidateAll onLeak refCount totalActive

Constructors

constructor

new RefRegistry(config?): RefRegistry
Parameters
- config: RefRegistryConfig = {}
Returns RefRegistry
- Defined in src/context/refs.ts:420

Accessors

isDisposed

get isDisposed(): boolean
Whether this registry has been disposed.

Returns boolean
- Defined in src/context/refs.ts:621

stats

get stats(): RefStats
Aggregate statistics snapshot.

Returns RefStats
- Defined in src/context/refs.ts:530

Methods

acquire

acquire<T>(token, value): ServiceRef<T>
Create a tracked ref for a resolved service value.
Type Parameters
- T
Parameters
- token: ServiceToken<T>
  The service token.
- value: T
  The resolved service instance.
Returns ServiceRef<T>
A new ServiceRef<T> linked to this registry.
- Defined in src/context/refs.ts:454

checkLeaks

checkLeaks(maxAgeMs?): LeakReport[]
Check for potential leaks: refs that have been alive longer than maxAgeMs without being released.

This is a heuristic — long-lived refs (e.g. for the lifetime of the app) are expected. Use this for debugging / dev mode.
Parameters
- maxAgeMs: number = 60_000
  Threshold in ms.
Returns LeakReport[]
Default
```
60_000
```
- Defined in src/context/refs.ts:561

dispose

dispose(): void
Dispose the registry — invalidates all refs, clears handlers.

Returns void
Implementation of Disposable.dispose
- Defined in src/context/refs.ts:613

invalidateAll

invalidateAll(): void
Force-release all active refs.

Called automatically when the owning SynapseContext is disposed. After this, all refs' .current will throw RefReleasedError.

Returns void
- Defined in src/context/refs.ts:601

onLeak

onLeak(handler): void
Register a handler for GC-detected leaks.

Called when a ServiceRef is garbage collected without .release() having been called first.
Parameters
- handler: ((report: LeakReport) => void)
  Receives a LeakReport for each leak.
  - - (report): void
    - Parameters
      report: LeakReport
      Returns void
Returns void
- Defined in src/context/refs.ts:589

refCount

refCount(token): number
Number of active refs for a specific token.
Parameters
- token: ServiceToken<unknown>
Returns number
- Defined in src/context/refs.ts:514

totalActive

totalActive(): number
Total number of active (unreleased) refs across all tokens.

Returns number
- Defined in src/context/refs.ts:521