docs: callable functions

Signed-off-by: David Dal Busco <david.dalbusco@outlook.com>

Author: peterpeterparker

docs/build/functions/development/components/query.mdx

@@ -0,0 +1,37 @@
+Defines a read-only function that returns data without modifying any state.
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+```mdx-code-block
+<Tabs groupId="functions">
+<TabItem value="Rust">
+```
+
+```rust
+#[ic_cdk::query]
+fn my_function() -> String {
+    // Your logic here
+}
+```
+
+```mdx-code-block
+</TabItem>
+<TabItem value="TypeScript">
+```
+
+```typescript
+export const myFunction = defineQuery({
+  args: Schema,
+  returns: Schema,
+  handler: ({ args }) => {
+    // Your logic here
+    return args;
+  }
+});
+```
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+```

docs/build/functions/development/components/update.mdx

@@ -0,0 +1,37 @@
+Defines a function that can read and write state.
+
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+```mdx-code-block
+<Tabs groupId="functions">
+<TabItem value="Rust">
+```
+
+```rust
+#[ic_cdk::update]
+fn my_function() -> String {
+    // Your logic here
+}
+```
+
+```mdx-code-block
+</TabItem>
+<TabItem value="TypeScript">
+```
+
+```typescript
+export const myFunction = defineUpdate({
+  args: Schema,
+  returns: Schema,
+  handler: async ({ args }) => {
+    // Your logic here
+    return args;
+  }
+});
+```
+
+```mdx-code-block
+</TabItem>
+</Tabs>
+```

docs/build/functions/development/index.mdx

@@ -4,116 +4,140 @@ When you're ready to implement Functions within your Juno Satellite, you'll have
 
 ---
 
-## Hooks
+## Event-driven Functions
+
+Event-driven functions respond to actions occurring in your Satellite. They are triggered automatically and never invoked directly.
+
+---
+
+### Hooks
 
 Hooks allow you to define event-driven logic that responds to specific actions within your Satellite. The following is a list of available hooks and their respective use cases.
 
-### on_set_doc
+#### on_set_doc
 
 import OnSetDoc from "./components/on-set-doc.mdx";
 
 <OnSetDoc />
 
-### on_set_many_docs
+#### on_set_many_docs
 
 import OnSetManyDocs from "./components/on-set-many-docs.mdx";
 
 <OnSetManyDocs />
 
-### on_delete_doc
+#### on_delete_doc
 
 import OnDeleteDoc from "./components/on-delete-doc.mdx";
 
 <OnDeleteDoc />
 
-### on_delete_many_docs
+#### on_delete_many_docs
 
 import OnDeleteManyDocs from "./components/on-delete-many-docs.mdx";
 
 <OnDeleteManyDocs />
 
-### on_delete_filtered_docs
+#### on_delete_filtered_docs
 
 import OnDeleteFilteredDocs from "./components/on-delete-filtered-docs.mdx";
 
 <OnDeleteFilteredDocs />
 
-### on_upload_asset
+#### on_upload_asset
 
 import OnUploadAsset from "./components/on-upload-asset.mdx";
 
 <OnUploadAsset />
 
-### on_delete_asset
+#### on_delete_asset
 
 import OnDeleteAsset from "./components/on-delete-asset.mdx";
 
 <OnDeleteAsset />
 
-### on_delete_many_assets
+#### on_delete_many_assets
 
 import OnDeleteManyAssets from "./components/on-delete-many-assets.mdx";
 
 <OnDeleteManyAssets />
 
-### on_delete_filtered_assets
+#### on_delete_filtered_assets
 
 import OnDeleteFilteredAssets from "./components/on-delete-filtered-assets.mdx";
 
 <OnDeleteFilteredAssets />
 
-### on_init
+#### on_init
 
 import OnInit from "./components/on-init.mdx";
 
 <OnInit />
 
-### on_post_upgrade
+#### on_post_upgrade
 
 import OnPostUpgrade from "./components/on-post-upgrade.mdx";
 
 <OnPostUpgrade />
 
 ---
 
-## Assertions
+### Assertions
 
 Assertions enable validation checks before specific actions are executed within your Satellite. The following is a list of available assertions and their functionalities.
 
-### assert_set_doc
+#### assert_set_doc
 
 import AssertSetDoc from "./components/assert-set-doc.mdx";
 
 <AssertSetDoc />
 
-### assert_delete_doc
+#### assert_delete_doc
 
 import AssertDeleteDoc from "./components/assert-delete-doc.mdx";
 
 <AssertDeleteDoc />
 
-### assert_upload_asset
+#### assert_upload_asset
 
 import AssertUploadAsset from "./components/assert-upload-asset.mdx";
 
 <AssertUploadAsset />
 
-### assert_delete_asset
+#### assert_delete_asset
 
 import AssertDeleteAsset from "./components/assert-delete-asset.mdx";
 
 <AssertDeleteAsset />
 
 ---
 
-## When the Functions Run
+### When Hooks and Assertions Run
 
 import Collections from "./components/collections.mdx";
 
 <Collections />
 
 ---
 
+## Callable Functions
+
+Callable functions (also referenced as custom functions) are explicitly invoked — from your frontend or from other canisters.
+
+### Query
+
+import Query from "./components/query.mdx";
+
+<Query />
+
+### Update
+
+import Update from "./components/update.mdx";
+
+<Update />
+
+---
+
 ## Further Resources
 
 import Resources from "./components/further-resources.mdx";

docs/build/functions/index.md

@@ -16,33 +16,28 @@ keywords:
 
 Functions are a set of features enabling developers to extend the native capabilities of [Satellites](../../terminology.mdx#satellite) using Rust or TypeScript. They let you define serverless behaviors directly within your containerized environment.
 
-Triggered by events like document and asset operations, they allow you to automatically run backend code or assertions. These functions are shipped with your container and don’t require you to manage or scale your own servers.
+There are two types of functions:
 
----
-
-## How does it work?
-
-Functions are defined using hooks that automatically respond to document and asset events such as create, update, or delete. This allows you to embed dynamic behavior directly into your container.
+- [Event-driven functions](#event-driven-functions): triggered automatically in response to actions such as a document being created or an asset being uploaded.
+- [Callable functions](#callable-functions): explicitly invoked from your frontend or from other services.
 
-A naive schema representation of a hook that is triggered when a document is set:
-
-![Functions hooks flow](../../img/functions.png)
+---
 
-### Asynchronous Hook Spawning
+## Event-driven Functions
 
-When a Function is triggered, it spawns hooks asynchronously, operating independently of the caller's action. This means that the execution of the hooks is initiated without waiting for a synchronous response, ensuring that the flow of update calls to the Satellite remains unhindered. Consequently, callers may receive feedback on their actions before the corresponding hooks have commenced their execution.
+Event-driven functions respond to actions occurring in your Satellite. They are triggered automatically and never invoked directly.
 
-### Error-Resilient Execution
+### Hooks
 
-Hooks are initiated only when there are no errors in the preceding operations. This ensures a robust and dependable execution flow, promoting reliability and consistency in the functioning of Functions.
+Hooks respond to specific actions within your Satellite. They run asynchronously, independently of the caller's request - meaning the caller may receive a response before the hook has finished executing.
 
-### Optional
+![Functions hooks flow](../../img/functions.png)
 
-Custom hooks are not active by default. You need to opt in to enable event-driven execution of your own logic.
+:::note
 
----
+Hooks are only initiated when the preceding operation completes without errors.
 
-## Available Hooks
+:::
 
 | Hook                        | Provider  | Description                                                     |
 | --------------------------- | --------- | --------------------------------------------------------------- |
@@ -58,11 +53,9 @@ Custom hooks are not active by default. You need to opt in to enable event-drive
 | `on_init`                   | Satellite | Called during the initialization of the Satellite.              |
 | `on_post_upgrade`           | Satellite | Invoked after the Satellite has been upgraded to a new version. |
 
----
-
-## Assertions
+### Assertions
 
-In addition to hooks, developers have the option to expand the native rule set of their Satellites by creating custom assertions. These assertions can be implemented similarly to hooks, with the key difference being that they are synchronous and must return a result indicating the outcome of the assertion.
+Assertions run synchronously before an operation is executed. They allow you to validate or reject actions before any data is written.
 
 | Assertion             | Provider  | Description                                   |
 | --------------------- | --------- | --------------------------------------------- |
@@ -73,6 +66,23 @@ In addition to hooks, developers have the option to expand the native rule set o
 
 ---
 
+## Callable Functions
+
+Callable functions are explicitly invoked — from your frontend or from other services. They expose query and update endpoints directly from your Satellite.
+
+:::tip
+
+This is conceptually similar to exposing your own endpoints on an API.
+
+:::
+
+| Type     | Description                                                     |
+| -------- | --------------------------------------------------------------- |
+| `query`  | A read-only function that returns data without modifying state. |
+| `update` | A function that can read and write state.                       |
+
+---
+
 ## Rust vs. TypeScript
 
 You can write serverless functions in either [Rust](./development/rust.mdx) or [TypeScript](./development/typescript.mdx), depending on your needs and project goals.