Overview

We provide hooks for React / React Native that allow you to easily load data from Tellescope API, store in local state, and modify as needed. Some hooks work both for Users and Endusers, while others work just for Users.

API

<aside> 💡 All of the hooks are typed with TypeScript. Using an editor which is TypeScript-aware, like VSCode, will make life easy when interacting with this API

</aside>

State Hook Cheatsheet

// state management hooks take the form of useModelName (lower camel case) 
// and exist for most models as defined in the API Documentation
import { useChatRooms } from "@tellescope/react-components"

// For TypeScript, types can be accessed from this package
// import { ChatRoom } from "@tellescope/types-client" 

// types for loaded data from the API
enum LoadingStatus {
  Unloaded = 0,
  Fetching, // 1
  Error, // 2
  Loaded, // 3
}
type APIError = { message: string }
type LoadedData<T=any> = 
    { status: LoadingStatus.Unloaded, value: undefined }
  | { status: LoadingStatus.Fetching, value: undefined }
  | { status: LoadingStatus.Error, value: APIError } 
  | { status: LoadingStatus.Loaded, value: T } 

const [roomsLoading, // type: LoadingData<ChatRoom[]>
{ // Utility functions for calling API and modifying state
	addLocalElement, // adds a ChatRoom to the local state
  addLocalElements, // adds a list of ChatRooms to the local state
  createElement, // creates a ChatRoom via API, adds to local state
  createElements, // creates ChatRooms via API, adds to local state
  doneLoading, // boolean - have all pages of data been loaded?
  findById, // find a ChatRoom by id, returns null if error, undefined if loading
  loadMore, // load the next page of data
  removeElement, // delete a ChatRoom for the given id, remove from local state
  reload, // load the most recent page of data, include updates in local state
  removeLocalElements, // remove a local element from state by id
  replaceLocalElement, // args: (id: string, updated: ChatRoom)
  searchLocalElements, // given a query string, returning matching ChatRooms

	// given (id: string, updates: Partial<ChatRoom>)
	// updates a ChatRoom via API and local state
  updateElement, 

  // given (id: string, updates: Partial<ChatRoom>)
  // updates a record locally
  updateLocalElement, 
}] = useChatRooms({ 
	// options for state hooks (all are optional)

	// defaults to false, calling hook will automatically load API data
	// if true, no API GET calls will be made
	dontFetch: false, 
  
  // an object that is passed as the filter when loading API data
  // using a new loadFilter will automatically load new matching API data
  // data returned will still include all loaded data, when this is defined
  loadFilter: {}, 
})