Registry / database / gun-fetch

gun-fetch

JSON →
library3.7.7jsnpmunverified

A fetch-like API for GunDB that provides HTTP-method-based access to Gun decentralized database operations. Version 3.7.7, actively maintained with irregular release cadence. Supports GET, PUT, HEAD methods and special query characters (_ for user/relay queries, - for hex-encoded keys). Enables register/login, pagination, peer management, and relay connections through custom headers. Differentiates from raw Gun by providing a familiar fetch interface for CRUD operations.

database
npm install gun-fetch
package ↗
INSTALL
IMPORT
SIG · GUN-FETCH
G
gun-fetch
databasejavascriptv3.7.7
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

gunFetch
✓ const gunFetch = require('gun-fetch')
✗ import gunFetch from 'gun-fetch'
gun-fetch uses CommonJS by default; no ESM exports as of v3.7.7
fetch
✓ const fetch = gunFetch(options)
✗ import { fetch } from 'gun-fetch'
gunFetch(options) returns a fetch function; not a named export
options
✓ const options = {file: path.resolve('./storage'), relay: true}
Options object with `file` (path for data storage) and `relay` (boolean to connect to relays). Can also pass Gun instance or relay URLs.

Demonstrates basic CRUD operations using gun-fetch: PUT to store data, GET to retrieve, HEAD to check existence. Uses local file storage without relay.

const path = require('path'); const gunFetch = require('gun-fetch'); // Configure storage and relay behavior const options = { file: path.resolve('./storage'), relay: false // Set true to connect to default relays }; const fetch = gunFetch(options); async function main() { // Write data await fetch('gun://hello/test/testing', { method: 'PUT', body: JSON.stringify({ message: 'Hello GunDB!' }) }); // Read data const response = await fetch('gun://hello/test/testing', { method: 'GET' }); const text = await response.text(); console.log('Fetched data:', text); // Check existence via HEAD const headResponse = await fetch('gun://hello/test/testing', { method: 'HEAD' }); console.log('Status:', headResponse.status); // 200 if exists } main().catch(console.error);
Debug
Known issues
breakingIn v3, the `gunFetch()` function returns a fetch function instead of a client object.
fix
Use the returned fetch function directly: const fetch = gunFetch(options);
affects: >=3.0.0
deprecatedPassing a Gun instance directly to gunFetch() is deprecated; use the `gun` option instead.
fix
Pass Gun instance via options: gunFetch({ gun: myGunInstance })
affects: >=3.5.0
gotchaThe `relay` option defaults to false; if not set, gun-fetch will not connect to any relays, causing network operations to fail.
fix
Set relay: true or provide a Gun instance with relay connection.
affects: >=3.0.0
gotchaPUT requests require body to be a JSON string; using a plain object will not be stored correctly.
fix
Always stringify body: body: JSON.stringify(yourData)
affects: all
gotchaThe `_` prefix in hostname triggers user/relay queries; using `_` in data keys will cause unintended behavior.
fix
Avoid starting data keys with underscore or hex-encode keys starting with `_` using `-` prefix.
affects: all
Errors
Common errors & fixes
TypeError: gunFetch is not a function
Using ESM import instead of CommonJS require, or incorrect module path.
fix
Use require('gun-fetch') or check that the package is installed correctly.
Error: No Gun instance provided
Calling gunFetch() without options or with invalid options object.
fix
Pass an options object with at least `file` and `relay` or a `gun` instance.
Error: Cannot find module 'gun'
GunDB peer dependency not installed.
fix
Run npm install gun to install GunDB as a dependency.
Upgrade
Version history
3.7.7latest on npm
Audit
Dependencies
gunrequiredPeer dependency; gun-fetch wraps GunDB operations
Agent activity
8 hits · last 30 days
node
8
Resources
packagegun-fetch ↗
gun-fetch — npm install gun-fetch · libregistry