nice-grpc - npm Package Compare versions

Comparing version 2.1.3 to 2.1.4

lib/client/channel.d.ts

 import { Channel, ChannelCredentials, ChannelOptions } from '@grpc/grpc-js';
+/**
+ * Creates a new channel. The channel represents a remote endpoint that can be
+ * connected to.
+ *
+ * @param address The address of the server, in the form `protocol://host:port`,
+ *     where `protocol` is one of `http` or `https`.
+ *     If the protocol is not specified, it will be inferred from the
+ *     credentials.
+ *     If the port is not specified, it will be inferred from the protocol.
+ * @param credentials Optional credentials object that is usually created by
+ *     calling `ChannelCredentials.createSsl()` or
+ *     `ChannelCredentials.createInsecure()`. If not specified, the credentials
+ *     will be inferred from the protocol. If the protocol is not specified,
+ *     `ChannelCredentials.createInsecure()` will be used.
+ * @param options Optional channel options object.
+ * @returns The new channel.
+ */
 export declare function createChannel(address: string, credentials?: ChannelCredentials, options?: ChannelOptions): Channel;
+/**
+ * Waits for the channel to be connected.
+ *
+ * It is not necessary to call this function before making a call on a client.
+ */
 export declare function waitForChannelReady(channel: Channel, deadline: Date): Promise<void>;

lib/client/channel.js

@@ -6,2 +6,19 @@ "use strict";
 const knownProtocols = new Set(['http', 'https']);
+/**
+ * Creates a new channel. The channel represents a remote endpoint that can be
+ * connected to.
+ *
+ * @param address The address of the server, in the form `protocol://host:port`,
+ *     where `protocol` is one of `http` or `https`.
+ *     If the protocol is not specified, it will be inferred from the
+ *     credentials.
+ *     If the port is not specified, it will be inferred from the protocol.
+ * @param credentials Optional credentials object that is usually created by
+ *     calling `ChannelCredentials.createSsl()` or
+ *     `ChannelCredentials.createInsecure()`. If not specified, the credentials
+ *     will be inferred from the protocol. If the protocol is not specified,
+ *     `ChannelCredentials.createInsecure()` will be used.
+ * @param options Optional channel options object.
+ * @returns The new channel.
+ */
 function createChannel(address, credentials, options = {}) {
@@ -22,2 +39,7 @@ const match = /^(?:([^:]+):\/\/)?(.*?)(?::(\d+))?$/.exec(address);
 exports.createChannel = createChannel;
+/**
+ * Waits for the channel to be connected.
+ *
+ * It is not necessary to call this function before making a call on a client.
+ */
 async function waitForChannelReady(channel, deadline) {
@@ -24,0 +46,0 @@ while (true) {

lib/client/ClientFactory.d.ts

@@ -6,3 +6,21 @@ import { Channel } from '@grpc/grpc-js';
 export type ClientFactory<CallOptionsExt = {}> = {
+    /**
+     * Attach a middleware to the client factory.
+     *
+     * This method returns a new client factory with the middleware attached.
+     *
+     * A middleware that is attached first, will be invoked last.
+     *
+     * @param middleware The middleware to attach.
+     * @returns A new client factory with the middleware attached.
+     */
     use<Ext>(middleware: ClientMiddleware<Ext, CallOptionsExt>): ClientFactory<CallOptionsExt & Ext>;
+    /**
+     * Create a client using the client factory.
+     *
+     * @param definition The service definition.
+     * @param channel The channel to use.
+     * @param defaultCallOptions Default call options per method, or `'*'` for all
+     *     methods.
+     */
     create<Service extends CompatServiceDefinition>(definition: Service, channel: Channel, defaultCallOptions?: DefaultCallOptions<NormalizedServiceDefinition<Service>, CallOptionsExt>): Client<Service, CallOptionsExt>;
@@ -13,3 +31,11 @@ };
 };
+/**
+ * Create a client factory that can be used to create clients with middleware.
+ */
 export declare function createClientFactory(): ClientFactory;
+/**
+ * Create a client with no middleware.
+ *
+ * This is the same as calling `createClientFactory().create()`.
+ */
 export declare function createClient<Service extends CompatServiceDefinition>(definition: Service, channel: Channel, defaultCallOptions?: DefaultCallOptions<NormalizedServiceDefinition<Service>>): Client<Service>;

lib/client/ClientFactory.js

@@ -11,2 +11,5 @@ "use strict";
 const createUnaryMethod_1 = require("./createUnaryMethod");
+/**
+ * Create a client factory that can be used to create clients with middleware.
+ */
 function createClientFactory() {
@@ -16,2 +19,7 @@ return createClientFactoryWithMiddleware();
 exports.createClientFactory = createClientFactory;
+/**
+ * Create a client with no middleware.
+ *
+ * This is the same as calling `createClientFactory().create()`.
+ */
 function createClient(definition, channel, defaultCallOptions) {
@@ -18,0 +26,0 @@ return createClientFactory().create(definition, channel, defaultCallOptions);

lib/server/Server.d.ts

@@ -6,4 +6,36 @@ import { ChannelOptions, ServerCredentials } from '@grpc/grpc-js';
 export type Server<CallContextExt = {}> = {
+    /**
+     * Attach a middleware to the server.
+     *
+     * This method returns a new server with the middleware attached.
+     *
+     * A middleware that is attached first, will be invoked first.
+     *
+     * This method must be used before adding any services or calling `listen()`.
+     *
+     * @param middleware The middleware to attach.
+     * @returns A new server with the middleware attached.
+     */
     use<Ext>(middleware: ServerMiddleware<Ext, CallContextExt>): Server<CallContextExt & Ext>;
+    /**
+     * Attach a middleware per service:
+     *
+     * ```ts
+     * server.with(middleware).add(TestDefinition, implementation)
+     * ```
+     *
+     * This will attach the middleware only to the service in the chained `add()`
+     * call. Multiple `with()` calls can be chained to attach multiple middleware.
+     *
+     * @param middleware The middleware to attach.
+     * @returns A builder that can be used to add services with the middleware
+     *     attached.
+     */
     with<Ext>(middleware: ServerMiddleware<Ext, CallContextExt>): ServerAddBuilder<CallContextExt & Ext>;
+    /**
+     * Add a service to the server.
+     *
+     * @param definition The service definition obtained from the generated code.
+     * @param implementation The service implementation.
+     */
     add<Service extends CompatServiceDefinition>(definition: Service, implementation: ServiceImplementation<Service, CallContextExt>): void;
@@ -16,5 +48,20 @@ /**
      * Returns port that the server is bound to.
+     *
+     * @param address The address to listen on, in the form 'host:port'.
+     * @param credentials Optional credentials object that is usually created by
+     *     calling `ServerCredentials.createSsl()` or
+     *     `ServerCredentials.createInsecure()`. If not specified, the server will
+     *     use `ServerCredentials.createInsecure()`.
+     * @returns A promise that resolves to the port that the server is bound to.
      */
     listen(address: string, credentials?: ServerCredentials): Promise<number>;
+    /**
+     * Gracefully shut down the server, waiting for all existing calls to finish.
+     */
     shutdown(): Promise<void>;
+    /**
+     * Forcefully shut down the server, cancelling all existing calls.
+     *
+     * The client will receive a gRPC error with code `CANCELLED`.
+     */
     forceShutdown(): void;
@@ -26,2 +73,8 @@ };
 };
+/**
+ * Create a new server.
+ *
+ * @param options Optional channel options.
+ * @returns The new server.
+ */
 export declare function createServer(options?: ChannelOptions): Server;

lib/server/Server.js

@@ -11,2 +11,8 @@ "use strict";
 const handleUnaryCall_1 = require("./handleUnaryCall");
+/**
+ * Create a new server.
+ *
+ * @param options Optional channel options.
+ * @returns The new server.
+ */
 function createServer(options = {}) {
@@ -13,0 +19,0 @@ return createServerWithMiddleware(options);

package.json

 {
   "name": "nice-grpc",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "A Node.js gRPC library that is nice to you",
@@ -50,5 +50,5 @@ "keywords": [
     "abort-controller-x": "^0.4.0",
-    "nice-grpc-common": "^2.0.1"
+    "nice-grpc-common": "^2.0.2"
   },
-  "gitHead": "0e773a1697c7fdcacdf9a244f78e813577c8c8bd"
+  "gitHead": "a2987f236be78513ea607faf691c9471d640bd0e"
 }

README.md

@@ -742,3 +742,4 @@ # nice-grpc [![npm version][npm-image]][npm-url] <!-- omit in toc -->
 all methods. This doesn't make much sense for built-in options, but may do for
-middleware.
+middleware, for example,
+[nice-grpc-client-middleware-deadline](/packages/nice-grpc-client-middleware-deadline):
 
@@ -749,5 +750,7 @@ ```ts
     // applies for all methods
+    deadline: 30_000,
   },
   exampleUnaryMethod: {
     // applies for single method
+    deadline: 10_000,
   },
@@ -757,2 +760,19 @@ });
 
+To add default metadata, instead use a middleware that merges it with the
+metadata passed to the call:
+
+```ts
+const token = '...';
+
+const client = createClientFactory().use((call, options) =>
+  call.next(call.request, {
+    ...options,
+    metadata: Metadata(options.metadata).set(
+      'Authorization',
+      `Bearer ${token}`,
+    ),
+  }),
+);
+```
+
 #### Channels
@@ -759,0 +779,0 @@

src/client/channel.ts

@@ -10,2 +10,19 @@ import {
 
+/**
+ * Creates a new channel. The channel represents a remote endpoint that can be
+ * connected to.
+ *
+ * @param address The address of the server, in the form `protocol://host:port`,
+ *     where `protocol` is one of `http` or `https`.
+ *     If the protocol is not specified, it will be inferred from the
+ *     credentials.
+ *     If the port is not specified, it will be inferred from the protocol.
+ * @param credentials Optional credentials object that is usually created by
+ *     calling `ChannelCredentials.createSsl()` or
+ *     `ChannelCredentials.createInsecure()`. If not specified, the credentials
+ *     will be inferred from the protocol. If the protocol is not specified,
+ *     `ChannelCredentials.createInsecure()` will be used.
+ * @param options Optional channel options object.
+ * @returns The new channel.
+ */
 export function createChannel(
@@ -33,2 +50,7 @@ address: string,
 
+/**
+ * Waits for the channel to be connected.
+ *
+ * It is not necessary to call this function before making a call on a client.
+ */
 export async function waitForChannelReady(
@@ -35,0 +57,0 @@ channel: Channel,

src/client/ClientFactory.ts

@@ -21,6 +21,23 @@ import {Channel, makeClientConstructor} from '@grpc/grpc-js';
 export type ClientFactory<CallOptionsExt = {}> = {
+  /**
+   * Attach a middleware to the client factory.
+   *
+   * This method returns a new client factory with the middleware attached.
+   *
+   * A middleware that is attached first, will be invoked last.
+   *
+   * @param middleware The middleware to attach.
+   * @returns A new client factory with the middleware attached.
+   */
   use<Ext>(
     middleware: ClientMiddleware<Ext, CallOptionsExt>,
   ): ClientFactory<CallOptionsExt & Ext>;
-
+  /**
+   * Create a client using the client factory.
+   *
+   * @param definition The service definition.
+   * @param channel The channel to use.
+   * @param defaultCallOptions Default call options per method, or `'*'` for all
+   *     methods.
+   */
   create<Service extends CompatServiceDefinition>(
@@ -43,2 +60,5 @@ definition: Service,
 
+/**
+ * Create a client factory that can be used to create clients with middleware.
+ */
 export function createClientFactory(): ClientFactory {
@@ -48,2 +68,7 @@ return createClientFactoryWithMiddleware();
 
+/**
+ * Create a client with no middleware.
+ *
+ * This is the same as calling `createClientFactory().create()`.
+ */
 export function createClient<Service extends CompatServiceDefinition>(
@@ -50,0 +75,0 @@ definition: Service,

src/server/Server.ts

@@ -21,9 +21,40 @@ import {
 export type Server<CallContextExt = {}> = {
+  /**
+   * Attach a middleware to the server.
+   *
+   * This method returns a new server with the middleware attached.
+   *
+   * A middleware that is attached first, will be invoked first.
+   *
+   * This method must be used before adding any services or calling `listen()`.
+   *
+   * @param middleware The middleware to attach.
+   * @returns A new server with the middleware attached.
+   */
   use<Ext>(
     middleware: ServerMiddleware<Ext, CallContextExt>,
   ): Server<CallContextExt & Ext>;
-
+  /**
+   * Attach a middleware per service:
+   *
+   * ```ts
+   * server.with(middleware).add(TestDefinition, implementation)
+   * ```
+   *
+   * This will attach the middleware only to the service in the chained `add()`
+   * call. Multiple `with()` calls can be chained to attach multiple middleware.
+   *
+   * @param middleware The middleware to attach.
+   * @returns A builder that can be used to add services with the middleware
+   *     attached.
+   */
   with<Ext>(
     middleware: ServerMiddleware<Ext, CallContextExt>,
   ): ServerAddBuilder<CallContextExt & Ext>;
+  /**
+   * Add a service to the server.
+   *
+   * @param definition The service definition obtained from the generated code.
+   * @param implementation The service implementation.
+   */
   add<Service extends CompatServiceDefinition>(
@@ -33,3 +64,2 @@ definition: Service,
   ): void;
-
   /**
@@ -41,6 +71,20 @@ * Start listening on given 'host:port'.
    * Returns port that the server is bound to.
+   *
+   * @param address The address to listen on, in the form 'host:port'.
+   * @param credentials Optional credentials object that is usually created by
+   *     calling `ServerCredentials.createSsl()` or
+   *     `ServerCredentials.createInsecure()`. If not specified, the server will
+   *     use `ServerCredentials.createInsecure()`.
+   * @returns A promise that resolves to the port that the server is bound to.
    */
   listen(address: string, credentials?: ServerCredentials): Promise<number>;
-
+  /**
+   * Gracefully shut down the server, waiting for all existing calls to finish.
+   */
   shutdown(): Promise<void>;
+  /**
+   * Forcefully shut down the server, cancelling all existing calls.
+   *
+   * The client will receive a gRPC error with code `CANCELLED`.
+   */
   forceShutdown(): void;
@@ -59,2 +103,8 @@ };
 
+/**
+ * Create a new server.
+ *
+ * @param options Optional channel options.
+ * @returns The new server.
+ */
 export function createServer(options: ChannelOptions = {}): Server {
@@ -61,0 +111,0 @@ return createServerWithMiddleware(options);

No alert changes

Improved metrics

Total package byte prevSize

200559

increased by4.73%

Lines of code

3561

increased by7.16%

Number of lines in readme file

1044

increased by1.95%

Dependency changes

• Updatednice-grpc-common@^2.0.2