webproxy-client

webproxy-client is the client library for the WebProxy distributed cache engine.

It gives you two ways to cache responses:

• Standalone local caching through IndexedDB with webProxy.fetch(...)
• Shared organization caching through webProxy.sync(...) plus webproxy.fetch(...) when a WebProxy server is available

Installation

npm install webproxy-client

Quick Start

Use webProxy.fetch(...) (also aliased as fetchCached(...)) directly if you only want local browser caching:

import { webProxy } from 'webproxy-client';

const response = await webProxy.fetch('https://api.example.com/data');
const data = await response.json();

If you want to participate in the shared organization cache, start the client first with webProxy.sync(...) (also aliased as start(...)) and then call webProxy.fetch(...) as usual:

import { webProxy } from 'webproxy-client';

await webProxy.sync('https://your-webproxy-server.example.com', 'your-authorization-token');

const response = await webProxy.fetch('https://api.example.com/data');
const data = await response.json();

How It Works

fetchCached(...)

fetchCached(...) works on its own. When you call it without start(...), it still caches successful responses locally in the browser using IndexedDB.

That means it can be used as a standalone cache layer even if no WebProxy server is running.

start(...)

Calling start(baseServerUrl, authorizationToken) connects the client to a running WebProxy server and enables access to the shared organization cache.

When the shared cache is enabled, fetchCached(...) will:

1. Check the local IndexedDB cache first
2. Try to read from the shared cache over WebSocket
3. Fall back to the network request if nothing is cached

For the shared cache to work, a WebProxy server must be running. See the server project here: https://github.com/R0DR160HM/webproxy_server. You should fork it and follow its documentation on how to run it.

Parameters

fetchCached(input, options) (webProxy.fetch(input, options))

• input: Any RequestInfo or URL accepted by fetch
• options.resourceName: Cache key used to identify the response. Defaults to the request URL
• options.resourceScopes: Scope labels used to match shared cache entries. Defaults to ['*']
• options.keepResourceFor: How long the cached value should stay valid in milliseconds. Defaults to 60 days
• options.waitForResource: How long to wait for a shared-cache response before falling back to fetch

start(baseServerUrl, authorizationToken) (webProxy.sync(baseServerUrl, authorizationToken))

• baseServerUrl: The WebProxy server base URL. Must use HTTPS or localhost
• authorizationToken: Token used to subscribe to the shared cache stream. This token should be generated by your service according to the WebProxy Server's description

Notes

• This library is intended for browser environments because it uses window, WebSocket, and IndexedDB.
• Cached JSON responses are returned as Response objects with Content-Type: application/json.
• If the shared cache is unavailable, fetchCached(...) still functions using local cache and network fallback.

License

MIT