grab-url

v3.0.0

Published

4 days ago

Generate Request to API from Browser — The FBEST Request Manager: Functionally Brilliant, Elegantly Simple Tool. One function, zero dependencies, minimalist syntax, with auto-JSON, dedupe, caching, retries, rate-limiting, mock testing, pagination, and loa

npm i grab-url          # ~5 kB gzipped, zero dependencies, no install scripts

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

Requests & Data

Send anything, get back parsed data — no boilerplate per content type.

Auto-JSON Convert: Pass parameters and get response or error in JSON, handling other data types as is.
Auto-Unzip: Automatically extracts ZIP responses into { data: { filename: content } } using archiver-web. Set unzip: false to disable. Import from grab-url/full — see Slim by default.
DOM Parsing: Automatically parses HTML responses. Pass parseDOM: "selector" for CSS selector extraction or parseDOM: false to disable. Uses linkedom. Import from grab-url/full — see Slim by default.
Request Stategies: 🎯 Examples show common stategies like debounce, repeat, proxy, unit tests, interceptors, file upload, etc

Reliability & Traffic Control

Keep flaky networks and click-happy users from cascading into your API.

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
Regrab On Error: Regrab on timeout error, or on window refocus, or on network change, or on stale data.
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.

Performance & UI State

Fewer round trips, and loading state your components can bind to directly.

isLoading Status: Sets .isLoading=true on the pre-initialized response object so you can show a "Loading..." in any framework
Frontend Cache: Set cache headers and retrieve from frontend memory for repeat requests to static data.
Pagination Infinite Scroll: Built-in pagination for infinite scroll to auto-load and merge next result page, with scroll position recovery.
Loading Icons: Import from grab-url/icons to get enhanced animated loading icons, including the quantum sphere — an interactive 3D orbital loader for React and Svelte that re-rolls its own colors and collapses each ring you hover: import QuantumOrbital from 'grab-url/icons/quantum-sphere'.

Testing & Debugging

See every request, fake the ones you don't have yet, and assert on the rest.

Mock Server Support: Configure window.grab.mock for development and testing environments
DevTools: Ctrl+Alt+I overlays webpage with devtools showing all requests and responses, timing, and JSON structure.
Debug Logging: Adds global log() and prints colored JSON structure, response, timing for requests in test.
Request History: Stores all request and response data in global grab.log object

Setup & Integration

Drop it into any stack, any runtime, or generate a whole client from a spec.

Agent Skill Install the skill into any agent (Claude, Cursor, Gemini, Codex, Antigravity, etc.) with one command: npx skills add vtempest/GRAB-URL@use-grab-request. Or copy SKILL.md into ~/.claude/skills/use-grab-request/SKILL.md.
Globals: Adds to window in browser or global in Node.js so you only import once: grab(), log(), grab.log, grab.mock, grab.defaults
Base URL Based on Environment: Configure grab.defaults.baseURL once at the top, overide with SERVER_API_URL in .env.
Framework Agnostic: Alternatives like TanStack work only in component initialization and depend on React & others.
OpenAPI SDKs: Generate a typed client from any OpenAPI spec with Hey API and have it send requests with grab instead of axios: npx api2client ./openapi.yaml ./src/client. Every endpoint gets caching, retries, rate limiting, dedupe and mocks.

Slim by default

import grab from "grab-url" gives you the slim build: about 5 kB gzipped, zero dependencies, nothing lazily reachable that you did not ask for. That is every feature above except the two that need a heavy library — ZIP extraction and HTML/DOM parsing.

Those two live one subpath away:

import grab from "grab-url";        // default — ~5 kB gzipped
import grab from "grab-url/full";   // + `unzip` and `parseDOM`

grab-url/full adds linkedom (~174 kB) and the archive extractor, both behind lazy imports, so they download only when a response actually needs one of them. grab-url/slim still resolves, as an alias of the default — it is the identical module, so a stub on grab.mock registered through either specifier is visible to the other.

The CLI is its own package, grab-url-cli. Installing the library runs no install script and pulls nothing down.

Examples

CLI File Downloader — npm i -g grab-url-cli, or npx grab-url-cli

npx grab-url-cli https://releases.ubuntu.com/24.04.2/ubuntu-24.04.2-live-server-amd64.iso

# 700+ media sites are detected by domain and pulled with yt-dlp, which
# installing grab-url-cli fetches for you
npx grab-url-cli "https://www.youtube.com/watch?v=VIDEO_ID"
npx grab-url-cli https://soundcloud.com/artist/track -a mp3

# SFTP, torrents and magnet links (needs aria2c installed)
npx grab-url-cli sftp://user@host/srv/backup.tar.gz --password hunter2
npx grab-url-cli "magnet:?xt=urn:btih:HASH" -d ./downloads

# Archive a page into ./<Page Title>/ - article, cite, transcript and any video
# (needs `npm i -g extract-webpage`; the video step needs yt-dlp)
npx grab-url-cli https://example.com/article --page

# Detach and keep going in the background; Ctrl+C on any transfer offers the same
npx grab-url-cli https://example.com/big.iso --background
npx grab-url-cli --jobs

import grab from 'grab-url';

let res = $state({}) as {
  results: Array<{title:string}>,
  isLoading: boolean,
  error: string,
};

await grab('search', {
  response: res,
  query: "search words",
  post: true
})

grab('user').then(log)

// Auto-extract ZIP files
const zipData = await grab('https://example.com/archive.zip', { 
  unzip: true 
})
// { data: { "file1.txt": "content...", "file2.js": "..." } }

// Parse HTML and extract elements
const title = await grab('https://example.com', { 
  parseDOM: 'h1' 
})
// { data: "Page Title" }

//in svelte component
{#if res.results}
    {res.results}
{:else if res.isLoading}
    ...
{:else if res.error}
    {res.error}
{/if}

 //Setup Mock testing server, response is object or function
 window.grab.mock["search"] = {
   response: (params) => {
     return { results: [{title:`Result about ${params.query}`}] };
   },
   method: "POST"
 };

 //set defaults for all requests
 grab("", {
   setDefaults: true,
   baseURL: "http://localhost:8080",
   timeout: 30,
   debug: true,
   rateLimit: 1,
   cache: true,
   cancelOngoingIfNew: true,
 });

 grab.defaults.baseURL = "http://localhost:8080/api/";

Screenshots

Animated SVG Loading Icons with Customizable Colors

icons

Quantum Sphere Loader — live demo

https://github.com/user-attachments/assets/903f2483-6fac-4592-be09-5fdc17196a84

Set Types for Tooltips on Request & Response

types

Debug Colorized log(JSON)

Debug log

Autocomplete option names

Autocomplete

Comparison of HTTP Request Libraries

Stop trying to make fetch happen! *

Why fetch things when you can just GRAB?

Debugging requests is a bitch. Make the switch!

🌟 Star this repo so it will grow and get updates!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme