Merge pull request #20 from NatLabs/dev

[Feat]: Add support for converting between candid and CBOR

.github/workflows/makefile.yml

@@ -24,21 +24,19 @@ jobs:
                 curl https://wasmtime.dev/install.sh -sSf | bash
                 echo "$HOME/.wasmtime/bin" >> $GITHUB_PATH
   
-            - name: Install mocv
-              run: |
                 npm --yes -g i mocv
 
             - name: Select mocv version
-              run: mocv use 0.10.0
+              run: mocv use 0.10.3
 
             - name: install mops
               run: |
-                  npm --yes -g i ic-mops
+                  npm --yes -g i ic-mops@0.34.3
                   mops i
                   mops sources
 
-            - name: Detect Warnings
-              run: make no-warn
+            # - name: Detect Warnings
+            #   run: make no-warn
 
             - name: Run Tests
               run: mops test

benchmarks/serde.bench.mo

@@ -30,13 +30,96 @@ actor {
 
     public query func cycles() : async Nat { Cycles.balance()};
 
-    public query func deserialize(n: Nat) : async (Nat64, Nat, Nat, Nat) {
+    type Benchmark = {
+        calls: Nat64;
+        heap: Nat;
+        memory: Nat;
+        cycles: Nat;
+    };
+
+    func benchmark(fn: () -> ()): Benchmark {
         let init_cycles = Cycles.balance();
 
         let init_heap = Prim.rts_heap_size();
         let init_memory = Prim.rts_memory_size();
 
-        let calls = IC.countInstructions(
+        let calls = IC.countInstructions(fn);
+
+        {
+            calls;
+            heap = Prim.rts_heap_size() - init_heap;
+            memory = Prim.rts_memory_size() - init_memory;
+            cycles = init_cycles - Cycles.balance();
+        }
+    };
+
+    public query func serialize(n: Nat): async Benchmark {
+        benchmark(
+            func(){
+                let admin_record : Record = {
+                    group = "admins";
+                    users = ?[{
+                        name = "John";
+                        age = 32;
+                        permission = #admin;
+                    }];
+                };
+
+                let user_record : Record = {
+                    group = "users";
+                    users = ?[{
+                        name = "Ali";
+                        age = 28;
+                        permission = #read_all;
+                    }, {
+                        name = "James";
+                        age = 40;
+                        permission = #write_all;
+                    }];
+                };
+
+                let empty_record : Record = {
+                    group = "empty";
+                    users = ?[];
+                };
+
+                let null_record : Record = {
+                    group = "null";
+                    users = null;
+                };
+
+                let base_record : Record = {
+                    group = "base";
+                    users = ?[{
+                        name = "Henry";
+                        age = 32;
+                        permission = #read(["posts", "comments"]);
+                    }, {
+                        name = "Steven";
+                        age = 32;
+                        permission = #write(["posts", "comments"]);
+                    }];
+                };
+
+                let records : [Record] = [
+                    null_record,
+                    empty_record,
+                    admin_record,
+                    user_record,
+                    base_record,
+                ];
+
+                for (_ in Iter.range(1, n)){
+                    let blob = to_candid (records);
+                    let #ok(candid) = Candid.decode(blob, [], null);
+                    Debug.print(debug_show (candid));
+                };
+            }
+        )
+    };
+
+    public query func deserialize(n: Nat) : async Benchmark {
+        benchmark(
             func() {
 
                 let admin_record_candid : Candid = #Record([
@@ -79,8 +162,6 @@ actor {
                 };
             }
         );
-
-        (calls, Prim.rts_heap_size() - init_heap, Prim.rts_memory_size() - init_memory, init_cycles - Cycles.balance())
     };
 
 };

mops.toml

@@ -1,15 +1,18 @@
 [package]
 name = "serde"
-version = "2.0.4"
+version = "2.1.0"
 description = "A serialisation and deserialisation library for Motoko."
 repository = "https://github.com/NatLabs/serde"
-keywords = [ "json", "candid", "parser", "urlencoded", "serialization" ]
+keywords = [ "json", "candid", "cbor", "urlencoded", "serialization" ]
 
 [dependencies]
-base = "0.10.0"
+base = "0.10.3"
 itertools = "0.1.2"
 candid = "1.0.2"
 xtended-numbers = "0.2.1"
-json = "https://github.com/aviate-labs/json.mo#v0.2.0"
-parser-combinators = "https://github.com/aviate-labs/parser-combinators.mo#v0.1.2"
-map = "9.0.0"
+json = "https://github.com/aviate-labs/json.mo#v0.2.0@99ae3761c09622a98ae45ebd9ad68f01353df336"
+parser-combinators = "https://github.com/aviate-labs/parser-combinators.mo#v0.1.2@6a331bf78e9dcd7623977f06c8e561fd1a8c0103"
+cbor = "0.1.3"
+
+[dev-dependencies]
+test = "1.2.0"

readme.md

@@ -2,11 +2,30 @@
 
 An efficient serialization and deserialization library for Motoko.
 
-<!-- 👉 [Demo on Motoko Playground](https://m7sm4-2iaaa-aaaab-qabra-cai.raw.ic0.app/?tag=3196250840) -->
+The library contains four modules:
+- **Candid**
+    - `fromText()` - Converts [Candid text](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-2/2.4-intro-candid/#candid-textual-values) to its serialized form.
+    - `toText()` - Converts serialized candid to its [textual representation](https://internetcomputer.org/docs/current/tutorials/developer-journey/level-2/2.4-intro-candid/#candid-textual-values).
+    - `encode()` - Converts the [Candid variant](./src/Candid/Types.mo#L6) to a blob.
+    - `decode()` - Converts a blob to the [Candid variant](./src/Candid/Types.mo#L6).
+
+- **CBOR**
+    - `encode()` - Converts serialized candid to CBOR.
+    - `decode()` - Converts CBOR to a serialized candid.
+
+- **JSON**
+    - `fromText()` - Converts JSON text to serialized candid.
+    - `toText()` - Converts serialized candid to JSON text.
+
+- **URL-Encoded Pairs**
+    - `fromText()` - Converts URL-encoded text to serialized candid.
+    - `toText()` - Converts serialized candid to URL-encoded text.
+
 
 ## Getting Started
 
-### Installation
+### Installation 
+[![mops](https://oknww-riaaa-aaaam-qaf6a-cai.raw.ic0.app/badge/mops/serde)](https://mops.one/serde)
 
 1. Install [`mops`](https://j4mwm-bqaaa-aaaam-qajbq-cai.ic0.app/#/docs/install).
 2. Inside your project directory, run: 
@@ -18,15 +37,15 @@ mops install serde
 
 To start, import the necessary modules:
 ```motoko
-import { JSON; Candid; UrlEncoded } from "mo:serde";
+import { JSON; Candid; CBOR; UrlEncoded } from "mo:serde";
 ```
 
 #### JSON
-> The API for all serde module is the same, so the following code can be used for converting data between the other modules (Candid and URL-Encoded Pairs).
+> The following code can be used for converting data between the other modules (Candid and URL-Encoded Pairs).
 
 **Example: JSON to Motoko**
 
-1. **Defining Data Type**: This critical step informs the conversion functions (`from_candid`` and `to_candid`) about how to handle the data.
+1. **Defining Data Type**: This critical step informs the conversion functions (`from_candid` and `to_candid`) about how to handle the data.
 
    Consider the following JSON data:
    ```json