npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@fireproof/react

v0.10.20

Published

React hooks: useLiveQuery and useDocument for Fireproof live database

Downloads

145

Readme

Add live data to your React app. Fireproof allows you to build your app first and connect to the cloud when you are ready. Use familiar APIs to write JSON documents:

const [newTodo, updateTodo, saveTodo] = useDocument({ 
  type : "todo", 
  text : "", 
  completed: false, 
  createdAt: Date.now() 
})

And later, triggerd by UI events:

updateTodo({text : "Buy milk"})

saveTodo()

This React hooks library also includes useLiveQuery (keep reading for docs) -- together they are all you need to write collaborative apps. Read the Fireproof React hooks tutorial for a detailed getting started guide, or continue in this README for API details. Also, you can learn more about the features and benefits of Fireproof in the core database.

Quick Start

Using Fireproof in your React app is as easy as running:

npm install use-fireproof

Then in your app, you can use the top-level useLiveQuery hook to get access to the database and live query responses. Here's an example to-do list that initializes the database and sets up automatic refresh for query results. It also uses the database.put function to add new todos. With sync connected, the list of todos will redraw for all users in real-time. Here's the code:

import { useLiveQuery } from 'use-fireproof';

export default TodoList = () => {
  const todos = useLiveQuery('date').docs;
  const database = useLiveQuery.database;
  const [newTodo, setNewTodo] = useState('');

  return (
    <div>
      <input type="text" onChange={(e) => setNewTodo(e.target.value)} />
      <button
        onClick={() =>
          database.put({ text: newTodo, date: Date.now(), completed: false })
        }
      >
        Save
      </button>
      <ul>
        {todos.map((todo) => (
          <li key={todo._id}>
            <input
              type="checkbox"
              checked={todo.completed}
              onChange={() => database.put({ ...todo, completed: !todo.completed })}
            />
            {todo.text}
          </li>
        ))}
      </ul>
    </div>
  );
};

This example shows calling useLiveQuery and database.put. It may be all you need to get started. You can try out a running version here.

Hooks usage

useLiveQuery

In your components, the database object and useLiveQuery hook are returned from the useFireproof hook. You can use the useLiveQuery hook to subscribe to query results, and automatically redraw when necessary. When sync is enabled you'll have both parties updating the same database in real-time. Here's an example of a simple shared to-do list. For something like a form you should use Live Document instead. There are two ways to call useLiveQuery - as a top-level hook, or based on the return value of useFireproof, which allows you to specifc the database name and replication options. Most apps will start with the top-level useLiveQuery hook, and then move to the lower-level API when they need more control.

import { useLiveQuery } from 'use-fireproof';

export default TodoList = () => {
  const todos = useLiveQuery('date').docs
  ...

The top-level call (above) will use the default database name, and the default replication options. You can also call useLiveQuery with a database name and replication options, by instantiating the useFireproof hook directly. Here's an example that uses the lower-level API:

import { useFireproof } from 'use-fireproof';

export default TodoList = () => {
  const { database, useLiveQuery } = useFireproof("my-todo-app")
  const todos = useLiveQuery('date').docs
  ...

This running CodePen example uses the useLiveQuery to display a list of todos, and the database.put function to add new todos.

useDocument

You can also subscribe directly to database updates, and automatically redraw when necessary. When sync is enabled you'll have both parties updating the same database in real-time. Here's an example of a simple shared text area (in real life you'd probably want to use an operational transform library like Yjs or Automerge for shared text areas, which both work great with Fireproof).

Just like useLiveQuery, you can call useDocument as a top-level hook, or based on the return value of useFireproof. Here's an example that uses the top-level hook:

import { useDocument } from 'use-fireproof';

const CustomerProfile = ({ customerId }) => {
  const [doc, setDoc, saveDoc] = useDocument({
    _id: `${customerId}-profile`,
    name: "",
    company: "",
    startedAt: Date.now()
  });
  return (
    <div>
      <form>
        Name:
        <input
          type="text"
          value={doc.name}
          onChange={(e) => setDoc({ name: e.target.value })}
        />
        Company:
        <input
          type="text"
          value={doc.company}
          onChange={(e) => setDoc({ company: e.target.value })}
        />
        <button
          onClick={(e) => {
            e.preventDefault();
            saveDoc();
          }}
        >
          Save
        </button>
      </form>
          <p>Started at: {doc.startedAt}</p>
        <pre>{JSON.stringify(doc, null, 2)}</pre>
    </div>
  );
};

The top-level call (above) will use the default database name, and the default replication options. You can also call useDocument with a database name and replication options, by instantiating the useFireproof hook directly. Here's an example that uses the lower-level API:

import { useFireproof } from 'use-fireproof';

const CustomerProfile = ({ customerId }) => {
  const { database, useDocument } = useFireproof("my-todo-app")
  const [doc, setDoc, saveDoc] = useDocument({
    _id: `${customerId}-profile`,
    name: "",
    company: "",
    createdAt: new Date()
  });
  ...

Another simple use case for Live Document is a shared form, where multiple users can edit the same document at the same time. For something like a chat room you should use Live Query instead:

import { useDocument } from 'use-fireproof'

function MyComponent() {
  const [doc, setDoc, saveDoc] = useDocument({ _id : "my-doc-id" })

  return <input
          value={doc.text}
          onChange={(e) => setDoc({text : e.target.value});}
        /><button onClick={saveDoc}>Save</button>
}

Using the useFireproof hook

The other top level hook, useFireproof, takes two optional setup function arguments, defineDatabaseFn and setupDatabaseFn. See below for examples.

The return value looks like { useLiveQuery, useDocument, database, ready } where the database is the Fireproof instance that you can interact with using put and get, or via your indexes. The ready flag turns true after setup completes, you can use this to activate your UI. The useLiveQuery and useDocument functions are hooks used to update your app in real-time.

Changes made via remote sync peers, or other members of your cloud replica group will appear automatically if you use these APIs. Makes writing collaborative workgroup software, and multiplayer games super easy.

Raw database subscription

Here is an example that uses direct database APIs instead of document and query hooks. You might see this in more complex applications that want to manage low-level details.

import { useFireproof } from 'use-fireproof';

function MyComponent() {
  const { ready, database } = useFireproof();

  // set a default empty document
  const [doc, setDoc] = useState({});

  // run the loader on first mount
  useEffect(() => {
    const getDataFn = async () => {
      setDoc(await database.get('my-doc-id'));
    };
    getDataFn();
    return database.subscribe(getDataFn);
  }, [database]);

  // a function to change the value of the document
  const updateFn = async () => {
    await database.put({ _id: 'my-doc-id', hello: 'world', updated_at: new Date() });
  };

  // render the document with a click handler to update it
  return <pre onclick={updateFn}>{JSON.stringify(doc)}</pre>;
}

This should result in a tiny application that updates the document when you click it. In a real application you'd probably query an index to present eg. all of the photos in a gallery.

setupDatabaseFn

A note on using Context

If you are just calling useLiveQuery and useDocument and doing setup with the synchronous defineDatabaseFn, you may not need to manage context. If you are doing async setup work with setupDatabaseFn you will need to manage context. This allows you to run database setup code once for your entire app. Here is what you might see in App.js:

import { FireproofCtx, useFireproof } from '@fireproof/core/hooks/use-fireproof';

function App() {
  // establish the Fireproof context value
  const fpCtxValue = useFireproof('dbname', setupDatabase);

  // render the rest of the application wrapped in the Fireproof provider
  return (
    <FireproofCtx.Provider value={fpCtxValue}>
      <MyComponent />
    </FireproofCtx.Provider>
  );
}

An asynchronous function that uses the database when it's ready, run this to load fixture data, insert a dataset from somewhere else, etc. Here's a simple example:

async function setupDatabase(database)) {
    const apiData = await (await fetch('https://dummyjson.com/products')).json()
    for (const product of apiData.products) {
        await database.put(product)
    }
}

If you are running the same setup across multiple users installations, you probably want to use deterministic randomness to generate the same data on each run, so people can sync together. Here is an example of generating deterministic fixtures, using mulberry32 for deterministic randomness so re-runs give the same CID, avoiding unnecessary bloat at development time, taken from the TodoMVC demo app.

function mulberry32(a) {
  return function () {
    let t = (a += 0x6d2b79f5);
    t = Math.imul(t ^ (t >>> 15), t | 1);
    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
  };
}
const rand = mulberry32(1); // determinstic fixtures

export default async function loadFixtures(database) {
  const nextId = (prefix = '') => prefix + rand().toString(32).slice(2);
  const listTitles = ['Building Apps', 'Having Fun', 'Getting Groceries'];
  const todoTitles = [
    [
      'In the browser',
      'On the phone',
      'With or without Redux',
      'Login components',
      'GraphQL queries',
      'Automatic replication and versioning',
    ],
    ['Rollerskating meetup', 'Motorcycle ride', 'Write a sci-fi story with ChatGPT'],
    [
      'Macadamia nut milk',
      'Avocado toast',
      'Coffee',
      'Bacon',
      'Sourdough bread',
      'Fruit salad',
    ],
  ];
  let ok;
  for (let j = 0; j < 3; j++) {
    ok = await database.put({
      title: listTitles[j],
      type: 'list',
      _id: nextId('' + j),
    });
    for (let i = 0; i < todoTitles[j].length; i++) {
      await database.put({
        _id: nextId(),
        title: todoTitles[j][i],
        listId: ok.id,
        completed: rand() > 0.75,
        type: 'todo',
      });
    }
  }
}