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) : retur