solid-drift 0.27.0 → 0.28.0

package/README.md

@@ -1600,6 +1600,23 @@ scanline.start();
 - `createShake(options?)` detects shake gestures from `devicemotion`: `{ supported, needsPermission, listening, shakes, error, requestPermission, start, stop }`. A shake counts when the acceleration delta exceeds `threshold` (default 15 m/s^2), rate-limited by `cooldown` (default 800ms); `onShake` fires per shake.
 - `createScanline(options?)` is the animated line of a QR/barcode viewfinder: `{ progress, running, start, stop }`. `progress()` sweeps 0..1 on the shared clock (`direction: "down" | "up" | "alternate"`); bind it to the line's position. Under reduced motion it freezes mid-frame. Every primitive is SSR-safe: server renders get `supported: false` and safe no-op actions.
 
+### Optimistic updates
+
+```tsx
+import { createOptimistic } from "solid-drift";
+
+const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+  bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+);
+
+// in an event handler:
+await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+  // already rolled back; read feed.error() for a toast
+});
+```
+
+`createOptimistic(initial, apply)` gives `{ value, setBase, pending, pendingCount, error, commit, reset }`. `commit(update, task)` applies the update instantly, then runs the task; on success the update is promoted into the base truth (no flicker while the server catches up), and on failure it is rolled back, `error()` is set, and the error is rethrown. `setBase()` folds fresh server truth in (after a refetch); write `apply` idempotently, for example upsert by id, so truth that already includes an optimistic update does not duplicate it. `reset()` drops in-flight updates. Pure signals, SSR-safe.
+
 ### Easings
 
 Named easings: `linear`, `easeInQuad`, `easeOutQuad`, `easeInOutQuad`, `easeInCubic`, `easeOutCubic`, `easeInOutCubic`, `easeInQuart`, `easeOutQuart`, `easeInOutQuart`, `easeOutExpo`, `easeOutBack`, plus the cartoon set: `easeInBack` (anticipation dip before movement), `easeInOutBack` (wind-up, overshoot, settle), `easeOutElastic` (decaying rubber-band oscillation), `easeOutBounce` (shrinking cartoon bounces). Also `cubicBezier(x1, y1, x2, y2)` for CSS-style curves. Pass a name or a custom `(t) => number` function anywhere an easing is accepted.

package/dist/index.d.ts

@@ -46,3 +46,5 @@ export { createVoiceState, createMicLevel, createSpeech, createWaveform, createT
 export type { VoiceStatus, VoiceStateControls, MicLevelOptions, MicLevelControls, SpeechOptions, SpeechControls, WaveformOptions, WaveformControls, TTSProvider, TTSOptions, TTSControls, ThinkingOptions, ThinkingControls, PromptOptions, PromptControls, } from "./voice.js";
 export { createBattery, createNetwork, createWakeLock, createContactPick, createOTP, createShare, createNFC, createTorch, createGyro, createShake, createScanline, } from "./hardware.js";
 export type { BatteryState, NetworkState, WakeLockState, PickedContact, ContactPickState, OTPState, ShareState, NFCRecord, NFCMessage, NFCState, TorchState, GyroState, ShakeOptions, ShakeState, ScanlineOptions, ScanlineState, } from "./hardware.js";
+export { createOptimistic } from "./optimistic.js";
+export type { OptimisticControls } from "./optimistic.js";

package/dist/index.js

@@ -39,3 +39,4 @@ export { createPoll, shortenAddress, isAddress, formatUnits, parseUnits, CHAINS,
 export { createSSEParser, createSSE, createChatModel, } from "./stream.js";
 export { createVoiceState, createMicLevel, createSpeech, createWaveform, createTTS, createThinking, createPrompt, } from "./voice.js";
 export { createBattery, createNetwork, createWakeLock, createContactPick, createOTP, createShare, createNFC, createTorch, createGyro, createShake, createScanline, } from "./hardware.js";
+export { createOptimistic } from "./optimistic.js";

package/dist/optimistic.d.ts

@@ -0,0 +1,44 @@
+export interface OptimisticControls<T, U> {
+    /** Server truth plus every in-flight optimistic update, in commit order. */
+    value: () => T;
+    /** Replace the server truth (for example after a refetch). */
+    setBase: (next: T | ((prev: T) => T)) => void;
+    /** True while at least one commit is in flight. */
+    pending: () => boolean;
+    /** Number of commits currently in flight. */
+    pendingCount: () => number;
+    /** Last commit failure, cleared when the next commit starts. */
+    error: () => Error | null;
+    /**
+     * Apply `update` immediately, then run `task`. On success the update is
+     * promoted into the base truth (so the value stays stable while the
+     * server catches up); on failure it is rolled back, `error()` is set,
+     * and the error is rethrown so callers can react (toast, retry).
+     */
+    commit: (update: U, task: (update: U) => Promise<unknown>) => Promise<void>;
+    /** Drop every in-flight optimistic update without running their tasks. */
+    reset: () => void;
+}
+/**
+ * createOptimistic
+ *
+ * Optimistic updates with rollback, in the spirit of React's `useOptimistic`.
+ * The UI reflects `update` the moment `commit()` is called; if the backing
+ * task (a transaction, a POST, a stream send) fails, that update is rolled
+ * back and the error surfaces on `error()`.
+ *
+ * Write `apply` idempotently (upsert by id rather than blind append) when
+ * the server truth delivered through `setBase` may already include an
+ * optimistic update.
+ *
+ * ```ts
+ * const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+ *   bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+ * );
+ *
+ * await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+ *   // already rolled back; show a toast from feed.error()
+ * });
+ * ```
+ */
+export declare function createOptimistic<T, U>(initial: T, apply: (state: T, update: U) => T): OptimisticControls<T, U>;

package/dist/optimistic.js

@@ -0,0 +1,76 @@
+import { createSignal } from "solid-js";
+/**
+ * createOptimistic
+ *
+ * Optimistic updates with rollback, in the spirit of React's `useOptimistic`.
+ * The UI reflects `update` the moment `commit()` is called; if the backing
+ * task (a transaction, a POST, a stream send) fails, that update is rolled
+ * back and the error surfaces on `error()`.
+ *
+ * Write `apply` idempotently (upsert by id rather than blind append) when
+ * the server truth delivered through `setBase` may already include an
+ * optimistic update.
+ *
+ * ```ts
+ * const feed = createOptimistic<Bid[], Bid>([], (bids, bid) =>
+ *   bids.some((b) => b.id === bid.id) ? bids : [...bids, bid],
+ * );
+ *
+ * await feed.commit(bid, (b) => sendBidTx(b)).catch(() => {
+ *   // already rolled back; show a toast from feed.error()
+ * });
+ * ```
+ */
+export function createOptimistic(initial, apply) {
+    const [base, setBaseSignal] = createSignal(initial);
+    const [queue, setQueue] = createSignal([]);
+    const [error, setError] = createSignal(null);
+    let nextId = 0;
+    const value = () => {
+        const truth = base();
+        const pending = queue();
+        if (pending.length === 0)
+            return truth;
+        return pending.reduce((state, entry) => apply(state, entry.update), truth);
+    };
+    const setBase = (next) => {
+        if (typeof next === "function") {
+            setBaseSignal(next);
+        }
+        else {
+            setBaseSignal(() => next);
+        }
+    };
+    const commit = async (update, task) => {
+        const id = nextId++;
+        setError(null);
+        setQueue((q) => [...q, { id, update }]);
+        try {
+            await task(update);
+            // Promote the confirmed update into the base truth so the value
+            // stays stable while the server truth catches up via setBase.
+            setBaseSignal((prev) => apply(prev, update));
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+        finally {
+            setQueue((q) => q.filter((entry) => entry.id !== id));
+        }
+    };
+    const reset = () => {
+        setQueue([]);
+        setError(null);
+    };
+    return {
+        value,
+        setBase,
+        pending: () => queue().length > 0,
+        pendingCount: () => queue().length,
+        error,
+        commit,
+        reset,
+    };
+}

package/package.json

@@ -43,5 +43,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.27.0"
+  "version": "0.28.0"
 }