grab-api
Documentation / grab-api
GrabResponse<T>
Defined in: grab-api.ts:540
Core response object that gets populated with API response data
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
Indexable
[key: string]: string | boolean | T
The actual response data - type depends on API endpoint
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
| Indicates if request is currently in progress | ||
| Error message if request failed |
GrabOptions<TResponse, TParams>
Defined in: grab-api.ts:550
Extended by
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
|
|
Indexable
[key: string]: any
All other params become GET params, POST body, and other methods
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
| include headers and authorization in the request | ||
| Pre-initialized object which becomes response JSON, no need for .data | ||
| default="GET" The HTTP method to use | ||
| default=false Whether to cache the request and from frontend cache | ||
| default=60 Seconds to consider data stale and invalidate cache | ||
| default=20 The timeout for the request in seconds | ||
| default='/api/' base url prefix, override with SERVER_API_URL env | ||
| default=true Cancel previous requests to same path | ||
| default=false Cancel if a request to path is in progress | ||
| default=false If set, how many seconds to wait between requests | ||
| default=false Whether to log the request and response | ||
[ | default=null [page key, response field to concatenate, element with results] | ||
| default=false Pass this with options to set those options as defaults for all requests | ||
| default=0 Retry failed requests this many times | ||
(... | default=log Custom logger to override the built-in color JSON log() | ||
(... | Set with defaults to modify each request data. Takes and returns in order: path, response, params, fetchParams | ||
(... | Set with defaults to modify each request data. Takes and returns in order: path, response, params, fetchParams | ||
| default=0 Repeat request this many times | ||
| default=null Repeat request every seconds | ||
| default=0 Seconds to debounce request, wait to execute so that other requests may override | ||
| default=false Refetch when cache is past staleTime | ||
| default=false Refetch on window refocus | ||
| default=false Refetch on network change | ||
| shortcut for method: "POST" | ||
| shortcut for method: "PUT" | ||
| shortcut for method: "PATCH" | ||
| default=null The body of the POST/PUT/PATCH request (can be passed into main) |
GrabRequestConfig<TResponse, TParams>
Defined in: grab-api.ts:611
Combined options and parameters interface
Extends
GrabOptions<TResponse,TParams>
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
|
|
Indexable
[key: string]: any
All other params become GET params, POST body, and other methods
Properties
| Property | Type | Description | Inherited from | Defined in |
|---|---|---|---|---|
| include headers and authorization in the request | |||
| Pre-initialized object which becomes response JSON, no need for .data | |||
| default="GET" The HTTP method to use | |||
| default=false Whether to cache the request and from frontend cache | |||
| default=60 Seconds to consider data stale and invalidate cache | |||
| default=20 The timeout for the request in seconds | |||
| default='/api/' base url prefix, override with SERVER_API_URL env | |||
| default=true Cancel previous requests to same path | |||
| default=false Cancel if a request to path is in progress | |||
| default=false If set, how many seconds to wait between requests | |||
| default=false Whether to log the request and response | |||
[ | default=null [page key, response field to concatenate, element with results] | |||
| default=false Pass this with options to set those options as defaults for all requests | |||
| default=0 Retry failed requests this many times | |||
(... | default=log Custom logger to override the built-in color JSON log() | |||
(... | Set with defaults to modify each request data. Takes and returns in order: path, response, params, fetchParams | |||
(... | Set with defaults to modify each request data. Takes and returns in order: path, response, params, fetchParams | |||
| default=0 Repeat request this many times | |||
| default=null Repeat request every seconds | |||
| default=0 Seconds to debounce request, wait to execute so that other requests may override | |||
| default=false Refetch when cache is past staleTime | |||
| default=false Refetch on window refocus | |||
| default=false Refetch on network change | |||
| shortcut for method: "POST" | |||
| shortcut for method: "PUT" | |||
| shortcut for method: "PATCH" | |||
| default=null The body of the POST/PUT/PATCH request (can be passed into main) |
GrabMockHandler<TParams, TResponse>
Defined in: grab-api.ts:617
Mock server configuration for testing
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
|
|
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
| Mock response data or function that returns response | ||
| HTTP method this mock should respond to | ||
| Request parameters this mock should match | ||
| Delay in seconds before returning mock response |
GrabLogEntry
Defined in: grab-api.ts:629
Request log entry for debugging and history
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
| API path that was requested | ||
| Stringified request parameters | ||
| Response data (only present for successful requests) | ||
| Error message (only present for failed requests) | ||
| Timestamp when request was made | ||
| Abort controller for request cancellation | ||
| Current page number for paginated requests |
GrabGlobal
Defined in: grab-api.ts:647
Global grab configuration and state
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
| Default options applied to all requests | ||
Request history and debugging info | |||
| Mock server handlers for testing | ||
( | Create a separate instance of grab with separate default options |
GrabFunction()
Defined in: grab-api.ts:659
Main grab function signature with overloads for different use cases
Call Signature
GrabFunction<TResponse>(path: string): Promise<GrabResponse<TResponse>>;
Defined in: grab-api.ts:668
Main grab function signature with overloads for different use cases
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
Parameters
| Parameter | Type |
|---|---|
|
|
Returns
Promise<GrabResponse<TResponse>>
The response object with resulting data or .error if error.
Author
See
Call Signature
GrabFunction<TResponse, TParams>(path: string, config: GrabRequestConfig<TResponse, TParams>): Promise<GrabResponse<TResponse>>;
Defined in: grab-api.ts:678
Main grab function signature with overloads for different use cases
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
|
|
Parameters
| Parameter | Type |
|---|---|
|
|
|
|
Returns
Promise<GrabResponse<TResponse>>
The response object with resulting data or .error if error.
Author
See
Properties
| Property | Type | Description | Defined in |
|---|---|---|---|
| Default options applied to all requests | ||
Request history and debugging info for all requests | |||
| Mock server handlers for testing | ||
( | Create a separate instance of grab with separate default options |
LogFunction()
Defined in: grab-api.ts:697
Log function for debugging
LogFunction(
message: string | object,
hideInProduction?: boolean,
style?: string): void;
Defined in: grab-api.ts:704
Log function for debugging
Parameters
| Parameter | Type | Description |
|---|---|---|
|
| Message to log (string or object) |
|
| Whether to hide in production (auto-detected if undefined) |
|
| CSS style string for console output |
Returns
void
PrintStructureJSONFunction()
Defined in: grab-api.ts:708
Utility function to describe JSON structure
PrintStructureJSONFunction(obj: any): string;
Defined in: grab-api.ts:714
Utility function to describe JSON structure
Parameters
| Parameter | Type | Description |
|---|---|---|
|
| The JSON object to describe |
Returns
string
String representation of object structure
GrabResponseWithData<T>
type GrabResponseWithData<T> = GrabResponse<T> & object;
Defined in: grab-api.ts:719
Type helpers for common use cases
Type declaration
| Name | Type | Defined in |
|---|---|---|
|
|
Type Parameters
| Type Parameter |
|---|
|
TypedGrabFunction()
type TypedGrabFunction = <TResponse, TParams>(path: string, config?: GrabRequestConfig<TResponse, TParams>) => Promise<GrabResponse<TResponse>>;
Defined in: grab-api.ts:725
Helper type for creating typed API clients
Type Parameters
| Type Parameter | Default type |
|---|---|
|
|
|
|
Parameters
| Parameter | Type |
|---|---|
|
|
|
|
Returns
Promise<GrabResponse<TResponse>>
grab()
function grab(path: string, options?: GrabOptions): Promise<
| Record<string, any>
| (...args: any[]) => Promise<void>>;
Defined in: grab-api.ts:81
GRAB: Generate Request to API from Browser
GRAB is the FBEST Request Manager: Functionally Brilliant, Elegantly Simple Tool
- One Function: 3Kb min, 0 dependencies, minimalist syntax, more features than top alternatives
- Auto-JSON Convert: Pass parameters and get response or error in JSON, handling other data types as is.
- isLoading Status: Sets
.isLoading=trueon the pre-initialized response object so you can show a "Loading..." in any framework - Debug Logging: Adds global
log()and prints colored JSON structure, response, timing for requests in test. - Mock Server Support: Configure
window.grab.mockfor development and testing environments - Cancel Duplicates: Prevent this request if one is ongoing to same path & params, or cancel the ongoing request.
- Timeout & Retry: Customizable request timeout, default 20s, and auto-retry on error
- DevTools:
Ctrl+Ioverlays webpage with devtools showing all requests and responses, timing, and JSON structure. - Request History: Stores all request and response data in global
grab.logobject - Pagination Infinite Scroll: Built-in pagination for infinite scroll to auto-load and merge next result page, with scroll position recovery.
- Base URL Based on Environment: Configure
grab.defaults.baseURLonce at the top, overide withSERVER_API_URLin.env. - Frontend Cache: Set cache headers and retrieve from frontend memory for repeat requests to static data.
- Regrab On Error: Regrab on timeout error, or on window refocus, or on network change, or on stale data.
- Framework Agnostic: Alternatives like TanStack work only in component initialization and depend on React & others.
- Globals: Adds to window in browser or global in Node.js so you only import once:
grab(),log(),grab.log,grab.mock,grab.defaults - TypeScript Tooltips: Developers can hover over option names and autocomplete TypeScript.
- Request Stategies: 🎯 Examples show common stategies like debounce, repeat, proxy, unit tests, interceptors, file upload, etc
- Rate Limiting: Built-in rate limiting to prevent multi-click cascading responses, require to wait seconds between requests.
- Repeat: Repeat request this many times, or repeat every X seconds to poll for updates.
- Loading Icons: Import from
grab-api.js/iconsto get enhanced animated loading icons.
Parameters
| Parameter | Type | Description |
|---|---|---|
|
| The full URL path OR relative path on this server after |
| Request params for GET or body for POST/PUT/PATCH and utility options |
Returns
Promise<
| Record<string, any>
| (...args: any[]) => Promise<void>>
The response object with resulting data or .error if error.
Author
See
Example
import grab from 'grab-api.js';
let res = {};
await grab('search', {
response: res,
query: "search words"
})
default
Renames and re-exports grab
log
Re-exports log
showAlert
Re-exports showAlert
printStructureJSON
Re-exports printStructureJSON