{ "manifest": { "version": "1.1.1", "name": "resolve.exports", "repository": { "type": "git", "url": "https://github.com/lukeed/resolve.exports.git" }, "description": "A tiny (813b), correct, general-purpose, and configurable \"exports\" resolver without file-system reliance", "module": "dist/index.mjs", "main": "dist/index.js", "types": "index.d.ts", "license": "MIT", "author": { "name": "Luke Edwards", "email": "luke.edwards05@gmail.com", "url": "https://lukeed.com" }, "engines": { "node": ">=10" }, "scripts": { "build": "bundt", "test": "uvu -r esm test" }, "files": [ "*.d.ts", "dist" ], "exports": { ".": { "types": "./index.d.ts", "import": "./dist/index.mjs", "require": "./dist/index.js" }, "./package.json": "./package.json" }, "keywords": [ "esm", "exports", "esmodules", "fields", "modules", "resolution", "resolve" ], "devDependencies": { "bundt": "1.1.2", "esm": "3.2.25", "uvu": "0.5.1" }, "_registry": "npm", "_loc": "/homez.1033/heliovt/.cache/yarn/v6/npm-resolve-exports-1.1.1-05cfd5b3edf641571fd46fa608b610dda9ead999-integrity/node_modules/resolve.exports/package.json", "readmeFilename": "readme.md", "readme": "# resolve.exports [![CI](https://github.com/lukeed/resolve.exports/workflows/CI/badge.svg)](https://github.com/lukeed/resolve.exports/actions) [![codecov](https://codecov.io/gh/lukeed/resolve.exports/branch/master/graph/badge.svg?token=4P7d4Omw2h)](https://codecov.io/gh/lukeed/resolve.exports)\n\n> A tiny (813b), correct, general-purpose, and configurable `\"exports\"` resolver without file-system reliance\n\n***Why?***\n\nHopefully, this module may serve as a reference point (and/or be used directly) so that the varying tools and bundlers within the ecosystem can share a common approach with one another **as well as** with the native Node.js implementation.\n\nWith the push for ESM, we must be _very_ careful and avoid fragmentation. If we, as a community, begin propagating different _dialects_ of `\"exports\"` resolution, then we're headed for deep trouble. It will make supporting (and using) `\"exports\"` nearly impossible, which may force its abandonment and along with it, its benefits.\n\nLet's have nice things.\n\n***TODO***\n\n- [x] exports string\n- [x] exports object (single entry)\n- [x] exports object (multi entry)\n- [x] nested / recursive conditions\n- [x] exports arrayable\n- [x] directory mapping (`./foobar/` => `/foobar/`)\n- [x] directory mapping (`./foobar/*` => `./other/*.js`)\n- [x] directory mapping w/ conditions\n- [x] directory mapping w/ nested conditions\n- [x] legacy fields (`main` vs `module` vs ...)\n- [x] legacy \"browser\" files object\n\n## Install\n\n```sh\n$ npm install resolve.exports\n```\n\n## Usage\n\n> Please see [`/test/`](/test) for examples.\n\n```js\nimport { resolve, legacy } from 'resolve.exports';\n\nconst contents = {\n \"name\": \"foobar\",\n \"module\": \"dist/module.mjs\",\n \"main\": \"dist/require.js\",\n \"exports\": {\n \".\": {\n \"import\": \"./dist/module.mjs\",\n \"require\": \"./dist/require.js\"\n },\n \"./lite\": {\n \"worker\": {\n \"browser\": \"./lite/worker.brower.js\",\n \"node\": \"./lite/worker.node.js\"\n },\n \"import\": \"./lite/module.mjs\",\n \"require\": \"./lite/require.js\"\n }\n }\n};\n\n// Assumes `.` as default entry\n// Assumes `import` as default condition\nresolve(contents); //=> \"./dist/module.mjs\"\n\n// entry: nullish === \"foobar\" === \".\"\nresolve(contents, 'foobar'); //=> \"./dist/module.mjs\"\nresolve(contents, '.'); //=> \"./dist/module.mjs\"\n\n// entry: \"foobar/lite\" === \"./lite\"\nresolve(contents, 'foobar/lite'); //=> \"./lite/module.mjs\"\nresolve(contents, './lite'); //=> \"./lite/module.mjs\"\n\n// Assume `require` usage\nresolve(contents, 'foobar', { require: true }); //=> \"./dist/require.js\"\nresolve(contents, './lite', { require: true }); //=> \"./lite/require.js\"\n\n// Throws \"Missing export in package\" Error\nresolve(contents, 'foobar/hello');\nresolve(contents, './hello/world');\n\n// Add custom condition(s)\nresolve(contents, 'foobar/lite', {\n conditions: ['worker']\n}); // => \"./lite/worker.node.js\"\n\n// Toggle \"browser\" condition\nresolve(contents, 'foobar/lite', {\n conditions: ['worker'],\n browser: true\n}); // => \"./lite/worker.browser.js\"\n\n// ---\n// Legacy\n// ---\n\n// prefer \"module\" > \"main\" (default)\nlegacy(contents); //=> \"dist/module.mjs\"\n\n// customize fields order\nlegacy(contents, {\n fields: ['main', 'module']\n}); //=> \"dist/require.js\"\n```\n\n## API\n\n### resolve(pkg, entry?, options?)\nReturns: `string` or `undefined`\n\nTraverse the `\"exports\"` within the contents of a `package.json` file.
\nIf the contents _does not_ contain an `\"exports\"` map, then `undefined` will be returned.\n\nSuccessful resolutions will always result in a string value. This will be the value of the resolved mapping itself – which means that the output is a relative file path.\n\nThis function may throw an Error if:\n\n* the requested `entry` cannot be resolved (aka, not defined in the `\"exports\"` map)\n* an `entry` _was_ resolved but no known conditions were found (see [`options.conditions`](#optionsconditions))\n\n#### pkg\nType: `object`
\nRequired: `true`\n\nThe `package.json` contents.\n\n#### entry\nType: `string`
\nRequired: `false`
\nDefault: `.` (aka, root)\n\nThe desired target entry, or the original `import` path.\n\nWhen `entry` _is not_ a relative path (aka, does not start with `'.'`), then `entry` is given the `'./'` prefix.\n\nWhen `entry` begins with the package name (determined via the `pkg.name` value), then `entry` is truncated and made relative.\n\nWhen `entry` is already relative, it is accepted as is.\n\n***Examples***\n\nAssume we have a module named \"foobar\" and whose `pkg` contains `\"name\": \"foobar\"`.\n\n| `entry` value | treated as | reason |\n|-|-|-|\n| `null` / `undefined` | `'.'` | default |\n| `'.'` | `'.'` | value was relative |\n| `'foobar'` | `'.'` | value was `pkg.name` |\n| `'foobar/lite'` | `'./lite'` | value had `pkg.name` prefix |\n| `'./lite'` | `'./lite'` | value was relative |\n| `'lite'` | `'./lite'` | value was not relative & did not have `pkg.name` prefix |\n\n\n#### options.require\nType: `boolean`
\nDefault: `false`\n\nWhen truthy, the `\"require\"` field is added to the list of allowed/known conditions.\n\nWhen falsey, the `\"import\"` field is added to the list of allowed/known conditions instead.\n\n#### options.browser\nType: `boolean`
\nDefault: `false`\n\nWhen truthy, the `\"browser\"` field is added to the list of allowed/known conditions.\n\n#### options.conditions\nType: `string[]`
\nDefault: `[]`\n\nProvide a list of additional/custom conditions that should be accepted when seen.\n\n> **Important:** The order specified within `options.conditions` does not matter.
The matching order/priority is **always** determined by the `\"exports\"` map's key order.\n\nFor example, you may choose to accept a `\"production\"` condition in certain environments. Given the following `pkg` content:\n\n```js\nconst contents = {\n // ...\n \"exports\": {\n \"worker\": \"./index.worker.js\",\n \"require\": \"./index.require.js\",\n \"production\": \"./index.prod.js\",\n \"import\": \"./index.import.mjs\",\n }\n};\n\nresolve(contents, '.');\n//=> \"./index.import.mjs\"\n\nresolve(contents, '.', {\n conditions: ['production']\n}); //=> \"./index.prod.js\"\n\nresolve(contents, '.', {\n conditions: ['production'],\n require: true,\n}); //=> \"./index.require.js\"\n\nresolve(contents, '.', {\n conditions: ['production', 'worker'],\n require: true,\n}); //=> \"./index.worker.js\"\n\nresolve(contents, '.', {\n conditions: ['production', 'worker']\n}); //=> \"./index.worker.js\"\n```\n\n#### options.unsafe\nType: `boolean`
\nDefault: `false`\n\n> **Important:** You probably do not want this option!
It will break out of Node's default resolution conditions.\n\nWhen enabled, this option will ignore **all other options** except [`options.conditions`](#optionsconditions). This is because, when enabled, `options.unsafe` **does not** assume or provide any default conditions except the `\"default\"` condition.\n\n```js\nresolve(contents);\n//=> Conditions: [\"default\", \"import\", \"node\"]\n\nresolve(contents, { unsafe: true });\n//=> Conditions: [\"default\"]\n\nresolve(contents, { unsafe: true, require: true, browser: true });\n//=> Conditions: [\"default\"]\n```\n\nIn other words, this means that trying to use `options.require` or `options.browser` alongside `options.unsafe` will have no effect. In order to enable these conditions, you must provide them manually into the `options.conditions` list:\n\n```js\nresolve(contents, {\n unsafe: true,\n conditions: [\"require\"]\n});\n//=> Conditions: [\"default\", \"require\"]\n\nresolve(contents, {\n unsafe: true,\n conditions: [\"browser\", \"require\", \"custom123\"]\n});\n//=> Conditions: [\"default\", \"browser\", \"require\", \"custom123\"]\n```\n\n\n### legacy(pkg, options?)\nReturns: `string` or `undefined`\n\nAlso included is a \"legacy\" method for resolving non-`\"exports\"` package fields. This may be used as a fallback method when for when no `\"exports\"` mapping is defined. In other words, it's completely optional (and tree-shakeable).\n\nYou may customize the field priority via [`options.fields`](#optionsfields).\n\nWhen a field is found, its value is returned _as written_.
\nWhen no fields were found, `undefined` is returned. If you wish to mimic Node.js behavior, you can assume this means `'index.js'` – but this module does not make that assumption for you.\n\n#### options.browser\nType: `boolean` or `string`
\nDefault: `false`\n\nWhen truthy, ensures that the `'browser'` field is part of the acceptable `fields` list.\n\n> **Important:** If your custom [`options.fields`](#optionsfields) value includes `'browser'`, then _your_ order is respected.
Otherwise, when truthy, `options.browser` will move `'browser'` to the front of the list, making it the top priority.\n\nWhen `true` and `\"browser\"` is an object, then `legacy()` will return the the entire `\"browser\"` object.\n\nYou may also pass a string value, which will be treated as an import/file path. When this is the case and `\"browser\"` is an object, then `legacy()` may return:\n\n* `false` – if the package author decided a file should be ignored; or\n* your `options.browser` string value – but made relative, if not already\n\n> See the [`\"browser\" field specification](https://github.com/defunctzombie/package-browser-field-spec) for more information.\n\n#### options.fields\nType: `string[]`
\nDefault: `['module', 'main']`\n\nA list of fields to accept. The order of the array determines the priority/importance of each field, with the most important fields at the beginning of the list.\n\nBy default, the `legacy()` method will accept any `\"module\"` and/or \"main\" fields if they are defined. However, if both fields are defined, then \"module\" will be returned.\n\n```js\nconst contents = {\n \"name\": \"...\",\n \"worker\": \"worker.js\",\n \"module\": \"module.mjs\",\n \"browser\": \"browser.js\",\n \"main\": \"main.js\",\n}\n\nlegacy(contents);\n// fields = [module, main]\n//=> \"module.mjs\"\n\nlegacy(contents, { browser: true });\n// fields = [browser, module, main]\n//=> \"browser.mjs\"\n\nlegacy(contents, {\n fields: ['missing', 'worker', 'module', 'main']\n});\n// fields = [missing, worker, module, main]\n//=> \"worker.js\"\n\nlegacy(contents, {\n fields: ['missing', 'worker', 'module', 'main'],\n browser: true,\n});\n// fields = [browser, missing, worker, module, main]\n//=> \"browser.js\"\n\nlegacy(contents, {\n fields: ['module', 'browser', 'main'],\n browser: true,\n});\n// fields = [module, browser, main]\n//=> \"module.mjs\"\n```\n\n## License\n\nMIT © [Luke Edwards](https://lukeed.com)\n", "licenseText": "The MIT License (MIT)\n\nCopyright (c) Luke Edwards (lukeed.com)\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n" }, "artifacts": [], "remote": { "resolved": "https://registry.yarnpkg.com/resolve.exports/-/resolve.exports-1.1.1.tgz#05cfd5b3edf641571fd46fa608b610dda9ead999", "type": "tarball", "reference": "https://registry.yarnpkg.com/resolve.exports/-/resolve.exports-1.1.1.tgz", "hash": "05cfd5b3edf641571fd46fa608b610dda9ead999", "integrity": "sha512-/NtpHNDN7jWhAaQ9BvBUYZ6YTXsRBgfqWFWP7BZBaoMJO/I3G5OFzvTuWNlZC3aPjins1F+TNrLKsGbH4rfsRQ==", "registry": "npm", "packageName": "resolve.exports", "cacheIntegrity": "sha512-/NtpHNDN7jWhAaQ9BvBUYZ6YTXsRBgfqWFWP7BZBaoMJO/I3G5OFzvTuWNlZC3aPjins1F+TNrLKsGbH4rfsRQ== sha1-Bc/Vs+32QVcf1G+mCLYQ3anq2Zk=" }, "registry": "npm", "hash": "05cfd5b3edf641571fd46fa608b610dda9ead999" }