ripple 0.3.25 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # ripple
 
+## 1.0.1
+
+### Patch Changes
+
+- [#886](https://github.com/Ripple-TS/ripple/pull/886)
+  [`316cba1`](https://github.com/Ripple-TS/ripple/commit/316cba18614e5ef59dce15e0de6e720eb922955f)
+  Thanks [@leonidaz](https://github.com/leonidaz)! - Add SSR-to-client
+  serialization/hydration for trackAsync by emitting per-call JSON <script>
+  envelopes (resolved payload + direct dependency hashes, or sanitized error
+  message) and consuming/removing them during client hydration to avoid re-running
+  the user async function. Add proper error handling routing to catch blocks with
+  actual error messages in DEV and safe production error messages, all with
+  correct hydration support
+- Updated dependencies
+  [[`316cba1`](https://github.com/Ripple-TS/ripple/commit/316cba18614e5ef59dce15e0de6e720eb922955f)]:
+  - ripple@1.0.1
+  - @tsrx/ripple@0.0.8
+
+## 1.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - ripple@1.0.0
+  - @tsrx/ripple@0.0.7
+
 ## 0.3.25
 
 ### 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.25",
+  "version": "1.0.1",
   "type": "module",
   "module": "src/runtime/index-client.js",
   "main": "src/runtime/index-client.js",
@@ -72,11 +72,11 @@
   },
   "dependencies": {
     "clsx": "^2.1.1",
-    "devalue": "^5.6.3",
+    "devalue": "^5.7.1",
     "esm-env": "^1.2.2",
     "@types/estree": "^1.0.8",
     "@types/estree-jsx": "^1.0.5",
-    "@tsrx/ripple": "0.0.6"
+    "@tsrx/ripple": "0.0.8"
   },
   "devDependencies": {
     "@types/node": "^24.3.0",
@@ -84,9 +84,9 @@
     "typescript": "^5.9.3",
     "@volar/language-core": "~2.4.28",
     "vscode-languageserver-types": "^3.17.5",
-    "@tsrx/core": "0.0.5"
+    "@tsrx/core": "0.0.6"
   },
   "peerDependencies": {
-    "ripple": "0.3.25"
+    "ripple": "1.0.1"
   }
 }

package/src/runtime/index-client.js

@@ -11,6 +11,7 @@ import { active_block } from './internal/client/runtime.js';
 import { create_anchor } from './internal/client/utils.js';
 import { remove_ssr_css } from './internal/client/css.js';
 import {
+	clear_track_hash_reference,
 	hydrate_next,
 	hydrate_node,
 	hydrating,
@@ -108,6 +109,9 @@ export function hydrate(component, options) {
 	} finally {
 		set_hydrating(was_hydrating);
 		set_hydrate_node(previous_hydrate_node, true);
+		if (!was_hydrating) {
+			clear_track_hash_reference();
+		}
 	}
 
 	return () => {

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

@@ -19,7 +19,7 @@ import { active_block, get, set, tracked } from './runtime.js';
  * @returns {ComponentWrapper}
  */
 export function hmr(fn) {
-	/** @type {Tracked<Component> | undefined} */
+	/** @type {Tracked | undefined} */
 	var current;
 
 	/**

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

@@ -1,3 +1,5 @@
+/** @import { Derived, Tracked } from '#client' */
+
 import {
 	COMMENT_NODE,
 	HYDRATION_END,
@@ -11,6 +13,18 @@ export let hydrating = false;
 /** @type {Node | null} */
 export let hydrate_node = null;
 
+/**
+ * Map of hash -> Tracked/Derived registered during hydration. Allows a
+ * hydrating trackAsync to look up its serialized dependencies by hash and
+ * wire up reactivity without re-running the user's async fn.
+ * @type {Map<string, Tracked | Derived>}
+ */
+export const track_hash_reference = new Map();
+
+export function clear_track_hash_reference() {
+	track_hash_reference.clear();
+}
+
 /**
  * @param {boolean} value
  */

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

@@ -1,5 +1,7 @@
-/** @import { Block, Component, Dependency, Derived, Tracked, BlockWithTryBoundaryAndCatch, DeferredTrackedEntry } from '#client' */
+/** @import { Block, Component, Dependency, BlockWithTryBoundaryAndCatch, DeferredTrackedEntry } from '#client' */
 /** @import { NAMESPACE_URI } from './constants.js' */
+/** @typedef {TrackedValue} Tracked */
+/** @typedef {DerivedValue} Derived */
 
 import { DEV } from 'esm-env';
 import {
@@ -51,6 +53,9 @@ import {
 	object_keys,
 } from './utils.js';
 import { get_async_track_result } from '../../../utils/async.js';
+import { get_track_async_script_id } from '../../../utils/track-async-serialization.js';
+import * as devalue from 'devalue';
+import { hydrating, track_hash_reference } from './hydration.js';
 
 const FLUSH_MICROTASK = 0;
 const FLUSH_SYNC = 1;
@@ -383,31 +388,42 @@ function complete_deferred_boundaries(t, show_resolved = true) {
 	}
 }
 
-/** @type {Tracked} */
 class TrackedValue {
 	/**
 	 * @param {any} v
 	 * @param {Block} block
 	 * @param {{ get?: Function; set?: Function }} a
+	 * @param {string} [hash]
 	 */
-	constructor(v, block, a) {
+	constructor(v, block, a, hash) {
+		/** @type {{ get?: Function; set?: Function }} */
 		this.a = a;
+		/** @type {Block} */
 		this.b = block;
+		/** @type {number} */
 		this.c = 0;
 		/** @type {DeferredTrackedEntry[] | null} */
 		this.d = null;
+		/** @type {number} */
 		this.f = TRACKED;
+		/** @type {string | undefined} */
+		this.h = hash;
+		/** @type {any} */
 		this.__v = v;
 	}
+	/** @returns {any} */
 	get [0]() {
 		return get_tracked(this);
 	}
+	/** @param {any} v */
 	set [0](v) {
 		set(this, v);
 	}
+	/** @returns {Tracked} */
 	get [1]() {
-		return this;
+		return /** @type {Tracked} */ (this);
 	}
+	/** @returns {any} */
 	get value() {
 		return get_tracked(this);
 	}
@@ -419,41 +435,55 @@ class TrackedValue {
 	get length() {
 		return 2;
 	}
+	/** @returns {Iterator<any | Tracked>} */
 	*[Symbol.iterator]() {
 		yield get_tracked(this);
 		yield this;
 	}
 }
 
-/** @type {Derived} */
 class DerivedValue {
 	/**
 	 * @param {Function} fn
 	 * @param {Block} block
 	 * @param {{ get?: Function; set?: Function }} a
+	 * @param {string} [hash]
 	 */
-	constructor(fn, block, a) {
+	constructor(fn, block, a, hash) {
+		/** @type {{ get?: Function; set?: Function }} */
 		this.a = a;
+		/** @type {Block} */
 		this.b = block;
-		/** @type {null | Block[]} */
+		/** @type {Block[] | null} */
 		this.blocks = null;
+		/** @type {number} */
 		this.c = 0;
+		/** @type {Component | null} */
 		this.co = active_component;
-		/** @type {null | Dependency} */
+		/** @type {Dependency | null} */
 		this.d = null;
+		/** @type {number} */
 		this.f = DERIVED;
+		/** @type {Function} */
 		this.fn = fn;
+		/** @type {string | undefined} */
+		this.h = hash;
+		/** @type {any} */
 		this.__v = UNINITIALIZED;
 	}
+	/** @returns {any} */
 	get [0]() {
 		return get_derived(this);
 	}
+	/** @param {any} v */
 	set [0](v) {
 		set(this, v);
 	}
+	/** @returns {Derived} */
 	get [1]() {
-		return this;
+		return /** @type {Derived} */ (this);
 	}
+	/** @returns {any} */
 	get value() {
 		return get_derived(this);
 	}
@@ -465,6 +495,7 @@ class DerivedValue {
 	get length() {
 		return 2;
 	}
+	/** @returns {Iterator<any | Derived>} */
 	*[Symbol.iterator]() {
 		yield get_derived(this);
 		yield this;
@@ -480,37 +511,48 @@ if (DEV) {
  *
  * @param {any} v
  * @param {Block} block
+ * @param {string} [hash]
  * @param {(value: any) => any} [get]
  * @param {(next: any, prev: any) => any} [set]
  * @returns {Tracked}
  */
-export function tracked(v, block, get, set) {
-	return /** @type {Tracked} */ (
-		new TrackedValue(v, block || active_block, get || set ? { get, set } : empty_get_set)
+export function tracked(v, block, hash, get, set) {
+	var t = /** @type {Tracked} */ (
+		new TrackedValue(v, block || active_block, get || set ? { get, set } : empty_get_set, hash)
 	);
+	if (hydrating && hash !== undefined) {
+		track_hash_reference.set(hash, t);
+	}
+	return t;
 }
 
 /**
  * @param {any} fn
- * @param {any} block
+ * @param {Block} block
+ * @param {string} [hash]
  * @param {(value: any) => any} [get]
  * @param {(next: any, prev: any) => any} [set]
  * @returns {Derived}
  */
-export function derived(fn, block, get, set) {
-	return /** @type {Derived} */ (
-		new DerivedValue(fn, block || active_block, get || set ? { get, set } : empty_get_set)
+export function derived(fn, block, hash, get, set) {
+	var d = /** @type {Derived} */ (
+		new DerivedValue(fn, block || active_block, get || set ? { get, set } : empty_get_set, hash)
 	);
+	if (hydrating && hash !== undefined) {
+		track_hash_reference.set(hash, d);
+	}
+	return d;
 }
 
 /**
  * @param {any} v
- * @param {(value: any) => any | undefined} get
- * @param {(next: any, prev: any) => any | undefined} set
  * @param {Block} b
+ * @param {string} [hash]
+ * @param {(value: any) => any} [get]
+ * @param {(next: any, prev: any) => any} [set]
  * @returns {Tracked | Derived}
  */
-export function track(v, get, set, b) {
+export function track(v, b, hash, get, set) {
 	if (is_ripple_object(v)) {
 		return v;
 	}
@@ -519,17 +561,18 @@ export function track(v, get, set, b) {
 	}
 
 	if (typeof v === 'function') {
-		return derived(v, b, get, set);
+		return derived(v, b, hash, get, set);
 	}
-	return tracked(v, b, get, set);
+	return tracked(v, b, hash, get, set);
 }
 
 /**
  * @param {any} fn
  * @param {Block} b
+ * @param {string} hash - Unique hash for SSR serialization/hydration
  * @returns {Tracked | void}
  */
-export function track_async(fn, b) {
+export function track_async(fn, b, hash) {
 	if (is_ripple_object(fn)) {
 		return fn;
 	}
@@ -545,7 +588,31 @@ export function track_async(fn, b) {
 		);
 	}
 
-	var t = tracked(SUSPENSE_PENDING, target_block);
+	// During hydration, attempt to read serialized data from SSR
+	var had_hydration_data = false;
+	var hydration_value;
+	/** @type {string[] | undefined} */
+	var hydration_deps;
+
+	if (hydrating) {
+		var script_id = get_track_async_script_id(hash);
+		var script_el = document.getElementById(script_id);
+		if (script_el) {
+			var envelope = JSON.parse(/** @type {string} */ (script_el.textContent));
+			script_el.remove();
+
+			if (envelope.ok) {
+				had_hydration_data = true;
+				hydration_value = devalue.parse(envelope.payload);
+				hydration_deps = envelope.deps;
+			} else {
+				// trigger the catch block
+				throw new Error(envelope.error?.message ?? 'Unknown server error');
+			}
+		}
+	}
+
+	var t = tracked(had_hydration_data ? hydration_value : SUSPENSE_PENDING, target_block, hash);
 
 	// Capture the call-site block for boundary lookups. target_block is the
 	// component's block (passed by compiler), but the actual try/pending/catch
@@ -559,15 +626,44 @@ export function track_async(fn, b) {
 	/** @type {Block | null} */
 	var boundary = null;
 
+	// TODO: decide if instead of insisting on pending, we create our own boundary
+	// we currently require a pending block upstream but we could also
+	// create a try/pending/catch boundary at mount and hydration like
+	// we do on the server so that there is always a boundary present.
+	// It can handle global pending when none were provided.
+	// Not sure about the catch boundary because if none were provided,
+	// the whole app for any error will be unmounted with the catch block rendered
+
 	// Find boundary from the call-site block.
 	boundary = get_pending_boundary(active_block);
 	if (boundary === null) {
 		throw new Error('Missing parent `try { ... } pending { ... }` statement');
 	}
 
-	request_id = begin_boundary_request(boundary);
+	// If we hydrated with resolved data, the SSR already completed this request.
+	// Otherwise mark a pending request on the boundary for the client-side run.
+	if (!had_hydration_data) {
+		request_id = begin_boundary_request(boundary);
+	}
 
 	pre_effect(() => {
+		if (had_hydration_data) {
+			// First run after hydration: skip fn() entirely (the SSR already
+			// produced the resolved value) and instead register the direct
+			// dependencies from the serialized deps list so future dep changes
+			// trigger a re-run via the normal async path.
+			had_hydration_data = false;
+			if (hydration_deps !== undefined) {
+				for (var i = 0; i < hydration_deps.length; i++) {
+					var dep_ref = track_hash_reference.get(hydration_deps[i]);
+					if (dep_ref !== undefined) {
+						get(dep_ref);
+					}
+				}
+			}
+			return;
+		}
+
 		var current_version = ++version;
 
 		// Abort previous in-flight request
@@ -583,7 +679,7 @@ export function track_async(fn, b) {
 			request_id = begin_boundary_request(boundary);
 		}
 
-		// Set to pending before calling fn() in case it's sync
+		// Set to pending before calling fn() in case it's sync.
 		if (t.__v !== SUSPENSE_PENDING) {
 			update_tracked_value_clock(t, SUSPENSE_PENDING);
 			schedule_update(t.b);
@@ -712,15 +808,15 @@ export function track_async(fn, b) {
 }
 
 /**
- * @param {(Derived | Tracked) | (() => any)} tracked
+ * @param {(Derived | Tracked) | (() => any)} t
  * @returns {boolean}
  */
-export function is_tracked_pending(tracked) {
+export function is_tracked_pending(t) {
 	try {
-		if (typeof tracked === 'function') {
-			tracked();
+		if (typeof t === 'function') {
+			t();
 		} else {
-			get(tracked);
+			get(t);
 		}
 		return false;
 	} catch (error) {
@@ -1225,7 +1321,7 @@ export function spread_props(fn) {
  * @returns {Object}
  */
 export function proxy_props(fn) {
-	const memo = derived(fn, active_block);
+	const memo = derived(fn, /** @type {Block} */ (active_block));
 
 	return new Proxy(
 		{},

package/src/runtime/internal/client/types.d.ts

@@ -1,5 +1,8 @@
+import type { Tracked, Derived } from './runtime.js';
 import type { Context } from './context.js';
 
+export { Tracked, Derived };
+
 export type Component = {
 	b: null | Block;
 	c: null | Map<Context<any>, any>;
@@ -18,44 +21,11 @@ export type Dependency = {
 	n: null | Dependency;
 };
 
-export type Tracked<V = any> = {
-	DO_NOT_ACCESS_THIS_OBJECT_DIRECTLY?: true;
-	a: { get?: Function; set?: Function };
-	b: Block;
-	c: number;
-	d: null | DeferredTrackedEntry[];
-	f: number;
-	__v: V;
-	readonly [0]: V;
-	[1]: Tracked<V>;
-	value: V;
-	readonly length: 2;
-	[Symbol.iterator](): Iterator<V | Tracked<V>>;
-};
-
 export type DeferredTrackedEntry = {
 	b: Block; // boundary block
 	r: number; // request version id
 };
 
-export type Derived = {
-	DO_NOT_ACCESS_THIS_OBJECT_DIRECTLY?: true;
-	a: { get?: Function; set?: Function };
-	b: Block;
-	blocks: null | Block[];
-	c: number;
-	co: null | Component;
-	d: null | Dependency;
-	f: number;
-	fn: Function;
-	__v: any;
-	readonly [0]: any;
-	[1]: Derived;
-	value: any;
-	readonly length: 2;
-	[Symbol.iterator](): Iterator<any | Derived>;
-};
-
 export type Block = {
 	co: null | Component;
 	d: null | Dependency;

package/src/runtime/internal/server/blocks.js

@@ -18,7 +18,16 @@ import {
 	ROOT_BLOCK,
 	CAUGHT_ERROR,
 } from './constants.js';
-import { run_block, active_block, active_component, Output, set_active_block } from './index.js';
+import {
+	run_block,
+	active_block,
+	active_component,
+	Output,
+	set_active_block,
+	TrackAsyncRunError,
+	create_public_track_async_error,
+	serialize_track_async_error,
+} from './index.js';
 
 /**
  * @param {number} flags
@@ -90,6 +99,17 @@ export function try_block(try_fn, catch_fn = null, pending_fn = null) {
 		if (created_block.f & TRY_CATCH_BLOCK) {
 			created_block.o.clear();
 			cancel_async_operations(created_block);
+
+			// make sure to serialize trackAsync error so the client can hydrate them properly
+			// needs to happen after clearing output
+			if (error instanceof TrackAsyncRunError) {
+				var { tracked: t, cause } = /** @type {InstanceType<typeof TrackAsyncRunError>} */ (error);
+				var public_error = create_public_track_async_error(cause);
+				catch_fn?.(public_error);
+				serialize_track_async_error(t.h, public_error);
+				return created_block;
+			}
+
 			// render the catch
 			catch_fn?.(/** @type {SSRError} */ (error));
 		} else {