storey: container impl docs

Author: uint

Diff for: docs-test-gen/src/main.rs

@@ -12,6 +12,7 @@ static TEMPLATES: phf::Map<&'static str, &'static str> = phf_map! {
     "ibc-channel" => include_str!("../templates/ibc-channel.tpl"),
     "ibc-packet" => include_str!("../templates/ibc-packet.tpl"),
     "storage" => include_str!("../templates/storage.tpl"),
+    "storey-container-impl" => include_str!("../templates/storey-container-impl.tpl"),
     "sylvia-storey-contract" => include_str!("../templates/sylvia/storey_contract.tpl"),
     "sylvia-cw-storage-contract" => include_str!("../templates/sylvia/cw_storage_contract.tpl"),
     "sylvia-empty" => include_str!("../templates/sylvia/empty.tpl"),

Diff for: docs-test-gen/templates/storey-container-impl.tpl

@@ -0,0 +1,200 @@
+#![allow(
+    unexpected_cfgs,
+    dead_code,
+    unused_variables,
+    unused_imports,
+    clippy::new_without_default
+)]
+use cosmwasm_schema::cw_serde;
+use cosmwasm_std::*;
+use storey::containers::{IterableStorable, NonTerminal, Storable};
+use storey::storage::{IntoStorage, StorageBranch};
+
+mod users {
+    use super::*;
+
+    use cw_storage_plus::{index_list, IndexedMap, MultiIndex, UniqueIndex};
+
+    pub type Handle = String;
+
+    #[cw_serde]
+    pub struct User {
+        pub handle: String,
+        pub country: String,
+    }
+
+    pub struct ExampleUsers {
+        pub alice: User,
+        pub bob: User,
+    }
+
+    pub fn example_users() -> ExampleUsers {
+        ExampleUsers {
+            alice: User {
+                handle: "alice".to_string(),
+                country: "Wonderland".to_string(),
+            },
+            bob: User {
+                handle: "bob".to_string(),
+                country: "USA".to_string(),
+            },
+        }
+    }
+
+    #[index_list(User)]
+    pub struct UserIndexes<'a> {
+        pub handle_ix: UniqueIndex<'a, Handle, User, Addr>,
+        pub country_ix: MultiIndex<'a, String, User, Addr>,
+    }
+
+    pub fn user_indexes() -> UserIndexes<'static> {
+        user_indexes_custom("u", "uh", "uc")
+    }
+
+    pub fn user_indexes_custom(
+        ns: &'static str,
+        handle_prefix: &'static str,
+        country_prefix: &'static str,
+    ) -> UserIndexes<'static> {
+        UserIndexes {
+            handle_ix: UniqueIndex::new(|user| user.handle.clone(), handle_prefix),
+            country_ix: MultiIndex::new(|_pk, user| user.country.clone(), ns, country_prefix),
+        }
+    }
+}
+
+fn advance_height(env: &mut Env, blocks: u64) {
+    env.block.height += blocks;
+}
+
+struct MyMap<V> {
+    prefix: u8,
+    phantom: std::marker::PhantomData<V>,
+}
+
+impl<V> MyMap<V>
+where
+    V: Storable,
+{
+    pub const fn new(prefix: u8) -> Self {
+        Self {
+            prefix,
+            phantom: std::marker::PhantomData,
+        }
+    }
+
+    pub fn access<F, S>(&self, storage: F) -> MyMapAccess<V, StorageBranch<S>>
+    where
+        (F,): IntoStorage<S>,
+    {
+        let storage = (storage,).into_storage();
+        Self::access_impl(StorageBranch::new(storage, vec![self.prefix]))
+    }
+}
+
+pub struct MyMapAccess<V, S> {
+    storage: S,
+    phantom: std::marker::PhantomData<V>,
+}
+
+impl<V> Storable for MyMap<V>
+where
+    V: Storable,
+{
+    type Kind = NonTerminal;
+    type Accessor<S> = MyMapAccess<V, S>;
+
+    fn access_impl<S>(storage: S) -> MyMapAccess<V, S> {
+        MyMapAccess {
+            storage,
+            phantom: std::marker::PhantomData,
+        }
+    }
+}
+
+impl<V> IterableStorable for MyMap<V>
+where
+    V: IterableStorable,
+    <V as IterableStorable>::KeyDecodeError: std::fmt::Display,
+{
+    type Key = (u32, V::Key);
+    type KeyDecodeError = ();
+    type Value = V::Value;
+    type ValueDecodeError = V::ValueDecodeError;
+
+    fn decode_key(key: &[u8]) -> Result<Self::Key, ()> {
+        todo!()
+    }
+
+    fn decode_value(value: &[u8]) -> Result<Self::Value, Self::ValueDecodeError> {
+        V::decode_value(value)
+    }
+}
+
+impl<V, S> MyMapAccess<V, S>
+where
+    V: Storable,
+{
+    pub fn entry(&self, key: u32) -> V::Accessor<StorageBranch<&S>> {
+        let key = key.to_be_bytes().to_vec();
+
+        V::access_impl(StorageBranch::new(&self.storage, key))
+    }
+
+    pub fn entry_mut(&mut self, key: u32) -> V::Accessor<StorageBranch<&mut S>> {
+        let key = key.to_be_bytes().to_vec();
+
+        V::access_impl(StorageBranch::new(&mut self.storage, key))
+    }
+}
+
+#[test]
+fn doctest() {
+    #[allow(unused_variables, unused_mut)]
+    let mut storage = cosmwasm_std::testing::MockStorage::new();
+    #[allow(unused_mut)]
+    let mut env = cosmwasm_std::testing::mock_env();
+
+    let users = cw_storage_plus::IndexedMap::<Addr, _, _>::new(
+        "uu",
+        users::user_indexes_custom("uu", "uuh", "uuc"),
+    );
+
+    let users_data = [
+        (
+            Addr::unchecked("aaa"),
+            users::User {
+                handle: "alice".to_string(),
+                country: "Wonderland".to_string(),
+            },
+        ),
+        (
+            Addr::unchecked("bbb"),
+            users::User {
+                handle: "bob".to_string(),
+                country: "USA".to_string(),
+            },
+        ),
+        (
+            Addr::unchecked("ccc"),
+            users::User {
+                handle: "carol".to_string(),
+                country: "UK".to_string(),
+            },
+        ),
+        (
+            Addr::unchecked("ddd"),
+            users::User {
+                handle: "dave".to_string(),
+                country: "USA".to_string(),
+            },
+        ),
+    ];
+
+    for (addr, user) in users_data {
+        users.save(&mut storage, addr, &user).unwrap();
+    }
+
+    #[rustfmt::skip]
+    {{code}}
+}

Diff for: src/pages/storey/container-impl.mdx

@@ -5,3 +5,15 @@ tags: ["storey"]
 import { Callout } from "nextra/components";
 
 # Implementing new containers
+
+Storey provides a set of built-in containers, but you're not limited to just those. For special
+needs, you can go ahead and create your own containers that will play along nicely with the rest of
+the Storey "ecosystem". If it's appropriate, your container could for example allow for nesting
+other containers - like [`Map`].
+
+In this section, you will find examples of custom containers with their full code.
+
+# Guides
+
+- [MyMap](container-impl/my-map)
+

Diff for: src/pages/storey/container-impl/_meta.js

@@ -0,0 +1,3 @@
+export default {
+    "my-map": "MyMap",
+};