Skip to content

Commit

Permalink
doc: revise dependency redirection text in policy.md
Browse files Browse the repository at this point in the history
PR-URL: #35276
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
  • Loading branch information
Trott authored and MylesBorins committed Sep 24, 2020
1 parent 7f35573 commit 1893449
Showing 1 changed file with 15 additions and 15 deletions.
30 changes: 15 additions & 15 deletions doc/api/policy.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,28 +137,28 @@ replaced.
```

The dependencies are keyed by the requested specifier string and have values
of either `true`, `null`, a string pointing to a module that will be resolved,
of either `true`, `null`, a string pointing to a module to be resolved,
or a conditions object.

The specifier string does not perform any searching and must match exactly
what is provided to the `require()` or `import`. Therefore, multiple specifiers
may be needed in the policy if it uses multiple different strings to point
to the same module (such as excluding the extension).

If the value of the redirection is `true` the default searching algorithms will
be used to find the module.
If the value of the redirection is `true` the default searching algorithms are
used to find the module.

If the value of the redirection is a string, it will be resolved relative to
the manifest and then immediately be used without searching.
If the value of the redirection is a string, it is resolved relative to
the manifest and then immediately used without searching.

Any specifier string that is attempted to resolve and not listed in the
dependencies will result in an error according to the policy.
Any specifier string for which resolution is attempted and that is not listed in
the dependencies results in an error according to the policy.

Redirection will not prevent access to APIs through means such as direct access
to `require.cache` and/or through `module.constructor` which allow access to
Redirection does not prevent access to APIs through means such as direct access
to `require.cache` or through `module.constructor` which allow access to
loading modules. Policy redirection only affects specifiers to `require()` and
`import`. Other means such as to prevent undesired access to APIs through
variables are necessary to lock down that path of loading modules.
`import`. Other means, such as to prevent undesired access to APIs through
variables, are necessary to lock down that path of loading modules.

A boolean value of `true` for the dependencies map can be specified to allow a
module to load any specifier without redirection. This can be useful for local
Expand All @@ -167,14 +167,14 @@ only with care after auditing a module to ensure its behavior is valid.

Similar to `"exports"` in `package.json`, dependencies can also be specified to
be objects containing conditions which branch how dependencies are loaded. In
the preceding example, `"http"` will be allowed when the `"import"` condition is
the preceding example, `"http"` is allowed when the `"import"` condition is
part of loading it.

A value of `null` for the resolved value will cause the resolution to fail. This
A value of `null` for the resolved value causes the resolution to fail. This
can be used to ensure some kinds of dynamic access are explicitly prevented.

Unknown values for the resolved module location will cause failure but are
not guaranteed to be forwards compatible.
Unknown values for the resolved module location cause failures but are
not guaranteed to be forward compatible.

#### Example: Patched dependency

Expand Down

0 comments on commit 1893449

Please sign in to comment.