@vobs/resource 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vobsjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/resource
+ */
+import { type ReadonlySignal } from '@vobs/reactivity';
+import { type Owner } from '@vobs/runtime-core';
+/**
+ * Implementation of the Resource And Action contract (docs/contracts/resource-action.md).
+ *
+ * Declarative async data resources: three-state machine (loading/error/data), key-based caching with
+ * concurrent deduplication, AbortSignal cancellation + race protection, invalidate/refetch, optimistic mutation.
+ */
+export interface ResourceSourceContext {
+    readonly signal: AbortSignal;
+    readonly key: string;
+}
+export type ResourceSource<T> = (context: ResourceSourceContext) => Promise<T> | T;
+/** Cache entry (the unit stored by ResourceCache): wraps data + state (contract §2). */
+export interface CacheEntry<T> {
+    readonly data: T;
+}
+export interface ResourceCache<T> {
+    get(key: string): Promise<CacheEntry<T>> | CacheEntry<T> | undefined;
+    set(key: string, entry: CacheEntry<T>): void;
+    delete(key: string): void;
+    clear(): void;
+}
+export interface ResourceOptions<T> {
+    /** Owner the resource belongs to (default currentOwner); in-flight work is cancelled and released on Owner disposal. */
+    readonly owner?: Owner;
+    /** Cache key; defaults to an independent counter per resource instance. */
+    readonly key?: string;
+    /** Custom cache (defaults to an in-process Map). */
+    readonly cache?: ResourceCache<T>;
+}
+export interface Resource<T> {
+    readonly key: string;
+    readonly data: ReadonlySignal<T | undefined>;
+    readonly error: ReadonlySignal<unknown>;
+    readonly loading: ReadonlySignal<boolean>;
+    /** Force a refetch (ignores the cache). */
+    refetch(): Promise<void>;
+    /** Invalidates the cached entry and refetches. */
+    invalidate(): Promise<void>;
+    /** Optimistically updates local data; rolls back and sets error if the updater throws. */
+    mutate(updater: (current: T | undefined) => T | Promise<T>): Promise<void>;
+    /**
+     * Resolves on first fetch settle (success/failure/cancel/sync hit/disposal) — SSR async setup
+     * awaits resource readiness before serializing (resource-action §8 assembly pattern). Idempotent.
+     */
+    whenReady(): Promise<void>;
+    /** Releases: cancels in-flight work and cleans up (idempotent). */
+    dispose(): void;
+}
+export declare function createResource<T>(source: ResourceSource<T>, options?: ResourceOptions<T>): Resource<T>;
+export { createResourceLoader, isResourceAbortError, type ResourceLoader, type ResourceLoaderContext, type ResourceLoaderOptions, } from './loader.js';
+/**
+ * Server-state serialization helper (resource-action.md §8 + ADR-0002):
+ *
+ * On the SSR side, ready Resource data is extracted into a JSON-serializable snapshot (injected with the page
+ * initial state); before client hydration, the snapshot pre-fills the cache so createResource for the same key
+ * hits the cache without re-requesting (symmetric rebuild, identical first screen).
+ *
+ * Assembly lives in the host/app layer: server-renderer does not depend on the resource package (dependency direction);
+ * SSR serializes → injects initial state → client createHydratedCache + createResource.
+ */
+/** Serializable snapshot of a single Resource (data only, without error/loading transients, see contract §8). */
+export interface ResourceStateSnapshot<T = unknown> {
+    readonly key: string;
+    readonly data: T;
+}
+/**
+ * Extracts a single Resource snapshot; returns undefined when data is not ready (undefined) or
+ * the default key (`resource:N`) is used (unstable across processes, SSR serialization must use explicit keys, see contract §8).
+ */
+export declare function serializeResourceState<T>(resource: Resource<T>): ResourceStateSnapshot<T> | undefined;
+export interface SerializeResourceStatesOptions {
+    /** Callback invoked when a default key (`resource:N`) is skipped — prevents silent mismatches (contract §8). */
+    readonly onWarning?: (key: string) => void;
+}
+/** Batch extraction; skips unready resources and default-key resources (the latter are reported via onWarning). */
+export declare function serializeResourceStates<T>(resources: readonly Resource<T>[], options?: SerializeResourceStatesOptions): ResourceStateSnapshot<T>[];
+/**
+ * Client hydration: builds a pre-filled cache from snapshots (a get hit returns immediately without calling source).
+ * Consistent with createResource's cache contract (ResourceCache stores CacheEntry items).
+ */
+export declare function createHydratedCache<T>(snapshots: readonly ResourceStateSnapshot<T>[]): ResourceCache<T>;
+/**
+ * Action (business mutation, resource-action.md §5 + ADR-0002):
+ *
+ * A stateful write primitive separated from Resource's read responsibility. Three-state signals
+ * (pending/error/data), AbortSignal cancellation + race protection, Owner ownership; on success it can
+ * invalidate declared associated Resource cache keys (read-write linkage loop).
+ *
+ * Difference from `mutate`: mutate is a resource-level optimistic update (mutates local data, no pending
+ * semantics, no invalidation linkage); Action is a business-level write (form submit/change API) that refreshes the read side on success.
+ */
+export interface ActionSourceContext<Args> {
+    readonly signal: AbortSignal;
+    readonly args: Args;
+}
+export type ActionSource<Args, T> = (context: ActionSourceContext<Args>) => Promise<T> | T;
+export interface ActionOptions<Args, T> {
+    /** Owner the Action belongs to (default currentOwner); in-flight work is cancelled on Owner disposal. */
+    readonly owner?: Owner;
+    /** Resource cache keys invalidated on success (read-write linkage: the read side auto-refreshes after a write). */
+    readonly invalidates?: readonly string[] | ((args: Args, data: T) => readonly string[]);
+}
+export interface Action<Args = void, T = unknown> {
+    readonly pending: ReadonlySignal<boolean>;
+    readonly error: ReadonlySignal<unknown>;
+    readonly data: ReadonlySignal<T | undefined>;
+    /** Runs one write. Cancellation (AbortError) does not set error; the returned Promise resolves on completion. */
+    run(args: Args): Promise<T>;
+    /** Cleans up: cancels in-flight work (idempotent). */
+    dispose(): void;
+}
+export declare function createAction<Args, T>(source: ActionSource<Args, T>, options?: ActionOptions<Args, T>): Action<Args, T>;

package/dist/index.js

@@ -0,0 +1,308 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/resource
+ */
+import { signal } from '@vobs/reactivity';
+import { currentOwner, createRuntimeError } from '@vobs/runtime-core';
+const defaultCacheStore = new Map();
+// Cross-instance concurrent deduplication per key (contract §2): dedup tables are isolated per cache instance
+// (an SSR per-request cache gets per-request deduplication without cross-contamination; the default cache shares one table, matching historical behavior).
+const cacheInFlightTables = new WeakMap();
+let defaultKeyCounter = 0;
+/** Default key pattern (generated by a process-level counter, unstable across processes — SSR serialization must use explicit keys). */
+const DEFAULT_KEY_PATTERN = /^resource:\d+$/u;
+function inFlightTable(cache) {
+    let table = cacheInFlightTables.get(cache);
+    if (table === undefined) {
+        table = new Map();
+        cacheInFlightTables.set(cache, table);
+    }
+    return table;
+}
+function isPromiseLike(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'then' in value &&
+        typeof value.then === 'function');
+}
+function isAbortError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'AbortError');
+}
+export function createResource(source, options = {}) {
+    const key = options.key ?? `resource:${defaultKeyCounter++}`;
+    const cache = (options.cache ?? defaultCacheStore);
+    const inFlight = inFlightTable(cache);
+    const owner = options.owner ?? currentOwner();
+    const data = signal(undefined);
+    const error = signal(undefined);
+    const loading = signal(false);
+    let controller;
+    let fetchToken = 0;
+    let disposed = false;
+    let readyResolved = false;
+    let resolveReady;
+    const ready = new Promise((resolve) => {
+        resolveReady = resolve;
+    });
+    const markReady = () => {
+        if (readyResolved)
+            return;
+        readyResolved = true;
+        resolveReady?.();
+    };
+    const applySuccess = (value, token) => {
+        if (disposed || token !== fetchToken)
+            return;
+        cache.set(key, { data: value });
+        data.value = value;
+        error.value = undefined;
+        loading.value = false;
+        markReady();
+    };
+    const applyFailure = (failure, token) => {
+        if (disposed || token !== fetchToken)
+            return;
+        if (isAbortError(failure)) {
+            // Cancelled: no error, no retry (contract §5); cancellation also counts as first settle (SSR await does not hang).
+            loading.value = false;
+            markReady();
+            return;
+        }
+        error.value = failure;
+        loading.value = false;
+        markReady();
+    };
+    const run = async (token) => {
+        controller?.abort();
+        controller = new AbortController();
+        loading.value = true;
+        // Sync hit (hydrated/pre-warmed cache): data is readable on the first frame of template rendering (contract §8 sync readiness).
+        const maybeCached = cache.get(key);
+        if (maybeCached !== undefined && !isPromiseLike(maybeCached)) {
+            if (disposed || token !== fetchToken)
+                return;
+            data.value = maybeCached.data;
+            error.value = undefined;
+            loading.value = false;
+            markReady();
+            return;
+        }
+        // Miss: a single await yields uniformly (a Promise awaits resolve / a sync value is wrapped in a resolved promise) —
+        // if dispose or a new refetch runs during the yield, this run terminates (cancelled runs never call source, contract semantics).
+        const cached = await Promise.resolve(maybeCached);
+        if (disposed || token !== fetchToken)
+            return;
+        if (cached !== undefined) {
+            data.value = cached.data;
+            error.value = undefined;
+            loading.value = false;
+            markReady();
+            return;
+        }
+        let promise = inFlight.get(key);
+        if (promise === undefined) {
+            // Snapshot the signal: this.controller may have been set to undefined by dispose when the then-callback runs.
+            const requestSignal = controller.signal;
+            promise = Promise.resolve().then(() => source({ signal: requestSignal, key }));
+            inFlight.set(key, promise);
+            promise.then(() => {
+                inFlight.delete(key);
+            }, () => {
+                inFlight.delete(key);
+            });
+        }
+        try {
+            const value = await promise;
+            if (disposed || token !== fetchToken)
+                return;
+            applySuccess(value, token);
+        }
+        catch (failure) {
+            if (disposed || token !== fetchToken)
+                return;
+            applyFailure(failure, token);
+        }
+    };
+    const refetch = () => {
+        if (disposed) {
+            throw createRuntimeError('VOR580', 'Resource is disposed');
+        }
+        fetchToken += 1;
+        const token = fetchToken;
+        cache.delete(key);
+        return run(token);
+    };
+    const invalidate = () => {
+        if (disposed)
+            return Promise.resolve();
+        cache.delete(key);
+        return refetch();
+    };
+    const mutate = async (updater) => {
+        if (disposed) {
+            throw createRuntimeError('VOR580', 'Resource is disposed');
+        }
+        const previous = data.value;
+        try {
+            const next = await updater(previous);
+            if (disposed)
+                return;
+            data.value = next;
+            cache.set(key, { data: next });
+            error.value = undefined;
+        }
+        catch (failure) {
+            if (disposed)
+                return;
+            data.value = previous;
+            error.value = failure;
+            throw failure;
+        }
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        controller?.abort();
+        controller = undefined;
+        fetchToken += 1;
+        loading.value = false;
+        // Clean the in-flight entry on cancellation: a pending promise that was aborted before source responded
+        // must not poison later requests for the same key (a new request would hang on a dead promise).
+        inFlight.delete(key);
+        // Disposal counts as settle (SSR await on whenReady does not hang).
+        markReady();
+    };
+    if (owner !== undefined) {
+        owner.own(dispose);
+    }
+    void run(fetchToken);
+    return {
+        key,
+        data,
+        error,
+        loading,
+        refetch,
+        invalidate,
+        mutate,
+        whenReady: () => ready,
+        dispose,
+    };
+}
+export { createResourceLoader, isResourceAbortError, } from './loader.js';
+/**
+ * Extracts a single Resource snapshot; returns undefined when data is not ready (undefined) or
+ * the default key (`resource:N`) is used (unstable across processes, SSR serialization must use explicit keys, see contract §8).
+ */
+export function serializeResourceState(resource) {
+    const data = resource.data.value;
+    if (data === undefined)
+        return undefined;
+    if (DEFAULT_KEY_PATTERN.test(resource.key))
+        return undefined;
+    return { key: resource.key, data };
+}
+/** Batch extraction; skips unready resources and default-key resources (the latter are reported via onWarning). */
+export function serializeResourceStates(resources, options = {}) {
+    const snapshots = [];
+    for (const resource of resources) {
+        if (DEFAULT_KEY_PATTERN.test(resource.key)) {
+            options.onWarning?.(resource.key);
+            continue;
+        }
+        const snapshot = serializeResourceState(resource);
+        if (snapshot !== undefined)
+            snapshots.push(snapshot);
+    }
+    return snapshots;
+}
+/**
+ * Client hydration: builds a pre-filled cache from snapshots (a get hit returns immediately without calling source).
+ * Consistent with createResource's cache contract (ResourceCache stores CacheEntry items).
+ */
+export function createHydratedCache(snapshots) {
+    const store = new Map();
+    for (const snapshot of snapshots) {
+        store.set(snapshot.key, { data: snapshot.data });
+    }
+    return {
+        get(key) {
+            return store.get(key);
+        },
+        set(key, entry) {
+            store.set(key, entry);
+        },
+        delete(key) {
+            return store.delete(key);
+        },
+        clear() {
+            store.clear();
+        },
+    };
+}
+export function createAction(source, options = {}) {
+    const owner = options.owner ?? currentOwner();
+    const pending = signal(false);
+    const error = signal(undefined);
+    const data = signal(undefined);
+    let controller;
+    let runToken = 0;
+    let disposed = false;
+    const run = async (args) => {
+        if (disposed) {
+            throw createRuntimeError('VOR580', 'Action is disposed');
+        }
+        controller?.abort();
+        controller = new AbortController();
+        const token = ++runToken;
+        const requestSignal = controller.signal;
+        pending.value = true;
+        try {
+            const value = await Promise.resolve().then(() => source({ signal: requestSignal, args }));
+            if (disposed || token !== runToken)
+                return value;
+            data.value = value;
+            error.value = undefined;
+            pending.value = false;
+            const invalidates = typeof options.invalidates === 'function'
+                ? options.invalidates(args, value)
+                : options.invalidates;
+            if (invalidates !== undefined) {
+                for (const key of invalidates) {
+                    defaultCacheStore.delete(key);
+                }
+            }
+            return value;
+        }
+        catch (failure) {
+            if (disposed || token !== runToken) {
+                if (isAbortError(failure))
+                    return undefined;
+                throw failure;
+            }
+            if (isAbortError(failure)) {
+                // Cancelled: no error, not thrown to the caller (cancellation is cooperative, see contract §6).
+                pending.value = false;
+                return undefined;
+            }
+            error.value = failure;
+            pending.value = false;
+            throw failure;
+        }
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        controller?.abort();
+        controller = undefined;
+        runToken += 1;
+        pending.value = false;
+    };
+    if (owner !== undefined) {
+        owner.own(dispose);
+    }
+    return { pending, error, data, run, dispose };
+}

package/dist/loader.d.ts

@@ -0,0 +1,32 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/resource
+ */
+import { type ResourceCache, type ResourceSource } from './index.js';
+/**
+ * Resource → Router loader adapter (contract resource-action.md §6).
+ *
+ * Wraps a Resource into a function matching the RouteLoader signature; zero changes on the Router side:
+ * - key defaults to route.path (overridable), reusing Resource caching/dedup/cancellation/race protection;
+ * - an external signal (navigation cancellation) bridges into the Resource's internal cancellation;
+ * - clean dependency direction: this package does not depend on @vobs/router, only on structural types.
+ */
+/** Structural subset of the loader context the adapter accepts (aligned with @vobs/router RouteLoaderContext). */
+export interface ResourceLoaderContext {
+    readonly route: {
+        readonly path: string;
+    };
+    readonly signal?: AbortSignal;
+    readonly request?: unknown;
+}
+export interface ResourceLoaderOptions<T> {
+    /** Cache key; defaults to route.path. A function form derives it from the route. */
+    readonly key?: string | ((route: {
+        readonly path: string;
+    }) => string);
+    /** Custom cache (defaults to an in-process Map). */
+    readonly cache?: ResourceCache<T>;
+}
+export type ResourceLoader<T> = (context: ResourceLoaderContext) => Promise<T>;
+export declare function createResourceLoader<T>(source: ResourceSource<T>, options?: ResourceLoaderOptions<T>): ResourceLoader<T>;
+export declare function isResourceAbortError(error: unknown): boolean;

package/dist/loader.js

@@ -0,0 +1,93 @@
+/** @license MIT
+ * Copyright (c) 2026 vobsjs
+ * @vobs/resource
+ */
+import { createResource } from './index.js';
+function isAbortError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'AbortError');
+}
+function readResourceLoaderKey(policy, route) {
+    if (typeof policy === 'function')
+        return policy(route);
+    return policy ?? route.path;
+}
+export function createResourceLoader(source, options = {}) {
+    return (context) => {
+        const key = readResourceLoaderKey(options.key, context.route);
+        const resource = createResource(source, {
+            key,
+            ...(options.cache === undefined ? {} : { cache: options.cache }),
+        });
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let externalAbortListener;
+            let unsubscribers;
+            const settle = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (externalAbortListener !== undefined) {
+                    context.signal?.removeEventListener('abort', externalAbortListener);
+                    externalAbortListener = undefined;
+                }
+                if (unsubscribers !== undefined) {
+                    for (const unsubscribe of unsubscribers)
+                        unsubscribe();
+                    unsubscribers = undefined;
+                }
+                resource.dispose();
+                result();
+            };
+            // external signal (navigation cancellation) → bridge into the Resource's internal cancellation
+            const onExternalAbort = () => {
+                settle(() => reject(createAbortError()));
+            };
+            if (context.signal !== undefined) {
+                if (context.signal.aborted) {
+                    settle(() => reject(createAbortError()));
+                    return;
+                }
+                context.signal.addEventListener('abort', onExternalAbort);
+                externalAbortListener = onExternalAbort;
+            }
+            // Watch the three states: settle when loading ends (data or error). onChange is the public subscription
+            // surface (P1 fix, replacing the previous type cast of ReadonlySignal).
+            const check = () => {
+                if (settled)
+                    return;
+                if (resource.loading.value)
+                    return;
+                const failure = resource.error.value;
+                if (failure !== undefined) {
+                    settle(() => reject(toError(failure)));
+                    return;
+                }
+                settle(() => resolve(resource.data.value));
+            };
+            unsubscribers = [
+                resource.data.onChange(check),
+                resource.error.onChange(check),
+                resource.loading.onChange(check),
+            ];
+            check();
+        });
+    };
+}
+function createAbortError() {
+    const error = new Error('Resource loader aborted');
+    error.name = 'AbortError';
+    return error;
+}
+/** Normalizes any failure value into an Error (promise rejection requires an Error). */
+function toError(failure) {
+    if (isAbortError(failure))
+        return createAbortError();
+    if (failure instanceof Error)
+        return failure;
+    return new Error(String(failure));
+}
+export function isResourceAbortError(error) {
+    return isAbortError(error);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vobs/resource",
+  "version": "0.1.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.1.0",
+    "@vobs/runtime-core": "0.1.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}