ripple 0.3.128 → 0.4.0

package/types/index.d.ts

@@ -1,4 +1,6 @@
 import type { ExtendedEventOptions } from '@tsrx/core/types';
+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 +63,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 {
@@ -208,14 +224,34 @@ export const SUSPENSE_REJECTED: unique symbol;
 interface TrackedBase<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 tracked value: `track(0)`. Read and write it through `.value`.
+export type 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.
+interface DerivedBase<V> {
+	'#v': V;
+	readonly value: V;
+	/** A derived is already read-only: returns itself. */
+	readOnly(): Derived<V>;
+}
+export type Derived<V> = DerivedBase<V> & TrackedCallable<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 type WritableDerived<V> = TrackedBase<V> & TrackedCallable<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 +271,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/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');
-	});
-});