feat: add a default export and support for importing the ES module build in Node 12+ (#1043)

billiegoose · web-flow · commit 064e62486284 · 2020-02-11T22:54:34.000-05:00
diff --git a/README.md b/README.md
@@ -72,6 +72,8 @@ At the time of writing, the following breaking changes are planned:
 - [ ] Make sure that the payload output of `readTag` and `readCommit` is newline-correct to easily verify. Then remove the `verify` command.
 - [x] Make sure all the example code works.
 - [x] Update the Getting Started guide.
+- [ ] Update the WebWorker Guide.
+- [ ] Update the Useful Snippets.
 
 ## Getting Started
 
@@ -100,12 +102,12 @@ const fs = new LightningFS('fs')
 </script>
 ```
 
-If you're using ES module syntax, use either a namespace import or named imports to benefit from tree-shaking:
+If you're using ES module syntax, you can use either the default import or named imports to benefit from tree-shaking:
 
 ```js
-import * as git from 'isomorphic-git'
+import git from 'isomorphic-git'
 // or
-import {plugins, clone, commit, push} from 'isomorphic-git
+import {plugins, clone, commit, push} from 'isomorphic-git'
 ```
 
 View the full [Getting Started guide](https://isomorphic-git.github.io/docs/quickstart.html) on the docs website.
@@ -150,9 +152,9 @@ In the package.json you'll see there are actually 3 different versions:
 
 This deserves a brief explanation.
 
-- the "main" version is for node.
-- the "module" version is for webpack or other browser bundlers.
-- the "unpkg" version is the UMD build.
+- the "main" version is a CommonJS build
+- the "module" version is an ES Module build
+- the "unpkg" version is a minified UMD build with dependencies already bundled
 
 ### `isogit` CLI
 
diff --git a/__tests__/__snapshots__/test-exports.js.snap b/__tests__/__snapshots__/test-exports.js.snap
@@ -15,6 +15,7 @@ Array [
   "clone",
   "commit",
   "currentBranch",
+  "default",
   "deleteBranch",
   "deleteRef",
   "deleteRemote",
diff --git a/__tests__/test-clone.js b/__tests__/test-clone.js
@@ -1,8 +1,9 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 
 const { clone } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/__tests__/test-fetch.js b/__tests__/test-fetch.js
@@ -1,8 +1,9 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 
 const { sleep } = require('isomorphic-git/internal-apis')
-const { http } = require('isomorphic-git/http')
 const { E, setConfig, fetch } = require('isomorphic-git')
 
 // this is so it works with either Node local tests or Browser WAN tests
diff --git a/__tests__/test-getRemoteInfo.js b/__tests__/test-getRemoteInfo.js
@@ -1,9 +1,10 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 // @ts-ignore
 const snapshots = require('./__snapshots__/test-getRemoteInfo.js.snap')
 const registerSnapshots = require('./__helpers__/jasmine-snapshots')
 const { E, getRemoteInfo } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/__tests__/test-hosting-providers.js b/__tests__/test-hosting-providers.js
@@ -1,8 +1,9 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 
 const { fetch, push } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/__tests__/test-plugin-http.js b/__tests__/test-plugin-http.js
@@ -1,8 +1,9 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 
 const { clone } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/__tests__/test-plugin_credentialManager.js b/__tests__/test-plugin_credentialManager.js
@@ -1,8 +1,9 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 
 const { setConfig, push, E } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/__tests__/test-push.js b/__tests__/test-push.js
@@ -1,11 +1,12 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 // @ts-ignore
 const snapshots = require('./__snapshots__/test-push.js.snap')
 const registerSnapshots = require('./__helpers__/jasmine-snapshots')
 
 const { setConfig, push, listBranches } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/__tests__/test-submodules.js b/__tests__/test-submodules.js
@@ -1,8 +1,9 @@
 /* eslint-env node, browser, jasmine */
+import http from 'isomorphic-git/http'
+
 const { makeFixture } = require('./__helpers__/FixtureFS.js')
 
 const { clone, checkout, listFiles, commit } = require('isomorphic-git')
-const { http } = require('isomorphic-git/http')
 
 // this is so it works with either Node local tests or Browser WAN tests
 const localhost =
diff --git a/docs/faq.md b/docs/faq.md
@@ -88,6 +88,33 @@ I haven't had time to review them all.
 > It seems that there's no default export which should just contain all the functions
 > I'm suggesting to have a default export that gathers all the functions together.
 
+In 0.x.x I withheld adding a `default` export for the reasons explained below. However in 1.x.x there _is_ a default export - with a caveat!
+The CommonJS format does _not_ have a default export. This actually makes the most sense because it means this Just Works (TM):
+
+```js
+const git = require('isomorphic-git')
+```
+
+If you have a default export _and_ a named export, Rollup spits out a file that has to be consumed like this...
+
+```js
+const git = require('isomorphic-git').default
+```
+
+which nobody wants.
+
+To benefit from tree-shaking, you still should use named exports. But for convenience there is a default export now! So either of these work:
+
+```js
+import git from 'isomorphic-git'
+// or
+import * as git from 'isomorphic-git'
+```
+
+which strays from my usual Pythonic "there should only be one way to do it, and that way should be the best way" attitude... but having a default export also makes using the library _simpler_ because you don't have to think about whether to use a namespace import or a default import. And it looks nicer.
+
+Old Answer preserved for posterity:
+
 _Answer by Will Hilton (@wmhilton):_
 
 Default exports are actually really bad for tree-shaking. If you do `import * as git from 'isomorphic-git'` and only use `git.log`, rollup and webpack are smart enough to only bundle `git.log`.
@@ -137,3 +164,5 @@ A slightly more efficient way of telling if you have the full history, would be
 ## Does it support wire protocol version 2?
 
 Not yet, but you can go [upvote the issue](https://github.com/isomorphic-git/isomorphic-git/issues/585)
+As soon as GitHub supports the [fetch filter feature](https://git-scm.com/docs/protocol-v2#_fetch) I'll have a reason to work on it, because that would be extremely useful in browser environments!
+But until then, there's no advantage to using the new protocol.
diff --git a/docs/guide-quickstart.md b/docs/guide-quickstart.md
@@ -12,7 +12,7 @@ First, let's set up LightningFS and isomorphic-git. *Note: I've already done thi
 <script src="https://unpkg.com/@isomorphic-git/lightning-fs"></script>
 <script src="https://unpkg.com/isomorphic-git@beta"></script>
 <script type="module">
-import { http } from 'https://unpkg.com/isomorphic-git@beta/dist/http.js'
+import http from 'https://unpkg.com/isomorphic-git@beta/dist/http.js'
 // Initialize isomorphic-git with a file system
 window.fs = new LightningFS('fs')
 // I prefer using the Promisified version honestly
diff --git a/docs/http.md b/docs/http.md
@@ -15,7 +15,7 @@ The Node client uses the [`simple-get`](https://npm.im/simple-get) package under
 
 ```js
 const git = require("isomorphic-git");
-const { http } = require("isomorphic-git/dist/http.cjs");
+const http = require("isomorphic-git/dist/http.cjs");
 git.getRemoteInfo({ http, url: 'https://github.com/isomorphic-git/isomorphic-git' })
   .then(console.log)
 ```
@@ -28,9 +28,9 @@ wrap your own HTTP client. (See section below.)
 The Browser client uses the [`Fetch API`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) under the hood.
 
 ```js
-import { getRemoteInfo } from "isomorphic-git";
-import { http } from "isomorphic-git/dist/http.js";
-getRemoteInfo({ http, url: 'https://github.com/isomorphic-git/isomorphic-git' })
+import git from "isomorphic-git";
+import http from "isomorphic-git/dist/http.js";
+git.getRemoteInfo({ http, url: 'https://github.com/isomorphic-git/isomorphic-git' })
   .then(console.log)
 ```
 
diff --git a/jest.config.js b/jest.config.js
@@ -2,7 +2,7 @@ module.exports = {
   testRegex: '/__tests__/(server-only\\.)?test-[^\\/]+\\.js',
   moduleNameMapper: {
     '^isomorphic-git$': '<rootDir>/src',
-    '^isomorphic-git/http$': '<rootDir>/src/builtin-node/http.js',
+    '^isomorphic-git/http$': '<rootDir>/dist/http.cjs',
     '^isomorphic-git/(.+)$': '<rootDir>/src/$1'
   },
   collectCoverageFrom: ['src/*.js', 'src/**/*.js'],
diff --git a/package-scripts.js b/package-scripts.js
@@ -69,18 +69,24 @@ module.exports = {
         : optional(`cross-env bundlewatch dist/bundle.umd.min.js`)
     },
     website: {
-      default: series.nps(
-        'website.codemirorify',
-        'website.cpstatic',
-        'website.build',
-        'website.publish'
-      ),
-      dev: '(cd website && npm start)',
+      default: process.env.CI
+        ? series.nps(
+          'website.codemirrorify',
+          'website.cpstatic',
+          'website.build',
+          'website.publish'
+        )
+        : series.nps(
+          'website.codemirrorify',
+          'website.cpstatic',
+          'website.dev'
+        ),
       codemirrorify:
         '(cd website/packages/codemirrorify && npm install && npm run build)',
       cpstatic:
         'cp dist/bundle.umd.min.* website/static/js && cp dist/http.js website/static/js && cp website/packages/codemirrorify/dist/main.js website/static/js/codemirrorify.js',
       build: '(cd website && npm install && npm run build)',
+      dev: '(cd website && npm start)',
       publish: '(cd website && node ./scripts/deploy-gh-pages.js)'
     },
     // ATTENTION:
diff --git a/package.json b/package.json
@@ -3,12 +3,19 @@
   "version": "0.0.0-development",
   "description": "A pure JavaScript reimplementation of git for node and browsers",
   "typings": "./dist/index.d.ts",
-  "main": "dist/index.cjs",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.cjs",
+    "./dist/index.js": "./dist/index.js",
+    "./dist/http.cjs": "./dist/http.cjs",
+    "./dist/http.js": "./dist/http.js"
+  },
   "browser": {
     "isomorphic-git": "./dist/bundle.umd.min.js",
     "isomorphic-git/internal-apis": "./dist/internal.umd.min.js"
   },
-  "module": "dist/index.js",
   "unpkg": "dist/bundle.umd.min.js",
   "bin": {
     "isogit": "./cli.js"
diff --git a/rollup.config.js b/rollup.config.js
@@ -10,6 +10,7 @@ const external = [
   'stream',
   'crc/lib/crc32.js',
   'sha.js/sha1',
+  'sha.js/sha1.js',
   ...Object.keys(pkg.dependencies)
 ]
 
@@ -28,23 +29,23 @@ const moduleConfig = input => ({
 })
 
 // Node.js
-const nodeConfig = input => ({
+const nodeConfig = (input, output = input) => ({
   input: `src/${input}`,
   external: [...external],
   output: [
     {
       format: 'cjs',
       name: 'git',
-      file: `dist/${path.basename(input, '.js')}.cjs`
+      file: `dist/${path.basename(output, '.js')}.cjs`
     }
   ]
 })
 
-const inputs = ['index.js', 'internal-apis.js']
-
 export default [
-  ...inputs.map(nodeConfig),
-  ...inputs.map(moduleConfig),
+  moduleConfig('index.js'),
+  nodeConfig('api/_index.js', 'index.js'),
+  moduleConfig('internal-apis.js'),
+  nodeConfig('internal-apis.js'),
   nodeConfig('builtin-node/http.js'),
   moduleConfig('builtin-browser/http.js')
 ]
diff --git a/src/api/_index.js b/src/api/_index.js
@@ -0,0 +1,65 @@
+import '../commands/typedefs.js'
+
+export * from './add.js'
+export * from './addNote.js'
+export * from './addRemote.js'
+export * from './annotatedTag.js'
+export * from './branch.js'
+export * from './checkout.js'
+export * from './clone.js'
+export * from './commit.js'
+export * from './getConfig.js'
+export * from './getConfigAll.js'
+export * from './setConfig.js'
+export * from './currentBranch.js'
+export * from './deleteBranch.js'
+export * from './deleteRef.js'
+export * from './deleteRemote.js'
+export * from './deleteTag.js'
+export * from './expandOid.js'
+export * from './expandRef.js'
+export * from './fetch.js'
+export * from './findMergeBase.js'
+export * from './findRoot.js'
+export * from './getRemoteInfo.js'
+export * from './hashBlob.js'
+export * from './indexPack.js'
+export * from './init.js'
+export * from './isDescendent.js'
+export * from './listBranches.js'
+export * from './listFiles.js'
+export * from './listNotes.js'
+export * from './listRemotes.js'
+export * from './listTags.js'
+export * from './log.js'
+export * from './merge.js'
+export * from './packObjects.js'
+export * from './pull.js'
+export * from './push.js'
+export * from './readBlob.js'
+export * from './readCommit.js'
+export * from './readNote.js'
+export * from './readObject.js'
+export * from './readTag.js'
+export * from './readTree.js'
+export * from './remove.js'
+export * from './removeNote.js'
+export * from './resetIndex.js'
+export * from './resolveRef.js'
+export * from './status.js'
+export * from './statusMatrix.js'
+export * from './tag.js'
+export * from './verify.js'
+export * from './version.js'
+export * from './walk.js'
+export * from './writeBlob.js'
+export * from './writeCommit.js'
+export * from './writeObject.js'
+export * from './writeRef.js'
+export * from './writeTag.js'
+export * from './writeTree.js'
+export * from './WORKDIR.js'
+export * from './STAGE.js'
+export * from './TREE.js'
+
+export { E } from '../models/GitError'
diff --git a/src/builtin-browser/http.js b/src/builtin-browser/http.js
@@ -2,7 +2,7 @@
 import { collect } from '../utils/collect.js'
 import { fromStream } from '../utils/fromStream'
 
-export async function http ({
+export default async function http ({
   onProgress,
   url,
   method = 'GET',
diff --git a/src/builtin-node/http.js b/src/builtin-node/http.js
@@ -2,7 +2,7 @@ import { asyncIteratorToStream } from '../utils/asyncIteratorToStream.js'
 import { collect } from '../utils/collect.js'
 import { fromNodeStream } from '../utils/fromNodeStream.js'
 
-export async function http ({
+export default async function http ({
   onProgress,
   url,
   method = 'GET',
diff --git a/src/commands/pack.js b/src/commands/pack.js
@@ -1,4 +1,4 @@
-import Hash from 'sha.js/sha1'
+import Hash from 'sha.js/sha1.js'
 
 import { types } from '../commands/types.js'
 import { FileSystem } from '../models/FileSystem.js'
diff --git a/src/index.js b/src/index.js
diff --git a/src/utils/shasum.js b/src/utils/shasum.js
diff --git a/website/i18n/en.json b/website/i18n/en.json
diff --git a/website/packages/codemirrorify/package-lock.json b/website/packages/codemirrorify/package-lock.json
diff --git a/website/sidebars.json b/website/sidebars.json
diff --git a/website/static/js/tutorial.js b/website/static/js/tutorial.js
