npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

request-registry

v0.12.2

Published

Type safe promise based HTTP request registry for the browser

Downloads

264

Readme

RequestRegistry

NPM version Size License Commitizen friendly

RequestRegistry is a minimal generic utility (~1.5kb gziped) to be used as part of your frontend data fetching layer to provide a typed, simplified and consistent API over various remote web services via caching.

Goals

  • Only ~1.5kb gziped (optimizable to 1kb with tree shaking)
  • Framework independent
  • Typesave

Getting started

import { createGetEndpoint } from "request-registry";

// Define a service endpoint to load user information
const userEndpoint = createGetEndpoint({
    url: keys => `http://example.com/user/${keys.id}`
});

// Load user information
const user = await userEndpoint({ id: "4" });
console.log(user.firstName);

Intellisense

intellisense demo

The optional build in typescript support will allow you to keep your data flow more maintainable as it allows you to understand which data has to be send and which data will be returned

import { createGetEndpoint } from "request-registry";

// The values needed to request the data
type Input = {
    id: string;
};
// The format the backend will provide
type Output = {
    firstName: string;
    lastName: string;
};
const userEndpoint = createGetEndpoint<Input, Output>({
    url: keys => `http://example.com/user/${keys.id}`
});
// The next lines will be fully typesafe without the need of adding any types
const data = await userEndpoint({ id: "4" });
console.log(data.firstName);

All CRUD operations are supported, for example a POST request would look like this:

import { createPostEndpoint } from "request-registry";

// The values needed to request the data
type Input = {
    id: string;
};
type Body = {
    firstName: string;
    lastName: string;
    address: string;
};
// The format the backend will provide
type Output = {
    userId: string;
};
const updateUserEndpoint = createPostEndpoint<Input, Body, Output>({
    url: keys => `http://example.com/user/${keys.id}`
});

updateUserEndpoint({ id: "4" }, {firstName: 'Alex', lastName 'Doe', address: 'Earth'})
    .then(data => console.log(data.userId));

A PUT request would look similair:

import { createPutEndpoint } from "request-registry";

// The values needed to request the data
type Input = {
    id: string;
};
type Body = {
    firstName: string;
    lastName: string;
    address: string;
};
// The format the backend will provide
type Output = {
    userId: string;
};
const putUserEndpoint = createPutEndpoint<Input, Body, Output>({
    url: keys => `http://example.com/user/${keys.id}`
});

putUserEndpoint({ id: "4" }, {firstName: 'Alex', lastName 'Doe', address: 'Earth'})
    .then(data => console.log(data.userId));

And a DELETE request would not need a body type, just like the GET request:

import { createDeleteRequest } from "request-registry";

// The values needed to request the data
type Input = {
    id: string;
};
// The format the backend will provide
type Output = {
    userId: string;
};
const userEndpoint = createPutEndpoint<Input, Output>({
    url: keys => `http://example.com/user/${keys.id}`
});

userEndpoint({ id: "4" }).then(data => console.log(data.userId));

GraphQL

Request registry is capable of sending and caching GraphQL requests:

import { createGraphQlEndpoint } from "request-registry";

const query = `{
  Movie(title: "Inception") {
    releaseDate
    actors {
      name
    }
  }
}`;
const actorsEndpoint = createGraphQlEndpoint<{}, {}>({
    url: keys => `http://example.com/user/${keys.id}`,
    query: query
});

actorsEndpoint().then(graphQLResponse => console.log(graphQLResponse));

Caching

The build in caching allows executing the same endpoint multiple times without sending duplicated requests.

Only GET and GraphQL operations will be cached by default.

const userLoader = createGetEndpoint(...)
const promise1A = userLoader.load(1)
const promise1B = userLoader.load(1)
assert(promise1A === promise1B)

Clearing Cache

Clearing the cache will also trigger a clear cache event which can be used to rerender outdated components

const userLoader = createGetEndpoint(...)
userLoader.refresh()

Disabling Cache

Caching can be disabled for cases where you always need a fresh result

const userLoader = createGetEndpoint({
    url: keys => `http://example.com/user/${keys.id}`,
    cacheRequest: false
});

Custom Caches

RequestRegistry can optionaly be provided a custom Map instance to use as its memoization cache. More specifically, any object that implements the methods get(), set(), delete() and clear() can be provided. This allows for custom Maps which implement various cache algorithms to be provided. By default, the standard Map is used which simply grows until the Endpoint is released.

const customCache = new Map();
const userLoader = createGetEndpoint({
    url: keys => `http://example.com/user/${keys.id}`,
    cache: customCache
});

Connecting Caches

Most of the time mutiation endpoints (POST / PUT / DELTE) influence the validity of data endpoints (GET). For example setting a users name should invalidate all caches including the old name.
RequestRegistry allows to define those relations for every endpoint using the afterSuccess hook:

const getUserName = createGetEndpoint({
    url: keys => `http://example.com/user/${keys.id}/get`,
})
const setUserName = createPostEndpoint({
    url: keys => `http://example.com/user/${keys.id}/update`,
    afterSuccess: () => getUserName.refresh();
})

Custom Headers

The headers option allows to customize request headers.

const userLoader = createGetEndpoint({
    url: keys => `http://example.com/user/${keys.id}`,
    headers: {
        Authorization: keys => `Bearer ${keys.token}`,
        contentType: "application/json"
    }
});
userLoader({ id: 9, token: "YXRvYmF0b2JhdG9i" });

Custom Loaders

If you wish, you can also override the default request-registry loader. By default it executes a request, using a fetch polyfill, and returns the request promise. You might want to do this if you don't want to actually execute a request, but are unable to mock the backend for some reason (eg. you are using Storybook).

type Input = {
    id: string;
};
type Output = {
    name: string;
};

const userEndpoint = createGetEndpoint<Input, Output>({
    url: keys => `http://example.com/user/${keys.id}`
});
userEndpoint.loader = () => Promise.resolve({ name: "I am a custom loader!" });
userEndpoint({ id: "4" }).then(data => console.log(data.name));

Success handling

The afterSuccess options allows to add a generic success handling for an endpoint.

type Input = {
    id: string;
};
type Output = {
    name: string;
};

const userEndpoint = createGetEndpoint<Input, Output>({
    url: keys => `http://example.com/user/${keys.id}`
    afterSuccess: (result) => {
        console.log("Load data", result);
    }
});

Error handling

The afterError options allows to add a generic error reporting for an endpoint.

type Input = {
    id: string;
};
type Output = {
    name: string;
};

const userEndpoint = createGetEndpoint<Input, Output>({
    url: keys => `http://example.com/user/${keys.id}`
    afterError: (error) => {
        console.error("Request failed", error);
    }
});

Endpoint observing

Invalidating the cache using refresh will internaly trigger a refresh event.
To subscribe to the initial data load and updates after a clear cache it is possible to observe an endpoint:

const userEndpoint = createGetEndpoint({
    url: keys => `http://example.com/user/${keys.id}`
});
const stopObserving = userEndpoint.observe(latestValue => {
    // Output the user data intially and on every cache clear:
    console.log(latestValue);
});

To unsubscribe just execute the function returned by the observe function:

stopObserving();

Framework integration

Although request-registry can be used standalone there are some unit tested packages to help with framework integrations:

License

MIT license