Repository: nodejs/node
Pull request: doc,src,lib: clarify experimental status of Web Storage support

Documentation around Web Storage is kinda all over the place, IMO we're really not making a good job at presenting the experimental aspect of it.

- in https://github.com/nodejs/node/pull/57666, the flag was renamed to remove the "experimental" part of it. I think that was a mistake.
- the history sections in the docs are not mentioning the fact it's no longer behind the flag.
- some sections were straight up missing the experimental status badge, or mentioning stability 1.0 despite the fact the API is now unflagged.
- adding a history entry for the throw behavior that was reintroduced recently.

<!--
Before submitting a pull request, please read:

- the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md
- the commit message formatting guidelines at
  https://github.com/nodejs/node/blob/HEAD/doc/contributing/pull-requests.md#commit-message-guidelines

For code changes:
1. Include tests for any bug fixes or new features.
2. Update documentation if relevant.
3. Ensure that `make -j4 test` (UNIX), or `vcbuild test` (Windows) passes.

If you believe this PR should be highlighted in the Node.js CHANGELOG
please add the `notable-change` label.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

(a) The contribution was created in whole or in part by me and I
    have the right to submit it under the open source license
    indicated in the file; or

(b) The contribution is based upon previous work that, to the best
    of my knowledge, is covered under an appropriate open source
    license and I have the right under that license to submit that
    work with modifications, whether created in whole or in part
    by me, under the same open source license (unless I am
    permitted to submit under a different license), as indicated
    in the file; or

(c) The contribution was provided directly to me by some other
    person who certified (a), (b) or (c) and I have not modified
    it.

(d) I understand and agree that this project and the contribution
    are public and that a record of the contribution (including all
    personal information I submit with it, including my sign-off) is
    maintained indefinitely and may be redistributed consistent with
    this project or the open source license(s) involved.
-->


Changed files:
filename: doc/api/cli.md
patch: @@ -1745,10 +1745,11 @@ surface on other platforms, but the performance impact may be severe.
 added: v22.4.0
 -->
 
+> Stability: 1.2 - Release candidate.
+
 The file used to store `localStorage` data. If the file does not exist, it is
 created the first time `localStorage` is accessed. The same file may be shared
-between multiple Node.js processes concurrently. This flag is a no-op if
-Node.js is started with the `--no-webstorage` (or `--no-experimental-webstorage`) flag.
+between multiple Node.js processes concurrently.
 
 ### `--max-http-header-size=size`
 
@@ -1910,6 +1911,20 @@ added: v22.0.0
 
 Disable exposition of {WebSocket} on the global scope.
 
+### `--no-experimental-webstorage`
+
+<!-- YAML
+added: v22.4.0
+changes:
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: The feature is now enabled by default.
+-->
+
+> Stability: 1.2 - Release candidate.
+
+Disable [`Web Storage`][] support.
+
 ### `--no-extra-info-on-fatal-exception`
 
 <!-- YAML
@@ -1978,14 +1993,6 @@ added: v6.0.0
 
 Silence all process warnings (including deprecations).
 
-### `--no-webstorage`
-
-<!-- YAML
-added: v25.0.0
--->
-
-Disable [`Web Storage`][] support.
-
 ### `--node-memory-debug`
 
 <!-- YAML

filename: doc/api/globals.md
patch: @@ -644,13 +644,28 @@ A browser-compatible implementation of {Headers}.
 
 <!-- YAML
 added: v22.4.0
--->
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/60351
+    description: Accessing the `localStorage` global without providing
+                 `--localstorage-file` now throws a `DOMException`, for
+                 compliance with the Web Storage specification.
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: When webstorage is enabled and `--localstorage-file` is not
+                 provided, accessing the `localStorage` global now returns an
+                 empty object.
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: This API is no longer behind `--experimental-webstorage` runtime flag.
+-->
+
+> Stability: 1.2 - Release candidate. Disable this API with [`--no-experimental-webstorage`][].
 
 A browser-compatible implementation of [`localStorage`][]. Data is stored
 unencrypted in the file specified by the [`--localstorage-file`][] CLI flag.
 The maximum amount of data that can be stored is 10 MB.
 Any modification of this data outside of the Web Storage API is not supported.
-Disable this API with the [`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag.
 `localStorage` data is not stored per user or per request when used in the context
 of a server, it is shared across all users and requests.
 
@@ -1073,9 +1088,13 @@ A browser-compatible implementation of {Request}.
 
 <!-- YAML
 added: v22.4.0
+changes:
+  - version: v25.0.0
+    pr-url: https://github.com/nodejs/node/pull/57666
+    description: This API is no longer behind `--experimental-webstorage` runtime flag.
 -->
 
-> Stability: 1.0 - Early development.
+> Stability: 1.2 - Release candidate. Disable this API with [`--no-experimental-webstorage`][].
 
 A browser-compatible implementation of [`sessionStorage`][]. Data is stored in
 memory, with a storage quota of 10 MB. `sessionStorage` data persists only within
@@ -1111,10 +1130,9 @@ added: v0.0.1
 added: v22.4.0
 -->
 
-> Stability: 1.0 - Early development.
+> Stability: 1.2 - Release candidate. Disable this API with [`--no-experimental-webstorage`][].
 
-A browser-compatible implementation of {Storage}. Disable this API with the
-[`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag.
+A browser-compatible implementation of {Storage}.
 
 ## `structuredClone(value[, options])`
 
@@ -1328,7 +1346,7 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][].
 [`--localstorage-file`]: cli.md#--localstorage-filefile
 [`--no-experimental-global-navigator`]: cli.md#--no-experimental-global-navigator
 [`--no-experimental-websocket`]: cli.md#--no-experimental-websocket
-[`--no-webstorage`]: cli.md#--no-webstorage
+[`--no-experimental-webstorage`]: cli.md#--no-experimental-webstorage
 [`ByteLengthQueuingStrategy`]: webstreams.md#class-bytelengthqueuingstrategy
 [`CompressionStream`]: webstreams.md#class-compressionstream
 [`CountQueuingStrategy`]: webstreams.md#class-countqueuingstrategy

filename: doc/node.1
patch: @@ -207,8 +207,8 @@ Enable experimental support for the EventSource Web API.
 .It Fl -no-experimental-websocket
 Disable experimental support for the WebSocket API.
 .
-.It Fl -no-webstorage
-Disable webstorage.
+.It Fl -no-experimental-webstorage
+Disable experimental support for the Web Storage API.
 .
 .It Fl -no-experimental-repl-await
 Disable top-level await keyword support in REPL.

filename: lib/internal/process/pre_execution.js
patch: @@ -398,7 +398,7 @@ function setupQuic() {
 
 function setupWebStorage() {
   if (getEmbedderOptions().noBrowserGlobals ||
-      !getOptionValue('--webstorage')) {
+      !getOptionValue('--experimental-webstorage')) {
     return;
   }
 

filename: src/node_options.cc
patch: @@ -567,12 +567,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             NoOp{},
 #endif
             kAllowedInEnvvar);
-  AddOption("--webstorage",
-            "Web Storage API",
+  AddOption("--experimental-webstorage",
+            "experimental Web Storage API",
             &EnvironmentOptions::webstorage,
             kAllowedInEnvvar,
             true);
-  AddAlias("--experimental-webstorage", "--webstorage");
+  AddAlias("--webstorage", "--experimental-webstorage");
   AddOption("--localstorage-file",
             "file used to persist localStorage data",
             &EnvironmentOptions::localstorage_file,