@fireproof/core 0.20.0-dev-preview-50 → 0.20.0-dev-preview-52

package/README.md

@@ -1,4 +1,4 @@
-# <img src="https://fireproof.storage/static/img/flame.svg" alt="Fireproof logo" width="25"> [Fireproof](https://fireproof.storage) realtime ledger
+# <img src="https://fireproof.storage/static/img/flame.svg" alt="Fireproof logo" width="25"> [Fireproof](https://fireproof.storage) database API
 
 <p align="right">
   <img src="https://img.shields.io/bundlephobia/minzip/%40fireproof%2Fcore" alt="Package size">
@@ -7,104 +7,158 @@
   </a>
 </p>
 
-### Build first, sync later: perfect for AI-generated apps and rapid prototypes
-
-Fireproof is an embedded document ledger that lets you build full-stack apps in a single file. This makes it ideal for AI code generation and rapid prototyping - just write your features and access your data anywhere.
+Fireproof is a lightweight embedded document database with encrypted live sync, designed to make browser apps easy. Use it in any JavaScript environment with a unified API that works both in React (with hooks) and as a standalone core API.
 
 [Point AI coders to these docs.](https://use-fireproof.com/llms-full.txt)
 
-### JavaScript quick start
+## Key Features
+
+- **Apps run anywhere:** Bundle UI, data, and logic in one file.
+- **Real-Time & Offline-First:** Automatic persistence and live queries, runs in the browser - no loading or error states.
+- **Unified API:** TypeScript works with Deno, Bun, Node.js, and the browser.
+- **React Hooks:** Leverage `useLiveQuery` and `useDocument` for live collaboration.
+
+Fireproof enforces cryptographic causal consistency and ledger integrity using hash history, providing git-like versioning with lightweight blockchain-style verification. Data is stored and replicated as content-addressed encrypted blobs, making it safe and easy to sync via commodity object storage providers.
 
-The document ledger API will feel familiar. Queries use dynamic indexes, and the ledger can refresh your UI, as seen in the `db.subscribe` call below, as well as the React liveQuery hook.
+## Installation
+
+The `use-fireproof` package provides both the core API and React hooks:
+
+```sh
+npm install use-fireproof
+```
+
+Works with ⚡️ ESM.sh:
 
 ```js
-import { fireproof } from "@fireproof/core";
+import { useFireproof } from "https://esm.sh/use-fireproof";
+```
 
-const db = fireproof("music-app");
+Or install the core ledger in any JavaScript environment:
 
-await db.put({ _id: "beyonce", name: "Beyoncé", hitSingles: 29 });
+```sh
+npm install @fireproof/core
+```
 
-db.subscribe(async () => {
-  const topArtists = await db.query("hitSingles", { range: [30, Infinity] });
-  // redraw the UI with the new topArtists
-});
+Add the ledger to any web page via HTML script tag (global is `Fireproof`):
 
-const beyonceDoc = await db.get("beyonce");
-beyonceDoc.hitSingles += 1;
-await db.put(beyonceDoc);
+```html
+<script src="https://cdn.jsdelivr.net/npm/@fireproof/core/dist/browser/fireproof.global.js"></script>
 ```
 
-Jump to the docs site [for JavaScript API basics.](https://use-fireproof.com/docs/ledger-api/basics)
+Deliver generated solutions as runnable micro applications via ChatGPT Canvas, v0, bolt.new, or Claude Artifacts. Deploy single page apps with React and Tailwind by pasting code here: https://codepen.io/useFireproof/pen/MYgNYdx
 
-### Live data hooks for React
+## ⚛️ React Usage
 
-Fireproof [React hooks for live data](https://use-fireproof.com/docs/category/react-hooks) avoid boilerplate and make building collaborative apps a breeze.
+React hooks are the recommended way to use Fireproof in LLM code generation contexts:
 
 ```js
-import { useFireproof } from 'use-fireproof'
+import { useFireproof } from "use-fireproof";
 
 function App() {
-  const { useLiveQuery, useDocument } = useFireproof("my-db-name")
-  const completedTodos = useLiveQuery('completed', { limit: 10 })
-  const { doc, merge, save } = useDocument(() => ({type: 'todo', text: '', completed: false, created: Date.now() }))
+  const { database, useLiveQuery, useDocument } = useFireproof("my-ledger");
+
+  // Create a new document with useDocument
+  const { doc, merge, submit } = useDocument({ text: "" });
+
+  // Query documents by _id, most recent first
+  const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });
+
+  return (
+    <div>
+      <form onSubmit={submit}>
+        <input value={doc.text} onChange={(e) => merge({ text: e.target.value })} placeholder="New document" />
+        <button type="submit">Submit</button>
+      </form>
+
+      <h3>Recent Documents</h3>
+      <ul>
+        {docs.map((doc) => (
+          <li key={doc._id}>{doc.text}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
 ```
 
-Read the [step-by-step React tutorial](https://use-fireproof.com/docs/react-tutorial) to get started.
+Read the [step-by-step React tutorial](https://use-fireproof.com/docs/react-tutorial) to get started or check the [full LLM documentation](https://use-fireproof.com/llms-full.txt) for more examples.
 
-## Why choose Fireproof
+### Working with Images
 
-Compared to other embedded ledgers, Fireproof:
+Fireproof makes it easy to store and display images in your applications. The `_files` property and `ImgFile` component handle all the complexities of file storage and retrieval:
 
-- is network aware, encrypted, and multi-writer safe
-- is designed for real-time collaboration with CRDTs
-- offers cryptographic causal integrity for all operations
-- is built for the web, with a small package size and no wasm
+```js
+// Store an image from a file input
+function handleFileUpload(e) {
+  if (e.target.files[0]) {
+    merge({
+      _files: { profilePic: e.target.files[0] },
+      uploadedAt: new Date().toISOString(),
+    });
+  }
+}
+
+// Display an image from a document
+function ImageDisplay({ doc }) {
+  return (
+    <div>
+      {doc._files?.profilePic && (
+        <ImgFile file={doc._files.profilePic} alt="Profile picture" onLoad={() => console.log("Image loaded")} />
+      )}
+      <p>Uploaded: {doc.uploadedAt}</p>
+    </div>
+  );
+}
+```
 
-Deliver interactive experiences without waiting on the backend. Fireproof runs in any cloud, browser, or edge environment, so your application can access data anywhere.
+The `ImgFile` component automatically handles loading and displaying images from Fireproof's storage, with all the expected props of a standard image element. For more in-depth examples see our [llms-full.txt](https://use-fireproof.com/llms-full.txt) documentation.
 
-[Get the latest roadmap updates on our blog](https://fireproof.storage/blog/) or join our [Discord](https://discord.gg/cCryrNHePH) to collaborate. Read the docs to learn more about the ledger [architecture](https://use-fireproof.com/docs/architecture).
+## JavaScript Core API
 
-### Use cases
+The document database API will feel familiar to those who have used other document databases:
 
-Fireproof allows web developers to build full-stack apps. It's especially useful for:
+```js
+import { fireproof } from "@fireproof/core";
 
-- Rapid prototyping
-- AI copilot safety
-- Collaborative editing
-- Personalization and configuration
-- Offline and local-first apps
+const db = fireproof("music-app");
 
-With Fireproof, you **build first** and sync via your cloud of choice when you are ready, so it's as easy to add to existing apps as it is to build something new. Drop Fireproof in your page with a script tag and start sharing interactive data.
+await db.put({ _id: "beyonce", name: "Beyoncé", hitSingles: 29 });
 
-Fireproof is a great fit for code sandboxes and online IDEs, as you can get started without any configuration. This also makes it [easy for AI to write Fireproof apps](https://use-fireproof.com/docs/chatgpt-quick-start).
+db.subscribe(async () => {
+  const topArtists = await db.query("hitSingles", { range: [30, Infinity] });
+  // redraw the UI with the new topArtists
+});
 
-### Install
+const beyonceDoc = await db.get("beyonce");
+beyonceDoc.hitSingles += 1;
+await db.put(beyonceDoc);
+```
 
-Get started with the React hooks:
+## Why choose Fireproof
 
-```sh
-npm install use-fireproof
-```
+Compared to other embedded databases, Fireproof:
 
-or install the ledger in any JavaScript environment:
+- Is network aware, encrypted, and multi-writer safe
+- Is designed for real-time collaboration with CRDTs
+- Offers cryptographic causal integrity for all operations
+- Is built for the web, with a small package size and no wasm
 
-```sh
-npm install @fireproof/core
-```
+Deliver interactive experiences without waiting on the backend. Fireproof runs in any cloud, browser, or edge environment, so your application can access data anywhere.
 
-The default build is optimized for browsers, to load the node build add `/node`:
+## Use cases
 
-```js
-import { fireproof } from "@fireproof/core/node";
-```
+Fireproof is especially useful for:
 
-Add the ledger to any web page via HTML script tag (global is `Fireproof`):
+- AI-generated apps and rapid prototypes
+- Collaborative editing
+- Offline and local-first apps
+- Personalization and configuration
+- AI copilot safety
 
-```html
-<script src="https://cdn.jsdelivr.net/npm/@fireproof/core/dist/browser/fireproof.global.js"></script>
-```
+With Fireproof, you **build first** and sync via your cloud of choice when you are ready, making it perfect for LLM code generation contexts and rapid development.
 
-Go ahead and write features, then [connect to any cloud backend](https://www.npmjs.com/package/@fireproof/connect) later.
+[Get the latest roadmap updates on our blog](https://fireproof.storage/blog/) or join our [Discord](https://discord.gg/cCryrNHePH) to collaborate. Read the docs to learn more about the [architecture](https://use-fireproof.com/docs/architecture).
 
 ### Debug
 
@@ -131,6 +185,38 @@ globalThis[Symbol.for("FP_PRESET_ENV")] = {
 };
 ```
 
+### Testing
+
+To run the full test suite across all projects (tested storage gateways configs), run:
+
+```bash
+pnpm run test
+```
+
+To run tests for specific components or modules, use the following command pattern:
+
+```bash
+pnpm run test -t 'test name pattern' path/to/test/file
+```
+
+For example, to run a specific test for the CRDT module, in just one project:
+
+```bash
+FP_DEBUG=Loader pnpm run test --project file -t 'codec implict iv' crdt
+```
+
+For testing React components, you can use:
+
+```bash
+pnpm run test tests/react/[ComponentName].test.tsx
+```
+
+Example for testing the ImgFile component:
+
+```bash
+pnpm run test tests/react/ImgFile.test.tsx
+```
+
 ### Log Formatting
 
 It's possible to change the logformat by setting FP_FORMAT to:
@@ -170,6 +256,8 @@ pnpm run build:docs
 
 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 ledger development via Apache CouchDB, one of the original document ledgers. The distinguishing work on immutable data-structures comes from the years of consideration [IPFS](https://ipfs.tech), [IPLD](https://ipld.io), and the [Filecoin APIs](https://docs.filecoin.io) have enjoyed.
 
+Thanks to [Meno Abels](https://github.com/mabels) who has taken on the role of project lead engineer. Fireproof is rapidly becoming a mature solution.
+
 Thanks to Alan Shaw and Mikeal Rogers without whom this project would have never got started. The core Merkle hash-tree clock is based on [Alan's Pail](https://github.com/alanshaw/pail), and you can see the repository history goes all the way back to work begun as a branch of that repo. Mikeal wrote [the prolly trees implementation](https://github.com/mikeal/prolly-trees).
 
 ## Contributing

package/index.cjs

@@ -1962,7 +1962,7 @@ var Index = class {
         if (this.mapFn) {
           if (mapFn) {
             if (this.mapFn.toString() !== mapFn.toString()) {
-              throw this.logger.Error().Msg("cannot apply different mapFn app2").AsError();
+              this.logger.Error().Msg("cannot apply different mapFn app2");
             }
           }
         } else {
@@ -1971,7 +1971,7 @@ var Index = class {
           }
           if (this.mapFnString) {
             if (this.mapFnString !== mapFn.toString()) {
-              throw this.logger.Error().Str("mapFnString", this.mapFnString).Str("mapFn", mapFn.toString()).Msg("cannot apply different mapFn app").AsError();
+              this.logger.Error().Str("mapFnString", this.mapFnString).Str("mapFn", mapFn.toString()).Msg("cannot apply different mapFn app");
             }
           } else {
             this.mapFnString = mapFn.toString();
@@ -4404,6 +4404,9 @@ function sanitizeDocumentFields(obj) {
       return item;
     });
   } else if (typeof obj === "object" && obj !== null) {
+    if (obj instanceof Date) {
+      return obj.toISOString();
+    }
     const typedObj = obj;
     const result = {};
     for (const key in typedObj) {
@@ -4411,8 +4414,12 @@ function sanitizeDocumentFields(obj) {
         const value = typedObj[key];
         if (value === null || !Number.isNaN(value) && value !== void 0) {
           if (typeof value === "object" && !key.startsWith("_")) {
-            const sanitized = sanitizeDocumentFields(value);
-            result[key] = sanitized;
+            if (value instanceof Date) {
+              result[key] = value.toISOString();
+            } else {
+              const sanitized = sanitizeDocumentFields(value);
+              result[key] = sanitized;
+            }
           } else {
             result[key] = value;
           }
@@ -5299,6 +5306,6 @@ __export(file_exports, {
 
 // src/version.ts
 var PACKAGE_VERSION = Object.keys({
-  "0.20.0-dev-preview-50": "xxxx"
+  "0.20.0-dev-preview-52": "xxxx"
 })[0];
 //# sourceMappingURL=index.cjs.map