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

vue-restful

v1.0.0

Published

Vue composables for streamlined RESTful API endpoint interactions.

Downloads

6

Readme

This is a TypeScript library to make RESTful API interactions reactive. It wraps an Axios instance for easy compatibility with any existing interceptors and headers you have. It also leverages Axios's request cancellation feature to avoid common race conditions and guarantee consistent states.

Here is an example of loading a "foo" object along with all its associated "bar"s based on a fooId prop to the component. In practice fooId might come from other locations such as a route or query parameter.

setup(props) {
  const { fooId } = toRefs(props);
  const { data: foo } = useDetailApi<Foo>('/foo/', fooId);
  const { data: bars } = useListApi<Bar>('/bar/', {
	  params: { foo: fooId },
  });

  return {
    foo,
    bars,
  }
},

If fooId is initially 123, this will load data from /foo/123/ and /bars/?foo=123. The resulting types are foo: Maybe<Foo> and bars: Bar[]. Any time fooId changes, any previous results from both endpoints are cleared, in-flight requests are canceled, and the new requests are sent out.

Common API

There are four variations of useApi right now, but they all share a few common inputs (options) and provide many common outputs (refs and functions).

Options

  • axiosInstance - The Axios instance to use. Defaults to the global instance.
  • auto - Controls whether the data is automatically fetched (immediately and reactively) or not. Defaults to true. Can be passed as a ref.
  • params - The query parameters to pass with the GET request. Supports either a ref containing an optional object, an object containing refs, or a plain object. Passing a ref containing an object or an object containing refs makes the system reactive to changes of those ref's values. If the object ref's value is null, requests are suppressed.
  • extractResponseData - Tells the library how to get the data item(s) from the response. The function gets passed response.data and defaults to x => x.
  • trailingSlash - Exists for all variants except useEndpointApi; controls how an ID is concatenated with the base URL for detail endpoints.
  • allowGlobal - Developers unfamiliar with the Composition API have a tendency to misuse the composables, so by default they throw an error if called from outside an active EffectScope (typically a component's setup() function). Set this to true to suppress the error if you're sure it's what you intend to do.

Refs

  • data - The currently loaded data; either a Maybe<T>> or T[] depending on the form.
  • mostRecentData loaded data; not cleared out when changing params, auto, or url.
  • loading - Whether any requests are in-flight.
  • loaded - Whether a GET has returned successfully since the last clear.
  • error - The last Error encountered by any requests made, or null.

Functions

  • list or detail - GET the data from the endpoint.
  • post - POST a new item to the endpoint.
  • put - PUT an item to the endpoint.
  • patch - PATCH an existing item to the endpoint.
  • remove - DELETE an existing item from the endpoint.
  • clear - Resets all internal state and cancels any in-flight requests. This method is called automatically for reactive updates.

useDetailApi and useEndpointApi

These variations are for use with an API that returns a single value. The data ref will be a Maybe<T> for both of them. The only difference between them is that useDetailApi requires an ID as an argument and automatically constructs the final URL using it. Technically useDetailApi is a special case of useEndpointApi, but it is expected to be far more commonly used.

Whenever the URL (or ID, for detail) refs are null, data loading is suppressed. This can be used to delay requests until all the necessary prerequisite data is available.

useListApi

This variation is for use with an API endpoint that returns a list. The data ref will be a T[]. Results are stored in an object map keyed by their ID (accessible via the byId ref) but their order is maintained by an array of IDs. These two data structures are then mapped together to produce the output data ref. This approach guarantees a consistent internal state for any given item ID.

It is expected that the detail endpoint for each item returned can be constructed by appending the ID of the item to the base URL in accordance with the trailingSlash property. For example, if you pass /foo/ as the URL, and it returns a Foo with ID 123, /foo/123/ should be the endpoint for PUT/PATCH/DELETE requests.

List Options

  • getId - How to extract the ID for an item. The function is passed an item of type T and must return a string or number.
  • extractResponseCount - A function to get the response's total count of results from response.data. Should return a number and defaults to () => 0.

List Refs

  • byId - Maps item IDs to their values.
  • count - The total count of items this endpoint can return (e.g. ignoring any limit clauses). Always zero unless extractResponseCount is set.

useInfiniteScrollApi

This variation builds on top of useListApi to provide a convenient mechanism for use with infinite scroll UIs. The limit option controls how many items are loaded at a time, and an internal offset state is tracked. Each call to list will increment offset by the value of limit and append the results. This means that unlike every other variant, it is expected that list will need to be manually called when more results are needed (generally auto reactivity is sufficient for other variants).

Infinite Scroll Options

  • limit - The amount of items to load at a time. Can be a number or a number ref. Defaults to 100.

Infinite Scroll Refs

  • offset - The offset that will be used for the next list call.

Provide/Inject

If you are using things bound from the use*Api call at multiple levels of the component tree, it is recommended to use Vue's provide/inject framework to provide the entire result of the call to your component tree using an InjectionKey symbol for type checking.

Sharing Configuration

Since it is likely that multiple endpoints will be used from a server with a shared Axios instance and response shapes, it is recommended to create wrapper functions for each variant that inject those options by default.