Valync

A lightweight, framework-agnostic async data handling library for React & Vue, inspired by Riverpod’s AsyncValue pattern and powered by ts-results-es.

---

Features

• Unified async state with AsyncLoading, AsyncError, and AsyncData wrapping Option<T>
• Built-in caching with auto revalidation & manual refresh
• Supports React & Vue with idiomatic hooks/composables
• Reactive watch dependencies to refetch on data change
• setData() for manual or partial UI updates
• Uses a strict API response shape for uniform error & data handling
• Flexible Mutations / Write operations to API

---

Installation

Npm

1npm i valync

yarn

1yarn add valync

Bun

1bun add valync

---

API Overview

useValync<T>(key, options?)

A hook/composable to fetch and manage async data.

• key: string | Record<string, any> — Unique cache key or URL.
• options?:

1{
2  init?: Omit<RequestInit, "signal">; // Pass request options for default client or custom client
3  cache?: boolean; // default true, enable/disable caching
4  fetchOnMount?: boolean; // default true, fetch automatically on mount
5  retryCount?: number; // retry count for failed requests
6  onData?: (data: T) => T; // transform data before setting
7  watch?: any[]; // reactive dependencies to trigger refetch
8  initialData?: ApiResponse<T>; // initial server-side data for hydration
9  fetchInterval?: number;
10  onSuccess?: (data: T) => void;
11  onError?: (err: ApiErrorResponse["error"]) => void;
12}

---

Return tuple

1const [state, refetch, setData] = useValync<T>(key, options);

AsyncValue States

1AsyncLoading<T>;
2AsyncError<T>; // contains error { name, message, code? }
3AsyncData<T>; // contains Option<T>: Some(value) or None

---

Example usage

React

1import { useValync, AsyncValue } from "@epikoder/valync-react";
2
3function UserProfile({ userId }: { userId: string }) {
4    const [state, refetch] = useValync<{ name: string; age: number }>(
5        `/api/user/${userId}`,
6        {
7            fetchOnMount: true,
8            retryCount: 2,
9        },
10    );
11
12    return state.when({
13        loading: () => <div>Loading...</div>,
14        error: (err) => <div>Error: {err.message}</div>,
15        data: (opt) =>
16            opt.some ? (
17                <div>
18                    {opt.val.name} ({opt.val.age} years old)
19                </div>
20            ) : (
21                <div>No data available</div>
22            ),
23    });
24}

1const [state, onLogin] = useValync("/api/auth", {
2    cache: false,
3    fetchOnMount: false,
4    init: {
5        method: "POST",
6        headers: { "Content-Type": "application/json" },
7        body: JSON.stringify({ email, password }),
8    },
9});

Vue 3

1import { useValync, AsyncValue } from "@epikoder/valync-vue";
2import { computed } from "vue";
3
4export default {
5    setup() {
6        const [state, refetch] = useValync("/api/user/123", {
7            fetchOnMount: true,
8        });
9
10        const userDisplay = computed(() =>
11            state.when({
12                loading: () => "Loading...",
13                error: (e) => `Error: ${e.message}`,
14                data: (opt) => (opt.some ? `${opt.val.name}` : "No user"),
15            }),
16        );
17
18        return { userDisplay, refetch };
19    },
20};

for use within template you can use state.isLoading(), state.isData() and state.isError().

For more usage check the examples

React demo counter

Vue demo counter

Axios or other HTTP client

1import axios from "axios";
2import { createValyn } from "valync/react";
3
4const useAxiosValync = createValyn({
5    client: async (url, init) =>
6        await axios({ url, ...init }).then((res) => {"status": "success"; "data": res.data}), // transforms to data
7});
8
9// use in a component
10const [state, refetch, setData] = useAxiosValync<User>("/api/user", {
11    onData: (data) => {
12        // transform data to User if needed
13        return data;
14    },
15});

☕️ Buy Me a Drink

If this project saved you time, helped you ship faster, or made you say "damn, that's slick!" — consider buying me a beer 🍻

👉 Send me a drink on Cointr.ee