@vizejs/data 0.0.0-stage → 0.713.0

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @vizejs/data
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Typed SSR data resource foundations for Vize applications.
+
+> This package is released on npm as `@vizejs/data`; its resource and adapter contracts remain
+> experimental throughout the Vize alpha line.
+
+```vue
+<script setup lang="ts">
+import { createDataClient, defineDataResource } from "@vizejs/data";
+
+const articleResource = defineDataResource({
+  key: "article.byId",
+  source: "./ArticleView.vue",
+  async loader({ input }: { input: { id: string } }) {
+    return { id: input.id, title: "Hello Vize" };
+  },
+});
+
+const data = createDataClient();
+const article = await data.load(
+  articleResource,
+  { id: "intro" },
+  {
+    retries: 2,
+    retryDelayMs: ({ attempt }) => attempt * 100,
+    deadlineMs: 1500,
+  },
+);
+</script>
+
+<template>
+  <article v-if="article.status === 'success'">
+    {{ article.data.title }}
+  </article>
+</template>
+```
+
+Server renderers can call `serializeDataSnapshot(data)` and hydrate the client with
+`hydrateDataClient(snapshot)`. Hydrated success entries satisfy the first client load without
+issuing duplicate network work; `policy: "replace"` opts back into a fresh request.
+
+## Cache, races, and optimistic work
+
+The client supports deduplication, cache-first reads, explicit revalidation, replacement, and
+stale-while-revalidate. Each request key has latest-result custody: an older response may resolve to
+its caller, but cannot overwrite a newer cache entry. `replace` aborts the previous request, while
+`cancel` exposes route- or scope-owned cancellation. Optimistic updates return a guarded rollback;
+the rollback refuses to overwrite data that a later request has already committed.
+
+```ts
+const rollback = data.optimistic(articleResource, { id: "intro" }, (article) => ({
+  ...article,
+  title: "Draft title",
+}));
+
+const stale = await data.load(
+  articleResource,
+  { id: "intro" },
+  {
+    policy: "stale-while-revalidate",
+  },
+);
+```
+
+## Runtime adapters
+
+`createFetchDataResource` adapts typed HTTP endpoints, `createStreamDataResource` reduces an
+abort-aware async iterable, and `hydrateDataClientFromStream` restores incremental SSR snapshots.
+None of them reads browser globals during module evaluation. `createDataTestAdapter` supplies a
+deterministic response queue and records every load context for race, retry, and cancellation tests.
+Resources can return an explicit unsupported reason from `supports` before their loader runs.

package/dist/index.d.mts

@@ -0,0 +1,296 @@
+//#region src/types.d.ts
+/** Source-owned Vue file that documents where a resource is used. */
+type DataSourceSpecifier = `${string}.vue`;
+/** Serializable metadata that generators and devtools can consume. */
+type DataResourceMeta = Readonly<Record<string, unknown>>;
+/** Stable resource key. Prefer domain-qualified literals such as `article.byId`. */
+type DataResourceKey = string;
+/** Reason a fetch was started or refreshed. */
+type DataLoadReason = "initial" | "hydrate" | "refresh" | "retry" | "optimistic";
+/** Context passed to every resource loader. */
+interface DataLoadContext<Input = unknown> {
+  readonly key: DataResourceKey;
+  readonly input: Input;
+  readonly meta: DataResourceMeta;
+  readonly reason: DataLoadReason;
+  readonly signal: AbortSignal;
+}
+/** Loader invoked by server renderers, client hydration, or manual refreshes. */
+type DataLoader<Input, Data> = {
+  bivarianceHack(context: DataLoadContext<Input>): Data | Promise<Data>;
+}["bivarianceHack"];
+/** Host capability check for a resource input. Return a reason to explain unsupported hosts. */
+type DataSupport<Input> = {
+  bivarianceHack(input: Input): boolean | string;
+}["bivarianceHack"];
+/** Typed data endpoint accepted by createDataClient. */
+interface DataResourceDefinition<Key extends DataResourceKey = DataResourceKey, Input = unknown, Data = unknown, ErrorPayload = unknown, Meta extends DataResourceMeta = DataResourceMeta> {
+  readonly key: Key;
+  readonly source: DataSourceSpecifier;
+  readonly meta?: Meta;
+  readonly loader: DataLoader<Input, Data>;
+  readonly serializeError?: (error: unknown) => ErrorPayload;
+  /** Return false or a reason when the active host cannot load this resource. */
+  readonly supports?: DataSupport<Input>;
+}
+/** Broad resource definition used by registries, clients, and generated manifests. */
+type AnyDataResourceDefinition = DataResourceDefinition<DataResourceKey, unknown, unknown, unknown, DataResourceMeta>;
+/** Resolve the successful payload type declared by a resource. */
+type InferData<Resource> = Resource extends DataResourceDefinition<DataResourceKey, infer _Input, infer Data> ? Data : never;
+/** Resolve the serialized error payload type declared by a resource. */
+type InferError<Resource> = Resource extends DataResourceDefinition<DataResourceKey, infer _Input, infer _Data, infer ErrorPayload> ? ErrorPayload : never;
+/** Resolve the loader input type declared by a resource. */
+type InferInput<Resource> = Resource extends DataResourceDefinition<infer _Key, infer Input> ? Input : never;
+/** Resolve a resource's literal key, falling back to the public key type. */
+type InferKey<Resource> = Resource extends {
+  readonly key: infer Key extends DataResourceKey;
+} ? Key : DataResourceKey;
+/** Complete lifecycle state for one keyed resource request. */
+type DataState<Key extends DataResourceKey = DataResourceKey, Input = unknown, Data = unknown, ErrorPayload = unknown> = DataIdleState<Key, Input> | DataPendingState<Key, Input> | DataSuccessState<Key, Input, Data> | DataStaleState<Key, Input, Data> | DataCancelledState<Key, Input> | DataUnsupportedState<Key, Input> | DataErrorState<Key, Input, ErrorPayload>;
+/** Identity shared by every resource lifecycle state. */
+interface DataStateBase<Key extends DataResourceKey, Input> {
+  readonly key: Key;
+  readonly input: Input;
+  readonly requestKey: string;
+}
+/** Resource request that has not started. */
+interface DataIdleState<Key extends DataResourceKey, Input> extends DataStateBase<Key, Input> {
+  readonly status: "idle";
+}
+/** Resource request with an active loader attempt. */
+interface DataPendingState<Key extends DataResourceKey, Input> extends DataStateBase<Key, Input> {
+  readonly status: "pending";
+  readonly attempt: number;
+  readonly startedAt: number;
+}
+/** Resource request whose current data completed successfully. */
+interface DataSuccessState<Key extends DataResourceKey, Input, Data> extends DataStateBase<Key, Input> {
+  readonly status: "success";
+  readonly data: Data;
+  readonly updatedAt: number;
+}
+/** Previously successful data marked for refresh or optimistic reconciliation. */
+interface DataStaleState<Key extends DataResourceKey, Input, Data> extends DataStateBase<Key, Input> {
+  readonly status: "stale";
+  readonly data: Data;
+  readonly staleAt: number;
+  readonly updatedAt: number;
+  readonly reason?: string;
+}
+/** Resource request cancelled before it could commit data. */
+interface DataCancelledState<Key extends DataResourceKey, Input> extends DataStateBase<Key, Input> {
+  readonly status: "cancelled";
+  readonly cancelledAt: number;
+  readonly reason: string;
+}
+/** Resource request rejected by its host capability check. */
+interface DataUnsupportedState<Key extends DataResourceKey, Input> extends DataStateBase<Key, Input> {
+  readonly status: "unsupported";
+  readonly reason: string;
+}
+/** Resource request that exhausted its loader and retry policy. */
+interface DataErrorState<Key extends DataResourceKey, Input, ErrorPayload> extends DataStateBase<Key, Input> {
+  readonly status: "error";
+  readonly error: ErrorPayload;
+  readonly updatedAt: number;
+}
+/** Context used to compute deterministic retry backoff. */
+interface DataRetryDelayContext<Key extends DataResourceKey = DataResourceKey, Input = unknown> {
+  readonly key: Key;
+  readonly input: Input;
+  readonly attempt: number;
+  readonly error: unknown;
+}
+/** Retry backoff in milliseconds or a deterministic backoff factory. */
+type DataRetryDelay<Key extends DataResourceKey = DataResourceKey, Input = unknown> = number | ((context: DataRetryDelayContext<Key, Input>) => number);
+/** Testable sleep hook used by retry backoff. */
+type DataSleep = (milliseconds: number, signal: AbortSignal) => Promise<void>;
+/** Per-request cache, cancellation, and retry policy. */
+interface DataLoadOptions<Key extends DataResourceKey = DataResourceKey, Input = unknown> {
+  /**
+   * Reason exposed to the first loader attempt.
+   *
+   * @default "initial"
+   */
+  readonly reason?: DataLoadReason;
+  /**
+   * External abort signal linked to the request-owned controller.
+   *
+   * @default undefined
+   */
+  readonly signal?: AbortSignal;
+  /**
+   * Cache and in-flight request policy.
+   *
+   * @default "dedupe"
+   */
+  readonly policy?: "dedupe" | "cache-first" | "revalidate" | "replace" | "stale-while-revalidate";
+  /**
+   * Additional attempts after the first loader call.
+   *
+   * @default 0
+   */
+  readonly retries?: number;
+  /**
+   * Backoff before retry attempts.
+   *
+   * @default 0
+   */
+  readonly retryDelayMs?: DataRetryDelay<Key, Input>;
+  /**
+   * Abort the load after this many milliseconds.
+   *
+   * @default undefined
+   */
+  readonly deadlineMs?: number;
+}
+/** Cache-owning resource client used by SSR and hydrated applications. */
+interface DataClient {
+  readonly load: <Resource extends AnyDataResourceDefinition>(resource: Resource, input: InferInput<Resource>, options?: DataLoadOptions<InferKey<Resource>, InferInput<Resource>>) => Promise<DataState<InferKey<Resource>, InferInput<Resource>, InferData<Resource>, InferError<Resource>>>;
+  readonly peek: <Resource extends AnyDataResourceDefinition>(resource: Resource, input: InferInput<Resource>) => DataState<InferKey<Resource>, InferInput<Resource>, InferData<Resource>, InferError<Resource>> | undefined;
+  readonly invalidate: <Resource extends AnyDataResourceDefinition>(resource: Resource, input?: InferInput<Resource>, reason?: string) => number;
+  readonly optimistic: <Resource extends AnyDataResourceDefinition>(resource: Resource, input: InferInput<Resource>, update: (current: InferData<Resource>) => InferData<Resource>) => () => boolean;
+  readonly cancel: <Resource extends AnyDataResourceDefinition>(resource: Resource, input: InferInput<Resource>, reason?: unknown) => boolean;
+  readonly subscribe: (listener: (state: DataState) => void) => () => void;
+  readonly snapshot: () => DataSnapshot;
+}
+/** Deterministic hooks and initial cache state for a data client. */
+interface DataClientOptions {
+  /**
+   * Clock used for lifecycle timestamps.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+  /**
+   * Server snapshot used to seed the cache.
+   *
+   * @default undefined
+   */
+  readonly snapshot?: DataSnapshot;
+  /**
+   * Abort-aware wait implementation used by retry backoff.
+   *
+   * @default built-in setTimeout-based sleep
+   */
+  readonly sleep?: DataSleep;
+}
+/** Versioned collection of serializable resource states for hydration. */
+interface DataSnapshot {
+  readonly schemaVersion: 1;
+  readonly resources: readonly SerializedDataState[];
+}
+/** Resource states that may cross the server-to-client boundary. */
+type SerializedDataState = DataSuccessState<DataResourceKey, unknown, unknown> | DataStaleState<DataResourceKey, unknown, unknown> | DataCancelledState<DataResourceKey, unknown> | DataUnsupportedState<DataResourceKey, unknown> | DataErrorState<DataResourceKey, unknown, unknown>;
+/** Versioned resource metadata emitted for tooling and documentation. */
+interface DataManifest {
+  readonly schemaVersion: 1;
+  readonly resources: readonly DataManifestEntry[];
+}
+/** One resource's stable key, source owner, and serializable metadata. */
+interface DataManifestEntry {
+  readonly key: DataResourceKey;
+  readonly source: DataSourceSpecifier;
+  readonly meta: DataResourceMeta;
+}
+//#endregion
+//#region src/runtime.d.ts
+/** Define a typed SSR data resource and preserve literal endpoint metadata. */
+declare function defineDataResource<const Key extends DataResourceKey, Input, Data, ErrorPayload = unknown, const Meta extends DataResourceMeta = DataResourceMeta>(resource: DataResourceDefinition<Key, Input, Data, ErrorPayload, Meta>): DataResourceDefinition<Key, Input, Data, ErrorPayload, Meta>;
+/** Create an SSR-safe data client with request deduplication and hydration cache. */
+declare function createDataClient(options?: DataClientOptions): DataClient;
+/** Serialize the current cache into an SSR payload. */
+declare function serializeDataSnapshot(client: Pick<DataClient, "snapshot">): DataSnapshot;
+/** Hydrate a data client from a server-rendered payload. */
+declare function hydrateDataClient(snapshot: DataSnapshot, options?: Omit<DataClientOptions, "snapshot">): DataClient;
+/** Emit metadata for generators, documentation, and devtools. */
+declare function createDataManifest<const Resources extends readonly AnyDataResourceDefinition[]>(resources: Resources): DataManifest;
+/** Stream a snapshot as deterministic records for render pipelines. */
+declare function streamDataSnapshot(snapshot: DataSnapshot): AsyncGenerator<SerializedDataState, void, void>;
+//#endregion
+//#region src/adapters.d.ts
+/** HTTP loader failure with the response status and decoded error body. */
+declare class DataHttpError extends Error {
+  readonly status: number;
+  readonly statusText: string;
+  readonly body: unknown;
+  constructor(response: Response, body: unknown);
+}
+/** Typed HTTP endpoint and decoding policy for a fetch-backed resource. */
+interface FetchDataResourceOptions<Key extends DataResourceKey, Input, Data, ErrorPayload = unknown, Meta extends DataResourceMeta = DataResourceMeta> {
+  readonly key: Key;
+  readonly source: DataSourceSpecifier;
+  readonly endpoint: (input: Input) => string | URL;
+  /**
+   * Request initialization derived from the typed input.
+   *
+   * @default undefined
+   */
+  readonly init?: (input: Input) => RequestInit;
+  /**
+   * Fetch implementation used by the loader.
+   *
+   * @default globalThis.fetch
+   */
+  readonly fetch?: typeof globalThis.fetch;
+  /**
+   * Successful response decoder.
+   *
+   * @default response.json()
+   */
+  readonly decode?: (response: Response) => Data | Promise<Data>;
+  /**
+   * Failed response body decoder.
+   *
+   * @default response.text(), falling back to undefined
+   */
+  readonly decodeError?: (response: Response) => unknown;
+  /**
+   * Error payload serializer forwarded to the resource definition.
+   *
+   * @default undefined
+   */
+  readonly serializeError?: (error: unknown) => ErrorPayload;
+  /**
+   * Serializable metadata forwarded to manifests and loaders.
+   *
+   * @default {}
+   */
+  readonly meta?: Meta;
+}
+/** Adapt a typed HTTP endpoint without reading `fetch` during module evaluation. */
+declare function createFetchDataResource<const Key extends DataResourceKey, Input, Data, ErrorPayload = unknown, const Meta extends DataResourceMeta = DataResourceMeta>(options: FetchDataResourceOptions<Key, Input, Data, ErrorPayload, Meta>): DataResourceDefinition<Key, Input, Data, ErrorPayload, Meta>;
+/** Typed async stream and reduction policy for a stream-backed resource. */
+interface StreamDataResourceOptions<Key extends DataResourceKey, Input, Chunk, Data, ErrorPayload = unknown, Meta extends DataResourceMeta = DataResourceMeta> {
+  readonly key: Key;
+  readonly source: DataSourceSpecifier;
+  readonly initial: (input: Input) => Data;
+  readonly open: (context: DataLoadContext<Input>) => AsyncIterable<Chunk>;
+  readonly reduce: (data: Data, chunk: Chunk) => Data;
+  /**
+   * Error payload serializer forwarded to the resource definition.
+   *
+   * @default undefined
+   */
+  readonly serializeError?: (error: unknown) => ErrorPayload;
+  /**
+   * Serializable metadata forwarded to manifests and loaders.
+   *
+   * @default {}
+   */
+  readonly meta?: Meta;
+}
+/** Collect an abort-aware async stream into one typed resource state. */
+declare function createStreamDataResource<const Key extends DataResourceKey, Input, Chunk, Data, ErrorPayload = unknown, const Meta extends DataResourceMeta = DataResourceMeta>(options: StreamDataResourceOptions<Key, Input, Chunk, Data, ErrorPayload, Meta>): DataResourceDefinition<Key, Input, Data, ErrorPayload, Meta>;
+/** Reconstruct an SSR cache from an incremental snapshot stream. */
+declare function hydrateDataClientFromStream(stream: AsyncIterable<SerializedDataState>, options?: Parameters<typeof hydrateDataClient>[1]): Promise<DataClient>;
+/** Queue-backed loader and call history exposed to deterministic tests. */
+interface DataTestAdapter<Input, Data> {
+  readonly calls: readonly DataLoadContext<Input>[];
+  readonly loader: (context: DataLoadContext<Input>) => Promise<Data>;
+  readonly enqueue: (result: Data | Error | ((context: DataLoadContext<Input>) => Data | Promise<Data>)) => void;
+}
+/** Deterministic queue-backed loader for resource and hydration tests. */
+declare function createDataTestAdapter<Input, Data>(): DataTestAdapter<Input, Data>;
+//#endregion
+export { AnyDataResourceDefinition, DataCancelledState, DataClient, DataClientOptions, DataErrorState, DataHttpError, DataIdleState, DataLoadContext, DataLoadOptions, DataLoadReason, DataLoader, DataManifest, DataManifestEntry, DataPendingState, DataResourceDefinition, DataResourceKey, DataResourceMeta, DataRetryDelay, DataRetryDelayContext, DataSleep, DataSnapshot, DataSourceSpecifier, DataStaleState, DataState, DataStateBase, DataSuccessState, DataSupport, DataTestAdapter, DataUnsupportedState, FetchDataResourceOptions, InferData, InferError, InferInput, InferKey, SerializedDataState, StreamDataResourceOptions, createDataClient, createDataManifest, createDataTestAdapter, createFetchDataResource, createStreamDataResource, defineDataResource, hydrateDataClient, hydrateDataClientFromStream, serializeDataSnapshot, streamDataSnapshot };

package/dist/index.mjs

@@ -0,0 +1,397 @@
+//#region src/runtime.ts
+const DATA_ERROR = {
+	invalidSource: "VIZE_DATA_SOURCE_NOT_VUE",
+	invalidKey: "VIZE_DATA_INVALID_KEY",
+	invalidDeadline: "VIZE_DATA_INVALID_DEADLINE",
+	invalidRetry: "VIZE_DATA_INVALID_RETRY"
+};
+/** Define a typed SSR data resource and preserve literal endpoint metadata. */
+function defineDataResource(resource) {
+	validateResource(resource);
+	return resource;
+}
+/** Create an SSR-safe data client with request deduplication and hydration cache. */
+function createDataClient(options = {}) {
+	const now = options.now ?? Date.now;
+	const sleep = options.sleep ?? defaultSleep;
+	const cache = /* @__PURE__ */ new Map();
+	const inflight = /* @__PURE__ */ new Map();
+	const versions = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	for (const state of options.snapshot?.resources ?? []) cache.set(state.requestKey, state);
+	return {
+		load(resource, input, loadOptions) {
+			validateResource(resource);
+			const requestKey = createRequestKey(resource.key, input);
+			const cached = cache.get(requestKey);
+			const policy = loadOptions?.policy ?? "dedupe";
+			if (policy !== "revalidate" && policy !== "replace" && policy !== "stale-while-revalidate" && cached?.status === "success") return Promise.resolve(cached);
+			if (policy === "cache-first" && cached != null && cached.status !== "pending") return Promise.resolve(cached);
+			const current = inflight.get(requestKey);
+			if (policy === "dedupe" && current) return current.promise;
+			const staleWhileRevalidate = policy === "stale-while-revalidate" && cached !== void 0 && (cached.status === "success" || cached.status === "stale");
+			if (staleWhileRevalidate && current) return Promise.resolve(cached);
+			if (policy === "replace") current?.controller.abort("replaced");
+			const version = (versions.get(requestKey) ?? 0) + 1;
+			versions.set(requestKey, version);
+			const controller = createLinkedAbortController(loadOptions);
+			const commit = (state) => {
+				if (versions.get(requestKey) !== version) return false;
+				cache.set(requestKey, state);
+				for (const listener of listeners) listener(state);
+				return true;
+			};
+			let immediate = cached;
+			if (staleWhileRevalidate && cached.status === "success") {
+				const stale = {
+					...cached,
+					status: "stale",
+					staleAt: now(),
+					reason: "stale-while-revalidate"
+				};
+				commit(stale);
+				immediate = stale;
+			}
+			const task = runLoadAttempt({
+				commit,
+				input,
+				loadOptions,
+				now,
+				requestKey,
+				resource,
+				signal: controller.signal,
+				sleep
+			}).finally(() => {
+				if (inflight.get(requestKey)?.version === version) inflight.delete(requestKey);
+				controller.dispose();
+			});
+			inflight.set(requestKey, {
+				controller,
+				promise: task,
+				version
+			});
+			return staleWhileRevalidate ? Promise.resolve(immediate) : task;
+		},
+		peek(resource, input) {
+			validateResource(resource);
+			return cache.get(createRequestKey(resource.key, input));
+		},
+		invalidate(resource, input, reason = "manual") {
+			validateResource(resource);
+			const prefix = `${resource.key}:`;
+			let changed = 0;
+			for (const [requestKey, state] of cache) {
+				if (input !== void 0 && requestKey !== createRequestKey(resource.key, input)) continue;
+				if (input === void 0 && !requestKey.startsWith(prefix)) continue;
+				if (state.status !== "success") continue;
+				const stale = {
+					...state,
+					status: "stale",
+					staleAt: now(),
+					reason
+				};
+				cache.set(requestKey, stale);
+				for (const listener of listeners) listener(stale);
+				changed += 1;
+			}
+			return changed;
+		},
+		optimistic(resource, input, update) {
+			validateResource(resource);
+			const requestKey = createRequestKey(resource.key, input);
+			const previous = cache.get(requestKey);
+			if (previous?.status !== "success" && previous?.status !== "stale") return () => false;
+			const optimistic = {
+				...previous,
+				status: "stale",
+				data: update(previous.data),
+				staleAt: now(),
+				reason: "optimistic"
+			};
+			cache.set(requestKey, optimistic);
+			for (const listener of listeners) listener(optimistic);
+			return () => {
+				if (cache.get(requestKey) !== optimistic) return false;
+				cache.set(requestKey, previous);
+				for (const listener of listeners) listener(previous);
+				return true;
+			};
+		},
+		cancel(resource, input, reason = "cancelled") {
+			validateResource(resource);
+			const requestKey = createRequestKey(resource.key, input);
+			const current = inflight.get(requestKey);
+			if (!current) return false;
+			current.controller.abort(reason);
+			return true;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		snapshot: () => ({
+			schemaVersion: 1,
+			resources: [...cache.values()].filter(isSerializableState)
+		})
+	};
+}
+/** Serialize the current cache into an SSR payload. */
+function serializeDataSnapshot(client) {
+	return client.snapshot();
+}
+/** Hydrate a data client from a server-rendered payload. */
+function hydrateDataClient(snapshot, options = {}) {
+	return createDataClient({
+		...options,
+		snapshot
+	});
+}
+/** Emit metadata for generators, documentation, and devtools. */
+function createDataManifest(resources) {
+	for (const resource of resources) validateResource(resource);
+	return {
+		schemaVersion: 1,
+		resources: resources.map((resource) => ({
+			key: resource.key,
+			source: resource.source,
+			meta: resource.meta ?? {}
+		}))
+	};
+}
+/** Stream a snapshot as deterministic records for render pipelines. */
+async function* streamDataSnapshot(snapshot) {
+	for (const state of snapshot.resources) yield state;
+}
+async function runLoadAttempt(options) {
+	const support = options.resource.supports?.(options.input);
+	if (support === false || typeof support === "string") {
+		const unsupported = {
+			status: "unsupported",
+			key: options.resource.key,
+			input: options.input,
+			requestKey: options.requestKey,
+			reason: typeof support === "string" ? support : "unsupported"
+		};
+		options.commit(unsupported);
+		return unsupported;
+	}
+	const retries = normalizeRetries(options.loadOptions?.retries);
+	for (let attempt = 1;; attempt += 1) {
+		options.commit({
+			status: "pending",
+			key: options.resource.key,
+			input: options.input,
+			requestKey: options.requestKey,
+			attempt,
+			startedAt: options.now()
+		});
+		try {
+			if (options.signal.aborted) return cacheCancelled(options);
+			const data = await options.resource.loader({
+				key: options.resource.key,
+				input: options.input,
+				meta: options.resource.meta ?? {},
+				reason: attempt === 1 ? options.loadOptions?.reason ?? "initial" : "retry",
+				signal: options.signal
+			});
+			if (options.signal.aborted) return cacheCancelled(options);
+			const success = {
+				status: "success",
+				key: options.resource.key,
+				input: options.input,
+				requestKey: options.requestKey,
+				data,
+				updatedAt: options.now()
+			};
+			options.commit(success);
+			return success;
+		} catch (error) {
+			if (options.signal.aborted) return cacheCancelled(options);
+			if (attempt > retries) {
+				const failed = {
+					status: "error",
+					key: options.resource.key,
+					input: options.input,
+					requestKey: options.requestKey,
+					error: options.resource.serializeError?.(error) ?? error,
+					updatedAt: options.now()
+				};
+				options.commit(failed);
+				return failed;
+			}
+			const delay = retryDelay(options.loadOptions?.retryDelayMs, {
+				attempt,
+				error,
+				input: options.input,
+				key: options.resource.key
+			});
+			try {
+				await options.sleep(delay, options.signal);
+			} catch (sleepError) {
+				if (options.signal.aborted) return cacheCancelled(options);
+				const failed = {
+					status: "error",
+					key: options.resource.key,
+					input: options.input,
+					requestKey: options.requestKey,
+					error: options.resource.serializeError?.(sleepError) ?? sleepError,
+					updatedAt: options.now()
+				};
+				options.commit(failed);
+				return failed;
+			}
+		}
+	}
+}
+function cacheCancelled(options) {
+	const cancelled = {
+		status: "cancelled",
+		key: options.resource.key,
+		input: options.input,
+		requestKey: options.requestKey,
+		reason: String(options.signal.reason ?? "aborted"),
+		cancelledAt: options.now()
+	};
+	options.commit(cancelled);
+	return cancelled;
+}
+function normalizeRetries(retries) {
+	if (retries == null) return 0;
+	if (!Number.isInteger(retries) || retries < 0) throw new Error(`[${DATA_ERROR.invalidRetry}] retries must be a non-negative integer`);
+	return retries;
+}
+function retryDelay(retryDelayMs, context) {
+	const value = typeof retryDelayMs === "function" ? retryDelayMs(context) : retryDelayMs ?? 0;
+	if (!Number.isFinite(value) || value < 0) throw new Error(`[${DATA_ERROR.invalidRetry}] retryDelayMs must be a non-negative number`);
+	return value;
+}
+function createLinkedAbortController(loadOptions) {
+	const controller = new AbortController();
+	const abort = () => controller.abort(loadOptions?.signal?.reason ?? "aborted");
+	if (loadOptions?.signal?.aborted) abort();
+	else loadOptions?.signal?.addEventListener("abort", abort, { once: true });
+	let deadline;
+	if (loadOptions?.deadlineMs != null) {
+		if (!Number.isFinite(loadOptions.deadlineMs) || loadOptions.deadlineMs < 0) throw new Error(`[${DATA_ERROR.invalidDeadline}] deadlineMs must be a non-negative number`);
+		if (loadOptions.deadlineMs === 0) controller.abort("deadline");
+		else deadline = setTimeout(() => controller.abort("deadline"), loadOptions.deadlineMs);
+	}
+	return {
+		signal: controller.signal,
+		abort(reason) {
+			controller.abort(reason);
+		},
+		dispose() {
+			if (deadline) clearTimeout(deadline);
+			loadOptions?.signal?.removeEventListener("abort", abort);
+		}
+	};
+}
+function defaultSleep(milliseconds, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	if (milliseconds <= 0) return Promise.resolve();
+	return new Promise((resolve, reject) => {
+		const done = () => {
+			signal.removeEventListener("abort", abort);
+			resolve();
+		};
+		const timeout = setTimeout(done, milliseconds);
+		const abort = () => {
+			clearTimeout(timeout);
+			reject(signal.reason);
+		};
+		signal.addEventListener("abort", abort, { once: true });
+	});
+}
+function createRequestKey(key, input) {
+	return `${key}:${stableStringify(input)}`;
+}
+function stableStringify(value) {
+	if (value == null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`).join(",")}}`;
+}
+function isSerializableState(state) {
+	return state.status !== "idle" && state.status !== "pending";
+}
+function validateResource(resource) {
+	if (!resource.key) throw new Error(`[${DATA_ERROR.invalidKey}] Data resource key is required`);
+	if (!resource.source.endsWith(".vue")) throw new Error(`[${DATA_ERROR.invalidSource}] Data resource ${resource.key} must use .vue`);
+}
+//#endregion
+//#region src/adapters.ts
+/** HTTP loader failure with the response status and decoded error body. */
+var DataHttpError = class extends Error {
+	status;
+	statusText;
+	body;
+	constructor(response, body) {
+		super(`HTTP ${response.status} ${response.statusText}`.trim());
+		this.name = "DataHttpError";
+		this.status = response.status;
+		this.statusText = response.statusText;
+		this.body = body;
+	}
+};
+/** Adapt a typed HTTP endpoint without reading `fetch` during module evaluation. */
+function createFetchDataResource(options) {
+	return defineDataResource({
+		key: options.key,
+		source: options.source,
+		...options.meta === void 0 ? {} : { meta: options.meta },
+		...options.serializeError === void 0 ? {} : { serializeError: options.serializeError },
+		supports: () => options.fetch !== void 0 || typeof globalThis.fetch === "function" || "fetch unavailable",
+		async loader({ input, signal }) {
+			const response = await (options.fetch ?? globalThis.fetch)(options.endpoint(input), {
+				...options.init?.(input),
+				signal
+			});
+			if (!response.ok) throw new DataHttpError(response, options.decodeError ? await options.decodeError(response) : await response.text().catch(() => void 0));
+			return options.decode ? await options.decode(response) : await response.json();
+		}
+	});
+}
+/** Collect an abort-aware async stream into one typed resource state. */
+function createStreamDataResource(options) {
+	return defineDataResource({
+		key: options.key,
+		source: options.source,
+		...options.meta === void 0 ? {} : { meta: options.meta },
+		...options.serializeError === void 0 ? {} : { serializeError: options.serializeError },
+		async loader(context) {
+			let data = options.initial(context.input);
+			for await (const chunk of options.open(context)) {
+				context.signal.throwIfAborted();
+				data = options.reduce(data, chunk);
+			}
+			return data;
+		}
+	});
+}
+/** Reconstruct an SSR cache from an incremental snapshot stream. */
+async function hydrateDataClientFromStream(stream, options = {}) {
+	const resources = [];
+	for await (const state of stream) resources.push(state);
+	return hydrateDataClient({
+		schemaVersion: 1,
+		resources
+	}, options);
+}
+/** Deterministic queue-backed loader for resource and hydration tests. */
+function createDataTestAdapter() {
+	const calls = [];
+	const results = [];
+	return {
+		calls,
+		enqueue: (result) => results.push(result),
+		async loader(context) {
+			calls.push(context);
+			const result = results.shift();
+			if (result === void 0) throw new Error("No queued data test result");
+			if (result instanceof Error) throw result;
+			return typeof result === "function" ? await result(context) : result;
+		}
+	};
+}
+//#endregion
+export { DataHttpError, createDataClient, createDataManifest, createDataTestAdapter, createFetchDataResource, createStreamDataResource, defineDataResource, hydrateDataClient, hydrateDataClientFromStream, serializeDataSnapshot, streamDataSnapshot };

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@vizejs/data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.713.0",
+  "description": "Typed SSR data resource foundations for Vize applications",
+  "keywords": [
+    "data-fetching",
+    "resource",
+    "ssr",
+    "type-safe",
+    "vize",
+    "vue"
+  ],
+  "homepage": "https://github.com/ubugeeei-prod/vize",
+  "bugs": {
+    "url": "https://github.com/ubugeeei-prod/vize/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ubugeeei-prod/vize.git",
+    "directory": "npm/compose/data"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp exec node --test 'src/**/*.test.ts'",
+    "check": "vp check src vite.config.ts && vp exec tsc --noEmit -p tsconfig.json",
+    "check:fix": "vp check --fix src vite.config.ts",
+    "check:types": "vp exec tsc --noEmit -p tsconfig.json",
+    "fmt": "vp fmt --write src vite.config.ts"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:typescript",
+    "tsdown": "catalog:vite-stack",
+    "typescript": "catalog:typescript",
+    "vite-plus": "catalog:vite-stack"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "metadata": {
+    "vize": {
+      "stability": "experimental",
+      "stabilityDocs": "https://github.com/ubugeeei-prod/vize/blob/main/docs/content/stability.md#package-support-tiers"
+    }
+  }
+}