Nine Pedestrians Mesmerized

    github-base

    1.0.0 • Public • Published

    github-base NPM version NPM monthly downloads NPM total downloads Linux Build Status Windows Build Status

    Low-level methods for working with the GitHub API in node.js/JavaScript.

    Please consider following this project's author, Jon Schlinkert, and consider starring the project to show your ❤️ and support.

    Table of Contents

    Details

    (TOC generated by verb using markdown-toc)

    Install

    Install with npm:

    $ npm install --save github-base

    Heads up!

    As of v1.0, the API is 100% promise based, callbacks are no longer supported. Please see the API documentation and release history for more details.

    Why github-base, instead of...?

    Every other GitHub API library we found either had a huge dependency tree, tries to be everything to everyone, was too bloated with boilerplace code, was too opinionated, or was not maintained.

    We created github-base to provide low-level support for a handful of HTTP verbs for creating higher-level libraries:

    • .request: the base handler all of the GitHub HTTP verbs: GET, PUT, POST, DELETE, PATCH
    • .get: proxy for .request('GET', path, options, cb)
    • .delete: proxy for .request('DELETE', path, options, cb)
    • .patch: proxy for .request('PATCH', path, options, cb)
    • .post: proxy for .request('POST', path, options, cb)
    • .put: proxy for .request('PUT', path, options, cb)
    • .paged: recursively makes GET requests until all pages have been retrieved.

    Jump to the API section for more details.

    Usage

    Add github-base to your node.js/JavaScript project with the following line of code:

    const GitHub = require('github-base');

    Example usage

    Recursively GET all pages of gists for a user:

    const github = new GitHub({ /* options */ });
    const owner = 'jonschlinkert';
     
    github.paged(`/users/${owner}/gists`)
      .then(res => console.log(res))
      .catch(console.error);

    API

    (All request methods take a callback, or return a promise if a callback isn't passed as the last argument).

    GitHub

    Create an instance of GitHub with the given options.

    Params

    • options {Object}

    Example

    const GitHub = require('github-base');
    const github = new GitHub([options]);

    .request

    Uses needle to make a request to the GitHub API. Supports the following verbs: GET, PUT, POST, PATCH, and DELETE. Takes a callback or returns a promise.

    Params

    • method {String}: The http VERB to use
    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // list all orgs for the authenticated user
    const auth = require('./local-private-auth-info');
    const github = new GitHub(auth);
    github.request('GET', '/user/orgs')
      .then(res => console.log(res.body));

    .get

    Make a GET request to the GitHub API.

    Params

    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // get a list of orgs for the authenticated user
    github.get('/user/orgs')
      .then(res => console.log(res.body));
     
    // get gists for the authenticated user
    github.get('/gists')
      .then(res => console.log(res.body));

    .delete

    Make a DELETE request to the GitHub API.

    Params

    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // un-follow someone
    github.delete('/user/following/:some_username', { some_username: 'whatever' })
      .then(res => {
        console.log('RESPONSE:', res);
      });

    .patch

    Make a PATCH request to the GitHub API.

    Params

    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // update a gist
    const fs = require('fs');
    const options = { files: { 'readme.md': { content: fs.readFileSync('README.md', 'utf8') } } };
    github.patch('/gists/bd139161a425896f35f8', options)
      .then(res => {
        console.log('RESPONSE:', res);
      });

    .post

    Make a POST request to the GitHub API.

    Params

    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // create a new repository
    github.post('/user/repos', { name: 'new-repo-name' })
      .then(res => {
        console.log('RESPONSE:', res);
      });

    .put

    Make a PUT request to the GitHub API.

    Params

    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // follow someone
    github.put('/user/following/jonschlinkert')
      .then(res => {
        console.log('RESPONSE:', res);
      });

    .paged

    Recursively make GET requests until all pages of records are returned.

    Params

    • path {String}: The path to append to the base GitHub API URL.
    • options {Options}: Request options.

    Example

    // get all repos for the authenticated user
    github.paged('/user/repos?type=all&per_page=1000&sort=updated')
      .then(res => console.log(res.pages))
      .catch(console.error)

    .use

    Register plugins with use.

    const github = new GitHub();
     
    github.use(function() {
      // do stuff with the github-base instance
    });

    Authentication

    There are a few ways to authenticate, all of them require info to be passed on the options.

    const github = new GitHub({
      username: YOUR_USERNAME,
      password: YOUR_PASSWORD,
    });
     
    // or 
    const github = new GitHub({
      token: YOUR_TOKEN
    });
     
    // or 
    const github = new GitHub({
      bearer: YOUR_JSON_WEB_TOKEN
    });

    Paths and placeholders

    Deprecated: Since es2015 templates make this feature less useful, we plan to remove it in a future release.

    Paths are similar to router paths, where placeholders in the given string are replaced with values from the options. For instance, the path in the following example:

    const github = new GitHub();
    const options = { user: 'jonschlinkert', repo: 'github-base', subscribed: true };
     
    github.put('/repos/:user/:repo/subscription', options);

    Expands to:

    '/repos/jonschlinkert/github-base/subscription'

    Placeholder names are also arbitrary, you can make them whatever you want as long as all placeholder names can be resolved using values defined on the options.

    Options

    Options may be passed to the constructor when instantiating, and/or set on the instance directly, and/or passed to any of the methods.

    Examples

    // pass to constructor
    const github = new GitHub({ user: 'doowb' });
     
    // and/or directly set on instance options
    github.options.user = 'doowb';
     
    // and/or pass to a method
    github.get('/users/:user/gists', { user: 'doowb' })

    options.query

    Type: object

    Default: { per_page: 100 } for get and paged requests, undefined for all other requests.

    Pass an object to stringify and append to the URL using the .stringify method from qs.

    Examples

    github.paged('/users/:user/gists', { user: 'doowb', query: { per_page: 30 } })
      .then(res => {
        console.log(res.pages);
      });

    You can also manually append the query string:

    github.paged('/users/:user/gists?per_page=30', { user: 'doowb' })
      .then(res => {
        console.log(res.pages);
      });

    About

    Contributing

    Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

    Running Tests

    Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

    $ npm install && npm test
    Building docs

    (This project's readme.md is generated by verb, please don't edit the readme directly. Any changes to the readme must be made in the .verb.md readme template.)

    To generate the readme, run the following command:

    $ npm install -g verbose/verb#dev verb-generate-readme && verb

    Related projects

    You might also be interested in these projects:

    Contributors

    Commits Contributor
    40 jonschlinkert
    10 doowb
    7 olstenlarck

    Author

    Jon Schlinkert

    License

    Copyright © 2018, Jon Schlinkert. Released under the MIT License.


    This file was generated by verb-generate-readme, v0.6.0, on August 14, 2018.

    Install

    npm i github-base

    DownloadsWeekly Downloads

    5,534

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    29.2 kB

    Total Files

    6

    Last publish

    Collaborators

    • doowb
    • jonschlinkert