add documentation for azle 0.22.0

demergent-labs · Jun 11, 2024 · 369b69e · 369b69e
1 parent 80bf4cd
commit 369b69e
Show file tree

Hide file tree

Showing 181 changed files with 1,093 additions and 274 deletions.
diff --git a/docs/404.html b/docs/404.html
diff --git a/docs/assets.html b/docs/assets.html
diff --git a/docs/authentication.html b/docs/authentication.html
diff --git a/docs/azle.html b/docs/azle.html
diff --git a/docs/bitcoin.html b/docs/bitcoin.html
diff --git a/docs/candid.html b/docs/candid.html
diff --git a/docs/candid_based_documentation.html b/docs/candid_based_documentation.html
diff --git a/docs/canister_lifecycle.html b/docs/canister_lifecycle.html
diff --git a/docs/canisters_overview.html b/docs/canisters_overview.html
diff --git a/docs/caveats.html b/docs/caveats.html
diff --git a/docs/cross_canister.html b/docs/cross_canister.html
diff --git a/docs/cycles.html b/docs/cycles.html
diff --git a/docs/databases.html b/docs/databases.html
diff --git a/docs/debugging.html b/docs/debugging.html
diff --git a/docs/deployment.html b/docs/deployment.html
diff --git a/docs/deployment_candid_based.html b/docs/deployment_candid_based.html
diff --git a/docs/ethereum.html b/docs/ethereum.html
diff --git a/docs/examples.html b/docs/examples.html
diff --git a/docs/fetch.html b/docs/fetch.html
diff --git a/docs/get_started.html b/docs/get_started.html
diff --git a/docs/hello_world.html b/docs/hello_world.html
diff --git a/docs/http.html b/docs/http.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/installation.html b/docs/installation.html
diff --git a/docs/internet_computer_overview.html b/docs/internet_computer_overview.html
diff --git a/docs/limitations.html b/docs/limitations.html
diff --git a/docs/management_canister.html b/docs/management_canister.html
diff --git a/docs/npm.html b/docs/npm.html
diff --git a/docs/print.html b/docs/print.html
diff --git a/docs/project_structure.html b/docs/project_structure.html
diff --git a/docs/query_methods.html b/docs/query_methods.html
diff --git a/docs/reference/bitcoin.html b/docs/reference/bitcoin.html
diff --git a/docs/reference/call_apis/accept_message.html b/docs/reference/call_apis/accept_message.html
diff --git a/docs/reference/call_apis/arg_data_raw.html b/docs/reference/call_apis/arg_data_raw.html
diff --git a/docs/reference/call_apis/arg_data_raw_size.html b/docs/reference/call_apis/arg_data_raw_size.html
diff --git a/docs/reference/call_apis/call.html b/docs/reference/call_apis/call.html
diff --git a/docs/reference/call_apis/call_apis.html b/docs/reference/call_apis/call_apis.html
diff --git a/docs/reference/call_apis/call_raw.html b/docs/reference/call_apis/call_raw.html
diff --git a/docs/reference/call_apis/call_raw128.html b/docs/reference/call_apis/call_raw128.html
diff --git a/docs/reference/call_apis/call_with_payment.html b/docs/reference/call_apis/call_with_payment.html
diff --git a/docs/reference/call_apis/call_with_payment128.html b/docs/reference/call_apis/call_with_payment128.html
diff --git a/docs/reference/call_apis/caller.html b/docs/reference/call_apis/caller.html
diff --git a/docs/reference/call_apis/method_name.html b/docs/reference/call_apis/method_name.html
diff --git a/docs/reference/call_apis/msg_cycles_accept.html b/docs/reference/call_apis/msg_cycles_accept.html
diff --git a/docs/reference/call_apis/msg_cycles_accept128.html b/docs/reference/call_apis/msg_cycles_accept128.html
diff --git a/docs/reference/call_apis/msg_cycles_available.html b/docs/reference/call_apis/msg_cycles_available.html
diff --git a/docs/reference/call_apis/msg_cycles_available128.html b/docs/reference/call_apis/msg_cycles_available128.html
diff --git a/docs/reference/call_apis/msg_cycles_refunded.html b/docs/reference/call_apis/msg_cycles_refunded.html
diff --git a/docs/reference/call_apis/msg_cycles_refunded128.html b/docs/reference/call_apis/msg_cycles_refunded128.html
diff --git a/docs/reference/call_apis/notify.html b/docs/reference/call_apis/notify.html
diff --git a/docs/reference/call_apis/notify_raw.html b/docs/reference/call_apis/notify_raw.html
diff --git a/docs/reference/call_apis/notify_with_payment_128.html b/docs/reference/call_apis/notify_with_payment_128.html
diff --git a/docs/reference/call_apis/reject.html b/docs/reference/call_apis/reject.html
diff --git a/docs/reference/call_apis/reject_code.html b/docs/reference/call_apis/reject_code.html
diff --git a/docs/reference/call_apis/reject_message.html b/docs/reference/call_apis/reject_message.html
diff --git a/docs/reference/call_apis/reply.html b/docs/reference/call_apis/reply.html
diff --git a/docs/reference/call_apis/reply_raw.html b/docs/reference/call_apis/reply_raw.html
diff --git a/docs/reference/candid/blob.html b/docs/reference/candid/blob.html
diff --git a/docs/reference/candid/bool.html b/docs/reference/candid/bool.html
diff --git a/docs/reference/candid/candid.html b/docs/reference/candid/candid.html
diff --git a/docs/reference/candid/empty.html b/docs/reference/candid/empty.html
diff --git a/docs/reference/candid/float32.html b/docs/reference/candid/float32.html
diff --git a/docs/reference/candid/float64.html b/docs/reference/candid/float64.html
diff --git a/docs/reference/candid/func.html b/docs/reference/candid/func.html
diff --git a/docs/reference/candid/int.html b/docs/reference/candid/int.html
diff --git a/docs/reference/candid/int16.html b/docs/reference/candid/int16.html
diff --git a/docs/reference/candid/int32.html b/docs/reference/candid/int32.html
diff --git a/docs/reference/candid/int64.html b/docs/reference/candid/int64.html
diff --git a/docs/reference/candid/int8.html b/docs/reference/candid/int8.html
diff --git a/docs/reference/candid/nat.html b/docs/reference/candid/nat.html
diff --git a/docs/reference/candid/nat16.html b/docs/reference/candid/nat16.html
diff --git a/docs/reference/candid/nat32.html b/docs/reference/candid/nat32.html
diff --git a/docs/reference/candid/nat64.html b/docs/reference/candid/nat64.html
diff --git a/docs/reference/candid/nat8.html b/docs/reference/candid/nat8.html
diff --git a/docs/reference/candid/null.html b/docs/reference/candid/null.html
diff --git a/docs/reference/candid/opt.html b/docs/reference/candid/opt.html
diff --git a/docs/reference/candid/principal.html b/docs/reference/candid/principal.html
diff --git a/docs/reference/candid/record.html b/docs/reference/candid/record.html
diff --git a/docs/reference/candid/reserved.html b/docs/reference/candid/reserved.html
diff --git a/docs/reference/candid/service.html b/docs/reference/candid/service.html
diff --git a/docs/reference/candid/text.html b/docs/reference/candid/text.html
diff --git a/docs/reference/candid/variant.html b/docs/reference/candid/variant.html
diff --git a/docs/reference/candid/vec.html b/docs/reference/candid/vec.html
diff --git a/docs/reference/canister_apis/candid_decode.html b/docs/reference/canister_apis/candid_decode.html
diff --git a/docs/reference/canister_apis/candid_encode.html b/docs/reference/canister_apis/candid_encode.html
diff --git a/docs/reference/canister_apis/canister_apis.html b/docs/reference/canister_apis/canister_apis.html
diff --git a/docs/reference/canister_apis/canister_balance.html b/docs/reference/canister_apis/canister_balance.html
diff --git a/docs/reference/canister_apis/canister_balance128.html b/docs/reference/canister_apis/canister_balance128.html
diff --git a/docs/reference/canister_apis/canister_id.html b/docs/reference/canister_apis/canister_id.html
diff --git a/docs/reference/canister_apis/canister_version.html b/docs/reference/canister_apis/canister_version.html
diff --git a/docs/reference/canister_apis/data_certificate.html b/docs/reference/canister_apis/data_certificate.html
diff --git a/docs/reference/canister_apis/instruction_counter.html b/docs/reference/canister_apis/instruction_counter.html
diff --git a/docs/reference/canister_apis/is_controller.html b/docs/reference/canister_apis/is_controller.html
diff --git a/docs/reference/canister_apis/performance_counter.html b/docs/reference/canister_apis/performance_counter.html
diff --git a/docs/reference/canister_apis/print.html b/docs/reference/canister_apis/print.html
diff --git a/docs/reference/canister_apis/set_certified_data.html b/docs/reference/canister_apis/set_certified_data.html
diff --git a/docs/reference/canister_apis/time.html b/docs/reference/canister_apis/time.html
diff --git a/docs/reference/canister_apis/trap.html b/docs/reference/canister_apis/trap.html
diff --git a/docs/reference/canister_methods/canister_methods.html b/docs/reference/canister_methods/canister_methods.html
diff --git a/docs/reference/canister_methods/heartbeat.html b/docs/reference/canister_methods/heartbeat.html
diff --git a/docs/reference/canister_methods/http_request.html b/docs/reference/canister_methods/http_request.html
diff --git a/docs/reference/canister_methods/http_request_update.html b/docs/reference/canister_methods/http_request_update.html
diff --git a/docs/reference/canister_methods/init.html b/docs/reference/canister_methods/init.html
diff --git a/docs/reference/canister_methods/inspect_message.html b/docs/reference/canister_methods/inspect_message.html
diff --git a/docs/reference/canister_methods/post_upgrade.html b/docs/reference/canister_methods/post_upgrade.html
diff --git a/docs/reference/canister_methods/pre_upgrade.html b/docs/reference/canister_methods/pre_upgrade.html
diff --git a/docs/reference/canister_methods/query.html b/docs/reference/canister_methods/query.html
diff --git a/docs/reference/canister_methods/update.html b/docs/reference/canister_methods/update.html
diff --git a/docs/reference/environment_variables.html b/docs/reference/environment_variables.html
diff --git a/docs/reference/management_canister/bitcoin_get_balance.html b/docs/reference/management_canister/bitcoin_get_balance.html
diff --git a/docs/reference/management_canister/bitcoin_get_current_fee_percentiles.html b/docs/reference/management_canister/bitcoin_get_current_fee_percentiles.html
diff --git a/docs/reference/management_canister/bitcoin_get_utxos.html b/docs/reference/management_canister/bitcoin_get_utxos.html
diff --git a/docs/reference/management_canister/bitcoin_send_transaction.html b/docs/reference/management_canister/bitcoin_send_transaction.html
diff --git a/docs/reference/management_canister/canister_status.html b/docs/reference/management_canister/canister_status.html
diff --git a/docs/reference/management_canister/create_canister.html b/docs/reference/management_canister/create_canister.html
diff --git a/docs/reference/management_canister/delete_canister.html b/docs/reference/management_canister/delete_canister.html
diff --git a/docs/reference/management_canister/deposit_cycles.html b/docs/reference/management_canister/deposit_cycles.html
diff --git a/docs/reference/management_canister/ecdsa_public_key.html b/docs/reference/management_canister/ecdsa_public_key.html
diff --git a/docs/reference/management_canister/http_request.html b/docs/reference/management_canister/http_request.html
diff --git a/docs/reference/management_canister/install_code.html b/docs/reference/management_canister/install_code.html
diff --git a/docs/reference/management_canister/management_canister.html b/docs/reference/management_canister/management_canister.html
diff --git a/docs/reference/management_canister/provisional_create_canister_with_cycles.html b/docs/reference/management_canister/provisional_create_canister_with_cycles.html
diff --git a/docs/reference/management_canister/provisional_top_up_canister.html b/docs/reference/management_canister/provisional_top_up_canister.html
diff --git a/docs/reference/management_canister/raw_rand.html b/docs/reference/management_canister/raw_rand.html
diff --git a/docs/reference/management_canister/sign_with_ecdsa.html b/docs/reference/management_canister/sign_with_ecdsa.html
diff --git a/docs/reference/management_canister/start_canister.html b/docs/reference/management_canister/start_canister.html
diff --git a/docs/reference/management_canister/stop_canister.html b/docs/reference/management_canister/stop_canister.html
diff --git a/docs/reference/management_canister/uninstall_code.html b/docs/reference/management_canister/uninstall_code.html
diff --git a/docs/reference/management_canister/update_settings.html b/docs/reference/management_canister/update_settings.html
diff --git a/docs/reference/plugins.html b/docs/reference/plugins.html
diff --git a/docs/reference/reference.html b/docs/reference/reference.html
diff --git a/docs/reference/stable_memory/stable64_grow.html b/docs/reference/stable_memory/stable64_grow.html
diff --git a/docs/reference/stable_memory/stable64_read.html b/docs/reference/stable_memory/stable64_read.html
diff --git a/docs/reference/stable_memory/stable64_size.html b/docs/reference/stable_memory/stable64_size.html
diff --git a/docs/reference/stable_memory/stable64_write.html b/docs/reference/stable_memory/stable64_write.html
diff --git a/docs/reference/stable_memory/stable_bytes.html b/docs/reference/stable_memory/stable_bytes.html
diff --git a/docs/reference/stable_memory/stable_grow.html b/docs/reference/stable_memory/stable_grow.html
diff --git a/docs/reference/stable_memory/stable_memory.html b/docs/reference/stable_memory/stable_memory.html
diff --git a/docs/reference/stable_memory/stable_read.html b/docs/reference/stable_memory/stable_read.html
diff --git a/docs/reference/stable_memory/stable_size.html b/docs/reference/stable_memory/stable_size.html
diff --git a/docs/reference/stable_memory/stable_structures.html b/docs/reference/stable_memory/stable_structures.html
diff --git a/docs/reference/stable_memory/stable_write.html b/docs/reference/stable_memory/stable_write.html
diff --git a/docs/reference/timers/clear_timer.html b/docs/reference/timers/clear_timer.html
diff --git a/docs/reference/timers/set_timer.html b/docs/reference/timers/set_timer.html
diff --git a/docs/reference/timers/set_timer_interval.html b/docs/reference/timers/set_timer_interval.html
diff --git a/docs/reference/timers/timers.html b/docs/reference/timers/timers.html
diff --git a/docs/reference/wasm_binary_optimization.html b/docs/reference/wasm_binary_optimization.html
diff --git a/docs/reference_http/autoreload.html b/docs/reference_http/autoreload.html
diff --git a/docs/reference_http/environment_variables.html b/docs/reference_http/environment_variables.html
diff --git a/docs/reference_http/native_compilation.html b/docs/reference_http/native_compilation.html
diff --git a/docs/reference_http/reference.html b/docs/reference_http/reference.html
diff --git a/docs/rest_based_examples.html b/docs/rest_based_examples.html
diff --git a/docs/searchindex.js b/docs/searchindex.js
diff --git a/docs/searchindex.json b/docs/searchindex.json
diff --git a/docs/servers.html b/docs/servers.html
diff --git a/docs/stable_structures.html b/docs/stable_structures.html
diff --git a/docs/the_azle_book.html b/docs/the_azle_book.html
diff --git a/docs/timers.html b/docs/timers.html
diff --git a/docs/tokens.html b/docs/tokens.html
diff --git a/docs/update_methods.html b/docs/update_methods.html
diff --git a/the_azle_book/book/404.html b/the_azle_book/book/404.html
diff --git a/the_azle_book/book/azle.html b/the_azle_book/book/azle.html
diff --git a/the_azle_book/book/candid.html b/the_azle_book/book/candid.html
diff --git a/the_azle_book/book/canisters_overview.html b/the_azle_book/book/canisters_overview.html
diff --git a/the_azle_book/book/cross_canister.html b/the_azle_book/book/cross_canister.html
diff --git a/the_azle_book/book/cycles.html b/the_azle_book/book/cycles.html
diff --git a/the_azle_book/book/deployment.html b/the_azle_book/book/deployment.html
diff --git a/the_azle_book/book/examples.html b/the_azle_book/book/examples.html
diff --git a/the_azle_book/book/http.html b/the_azle_book/book/http.html
diff --git a/the_azle_book/book/index.html b/the_azle_book/book/index.html
diff --git a/the_azle_book/book/installation.html b/the_azle_book/book/installation.html
diff --git a/the_azle_book/book/internet_computer_overview.html b/the_azle_book/book/internet_computer_overview.html
diff --git a/the_azle_book/book/print.html b/the_azle_book/book/print.html
diff --git a/the_azle_book/book/searchindex.js b/the_azle_book/book/searchindex.js
diff --git a/the_azle_book/book/searchindex.json b/the_azle_book/book/searchindex.json
diff --git a/the_azle_book/book/timers.html b/the_azle_book/book/timers.html
diff --git a/the_azle_book/src/SUMMARY.md b/the_azle_book/src/SUMMARY.md
@@ -13,7 +13,7 @@
 -   [Tokens](./tokens.md)
 -   [Bitcoin](./bitcoin.md)
 -   [Ethereum](./ethereum.md)
--   [Databases]()
+-   [Databases](./databases.md)
 -   [Cycles]()
 -   [Debugging](./debugging.md)
 -   [Limitations](./limitations.md)

diff --git a/the_azle_book/src/bitcoin.md b/the_azle_book/src/bitcoin.md
@@ -4,8 +4,9 @@ Examples:
 
 -   [basic_bitcoin](https://github.com/demergent-labs/azle/tree/main/examples/basic_bitcoin)
 -   [bitcoin](https://github.com/demergent-labs/azle/tree/main/examples/bitcoin)
--   [bitcoinjs-lib](https://github.com/demergent-labs/azle/tree/main/examples/bitcoinjs-lib)
--   [bitcore-lib](https://github.com/demergent-labs/azle/tree/main/examples/bitcore-lib)
+-   [bitcoin_psbt](https://github.com/demergent-labs/azle/tree/main/examples/bitcoin_psbt)
+-   [bitcoinjs_lib](https://github.com/demergent-labs/azle/tree/main/examples/bitcoinjs_lib)
+-   [bitcore_lib](https://github.com/demergent-labs/azle/tree/main/examples/bitcore_lib)
 -   [ckbtc](https://github.com/demergent-labs/azle/tree/main/examples/ckbtc)
 
 There are two main ways to interact with Bitcoin on ICP: through the [management canister](#management-canister) and through the [ckBTC canister](#ckbtc).

diff --git a/the_azle_book/src/databases.md b/the_azle_book/src/databases.md
@@ -0,0 +1,83 @@
+# Databases
+
+The eventual goal for Azle is to support as many database solutions as possible. This is difficult for a number of reasons related to ICP's decentralized computing paradigm and Wasm environment.
+
+[SQLite](https://sqlite.org/) is the current recommended approach to databases with Azle. We plan to provide Postgres support through [pglite](https://github.com/electric-sql/pglite) next.
+
+Azle has good support for SQLite through [sql.js](https://www.npmjs.com/package/sql.js). It also has good support for ORMs like [Drizzle](https://orm.drizzle.team/) and [TypeORM](https://typeorm.io/) using `sql.js`.
+
+The following examples should be very useful as you get started using SQLite in Azle:
+
+Examples:
+
+-   [sqlite](https://github.com/demergent-labs/azle/tree/main/examples/sqlite)
+-   [sqlite_drizzle](https://github.com/demergent-labs/azle/tree/main/examples/sqlite_drizzle)
+-   [sqlite_typeorm](https://github.com/demergent-labs/azle/tree/main/examples/sqlite_typeorm)
+
+## sql.js
+
+SQLite in Azle works using an [asm.js](https://en.wikipedia.org/wiki/Asm.js) build of SQLite from `sql.js` without modifications to the library. The database is stored entirely in memory on the heap, giving you ~2 GiB of space. Serialization across upgrades is possible using stable memory like this:
+
+```typescript
+// src/index.its
+
+import {
+    init,
+    postUpgrade,
+    preUpgrade,
+    Server,
+    StableBTreeMap,
+    stableJson
+} from 'azle';
+import { Database } from 'sql.js/dist/sql-asm.js';
+
+import { initDb } from './db';
+import { initServer } from './server';
+
+export let db: Database;
+
+let stableDbMap = StableBTreeMap<'DATABASE', Uint8Array>(0, stableJson, {
+    toBytes: (data: Uint8Array) => data,
+    fromBytes: (bytes: Uint8Array) => bytes
+});
+
+export default Server(initServer, {
+    init: init([], async () => {
+        db = await initDb();
+    }),
+    preUpgrade: preUpgrade(() => {
+        stableDbMap.insert('DATABASE', db.export());
+    }),
+    postUpgrade: postUpgrade([], async () => {
+        db = await initDb(stableDbMap.get('DATABASE').Some);
+    })
+});
+```
+
+```typescript
+// src/db/index.ts
+
+import initSqlJs, {
+    Database,
+    QueryExecResult,
+    SqlValue
+} from 'sql.js/dist/sql-asm.js';
+
+import { migrations } from './migrations';
+
+export async function initDb(
+    bytes: Uint8Array = Uint8Array.from([])
+): Promise<Database> {
+    const SQL = await initSqlJs({});
+
+    let db = new SQL.Database(bytes);
+
+    if (bytes.length === 0) {
+        for (const migration of migrations) {
+            db.run(migration);
+        }
+    }
+
+    return db;
+}
+```
diff --git a/the_azle_book/src/reference_http/environment_variables.md b/the_azle_book/src/reference_http/environment_variables.md
@@ -9,7 +9,9 @@
 -   [AZLE_PROPTEST_QUIET](#azle_proptest_quiet)
 -   [AZLE_PROPTEST_SEED](#azle_proptest_seed)
 -   [AZLE_PROPTEST_VERBOSE](#azle_proptest_verbose)
--   [AZLE_TEST_FETCH]()
+-   [AZLE_SKIP_COMPILER_INFO](#azle_skip_compiler_info)
+-   [AZLE_TEST_FETCH](#azle_test_fetch)
+-   [AZLE_UPLOADER_IDENTITY_NAME]()
 -   [AZLE_USE_DOCKERFILE](#azle_use_dockerfile)
 -   [AZLE_VERBOSE](#azle_verbose)
 -   [AZLE_WASMEDGE_QUICKJS_DIR](#azle_wasmedge_quickjs_dir)
@@ -50,10 +52,18 @@ Used for automated testing.
 
 Used for automated testing.
 
+## AZLE_SKIP_COMPILER_INFO
+
+Used internally in the Dockerfile.
+
 ## AZLE_TEST_FETCH
 
 Used for automated testing.
 
+## AZLE_UPLOADER_IDENTITY_NAME
+
+Change the name of the `dfx` identity added as a controller for uploading large assets and autoreload.
+
 ## AZLE_USE_DOCKERFILE
 
 Set this to `true` to force Azle to build the container image locally from the internal Dockerfile instead of attempting to download the container image.

diff --git a/the_azle_book/src/reference_http/instruction_limit_chunking.md b/the_azle_book/src/reference_http/instruction_limit_chunking.md
@@ -0,0 +1,26 @@
+# TODO this will be in Azle 0.23.0 or later
+
+# Instruction Limit Chunking
+
+Query and Update calls on ICP have [instruction limits](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/resource-limits).
+
+The limit can only be increased as a protocol-level change. If after optimizing your code you still cannot stay under the limit, then considering using `ic.chunk()` imported from `azle`.
+
+Awaiting `ic.chunk()` will reset the instruction limit of your call. If you have access to and can change the source code where the instruction limit is being hit, then this may help you to overcome the limit.
+
+Unfortunately libraries or algorithms that cannot have this call inserted easily will be difficult or impossible to keep under the limit.
+
+Here's an example of using `ic.chunk()`:
+
+```typescript
+import { Canister, ic, update, Void } from 'azle';
+
+export default Canister({
+    huge_limit: update([], Void, async () => {
+        for (let i = 0; i < 1_000_000; i++) {
+            Math.random();
+            await ic.chunk();
+        }
+    })
+});
+```