feat(didc-js): Javascript multi purpose library with candid utils (#577)

* feat(didc-js): Javascript multi purpose library with candid utils

* use latest pnpm

* remove idl2json

* update build

* allow decoding with the service method arg type

* PR comments

* include dist folder in publish

Cargo.toml

@@ -5,6 +5,7 @@ members = [
     "rust/candid_derive",
     "rust/ic_principal",
     "tools/didc",
+    "tools/didc-js/wasm-package",
 ]
 resolver = "2"
 

tools/README.md

@@ -2,3 +2,4 @@
 
 - Didc -- multiple-purpose candid tool, including the "DFINITY Interface Description Compiler"
 - Candiff -- relates candid values that change over time
+- [@dfinity/didc](https://www.npmjs.com/package/@dfinity/didc) -- JavaScript library counter part of the didc tool, meant to be used in JavaScript projects.

tools/didc-js/.gitignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+pkg

tools/didc-js/.node-version

@@ -0,0 +1 @@
+20.18

tools/didc-js/.npmrc

@@ -0,0 +1,4 @@
+engine-strict=true
+enable-pre-post-scripts=true
+package-manager-strict=true
+manage-package-manager-versions=true

tools/didc-js/LICENSE

@@ -0,0 +1,208 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+   "License" shall mean the terms and conditions for use, reproduction, and
+   distribution as defined by Sections 1 through 9 of this document.
+
+   "Licensor" shall mean the copyright owner or entity authorized by the
+   copyright owner that is granting the License.
+
+   "Legal Entity" shall mean the union of the acting entity and all other
+   entities that control, are controlled by, or are under common control with
+   that entity. For the purposes of this definition, "control" means (i) the
+   power, direct or indirect, to cause the direction or management of such
+   entity, whether by contract or otherwise, or (ii) ownership of fifty percent
+   (50%) or more of the outstanding shares, or (iii) beneficial ownership of
+   such entity.
+
+   "You" (or "Your") shall mean an individual or Legal Entity exercising
+   permissions granted by this License.
+
+   "Source" form shall mean the preferred form for making modifications,
+   including but not limited to software source code, documentation source, and
+   configuration files.
+
+   "Object" form shall mean any form resulting from mechanical transformation
+   or translation of a Source form, including but not limited to compiled
+   object code, generated documentation, and conversions to other media types.
+
+   "Work" shall mean the work of authorship, whether in Source or Object form,
+   made available under the License, as indicated by a copyright notice that is
+   included in or attached to the work (an example is provided in the Appendix
+   below).
+
+   "Derivative Works" shall mean any work, whether in Source or Object form,
+   that is based on (or derived from) the Work and for which the editorial
+   revisions, annotations, elaborations, or other modifications represent, as a
+   whole, an original work of authorship. For the purposes of this License,
+   Derivative Works shall not include works that remain separable from, or
+   merely link (or bind by name) to the interfaces of, the Work and Derivative
+   Works thereof.
+
+   "Contribution" shall mean any work of authorship, including the original
+   version of the Work and any modifications or additions to that Work or
+   Derivative Works thereof, that is intentionally submitted to Licensor for
+   inclusion in the Work by the copyright owner or by an individual or Legal
+   Entity authorized to submit on behalf of the copyright owner. For the
+   purposes of this definition, "submitted" means any form of electronic,
+   verbal, or written communication sent to the Licensor or its
+   representatives, including but not limited to communication on electronic
+   mailing lists, source code control systems, and issue tracking systems that
+   are managed by, or on behalf of, the Licensor for the purpose of discussing
+   and improving the Work, but excluding communication that is conspicuously
+   marked or otherwise designated in writing by the copyright owner as "Not a
+   Contribution."
+
+   "Contributor" shall mean Licensor and any individual or Legal Entity on
+   behalf of whom a Contribution has been received by Licensor and subsequently
+   incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable copyright license to
+   reproduce, prepare Derivative Works of, publicly display, publicly perform,
+   sublicense, and distribute the Work and such Derivative Works in Source or
+   Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this
+   License, each Contributor hereby grants to You a perpetual, worldwide,
+   non-exclusive, no-charge, royalty-free, irrevocable (except as stated in
+   this section) patent license to make, have made, use, offer to sell, sell,
+   import, and otherwise transfer the Work, where such license applies only to
+   those patent claims licensable by such Contributor that are necessarily
+   infringed by their Contribution(s) alone or by combination of their
+   Contribution(s) with the Work to which such Contribution(s) was submitted.
+   If You institute patent litigation against any entity (including a
+   cross-claim or counterclaim in a lawsuit) alleging that the Work or a
+   Contribution incorporated within the Work constitutes direct or contributory
+   patent infringement, then any patent licenses granted to You under this
+   License for that Work shall terminate as of the date such litigation is
+   filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or
+   Derivative Works thereof in any medium, with or without modifications, and
+   in Source or Object form, provided that You meet the following conditions:
+
+   a. You must give any other recipients of the Work or Derivative Works a
+      copy of this License; and
+
+   b. You must cause any modified files to carry prominent notices stating
+      that You changed the files; and
+
+   c. You must retain, in the Source form of any Derivative Works that You
+      distribute, all copyright, patent, trademark, and attribution notices
+      from the Source form of the Work, excluding those notices that do not
+      pertain to any part of the Derivative Works; and
+
+   d. If the Work includes a "NOTICE" text file as part of its distribution,
+      then any Derivative Works that You distribute must include a readable
+      copy of the attribution notices contained within such NOTICE file,
+      excluding those notices that do not pertain to any part of the Derivative
+      Works, in at least one of the following places: within a NOTICE text file
+      distributed as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or, within a
+      display generated by the Derivative Works, if and wherever such
+      third-party notices normally appear. The contents of the NOTICE file are
+      for informational purposes only and do not modify the License. You may
+      add Your own attribution notices within Derivative Works that You
+      distribute, alongside or as an addendum to the NOTICE text from the Work,
+      provided that such additional attribution notices cannot be construed as
+      modifying the License.
+
+      You may add Your own copyright statement to Your modifications and may
+      provide additional or different license terms and conditions for use,
+      reproduction, or distribution of Your modifications, or for any such
+      Derivative Works as a whole, provided Your use, reproduction, and
+      distribution of the Work otherwise complies with the conditions stated in
+      this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any
+   Contribution intentionally submitted for inclusion in the Work by You to the
+   Licensor shall be under the terms and conditions of this License, without
+   any additional terms or conditions. Notwithstanding the above, nothing
+   herein shall supersede or modify the terms of any separate license agreement
+   you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names,
+   trademarks, service marks, or product names of the Licensor, except as
+   required for reasonable and customary use in describing the origin of the
+   Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
+   writing, Licensor provides the Work (and each Contributor provides its
+   Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+   KIND, either express or implied, including, without limitation, any
+   warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or
+   FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining
+   the appropriateness of using or redistributing the Work and assume any risks
+   associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in
+   tort (including negligence), contract, or otherwise, unless required by
+   applicable law (such as deliberate and grossly negligent acts) or agreed to
+   in writing, shall any Contributor be liable to You for damages, including
+   any direct, indirect, special, incidental, or consequential damages of any
+   character arising as a result of this License or out of the use or inability
+   to use the Work (including but not limited to damages for loss of goodwill,
+   work stoppage, computer failure or malfunction, or any and all other
+   commercial damages or losses), even if such Contributor has been advised of
+   the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or
+   Derivative Works thereof, You may choose to offer, and charge a fee for,
+   acceptance of support, warranty, indemnity, or other liability obligations
+   and/or rights consistent with this License. However, in accepting such
+   obligations, You may act only on Your own behalf and on Your sole
+   responsibility, not on behalf of any other Contributor, and only if You
+   agree to indemnify, defend, and hold each Contributor harmless for any
+   liability incurred by, or claims asserted against, such Contributor by
+   reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+LLVM EXCEPTIONS TO THE APACHE 2.0 LICENSE
+
+As an exception, if, as a result of your compiling your source code, portions
+of this Software are embedded into an Object form of such source code, you may
+redistribute such embedded portions in such Object form without complying with
+the conditions of Sections 4(a), 4(b) and 4(d) of the License.
+
+In addition, if you combine or link compiled forms of this Software with
+software that is licensed under the GPLv2 ("Combined Software") and if a court
+of competent jurisdiction determines that the patent provision (Section 3), the
+indemnity provision (Section 9) or other Section of the License conflicts with
+the conditions of the GPLv2, you may retroactively and prospectively choose to
+deem waived or otherwise exclude such Section(s) of the License, but only in
+their entirety and only with respect to the Combined Software.
+
+END OF LLVM EXCEPTIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate
+notice, with the fields enclosed by brackets "[]" replaced with your own
+identifying information. (Don't include the brackets!)  The text should be
+enclosed in the appropriate comment syntax for the file format. We also
+recommend that a file or class name and description of purpose be included on
+the same "printed page" as the copyright notice for easier identification
+within third-party archives.
+
+Copyright 2024 DFINITY Stiftung
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+
+END OF APPENDIX

tools/didc-js/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 <canisterId> 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",
+});
+```

tools/didc-js/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "didc-js",
+  "description": "Workspace for the didc-js project.",
+  "private": true,
+  "packageManager": "pnpm@9.12.2",
+  "engines": {
+    "node": "^20",
+    "pnpm": "^9",
+    "npm": "please use pnpm",
+    "yarn": "please use pnpm"
+  },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "build": "pnpm run -r build",
+    "dev": "pnpm run -r dev",
+    "test": "pnpm run -r test"
+  },
+  "devDependencies": {
+    "@types/jest": "29.5.14",
+    "@types/node": "22.7.9",
+    "jest": "29.7.0",
+    "terser": "5.36.0",
+    "ts-jest": "29.2.5",
+    "ts-node": "10.9.2",
+    "tslib": "2.8.0",
+    "typescript": "5.6.3",
+    "wasm-pack": "0.13.0"
+  }
+}