chore: update JSDOC type to support plug agent (#1827)

* chore: update JS types to support plug agent
[SDK-127]

* moving types to .d.ts file

* formatting + IDL import

src/dfx/assets/language_bindings/canister.js

@@ -10,17 +10,17 @@ export const canisterId = process.env.{canister_name_uppercase}_CANISTER_ID;
  * @deprecated since dfx 0.11.1
  * Do not import from `.dfx`, instead switch to using `dfx generate` to generate your JS interface.
  * @param {string | import("@dfinity/principal").Principal} canisterId Canister ID of Agent
- * @param {{agentOptions?: import("@dfinity/agent").HttpAgentOptions; actorOptions?: import("@dfinity/agent").ActorConfig}} [options]
+ * @param {{agentOptions?: import("@dfinity/agent").HttpAgentOptions; actorOptions?: import("@dfinity/agent").ActorConfig} | { agent?: import("@dfinity/agent").Agent; actorOptions?: import("@dfinity/agent").ActorConfig }} [options]
  * @return {import("@dfinity/agent").ActorSubclass<import("./{canister_name}.did.js")._SERVICE>}
  */
-export const createActor = (canisterId, options) => {
+export const createActor = (canisterId, options = {}) => {
   console.warn(`Deprecation warning: you are currently importing code from .dfx. Going forward, refactor to use the dfx generate command for JavaScript bindings.
-  
+
 See https://internetcomputer.org/docs/current/developer-docs/updates/release-notes/ for migration instructions`);
-  const agent = new HttpAgent(options ? { ...options.agentOptions } : {});
+  const agent = options.agent || new HttpAgent({ ...options.agentOptions });
 
   // Fetch root key for certificate validation during development
-  if (process.env.NODE_ENV !== "production") {
+  if (process.env.DFX_NETWORK !== "ic") {
     agent.fetchRootKey().catch(err => {
       console.warn("Unable to fetch root key. Check to ensure that your local replica is running");
       console.error(err);

src/dfx/assets/language_bindings/index.d.ts.hbs

@@ -1,20 +1,50 @@
-import { ActorSubclass, HttpAgentOptions, ActorConfig } from '@dfinity/agent';
-import { Principal } from '@dfinity/principal';
-import { IDL } from '@dfinity/candid';
+import type {
+  ActorSubclass,
+  HttpAgentOptions,
+  ActorConfig,
+  Agent,
+} from "@dfinity/agent";
+import type { Principal } from "@dfinity/principal";
+import type { IDL } from "@dfinity/candid";
 
 import { _SERVICE } from './{{canister_name}}.did';
 
 export declare const idlFactory: IDL.InterfaceFactory;
 export declare const canisterId: string;
 
 export declare interface CreateActorOptions {
+  /**
+   * @see {@link Agent}
+   */
+  agent?: Agent;
+  /**
+   * @see {@link HttpAgentOptions}
+   */
   agentOptions?: HttpAgentOptions;
+  /**
+   * @see {@link ActorConfig}
+   */
   actorOptions?: ActorConfig;
 }
 
+/**
+ * Intializes an {@link ActorSubclass}, configured with the provided SERVICE interface of a canister.
+ * @constructs {@link ActorSubClass}
+ * @param {string | Principal} canisterId - ID of the canister the {@link Actor} will talk to
+ * @param {CreateActorOptions} options - see {@link CreateActorOptions}
+ * @param {CreateActorOptions["agent"]} options.agent - a pre-configured agent you'd like to use. Supercedes agentOptions
+ * @param {CreateActorOptions["agentOptions"]} options.agentOptions - options to set up a new agent
+ * @see {@link HttpAgentOptions}
+ * @param {CreateActorOptions["actorOptions"]} options.actorOptions - options for the Actor
+ * @see {@link ActorConfig}
+ */
 export declare const createActor: (
   canisterId: string | Principal,
-  options: CreateActorOptions
+  options?: CreateActorOptions
 ) => ActorSubclass<_SERVICE>;
 
+/**
+ * Intialized Actor using default settings, ready to talk to a canister using its candid interface
+ * @constructs {@link ActorSubClass}
+ */
 export declare const {{canister_name}}: ActorSubclass<_SERVICE>;

src/dfx/assets/language_bindings/index.js.hbs

@@ -3,26 +3,10 @@ import { Actor, HttpAgent } from "@dfinity/agent";
 // Imports and re-exports candid interface
 import { idlFactory } from "./{{canister_name}}.did.js";
 export { idlFactory } from "./{{canister_name}}.did.js";
+
 // CANISTER_ID is replaced by webpack based on node environment
 export const canisterId = {{{canister_name_process_env}}};
 
-{{{{raw}}}}
-/**
- * @typedef CreateActorOptions
- * @property {(import("@dfinity/agent").Agent)} [agent]
- * @property {(import("@dfinity/agent").HttpAgentOptions)} [agentOptions]
- * @property {(import("@dfinity/agent").ActorConfig)} [actorOptions]
- */
-
-/**
- *
- * @param {string | import("@dfinity/principal").Principal} canisterId Canister ID of Agent
- * @param {CreateActorOptions} options {@link CreateActorOptions}
- * @param {CreateActorOptions["agent"]} [options.agent] An initialized agent
- * @param {CreateActorOptions["agentOptions"]} [options.agentOptions] Options to initialize an {@link HttpAgent}. Overridden if an `agent` is passed.
- * @param {CreateActorOptions["actorOptions"]} [options.actorOptions] Options of to pass during the actor initialization.
- * @return {import("@dfinity/agent").ActorSubclass<import("{{{{/raw}}}}./{{canister_name}}.did.js")._SERVICE>} ActorSubclass configured for the canister
- */
 export const createActor = (canisterId, options = {}) => {
   const agent = options.agent || new HttpAgent({ ...options.agentOptions });
 

src/dfx/src/lib/builders/mod.rs

@@ -260,10 +260,6 @@ fn compile_handlebars_files(
                 format!(
                     r#"
 
-/**
- * A ready-to-use agent for the {0} canister
- * @type {{import("@dfinity/agent").ActorSubclass<import("./{0}.did.js")._SERVICE>}}
-*/
 export const {0} = createActor(canisterId);"#,
                     canister_name
                 )