Development
When you're ready to implement Functions within your Juno Satellite, you'll have a variety of event-driven macros at your disposal, enabling custom logic execution in response to specific actions. Here's how to implement each available Function:
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
Triggered when a document is created or updated in the datastore.
- Rust
- TypeScript
#[on_set_doc]
async fn on_set_doc(context: OnSetDocContext) -> Result<(), String> {
// Custom logic for handling document creation or updates
Ok(())
}
export const onSetDoc = defineHook<OnSetDoc>({
collections: [],
run: async (context) => {
// Custom logic for handling document creation or updates
}
});
on_set_many_docs
Invoked for batch operations involving multiple document creations or updates.
- Rust
- TypeScript
#[on_set_many_docs]
async fn on_set_many_docs(context: OnSetManyDocsContext) -> Result<(), String> {
// Custom logic for handling multiple document creations or updates
Ok(())
}
export const onSetManyDocs = defineHook<OnSetManyDocs>({
collections: [],
run: async (context) => {
// Custom logic for handling multiple document creations or updates
}
});
on_delete_doc
Invoked when a document is deleted from the datastore.
- Rust
- TypeScript
#[on_delete_doc]
async fn on_delete_doc(context: OnDeleteDocContext) -> Result<(), String> {
// Custom logic for handling document deletion
Ok(())
}
export const onDeleteDoc = defineHook<OnDeleteDoc>({
collections: [],
run: async (context) => {
// Custom logic for handling document deletion
}
});
on_delete_many_docs
Used when multiple documents are deleted in a batch operation.
- Rust
- TypeScript
#[on_delete_many_docs]
async fn on_delete_many_docs(context: OnDeleteManyDocsContext) -> Result<(), String> {
// Custom logic for handling the deletion of multiple documents
Ok(())
}
export const onDeleteManyDocs = defineHook<OnDeleteManyDocs>({
collections: [],
run: async (context) => {
// Custom logic for handling the deletion of multiple documents
}
});
on_delete_filtered_docs
Invoked when documents are deleted according to specified filters in the datastore.
- Rust
- TypeScript
#[on_delete_filtered_docs]
async fn on_delete_filtered_docs(context: OnDeleteFilteredDocsContext) -> Result<(), String> {
// Custom logic for handling the deletion of filtered documents
Ok(())
}
export const onDeleteFilteredDocs = defineHook<OnDeleteFilteredDocs>({
collections: [],
run: async (context) => {
// Custom logic for handling the deletion of filtered documents
}
});
on_upload_asset
Triggered during the process of uploading an asset.
- Rust
- TypeScript
#[on_upload_asset]
async fn on_upload_asset(context: OnUploadAssetContext) -> Result<(), String> {
// Custom logic for handling asset uploads
Ok(())
}
export const onUploadAsset = defineHook<OnUploadAsset>({
collections: [],
run: async (context) => {
// Custom logic for handling asset uploads
}
});
on_delete_asset
Activated when an asset is removed from the datastore.
- Rust
- TypeScript
#[on_delete_asset]
async fn on_delete_asset(context: OnDeleteAssetContext) -> Result<(), String> {
// Custom logic for handling asset deletion
Ok(())
}
export const onDeleteAsset = defineHook<OnDeleteAsset>({
collections: [],
run: async (context) => {
// Custom logic for handling asset deletion
}
});
on_delete_many_assets
Used for operations that involve deleting multiple assets in a batch.
- Rust
- TypeScript
#[on_delete_many_assets]
async fn on_delete_many_assets(context: OnDeleteManyAssetsContext) -> Result<(), String> {
// Custom logic for handling the deletion of multiple assets
Ok(())
}
export const onDeleteManyAssets = defineHook<OnDeleteManyAssets>({
collections: [],
run: async (context) => {
// Custom logic for handling the deletion of multiple assets
}
});
on_delete_filtered_assets
Invoked when assets are deleted according to specified filters in the storage.
- Rust
- TypeScript
#[on_delete_filtered_assets]
async fn on_delete_filtered_assets(context: OnDeleteFilteredAssetsContext) -> Result<(), String> {
// Custom logic for handling the deletion of filtered assets
Ok(())
}
export const onDeleteFilteredAssets = defineHook<OnDeleteFilteredAssets>({
collections: [],
run: async (context) => {
// Custom logic for handling the deletion of filtered assets
}
});
on_init
Called during the initialization of the satellite. This hook is invoked when the satellite is first deployed and can be used to set up initial configurations or resources.
#[on_init]
fn on_init() -> Result<(), String> {
// Custom logic for initialization
Ok(())
}
Unlike datastore or storage hooks, on_init
cannot be scoped to specific collections or assets, as it is meant to handle global initialization logic.
This feature is not enabled by default. To use it, you’ll need to opt in by updating your Cargo.toml
file.
[dependencies]
junobuild-satellite = { version = "*", features = ["default", "on_init"] }
This hook is not available when writing functions in TypeScript.
on_post_upgrade
Invoked after the satellite has been upgraded to a new version. This hook is typically used to manage migration tasks, or starting custom processes like timers.
#[on_post_upgrade]
fn on_post_upgrade() -> Result<(), String> {
// Custom logic for post-upgrade tasks
Ok(())
}
Similar to on_init
, the on_post_upgrade
hook cannot be scoped to collections or assets. It operates globally to handle upgrade-related operations.
This feature is not enabled by default. To use it, you’ll need to opt in by updating your Cargo.toml
file.
[dependencies]
junobuild-satellite = { version = "*", features = ["default", "on_post_upgrade"] }
This hook is not available when writing functions in TypeScript.
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
Ensures a document can be created or updated.
- Rust
- TypeScript
#[assert_set_doc]
fn assert_set_doc(_context: AssertSetDocContext) -> Result<(), String> {
// Custom logic for asserting a document's creation or update is possible
// Return an error if the condition fails to prevent the action
Ok(())
}
export const assertSetDoc = defineAssert<AssertSetDoc>({
collections: [],
assert: (context) => {
// Custom logic for asserting a document's creation or update is possible
// Throw an error if the condition fails to prevent the action
}
});
assert_delete_doc
Verifies that a document can be deleted.
- Rust
- TypeScript
#[assert_delete_doc]
fn assert_delete_doc(context: AssertDeleteDocContext) -> Result<(), String> {
// Custom logic for asserting a document can be deleted
// Return an error if the condition fails to prevent the action
Ok(())
}
export const assertDeleteDoc = defineAssert<AssertDeleteDoc>({
collections: [],
assert: (context) => {
// Custom logic for asserting a document can be deleted
// Throw an error if the condition fails to prevent the action
}
});
assert_upload_asset
Confirms an asset upload can be committed.
- Rust
- TypeScript
#[assert_upload_asset]
fn assert_upload_asset(_context: AssertUploadAssetContext) -> Result<(), String> {
// Custom logic for asserting an asset upload is possible
// Return an error if the condition fails to prevent the action
Ok(())
}
export const assertUploadAsset = defineAssert<AssertUploadAsset>({
collections: [],
assert: (context) => {
// Custom logic for asserting an asset upload is possible
// Throw an error if the condition fails to prevent the action
}
});
assert_delete_asset
Checks that an asset can be deleted.
- Rust
- TypeScript
#[assert_delete_asset]
fn assert_delete_asset(_context: AssertDeleteAssetContext) -> Result<(), String> {
// Custom logic for asserting an asset can be deleted
// Return an error if the condition fails to prevent the action
Ok(())
}
export const assertDeleteAsset = defineAssert<AssertDeleteAsset>({
collections: [],
assert: (context) => {
// Custom logic for asserting an asset can be deleted
// Throw an error if the condition fails to prevent the action
}
});
When the Functions Run
When no attributes are provided, the hook is triggered for any document set in any collection. For better control and performance, it’s recommended to scope the hook to a specific list of collections
.
This behavior applies to all hooks and assertions, except for the lifecycle hooks such as on_init
or on_post_upgrade
, which operate globally.
A hook is only executed if the function is declared and exported. Additionally, the collections
field must be defined. If it's empty, the hook will not run.
This behavior applies to all hooks and assertions, except for the lifecycle hooks such as on_init
or on_post_upgrade
, which operate globally.
- Rust
- TypeScript
#[on_set_doc(collections = ["demo"])]
async fn on_set_doc(context: OnSetDocContext) -> Result<(), String> {
// Custom logic for handling document creation or updates
Ok(())
}
The attributes accept a list of comma-separated collections. If the attribute array is left empty, the hook will never be called.
export const onSetDoc = defineHook<OnSetDoc>({
collections: ["demo"],
run: async (context) => {
// Custom logic for handling document creation or updates
}
});
The collections
attribute accepts a list of comma-separated collection names.