From 8e67974a9f979e9cab4f705febc358da61837031 Mon Sep 17 00:00:00 2001 From: Kyle Peacock Date: Mon, 10 Oct 2022 12:30:20 -0700 Subject: [PATCH] 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 ++--- .../assets/language_bindings/index.d.ts.hbs | 38 +++++++++++++++++-- src/dfx/assets/language_bindings/index.js.hbs | 18 +-------- src/dfx/src/lib/builders/mod.rs | 4 -- 4 files changed, 40 insertions(+), 30 deletions(-) diff --git a/src/dfx/assets/language_bindings/canister.js b/src/dfx/assets/language_bindings/canister.js index a8aae8dbe6..0b5ec9b3f2 100644 --- a/src/dfx/assets/language_bindings/canister.js +++ b/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} */ -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); diff --git a/src/dfx/assets/language_bindings/index.d.ts.hbs b/src/dfx/assets/language_bindings/index.d.ts.hbs index fbe6585993..cec9eaccaa 100644 --- a/src/dfx/assets/language_bindings/index.d.ts.hbs +++ b/src/dfx/assets/language_bindings/index.d.ts.hbs @@ -1,6 +1,11 @@ -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'; @@ -8,13 +13,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..472c08d38a 100644 --- a/src/dfx/assets/language_bindings/index.js.hbs +++ b/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} 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..bba486ff4f 100644 --- a/src/dfx/src/lib/builders/mod.rs +++ b/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}} -*/ export const {0} = createActor(canisterId);"#, canister_name )