reactite v1.0.0

reactite

reactite is a powerful and lightweight ORM designed specifically for React Native applications using SQLite3. It simplifies database management, offering a seamless way to interact with SQLite databases within your React Native apps.

Table of Contents

• reactite
• Table of Contents
• Key Features
• Installation
• Getting started
• ReactiteClient
  • ReactiteClient Options
• useReactiteClient() hook.
• useCreateTables() hook
  • Arguments
    • options
    • callbacks
  • Return Values
• useTables() hook
• useDatabaseName() hook
• useQuery() hook
  • Arguments
  • Return Values
    • Options
    • callbacks
  • Usage Notes
• usePaginatedQuery() hook
  • Arguments
  • TPaginatedQueryOptions
  • Callbacks
• Return Types
• useMutation() hook
  • Arguments
    • callbacks
• useMutationByPK() hook
  • Arguments
• useMutationByPKs() hook
  • Arguments
• useQueryByPK() hook
  • Arguments
  • Return Values
    • callbacks
• useQueryByPKs() hook.
  • Arguments
  • Return Values
    • callbacks
• Operands
• Filters
• Examples
• Contribution
• Change logs.
• LICENSE

Key Features

• Type-Safe API: Ensures that database operations are type-checked at compile time, reducing runtime errors and enhancing code reliability.
• Easy Setup: Simplifies database setup and configuration with minimal boilerplate code.
• React Integration: Provides hooks and context-based components for easy integration with React Native, making it straightforward to access and manage database connections.
• Schema Management: Includes tools for defining and managing database schemas, allowing you to create, update, and manage tables effortlessly.
• Flexible Configuration: Offers customizable options to tailor database behavior to your specific needs, including support for timestamps and connection settings.

Installation

To install Reactite, run one of the following commands based on your package manager:

# Using Yarn
yarn add reactite

# Using npm
npm install reactite

# Using pnpm
pnpm install reactite

Getting started

After installation, follow these steps to set up Reactite in your application:

Wrap Your Application: Wrap your app with the ReactiteClientProvider and provide it with a ReactiteClient client.

import { ReactiteClient, ReactiteClientProvider } from "reactite";

const client = new ReactiteClient({ dbName: "hi" });
const Layout = () => {
  return (
    <ReactiteClientProvider client={client}>
      <App />
    </ReactiteClientProvider>
  );
};

ReactiteClient

The ReactiteClient constructor takes an options object to configure the client on the sqlite3 database. The following table details the available arguments:

ReactiteClient Options

The options object can include the following properties:

useReactiteClient() hook.

The useReactiteClient hook is used to access the SQLiteDatabase instance within your React components. This hook simplifies interacting with the database by providing a direct reference to the database client.

Here's an example of how to use the useReactiteClient hook:

import { useReactiteClient } from "reactite";

const MyComponent = () => {
  // Retrieve the SQLiteDatabase instance
  const client = useReactiteClient();

  // Use the client instance to perform database operations
  // Example: client.execute('SELECT * FROM users');

  return <View>{/* Your component code here */}</View>;
};

The client gives you flexibility of excecuting raw sql statements on the sql database without using reactite hooks.

useCreateTables() hook

A custom React hook that manages the creation of SQL tables with various options and lifecycle callbacks. This hook handles the creation, error management, and provides various callbacks for handling the state of the table creation process.

Arguments

options

callbacks

Return Values

useTables() hook

This hook allows you to get all the table names in your sqlite database.

const { tables, loading } = useTables();

useDatabaseName() hook

This hook is used to get the currenly connected database name with reactite.

const { db } = useDatabaseName();

useQuery() hook

The useQuery() hook is a powerful utility for retrieving records from an SQLite database within a React Native application. It allows you to perform SQL queries while managing the state of the query process, including loading, success, and error states.

const { data, error, querying, status, success, refetchQuery } = useQuery<
  {
    username: string;
    id: number;
    avatar: string;
  }[],
  any
>(
  "users",
  flt.geq("id", 8),
  ["id", "username", "avatar"],
  {
    distinct: true,
    limit: 3,
    offset: 1,
    order: { column: "id", order: "asc" },
  },
  {
    onSettled(result) {
      console.log({ result });
    },
  }
);

Arguments

Return Values

The useQuery() hook returns an object containing the following properties:

Options

The third option of this hook is options which are the option that are passed with a query. These options are:

callbacks

As a forth argument the useQuery have callback functions that are called during the query operation.

Usage Notes

• The useQuery() hook is essential for fetching and displaying data from an SQLite database in your React Native components.
• Use the refetchQuery method to manually refresh the data when needed, such as in response to user actions.
• The querying state is useful for displaying loading indicators during data fetching.
• The error and status properties provide detailed error handling, allowing you to respond appropriately to query failures.

👍 If you want to do pagination with your SQLite reactite exposes a hook called usePaginatedQuery() which is different from the useQuery() in the sense that this hoot returns a paginated result instead of a regular query result.

usePaginatedQuery() hook

The usePaginatedQuery hook is designed to fetch paginated data from a SQLite table with various options for filtering, selecting specific columns, and handling different stages of the query process through callbacks.

import { usePaginatedQuery } from "reactite";

const { data, error, querying, status, success, fetchNextPage, refetchPage } =
  usePaginatedQuery<
    {
      username: string;
      id: number;
      avatar: string;
    }[],
    any
  >(
    "users",
    {
      distinct: true,
      pageSize: 2,
      order: { column: "id", order: "asc" },
      cursor: 1,
    },
    flt.gt("id", 5),
    ["id", "username", "avatar"],
    {
      onSettled({ data }) {},
    }
  );

Arguments

TPaginatedQueryOptions

Callbacks

Return Types

useMutation() hook

The useMutation hook is a versatile hook used for performing asynchronous mutations (insert, update, delete) on a database table within a React Native component.

import { useMutation } from "reactite";

const Post = () => {
  const [mutateAsync, { mutating }] = useMutation<{
    id: string;
    username: string;
    avatar: string | null;
    password: string;
    createAt: string;
    updatedAt: string;
  }>("users", "delete", {
    onData(result) {
      console.log(JSON.stringify(result, null, 2));
    },
    onError(error) {
      console.log(error);
    },
  });

  return (
    <Button
      title="Delete"
      onPress={async () => {
        await mutateAsync(op.or(flt.eq("id", 1), flt.in("id", [10, 11])));
      }}
    />
  );
};

This hooks takes the following as arguments:

Arguments

callbacks

This hook return a tuple of 2 values, the mutation function and a result which is an object that contains the following properties

👍 The useMutation hook is effective when you want to run mutations based on filters. However, there is a hook called useMutationByPK, which does the same thing but doesn't accept filters as it uses the table's primary key to mutate documents. Note that this hook only works for the delete and update operations.

useMutationByPK() hook

The useMutationByPK hook is a specialized hook for performing asynchronous mutations (update, delete) on a database table using the primary key of the records. This hook is a streamlined alternative to the useMutation hook, focusing on operations where only the primary key is needed.

import { useMutationByPK } from "reactite";

const Post = () => {
  const [mutateAsync, { mutating }] = useMutationByPK<{
    id: string;
    username: string;
    avatar: string | null;
    password: string;
    createAt: string;
    updatedAt: string;
  }>("users", "delete", {
    onData(result) {
      console.log(JSON.stringify(result, null, 2));
    },
    onError(error) {
      console.log(error);
    },
  });

  return (
    <Button
      title="Delete"
      onPress={async () => {
        await mutateAsync(1);
      }}
    />
  );
};

Arguments

Note that the return types of this hooks and callbacks are the same as the ones in the useMutation() hook.

👍 If you want to perform mutations based on multiple ids the useMutationByPKs do that.

useMutationByPKs() hook

The useMutationByPKs hook is a specialized hook for performing asynchronous mutations (update, delete) on multiple records in a database table using their primary keys. This hook is designed for operations where multiple primary keys are needed for the mutation.

import { useMutationByPKs } from "reactite";

const Post = () => {
  const [mutateAsync, { mutating }] = useMutationByPKs<{
    id: string;
    username: string;
    avatar: string | null;
    password: string;
    createAt: string;
    updatedAt: string;
  }>("users", "delete", {
    onData(result) {
      console.log(JSON.stringify(result, null, 2));
    },
    onError(error) {
      console.log(error);
    },
  });

  return (
    <Button
      title="Delete"
      onPress={async () => {
        await mutateAsync([1, 2, 7]);
      }}
    />
  );
};

Arguments

👍 The useMutationByPK and useMutationByPKs hooks are quite similar. The key difference is that useMutationByPK accepts a single ID, while useMutationByPKs accepts an array of IDs.

useQueryByPK() hook

The useQueryByPK() hook is designed to retrieve a record from a table in your SQLite database based on a primary key. It also allows you to specify which columns to retrieve. To use the useQueryByPK() hook, call it within your functional component, passing in the table name, an array of primary key values, and an optional array of column names you wish to retrieve. The hook returns an object containing the queried data and other useful states.

import { useQueryByPK } from "reactite";
....

const { data, error, querying, status, success, refetchQuery } = useQueryByPK<
  {
    id: string;
    username: string;
  },
  number
>("users", 8, ["id", "username"]);

Arguments

Return Values

👍 Note: The difference between useQuery and useQueryByPK is that the former takes in filters, while the latter uses your primary key column to retrieve a single record by its value.

callbacks

As a third argument the useQueryByPK have callback functions that are called during the query operation.

useQueryByPKs() hook.

The useQueryByPKs() hook is designed to retrieve multiple records from a table in your SQLite database based on an array of primary keys. It also allows you to specify which columns to retrieve.

import { useQueryByPKs } from "reactite";
....

 const { data, error, querying, status, success, refetchQuery } =
    useQueryByPKs<
      {
        id: string;
        username: string;
      },
      number
    >("users", [3, 8], ["id", "username"]);

Arguments

Return Values

👍 Note: The difference between useQueryByPK and useQueryByBKs is that the former takes in a single value of id, while the latter uses list or array primary keys to retrieve records by their primary keys.

callbacks

As a third argument the useQueryByPKs have callback functions that are called during the query operation.

Operands

The reactite operands allows you to use one or more filters in a query.

import { flt, op, useQuery } from "reactite";

// ....

const { data, error, querying, status, success, refetchQuery } = useQuery<
  {
    username: string;
    id: number;
  }[],
  any
>("users", op.or(flt.notIn("id", [8, 9]), flt.eq("id", 9)), ["id", "username"]);

Here are the supported operands in reactite.

Filters

You can get all the supported filters from reactite as follows:

import {flt} from `reactite`

 const { data, error, querying, status, success, refetchQuery } = useQuery<
    {
      username: string;
      id: number;
    }[],
    any
  >("users", flt.in("id", [8, 9]), ["id", "username"]);

Here are the filters that can be applied within queries and mutations.

Examples

In this section we are going to create 2 applications that demonstrate how to use reactite in a react native expo project.

1. Basic Crud
2. Pagination Example

Contribution

To contribute follow our guides in the CONTRIBUTION.md file

Change logs.

All the changes that will be done to reactite will be documented in the CHANGELOG.md

LICENSE

This project is using the MIT.