module: runtime deprecate subpath folder mappings

PR-URL: https://github.com/nodejs/node/pull/35747
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Myles Borins <myles.borins@gmail.com>

2 files changed, 66 insertions, 0 deletions

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 326f4705856..724d5abae68 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -2677,6 +2677,28 @@ In future versions of Node.js, `fs.rmdir(path, { recursive: true })` will throw
 if `path` does not exist or is a file.
 Use `fs.rm(path, { recursive: true, force: true })` instead.
 
+### DEP0148: Folder mappings in `"exports"` (trailing `"/"`)
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/35746
+    description: Runtime deprecation.
+  - version: v14.13.0
+    pr-url: https://github.com/nodejs/node/pull/34718
+    description: Documentation-only deprecation.
+-->
+
+Type: Runtime (supports [`--pending-deprecation`][])
+
+Prior to [subpath patterns][] support, it was possible to define
+[subpath folder mappings][] in the [subpath exports][] or
+[subpath imports][] fields using a trailing `"/"`.
+
+Without `--pending-deprecation`, runtime warnings occur only for exports
+resolutions not in `node_modules`. This means there will not be deprecation
+warnings for `"exports"` in dependencies. With `--pending-deprecation`, a
+runtime warning results no matter where the `"exports"` usage occurs.
+
 [Legacy URL API]: url.md#url_legacy_url_api
 [NIST SP 800-38D]: https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication800-38d.pdf
 [RFC 6066]: https://tools.ietf.org/html/rfc6066#section-3
@@ -2801,3 +2823,7 @@ Use `fs.rm(path, { recursive: true, force: true })` instead.
 [from_string_encoding]: buffer.md#buffer_static_method_buffer_from_string_encoding
 [legacy `urlObject`]: url.md#url_legacy_urlobject
 [static methods of `crypto.Certificate()`]: crypto.md#crypto_class_certificate
+[subpath exports]: #packages_subpath_exports
+[subpath folder mappings]: #packages_subpath_folder_mappings
+[subpath imports]: #packages_subpath_imports
+[subpath patterns]: #packages_subpath_patterns
diff --git a/doc/api/packages.md b/doc/api/packages.md
index 5fef7f4766d..9b7ba7fb119 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -365,6 +365,45 @@ treating the right hand side target pattern as a `**` glob against the list of
 files within the package. Because `node_modules` paths are forbidden in exports
 targets, this expansion is dependent on only the files of the package itself.
 
+### Subpath folder mappings
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/35746
+    description: Runtime deprecation.
+  - version: v14.13.0
+    pr-url: https://github.com/nodejs/node/pull/34718
+    description: Documentation-only deprecation.
+-->
+
+> Stability: 0 - Deprecated: Use subpath patterns instead.
+
+Before subpath patterns were supported, a trailing `"/"` suffix was used to
+support folder mappings:
+
+```json
+{
+  "exports": {
+    "./features/": "./features/"
+  }
+}
+```
+
+_This feature will be removed in a future release._
+
+Instead, use direct [subpath patterns][]:
+
+```json
+{
+  "exports": {
+    "./features/*": "./features/*.js"
+  }
+}
+```
+
+The benefit of patterns over folder exports is that packages can always be
+imported by consumers without subpath file extensions being necessary.
+
 ### Exports sugar
 
 If the `"."` export is the only export, the [`"exports"`][] field provides sugar
@@ -1028,5 +1067,6 @@ This field defines [subpath imports][] for the current package.
 [self-reference]: #packages_self_referencing_a_package_using_its_name
 [subpath exports]: #packages_subpath_exports
 [subpath imports]: #packages_subpath_imports
+[subpath patterns]: #packages_subpath_patterns
 [the full specifier path]: esm.md#esm_mandatory_file_extensions
 [the dual CommonJS/ES module packages section]: #packages_dual_commonjs_es_module_packages