mirror of
https://github.com/ilyakooo0/purescript-indexedDB.git
synced 2024-09-11 15:05:46 +03:00
rework README
This commit is contained in:
parent
cba6b08b7a
commit
1a1e3e3810
BIN
.github/browserstack.png
vendored
Normal file
BIN
.github/browserstack.png
vendored
Normal file
Binary file not shown.
After Width: | Height: | Size: 10 KiB |
304
README.md
304
README.md
@ -1,283 +1,53 @@
|
|||||||
## API
|
PureScript IndexedDB [![](https://img.shields.io/badge/doc-pursuit-60b5cc.svg)](http://pursuit.purescript.org/packages/purescript-indexeddb) [![Build Status](https://travis-ci.org/truqu/purescript-indexeddb.svg?branch=master)](https://travis-ci.org/truqu/purescript-indexeddb)
|
||||||
|
=====
|
||||||
|
|
||||||
This document is a general grooming of the current state of the IndexedDB API. It covers only
|
This package offers complete bindings and type-safety upon the [IndexedDB API](https://w3c.github.io/IndexedDB).
|
||||||
the features specified in the official specs.
|
|
||||||
|
|
||||||
### Remarks
|
## Overview
|
||||||
|
|
||||||
- Better define a 'all' range instead of using Maybe `IDBKeyRange` in function
|
```purescript
|
||||||
signatures (Nothing meaning 'all').
|
main :: Eff (idb :: IDB, exception :: EXCEPTION, console :: CONSOLE) Unit
|
||||||
|
main = launchAff' do
|
||||||
|
db <- IDBFactory.open "db" Nothing { onBlocked : Nothing
|
||||||
|
, onUpgradeNeeded : Just onUpgradeNeeded
|
||||||
|
}
|
||||||
|
|
||||||
- Some errors (like TypeError or DataError) can be avoided via static typing
|
tx <- IDBDatabase.transaction db ["store"] ReadOnly
|
||||||
|
store <- IDBTransaction.objectStore tx "store"
|
||||||
|
(val :: Maybe String) <- IDBObjectStore.get store (IDBKeyRange.only 1)
|
||||||
|
log $ maybe "not found" id val
|
||||||
|
|
||||||
- The `IDBRequest` is mostly a callback result holding an error or a value. We probably want to
|
|
||||||
use a typed Except or ExceptT instead.
|
|
||||||
|
|
||||||
|
onUpgradeNeeded :: forall e. Database -> Transaction -> Eff (idb :: IDB, exception :: EXCEPTION | e) Unit
|
||||||
|
onUpgradeNeeded db _ = launchAff' do
|
||||||
|
store <- IDBDatabase.createObjectStore db "store" IDBObjectStore.defaultParameters
|
||||||
|
_ <- IDBObjectStore.add store "patate" (Just 1)
|
||||||
|
_ <- IDBObjectStore.add store { property: 42 } (Just 2)
|
||||||
|
_ <- IDBObjectStore.createIndex store "index" ["property"] IDBIndex.defaultParameters
|
||||||
|
pure unit
|
||||||
|
```
|
||||||
|
|
||||||
### Table of Contents
|
## Changelog
|
||||||
|
|
||||||
- [IDBCursor](#idbcursor)
|
- Release incoming
|
||||||
- [IDBCursorWithValue](#idbcursorwithvalue)
|
|
||||||
- [IDBCursorDirection](#idbcursordirection)
|
|
||||||
- [IDBDatabase](#idbdatabase)
|
|
||||||
- [IDBError](#idberror)
|
|
||||||
- [IDBFactory](#idbfactory)
|
|
||||||
- [IDBIndex](#idbindex)
|
|
||||||
- [IDBKeyRange](#idbkeyrange)
|
|
||||||
- [IDBRequest](#idbrequest)
|
|
||||||
- [IDBOpenDBRequest](#idbopendbrequest)
|
|
||||||
- [IDBObjectStore](#idbobjectstore)
|
|
||||||
- [IDBTransaction](#idbtransaction)
|
|
||||||
- [IDBTransactionMode](#idbtransactionmode)
|
|
||||||
|
|
||||||
|
#### TODO
|
||||||
|
|
||||||
---
|
- Add support for `index.getAll` method
|
||||||
|
- Complete the specifications with the [official tests list](https://github.com/w3c/web-platform-tests/blob/master/IndexedDB/README.md) provided by W3C
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
#### IDBCursor
|
Module documentation is [published on Pursuit](http://pursuit.purescript.org/packages/purescript-indexeddb).
|
||||||
> https://developer.mozilla.org/en-US/docs/Web/API/IDBCursor
|
|
||||||
|
|
||||||
- source :: [IDBIndex](#idbindex), [IDBObjectStore](#idbobjectstore)
|
## Testing
|
||||||
- direction :: [IDBCursorDirection](#idbcursordirection)
|
Tested in the cloud on multiple browsers and operating systems thanks to [BrowserStack](https://www.browserstack.com)
|
||||||
- key :: [IDBKey](#idbkey)
|
|
||||||
- primaryKey :: [IDBKey](#idbkey)
|
|
||||||
- value :: Any
|
|
||||||
- advance :: [IDBCursor](#idbcursor) -> Int -> ()
|
|
||||||
> `throw` TransactionInactiveError, TypeError, InvalidStateError
|
|
||||||
- continue :: [IDBCursor](#idbcursor) -> Maybe [IDBKey](#idbkey) -> ()
|
|
||||||
> `throw` TransactionInactivError, DataError, InvalidStateError
|
|
||||||
- continuePrimaryKey :: [IDBCursor](#idbcursor) -> [IDBKey](#idbkey) -> [IDBKey](#idbkey) -> ()
|
|
||||||
> `throw` TransactionInactiveError, DataError, InvalidStateError, InvalidAccessError
|
|
||||||
|
|
||||||
|
|
||||||
---
|
| IE / Edge | Chrome | Firefox | Safari | Opera | Android | iOS Safari |
|
||||||
|
| ----------| ------ | ------- | ------- | ----- | ------- | ---------- |
|
||||||
|
| - | >= 56 | >= 51 | >= 10.1 | >= 43 | >= 4.4 | >= 10.3 |
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
#### IDBCursorWithValue
|
<a href="https://www.browserstack.com"><img alt="browserstack" src=".github/browserstack.png" /></a>
|
||||||
> https://developer.mozilla.org/en-US/docs/Web/API/IDBCursorwithValue
|
</p>
|
||||||
|
|
||||||
Inherit from [IDBCursor](#idbcursor)
|
|
||||||
|
|
||||||
- delete :: [IDBCursor](#idbcursor) -> [IDBRequest](#idbrequest) ()
|
|
||||||
> `throw` TransactionInactiveError, ReadOnlyError, InvalidStateError
|
|
||||||
- update :: [IDBCursor](#idbcursor) -> a -> [IDBRequest](#idbrequest) a
|
|
||||||
> `throw` TransactionInactiveError, ReadOnlyError, InvalidStateError, DataError, DataCloneError
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBCursorDirection
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBCursorDirection
|
|
||||||
|
|
||||||
data [IDBCursorDirection](#idbcursordirection)
|
|
||||||
= Next
|
|
||||||
| NextUnique
|
|
||||||
| Prev
|
|
||||||
| PrevUnique
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBDatabase
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBDatabase
|
|
||||||
|
|
||||||
- name :: String
|
|
||||||
- version :: Long
|
|
||||||
- objectStoreNames :: [String]
|
|
||||||
- close :: [IDBDatabase](#idbdatabase) -> ()
|
|
||||||
- createObjectStore :: [IDBDatabase](#idbdatabase) -> String -> { keyPath :: String, autoIncrement :: Bool } -> [IDBObjectStore](#idbobjectstore)
|
|
||||||
> `throw` InvalidStateError, TransactionInactiveError, ConstraintError, InvalidAccessError
|
|
||||||
- deleteObjectStore :: [IDBDatabase](#idbdatabase) -> String -> ()
|
|
||||||
> `throw` InvalidSateError, TransactionInactiveError, NotFoundError
|
|
||||||
- transaction :: [IDBDatabase](#idbdatabase) -> [String] -> [IDBTransactionMode](#idbtransactionmode) -> [IDBTransaction](#idbtransaction)
|
|
||||||
> `throw` InvalidStateError, NotFoundError, TypeError, InvalidAccessError
|
|
||||||
|
|
||||||
##### Events
|
|
||||||
- onabort
|
|
||||||
- onerror
|
|
||||||
- onversionchange
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBError
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#exceptions
|
|
||||||
|
|
||||||
data IDBError
|
|
||||||
= AbortError
|
|
||||||
| ConstraintError
|
|
||||||
| QuotaExceededError
|
|
||||||
| UnknownError
|
|
||||||
| NoError
|
|
||||||
| VersionError
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBFactory
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBFactory
|
|
||||||
|
|
||||||
The method `cmp` isn't included; instead, we consider [IDBKey](#idbkey) to be comparable.
|
|
||||||
|
|
||||||
- open :: String -> Maybe Long -> [IDBOpenDBRequest](#idbopendbrequest) ()
|
|
||||||
- deleteDatabase :: String -> [IDBOpenDBRequest](#idbopendbrequest) ()
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBIndex
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#index-concept
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#index
|
|
||||||
|
|
||||||
- name :: String
|
|
||||||
- objectStore :: [IDBObjectStore](#idbobjectstore)
|
|
||||||
- keyPath :: String
|
|
||||||
- multiEntry :: Bool
|
|
||||||
- unique :: Bool
|
|
||||||
- count :: [IDBIndex](#idbindex) -> Maybe [IDBKeyRange](#idbkeyrange) -> [IDBRequest](#idbrequest) Int
|
|
||||||
> `throw` TransactionInactiveError, DataError, InvalidStateError
|
|
||||||
- get :: [IDBIndex](#idbindex) -> [IDBKeyRange](#idbkeyrange) -> [IDBRequest](#idbrequest) a
|
|
||||||
> `throw` TransactionInactiveError, DataError, InvalidStateError
|
|
||||||
- getKey :: [IDBIndex](#idbindex) -> [IDBKeyRange](#idbkeyrange) -> [IDBRequest](#idbrequest) [IDBKey](#idbkey)
|
|
||||||
> `throw` TransactionInactiveError, DataError, InvalidStateError
|
|
||||||
- openCursor :: [IDBIndex](#idbindex) -> Maybe [IDBKeyRange](#idbkeyrange) -> Maybe Direction -> [IDBRequest](#idbrequest) CursorWithValue
|
|
||||||
> `throw` TransactionInactiveError, DataError, TypeError, InvalidStateError
|
|
||||||
- openKeyCursor :: [IDBIndex](#idbindex) -> Maybe [IDBKeyRange](#idbkeyrange)-> Maybe Direction -> [IDBRequest](#idbrequest) Cursor
|
|
||||||
> `throw` TransactionInactiveError, DataError, TypeError, InvalidStateError
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBKey
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#key-construct
|
|
||||||
|
|
||||||
Should be comparable / derive Ord
|
|
||||||
|
|
||||||
data IDBKey
|
|
||||||
= Int Int
|
|
||||||
| Float Float
|
|
||||||
| String String
|
|
||||||
| Date Date
|
|
||||||
| Array [[IDBKey](#idbkey)]
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBKeyRange
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBKeyRange
|
|
||||||
|
|
||||||
- lower :: [IDBKey](#idbkey)
|
|
||||||
- upper :: [IDBKey](#idbkey)
|
|
||||||
- lowerOpen :: Boolean
|
|
||||||
- upperOpen :: Boolean
|
|
||||||
- bound :: [IDBKey](#idbkey) -> [IDBKey](#idbkey) -> Bool -> Bool -> [IDBKeyRange](#idbkeyrange)
|
|
||||||
> `throw` DataError
|
|
||||||
- only :: [IDBKey](#idbkey) -> [IDBKeyRange](#idbkeyrange)
|
|
||||||
> `throw` DataError
|
|
||||||
- lowerBound :: [IDBKey](#idbkey) -> Bool -> [IDBKeyRange](#idbkeyrange)
|
|
||||||
> `throw` DataError
|
|
||||||
- upperBound :: [IDBKey](#idbkey) -> Bool -> [IDBKeyRange](#idbkeyrange)
|
|
||||||
> `throw` DataError
|
|
||||||
- includes :: [IDBKey](#idbkey) -> Boolean
|
|
||||||
> `throw` DataError
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBRequest
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBRequest
|
|
||||||
|
|
||||||
- error :: [IDBError](#idberror)
|
|
||||||
- result :: a
|
|
||||||
- source :: [IDBIndex](#idbindex) | [IDBObjectStore](#idbobjectstore) | [IDBCursor](#idbcursor)
|
|
||||||
- readyState :: Bool
|
|
||||||
- transaction :: Maybe [IDBTransaction](#idbtransaction)
|
|
||||||
|
|
||||||
##### Events
|
|
||||||
- onerror
|
|
||||||
- onsuccess
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBOpenDBRequest
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBRequest
|
|
||||||
|
|
||||||
Inherit from [IDBRequest](#idbrequest)
|
|
||||||
|
|
||||||
##### Events
|
|
||||||
- onblocked
|
|
||||||
- onupgradeneeded
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBObjectStore
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBObjectStore
|
|
||||||
|
|
||||||
- indexNames:: [String]
|
|
||||||
- keyPath :: String
|
|
||||||
- name :: String
|
|
||||||
- transaction :: [IDBTransaction](#idbtransaction)
|
|
||||||
- autoIncrement :: Bool
|
|
||||||
- add :: [IDBObjectStore](#idbobjectstore) -> Value -> Maybe [IDBKey](#idbkey) -> [IDBRequest](#idbrequest) ()
|
|
||||||
> `throw` ReadOnlyError, TransactionInactiveError, DataError, InvalidStateError, DataCloneError
|
|
||||||
- clear :: [IDBObjectStore](#idbobjectstore) -> [IDBRequest](#idbrequest) ()
|
|
||||||
> `throw` ReadOnlyError, TransactionInactiveError
|
|
||||||
- count :: [IDBObjectStore](#idbobjectstore) -> [IDBKeyRange](#idbkeyrange) -> [IDBRequest](#idbrequest) Int
|
|
||||||
> `throw` InvalidStateError, TransactionInactiveError, DataError
|
|
||||||
- createIndex :: [IDBObjectStore](#idbobjectstore) -> String -> String -> { unique :: Bool, multiEntry :: true } -> [IDBIndex](#idbindex)
|
|
||||||
> `throw` ConstraintError, InvalidAccessError, InvalidStateError, SyntaxError, TransactionInactiveError
|
|
||||||
- delete :: [IDBObjectStore](#idbobjectstore) -> [IDBKeyRange](#idbkeyrange) -> [IDBRequest](#idbrequest) ()
|
|
||||||
> `throw` TransactionInactiveError, ReadOnlyError, InvalidStateError, DataError
|
|
||||||
- deleteIndex :: [IDBObjectStore](#idbobjectstore) -> String -> ()
|
|
||||||
> `throw` InvalidStateError, TransactionInactiveError, NotFoundError
|
|
||||||
- get :: [IDBObjectStore](#idbobjectstore) -> [IDBKeyRange](#idbkeyrange) -> [IDBRequest](#idbrequest) a
|
|
||||||
> `throw` InvalidStateError, TransactionInactiveError, DataError
|
|
||||||
- index :: [IDBObjectStore](#idbobjectstore) -> String -> [IDBIndex](#idbindex)
|
|
||||||
> `throw` InvalidStateError, NotfoundError
|
|
||||||
- openCursor :: [IDBObjectStore](#idbobjectstore) -> Maybe [IDBKeyRange](#idbkeyrange) -> Maybe [IDBCursorDirection](#idbcursordirection) -> [IDBRequest](#idbrequest) [IDBCursorWithValue](#idbcursorwithvalue)
|
|
||||||
> `throw` TransactionInactiveError, InvalidStateError, DataError
|
|
||||||
- put :: [IDBObjectStore](#idbobjectstore) -> a -> [IDBKey](#idbkey) -> [IDBRequest](#idbrequest) ()
|
|
||||||
> `throw` ReadOnlyError, TransactionInactiveError, DataError, InvalidStateError, DataCloneError
|
|
||||||
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBTransaction
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBTransaction
|
|
||||||
|
|
||||||
- db :: [IDBDatabase](#idbdatabase)
|
|
||||||
- error :: [IDBError](#idberror)
|
|
||||||
- mode :: [IDBTransactionMode](#idbtransactionmode)
|
|
||||||
- abort :: [IDBTransaction](#idbtransaction) -> ()
|
|
||||||
> `throw` InvalidStateError
|
|
||||||
- objectStore :: [IDBTransaction](#idbtransaction) -> String -> [IDBObjectStore](#idbobjectstore)
|
|
||||||
> `throw` InvalidStateError, NotFoundError
|
|
||||||
|
|
||||||
##### Events
|
|
||||||
- onabort
|
|
||||||
- oncomplete
|
|
||||||
- onerror
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
|
|
||||||
#### IDBTransactionMode
|
|
||||||
> https://www.w3.org/TR/IndexedDB/#idl-def-IDBTransactionMode
|
|
||||||
|
|
||||||
data IDBTransactionMode
|
|
||||||
= ReadOnly
|
|
||||||
| ReadWrite
|
|
||||||
| VersionChange
|
|
||||||
|
Loading…
Reference in New Issue
Block a user