Skip to content
This repository was archived by the owner on Oct 20, 2023. It is now read-only.

Commit 10523ca

Browse files
clayreimannclayreimann
committed
feature: refactor API to be more uniform
* Update npm for publishing * Update changelog to reflect the breaking changes * Update travis.yml to properly run tests * Update jsdoc config
1 parent efffc70 commit 10523ca

30 files changed

+623
-486
lines changed

‎.babelrc

Lines changed: 0 additions & 10 deletions
This file was deleted.

‎.editorconfig

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ charset = utf-8
88
trim_trailing_whitespace = true
99
insert_final_newline = true
1010

11-
[*.yml,package.json]
11+
[{*.yml,package.json}]
1212
indent_size = 2
1313

1414
[*.md]

‎.gitignore

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,7 @@ docs/
22
dist/
33
coverage/
44
node_modules/
5-
.nyc_output/
65

76
.DS_Store
8-
.idea
9-
.zuulrc
107
npm-debug.log
118
sauce.json

‎.jsdoc.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"dictionaries": ["jsdoc"]
44
},
55
"source": {
6-
"include": ["src", "package.json", "README.md"],
6+
"include": ["lib/", "package.json", "README.md"],
77
"includePattern": ".js$",
88
"excludePattern": "(node_modules/|docs)"
99
},

‎.npmignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
docs/
2+
coverage/
3+
node_modules/
4+
5+
.DS_Store
6+
sauce.json

‎.travis.yml

Lines changed: 21 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,27 @@
11
language: node_js
2-
3-
sudo: false
4-
52
node_js:
6-
- "5.7"
7-
- "4.3"
8-
- "0.12"
9-
- "0.10"
10-
3+
- '5'
4+
- '4'
5+
- '0.12'
6+
- '0.10'
117
cache:
128
directories:
139
- node_modules
14-
15-
before_install:
16-
- npm install -g npm@latest
17-
10+
before_install: npm install -g npm@latest
11+
before_script:
12+
- npm run lint
13+
# - npm run build # will need this when we do sauce testing of compiled files
1814
script:
19-
- gulp lint
20-
- gulp test:mocha
21-
# - npm run codecov # disabled temporarialy while I work out how to generate accurate coverage of ES2015 code
15+
- npm test
16+
# - npm run test-dist # test the compiled files
17+
# after_success:
18+
# - npm run codecov # disabled temporarialy while I work out how to generate accurate coverage of ES2015 code
19+
before_deploy:
20+
- npm run build
21+
deploy:
22+
provider: npm
23+
skip_cleanup: true
24+
on:
25+
tags: true
26+
api_key:
27+
secure: TZHqJ9Kh2Qf0GAVDjEOQ01Ez6rGMYHKwVLOKTbnb7nSzF7iiGNT4UwzvYawm0T9p1k7X1WOqW3l7OEbIwoKl7/9azT4BBJm7qUMRfB9Zio5cL3rKubJVz7+LEEIW4iBeDWLanhUDgy9BO2JKCt8bfp/U2tltgXtu9Fm/UFPALI8=

‎CHANGELOG.md

Lines changed: 45 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,13 +6,51 @@ Complete rewrite in ES2015.
66
* Promise-ified the API
77
* Auto-generation of documentation
88
* Modularized codebase
9-
* Refactored tests to run primarially in mocha
9+
* Refactored tests to run primarily in mocha
1010

1111
#### Breaking changes
12-
* Search API no longer takes a string it now takes an object with properties `q`, `sort`, and `order` to make
13-
the parts of the query easier to grok and to better match GitHub's API
14-
* `Repository.getSha` now returns the same data as GitHub's API. If the reqeusted object is not a directory then the
15-
response will contain a property `SHA`, and if the reqeusted object is a directory then the contents of the
16-
directory are `stat`ed
12+
Most of the breaking changes are just methods that got renamed. The changes to `User` and `Organization` are deeper
13+
changes that now scope a particular `User` or `Organization` to the entity they were instantiated with. You will need
14+
separate `User`s to query data about different user accounts.
15+
16+
* `Github.getOrg` → `Github.getOrganization` and requires an organization name.
17+
* `Github.getUser` now requires a username.
18+
* `Issue.comment` → `Issue.createIssueComment`
19+
* `Issue.create` → `Issue.createIssue`
20+
* `Issue.edit` → `Issue.editIssue`
21+
* `Issue.get` → `Issue.getIssue`
22+
* `Issue.list` → `Issue.listIssues`
23+
* `Repository.branch` → `Repository.createBranch`
24+
* `Repository.collaborators` → `Repository.getCollaborators`
25+
* `Repository.compare` → `Repository.compareBranches`
26+
* `Repository.contents` → `Repository.getContents` and now takes an argument for the content type
27+
* `Repository.delete` has been removed.
28+
* `Repository.editHook` → `Repository.updateHook`
29+
* `Repository.editRelease` → `Repository.updateRelease`
30+
* `Repository.getCommit` no longer takes a branch as the first argument
31+
* `Repository.getPull` → `Repository.getPullRequest`
1732
* `Repository.getRef` now returns the `refspec` from GitHub's API.
18-
* `Repository.delete` has been removed
33+
* `Repository.getSha` now returns the same data as GitHub's API. If the reqeusted object is not a directory then the
34+
response will contain a property `SHA`, and if the reqeusted object is a directory then the contents of the directory
35+
are `stat`ed.
36+
* `Repository.getStatuses` → `Repository.listStatuses`
37+
* `Repository.listPulls` → `Repository.listPullRequests`
38+
* `Repository.postBlob` → `Repository.createBlob`
39+
* `Repository.postTree` → `Repository.createTree`
40+
* `Repository.read` remove in favor of `Repository.getContents`
41+
* `Repository.remove` → `Repository.deleteFile`
42+
* `Repository.show` → `Repository.getDetails`
43+
* `Repository.write` → `Repository.writeFile`
44+
* `Search.code` → `Search.forCode`
45+
* `Search.issues` → `Search.forIssues`
46+
* `Search.repositories` → `Search.forRepositories`
47+
* `Search.users` → `Search.forUsers`
48+
* The Search API no longer takes a string, it now takes an object with properties `q`, `sort`, and `order` to make the
49+
parts of the query easier to grok and to better match GitHub's API.
50+
* `User.gists` → `User.getGists`
51+
* `User.notifications` → `User.getNotifications`
52+
* `User.orgRepos` → `Organization.getRepos`
53+
* `User.orgs` → `User.getOrgs`
54+
* `User.repos` → `User.getRepos`
55+
* `User.show` → `User.getProfile` and no longer takes filtering options
56+
* `User.userStarred` → `User.getStarredRepos`

‎README.md

Lines changed: 72 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -17,25 +17,86 @@ npm install github-api
1717
```
1818

1919
## Compatibility
20-
21-
[![Sauce Test Status](https://saucelabs.com/browser-matrix/githubjs.svg)](https://saucelabs.com/u/githubjs)
22-
23-
**Note**: Starting from version 0.10.8, Github.js supports **Internet Explorer 9**. However, the underlying methodology
24-
used under the hood to perform CORS requests (the `XDomainRequest` object), [has limitations](xhr-link).
25-
In particular, requests must be targeted to the same scheme as the hosting page. This means that if a page is at
26-
http://example.com, your target URL must also begin with HTTP. Similarly, if your page is at https://example.com, then
27-
your target URL must also begin with HTTPS. For this reason, if your requests are sent to the GitHub API (the default),
28-
which are served via HTTPS, your page must use HTTPS too.
20+
Github.js is tested on Node:
21+
* 0.10
22+
* 0.12
23+
* 4.x
24+
* 5.x
2925

3026
## GitHub Tools
3127

3228
The team behind Github.js has created a whole organization, called [GitHub Tools](https://github.com/github-tools),
3329
dedicated to GitHub and its API. In the near future this repository could be moved under the GitHub Tools organization
3430
as well. In the meantime, we recommend you to take a look at other projects of the organization.
3531

36-
## Example
32+
## Samples
33+
34+
```javascript
35+
/*
36+
Data can be retrieved from the API either using callbacks (as in versions < 1.0)
37+
or using a new promise-based API. For now the promise-based API just returns the
38+
raw HTTP request promise; this might change in the next version.
39+
*/
40+
var GitHub = require('github-api');
41+
42+
// unauthenticated client
43+
var gh = new GitHub();
44+
var gist = gh.getGist(); // not a gist yet
45+
gist.create({
46+
public: true,
47+
description: 'My first gist',
48+
files: {
49+
"file1.txt": {
50+
contents: "Aren't gists great!"
51+
}
52+
}
53+
}).then(function(httpResponse) {
54+
// Promises!
55+
var gist = httpResponse.data;
56+
gist.read(function(err, gist, xhr) {
57+
// if no error occurred then err == null
58+
59+
// gist == httpResponse.data
60+
61+
// xhr == httpResponse
62+
});
63+
});
64+
```
65+
66+
```javascript
67+
var GitHub = require('github-api');
3768

38-
**TODO**
69+
// basic auth
70+
var gh = new GitHub({
71+
username: 'FOO',
72+
password: 'NotFoo'
73+
});
74+
75+
var me = gh.getUser();
76+
me.getNotification(function(err, notifcations) {
77+
// do some stuff
78+
});
79+
80+
var clayreimann = gh.getUser('clayreimann');
81+
clayreimann.getStarredRepos()
82+
.then(function(httpPromise) {
83+
var repos = httpPromise.data;
84+
});
85+
```
86+
87+
```javascript
88+
var GitHub = require('github-api');
89+
90+
// token auth
91+
var gh = new GitHub({
92+
token: 'MY_OAUTH_TOKEN'
93+
});
94+
95+
var yahoo = gh.getOrganization('yahoo');
96+
yahoo.getRepos(function(err, repos) {
97+
// look at all the repos!
98+
})
99+
```
39100

40101
[cdnjs]: https://cdnjs.com/
41102
[codecov]: https://codecov.io/github/michael/github?branch=master

‎gulpfile.babel.js

Lines changed: 60 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,14 @@ import stylish from 'gulp-jscs-stylish';
66
import babel from 'gulp-babel';
77
import rename from 'gulp-rename';
88

9-
import browserify from 'browserify';
10-
import buffer from 'vinyl-buffer';
11-
import del from 'del';
12-
import path from 'path';
9+
import browserify from 'browserify';
10+
import buffer from 'vinyl-buffer';
11+
import del from 'del';
12+
import path from 'path';
1313
import {Promise} from 'es6-promise';
14-
import source from 'vinyl-source-stream';
15-
import sourcemaps from 'gulp-sourcemaps';
16-
import uglify from 'gulp-uglify';
14+
import source from 'vinyl-source-stream';
15+
import sourcemaps from 'gulp-sourcemaps';
16+
import uglify from 'gulp-uglify';
1717

1818
const ALL_SOURCES = [
1919
path.join(__dirname, '/*.js'),
@@ -37,51 +37,69 @@ gulp.task('clean', function() {
3737
return Promise.all([del('dist/'), del('coverage/')]);
3838
});
3939

40-
const browserifyConfig = {
40+
gulp.task('build', [
41+
'build:bundled:min',
42+
'build:external:min',
43+
'build:bundled:debug',
44+
'build:external:debug',
45+
'build:components'
46+
]);
47+
48+
const bundledConfig = {
4149
debug: true,
42-
entries: 'src/Github.js',
43-
standalone: 'Github'
50+
entries: 'lib/GitHub.js',
51+
standalone: 'GitHub'
4452
};
45-
gulp.task('build', function() {
46-
browserify(browserifyConfig)
47-
.transform('babelify')
48-
.bundle()
49-
.pipe(source('Github.js'))
50-
.pipe(buffer())
51-
.pipe(sourcemaps.init({
52-
loadMaps: true
53-
}))
54-
.pipe(uglify())
55-
.pipe(rename({
56-
extname: '.bundle.min.js'
57-
}))
53+
const externalConfig = {
54+
debug: true,
55+
entries: 'lib/GitHub.js',
56+
standalone: 'GitHub',
57+
external: [
58+
'axios',
59+
'js-base64',
60+
'es6-promise',
61+
'debug',
62+
'utf8'
63+
],
64+
bundleExternal: false
65+
};
66+
gulp.task('build:bundled:min', function() {
67+
return buildBundle(bundledConfig, '.bundle.min.js', true);
68+
});
69+
gulp.task('build:external:min', function() {
70+
return buildBundle(externalConfig, '.min.js', true);
71+
});
72+
gulp.task('build:bundled:debug', function() {
73+
return buildBundle(bundledConfig, '.bundle.js', false);
74+
});
75+
gulp.task('build:external:debug', function() {
76+
return buildBundle(externalConfig, '.js', false);
77+
});
78+
gulp.task('build:components', function() {
79+
return gulp.src('lib/*.js')
80+
.pipe(sourcemaps.init())
81+
.pipe(babel())
5882
.pipe(sourcemaps.write('.'))
59-
.pipe(gulp.dest('dist'))
83+
.pipe(gulp.dest('dist/components'))
6084
;
85+
});
6186

62-
browserify(browserifyConfig)
87+
function buildBundle(options, extname, minify) {
88+
let stream = browserify(options)
6389
.transform('babelify')
6490
.bundle()
65-
.pipe(source('Github.js'))
91+
.pipe(source('GitHub.js'))
6692
.pipe(buffer())
6793
.pipe(sourcemaps.init({
6894
loadMaps: true
69-
}))
70-
.pipe(rename({
71-
extname: '.bundle.js'
72-
}))
73-
.pipe(sourcemaps.write('.'))
74-
.pipe(gulp.dest('dist'))
75-
;
95+
}));
7696

77-
return gulp.src('src/*.js')
78-
.pipe(babel())
79-
.pipe(sourcemaps.init())
97+
if (minify) {
98+
stream = stream.pipe(uglify());
99+
}
100+
101+
return stream.pipe(rename({extname}))
80102
.pipe(sourcemaps.write('.'))
81-
.pipe(gulp.dest('dist/components'))
103+
.pipe(gulp.dest('dist'))
82104
;
83-
});
84-
85-
gulp.task('default', ['clean'], function() {
86-
gulp.start('lint', 'test:mocha', 'build');
87-
});
105+
}

0 commit comments

Comments
 (0)