GRAB API Reference
Documentation / GRAB-URL
GrabMockHandler<TParams, TResponse>
Defined in: GRAB-URL.ts:654
Combined options and parameters interface Mock server configuration for testing
Type Parameters
TParams
any
TResponse
any
Properties
response
TResponse | (params: TParams) => TResponse
Mock response data or function that returns response
method?
"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD"
HTTP method this mock should respond to
params?
TParams
Request parameters this mock should match
delay?
number
Delay in seconds before returning mock response
GrabLogEntry
Defined in: GRAB-URL.ts:666
Request log entry for debugging and history
Properties
path
string
API path that was requested
request
string
Stringified request parameters
response?
any
Response data (only present for successful requests)
error?
string
Error message (only present for failed requests)
lastFetchTime
number
Timestamp when request was made
controller?
AbortController
Abort controller for request cancellation
currentPage?
number
Current page number for paginated requests
GrabGlobal
Defined in: GRAB-URL.ts:684
Global grab configuration and state
Properties
defaults?
Partial<GrabOptions>
Default options applied to all requests
log?
Request history and debugging info
mock?
Record<string, GrabMockHandler>
Mock server handlers for testing
instance?
(defaultOptions?: Partial<GrabOptions>) => GrabFunction
Create a separate instance of grab with separate default options
GrabFunction()
Defined in: GRAB-URL.ts:696
Main grab function signature with overloads for different use cases
Call Signature
GrabFunction<TResponse, TParams>(path: string): Promise<GrabResponse<TResponse>>;Defined in: GRAB-URL.ts:705
Main grab function signature with overloads for different use cases
Type Parameters
TResponse
any
TParams
Record<string, any>
Parameters
path
string
Returns
Promise<GrabResponse<TResponse>>
The response object with resulting data or .error if error.
Author
See
Call Signature
GrabFunction<TResponse, TParams>(path: string, config: GrabOptions<TResponse, TParams>): Promise<GrabResponse<TResponse>>;Defined in: GRAB-URL.ts:717
Main grab function signature with overloads for different use cases
Type Parameters
TResponse
any
TParams
Record<string, any>
Parameters
path
string
config
GrabOptions<TResponse, TParams>
Returns
Promise<GrabResponse<TResponse>>
The response object with resulting data or .error if error.
Author
See
Properties
defaults?
Partial<GrabOptions>
Default options applied to all requests
log?
Request history and debugging info for all requests
mock?
Record<string, GrabMockHandler>
Mock server handlers for testing
instance?
(defaultOptions?: Partial<GrabOptions>) => GrabFunction
Create a separate instance of grab with separate default options
LogFunction()
Defined in: GRAB-URL.ts:736
Log function for debugging
LogFunction(message: string | object, options?: LogOptions): void;Defined in: GRAB-URL.ts:741
Log function for debugging
Parameters
message
string | object
Message to log (string or object)
options?
‐
Returns
void
printJSONStructureFunction()
Defined in: GRAB-URL.ts:745
Utility function to describe JSON structure
printJSONStructureFunction(obj: any): string;Defined in: GRAB-URL.ts:751
Utility function to describe JSON structure
Parameters
obj
any
The JSON object to describe
Returns
string
String representation of object structure
GrabResponse<TResponse>
type GrabResponse<TResponse> = TResponse & object;Defined in: GRAB-URL.ts:577
Core response object that gets populated with API response data
Type declaration
isLoading?
boolean
Indicates if request is currently in progress
error?
string
Error message if request failed
data?
TResponse | any
Binary or text response data (JSON is set to the root)
Type Parameters
TResponse
any
GrabOptions<TResponse, TParams>
type GrabOptions<TResponse, TParams> = TParams & object;Defined in: GRAB-URL.ts:588
Type declaration
headers?
Record<string, string>
include headers and authorization in the request
response?
TResponse | (params: TParams) => TResponse | any
Pre-initialized object which becomes response JSON, no need for .data
method?
"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD"
default="GET" The HTTP method to use
cache?
boolean
default=false Whether to cache the request and from frontend cache
cacheForTime?
number
default=60 Seconds to consider data stale and invalidate cache
timeout?
number
default=30 The timeout for the request in seconds
baseURL?
string
default='/api/' base url prefix, override with SERVER_API_URL env
cancelOngoingIfNew?
boolean
default=true Cancel previous requests to same path
cancelNewIfOngoing?
boolean
default=false Cancel if a request to path is in progress
rateLimit?
number
default=false If set, how many seconds to wait between requests
debug?
boolean
default=false Whether to log the request and response
infiniteScroll?
[string, string, string]
default=null [page key, response field to concatenate, element with results]
setDefaults?
boolean
default=false Pass this with options to set those options as defaults for all requests
retryAttempts?
number
default=0 Retry failed requests this many times
logger()?
(...args: any[]) => void
default=log Custom logger to override the built-in color JSON log()
onRequest()?
(...args: any[]) => any
Set with defaults to modify each request data. Takes and returns in order: path, response, params, fetchParams
onResponse()?
(...args: any[]) => any
Set with defaults to modify each request data. Takes and returns in order: path, response, params, fetchParams
onError()?
(...args: any[]) => any
Set with defaults to modify each request data. Takes and returns in order: error, path, params
onStream()?
(...args: any[]) => any
Set with defaults to process the response as a stream (i.e., for instant unzip)
repeat?
number
default=0 Repeat request this many times
repeatEvery?
number
default=null Repeat request every seconds
debounce?
number
default=0 Seconds to debounce request, wait to execute so that other requests may override
regrabOnStale?
boolean
default=false Refetch when cache is past cacheForTime
regrabOnFocus?
boolean
default=false Refetch on window refocus
regrabOnNetwork?
boolean
default=false Refetch on network change
post?
boolean
shortcut for method: "POST"
put?
boolean
shortcut for method: "PUT"
patch?
boolean
shortcut for method: "PATCH"
body?
any
default=null The body of the POST/PUT/PATCH request (can be passed into main)
Type Parameters
TResponse
any
TParams
any
grab()
function grab<TResponse, TParams>(path: string, options?: GrabOptions<TResponse, TParams>): Promise<GrabResponse<TResponse>>;Defined in: GRAB-URL.ts:88
GRAB: Generate Request to API from Browser
- GRAB is the FBEST Request Manager: Functionally Brilliant, Elegantly Simple Tool: One Function, no dependencies, minimalist syntax, more features than 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 30s, 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-url/iconsto get enhanced animated loading icons.
Type Parameters
TResponse
any
TParams
any
Parameters
path
string
The full URL path OR relative path on this server after grab.defaults.baseURL
options?
GrabOptions<TResponse, TParams>
Request params for GET or body for POST/PUT/PATCH and utility options
Returns
Promise<GrabResponse<TResponse>>
The response object with resulting data or .error if error.
Author
See
Example
import grab from 'grab-url';
let res = {};
await grab('search', {
response: res,
query: "search words"
})default
Renames and re-exports grab
log
Re-exports log
showAlert
Re-exports showAlert
printJSONStructure
Re-exports printJSONStructure