From 6e4f8b156f09d27c37ff79ad3381de9a5a57e387 Mon Sep 17 00:00:00 2001 From: William Hilton Date: Thu, 20 Feb 2020 22:29:37 -0500 Subject: [PATCH] chore: cleanup import paths and function name mangling (#1056) --- .eslintignore | 15 +- .gitignore | 74 +++---- README.md | 130 ++++++------ .../__helpers__/FixtureFS/makeBrowserFS.js | 9 +- .../__helpers__/FixtureFS/makeLightningFS.js | 4 +- .../__helpers__/FixtureFS/makeNodeFixture.js | 4 +- __tests__/__helpers__/generate-docs.js | 17 +- .../karma-load-successful-browsers.js | 11 +- __tests__/test-GitObjectManager.js | 24 --- azure-pipelines.yml | 134 ++++++------ declaration.tsconfig.json | 2 +- docs/guide-quickstart.md | 2 +- docs/http.md | 38 ++-- docs/snippets.md | 2 +- jest.config.js | 2 +- karma.conf.js | 11 +- package-lock.json | 6 +- package-scripts.js | 20 +- package.json | 42 ++-- rollup.config.js | 58 ++++-- spec/support/jasmine.json | 11 - src/api/_index.js | 64 ------ src/api/add.js | 47 ++++- src/api/addNote.js | 2 +- src/api/addRemote.js | 2 +- src/api/annotatedTag.js | 2 +- src/api/branch.js | 2 +- src/api/checkout.js | 2 +- src/api/clone.js | 2 +- src/api/commit.js | 2 +- src/api/currentBranch.js | 2 +- src/api/deleteBranch.js | 2 +- src/api/deleteRef.js | 8 +- src/api/deleteRemote.js | 2 +- src/api/deleteTag.js | 2 +- src/api/expandOid.js | 2 +- src/api/fetch.js | 2 +- src/api/findMergeBase.js | 2 +- src/api/findRoot.js | 2 +- src/api/getConfig.js | 2 +- src/api/getConfigAll.js | 2 +- src/api/indexPack.js | 2 +- src/api/init.js | 2 +- src/api/isDescendent.js | 2 +- src/api/listFiles.js | 2 +- src/api/listNotes.js | 2 +- src/api/listRemotes.js | 2 +- src/api/log.js | 2 +- src/api/merge.js | 2 +- src/api/packObjects.js | 2 +- src/api/pull.js | 2 +- src/api/push.js | 2 +- src/api/readBlob.js | 2 +- src/api/readCommit.js | 2 +- src/api/readNote.js | 2 +- src/api/readObject.js | 2 +- src/api/readTag.js | 2 +- src/api/readTree.js | 2 +- src/api/removeNote.js | 2 +- src/api/setConfig.js | 21 +- src/api/status.js | 8 +- src/api/statusMatrix.js | 4 +- src/api/walk.js | 2 +- src/api/writeBlob.js | 8 +- src/api/writeCommit.js | 2 +- src/api/writeObject.js | 2 +- src/api/writeTag.js | 2 +- src/api/writeTree.js | 2 +- src/commands/add.js | 49 ----- src/commands/addNote.js | 22 +- src/commands/addRemote.js | 2 +- src/commands/annotatedTag.js | 6 +- src/commands/branch.js | 2 +- src/commands/checkout.js | 31 ++- src/commands/clone.js | 31 ++- src/commands/commit.js | 4 +- src/commands/currentBranch.js | 2 +- src/commands/deleteBranch.js | 6 +- src/commands/deleteRef.js | 19 -- src/commands/deleteRemote.js | 2 +- src/commands/deleteTag.js | 6 +- src/commands/fetch.js | 8 +- src/commands/findMergeBase.js | 4 +- src/commands/findRoot.js | 4 +- src/commands/getConfig.js | 2 +- src/commands/getConfigAll.js | 2 +- src/commands/indexPack.js | 4 +- src/commands/init.js | 2 +- src/commands/isDescendent.js | 4 +- src/commands/listCommitsAndTags.js | 2 +- src/commands/listFiles.js | 6 +- src/commands/listNotes.js | 6 +- src/commands/listObjects.js | 2 +- src/commands/listRemotes.js | 2 +- src/commands/log.js | 8 +- src/commands/merge.js | 14 +- src/commands/pack.js | 4 +- src/commands/packObjects.js | 6 +- src/commands/pull.js | 22 +- src/commands/push.js | 18 +- src/commands/readBlob.js | 2 +- src/commands/readCommit.js | 2 +- src/commands/readNote.js | 6 +- src/commands/readTag.js | 4 +- src/commands/readTree.js | 2 +- src/commands/removeNote.js | 14 +- src/commands/setConfig.js | 25 --- src/commands/walk.js | 2 +- src/commands/writeBlob.js | 22 -- src/commands/writeCommit.js | 4 +- src/commands/writeTag.js | 4 +- src/commands/writeTree.js | 4 +- .../http.js => http/node/index.js} | 13 +- .../http.js => http/web/index.js} | 8 +- src/index.js | 194 +++++++++++++++++- src/managers/GitRemoteHTTP.js | 4 +- src/models/GitWalkerRepo.js | 2 +- src/storage/expandOid.js | 4 +- src/storage/hasObject.js | 2 +- src/storage/readObject.js | 4 +- src/storage/writeObject.js | 2 +- src/typedefs.js | 7 +- src/utils/mergeTree.js | 8 +- src/utils/normalizeAuthorObject.js | 6 +- src/utils/resolveBlob.js | 2 +- src/utils/resolveCommit.js | 2 +- src/utils/resolveFilepath.js | 2 +- src/utils/resolveTree.js | 2 +- tsconfig.json | 6 +- webpack.config.js | 6 +- 130 files changed, 759 insertions(+), 764 deletions(-) delete mode 100644 __tests__/test-GitObjectManager.js delete mode 100644 spec/support/jasmine.json delete mode 100644 src/api/_index.js delete mode 100644 src/commands/add.js delete mode 100644 src/commands/deleteRef.js delete mode 100644 src/commands/setConfig.js delete mode 100644 src/commands/writeBlob.js rename src/{builtin-node/http.js => http/node/index.js} (89%) rename src/{builtin-browser/http.js => http/web/index.js} (93%) diff --git a/.eslintignore b/.eslintignore index 53c37a166..cd6d12265 100644 --- a/.eslintignore +++ b/.eslintignore @@ -1 +1,14 @@ -dist \ No newline at end of file +/__tests__/__fixtures__ +/docs +/node_modules +/website + +# Build artifacts +/__tests__/__examples__ +/coverage +/http +/index.js +/internal-apis.js +/index.umd.min.js +/internal-apis.umd.min.js +/junit diff --git a/.gitignore b/.gitignore index f42c72768..b8d51bf7a 100644 --- a/.gitignore +++ b/.gitignore @@ -1,24 +1,37 @@ -__tests__/__fixtures__/.superblock.txt -__tests__/__fixtures__/index.json -dist -doc -junit -junit.xml -lib - +# stuff that gets generated during test setup +/__tests__/__fixtures__/.superblock.txt +/__tests__/__fixtures__/index.json + +# Dist +/http +/index.cjs +/index.d.ts +/index.js +/index.umd.min.js +/index.umd.min.js.map +/internal-apis.js +/internal-apis.d.ts +/internal-apis.cjs +/internal-apis.umd.min.js +/internal-apis.umd.min.js.map + +# Test run artifacts +/coverage +/junit +/browser-tests.json +/size_report.html +/__tests__/__examples__/** + +# PGP misc openpgp.store/ private.key -src/errors.d.ts - -lib/core/metadata.js -lib/core/MetadataBlog.js -website/build/ -website/node_modules -website/translated_docs -website/yarn.lock - -website/i18n/* +# Website Stuff +/website/build/ +/website/node_modules +/website/translated_docs +/website/yarn.lock +/website/i18n/* !website/i18n/en.json # Logs @@ -34,33 +47,8 @@ pids *.seed *.pid.lock -# Directory for instrumented libs generated by jscoverage/JSCover -lib-cov - -# Coverage directory used by tools like istanbul -coverage - -# nyc test coverage -.nyc_output - -# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) -.grunt - -# Bower dependency directory (https://bower.io/) -bower_components - -# node-waf configuration -.lock-wscript - -# Compiled binary addons (http://nodejs.org/api/addons.html) -build/Release - # Dependency directories node_modules -jspm_packages/ - -# Typescript v1 declaration files -typings/ # Optional npm cache directory .npm diff --git a/README.md b/README.md index 57ae05429..f411722ee 100644 --- a/README.md +++ b/README.md @@ -34,61 +34,72 @@ The following environments are tested in CI and will continue to be supported un ## 1.0 Breaking Changes -TODO: -- [ ] Rename `dist/http.js` to `dist/http-web.js` and `dist/http-web.cjs`, rename `dist/http.cjs` to `dist/http-node.js` and `dist/http-node.cjs` -- [ ] Rename `bundle.umd.min.js` to `index.umd.min.js`? -- [ ] Strongly consider lifting stuff out of `dist` so it's less to type. e.g. `import http from 'isomorphic-git/http-web'` -- [ ] Oooooooh I'm thinking about tweaking `onAuth` again. _Really_ all you need to do is update the `Authorization` header. But for future-proofing, updating _any_ header would be fun. And the `oauth2format` function could be moved to `@isomorphic-git/quirksmode` or something.... - ### Big changes -- [x] The supported node & browser versions have been bumped. (See beautiful table above.) -- [x] The plugin system has been eliminated and we're back to plain old dependency injection via function arguments! The plugin cores created a mysterious "global state" that makes it easy to trip up (I myself sometimes forgot to unset plugins after running tests). The old style of passing `fs` as a function argument was less aesthetic and more verbose, but it is a much simpler model than the plugin core model, and much safer because it makes it impossible for dependencies to accidentally share the default plugin core. -- [x] There is an additional setup step to choose which `http` client to use, and functions that make HTTP requests have a new required `http` parameter. Previously I used a mix of bundler and runtime magic to try and pick between a build that used `fetch` and one that used `require('http')` but that didn't always work. For instance, if you were bundling a Node application using Webpack, it would pick the wrong build [(#938)](https://github.com/isomorphic-git/isomorphic-git/issues/938). Another example: in an Electron renderer thread, _both_ options could work (if the window is launched with `nodeIntegration: true`) but in a Web Worker thread only the fetch option should work (_unless_ you have `nodeIntegrationInWorker: true` set). See "Getting Started" below to see the extra line of code you need. +- The supported node & browser versions have been bumped. (See beautiful table above.) +- The plugin system has been eliminated and we're back to plain old dependency injection via function arguments! The plugin cores created a mysterious "global state" that makes it easy to trip up (I myself sometimes forgot to unset plugins after running tests). The old style of passing `fs` as a function argument was less aesthetic and more verbose, but it is a much simpler model than the plugin core model, and much safer because it makes it impossible for dependencies to accidentally share the default plugin core. + - The `emitter` plugin has been replaced with `onMessage` and `onProgress` callbacks. + - The `credentialManager` plugin has been replaced with `onAuth`, `onAuthFailure` and `onAuthSuccess` callbacks + - The `fs` plugin has been replaced with an `fs` parameter. + - The `http` plugin has been replaced with an `http` parameter. + - The `pgp` plugin has been replaced with an `onSign` callback. +- There is an additional setup step to choose which `http` client to use, and functions that make HTTP requests have a new required `http` parameter. Previously I used a mix of bundler and runtime magic to try and pick between a build that used `fetch` and one that used `require('http')` but that didn't always work. For instance, if you were bundling a node application using Webpack, it would pick the wrong build [(#938)](https://github.com/isomorphic-git/isomorphic-git/issues/938). Another example: in an Electron renderer thread, _both_ options could work (if the window is launched with `nodeIntegration: true`) but in a Web Worker thread only the fetch option should work (_unless_ you have `nodeIntegrationInWorker: true` set). See "Getting Started" below to see the extra line of code you need. +- The files in the package have been renamed so the import paths are short and sweet: + - `dist/bundle.umd.min.js` -> `index.umd.min.js` + - `dist/for-future/isomorphic-git/index.js` -> `index.js` (the future has arrived) + - `dist/for-node/isomorphic-git/index.js` -> `index.cjs` ### Some functions have been renamed or removed: - - [x] The `walkBeta2` function was renamed to `walk`. - - [x] The `walkBeta1` function was removed. - - [x] The `fastCheckout` function has been renamed `checkout` and the old `checkout` has been removed. - - [x] The (previously deprecated) `sign` function was removed. - - [x] The (previously deprecated) `utils.auth` function was removed. - - [x] The (previously deprecated) `utils.oauth2` was removed. - - [x] The `config` function has been removed and replaced by `getConfig`, `getConfigAll`, and `setConfig`. - - [x] The `verify` function has been removed, but `log`, `readCommit`, and `readTag` all return the `gpgsig` and signing `payload` now. This actually makes verification simpler and more efficient, because it can be done in batch on `git.log` output and the `gpgsig` itself can be parsed and used to lookup the public key. See [onSign](https://isomorphic-git.org/docs/en/onSign) for complete code examples. +- The `walkBeta2` function was renamed to `walk`. +- The `walkBeta1` function was removed. +- The `fastCheckout` function has been renamed `checkout` and the old `checkout` has been removed. +- The (previously deprecated) `sign` function was removed. +- The (previously deprecated) `utils.auth` function was removed. +- The (previously deprecated) `utils.oauth2` was removed. +- The `config` function has been removed and replaced by `getConfig`, `getConfigAll`, and `setConfig`. +- The `verify` function has been removed, but `log`, `readCommit`, and `readTag` all return the `gpgsig` and signing `payload` now. This actually makes verification simpler and more efficient, because it can be done in batch on `git.log` output and the `gpgsig` itself can be parsed and used to lookup the public key. See [onSign](https://isomorphic-git.org/docs/en/onSign) for complete code examples. ### Some function parameters have been removed or replaced: - - [x] The undocumented parameter aliases `authUsername` and `authPassword` were removed. - - [x] The `emitter` parameter was removed and replaced with the `onMessage` and `onProgress` callbacks. (Note that `onMessage` emits un-trimmed strings, so you get those `\r`s.) - - [x] The `username`, `password`, `token`, and `oauth2format` parameters were removed and replaced with the `onAuth` callback. - - [x] The `fast` parameter of `pull` was removed, since there is no "slow" implementation anymore. - - [x] The `signing` parameter of `log` was removed, since `log` will always return a payload. - - [x] The `pattern` parameter was removed from `statusMatrix` and replaced with a new `filter` function. (This is so we can drop the dependencies on `globalyzer` and `globrex`.) - - [x] The `newSubmoduleBehavior` parameter was removed and is now the default and only behavior, because it makes much more sense to have non-destructive defaults! - - [x] The `noSubmodules` parameter was removed because with the new submodule behavior it is no longer necessary to print console warnings about how submodules aren't supported. (When submodule support IS added to isomorphic-git, it will be opt-in using `recurseSubmodules: true` or something like that.) - - [x] The `autoTranslateSSH` feature was removed, since it is trivial to implement your own version using just the `UnknownTransportError.data.suggestion` - - [x] The `writeObject` function when used to write a tree now expects a plain array rather than an object with a property called `entries` which is the array. (This is so that argument to `writeObject` has the same shame as the arguments to `writeBlob`/`writeCommit`/`writeTag`/`writeTree`.) - - [x] The `noOverwrite` parameter was removed from `init` and is the new behavior. - - [x] The `author.date`, `committer.date`, `tagger.date` parameters were removed in favor of `author.timestamp`, `comitter.timestamp`, `tagger.timestamp` in order to be clear about what is actually written and better reflect the return types in `readCommit`, `log`, and `readTag`. +- The undocumented parameter aliases `authUsername` and `authPassword` were removed. +- The `emitter` parameter was removed and replaced with the `onMessage` and `onProgress` callbacks. (Note that `onMessage` emits un-trimmed strings, so you get those `\r`s.) +- The `username`, `password`, `token`, and `oauth2format` parameters were removed and replaced with the `onAuth` callback. +- The `fast` parameter of `pull` was removed, since there is no "slow" implementation anymore. +- The `signing` parameter of `log` was removed, since `log` will always return a payload. +- The `pattern` parameter was removed from `statusMatrix` and replaced with a new `filter` function. (This is so we can drop the dependencies on `globalyzer` and `globrex`.) +- The `newSubmoduleBehavior` parameter was removed and is now the default and only behavior, because it makes much more sense to have non-destructive defaults! +- The `noSubmodules` parameter was removed because with the new submodule behavior it is no longer necessary to print console warnings about how submodules aren't supported. (When submodule support IS added to isomorphic-git, it will be opt-in using `recurseSubmodules: true` or something like that.) +- The `autoTranslateSSH` feature was removed, since it is trivial to implement your own version using just the `UnknownTransportError.data.suggestion` +- The `writeObject` function when used to write a tree now expects a plain array rather than an object with a property called `entries` which is the array. (This is so that argument to `writeObject` has the same shame as the arguments to `writeBlob`/`writeCommit`/`writeTag`/`writeTree`.) +- The `noOverwrite` parameter was removed from `init` and is the new behavior. +- The `author.date`, `committer.date`, `tagger.date` parameters were removed in favor of `author.timestamp`, `comitter.timestamp`, `tagger.timestamp` in order to be clear about what is actually written and better reflect the return types in `readCommit`, `log`, and `readTag`. ### The return types of some functions have changed: - - [x] Functions that used to return `Buffer` objects now return `Uint8Array` objects. (This is so we can eventually remove all internal dependencies on the Buffer browser polyfill, which is quite heavy!) - - [x] The `log` function now returns an array of the same kind of objects that `readCommit` returns. (This change simplifies the type signature of `log` so we don't need function overloading; that function overloading was the one thing preventing me from auto-generating `index.d.ts`.) - - [x] The `readObject` function returns a proper discriminated union so TypeScript can infer the type of `.object` once you establish the value of `.format` and `.type`. Also `.object` has the same shape as as the return value of `readBlob`/`readCommit`/`readTag`/`readTree`. (Meaning trees are now plain arrays rather than objects with a `.entries` property that is the array.) +- Functions that used to return `Buffer` objects now return `Uint8Array` objects. (This is so we can eventually remove all internal dependencies on the Buffer browser polyfill, which is quite heavy!) +- The `log` function now returns an array of the same kind of objects that `readCommit` returns. (This change simplifies the type signature of `log` so we don't need function overloading; that function overloading was the one thing preventing me from auto-generating `index.d.ts`.) +- The `readObject` function returns a proper discriminated union so TypeScript can infer the type of `.object` once you establish the value of `.format` and `.type`. Also `.object` has the same shape as as the return value of `readBlob`/`readCommit`/`readTag`/`readTree`. (Meaning trees are now plain arrays rather than objects with a `.entries` property that is the array.) -### Some functions behavior changed -- [x] The `push` function now pushes to the remote tracking branch (rather than a branch with the same name) by default. +### Some function behaviors have changed +- The `push` function now pushes to the remote tracking branch (rather than a branch with the same name) by default. ### Docs and DX improvements -- [x] The `docs/alphabetic.md` and function list in `README.md` are auto-generated from the filenames in `src/api`. -- [x] The entire docs website is auto-generated from the JSDoc actually so from now on the docs website and source code will always be in sync. -- [x] All the example code in JSDoc is now type-checked during CI tests. -- [x] The live code examples on the website are displayed in a full-blown mobile-friendly code editor (CodeMirror 6). -- [x] Each page with live code examples includes a code snippet at the bottom to reset the browser file system. -- [x] The Getting Started guide has been updated. -- [x] All the example code in JSDoc has been updated. +- The `docs/alphabetic.md` and function list in `README.md` are auto-generated from the filenames in `src/api`. +- Nearly the entire docs website is auto-generated from the JSDoc actually so keeping the docs website and source code in sync is easier. +- All the example code in JSDoc is now type-checked during CI tests. +- The live code examples on the website are displayed in a full-blown mobile-friendly code editor (CodeMirror 6). +- Each page with live code examples includes a code snippet at the bottom to reset the browser file system. +- The Getting Started guide has been updated. +- All the example code in JSDoc has been updated. ### Miscellaneous stuff -- [x] Update the README to recommend LightningFS rather than BrowserFS. -- [x] The `internal-apis` bundle is no longer included in the published package. Those were only exposed so I could run unit tests and no one should have been using them I hope. +- Update the README to recommend LightningFS rather than BrowserFS. +- The `internal-apis` bundle is no longer included in the published package. Those were only exposed so I could run unit tests and no one should have been using them I hope. + +## Install + +You can install it from npm: + +``` +npm install --save isomorphic-git +``` ## Getting Started @@ -99,13 +110,13 @@ And node and browsers have different APIs for making HTTP requests! So rather than relying on the `fs` and `http` modules, `isomorphic-git` lets you bring your own file system and HTTP client. -If you're using `isomorphic-git` in Node, you use the native `fs` module and the include Node HTTP client. +If you're using `isomorphic-git` in node, you use the native `fs` module and the provided node HTTP client. ```js // node.js example const path = require('path') const git = require('isomorphic-git'); -const http = require('isomorphic-git/dist/http.cjs') // NOTE THE FILE EXTENSION IS .cjs +const http = require('isomorphic-git/http/node') const fs = require('fs'); const dir = path.join(process.cwd(), 'test-clone') @@ -115,12 +126,13 @@ git.clone({ fs, http, dir, url: 'https://github.com/isomorphic-git/lightning-fs' If you're using `isomorphic-git` in the browser, you'll need something that emulates the `fs` API. The easiest to setup and most performant library is [LightningFS](https://github.com/isomorphic-git/lightning-fs) which is written and maintained by the same author and is part of the `isomorphic-git` suite. If LightningFS doesn't meet your requirements, isomorphic-git should also work with [BrowserFS](https://github.com/jvilk/BrowserFS) and [Filer](https://github.com/filerjs/filer). +Instead of `isomorphic-git/http/node` this time import `isomorphic-git/http/web`: ```html