react-pouchdb
v2.1.0
Published
React wrapper for PouchDB that also subscribes to changes.
Downloads
1,683
Readme
react-pouchdb
React wrapper for PouchDB that also subscribes to changes.
Contents
Examples
Hooks
import { Suspense } from "react";
import { PouchDB, useFind, useDB } from "react-pouchdb";
function MyComponent() {
const docs = useFind({
selector: {
name: { $gte: null }
},
sort: ["name"]
});
const db = useDB();
return (
<ul>
{docs.map(doc => (
<li key={doc._id}>
{doc.name}
<button onClick={() => db.remove(doc)}>Remove</button>
</li>
))}
</ul>
);
}
<PouchDB name="dbname">
<Suspense fallback="loading...">
<MyComponent />
</Suspense>
</PouchDB>;Components
import { Suspense } from "react";
import { PouchDB, Find } from "react-pouchdb";
<PouchDB name="dbname">
<Suspense fallback="loading...">
<Find
selector={{
name: { $gte: null }
}}
sort={["name"]}
children={({ db, docs }) => (
<ul>
{docs.map(doc => (
<li key={doc._id}>
{doc.name}
<button onClick={() => db.remove(doc)}>Remove</button>
</li>
))}
</ul>
)}
/>
</Suspense>
</PouchDB>;API
useGet([db,] options)
Get document and listen to changes.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
options: object
Options to get. If other than id, attachments, ajax or binary options are set, live changes are disabled.
options.attachments: bool|string (optional)
Include document attachments. Set to "u8a" to get attachments as Uint8Arrays.
Returns
| Value | Description | Example |
| --- | --- | --- |
| undefined | Request is pending (only in Concurrent API) | undefined |
| null | Missing document | null |
| Document | Found document | {"_id": ..., "_rev": ..., ...} |
| Deleted document | Deleted document | {"_id": ..., "_rev": ..., "_deleted": true} |
import { useGet } from "react-pouchdb";
function MyComponent() {
const doc = useGet({ id: "mydoc" });
return <div>{doc.name}</div>;
}useFind([db,] options)
Find documents and listen to changes.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
options: object
Options to find.
options.sort: (string|object)[] (optional)
If sort is present, then it will be used to create a mango index with createIndex.
Returns
| Value | Description | Example |
| --- | --- | --- |
| undefined | Request is pending (only in Concurrent API) | undefined |
| Array | List of documents | [{"_id": ..., "_rev": ..., ...}, ...] |
import { useFind } from "react-pouchdb";
function MyComponent() {
const docs = useFind({
selector: {
name: { $gte: null }
},
sort: ["name"]
});
return (
<ul>
{docs.map(doc => (
<li key={doc._id}>{doc.name}</li>
))}
</ul>
);
}useAllDocs([db,] options)
Get multiple rows of document meta-data (id and rev) with optional the documents and listen to changes.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
options: object
Options to allDocs.
options.attachments: bool|string (optional)
Include document attachments. Set to "u8a" to get attachments as Uint8Arrays.
Returns
| Value | Description | Example |
| --- | --- | --- |
| undefined | Request is pending (only in Concurrent API) | undefined |
| Array | List of document meta data with the document. The rows-field from allDocs. | [{"id": "doc_id", "key": "doc_id", "value": { "rev": ... }, "doc": { ... } }, ...] |
import { useAllDocs } from "react-pouchdb";
function MyComponent() {
const rows = useAllDocs({
include_docs: true,
startkey: "profile_",
endkey: "profile_\uffff"
});
return (
<ul>
{rows.map(row => (
<li key={row.id}>{row.doc.name}</li>
))}
</ul>
);
}useDB([db])
Get the PouchDB instance from the context.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
import { useDB } from "react-pouchdb";
function MyComponent({ title }) {
const db = useDB();
return <button onClick={() => db.post({ title })}>Add</button>;
}<PouchDB>
Connect to a database and provide it from the context to other components and hooks.
name: string
maxListeners: number
Similar change requests are detected and cached. You might still need to increase the number of maxListeners, if you use useGet / <Get> with lots of different options.
...rest: any
Other props are passed to PouchDB constructor as a second argument.
<PouchDB name="dbname">
<App />
</PouchDB><Get>
Get document and listen to changes.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
<Get db="dbname" id="mydoc" ... />id: string
docId.
children: func|component|element
Function is called / component is rendered / element is cloned with props db and doc. See useGet return value for possible values for doc.
<Get id="mydoc" children={({ doc }) => <h1>{doc.title}</h1>} />attachments: bool|string
Include document attachments. Set to "u8a" to get attachments as Uint8Arrays.
<Get
attachments
id="mydoc"
children={({ doc }) => (
<>
<h1>{doc.title}</h1>
<code>{doc._attachments["att.txt"].data}</code>
</>
)}
/>...rest: any
Other props are passed to get method as second argument. If other than attachments, ajax or binary props are provided, live changes are disabled.
<Find>
Find documents and listen to changes.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
<Find db="dbname" selector={...} ... />selector: object
sort: array
If sort is present, then it will be used to create a mango index with createIndex.
limit: number
skip: number
See find.
children: func|component|element
Function is called / component is rendered / element is cloned with props db and docs. See useFind return value for possible values for docs.
<Find
selector={{
name: { $gte: null }
}}
sort={["name"]}
children={({ docs }) => (
<ul>
{docs.map(doc => (
<li key={doc._id}>{doc.name}</li>
))}
</ul>
)}
/><AllDocs>
Get multiple rows of document meta-data (id and rev) with optional the documents and listen to changes.
db: string|object (optional)
Override the context value or use as an alternative to <PouchDB>.
<AllDocs db="dbname" include_docs ... />include_docs: bool
conflicts: bool
attachments: bool|string
Include document attachments. Set to "u8a" to get attachments as Uint8Arrays.
startkey: string
endkey: string
descending: bool
keys: string[]
limit: number
skip: number
See allDocs.
children: func|component|element
Function is called / component is rendered / element is cloned with props db and rows. See useAllDocs return value for possible values for rows.
<AllDocs
include_docs
startkey="profile_"
endkey="profile_\uffff"
children={({ rows }) => (
<ul>
{rows.map(row => (
<li key={doc.id}>{row.doc.name}</li>
))}
</ul>
)}
/>withDB([db,] Component)
Higher-order component for accessing the PouchDB instance anywhere in the <PouchDB> children. Note that for convenience <Get> and <Find> render methods will be passed the db prop as well.
import { withDB } from "react-pouchdb";
const MyComponent = withDB(({ db, title }) => (
<button onClick={() => db.post({ title })}>Add</button>
));API Variants
Synchronous
It is guaranteed that the API returns with a final response value from PouchDB. Because of this, requests are made sequentially.
Import from react-pouchdb to use the Synchronous API. Example:
import { useFind, useDB } from "react-pouchdb";Concurrent
Requests are made simultaneously. The drawback is that while a request is pending, the API returns undefined, which user must handle without error, i.e. render null and use <Suspense> to show a loading indicator.
Import from react-pouchdb/concurrent to use the Concurrent API. Example:
import { useFind, useDB } from "react-pouchdb/concurrent";Package dependencies
The package expects pouchdb to be available. If you use pouchdb-browser or pouchdb-node, import from react-pouchdb/browser or react-pouchdb/node respectively.
If you use pouchdb-browser or pouchdb-node and Concurrent API, import from react-pouchdb/browser/concurrent or react-pouchdb/node/concurrent.