Add .rateLimit property to responses and errors (#34)

index.js

@@ -1,6 +1,12 @@
 'use strict';
 const got = require('got');
 
+const getRateLimit = ({headers}) => ({
+	limit: parseInt(headers['x-ratelimit-limit'], 10),
+	remaining: parseInt(headers['x-ratelimit-remaining'], 10),
+	reset: new Date(parseInt(headers['x-ratelimit-reset'], 10) * 1000)
+});
+
 const create = () => got.create({
 	options: got.mergeOptions(got.defaults.options, {
 		json: true,
@@ -23,14 +29,26 @@ const create = () => got.create({
 			return next(options);
 		}
 
-		return next(options).catch(error => {
-			if (error.response && error.response.body) {
-				error.name = 'GitHubError';
-				error.message = `${error.response.body.message} (${error.statusCode})`;
-			}
-
-			throw error;
-		});
+		// TODO: Use async/await here when Got supports the `handler` being an async function
+		return next(options)
+			.then(response => { // eslint-disable-line promise/prefer-await-to-then
+				response.rateLimit = getRateLimit(response);
+				return response;
+			})
+			.catch(error => {
+				const {response} = error;
+
+				if (response && response.body) {
+					error.name = 'GitHubError';
+					error.message = `${response.body.message} (${error.statusCode})`;
+				}
+
+				if (response) {
+					error.rateLimit = getRateLimit(response);
+				}
+
+				throw error;
+			});
 	}
 });
 

readme.md

@@ -91,6 +91,22 @@ Type: `Object`
 Can be specified as a plain object and will be serialized as JSON with the appropriate headers set.
 
 
+## Rate limit
+
+Responses and errors have a `.rateLimit` property with info about the current [rate limit](https://developer.github.com/v3/#rate-limiting). *(This is not yet implemented for the stream API)*
+
+```js
+const ghGot = require('gh-got');
+
+(async () => {
+	const {rateLimit} = await ghGot('users/sindresorhus');
+
+	console.log(rateLimit);
+	//=> {limit: 5000, remaining: 4899, reset: [Date 2018-12-31T20:45:20.000Z]}
+})();
+```
+
+
 ## Authorization
 
 Authorization for GitHub uses the following logic:

test.js

@@ -72,3 +72,17 @@ test('custom error', async t => {
 		message: 'Bad credentials (401)'
 	});
 });
+
+test('.rateLimit response property', async t => {
+	const {rateLimit} = await ghGot('users/sindresorhus');
+	t.is(typeof rateLimit.limit, 'number');
+	t.is(typeof rateLimit.remaining, 'number');
+	t.true(rateLimit.reset instanceof Date);
+});
+
+test('.rateLimit error property', async t => {
+	const {rateLimit} = await t.throwsAsync(ghGot('users/sindresorhus', {token: 'fail'}));
+	t.is(typeof rateLimit.limit, 'number');
+	t.is(typeof rateLimit.remaining, 'number');
+	t.true(rateLimit.reset instanceof Date);
+});