improve on compound key API

Author: Ekleog

src/cursor.rs

@@ -3,7 +3,6 @@ use crate::{
     utils::{
         map_cursor_advance_err, map_cursor_advance_until_err,
         map_cursor_advance_until_primary_key_err, map_cursor_delete_err, map_cursor_update_err,
-        slice_to_array,
     },
 };
 use std::marker::PhantomData;
@@ -105,9 +104,6 @@ impl<Err> Cursor<Err> {
 
     /// Advance this [`Cursor`] until the provided key
     ///
-    /// Note that if this [`Cursor`] was built from an [`Index`], then you need to
-    /// encode the [`Array`] yourself.
-    ///
     /// Internally, this uses [`IDBCursor::continue`](https://developer.mozilla.org/en-US/docs/Web/API/IDBCursor/continue).
     pub async fn advance_until(&mut self, key: &JsValue) -> crate::Result<(), Err> {
         let Some(sys) = &self.sys else {
@@ -133,13 +129,13 @@ impl<Err> Cursor<Err> {
     /// Internally, this uses [`IDBCursor::continuePrimaryKey`](https://developer.mozilla.org/en-US/docs/Web/API/IDBCursor/continuePrimaryKey).
     pub async fn advance_until_primary_key(
         &mut self,
-        index_key: &[&JsValue],
+        index_key: &JsValue,
         primary_key: &JsValue,
     ) -> crate::Result<(), Err> {
         let Some(sys) = &self.sys else {
             return Err(crate::Error::CursorCompleted);
         };
-        sys.continue_primary_key(&slice_to_array(index_key), primary_key)
+        sys.continue_primary_key(&index_key, primary_key)
             .map_err(map_cursor_advance_until_primary_key_err)?;
         if transaction_request(self.req.clone()).await?.is_null() {
             self.sys = None;

src/database.rs

@@ -1,6 +1,6 @@
 use crate::{transaction::TransactionBuilder, utils::str_slice_to_array, ObjectStore};
 use std::marker::PhantomData;
-use web_sys::{IdbDatabase, IdbObjectStoreParameters};
+use web_sys::{js_sys::JsString, IdbDatabase, IdbObjectStoreParameters};
 
 /// Wrapper for [`IDBDatabase`](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase)
 #[derive(Debug)]
@@ -123,11 +123,21 @@ impl<'a, Err> ObjectStoreBuilder<'a, Err> {
             .map(ObjectStore::from_sys)
     }
 
+    /// Set the key path for out-of-line keys
+    ///
+    /// If you want to use a compound primary key made of multiple attributes, please see [`ObjectStoreBuilder::compound_key_path`].
+    ///
+    /// Internally, this [sets this setting](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase/createObjectStore#keypath).
+    pub fn key_path(mut self, path: &str) -> Self {
+        self.options.key_path(Some(&JsString::from(path)));
+        self
+    }
+
     /// Set the key path for out-of-line keys
     ///
     /// Internally, this [sets this setting](https://developer.mozilla.org/en-US/docs/Web/API/IDBDatabase/createObjectStore#keypath).
-    pub fn key_path(mut self, path: &[&str]) -> Self {
-        self.options.key_path(Some(&str_slice_to_array(path)));
+    pub fn compound_key_path(mut self, paths: &[&str]) -> Self {
+        self.options.key_path(Some(&str_slice_to_array(paths)));
         self
     }
 

src/index.rs

@@ -1,8 +1,7 @@
 use crate::{
     transaction::transaction_request,
     utils::{
-        array_to_vec, make_key_range_from_slice, map_count_err, map_count_res, map_get_err,
-        none_if_undefined, slice_to_array,
+        array_to_vec, make_key_range, map_count_err, map_count_res, map_get_err, none_if_undefined,
     },
 };
 use futures_util::future::{Either, FutureExt};
@@ -11,6 +10,10 @@ use web_sys::{wasm_bindgen::JsValue, IdbIndex};
 
 /// Wrapper for [`IDBIndex`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex),
 /// for use in transactions
+///
+/// Most of the functions here take a [`JsValue`] as the key(s) to use in the index. If the index was
+/// built with a compound key, then you should use eg. `js_sys::Array::from_iter([key_1, key_2])` as
+/// the key.
 pub struct Index<Err> {
     sys: IdbIndex,
     _phantom: PhantomData<Err>,
@@ -27,8 +30,8 @@ impl<Err> Index<Err> {
     /// Checks whether the provided key (for this index) already exists
     ///
     /// Internally, this uses [`IDBIndex::count`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/count).
-    pub fn contains(&self, key: &[&JsValue]) -> impl Future<Output = crate::Result<bool, Err>> {
-        match self.sys.count_with_key(&slice_to_array(key)) {
+    pub fn contains(&self, key: &JsValue) -> impl Future<Output = crate::Result<bool, Err>> {
+        match self.sys.count_with_key(key) {
             Ok(count_req) => Either::Right(
                 transaction_request(count_req).map(|res| res.map(map_count_res).map(|n| n != 0)),
             ),
@@ -39,11 +42,11 @@ impl<Err> Index<Err> {
     /// Count all the keys (for this index) in the provided range
     ///
     /// Internally, this uses [`IDBIndex::count`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/count).
-    pub fn count_in<'a>(
+    pub fn count_in(
         &self,
-        range: impl RangeBounds<[&'a JsValue]>,
+        range: impl RangeBounds<JsValue>,
     ) -> impl Future<Output = crate::Result<usize, Err>> {
-        let range = match make_key_range_from_slice(range) {
+        let range = match make_key_range(range) {
             Ok(range) => range,
             Err(e) => return Either::Left(std::future::ready(Err(e))),
         };
@@ -58,11 +61,8 @@ impl<Err> Index<Err> {
     /// Get the object with key `key` for this index
     ///
     /// Internally, this uses [`IDBIndex::get`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/get).
-    pub fn get(
-        &self,
-        key: &[&JsValue],
-    ) -> impl Future<Output = crate::Result<Option<JsValue>, Err>> {
-        match self.sys.get(&slice_to_array(key)) {
+    pub fn get(&self, key: &JsValue) -> impl Future<Output = crate::Result<Option<JsValue>, Err>> {
+        match self.sys.get(key) {
             Ok(get_req) => {
                 Either::Right(transaction_request(get_req).map(|res| res.map(none_if_undefined)))
             }
@@ -75,11 +75,11 @@ impl<Err> Index<Err> {
     /// Note that the unbounded range is not a valid range for IndexedDB.
     ///
     /// Internally, this uses [`IDBIndex::get`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/get).
-    pub fn get_first_in<'a>(
+    pub fn get_first_in(
         &self,
-        range: impl RangeBounds<[&'a JsValue]>,
+        range: impl RangeBounds<JsValue>,
     ) -> impl Future<Output = crate::Result<Option<JsValue>, Err>> {
-        let range = match make_key_range_from_slice(range) {
+        let range = match make_key_range(range) {
             Ok(range) => range,
             Err(e) => return Either::Left(std::future::ready(Err(e))),
         };
@@ -116,12 +116,12 @@ impl<Err> Index<Err> {
     /// results of `limit`, ordered by this index
     ///
     /// Internally, this uses [`IDBIndex::getAll`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/getAll).
-    pub fn get_all_in<'a>(
+    pub fn get_all_in(
         &self,
-        range: impl RangeBounds<[&'a JsValue]>,
+        range: impl RangeBounds<JsValue>,
         limit: Option<u32>,
     ) -> impl Future<Output = crate::Result<Vec<JsValue>, Err>> {
-        let range = match make_key_range_from_slice(range) {
+        let range = match make_key_range(range) {
             Ok(range) => range,
             Err(e) => return Either::Left(std::future::ready(Err(e))),
         };
@@ -140,11 +140,11 @@ impl<Err> Index<Err> {
     /// Get the first existing key (for this index) in the provided range
     ///
     /// Internally, this uses [`IDBIndex::getKey`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/getKey).
-    pub fn get_first_key_in<'a>(
+    pub fn get_first_key_in(
         &self,
-        range: impl RangeBounds<[&'a JsValue]>,
+        range: impl RangeBounds<JsValue>,
     ) -> impl Future<Output = crate::Result<Option<JsValue>, Err>> {
-        let range = match make_key_range_from_slice(range) {
+        let range = match make_key_range(range) {
             Ok(range) => range,
             Err(e) => return Either::Left(std::future::ready(Err(e))),
         };
@@ -181,12 +181,12 @@ impl<Err> Index<Err> {
     /// ordered by this index
     ///
     /// Internally, this uses [`IDBIndex::getAllKeys`](https://developer.mozilla.org/en-US/docs/Web/API/IDBIndex/getAllKeys).
-    pub fn get_all_keys_in<'a>(
+    pub fn get_all_keys_in(
         &self,
-        range: impl RangeBounds<[&'a JsValue]>,
+        range: impl RangeBounds<JsValue>,
         limit: Option<u32>,
     ) -> impl Future<Output = crate::Result<Vec<JsValue>, Err>> {
-        let range = match make_key_range_from_slice(range) {
+        let range = match make_key_range(range) {
             Ok(range) => range,
             Err(e) => return Either::Left(std::future::ready(Err(e))),
         };

src/object_store.rs

@@ -10,7 +10,7 @@ use crate::{
 use futures_util::future::{Either, FutureExt};
 use std::{future::Future, marker::PhantomData, ops::RangeBounds};
 use web_sys::{
-    js_sys::Array, wasm_bindgen::JsValue, IdbCursorDirection, IdbIndexParameters, IdbObjectStore,
+    js_sys::JsString, wasm_bindgen::JsValue, IdbCursorDirection, IdbIndexParameters, IdbObjectStore,
 };
 
 /// Wrapper for [`IDBObjectStore`](https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore),
@@ -34,17 +34,40 @@ impl<Err> ObjectStore<Err> {
     /// Note that this method can only be called from within an `on_upgrade_needed` callback. It returns
     /// a builder, and calling the `create` method on this builder will perform the actual creation.
     ///
+    /// If you want to make an index that searches multiple columns, please use [`ObjectStore::build_compound_index`].
+    ///
+    /// Internally, this uses [`IDBObjectStore::createIndex`](https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore/createIndex).
+    pub fn build_index<'a>(&self, name: &'a str, key_path: &str) -> IndexBuilder<'a, Err> {
+        IndexBuilder {
+            store: self.sys.clone(),
+            name,
+            key_path: JsString::from(key_path).into(),
+            options: IdbIndexParameters::new(),
+            _phantom: PhantomData,
+        }
+    }
+
+    /// Build a compound index over this object store
+    ///
+    /// Note that this method can only be called from within an `on_upgrade_needed` callback. It returns
+    /// a builder, and calling the `create` method on this builder will perform the actual creation.
+    ///
     /// Interesting points about indices:
     /// - It is not possible to index `bool` in IndexedDB.
     /// - If your index uses a column that does not exist, then the object will not be recorded in the index.
-    ///   This is useful for unique compound indices, usually when you'd have indexed a `bool` column otherwise.
+    ///   This is useful for unique compound indices, usually when you would have conditionally indexed a `bool` column otherwise.
+    /// - You cannot build a compound multi-entry index, it needs to be a regular index.
     ///
     /// Internally, this uses [`IDBObjectStore::createIndex`](https://developer.mozilla.org/en-US/docs/Web/API/IDBObjectStore/createIndex).
-    pub fn build_index<'a>(&self, name: &'a str, key_path: &[&str]) -> IndexBuilder<'a, Err> {
+    pub fn build_compound_index<'a>(
+        &self,
+        name: &'a str,
+        key_paths: &[&str],
+    ) -> IndexBuilder<'a, Err> {
         IndexBuilder {
             store: self.sys.clone(),
             name,
-            key_path: str_slice_to_array(key_path),
+            key_path: str_slice_to_array(key_paths).into(),
             options: IdbIndexParameters::new(),
             _phantom: PhantomData,
         }
@@ -389,7 +412,7 @@ impl<Err> ObjectStore<Err> {
 pub struct IndexBuilder<'a, Err> {
     store: IdbObjectStore,
     name: &'a str,
-    key_path: Array,
+    key_path: JsValue,
     options: IdbIndexParameters,
     _phantom: PhantomData<Err>,
 }

src/utils.rs

@@ -43,14 +43,6 @@ pub(crate) fn array_to_vec(v: JsValue) -> Vec<JsValue> {
     res
 }
 
-pub(crate) fn slice_to_array(s: &[&JsValue]) -> Array {
-    let res = Array::new_with_length(u32::try_from(s.len()).unwrap());
-    for (i, v) in s.iter().enumerate() {
-        res.set(u32::try_from(i).unwrap(), (*v).clone());
-    }
-    res
-}
-
 pub(crate) fn str_slice_to_array(s: &[&str]) -> Array {
     let res = Array::new_with_length(u32::try_from(s.len()).unwrap());
     for (i, v) in s.iter().enumerate() {
@@ -187,25 +179,6 @@ pub(crate) fn map_cursor_update_err<Err>(err: JsValue) -> crate::Error<Err> {
     }
 }
 
-fn bound_map<T, U>(b: Bound<T>, f: impl FnOnce(T) -> U) -> Bound<U> {
-    // TODO: replace with Bound::map once https://github.com/rust-lang/rust/issues/86026 is stable
-    match b {
-        Bound::Unbounded => Bound::Unbounded,
-        Bound::Included(b) => Bound::Included(f(b)),
-        Bound::Excluded(b) => Bound::Excluded(f(b)),
-    }
-}
-
-pub(crate) fn make_key_range_from_slice<'a, Err>(
-    range: impl RangeBounds<[&'a JsValue]>,
-) -> crate::Result<JsValue, Err> {
-    let range: (Bound<JsValue>, Bound<JsValue>) = (
-        bound_map(range.start_bound(), |s| slice_to_array(s).into()),
-        bound_map(range.end_bound(), |s| slice_to_array(s).into()),
-    );
-    make_key_range(range)
-}
-
 pub(crate) fn make_key_range<Err>(range: impl RangeBounds<JsValue>) -> crate::Result<JsValue, Err> {
     match (range.start_bound(), range.end_bound()) {
         (Bound::Unbounded, Bound::Unbounded) => return Err(crate::Error::InvalidRange),

tests/js.rs

@@ -50,10 +50,10 @@ async fn smoke_test() {
             let db = evt.database();
             db.build_object_store("objects").create()?;
             db.build_object_store("things")
-                .key_path(&["foo", "bar"])
+                .compound_key_path(&["foo", "bar"])
                 .create()?;
             let stuffs = db.build_object_store("stuffs").auto_increment().create()?;
-            stuffs.build_index("contents", &[""]).create()?;
+            stuffs.build_index("contents", "").create()?;
             Ok(())
         })
         .await