This change fixes the TypeScript checking of output "any" maps.
Previously, as in the referenced issue, an `Output<Record<string, any>>`
had unusable properties with the lifting mechanisms in TypeScript. That
is, for such an output `foo`, using `foo["bar"]` would typically result
in a type error, as the type would be:
```typescript
pulumi.OutputInstance<unknown> | pulumi.Output<any>
```
This union type with unknown results in a type error on trying to use
`foo["bar"].apply(...)`. This is caused by the conditional type of
`Lifted<T>` having a condition `T[P] extends OutputInstance<infer T1>`
evaluating to the true branch, with `T1` inferred as `unknown`.
This is because `any extends OutputInstance<unknown>`.
Adding a strict check for `any` in the conditional type `Lifted<T>`
fixes the issue.
Fixes#16958
This commit improves the TypeScript TypeDocs for the remaining 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.
---------
Co-authored-by: Thomas Gummerer <t.gummerer@gmail.com>
As @denbezrukov notes in #13885, Rome (https://github.com/rome/tools,
the JavaScript toolchain we have been using to format and lint code in
the NodeJS SDK) has been deprecated. Biome (https://biomejs.dev/) has
sprung up in its place as a community fork and appears to be the best
bet for migration going forward. This commit introduces Biome, ports the
bits of configuration that need changing and updates formatting
accordingly.
Closes#13885
Co-authored-by: Denis Bezrukov <6227442+denbezrukov@users.noreply.github.com>
Raised by @lunaris in onboarding, we don't advertise the [Pulumi ESLint
Plugin](https://github.com/pulumi/eslint-plugin-pulumi). As using an
output in a template literal is one of the most common avenues to
discovering this issue, perhaps we should advertise the plugin here?
What's lacking from this is documentation, but I imagine that users will
see this, create issues, and that will drive improvements either in the
base SDK or the ESLint Plugin.
This commit fixes a few errant documentation comments that use `//`
instead of the recognised `/**`. This should hopefully improve
documentation generation as well as hover-over documentation provided by
e.g. TSServer.
Currently during updates we try to make the values known during apply,
even if they are marked unknown. This results in knows that should
really still be unknown.
Note that this behaviour is currently encoded in tests, which also
needed to change.
<!---
Thanks so much for your contribution! If this is your first time
contributing, please ensure that you have read the
[CONTRIBUTING](https://github.com/pulumi/pulumi/blob/master/CONTRIBUTING.md)
documentation.
-->
# Description
This adds an environment variable that changes output's `.toString` and
`.toJSON` methods to throw an exception instead of returning a string
containing a warning.
This feature mitigates the issue described in #4261 by allowing users to
opt in to having accidental toString calls (e.g. in a JS backtick string
that is missing `pulumi.interpolate`) throw an exception. The behaviour
ends up similar to the `get()` method of outputs, which throws an
exception.
I don't know how to write tests for this change, or even test it
manually.
## Checklist
- [x] I have run `make tidy` to update any new dependencies
- [x] I have run `make lint` to verify my code passes the lint check
- [ ] I have formatted my code using `gofumpt`
<!--- Please provide details if the checkbox below is to be left
unchecked. -->
- [ ] I have added tests that prove my fix is effective or that my
feature works
<!---
User-facing changes require a CHANGELOG entry.
-->
- [x] I have run `make changelog` and committed the
`changelog/pending/<file>` documenting my change
<!--
If the change(s) in this PR is a modification of an existing call to the
Pulumi Cloud,
then the service should honor older versions of the CLI where this
change would not exist.
You must then bump the API version in
/pkg/backend/httpstate/client/api.go, as well as add
it to the service.
-->
- [ ] Yes, there are changes in this PR that warrants bumping the Pulumi
Cloud API version
<!-- @Pulumi employees: If yes, you must submit corresponding changes in
the service repo. -->
---------
Co-authored-by: Fraser Waters <frassle@gmail.com>
Empty interfaces have no effect, even when they are subtyping
other interfaces. An empty interface is always equivalent to its supertype.
They can be safely replaced with type aliases, which better express
the semantic equivalence between the two types.
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.
This isn't _quite_ right, because you could possibly end up with an
output value being passed to stringify still via a custom replacer or
toJson method, and we don't handle that. But I don't think we _can_
handle that as we'd need async in sync to do it.
Using `all` currently looses type safety around the handling of input values which are possibly undefined.
By adding the explicit undefined option to each argument, the undefined case outside the inputty type does not get captured.
By removing the explicit `undefined` cases, the undefined is captured by the generic parameter and correctly carried through to the output type.
For example, if an input to `all` is possibly undefined, the value after `all` won't be labeled as possibly undefined.
```
// pulumi.Input<string> | undefined
let input = possiblyUndefinedInput();
// pulumi.Output<string>
let original = pulumi.all([input])[0];
// pulumi.Output<string | undefined>
let newBehaviour = pulumi.all([input])[0];
function possiblyUndefinedInput(): pulumi.Input<string> | undefined {
return undefined;
}
```
* Avoid importing typescript in node SDK where possible
* Lazy-load runtime/closure in dynamic/index.ts
* More targeted runtime import in config.ts
* More precise imports in run-policy-pack/run.ts
* More precise imports for dynamic-provider/index.ts
* More precise imports for automation/server.ts
* Share typescript compiler option loading func in run.ts and run-policy-pack/run.ts
* Lazy-load ts-node that depends on TypeScript
* Break module import cycle
* Fix node lint
Related: #5653
This will take an existing output and then unwrap the secret, and
return a new output
```
import * as pulumi from "@pulumi/pulumi";
const x = pulumi.secret("test")
export const xVal = x;
const y = pulumi.unsecret(x);
export const yVal = y;
```
```
▶ pulumi stack output
Current stack outputs (3):
OUTPUT VALUE
xVal [secret]
yVal test
```
Also adds the ability to check if an output is as secret:
```
import * as pulumi from "@pulumi/pulumi";
const x = pulumi.secret("test")
const isSecret = x.isSecret;
export const isSecretDeets = isSecret;
```
* Do not allocate outputs for nested prompt values.
Currently, `outupt`/`all` in the NodeJS SDK work recursively, allocating
outputs for every value at every depth, then collecting the component
promises into a top-level output. In the case of prompt values, these
nested outputs are not necessary, and allocating them can create massive
amounts of garbage. This appears to be the cause of
https://github.com/pulumi/pulumi-kubernetes/issues/963.
Also:
- Cleaned up existing tags so they're consistently at the bottom of doc comments where they should be
- Cleaned up some unused imports while I was taking a pass over the files
- Marked one function `@deprecated` that should be deprecated
These changes restore a more-correct version of the behavior that was
disabled with #3014. The original implementation of this behavior was
done in the SDKs, which do not have access to the complete inputs for a
resource (in particular, default values filled in by the provider during
`Check` are not exposed to the SDK). This lack of information meant that
the resolved output values could disagree with the typings present in
a provider SDK. Exacerbating this problem was the fact that unknown
values were dropped entirely, causing `undefined` values to appear in
unexpected places.
By doing this in the engine and allowing unknown values to be
represented in a first-class manner in the SDK, we can attack both of
these issues.
Although this behavior is not _strictly_ consistent with respect to the
resource model--in an update, a resource's output properties will come
from its provider and may differ from its input properties--this
behavior was present in the product for a fairly long time without
significant issues. In the future, we may be able to improve the
accuracy of resource outputs during a preview by allowing the provider
to dry-run CRUD operations and return partially-known values where
possible.
These changes also introduce new APIs in the Node and Python SDKs
that work with unknown values in a first-class fashion:
- A new parameter to the `apply` function that indicates that the
callback should be run even if the result of the apply contains
unknown values
- `containsUnknowns` and `isUnknown`, which return true if a value
either contains nested unknown values or is exactly an unknown value
- The `Unknown` type, which represents unknown values
The primary use case for these APIs is to allow nested, properties with
known values to be accessed via the lifted property accessor even when
the containing property is not fully know. A common example of this
pattern is the `metadata.name` property of a Kubernetes `Namespace`
object: while other properties of the `metadata` bag may be unknown,
`name` is often known. These APIs allow `ns.metadata.name` to return a
known value in this case.
In order to avoid exposing downlevel SDKs to unknown values--a change
which could break user code by exposing it to unexpected values--a
language SDK must indicate whether or not it supports first-class
unknown values as part of each `RegisterResourceRequest`.
These changes also allow us to avoid breaking user code with the new
behavior introduced by the prior commit.
Fixes#3190.
These changes restore a more-correct version of the behavior that was
disabled with #3014. The original implementation of this behavior was
done in the SDKs, which do not have access to the complete inputs for a
resource (in particular, default values filled in by the provider during
`Check` are not exposed to the SDK). This lack of information meant that
the resolved output values could disagree with the typings present in
a provider SDK. Exacerbating this problem was the fact that unknown
values were dropped entirely, causing `undefined` values to appear in
unexpected places.
By doing this in the engine and allowing unknown values to be
represented in a first-class manner in the SDK, we can attack both of
these issues.
Although this behavior is not _strictly_ consistent with respect to the
resource model--in an update, a resource's output properties will come
from its provider and may differ from its input properties--this
behavior was present in the product for a fairly long time without
significant issues. In the future, we may be able to improve the
accuracy of resource outputs during a preview by allowing the provider
to dry-run CRUD operations and return partially-known values where
possible.
These changes also introduce new APIs in the Node and Python SDKs
that work with unknown values in a first-class fashion:
- A new parameter to the `apply` function that indicates that the
callback should be run even if the result of the apply contains
unknown values
- `containsUnknowns` and `isUnknown`, which return true if a value
either contains nested unknown values or is exactly an unknown value
- The `Unknown` type, which represents unknown values
The primary use case for these APIs is to allow nested, properties with
known values to be accessed via the lifted property accessor even when
the containing property is not fully know. A common example of this
pattern is the `metadata.name` property of a Kubernetes `Namespace`
object: while other properties of the `metadata` bag may be unknown,
`name` is often known. These APIs allow `ns.metadata.name` to return a
known value in this case.
In order to avoid exposing downlevel SDKs to unknown values--a change
which could break user code by exposing it to unexpected values--a
language SDK must indicate whether or not it supports first-class
unknown values as part of each `RegisterResourceRequest`.
These changes also allow us to avoid breaking user code with the new
behavior introduced by the prior commit.
Fixes#3190.
Because of our Proxy types, every output will return something when
you call `.isSecret` on it. However, if you call it on an output from
a version of `@pulumi/pulumi` which did not support secrets, the thing
you will get back is not undefined but rather an `Output` which wraps
undefined.
Because of this, care must be taken when reading this property and so
a small helper is introduced and used in places we care about.
`Output<T>` now tracks if an output represents secret data or
not. When secret, it is marshalled as a secret value and we signal to
the resource monitor that it is safe to return secret values to us.
The `pulumi` module exports a new functiion, `secret<T>` which works
in the same was a `output<T>` except that it marks the underlying
output as a secret.
This secret bit flows as you would expect across `all`'s and
`apply`'s.
Note that in process memory, the raw value is still present, when you
run an `apply` for a secret output, you are able to see the raw
value. In addition, if you capture a secret output with a lambda, the
raw value will be present in the captured source text.
We changed the `pulumi update` command to be `pulumi up` a while back
(`update` is an alias of `up`). This change just makes it so we refer to
the actual command, `pulumi up`, instead of the older `pulumi update`.
This update includes several changes to core `@pulumi/pulumi` constructs that will not play nicely
in side-by-side applications that pull in prior versions of this package. As such, we are rev'ing
the minor version of the package from 0.16 to 0.17. Recent version of `pulumi` will now detect,
and warn, if different versions of `@pulumi/pulumi` are loaded into the same application. If you
encounter this warning, it is recommended you move to versions of the `@pulumi/...` packages that
are compatible. i.e. keep everything on 0.16.x until you are ready to move everything to 0.17.x.
### Improvements
- `Output<T>` now 'lifts' property members from the value it wraps, simplifying common coding patterns. Note: this wrapping only happens for POJO values, not `Output<Resource>`s.
- Depending on a **Component** Resource will now depend on all other Resources parented by that
Resource. This will help out the programming model for Component Resources as your consumers can
just depend on a Component and have that automatically depend on all the child Resources created
by that Component. Note: this does not apply to a **Custom** resource. Depending on a
CustomResource will still only wait on that single resource being created, not any other Resources
that consider that CustomResource to be a parent.
* Revert "Make toString and toJSON internal (#2489)"
This reverts commit 7579b84f73.
* Revert "Update error message to point at docs. (#2488)"
This reverts commit 9156c26a2e.
* Revert "Throw on Output.toString and toJSON (#2486)"
This reverts commit c33b4505c0.