bare-module 3.1.4 → 3.1.6

package/README.md

@@ -12,14 +12,179 @@ npm i bare-module
 const Module = require('bare-module')
 ````
 
+## Packages
+
+A package is directory with a `package.json` file.
+
+### Fields
+
+#### `"name"`
+
+```json
+{
+  "name": "my-package"
+}
+```
+
+The name of the package. This is used for [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm), [self-referencing](#self-referencing), and importing packages by name.
+
+#### `"version"`
+
+```json
+{
+  "version": "1.2.3"
+}
+```
+
+The current version of the package. This is used for [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm).
+
+#### `"type"`
+
+```json
+{
+  "type": "module"
+}
+```
+
+The module format used for `.js` files. If not defined, `.js` files are interpreted as CommonJS. If set to `"module"`, `.js` files are instead interpreted as ES modules.
+
+#### `"exports"`
+
+```json
+{
+  "exports": {
+    ".": "./index.js"
+  }
+}
+```
+
+The entry points of the package. If defined, only the modules explicitly exported by the package may be imported when importing the package by name.
+
+##### Subpath exports
+
+A package may define more than one entry point by declaring several subpaths with the main export being `"."`:
+
+```json
+{
+  "exports": {
+    ".": "./index.js",
+    "./submodule": "./lib/submodule.js"
+  }
+}
+```
+
+When importing the package by name, `require('my-package')` will resolve to `<modules>/my-package/index.js` whereas `require('my-package/submodule')` will resolve to `<modules>/my-package/lib/submodule.js`.
+
+##### Conditional exports
+
+Conditional exports allow packages to provide different exports depending for different conditions, such as the module format of the importing module:
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.cjs"
+    }
+  }
+}
+```
+
+When importing the package by name, `require('my-package')` will resolve to `<modules>/my-package/index.cjs` whereas `import 'my-package'` will resolve to `<modules>/my-package/index.mjs`.
+
+Similarly, conditional exports can be used to provide different entry points for different runtimes:
+
+```json
+{
+  "exports": {
+    ".": {
+      "bare": "./bare.js",
+      "node": "./node.js"
+    }
+  }
+}
+```
+
+To provide a fallback for when no other conditions match, the `"default"` condition can be declared:
+
+```json
+{
+  "exports": {
+    ".": {
+      "bare": "./bare.js",
+      "node": "./node.js",
+      "default": "./fallback.js"
+    }
+  }
+}
+```
+
+The following conditions are supported, listed in order from most specific to least specific as conditions should be defined:
+
+Condition | Description
+:-- | :--
+`"bare"` |
+`"node"` |
+`"import"` |
+`"require"` |
+`"default"` |
+
+##### Self-referencing
+
+Within a package, exports defined in the `"exports"` field can be referenced by importing the package by name. For example, given the following `package.json`...
+
+```json
+{
+  "name": "my-package",
+  "exports": {
+    ".": "./index.js",
+    "./submodule": "./lib/submodule.js"
+  }
+}
+```
+
+...any module within `my-package` may reference these entry points using either `require('my-package')` or `require('my-package/submodule')`.
+
+##### Exports sugar
+
+If a package defines only a single export, `"."`, it may leave out the subpath entirely:
+
+```json
+{
+  "exports": "./index.js"
+}
+```
+
+#### `"imports"`
+
+##### Subpath imports
+
+##### Conditional imports
+
+##### Private imports
+
 ## API
 
 #### `Module.constants`
 
 #### `Module.constants.states`
 
+Constant | Description
+:-- | :--
+`EVALUATED` |
+`SYNTHESIZED` |
+`DESTROYED` |
+
 #### `Module.constants.types`
 
+Constant | Description
+:-- | :--
+`SCRIPT` |
+`MODULE` |
+`JSON` |
+`BUNDLE` |
+`ADDON` |
+
 #### `Module.cache`
 
 #### `const url = Module.resolve(specifier, parentURL[, options])`
@@ -28,6 +193,12 @@ Options include:
 
 ```js
 {
+  referrer = null,
+  protocol,
+  imports,
+  resolutions,
+  builtins,
+  conditions
 }
 ```
 
@@ -37,6 +208,16 @@ Options include:
 
 ```js
 {
+  referrer = null,
+  type,
+  defaultType = constants.types.SCRIPT,
+  cache,
+  main,
+  protocol,
+  imports,
+  resolutions,
+  builtins,
+  conditions
 }
 ```
 
@@ -50,12 +231,16 @@ Options include:
 
 #### `module.defaultType`
 
+#### `module.cache`
+
 #### `module.main`
 
 #### `module.exports`
 
 #### `module.imports`
 
+#### `module.resolutions`
+
 #### `module.builtins`
 
 #### `module.conditions`
@@ -68,6 +253,23 @@ Options include:
 
 #### `const require = Module.createRequire(parentURL[, options])`
 
+Options include:
+
+```js
+{
+  referrer = null,
+  type = constants.types.SCRIPT,
+  defaultType = constants.types.SCRIPT,
+  cache,
+  main,
+  protocol,
+  imports,
+  resolutions,
+  builtins,
+  conditions
+}
+```
+
 ### Protocols
 
 #### `const protocol = new Module.Protocol(options)`
@@ -76,6 +278,12 @@ Options include:
 
 ```js
 {
+  preresolve,
+  postresolve,
+  resolve,
+  exists,
+  read,
+  load
 }
 ```
 
@@ -83,6 +291,8 @@ Options include:
 
 #### `const bundle = new Module.Bundle()`
 
+See <https://github.com/holepunchto/bare-bundle>.
+
 ## License
 
 Apache-2.0

package/index.js

@@ -1,13 +1,15 @@
 /* global Bare */
 const path = require('bare-path')
-const url = require('bare-url')
 const resolve = require('bare-module-resolve')
 const Bundle = require('bare-bundle')
+const { fileURLToPath, pathToFileURL } = require('url-file-url')
 const Protocol = require('./lib/protocol')
 const constants = require('./lib/constants')
 const errors = require('./lib/errors')
 const binding = require('./binding')
 
+const isWindows = Bare.platform === 'win32'
+
 const { startsWithWindowsDriveLetter } = resolve
 
 const Module = module.exports = exports = class Module {
@@ -544,14 +546,12 @@ Module._extensions['.cjs'] = function (module, source, referrer) {
 
     module._exports = {}
 
-    const filename = urlToPath(module._url)
-
     binding.createFunction(module._url.href, ['require', 'module', 'exports', '__filename', '__dirname'], source, 0)(
       require,
       module,
       module._exports,
-      filename,
-      path.dirname(filename)
+      urlToPath(module._url),
+      urlToDirname(module._url)
     )
 
     function require (specifier) {
@@ -665,16 +665,16 @@ Module._extensions['.bundle'] = function (module, source, referrer) {
 }
 
 Module._protocols['file:'] = new Protocol({
-  postresolve (fileURL) {
-    return url.pathToFileURL(binding.realpath(url.fileURLToPath(fileURL)))
+  postresolve (url) {
+    return pathToFileURL(binding.realpath(fileURLToPath(url)))
   },
 
-  exists (fileURL) {
-    return binding.exists(url.fileURLToPath(fileURL))
+  exists (url) {
+    return binding.exists(fileURLToPath(url))
   },
 
-  read (fileURL) {
-    return Buffer.from(binding.read(url.fileURLToPath(fileURL)))
+  read (url) {
+    return Buffer.from(binding.read(fileURLToPath(url)))
   }
 })
 
@@ -687,14 +687,34 @@ Bare
     binding.destroy(Module._handle)
   })
 
-function urlToPath (u) {
-  return u.protocol === 'file:'
-    ? url.fileURLToPath(u)
-    : decodeURIComponent(u.pathname)
+function urlToPath (url) {
+  if (url.protocol === 'file:') return fileURLToPath(url)
+
+  if (isWindows) {
+    if (/%2f|%5c/i.test(url.pathname)) {
+      throw errors.INVALID_URL_PATH('The URL path must not include encoded \\ or / characters')
+    }
+  } else {
+    if (/%2f/i.test(url.pathname)) {
+      throw errors.INVALID_URL_PATH('The URL path must not include encoded / characters')
+    }
+  }
+
+  return decodeURIComponent(url.pathname)
 }
 
-function urlToDirname (u) {
-  return u.protocol === 'file:'
-    ? path.dirname(url.fileURLToPath(u))
-    : decodeURIComponent((new URL('.', u)).pathname).replace(/\/$/, '')
+function urlToDirname (url) {
+  if (url.protocol === 'file:') return path.dirname(fileURLToPath(url))
+
+  if (isWindows) {
+    if (/%2f|%5c/i.test(url.pathname)) {
+      throw errors.INVALID_URL_PATH('The URL path must not include encoded \\ or / characters')
+    }
+  } else {
+    if (/%2f/i.test(url.pathname)) {
+      throw errors.INVALID_URL_PATH('The URL path must not include encoded / characters')
+    }
+  }
+
+  return decodeURIComponent((new URL('.', url)).pathname).replace(/\/$/, '')
 }

package/lib/errors.js

@@ -23,4 +23,8 @@ module.exports = class ModuleError extends Error {
   static INVALID_BUNDLE_EXTENSION (msg) {
     return new ModuleError(msg, 'INVALID_BUNDLE_EXTENSION', ModuleError.INVALID_BUNDLE_EXTENSION)
   }
+
+  static INVALID_URL_PATH (msg) {
+    return new ModuleError(msg, 'INVALID_URL_PATH', ModuleError.INVALID_URL_PATH)
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-module",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "description": "Module support for JavaScript",
   "main": "index.js",
   "files": [
@@ -29,7 +29,7 @@
     "bare-bundle": "^1.0.0",
     "bare-module-resolve": "^1.4.4",
     "bare-path": "^2.0.0",
-    "bare-url": "^1.0.0"
+    "url-file-url": "^1.0.2"
   },
   "devDependencies": {
     "brittle": "^3.1.1",