WatermelonDB hooks

[lucaswitch]

WatermelonDB Hooks Proposal

This idea brings React-style hooks to WatermelonDB, aligning with the hooks philosophy for better state and data management in components.

While WatermelonDB already provides observable components, hooks offer greater flexibility, improved developer experience, and cleaner integration in React components.

---

Core Assumptions

1. Hooks will rely on a context provider from WatermelonDB that supplies the database instance.
2. If the database instance is missing or not ready, the hook should return a default value (e.g. null or []).
3. When a record is updated, the hook should return a new reference to the updated object(for better dx on using that inside a side effect like useEffect).
4. Maintain only a single reference even if the same query is executed across different components. This can save memory and avoid selecting the same model all over again.
5. The user can provide a custom database on each hook in case of apps that can have multiple db instances.
6. The hooks should be implemented only using the tools that we already have in watermelon

Key hooks to implement:

• useModel – Fetches a model instance by primary key.
• useQuery – Executes a query and returns the result.
• useQuerySuspense – Execute a query in suspense way .
• useModelSuspense – Same as useModel, but uses Suspense for blocking until the data is available.
• useInfiniteQuery – Supports infinite scroll behavior, built using useQuery with pagination, and provides callbacks for loading more data (e.g. fetchNext, fetchPrevious).
• useDatabaseWrite – Receives a callback function that can perform a write in the database

---

Example: Using Hooks in a Component

import { useModel, useModelSuspense } from 'watermelondb';

export function UserProfile({ id }) {
  // Assumes that the app is wrapped in a WatermelonDB database context provider

  const user = useModel(Users.collection, id);
  const suspenseUser = useModelSuspense(Users.collection, id); // waits until user is loaded

  return (
    <View>
     {user ? <Text>Hello {user.firstName}</Text> : <Text>wait...</Text>}
    </View>
  );
}