fix: Resolve circular dependencies in the SDK package (#3361)

## Summary

Resolve circular dependencies in the SDK's dependency injection (DI)
container by using token-based injection instead of direct class
references. This eliminates the need for `delay()` wrappers for
`Resends` and `Subscriber` classes.

> [!important]
> This change is necessary for future ESM compatibility. The current
`delay(() => Class)` approach relies on CommonJS module semantics where
circular imports can be partially resolved at runtime. In ESM, module
bindings are evaluated differently and `delay()` won't be sufficient to
break circular dependency cycles.
>
> Token-based injection provides a clean solution that works in both
module systems.

## Changes

- Add `tokens.ts` with Symbol-based injection tokens for `Resends` and
`Subscriber`
- Update `setupTsyringe.ts` to register `Resends` and `Subscriber`
classes with the DI container using tokens (with `ContainerScoped`
lifecycle)
- Replace `@scoped(Lifecycle.ContainerScoped)` decorators with
`@injectable()` for `Resends` and `Subscriber` classes (lifecycle is now
specified during token registration)
- Update `MessagePipelineFactory` to use token injection for `Resends`
instead of `delay(() => Resends)`
- Update `SubscriberKeyExchange` to use token injection for `Subscriber`
(previously injected directly without `delay()`)
- Update `StreamrClient` to resolve `Subscriber` and `Resends` using
tokens instead of class references

## Limitations and future improvements

- Only `Resends` and `Subscriber` are currently registered via tokens;
other classes with circular dependency potential could be migrated to
this pattern in the future
- The `delay()` wrapper is still used for `StreamRegistry` and
`GroupKeyManager` in `MessagePipelineFactory`; these could be converted
to token injection for consistency

Author: mondoreale

packages/sdk/src/StreamrClient.ts

@@ -65,6 +65,7 @@ import { addStreamToStorageNode } from './utils/addStreamToStorageNode'
 import { assertCompliantIdentity } from './utils/encryptionCompliance'
 import { pOnce } from './utils/promises'
 import { convertPeerDescriptorToNetworkPeerDescriptor, createTheGraphClient } from './utils/utils'
+import { Tokens } from './tokens'
 
 // TODO: this type only exists to enable tsdoc to generate proper documentation
 export type SubscribeOptions = StreamDefinition & ExtraSubscribeOptions
@@ -137,8 +138,8 @@ export class StreamrClient {
         this.identity = identity
         this.theGraphClient = theGraphClient
         this.publisher = container.resolve<Publisher>(Publisher)
-        this.subscriber = container.resolve<Subscriber>(Subscriber)
-        this.resends = container.resolve<Resends>(Resends)
+        this.subscriber = container.resolve<Subscriber>(Tokens.Subscriber)
+        this.resends = container.resolve<Resends>(Tokens.Resends)
         this.node = container.resolve<NetworkNodeFacade>(NetworkNodeFacade)
         this.rpcProviderSource = container.resolve(RpcProviderSource)
         this.streamRegistry = container.resolve<StreamRegistry>(StreamRegistry)

packages/sdk/src/encryption/SubscriberKeyExchange.ts

@@ -10,7 +10,7 @@ import { StreamMessage, StreamMessageType } from '../protocol/StreamMessage'
 import { createRandomMsgChainId } from '../publish/messageChain'
 import { MessageSigner } from '../signature/MessageSigner'
 import { SignatureValidator } from '../signature/SignatureValidator'
-import { Subscriber } from '../subscribe/Subscriber'
+import type { Subscriber } from '../subscribe/Subscriber'
 import { LoggerFactory } from '../utils/LoggerFactory'
 import { pOnce, withThrottling } from '../utils/promises'
 import { MaxSizedSet } from '../utils/utils'
@@ -21,6 +21,7 @@ import { AsymmetricEncryptionType, ContentType, EncryptionType, GroupKeyRequest,
 import { KeyExchangeKeyPair } from './KeyExchangeKeyPair'
 import { createCompliantExchangeKeys } from '../utils/encryptionCompliance'
 import { StreamrClientError } from '../StreamrClientError'
+import { Tokens } from '../tokens'
 
 const MAX_PENDING_REQUEST_COUNT = 50000 // just some limit, we can tweak the number if needed
 
@@ -51,7 +52,7 @@ export class SubscriberKeyExchange {
         signatureValidator: SignatureValidator,
         messageSigner: MessageSigner,
         store: LocalGroupKeyStore,
-        subscriber: Subscriber,
+        @inject(Tokens.Subscriber) subscriber: Subscriber,
         @inject(ConfigInjectionToken) config: Pick<StrictStreamrClientConfig, 'encryption' | 'validation'>,
         @inject(IdentityInjectionToken) identity: Identity,
         loggerFactory: LoggerFactory

packages/sdk/src/setupTsyringe.ts

@@ -1 +1,26 @@
 import 'reflect-metadata'
+
+import { container, Lifecycle } from 'tsyringe'
+import { Resends } from './subscribe/Resends'
+import { Subscriber } from './subscribe/Subscriber'
+import { Tokens } from './tokens'
+
+container.register(
+    Tokens.Resends,
+    {
+        useClass: Resends,
+    },
+    {
+        lifecycle: Lifecycle.ContainerScoped,
+    }
+)
+
+container.register(
+    Tokens.Subscriber,
+    {
+        useClass: Subscriber,
+    },
+    {
+        lifecycle: Lifecycle.ContainerScoped,
+    }
+)

packages/sdk/src/subscribe/MessagePipelineFactory.ts

@@ -10,8 +10,9 @@ import { StreamMessage } from '../protocol/StreamMessage'
 import { SignatureValidator } from '../signature/SignatureValidator'
 import { LoggerFactory } from '../utils/LoggerFactory'
 import { PushPipeline } from '../utils/PushPipeline'
-import { Resends } from './Resends'
+import type { Resends } from './Resends'
 import { MessagePipelineOptions, createMessagePipeline as _createMessagePipeline } from './messagePipeline'
+import { Tokens } from '../tokens'
 
 type MessagePipelineFactoryOptions = MarkOptional<Omit<MessagePipelineOptions,
     'resends' |
@@ -37,7 +38,7 @@ export class MessagePipelineFactory {
 
     /* eslint-disable indent */
     constructor(
-        @inject(delay(() => Resends)) resends: Resends,
+        @inject(Tokens.Resends) resends: Resends,
         streamStorageRegistry: StreamStorageRegistry,
         @inject(delay(() => StreamRegistry)) streamRegistry: StreamRegistry,
         signatureValidator: SignatureValidator,

packages/sdk/src/subscribe/Resends.ts

@@ -13,7 +13,7 @@ import {
 import random from 'lodash/random'
 import sample from 'lodash/sample'
 import without from 'lodash/without'
-import { Lifecycle, delay, inject, scoped } from 'tsyringe'
+import { delay, inject, injectable } from 'tsyringe'
 import { ConfigInjectionToken, type StrictStreamrClientConfig } from '../ConfigTypes'
 import { StreamrClientError } from '../StreamrClientError'
 import { StorageNodeRegistry } from '../contracts/StorageNodeRegistry'
@@ -119,7 +119,7 @@ export const toInternalResendOptions = (options: ResendOptions): InternalResendO
     }
 }
 
-@scoped(Lifecycle.ContainerScoped)
+@injectable()
 export class Resends {
 
     private readonly storageNodeRegistry: StorageNodeRegistry

packages/sdk/src/subscribe/Subscriber.ts

@@ -1,12 +1,12 @@
 import { EthereumAddress, Logger, StreamPartID } from '@streamr/utils'
-import { Lifecycle, delay, inject, scoped } from 'tsyringe'
+import { delay, inject, injectable } from 'tsyringe'
 import { NetworkNodeFacade } from '../NetworkNodeFacade'
 import { LoggerFactory } from '../utils/LoggerFactory'
 import { MessagePipelineFactory } from './MessagePipelineFactory'
 import { Subscription } from './Subscription'
 import { SubscriptionSession } from './SubscriptionSession'
 
-@scoped(Lifecycle.ContainerScoped)
+@injectable()
 export class Subscriber {
 
     private readonly subSessions: Map<StreamPartID, SubscriptionSession> = new Map()

packages/sdk/src/tokens.ts

@@ -0,0 +1,4 @@
+export const Tokens = {
+    Resends: Symbol('Resends'),
+    Subscriber: Symbol('Subscriber')
+}