protobufjs.javascript.txt

                                  ┏━━━━━━━━━━━━━━━━┓
                                  ┃   PROTOBUFJS   ┃
                                  ┗━━━━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #  - protoc + google-protobuf:
                                  #     - convert protobuf <-> JavaScript classes
                                  #     - build-time
                                  #  - protobufjs:
                                  #     - convert protobuf <-> OBJ
                                  #     - runtime (parse can be done build-time using ROOT.toJSON())
                                  #     - simpler

VERSION ==>                       #6.11.3
                                  #Node/browser

require('protobufjs')             #
require('protobufjs/light')       #Does not include some low-level parser|tokenizer utilities
require('protobufjs/minimal')     #Also does not include Root.fromJSON() nor load()

TYPES ==>                         #  - undefined|null: means not set
                                  #  - [s|u]int64: For precise support, must also install long.js
                                  #  - bytes: BUFFER|UINT8_ARR
                                  #  - enum: ID_NUM|STR
                                  #  - map: OBJ

                                  ┌──────────┐
                                  │   LOAD   │
                                  └──────────┘

new Root()                        #ROOT
[ROOT.]load('PATH.proto'[, OPTS]) #Throw if invalid PATH.proto
 ->PROMISE_ROOT                   #OPTS (only allowed if ROOT):
                                  #  - keepCase BOOL: if false (def), convert to camelCase
                                  #     - except package, message, enum
                                  #  - alternateCommentMode BOOL (def: false): recognize //COMMENT
                                  #  - preferTrailingComment BOOL (def: false)
ROOT.lookup('TYPE')->TYPE         #

ROOT_OBJ                          #JSON-serializable ROOT
                                  #Allows caching protobuf parsing.
                                  #Performance is not always better: need to benchmark case-by-case.
ROOT.toJSON()->ROOT_OBJ           #
Root.fromJSON(ROOT_OBJ[, ROOT])
 ->ROOT                           #

require                           #MESSAGE_TYPE of file descriptor set, i.e. reflection representation of a FILE.proto
 ('protobufjs/ext/descriptor')    #Can use MESSAGE_TYPE.encode|decode() to convert FILE_DESCRIPTOR_BUFFER <-> FILE_DESCRIPTOR
FILE_DESCRIPTOR                   #File descriptor set as OBJ. Not JSON-serializable
ROOT.toDescriptor()
 ->FILE_DESCRIPTOR                #
Root.fromDescriptor
 (FILE_DESCRIPTOR[, ROOT])->ROOT  #
Root|Type|Field(...)              #Create FILE_DESCRIPTOR     dynamically.
                                  #Not documented here since using FILE.proto is usually better.
                                  #TypeScript decorators also available.


                                  ┌─────────────┐
                                  │   MESSAGE   │
                                  └─────────────┘

MESSAGE_TYPE.verify(OBJ)[->'ERR'] #Validate OBJ

MESSAGE_TYPE.create(OBJ)->MESSAGE #Convert OBJ to MESSAGE
MESSAGE_TYPE.fromObject(OBJ)
 ->MESSAGE                        #Same but also transtypes
MESSAGE_TYPE.toObject             #OPTS:
 (MESSAGE[, OPTS])->OBJ           #  - longs String or Number (def: both): how to convert [s|u]int64
                                  #  - bytes Array (of numbers) or String (base64) (def: both or BUFFER|UINT_ARR): how to convert bytes
                                  #  - defaults BOOL (def: false): add default values, instead of undefined
                                  #  - array|objects BOOL (def: false): like OPTS.defaults, but only for repeated fields and map fields
                                  #  - oneofs BOOL (def: false): sets OBJ.ONEOF 'CASE_VAR'
                                  #  - json BOOL (def: false): JSON-friendly, e.g. NaN|Infinity to STR
MESSAGE_TYPE.toJSON()->OBJ        #Same as toObject() with OPTS: enums|longs|bytes String, json true

                                  ┌────────────┐
                                  │   BINARY   │
                                  └────────────┘

MESSAGE_TYPE.encode[Delimited]    #Serialize
 (OBJ|MESSAGE[, WRITER])->WRITER  #If "Delimited", also serialize the length of the message, allowing multiple messages to be written.
WRITER.finish()->BUFFER           #

MESSAGE_TYPE.decode[Delimited]
 (BUFFER)->MESSAGE                #Parse

                                  ┌─────────────┐
                                  │   SERVICE   │
                                  └─────────────┘

SERVICE_TYPE.create
 (FUNC(RPC, REQ_BUFFER,
 FUNC2(ERROR, RES_BUFFER)))
 ->SERVICE                        #If streaming, use SERVICE is a STREAM
RPC.name                          #'RPC_NAME'
SERVICE.RPC(REQ_OBJ)
 ->PROMISE_RES_OBJ                #