From 93cc95dcc1639faeb9d4ba96e238ffc42480a653 Mon Sep 17 00:00:00 2001 From: Nathan Mc Grath Date: Tue, 6 Sep 2022 18:17:57 +0200 Subject: [PATCH 1/3] fix(typescript): add index.d.ts file for type safety when importing generated declarations fixes #2537 --- CHANGELOG.md | 4 +++ docs/cli-reference/dfx-generate.md | 12 +++---- e2e/tests-dfx/generate.bash | 32 +++++++++++++++++++ .../assets/language_bindings/index.d.ts.hbs | 16 ++++++++++ src/dfx/src/lib/models/canister.rs | 1 + 5 files changed, 59 insertions(+), 6 deletions(-) create mode 100755 e2e/tests-dfx/generate.bash create mode 100644 src/dfx/assets/language_bindings/index.d.ts.hbs diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f2d752ab5..5499e75888 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,6 +84,10 @@ It is now possible to set the http adapter's log level in dfx.json or in network By default, a log level of "error" is used, in order to keep the output of a first-time `dfx start` minimal. Change it to "debug" for more verbose logging. +### fix(typescript): add index.d.ts file for type safety when importing generated declarations + +Adds an index.d.ts file to the generated declarations, allowing for better type safety in TypeScript projects. + ### feat: generate secp256k1 keys by default When creating a new identity with `dfx identity new`, whereas previously it would have generated an Ed25519 key, it now generates a secp256k1 key. This is to enable users to write down a BIP39-style seed phrase, to recover their key in case of emergency, which will be printed when the key is generated and can be used with a new `--seed-phrase` flag in `dfx identity import`. `dfx identity import` is however still capable of importing an Ed25519 key. diff --git a/docs/cli-reference/dfx-generate.md b/docs/cli-reference/dfx-generate.md index 6bbf8cc86c..bc0463be8f 100644 --- a/docs/cli-reference/dfx-generate.md +++ b/docs/cli-reference/dfx-generate.md @@ -43,12 +43,12 @@ The behavior of `dfx generate` is controlled by the `dfx.json` configuration fil Outputs from `dfx generate`: -| Language | File | -|------------------|-----------------------------------------| -| `JavaScript(js)` | `index.js` and `.did.js` | -| `TypeScript(ts)` | `.did.ts` | -| `Candid(did)` | `.did` | -| `Motoko(mo)` | `.mo` | +| Language | File | +|------------------|------------------------------------------| +| `JavaScript(js)` | `index.js` and `.did.js` | +| `TypeScript(ts)` | `index.d.ts` and `.did.ts`| +| `Candid(did)` | `.did` | +| `Motoko(mo)` | `.mo` | ## Examples diff --git a/e2e/tests-dfx/generate.bash b/e2e/tests-dfx/generate.bash new file mode 100755 index 0000000000..96ba153af7 --- /dev/null +++ b/e2e/tests-dfx/generate.bash @@ -0,0 +1,32 @@ +#!/usr/bin/env bats + +load ../utils/_ + +setup() { + standard_setup + + dfx_new hello +} + +teardown() { + dfx_stop + + standard_teardown +} + +@test "dfx generate creates files" { + dfx_start + dfx canister create --all + dfx build + dfx canister install --all + + dfx --version + dfx generate + + assert_command ls src/declarations/hello_backend + assert_match "hello_backend.did" + assert_match "hello_backend.did.js" + assert_match "hello_backend.did.d.ts" + assert_match "index.js" + assert_match "index.d.ts" +} diff --git a/src/dfx/assets/language_bindings/index.d.ts.hbs b/src/dfx/assets/language_bindings/index.d.ts.hbs new file mode 100644 index 0000000000..67b9b56b57 --- /dev/null +++ b/src/dfx/assets/language_bindings/index.d.ts.hbs @@ -0,0 +1,16 @@ +import { ActorSubclass, HttpAgentOptions, ActorConfig } from '@dfinity/agent'; +import { Principal } from '@dfinity/principal'; + +import { _SERVICE } from './{{canister_name}}.did'; + +export declare interface CreateActorOptions { + agentOptions?: HttpAgentOptions; + actorOptions?: ActorConfig; +} + +export declare const createActor: ( + canisterId: string | Principal, + options: CreateActorOptions +) => ActorSubclass<_SERVICE>; + +export declare const {{canister_name}}: ActorSubclass<_SERVICE>; diff --git a/src/dfx/src/lib/models/canister.rs b/src/dfx/src/lib/models/canister.rs index c58fedd401..80a1f9bfb5 100644 --- a/src/dfx/src/lib/models/canister.rs +++ b/src/dfx/src/lib/models/canister.rs @@ -596,6 +596,7 @@ fn build_canister_js(canister_id: &CanisterId, canister_info: &CanisterInfo) -> } // skip "index.js.hbs" => {} + "index.d.ts.hbs" => {} _ => unreachable!(), } } From 2306f79ad0f6fd59f642788c8810d7d55e943fce Mon Sep 17 00:00:00 2001 From: Nathan Mc Grath Date: Wed, 21 Sep 2022 15:12:10 +0200 Subject: [PATCH 2/3] docs(dfx): update docs --- docs/dfx-json-schema.json | 56 ++++++++++++++++++++++++++++++++-- docs/networks-json-schema.json | 46 +++++++++++++++++++++++++++- 2 files changed, 98 insertions(+), 4 deletions(-) diff --git a/docs/dfx-json-schema.json b/docs/dfx-json-schema.json index 259ad5a928..44b5593365 100644 --- a/docs/dfx-json-schema.json +++ b/docs/dfx-json-schema.json @@ -192,7 +192,7 @@ }, "candid": { "title": "Candid File", - "description": "Path to this canister's candid interface declaration.", + "description": "Path to this canister's candid interface declaration. A URL to a candid file is also acceptable.", "type": "string" }, "type": { @@ -203,7 +203,7 @@ }, "wasm": { "title": "WASM Path", - "description": "Path to WASM to be installed.", + "description": "Path to WASM to be installed. URLs to a WASM module are also acceptable.", "type": "string" } } @@ -312,6 +312,12 @@ "type": "null" } ] + }, + "shrink": { + "title": "Shrink Canister WASM", + "description": "Whether run `ic-wasm shrink` after building the Canister. Default is true.", + "default": true, + "type": "boolean" } } }, @@ -482,8 +488,18 @@ "properties": { "enabled": { "title": "Enable HTTP Adapter", - "default": false, + "default": true, "type": "boolean" + }, + "log_level": { + "title": "Logging Level", + "description": "The logging level of the adapter.", + "default": "error", + "allOf": [ + { + "$ref": "#/definitions/HttpAdapterLogLevel" + } + ] } } }, @@ -491,6 +507,17 @@ "title": "Local Replica Configuration", "type": "object", "properties": { + "log_level": { + "description": "Run replica with the provided log level. Default is 'error'. Debug prints still get displayed", + "anyOf": [ + { + "$ref": "#/definitions/ReplicaLogLevel" + }, + { + "type": "null" + } + ] + }, "port": { "description": "Port the replica listens on.", "type": [ @@ -611,6 +638,18 @@ } } }, + "HttpAdapterLogLevel": { + "description": "Represents the log level of the HTTP adapter.", + "type": "string", + "enum": [ + "critical", + "error", + "warning", + "info", + "debug", + "trace" + ] + }, "InitializationValues": { "title": "Initial Resource Allocations", "type": "object", @@ -671,6 +710,17 @@ "Release" ] }, + "ReplicaLogLevel": { + "type": "string", + "enum": [ + "critical", + "error", + "warning", + "info", + "debug", + "trace" + ] + }, "ReplicaSubnetType": { "type": "string", "enum": [ diff --git a/docs/networks-json-schema.json b/docs/networks-json-schema.json index a18ccc4931..31ea534f55 100644 --- a/docs/networks-json-schema.json +++ b/docs/networks-json-schema.json @@ -83,8 +83,18 @@ "properties": { "enabled": { "title": "Enable HTTP Adapter", - "default": false, + "default": true, "type": "boolean" + }, + "log_level": { + "title": "Logging Level", + "description": "The logging level of the adapter.", + "default": "error", + "allOf": [ + { + "$ref": "#/definitions/HttpAdapterLogLevel" + } + ] } } }, @@ -92,6 +102,17 @@ "title": "Local Replica Configuration", "type": "object", "properties": { + "log_level": { + "description": "Run replica with the provided log level. Default is 'error'. Debug prints still get displayed", + "anyOf": [ + { + "$ref": "#/definitions/ReplicaLogLevel" + }, + { + "type": "null" + } + ] + }, "port": { "description": "Port the replica listens on.", "type": [ @@ -212,6 +233,18 @@ } } }, + "HttpAdapterLogLevel": { + "description": "Represents the log level of the HTTP adapter.", + "type": "string", + "enum": [ + "critical", + "error", + "warning", + "info", + "debug", + "trace" + ] + }, "NetworkType": { "title": "Network Type", "description": "Type 'ephemeral' is used for networks that are regularly reset. Type 'persistent' is used for networks that last for a long time and where it is preferred that canister IDs get stored in source control.", @@ -221,6 +254,17 @@ "persistent" ] }, + "ReplicaLogLevel": { + "type": "string", + "enum": [ + "critical", + "error", + "warning", + "info", + "debug", + "trace" + ] + }, "ReplicaSubnetType": { "type": "string", "enum": [ From b4292ce4668c814417f8ac7646bae56bf09770aa Mon Sep 17 00:00:00 2001 From: Nathan Mc Grath Date: Thu, 22 Sep 2022 15:31:06 +0200 Subject: [PATCH 3/3] Update e2e/tests-dfx/generate.bash Co-authored-by: Eric Swanson <64809312+ericswanson-dfinity@users.noreply.github.com> --- e2e/tests-dfx/generate.bash | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/e2e/tests-dfx/generate.bash b/e2e/tests-dfx/generate.bash index 96ba153af7..33a1ffcc57 100755 --- a/e2e/tests-dfx/generate.bash +++ b/e2e/tests-dfx/generate.bash @@ -23,10 +23,9 @@ teardown() { dfx --version dfx generate - assert_command ls src/declarations/hello_backend - assert_match "hello_backend.did" - assert_match "hello_backend.did.js" - assert_match "hello_backend.did.d.ts" - assert_match "index.js" - assert_match "index.d.ts" + assert_file_exists "src/declarations/hello_backend/hello_backend.did" + assert_file_exists "src/declarations/hello_backend/hello_backend.did.js" + assert_file_exists "src/declarations/hello_backend/hello_backend.did.d.ts" + assert_file_exists "src/declarations/hello_backend/index.js" + assert_file_exists "src/declarations/hello_backend/index.d.ts" }