From fbb709fae6361193265b4e5348af73c06e4537fd Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 20 Sep 2021 15:55:18 -0700 Subject: [PATCH 1/6] chore: update JSDOC type to support plug agent [SDK-127] --- src/dfx/assets/language_bindings/canister.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/dfx/assets/language_bindings/canister.js b/src/dfx/assets/language_bindings/canister.js index fb6d74c664..bef63823c6 100644 --- a/src/dfx/assets/language_bindings/canister.js +++ b/src/dfx/assets/language_bindings/canister.js @@ -7,10 +7,10 @@ export { idlFactory } from './{canister_name}.did.js'; export const canisterId = process.env.{canister_name_uppercase}_CANISTER_ID; /** - * + * * @param {string | import("@dfinity/principal").Principal} canisterId Canister ID of Agent - * @param {{agentOptions?: import("@dfinity/agent").HttpAgentOptions; actorOptions?: import("@dfinity/agent").ActorConfig}} [options] - * @return {import("@dfinity/agent").ActorSubclass} + * @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} */ export const createActor = (canisterId, options) => { const agent = new HttpAgent({ ...options?.agentOptions }); From aef940e501434095c4e771129b5e61e5a43f6624 Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 20 Sep 2021 15:59:20 -0700 Subject: [PATCH 2/6] amended --- src/dfx/assets/language_bindings/canister.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dfx/assets/language_bindings/canister.js b/src/dfx/assets/language_bindings/canister.js index bef63823c6..ca9f116a01 100644 --- a/src/dfx/assets/language_bindings/canister.js +++ b/src/dfx/assets/language_bindings/canister.js @@ -13,7 +13,7 @@ export const canisterId = process.env.{canister_name_uppercase}_CANISTER_ID; * @return {import("@dfinity/agent").ActorSubclass} */ export const createActor = (canisterId, options) => { - const agent = new HttpAgent({ ...options?.agentOptions }); + const agent = options.agent || new HttpAgent({ ...options?.agentOptions }); // Fetch root key for certificate validation during development if(process.env.NODE_ENV !== "production") { From f630dd845d9cc0245258bcb920a055ef57fff453 Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 20 Sep 2021 17:48:13 -0700 Subject: [PATCH 3/6] canister_name --- src/dfx/assets/language_bindings/canister.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/dfx/assets/language_bindings/canister.js b/src/dfx/assets/language_bindings/canister.js index ca9f116a01..c4ff159d8c 100644 --- a/src/dfx/assets/language_bindings/canister.js +++ b/src/dfx/assets/language_bindings/canister.js @@ -10,7 +10,7 @@ export const canisterId = process.env.{canister_name_uppercase}_CANISTER_ID; * * @param {string | import("@dfinity/principal").Principal} canisterId Canister ID of Agent * @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} + * @return {import("@dfinity/agent").ActorSubclass} */ export const createActor = (canisterId, options) => { const agent = options.agent || new HttpAgent({ ...options?.agentOptions }); From 3f9b0d89d2bc09251ebbdc3b516320846c2d4937 Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 10 Oct 2022 10:09:14 -0700 Subject: [PATCH 4/6] updates for consistency --- src/dfx/assets/language_bindings/canister.js | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/dfx/assets/language_bindings/canister.js b/src/dfx/assets/language_bindings/canister.js index 096a35bd88..0b5ec9b3f2 100644 --- a/src/dfx/assets/language_bindings/canister.js +++ b/src/dfx/assets/language_bindings/canister.js @@ -13,14 +13,14 @@ export const canisterId = process.env.{canister_name_uppercase}_CANISTER_ID; * @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} */ -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 = options.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); From 0d4c197f0dd62fb9a7f5d083f2802f73cbd881e3 Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 10 Oct 2022 10:50:45 -0700 Subject: [PATCH 5/6] moving types to .d.ts file --- .../assets/language_bindings/index.d.ts.hbs | 37 +++++++++++++++++-- src/dfx/assets/language_bindings/index.js.hbs | 17 --------- src/dfx/src/lib/builders/mod.rs | 8 +--- 3 files changed, 34 insertions(+), 28 deletions(-) diff --git a/src/dfx/assets/language_bindings/index.d.ts.hbs b/src/dfx/assets/language_bindings/index.d.ts.hbs index fbe6585993..03bd7b7710 100644 --- a/src/dfx/assets/language_bindings/index.d.ts.hbs +++ b/src/dfx/assets/language_bindings/index.d.ts.hbs @@ -1,6 +1,10 @@ -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 { _SERVICE } from './{{canister_name}}.did'; @@ -8,13 +12,38 @@ 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>; diff --git a/src/dfx/assets/language_bindings/index.js.hbs b/src/dfx/assets/language_bindings/index.js.hbs index a6bada127d..6b09e6e61b 100644 --- a/src/dfx/assets/language_bindings/index.js.hbs +++ b/src/dfx/assets/language_bindings/index.js.hbs @@ -6,23 +6,6 @@ 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} ActorSubclass configured for the canister - */ export const createActor = (canisterId, options = {}) => { const agent = options.agent || new HttpAgent({ ...options.agentOptions }); diff --git a/src/dfx/src/lib/builders/mod.rs b/src/dfx/src/lib/builders/mod.rs index a67ddf2ce2..41980463c7 100644 --- a/src/dfx/src/lib/builders/mod.rs +++ b/src/dfx/src/lib/builders/mod.rs @@ -258,13 +258,7 @@ fn compile_handlebars_files( "".to_string() } else { format!( - r#" - -/** - * A ready-to-use agent for the {0} canister - * @type {{import("@dfinity/agent").ActorSubclass}} -*/ -export const {0} = createActor(canisterId);"#, + r#"export const {0} = createActor(canisterId);"#, canister_name ) .to_string() From 45a8a5be9915ec873d96408f2fb7ce050b233321 Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 10 Oct 2022 11:01:25 -0700 Subject: [PATCH 6/6] formatting + IDL --- src/dfx/assets/language_bindings/index.d.ts.hbs | 1 + src/dfx/assets/language_bindings/index.js.hbs | 1 + src/dfx/src/lib/builders/mod.rs | 4 +++- 3 files changed, 5 insertions(+), 1 deletion(-) diff --git a/src/dfx/assets/language_bindings/index.d.ts.hbs b/src/dfx/assets/language_bindings/index.d.ts.hbs index 03bd7b7710..cec9eaccaa 100644 --- a/src/dfx/assets/language_bindings/index.d.ts.hbs +++ b/src/dfx/assets/language_bindings/index.d.ts.hbs @@ -5,6 +5,7 @@ import type { Agent, } from "@dfinity/agent"; import type { Principal } from "@dfinity/principal"; +import type { IDL } from "@dfinity/candid"; import { _SERVICE } from './{{canister_name}}.did'; diff --git a/src/dfx/assets/language_bindings/index.js.hbs b/src/dfx/assets/language_bindings/index.js.hbs index 6b09e6e61b..472c08d38a 100644 --- a/src/dfx/assets/language_bindings/index.js.hbs +++ b/src/dfx/assets/language_bindings/index.js.hbs @@ -3,6 +3,7 @@ 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}}}; diff --git a/src/dfx/src/lib/builders/mod.rs b/src/dfx/src/lib/builders/mod.rs index 41980463c7..bba486ff4f 100644 --- a/src/dfx/src/lib/builders/mod.rs +++ b/src/dfx/src/lib/builders/mod.rs @@ -258,7 +258,9 @@ fn compile_handlebars_files( "".to_string() } else { format!( - r#"export const {0} = createActor(canisterId);"#, + r#" + +export const {0} = createActor(canisterId);"#, canister_name ) .to_string()