diff --git a/Cargo.toml b/Cargo.toml index c6513384..32e4f8f3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -23,10 +23,3 @@ anyhow = "1.0" rand = "0.8" arbitrary = "1.3" console = "0.15" -wasm-bindgen = "0.2" -console_error_panic_hook = "0.1" -wasm-bindgen-console-logger = "0.1" -log = "0.4" -getrandom = "0.2" -serde-wasm-bindgen = "0.5" -js-sys = "0.3" diff --git a/tools/README.md b/tools/README.md index e8416d83..42a3a1a5 100644 --- a/tools/README.md +++ b/tools/README.md @@ -2,4 +2,4 @@ - Didc -- multiple-purpose candid tool, including the "DFINITY Interface Description Compiler" - Candiff -- relates candid values that change over time -- @dfinity/didc -- JavaScript library counter part of the didc tool, meant to be used in JavaScript projects. +- [@dfinity/didc](https://www.npmjs.com/package/@dfinity/didc) -- JavaScript library counter part of the didc tool, meant to be used in JavaScript projects. diff --git a/tools/didc-js/wasm-package/Cargo.toml b/tools/didc-js/wasm-package/Cargo.toml index a31c4c10..51670581 100644 --- a/tools/didc-js/wasm-package/Cargo.toml +++ b/tools/didc-js/wasm-package/Cargo.toml @@ -22,12 +22,12 @@ pretty-hex = "0.4.1" hex.workspace = true anyhow.workspace = true rand.workspace = true -wasm-bindgen.workspace = true -console_error_panic_hook.workspace = true -wasm-bindgen-console-logger.workspace = true -log.workspace = true -getrandom = { workspace = true, features = ["js"] } serde.workspace = true -serde-wasm-bindgen.workspace = true thiserror.workspace = true -js-sys.workspace = true +wasm-bindgen = "0.2" +console_error_panic_hook = "0.1" +wasm-bindgen-console-logger = "0.1" +log = "0.4" +getrandom = { version = "0.2", features = ["js"] } +serde-wasm-bindgen = "0.5" +js-sys = "0.3" diff --git a/tools/didc-js/wasm-package/README.md b/tools/didc-js/wasm-package/README.md new file mode 100644 index 00000000..b7cd542c --- /dev/null +++ b/tools/didc-js/wasm-package/README.md @@ -0,0 +1,68 @@ +# @dfinity/didc + +A multi-purpose Candid tool for JavaScript projects, including encoding and decoding Candid values. + +## Usage + +```javascript +import { getServiceMethods, encode, decode } from "@dfinity/didc"; + +// The IDL in text format to be used, most canisters expose their IDL through +// the `candid:service` public metadata. +// +// You can fetch the IDL with an agent call or dfx with `dfx canister metadata candid:service` +export const IDL = ` + type StoreNumberInput = record { + number : nat64; + }; + + service : { + store_number : (input : StoreNumberInput) -> (); + get_number : () -> (nat64) query; + }; +`; + +// Gets the service methods from the IDL and returns an array of the methods. +// +// Example returned value: ['store_number', 'get_number'] +const methods = getServiceMethods(IDL); + +// Encodes a candid text representation of a value to a hex representation. +// +// Example returned value: '4449444c016c01c98dea8b0a7801005a00000000000000' +const encoded encode({ + idl: IDL, + input: "(record { number=90; })", + serviceMethod: "store_number", + targetFormat: "hex", +}); + +// Decodes a hex representation of a candid value to a text representation. +// +// Example returned value: '(90 : nat64)' +const decoded = decode({ + idl: IDL, + input: "4449444c0001785a00000000000000", + serviceMethod: "get_number", + inputFormat: "hex", + targetFormat: "candid", +}); +``` + +### Web Usage + +For web usage, you need to initialize the async wasm module before using the functions. + +```javascript +import init, { encode } from "@dfinity/didc"; + +await init(); + +// then you can use the functions because the wasm will be initialized +const encoded = encode({ + idl: IDL, + input: "(record { number=90; })", + serviceMethod: "store_number", + targetFormat: "hex", +}); +``` diff --git a/tools/didc-js/wasm-package/package.json b/tools/didc-js/wasm-package/package.json index 9c10d252..eddc1b0e 100644 --- a/tools/didc-js/wasm-package/package.json +++ b/tools/didc-js/wasm-package/package.json @@ -14,7 +14,9 @@ ], "packageManager": "pnpm@9.12.2", "files": [ - "dist" + "dist", + "LICENSE", + "README.md" ], "main": "./dist/nodejs/didc.js", "browser": "./dist/web/didc.js",