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

teleman

v0.7.4

Published

A browser and node.js fetch API wrapper.

Downloads

9

Readme

Teleman

A tiny (~2kb after gzipped) fetch API wrapper.

Features

  • Tiny, only about 2kb after gzipped.
  • Support middleware.
  • Return decoded response body.
  • Handle response.ok for you.

Installation

npm i teleman

NOTE: The code is written in ES2020 syntax and not transpiled. To use it in old browsers, you should transpile the code using tools such as Babel.

Usage

import Teleman from 'teleman'

async function main() {
  const api = new Teleman({
    base: 'http://api.example.com'
  });

  const article = await api.get('/articles', { id: 123 });

  // post JSON
  await api.post('/articles', { title: 'Hello', content: '# Hello' });

  // post with Content-Type: multipart/form-data
  await api.post('/upload', new FormData(document.forms[0]));
}

Singleton

You can also use Teleman directly without creating an instance.

import { teleman } from 'teleman';

teleman.get(url, query, options);
teleman.post(url, body, options);
teleman.put(url, body, options);
teleman.patch(url, body, options);
teleman.delete(url, query, options);
teleman.head(url, query, options);
teleman.purge(url, query, options);
teleman.use(middleware);

Constructor

new Teleman({ base, headers })

Creates a Teleman instance.

base

String. Optional. Base URL. In browser, it's default value is document.baseURI.

headers

Object. Optional. Default headers. It can be a simple key-value object or Headers object.

Methods

instance.fetch()

instance.fetch(url, {
  method = 'GET',
  base = this.base,
  headers,
  query,
  params = {},
  body,
  use = this.middleware,
  ...rest 
} = {})

Parameters

url

String. The URL of the request. If it's a relative URL, it's relative to base parameter.

base

String. Base URL. The request URL will be new URL(url, base).

method

String. HTTP methods. GET, POST, PUT, PATCH, DELETE, HEAD, PURGE. Defaults to 'GET'.

headers

Object | Headers. HTTP headers. It will be merged with instance's default headers.

query

String | Object | Array | URLSearchParams. The query string appends to the URL. It takes the same format as URLSearchParams constructor's param.

params

Object. URL path params.

instance.fetch('/articles/:id', { params: { id: 1 } })

It will use encodeURIComponent() to encode the values.

body

Object | FormData | Blob | BufferSource | URLSearchParams | String. The request body. If the body is a plain object, it will be converted to other type according to content-type of headers:

  • not set: to JSON string, and set content-type to application/json.
  • application/json: to JSON string.
  • multipart/form-data: to FormData.
  • application/x-www-form-urlencoded: to URLSearchParams.
use

Array<Middleware>. Middleware functions to use. Defaults to instance.middleware array.

...rest

Other parameters will be set into the context object.

Return Value

instance.fetch() returns a promise.

According to content-type header of the response, it will resolve/reject (depends on response.ok) to different types:

  • application/json: response.json()
  • text/*: response.text()
  • Others: the response object as is.

If any error occurs, the promise will be rejected with that error.

Shortcut methods

instance.get(url, query, options)
instance.post(url, body, options)
instance.put(url, body, options)
instance.patch(url, body, options)
instance.delete(url, query, options)
instance.head(url, query, options)
instance.purge(url, query, options)

instance.use(middleware)

Add the given middleware to instance.middleware array. It returns this so is chainable.

Parameters

middleware

Function. The middleware function to use.

instance
  .use(async(ctx, next) => {
    try {
      return await next();
    } catch (e) {
      alert(e?.message || 'fetch failed');
      throw e;
    }
  });
  .use(async(ctx, next) => {
    const start = Date.now();
    const data = await next();
    const ms = Date.now() - start;
    console.log(`${ctx.options.method} ${ctx.url.href} - ${ms}ms`);
    
    // you can modify the data then return it
    return {
      ...data,
      foo: data.foo || 0
    };
  })

ctx

{
  url, // URL object
  options: { method, headers, body },
  response, // available after `await next()`
  ...rest // additional parameters passed from `instance.fetch()` options
}

url and options will be used to call the fetch() function:

fetch(ctx.url.href, ctx.options)

You can modify the context properties to interfere the request and response.

next

A middleware function should receive the response body from next(), and can optionally modify the data. Finally it should return the data.

License

MIT