feat: Ability to read a signal value without subscribing to it via th…

…e `peek` function.

README.md

@@ -191,6 +191,33 @@ $effect(() => console.log(counter.value));
 
 > ❗ DO NOT use `$effect` to update the signal value, as it will create an infinite loop.
 
+## Peeking at the signal value
+
+If the rare case that you have an effect that needs to read of a signal without subscribing to it, you can
+use the signal's `peek` function to read the value.
+
+```javascript
+import { $signal, $effect } from "c/signals";
+
+const counter = $signal(0);
+
+$effect(() => console.log(counter.peek()));
+```
+
+This can be useful when you need to update the value of a signal based on its current value, but you want
+to avoid causing a circular dependency.
+
+```javascript
+const counter = $signal(0);
+$effect(() => {
+  // Without peeking, this kind of operation would cause a circular dependency.
+  counter.value = counter.peek() + 1;
+});
+```
+
+Note that you should use this feature sparingly, as it can lead to bugs that are hard to track down.
+The preferred way of reading a signal is through the `signal.value`.
+
 ## Error Handling
 
 When unhandled errors occur in a `computed` or `effect`, by default, the error will be logged to the console through

src/lwc/signals/__tests__/effect.test.ts

@@ -62,4 +62,14 @@ describe("effects", () => {
 
     expect(customErrorHandlerFn).toHaveBeenCalled();
   });
+
+  test("can change and read a signal value without causing a cycle by peeking at it", () => {
+    const counter = $signal(0);
+    $effect(() => {
+      // Without peeking, this kind of operation would cause a circular dependency.
+      counter.value = counter.peek() + 1;
+    });
+
+    expect(counter.value).toBe(1);
+  });
 });

src/lwc/signals/__tests__/signals.test.ts

@@ -30,6 +30,14 @@ describe("signals", () => {
     const signal = $signal(0);
     expect(signal.brand).toBe(Symbol.for("lwc-signals"));
   });
+
+  test("allow for peeking the value without triggering a reactivity", () => {
+    const signal = $signal(0);
+    const spy = jest.fn(() => signal.value);
+    const value = signal.peek();
+    expect(spy).not.toHaveBeenCalled();
+    expect(value).toBe(0);
+  });
 });