createDataSource

import { createDataSource } from "mountly/data";

createDataSource() is for widget data that should be shared across islands without each widget inventing its own cache lifecycle. It wraps an async loader with request dedupe, stale-while-revalidate, retry, abort, subscriptions, and a standard snapshot shape.

Basic usage

const products = createDataSource<string, Product>({
  staleTime: 30_000,
  retry: 2,
  load: async ({ key, signal }) => {
    const res = await fetch(`/api/products/${key}`, { signal });
    if (!res.ok) throw new Error(`Failed to load product ${key}`);
    return res.json();
  },
});

const data = await products.read("sku_123");
const snapshot = products.getSnapshot("sku_123");

Snapshot

interface DataSourceSnapshot<T> {
  status: "idle" | "loading" | "success" | "error";
  data: T | undefined;
  error: unknown;
  loading: boolean;
  stale: boolean;
  cacheHit: boolean;
  updatedAt: number | null;
}

Widgets can render consistently from status, loading, error, and data rather than each framework inventing a slightly different shape.

Options

| Field | Type | Default | Notes | |---|---|---|---| | load | ({ key, signal }) => Promise<T> | required | Fetcher for one key. Always receives an AbortSignal. | | cacheKey | (key) => string | string or JSON.stringify(key) | Normalizes cache keys. | | ttl | number \| null | null | Hard cache expiry in milliseconds. | | staleTime | number \| null | null | Marks data as stale after this many milliseconds. | | staleWhileRevalidate | boolean | true | Return stale data immediately while refreshing in the background. | | retry | number | 0 | Retry count after the first failed attempt. | | retryDelay | number \| (attempt, error) => number | 0 | Delay between retries. | | cache | DedupCache<string, T> | new cache | Override storage for tests or advanced sharing. |

Subscribe

const off = products.subscribe("sku_123", (snapshot) => {
  render(snapshot);
});

await products.read("sku_123");
off();

Subscribers receive the current snapshot immediately and then every transition: loading, success, error, and invalidation.

Abort and invalidation

products.abort("sku_123");      // abort one in-flight key
products.abort();               // abort every in-flight key

products.invalidate("sku_123"); // drop one cached value
products.clear();               // drop everything

Use abort() when an island is no longer relevant, such as a route transition or a closing modal. Use invalidate() when a mutation changes server state.

With createOnDemandFeature

const quoteSource = createDataSource<string, Quote>({
  staleTime: 60_000,
  load: ({ key, signal }) =>
    fetch(`/api/quotes/${key}`, { signal }).then((r) => r.json()),
});

const quoteFeature = createOnDemandFeature({
  moduleId: "quote-card",
  moduleUrl: "/widgets/quote-card/dist/index.js",
  loadData: (ctx) => quoteSource.read(String(ctx.quoteId)),
  getCacheKey: (ctx) => `quote:${ctx.quoteId}`,
});

createOnDemandFeature still owns feature lifecycle. createDataSource owns data lifecycle when more than one feature or widget needs the same data semantics.