ripple 0.3.128 → 0.4.0

package/tests/server/track-async-serialization.test.tsrx

@@ -1,14 +1,17 @@
 import { DEV } from 'esm-env';
-import { trackAsync } from 'ripple';
+import { setTransport, track, trackAsync } from 'ripple';
+import * as devalue from 'devalue';
 
 const TRACK_ASYNC_PUBLIC_ERROR_MESSAGE = 'An error occurred during async rendering';
 
 describe('trackAsync serialization (server)', () => {
+	afterEach(() => setTransport());
+
 	it('serializes resolved trackAsync data as a script tag in SSR output', async () => {
 		function App() @{
 			@try {
-				let &[data] = trackAsync(() => Promise.resolve('hello world'));
-				<p class="result">{data}</p>
+				const data = trackAsync(() => Promise.resolve('hello world'));
+				<p class="result">{data.value}</p>
 			} @pending {
 				<p class="loading">{'loading...'}</p>
 			}
@@ -24,8 +27,8 @@ describe('trackAsync serialization (server)', () => {
 	it('serializes numeric trackAsync data correctly', async () => {
 		function App() @{
 			@try {
-				let &[count] = trackAsync(() => Promise.resolve(42));
-				<span class="count">{count}</span>
+				const count = trackAsync(() => Promise.resolve(42));
+				<span class="count">{count.value}</span>
 			} @pending {
 				<span>{'...'}</span>
 			}
@@ -39,8 +42,8 @@ describe('trackAsync serialization (server)', () => {
 	it('serializes object trackAsync data correctly', async () => {
 		function App() @{
 			@try {
-				let &[data] = trackAsync(() => Promise.resolve({ name: 'Alice', age: 30 }));
-				<p>{data.name}</p>
+				const data = trackAsync(() => Promise.resolve({ name: 'Alice', age: 30 }));
+				<p>{data.value.name}</p>
 			} @pending {
 				<p>{'...'}</p>
 			}
@@ -54,9 +57,9 @@ describe('trackAsync serialization (server)', () => {
 	it('serializes array trackAsync data correctly', async () => {
 		function App() @{
 			@try {
-				let &[items] = trackAsync(() => Promise.resolve(['a', 'b', 'c']));
+				const items = trackAsync(() => Promise.resolve(['a', 'b', 'c']));
 				<ul>
-					@for (let item of items) {
+					@for (let item of items.value) {
 						<li>{item}</li>
 					}
 				</ul>
@@ -73,8 +76,8 @@ describe('trackAsync serialization (server)', () => {
 	it('serializes rejected trackAsync as error envelope', async () => {
 		function App() @{
 			@try {
-				let &[data] = trackAsync(() => Promise.reject(new Error('fetch failed')));
-				<p class="result">{data}</p>
+				const data = trackAsync(() => Promise.reject(new Error('fetch failed')));
+				<p class="result">{data.value}</p>
 			} @pending {
 				<p class="loading">{'loading...'}</p>
 			} @catch (e) {
@@ -93,8 +96,8 @@ describe('trackAsync serialization (server)', () => {
 	it('serializes error when child component error bubbles to parent catch', async () => {
 		function Child() @{
 			@try {
-				let &[data] = trackAsync(() => Promise.reject(new Error('child error')));
-				<p class="result">{data}</p>
+				const data = trackAsync(() => Promise.reject(new Error('child error')));
+				<p class="result">{data.value}</p>
 			} @pending {
 				<p class="pending">{'loading...'}</p>
 			}
@@ -119,10 +122,10 @@ describe('trackAsync serialization (server)', () => {
 	it('serializes sync trackAsync throw using original cause message', async () => {
 		function App() @{
 			@try {
-				let &[data] = trackAsync(() => {
+				const data = trackAsync(() => {
 					throw new Error('sync failure');
 				});
-				<p class="result">{data}</p>
+				<p class="result">{data.value}</p>
 			} @pending {
 				<p class="loading">{'loading...'}</p>
 			} @catch (e) {
@@ -139,13 +142,193 @@ describe('trackAsync serialization (server)', () => {
 		expect(body).not.toContain('Error thrown during trackAsync execution');
 	});
 
+	describe('hydration envelope dependencies', () => {
+		/** @param {'direct' | 'view'} read */
+		async function deps_for(read: 'direct' | 'view') {
+			function App() @{
+				const count = track(3);
+				const view = count.readOnly();
+				@try {
+					const data = trackAsync(
+						() => Promise.resolve(`count-${read === 'view' ? view.value : count.value}`),
+					);
+					<p>{data.value}</p>
+				} @pending {
+					<p>{'...'}</p>
+				}
+			}
+
+			const { body } = await render(App);
+			const match = body.match(
+				/<script id="__ripple_ta_[a-f0-9]+" type="application\/json">(.*?)<\/script>/s,
+			);
+			expect(match).not.toBeNull();
+			return JSON.parse(/** @type {RegExpMatchArray} */ (match)[1]).deps;
+		}
+
+		it('records the tracked a trackAsync read directly', async () => {
+			expect(await deps_for('direct')).toHaveLength(1);
+		});
+
+		it('records the tracked behind a readOnly() view a trackAsync read', async () => {
+			// The view itself has no hash; the client must still re-subscribe to
+			// the source after hydration, so its hash is what gets recorded.
+			expect(await deps_for('view')).toEqual(await deps_for('direct'));
+		});
+	});
+
+	describe('hydration envelope encoding', () => {
+		async function envelope_for(value: unknown) {
+			function App() @{
+				@try {
+					const data = trackAsync(() => Promise.resolve(value));
+					<p>{String(data.value !== undefined)}</p>
+				} @pending {
+					<p>{'...'}</p>
+				}
+			}
+
+			const { body } = await render(App);
+			const match = body.match(
+				/<script id="__ripple_ta_[a-f0-9]+" type="application\/json">(.*?)<\/script>/s,
+			);
+			expect(match).not.toBeNull();
+			const text = /** @type {RegExpMatchArray} */ (match)[1];
+			expect(text).not.toContain('<');
+			return JSON.parse(text);
+		}
+
+		it('ships plain data trees as raw JSON', async () => {
+			const value = {
+				title: 'Card 0 — "alpha" \\ <b>&</b>',
+				count: 3,
+				ratio: 0.5,
+				ok: true,
+				none: null,
+				items: [{ label: 'a\nb', value: 'tab\there' }, ['x', 1, false], '😀 '],
+				'odd key': { nested: [] },
+			};
+			const envelope = await envelope_for(value);
+			expect(envelope.ok).toBe(true);
+			expect(envelope.payload).toBeUndefined();
+			expect(envelope.value).toEqual(value);
+		});
+
+		it('ships primitives as raw JSON', async () => {
+			expect((await envelope_for('hello')).value).toBe('hello');
+			expect((await envelope_for('lone � surrogate')).value).toBe('lone � surrogate');
+			expect((await envelope_for(42)).value).toBe(42);
+			expect((await envelope_for(false)).value).toBe(false);
+			expect((await envelope_for(null)).value).toBe(null);
+		});
+
+		it('keeps the devalue encoding for values JSON cannot represent', async () => {
+			const shared = { n: 1 };
+			const cyclic: { self?: unknown } = {};
+			cyclic.self = cyclic;
+			for (const value of [
+				undefined,
+				NaN,
+				Infinity,
+				-0,
+				10n,
+				new Date(0),
+				new Map([[1, 2]]),
+				new Set([1]),
+				/re/,
+				Object.create(null),
+				{ a: undefined },
+				{ a: shared, b: shared },
+				[shared, shared],
+				cyclic,
+				// eslint-disable-next-line no-sparse-arrays
+				[1, , 3],
+			]) {
+				const envelope = await envelope_for(value);
+				expect(envelope.value).toBeUndefined();
+				expect(typeof envelope.payload).toBe('string');
+			}
+		});
+
+		it('keeps the raw JSON path for an empty transport', async () => {
+			setTransport({});
+			const value = { title: 'Card', items: [1, true, null] };
+			expect(await envelope_for(value)).toEqual({ ok: true, value });
+		});
+
+		it('serializes custom classes and preserves shared references', async () => {
+			class Money {
+				amount: number;
+				currency: string;
+				constructor(amount: number, currency: string) {
+					this.amount = amount;
+					this.currency = currency;
+				}
+			}
+			const decode = ([amount, currency]: [number, string]) => new Money(amount, currency);
+			setTransport({
+				Money: {
+					encode: (value) => value instanceof Money && [value.amount, value.currency],
+					decode,
+				},
+			});
+			const money = new Money(12, '</script><script>injected</script>');
+			const envelope = await envelope_for({ first: money, second: money, date: new Date(0) });
+			expect(envelope.value).toBeUndefined();
+			const restored = devalue.unflatten(envelope.payload, { Money: decode });
+			expect(restored.first).toBeInstanceOf(Money);
+			expect(restored.first).toEqual(money);
+			expect(restored.second).toBe(restored.first);
+			expect(restored.date).toEqual(new Date(0));
+		});
+
+		it('lets reducers claim plain objects without first walking the JSON path', async () => {
+			const read_amount = vi.fn(() => 12);
+			const encode = vi.fn((value: any) => value?.__type === 'Money' && [value.amount]);
+			const decode = ([amount]: [number]) => ({ amount, revived: true });
+			setTransport({ Money: { encode, decode } });
+			const value = {
+				nested: {
+					__type: 'Money',
+					get amount() {
+						return read_amount();
+					},
+				},
+			};
+			const envelope = await envelope_for(value);
+			expect(envelope.value).toBeUndefined();
+			expect(devalue.unflatten(envelope.payload, { Money: decode })).toEqual({
+				nested: { amount: 12, revived: true },
+			});
+			expect(encode.mock.calls.filter(([node]) => node === value.nested)).toHaveLength(1);
+			expect(read_amount).toHaveBeenCalledTimes(1);
+		});
+
+		it(
+			'uses devalue for plain data under an unused transport and restores JSON after reset',
+			async () => {
+				setTransport({ Unused: { encode: () => undefined, decode: (value) => value } });
+				const value = { title: 'Card', items: [1, true, null] };
+				const envelope = await envelope_for(value);
+				expect(envelope.value).toBeUndefined();
+				expect(devalue.unflatten(envelope.payload)).toEqual(value);
+				for (const special of [undefined, NaN, Infinity, -Infinity, -0, 10n, new Date(0)]) {
+					const encoded = await envelope_for(special);
+					expect(devalue.unflatten(encoded.payload)).toEqual(special);
+				}
+				setTransport();
+				expect(await envelope_for(value)).toEqual({ ok: true, value });
+			},
+		);
+	});
+
 	it('escapes serialized error payload to keep script tag safe', async () => {
 		function App() @{
 			@try {
-				let &[data] = trackAsync(
+				const data = trackAsync(
 					() => Promise.reject(new Error('</script><div data-injected="1">boom</div>')),
 				);
-				<p class="result">{data}</p>
+				<p class="result">{data.value}</p>
 			} @pending {
 				<p class="loading">{'loading...'}</p>
 			} @catch (e) {
@@ -166,11 +349,11 @@ describe('trackAsync serialization (server)', () => {
 	it('generates unique hashes for multiple trackAsync calls', async () => {
 		function App() @{
 			@try {
-				let &[a] = trackAsync(() => Promise.resolve('first'));
-				let &[b] = trackAsync(() => Promise.resolve('second'));
+				const a = trackAsync(() => Promise.resolve('first'));
+				const b = trackAsync(() => Promise.resolve('second'));
 				<>
-					<p>{a}</p>
-					<p>{b}</p>
+					<p>{a.value}</p>
+					<p>{b.value}</p>
 				</>
 			} @pending {
 				<p>{'...'}</p>

package/tests/server/try.test.tsrx

@@ -3,8 +3,8 @@ import { trackAsync } from 'ripple';
 describe('try block with catch and pending (server)', () => {
 	it('renders resolved content with an empty pending fallback', async () => {
 		function DataChild() @{
-			let &[data] = trackAsync(() => Promise.resolve('resolved value'));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.resolve('resolved value'));
+			<p>{data.value}</p>
 		}
 
 		function App() @{
@@ -47,9 +47,9 @@ describe('try block with catch and pending (server)', () => {
 
 	it('catch block works when component throws after await with pending block', async () => {
 		function ThrowingAfterAwait() @{
-			let &[data] = trackAsync(() => Promise.resolve('hello'));
+			const data = trackAsync(() => Promise.resolve('hello'));
 			throw new Error('error after await');
-			<p>{data}</p>
+			<p>{data.value}</p>
 		}
 
 		function App() @{
@@ -70,8 +70,8 @@ describe('try block with catch and pending (server)', () => {
 	it('catch block works with try/catch/pending when async body rejects', async () => {
 		function App() @{
 			@try {
-				let &[data] = trackAsync(() => Promise.reject(new Error('rejected')));
-				<p>{data}</p>
+				const data = trackAsync(() => Promise.reject(new Error('rejected')));
+				<p>{data.value}</p>
 			} @pending {
 				<p>{'loading...'}</p>
 			} @catch (err) {
@@ -88,8 +88,8 @@ describe('try block with catch and pending (server)', () => {
 		function App() @{
 			@try {
 				@try {
-					let &[data] = trackAsync(() => Promise.resolve('resolved'));
-					<p>{data}</p>
+					const data = trackAsync(() => Promise.resolve('resolved'));
+					<p>{data.value}</p>
 				} @pending {
 					<p>{'inner loading...'}</p>
 				}
@@ -116,8 +116,8 @@ describe('trackAsync directly in component body (server)', () => {
 		}
 
 		function DataChild() @{
-			let &[data] = trackAsync(() => Promise.resolve('from child'));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.resolve('from child'));
+			<p>{data.value}</p>
 		}
 
 		const { body } = await render(App);
@@ -128,12 +128,12 @@ describe('trackAsync directly in component body (server)', () => {
 	it('resolves multiple trackAsync values in the same component', async () => {
 		function App() @{
 			@try {
-				let &[a] = trackAsync(() => Promise.resolve('hello'));
-				let &[b] = trackAsync(() => Promise.resolve('world'));
+				const a = trackAsync(() => Promise.resolve('hello'));
+				const b = trackAsync(() => Promise.resolve('world'));
 				<p>
-					{a}
+					{a.value}
 					{' '}
-					{b}
+					{b.value}
 				</p>
 			} @catch (err) {
 				<p>{'error'}</p>
@@ -147,8 +147,8 @@ describe('trackAsync directly in component body (server)', () => {
 
 	it('renders catch when trackAsync rejects in a child component without its own try', async () => {
 		function RejectChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('child rejected')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('child rejected')));
+			<p>{data.value}</p>
 		}
 
 		function App() @{
@@ -166,12 +166,12 @@ describe('trackAsync directly in component body (server)', () => {
 	it('chained trackAsync resolves both values', async () => {
 		function App() @{
 			@try {
-				let &[name] = trackAsync(() => Promise.resolve('ripple'));
-				let &[upper] = trackAsync(() => {
-					const n = name;
+				const name = trackAsync(() => Promise.resolve('ripple'));
+				const upper = trackAsync(() => {
+					const n = name.value;
 					return Promise.resolve(n.toUpperCase());
 				});
-				<p>{upper}</p>
+				<p>{upper.value}</p>
 			} @catch (err) {
 				<p>{'error'}</p>
 			}
@@ -185,12 +185,12 @@ describe('trackAsync directly in component body (server)', () => {
 	it('chained trackAsync catches when first rejects', async () => {
 		function App() @{
 			@try {
-				let &[name] = trackAsync(() => Promise.reject<string>(new Error('first failed')));
-				let &[upper] = trackAsync(() => {
-					const n = name;
+				const name = trackAsync(() => Promise.reject<string>(new Error('first failed')));
+				const upper = trackAsync(() => {
+					const n = name.value;
 					return Promise.resolve(n.toUpperCase());
 				});
-				<p>{upper}</p>
+				<p>{upper.value}</p>
 			} @catch (err: Error) {
 				<p>{err.message}</p>
 			}
@@ -203,12 +203,12 @@ describe('trackAsync directly in component body (server)', () => {
 	it('chained trackAsync catches when second rejects', async () => {
 		function App() @{
 			@try {
-				let &[name] = trackAsync(() => Promise.resolve('ripple'));
-				let &[upper] = trackAsync(() => {
-					const n = name;
+				const name = trackAsync(() => Promise.resolve('ripple'));
+				const upper = trackAsync(() => {
+					const n = name.value;
 					return Promise.reject(new Error('second failed'));
 				});
-				<p>{upper}</p>
+				<p>{upper.value}</p>
 			} @catch (err: Error) {
 				<p>{err.message}</p>
 			}
@@ -248,8 +248,8 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('inner try/catch catches async rejection from its own child', async () => {
 		function AsyncChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('async inner error')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('async inner error')));
+			<p>{data.value}</p>
 		}
 
 		function Inner() @{
@@ -301,8 +301,8 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('async rejection propagates to outer catch when inner try has no catch', async () => {
 		function AsyncChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('async propagated')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('async propagated')));
+			<p>{data.value}</p>
 		}
 
 		function Inner() @{
@@ -364,13 +364,13 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('sibling components: one fails, the other does not affect catch', async () => {
 		function GoodChild() @{
-			let &[data] = trackAsync(() => Promise.resolve('good'));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.resolve('good'));
+			<p>{data.value}</p>
 		}
 
 		function BadChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('bad child')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('bad child')));
+			<p>{data.value}</p>
 		}
 
 		function App() @{
@@ -391,13 +391,13 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('independent try/catch boundaries each handle their own errors', async () => {
 		function FailChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('fail')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('fail')));
+			<p>{data.value}</p>
 		}
 
 		function SuccessChild() @{
-			let &[data] = trackAsync(() => Promise.resolve('success'));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.resolve('success'));
+			<p>{data.value}</p>
 		}
 
 		function App() @{
@@ -423,8 +423,8 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('inner catch handles rejection, outer renders normally', async () => {
 		function AsyncChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('handled inside')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('handled inside')));
+			<p>{data.value}</p>
 		}
 
 		function Inner() @{
@@ -449,9 +449,9 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('sync error in child after trackAsync routes to catch boundary', async () => {
 		function BrokenChild() @{
-			let &[data] = trackAsync(() => Promise.resolve('loaded'));
+			const data = trackAsync(() => Promise.resolve('loaded'));
 			throw new Error('sync after async');
-			<p>{data}</p>
+			<p>{data.value}</p>
 		}
 
 		function Inner() @{
@@ -472,8 +472,8 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('outer try with pending, inner try with catch: rejection goes to inner catch', async () => {
 		function AsyncChild() @{
-			let &[data] = trackAsync(() => Promise.reject(new Error('inner rejection')));
-			<p>{data}</p>
+			const data = trackAsync(() => Promise.reject(new Error('inner rejection')));
+			<p>{data.value}</p>
 		}
 
 		function Inner() @{
@@ -499,8 +499,8 @@ describe('nested child components with try/catch boundaries (server)', () => {
 
 	it('deeply nested: async resolves through multiple component layers', async () => {
 		function DataFetcher() @{
-			let &[data] = trackAsync(() => Promise.resolve('deep data'));
-			<span>{data}</span>
+			const data = trackAsync(() => Promise.resolve('deep data'));
+			<span>{data.value}</span>
 		}
 
 		function Level2() @{

package/tests/types/transport.ts

@@ -0,0 +1,40 @@
+import { setTransport, type Transport, type Transporter } from 'ripple';
+import { setTransport as setServerTransport } from 'ripple/server';
+import { setTransport as registerTransport } from 'ripple/transport';
+import { defineConfig } from '@ripple-ts/vite-plugin';
+
+class Money {
+	constructor(
+		public amount: number,
+		public currency: string,
+	) {}
+}
+
+const money: Transporter<Money, [number, string]> = {
+	encode: (value) => value instanceof Money && [value.amount, value.currency],
+	decode: ([amount, currency]) => new Money(amount, currency),
+};
+const transport: Transport = { Money: money };
+defineConfig({ transport });
+defineConfig({
+	transport: {
+		Money: {
+			encode: (value) => value instanceof Money && [value.amount, value.currency],
+			decode: ([amount, currency]) => new Money(amount, currency),
+		},
+	},
+});
+setTransport(transport);
+setServerTransport(transport);
+registerTransport(transport);
+setTransport();
+setServerTransport({});
+
+// @ts-expect-error Every handler needs both directions.
+defineConfig({ transport: { Money: { encode: () => false } } });
+const invalid: Transporter<Money, [number, string]> = {
+	...money,
+	// @ts-expect-error A decoder must accept the encoded representation.
+	decode: (data: number) => new Money(data, 'USD'),
+};
+void invalid;

package/tests/utils/vite-plugin-config.test.js

@@ -18,6 +18,7 @@ describe('vite-plugin-ripple config resolution', () => {
 		expect(config.platform.env).toEqual({});
 		expect(config.server.trustProxy).toBe(false);
 		expect(config.rootBoundary).toEqual({});
+		expect(config.transport).toEqual({});
 		expect(config.build.outDir).toBe('dist');
 	});
 
@@ -77,4 +78,26 @@ describe('vite-plugin-ripple config resolution', () => {
 			}),
 		).toThrow('router.routes must be an array');
 	});
+
+	it('preserves transport functions when resolving a config again', () => {
+		const transport = {
+			Money: { encode: () => false, decode: (data) => data },
+		};
+		const config = resolveRippleConfig({ transport });
+		expect(config.transport).toBe(transport);
+		expect(resolveRippleConfig(config).transport).toBe(transport);
+	});
+
+	it.each([null, false, [], 'Money', () => {}])('rejects invalid transport %s', (transport) => {
+		expect(() => resolveRippleConfig({ transport })).toThrow('transport must be an object');
+	});
+
+	it.each([null, [], false, {}, { encode() {} }, { decode() {} }, { encode: true, decode() {} }])(
+		'rejects invalid transport handler %s',
+		(Money) => {
+			expect(() => resolveRippleConfig({ transport: { Money } })).toThrow(
+				'transport.Money must be an object with encode and decode functions',
+			);
+		},
+	);
 });