chore: add possibility to create actors without the implementation

Signed-off-by: Xavier Geerinck <[email protected]>

Author: XavierGeerinck

README.md

@@ -28,7 +28,7 @@ The Dapr community can be found on [Discord](https://discord.com/invite/ptHhX6jc
 
 ## Contributing
 
-Please see our [Contributing Overview](https://docs.dapr.io/contributing/sdk-contrib/js-contributing/).
+Please see our [Contributing Overview](https://docs.dapr.io/contributing/sdk-contrib/js-contributing/) and [Development Guide](./documentation//development.md) for more information on how to contribute to the Dapr JS SDK.
 
 ### Good First Issues
 

daprdocs/content/en/js-sdk-docs/js-actors/_index.md

@@ -136,7 +136,42 @@ console.log(`Registered Actors: ${JSON.stringify(resRegisteredActors)}`);
 
 ## Invoking Actor Methods
 
-After Actors are registered, create a Proxy object that implements `ParkingSensorInterface` using the `ActorProxyBuilder`. You can invoke the actor methods by directly calling methods on the Proxy object. Internally, it translates to making a network call to the Actor API and fetches the result back.
+After Actors are registered, we can create a Proxy object that uses a implementation stub class (as we require the methods through reflection internally). You can invoke the actor methods by directly calling methods on the Proxy object. Internally, it translates to making a network call to the Actor API and fetches the result back.
+
+```typescript
+export default class ParkingSensorContract {
+  async carEnter(): Promise<void> {
+    throw new Error("Not implemented");
+  }
+
+  async carLeave(): Promise<void> {
+    throw new Error("Not implemented");
+  }
+}
+```
+
+```typescript
+import { ActorId, DaprClient } from "@dapr/dapr";
+import ParkingSensorContract from "./ParkingSensorContract";
+
+const daprHost = "127.0.0.1";
+const daprPort = "50000";
+
+const client = new DaprClient({ daprHost, daprPort });
+
+// Create a new actor builder for the registered actor ParkingSensorContract with interface ParkingSensorContract. It can be used to create multiple actors of a type.
+const builder = new ActorProxyBuilder<ParkingSensorContract>("ParkingSensorContract", ParkingSensorContract, client);
+
+// Create a new actor instance.
+const actor = builder.build(new ActorId("my-actor"));
+// Or alternatively, use a random ID
+// const actor = builder.build(ActorId.createRandomId());
+
+// Invoke the method.
+await actor.carEnter();
+```
+
+Alternatively, you can also use the existing implementation (if you have access to it):
 
 ```typescript
 import { ActorId, DaprClient } from "@dapr/dapr";
@@ -148,8 +183,8 @@ const daprPort = "50000";
 
 const client = new DaprClient({ daprHost, daprPort });
 
-// Create a new actor builder. It can be used to create multiple actors of a type.
-const builder = new ActorProxyBuilder<ParkingSensorInterface>(ParkingSensorImpl, client);
+// Create a new actor builder for the registered actor ParkingSensorImpl with interface ParkingSensorImpl. It can be used to create multiple actors of a type.
+const builder = new ActorProxyBuilder<ParkingSensorInterface>("ParkingSensorImpl", ParkingSensorImpl, client);
 
 // Create a new actor instance.
 const actor = builder.build(new ActorId("my-actor"));

documentation/development.md

@@ -20,6 +20,30 @@ The command below runs the build process and will rebuild each time we change a
 npm run start:dev
 ```
 
+## Running Tests
+
+Tests are written per protocol layer: http or grpc. This is done because Dapr requires endpoints to be registered for for pubsub and bindings, making us having to start up the test, initialize those endpoints and then run. Since Dapr is a sidecar architecture, we thus have to start 2 test suites seperately. It requires the following containers:
+
+- **EMQX:** Used for Binding Tests
+  - Credentials: http://localhost:18083 (user: admin, pass: public)
+- **MongoDB:** Used for State Query API
+
+```bash
+# Start Container
+docker run -d --rm --name emqx -p 1883:1883 -p 8081:8081 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx
+docker run -d --rm --name mongodb -p 27017:27017 mongo
+
+# Run Unit Tests
+npm run test:unit:main
+npm run test:unit:actors
+
+# Start gRPC tests
+npm run test:e2e:grpc
+
+# Start HTTP tests
+npm run test:e2e:http
+```
+
 ## Publishing Package Package Maintenance
 
 To publish a new package to [https://www.npmjs.com/package/@dapr/dapr](https://www.npmjs.com/package/@dapr/dapr) we need to do the following building and publishing steps.
@@ -45,29 +69,6 @@ For **publishing** the package, we simply cut a new release by:
 
 Publishing is automated in the CI/CD pipeline. Each time a version is release (GitHub ref starting with `refs/tags/v`) then the pipeline will deploy the package as described in [build.yml](./.github/workflows/build.yml).
 
-## Running Tests
-
-Tests are written per protocol layer: http or grpc. This is done because Dapr requires endpoints to be registered for for pubsub and bindings, making us having to start up the test, initialize those endpoints and then run. Since Dapr is a sidecar architecture, we thus have to start 2 test suites seperately. It requires the following containers:
-
-- **EMQX:** Used for Binding Tests
-  - Credentials: http://localhost:18083 (user: admin, pass: public)
-- **MongoDB:** Used for State Query API
-
-```bash
-# Start Container
-docker run -d --rm --name emqx -p 1883:1883 -p 8081:8081 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx
-docker run -d --rm --name mongodb -p 27017:27017 mongo
-
-# Run Unit Tests
-npm run test:unit:main
-npm run test:unit:actors
-
-# Start gRPC tests
-npm run test:e2e:grpc
-
-# Start HTTP tests
-npm run test:e2e:http
-```
 
 ## Setup GitHub actions
 

src/actors/client/ActorProxyBuilder.ts

@@ -11,27 +11,30 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-import { CommunicationProtocolEnum, DaprClient } from "../..";
-import Class from "../../types/Class";
+import { CommunicationProtocolEnum, DaprClient, DaprClientOptions } from "../..";
 import ActorClient from "./ActorClient/ActorClient";
 import ActorId from "../ActorId";
-import { DaprClientOptions } from "../../types/DaprClientOptions";
 
 export default class ActorProxyBuilder<T> {
+  // The registered actor name
+  actorTypeName: string;
   actorClient: ActorClient;
-  actorTypeClass: Class<T>;
+  actorAbstractClass: Function;
 
-  constructor(actorTypeClass: Class<T>, daprClient: DaprClient);
+  constructor(actorTypeName: string, actorTypeClass: Function, daprClient: DaprClient);
   constructor(
-    actorTypeClass: Class<T>,
+    actorTypeName: string,
+    abstractClass: Function,
     host: string,
     port: string,
     communicationProtocol: CommunicationProtocolEnum,
     clientOptions: DaprClientOptions,
   );
-  constructor(actorTypeClass: Class<T>, ...args: any[]) {
-    this.actorTypeClass = actorTypeClass;
+  constructor(actorTypeName: string, abstractClass: Function, ...args: any[]) {
+    this.actorTypeName = actorTypeName;
+    this.actorAbstractClass = abstractClass;
 
+    // Create the actor client based on the provided arguments
     if (args.length == 1) {
       const [daprClient] = args;
       this.actorClient = new ActorClient(
@@ -46,27 +49,35 @@ export default class ActorProxyBuilder<T> {
     }
   }
 
-  build(actorId: ActorId): T {
-    const actorTypeClassName = this.actorTypeClass.name;
-    const actorClient = this.actorClient;
+  build(actorId?: ActorId | string): T {
+    const self = this;
+    const actorIdParsed = actorId ? (actorId instanceof ActorId ? actorId : new ActorId(actorId)) : ActorId.createRandomId();
 
+    // Create an instance of the abstract class to inspect its methods
+    // This won't be used directly but helps with method discovery
+    const methodNames = Object.getOwnPropertyNames(this.actorAbstractClass.prototype)
+      .filter(prop => prop !== 'constructor');
+
+    // Create the handler for the proxy
     const handler = {
-      get(_target: any, propKey: any, _receiver: any) {
+      get: (_target: any, prop: any) => {
+        // Ensure the property exists on the abstract class prototype
+        if (!methodNames.includes(prop)) {
+          throw new Error(`Method ${prop} is not defined in the actor class.`);
+        }
+
+        // Proxy the method call to the actor client
         return async function (...args: any) {
           const body = args.length > 0 ? args : null;
-          const res = await actorClient.actor.invoke(actorTypeClassName, actorId, propKey, body);
-
+          const res = await self.actorClient.actor.invoke(self.actorTypeName, actorIdParsed, prop, body);
           return res;
         };
       },
     };
 
     // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy/Proxy
     // we implement a handler that will take a method and forward it to the actor client
-    const proxy = new Proxy(this.actorTypeClass, handler);
-
-    // Return a NOT strongly typed API
-    // @todo: this should return a strongly typed API as well, but requires reflection. How to do this in typescript?
+    const proxy = new Proxy(this.actorAbstractClass, handler);
     return proxy as unknown as T;
   }
 }

src/implementation/Client/GRPCClient/GRPCClient.ts

@@ -19,10 +19,11 @@ import { Settings } from "../../../utils/Settings.util";
 import { Logger } from "../../../logger/Logger";
 import GRPCClientSidecar from "./sidecar";
 import DaprClient from "../DaprClient";
-import { SDK_VERSION } from "../../../version";
+import pkg from "../../../../package.json";
 import communicationProtocolEnum from "../../../enum/CommunicationProtocol.enum";
 import { GrpcEndpoint } from "../../../network/GrpcEndpoint";
 
+
 export default class GRPCClient implements IClient {
   readonly options: DaprClientOptions;
 
@@ -115,7 +116,7 @@ export default class GRPCClient implements IClient {
     options["grpc-node.max_session_memory"] = Number.MAX_SAFE_INTEGER;
 
     // Add user agent
-    options["grpc.primary_user_agent"] = "dapr-sdk-js/v" + SDK_VERSION;
+    options["grpc.primary_user_agent"] = "dapr-sdk-js/v" + pkg.version;
 
     // Add interceptors if we have an API token
     if (this.options.daprApiToken !== "") {

src/implementation/Client/GRPCClient/actor.ts

@@ -29,6 +29,7 @@ export default class GRPCClientActor implements IClientActorBuilder {
   // this means that we can't use T to new up an object (sadly enough) so we have to pass it
   create<T>(actorTypeClass: Class<T>): T {
     const builder = new ActorProxyBuilder<T>(
+      actorTypeClass.name,
       actorTypeClass,
       this.client.options.daprHost,
       this.client.options.daprPort,

src/implementation/Client/HTTPClient/HTTPClient.ts

@@ -21,7 +21,7 @@ import { Settings } from "../../../utils/Settings.util";
 import { THTTPExecuteParams } from "../../../types/http/THTTPExecuteParams.type";
 import { Logger } from "../../../logger/Logger";
 import HTTPClientSidecar from "./sidecar";
-import { SDK_VERSION } from "../../../version";
+import pkg from "../../../../package.json";
 import * as SerializerUtil from "../../../utils/Serializer.util";
 import communicationProtocolEnum from "../../../enum/CommunicationProtocol.enum";
 import { HttpEndpoint } from "../../../network/HttpEndpoint";
@@ -155,7 +155,7 @@ export default class HTTPClient implements IClient {
       clientOptions.headers["dapr-api-token"] = this.options.daprApiToken;
     }
 
-    clientOptions.headers["user-agent"] = `dapr-sdk-js/v${SDK_VERSION} http/1`;
+    clientOptions.headers["user-agent"] = `dapr-sdk-js/v${pkg.version} http/1`;
 
     // Set Body and Content-Type Header
     if (params?.body) {

src/implementation/Client/HTTPClient/actor.ts

@@ -29,6 +29,7 @@ export default class HTTPClientActor implements IClientActorBuilder {
   // this means that we can't use T to new up an object (sadly enough) so we have to pass it
   create<T>(actorTypeClass: Class<T>): T {
     const builder = new ActorProxyBuilder<T>(
+      actorTypeClass.name,
       actorTypeClass,
       this.client.options.daprHost,
       this.client.options.daprPort,

test/actor/DemoActorCounterContract.ts

@@ -0,0 +1,26 @@
+/*
+Copyright 2022 The Dapr Authors
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+export default class DemoActorCounterContract {
+  count(): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+
+  countBy(amount: number, multiplier: number): Promise<void> {
+    throw new Error("Method not implemented.");
+  }
+
+  getCounter(): Promise<number> {
+    throw new Error("Method not implemented.");
+  }
+}