Skip to main content

​
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()

​
.getAll()
Promise<T[]>
Fetch all items from the table. Returns an empty array if no items exist.
Filtering with .getAll() is not yet supported server-side. Use .filter() for client-side filtering, or conduct filtering in your client logic. Joins are not supported yet—manually fetch from separate tables and join them in your client logic.

​
.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>
}