@vobs/resource 0.3.0 → 1.0.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 vobsjs
+Copyright (c) 2026 vobs contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -0,0 +1,56 @@
+# @vobs/resource
+
+Signal-backed async data for vobs: keyed request caching, stale-while-revalidate, revision-guarded mutations, and SSR dehydration.
+
+## Install
+
+```bash
+npm install @vobs/resource
+```
+
+## Quick start
+
+```ts
+import { createResourceClient } from '@vobs/resource'
+
+const client = createResourceClient({ staleTime: 30_000, retry: 2 })
+
+const users = client.resource({
+  key: ['users', { page: 1 }],
+  fetcher: signal => fetch('/api/users?page=1', { signal }).then(res => res.json()),
+  strategy: 'stale-while-revalidate'
+})
+
+users.loading.value // true while the first request is in flight
+users.data.value    // T | null once settled
+users.error.value   // Error | null on failure
+
+await users.refetch()
+client.invalidate(['users', { page: 1 }])
+```
+
+Resources created with the same serialized key share one cache entry and one in-flight request. Results carry a revision: a response that settles after `mutate` or `optimistic` is discarded, so late data never overwrites newer local writes. With `stale-while-revalidate`, cached data is returned immediately while a fresh request runs in the background; `cache-first` re-fetches only after `staleTime` expires.
+
+## API
+
+| Signature | Description |
+| --- | --- |
+| `createResourceClient(options?: ResourceClientOptions): ResourceClient` | Create a client; options set default `staleTime`, `retry`, `retryDelay`, and `onError`. |
+| `resource(fetcher or options): Resource` | Create a resource on the module-level default client. |
+| `client.resource(options): Resource` | Pass `key` to enable caching (also accepts a signal or function key for reactive re-fetch); `cache: false` opts out. |
+| `resource.data / error / loading` | Signals for current value, error, and request state. |
+| `resource.refetch() / prefetch() / invalidate()` | Force a request, start one opportunistically, or expire the cache. |
+| `resource.execute()` | Runs the fetcher now and returns the result; revision-guarded like every settle path. |
+| `resource.mutate(next)` | Write through the shared cache immediately. |
+| `resource.optimistic(next, action)` | Apply `next`, then roll back and set `error` if `action` rejects. |
+| `resource.dispose()` | Detach; aborts the request when it is the last subscriber. |
+| `client.invalidate(key) / client.get(key)` | Expire or read a cached snapshot by key. |
+| `client.prefetchAll() / dehydrate() / hydrate(snapshot) / clear()` | Await in-flight work, serialize for SSR, restore, and reset. |
+| `stableSerialize(value): string` | Deterministic serialization used for cache keys. |
+| `serializeResourceState(snapshot): string` | JSON-stringify dehydrated state with HTML-safe escaping. |
+| `resourcePlugin(options?) / resourceRouterPlugin(options?)` | Provide the client as `RESOURCE_KEY`; run `route.meta.prefetch` handlers before navigation. |
+| `insertResourceBoundary(parent, anchor, options) / ResourceBoundary(props)` | Branch on loading, empty, error, and data of a resource. |
+
+## Types
+
+Resource, ResourceKey, ResourceKeySource, ResourceFetcher, ResourceOptions, ResourceCacheStrategy, RetryDelay, ResourceSnapshot, ResourceClient, ResourceClientOptions, ResourceDehydratedEntry, ResourceDehydratedState, ResourceBoundaryChild, ResourceBoundaryFallback, ResourceBoundaryOptions, ResourceBoundaryProps, ResourceBoundaryView, ResourcePluginOptions, ResourceRoutePrefetch, ResourceRoutePrefetchContext, ResourceRouterPluginOptions

package/package.json

@@ -1,41 +1,22 @@
 {
-  "name": "@vobs/resource",
-  "version": "0.3.0",
-  "description": "Declarative async data resources for vobs: fetch, cancel, cache, invalidate, refetch and mutation.",
-  "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "license": "MIT",
-  "author": "vobsjs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vobsjs/vobs.git",
-    "directory": "packages/features/resource"
-  },
-  "bugs": {
-    "url": "https://github.com/vobsjs/vobs/issues"
-  },
-  "homepage": "https://github.com/vobsjs/vobs#readme",
-  "dependencies": {
-    "@vobs/reactivity": "0.3.0",
-    "@vobs/runtime-core": "0.3.0"
-  },
   "files": [
-    "dist"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "name": "@vobs/resource",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
+    ".": "./src/index.ts"
   },
-  "types": "./dist/index.d.ts",
-  "module": "./dist/index.js",
-  "main": "./dist/index.js",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22.12.0"
+  "dependencies": {
+    "@vobs/reactivity": "1.0.0",
+    "@vobs/router": "1.0.0",
+    "@vobs/runtime": "1.0.0",
+    "@vobs/vobs": "1.0.0"
   }
 }

package/src/boundary.ts

@@ -0,0 +1,52 @@
+import { createFragment, insertBoundary, type NodeFactory, type VobsNode } from '@vobs/vobs'
+import type { Resource } from './resource'
+
+export type ResourceBoundaryChild<T> = (data: T) => ReturnType<NodeFactory>
+export type ResourceBoundaryView = ReturnType<NodeFactory> | NodeFactory
+export type ResourceBoundaryFallback = (
+  error: Error,
+  retry: () => Promise<unknown>
+) => ReturnType<NodeFactory>
+
+export interface ResourceBoundaryOptions<T> {
+  resource: Resource<T>
+  children: ResourceBoundaryChild<T>
+  loading?: ResourceBoundaryView
+  empty?: ResourceBoundaryView
+  fallback?: ResourceBoundaryFallback
+}
+
+export interface ResourceBoundaryProps<T> extends ResourceBoundaryOptions<T> {}
+
+/**
+ * Inserts a reactive Resource state branch. The compiler can lower a future
+ * ResourceBoundary JSX element to this host-level instruction without a wrapper node.
+ */
+export function insertResourceBoundary<T>(
+  parent: Node,
+  anchor: Node | null,
+  options: ResourceBoundaryOptions<T>
+): void {
+  insertBoundary(parent, anchor, {
+    onRetry: () => options.resource.refetch(),
+    fallback: (error, retry) => options.fallback?.(error, () => Promise.resolve(retry())) ?? null,
+    children: () => {
+      if (options.resource.error.value) throw options.resource.error.value
+      if (options.resource.loading.value) return resolveView(options.loading)
+
+      const data = options.resource.data.value
+      if (data === null) return resolveView(options.empty)
+      return options.children(data)
+    }
+  })
+}
+
+/** Component-shaped API backed by the same no-wrapper boundary instruction. */
+export function ResourceBoundary<T>(props: ResourceBoundaryProps<T>): VobsNode {
+  return createFragment((parent, anchor) => insertResourceBoundary(parent, anchor, props))
+}
+
+function resolveView(view: ResourceBoundaryView | undefined): ReturnType<NodeFactory> {
+  if (!view) return null
+  return typeof view === 'function' ? view() : view
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+export {
+  createResourceClient,
+  resource,
+  stableSerialize,
+  serializeResourceState
+} from './resource'
+export { insertResourceBoundary, ResourceBoundary } from './boundary'
+export type {
+  Resource,
+  ResourceCacheStrategy,
+  ResourceClient,
+  ResourceClientOptions,
+  ResourceDehydratedEntry,
+  ResourceDehydratedState,
+  ResourceFetcher,
+  ResourceKey,
+  ResourceKeySource,
+  ResourceOptions,
+  RetryDelay,
+  ResourceSnapshot
+} from './resource'
+export type {
+  ResourceBoundaryChild,
+  ResourceBoundaryFallback,
+  ResourceBoundaryOptions,
+  ResourceBoundaryProps,
+  ResourceBoundaryView
+} from './boundary'
+export { RESOURCE_KEY, resourcePlugin, resourceRouterPlugin } from './plugin'
+export type {
+  ResourcePluginOptions,
+  ResourceRoutePrefetchContext,
+  ResourceRoutePrefetch,
+  ResourceRouterPluginOptions
+} from './plugin'

package/src/plugin.ts

@@ -0,0 +1,70 @@
+import { createInjectionKey, type VobsPlugin } from '@vobs/vobs'
+import { ROUTER_KEY, type RouteLocation, type Router } from '@vobs/router'
+import { createResourceClient, type ResourceClient, type ResourceClientOptions } from './resource'
+
+export const RESOURCE_KEY = createInjectionKey<ResourceClient>('vobs.resource')
+
+export interface ResourcePluginOptions extends ResourceClientOptions {
+  client?: ResourceClient
+}
+
+export interface ResourceRoutePrefetchContext {
+  readonly route: RouteLocation
+  readonly client: ResourceClient
+}
+
+export type ResourceRoutePrefetch = (
+  context: ResourceRoutePrefetchContext
+) => unknown | PromiseLike<unknown>
+
+export interface ResourceRouterPluginOptions {
+  readonly router?: Router
+  readonly client?: ResourceClient
+}
+
+export function resourcePlugin(options: ResourcePluginOptions = {}): VobsPlugin {
+  return {
+    name: '@vobs/resource',
+    version: '0.1.0',
+    install(context) {
+      const client = options.client ?? createResourceClient(options)
+      context.provide(RESOURCE_KEY, client)
+      return () => {
+        if (!options.client) client.clear()
+      }
+    }
+  }
+}
+
+export function resourceRouterPlugin(options: ResourceRouterPluginOptions = {}): VobsPlugin {
+  return {
+    name: '@vobs/resource-router',
+    version: '0.1.0',
+    install(context) {
+      const router = options.router ?? context.inject(ROUTER_KEY)
+      const client = options.client ?? context.inject(RESOURCE_KEY)
+      if (!router) throw new Error('Vobs Resource Router: 找不到 Router，请安装 routerPlugin 或传入 router')
+      if (!client) throw new Error('Vobs Resource Router: 找不到 ResourceClient，请安装 resourcePlugin 或传入 client')
+
+      return router.beforeEach(async to => {
+        const prefetch = readPrefetch(to)
+        await Promise.all(prefetch.map((task, index) => router.devtools.trackDataRequest(
+          'loader',
+          `${to.fullPath}#prefetch-${index + 1}`,
+          () => task({ route: to, client }),
+          { route: to.fullPath, trigger: 'resource' }
+        )))
+      })
+    }
+  }
+}
+
+function readPrefetch(route: RouteLocation): readonly ResourceRoutePrefetch[] {
+  const value = route.meta.prefetch
+  if (value === undefined) return []
+  if (typeof value === 'function') return [value as ResourceRoutePrefetch]
+  if (!Array.isArray(value) || value.some(task => typeof task !== 'function')) {
+    throw new Error('Vobs Resource Router: route.meta.prefetch 必须是函数或函数数组')
+  }
+  return value as ResourceRoutePrefetch[]
+}