Stronger query and signal definitions (#1056)

Co-authored-by: Jon Parise <jon@indelible.org>

Author: josiah-roberts

packages/client/src/workflow-options.ts

@@ -47,7 +47,7 @@ export interface WorkflowSignalWithStartOptionsWithoutArgs<SignalArgs extends an
   /**
    * SignalDefinition or name of signal
    */
-  signal: SignalDefinition | string;
+  signal: SignalDefinition<SignalArgs> | string;
 
   /**
    * Arguments to invoke the signal handler with

packages/common/src/interfaces.ts

@@ -15,26 +15,43 @@ export type WorkflowQueryType = (...args: any[]) => any;
  */
 export type Workflow = (...args: any[]) => WorkflowReturnType;
 
+declare const argsBrand: unique symbol;
 /**
  * An interface representing a Workflow signal definition, as returned from {@link defineSignal}
  *
- * @remarks `_Args` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
+ * @remarks `Args` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
+ * `Name` can optionally be specified with a string literal type to preserve type-level knowledge of the signal name.
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export interface SignalDefinition<_Args extends any[] = []> {
+export interface SignalDefinition<Args extends any[] = [], Name extends string = string> {
   type: 'signal';
-  name: string;
+  name: Name;
+  /**
+   * Virtual type brand to maintain a distinction between {@link SignalDefinition} types with different args.
+   * This field is not present at run-time.
+   */
+  [argsBrand]: Args;
 }
 
+declare const retBrand: unique symbol;
 /**
  * An interface representing a Workflow query definition as returned from {@link defineQuery}
  *
- * @remarks `_Args` and `_Ret` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
+ * @remarks `Args` and `Ret` can be used for parameter type inference in handler functions and *WorkflowHandle methods.
+ * `Name` can optionally be specified with a string literal type to preserve type-level knowledge of the query name.
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-export interface QueryDefinition<_Ret, _Args extends any[] = []> {
+export interface QueryDefinition<Ret, Args extends any[] = [], Name extends string = string> {
   type: 'query';
-  name: string;
+  name: Name;
+  /**
+   * Virtual type brand to maintain a distinction between {@link QueryDefinition} types with different args.
+   * This field is not present at run-time.
+   */
+  [argsBrand]: Args;
+  /**
+   * Virtual type brand to maintain a distinction between {@link QueryDefinition} types with different return types.
+   * This field is not present at run-time.
+   */
+  [retBrand]: Ret;
 }
 
 /** Get the "unwrapped" return type (without Promise) of the execute handler from Workflow type `W` */

packages/common/src/workflow-handle.ts

@@ -21,7 +21,10 @@ export interface BaseWorkflowHandle<T extends Workflow> {
    * await handle.signal(incrementSignal, 3);
    * ```
    */
-  signal<Args extends any[] = []>(def: SignalDefinition<Args> | string, ...args: Args): Promise<void>;
+  signal<Args extends any[] = [], Name extends string = string>(
+    def: SignalDefinition<Args, Name> | string,
+    ...args: Args
+  ): Promise<void>;
 
   /**
    * The workflowId of the current Workflow

packages/test/src/test-interface-type-safety.ts

@@ -0,0 +1,55 @@
+import test from 'ava';
+import { defineSignal, defineQuery } from '@temporalio/workflow';
+
+test('SignalDefinition Name type safety', (t) => {
+  // @ts-expect-error Assert expect a type error when generic and concrete names do not match
+  defineSignal<[string], 'mismatch'>('illegal value');
+
+  const signalA = defineSignal<[string], 'a'>('a');
+  const signalB = defineSignal<[string], 'b'>('b');
+
+  type TypeAssertion = typeof signalB extends typeof signalA ? 'intermixable' : 'not-intermixable';
+
+  const _assertion: TypeAssertion = 'not-intermixable';
+  t.pass();
+});
+
+test('SignalDefinition Args type safety', (t) => {
+  const signalString = defineSignal<[string]>('a');
+  const signalNumber = defineSignal<[number]>('b');
+
+  type TypeAssertion = typeof signalNumber extends typeof signalString ? 'intermixable' : 'not-intermixable';
+
+  const _assertion: TypeAssertion = 'not-intermixable';
+  t.pass();
+});
+
+test('QueryDefinition Name type safety', (t) => {
+  // @ts-expect-error Assert expect a type error when generic and concrete names do not match
+  defineQuery<void, [string], 'mismatch'>('illegal value');
+
+  const queryA = defineQuery<void, [string], 'a'>('a');
+  const queryB = defineQuery<void, [string], 'b'>('b');
+
+  type TypeAssertion = typeof queryB extends typeof queryA ? 'intermixable' : 'not-intermixable';
+
+  const _assertion: TypeAssertion = 'not-intermixable';
+  t.pass();
+});
+
+test('QueryDefinition Args and Ret type safety', (t) => {
+  const retVariantA = defineQuery<string>('a');
+  const retVariantB = defineQuery<number>('b');
+
+  type RetTypeAssertion = typeof retVariantB extends typeof retVariantA ? 'intermixable' : 'not-intermixable';
+
+  const _retAssertion: RetTypeAssertion = 'not-intermixable';
+
+  const argVariantA = defineQuery<string, [number]>('a');
+  const argVariantB = defineQuery<string, [string]>('b');
+
+  type ArgTypeAssertion = typeof argVariantB extends typeof argVariantA ? 'intermixable' : 'not-intermixable';
+
+  const _argAssertion: ArgTypeAssertion = 'not-intermixable';
+  t.pass();
+});

packages/workflow/src/workflow.ts

@@ -1122,11 +1122,13 @@ function conditionInner(fn: () => boolean): Promise<void> {
  * Definitions are used to register handler in the Workflow via {@link setHandler} and to signal Workflows using a {@link WorkflowHandle}, {@link ChildWorkflowHandle} or {@link ExternalWorkflowHandle}.
  * Definitions can be reused in multiple Workflows.
  */
-export function defineSignal<Args extends any[] = []>(name: string): SignalDefinition<Args> {
+export function defineSignal<Args extends any[] = [], Name extends string = string>(
+  name: Name
+): SignalDefinition<Args, Name> {
   return {
     type: 'signal',
     name,
-  };
+  } as SignalDefinition<Args, Name>;
 }
 
 /**
@@ -1135,11 +1137,13 @@ export function defineSignal<Args extends any[] = []>(name: string): SignalDefin
  * Definitions are used to register handler in the Workflow via {@link setHandler} and to query Workflows using a {@link WorkflowHandle}.
  * Definitions can be reused in multiple Workflows.
  */
-export function defineQuery<Ret, Args extends any[] = []>(name: string): QueryDefinition<Ret, Args> {
+export function defineQuery<Ret, Args extends any[] = [], Name extends string = string>(
+  name: Name
+): QueryDefinition<Ret, Args, Name> {
   return {
     type: 'query',
     name,
-  };
+  } as QueryDefinition<Ret, Args, Name>;
 }
 
 /**