@status-kit/promise-svelte

A tiny utility that wraps any Promise into a reactive Svelte 5 status object — pending / success / failed, plus the resolved data or caught error, with no boilerplate.

• Primitive — three $state fields, no $effect.
• Standalone — no dependency on any other @status-kit package.
• SSR-safe — as long as you create it per component/request (see below).

Install

pnpm add @status-kit/promise-svelte

Quick start

import { statusPromise } from "@status-kit/promise-svelte";

const state = statusPromise(fetch("/api/profile").then((r) => r.json()));

{#if state.isPending}
  <p>Loading…</p>
{:else if state.isFailed}
  <p>Something went wrong: {state.error}</p>
{:else if state.isSuccess}
  <p>Welcome, {state.data.name}</p>
{/if}

If you only need pending/success/error state to drive a single template block, Svelte's native {#await} often does the same job with no extra code:

{#await somePromise}
  <p>Loading…</p>
{:then value}
  <p>{value}</p>
{:catch error}
  <p>{error}</p>
{/await}

Reach for statusPromise() instead when you need that state available outside a single template block — e.g. to disable a button elsewhere on the page, or to drive non-template logic.

API

statusPromise<T>(promise: Promise<T>): StatusPromiseResult<T>

Call this once per promise you want to track (e.g. once in a component's <script>, not inline in markup or inside a block that re-runs) — each call starts a fresh tracker and a fresh .then()/.catch() subscription on the given promise. Calling it repeatedly for what's conceptually "the same" async operation creates redundant, independent trackers rather than reusing one.

StatusPromiseResult<T>:

| Property | Type | Description | | ------------- | -------------------------------------- | ---------------------------------------------------- | | status | 'pending' \| 'success' \| 'failed' | Current state of the promise. | | isPending | boolean | true while the promise is still pending. | | isSuccess | boolean | true once the promise has resolved. | | isFailed | boolean | true once the promise has rejected. | | isFinished | boolean | true once the promise has settled, either way. | | data | T \| null | Resolved value, or null until success. | | error | unknown | Caught rejection reason, or null until failure. |

SSR

Never call statusPromise() at module scope and share the result across requests — with SSR enabled, module-level state is shared by every concurrent request on the server and will leak between users. Always call it inside a component's <script> (or another per-request scope) so each request gets its own tracker.

License

MIT