chainify-url
TypeScript icon, indicating that this package has built-in type declarations

1.0.0 • Public • Published

Chainify URL

CircleCI Coverage Status

Object oriented URL builder.

Installation

npm install chainify-url

Usage

See sample project and examples below.

Why?

Have you ever concatenated strings to build a URL? With this library you can do the same (and not only) but in an object oriented way — by chaining properties. Huh? 😳 Watch this:

import chainify from 'chainify-url';

// Pass a string or a URL as baseURL
const chain = chainify('https://example.com/', {
  // Define "chain enders" - the rightmost properties that end the chain
  url(url) {
    // It is not necessarily to return the URL or any other value from enders,
    // but we are going to read this property
    return url;
  },

  // We want this property to be a function
  build(url) {
    return () => url;
  }
});

// Build a chain

chain.foo.bar.baz.url.href; // => 'https://example.com/foo/bar/baz'

chain.foo('bar baz').build().href; // => 'https://example.com/foo/bar%20baz'

That's it! 🙂 Yes, it's that simple. Now let's look at another, more realistic example, a Discord client:

import axios from 'axios'; // Or any other HTTP client
import chainify from 'chainify-url';

const api = chainify('https://discord.com/api/v9/', {
  get: (url) => (config = {}) => {
    // What if there are search parameters? 🤔 Pass them in config!
    if (config.search) {
      url.search = new URLSearchParams(config.search).toString();
    }

    return axios.get(url.href, { headers: config.headers })
  },

  // Let's add a method for POSTing requests
  post: (url) => (config = {}) => {
    if (config.search) {
      url.search = new URLSearchParams(config.search).toString();
    }

    return axios.post(url.href, config.data, { headers: config.headers })
  },
});

// GET https://discord.com/api/v9/users/%40me
api.users('@me').get({
  headers: {
    Authorization: 'Bearer <ACCESS_TOKEN>',
  }
})
  .then((res) => {
    console.log(res.data);
  })
  .catch((error) => {
    console.log(error.message);
  });

// Exactly the same URL as above, but built by accessing the property
api.users['@me'].get({
  headers: {
    Authorization: 'Bearer <ACCESS_TOKEN>',
  }
});

// GET https://discord.com/api/v9/users/%40me/guilds/12345/member
api.users('@me').guilds(12345).member.get({
  headers: {
    Authorization: 'Bearer <ACCESS_TOKEN>',
  }
});

// POST https://discord.com/api/v9/guilds/12345/channels
api.guilds(12345).channels.post({
  data: {
    name: 'My Channel',
    type: 0,
    // ...
  },
  headers: {
    Authorization: 'Bearer <ACCESS_TOKEN>',
  }
});

We just turned our URL builder into an HTTP client that covers every endpoint, even with the deepest nesting, WOAH! 😀 API calls are intuitive and look very similar to the endpoints they use, no additional classes or functions required, simplicity and readability, everything is right here!

Readme

Keywords

Package Sidebar

Install

npm i chainify-url

Weekly Downloads

13

Version

1.0.0

License

ISC

Unpacked Size

199 kB

Total Files

15

Last publish

Collaborators

  • digaev