@wentools/simmer-svelte 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wentools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @wentools/simmer-svelte
+
+Svelte 5 adapters for [@wentools/simmer](https://jsr.io/@wentools/simmer).
+
+## Install
+
+```bash
+# JSR
+deno add jsr:@wentools/simmer-svelte
+
+# npm
+npx jsr add @wentools/simmer-svelte
+```
+
+## Usage
+
+### `createEventualState`
+
+Bridges simmer's `EventualResult` to Svelte 5 reactive state. Returns the
+current (cached) value immediately, then automatically updates when fresh data
+arrives.
+
+```svelte
+<script lang="ts">
+  import { createEventualState } from '@wentools/simmer-svelte'
+
+  let { data } = $props()
+
+  // data.patronShowcase is EventualResult<ShowcaseData>
+  const showcase = createEventualState(() => data.patronShowcase)
+</script>
+
+<!-- Renders immediately with cached data -->
+<PatronShowcase data={showcase.value} />
+
+{#if showcase.isRefreshing}
+  <LoadingSpinner />
+{/if}
+
+{#if showcase.error}
+  <p>Failed to refresh: {showcase.error.message}</p>
+{/if}
+```
+
+### How it works
+
+`EventualResult<T>` contains `{ current: T, fresh: Promise<T> | null }`.
+
+- `current` is served immediately (from cache or SSR)
+- `fresh` resolves when updated data arrives from the API
+
+`createEventualState` wraps this in a reactive rune that:
+
+1. Returns `current` as `value` immediately
+2. Sets `isRefreshing: true` while `fresh` is pending
+3. Swaps `value` to the resolved fresh data automatically
+4. Handles race conditions when navigation triggers new requests
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@wentools/simmer-svelte",
+  "version": "0.1.0",
+  "description": "Svelte 5 adapters for @wentools/simmer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/wentools/simmer-svelte"
+  },
+  "keywords": [
+    "svelte",
+    "runes",
+    "eventual",
+    "simmer",
+    "reactive",
+    "typescript"
+  ],
+  "type": "module",
+  "svelte": "./src/mod.ts",
+  "exports": {
+    ".": {
+      "svelte": "./src/mod.ts",
+      "types": "./src/mod.ts",
+      "default": "./src/mod.ts"
+    }
+  },
+  "peerDependencies": {
+    "svelte": ">=5.0.0",
+    "@wentools/simmer": ">=0.1.0"
+  }
+}

package/src/eventual_state/eventual_state.svelte.ts

@@ -0,0 +1,108 @@
+/**
+ * Svelte 5 rune for handling EventualResult on the client side.
+ *
+ * Automatically switches from current to fresh data when the promise resolves,
+ * with proper handling of race conditions during navigation.
+ */
+
+import type { EventualResult } from '@wentools/simmer'
+
+type EventualInput<TData> = EventualResult<TData>
+
+type EventualState<TData> = {
+	/** The current value - starts with cached data, updates when fresh arrives */
+	readonly value: TData
+	/** True while waiting for fresh data */
+	readonly isRefreshing: boolean
+	/** Error if the fresh promise rejected */
+	readonly error: Error | null
+}
+
+/**
+ * Creates reactive state from an EventualResult.
+ *
+ * Returns the current value immediately, then automatically updates
+ * when fresh data arrives. Handles race conditions from navigation
+ * and errors gracefully.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { createEventualState } from '@wentools/simmer-svelte'
+ *
+ *   let { data } = $props()
+ *
+ *   const showcase = createEventualState(() => data.patronShowcase)
+ * </script>
+ *
+ * <Footer patronShowcase={showcase.value} />
+ *
+ * {#if showcase.isRefreshing}
+ *   <span class="loading-indicator" />
+ * {/if}
+ * ```
+ *
+ * @param getEventual - Getter returning EventualResult (or compatible { current, fresh })
+ * @returns Reactive state with value, isRefreshing, and error
+ */
+const createEventualState = <TData>(
+	getEventual: () => EventualInput<TData>,
+): EventualState<TData> => {
+	// Initialize with current value
+	const initial = getEventual()
+	let currentValue = $state<TData>(initial.current)
+	let freshValue = $state<TData | undefined>(undefined)
+	let hasFreshValue = $state(false)
+	let hasFreshPromise = $state(initial.fresh !== null)
+	let error = $state<Error | null>(null)
+
+	// Counter to handle race conditions - stale promises are ignored
+	let promiseCounter = 0
+
+	$effect(() => {
+		const { current, fresh } = getEventual()
+
+		// Update tracked state
+		currentValue = current
+		hasFreshPromise = fresh !== null
+
+		// Reset fresh state for new input
+		const myCounter = ++promiseCounter
+		freshValue = undefined
+		hasFreshValue = false
+		error = null
+
+		if (fresh) {
+			fresh
+				.then((result) => {
+					// Only update if this is still the active promise
+					if (myCounter === promiseCounter) {
+						freshValue = result
+						hasFreshValue = true
+					}
+				})
+				.catch((err) => {
+					if (myCounter === promiseCounter) {
+						error = err instanceof Error ? err : new Error(String(err))
+						hasFreshValue = true // Mark as done even on error
+					}
+				})
+		}
+	})
+
+	return {
+		get value() {
+			// Return fresh value if available and no error, otherwise current
+			return hasFreshValue && !error ? (freshValue as TData) : currentValue
+		},
+		get isRefreshing() {
+			return hasFreshPromise && !hasFreshValue
+		},
+		get error() {
+			return error
+		},
+	}
+}
+
+export { createEventualState }
+export type { EventualInput, EventualState }

package/src/eventual_state/mod.ts

@@ -0,0 +1,2 @@
+export { createEventualState } from './eventual_state.svelte.ts'
+export type { EventualInput, EventualState } from './eventual_state.svelte.ts'

package/src/mod.ts

@@ -0,0 +1,2 @@
+export { createEventualState } from './eventual_state/mod.ts'
+export type { EventualInput, EventualState } from './eventual_state/mod.ts'