Merge pull request #2672 from demergent-labs/stable_b_tree_map_js_docs

StableBTreeMap JSDocs beautiful and `null` return type changed to `undefined`; `Uint8Array` optimizations (breaking changes)
demergent-labs · Feb 14, 2025 · d96df0f · d96df0f
2 parents 67694c3 + 8234a3f
commit d96df0f
Show file tree

Hide file tree

Showing 49 changed files with 418 additions and 300 deletions.
diff --git a/canister_templates/experimental.wasm b/canister_templates/experimental.wasm
diff --git a/canister_templates/stable.wasm b/canister_templates/stable.wasm
diff --git a/examples/stable/test/end_to_end/candid_rpc/audio_recorder/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/audio_recorder/src/index.ts
@@ -55,7 +55,7 @@ export default class {
     @query([IDL.Principal], IDL.Opt(User))
     readUserById(id: Principal): [User] | [] {
         const result = this.users.get(id);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -66,7 +66,7 @@ export default class {
     deleteUser(id: Principal): User {
         const user = this.users.get(id);
 
-        if (user === null) {
+        if (user === undefined) {
             throw new Error(`User does not exist: ${id.toText()}`);
         }
 
@@ -87,7 +87,7 @@ export default class {
     ): Recording {
         const user = this.users.get(userId);
 
-        if (user === null) {
+        if (user === undefined) {
             throw new Error(`User does not exist: ${userId.toText()}`);
         }
 
@@ -120,7 +120,7 @@ export default class {
     @query([IDL.Principal], IDL.Opt(Recording))
     readRecordingById(id: Principal): [Recording] | [] {
         const result = this.recordings.get(id);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -131,13 +131,13 @@ export default class {
     deleteRecording(id: Principal): Recording {
         const recording = this.recordings.get(id);
 
-        if (recording === null) {
+        if (recording === undefined) {
             throw new Error(`Recording does not exist: ${id.toText()}`);
         }
 
         const user = this.users.get(recording.userId);
 
-        if (user === null) {
+        if (user === undefined) {
             throw new Error(
                 `User does not exist: ${recording.userId.toText()}`
             );

diff --git a/examples/stable/test/end_to_end/candid_rpc/complex_init/src/complex_init/index.ts b/examples/stable/test/end_to_end/candid_rpc/complex_init/src/complex_init/index.ts
@@ -11,9 +11,13 @@ export default class {
 
     @init([IDL.Tuple(IDL.Text, User)], { manual: true })
     init(): void {
+        const argData = msgArgData();
+
         const tuple = IDL.decode(
             [IDL.Tuple(IDL.Text, User)],
-            new Uint8Array(msgArgData()).buffer
+            argData.buffer instanceof ArrayBuffer
+                ? argData.buffer
+                : new Uint8Array(argData).buffer
         )[0] as [string, User];
 
         this.greeting = tuple[0];

diff --git a/examples/stable/test/end_to_end/candid_rpc/ethereum_json_rpc/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/ethereum_json_rpc/src/index.ts
@@ -26,7 +26,7 @@ export default class {
     async ethGetBalance(ethereumAddress: string): Promise<string> {
         const url = this.stableStorage.get('ethereumUrl');
 
-        if (url === null) {
+        if (url === undefined) {
             throw new Error('ethereumUrl is not defined');
         }
 
@@ -37,7 +37,7 @@ export default class {
     async ethGetBlockByNumber(number: number): Promise<string> {
         const urlOpt = this.stableStorage.get('ethereumUrl');
 
-        if (urlOpt === null) {
+        if (urlOpt === undefined) {
             throw new Error('ethereumUrl is not defined');
         }
 

diff --git a/examples/stable/test/end_to_end/candid_rpc/func_types/canisters/func_types/index.ts b/examples/stable/test/end_to_end/candid_rpc/func_types/canisters/func_types/index.ts
@@ -69,7 +69,7 @@ export default class {
     @query([], StableFunc)
     getStableFunc(): StableFunc {
         const stableFunc = this.stableStorage.get('stableFunc');
-        if (stableFunc === null) {
+        if (stableFunc === undefined) {
             return [Principal.from('aaaaa-aa'), 'raw_rand'];
         }
         return stableFunc;

diff --git a/examples/stable/test/end_to_end/candid_rpc/ic_api/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/ic_api/src/index.ts
@@ -94,9 +94,13 @@ export default class {
 
     @query([IDL.Text], IDL.Empty, { manual: true })
     msgReject(): void {
+        const argData = msgArgData();
+
         const message = IDL.decode(
             [IDL.Text],
-            new Uint8Array(msgArgData()).buffer
+            argData.buffer instanceof ArrayBuffer
+                ? argData.buffer
+                : new Uint8Array(argData).buffer
         )[0] as string;
 
         msgReject(message);

diff --git a/examples/stable/test/end_to_end/candid_rpc/manual_reply/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/manual_reply/src/index.ts
@@ -98,9 +98,13 @@ export default class {
     // Updates
     @update([IDL.Text], IDL.Text, { manual: true })
     manualUpdate(): void {
+        const argData = msgArgData();
+
         const message = IDL.decode(
             [IDL.Text],
-            new Uint8Array(msgArgData()).buffer
+            argData.buffer instanceof ArrayBuffer
+                ? argData.buffer
+                : new Uint8Array(argData).buffer
         )[0] as string;
 
         if (message === 'reject') {
@@ -196,9 +200,13 @@ export default class {
     // Queries
     @query([IDL.Text], IDL.Text, { manual: true })
     manualQuery(): void {
+        const argData = msgArgData();
+
         const message = IDL.decode(
             [IDL.Text],
-            new Uint8Array(msgArgData()).buffer
+            argData.buffer instanceof ArrayBuffer
+                ? argData.buffer
+                : new Uint8Array(argData).buffer
         )[0] as string;
 
         if (message === 'reject') {

diff --git a/examples/stable/test/end_to_end/candid_rpc/motoko_examples/cert-var/test/tests.ts b/examples/stable/test/end_to_end/candid_rpc/motoko_examples/cert-var/test/tests.ts
@@ -123,9 +123,13 @@ function verifyCertifiedData(
     canisterPrincipal: Principal,
     expectedValue: number
 ): void {
+    const canisterPrincipalBytes = canisterPrincipal.toUint8Array();
+
     const rawData = findLookupValueOrThrow(certificate, [
         'canister',
-        new Uint8Array(canisterPrincipal.toUint8Array()).buffer,
+        canisterPrincipalBytes.buffer instanceof ArrayBuffer
+            ? canisterPrincipalBytes.buffer
+            : new Uint8Array(canisterPrincipalBytes).buffer,
         'certified_data'
     ]);
 

diff --git a/examples/stable/test/end_to_end/candid_rpc/motoko_examples/http_counter/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/motoko_examples/http_counter/src/index.ts
@@ -133,7 +133,7 @@ export default class {
 
                 const counter = this.stableStorage.get('counter');
 
-                if (counter === null) {
+                if (counter === undefined) {
                     trap('counter does not exist');
                 }
 
@@ -190,7 +190,7 @@ export default class {
         if (req.method === 'POST') {
             const counterOpt = this.stableStorage.get('counter');
             const counter =
-                counterOpt === null
+                counterOpt === undefined
                     ? trap('counter does not exist')
                     : counterOpt;
 
@@ -199,7 +199,7 @@ export default class {
             if (req.headers.find(isGzip) === undefined) {
                 const counterOpt = this.stableStorage.get('counter');
                 const counter =
-                    counterOpt === null
+                    counterOpt === undefined
                         ? trap('counter does not exist')
                         : counterOpt;
 
@@ -253,7 +253,7 @@ export default class {
             case 'next': {
                 const counterOpt = this.stableStorage.get('counter');
                 const counter =
-                    counterOpt === null
+                    counterOpt === undefined
                         ? trap('counter does not exist')
                         : counterOpt;
 

diff --git a/examples/stable/test/end_to_end/candid_rpc/motoko_examples/persistent-storage/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/motoko_examples/persistent-storage/src/index.ts
@@ -31,7 +31,7 @@ export default class {
     increment(): bigint {
         let counter = this.stableStorage.get('counter');
 
-        if (counter === null) {
+        if (counter === undefined) {
             trap('counter not defined');
         }
 
@@ -46,7 +46,7 @@ export default class {
     get(): bigint {
         const counter = this.stableStorage.get('counter');
 
-        if (counter === null) {
+        if (counter === undefined) {
             trap('counter not defined');
         }
 
@@ -59,7 +59,7 @@ export default class {
 
         const counter = this.stableStorage.get('counter');
 
-        if (counter === null) {
+        if (counter === undefined) {
             trap('counter not defined');
         }
 

diff --git a/examples/stable/test/end_to_end/candid_rpc/motoko_examples/whoami/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/motoko_examples/whoami/src/index.ts
@@ -25,9 +25,13 @@ class WhoAmI {
     // Manually re-save these variables after new deploys.
     @postUpgrade([IDL.Principal], { manual: true })
     postUpgrade(): void {
+        const argData = msgArgData();
+
         const somebody = IDL.decode(
             [IDL.Principal],
-            new Uint8Array(msgArgData()).buffer
+            argData.buffer instanceof ArrayBuffer
+                ? argData.buffer
+                : new Uint8Array(argData).buffer
         )[0] as unknown as Principal;
 
         this.install = msgCaller();

diff --git a/examples/stable/test/end_to_end/candid_rpc/pre_and_post_upgrade/src/index.ts b/examples/stable/test/end_to_end/candid_rpc/pre_and_post_upgrade/src/index.ts
@@ -37,7 +37,7 @@ export default class {
 
         const stableEntries = this.stableStorage.get('entries');
 
-        if (stableEntries === null) {
+        if (stableEntries === undefined) {
             return;
         }
 

diff --git a/examples/stable/test/end_to_end/candid_rpc/rejections/src/some_canister/index.ts b/examples/stable/test/end_to_end/candid_rpc/rejections/src/some_canister/index.ts
@@ -3,9 +3,13 @@ import { IDL, msgArgData, msgReject, query } from 'azle';
 export default class {
     @query([IDL.Text], IDL.Empty, { manual: true })
     reject(): void {
+        const argData = msgArgData();
+
         const message = IDL.decode(
             [IDL.Text],
-            new Uint8Array(msgArgData()).buffer
+            argData.buffer instanceof ArrayBuffer
+                ? argData.buffer
+                : new Uint8Array(argData).buffer
         )[0] as string;
 
         msgReject(message);

diff --git a/examples/stable/test/end_to_end/candid_rpc/stable_structures/src/canister1/index.ts b/examples/stable/test/end_to_end/candid_rpc/stable_structures/src/canister1/index.ts
@@ -24,7 +24,7 @@ export default class {
     @query([IDL.Nat8], IDL.Opt(IDL.Text))
     stableMap0Get(key: number): [string] | [] {
         const result = this.stableMap0.get(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -34,7 +34,7 @@ export default class {
     @update([IDL.Nat8, IDL.Text], IDL.Opt(IDL.Text))
     stableMap0Insert(key: number, value: string): [string] | [] {
         const result = this.stableMap0.insert(key, value);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -64,7 +64,7 @@ export default class {
     @update([IDL.Nat8], IDL.Opt(IDL.Text))
     stableMap0Remove(key: number): [string] | [] {
         const result = this.stableMap0.remove(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -86,7 +86,7 @@ export default class {
     @query([IDL.Nat16], IDL.Opt(IDL.Vec(IDL.Nat8)))
     stableMap1Get(key: number): [Uint8Array] | [] {
         const result = this.stableMap1.get(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -96,7 +96,7 @@ export default class {
     @update([IDL.Nat16, IDL.Vec(IDL.Nat8)], IDL.Opt(IDL.Vec(IDL.Nat8)))
     stableMap1Insert(key: number, value: Uint8Array): [Uint8Array] | [] {
         const result = this.stableMap1.insert(key, value);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -126,7 +126,7 @@ export default class {
     @update([IDL.Nat16], IDL.Opt(IDL.Vec(IDL.Nat8)))
     stableMap1Remove(key: number): [Uint8Array] | [] {
         const result = this.stableMap1.remove(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -148,7 +148,7 @@ export default class {
     @query([IDL.Nat32], IDL.Opt(IDL.Nat))
     stableMap2Get(key: number): [bigint] | [] {
         const result = this.stableMap2.get(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -158,7 +158,7 @@ export default class {
     @update([IDL.Nat32, IDL.Nat], IDL.Opt(IDL.Nat))
     stableMap2Insert(key: number, value: bigint): [bigint] | [] {
         const result = this.stableMap2.insert(key, value);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -188,7 +188,7 @@ export default class {
     @update([IDL.Nat32], IDL.Opt(IDL.Nat))
     stableMap2Remove(key: number): [bigint] | [] {
         const result = this.stableMap2.remove(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -210,7 +210,7 @@ export default class {
     @query([Reaction], IDL.Opt(IDL.Int))
     stableMap3Get(key: Reaction): [bigint] | [] {
         const result = this.stableMap3.get(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -220,7 +220,7 @@ export default class {
     @update([Reaction, IDL.Int], IDL.Opt(IDL.Int))
     stableMap3Insert(key: Reaction, value: bigint): [bigint] | [] {
         const result = this.stableMap3.insert(key, value);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -250,7 +250,7 @@ export default class {
     @update([Reaction], IDL.Opt(IDL.Int))
     stableMap3Remove(key: Reaction): [bigint] | [] {
         const result = this.stableMap3.remove(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -272,7 +272,7 @@ export default class {
     @query([User], IDL.Opt(IDL.Float32))
     stableMap4Get(key: User): [number] | [] {
         const result = this.stableMap4.get(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -282,7 +282,7 @@ export default class {
     @update([User, IDL.Float32], IDL.Opt(IDL.Float32))
     stableMap4Insert(key: User, value: number): [number] | [] {
         const result = this.stableMap4.insert(key, value);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
@@ -312,7 +312,7 @@ export default class {
     @update([User], IDL.Opt(IDL.Float32))
     stableMap4Remove(key: User): [number] | [] {
         const result = this.stableMap4.remove(key);
-        if (result === null) {
+        if (result === undefined) {
             return [];
         } else {
             return [result];
-Original file line number
+Diff line change
@@ Expand Up / @@ -37,7 +37,7 @@ export default class { @@
             const stableEntries = this.stableStorage.get('entries');
-            if (stableEntries === null) {
+            if (stableEntries === undefined) {
                 return;
             }
@@ Expand Down @@