diff --git a/.llms-snapshots/llms-full.txt b/.llms-snapshots/llms-full.txt index 74623d31..876b3c28 100644 --- a/.llms-snapshots/llms-full.txt +++ b/.llms-snapshots/llms-full.txt @@ -1216,6 +1216,48 @@ The `deleteFilteredDocs` function allows you to delete multiple documents from a import { deleteFilteredDocs } from "@junobuild/core";await deleteFilteredDocs({ collection: "my_collection_key", filter: { // Same options as filter of listDocs }}); ``` +--- + +## Options + +This section covers additional options that can be used with most of the functions listed above. + +### Certified Reads + +All read functions support a `certified` option that can be enabled to guarantee cryptographic verification of the returned data. + +By default, uncertified reads are used for better performance and UX. Those are faster but do not provide cryptographic guarantees. + +When `options.certified` is enabled, the function performs an update call under the hood. This ensures the response is verified by the Internet Computer but may increase latency. + +#### When to Use Certified Reads + +Certified reads matter when trust in displayed information is more important than speed, or when your app exposes publicly verifiable data — such as user balances, or voting results. + +For those use cases, a common pattern is deduplicating the call: making an uncertified call for UX purposes — fetching and displaying data quickly — and an update call in parallel, which might take longer but ensures verification. If the latter fails, revert the information and warn users about the issue. + +#### Example + +``` +import { listDocs } from "@junobuild/core";await listDocs({ collection: "my_collection_key", options: { certified: true }}); +``` + +### Node.js Usage + +In Node.js or outside the browser, you must explicitly pass a `satellite` parameter specifying the satellite configuration, so the function knows which satellite to target and how to connect to it. + +This is required because `initSatellite()` is only available in browser environments. + +**Important:** + +You never need to set this parameter in a browser context. + +#### Example + +``` +import { getDoc } from "@junobuild/core";await getDoc({ collection: "my_collection_key", key: "my_document_key", satellite: { identity: myIdentity, satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai", container: true }}); +``` + # Lifecycle Understand the full journey of Serverless Functions in Juno, from setup and development to deployment and maintenance. @@ -2191,6 +2233,48 @@ The `deleteFilteredAssets` function allows you to delete multiple assets from a import { deleteFilteredAssets } from "@junobuild/core";await deleteFilteredAssets({ collection: "my_collection_key", filter: { // Uses the same filter options as listAssets }}); ``` +--- + +## Options + +This section covers additional options that can be used with most of the functions listed above. + +### Certified Reads + +All read functions support a `certified` option that can be enabled to guarantee cryptographic verification of the returned data. + +By default, uncertified reads are used for better performance and UX. Those are faster but do not provide cryptographic guarantees. + +When `options.certified` is enabled, the function performs an update call under the hood. This ensures the response is verified by the Internet Computer but may increase latency. + +#### When to Use Certified Reads + +Certified reads matter when trust in displayed information is more important than speed, or when your app exposes publicly verifiable data — such as user balances, or voting results. + +For those use cases, a common pattern is deduplicating the call: making an uncertified call for UX purposes — fetching and displaying data quickly — and an update call in parallel, which might take longer but ensures verification. If the latter fails, revert the information and warn users about the issue. + +#### Example + +``` +import { listAssets } from "@junobuild/core";await listAssets({ collection: "my_collection_key", options: { certified: true }}); +``` + +### Node.js Usage + +In Node.js or outside the browser, you must explicitly pass a `satellite` parameter specifying the satellite configuration, so the function knows which satellite to target and how to connect to it. + +This is required because `initSatellite()` is only available in browser environments. + +**Important:** + +You never need to set this parameter in a browser context. + +#### Example + +``` +import { getAsset } from "@junobuild/core";await getAsset({ collection: "my_collection_key", fullPath: "/images/logo.png", satellite: { identity: myIdentity, satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai", container: true }}); +``` + # Frontend Build full apps with Juno using your preferred frontend framework. These examples cover everything from auth to data handling with React, SvelteKit, Angular, Next.js, and more. diff --git a/docs/build/components/certified-reads.md b/docs/build/components/certified-reads.md new file mode 100644 index 00000000..04b12596 --- /dev/null +++ b/docs/build/components/certified-reads.md @@ -0,0 +1,13 @@ +### Certified Reads + +All read functions support a `certified` option that can be enabled to guarantee cryptographic verification of the returned data. + +By default, uncertified reads are used for better performance and UX. Those are faster but do not provide cryptographic guarantees. + +When `options.certified` is enabled, the function performs an update call under the hood. This ensures the response is verified by the Internet Computer but may increase latency. + +#### When to Use Certified Reads + +Certified reads matter when trust in displayed information is more important than speed, or when your app exposes publicly verifiable data — such as user balances, or voting results. + +For those use cases, a common pattern is deduplicating the call: making an uncertified call for UX purposes — fetching and displaying data quickly — and an update call in parallel, which might take longer but ensures verification. If the latter fails, revert the information and warn users about the issue. diff --git a/docs/build/components/nodejs-usage.md b/docs/build/components/nodejs-usage.md new file mode 100644 index 00000000..f121b88a --- /dev/null +++ b/docs/build/components/nodejs-usage.md @@ -0,0 +1,11 @@ +### Node.js Usage + +In Node.js or outside the browser, you must explicitly pass a `satellite` parameter specifying the satellite configuration, so the function knows which satellite to target and how to connect to it. + +This is required because `initSatellite()` is only available in browser environments. + +:::important + +You never need to set this parameter in a browser context. + +::: diff --git a/docs/build/datastore/development.mdx b/docs/build/datastore/development.mdx index 5328c8d5..927120c3 100644 --- a/docs/build/datastore/development.mdx +++ b/docs/build/datastore/development.mdx @@ -414,4 +414,45 @@ await deleteFilteredDocs({ }); ``` +--- + +## Options + +This section covers additional options that can be used with most of the functions listed above. + +import CertifiedReads from "../components/certified-reads.md"; + + + +#### Example + +```typescript +import { listDocs } from "@junobuild/core"; + +await listDocs({ + collection: "my_collection_key", + options: { certified: true } +}); +``` + +import NodeJSUsage from "../components/nodejs-usage.md"; + + + +#### Example + +```typescript +import { getDoc } from "@junobuild/core"; + +await getDoc({ + collection: "my_collection_key", + key: "my_document_key", + satellite: { + identity: myIdentity, + satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai", + container: true + } +}); +``` + [JSON]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#description diff --git a/docs/build/storage/development.mdx b/docs/build/storage/development.mdx index f55e7f74..104cc797 100644 --- a/docs/build/storage/development.mdx +++ b/docs/build/storage/development.mdx @@ -410,3 +410,44 @@ await deleteFilteredAssets({ } }); ``` + +--- + +## Options + +This section covers additional options that can be used with most of the functions listed above. + +import CertifiedReads from "../components/certified-reads.md"; + + + +#### Example + +```typescript +import { listAssets } from "@junobuild/core"; + +await listAssets({ + collection: "my_collection_key", + options: { certified: true } +}); +``` + +import NodeJSUsage from "../components/nodejs-usage.md"; + + + +#### Example + +```typescript +import { getAsset } from "@junobuild/core"; + +await getAsset({ + collection: "my_collection_key", + fullPath: "/images/logo.png", + satellite: { + identity: myIdentity, + satelliteId: "aaaaa-bbbbb-ccccc-ddddd-cai", + container: true + } +}); +```