ripple 0.3.83 → 0.3.84

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # ripple
 
+## 0.3.84
+
+### Patch Changes
+
+- [`a5d1860`](https://github.com/Ripple-TS/ripple/commit/a5d18603beac4b15e99f9d23f4d0b18b67ffe413)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Adds snapshot() api for
+  non-reactive shallow copies of RippleArray and RippleObject
+- Updated dependencies
+  [[`cc3176b`](https://github.com/Ripple-TS/ripple/commit/cc3176b4e40021021986830bdfa3295530715432),
+  [`cc3176b`](https://github.com/Ripple-TS/ripple/commit/cc3176b4e40021021986830bdfa3295530715432)]:
+  - @tsrx/core@0.1.32
+  - @tsrx/ripple@0.1.32
+
 ## 0.3.83
 
 ### Patch Changes

package/package.json

@@ -3,7 +3,7 @@
   "description": "Ripple is an elegant TypeScript UI framework",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.3.83",
+  "version": "0.3.84",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -73,8 +73,8 @@
     "clsx": "^2.1.1",
     "devalue": "^5.8.1",
     "esm-env": "^1.2.2",
-    "@tsrx/core": "0.1.31",
-    "@tsrx/ripple": "0.1.31"
+    "@tsrx/core": "0.1.32",
+    "@tsrx/ripple": "0.1.32"
   },
   "devDependencies": {
     "@types/estree": "^1.0.8",

package/src/runtime/index-client.js

@@ -178,6 +178,8 @@ export {
 	peek_tracked as peek,
 } from './internal/client/runtime.js';
 
+export { snapshot } from './proxy.js';
+
 export { RippleArray } from './array.js';
 
 export { RippleObject } from './object.js';

package/src/runtime/index-server.js

@@ -17,6 +17,19 @@ export {
 } from './internal/client/constants.js';
 export { isRefProp } from '@tsrx/core/runtime/ref';
 
+/**
+ * Server values are never proxied, so a snapshot is just a shallow copy.
+ * @template {Iterable<unknown> | object} T
+ * @param {T} value
+ * @returns {T}
+ */
+export function snapshot(value) {
+	if (typeof value !== 'object' || value === null) {
+		return value;
+	}
+	return /** @type {T} */ (Array.isArray(value) ? [...value] : { ...value });
+}
+
 export const effect = noop;
 export const createRefKey = noop;
 export const on = noop;

package/src/runtime/proxy.js

@@ -1,7 +1,7 @@
 /** @import { Block, Tracked } from '#client' */
 /** @import { RippleArray, RippleObject } from '#public' */
 
-import { get, set, tracked } from './internal/client/runtime.js';
+import { get, set, tracked, untrack } from './internal/client/runtime.js';
 import {
 	array_prototype,
 	get_descriptor,
@@ -16,6 +16,22 @@ import {
 	UNINITIALIZED,
 } from './internal/client/constants.js';
 
+/**
+ * Returns a shallow, detached plain copy of a reactive array or object.
+ * Values are read without registering any reactivity.
+ *
+ * @template {Iterable<unknown> | object} T
+ * @param {T} value
+ * @returns {T}
+ */
+export function snapshot(value) {
+	if (typeof value !== 'object' || value === null) {
+		return value;
+	}
+
+	return untrack(() => /** @type {T} */ (is_array(value) ? [...value] : { ...value }));
+}
+
 /**
  * @template T
  * @param {T[] | Record<PropertyKey, any>} value

package/tests/client/object.test.tsrx

@@ -1,4 +1,4 @@
-import { RippleObject, flushSync } from 'ripple';
+import { RippleObject, effect, flushSync, snapshot } from 'ripple';
 import { TRACKED_OBJECT } from '../../src/runtime/internal/client/constants.js';
 
 describe('RippleObject', () => {
@@ -194,4 +194,50 @@ describe('RippleObject', () => {
 		expect(pre1.textContent).toBe('1');
 		expect(pre3.textContent).toBe('{"a":1,"b":1,"c":{"d":{"e":8}}}');
 	});
+
+	it('snapshot() returns a detached plain copy of current values', () => {
+		let snap: any;
+
+		function ObjectTest() @{
+			const obj = new RippleObject({ a: 1, b: 2 });
+			obj.a = 10;
+			snap = snapshot(obj);
+			// a later mutation must not affect the snapshot
+			obj.a = 99;
+			<div />
+		}
+
+		render(ObjectTest);
+
+		expect(snap).toEqual({ a: 10, b: 2 });
+		// detached: a plain object, not a proxy
+		expect(TRACKED_OBJECT in snap).toBe(false);
+		expect(snap.a).toBe(10);
+	});
+
+	it('snapshot() reads without registering reactivity', () => {
+		let runs = 0;
+
+		function ObjectTest() @{
+			const obj = new RippleObject({ a: 0 });
+			effect(() => {
+				snapshot(obj);
+				runs++;
+			});
+			<button
+				onClick={() => {
+					obj.a++;
+				}}
+			>{'Increment A'}</button>
+		}
+
+		render(ObjectTest);
+		flushSync();
+		expect(runs).toBe(1);
+
+		container.querySelectorAll('button')[0].click();
+		flushSync();
+		// snapshot did not subscribe, so the effect must not re-run
+		expect(runs).toBe(1);
+	});
 });

package/types/index.d.ts

@@ -69,6 +69,8 @@ export function tick(): Promise<void>;
 
 export function untrack<T>(fn: () => T): T;
 
+export function snapshot<T extends Iterable<unknown> | object>(value: T): T;
+
 export function flushSync<T>(fn?: () => T): T;
 
 export function effect(fn: (() => void) | (() => () => void)): void;