bare-module 4.7.1 → 4.8.1

package/README.md

@@ -458,6 +458,112 @@ The `ModuleProtocol` class used for resolving, reading and loading modules. See
 
 Unloads the module.
 
+### CommonJS modules
+
+#### `require(specifier[, options])`
+
+Used to import JavaScript or JSON modules and local files. Relative paths such as `./`, `./foo`, `./bar/baz`, and `../foo` will be resolved against the directory named by `__dirname`. POSIX style paths are resolved in an OS independent fashion, meaning that the examples above will work on Windows in the same way they would on POSIX systems.
+
+Returns the exported module contents.
+
+Options include:
+
+```js
+options = {
+  // The import attributes which instruct how the file or module should be loaded.
+  // Possible values for `type` are `script`, `module`, `json`, `bundle`,
+  // `addon`, `binary` and `text`.
+  with: { type: 'json' }
+}
+```
+
+#### `require.main`
+
+The module representing the entry script where the program was launched. The same value as [`module.main`](#modulemain) for the current module.
+
+#### `require.cache`
+
+A cache of loaded modules for this module. The same value as `module.cache` for the current module.
+
+#### `const path = require.resolve(specifier[, parentURL])`
+
+Use the internal machinery of `require()` to resolve the `specifier` string relative to the URL `parentURL` and return the path string.
+
+#### `require.addon([specifier][, parentURL])`
+
+Also used to import modules but specifically loads only addon modules. `specifier` is resolved relative to `parentURL` using the [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm) algorithm.
+
+Returns the exported module contents.
+
+A common pattern for writing an addon module is to use `require.addon()` as the JavaScript module exports:
+
+```js
+module.exports = require.addon()
+```
+
+See [`bare-addon`](https://github.com/holepunchto/bare-addon) for a template of building native addon modules.
+
+#### `require.addon.host`
+
+Returns the string representation of the platform and architecture used when resolving addons with the pattern `<platform>-<arch>[-simulator]`. Returns the same value as `Bare.Addon.host`.
+
+#### `const path = require.addon.resolve([specifier][, parentURL])`
+
+Resolve the `specifier` string relative to the URL `parentURL` as an addon and returns the path string. The `specifier` is resolved using the [addon resolution algorithm](https://github.com/holepunchto/bare-addon-resolve#algorithm).
+
+#### `const path = require.asset(specifier[, parentURL])`
+
+Resolve the `specifier` relative to the `parentURL` and return the path of the asset as a string.
+
+Can be used to load assets, for example the following loads `./foo.txt` from the local files:
+
+```js
+const fs = require('bare-fs')
+const contents = fs.readFileSync(require.asset('./foo.txt'))
+```
+
+### ECMAScript modules
+
+#### `import defaultExport, * as name, { export1, export2 as alias2, ... } from 'specifier' with { type: 'json' }`
+
+The static `import` declaration is used to import read-only live bindings that are exported by another module. The imported bindings are called _live_ bindings because they are updated by the module that exported the binding, but cannot be re-assigned by the importing module. In brief, you can import what is exported from another module.
+
+For more information on `import` syntax, see [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).
+
+#### `import.meta.url`
+
+The string representation of the URL for the current module.
+
+#### `import.meta.main`
+
+A boolean representing whether the current module is the entry script where the program was launched.
+
+#### `import.meta.cache`
+
+A cache of loaded modules for this module. The same value as `module.cache` for the current module.
+
+#### `const href = import.meta.resolve(specifier[, parentURL])`
+
+A module-relative resolution function which returns the URL string for the module. The `specifier` is a string which is resolved relative to the `parentURL` which is a WHATWG URL.
+
+#### `import.meta.addon([specifier][, parentURL])`
+
+Also used to import modules but specifically loads only addon modules. `specifier` is resolved relative to `parentURL` using the [addon resolution](https://github.com/holepunchto/bare-addon-resolve#algorithm) algorithm.
+
+Returns the exported module contents.
+
+#### `import.meta.addon.host`
+
+Returns the string representation of the platform and architecture used when resolving addons with the pattern `<platform>-<arch>[-simulator]`. Returns the same value as `Bare.Addon.host`.
+
+#### `const href = import.meta.addon.resolve([specifier][, parentURL])`
+
+Resolve the `specifier` string relative to the URL `parentURL` as an addon and returns the URL string. The `specifier` is resolved using the [addon resolution algorithm](https://github.com/holepunchto/bare-addon-resolve#algorithm).
+
+#### `const href = import.meta.asset(specifier[, parentURL])`
+
+Resolve the `specifier` relative to the `parentURL` and return the URL of the asset as a string.
+
 ### Custom `require()`
 
 Creating a custom require allows one to create a preconfigured `require()`. This can be useful in scenarios such as a Read-Evaluate-Print-Loop (REPL) where the parent URL is set to a directory so requiring relative paths to work correctly.

package/binding.c

@@ -529,25 +529,29 @@ bare_module_exists(js_env_t *env, js_callback_info_t *info) {
   err = js_get_env_loop(env, &loop);
   assert(err == 0);
 
-  js_value_t *argv[1];
-  size_t argc = 1;
+  js_value_t *argv[2];
+  size_t argc = 2;
 
   err = js_get_callback_info(env, info, &argc, argv, NULL, NULL);
   assert(err == 0);
 
-  assert(argc == 1);
+  assert(argc == 2);
 
   utf8_t path[4096];
   err = js_get_value_string_utf8(env, argv[0], path, 4096, NULL);
   assert(err == 0);
 
+  uint32_t mode;
+  err = js_get_value_uint32(env, argv[1], &mode);
+  assert(err == 0);
+
   uv_fs_t req;
   uv_fs_stat(loop, &req, (char *) path, NULL);
 
   uv_stat_t *st = req.result < 0 ? NULL : req.ptr;
 
   js_value_t *result;
-  err = js_get_boolean(env, st && st->st_mode & S_IFREG, &result);
+  err = js_get_boolean(env, st && st->st_mode & mode, &result);
   assert(err == 0);
 
   uv_fs_req_cleanup(&req);
@@ -707,6 +711,19 @@ bare_module_exports(js_env_t *env, js_value_t *exports) {
   V("read", bare_module_read)
 #undef V
 
+#define V(name, n) \
+  { \
+    js_value_t *val; \
+    err = js_create_uint32(env, n, &val); \
+    assert(err == 0); \
+    err = js_set_named_property(env, exports, name, val); \
+    assert(err == 0); \
+  }
+
+  V("FILE", S_IFREG)
+  V("DIR", S_IFDIR)
+#undef V
+
   return exports;
 }
 

package/index.d.ts

@@ -0,0 +1,127 @@
+import Buffer from 'bare-buffer'
+import URL from 'bare-url'
+import Bundle from 'bare-bundle'
+import {
+  type Builtins,
+  type Conditions,
+  type ImportsMap,
+  type ResolutionsMap
+} from 'bare-module-resolve'
+import Protocol from './lib/protocol'
+import constants from './lib/constants'
+
+interface Cache {
+  [href: string]: Module
+}
+
+interface Attributes {
+  type: Lowercase<keyof typeof constants.types>
+}
+
+interface Options {
+  attributes?: Attributes
+  builtins?: Builtins
+  cache?: Cache
+  conditions?: Conditions
+  defaultType?: number
+  imports?: ImportsMap
+  main?: Module
+  protocol?: Protocol
+  referrer?: Module
+  resolutions?: ResolutionsMap
+  type?: number
+}
+
+interface LoadOptions extends Options {
+  isDynamicImport?: boolean
+  isImport?: boolean
+}
+
+interface ResolveOptions extends Options {
+  isImport?: boolean
+}
+
+interface Module {
+  readonly builtins: Builtins
+  readonly cache: Cache
+  readonly conditions: Conditions
+  readonly defaultType: number
+  readonly dirname: string
+  exports: unknown
+  readonly filename: string
+  readonly id: string
+  readonly imports: ImportsMap
+  readonly main: Module
+  readonly path: string
+  readonly protocol: Protocol
+  readonly resolutions: ResolutionsMap
+  readonly type: number
+  readonly url: URL
+
+  destroy(): void
+}
+
+declare class Module {
+  static readonly protocol: Protocol
+  static readonly cache: Cache
+
+  static load(url: URL, opts: LoadOptions): Module
+  static load(
+    url: URL,
+    source?: Buffer | string | Bundle | null,
+    opts?: LoadOptions
+  ): Module
+
+  static resolve(specifier: string, parentURL: URL, opts?: ResolveOptions): URL
+
+  static asset(specifier: string, parentURL: URL, opts?: Options): URL
+
+  constructor(url: URL)
+}
+
+declare namespace Module {
+  export {
+    type Attributes,
+    type Cache,
+    type Options,
+    type LoadOptions,
+    type ResolveOptions,
+    Protocol,
+    Bundle,
+    constants
+  }
+
+  export const builtinModules: Module[]
+
+  export function isBuiltin(): boolean
+
+  export interface CreateRequireOptions extends Options {
+    module?: Module
+  }
+
+  export interface RequireOptions {
+    with?: Attributes
+  }
+
+  export interface RequireAddon {
+    (specifier?: string, parentURL?: URL): string
+    host: string
+    resolve: (specifier: string, parentURL?: URL) => unknown
+  }
+
+  export interface Require {
+    (parentURL: string | URL, opts?: RequireOptions): unknown
+    main: Module
+    cache: Cache
+    resolve: (specifier: string, parentURL?: URL) => string
+    addon: RequireAddon
+    asset: (specifier: string, parentURL?: URL) => string
+  }
+
+  export function createRequire(
+    parentURL: string | URL,
+    opts?: CreateRequireOptions
+  ): Require
+}
+
+export = Module

package/index.js

@@ -390,6 +390,7 @@ module.exports = exports = class Module {
 
     if (
       !ArrayBuffer.isView(source) &&
+      !Bundle.isBundle(source) &&
       typeof source !== 'string' &&
       source !== null
     ) {
@@ -448,9 +449,11 @@ module.exports = exports = class Module {
             canonicalExtensionForType(type) || path.extname(url.pathname)
 
           if (extension in self._extensions === false) {
-            if (defaultType)
+            if (defaultType) {
               extension = canonicalExtensionForType(defaultType) || '.js'
-            else extension = '.js'
+            } else {
+              extension = '.js'
+            }
           }
 
           self._extensions[extension](module, source, referrer)
@@ -513,7 +516,7 @@ module.exports = exports = class Module {
         case 'builtin:':
           return resolution
         default:
-          if (protocol.exists(resolution)) {
+          if (protocol.exists(resolution, type)) {
             return protocol.postresolve(resolution)
           }
       }
@@ -524,7 +527,7 @@ module.exports = exports = class Module {
     )
 
     function readPackage(packageURL) {
-      if (protocol.exists(packageURL)) {
+      if (protocol.exists(packageURL, constants.types.JSON)) {
         return Module.load(packageURL, { protocol })._exports
       }
 
@@ -566,7 +569,7 @@ module.exports = exports = class Module {
       },
       readPackage
     )) {
-      if (protocol.exists(resolution)) {
+      if (protocol.exists(resolution, constants.types.ASSET)) {
         return protocol.postresolve(
           protocol.asset ? protocol.asset(resolution) : resolution
         )
@@ -578,7 +581,7 @@ module.exports = exports = class Module {
     )
 
     function readPackage(packageURL) {
-      if (protocol.exists(packageURL)) {
+      if (protocol.exists(packageURL, constants.types.JSON)) {
         return Module.load(packageURL, { protocol })._exports
       }
 
@@ -799,7 +802,7 @@ Module._extensions['.js'] = function (module, source, referrer) {
       break
     }
 
-    if (protocol.exists(packageURL)) {
+    if (protocol.exists(packageURL, constants.types.JSON)) {
       pkg = self.load(packageURL, { protocol })
       break
     }
@@ -905,10 +908,9 @@ Module._extensions['.bundle'] = function (module, source, referrer) {
 
   referrer = module
 
-  const bundle = (module._bundle = Bundle.from(source).mount(
-    module._url.href + '/'
-  ))
+  const bundle = Bundle.from(source).mount(module._url.href + '/')
 
+  module._bundle = bundle
   module._imports = bundle.imports
   module._resolutions = bundle.resolutions
 
@@ -969,10 +971,15 @@ Module._protocol = new Protocol({
     }
   },
 
-  exists(url) {
+  exists(url, type = 0) {
     switch (url.protocol) {
       case 'file:':
-        return binding.exists(fileURLToPath(url))
+        return binding.exists(
+          fileURLToPath(url),
+          type === constants.types.ASSET
+            ? binding.FILE | binding.DIR
+            : binding.FILE
+        )
       default:
         return false
     }

package/lib/constants.d.ts

@@ -0,0 +1,19 @@
+declare const constants: {
+  states: {
+    EVALUATED: number
+    SYNTHESIZED: number
+    DESTROYED: number
+  }
+  types: {
+    SCRIPT: number
+    MODULE: number
+    JSON: number
+    BUNDLE: number
+    ADDON: number
+    BINARY: number
+    TEXT: number
+    ASSET: number
+  }
+}
+
+export = constants

package/lib/constants.js

@@ -12,6 +12,7 @@ module.exports = {
     BUNDLE: 4,
     ADDON: 5,
     BINARY: 6,
-    TEXT: 7
+    TEXT: 7,
+    ASSET: 8
   }
 }

package/lib/protocol.d.ts

@@ -0,0 +1,27 @@
+import URL from 'bare-url'
+import Buffer from 'bare-buffer'
+import { type ImportsMap } from 'bare-module-resolve'
+
+interface ModuleProtocol {
+  preresolve(specifier: string, parentURL: URL): string
+
+  postresolve(url: URL): URL
+
+  resolve(specifier: string, parentURL: URL, imports: ImportsMap): URL
+
+  exists(url: URL, type: number): boolean
+
+  read(url: URL): Buffer | string | null
+
+  addon(url: URL): URL
+
+  asset(url: URL): URL
+
+  extend(methods: Partial<ModuleProtocol>): ModuleProtocol
+}
+
+declare class ModuleProtocol {
+  constructor(methods?: Partial<ModuleProtocol>, context?: ModuleProtocol)
+}
+
+export = ModuleProtocol

package/lib/protocol.js

@@ -34,7 +34,7 @@ module.exports = class ModuleProtocol {
 
   *resolve(specifier, parentURL, imports) {}
 
-  exists(url) {
+  exists(url, type) {
     return false
   }
 

package/package.json

@@ -1,10 +1,17 @@
 {
   "name": "bare-module",
-  "version": "4.7.1",
+  "version": "4.8.1",
   "description": "Module support for JavaScript",
-  "main": "index.js",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package": "./package.json"
+  },
   "files": [
     "index.js",
+    "index.d.ts",
     "binding.c",
     "binding.js",
     "CMakeLists.txt",
@@ -33,9 +40,18 @@
     "bare-url": "^2.0.1"
   },
   "devDependencies": {
+    "bare-buffer": "^3.0.2",
     "brittle": "^3.1.1",
     "cmake-bare": "^1.1.6",
     "prettier": "^3.3.3",
     "prettier-config-standard": "^7.0.0"
+  },
+  "peerDependencies": {
+    "bare-buffer": "*"
+  },
+  "peerDependenciesMeta": {
+    "bare-buffer": {
+      "optional": true
+    }
   }
 }