fix(types): tweak onAuth typings + add http.d.ts (#1053)

billiegoose · web-flow · commit 7b05b3df39c0 · 2020-02-17T20:36:27.000-05:00
diff --git a/__tests__/test-push.js b/__tests__/test-push.js
@@ -282,29 +282,46 @@ describe('push', () => {
     let fillCalled = false
     let approvedCalled = false
     let rejectedCalled = false
+    let onAuthArgs = null
+    let onAuthSuccessArgs = null
+    let onAuthFailureArgs = null
     await push({
       fs,
       http,
       gitdir,
       remote: 'auth',
       ref: 'master',
-      async onAuth({ url }) {
+      async onAuth(...args) {
         fillCalled = true
+        onAuthArgs = args
         return {
           username: 'testuser',
           password: 'testpassword',
         }
       },
-      async onAuthSuccess(auth) {
+      async onAuthSuccess(...args) {
         approvedCalled = true
+        onAuthSuccessArgs = args
       },
-      async onAuthFailure(auth) {
+      async onAuthFailure(...args) {
         rejectedCalled = true
+        onAuthFailureArgs = args
       },
     })
     expect(fillCalled).toBe(true)
     expect(approvedCalled).toBe(true)
     expect(rejectedCalled).toBe(false)
+    expect(onAuthArgs).toEqual([
+      `https://${localhost}:8888/test-push-server-auth.git`,
+    ])
+    expect(onAuthSuccessArgs).toEqual([
+      `https://${localhost}:8888/test-push-server-auth.git`,
+      {
+        username: 'testuser',
+        password: 'testpassword',
+      },
+    ])
+    expect(onAuthFailureArgs).toBeNull()
   })
   it('onAuthFailure', async () => {
     // Setup
@@ -320,25 +337,32 @@ describe('push', () => {
     let approvedCalled = false
     let rejectedCalled = false
     let err
+    let onAuthArgs = null
+    let onAuthSuccessArgs = null
+    let onAuthFailureArgs = null
+
     try {
       await push({
         fs,
         http,
         gitdir,
         remote: 'auth',
         ref: 'master',
-        async onAuth({ url }) {
+        async onAuth(...args) {
           fillCalled = true
+          onAuthArgs = args
           return {
             username: 'testuser',
             password: 'NoT_rIgHt',
           }
         },
-        async onAuthSuccess(auth) {
+        async onAuthSuccess(...args) {
           approvedCalled = true
+          onAuthSuccessArgs = args
         },
-        async onAuthFailure(auth) {
+        async onAuthFailure(...args) {
           rejectedCalled = true
+          onAuthFailureArgs = args
         },
       })
     } catch (e) {
@@ -349,5 +373,16 @@ describe('push', () => {
     expect(fillCalled).toBe(true)
     expect(approvedCalled).toBe(false)
     expect(rejectedCalled).toBe(true)
+    expect(onAuthArgs).toEqual([
+      `https://${localhost}:8888/test-push-server-auth.git`,
+    ])
+    expect(onAuthSuccessArgs).toBeNull()
+    expect(onAuthFailureArgs).toEqual([
+      `https://${localhost}:8888/test-push-server-auth.git`,
+      {
+        username: 'testuser',
+        password: 'NoT_rIgHt',
+      },
+    ])
   })
 })
diff --git a/declaration.tsconfig.json b/declaration.tsconfig.json
@@ -1,5 +1,5 @@
 {
-  "include": ["dist/index.js"],
+  "include": ["dist/index.js", "dist/http.js"],
   "exclude": ["node_modules"],
   "compilerOptions": {
     "strictNullChecks": true,
diff --git a/docs/onAuth.md b/docs/onAuth.md
@@ -13,14 +13,19 @@ Git does all its authentication using HTTPS Basic Authentication.
 An `onAuth` function is called with a `url` and should return a credential object:
 
 ```ts
-type AuthCallback = (url: string) => Promise<GitAuth>;
-
-type GitAuth = {
-  username?: string;
-  password?: string;
-  token?: string;
-  oauth2format?: string;
-}
+/**
+ * @callback AuthCallback
+ * @param {string} url
+ * @returns {GitAuth | Promise<GitAuth>}
+ */
+
+/**
+ * @typedef {Object} GitAuth
+ * @property {string} [username]
+ * @property {string} [password]
+ * @property {string} [token]
+ * @property {string} [oauth2format]
+ */
 ```
 
 ## Option 1: Username & Password
diff --git a/docs/onAuthFailure.md b/docs/onAuthFailure.md
@@ -5,16 +5,14 @@ sidebar_label: onAuthFailure
 
 The `onAuthFailure` callback is called when credentials fail. This is helpful to know if say, you have saved password and want to offer to delete ones that fail.
 
-An `onAuthFailure` function is called with a `{ url, auth }` object.
+An `onAuthFailure` function is called with a `url` and an `auth` object.
 
 ```js
 /**
  * @callback AuthFailureCallback
- * @param {object} args.
- * @param {string} args.url
- * @param {GitAuth} args.auth
- *
- * @returns {Promise<void>}
+ * @param {string} url
+ * @param {GitAuth} auth
+ * @returns {void | Promise<void>}
  */
 
 /**
@@ -32,7 +30,7 @@ An `onAuthFailure` function is called with a `{ url, auth }` object.
 const git = require('isomorphic-git')
 git.clone({
   ...,
-  onAuthFailure: ({ url, auth }) => {
+  onAuthFailure: (url, auth) => {
     if (confirm('Access was denied. Delete saved password?')) {
       forgetSavedPassword(url)
     }
diff --git a/docs/onAuthSuccess.md b/docs/onAuthSuccess.md
@@ -5,16 +5,14 @@ sidebar_label: onAuthSuccess
 
 The `onAuthSuccess` callback is called when credentials fail. This is helpful to know if say, you want to offer to save a password but only after it succeeds.
 
-An `onAuthSuccess` function is called with a `{ url, auth }` object.
+An `onAuthSuccess` function is called with a `url` and an `auth` object.
 
 ```js
 /**
  * @callback AuthSuccessCallback
- * @param {object} args.
- * @param {string} args.url
- * @param {GitAuth} args.auth
- *
- * @returns {Promise<void>}
+ * @param {string} url
+ * @param {GitAuth} auth
+ * @returns {void | Promise<void>}
  */
 
 /**
@@ -32,7 +30,7 @@ An `onAuthSuccess` function is called with a `{ url, auth }` object.
 const git = require('isomorphic-git')
 git.clone({
   ...,
-  onAuthSuccess: ({ url, auth }) => {
+  onAuthSuccess: (url, auth) => {
     if (confirm('Remember password?')) {
       savedPassword(url, auth)
     }
diff --git a/package.json b/package.json
@@ -8,6 +8,7 @@
   "module": "./dist/index.js",
   "exports": {
     ".": "./dist/index.cjs",
+    "./dist/index.cjs": "./dist/index.cjs",
     "./dist/index.js": "./dist/index.js",
     "./dist/http.cjs": "./dist/http.cjs",
     "./dist/http.js": "./dist/http.js"
@@ -54,6 +55,7 @@
     "dist/bundle.umd.min.js",
     "dist/bundle.umd.min.js.map",
     "dist/http.cjs",
+    "dist/http.d.ts",
     "dist/http.js",
     "dist/http.umd.min.js",
     "dist/index.cjs",
diff --git a/src/builtin-browser/http.js b/src/builtin-browser/http.js
@@ -2,6 +2,36 @@
 import { collect } from '../utils/collect.js'
 import { fromStream } from '../utils/fromStream'
 
+// Sorry for the copy & paste from typedefs.js but if we import typedefs.js we'll get a whole bunch of extra comments
+// in the rollup output
+
+/**
+ * @typedef {Object} GitHttpRequest
+ * @property {string} url - The URL to request
+ * @property {string} [method='GET'] - The HTTP method to use
+ * @property {Object<string, string>} [headers={}] - Headers to include in the HTTP request
+ * @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of POST requests
+ * @property {string} [core] - If your `http` plugin needs access to other plugins, it can do so via `git.cores.get(core)`
+ * @property {GitEmitterPlugin} [emitter] - If your `http` plugin emits events, it can do so via `emitter.emit()`
+ * @property {string} [emitterPrefix] - The `emitterPrefix` passed by the user when calling a function. If your plugin emits events, prefix the event name with this.
+ */
+
+/**
+ * @typedef {Object} GitHttpResponse
+ * @property {string} url - The final URL that was fetched after any redirects
+ * @property {string} [method] - The HTTP method that was used
+ * @property {Object<string, string>} [headers] - HTTP response headers
+ * @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of the response
+ * @property {number} statusCode - The HTTP status code
+ * @property {string} statusMessage - The HTTP status message
+ */
+
+/**
+ * HttpClient
+ *
+ * @param {GitHttpRequest} request
+ * @returns {Promise<GitHttpResponse>}
+ */
 export default async function http({
   onProgress,
   url,
diff --git a/src/builtin-node/http.js b/src/builtin-node/http.js
@@ -2,6 +2,36 @@ import { asyncIteratorToStream } from '../utils/asyncIteratorToStream.js'
 import { collect } from '../utils/collect.js'
 import { fromNodeStream } from '../utils/fromNodeStream.js'
 
+// Sorry for the copy & paste from typedefs.js but if we import typedefs.js we'll get a whole bunch of extra comments
+// in the rollup output
+
+/**
+ * @typedef {Object} GitHttpRequest
+ * @property {string} url - The URL to request
+ * @property {string} [method='GET'] - The HTTP method to use
+ * @property {Object<string, string>} [headers={}] - Headers to include in the HTTP request
+ * @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of POST requests
+ * @property {string} [core] - If your `http` plugin needs access to other plugins, it can do so via `git.cores.get(core)`
+ * @property {GitEmitterPlugin} [emitter] - If your `http` plugin emits events, it can do so via `emitter.emit()`
+ * @property {string} [emitterPrefix] - The `emitterPrefix` passed by the user when calling a function. If your plugin emits events, prefix the event name with this.
+ */
+
+/**
+ * @typedef {Object} GitHttpResponse
+ * @property {string} url - The final URL that was fetched after any redirects
+ * @property {string} [method] - The HTTP method that was used
+ * @property {Object<string, string>} [headers] - HTTP response headers
+ * @property {AsyncIterableIterator<Uint8Array>} [body] - An async iterator of Uint8Arrays that make up the body of the response
+ * @property {number} statusCode - The HTTP status code
+ * @property {string} statusMessage - The HTTP status message
+ */
+
+/**
+ * HttpClient
+ *
+ * @param {GitHttpRequest} request
+ * @returns {Promise<GitHttpResponse>}
+ */
 export default async function http({
   onProgress,
   url,
diff --git a/src/managers/GitRemoteHTTP.js b/src/managers/GitRemoteHTTP.js
@@ -83,7 +83,7 @@ export class GitRemoteHTTP {
     // apparently doesn't realize this is a git request and is returning the HTML for the "Azure DevOps Services | Sign In" page.
     if ((res.statusCode === 401 || res.statusCode === 203) && onAuth) {
       // Acquire credentials and try again
-      // TODO: read `useHttpPath` value from git config and pass as 2nd argument
+      // TODO: read `useHttpPath` value from git config and pass as 2nd argument?
       auth = await onAuth(_origUrl)
       const _auth = calculateBasicAuthUsernamePasswordPair(auth)
       if (_auth) {
@@ -97,9 +97,9 @@ export class GitRemoteHTTP {
       })
       // Tell credential manager if the credentials were no good
       if (res.statusCode === 401 && onAuthFailure) {
-        await onAuthFailure({ url: _origUrl, auth })
+        await onAuthFailure(_origUrl, auth)
       } else if (res.statusCode === 200 && onAuthSuccess) {
-        await onAuthSuccess({ url: _origUrl, auth })
+        await onAuthSuccess(_origUrl, auth)
       }
     }
     if (res.statusCode !== 200) {
diff --git a/src/typedefs.js b/src/typedefs.js

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`		`- "include": ["dist/index.js"],`
	`2`	`+ "include": ["dist/index.js", "dist/http.js"],`
`3`	`3`	`"exclude": ["node_modules"],`
`4`	`4`	`"compilerOptions": {`
`5`	`5`	`"strictNullChecks": true,`