A complete example for this lib please

[kasir-barati]

I am OK with the docs but TBH it is so hard to connect to this lib for me and I was hopping to see a fully functional NestJS app using different features of this lib but unfortunately I could not find one. At least not one that uses @UseCls. I need to see how I can and should do it. For now I think we need either some examples in this repo so people can look and see how something should be done and as a the cherry on top I would love to see some integration/unit/container tests as well so people can see how to mock stuff, and tests their software.

[Papooch]

You are very right, I am still putting off creating examples, but this library is getting pretty feature-rich, so they're definitely needed.

As for unit/integration tests - there's a lot of tests within the codebase, feel free to browse through files ending with spec.ts. Each feature has a solid collection of tests, that can also serve as an inspiration.

[kasir-barati]

Love that, so I am really looking forward to the examples since I was not able to wrap my head around they @UseCls decorator which I think it will be really helpful, especially when you do not wanna use ClsService#run since it is a pure callback with no way of returning a result from it. Or is there?

I have a bunch of async code running inside it and was not able to find a clean way out of it. So that's why I asked for examples.

In the meantime maybe you can help me to know how I can use @UseCls in this setup:

import { ClsService } from 'nestjs-cls'

@Injectable()
export class CorrelationIdService {
  constructor(private readonly clsStoreClsService: ClsService) {}

  correlationId(): string | undefined {
    return this.clsStoreClsService.get('key')
  }

  correlationIdOrGenerate(): string {
    let correlationId = this.correlationId()
    
    if (!correlationId) {
      correlationId = randomUUID()
      this.logger.debug(`Could not file correlation id, generating a new one: ${correlationId}`)
    }

    return correlationId
  }
  
  openScope(correlationId: string, func: () => void) {
    this.clsStoreClsService.run(() => {
      this.clsStoreClsService.set('key', correlationId)
      func()
    })
  }
}

@Injectable()
export class SomeService {
  constructor(private readonly correlationIdService: CorrelationIdService) {}

  createUser(user: UserDto, correlationId: string) {
    this.correlationIdService.openScope(correlationId, async () => await this.someMethod())
  }

  async someMethod(): Promise<string> {
    return new Promise(resolve => { setTimeout(() => resolve("test"), 1000) })
  }
}

Right now I need to somehow to do something like this:

// ...
  async createUser(user: UserDto, correlationId: string) {
    await this.someMethod()
  }
  @UseCls(/* what should I write here? */)
  async someMethod(): Promise<string> {
    return new Promise(resolve => { setTimeout(() => resolve("test"), 1000) })
  }
// ...

[Papooch]

I'll take a closer look later, but @UseCls is essentially just a syntactic sugar over ClsService#run.

Whatever gets returned from the function passed to run gets also returned into the call site of run.

async getUser() {
  const user = await this.cls.run(
    async ()=> {
      return await this.db.getUser()
    }
  )
  return user
}

is equivalent to

async getUser() {
  return this.getUserFromDb()
}

@UseCls()
async getUserFromDb() {
  return this.db.getUser()
}

However, you should keep in mind tha the @UseCls decorator is meant to be used as the entry point to the context, and the context should be set up as early as possible. You can't really pass variables to @UseCls, it can only read the arguments passed to the function -that's why it's useful for example on Job processors, because it can get ahold of the job object passed to the process method and set up the context using that.

---

From your example, ad given how CorrelationIdService is set up. It doesn't make sense to use with @UseCls.
The only thing that needs to be changed to get the behavior you want is some returns and generics:

async openScope<T>(correlationId: string, func: () => T): T {
    // make sure to return whatever the `run` method returns
    return this.clsStoreClsService.run(() => {
      this.clsStoreClsService.set('key', correlationId)
      // make sure to return whatever `func` returns, so it can be propagated to outer scope
      return func()
    })
  }

And use it like so:

  createUser(user: UserDto, correlationId: string) {
    const user = await this.correlationIdService.openScope(correlationId, async () => { return await this.someMethod() })
  }

You could technically use this syntax, but as you can see, it's not very practical for this use-case

  @UseCls<[UserDto, string]>({
    setup: (cls, _user, correlationId) => {
       cls.set.set('key', correlationId)
    }
  })
  createUser(user: UserDto, _correlationId: string) {
    const user = await this.someMethod()
  }

---

(btw, just a suggestion: a better naming for the openScope would be withScope, because it only the func with the correlationId in scope. There's no complementary closeScope function, as it happens automatically)