This commit improves the TypeScript TypeDocs for `runtime` modules in
the NodeJS SDK. Specifically:
* It adds documentation to interfaces, properties, etc. that are missing
it.
* It transforms would-be TypeDoc comments erroneously written using
either `/*` (a single asterisk) or `//` (a normal line comment) to
actual TypeDoc comments.
* It standardises on TypeDoc's `{@link Name}` syntax for linking
identifiers, as opposed to the mixture of backticks and square brackets
we have today.
* It fixes typos and generally cleans up the formatting here and there,
as well as introducing more consistency where the same concepts crop up
in multiple places.
This commit addresses part of #11942, in which we fail to serialise
closures whose code would use reserved identifiers like `exports`. This
is due to a change we made where module imports are hoisted to avoid
importing the same module multiple times. Previously, code adopted a
strategy of passing all dependencies using a `with` statement, viz.:
```typescript
function x() {
return (function () {
with({ fooBarBaz: require("foo/bar/baz"), ... }) {
// Use of fooBarBaz
}
}).apply(...)
}
function y() {
return (function () {
with({ fooBarBaz: require("foo/bar/baz"), ... }) {
// Use of fooBarBaz
}
}).apply(...)
}
```
This was changed to remove the duplicate imports, yielding code like:
```typescript
const fooBarBaz = require("foo/bar/baz")
function x() {
return (function () {
with({ ... }) {
// Use of fooBarBaz
}
}).apply(...)
}
function y() {
return (function () {
with({ ... }) {
// Use of fooBarBaz
}
}).apply(...)
}
```
However, while the previous approach would work with reserved
identifiers such as `exports` (`with({ exports, ... }) { ... }` is
perfectly acceptable), the new one does not (`const exports = ...` is
not acceptable since NodeJS will not allow redeclaration of the
`exports` global).
This commit combines the two approaches. Modules are only imported once,
but if an import would use a reserved identifier, we generate a fresh
non-conflicting identifier and alias this using a `with` statement. For
example:
```typescript
const fooBarBaz = require("foo/bar/baz")
// __pulumi_closure_import_exports is generated to avoid shadowing the reserved "exports"
const __pulumi_closure_import_exports = require("some/other/module")
function x() {
return (function () {
with({ exports: __pulumi_closure_import_exports, ... }) {
// Use of fooBarBaz and exports
}
}).apply(...)
}
```
Note that it is not expected that #11942 will be solved in its entirety.
While this commit fixes code that introduces identifiers like `exports`,
the introduction in question in that issue is caused by the use of
`pulumi.output(...)` in the constructor of a dynamic resource provider.
Since dynamic resource providers are implemented under the hood by
serialising their code, we attempt to serialise `pulumi.output` and its
dependency chain. This commit allows us to make more progress in that
regard, but other things go wrong thereafter. Fixing the deeper issue
that underpins #11942 (and likely other challenges with dynamic
providers) is probably a more involved piece of work.
This commit applies the Rome autoformatter to the Node SDK.
These changes are automatically produced. To reproduce these
changes, run `make format` from inside sdk/nodejs.
Adds an opt-in `allowSecrets` flag to `serializeFunction` to allow it to capture secrets. If passed, `serializeFunction` will now report back whether it captured any secrets. This information can be used by callers to wrap the resulting text in a Secret value.
Fixes#2718.
* Make v8 primitives async as there is no way to avoid async in node11.
* Simplify API.
* Move processing of well-known globals into the v8 layer.
We'll need this so that we can map from RemoteObjectIds back to these well known values.
* Remove unnecesssary check.
* Cleanup comments and extract helper.
* Introduce helper bridge method for the simple case of making an entry for a string.
* Make functions async. They'll need to be async once we move to the Inspector api.
* Make functions async. They'll need to be async once we move to the Inspector api.
* Make functions async. They'll need to be async once we move to the Inspector api.
* Move property access behind helpers so they can move to the Inspector API in the future.
* Only call function when we know we have a Function. Remove redundant null check.
* Properly serialize certain special JavaScript number values that JSON serialization cannot handle.
* Only marshall across the 'source' and 'flags' for a RegExp when serializing.
* Add a simple test to validate a regex without flags.
* Extract functionality into helper method.
* Add test with complex output scenarios.
* Output serialization needs to avoid recursively trying to serialize a serialized value.
* Introduce indirection for introspecting properties of an object.
* Use our own introspection API for examining an Array.
* Hide direct property access through API indirection.
* Produce values like the v8 Inspector does.
* Compute the module map asynchronously. Will need that when mapping mirrors instead.
* Cleanup a little code in closure creation.
* Get serialization working on Node11 (except function locations).
* Run tests in the same order on <v11 and >=v11
* Make tests run on multiple versions of node.
* Rename file to make PR simpler to review.
* Cleanup.
* Be more careful with global state.
* Remove commented line.
* Only allow getting a session when on Node11 or above.
* Promisify methods.
* Revert RunError behavior. Introduce new ResourceError for errors associated with a resource.
* Fix docs.
* Use resource error.
* Use ResourceError in more places.
* Use ResourceError in a few more places.
* Throw a resource error.
* Make required.
* Revert this.
* Lint.
* Only report errors once.
* Better comment.
Closure serialization now keeps track of the `require`d packages it sees in the function bodies that are serialized during a call to `serializeFunction`.
Also, replaces `serializeFunctionAsync` with `serializeFunction` which accepts richer parameters and return type, deprecating the former API (but leaving it available for now to avoid a breaking change).
The four concerns are:
parsing a v8 function string so we can figure out captured variables.
walkgin the function/object graph producing the graph we will serialize.
rewriting constructors and methods so that 'super' works.
serializing graph to text.