ripple 0.3.128 → 0.4.1

package/tests/utils/tracked-types.test.js

@@ -0,0 +1,117 @@
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * @param {string} source
+ */
+function create_service(source) {
+	const root = process.cwd();
+	const file_name = `${root}/packages/ripple/tracked-types-test.tsx`;
+	const options = {
+		strict: true,
+		target: ts.ScriptTarget.ESNext,
+		module: ts.ModuleKind.ESNext,
+		moduleResolution: ts.ModuleResolutionKind.Bundler,
+		jsx: ts.JsxEmit.Preserve,
+		jsxImportSource: 'ripple',
+		skipLibCheck: true,
+		types: [],
+		paths: {
+			'#public': [`${root}/packages/ripple/types/index.d.ts`],
+			ripple: [`${root}/packages/ripple/types/index.d.ts`],
+			'ripple/jsx-runtime': [`${root}/packages/ripple/src/jsx-runtime.d.ts`],
+		},
+	};
+	const service = ts.createLanguageService({
+		getCompilationSettings: () => options,
+		getScriptFileNames: () => [file_name],
+		getScriptVersion: () => '0',
+		getScriptSnapshot: (name) => {
+			const text = name === file_name ? source : ts.sys.readFile(name);
+			return text === undefined ? undefined : ts.ScriptSnapshot.fromString(text);
+		},
+		getCurrentDirectory: () => root,
+		getDefaultLibFileName: ts.getDefaultLibFilePath,
+		realpath: ts.sys.realpath,
+		directoryExists: ts.sys.directoryExists,
+		getDirectories: ts.sys.getDirectories,
+		fileExists: (name) => name === file_name || ts.sys.fileExists(name),
+		readFile: (name) => (name === file_name ? source : ts.sys.readFile(name)),
+	});
+	return { service, file_name };
+}
+
+describe('Ripple tracked types', () => {
+	it('shows public names in value property hovers', () => {
+		const source = `
+			import { track } from 'ripple';
+			const count = track(0);
+			const derived = track(() => count.value * 2);
+			const writable = track(() => count.value, undefined, true);
+			count.value;
+			derived.value;
+			writable.value;
+		`;
+		const { service, file_name } = create_service(source);
+		try {
+			expect(service.getSemanticDiagnostics(file_name)).toEqual([]);
+			for (const [name, type] of [
+				['count', 'Tracked'],
+				['derived', 'Derived'],
+				['writable', 'WritableDerived'],
+			]) {
+				const info = service.getQuickInfoAtPosition(
+					file_name,
+					source.lastIndexOf(`${name}.value`) + name.length + 1,
+				);
+				expect(ts.displayPartsToString(info?.displayParts)).toBe(
+					`(property) ${type}<number>.value: number`,
+				);
+			}
+		} finally {
+			service.dispose();
+		}
+	});
+
+	it('preserves writes, read-only views, and tracked component props', () => {
+		const source = `
+			import { track, type Component, type Derived, type Tracked } from 'ripple';
+			const count = track(0);
+			count.value = 1;
+			const tracked: Tracked<number> = track(count);
+			const derived: Derived<number> = tracked;
+			const view = count.readOnly();
+			// @ts-expect-error Read-only views reject writes.
+			view.value = 2;
+			const computed = track(() => count.value * 2);
+			// @ts-expect-error Computed values reject writes.
+			computed.value = 2;
+			const writable = track(() => count.value, undefined, true);
+			writable.value = 2;
+			const with_setter = track(() => count.value, undefined, (next) => next);
+			with_setter.value = 3;
+			// @ts-expect-error Tracked values preserve their value type.
+			count.value = 'wrong';
+			// @ts-expect-error Non-component tracked values are not callable.
+			count({});
+			declare const TrackedComponent: Tracked<Component<{ name: string }>>;
+			declare const DerivedComponent: Derived<Component<{ name: string }>>;
+			const valid = <TrackedComponent name="Ripple" />;
+			const valid_derived = <DerivedComponent name="Ripple" />;
+			// @ts-expect-error Tracked components preserve required props.
+			const missing = <TrackedComponent />;
+			// @ts-expect-error Derived components preserve prop types.
+			const invalid = <DerivedComponent name={123} />;
+		`;
+		const { service, file_name } = create_service(source);
+		try {
+			expect(
+				service
+					.getSemanticDiagnostics(file_name)
+					.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')),
+			).toEqual([]);
+		} finally {
+			service.dispose();
+		}
+	});
+});

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',
+			);
+		},
+	);
 });

package/types/index.d.ts

@@ -1,4 +1,7 @@
 import type { ExtendedEventOptions } from '@tsrx/core/types';
+export type { CSSProperties, JSX, Ripple } from '../src/jsx-runtime.js';
+export { setTransport } from './transport.js';
+export type { Transport, Transporter } from './transport.js';
 export type { RefValue } from '@tsrx/core/runtime/ref';
 export type { AddEventOptions, AddEventObject, ExtendedEventOptions } from '@tsrx/core/types';
 
@@ -61,12 +64,26 @@ export function Dynamic<T>(
 
 export function mount(
 	component: Component,
-	options: { target: HTMLElement; props?: Record<string, any>; rootBoundary?: RootBoundaryOptions },
+	options: {
+		target: HTMLElement;
+		props?: Record<string, any>;
+		/**
+		 * The default `try`/`pending`/`catch` boundary the app renders under.
+		 * `false` renders without one: `trackAsync()` must then sit inside a
+		 * user `@try` block, and errors that escape one propagate out of the
+		 * flush.
+		 */
+		rootBoundary?: RootBoundaryOptions | false;
+	},
 ): () => void;
 
 export function hydrate(
 	component: Component,
-	options: { target: HTMLElement; props?: Record<string, any>; rootBoundary?: RootBoundaryOptions },
+	options: {
+		target: HTMLElement;
+		props?: Record<string, any>;
+		rootBoundary?: RootBoundaryOptions | false;
+	},
 ): () => void;
 
 export interface RootBoundaryOptions {
@@ -204,18 +221,36 @@ export const TRACKED_UPDATED: unique symbol;
 export const SUSPENSE_PENDING: unique symbol;
 export const SUSPENSE_REJECTED: unique symbol;
 
-// Base Tracked interface - all tracked values have a '#v' property containing the actual value
-interface TrackedBase<V> {
+// A tracked value: `track(0)`. Read and write it through `.value`.
+export interface Tracked<V> extends TrackedCallable<V> {
 	'#v': V;
 	value: V;
+	/**
+	 * A read-only view of this value: a `Derived<V>` that follows it, for a
+	 * receiver that should read but not write it. Equivalent to
+	 * `track(() => tracked.value)`.
+	 */
+	readOnly(): Derived<V>;
 }
 // Augment Tracked to be callable when V is a Component.
 // This allows tracked component values to continue flowing through JSX checks.
 interface TrackedCallable<V> {
 	(props: V extends Component<infer P> ? P : never): V extends Component ? void : never;
 }
-// Supports destructuring `const [one, two] = track(0);`
-export type Tracked<V> = [V, Tracked<V>] & TrackedBase<V> & TrackedCallable<V>;
+// A computed value: `track(() => ...)`. Its `value` is read-only unless the
+// call opted into writes (see `WritableDerived`). A `Tracked` satisfies it.
+export interface Derived<V> extends TrackedCallable<V> {
+	'#v': V;
+	readonly value: V;
+	/** A derived is already read-only: returns itself. */
+	readOnly(): Derived<V>;
+}
+// A computed value created with a setter (`track(fn, get, set)`) or with
+// `true` in the setter position: writes land as a temporary value until the
+// next recompute.
+export interface WritableDerived<V> extends Tracked<V> {
+	value: V;
+}
 
 // Helper type to infer component type from a function that returns a component
 // If T is a function returning a Component, extract the Component type itself, not the return type (void)
@@ -235,12 +270,17 @@ type Expand<T> = T extends infer O ? { [K in keyof O]: O[K] } : never;
 
 // Overload for tracked values - returns the original tracked value type
 export function track<V>(value: Tracked<V>): Tracked<V>;
-// Overload for function values - infers the return type of the function
+// Overload for function values - a read-only derived
 export function track<V>(
 	value: () => V,
 	get?: (v: InferComponent<V>) => InferComponent<V>,
-	set?: (next: InferComponent<V>, prev: InferComponent<V>) => InferComponent<V>,
-): Tracked<InferComponent<V>>;
+): Derived<InferComponent<V>>;
+// Overload for function values with a setter (or `true`) - a writable derived
+export function track<V>(
+	value: () => V,
+	get: ((v: InferComponent<V>) => InferComponent<V>) | undefined,
+	set: ((next: InferComponent<V>, prev: InferComponent<V>) => InferComponent<V>) | true,
+): WritableDerived<InferComponent<V>>;
 // Overload for non-function values
 export function track<V>(value?: V, get?: (v: V) => V, set?: (next: V, prev: V) => V): Tracked<V>;
 

package/types/server.d.ts

@@ -2,6 +2,7 @@ import type { Component, RootBoundaryOptions } from '#public';
 
 // Re-export runtime types for server-compiled components
 export {
+	setTransport,
 	track,
 	untrack,
 	flushSync,
@@ -16,6 +17,8 @@ export {
 	RippleURLSearchParams,
 } from './index.js';
 
+export type { Transport, Transporter } from './index.js';
+
 export interface RenderResult {
 	head: string;
 	body: string;

package/types/transport.d.ts

@@ -0,0 +1,15 @@
+/** A custom type's synchronous serialization pair for hydration and RPC. */
+export interface Transporter<T = any, Encoded = any> {
+	/** Return truthy serializable data, or false/undefined for values not handled. */
+	encode: (value: unknown) => Encoded | false | undefined;
+	decode: (data: Encoded) => T;
+}
+
+export type Transport = Record<string, Transporter>;
+
+/**
+ * Register the app's transport once, before rendering, hydration, mounting or
+ * RPC. The Vite plugin calls this automatically for ripple.config.ts transport.
+ * Omit the argument or pass an empty object to restore built-in serialization.
+ */
+export function setTransport(transport?: Transport): void;

package/src/runtime/internal/client/switch.js

@@ -1,113 +0,0 @@
-/** @import { Block } from '#client' */
-
-import { branch, destroy_block, get_first_node, get_last_node, render } from './blocks.js';
-import { SWITCH_BLOCK } from './constants.js';
-import { hydrate_next, hydrate_node, hydrating } from './hydration.js';
-import { next_sibling } from './operations.js';
-import { append } from './template.js';
-
-/**
- * Moves a block's DOM nodes to before an anchor node
- * @param {Block} block
- * @param {ChildNode} anchor
- * @returns {void}
- */
-function move(block, anchor) {
-	// Fast path: a normal case records its own range. Only an optimized single
-	// control-flow / component root case (DOM rendered through a descendant
-	// block, `s.start` null) needs the descent via `get_first_node`/`get_last_node`.
-	var s = block.s;
-	var node = s !== null ? s.start : null;
-	var end;
-
-	if (node === null) {
-		node = get_first_node(block);
-		if (node === null) {
-			return;
-		}
-		end = get_last_node(block);
-	} else {
-		end = s.end;
-	}
-	/** @type {Node | null} */
-	var sibling;
-
-	while (node !== null) {
-		if (node === end) {
-			append(anchor, node);
-			break;
-		}
-		sibling = next_sibling(node);
-		append(anchor, node);
-		node = sibling;
-	}
-}
-
-/**
- * @param {ChildNode} anchor
- * @param {() => ((anchor: ChildNode) => void)[] | null} fn
- * @param {boolean} [root_controlled] When true the block renders before the
- *   component's `__anchor` (no `<!>` wrapper); during hydration the SSR boundary
- *   marker is handed to `append()` afterwards for the context-aware cursor
- *   advance the eliminated wrapper used to perform.
- * @returns {void}
- */
-export function switch_block(anchor, fn, root_controlled) {
-	/** @type {Node | undefined} */
-	var boundary;
-
-	if (hydrating) {
-		if (root_controlled) {
-			boundary = /** @type {Node} */ (hydrate_node);
-		}
-		hydrate_next();
-	}
-
-	/** @type {((anchor: ChildNode) => void)[]} */
-	var prev = [];
-	/** @type {Map<(anchor: ChildNode) => void, Block>} */
-	var blocks = new Map();
-
-	render(
-		() => {
-			var funcs = fn();
-			let same = prev.length === funcs?.length || false;
-
-			for (var i = 0; i < prev.length; i++) {
-				var p = prev[i];
-
-				if (!funcs || funcs.indexOf(p) === -1) {
-					same = false;
-					destroy_block(/** @type {Block} */ (blocks.get(p)));
-					blocks.delete(p);
-				}
-			}
-
-			prev = funcs ?? [];
-
-			if (same || !funcs) {
-				return;
-			}
-
-			for (var i = 0; i < funcs.length; i++) {
-				var n = funcs[i];
-				var b = blocks.get(n);
-				if (b) {
-					move(b, anchor);
-					continue;
-				}
-
-				blocks.set(
-					n,
-					branch(() => n(anchor)),
-				);
-			}
-		},
-		null,
-		SWITCH_BLOCK,
-	);
-
-	if (hydrating && root_controlled) {
-		append(anchor, /** @type {Node} */ (boundary));
-	}
-}

package/src/utils/errors.js

@@ -1,13 +0,0 @@
-/** @returns {never} */
-export function throw_tracked_index_value_error() {
-	throw new Error(
-		'Do not access tracked values with [0]. Use .value or &[] lazy destructuring instead. Numeric tracked access leads to degraded performance.',
-	);
-}
-
-/** @returns {never} */
-export function throw_tracked_index_reference_error() {
-	throw new Error(
-		'Do not access tracked values with [1]. Use the tracked value directly instead. Numeric tracked access leads to degraded performance.',
-	);
-}

package/tests/client/compiler/__snapshots__/compiler.assignments.test.rsrx.snap

@@ -1,12 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`compiler > assignments > compiles tracked values in effect with assignment expression 1`] = `"state.count = lazy.value;"`;
-
-exports[`compiler > assignments > compiles tracked values in effect with update expressions 1`] = `
-"_$_.untrack(() => {
-				state.preIncrement = _$_.update_pre(lazy);
-				state.postIncrement = _$_.update(lazy);
-				state.preDecrement = _$_.update_pre(lazy, -1);
-				state.postDecrement = _$_.update(lazy, -1);
-			});"
-`;

package/tests/client/compiler/__snapshots__/compiler.typescript.test.rsrx.snap

@@ -1,46 +0,0 @@
-// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-
-exports[`compiler > typescript > compiles TSInstantiationExpression 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-function makeBox(value) {
-	return { value };
-}
-
-const makeStringBox = (makeBox);
-const stringBox = makeStringBox('abc');
-const ErrorMap = (Map);
-const errorMap = new ErrorMap();"
-`;
-
-exports[`compiler > typescript > removes class TypeScript syntax from JS output 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-class PrintEvent {
-	text;
-
-	constructor(text) {
-		this.text = text;
-	}
-}"
-`;
-
-exports[`compiler > typescript > removes class extends type arguments from JS output 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-class StringMap extends Map {
-	constructor() {
-		var __block = _$_.scope();
-
-		super();
-	}
-}"
-`;
-
-exports[`compiler > typescript > removes type assertions from function parameters and leaves default values 1`] = `
-"import * as _$_ from 'ripple/internal/client';
-
-function getString(e = 'test') {
-	return e;
-}"
-`;

package/tests/client/lazy-array.test.tsrx

@@ -1,31 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { flushSync, track } from 'ripple';
-
-describe('lazy array destructuring', () => {
-	it('updates unknown lazy array bindings through tracked values', () => {
-		function Child({ tr: &[count, tr] }) @{
-			<button
-				onClick={() => {
-					count++;
-					tr[0]++;
-				}}
-			>{count}</button>
-		}
-
-		function App() @{
-			let tracked = track(0);
-			<Child tr={tracked} />
-		}
-
-		render(App);
-
-		const button = container.querySelector('button');
-		expect(button?.textContent).toBe('0');
-
-		flushSync(() => {
-			button?.click();
-		});
-
-		expect(button?.textContent).toBe('2');
-	});
-});