Class SynapseContext

constructor

• new SynapseContext(scopeId?, parent?): SynapseContext

• Parameters

  • scopeId: string = 'root'

    Unique scope identifier (auto-generated for child scopes).
  • Optionalparent: SynapseContext

    Parent context for hierarchical resolution.

  Returns SynapseContext

ReadonlyscopeId

allTokens

• get allTokens(): ServiceToken<unknown>[]

• Get all registered tokens across this scope and all parents.

  Returns ServiceToken<unknown>[]

  Since

  1.2.0

isDisposed

• get isDisposed(): boolean

• Whether this context has been disposed.

  Returns boolean

  Since

  1.2.0

memoryGuard

• get memoryGuard(): undefined | MemoryGuard

• The active memory guard, if enabled.

  Returns undefined | MemoryGuard

  Since

  1.2.0

refs

• get refs(): undefined | RefRegistry

• The ref registry for this context, if any refs have been acquired.

  Returns undefined if acquireRef() has never been called.

  Returns undefined | RefRegistry

  Since

  1.2.0

size

• get size(): number

• Number of services registered in this scope.

  Returns number

  Since

  1.2.0

tokens

• get tokens(): ServiceToken<unknown>[]

• Get all registered tokens (this scope only, not parent).

  Returns ServiceToken<unknown>[]

  Since

  1.2.0

acquireRef

• acquireRef<T>(token): ServiceRef<T>

• Acquire a tracked, ref-counted reference to a service.

  Returns a ServiceRef that must be .release()'d when no longer needed. Multiple acquireRef() calls for the same singleton token return different refs to the same instance — the ref count tracks how many holders exist.

  Type Parameters

  • T

    The service type.

  Parameters

  • token: ServiceToken<T>

    The service token to resolve.

  Returns ServiceRef<T>

  A new ServiceRef<T> linked to this context's ref registry.

  Throws

  If no provider is registered for the token.

  Since

  1.2.0

  Example

  // Component A
  const rpcRef = ctx.acquireRef(Tokens.RPC);
  await rpcRef.current.getBalance(pubkey);
  
  // Component B — same singleton, separate ref
  const rpcRef2 = ctx.acquireRef(Tokens.RPC);
  ctx.refCount(Tokens.RPC); // → 2
  
  // Cleanup
  rpcRef.release();   // ref count → 1
  rpcRef2.release();  // ref count → 0
  Copy

bind

• bind<T>(tokens): ServiceBinding<T>

• Acquire tracked refs for multiple tokens at once.

  Returns a ServiceBinding whose .services proxy lazily resolves each token. A single .release() frees all refs.

  Type Parameters

  • T extends Record<string, ServiceToken<unknown>>

  Parameters

  • tokens: T

    Record mapping property names to service tokens.

  Returns ServiceBinding<T>

  A binding with lazy services and batch release.

  Since

  1.2.0

  Example

  const binding = ctx.bind({
    rpc: Tokens.RPC,
    das: Tokens.DAS,
    programs: Tokens.PROGRAMS,
  });
  
  await binding.services.rpc.getBalance(pubkey);
  binding.release(); // releases all at once
  Copy

createScope

• createScope(scopeId?): SynapseContext

• Create a child scope that inherits all parent registrations.

  Scoped services get fresh instances in the child scope. The child scope is tracked and disposed when the parent is disposed.

  Parameters

  • OptionalscopeId: string

    Unique identifier for the child scope.

  Returns SynapseContext

  A new SynapseContext linked to this parent.

  Since

  1.2.0

  Example

  const reqScope = ctx.createScope(`request-${id}`);
  reqScope.register(REQUEST_CTX, { useValue: { id, user } });
  // ... handle request ...
  reqScope.dispose();
  Copy

dispose

• dispose(): Promise<number>

• Dispose this context and all child scopes.

  Calls .dispose() on all singleton/scoped services that implement Disposable. After disposal, any call to resolve() throws.

  Returns Promise<number>

  Number of services disposed.

  Since

  1.2.0

enableMemoryGuard

• enableMemoryGuard(config?): MemoryGuard

• Enable a memory guard with configurable thresholds.

  The guard monitors ref counts and emits pressure/leak events. Can only be called once per context.

  Parameters

  • Optionalconfig: MemoryGuardConfig

    Guard thresholds.

  Returns MemoryGuard

  The created MemoryGuard.

  Since

  1.2.0

  Example

  const guard = ctx.enableMemoryGuard({
    maxRefAgeMs: 30_000,
    maxActiveRefs: 50,
    checkIntervalMs: 10_000,
  });
  
  guard.onPressure(stats => console.warn('Memory pressure:', stats));
  guard.onLeak(leak => console.error('Leaked ref:', leak));
  Copy

has

• has(token): boolean

• Check if a token has a provider (searches parent scopes too).

  Parameters

  • token: ServiceToken<unknown>

  Returns boolean

  Since

  1.2.0

off

• off<K>(event, handler): this

• Unsubscribe from a container event.

  Type Parameters

  • K extends keyof ContextEvents

  Parameters

  • event: K
  • handler: ((payload: ContextEvents[K]) => void)
    • • (payload): void

      • Parameters

        • payload: ContextEvents[K]

        Returns void

  Returns this

  Since

  1.2.0

on

• on<K>(event, handler): this

• Subscribe to a container event.

  Type Parameters

  • K extends keyof ContextEvents

  Parameters

  • event: K
  • handler: ((payload: ContextEvents[K]) => void)
    • • (payload): void

      • Parameters

        • payload: ContextEvents[K]

        Returns void

  Returns this

  Since

  1.2.0

refCount

• refCount(token): number

• Number of active (unreleased) refs for a specific token.

  Returns 0 if no refs have been acquired or the ref registry hasn't been initialized yet.

  Parameters

  • token: ServiceToken<unknown>

  Returns number

  Since

  1.2.0

register

• register<T>(token, provider, tags?): this

• Register a service provider for a token.

  Type Parameters

  • T

  Parameters

  • token: ServiceToken<T>

    The service token.
  • provider: ServiceProvider<T>

    How to create the service.
  • Optionaltags: string[]

    Optional tags for filtering.

  Returns this

  this for chaining.

  Example

  ctx.register(DB, { useFactory: r => new PostgresDB(r.resolve(CONFIG)) });
  ctx.register(LOGGER, { useValue: console }, ['core']);
  ctx.register(CACHE, { useClass: RedisCache, lifecycle: 'singleton' });
  Copy

  Since

  1.2.0

registerIfMissing

• registerIfMissing<T>(token, provider, tags?): this

• Register a service only if the token is not already registered.

  Useful for default/fallback providers that should not override user-provided registrations.

  Type Parameters

  • T

  Parameters

  • token: ServiceToken<T>
  • provider: ServiceProvider<T>
  • Optionaltags: string[]

  Returns this

  Since

  1.2.0

registerMany

• registerMany(registrations): this

• Register multiple services at once.

  Parameters

  • registrations: ServiceRegistration<unknown>[]

    Array of { token, provider, tags? } descriptors.

  Returns this

  this for chaining.

  Since

  1.2.0

resolve

• resolve<T>(token): T

• Resolve a service synchronously.

  Type Parameters

  • T

  Parameters

  • token: ServiceToken<T>

  Returns T

  Throws

  If no provider is registered.

  Throws

  If a circular dependency is detected.

  Throws

  If the provider is async.

  Since

  1.2.0

resolveAsync

• resolveAsync<T>(token): Promise<T>

• Resolve a service asynchronously.

  Required for services registered with useAsyncFactory. Also works for sync providers (wraps result in a resolved promise).

  Type Parameters

  • T

  Parameters

  • token: ServiceToken<T>

  Returns Promise<T>

  Since

  1.2.0

resolveByTag

• resolveByTag(tag): unknown[]

• Resolve all services whose registrations contain the given tag.

  Parameters

  • tag: string

  Returns unknown[]

  Since

  1.2.0

snapshot

• snapshot(): {
      lifecycle: ServiceLifecycle;
      resolved: boolean;
      tags: string[];
      token: string;
  }[]

• Return a snapshot of registered services for debugging.

  Returns {
      lifecycle: ServiceLifecycle;
      resolved: boolean;
      tags: string[];
      token: string;
  }[]

  Since

  1.2.0

tryResolve

• tryResolve<T>(token): undefined | T

• Try to resolve a service; return undefined if not registered.

  Type Parameters

  • T

  Parameters

  • token: ServiceToken<T>

  Returns undefined | T

  Since

  1.2.0

use

• use(mw): this

• Add a resolve middleware.

  Middleware functions wrap every resolve() call. They execute in the order they are added (first-in, outermost).

  Parameters

  • mw: ResolveMiddleware

    Middleware function.

  Returns this

  this for chaining.

  Since

  1.2.0

  Example

  ctx.use((token, next) => {
    console.time(token.name);
    const result = next();
    console.timeEnd(token.name);
    return result;
  });
  Copy