feat: signals implementation v1

packages/@lwc/engine-core/package.json

@@ -46,6 +46,7 @@
         "@lwc/shared": "6.0.0"
     },
     "devDependencies": {
-        "observable-membrane": "2.0.0"
+        "observable-membrane": "2.0.0",
+        "@lwc/signals": "6.0.0"
     }
 }

packages/@lwc/engine-core/src/framework/component.ts

@@ -13,7 +13,11 @@ import {
     LOWEST_API_VERSION,
 } from '@lwc/shared';
 
-import { createReactiveObserver, ReactiveObserver } from './mutation-tracker';
+import {
+    createReactiveObserver,
+    ReactiveObserver,
+    unsubscribeFromSignals,
+} from './mutation-tracker';
 
 import { invokeComponentRenderMethod, isInvokingRender, invokeEventListener } from './invoker';
 import { VM, scheduleRehydration } from './vm';
@@ -92,6 +96,9 @@ export function renderComponent(vm: VM): VNodes {
     }
 
     vm.tro.reset();
+    if (lwcRuntimeFlags.ENABLE_EXPERIMENTAL_SIGNALS) {
+        unsubscribeFromSignals(vm.component);
+    }
     const vnodes = invokeComponentRenderMethod(vm);
     vm.isDirty = false;
     vm.isScheduled = false;

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

@@ -40,8 +40,9 @@ export function createPublicPropertyDescriptor(key: string): PropertyDescriptor
                 }
                 return;
             }
-            componentValueObserved(vm, key);
-            return vm.cmpProps[key];
+            const val = vm.cmpProps[key];
+            componentValueObserved(vm, key, val);
+            return val;
         },
         set(this: LightningElement, newValue: any) {
             const vm = getAssociatedVM(this);

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

@@ -40,8 +40,9 @@ export function internalTrackDecorator(key: string): PropertyDescriptor {
     return {
         get(this: LightningElement): any {
             const vm = getAssociatedVM(this);
-            componentValueObserved(vm, key);
-            return vm.cmpFields[key];
+            const val = vm.cmpFields[key];
+            componentValueObserved(vm, key, val);
+            return val;
         },
         set(this: LightningElement, newValue: any) {
             const vm = getAssociatedVM(this);

packages/@lwc/engine-core/src/framework/mutation-tracker.ts

@@ -11,6 +11,7 @@ import {
     valueMutated,
     valueObserved,
 } from '../libs/mutation-tracker';
+import { subscribeToSignal } from '../libs/signal-tracker';
 import { VM } from './vm';
 
 const DUMMY_REACTIVE_OBSERVER = {
@@ -28,10 +29,29 @@ export function componentValueMutated(vm: VM, key: PropertyKey) {
     }
 }
 
-export function componentValueObserved(vm: VM, key: PropertyKey) {
+export function componentValueObserved(vm: VM, key: PropertyKey, target: any = {}) {
+    const { component, tro } = vm;
     // On the server side, we don't need mutation tracking. Skipping it improves performance.
     if (process.env.IS_BROWSER) {
-        valueObserved(vm.component, key);
+        valueObserved(component, key);
+    }
+
+    // The portion of reactivity that's exposed to signals is to subscribe a callback to re-render the VM (templates).
+    // We check check the following to ensure re-render is subscribed at the correct time.
+    //  1. The template is currently being rendered (there is a template reactive observer)
+    //  2. There was a call to a getter to access the signal (happens during vnode generation)
+    if (
+        lwcRuntimeFlags.ENABLE_EXPERIMENTAL_SIGNALS &&
+        target &&
+        typeof target === 'object' &&
+        'value' in target &&
+        'subscribe' in target &&
+        typeof target.subscribe === 'function' &&
+        // Only subscribe if a template is being rendered by the engine
+        tro.isObserving()
+    ) {
+        // Subscribe the template reactive observer's notify method, which will mark the vm as dirty and schedule hydration.
+        subscribeToSignal(component, target, tro.notify.bind(tro));
     }
 }
 
@@ -41,3 +61,4 @@ export function createReactiveObserver(callback: CallbackFunction): ReactiveObse
 }
 
 export * from '../libs/mutation-tracker';
+export * from '../libs/signal-tracker';

packages/@lwc/engine-core/src/framework/observed-fields.ts

@@ -13,8 +13,9 @@ export function createObservedFieldPropertyDescriptor(key: string): PropertyDesc
     return {
         get(this: LightningElement): any {
             const vm = getAssociatedVM(this);
-            componentValueObserved(vm, key);
-            return vm.cmpFields[key];
+            const val = vm.cmpFields[key];
+            componentValueObserved(vm, key, val);
+            return val;
         },
         set(this: LightningElement, newValue: any) {
             const vm = getAssociatedVM(this);

packages/@lwc/engine-core/src/framework/vm.ts

@@ -51,7 +51,7 @@ import {
     logGlobalOperationStart,
 } from './profiler';
 import { patchChildren } from './rendering';
-import { ReactiveObserver } from './mutation-tracker';
+import { ReactiveObserver, unsubscribeFromSignals } from './mutation-tracker';
 import { connectWireAdapters, disconnectWireAdapters, installWireAdapters } from './wiring';
 import {
     VNodes,
@@ -272,9 +272,12 @@ function resetComponentStateWhenRemoved(vm: VM) {
     const { state } = vm;
 
     if (state !== VMState.disconnected) {
-        const { tro } = vm;
+        const { tro, component } = vm;
         // Making sure that any observing record will not trigger the rehydrated on this vm
         tro.reset();
+        if (lwcRuntimeFlags.ENABLE_EXPERIMENTAL_SIGNALS) {
+            unsubscribeFromSignals(component);
+        }
         runDisconnectedCallback(vm);
         // Spec: https://dom.spec.whatwg.org/#concept-node-remove (step 14-15)
         runChildNodesDisconnectedCallback(vm);

packages/@lwc/engine-core/src/libs/mutation-tracker/index.ts

@@ -125,4 +125,8 @@ export class ReactiveObserver {
         // we keep track of observing records where the observing record was added to so we can do some clean up later on
         ArrayPush.call(this.listeners, reactiveObservers);
     }
+
+    isObserving() {
+        return currentReactiveObserver === this;
+    }
 }

packages/@lwc/engine-core/src/libs/signal-tracker/index.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2024, salesforce.com, 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 { isFalse, isUndefined } from '@lwc/shared';
+import { Signal } from '@lwc/signals';
+import { logWarnOnce } from '../../shared/logger';
+
+/**
+ * This map keeps track of objects to signals. There is an assumption that the signal is strongly referenced
+ * on the object which allows the SignalTracker to be garbage collected along with the object.
+ */
+const TargetToSignalTrackerMap: WeakMap<Object, SignalTracker> = new WeakMap();
+
+function getSignalTracker(target: Object) {
+    let signalTracker = TargetToSignalTrackerMap.get(target);
+    if (isUndefined(signalTracker)) {
+        signalTracker = new SignalTracker();
+        TargetToSignalTrackerMap.set(target, signalTracker);
+    }
+    return signalTracker;
+}
+
+export function subscribeToSignal(
+    target: Object,
+    signal: Signal<unknown>,
+    update: CallbackFunction
+) {
+    const signalTracker = getSignalTracker(target);
+    if (isFalse(signalTracker.seen(signal))) {
+        signalTracker.subscribeToSignal(signal, update);
+    }
+}
+
+export function unsubscribeFromSignals(target: Object) {
+    if (TargetToSignalTrackerMap.has(target)) {
+        const signalTracker = getSignalTracker(target);
+        signalTracker.unsubscribeFromSignals();
+        signalTracker.reset();
+    }
+}
+
+type CallbackFunction = () => void;
+
+/**
+ * This class is used to keep track of the signals associated to a given object.
+ * It is used to prevent the LWC engine from subscribing duplicate callbacks multiple times
+ * to the same signal. Additionally, it keeps track of all signal unsubscribe callbacks, handles invoking
+ * them when necessary and discarding them.
+ */
+class SignalTracker {
+    private signalToUnsubscribeMap: Map<Signal<unknown>, CallbackFunction> = new Map();
+
+    seen(signal: Signal<unknown>) {
+        return this.signalToUnsubscribeMap.has(signal);
+    }
+
+    subscribeToSignal(signal: Signal<unknown>, update: CallbackFunction) {
+        try {
+            const unsubscribe = signal.subscribe(update);
+            this.signalToUnsubscribeMap.set(signal, unsubscribe);
+        } catch (err) {
+            logWarnOnce(
+                `Attempted to subscribe to an object that has the shape of a signal but received the following error: ${err}`
+            );
+        }
+    }
+
+    unsubscribeFromSignals() {
+        try {
+            this.signalToUnsubscribeMap.forEach((unsubscribe) => unsubscribe());
+        } catch (err) {
+            logWarnOnce(
+                `Attempted to call a signal's unsubscribe callback but received the following error: ${err}`
+            );
+        }
+    }
+
+    reset() {
+        this.signalToUnsubscribeMap.clear();
+    }
+}

packages/@lwc/features/src/index.ts

@@ -19,6 +19,7 @@ const features: FeatureFlagMap = {
     ENABLE_FROZEN_TEMPLATE: null,
     ENABLE_LEGACY_SCOPE_TOKENS: null,
     ENABLE_FORCE_SHADOW_MIGRATE_MODE: null,
+    ENABLE_EXPERIMENTAL_SIGNALS: null,
 };
 
 // eslint-disable-next-line no-restricted-properties

packages/@lwc/features/src/types.ts

@@ -69,6 +69,12 @@ export interface FeatureFlagMap {
      * If true, enable experimental shadow DOM migration mode globally.
      */
     ENABLE_FORCE_SHADOW_MIGRATE_MODE: FeatureFlagValue;
+
+    /**
+     * EXPERIMENTAL FEATURE, DO NOT USE IN PRODUCTION
+     * If true, allows the engine to expose reactivity to signals as describe in @lwc/signals.
+     */
+    ENABLE_EXPERIMENTAL_SIGNALS: FeatureFlagValue;
 }
 
 export type FeatureFlagName = keyof FeatureFlagMap;

packages/@lwc/signals/README.md

@@ -0,0 +1,75 @@
+# @lwc/signals
+
+This is an experimental package containing the interface expected for signals.
+
+A key point to note is that when a signal is both bound to an LWC class member variable and used on a template,
+the LWC engine will attempt to subscribe a callback to rerender the template.
+
+## Reactivity with Signals
+
+A Signal is an object that holds a value and allows components to react to changes to that value.
+It exposes a `.value` property for accessing the current value, and `.subscribe` methods for responding to changes.
+
+```js
+import { signal } from 'some/signals';
+
+export default class ExampleComponent extends LightningElement {
+    count = signal(0);
+
+    increment() {
+        this.count.value++;
+    }
+}
+```
+
+In the template, we can bind directly to the `.value` property:
+
+```html
+<template>
+    <button onclick="{increment}">Increment</button>
+    <p>{count.value}</p>
+</template>
+```
+
+## Supported APIs
+
+This package supports the following APIs.
+
+### Signal
+
+This is the shape of the signal that the LWC engine expects.
+
+```js
+export type OnUpdate = () => void;
+export type Unsubscribe = () => void;
+
+export interface Signal<T> {
+    get value(): T;
+    subscribe(onUpdate: OnUpdate): Unsubscribe;
+}
+```
+
+### SignalBaseClass
+
+A base class is provided as a starting point for implementation.
+
+```js
+export abstract class SignalBaseClass<T> implements Signal<T> {
+    abstract get value(): T;
+
+    private subscribers: Set<OnUpdate> = new Set();
+
+    subscribe(onUpdate: OnUpdate) {
+        this.subscribers.add(onUpdate);
+        return () => {
+            this.subscribers.delete(onUpdate);
+        };
+    }
+
+    protected notify() {
+        for (const subscriber of this.subscribers) {
+            subscriber();
+        }
+    }
+}
+```

packages/@lwc/signals/jest.config.js

@@ -0,0 +1,12 @@
+/*
+ * Copyright (c) 2018, salesforce.com, 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
+ */
+const BASE_CONFIG = require('../../../scripts/jest/base.config');
+
+module.exports = {
+    ...BASE_CONFIG,
+    displayName: 'lwc-signals',
+};

packages/@lwc/signals/package.json

@@ -0,0 +1,44 @@
+{
+    "//": [
+        "THIS FILE IS AUTOGENERATED. If you modify it, it will be rewritten by check-and-rewrite-package-json.js",
+        "You can safely modify dependencies, devDependencies, keywords, etc., but other props will be overwritten."
+    ],
+    "name": "@lwc/signals",
+    "version": "6.0.0",
+    "description": "Provides the protocol to to expose reactivity outside of the LWC framework",
+    "keywords": [
+        "lwc"
+    ],
+    "homepage": "https://lwc.dev",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/salesforce/lwc.git",
+        "directory": "packages/@lwc/signals"
+    },
+    "bugs": {
+        "url": "https://github.com/salesforce/lwc/issues"
+    },
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "main": "dist/index.cjs.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "rollup --config ../../../scripts/rollup/rollup.config.js",
+        "dev": "rollup  --config ../../../scripts/rollup/rollup.config.js --watch --no-watch.clearScreen"
+    },
+    "nx": {
+        "targets": {
+            "build": {
+                "outputs": [
+                    "{projectRoot}/dist"
+                ]
+            }
+        }
+    }
+}