@@ -1,3 +1,12 @@
1+-- | The Core module gathers types used across the library and provides basic Show instances for
2+-- | those types.
3+-- |
4+-- | NOTE:
5+-- | Errors normally thrown by the IDB* interfaces are wrapped in the `Aff` Monad as `Error`
6+-- | where the `message` corresponds to the error's name (e.g. "InvalidStateError").
7+-- | Pattern matching can therefore be done on any error message to handle specific errors thrown
8+-- | by the API.
9+
110module Database.IndexedDB.Core
211 ( class FromString, parse
312 , IDB
@@ -22,43 +31,85 @@ import Data.Maybe (Maybe(..))
2231
2332import Database.IndexedDB.IDBKey
2433
25−
34+-- | IDB Effects, manifestation that something happened with the IndexedDB
2635foreign import data IDB :: Effect
2736
2837
29−data CursorDirection = Next | NextUnique | Prev | PrevUnique
38+-- | A cursor has a direction that determines whether it moves in monotonically
39+-- | increasing or decreasing order of the record keys when iterated, and if it
40+-- | skips duplicated values when iterating indexes.
41+-- | The direction of a cursor also determines if the cursor initial position is at
42+-- | the start of its source or at its end.
43+data CursorDirection
44+ = Next
45+ | NextUnique
46+ | Prev
47+ | PrevUnique
3048
3149
32−data CursorSource = ObjectStore ObjectStore | Index Index
50+-- | If the source of a cursor is an object store, the effective object store of
51+-- | the cursor is that object store and the effective key of the cursor is the
52+-- | cursor’s position. If the source of a cursor is an index, the effective object
53+-- | store of the cursor is that index’s referenced object store and the effective key
54+-- | is the cursor’s object store position.
55+data CursorSource
56+ = ObjectStore ObjectStore
57+ | Index Index
3358
3459
35−data TransactionMode = ReadOnly | ReadWrite | VersionChange
60+-- | A transaction has a mode that determines which types of interactions can be performed
61+-- | upon that transaction. The mode is set when the transaction is created and remains
62+-- | fixed for the life of the transaction.
63+data TransactionMode
64+ = ReadOnly -- ^ The transaction is only allowed to read data.
65+ | ReadWrite -- ^ The transaction is allowed to read, modify and delete data from existing object stores
66+ | VersionChange -- ^ The transaction is allowed to read, modify and delete data from existing object stores, and can also create and remove object stores and indexes.
3667
3768
38−type KeyPath = Array String
3969
70+-- | A key path is a list of strings that defines how to extract a key from a value.
71+-- | A valid key path is one of:
72+-- |
73+-- | - An empty list.
74+-- | - An singleton identifier, which is a string matching the IdentifierName production from the ECMAScript Language Specification [ECMA-262].
75+-- | - A singleton string consisting of two or more identifiers separated by periods (U+002E FULL STOP).
76+-- | - A non-empty list containing only strings conforming to the above requirements.
77+type KeyPath = Array String
4078
41−foreign import data Database :: Type
4279
80+-- | Each origin has an associated set of databases. A database has zero or more object
81+-- | stores which hold the data stored in the database.
82+foreign import data Database :: Type
4383
84+-- | An index allows looking up records in an object store using properties of the values
85+-- | in the object stores records.
4486foreign import data Index :: Type
4587
4688
89+-- | A cursor is used to iterate over a range of records in an index or an object store
90+-- | in a specific direction. A KeyCursor doesn't hold any value.
4791foreign import data KeyCursor :: Type
4892
4993
94+-- | A key range is a continuous interval over some data type used for keys.
5095foreign import data KeyRange :: Type
5196
5297
98+-- | An object store is the primary storage mechanism for storing data in a database.
5399foreign import data ObjectStore :: Type
54100
55101
102+-- | A Transaction is used to interact with the data in a database.
103+-- | Whenever data is read or written to the database it is done by using a transaction.
56104foreign import data Transaction :: Type
57105
58106
107+-- | A cursor is used to iterate over a range of records in an index or an object store
108+-- | in a specific direction. A ValueCursor also holds the value corresponding to matching key.
59109foreign import data ValueCursor :: Type
60110
61111
112+-- | FromString represents enumerations that can be represented as Strings.
62113class FromString a where
63114 parse :: String -> Maybe a
64115
@@ -72,27 +123,37 @@ instance showValueCursor :: Show ValueCursor where
72123 show = _showCursor
73124
74125
75−foreign import _showDatabase :: Database -> String
126+foreign import _showDatabase
127+ :: Database
128+ -> String
76129instance showDatabase :: Show Database where
77130 show = _showDatabase
78131
79132
80−foreign import _showIndex :: Index -> String
133+foreign import _showIndex
134+ :: Index
135+ -> String
81136instance showIndex :: Show Index where
82137 show = _showIndex
83138
84139
85−foreign import _showKeyRange :: KeyRange -> String
140+foreign import _showKeyRange
141+ :: KeyRange
142+ -> String
86143instance showKeyRange :: Show KeyRange where
87144 show = _showKeyRange
88145
89146
90−foreign import _showObjectStore :: ObjectStore -> String
147+foreign import _showObjectStore
148+ :: ObjectStore
149+ -> String
91150instance showObjectStore :: Show ObjectStore where
92151 show = _showObjectStore
93152
94153
95−foreign import _showTransaction :: Transaction -> String
154+foreign import _showTransaction
155+ :: Transaction
156+ -> String
96157instance showTransaction :: Show Transaction where
97158 show = _showTransaction
98159