@fireproof/core 0.5.22 → 0.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +63 -58
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -6,74 +6,91 @@ to offer a new kind of database that:
|
|
|
6
6
|
- can be hosted on any cloud
|
|
7
7
|
- uses cryptographically verifiable protocols (what plants crave)
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Fireproof is optimized to make building React apps fast and fun, with reliable results. The data can be as mission-critical as you want, as everything is encrypted and hash-based proofs are used to verify integrity. [Great use cases](https://fireproof.storage/posts/great-opportunites-to-use-fireproof/) include everything from social media to collaborative world-building (metaverse) to executive decision support tools that can stand up to blockchain levels of scrutiny.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## React hooks API
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
Here's an example app using Fireproof and React. Look out for `useLiveQuery` and `database.put` -- that's all you really need to get started:
|
|
14
14
|
|
|
15
|
-
```
|
|
16
|
-
|
|
15
|
+
```js
|
|
16
|
+
import { useFireproof } from '@fireproof/react'
|
|
17
|
+
|
|
18
|
+
export default App = () => {
|
|
19
|
+
const { database, useLiveQuery } = useFireproof()
|
|
20
|
+
const todoList = useLiveQuery((doc) => doc.date).docs
|
|
21
|
+
const [newTodo, setNewTodo] = useState('')
|
|
22
|
+
|
|
23
|
+
return (
|
|
24
|
+
<div>
|
|
25
|
+
<input type="text" onChange={(e) => setNewTodo(e.target.value)} />
|
|
26
|
+
<button onClick={() => database.put({text: newTodo, date: Date.now(), completed: false})}>Save</button>
|
|
27
|
+
<ul>
|
|
28
|
+
{todoList.map((todo) => (
|
|
29
|
+
<li key={todo._id}>
|
|
30
|
+
<input
|
|
31
|
+
type="checkbox"
|
|
32
|
+
checked={todo.completed}
|
|
33
|
+
onChange={() => database.put({...todo, completed: !todo.completed})} />
|
|
34
|
+
{todo.text}
|
|
35
|
+
</li>
|
|
36
|
+
))}
|
|
37
|
+
</div>
|
|
38
|
+
)
|
|
39
|
+
}
|
|
17
40
|
```
|
|
18
41
|
|
|
19
|
-
|
|
42
|
+
### Features
|
|
20
43
|
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
const doc = await fireproof.get(ok.id)
|
|
26
|
-
```
|
|
44
|
+
* **Realtime** - data is updated as soon as it is available, with no polling or refreshes required.
|
|
45
|
+
* **Distributed** - data is stored in a distributed network, so it is always available.
|
|
46
|
+
* **Sync** - users can collaborate on data subsets, with changes synced across devices or via the cloud.
|
|
47
|
+
* **Proofs** - cryptographic verification makes results verifiable and lowers operating costs
|
|
27
48
|
|
|
28
|
-
|
|
49
|
+
### Architecture
|
|
29
50
|
|
|
30
|
-
|
|
51
|
+
* Powered by IPFS data structures, Fireproof can be hosted on traditional cloud or Filecoin infrastructure.
|
|
52
|
+
* Immutable content-addressed data ensures that data is always consistent, accurate, and verified
|
|
53
|
+
* Encrypted at rest and in transit, with optional clear-text database publishing for content management use cases.
|
|
54
|
+
* Open source, so you can inspect the code and make sure that it meets your security and privacy requirements.
|
|
31
55
|
|
|
32
|
-
|
|
56
|
+
Learn more about the [concepts](https://fireproof.storage/posts/from-mlops-to-point-of-sale:-merkle-proofs-and-data-locality/) and [architecture](https://fireproof.storage/documentation/how-the-database-engine-works/) behind Fireproof, or look in the `examples/` directory for projects using the database, or see [examples on CodePen](https://codepen.io/jchrisa/pen/GRYJJEM).
|
|
57
|
+
|
|
58
|
+
## ChatGPT / Bard Quick Start
|
|
59
|
+
|
|
60
|
+
Paste this to GPT 4, 3.5, or Bard to enable it to write React apps using Fireproof:
|
|
33
61
|
|
|
34
62
|
```
|
|
35
|
-
Fireproof/
|
|
63
|
+
Fireproof/React/Usage: import { useFireproof } from '@fireproof/react'; function App() { const { useLiveQuery, useLiveDocument, database } = useFireproof(); const result = useLiveQuery(doc => doc.word, { limit: 10 }); const [{ count }, saveCountDocument] = useLiveDocument({_id: 'count', count: 0}); return (<><p>{count} changes</p><input type='text' onChange={() => saveCountDocument({count: count + 1})} onSubmit={e => database.put({word: e.target.value})} /><ul>{result.map(row => (<li key={row.id}>{row.key}</li>))}</ul></>)}
|
|
36
64
|
```
|
|
37
65
|
|
|
38
66
|
In the same prompt, describe the app you want to build. Here are some examples that worked for us:
|
|
39
67
|
|
|
40
|
-
* Create a
|
|
68
|
+
* Create a React app using Fireproof for tracking party invites. It should have a text input that creates a new document with the guest name, and an Index that lists all guests in a <ul>. ([Running copy here.](https://codepen.io/jchrisa/pen/zYmogWO))
|
|
41
69
|
* Build a React app that allows you to create profiles for dogs, and browse to each profile. It should be optimized for mobile. Use Tailwind.
|
|
42
|
-
* Build a photo grid app
|
|
43
|
-
* Build an app using React, Fireproof, MagicLink, and Tailwind that allows
|
|
44
|
-
* Create a note
|
|
70
|
+
* Build a photo grid app with drag-and-drop ordering that references photos by URL. Use tailwind and render all photos as squares. Keep grid arrangement in Fireproof with one document for each gallery, that is 4-16 photos arranged into a layout.
|
|
71
|
+
* Build an app using React, Fireproof, MagicLink, and Tailwind that allows users to create one-question multiple-choice polls and collect the answers.
|
|
72
|
+
* Create a note-taking app using React, Tailwind, and Fireproof that stores each note as a large text string in a Fireproof document, and uses an Index to split the text of the documents into tokens for full-text search. The app has an input field to search the documents via an index query.
|
|
45
73
|
|
|
46
74
|
Please share your successes with us here or on [Twitter.](https://twitter.com/FireproofStorge)
|
|
47
75
|
|
|
48
|
-
|
|
76
|
+
#### Advanced AI Docs
|
|
49
77
|
|
|
50
|
-
|
|
78
|
+
You can enhance the AI's understanding by adding the core APIs. Use this if you aren't using React, or you are adding additional features to your app and you need to go deeper than the React hooks.
|
|
51
79
|
|
|
52
|
-
|
|
53
|
-
|
|
80
|
+
```
|
|
81
|
+
Fireproof/API/Usage: import { Fireproof, Index } from '@fireproof/core'; const db = fireproof.storage('app-db-name'); const ok = await db.put({ any: 'json' }); const doc = await db.get(ok.id); await db.del(doc._id); const all = await db.allDocuments(); all.rows.map(({key, value}) => value); useEffect(()=> db.subscribe(updateReactStateFn), []); const index = new Index(db, (doc, map) => map(doc.any, {custom: Object.keys(doc)})); const result = await index.query({range : ['a', 'z']}); result.rows.map(({ key }) => key);
|
|
82
|
+
```
|
|
54
83
|
|
|
55
|
-
|
|
84
|
+
### Status
|
|
56
85
|
|
|
57
|
-
|
|
58
|
-
import { Fireproof } from 'fireproof';
|
|
59
|
-
|
|
60
|
-
async function main() {
|
|
61
|
-
const database = Fireproof.storage('my-db');
|
|
62
|
-
const ok = await database.put({
|
|
63
|
-
name: 'alice',
|
|
64
|
-
age: 42
|
|
65
|
-
});
|
|
66
|
-
|
|
67
|
-
const doc = await database.get(ok.id);
|
|
68
|
-
console.log(doc.name); // 'alice'
|
|
69
|
-
}
|
|
86
|
+
Fireproof 0.6.0 is alpha software, 0.7.0 will be the first beta release. It is ready for you to evaluate for your future applications.
|
|
70
87
|
|
|
71
|
-
|
|
72
|
-
|
|
88
|
+
[](https://github.com/jchris/fireproof/actions/workflows/test.yml)
|
|
89
|
+
[](https://standardjs.com)
|
|
73
90
|
|
|
74
91
|
## Features
|
|
75
92
|
|
|
76
|
-
###
|
|
93
|
+
### Encrypted Documents
|
|
77
94
|
|
|
78
95
|
A simple put, get, and delete interface for keeping track of all your JSON documents. Once your data is in Fireproof you can access it from any app or website. Fireproof document store uses MVCC versioning and Merkle clocks so you can always recover the version you are looking for.
|
|
79
96
|
|
|
@@ -83,7 +100,7 @@ const { id, ref } = await database.put({
|
|
|
83
100
|
name: 'André',
|
|
84
101
|
age: 47
|
|
85
102
|
});
|
|
86
|
-
const doc = await database.get('three-thousand', {mvcc : true}) // mvcc is optional
|
|
103
|
+
const doc = await database.get('three-thousand', { mvcc : true }) // mvcc is optional
|
|
87
104
|
// {
|
|
88
105
|
// _id : 'three-thousand'
|
|
89
106
|
// _clock : CID(bafy84...agfw7)
|
|
@@ -92,9 +109,11 @@ const doc = await database.get('three-thousand', {mvcc : true}) // mvcc is optio
|
|
|
92
109
|
// }
|
|
93
110
|
```
|
|
94
111
|
|
|
95
|
-
|
|
112
|
+
As you can see in the return value above, the `_clock` allows you to query a stable snapshot of that version of the database. Fireproof uses immutable data structures under the hood, so you can always rollback to old data. Files can be embedded anywhere in your document using IPFS links like `{"/":"bafybeih3e3zdiehbqfpxzpppxrb6kaaw4xkbqzyr2f5pwr5refq2te2ape"}`, with API sugar coming soon.
|
|
113
|
+
|
|
114
|
+
### Live Query
|
|
96
115
|
|
|
97
|
-
|
|
116
|
+
Fireproof provides a live query interface that allows you to subscribe to changes in your data. This means that your UI will automatically update whenever there is a change to your data.
|
|
98
117
|
|
|
99
118
|
Fireproof indexes are defined by custom JavaScript functions that you write, allowing you to easily index and search your data in the way that works best for your application. Easily handle data variety and schema drift by normalizing any data to the desired index.
|
|
100
119
|
|
|
@@ -135,20 +154,6 @@ Documents changes are persisted to [Filecoin](https://filecoin.io) via [web3.sto
|
|
|
135
154
|
|
|
136
155
|
The [UCAN protocol](https://ucan.xyz) verifiably links Fireproof updates to authorized agents via cryptographic proof chains. These proofs are portable like bearer tokens, but because invocations are signed by end-user device keys, UCAN proofs don't need to be hidden to be secure, allowing for delegation of service capabilities across devices and parties. Additionally, Fireproof's Merkle clocks and hash trees are immutable and self-validating, making merging changes safe and efficient. Fireproof makes cryptographic proofs available for all of its operations, making it an ideal verifiable document database for smart contracts and other applications running in trustless environments. [Proof chains provide performance benefits as well](https://purrfect-tracker-45c.notion.site/Data-Routing-23c37b269b4c4c3dacb60d0077113bcb), by allowing recipients to skip costly I/O operations and instead cryptographically verify that changes contain all of the required context.
|
|
137
156
|
|
|
138
|
-
## Limitations 💣
|
|
139
|
-
|
|
140
|
-
### Security
|
|
141
|
-
|
|
142
|
-
Until encryption support is enabled, all data written to Fireproof is public. There are no big hurdles for this feature but it's not ready yet.
|
|
143
|
-
|
|
144
|
-
### Replication
|
|
145
|
-
|
|
146
|
-
Currently Fireproof writes transactions and proofs to [CAR files](https://ipld.io/specs/transport/car/carv2/) which are well suited for peer and cloud replication. They are stored in IndexedDB locally, with cloud replication coming very soon.
|
|
147
|
-
|
|
148
|
-
### Pre-beta Software
|
|
149
|
-
|
|
150
|
-
While the underlying data structures and libraries Fireproof uses are trusted with billions of dollars worth of data, Fireproof started in February of 2023. Results may vary.
|
|
151
|
-
|
|
152
157
|
## Thanks 🙏
|
|
153
158
|
|
|
154
159
|
Fireproof is a synthesis of work done by people in the web community over the years. I couldn't even begin to name all the folks who made pivotal contributions. Without npm, React, and VS Code all this would have taken so much longer. Thanks to everyone who supported me getting into database development via Apache CouchDB, one of the original document databases. The distinguishing work on immutable datastructures comes from the years of consideration [IPFS](https://ipfs.tech), [IPLD](https://ipld.io), and the [Filecoin APIs](https://docs.filecoin.io) have enjoyed.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fireproof/core",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Live data for
|
|
3
|
+
"version": "0.6.1",
|
|
4
|
+
"description": "Live data for React, accelerated by proofs, powered by IPFS",
|
|
5
5
|
"main": "dist/src/fireproof.js",
|
|
6
6
|
"module": "dist/src/fireproof.mjs",
|
|
7
7
|
"typings": "dist/src/fireproof.d.ts",
|