Never Play Metal

    @cheep/nestjs
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.4 • Public • Published

    @cheep/nestjs

    An adapter to use the @cheep/microservices library in the NestJS framework.

    Setup

    App Level

    Import the CheepMicroservicesModule.forRoot in a top-level module, once per application/microservice. This establishes the primary transport for all feature modules in this process.

    import {
      CheepTransportModule,
      NestTransportUtils,
    } from '@cheep/nestjs'
    // ... more imports!
    @Module({
      imports: [
        CheepMicroservicesModule.forRoot({
          // MemoryTransport is included by default in @cheep/transport,
          // others are also available!
          transport: new MemoryTransport(
            {
              // optional metadata config goes here
            },
            // this is the set of external plugins / functional callbacks cheep will utilise
            // we provide a default object for your convenience, but you can override it
            NestTransportUtils,
          ),
        }),
        /* ...other providers */
      ],
    })
    export class AppModule {}

    Feature module

    Defines an individual microservice API namespace.

    First, create some services which you would like to expose functions from, then, delcare your API in pure Typescript (this file will disappear after compilation)

    // user.api.ts
    /**
     * *NOTE* use of import type - the api definition file should never
     * import anything other than types.
     *
     * UserQueryService and UserCommandService are normal
     * NestJS Injectable services
     */
    import type { UserCommandService } from './user.command.service'
    import type { UserQueryService } from './user.query.service'
    
    /**
     * UserApi
     * a declarative type of the public api of this module,
     * consumed by other modules and used to ensure all handlers
     * are adequately provided in this module
     */
    export type UserApi = ApiWithExecutableKeys<
      // this is the shape of the api itself, can be either imported classes
      // or function definitions
      {
        Query: {
          User: UserQueryService
        }
        Command: {
          User: UserCommandService
        }
        Event: {
          created: (user: User) => void
        }
      },
      // this is a union of the top level keys from the object which can be "executed",
      // meaning they can be awaited for a response
      'Query' | 'Command'
    >
    
    /**
     * UserRemoteApi
     * a union type of the api types that are consumed by this module
     * it's helpful to use import(...) syntax here to allow tools like NX
     * to differentiate the dependencies, as these dependencies will disappear
     * after typescript compilation (keeping your bundle size small!)
     */
    export type UserRemoteApi =
      | import('../groups/group.api.ts').GroupApi
      | import('../accounts/account.api.ts').AccountApi

    With those types defined, import the CheepMicroservicesModule.forModule in your module

    // user.module.ts
    
    @Module({
      imports: [
        // call for module with this module's api, and the remote api union to be consumed
        CheepMicroservicesModule.forModule<UserApi, UserRemoteApi>({
          // this registers your services as handlers of the various API routes available from
          // the intersection of remote and local api types
          handlers:{
            Query: {
              User: UserQueryService
            },
            Command:{
              User: UserCommandService
            }
          }
          // for any events which will be subscribed with observables, include them in this
          // map by setting them to true; you can set specific routes, or whole subtrees
          listenEventsFrom: {
            Event:{
              Group: true
            }
          },
        }),
        /* ...other providers */
      ],
      // be sure to also provide the query and command handler services to Nest!
      providers: [UserQueryService, UserCommandService],
    })
    export class UserModule {}

    Usage

    Once the setup is complete, you may consume the exported services from CheepMicroservicesModule.forModule using CheepApi in other modules

    CheepApi

    The CheepApi is for executing queries or commands on remote modules, such as from a gateway controller which is not in the same module/microservice.

    Usage of the API is transparent, and has instant type safety to changes in the remote module.

    // gateway.controller.ts
    
    @Controller()
    export class GatewayService implements OnApplicationBootstrap {
      constructor(
        // ConsumedApis is an intersection type = UserApi & GroupApi
        private api: CheepApi<ConsumedApis>,
      ) {}
    
      @Get('users')
      async getUsers() {
        // calling a query
        return this.api.execute.Query.User.getAll()
      }
    
      @Get('user/create')
      async createUser() {
        // calling commands
        const id = await this.api.execute.Command.User.create({
          user: {
            email: faker.internet.email(),
            name: faker.name.findName(),
          },
        })
    
        return this.api.execute.Query.User.getById({ id })
      }
    
      @Get('groups')
      async getGroups() {
        // the query object has keys for each unique namespace
        return this.api.execute.Query.Group.getAll()
      }
    
      @Get('group/create')
      async createGroup() {
        // the command object has keys for each unique namespace
        const id = await this.api.execute.Command.Group.create({
          group: {
            name: faker.commerce.department(),
            color: faker.random.arrayElement(['red', 'blue']),
          },
        })
    
        return this.api.execute.Query.Group.getById({ id })
      }
    
      /**
       * This is to show that *private* members of remote apis may still be
       * called without type safety, just like private functions in JS at runtime
       *
       */
      @Get('test')
      async test() {
        return await this.api.execute.Command.User['thisIsPrivate']() // will be *any*
      }
    }

    Install

    npm i @cheep/nestjs

    DownloadsWeekly Downloads

    5

    Version

    1.0.4

    License

    none

    Unpacked Size

    43.7 kB

    Total Files

    44

    Last publish

    Collaborators

    • ezeki
    • kylebjordahl