Add test util to create Nexus endpoint.

[Quinn-With-Two-Ns]

Add test utility to create Nexus endpoint. This matches what we have in Java and Dotnet

---

Note

Introduces convenience utilities for Nexus endpoint lifecycle in the testing environment.

• Add TestWorkflowEnvironment.createNexusEndpoint(name, taskQueue) and deleteNexusEndpoint(endpoint); export NexusEndpointIdentifier
• Refactor test-nexus-handler.ts and test-nexus-workflow-caller.ts to use the new helpers, passing endpoint names and registering teardown cleanup
• Add a focused test validating createNexusEndpoint/deleteNexusEndpoint

^{Written by Cursor Bugbot for commit 0a1bfd1. This will update automatically on new commits. Configure here.}

[chris-olszewski]

I think it is worthwhile to do some type refinement with createNexusEndpoint return type and deleteNexusEndpoint parameter as they're both fairly permissive.

temporal.api.nexus.v1.IEndpoint is extremely permissible so it'll allow deleteNexusEndpoint({}) and the endpoint we return from createNexusEndpoint isn't required to have any defined fields which makes it awkward to use.

I think bare minimum we should ensure that the endpoint type we return/use here has id and version. I think the easiest way to achieve this is

type PartialRequire<T, K extends keyof T> = Omit<T, K> & {
  [P in K]-?: NonNullable<T[P]>;
};

export type NexusEndpoint = PartialRequire<temporal.api.nexus.v1.IEndpoint, 'id' | 'version'>;

We could also just do something more explicit to keep types more legible:

interface NexusEndpointIdentifier {
  id: temporal.api.nexus.v1.IEndpoint['id'];
  version: temporal.api.nexus.v1.IEndpoint['version'];
}

and update types to

createNexusEndpoint(name: string, taskQueue: string): Promise<NexusEndpointIdentifier & temporal.api.nexus.v1.IEndpoint>
deleteNexusEndpoint(endpoint: NexusEndpointIdentifier): Promise<void>

What do you think?

[chris-olszewski]

Can we throw a descriptive response here if we do end up not getting back an endpoint on the response? With ! we're just passing on the undefined to the end user.

[mjameswh]

Agreed, though, to be fair, we're generally not paranoid about these kinds of checks. The grpc library will throw an error if server failed with some grpc error code, and if the service succeeded the request, then it is expected to return a valid value.

[chris-olszewski]

Suggested change

	id: endpoint.id!,
	version: endpoint.version!,
	id: endpoint.id,
	version: endpoint.version,

[mjameswh]

Could we return a more user-friendly type than the protobuf-generated IEndpoint interface? Expecting users to use the non-null-assertion operator to get to the endpoint ID and other known-present fields is harsh. Many teams actually raise lint errors on usage of that syntax.

[mjameswh]

I'd propose this:

-  async createNexusEndpoint(name: string, taskQueue: string): Promise<temporal.api.nexus.v1.IEndpoint> {
+  async createNexusEndpoint(name: string, taskQueue: string): Promise<NexusEndpointIdentifier> {
     // ...

+    if (!response.endpoint?.id || !response.endpoint?.version) {
+      throw new TypeError('Unexpected response from createNexusEndpoint');
+    }

-    return response.endpoint;
+    return {
+      id: response.endpoint.id,
+      version: response.endpoint.version,
+      raw: response.endpoint,
+    };
   }

-  async deleteNexusEndpoint(endpoint: Pick<temporal.api.nexus.v1.IEndpoint>): Promise<void> {
+  async deleteNexusEndpoint(endpoint: Omit<NexusEndpointIdentifier, 'raw'>): Promise<void> {
     // ...
   }

with the following type definition at the bottom of testing-workflow-environment.ts (and reexported from that package's index.ts)

export type NexusEndpointIdentifier = {
  id: NonNullable<temporal.api.nexus.v1.IEndpoint['id']>;
  version: NonNullable<temporal.api.nexus.v1.IEndpoint['version']>;
  raw: temporal.api.nexus.v1.IEndpoint;
};

This is not intended to be a general-purpose Operator Service Client, so I would personally be ok reducing NexusEndpointIdentifier to only {id, version}, without anything else. But then, doesn't cost much keeping the original protobuf IEndpoint object as raw. This is something we did in a few other places in TS SDK.