refactor(decorators): update decorator types @W-16373548@ (#4429)

* chore: hushsky

* feat(wire): ensure prop type matches adapter value

* fix(wire): account for reactive prop replacement

* feat(wire): drop experimental decorator signature

* refactor(api): only support modern decorators

also, only allow @api on LightningElement classes

* refactor(track): only support modern decorators

also, only allow on LightningElements

* refactor(wire): only support modern decorators

also, only allow on LightningElements

* refactor(integration-types): remove tests for experimental decorators

* docs: add comment explaining assertions

* refactor(playground): remove experimental decorator support

* refactor(integration-types): split decorator tests into multiple files

one file per decorator

* refactor(track): make function signature work as decorator and non-decorator

* refactor(wire): allow values to be undefined

* test(wire): expand type validations

* docs: simplify comment

* test(wire): expand type validations

* feat(wire): properly type reactive values

* test(wire): expand type validations

* test(decorators): validate type error when used on non-components

* refactor(wire): method param is never explicit undefined

* test(wire): split type validations into separate classes

* refactor(wire): @wire cannot be used on getters/setters

* test(wire): validate that nested props are not reactive

* fix(test): use correct context type

* docs: clarify comment

* revert(track): check arguments instead of undefined

* test(wire): validate wire doesn't work on non-component with superclass

* fix(wire): make wire work with adapters typed as `any`

* test(types): assert decorators don't work on non-LightningElement classes

* refactor(wire): remove type error if extending a non-component

TypeScript can't differentiate between a class without a superclass
and a class that extends `any`. Because extending `any` is probably
a fairly common use case (e.g. base components without a type stub),
we need to allow it, at the cost of also allowing non-extended classes.

* feat(wire): update signature to allow decorating getters/setters

* docs(wire): add comments to decorator type

* refactor(wire): update type def to always split on "."

runtime behavior is to use "." as a delimiter, never as part of the property key

* test(wire): update type validations for prop/method decorators

* test(wire): add type validations for decorated getters

* test(wire): add type validations for decorated setters

* feat(wire): allow undefined in wired getter

* refactor(decorators): relax type constraint restricting to LightningElement

Components could extend a superclass typed as `any`

* chore(decorators): remove useless generic type param

* docs(test): clarify use of nested.prop

* chore: prettier

packages/@lwc/engine-core/src/framework/decorators/api.ts

@@ -8,9 +8,9 @@ import { assert, isFunction, isNull, toString } from '@lwc/shared';
 import { logError } from '../../shared/logger';
 import { isInvokingRender, isBeingConstructed } from '../invoker';
 import { componentValueObserved, componentValueMutated } from '../mutation-tracker';
-import { LightningElement } from '../base-lightning-element';
 import { getAssociatedVM } from '../vm';
 import { isUpdatingTemplate, getVMBeingRendered } from '../template';
+import type { LightningElement } from '../base-lightning-element';
 
 /**
  * The `@api` decorator marks public fields and public methods in
@@ -21,7 +21,7 @@ export default function api(
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
  value: unknown,
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
- context: ClassMemberDecoratorContext | string | symbol
+ context: ClassMemberDecoratorContext
 ): void {
  if (process.env.NODE_ENV !== 'production') {
  assert.fail(`@api decorator can only be used as a decorator function.`);

packages/@lwc/engine-core/src/framework/decorators/track.ts

@@ -9,21 +9,23 @@ import { componentValueObserved } from '../mutation-tracker';
 import { isInvokingRender } from '../invoker';
 import { getAssociatedVM } from '../vm';
 import { getReactiveProxy } from '../membrane';
-import { LightningElement } from '../base-lightning-element';
 import { isUpdatingTemplate, getVMBeingRendered } from '../template';
 import { updateComponentValue } from '../update-component-value';
 import { logError } from '../../shared/logger';
+import type { LightningElement } from '../base-lightning-element';
 
 /**
  * The `@track` decorator function marks field values as reactive in
  * LWC Components. This function can also be invoked directly
  * with any value to obtain the trackable version of the value.
  */
+export default function track(target: undefined, context: ClassFieldDecoratorContext): void;
+export default function track<T>(target: T, context?: never): T;
 export default function track(
- value: unknown,
- context: ClassMemberDecoratorContext | string | symbol
-): void;
-export default function track<T>(target: T): T {
+ target: unknown,
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
+ context?: ClassFieldDecoratorContext
+): unknown {
  if (arguments.length === 1) {
  return getReactiveProxy(target);
  }

packages/@lwc/engine-core/src/framework/decorators/wire.ts

@@ -5,11 +5,47 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
  */
 import { assert } from '@lwc/shared';
-import { LightningElement } from '../base-lightning-element';
 import { componentValueObserved } from '../mutation-tracker';
 import { getAssociatedVM } from '../vm';
-import { WireAdapterConstructor } from '../wiring';
 import { updateComponentValue } from '../update-component-value';
+import type { LightningElement } from '../base-lightning-element';
+import type {
+ ConfigValue,
+ ContextValue,
+ ReplaceReactiveValues,
+ WireAdapterConstructor,
+} from '../wiring';
+
+/**
+ * The decorator returned by `@wire()`; not the `wire` function.
+ *
+ * For TypeScript users:
+ * - If you are seeing an unclear error message, ensure that both the type of the decorated prop and
+ * the config used match the types expected by the wire adapter.
+ * - String literal types in the config are resolved to the corresponding prop on the component.
+ * For example, a component with `id = 555` and `@wire(getBook, {id: "$id"} as const) book` will
+ * have `"$id"` resolve to type `number`.
+ */
+interface WireDecorator<Value, Class> {
+ (
+ target: unknown,
+ context: // A wired prop doesn't have any data on creation, so we must allow `undefined`
+ | ClassFieldDecoratorContext<Class, Value | undefined>
+ | ClassMethodDecoratorContext<
+ Class,
+ // When a wire adapter is typed as `WireAdapterConstructor`, then this `Value`
+ // generic is inferred as the value used by the adapter for all decorator contexts
+ // (field/method/getter/setter). But when the adapter is typed as `any`, then
+ // decorated methods have `Value` inferred as the full method. (I'm not sure why.)
+ // This conditional checks `Value` so that we get the correct decorator context.
+ Value extends (value: any) => any ? Value : (this: Class, value: Value) => void
+ >
+ // The implementation of a wired getter/setter is ignored; they are treated identically
+ // to wired props. Wired props don't have data on creation, so we must allow `undefined`
+ | ClassGetterDecoratorContext<Class, Value | undefined>
+ | ClassSetterDecoratorContext<Class, Value>
+ ): void;
+}
 
 /**
  * Decorator factory to wire a property or method to a wire adapter data source.
@@ -22,12 +58,17 @@ import { updateComponentValue } from '../update-component-value';
  * \@wire(getBook, { id: '$bookId'}) book;
  * }
  */
-export default function wire(
+export default function wire<
+ ReactiveConfig extends ConfigValue = ConfigValue,
+ Value = any,
+ Context extends ContextValue = ContextValue,
+ Class = LightningElement,
+>(
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
- adapter: WireAdapterConstructor,
+ adapter: WireAdapterConstructor<ReplaceReactiveValues<ReactiveConfig, Class>, Value, Context>,
  // eslint-disable-next-line @typescript-eslint/no-unused-vars
- config?: Record<string, any>
-): (value: unknown, context: ClassMemberDecoratorContext | string | symbol) => void {
+ config?: ReactiveConfig
+): WireDecorator<Value, Class> {
  if (process.env.NODE_ENV !== 'production') {
  assert.fail('@wire(adapter, config?) may only be used as a decorator.');
  }

packages/@lwc/engine-core/src/framework/wiring/index.ts

@@ -14,6 +14,7 @@ export {
  ContextProvider,
  ContextValue,
  DataCallback,
+ ReplaceReactiveValues,
  WireAdapter,
  WireAdapterConstructor,
  WireAdapterSchemaValue,

packages/@lwc/engine-core/src/framework/wiring/types.ts

@@ -87,3 +87,39 @@ export type RegisterContextProviderFn = (
  adapterContextToken: string,
  onContextSubscription: WireContextSubscriptionCallback
 ) => void;
+
+/** Resolves a property chain to the corresponding value on the target type. */
+type ResolveReactiveValue<
+ /** The object to search for properties; initially the component. */
+ Target,
+ /** A string representing a chain of of property keys, e.g. "data.user.name". */
+ Keys extends string,
+> = Keys extends `${infer FirstKey}.${infer Rest}`
+ ? // If the string is "a.b.c", check if "a" is a prop on the target object
+ FirstKey extends keyof Target
+ ? // If "a" exists on the target, check `target["a"]` for "b.c"
+ ResolveReactiveValue<Target[FirstKey], Rest>
+ : undefined
+ : // The string has no ".", use the full string as the key (e.g. we've reached "c" in "a.b.c")
+ Keys extends keyof Target
+ ? Target[Keys]
+ : undefined;
+
+/**
+ * Detects if the `Value` type is a property chain starting with "$". If so, it resolves the
+ * properties to the corresponding value on the target type.
+ */
+type ResolveValueIfReactive<Value, Target> = Value extends string
+ ? string extends Value // `Value` is type `string`
+ ? // Workaround for not being able to enforce `as const` assertions -- we don't know if this
+ // is a true string value (e.g. `@wire(adapter, {val: 'str'})`) or if it's a reactive prop
+ // (e.g. `@wire(adapter, {val: '$number'})`), so we have to go broad to avoid type errors.
+ any
+ : Value extends `$${infer Keys}` // String literal starting with "$", e.g. `$prop`
+ ? ResolveReactiveValue<Target, Keys>
+ : Value // String literal *not* starting with "$", e.g. `"hello world"`
+ : Value; // non-string type
+
+export type ReplaceReactiveValues<Config extends ConfigValue, Component> = {
+ [K in keyof Config]: ResolveValueIfReactive<Config[K], Component>;
+};

packages/@lwc/integration-types/package.json

@@ -5,8 +5,7 @@
  "description": "Type validation for LWC packages",
  "type": "module",
  "scripts": {
- "test": "node ./scripts/update-paths.js --check && tsc && yarn run test:experimental-decorators",
- "test:experimental-decorators": "tsc -p tsconfig.experimental-decorators.json",
+ "test": "node ./scripts/update-paths.js --check && tsc",
  "playground": "rollup -c src/playground/rollup.config.js --watch"
  },
  "dependencies": {

packages/@lwc/integration-types/src/decorators/api.ts

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+
+import { LightningElement, api } from 'lwc';
+
+// @ts-expect-error bare decorator cannot be used
+api();
+
+// @ts-expect-error decorator doesn't work on classes
+@api
+export default class Test extends LightningElement {
+ @api optionalProperty?: string;
+ @api propertyWithDefault = true;
+ @api nonNullAssertedProperty!: object;
+ @api method() {}
+ @api getter(): undefined {}
+ @api setter(_: string) {}
+}

packages/@lwc/integration-types/src/decorators/track.ts

@@ -0,0 +1,31 @@
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+
+import { LightningElement, track } from 'lwc';
+
+// This is okay! track has a non-decorator signature
+track(123);
+// This is okay because we treat implicit and explicit `undefined` identically
+track(123, undefined);
+// @ts-expect-error wrong number of arguments
+track();
+// @ts-expect-error wrong number of arguments
+track({}, {});
+
+// @ts-expect-error doesn't work on classes
+@track
+export default class Test extends LightningElement {
+ @track optionalProperty?: string;
+ @track propertyWithDefault = true;
+ @track nonNullAssertedProperty!: object;
+ // @ts-expect-error cannot be used on methods
+ @track method() {}
+ // @ts-expect-error cannot be used on getters
+ @track getter(): undefined {}
+ // @ts-expect-error cannot be used on setters
+ @track setter(_: string) {}
+}