mirror of
https://github.com/ilyakooo0/purescript-indexedDB.git
synced 2024-08-16 10:20:24 +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
|
||||
the features specified in the official specs.
|
||||
This package offers complete bindings and type-safety upon the [IndexedDB API](https://w3c.github.io/IndexedDB).
|
||||
|
||||
### Remarks
|
||||
## Overview
|
||||
|
||||
- Better define a 'all' range instead of using Maybe `IDBKeyRange` in function
|
||||
signatures (Nothing meaning 'all').
|
||||
```purescript
|
||||
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)
|
||||
- [IDBCursorWithValue](#idbcursorwithvalue)
|
||||
- [IDBCursorDirection](#idbcursordirection)
|
||||
- [IDBDatabase](#idbdatabase)
|
||||
- [IDBError](#idberror)
|
||||
- [IDBFactory](#idbfactory)
|
||||
- [IDBIndex](#idbindex)
|
||||
- [IDBKeyRange](#idbkeyrange)
|
||||
- [IDBRequest](#idbrequest)
|
||||
- [IDBOpenDBRequest](#idbopendbrequest)
|
||||
- [IDBObjectStore](#idbobjectstore)
|
||||
- [IDBTransaction](#idbtransaction)
|
||||
- [IDBTransactionMode](#idbtransactionmode)
|
||||
- Release incoming
|
||||
|
||||
#### 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
|
||||
> https://developer.mozilla.org/en-US/docs/Web/API/IDBCursor
|
||||
Module documentation is [published on Pursuit](http://pursuit.purescript.org/packages/purescript-indexeddb).
|
||||
|
||||
- source :: [IDBIndex](#idbindex), [IDBObjectStore](#idbobjectstore)
|
||||
- direction :: [IDBCursorDirection](#idbcursordirection)
|
||||
- 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
|
||||
## Testing
|
||||
Tested in the cloud on multiple browsers and operating systems thanks to [BrowserStack](https://www.browserstack.com)
|
||||
|
||||
|
||||
---
|
||||
| IE / Edge | Chrome | Firefox | Safari | Opera | Android | iOS Safari |
|
||||
| ----------| ------ | ------- | ------- | ----- | ------- | ---------- |
|
||||
| - | >= 56 | >= 51 | >= 10.1 | >= 43 | >= 4.4 | >= 10.3 |
|
||||
|
||||
|
||||
#### IDBCursorWithValue
|
||||
> https://developer.mozilla.org/en-US/docs/Web/API/IDBCursorwithValue
|
||||
|
||||
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
|
||||
<p align="center">
|
||||
<a href="https://www.browserstack.com"><img alt="browserstack" src=".github/browserstack.png" /></a>
|
||||
</p>
|
||||
|
Loading…
Reference in New Issue
Block a user