Nutritious Pumpkin Meal

    wsession
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.3 • Public • Published

    WSession

    WSession is a server-side websocket framework which enables creating declarative and beautifully organized class-based controllers with decorators.

    Table of Contents

    Installation

    • install with npm npm install wsession --save
    • install with yarn yarn add wsession

    Quick Start

    1. Create a file testController.ts

      import {WS, WSCtx, WSHandler, WSParam, WSContext} from "wsession";
       
      enum MSG_CODE {
          CS_MSG1 = 1,
          CS_MSG2 = 2,
          CS_MSG3 = 3,
          CS_MSG4 = 4,
          SC_MSG4 = 5,
          // ...
      }
       
      @WS()
      export class TestController {
       
          @WSHandler(MSG_CODE.CS_MSG1, MSG_CODE.CS_MSG2)
          async echo(@WSParam("arg1") input: number, @WSCtx() ctx: WSContext) {
              console.log("SC_MSG3 received");
              console.log("input is", input);
              console.log("context is", ctx);
              return input;
          }
      }
    2. create a file app.ts, and run it.

          import {TestController} from "./testController"
       
          const server = ... // create http server and activate it
          server.listen(port, resolve)
       
          const svr = new WSvr(
              server,
              [TestController],
              async a => a
          )
    3. create a client project, and try make some messages to the app.

    Decorators

    Examples

    Using WSHandler

    You can declare a class method as an event handler, with the @WS and @WSHandler decorator. When decorator @WSParam and @WSCtx are not setted, default args will be data and context.

     
    // ...
     
    @WS()
    export class TestController {
     
        @WSHandler(MSG_CODE.CS_MSG1)
        async sample(data: IDataType, ctx: WSContext) {
            console.log("SC_MSG3 received");
            console.log("input is", input);
            console.log("context is", ctx);
        }
    }

    Response

    If the rsp_code are specified, which are provided as the second param of @WSHandler, the return value will be sent to client as a response.

     
    // ...
     
    @WS()
    export class TestController {
     
        @WSHandler(MSG_CODE.CS_MSG4, MSG_CODE.SC_MSG4)
        async sample(data: IDataType, ctx: WSContext) {
            console.log("SC_MSG3 received");
            console.log("input is", input);
            console.log("context is", ctx);
            return input;
        }
    }

    Send notice

    You can use the method ctx.notice to send a message to any user in connection.

     
    // ...
     
    @WS()
    export class TestController {
     
        @WSHandler(MSG_CODE.CS_MSG5)
        async sample(data: { uid: string }, ctx: WSContext) {
            ctx.notice(data.uid, MSG_CODE.SC_NOTICE, { d: "notice data" });
        }
    }

    Using param objects

    You can use @WSParam decorator to define arguments which are inject by request massage. In this example, data.arg1 from request message will be insert as the param input.

     
    // ...
     
    @WS()
    export class TestController {
     
        @WSHandler(MSG_CODE.CS_MSG3)
        async method3(@WSParam("arg1") input: number) {
            console.log("CS_MSG3 received");
            console.log("input is", input);
            console.log("context is", ctx);
            return input;
        }
    }

    Using context objects

    You can use @WSCtx decorator to define argument which are inject as context. In this example, ctx will be current WSContext

     
    // ...
     
    @WSHandler(MSG_CODE.CS_MSG3)
    async method3(@WSParam("arg1") anumber, @WSCtx() ctxWSContext, @WSParam("arg2") bnumber) {
        console.log("context is", ctx);
        return input;
    }

    Service injection

    You can use @Inject to inject services into your class.

     
    @WS()
    export class InjectBTest {
        word: string = "world";
    }
     
     
    @WS()
    export class InjectATest {
     
        @WSInject(InjectBTest)
        anotherInjectClass: InjectBTest;
     
        get sentence() {
            return "hello " + this.anotherInjectClass.word;
        }
    }
     
    @WS()
    export class InjectFieldTestController {
     
        constructor() {
        }
     
        @WSInject(InjectATest)
        injectedObject: InjectATest;
     
        @WSHandler(MSG_CODE.CS_MSG8)
        async method1() {
            console.log("CS_MSG8 received", this.injectedObject.sentence);
        }
     
    }
     

    Manually set instance

    WSMeta will create a instance of classes who marked by decorator @WS() when necessary, such as when the message arrives. By default, each class will be instantiated only once, and when instantiated, an empty parameter list will be passed to the constructor.

    hard set instance

    Sometimes, you may expect to create the service instance by yourself. In these cases, you can inject the instance into the meta table in the constructor by your self.

    @WS()
    class NewService {
     
        constructor(
            public readonly paramA: any,
            public readonly paramB: any
        ){
            WSMeta.inject(this);
        }
    }
     
    const newService = new NewService("a", "b");
     
    // ...
     
    const svr = new WSvr(server, [NewService], async a => a);
     

    soft set instance

    In some another cases, the instantiate method can be a lazy-load implementation. You can provide getInstance option to inject the instances.

    @WS({ getInstance: () => new NewService("a", "b") })
    class NewService {
     
        constructor(
            public readonly paramA: any,
            public readonly paramB: any
        ){
            WSMeta.inject(this);
        }
    }
     
    // ...
    const svr = new WSvr(server, [NewService], async a => a);
     

    priority

    hard inject > soft inject > natural inject

    Install

    npm i wsession

    DownloadsWeekly Downloads

    0

    Version

    0.2.3

    License

    Apache-2.0

    Unpacked Size

    163 kB

    Total Files

    102

    Last publish

    Collaborators

    • kinghand