chore: move connect* endpoints to be a method on ActorHandle

Author: NathanFlurry

packages/actor-core/src/client/actor_conn.ts

@@ -8,7 +8,7 @@ import * as cbor from "cbor-x";
 import * as errors from "./errors";
 import { logger } from "./log";
 import { type WebSocketMessage as ConnMessage, messageLength } from "./utils";
-import { ACTOR_CONNS_SYMBOL, type ClientRaw } from "./client";
+import { ACTOR_CONNS_SYMBOL, TRANSPORT_SYMBOL, type ClientRaw } from "./client";
 import type { AnyActorDefinition } from "@/actor/definition";
 import pRetry from "p-retry";
 import { importWebSocket } from "@/common/websocket";
@@ -120,7 +120,6 @@ export class ActorConnRaw {
 		private readonly endpoint: string,
 		private readonly params: unknown,
 		private readonly encodingKind: Encoding,
-		private readonly transport: Transport,
 		private readonly actorQuery: ActorQuery,
 	) {
 		this.#keepNodeAliveInterval = setInterval(() => 60_000);
@@ -240,12 +239,12 @@ enc
 			this.#onOpenPromise = Promise.withResolvers();
 
 			// Connect transport
-			if (this.transport === "websocket") {
+			if (this.client[TRANSPORT_SYMBOL] === "websocket") {
 				this.#connectWebSocket();
-			} else if (this.transport === "sse") {
+			} else if (this.client[TRANSPORT_SYMBOL] === "sse") {
 				this.#connectSse();
 			} else {
-				assertUnreachable(this.transport);
+				assertUnreachable(this.client[TRANSPORT_SYMBOL]);
 			}
 
 			// Wait for result

packages/actor-core/src/client/actor_handle.ts

@@ -5,6 +5,8 @@ import type { AnyActorDefinition } from "@/actor/definition";
 import type { ActorQuery } from "@/manager/protocol/query";
 import type { ActorDefinitionRpcs } from "./actor_common";
 import type { RpcRequest, RpcResponse } from "@/actor/protocol/http/rpc";
+import { type ActorConn, ActorConnRaw } from "./actor_conn";
+import { CREATE_ACTOR_CONN_PROXY, type ClientRaw } from "./client";
 
 /**
  * Provides underlying functions for stateless {@link ActorHandle} for RPC calls.
@@ -13,6 +15,7 @@ import type { RpcRequest, RpcResponse } from "@/actor/protocol/http/rpc";
  * @see {@link ActorHandle}
  */
 export class ActorHandleRaw {
+	#client: ClientRaw;
 	#endpoint: string;
 	#encodingKind: Encoding;
 	#actorQuery: ActorQuery;
@@ -27,11 +30,13 @@ export class ActorHandleRaw {
 	 * @protected
 	 */
 	public constructor(
+		client: any,
 		endpoint: string,
 		private readonly params: unknown,
 		encodingKind: Encoding,
 		actorQuery: ActorQuery,
 	) {
+		this.#client = client;
 		this.#endpoint = endpoint;
 		this.#encodingKind = encodingKind;
 		this.#actorQuery = actorQuery;
@@ -82,6 +87,30 @@ export class ActorHandleRaw {
 
 		return responseData.o as Response;
 	}
+
+	/**
+	 * Establishes a persistent connection to the actor.
+	 *
+	 * @template AD The actor class that this connection is for.
+	 * @returns {ActorConn<AD>} A connection to the actor.
+	 */
+	connect(): ActorConn<AnyActorDefinition> {
+		logger().debug("establishing connection from handle", {
+			query: this.#actorQuery,
+		});
+
+		const conn = new ActorConnRaw(
+			this.#client,
+			this.#endpoint,
+			this.params,
+			this.#encodingKind,
+			this.#actorQuery,
+		);
+
+		return this.#client[CREATE_ACTOR_CONN_PROXY](
+			conn,
+		) as ActorConn<AnyActorDefinition>;
+	}
 }
 
 /**
@@ -100,5 +129,10 @@ export class ActorHandleRaw {
  * @template AD The actor class that this handle is for.
  * @see {@link ActorHandleRaw}
  */
-export type ActorHandle<AD extends AnyActorDefinition> = ActorHandleRaw &
-	ActorDefinitionRpcs<AD>;
+export type ActorHandle<AD extends AnyActorDefinition> = Omit<
+	ActorHandleRaw,
+	"connect"
+> & {
+	// Add typed version of ActorConn (instead of using AnyActorDefinition)
+	connect(): ActorConn<AD>;
+} & ActorDefinitionRpcs<AD>;