Class ServiceRef<T>

A tracked, ref-counted reference to a resolved service.

Provides memory-safe access: accessing .current after .release() throws RefReleasedError instead of returning a stale value.

Since

1.2.0

Example

const rpcRef = ctx.acquireRef(Tokens.RPC);

// Use the service
const balance = await rpcRef.current.getBalance(pubkey);

// Release when done (e.g. on unmount)
rpcRef.release();

// Accessing after release throws
rpcRef.current; // ❌ RefReleasedError

Type Parameters

  • T

    The service type.

Implements

Constructors

constructor

Properties

id

Accessors

acquiredAt ageMs alive current token

Methods

dispose release toWeak use useAsync

Constructors

constructor

  • new ServiceRef<T>(_value, _token, _onRelease, id): ServiceRef<T>
  • Internal

    Use ctx.acquireRef(token) or RefRegistry.acquire() to create refs.

    Type Parameters

    • T

    Parameters

    • _value: T
    • _token: ServiceToken<T>
    • _onRelease: ((ref: ServiceRef<T>) => void)
    • id: number

      Unique reference ID (monotonically increasing within a registry).

    Returns ServiceRef<T>

Properties

Readonlyid

id: number

Unique reference ID (monotonically increasing within a registry).

Accessors

acquiredAt

  • get acquiredAt(): number

  • performance.now() timestamp when this ref was acquired.

    Returns number

ageMs

alive

  • get alive(): boolean

  • Whether this reference is still valid (not released).

    Returns boolean

current

  • get current(): T

  • The resolved service instance.

    Returns T

    Throws

    If the ref has been released or invalidated.

token

Methods

dispose

release

  • release(): void

  • Release this reference, decrementing the ref count.

    After release:

    • .current throws RefReleasedError
    • .alive returns false
    • The ref count for this token decreases by 1

    Safe to call multiple times (idempotent).

    Returns void

toWeak

  • toWeak(): WeakServiceRef<T & object>

  • Create a weak reference that does not prevent garbage collection.

    The returned WeakServiceRef can be shared to components that only need the service optionally — if the strong refs are all released and the GC collects the object, .deref() returns undefined instead of throwing.

    Returns WeakServiceRef<T & object>

    Throws

    If the service value is a primitive (not weakly referenceable).

    Example

    const weakRpc = rpcRef.toWeak();
    // Later:
    const rpc = weakRpc.deref();
    if (rpc) rpc.getBalance(pubkey);

use

  • use<R>(fn): R

  • Execute a function with this reference, auto-releasing afterward.

    The ref is released in a finally block, guaranteeing cleanup even if the function throws.

    Type Parameters

    • R

    Parameters

    • fn: ((service: T) => R)

      Receives the unwrapped service value.

        • (service): R

        • Parameters

          • service: T

          Returns R

    Returns R

    The return value of fn.

    Example

    const balance = rpcRef.use(rpc => rpc.getBalance(pubkey));
    // rpcRef is now released — no leak possible

useAsync

  • useAsync<R>(fn): Promise<R>

  • Async version of use. Awaits the function, then releases.

    Type Parameters

    • R

    Parameters

    • fn: ((service: T) => Promise<R>)
        • (service): Promise<R>

        • Parameters

          • service: T

          Returns Promise<R>

    Returns Promise<R>

    Example

    const balance = await rpcRef.useAsync(rpc => rpc.getBalance(pubkey));

Settings

Member Visibility

On This Page

Constructors
Properties
Accessors
Methods