FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

esm: fix hook mistypes and links to types · nodejs/node@44e6c01 · GitHub

/ node Public

Commit 44e6c01

Browse files
Derek Lewis
authored and
codebytere
committed
esm: fix hook mistypes and links to types
Prior to this commit, the custom loader hooks were: * missing the Node.js API ref docs types * missing the function signature from their sections * linking directly to the specification (not customary) * had an inconsistent non-nullable JSDoc promise return * had JSDoc object properties that weren't alpha-sorted * designated set of non-nullable types when single was fine Notes: https://www.typescriptlang.org/play/index.html?strictNullChecks=true&useJavaScript=true#code/PQKhCgAIUgBAHAhgJ0QW0gbwM4BdkCWAdgOYC+k28ApgMYEBmB1yUMCK6WmbkftAeyIATArgJDsALkgBCAILJUATwA8eQqQB8AGl58kyakVwBVAEoAZGbIAUG4iUgAfSAFcR1JkWrCAlHrQkGQUgibUAB64vByoGJgAYh604kIUwl6IbgA2uObU2ALZAG7UMUa4bshE2FgACsgCaATY1KqY7sjZMg6kwVpkbMDgkfACyLiQiNjKRLSQDMmpRJBGhSXU9jT0TCw6kGG4kbj7GQxZufnrpX5YUAeSkx2GxmZWkAC8kEQ52cGfD3CUQA3PdGJBbABZRC4AAWADpUCImrZblpIAAGeEAVluHWAwEgAGUmtRAaJlvD7nwCZAEuNKKTIAzENk-lQ6IxmMhsKcBIy0GTaG48E1INkBCQCPMGAy1kVio4qXwaYT5NkAO6IZS1CpVFaIFYCABGACs6JMBAxIHCybLkPEqt1IOp8I4BsqVXrqncVSqnTIXiYLJZIAB+al+77UDWQENbTm7ZD7INvSx+eGwozWqSRv0+WPxjk7bkZrNeQIqsigviDPjgqEwhFI4Qo26qTE4vGQWnyIgCW3IcliCRET2qyAAdVhxgOrOyjkgAAMzhc8gUFdQl-tbVNkCQ3IKTLVaIbIMayWgBKJdsJ4ZAAJIrOEtSO00+tSBiADktUQwlEPpDQHGch2KVk3DtBk0BhWhYUXMIKVHVlIFGcZcGwcdVmoSofVXHJ12uTZiy5PZfSjeFKMOY5Kz9RCR0kGQAG1KPhaiojYoQkMkfZv2AwcAFp6OWb8AF1aOCPwa2Ce5aQAES8FgbX5AA5a9qHhU1antKY2WZQdKG2UieU9b0Vnwy4Nw2BMSzI9iTkgCzCM3KTwDIIA https://closure-compiler.appspot.com/home#code%3D%252F%252F%2520%253D%253DClosureCompiler%253D%253D%250A%252F%252F%2520%2540compilation_level%2520ADVANCED_OPTIMIZATIONS%250A%252F%252F%2520%2540warning_level%2520VERBOSE%250A%252F%252F%2520%2540jscomp_error%2520strictCheckTypes%250A%252F%252F%2520%2540language_out%2520ECMASCRIPT_NEXT%250A%252F%252F%2520%2540checks_only%250A%252F%252F%2520%253D%253D%252FClosureCompiler%253D%253D%250A%250A%252F**%250A%2520*%2520%2540param%2520%257Bstring%257D%2520specifier%250A%2520*%2520%2540param%2520%257B%257B%250A%2520*%2520%2520%2520conditions%253A%2520!Array%253Cstring%253E%252C%250A%2520*%2520%2520%2520parentURL%253A%2520!(string%2520%257C%2520undefined)%252C%250A%2520*%2520%257D%257D%2520context%250A%2520*%2520%2540param%2520%257BFunction%257D%2520defaultResolve%250A%2520*%2520%2540returns%2520%257BPromise%253C%257B%2520url%253A%2520string%2520%257D%253E%257D%250A%2520*%252F%250Aexport%2520async%2520function%2520resolve(specifier%252C%2520context%252C%2520defaultResolve)%2520%257B%250A%2520%2520const%2520%257B%2520parentURL%2520%253D%2520null%2520%257D%2520%253D%2520context%253B%250A%2520%2520if%2520(Math.random()%2520%253E%25200.5)%2520%257B%2520%252F%252F%2520Some%2520condition.%250A%2520%2520%2520%2520%252F%252F%2520For%2520some%2520or%2520all%2520specifiers%252C%2520do%2520some%2520custom%2520logic%2520for%2520resolving.%250A%2520%2520%2520%2520%252F%252F%2520Always%2520return%2520an%2520object%2520of%2520the%2520form%2520%257Burl%253A%2520%253Cstring%253E%257D.%250A%2520%2520%2520%2520return%2520%257B%250A%2520%2520%2520%2520%2520%2520url%253A%2520parentURL%2520%253F%250A%2520%2520%2520%2520%2520%2520%2520%2520new%2520URL(specifier%252C%2520parentURL).href%2520%253A%250A%2520%2520%2520%2520%2520%2520%2520%2520new%2520URL(specifier).href%252C%250A%2520%2520%2520%2520%257D%253B%250A%2520%2520%257D%250A%2520%2520if%2520(Math.random()%2520%253C%25200.5)%2520%257B%2520%252F%252F%2520Another%2520condition.%250A%2520%2520%2520%2520%252F%252F%2520When%2520calling%2520%2560defaultResolve%2560%252C%2520the%2520arguments%2520can%2520be%2520modified.%2520In%2520this%250A%2520%2520%2520%2520%252F%252F%2520case%2520it's%2520adding%2520another%2520value%2520for%2520matching%2520conditional%2520exports.%250A%2520%2520%2520%2520return%2520defaultResolve(specifier%252C%2520%257B%250A%2520%2520%2520%2520%2520%2520...context%252C%250A%2520%2520%2520%2520%2520%2520conditions%253A%2520%255B...context.conditions%252C%2520'another-condition'%255D%252C%250A%2520%2520%2520%2520%257D)%253B%250A%2520%2520%257D%250A%2520%2520%252F%252F%2520Defer%2520to%2520Node.js%2520for%2520all%2520other%2520specifiers.%250A%2520%2520return%2520defaultResolve(specifier%252C%2520context%252C%2520defaultResolve)%253B%250A%257D PR-URL: #34240 Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Guy Bedford <guybedford@gmail.com>
1 parent befbaf3 commit 44e6c01

1 file changed

Lines changed: 56 additions & 27 deletions

File tree

‎doc/api/esm.md‎

Lines changed: 56 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1184,11 +1184,19 @@ CommonJS modules loaded.
11841184

11851185
### Hooks
11861186

1187-
#### <code>resolve</code> hook
1187+
#### `resolve(specifier, context, defaultResolve)`
11881188

11891189
> Note: The loaders API is being redesigned. This hook may disappear or its
11901190
> signature may change. Do not rely on the API described below.
11911191

1192+
* `specifier` {string}
1193+
* `context` {Object}
1194+
* `conditions` {string[]}
1195+
* `parentURL` {string}
1196+
* `defaultResolve` {Function}
1197+
* Returns: {Object}
1198+
* `url` {string}
1199+
11921200
The `resolve` hook returns the resolved file URL for a given module specifier
11931201
and parent URL. The module specifier is the string in an `import` statement or
11941202
`import()` expression, and the parent URL is the URL of the module that imported
@@ -1209,11 +1217,11 @@ Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
12091217
/**
12101218
* @param {string} specifier
12111219
* @param {{
1220+
* conditions: !Array<string>,
12121221
* parentURL: !(string | undefined),
1213-
* conditions: !(Array<string>),
12141222
* }} context
12151223
* @param {Function} defaultResolve
1216-
* @returns {!(Promise<{ url: string }>)}
1224+
* @returns {Promise<{ url: string }>}
12171225
*/
12181226
export async function resolve(specifier, context, defaultResolve) {
12191227
const { parentURL = null } = context;
@@ -1239,29 +1247,34 @@ export async function resolve(specifier, context, defaultResolve) {
12391247
}
12401248
```
12411249

1242-
#### <code>getFormat</code> hook
1250+
#### `getFormat(url, context, defaultGetFormat)`
12431251

12441252
> Note: The loaders API is being redesigned. This hook may disappear or its
12451253
> signature may change. Do not rely on the API described below.
12461254

1255+
* `url` {string}
1256+
* `context` {Object}
1257+
* `defaultGetFormat` {Function}
1258+
* Returns: {Object}
1259+
* `format` {string}
1260+
12471261
The `getFormat` hook provides a way to define a custom method of determining how
12481262
a URL should be interpreted. The `format` returned also affects what the
12491263
acceptable forms of source values are for a module when parsing. This can be one
12501264
of the following:
12511265

1252-
| `format` | Description | Acceptable Types For `source` Returned by `getSource` or `transformSource` |
1253-
| --- | --- | --- |
1254-
| `'builtin'` | Load a Node.js builtin module | Not applicable |
1255-
| `'commonjs'` | Load a Node.js CommonJS module | Not applicable |
1256-
| `'json'` | Load a JSON file | { [ArrayBuffer][], [string][], [TypedArray][] } |
1257-
| `'module'` | Load an ES module | { [ArrayBuffer][], [string][], [TypedArray][] } |
1258-
| `'wasm'` | Load a WebAssembly module | { [ArrayBuffer][], [string][], [TypedArray][] } |
1266+
| `format` | Description | Acceptable Types For `source` Returned by `getSource` or `transformSource` |
1267+
| ------------ | ------------------------------ | -------------------------------------------------------------------------- |
1268+
| `'builtin'` | Load a Node.js builtin module | Not applicable |
1269+
| `'commonjs'` | Load a Node.js CommonJS module | Not applicable |
1270+
| `'json'` | Load a JSON file | { [`string`][], [`ArrayBuffer`][], [`TypedArray`][] } |
1271+
| `'module'` | Load an ES module | { [`string`][], [`ArrayBuffer`][], [`TypedArray`][] } |
1272+
| `'wasm'` | Load a WebAssembly module | { [`ArrayBuffer`][], [`TypedArray`][] } |
12591273

12601274
Note: These types all correspond to classes defined in ECMAScript.
12611275

1262-
* The specific [ArrayBuffer][] object is a [SharedArrayBuffer][].
1263-
* The specific [string][] object is not the class constructor, but an instance.
1264-
* The specific [TypedArray][] object is a [Uint8Array][].
1276+
* The specific [`ArrayBuffer`][] object is a [`SharedArrayBuffer`][].
1277+
* The specific [`TypedArray`][] object is a [`Uint8Array`][].
12651278

12661279
Note: If the source value of a text-based format (i.e., `'json'`, `'module'`) is
12671280
not a string, it will be converted to a string using [`util.TextDecoder`][].
@@ -1287,11 +1300,18 @@ export async function getFormat(url, context, defaultGetFormat) {
12871300
}
12881301
```
12891302

1290-
#### <code>getSource</code> hook
1303+
#### `getSource(url, context, defaultGetSource)`
12911304

12921305
> Note: The loaders API is being redesigned. This hook may disappear or its
12931306
> signature may change. Do not rely on the API described below.
12941307

1308+
* `url` {string}
1309+
* `context` {Object}
1310+
* `format` {string}
1311+
* `defaultGetSource` {Function}
1312+
* Returns: {Object}
1313+
* `source` {string|SharedArrayBuffer|Uint8Array}
1314+
12951315
The `getSource` hook provides a way to define a custom method for retrieving
12961316
the source code of an ES module specifier. This would allow a loader to
12971317
potentially avoid reading files from disk.
@@ -1301,7 +1321,7 @@ potentially avoid reading files from disk.
13011321
* @param {string} url
13021322
* @param {{ format: string }} context
13031323
* @param {Function} defaultGetSource
1304-
* @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>}
1324+
* @returns {Promise<{ source: !(string | SharedArrayBuffer | Uint8Array) }>}
13051325
*/
13061326
export async function getSource(url, context, defaultGetSource) {
13071327
const { format } = context;
@@ -1317,11 +1337,18 @@ export async function getSource(url, context, defaultGetSource) {
13171337
}
13181338
```
13191339

1320-
#### <code>transformSource</code> hook
1340+
#### `transformSource(source, context, defaultTransformSource)`
13211341

13221342
> Note: The loaders API is being redesigned. This hook may disappear or its
13231343
> signature may change. Do not rely on the API described below.
13241344

1345+
* `source` {string|SharedArrayBuffer|Uint8Array}
1346+
* `context` {Object}
1347+
* `format` {string}
1348+
* `url` {string}
1349+
* Returns: {Object}
1350+
* `source` {string|SharedArrayBuffer|Uint8Array}
1351+
13251352
The `transformSource` hook provides a way to modify the source code of a loaded
13261353
ES module file after the source string has been loaded but before Node.js has
13271354
done anything with it.
@@ -1332,13 +1359,13 @@ unknown-to-Node.js file extensions. See the [transpiler loader example][] below.
13321359

13331360
```js
13341361
/**
1335-
* @param {!(SharedArrayBuffer | string | Uint8Array)} source
1362+
* @param {!(string | SharedArrayBuffer | Uint8Array)} source
13361363
* @param {{
1337-
* url: string,
13381364
* format: string,
1365+
* url: string,
13391366
* }} context
13401367
* @param {Function} defaultTransformSource
1341-
* @returns {Promise<{ source: !(SharedArrayBuffer | string | Uint8Array) }>}
1368+
* @returns {Promise<{ source: !(string | SharedArrayBuffer | Uint8Array) }>}
13421369
*/
13431370
export async function transformSource(source, context, defaultTransformSource) {
13441371
const { url, format } = context;
@@ -1354,11 +1381,13 @@ export async function transformSource(source, context, defaultTransformSource) {
13541381
}
13551382
```
13561383

1357-
#### <code>getGlobalPreloadCode</code> hook
1384+
#### `getGlobalPreloadCode()`
13581385

13591386
> Note: The loaders API is being redesigned. This hook may disappear or its
13601387
> signature may change. Do not rely on the API described below.
13611388

1389+
* Returns: {string}
1390+
13621391
Sometimes it can be necessary to run some code inside of the same global scope
13631392
that the application will run in. This hook allows to return a string that will
13641393
be ran as sloppy-mode script on startup.
@@ -1909,12 +1938,12 @@ success!
19091938
[`import`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import
19101939
[`module.createRequire()`]: modules.html#modules_module_createrequire_filename
19111940
[`module.syncBuiltinESMExports()`]: modules.html#modules_module_syncbuiltinesmexports
1912-
[`transformSource` hook]: #esm_code_transformsource_code_hook
1913-
[ArrayBuffer]: https://www.ecma-international.org/ecma-262/6.0/#sec-arraybuffer-constructor
1914-
[SharedArrayBuffer]: https://tc39.es/ecma262/#sec-sharedarraybuffer-constructor
1915-
[string]: https://www.ecma-international.org/ecma-262/6.0/#sec-string-constructor
1916-
[TypedArray]: https://www.ecma-international.org/ecma-262/6.0/#sec-typedarray-objects
1917-
[Uint8Array]: https://www.ecma-international.org/ecma-262/6.0/#sec-uint8array
1941+
[`transformSource` hook]: #esm_transformsource_source_context_defaulttransformsource
1942+
[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
1943+
[`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
1944+
[`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
1945+
[`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
1946+
[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
19181947
[`util.TextDecoder`]: util.html#util_class_util_textdecoder
19191948
[import an ES or CommonJS module for its side effects only]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Import_a_module_for_its_side_effects_only
19201949
[special scheme]: https://url.spec.whatwg.org/#special-scheme

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL