@vertz/fetch 0.2.11 → 0.2.13

package/dist/index.d.ts

@@ -66,6 +66,32 @@ interface ListResponse<T> {
 	nextCursor: string | null;
 	hasNextPage: boolean;
 }
+/** Metadata for entity-backed query descriptors. */
+interface EntityQueryMeta {
+	readonly entityType: string;
+	readonly kind: "get" | "list";
+	readonly id?: string;
+}
+/** Metadata for mutation descriptors. */
+interface MutationMeta {
+	readonly entityType: string;
+	readonly kind: "update" | "delete" | "create";
+	readonly id?: string;
+	readonly body?: unknown;
+	/** Skip MutationEventBus emission on commit. Defaults to false. */
+	readonly skipInvalidation?: boolean;
+}
+/**
+* Callback interface for optimistic updates.
+* Decouples @vertz/fetch from @vertz/ui — fetch defines the contract,
+* ui provides the implementation via EntityStore.
+*/
+interface OptimisticHandler {
+	/** Apply optimistic patch. Returns a rollback function. */
+	apply(meta: MutationMeta, mutationId: string): (() => void) | undefined;
+	/** Commit server-confirmed data after successful mutation. */
+	commit(meta: MutationMeta, mutationId: string, data: unknown): void;
+}
 declare class FetchClient {
 	private readonly config;
 	/**
@@ -106,6 +132,19 @@ interface QueryDescriptor<
 	readonly _tag: "QueryDescriptor";
 	readonly _key: string;
 	readonly _fetch: () => Promise<Result2<T, E>>;
+	/** Entity metadata for entity-backed queries. */
+	readonly _entity?: EntityQueryMeta;
+	/** Phantom field to carry the error type through generics. Never set at runtime. */
+	readonly _error?: E;
+}
+interface MutationDescriptor<
+	T,
+	E = FetchError
+> extends PromiseLike<Result2<T, E>> {
+	readonly _tag: "MutationDescriptor";
+	readonly _key: string;
+	readonly _fetch: () => Promise<Result2<T, E>>;
+	readonly _mutation: MutationMeta;
 	/** Phantom field to carry the error type through generics. Never set at runtime. */
 	readonly _error?: E;
 }
@@ -113,7 +152,12 @@ declare function isQueryDescriptor<
 	T,
 	E = FetchError
 >(value: unknown): value is QueryDescriptor<T, E>;
-declare function createDescriptor<T>(method: string, path: string, fetchFn: () => Promise<FetchResponse<T>>, query?: Record<string, unknown>): QueryDescriptor<T>;
+declare function createDescriptor<T>(method: string, path: string, fetchFn: () => Promise<FetchResponse<T>>, query?: Record<string, unknown>, entity?: EntityQueryMeta): QueryDescriptor<T>;
+declare function isMutationDescriptor<
+	T,
+	E = FetchError
+>(value: unknown): value is MutationDescriptor<T, E>;
+declare function createMutationDescriptor<T>(method: string, path: string, fetchFn: () => Promise<FetchResponse<T>>, mutation: MutationMeta, handler?: OptimisticHandler): MutationDescriptor<T>;
 declare class FetchError2 extends Error {
 	readonly status: number;
 	readonly body?: unknown;
@@ -150,4 +194,4 @@ declare class ServiceUnavailableError extends FetchError2 {
 	constructor(message: string, body?: unknown);
 }
 declare function createErrorFromStatus(status: number, message: string, body?: unknown): FetchError2;
-export { unwrapOr, unwrap, ok, matchError, isQueryDescriptor, isOk, isErr, err, createErrorFromStatus, createDescriptor, UnprocessableEntityError, UnauthorizedError, StreamingRequestOptions, StreamingFormat, ServiceUnavailableError, RetryConfig, Result3 as Result, RequestOptions, RateLimitError, QueryDescriptor, NotFoundError, ListResponse, InternalServerError, HooksConfig, GoneError, ForbiddenError, FetchResponse, FetchErrorType, FetchError2 as FetchError, FetchClientConfig, FetchClient, EntityErrorType, ConflictError, BadRequestError, AuthStrategy };
+export { unwrapOr, unwrap, ok, matchError, isQueryDescriptor, isOk, isMutationDescriptor, isErr, err, createMutationDescriptor, createErrorFromStatus, createDescriptor, UnprocessableEntityError, UnauthorizedError, StreamingRequestOptions, StreamingFormat, ServiceUnavailableError, RetryConfig, Result3 as Result, RequestOptions, RateLimitError, QueryDescriptor, OptimisticHandler, NotFoundError, MutationMeta, MutationDescriptor, ListResponse, InternalServerError, HooksConfig, GoneError, ForbiddenError, FetchResponse, FetchErrorType, FetchError2 as FetchError, FetchClientConfig, FetchClient, EntityQueryMeta, EntityErrorType, ConflictError, BadRequestError, AuthStrategy };

package/dist/index.js

@@ -349,7 +349,7 @@ import { ok as ok2 } from "@vertz/errors";
 function isQueryDescriptor(value) {
   return value !== null && typeof value === "object" && "_tag" in value && value._tag === "QueryDescriptor";
 }
-function createDescriptor(method, path, fetchFn, query) {
+function createDescriptor(method, path, fetchFn, query, entity) {
   const key = `${method}:${path}${serializeQuery(query)}`;
   const fetchResult = async () => {
     const response = await fetchFn();
@@ -361,11 +361,48 @@ function createDescriptor(method, path, fetchFn, query) {
     _tag: "QueryDescriptor",
     _key: key,
     _fetch: fetchResult,
+    ...entity ? { _entity: entity } : {},
     then(onFulfilled, onRejected) {
       return fetchResult().then(onFulfilled, onRejected);
     }
   };
 }
+function isMutationDescriptor(value) {
+  return value !== null && typeof value === "object" && "_tag" in value && value._tag === "MutationDescriptor";
+}
+function createMutationDescriptor(method, path, fetchFn, mutation, handler) {
+  const key = `${method}:${path}`;
+  let mutationCounter = 0;
+  const fetchResult = async () => {
+    const response = await fetchFn();
+    if (!response.ok)
+      return response;
+    return ok2(response.data.data);
+  };
+  return {
+    _tag: "MutationDescriptor",
+    _key: key,
+    _mutation: mutation,
+    _fetch: fetchResult,
+    then(onFulfilled, onRejected) {
+      const id = `m_${++mutationCounter}_${Date.now().toString(36)}`;
+      const rollback = handler?.apply(mutation, id);
+      return fetchResult().then((result) => {
+        if (result.ok) {
+          handler?.commit(mutation, id, result.data);
+        } else {
+          rollback?.();
+        }
+        return onFulfilled?.(result) ?? result;
+      }, (err2) => {
+        rollback?.();
+        if (onRejected)
+          return onRejected(err2);
+        throw err2;
+      });
+    }
+  };
+}
 function serializeQuery(query) {
   if (!query)
     return "";
@@ -486,8 +523,10 @@ export {
   matchError,
   isQueryDescriptor,
   isOk,
+  isMutationDescriptor,
   isErr,
   err2 as err,
+  createMutationDescriptor,
   createErrorFromStatus,
   createDescriptor,
   UnprocessableEntityError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertz/fetch",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "type": "module",
   "license": "MIT",
   "description": "Type-safe HTTP client for Vertz",
@@ -25,7 +25,7 @@
     "dist"
   ],
   "dependencies": {
-    "@vertz/errors": "^0.2.11"
+    "@vertz/errors": "^0.2.12"
   },
   "scripts": {
     "build": "bunup",