Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite the item page of the storage docs #82

Merged
merged 5 commits into from
Jul 16, 2024
Merged
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 23 additions & 17 deletions src/pages/cw-storage-plus/containers/item.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -2,31 +2,35 @@
tags: ["storage-plus", "containers"]
---

import { Callout } from "nextra/components";

# `Item`

An `Item` is a container that stores a single value under a specific key in
storage.
An `Item` is a container that contains a single value that is potentially stored
in some storage identified by a unique key.

## Item lifecycle

Merely constructing the `Item` object does not commit anything to storage. If an
`Item` has never been written to before (or the value has been
[removed](https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Item.html#method.remove)),
it will be empty.
Just creating an `Item` does not commit anything to storage yet. In order to
actually store a value into a storage, you need to call the `save` method.

Under the hood, values are serialized with [`serde`](https://serde.rs/) and
[`serde_json_wasm`](https://docs.rs/serde_json_wasm/).
At the moment, values are serialized to the underlying storage in the JSON
format. Your value must implement the `Serialize` and `Deserialize` traits from
the [`serde`] crate in order to be stored.

Use `save` to write to an `Item`.
<Callout>
This is an implementation detail that may change in the future. You should
always use the provided API methods to interact with the storage.
</Callout>

Use `load` to read from the `Item`, producing an error if the `Item` is empty or
if deserialization fails.
### Loading existing values

Use `may_load` if you want to explicitly handle the possibility the `Item` is
empty - this will produce an
[`StdError`](https://docs.rs/cosmwasm-std/latest/cosmwasm_std/enum.StdError.html)
if deserialization fails, but produce an `Ok(None)` if it is empty.
`cw-storage-plus` provides you with two functions for loading an `Item`:

More information can be found in the
[API docs](https://docs.rs/cw-storage-plus/latest/cw_storage_plus/struct.Item.html).
- `load` - which will return an error if the `Item` is empty or if
deserialization fails.
- `may_load` - which will return `Ok(None)` if the `Item` is empty, and an error
if deserialization fails.

## Usage examples

Expand Down Expand Up @@ -82,3 +86,5 @@ total += 1;

counter.save(&mut storage, &total).unwrap();
```

[`serde`]: https://serde.rs/