@absolutejs/absolute 0.19.0-beta.1070 → 0.19.0-beta.1072

package/dist/src/vue/index.d.ts

@@ -7,3 +7,5 @@ export { createTypedIsland } from './createIsland';
 export { useIslandStore } from './useIslandStore';
 export { Image } from './components/Image';
 export { StreamSlot, SuspenseSlot } from './components';
+export { useResource } from './useResource';
+export type { Resource, ResourceFetcher, ResourceMutator, ResourceOptions, ResourceStart } from './useResource';

package/dist/src/vue/useResource.d.ts

@@ -0,0 +1,65 @@
+import { type Ref } from 'vue';
+export type ResourceFetcher<T> = (signal: AbortSignal) => Promise<T>;
+/** Controls the resource's startup behavior.
+ *
+ *  - `'immediate'` (default) — fire the fetcher synchronously at creation;
+ *    `loading.value` starts `true`.
+ *  - `'pending'` — don't fire the fetcher yet, but render as if a fetch is
+ *    coming: `loading.value` starts `true`. Pair with a manual `refresh()`
+ *    call from `onMounted` (or wherever the dependencies become available).
+ *    Use this when the fetcher depends on state set after setup runs (e.g. a
+ *    route param resolved asynchronously) — it avoids the blank-frame flash
+ *    you'd get from `'idle'`.
+ *  - `'idle'` — don't fire the fetcher and don't pretend you will:
+ *    `loading.value` starts `false`. The resource is dormant until
+ *    `refresh()` or `mutate()` is called.
+ */
+export type ResourceStart = 'immediate' | 'pending' | 'idle';
+export type ResourceOptions = {
+    /** When and how the fetcher fires on creation. Default: `'immediate'`. */
+    start?: ResourceStart;
+};
+export type ResourceMutator<T> = T | null | ((prev: T | null) => T | null);
+export type Resource<T> = {
+    /** Latest resolved value, or `null` before the first successful load. */
+    data: Ref<T | null>;
+    /** Latest rejection reason, or `null` when the resource is healthy. */
+    error: Ref<unknown>;
+    /** True while a fetch is in flight, or when `start: 'pending'` was set
+     *  and `refresh()` hasn't been called yet. */
+    loading: Ref<boolean>;
+    /** Re-runs the fetcher. Any in-flight request is aborted first. */
+    refresh: () => Promise<void>;
+    /** Aborts the in-flight request, if any. No-op otherwise. */
+    cancel: () => void;
+    /** Imperatively write the data ref without re-fetching. Accepts a new
+     *  value or an updater function. Use after an edit action returns the new
+     *  entity, so you avoid a wasteful re-fetch. Pending fetches are aborted
+     *  so a slower response can't clobber the mutation. */
+    mutate: (next: ResourceMutator<T>) => void;
+};
+/** Ref-backed async data composable for AbsoluteJS Vue pages. Replaces the
+ *  hand-rolled `onMounted(() => { loading.value = true; data.value = await
+ *  fetch(); })` + `ref` boilerplate with a single call that also handles
+ *  abort-on-teardown, refresh, and optimistic mutation.
+ *
+ *  This is a per-component LOADER, not a cross-component cache — every call
+ *  owns its own state and refetches on creation. For data that should survive
+ *  navigation / be shared across components (so revisiting a route doesn't
+ *  refetch), use a cache layer (e.g. TanStack Query) or `@absolutejs/sync`
+ *  instead. Reach for `useResource` when a one-shot, component-scoped fetch is
+ *  exactly what you want.
+ *
+ *  ```ts
+ *  const profile = useResource((signal) => api.profile.me.get({ signal }));
+ *
+ *  // in template:
+ *  // <Spinner v-if="profile.loading.value" />
+ *  // <h1 v-else-if="profile.data.value">{{ profile.data.value.name }}</h1>
+ *  ```
+ *
+ *  The fetcher receives an `AbortSignal` it can pass to `fetch` — the signal
+ *  aborts when the owning effect scope is disposed (component unmount) or on a
+ *  new `refresh()` call. Call it during `setup()` so an effect scope is
+ *  active; teardown won't be wired up otherwise. */
+export declare const useResource: <T>(fetcher: ResourceFetcher<T>, options?: ResourceOptions) => Resource<T>;

package/dist/vue/index.js

@@ -5237,7 +5237,74 @@ var useIslandStore = (store, selector) => {
   });
   return state;
 };
+// src/vue/useResource.ts
+import {
+  getCurrentScope,
+  onScopeDispose,
+  ref as ref3,
+  shallowRef
+} from "vue";
+var useResource = (fetcher, options = {}) => {
+  const start = options.start ?? "immediate";
+  const data = shallowRef(null);
+  const error = shallowRef(null);
+  const loading = ref3(start !== "idle");
+  let controller = null;
+  let destroyed = false;
+  const cancel = () => {
+    if (controller) {
+      controller.abort();
+      controller = null;
+    }
+  };
+  const refresh = async () => {
+    if (destroyed)
+      return;
+    cancel();
+    const next = new AbortController;
+    controller = next;
+    loading.value = true;
+    error.value = null;
+    try {
+      const result = await fetcher(next.signal);
+      if (next.signal.aborted)
+        return;
+      data.value = result;
+    } catch (cause) {
+      if (next.signal.aborted)
+        return;
+      error.value = cause;
+    } finally {
+      if (controller === next) {
+        controller = null;
+      }
+      if (!next.signal.aborted) {
+        loading.value = false;
+      }
+    }
+  };
+  const mutate = (next) => {
+    if (destroyed)
+      return;
+    cancel();
+    error.value = null;
+    loading.value = false;
+    const resolved = typeof next === "function" ? next(data.value) : next;
+    data.value = resolved;
+  };
+  if (getCurrentScope()) {
+    onScopeDispose(() => {
+      destroyed = true;
+      cancel();
+    });
+  }
+  if (start === "immediate") {
+    refresh();
+  }
+  return { cancel, data, error, loading, mutate, refresh };
+};
 export {
+  useResource,
   useIslandStore,
   handleVuePageRequest,
   defineVueSetupApp,
@@ -5250,5 +5317,5 @@ export {
   Image
 };
 
-//# debugId=C239CE1A81D9CAA564756E2164756E21
+//# debugId=CDB2A0DB62376A8D64756E2164756E21
 //# sourceMappingURL=index.js.map