Overview

There are 7 methods you can use to interact with the database. They are used in conjunction with the db property from the useBasic() hook, and are appended in the format of db.collection('tablename').METHOD().

Methods

.get()

.get(id: string)

Promise<T | null>

Fetch a single item from the table by its ID. Returns null if not found.

.getAll()

Promise<T[]>

Fetch all items from the table. Returns an empty array if no items exist.

In the React / Next.js client SDK (sync or remote mode), .getAll() loads items for that collection and .filter() applies your predicate on the client after fetch. For server-side query parameters on HTTP, use the REST API filtering guide against the PDS endpoints instead.

.add()

.add(data: Omit<T, 'id'>)

Promise<T>

Adds a new item to the table. The id is automatically generated by the server. Returns the created object with its new ID.

.put()

.put(data: T)

Promise<T>

Upsert (insert or replace) an item. The data object must include an id field. If an item with that ID exists, it will be replaced entirely. If not, a new item will be created. Returns the upserted object.

.update()

.update(id: string, data: Partial<T>)

Promise<T | null>

Partially update an existing item by ID. Only the fields you provide will be updated—other fields remain unchanged. Returns the updated object, or null if the item was not found.

.delete()

.delete(id: string)

Promise<boolean>

Deletes an item from the table by ID. Returns true if deleted, false if the item was not found.

.filter()

.filter(fn: (item: T) => boolean)

Promise<T[]>

Filter records using a predicate function. This fetches all records and filters client-side. Returns an array of matching objects.

Examples

Read items

There are 2 ways to read items from the database:

.get('ID_OF_ITEM'): Fetches a single item by ID
.getAll(): Fetches all items from the table

App.tsx

import { useBasic, useQuery } from '@basictech/react'
import { useState } from 'react'

function App() {
  // Import db from useBasic() inside your React component
  const { db } = useBasic()

  // Example 1: Use useQuery to "subscribe" to data from the database
  // This will automatically re-render when data changes
  const items = useQuery(() => db.collection('tablename').getAll())
  
  // Example 2: Or get a single item by ID using async/await
  const [singleItem, setSingleItem] = useState(null)
  const getItem = async () => {
    const item = await db.collection('tablename').get('ID_OF_ITEM')
    if (item) {
      setSingleItem(item)
      console.log("Successfully fetched item: ", item)
    } else {
      console.log("Item not found")
    }
  }

  return (
    <>
      {/* render items */}
    </>
  )
}

Add new item

App.tsx

import { useBasic } from '@basictech/react'

function App() {
  const { db } = useBasic()

  // Use .add() to add items - id is auto-generated
  const addItem = async () => {
    const newItem = await db.collection('tablename').add({ name: 'cutie' })
    console.log("Created item with ID: ", newItem.id)
  }

  return (
    <>
      <button onClick={addItem}>Add Item</button>
    </>
  )
}

Put (upsert) item

App.tsx

import { useBasic } from '@basictech/react'

function App() {
  const { db } = useBasic()

  // Use .put() to upsert items - requires id in data
  const upsertItem = async () => {
    const item = await db.collection('tablename').put({ 
      id: 'specific-id-123', 
      name: 'updated name',
      completed: true 
    })
    console.log("Upserted item: ", item)
  }

  return (
    <>
      <button onClick={upsertItem}>Upsert Item</button>
    </>
  )
}

Update item

App.tsx

import { useBasic } from '@basictech/react'

function App() {
  const { db } = useBasic()

  // Use .update() to partially update items
  // Only the fields you provide will be changed
  const updateItem = async () => {
    const updated = await db.collection('tablename').update('ID_OF_ITEM', { 
      name: 'super cute' 
    })
    if (updated) {
      console.log("Successfully updated item: ", updated)
    } else {
      console.log("Item not found")
    }
  }

  return (
    <>
      <button onClick={updateItem}>Update Item</button>
    </>
  )
}

Delete item

App.tsx

import { useBasic } from '@basictech/react' 

function App() {
  const { db } = useBasic()

  // Use .delete() to delete items by ID
  const deleteItem = async () => {
    const deleted = await db.collection('tablename').delete('ID_OF_ITEM')
    if (deleted) {
      console.log("Successfully deleted item")
    } else {
      console.log("Item not found")
    }
  }

  return (
    <>
      <button onClick={deleteItem}>Delete Item</button>
    </>
  )
}

Filter items

App.tsx

import { useBasic } from '@basictech/react'
import { useState } from 'react'

function App() {
  const { db } = useBasic()
  const [completedItems, setCompletedItems] = useState([])

  // Use .filter() to filter items client-side
  const getCompletedItems = async () => {
    const items = await db.collection('todos').filter(
      (item) => item.completed === true
    )
    setCompletedItems(items)
    console.log("Completed items: ", items)
  }

  return (
    <>
      <button onClick={getCompletedItems}>Get Completed</button>
    </>
  )
}

TypeScript Support

The collection method supports generics for type-safe database operations:

App.tsx

import { useBasic } from '@basictech/react'

// Define your item type
type Todo = {
  id: string
  title: string
  completed: boolean
  createdAt: string
}

function App() {
  const { db } = useBasic()

  // Type-safe collection access
  const todos = db.collection<Todo>('todos')

  const addTodo = async () => {
    // TypeScript knows the shape of your data
    const newTodo = await todos.add({
      title: 'Learn Basic',
      completed: false,
      createdAt: new Date().toISOString()
    })
    console.log(newTodo.id) // TypeScript knows this exists
  }

  return <button onClick={addTodo}>Add Todo</button>
}

React Guide

Guides

SDK Reference

Database (get, add, update, delete, etc.)

Overview

Methods

.get()

.getAll()

.add()

.put()

.update()

.delete()

.filter()

Examples

Read items

Add new item

Put (upsert) item

Update item

Delete item

Filter items

TypeScript Support

​Overview

​Methods

​.get()

​.getAll()

​.add()

​.put()

​.update()

​.delete()

​.filter()

​Examples

​Read items

​Add new item

​Put (upsert) item

​Update item

​Delete item

​Filter items

​TypeScript Support

Overview

Methods

.get()

.getAll()

.add()

.put()

.update()

.delete()

.filter()

Examples

Read items

Add new item

Put (upsert) item

Update item

Delete item

Filter items

TypeScript Support