From d19b84c291cfdfd962a48dfcaf0f2bb24f2f8c22 Mon Sep 17 00:00:00 2001 From: KtorZ Date: Thu, 6 Jul 2017 14:30:50 +0200 Subject: [PATCH] add documentation for IDBIndex --- src/Database/IndexedDB/IDBDatabase.purs | 10 +- src/Database/IndexedDB/IDBFactory.purs | 6 +- src/Database/IndexedDB/IDBIndex.purs | 2 + src/Database/IndexedDB/IDBIndex/Internal.purs | 134 ++++++++++++++---- 4 files changed, 113 insertions(+), 39 deletions(-) diff --git a/src/Database/IndexedDB/IDBDatabase.purs b/src/Database/IndexedDB/IDBDatabase.purs index 35d62f1..a9697bb 100644 --- a/src/Database/IndexedDB/IDBDatabase.purs +++ b/src/Database/IndexedDB/IDBDatabase.purs @@ -69,7 +69,7 @@ objectStoreNames = _objectStoreNames --- | Returns the version of the database +-- | Returns the version of the database. version :: Database -> Int @@ -80,7 +80,7 @@ version = -------------------- -- EVENT HANDLERS -- --- | Event handler for the `abort` event +-- | Event handler for the `abort` event. onAbort :: forall e e' . Database @@ -90,7 +90,7 @@ onAbort db f = Fn.runFn2 _onAbort db f --- | Event handler for the `close` event +-- | Event handler for the `close` event. onClose :: forall e e' . Database @@ -100,7 +100,7 @@ onClose db f = Fn.runFn2 _onClose db f --- | Event handler for the `error` event +-- | Event handler for the `error` event. onError :: forall e e' . Database @@ -110,7 +110,7 @@ onError db f = Fn.runFn2 _onError db f --- | Event handler for the `versionchange` event +-- | Event handler for the `versionchange` event. onVersionChange :: forall e e' . Database diff --git a/src/Database/IndexedDB/IDBFactory.purs b/src/Database/IndexedDB/IDBFactory.purs index 74ed920..81e1aa9 100644 --- a/src/Database/IndexedDB/IDBFactory.purs +++ b/src/Database/IndexedDB/IDBFactory.purs @@ -17,18 +17,18 @@ import Database.IndexedDB.Core -------------------- -- INTERFACE -- --- Type alias for binding listeners to an initial open action +-- Type alias for binding listeners to an initial open action. type OpenRequest e = { onBlocked :: Maybe (Eff (| e) Unit) , onUpgradeNeeded :: Maybe (Database -> Transaction -> Eff (| e) Unit) } --- | Type alias for DatabaseName +-- | Type alias for DatabaseName. type DatabaseName = String --- | Type alias for Version +-- | Type alias for Version. type Version = Int diff --git a/src/Database/IndexedDB/IDBIndex.purs b/src/Database/IndexedDB/IDBIndex.purs index d017716..cad2272 100644 --- a/src/Database/IndexedDB/IDBIndex.purs +++ b/src/Database/IndexedDB/IDBIndex.purs @@ -1,3 +1,5 @@ +-- | An index allows looking up records in an object store using properties of the values +-- | in the object stores records. module Database.IndexedDB.IDBIndex ( module Database.IndexedDB.IDBIndex.Internal ) where diff --git a/src/Database/IndexedDB/IDBIndex/Internal.purs b/src/Database/IndexedDB/IDBIndex/Internal.purs index 0d1b5de..8e19917 100644 --- a/src/Database/IndexedDB/IDBIndex/Internal.purs +++ b/src/Database/IndexedDB/IDBIndex/Internal.purs @@ -1,60 +1,117 @@ +-- | An index allows looking up records in an object store using properties of the values +-- | in the object stores records. module Database.IndexedDB.IDBIndex.Internal where import Prelude -import Control.Monad.Aff (Aff) -import Data.Foreign (Foreign, unsafeFromForeign) -import Data.Function.Uncurried as Fn -import Data.Function.Uncurried (Fn2, Fn3) -import Data.Maybe (Maybe) -import Data.Nullable (Nullable, toMaybe, toNullable) +import Control.Monad.Aff (Aff) +import Data.Foreign (Foreign, unsafeFromForeign) +import Data.Function.Uncurried as Fn +import Data.Function.Uncurried (Fn2, Fn3) +import Data.Maybe (Maybe) +import Data.Nullable (Nullable, toMaybe, toNullable) -import Database.IndexedDB.Core (IDB, CursorDirection, Index, Key, KeyCursor, KeyRange, - KeyPath, ObjectStore, ValueCursor) +import Database.IndexedDB.Core (IDB, CursorDirection, Index, Key, KeyCursor, KeyRange, + KeyPath, ObjectStore, ValueCursor) -------------------- -- INTERFACES -- +-- | The IDBIndex interface represents an index handle. +-- | Any of these methods throw an "TransactionInactiveError" DOMException +-- | if called when the transaction is not active. class IDBIndex index where + -- | Retrieves the number of records matching the key range in query. count :: forall e. index -> Maybe KeyRange -> Aff (idb :: IDB | e) Int + + -- | Retrieves the value of the first record matching the given key range in query. + -- | + -- | NOTE + -- | The coercion from `a` to any type is unsafe and might throw a runtime error if incorrect. get :: forall a e. index -> KeyRange -> Aff (idb :: IDB | e) (Maybe a) + + -- | Retrieves the keys of records matching the given key range in query + -- | (up to the number given if given). getAllKeys :: forall e. index -> Maybe KeyRange -> Maybe Int -> Aff (idb :: IDB | e) (Array Key) + + -- | Retrieves the key of the first record matching the given key or key range in query. getKey :: forall e. index -> KeyRange -> Aff (idb :: IDB | e) (Maybe Key) + + -- | Opens a ValueCursor over the records matching query, ordered by direction. + -- | If query is `Nothing`, all records in index are matched. openCursor :: forall e. index -> Maybe KeyRange -> CursorDirection -> Aff (idb :: IDB | e) ValueCursor + + -- | Opens a KeyCursor over the records matching query, ordered by direction. + -- | If query is `Nothing`, all records in index are matched. openKeyCursor :: forall e. index -> Maybe KeyRange -> CursorDirection -> Aff (idb :: IDB | e) KeyCursor +-- | Flags to set on the index. +-- | +-- | An index has a `unique` flag. When this flag is set, the index enforces that no +-- | two records in the index has the same key. If a record in the index’s referenced +-- | object store is attempted to be inserted or modified such that evaluating the index’s +-- | key path on the records new value yields a result which already exists in the index, +-- | then the attempted modification to the object store fails. +-- | +-- | An index has a `multiEntry` flag. This flag affects how the index behaves when the +-- | result of evaluating the index’s key path yields an array key. If the `multiEntry` flag +-- | is unset, then a single record whose key is an array key is added to the index. +-- | If the `multiEntry` flag is true, then the one record is added to the index for each +-- | of the subkeys. type IDBIndexParameters = { unique :: Boolean , multiEntry :: Boolean } +defaultParameters :: IDBIndexParameters +defaultParameters = + { unique : false + , multiEntry : false + } + + -------------------- -- ATTRIBUTES -- -keyPath :: Index -> KeyPath +-- | Returns the key path of the index. +keyPath + :: Index + -> KeyPath keyPath = _keyPath -multiEntry :: Index -> Boolean +-- | Returns true if the index's multiEntry flag is set. +multiEntry + :: Index + -> Boolean multiEntry = _multiEntry -name :: Index -> String +-- | Returns the name of the index. +name + :: Index + -> String name = _name -objectStore :: Index -> ObjectStore +-- | Returns the IDBObjectStore the index belongs to. +objectStore + :: Index + -> ObjectStore objectStore = _objectStore -unique :: Index -> Boolean +-- | Returns true if the index's unique flag is set. +unique + :: Index + -> Boolean unique = _unique @@ -102,44 +159,59 @@ instance idbIndexObjectStore :: IDBIndex ObjectStore where Fn.runFn3 _openKeyCursor store (toNullable range) (show dir) -defaultParameters :: IDBIndexParameters -defaultParameters = - { unique : false - , multiEntry : false - } - - -------------------- -- FFI -- -foreign import _keyPath :: Index -> Array String +foreign import _keyPath + :: Index + -> Array String -foreign import _multiEntry :: Index -> Boolean +foreign import _multiEntry + :: Index + -> Boolean -foreign import _name :: Index -> String +foreign import _name + :: Index + -> String -foreign import _objectStore :: Index -> ObjectStore +foreign import _objectStore + :: Index + -> ObjectStore -foreign import _unique :: Index -> Boolean +foreign import _unique + :: Index + -> Boolean -foreign import _count :: forall index e. Fn2 index (Nullable KeyRange) (Aff (idb :: IDB | e) Int) +foreign import _count + :: forall index e + . Fn2 index (Nullable KeyRange) (Aff (idb :: IDB | e) Int) -foreign import _get :: forall index e. Fn2 index KeyRange (Aff (idb :: IDB | e) (Nullable Foreign)) +foreign import _get + :: forall index e + . Fn2 index KeyRange (Aff (idb :: IDB | e) (Nullable Foreign)) -foreign import _getAllKeys :: forall index e. Fn3 index (Nullable KeyRange) (Nullable Int) (Aff (idb :: IDB | e) (Array Key)) +foreign import _getAllKeys + :: forall index e + . Fn3 index (Nullable KeyRange) (Nullable Int) (Aff (idb :: IDB | e) (Array Key)) -foreign import _getKey :: forall index e. Fn2 index KeyRange (Aff (idb :: IDB | e) (Nullable Key)) +foreign import _getKey + :: forall index e + . Fn2 index KeyRange (Aff (idb :: IDB | e) (Nullable Key)) -foreign import _openCursor :: forall index e. Fn3 index (Nullable KeyRange) String (Aff (idb :: IDB | e) ValueCursor) +foreign import _openCursor + :: forall index e + . Fn3 index (Nullable KeyRange) String (Aff (idb :: IDB | e) ValueCursor) -foreign import _openKeyCursor :: forall index e. Fn3 index (Nullable KeyRange) String (Aff (idb :: IDB | e) KeyCursor) +foreign import _openKeyCursor + :: forall index e + . Fn3 index (Nullable KeyRange) String (Aff (idb :: IDB | e) KeyCursor)