Version 1.0.0

.clang-format

@@ -0,0 +1,12 @@
+BasedOnStyle: Google
+AlignAfterOpenBracket: AlwaysBreak
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: None
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+BinPackArguments: false
+# This breaks async functions sometimes, see
+#     https://github.com/Polymer/polymer-analyzer/pull/393
+# BinPackParameters: false

.gitignore

@@ -0,0 +1,3 @@
+node_modules
+lib
+*.tgz

.travis.yml

@@ -0,0 +1,10 @@
+language: node_js
+node_js:
+  - "node"
+dist: xenial
+cache:
+  directories:
+    - node_modules
+script:
+  - npm run build
+  - npm test

CHANGELOG.md

@@ -0,0 +1,16 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+<!--
+   PRs should document their user-visible changes (if any) in the
+   Unreleased section, uncommenting the header as necessary.
+-->
+
+## Unreleased
+
+- Rewrites resolvable Node package specifiers in JavaScript module files.
+- Rewrites resolvable Node package specifiers in HTML files in `<script type="module">` elements, honoring `<base href>` where present.

LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2019 The Polymer Authors. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,2 +1,73 @@
-# koa-npm-resolution
-Koa middleware that transforms NPM package specifiers to relative paths
+# koa-node-resolve
+
+Middleware for Koa servers that resolves Node package specifiers in standard JS modules to relative paths for use on the web.
+
+The following import uses a _bare module specifier_, which won't currently load natively in browsers (until [import maps](https://www.chromestatus.com/feature/5315286962012160) are available):
+
+```js
+import { foo } from "stuff";
+```
+
+`koa-node-resolve` solves this problem by resolving `stuff` using the same rules as [Node `require()`](https://nodejs.org/api/modules.html#modules_all_together), and transforming the import specifier to a path that can be loaded natively by any browser that [supports](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Browser_compatibility) standard JS modules:
+
+```js
+import { foo } from "./node_modules/stuff/index.js";
+```
+
+Because this is middleware, you can use it in a simple static file server as well as a proxy server sitting in front of a test server such as the one `karma` starts up. (See [karma testing setup](#karma-testing-setup) below.)
+
+Note: HTML and JavaScript are parsed on every request for those content-types, it is intended for use in development context to facilitate build-free testing/iteration as opposed to in a high volume production web server.
+
+## Installation
+
+```sh
+$ npm install --save koa-node-resolve
+```
+
+## Usage
+
+Create your own mini-development server in file `./dev-server.js`. This one depends on `koa` and `koa-static`, so you'll need to `npm install --save-dev koa koa-static` for your project to use it.
+
+```js
+const Koa = require("koa");
+const server = new Koa()
+  .use(require("koa-node-resolve").middleware())
+  .use(require("koa-static")("."))
+  .listen(3000);
+```
+
+```sh
+$ node dev-server.js
+```
+
+Now you can serve up your web assets and Node package specifiers will be transformed on request.
+
+## Karma Testing Setup
+
+In a `karma` setup, your `karma.conf.js` file could create the Koa server before exporting the config. The Koa server uses the `koa-proxy` package (therefore `npm install --save-dev koa-proxy`) in between the browser and the Karma server, transforming all the Node package specifiers encountered in documents located under the `base/` URL namespace, which is a special Karma behavior for partitioning the package resources under test from Karma support resources.
+
+```js
+const Koa = require("koa");
+const server = new Koa()
+  .use(require("koa-mount")("/base", require("koa-node-resolve").middleware()))
+  .use(require("koa-proxy")({ host: "http://127.0.0.1:9876" }))
+  .listen(9877);
+
+module.exports = config => {
+  config.set({
+    upstreamProxy: {
+      hostname: "127.0.0.1",
+      port: 9877,
+    },
+    files: [
+      { pattern: "test/**/*.js", type: "module" },
+      { pattern: "**/*.js", included: false },
+      { pattern: "node_modules/**/*", included: false },
+    ],
+  });
+};
+```
+
+In this setup, the Koa proxy server that runs the Node resolution middleware will be on port 9877 and the Karma server will be on port 9876, so be sure to open up `http://127.0.0.1:9877` in your browser rather than `http://127.0.0.1:9876`. The `upstreamProxy` configuration block tells Karma, when it launches browsers, to points them to the Koa app instead of directly to the Karma server.
+
+Note also that in this configuration its important to tell Karma that the test files are modules and to serve those up, but to list the other files, like the ones in `node_modules` as available but not "included" (i.e. Karma can serve them by request, but shouldn't add inline dependencies on them when generating its "context" HTML).