gh3

gh3 is a client-side Javascript API v3 wrapper for GitHub

gh3 is async.js compliant. (thank you to Atinux and mklabs)

Dependencies

• jQuery
• Underscore

Bundled with gh3 :

gh3 supports several kind of objects:

• Gh3.Users
• Gh3.User
• Gh3.Repositories
• Gh3.Repository
• Gh3.Issue
• Gh3.Pull
• Gh3.Branch
• Gh3.Dir inherits of Gh3.ItemContent
• Gh3.File inherits of Gh3.ItemContent
• Gh3.Commit
• Gh3.Gists
• Gh3.Gist
• Gh3.GistComment

You can extend all Gh3 types, eg :

var myComment = Gh3.GistComment.extend({
    //...
})

See § "Extend User" for more details.

GitHub Users : Gh3.Users

Static Methods of Gh3.Users

• Gh3.Users.search(keyword, pagesInfo, callback) retrieve Gh3.User instances by keyword
  • pagesInfo : { start_page : which_page } (always 100 items max. per page) see http://developer.github.com/v3/search/
• Gh3.Users.getAll() : return an array of all Gh3.User instances (you have to call search() before)
• Gh3.Users.getByName(name) : get a user by his name (you have to call search() before) (return first found user)
• Gh3.Users.each(callback) : execute callback for each found users (you have to call search() before)
• Gh3.Users.reverse() : reverse order of users (you have to call fetch() before)
• Gh3.Users.sort(comparator) : sort users (you have to call search() before)
• Gh3.Users.filter(comparator) : return an array of Gh3.User instances filtered by comparator (you have to call search() before)

example :

Gh3.Users.search("mad", {start_page : 3}, function (err, response) {
    if(err) {
        throw "outch ..."
    }
    //console.log(Gh3.Users.getAll());
    console.log(response.getAll());
    response.each(function (user) {
        console.log(user.name, user.login, user.repos, user)
    });
});

See samples/10-users.html

GitHub User : Gh3.User

Declare User

var k33g = new Gh3.User("k33g");

Methods of Gh3.User

• fetch(callback) : retrieve GitHub User's informations

Get User data

k33g.fetch(function (err, resUser){

    if(err) {
        throw "outch ..."
    }

    console.log("Blog : ", resUser.blog); // == k33g.blog
    console.log("Name : ", resUser.name);
    //etc. ...
});

See /samples/01-user.html

Extend User

I've cribbed the Backbone object model :

var GitHubUser = Gh3.User.extend({//instance members
    constructor : function(login) {
        GitHubUser.__super__.constructor.call(this, login);
        GitHubUser.allUsers.push(this);
    }
},{ //Static members
    allUsers : [],
    each : function (callback) {
        _.each(GitHubUser.allUsers, function (user) {
            callback(user);
        })
    }
});

var k33g = new GitHubUser("k33g")
,   loicdescotte = new GitHubUser("loicdescotte")
,   mklabs = new GitHubUser("mklabs")
,   chamerling = new GitHubUser("chamerling");

GitHubUser.each(function (user) {
    user.fetch(function (err, resUser) {

        if(err) {
            throw "outch ..."
        }

        console.log(JSON.stringify(resUser));
    });
})

See samples/02-user.html

GitHub Repositories of a user : Gh3.Repositories

Declare and Get Repositories of a user

var k33gRepositories = new Gh3.Repositories(k33g);
k33gRepositories.fetch(function () {
    console.log("Repositories", k33gRepositories);
}, function(){/*error*/},{page:1, per_page:500, direction : "desc"});
//all repositories, one page, 500 items per page, sort : descending

Methods of Gh3.Repositories

• fetch(pagesInfoAndParameters, paginationInfo, callback) retrieve Gh3.Repository instances of a user
  • pagesInfoAndParameters : { pages : number_of_pages, per_page : number_of_repositories_per page }
  • you can pass other parameters as : direction : "desc", see http://developer.github.com/v3/repos/
  • paginationInfo : which page. Possible values : see http://developer.github.com/v3/#pagination
    • "next"
    • "last"
    • "first"
    • "prev"
• getRepositories() : return an array of Gh3.Repository instances (you have to call fetch() before)
• getRepositoryByName(name) : get a repository by his name (you have to call fetch() before)
• eachRepository(callback) : execute callback for each repository of the user (you have to call fetch() before)
• reverseRepositories() : reverse order of repositories (you have to call fetch() before)
• sortRepositories(comparator) : sort repositories (you have to call fetch() before)
• filterRepositories(comparator) : return an array of Gh3.Repository instances filtered by comparator (you have to call fetchContents() before)

Static Methods

• Gh3.Repositories.search(keyword, pagesInfo, callback) retrieve Gh3.Repository instances by keyword
  • pagesInfo : { start_page : which_page } (always 100 items max. per page) see http://developer.github.com/v3/search/
• Gh3.Repositories.getAll() : return an array of all Gh3.Repository instances (you have to call search() before)
• Gh3.Repositories.getByName(name) : get a repository by his name (you have to call search() before) (return first found repository)
• Gh3.Repositories.each(callback) : execute callback for each found repositories (you have to call search() before)
• Gh3.Repositories.reverse() : reverse order of repositories (you have to call fetch() before)
• Gh3.Repositories.sort(comparator) : sort repositories (you have to call search() before)
• Gh3.Repositories.filter(comparator) : return an array of Gh3.Repository instances filtered by comparator (you have to call search() before)

See samples/03-repository.html See samples/09-repositories.html

GitHub Repository : Gh3.Repository

Declare and Get Repository informations

var k33g = new Gh3.User("k33g"); // You need a user first

var k33gBlog = new Gh3.Repository("k33g.github.com", k33g);

k33gBlog.fetch(function (err, res) {
    if(err) { throw "outch ..." }

    console.log(k33gBlog);
});

Methods of Gh3.Repository

• getBranches() : return array of Gh3.Branch instances
• fetch(callback) : retrieve repository's informations
• fetchBranches(callback) : retrieve repository's branches (you have to call fetch() before)
• getBranchByName(branch_name) : return a Gh3.Branch instance found by name (you have to call fetchBranches() before)
• eachBranch(callback) : execute callback for each branch of the repository (you have to call fetchBranches() before)
• reverseBranches() : reverse order of branches
• sortBranches(comparator) : sort branches
• fetchIssuesByLabel : receive repository issues with certain label or labels

Get Branches of Repository

After calling repository fetch() method :

k33gBlog.fetchBranches(function (err, res) {
    if(err) { throw "outch ..." }

    console.log(k33gBlog.getBranches());
})

branches is an array of Gh3.Branch instances populated when fetchBranches() is called.

You can do that too :

k33gBlog.fetchBranches(function (err, res) {
    if(err) { throw "outch ..." }

    console.log("Array of branches : ", k33gBlog.getBranches());
    k33gBlog.eachBranch(function (branch) {
        console.log(branch.name);
    })

    //and :
    console.log("Master Branch : ", k33gBlog.getBranchByName("master"));

})

See samples/03-repository.html

GitHub Branch : Gh3.Branch

Methods of Gh3.Branch

• fetchContents(callback) : retrieve Gh3.File instances and/or Gh3.Dir instances of the branch
• getContents() : return array of Gh3.ItemContent instances (so Gh3.File instances and/or Gh3.Dir instances)
• getFileByName(file_name) : return a Gh3.File instance found by name (you have to call fetchContents() before)
• getDirByName(dir_name) : return a Gh3.Dir instance found by name (you have to call fetchContents() before)
• eachContent(callback) : execute callback for each content item of the branch (you have to call fetchContents() before)
• reverseContents() : reverse order of contents
• sortContents(comparator) : sort contents
• filterContents(comparator) : return an array of Gh3.ItemContent instances filtered by comparator (you have to call fetchContents() before)

Get contents of a branch

You have to declare, get repository informations and fetch branches before calling fetchContents(callback) :

var k33g = new Gh3.User("k33g")
,   k33gBlog = new Gh3.Repository("k33g.github.com", k33g);

k33gBlog.fetch(function (err, res) {
    if(err) { throw "outch ..." }

    k33gBlog.fetchBranches(function (err, res) {
        if(err) { throw "outch ..." }

        var master = k33gBlog.getBranchByName("master");

        master.fetchContents(function (err, res) {
            if(err) { throw "outch ..." }

            master.eachContent(function (content) {
                console.log(content.path, content.type);
            });
        });

    })
});

See samples/04-branch.html

You obtain a list of files and directories. You can directly fetch raw content of a file or fetch contents of a directory.

GitHub File : Gh3.File

Methods of Gh3.File

• fetchContent(callback) : retrieve (raw) content of the file
• fetchCommits(callback) : retrieve commits of the file
• getRawContent() : return raw content of the file (you have to call fetchContent() before)
• getCommits() : return array of Gh3.Commit instances (you have to call fetchCommits() before)
• getLastCommit() : return last Gh3.Commit instance
• getFirstCommit() : return first Gh3.Commit instance
• eachCommit(callback) : execute callback for each commit of the file (you have to call fetchCommits() before)
• filterCommits(comparator) : return an array of Gh3.Commit instances filtered by comparator (you have to call fetchCommits() before)
• reverseCommits() : reverse order of commits
• sortCommits(comparator) : sort commits

Get raw content of a file

master.fetchContents(function (err, res) {
    if(err) { throw "outch ..." }

    var myfile = master.getFileByName("index.html");

    /* this way is possible to :
        var myfile = master.getContents()[8];
    */

    myfile.fetchContent(function (err, res) {
        if(err) { throw "outch ..." }

        console.log(myfile.getRawContent());
    });

});

See samples/05-file.html

Get commits of a file

myfile.fetchCommits(function (err, res) {
    if(err) { throw "outch ..." }

    console.log(myfile.getCommits());

    myfile.eachCommit(function (commit) {
        console.log(commit.author.login, commit.message, commit.date);
    });
});

See samples/05-file.html

GitHub Directory : Gh3.Dir

It works much like a Gh3.Branch.

Methods of Gh3.Dir

• fetchContents(callback) : retrieve Gh3.File instances and/or Gh3.Dir instances of the directory
• getContents() : return array of Gh3.ItemContent instances (so Gh3.File instances and/or Gh3.Dir instances)
• getFileByName(file_name) : return a Gh3.File instance found by name (you have to call fetchContents() before)
• getDirByName(dir_name) : return a Gh3.Dir instance found by name (you have to call fetchContents() before)
• eachContent(callback) : execute callback for each content item of the directory (you have to call fetchContents() before)
• reverseContents() : reverse order of contents
• sortContents(comparator) : sort contents
• filterContents(comparator) : return an array of Gh3.ItemContent instances filtered by comparator (you have to call fetchContents() before)

Get contents of a directory

master.fetchContents(function (err, res) {
    if(err) { throw "outch ..." }

    var dir = master.getDirByName('_posts');

    dir.fetchContents(function (err, res) {
        if(err) { throw "outch ..." }

        console.log(dir.getContents());

        dir.eachContent(function (content) {
            console.log(content.name, content.type, content.size);

        });
    });

});

See samples/06-dir.html

GitHub Gists : Gh3.Gists

Methods of Gh3.Gists

• fetch(pagesInfo, paginationInfo, callback) : retrieve Gh3.Gist instances of a user
  • pagesInfo : { pages : number_of_pages, per_page : number_of_gists_per page }
  • paginationInfo : which page. Possible values : see http://developer.github.com/v3/#pagination
    • "next"
    • "last"
    • "first"
    • "prev"
• getGists() : return an array of Gh3.Gist instances (you have to call fetch() before)
• eachGist : execute callback for each gist of the user (you have to call fetch() before)
• filter(comparator) : return an array of Gh3.Gist instances filtered by comparator (you have to call fetch() before)

Get public gists of a user

    var GistsOfK33g = new Gh3.Gists(new Gh3.User("k33g"));

    GistsOfK33g.fetch(null, null, function (err, res) {
        if(err) {
            throw "outch ..."
        }

        GistsOfK33g.eachGist(function (gist) {
            console.log(gist.description, gist.id);
        });
    });

Get public gists of a user : five gists of the next page

    GistsOfK33g.fetch({page:2, per_page:5}, "next", function (err, res) {
        if(err) {
            throw "outch ..."
        }

        GistsOfK33g.eachGist(function (gist) {
            console.log(gist.description, gist.id);
        });
    };

See samples/07-gists.html

Get public gists of a user only if they have comment(s)

AllGistsOfK33g.fetch(function (err, res) {
    if(err) {
        throw "outch ..."
    }

    console.log("Filtered gists : ", AllGistsOfK33g.filter(function (gist) {
        return gist.comments > 0;
    }));

},function(){//onerror},{page:1, per_page:500});

See samples/07-gists.html

GitHub Gist : Gh3.Gist

Methods of Gh3.Gist

• fetchContents(callback) : retrieve contents (files) of the gist
• fetchComments(callback) : retrieve comments of the gist
• getFileByName() : return a file of the gist, found by his name
• getFiles() : return array of files objects
• eachFile(callback) : execute callback for each file of the gist (you have to call fetchContents() before)
• getComments() : return an array of Gh3.GistComment instances
• eachComment(callback) : execute callback for each comment of the gist (you have to call fetchComments() before)
• filterComments(comparator) : return an array of Gh3.GistComment instances filtered by comparator (you have to call fetchComments() before)

Get a public gist by id

var oneGist = new Gh3.Gist({id:"2287018"});

oneGist.fetchContents(function (err, res) {
    if(err) {
        throw "outch ..."
    }

    console.log("oneGist : ", oneGist);
    console.log("Files : ", oneGist.files);

    oneGist.eachFile(function (file) {
        console.log(file.filename, file.language, file.type, file.size);
    });
});

Get content of a file of a gist

    console.log(oneGist.getFileByName("use.thing.js").content);

See samples/07-gists.html

Get comments of a public gist

    var anOtherGist = new Gh3.Gist({id:"1096826"});

    anOtherGist.fetchContents(function (err, res) {
        if(err) { throw "outch ..." }

        anOtherGist.fetchComments(function (err, res) {
            if(err) { throw "outch ..." }

            anOtherGist.eachComment(function (comment) {
                console.log(comment.body, "By ", comment.user.login);
            });
        });
    });

See samples/07-gists.html

Filter comments of a public gist

    var PaulIrishGist = new Gh3.Gist({id:"3098860"});

    PaulIrishGist.fetchContents(function (err, res) {
        if(err) { throw "outch ..." }

        PaulIrishGist.fetchComments(function (err, res) {
            if(err) { throw "outch ..." }

            console.log(
                PaulIrishGist.filterComments(function (comment) {
                    return comment.user.login == "codepo8";
                })
            );
        });

    });

See samples/08-gists_comments.html

... to be continued

History

• 2012.07.25 : '0.0.1' : first version
• 2012.07.26 : '0.0.2' : fixes
• 2012.07.26 : '0.0.3' : gists pagination
• 2012.07.28 : '0.0.4' :
  • refactoring : Gh3.Helper
  • gists filtering
  • gist comments filtering
  • file commits filtering
  • commits sorting
  • new Type : Gh3.Repositories (with pagination)
• 2012.07.29 : '0.0.5' :
  • Gh3.Repositories : add search ability
  • add Gh3.Users : search user ability
• 2012.07.29 : '0.0.6' :
  • async.js compliant
• 2014.04.20 : '1.0.0' : bower package + semantic versioning
• 2014.04.20 : '1.0.1' : temporary fixes

License

Gh3 is available under the terms of the MIT-License.

Copyright 2014-2015, Philippe Charrière