feat(client): Add utility functions isGrpcDeadlineError and isGrpcCancelledError (#1548)

Author: mjameswh

packages/client/src/base-client.ts

@@ -73,7 +73,7 @@ export class BaseClient {
    *
    * The deadline is a point in time after which any pending gRPC request will be considered as failed;
    * this will locally result in the request call throwing a {@link _grpc.ServiceError|ServiceError}
-   * with code {@link _grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   * with code {@link _grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}; see {@link isGrpcDeadlineError}.
    *
    * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
    * possible for the client to end up waiting forever for a response.
@@ -93,7 +93,7 @@ export class BaseClient {
   /**
    * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
    * `fn`'s scope. This will locally result in the request call throwing a {@link _grpc.ServiceError|ServiceError}
-   * with code {@link _grpc.status.CANCELLED|CANCELLED}.
+   * with code {@link _grpc.status.CANCELLED|CANCELLED}; see {@link isGrpcCancelledError}.
    *
    * This method is only a convenience wrapper around {@link Connection.withAbortSignal}.
    *

packages/client/src/connection.ts

@@ -471,7 +471,7 @@ export class Connection {
    *
    * The deadline is a point in time after which any pending gRPC request will be considered as failed;
    * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}; see {@link isGrpcDeadlineError}.
    *
    * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
    * possible for the client to end up waiting forever for a response.
@@ -490,7 +490,7 @@ export class Connection {
   /**
    * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
    * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.CANCELLED|CANCELLED}.
+   * with code {@link grpc.status.CANCELLED|CANCELLED}; see {@link isGrpcCancelledError}.
    *
    * This method is only a convenience wrapper around {@link Connection.withAbortSignal}.
    *

packages/client/src/errors.ts

@@ -1,4 +1,4 @@
-import { ServiceError as GrpcServiceError } from '@grpc/grpc-js';
+import { ServiceError as GrpcServiceError, status } from '@grpc/grpc-js';
 import { RetryState, TemporalFailure } from '@temporalio/common';
 import { isError, isRecord, SymbolBasedInstanceOfError } from '@temporalio/common/lib/type-helpers';
 
@@ -79,6 +79,9 @@ export class WorkflowContinuedAsNewError extends Error {
   }
 }
 
+/**
+ * Returns true if the provided error is a {@link GrpcServiceError}.
+ */
 export function isGrpcServiceError(err: unknown): err is GrpcServiceError {
   return (
     isError(err) &&
@@ -87,6 +90,36 @@ export function isGrpcServiceError(err: unknown): err is GrpcServiceError {
   );
 }
 
+/**
+ * Returns true if the provided error or its cause is a {@link GrpcServiceError} with code DEADLINE_EXCEEDED.
+ *
+ * @see {@link Connection.withDeadline}
+ */
+export function isGrpcDeadlineError(err: unknown): err is Error {
+  while (isError(err)) {
+    if (isGrpcServiceError(err) && (err as GrpcServiceError).code === status.DEADLINE_EXCEEDED) {
+      return true;
+    }
+    err = (err as any).cause;
+  }
+  return false;
+}
+
+/**
+ * Returns true if the provided error or its cause is a {@link GrpcServiceError} with code CANCELLED.
+ *
+ * @see {@link Connection.withAbortSignal}
+ */
+export function isGrpcCancelledError(err: unknown): err is Error {
+  while (isError(err)) {
+    if (isGrpcServiceError(err) && (err as GrpcServiceError).code === status.CANCELLED) {
+      return true;
+    }
+    err = (err as any).cause;
+  }
+  return false;
+}
+
 /**
  * @deprecated Use `isGrpcServiceError` instead
  */

packages/client/src/types.ts

@@ -102,7 +102,7 @@ export interface ConnectionLike {
    *
    * The deadline is a point in time after which any pending gRPC request will be considered as failed;
    * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}; see {@link isGrpcDeadlineError}.
    *
    * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
    * possible for the client to end up waiting forever for a response.
@@ -127,7 +127,7 @@ export interface ConnectionLike {
   /**
    * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
    * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.CANCELLED|CANCELLED}.
+   * with code {@link grpc.status.CANCELLED|CANCELLED}; see {@link isGrpcCancelledError}.
    *
    * @returns value returned from `fn`
    *

packages/cloud/src/cloud-operations-client.ts

@@ -59,7 +59,7 @@ export class CloudOperationsClient {
    *
    * The deadline is a point in time after which any pending gRPC request will be considered as failed;
    * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}; see {@link isGrpcDeadlineError}.
    *
    * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
    * possible for the client to end up waiting forever for a response.
@@ -80,7 +80,7 @@ export class CloudOperationsClient {
   /**
    * Set an {@link AbortSignal} that, when aborted, cancels any ongoing service requests executed in
    * `fn`'s scope. This will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.CANCELLED|CANCELLED}.
+   * with code {@link grpc.status.CANCELLED|CANCELLED}; see {@link isGrpcCancelledError}.
    *
    * This method is only a convenience wrapper around {@link CloudOperationsConnection.withAbortSignal}.
    *
@@ -468,7 +468,7 @@ export class CloudOperationsConnection {
    *
    * The deadline is a point in time after which any pending gRPC request will be considered as failed;
    * this will locally result in the request call throwing a {@link grpc.ServiceError|ServiceError}
-   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}.
+   * with code {@link grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED}; see {@link isGrpcDeadlineError}.
    *
    * It is stronly recommended to explicitly set deadlines. If no deadline is set, then it is
    * possible for the client to end up waiting forever for a response.

packages/test/src/test-client-connection.ts

@@ -10,6 +10,7 @@ import {
   Client,
   Connection,
   defaultGrpcRetryOptions,
+  isGrpcCancelledError,
   isGrpcServiceError,
   isRetryableError,
   makeGrpcRetryInterceptor,
@@ -123,7 +124,7 @@ test('withMetadata / withDeadline / withAbortSignal set the CallContext for RPC
   const ctrl = new AbortController();
   setTimeout(() => ctrl.abort(), 10);
   const err = await t.throwsAsync(conn.withAbortSignal(ctrl.signal, () => conn.workflowService.updateNamespace({})));
-  t.true(isGrpcServiceError(err) && err.code === grpc.status.CANCELLED);
+  t.true(isGrpcCancelledError(err));
 });
 
 test('Connection can connect using "[ipv6]:port" address', async (t) => {