Proto Loader API

Reference for the loader-side surface. The constructor, init(), and the metadata / credentials helpers all live on the same ProtoLoader instance and share state. Most users only call the three highlighted entry points (new ProtoLoader, loader.init, loader.initServer / initClients / initReflection); the lower-level helpers below back-fill the rest.

ProtoLoader


import { ProtoLoader } from 'grpcity'
 
const loader = new ProtoLoader(protoFileOptions)

protoFileOptions is described as follows:

Option	Type	Description
single	Object	{ location, files }
array	Object Array	[ { location, files } ]

Explanation for { location, files }:

Option	Type	Description
location	Path String	Required, e.g., path.join(__dirname, './proto')
files	Path String Array	Required, e.g., ['path/to/service-a.proto', 'path/to/service-b.proto']

The following will display the APIs inside the loader.

init()


await loader.init({ isDev, packagePrefix, loadOptions })

Description:

Loads the proto files and generates proto definitions based on the specified parameters.
Idempotent and concurrent-safe: subsequent calls (including parallel calls before the first one resolves) share a single in-flight Promise. initServer, initClients, and initReflection invoke init() internally if it hasn’t run yet.

Parameters:

Option	Type	Description
isDev	Boolean	Optional. Toggles dev mode; on its own it does nothing visible — it gates packagePrefix. Default false.
packagePrefix	String	Optional. Only honored when isDev is true. Rebinds every loaded service/type under <prefix>.<originalName>; on-wire method paths become /<prefix>.<package>.<Service>/...
loadOptions	LoadOptions	Optional. Passed straight through to @grpc/proto-loader. Defaults: keepCase: true, longs: String, enums: String, defaults: false, oneofs: true.

Returns:

Promise<void>.

initClients()


const clients = await loader.initClients({ services, channelOptions, credentials })

Description:

Initializes clients, binds server addresses and proto definitions from the services, and returns clients instances.

Parameters:

Option	Type	Description
services	Object	Required, service and address
channelOptions	ChannelOptions	Optional, proto channel options, default uses built-in channelOptions
credentials	ChannelCredentials	Optional, certificate chain, use `loader.makeCredentials()` to get`

Detailed explanation of services:


await loader.initClients({
  services: {
    'test.path.service': '192.168.1.33:5001',
    'dev.path.service': { host: '192.168.1.33', port: 5002 }
  }
})

Option	Type	Description
services.key	String	service name, including the complete package name, e.g., 'test.helloworld.Greeter'
services.value	String	ip/domain + port format, e.g., '192.168.1.33:5001'
services.value	Object	{ host, port } format, `host`: string, supports IP and domain; `port`: number, minimum value is 0, maximum value is 65535

Returns:

clients: Includes a series of APIs in clients. For more related APIs, please refer to Client Side.

makeClientCredentials()


const credentials = loader.makeClientCredentials(rootCerts, privateKey, certChain, verifyOptions)

Description:

Generates certificate instances for client use.

Parameters:

Option	Type	Description
rootCerts	Buffer	Optional, generally read ca file
privateKey	Buffer	Optional, generally read key file
certChain	Buffer	Optional, generally read crt file
verifyOptions	Object	Optional, { checkServerIdentity: (hostname, cert) => { } }

Returns:

If there are complete parameters, returns: grpc.credentials.createSsl();
If there are no parameters, returns: grpc.credentials.createInsecure();

initServer()


const server = await loader.initServer(channelOptions)

Description:

Creates a gRPC server instance and provides a series of server APIs.

Parameters:

Option	Type	Description
channelOptions	ChannelOptions	Optional, proto channel options, default uses built-in channelOptions
credentials	ServerCredentials	Optional, certificate chain, use `loader.makeServerCredentials()` to get`

Returns:

Server: Includes a series of APIs in server. For more related APIs, please refer to Server Side.

makeServerCredentials()


const credentials = server.makeServerCredentials(rootCerts, keyCertPairs, checkClientCertificate)

Description:

Generates certificate instances for server use.

Parameters:

Option	Type	Description
rootCerts	Buffer	Optional, generally read ca file
keyCertPairs	Object[]	Optional, { private_key: Buffer, cert_chain: Buffer }, certificate pair, key and crt
checkClientCertificate	Boolean	Optional, whether to check client certificate

Returns:

If there are complete parameters, returns: grpc.ServerCredentials.createSsl();
If there are no parameters, returns: grpc.ServerCredentials.createInsecure();

makeMetadata()


const meta = loader.makeMetadata({ key: value })

Description:

Creates metadata instances for client use. Parameters can be empty.

Parameters:

Option	Type	Description
key	String	key value
value	any / any[]	Usually a string or string array, non-string cases will be converted to Buffer internally

Returns:

Metadata instance.

service()


const service = loader.service(name)

Description:

Gets the service definition from the proto.

Parameters:

Option	Type	Description
name	String	Required, indicates the route to the `service` in the `proto` file

name: ;

Returns:

service definition in proto.

type()


const type = loader.type(name)

Description:

Gets the type definition from the proto;
Capabilities include service().

Parameters:

Option	Type	Description
name	String	Required, indicates the route to the `proto` file, from package to `service`, `model`, or `message`

Returns:

type definition in proto.