@lwc/engine-core 8.28.1 → 9.0.0

package/dist/framework/decorators/wire.d.ts

@@ -1,20 +1,17 @@
 import type { LightningElement } from '../base-lightning-element';
-import type { ConfigValue, ContextValue, ReplaceReactiveValues, WireAdapterConstructor } from '../wiring';
+import type { ConfigValue, ConfigWithReactiveProps, 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: ClassFieldDecoratorContext<Class, Value | undefined> | ClassMethodDecoratorContext<Class, Value extends (value: any) => any ? Value : (this: Class, value: Value) => void> | ClassGetterDecoratorContext<Class, Value | undefined> | ClassSetterDecoratorContext<Class, Value>): void;
 }
 /**
  * Decorator factory to wire a property or method to a wire adapter data source.
+ *
+ * TypeScript users: Due to limitations of the type system, some edge cases are
+ * not fully type checked. See the type definition for {@linkcode ConfigWithReactiveProps}
+ * for details.
  * @param adapter the adapter used to provision data
  * @param config configuration object for the adapter
  * @returns A decorator function
@@ -24,9 +21,9 @@ interface WireDecorator<Value, Class> {
  *   \@wire(getBook, { id: '$bookId'}) book;
  * }
  */
-export default function wire<ReactiveConfig extends ConfigValue = ConfigValue, Value = any, Context extends ContextValue = ContextValue, Class = LightningElement>(adapter: WireAdapterConstructor<ReplaceReactiveValues<ReactiveConfig, Class>, Value, Context> | {
-    adapter: WireAdapterConstructor<ReplaceReactiveValues<ReactiveConfig, Class>, Value, Context>;
-}, config?: ReactiveConfig): WireDecorator<Value, Class>;
+export default function wire<const Config extends ConfigValue = ConfigValue, const Value = any, const Class = LightningElement>(adapter: WireAdapterConstructor<Config, Value> | {
+    adapter: WireAdapterConstructor<Config, Value>;
+}, config?: ConfigWithReactiveProps<Config, Class>): WireDecorator<Value, Class>;
 export declare function internalWireFieldDecorator(key: string): PropertyDescriptor;
 export {};
 //# sourceMappingURL=wire.d.ts.map

package/dist/framework/wiring/index.d.ts

@@ -1,4 +1,4 @@
 export { createContextProviderWithRegister, createContextWatcher } from './context';
-export { ConfigCallback, ConfigValue, ContextConsumer, ContextProvider, ContextProviderOptions, ContextValue, DataCallback, ReplaceReactiveValues, WireAdapter, WireAdapterConstructor, WireAdapterSchemaValue, WireContextSubscriptionPayload, WireContextSubscriptionCallback, } from './types';
+export type { ConfigCallback, ConfigValue, ConfigWithReactiveProps, ContextConsumer, ContextProvider, ContextProviderOptions, ContextValue, DataCallback, WireAdapter, WireAdapterConstructor, WireAdapterSchemaValue, WireContextSubscriptionPayload, WireContextSubscriptionCallback, } from './types';
 export { connectWireAdapters, disconnectWireAdapters, installWireAdapters, storeWiredFieldMeta, storeWiredMethodMeta, } from './wiring';
 //# sourceMappingURL=index.d.ts.map

package/dist/framework/wiring/types.d.ts

@@ -50,19 +50,84 @@ export interface ContextProviderOptions {
 }
 export type ContextProvider = (elmOrComponent: EventTarget, options: ContextProviderOptions) => void;
 export type RegisterContextProviderFn = (element: HostElement, 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}` ? FirstKey extends keyof Target ? ResolveReactiveValue<Target[FirstKey], Rest> : undefined : 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.
+ * Gets the property keys that can be used in a reactive string. Excludes symbols and string props
+ * with `.` (`$foo.bar` maps to `Class["foo"]["bar"]`; `Class["foo.bar"]` can never be used).
  */
-type ResolveValueIfReactive<Value, Target> = Value extends string ? string extends Value ? any : Value extends `$${infer Keys}` ? ResolveReactiveValue<Target, Keys> : Value : Value;
-export type ReplaceReactiveValues<Config extends ConfigValue, Component> = {
-    [K in keyof Config]: ResolveValueIfReactive<Config[K], Component>;
+type ReactivePropsOnly<K extends PropertyKey> = Exclude<K, symbol | `${string}.${string}`>;
+/** The string keys of an object that match the target type. */
+type PropsOfType<Class, Target> = ReactivePropsOnly<{
+    [K in keyof Class]-?: NonNullable<Class[K]> extends Target ? K : never;
+}[keyof Class]>;
+/** Gets the property keys that can be used in a reactive property chain. */
+type ChainableObjectProps<Class> = ReactivePropsOnly<{
+    [K in keyof Class]-?: NonNullable<Class[K]> extends object ? keyof NonNullable<Class[K]> extends never ? never : K : never;
+}[keyof Class]>;
+/**
+ * Extends a given wire adapter config with reactive property strings
+ * (for example, `$prop`) for values on the given class that match the config.
+ *
+ * Due to limitations of the type system, and to limit the size of the
+ * resulting type union, a number of restrictions apply to this type that can
+ * result in false positives or false negatives.
+ *
+ * - Config values with a `string` type inherently permit _any_ string,
+ *   even reactive strings that resolve to the wrong type.
+ * - Only top-level props are validated. Type checking is _not_ done on nested
+ *   property chains.
+ * - Property chains are allowed only if the top-level property is an object.
+ * - Property chains from `LightningElement` props are excluded.
+ *
+ * For property chains, a getter can be used to avoid incorrect error reporting,
+ * as top-level properties are always validated. Alternatively, a type assertion
+ * can be used to suppress the error.
+ *
+ * @example
+ * // Wire adapter with a required number prop and optional string prop
+ * declare const Adapter: WireAdapterConstructor<{ num: number; str?: string }>;
+ * declare class Component extends LightningElement {
+ *   numberProp = 6_7;
+ *   stringProp = '🙌';
+ *   objectProp?: { nestedStringProp: string };
+
+ *   \@wire(Adapter, { num: 123 }) validNumberValue?: unknown;
+ *   \@wire(Adapter, { num: "$numberProp" }) validNumberProp?: unknown;
+ *   \@wire(Adapter, { num: "bad value" }) invalidNumberValue?: unknown;
+ *   \@wire(Adapter, { num: "$stringProp" }) invalidNumberProp?: unknown;
+ *
+ *   \@wire(Adapter, { str: "valid string", num: 0 }) validStringValue?: unknown;
+ *   \@wire(Adapter, { str: "$stringProp", num: 0 }) validStringProp?: unknown;
+
+ *   // `"$numberProp"` is a string, and therefore satisfies the type,
+ *   // despite resolving to a number at runtime
+ *   \@wire(Adapter, { str: "$numberProp", num: 0 }) falseNegativeString?: unknown;
+ *
+ *   // Nested props aren't checked to avoid crashing on recursive types
+ *   \@wire(Adapter, { num: "$objectProp.nestedStringProp" }) falseNegativeNested?: unknown;
+ *
+ *   // Any value can have properties accessed at runtime, but property chains using
+ *   // non-objects are uncommon, and are excluded for simplicity
+ *   \@wire(Adapter, { num: "$stringProp.length" }) falsePositiveString?: unknown;
+ *
+ *   // Using props inherited from `LightningElement` for property chains is uncommon,
+ *   // and are excluded for simplicity
+ *   \@wire(Adapter, { num: "$hostElement.childElementCount" }) falsePositiveLightningElement?: unknown;
+ *
+ *   get propertyChainWorkaround(): string {
+ *     return this.objectProp.nestedStringProp;
+ *   }
+ *
+ *   // Top-level prop is type checked and correctly reports an error
+ *   \@wire(Adapter, { num: "$propertyChainWorkaround" }) truePositiveGetter?: unknown;
+ *
+ *   // Type assertion is used and correctly reports an error
+ *   \@wire(Adapter, {
+ *     num: "$objectProp.nestedStringProp" as unknown as Component["objectProp"]["nestedStringProp"]
+ *   }) truePositiveTypeAssertion?: unknown;
+ * }
+ */
+export type ConfigWithReactiveProps<Config extends ConfigValue, Class> = {
+    [K in keyof Config]: Config[K] | `$${PropsOfType<Class, Config[K]>}` | `$${ChainableObjectProps<Class>}.${string}`;
 };
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/index.js

@@ -2452,10 +2452,7 @@ function api$1(
 value, 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 context) {
-    if (process.env.NODE_ENV !== 'production') {
-        assert.fail(`@api decorator can only be used as a decorator function.`);
-    }
-    throw new Error();
+    assert.fail(`@api decorator can only be used as a decorator function.`);
 }
 function createPublicPropertyDescriptor(key) {
     return {
@@ -2535,10 +2532,7 @@ context) {
     if (arguments.length === 1) {
         return getReactiveProxy(target);
     }
-    if (process.env.NODE_ENV !== 'production') {
-        assert.fail(`@track decorator can only be used with one argument to return a trackable object, or as a decorator function.`);
-    }
-    throw new Error();
+    assert.fail(`@track decorator can only be used with one argument to return a trackable object, or as a decorator function.`);
 }
 function internalTrackDecorator(key) {
     return {
@@ -2578,6 +2572,10 @@ function internalTrackDecorator(key) {
  */
 /**
  * Decorator factory to wire a property or method to a wire adapter data source.
+ *
+ * TypeScript users: Due to limitations of the type system, some edge cases are
+ * not fully type checked. See the type definition for {@linkcode ConfigWithReactiveProps}
+ * for details.
  * @param adapter the adapter used to provision data
  * @param config configuration object for the adapter
  * @returns A decorator function
@@ -2592,10 +2590,7 @@ function wire(
 adapter, 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 config) {
-    if (process.env.NODE_ENV !== 'production') {
-        assert.fail('@wire(adapter, config?) may only be used as a decorator.');
-    }
-    throw new Error();
+    assert.fail('@wire(adapter, config?) may only be used as a decorator.');
 }
 function internalWireFieldDecorator(key) {
     return {
@@ -2641,7 +2636,7 @@ function validateObservedField(Ctor, fieldName, descriptor) {
     if (!isUndefined$1(descriptor)) {
         const type = getClassDescriptorType(descriptor);
         const message = `Invalid observed ${fieldName} field. Found a duplicate ${type} with the same name.`;
-        // TODO [#3408]: this should throw, not log
+        // TODO [#4450]: this should throw, not log
         logError(message);
     }
 }
@@ -2649,7 +2644,7 @@ function validateFieldDecoratedWithTrack(Ctor, fieldName, descriptor) {
     assertNotProd(); // this method should never leak to prod
     if (!isUndefined$1(descriptor)) {
         const type = getClassDescriptorType(descriptor);
-        // TODO [#3408]: this should throw, not log
+        // TODO [#4450]: this should throw, not log
         logError(`Invalid @track ${fieldName} field. Found a duplicate ${type} with the same name.`);
     }
 }
@@ -2657,14 +2652,14 @@ function validateFieldDecoratedWithWire(Ctor, fieldName, descriptor) {
     assertNotProd(); // this method should never leak to prod
     if (!isUndefined$1(descriptor)) {
         const type = getClassDescriptorType(descriptor);
-        // TODO [#3408]: this should throw, not log
+        // TODO [#4450]: this should throw, not log
         logError(`Invalid @wire ${fieldName} field. Found a duplicate ${type} with the same name.`);
     }
 }
 function validateMethodDecoratedWithWire(Ctor, methodName, descriptor) {
     assertNotProd(); // this method should never leak to prod
     if (isUndefined$1(descriptor) || !isFunction$1(descriptor.value) || isFalse(descriptor.writable)) {
-        // TODO [#3441]: This line of code does not seem possible to reach.
+        // TODO [#4450]: This line of code does not seem possible to reach.
         logError(`Invalid @wire ${methodName} field. The field should have a valid writable descriptor.`);
     }
 }
@@ -2673,7 +2668,7 @@ function validateFieldDecoratedWithApi(Ctor, fieldName, descriptor) {
     if (!isUndefined$1(descriptor)) {
         const type = getClassDescriptorType(descriptor);
         const message = `Invalid @api ${fieldName} field. Found a duplicate ${type} with the same name.`;
-        // TODO [#3408]: this should throw, not log
+        // TODO [#4450]: this should throw, not log
         logError(message);
     }
 }
@@ -2681,7 +2676,7 @@ function validateAccessorDecoratedWithApi(Ctor, fieldName, descriptor) {
     assertNotProd(); // this method should never leak to prod
     if (isFunction$1(descriptor.set)) {
         if (!isFunction$1(descriptor.get)) {
-            // TODO [#3441]: This line of code does not seem possible to reach.
+            // TODO [#4450]: This line of code does not seem possible to reach.
             logError(`Missing getter for property ${fieldName} decorated with @api in ${Ctor}. You cannot have a setter without the corresponding getter.`);
         }
     }
@@ -2767,7 +2762,7 @@ function registerDecorators(Ctor, meta) {
             if (method === 1) {
                 if (process.env.NODE_ENV !== 'production') {
                     if (!adapter) {
-                        // TODO [#3408]: this should throw, not log
+                        // TODO [#4450]: this should throw, not log
                         logError(`@wire on method "${fieldOrMethodName}": adapter id must be truthy.`);
                     }
                     validateMethodDecoratedWithWire(Ctor, fieldOrMethodName, descriptor);
@@ -2781,7 +2776,7 @@ function registerDecorators(Ctor, meta) {
             else {
                 if (process.env.NODE_ENV !== 'production') {
                     if (!adapter) {
-                        // TODO [#3408]: this should throw, not log
+                        // TODO [#4450]: this should throw, not log
                         logError(`@wire on field "${fieldOrMethodName}": adapter id must be truthy.`);
                     }
                     validateFieldDecoratedWithWire(Ctor, fieldOrMethodName, descriptor);
@@ -3323,6 +3318,9 @@ function evaluateStylesheetsContent(stylesheets, stylesheetToken, vm) {
 function getStylesheetsContent(vm, template) {
     const { stylesheets, stylesheetToken } = template;
     const { stylesheets: vmStylesheets } = vm;
+    if (!isUndefined$1(stylesheetToken) && !isValidScopeToken(stylesheetToken)) {
+        throw new Error('stylesheet token must be a valid string');
+    }
     const hasTemplateStyles = hasStyles(stylesheets);
     const hasVmStyles = hasStyles(vmStylesheets);
     if (hasTemplateStyles) {
@@ -5234,7 +5232,6 @@ function hasDynamicChildren(children) {
 }
 function createKeyToOldIdx(children, beginIdx, endIdx) {
     const map = {};
-    // TODO [#1637]: simplify this by assuming that all vnodes has keys
     for (let j = beginIdx; j <= endIdx; ++j) {
         const ch = children[j];
         if (isVNode(ch)) {
@@ -8766,5 +8763,5 @@ function readonly(obj) {
 }
 
 export { BaseBridgeElement, LightningElement, profilerControl as __unstable__ProfilerControl, reportingControl as __unstable__ReportingControl, api$1 as api, computeShadowAndRenderMode, connectRootElement, createContextProviderWithRegister, createVM, disconnectRootElement, freezeTemplate, getAssociatedVMIfPresent, getComponentAPIVersion, getComponentConstructor, getComponentDef, getComponentHtmlPrototype, hydrateRoot, isComponentConstructor, parseFragment, parseSVGFragment, readonly, registerComponent, registerDecorators, registerTemplate, runFormAssociatedCallback, runFormDisabledCallback, runFormResetCallback, runFormStateRestoreCallback, sanitizeAttribute, shouldBeFormAssociated, swapComponent, swapStyle, swapTemplate, track, unwrap, wire };
-/** version: 8.28.1 */
+/** version: 9.0.0 */
 //# sourceMappingURL=index.js.map

package/package.json

@@ -4,7 +4,7 @@
         "You can safely modify dependencies, devDependencies, keywords, etc., but other props will be overwritten."
     ],
     "name": "@lwc/engine-core",
-    "version": "8.28.1",
+    "version": "9.0.0",
     "description": "Core LWC engine APIs.",
     "keywords": [
         "lwc"
@@ -19,13 +19,17 @@
         "url": "https://github.com/salesforce/lwc/issues"
     },
     "license": "MIT",
+    "type": "module",
     "publishConfig": {
         "access": "public"
     },
+    "engines": {
+        "node": ">=16.6.0"
+    },
     "volta": {
         "extends": "../../../package.json"
     },
-    "main": "dist/index.cjs.js",
+    "main": "dist/index.js",
     "module": "dist/index.js",
     "types": "dist/index.d.ts",
     "files": [
@@ -46,9 +50,9 @@
         }
     },
     "dependencies": {
-        "@lwc/features": "8.28.1",
-        "@lwc/shared": "8.28.1",
-        "@lwc/signals": "8.28.1"
+        "@lwc/features": "9.0.0",
+        "@lwc/shared": "9.0.0",
+        "@lwc/signals": "9.0.0"
     },
     "devDependencies": {
         "observable-membrane": "2.0.0"