@zenstackhq/tanstack-query 2.0.0-alpha.7 → 2.0.0-beta.2

package/runtime-v5/common--_wRp2eo.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Function signature for `fetch`.
+ */
+type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;
+/**
+ * Type for query and mutation errors.
+ */
+type QueryError = Error & {
+    /**
+     * Additional error information.
+     */
+    info?: unknown;
+    /**
+     * HTTP status code.
+     */
+    status?: number;
+};
+/**
+ * Result of optimistic data provider.
+ */
+type OptimisticDataProviderResult = {
+    /**
+     * Kind of the result.
+     *   - Update: use the `data` field to update the query cache.
+     *   - Skip: skip the optimistic update for this query.
+     *   - ProceedDefault: proceed with the default optimistic update.
+     */
+    kind: 'Update' | 'Skip' | 'ProceedDefault';
+    /**
+     * Data to update the query cache. Only applicable if `kind` is 'Update'.
+     *
+     * If the data is an object with fields updated, it should have a `$optimistic`
+     * field set to `true`. If it's an array and an element object is created or updated,
+     * the element should have a `$optimistic` field set to `true`.
+     */
+    data?: any;
+};
+/**
+ * Optimistic data provider.
+ *
+ * @param args Arguments.
+ * @param args.queryModel The model of the query.
+ * @param args.queryOperation The operation of the query, `findMany`, `count`, etc.
+ * @param args.queryArgs The arguments of the query.
+ * @param args.currentData The current cache data for the query.
+ * @param args.mutationArgs The arguments of the mutation.
+ */
+type OptimisticDataProvider = (args: {
+    queryModel: string;
+    queryOperation: string;
+    queryArgs: any;
+    currentData: any;
+    mutationArgs: any;
+}) => OptimisticDataProviderResult | Promise<OptimisticDataProviderResult>;
+/**
+ * Extra mutation options.
+ */
+type ExtraMutationOptions = {
+    /**
+     * Whether to automatically invalidate queries potentially affected by the mutation. Defaults to `true`.
+     */
+    invalidateQueries?: boolean;
+    /**
+     * Whether to optimistically update queries potentially affected by the mutation. Defaults to `false`.
+     */
+    optimisticUpdate?: boolean;
+    /**
+     * A callback for computing optimistic update data for each query cache entry.
+     */
+    optimisticDataProvider?: OptimisticDataProvider;
+};
+/**
+ * Extra query options.
+ */
+type ExtraQueryOptions = {
+    /**
+     * Whether to opt-in to optimistic updates for this query. Defaults to `true`.
+     */
+    optimisticUpdate?: boolean;
+};
+/**
+ * Context type for configuring the hooks.
+ */
+type APIContext = {
+    /**
+     * The endpoint to use for the queries.
+     */
+    endpoint?: string;
+    /**
+     * A custom fetch function for sending the HTTP requests.
+     */
+    fetch?: FetchFn;
+    /**
+     * If logging is enabled.
+     */
+    logging?: boolean;
+};
+type QueryKey = [
+    string,
+    string,
+    string,
+    unknown,
+    {
+        infinite: boolean;
+        optimisticUpdate: boolean;
+    }
+];
+/**
+ * Computes query key for the given model, operation and query args.
+ * @param model Model name.
+ * @param urlOrOperation Prisma operation (e.g, `findMany`) or request URL. If it's a URL, the last path segment will be used as the operation name.
+ * @param args Prisma query arguments.
+ * @param options Query options, including `infinite` indicating if it's an infinite query (defaults to false), and `optimisticUpdate` indicating if optimistic updates are enabled (defaults to true).
+ * @returns Query key
+ */
+declare function getQueryKey(model: string, urlOrOperation: string, args: unknown, options?: {
+    infinite: boolean;
+    optimisticUpdate: boolean;
+}): QueryKey;
+
+export { type APIContext as A, type ExtraMutationOptions as E, type FetchFn as F, type QueryError as Q, type ExtraQueryOptions as a, getQueryKey as g };

package/runtime-v5/index.d.mts

@@ -1,4 +1,4 @@
-export { F as FetchFn, Q as QueryError, g as getQueryKey } from './common-ZSgIGN1q.mjs';
+export { E as ExtraMutationOptions, a as ExtraQueryOptions, F as FetchFn, Q as QueryError, g as getQueryKey } from './common--_wRp2eo.mjs';
 
 type Enumerable<T> = T | Array<T>;
 type _TupleToUnion<T> = T extends (infer E)[] ? E : never;

package/runtime-v5/index.d.ts

@@ -1,4 +1,4 @@
-export { F as FetchFn, Q as QueryError, g as getQueryKey } from './common-ZSgIGN1q.js';
+export { E as ExtraMutationOptions, a as ExtraQueryOptions, F as FetchFn, Q as QueryError, g as getQueryKey } from './common--_wRp2eo.js';
 
 type Enumerable<T> = T | Array<T>;
 type _TupleToUnion<T> = T extends (infer E)[] ? E : never;

package/runtime-v5/index.js

@@ -39,11 +39,13 @@ var import_browser = require("@zenstackhq/runtime/browser");
 var import_cross = require("@zenstackhq/runtime/cross");
 var crossFetch = __toESM(require("cross-fetch"));
 var QUERY_KEY_PREFIX = "zenstack";
-function getQueryKey(model, urlOrOperation, args, infinite = false, optimisticUpdate = false) {
+function getQueryKey(model, urlOrOperation, args, options = { infinite: false, optimisticUpdate: true }) {
   if (!urlOrOperation) {
     throw new Error("Invalid urlOrOperation");
   }
   const operation = urlOrOperation.split("/").pop();
+  const infinite = options.infinite;
+  const optimisticUpdate = options.infinite ? false : options.optimisticUpdate;
   return [QUERY_KEY_PREFIX, model, operation, args, { infinite, optimisticUpdate }];
 }
 // Annotate the CommonJS export names for ESM import in node:

package/runtime-v5/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/runtime-v5/index.ts","../../src/runtime/common.ts"],"sourcesContent":["export * from '../runtime/prisma-types';\nexport { type FetchFn, type QueryError, getQueryKey } from '../runtime/common';\n","/* eslint-disable @typescript-eslint/no-unused-vars */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { deserialize, serialize } from '@zenstackhq/runtime/browser';\nimport {\n    applyMutation,\n    getMutatedModels,\n    getReadModels,\n    type ModelMeta,\n    type PrismaWriteActionType,\n} from '@zenstackhq/runtime/cross';\nimport * as crossFetch from 'cross-fetch';\n\n/**\n * The default query endpoint.\n */\nexport const DEFAULT_QUERY_ENDPOINT = '/api/model';\n\n/**\n * Prefix for react-query keys.\n */\nexport const QUERY_KEY_PREFIX = 'zenstack';\n\n/**\n * Function signature for `fetch`.\n */\nexport type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;\n\n/**\n * Type for query and mutation errors.\n */\nexport type QueryError = Error & {\n    /**\n     * Additional error information.\n     */\n    info?: unknown;\n\n    /**\n     * HTTP status code.\n     */\n    status?: number;\n};\n\n/**\n * Context type for configuring the hooks.\n */\nexport type APIContext = {\n    /**\n     * The endpoint to use for the queries.\n     */\n    endpoint?: string;\n\n    /**\n     * A custom fetch function for sending the HTTP requests.\n     */\n    fetch?: FetchFn;\n\n    /**\n     * If logging is enabled.\n     */\n    logging?: boolean;\n};\n\nexport async function fetcher<R, C extends boolean>(\n    url: string,\n    options?: RequestInit,\n    fetch?: FetchFn,\n    checkReadBack?: C\n): Promise<C extends true ? R | undefined : R> {\n    const _fetch = fetch ?? crossFetch.fetch;\n    const res = await _fetch(url, options);\n    if (!res.ok) {\n        const errData = unmarshal(await res.text());\n        if (\n            checkReadBack !== false &&\n            errData.error?.prisma &&\n            errData.error?.code === 'P2004' &&\n            errData.error?.reason === 'RESULT_NOT_READABLE'\n        ) {\n            // policy doesn't allow mutation result to be read back, just return undefined\n            return undefined as any;\n        }\n        const error: QueryError = new Error('An error occurred while fetching the data.');\n        error.info = errData.error;\n        error.status = res.status;\n        throw error;\n    }\n\n    const textResult = await res.text();\n    try {\n        return unmarshal(textResult).data as R;\n    } catch (err) {\n        console.error(`Unable to deserialize data:`, textResult);\n        throw err;\n    }\n}\n\ntype QueryKey = [\n    string /* prefix */,\n    string /* model */,\n    string /* operation */,\n    unknown /* args */,\n    {\n        infinite: boolean;\n        optimisticUpdate: boolean;\n    } /* flags */\n];\n\n/**\n * Computes query key for the given model, operation and query args.\n * @param model Model name.\n * @param urlOrOperation Prisma operation (e.g, `findMany`) or request URL. If it's a URL, the last path segment will be used as the operation name.\n * @param args Prisma query arguments.\n * @param infinite Whether the query is infinite.\n * @param optimisticUpdate Whether the query is optimistically updated.\n * @returns Query key\n */\nexport function getQueryKey(\n    model: string,\n    urlOrOperation: string,\n    args: unknown,\n    infinite = false,\n    optimisticUpdate = false\n): QueryKey {\n    if (!urlOrOperation) {\n        throw new Error('Invalid urlOrOperation');\n    }\n    const operation = urlOrOperation.split('/').pop();\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    return [QUERY_KEY_PREFIX, model, operation!, args, { infinite, optimisticUpdate }];\n}\n\nexport function marshal(value: unknown) {\n    const { data, meta } = serialize(value);\n    if (meta) {\n        return JSON.stringify({ ...(data as any), meta: { serialization: meta } });\n    } else {\n        return JSON.stringify(data);\n    }\n}\n\nexport function unmarshal(value: string) {\n    const parsed = JSON.parse(value);\n    if (parsed.data && parsed.meta?.serialization) {\n        const deserializedData = deserialize(parsed.data, parsed.meta.serialization);\n        return { ...parsed, data: deserializedData };\n    } else {\n        return parsed;\n    }\n}\n\nexport function makeUrl(url: string, args: unknown) {\n    if (!args) {\n        return url;\n    }\n\n    const { data, meta } = serialize(args);\n    let result = `${url}?q=${encodeURIComponent(JSON.stringify(data))}`;\n    if (meta) {\n        result += `&meta=${encodeURIComponent(JSON.stringify({ serialization: meta }))}`;\n    }\n    return result;\n}\n\ntype InvalidationPredicate = ({ queryKey }: { queryKey: readonly unknown[] }) => boolean;\ntype InvalidateFunc = (predicate: InvalidationPredicate) => Promise<void>;\ntype MutationOptions = {\n    onMutate?: (...args: any[]) => any;\n    onSuccess?: (...args: any[]) => any;\n    onSettled?: (...args: any[]) => any;\n};\n\n// sets up invalidation hook for a mutation\nexport function setupInvalidation(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions,\n    invalidate: InvalidateFunc,\n    logging = false\n) {\n    const origOnSuccess = options?.onSuccess;\n    options.onSuccess = async (...args: unknown[]) => {\n        const [_, variables] = args;\n        const predicate = await getInvalidationPredicate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            modelMeta,\n            logging\n        );\n        await invalidate(predicate);\n        return origOnSuccess?.(...args);\n    };\n}\n\n// gets a predicate for evaluating whether a query should be invalidated\nasync function getInvalidationPredicate(\n    model: string,\n    operation: PrismaWriteActionType,\n    mutationArgs: any,\n    modelMeta: ModelMeta,\n    logging = false\n) {\n    const mutatedModels = await getMutatedModels(model, operation, mutationArgs, modelMeta);\n\n    return ({ queryKey }: { queryKey: readonly unknown[] }) => {\n        const [_, queryModel, , args] = queryKey as QueryKey;\n\n        if (mutatedModels.includes(queryModel)) {\n            // direct match\n            if (logging) {\n                console.log(`Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`);\n            }\n            return true;\n        }\n\n        if (args) {\n            // traverse query args to find nested reads that match the model under mutation\n            if (findNestedRead(queryModel, mutatedModels, modelMeta, args)) {\n                if (logging) {\n                    console.log(\n                        `Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`\n                    );\n                }\n                return true;\n            }\n        }\n\n        return false;\n    };\n}\n\n// find nested reads that match the given models\nfunction findNestedRead(visitingModel: string, targetModels: string[], modelMeta: ModelMeta, args: any) {\n    const modelsRead = getReadModels(visitingModel, modelMeta, args);\n    return targetModels.some((m) => modelsRead.includes(m));\n}\n\ntype QueryCache = {\n    queryKey: readonly unknown[];\n    state: {\n        data: unknown;\n        error: unknown;\n    };\n}[];\n\ntype SetCacheFunc = (queryKey: readonly unknown[], data: unknown) => void;\n\nexport function setupOptimisticUpdate(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    invalidate?: InvalidateFunc,\n    logging = false\n) {\n    const origOnMutate = options?.onMutate;\n    const origOnSettled = options?.onSettled;\n\n    // optimistic update on mutate\n    options.onMutate = async (...args: unknown[]) => {\n        const [variables] = args;\n        await optimisticUpdate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            modelMeta,\n            queryCache,\n            setCache,\n            logging\n        );\n        return origOnMutate?.(...args);\n    };\n\n    // invalidate on settled\n    options.onSettled = async (...args: unknown[]) => {\n        if (invalidate) {\n            const [, , variables] = args;\n            const predicate = await getInvalidationPredicate(\n                model,\n                operation as PrismaWriteActionType,\n                variables,\n                modelMeta,\n                logging\n            );\n            await invalidate(predicate);\n        }\n        return origOnSettled?.(...args);\n    };\n}\n\n// optimistically updates query cache\nasync function optimisticUpdate(\n    mutationModel: string,\n    mutationOp: string,\n    mutationArgs: any,\n    modelMeta: ModelMeta,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    logging = false\n) {\n    for (const cacheItem of queryCache) {\n        const {\n            queryKey,\n            state: { data, error },\n        } = cacheItem;\n\n        if (error) {\n            if (logging) {\n                console.warn(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to error:`, error);\n            }\n            continue;\n        }\n\n        const [_, queryModel, queryOp, _queryArgs, { optimisticUpdate }] = queryKey as QueryKey;\n        if (!optimisticUpdate) {\n            if (logging) {\n                console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to opt-out`);\n            }\n            continue;\n        }\n\n        const mutatedData = await applyMutation(\n            queryModel,\n            queryOp,\n            data,\n            mutationModel,\n            mutationOp as PrismaWriteActionType,\n            mutationArgs,\n            modelMeta,\n            logging\n        );\n\n        if (mutatedData !== undefined) {\n            // mutation applicable to this query, update cache\n            if (logging) {\n                console.log(\n                    `Optimistically updating query ${JSON.stringify(\n                        queryKey\n                    )} due to mutation \"${mutationModel}.${mutationOp}\"`\n                );\n            }\n            setCache(queryKey, mutatedData);\n        }\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,qBAAuC;AACvC,mBAMO;AACP,iBAA4B;AAUrB,IAAM,mBAAmB;AAgGzB,SAAS,YACZ,OACA,gBACA,MACA,WAAW,OACX,mBAAmB,OACX;AACR,MAAI,CAAC,gBAAgB;AACjB,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC5C;AACA,QAAM,YAAY,eAAe,MAAM,GAAG,EAAE,IAAI;AAEhD,SAAO,CAAC,kBAAkB,OAAO,WAAY,MAAM,EAAE,UAAU,iBAAiB,CAAC;AACrF;","names":[]}
+{"version":3,"sources":["../../src/runtime-v5/index.ts","../../src/runtime/common.ts"],"sourcesContent":["export {\n    getQueryKey,\n    type ExtraMutationOptions,\n    type ExtraQueryOptions,\n    type FetchFn,\n    type QueryError,\n} from '../runtime/common';\nexport * from '../runtime/prisma-types';\n","/* eslint-disable @typescript-eslint/no-unused-vars */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { deserialize, serialize } from '@zenstackhq/runtime/browser';\nimport {\n    applyMutation,\n    getMutatedModels,\n    getReadModels,\n    type ModelMeta,\n    type PrismaWriteActionType,\n} from '@zenstackhq/runtime/cross';\nimport * as crossFetch from 'cross-fetch';\n\n/**\n * The default query endpoint.\n */\nexport const DEFAULT_QUERY_ENDPOINT = '/api/model';\n\n/**\n * Prefix for react-query keys.\n */\nexport const QUERY_KEY_PREFIX = 'zenstack';\n\n/**\n * Function signature for `fetch`.\n */\nexport type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;\n\n/**\n * Type for query and mutation errors.\n */\nexport type QueryError = Error & {\n    /**\n     * Additional error information.\n     */\n    info?: unknown;\n\n    /**\n     * HTTP status code.\n     */\n    status?: number;\n};\n\n/**\n * Result of optimistic data provider.\n */\nexport type OptimisticDataProviderResult = {\n    /**\n     * Kind of the result.\n     *   - Update: use the `data` field to update the query cache.\n     *   - Skip: skip the optimistic update for this query.\n     *   - ProceedDefault: proceed with the default optimistic update.\n     */\n    kind: 'Update' | 'Skip' | 'ProceedDefault';\n\n    /**\n     * Data to update the query cache. Only applicable if `kind` is 'Update'.\n     *\n     * If the data is an object with fields updated, it should have a `$optimistic`\n     * field set to `true`. If it's an array and an element object is created or updated,\n     * the element should have a `$optimistic` field set to `true`.\n     */\n    data?: any;\n};\n\n/**\n * Optimistic data provider.\n *\n * @param args Arguments.\n * @param args.queryModel The model of the query.\n * @param args.queryOperation The operation of the query, `findMany`, `count`, etc.\n * @param args.queryArgs The arguments of the query.\n * @param args.currentData The current cache data for the query.\n * @param args.mutationArgs The arguments of the mutation.\n */\nexport type OptimisticDataProvider = (args: {\n    queryModel: string;\n    queryOperation: string;\n    queryArgs: any;\n    currentData: any;\n    mutationArgs: any;\n}) => OptimisticDataProviderResult | Promise<OptimisticDataProviderResult>;\n\n/**\n * Extra mutation options.\n */\nexport type ExtraMutationOptions = {\n    /**\n     * Whether to automatically invalidate queries potentially affected by the mutation. Defaults to `true`.\n     */\n    invalidateQueries?: boolean;\n\n    /**\n     * Whether to optimistically update queries potentially affected by the mutation. Defaults to `false`.\n     */\n    optimisticUpdate?: boolean;\n\n    /**\n     * A callback for computing optimistic update data for each query cache entry.\n     */\n    optimisticDataProvider?: OptimisticDataProvider;\n};\n\n/**\n * Extra query options.\n */\nexport type ExtraQueryOptions = {\n    /**\n     * Whether to opt-in to optimistic updates for this query. Defaults to `true`.\n     */\n    optimisticUpdate?: boolean;\n};\n\n/**\n * Context type for configuring the hooks.\n */\nexport type APIContext = {\n    /**\n     * The endpoint to use for the queries.\n     */\n    endpoint?: string;\n\n    /**\n     * A custom fetch function for sending the HTTP requests.\n     */\n    fetch?: FetchFn;\n\n    /**\n     * If logging is enabled.\n     */\n    logging?: boolean;\n};\n\nexport async function fetcher<R, C extends boolean>(\n    url: string,\n    options?: RequestInit,\n    fetch?: FetchFn,\n    checkReadBack?: C\n): Promise<C extends true ? R | undefined : R> {\n    const _fetch = fetch ?? crossFetch.fetch;\n    const res = await _fetch(url, options);\n    if (!res.ok) {\n        const errData = unmarshal(await res.text());\n        if (\n            checkReadBack !== false &&\n            errData.error?.prisma &&\n            errData.error?.code === 'P2004' &&\n            errData.error?.reason === 'RESULT_NOT_READABLE'\n        ) {\n            // policy doesn't allow mutation result to be read back, just return undefined\n            return undefined as any;\n        }\n        const error: QueryError = new Error('An error occurred while fetching the data.');\n        error.info = errData.error;\n        error.status = res.status;\n        throw error;\n    }\n\n    const textResult = await res.text();\n    try {\n        return unmarshal(textResult).data as R;\n    } catch (err) {\n        console.error(`Unable to deserialize data:`, textResult);\n        throw err;\n    }\n}\n\ntype QueryKey = [\n    string /* prefix */,\n    string /* model */,\n    string /* operation */,\n    unknown /* args */,\n    {\n        infinite: boolean;\n        optimisticUpdate: boolean;\n    } /* flags */\n];\n\n/**\n * Computes query key for the given model, operation and query args.\n * @param model Model name.\n * @param urlOrOperation Prisma operation (e.g, `findMany`) or request URL. If it's a URL, the last path segment will be used as the operation name.\n * @param args Prisma query arguments.\n * @param options Query options, including `infinite` indicating if it's an infinite query (defaults to false), and `optimisticUpdate` indicating if optimistic updates are enabled (defaults to true).\n * @returns Query key\n */\nexport function getQueryKey(\n    model: string,\n    urlOrOperation: string,\n    args: unknown,\n    options: { infinite: boolean; optimisticUpdate: boolean } = { infinite: false, optimisticUpdate: true }\n): QueryKey {\n    if (!urlOrOperation) {\n        throw new Error('Invalid urlOrOperation');\n    }\n    const operation = urlOrOperation.split('/').pop();\n\n    const infinite = options.infinite;\n    // infinite query doesn't support optimistic updates\n    const optimisticUpdate = options.infinite ? false : options.optimisticUpdate;\n\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    return [QUERY_KEY_PREFIX, model, operation!, args, { infinite, optimisticUpdate }];\n}\n\nexport function marshal(value: unknown) {\n    const { data, meta } = serialize(value);\n    if (meta) {\n        return JSON.stringify({ ...(data as any), meta: { serialization: meta } });\n    } else {\n        return JSON.stringify(data);\n    }\n}\n\nexport function unmarshal(value: string) {\n    const parsed = JSON.parse(value);\n    if (parsed.data && parsed.meta?.serialization) {\n        const deserializedData = deserialize(parsed.data, parsed.meta.serialization);\n        return { ...parsed, data: deserializedData };\n    } else {\n        return parsed;\n    }\n}\n\nexport function makeUrl(url: string, args: unknown) {\n    if (!args) {\n        return url;\n    }\n\n    const { data, meta } = serialize(args);\n    let result = `${url}?q=${encodeURIComponent(JSON.stringify(data))}`;\n    if (meta) {\n        result += `&meta=${encodeURIComponent(JSON.stringify({ serialization: meta }))}`;\n    }\n    return result;\n}\n\ntype InvalidationPredicate = ({ queryKey }: { queryKey: readonly unknown[] }) => boolean;\ntype InvalidateFunc = (predicate: InvalidationPredicate) => Promise<void>;\ntype MutationOptions = {\n    onMutate?: (...args: any[]) => any;\n    onSuccess?: (...args: any[]) => any;\n    onSettled?: (...args: any[]) => any;\n};\n\n// sets up invalidation hook for a mutation\nexport function setupInvalidation(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions,\n    invalidate: InvalidateFunc,\n    logging = false\n) {\n    const origOnSuccess = options?.onSuccess;\n    options.onSuccess = async (...args: unknown[]) => {\n        const [_, variables] = args;\n        const predicate = await getInvalidationPredicate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            modelMeta,\n            logging\n        );\n        await invalidate(predicate);\n        return origOnSuccess?.(...args);\n    };\n}\n\n// gets a predicate for evaluating whether a query should be invalidated\nasync function getInvalidationPredicate(\n    model: string,\n    operation: PrismaWriteActionType,\n    mutationArgs: any,\n    modelMeta: ModelMeta,\n    logging = false\n) {\n    const mutatedModels = await getMutatedModels(model, operation, mutationArgs, modelMeta);\n\n    return ({ queryKey }: { queryKey: readonly unknown[] }) => {\n        const [_, queryModel, , args] = queryKey as QueryKey;\n\n        if (mutatedModels.includes(queryModel)) {\n            // direct match\n            if (logging) {\n                console.log(`Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`);\n            }\n            return true;\n        }\n\n        if (args) {\n            // traverse query args to find nested reads that match the model under mutation\n            if (findNestedRead(queryModel, mutatedModels, modelMeta, args)) {\n                if (logging) {\n                    console.log(\n                        `Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`\n                    );\n                }\n                return true;\n            }\n        }\n\n        return false;\n    };\n}\n\n// find nested reads that match the given models\nfunction findNestedRead(visitingModel: string, targetModels: string[], modelMeta: ModelMeta, args: any) {\n    const modelsRead = getReadModels(visitingModel, modelMeta, args);\n    return targetModels.some((m) => modelsRead.includes(m));\n}\n\ntype QueryCache = {\n    queryKey: readonly unknown[];\n    state: {\n        data: unknown;\n        error: unknown;\n    };\n}[];\n\ntype SetCacheFunc = (queryKey: readonly unknown[], data: unknown) => void;\n\n/**\n * Sets up optimistic update and invalidation (after settled) for a mutation.\n */\nexport function setupOptimisticUpdate(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions & ExtraMutationOptions,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    invalidate?: InvalidateFunc,\n    logging = false\n) {\n    const origOnMutate = options?.onMutate;\n    const origOnSettled = options?.onSettled;\n\n    // optimistic update on mutate\n    options.onMutate = async (...args: unknown[]) => {\n        const [variables] = args;\n        await optimisticUpdate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            options,\n            modelMeta,\n            queryCache,\n            setCache,\n            logging\n        );\n        return origOnMutate?.(...args);\n    };\n\n    // invalidate on settled\n    options.onSettled = async (...args: unknown[]) => {\n        if (invalidate) {\n            const [, , variables] = args;\n            const predicate = await getInvalidationPredicate(\n                model,\n                operation as PrismaWriteActionType,\n                variables,\n                modelMeta,\n                logging\n            );\n            await invalidate(predicate);\n        }\n        return origOnSettled?.(...args);\n    };\n}\n\n// optimistically updates query cache\nasync function optimisticUpdate(\n    mutationModel: string,\n    mutationOp: string,\n    mutationArgs: any,\n    options: MutationOptions & ExtraMutationOptions,\n    modelMeta: ModelMeta,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    logging = false\n) {\n    for (const cacheItem of queryCache) {\n        const {\n            queryKey,\n            state: { data, error },\n        } = cacheItem;\n\n        if (error) {\n            if (logging) {\n                console.warn(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to error:`, error);\n            }\n            continue;\n        }\n\n        const [_, queryModel, queryOperation, queryArgs, { optimisticUpdate }] = queryKey as QueryKey;\n        if (!optimisticUpdate) {\n            if (logging) {\n                console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to opt-out`);\n            }\n            continue;\n        }\n\n        if (options.optimisticDataProvider) {\n            const providerResult = await options.optimisticDataProvider({\n                queryModel,\n                queryOperation,\n                queryArgs,\n                currentData: data,\n                mutationArgs,\n            });\n\n            if (providerResult?.kind === 'Skip') {\n                // skip\n                if (logging) {\n                    console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to provider`);\n                }\n                continue;\n            } else if (providerResult?.kind === 'Update') {\n                // update cache\n                if (logging) {\n                    console.log(`Optimistically updating query ${JSON.stringify(queryKey)} due to provider`);\n                }\n                setCache(queryKey, providerResult.data);\n                continue;\n            }\n        }\n\n        // proceed with default optimistic update\n        const mutatedData = await applyMutation(\n            queryModel,\n            queryOperation,\n            data,\n            mutationModel,\n            mutationOp as PrismaWriteActionType,\n            mutationArgs,\n            modelMeta,\n            logging\n        );\n\n        if (mutatedData !== undefined) {\n            // mutation applicable to this query, update cache\n            if (logging) {\n                console.log(\n                    `Optimistically updating query ${JSON.stringify(\n                        queryKey\n                    )} due to mutation \"${mutationModel}.${mutationOp}\"`\n                );\n            }\n            setCache(queryKey, mutatedData);\n        }\n    }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACEA,qBAAuC;AACvC,mBAMO;AACP,iBAA4B;AAUrB,IAAM,mBAAmB;AAqKzB,SAAS,YACZ,OACA,gBACA,MACA,UAA4D,EAAE,UAAU,OAAO,kBAAkB,KAAK,GAC9F;AACR,MAAI,CAAC,gBAAgB;AACjB,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC5C;AACA,QAAM,YAAY,eAAe,MAAM,GAAG,EAAE,IAAI;AAEhD,QAAM,WAAW,QAAQ;AAEzB,QAAM,mBAAmB,QAAQ,WAAW,QAAQ,QAAQ;AAG5D,SAAO,CAAC,kBAAkB,OAAO,WAAY,MAAM,EAAE,UAAU,iBAAiB,CAAC;AACrF;","names":[]}

package/runtime-v5/index.mjs

@@ -7,11 +7,13 @@ import {
 } from "@zenstackhq/runtime/cross";
 import * as crossFetch from "cross-fetch";
 var QUERY_KEY_PREFIX = "zenstack";
-function getQueryKey(model, urlOrOperation, args, infinite = false, optimisticUpdate = false) {
+function getQueryKey(model, urlOrOperation, args, options = { infinite: false, optimisticUpdate: true }) {
   if (!urlOrOperation) {
     throw new Error("Invalid urlOrOperation");
   }
   const operation = urlOrOperation.split("/").pop();
+  const infinite = options.infinite;
+  const optimisticUpdate = options.infinite ? false : options.optimisticUpdate;
   return [QUERY_KEY_PREFIX, model, operation, args, { infinite, optimisticUpdate }];
 }
 export {

package/runtime-v5/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/runtime/common.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-unused-vars */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { deserialize, serialize } from '@zenstackhq/runtime/browser';\nimport {\n    applyMutation,\n    getMutatedModels,\n    getReadModels,\n    type ModelMeta,\n    type PrismaWriteActionType,\n} from '@zenstackhq/runtime/cross';\nimport * as crossFetch from 'cross-fetch';\n\n/**\n * The default query endpoint.\n */\nexport const DEFAULT_QUERY_ENDPOINT = '/api/model';\n\n/**\n * Prefix for react-query keys.\n */\nexport const QUERY_KEY_PREFIX = 'zenstack';\n\n/**\n * Function signature for `fetch`.\n */\nexport type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;\n\n/**\n * Type for query and mutation errors.\n */\nexport type QueryError = Error & {\n    /**\n     * Additional error information.\n     */\n    info?: unknown;\n\n    /**\n     * HTTP status code.\n     */\n    status?: number;\n};\n\n/**\n * Context type for configuring the hooks.\n */\nexport type APIContext = {\n    /**\n     * The endpoint to use for the queries.\n     */\n    endpoint?: string;\n\n    /**\n     * A custom fetch function for sending the HTTP requests.\n     */\n    fetch?: FetchFn;\n\n    /**\n     * If logging is enabled.\n     */\n    logging?: boolean;\n};\n\nexport async function fetcher<R, C extends boolean>(\n    url: string,\n    options?: RequestInit,\n    fetch?: FetchFn,\n    checkReadBack?: C\n): Promise<C extends true ? R | undefined : R> {\n    const _fetch = fetch ?? crossFetch.fetch;\n    const res = await _fetch(url, options);\n    if (!res.ok) {\n        const errData = unmarshal(await res.text());\n        if (\n            checkReadBack !== false &&\n            errData.error?.prisma &&\n            errData.error?.code === 'P2004' &&\n            errData.error?.reason === 'RESULT_NOT_READABLE'\n        ) {\n            // policy doesn't allow mutation result to be read back, just return undefined\n            return undefined as any;\n        }\n        const error: QueryError = new Error('An error occurred while fetching the data.');\n        error.info = errData.error;\n        error.status = res.status;\n        throw error;\n    }\n\n    const textResult = await res.text();\n    try {\n        return unmarshal(textResult).data as R;\n    } catch (err) {\n        console.error(`Unable to deserialize data:`, textResult);\n        throw err;\n    }\n}\n\ntype QueryKey = [\n    string /* prefix */,\n    string /* model */,\n    string /* operation */,\n    unknown /* args */,\n    {\n        infinite: boolean;\n        optimisticUpdate: boolean;\n    } /* flags */\n];\n\n/**\n * Computes query key for the given model, operation and query args.\n * @param model Model name.\n * @param urlOrOperation Prisma operation (e.g, `findMany`) or request URL. If it's a URL, the last path segment will be used as the operation name.\n * @param args Prisma query arguments.\n * @param infinite Whether the query is infinite.\n * @param optimisticUpdate Whether the query is optimistically updated.\n * @returns Query key\n */\nexport function getQueryKey(\n    model: string,\n    urlOrOperation: string,\n    args: unknown,\n    infinite = false,\n    optimisticUpdate = false\n): QueryKey {\n    if (!urlOrOperation) {\n        throw new Error('Invalid urlOrOperation');\n    }\n    const operation = urlOrOperation.split('/').pop();\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    return [QUERY_KEY_PREFIX, model, operation!, args, { infinite, optimisticUpdate }];\n}\n\nexport function marshal(value: unknown) {\n    const { data, meta } = serialize(value);\n    if (meta) {\n        return JSON.stringify({ ...(data as any), meta: { serialization: meta } });\n    } else {\n        return JSON.stringify(data);\n    }\n}\n\nexport function unmarshal(value: string) {\n    const parsed = JSON.parse(value);\n    if (parsed.data && parsed.meta?.serialization) {\n        const deserializedData = deserialize(parsed.data, parsed.meta.serialization);\n        return { ...parsed, data: deserializedData };\n    } else {\n        return parsed;\n    }\n}\n\nexport function makeUrl(url: string, args: unknown) {\n    if (!args) {\n        return url;\n    }\n\n    const { data, meta } = serialize(args);\n    let result = `${url}?q=${encodeURIComponent(JSON.stringify(data))}`;\n    if (meta) {\n        result += `&meta=${encodeURIComponent(JSON.stringify({ serialization: meta }))}`;\n    }\n    return result;\n}\n\ntype InvalidationPredicate = ({ queryKey }: { queryKey: readonly unknown[] }) => boolean;\ntype InvalidateFunc = (predicate: InvalidationPredicate) => Promise<void>;\ntype MutationOptions = {\n    onMutate?: (...args: any[]) => any;\n    onSuccess?: (...args: any[]) => any;\n    onSettled?: (...args: any[]) => any;\n};\n\n// sets up invalidation hook for a mutation\nexport function setupInvalidation(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions,\n    invalidate: InvalidateFunc,\n    logging = false\n) {\n    const origOnSuccess = options?.onSuccess;\n    options.onSuccess = async (...args: unknown[]) => {\n        const [_, variables] = args;\n        const predicate = await getInvalidationPredicate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            modelMeta,\n            logging\n        );\n        await invalidate(predicate);\n        return origOnSuccess?.(...args);\n    };\n}\n\n// gets a predicate for evaluating whether a query should be invalidated\nasync function getInvalidationPredicate(\n    model: string,\n    operation: PrismaWriteActionType,\n    mutationArgs: any,\n    modelMeta: ModelMeta,\n    logging = false\n) {\n    const mutatedModels = await getMutatedModels(model, operation, mutationArgs, modelMeta);\n\n    return ({ queryKey }: { queryKey: readonly unknown[] }) => {\n        const [_, queryModel, , args] = queryKey as QueryKey;\n\n        if (mutatedModels.includes(queryModel)) {\n            // direct match\n            if (logging) {\n                console.log(`Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`);\n            }\n            return true;\n        }\n\n        if (args) {\n            // traverse query args to find nested reads that match the model under mutation\n            if (findNestedRead(queryModel, mutatedModels, modelMeta, args)) {\n                if (logging) {\n                    console.log(\n                        `Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`\n                    );\n                }\n                return true;\n            }\n        }\n\n        return false;\n    };\n}\n\n// find nested reads that match the given models\nfunction findNestedRead(visitingModel: string, targetModels: string[], modelMeta: ModelMeta, args: any) {\n    const modelsRead = getReadModels(visitingModel, modelMeta, args);\n    return targetModels.some((m) => modelsRead.includes(m));\n}\n\ntype QueryCache = {\n    queryKey: readonly unknown[];\n    state: {\n        data: unknown;\n        error: unknown;\n    };\n}[];\n\ntype SetCacheFunc = (queryKey: readonly unknown[], data: unknown) => void;\n\nexport function setupOptimisticUpdate(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    invalidate?: InvalidateFunc,\n    logging = false\n) {\n    const origOnMutate = options?.onMutate;\n    const origOnSettled = options?.onSettled;\n\n    // optimistic update on mutate\n    options.onMutate = async (...args: unknown[]) => {\n        const [variables] = args;\n        await optimisticUpdate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            modelMeta,\n            queryCache,\n            setCache,\n            logging\n        );\n        return origOnMutate?.(...args);\n    };\n\n    // invalidate on settled\n    options.onSettled = async (...args: unknown[]) => {\n        if (invalidate) {\n            const [, , variables] = args;\n            const predicate = await getInvalidationPredicate(\n                model,\n                operation as PrismaWriteActionType,\n                variables,\n                modelMeta,\n                logging\n            );\n            await invalidate(predicate);\n        }\n        return origOnSettled?.(...args);\n    };\n}\n\n// optimistically updates query cache\nasync function optimisticUpdate(\n    mutationModel: string,\n    mutationOp: string,\n    mutationArgs: any,\n    modelMeta: ModelMeta,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    logging = false\n) {\n    for (const cacheItem of queryCache) {\n        const {\n            queryKey,\n            state: { data, error },\n        } = cacheItem;\n\n        if (error) {\n            if (logging) {\n                console.warn(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to error:`, error);\n            }\n            continue;\n        }\n\n        const [_, queryModel, queryOp, _queryArgs, { optimisticUpdate }] = queryKey as QueryKey;\n        if (!optimisticUpdate) {\n            if (logging) {\n                console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to opt-out`);\n            }\n            continue;\n        }\n\n        const mutatedData = await applyMutation(\n            queryModel,\n            queryOp,\n            data,\n            mutationModel,\n            mutationOp as PrismaWriteActionType,\n            mutationArgs,\n            modelMeta,\n            logging\n        );\n\n        if (mutatedData !== undefined) {\n            // mutation applicable to this query, update cache\n            if (logging) {\n                console.log(\n                    `Optimistically updating query ${JSON.stringify(\n                        queryKey\n                    )} due to mutation \"${mutationModel}.${mutationOp}\"`\n                );\n            }\n            setCache(queryKey, mutatedData);\n        }\n    }\n}\n"],"mappings":";AAEA,SAAS,aAAa,iBAAiB;AACvC;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,OAGG;AACP,YAAY,gBAAgB;AAUrB,IAAM,mBAAmB;AAgGzB,SAAS,YACZ,OACA,gBACA,MACA,WAAW,OACX,mBAAmB,OACX;AACR,MAAI,CAAC,gBAAgB;AACjB,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC5C;AACA,QAAM,YAAY,eAAe,MAAM,GAAG,EAAE,IAAI;AAEhD,SAAO,CAAC,kBAAkB,OAAO,WAAY,MAAM,EAAE,UAAU,iBAAiB,CAAC;AACrF;","names":[]}
+{"version":3,"sources":["../../src/runtime/common.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-unused-vars */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nimport { deserialize, serialize } from '@zenstackhq/runtime/browser';\nimport {\n    applyMutation,\n    getMutatedModels,\n    getReadModels,\n    type ModelMeta,\n    type PrismaWriteActionType,\n} from '@zenstackhq/runtime/cross';\nimport * as crossFetch from 'cross-fetch';\n\n/**\n * The default query endpoint.\n */\nexport const DEFAULT_QUERY_ENDPOINT = '/api/model';\n\n/**\n * Prefix for react-query keys.\n */\nexport const QUERY_KEY_PREFIX = 'zenstack';\n\n/**\n * Function signature for `fetch`.\n */\nexport type FetchFn = (url: string, options?: RequestInit) => Promise<Response>;\n\n/**\n * Type for query and mutation errors.\n */\nexport type QueryError = Error & {\n    /**\n     * Additional error information.\n     */\n    info?: unknown;\n\n    /**\n     * HTTP status code.\n     */\n    status?: number;\n};\n\n/**\n * Result of optimistic data provider.\n */\nexport type OptimisticDataProviderResult = {\n    /**\n     * Kind of the result.\n     *   - Update: use the `data` field to update the query cache.\n     *   - Skip: skip the optimistic update for this query.\n     *   - ProceedDefault: proceed with the default optimistic update.\n     */\n    kind: 'Update' | 'Skip' | 'ProceedDefault';\n\n    /**\n     * Data to update the query cache. Only applicable if `kind` is 'Update'.\n     *\n     * If the data is an object with fields updated, it should have a `$optimistic`\n     * field set to `true`. If it's an array and an element object is created or updated,\n     * the element should have a `$optimistic` field set to `true`.\n     */\n    data?: any;\n};\n\n/**\n * Optimistic data provider.\n *\n * @param args Arguments.\n * @param args.queryModel The model of the query.\n * @param args.queryOperation The operation of the query, `findMany`, `count`, etc.\n * @param args.queryArgs The arguments of the query.\n * @param args.currentData The current cache data for the query.\n * @param args.mutationArgs The arguments of the mutation.\n */\nexport type OptimisticDataProvider = (args: {\n    queryModel: string;\n    queryOperation: string;\n    queryArgs: any;\n    currentData: any;\n    mutationArgs: any;\n}) => OptimisticDataProviderResult | Promise<OptimisticDataProviderResult>;\n\n/**\n * Extra mutation options.\n */\nexport type ExtraMutationOptions = {\n    /**\n     * Whether to automatically invalidate queries potentially affected by the mutation. Defaults to `true`.\n     */\n    invalidateQueries?: boolean;\n\n    /**\n     * Whether to optimistically update queries potentially affected by the mutation. Defaults to `false`.\n     */\n    optimisticUpdate?: boolean;\n\n    /**\n     * A callback for computing optimistic update data for each query cache entry.\n     */\n    optimisticDataProvider?: OptimisticDataProvider;\n};\n\n/**\n * Extra query options.\n */\nexport type ExtraQueryOptions = {\n    /**\n     * Whether to opt-in to optimistic updates for this query. Defaults to `true`.\n     */\n    optimisticUpdate?: boolean;\n};\n\n/**\n * Context type for configuring the hooks.\n */\nexport type APIContext = {\n    /**\n     * The endpoint to use for the queries.\n     */\n    endpoint?: string;\n\n    /**\n     * A custom fetch function for sending the HTTP requests.\n     */\n    fetch?: FetchFn;\n\n    /**\n     * If logging is enabled.\n     */\n    logging?: boolean;\n};\n\nexport async function fetcher<R, C extends boolean>(\n    url: string,\n    options?: RequestInit,\n    fetch?: FetchFn,\n    checkReadBack?: C\n): Promise<C extends true ? R | undefined : R> {\n    const _fetch = fetch ?? crossFetch.fetch;\n    const res = await _fetch(url, options);\n    if (!res.ok) {\n        const errData = unmarshal(await res.text());\n        if (\n            checkReadBack !== false &&\n            errData.error?.prisma &&\n            errData.error?.code === 'P2004' &&\n            errData.error?.reason === 'RESULT_NOT_READABLE'\n        ) {\n            // policy doesn't allow mutation result to be read back, just return undefined\n            return undefined as any;\n        }\n        const error: QueryError = new Error('An error occurred while fetching the data.');\n        error.info = errData.error;\n        error.status = res.status;\n        throw error;\n    }\n\n    const textResult = await res.text();\n    try {\n        return unmarshal(textResult).data as R;\n    } catch (err) {\n        console.error(`Unable to deserialize data:`, textResult);\n        throw err;\n    }\n}\n\ntype QueryKey = [\n    string /* prefix */,\n    string /* model */,\n    string /* operation */,\n    unknown /* args */,\n    {\n        infinite: boolean;\n        optimisticUpdate: boolean;\n    } /* flags */\n];\n\n/**\n * Computes query key for the given model, operation and query args.\n * @param model Model name.\n * @param urlOrOperation Prisma operation (e.g, `findMany`) or request URL. If it's a URL, the last path segment will be used as the operation name.\n * @param args Prisma query arguments.\n * @param options Query options, including `infinite` indicating if it's an infinite query (defaults to false), and `optimisticUpdate` indicating if optimistic updates are enabled (defaults to true).\n * @returns Query key\n */\nexport function getQueryKey(\n    model: string,\n    urlOrOperation: string,\n    args: unknown,\n    options: { infinite: boolean; optimisticUpdate: boolean } = { infinite: false, optimisticUpdate: true }\n): QueryKey {\n    if (!urlOrOperation) {\n        throw new Error('Invalid urlOrOperation');\n    }\n    const operation = urlOrOperation.split('/').pop();\n\n    const infinite = options.infinite;\n    // infinite query doesn't support optimistic updates\n    const optimisticUpdate = options.infinite ? false : options.optimisticUpdate;\n\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    return [QUERY_KEY_PREFIX, model, operation!, args, { infinite, optimisticUpdate }];\n}\n\nexport function marshal(value: unknown) {\n    const { data, meta } = serialize(value);\n    if (meta) {\n        return JSON.stringify({ ...(data as any), meta: { serialization: meta } });\n    } else {\n        return JSON.stringify(data);\n    }\n}\n\nexport function unmarshal(value: string) {\n    const parsed = JSON.parse(value);\n    if (parsed.data && parsed.meta?.serialization) {\n        const deserializedData = deserialize(parsed.data, parsed.meta.serialization);\n        return { ...parsed, data: deserializedData };\n    } else {\n        return parsed;\n    }\n}\n\nexport function makeUrl(url: string, args: unknown) {\n    if (!args) {\n        return url;\n    }\n\n    const { data, meta } = serialize(args);\n    let result = `${url}?q=${encodeURIComponent(JSON.stringify(data))}`;\n    if (meta) {\n        result += `&meta=${encodeURIComponent(JSON.stringify({ serialization: meta }))}`;\n    }\n    return result;\n}\n\ntype InvalidationPredicate = ({ queryKey }: { queryKey: readonly unknown[] }) => boolean;\ntype InvalidateFunc = (predicate: InvalidationPredicate) => Promise<void>;\ntype MutationOptions = {\n    onMutate?: (...args: any[]) => any;\n    onSuccess?: (...args: any[]) => any;\n    onSettled?: (...args: any[]) => any;\n};\n\n// sets up invalidation hook for a mutation\nexport function setupInvalidation(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions,\n    invalidate: InvalidateFunc,\n    logging = false\n) {\n    const origOnSuccess = options?.onSuccess;\n    options.onSuccess = async (...args: unknown[]) => {\n        const [_, variables] = args;\n        const predicate = await getInvalidationPredicate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            modelMeta,\n            logging\n        );\n        await invalidate(predicate);\n        return origOnSuccess?.(...args);\n    };\n}\n\n// gets a predicate for evaluating whether a query should be invalidated\nasync function getInvalidationPredicate(\n    model: string,\n    operation: PrismaWriteActionType,\n    mutationArgs: any,\n    modelMeta: ModelMeta,\n    logging = false\n) {\n    const mutatedModels = await getMutatedModels(model, operation, mutationArgs, modelMeta);\n\n    return ({ queryKey }: { queryKey: readonly unknown[] }) => {\n        const [_, queryModel, , args] = queryKey as QueryKey;\n\n        if (mutatedModels.includes(queryModel)) {\n            // direct match\n            if (logging) {\n                console.log(`Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`);\n            }\n            return true;\n        }\n\n        if (args) {\n            // traverse query args to find nested reads that match the model under mutation\n            if (findNestedRead(queryModel, mutatedModels, modelMeta, args)) {\n                if (logging) {\n                    console.log(\n                        `Invalidating query ${JSON.stringify(queryKey)} due to mutation \"${model}.${operation}\"`\n                    );\n                }\n                return true;\n            }\n        }\n\n        return false;\n    };\n}\n\n// find nested reads that match the given models\nfunction findNestedRead(visitingModel: string, targetModels: string[], modelMeta: ModelMeta, args: any) {\n    const modelsRead = getReadModels(visitingModel, modelMeta, args);\n    return targetModels.some((m) => modelsRead.includes(m));\n}\n\ntype QueryCache = {\n    queryKey: readonly unknown[];\n    state: {\n        data: unknown;\n        error: unknown;\n    };\n}[];\n\ntype SetCacheFunc = (queryKey: readonly unknown[], data: unknown) => void;\n\n/**\n * Sets up optimistic update and invalidation (after settled) for a mutation.\n */\nexport function setupOptimisticUpdate(\n    model: string,\n    operation: string,\n    modelMeta: ModelMeta,\n    options: MutationOptions & ExtraMutationOptions,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    invalidate?: InvalidateFunc,\n    logging = false\n) {\n    const origOnMutate = options?.onMutate;\n    const origOnSettled = options?.onSettled;\n\n    // optimistic update on mutate\n    options.onMutate = async (...args: unknown[]) => {\n        const [variables] = args;\n        await optimisticUpdate(\n            model,\n            operation as PrismaWriteActionType,\n            variables,\n            options,\n            modelMeta,\n            queryCache,\n            setCache,\n            logging\n        );\n        return origOnMutate?.(...args);\n    };\n\n    // invalidate on settled\n    options.onSettled = async (...args: unknown[]) => {\n        if (invalidate) {\n            const [, , variables] = args;\n            const predicate = await getInvalidationPredicate(\n                model,\n                operation as PrismaWriteActionType,\n                variables,\n                modelMeta,\n                logging\n            );\n            await invalidate(predicate);\n        }\n        return origOnSettled?.(...args);\n    };\n}\n\n// optimistically updates query cache\nasync function optimisticUpdate(\n    mutationModel: string,\n    mutationOp: string,\n    mutationArgs: any,\n    options: MutationOptions & ExtraMutationOptions,\n    modelMeta: ModelMeta,\n    queryCache: QueryCache,\n    setCache: SetCacheFunc,\n    logging = false\n) {\n    for (const cacheItem of queryCache) {\n        const {\n            queryKey,\n            state: { data, error },\n        } = cacheItem;\n\n        if (error) {\n            if (logging) {\n                console.warn(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to error:`, error);\n            }\n            continue;\n        }\n\n        const [_, queryModel, queryOperation, queryArgs, { optimisticUpdate }] = queryKey as QueryKey;\n        if (!optimisticUpdate) {\n            if (logging) {\n                console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to opt-out`);\n            }\n            continue;\n        }\n\n        if (options.optimisticDataProvider) {\n            const providerResult = await options.optimisticDataProvider({\n                queryModel,\n                queryOperation,\n                queryArgs,\n                currentData: data,\n                mutationArgs,\n            });\n\n            if (providerResult?.kind === 'Skip') {\n                // skip\n                if (logging) {\n                    console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to provider`);\n                }\n                continue;\n            } else if (providerResult?.kind === 'Update') {\n                // update cache\n                if (logging) {\n                    console.log(`Optimistically updating query ${JSON.stringify(queryKey)} due to provider`);\n                }\n                setCache(queryKey, providerResult.data);\n                continue;\n            }\n        }\n\n        // proceed with default optimistic update\n        const mutatedData = await applyMutation(\n            queryModel,\n            queryOperation,\n            data,\n            mutationModel,\n            mutationOp as PrismaWriteActionType,\n            mutationArgs,\n            modelMeta,\n            logging\n        );\n\n        if (mutatedData !== undefined) {\n            // mutation applicable to this query, update cache\n            if (logging) {\n                console.log(\n                    `Optimistically updating query ${JSON.stringify(\n                        queryKey\n                    )} due to mutation \"${mutationModel}.${mutationOp}\"`\n                );\n            }\n            setCache(queryKey, mutatedData);\n        }\n    }\n}\n"],"mappings":";AAEA,SAAS,aAAa,iBAAiB;AACvC;AAAA,EACI;AAAA,EACA;AAAA,EACA;AAAA,OAGG;AACP,YAAY,gBAAgB;AAUrB,IAAM,mBAAmB;AAqKzB,SAAS,YACZ,OACA,gBACA,MACA,UAA4D,EAAE,UAAU,OAAO,kBAAkB,KAAK,GAC9F;AACR,MAAI,CAAC,gBAAgB;AACjB,UAAM,IAAI,MAAM,wBAAwB;AAAA,EAC5C;AACA,QAAM,YAAY,eAAe,MAAM,GAAG,EAAE,IAAI;AAEhD,QAAM,WAAW,QAAQ;AAEzB,QAAM,mBAAmB,QAAQ,WAAW,QAAQ,QAAQ;AAG5D,SAAO,CAAC,kBAAkB,OAAO,WAAY,MAAM,EAAE,UAAU,iBAAiB,CAAC;AACrF;","names":[]}

package/runtime-v5/react.d.mts

@@ -2,7 +2,7 @@ import * as _tanstack_react_query_v5_build_legacy_types from '@tanstack/react-qu
 import * as react from 'react';
 import { UseQueryOptions, UseSuspenseQueryOptions, UseInfiniteQueryOptions, InfiniteData, UseSuspenseInfiniteQueryOptions, UseMutationOptions } from '@tanstack/react-query';
 import { ModelMeta } from '@zenstackhq/runtime/cross';
-import { A as APIContext, F as FetchFn } from './common-ZSgIGN1q.mjs';
+import { A as APIContext, F as FetchFn, a as ExtraQueryOptions, E as ExtraMutationOptions } from './common--_wRp2eo.mjs';
 
 /**
  * Context for configuring react hooks.
@@ -28,10 +28,9 @@ declare const Provider: react.Provider<APIContext>;
  * @param args The request args object, URL-encoded and appended as "?q=" parameter
  * @param options The react-query options object
  * @param fetch The fetch function to use for sending the HTTP request
- * @param optimisticUpdate Whether to enable automatic optimistic update
  * @returns useQuery hook
  */
-declare function useModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'>, fetch?: FetchFn, optimisticUpdate?: boolean): _tanstack_react_query_v5_build_legacy_types.UseQueryResult<TData, TError>;
+declare function useModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'> & ExtraQueryOptions, fetch?: FetchFn): _tanstack_react_query_v5_build_legacy_types.UseQueryResult<TData, TError>;
 /**
  * Creates a react-query suspense query.
  *
@@ -40,10 +39,9 @@ declare function useModelQuery<TQueryFnData, TData, TError>(model: string, url:
  * @param args The request args object, URL-encoded and appended as "?q=" parameter
  * @param options The react-query options object
  * @param fetch The fetch function to use for sending the HTTP request
- * @param optimisticUpdate Whether to enable automatic optimistic update
  * @returns useSuspenseQuery hook
  */
-declare function useSuspenseModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseSuspenseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'>, fetch?: FetchFn, optimisticUpdate?: boolean): _tanstack_react_query_v5_build_legacy_types.UseSuspenseQueryResult<TData, TError>;
+declare function useSuspenseModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseSuspenseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'> & ExtraQueryOptions, fetch?: FetchFn): _tanstack_react_query_v5_build_legacy_types.UseSuspenseQueryResult<TData, TError>;
 /**
  * Creates a react-query infinite query.
  *
@@ -75,10 +73,8 @@ declare function useSuspenseInfiniteModelQuery<TQueryFnData, TData, TError>(mode
  * @param modelMeta The model metadata.
  * @param options The react-query options.
  * @param fetch The fetch function to use for sending the HTTP request
- * @param invalidateQueries Whether to invalidate queries after mutation.
  * @param checkReadBack Whether to check for read back errors and return undefined if found.
- * @param optimisticUpdate Whether to enable automatic optimistic update
  */
-declare function useModelMutation<TArgs, TError, R = any, C extends boolean = boolean, Result = C extends true ? R | undefined : R>(model: string, method: 'POST' | 'PUT' | 'DELETE', url: string, modelMeta: ModelMeta, options?: Omit<UseMutationOptions<Result, TError, TArgs>, 'mutationFn'>, fetch?: FetchFn, invalidateQueries?: boolean, checkReadBack?: C, optimisticUpdate?: boolean): _tanstack_react_query_v5_build_legacy_types.UseMutationResult<Result, TError, TArgs, unknown>;
+declare function useModelMutation<TArgs, TError, R = any, C extends boolean = boolean, Result = C extends true ? R | undefined : R>(model: string, method: 'POST' | 'PUT' | 'DELETE', url: string, modelMeta: ModelMeta, options?: Omit<UseMutationOptions<Result, TError, TArgs>, 'mutationFn'> & ExtraMutationOptions, fetch?: FetchFn, checkReadBack?: C): _tanstack_react_query_v5_build_legacy_types.UseMutationResult<Result, TError, TArgs, unknown>;
 
 export { Provider, RequestHandlerContext, getHooksContext, useInfiniteModelQuery, useModelMutation, useModelQuery, useSuspenseInfiniteModelQuery, useSuspenseModelQuery };

package/runtime-v5/react.d.ts

@@ -2,7 +2,7 @@ import * as _tanstack_react_query_v5_build_legacy_types from '@tanstack/react-qu
 import * as react from 'react';
 import { UseQueryOptions, UseSuspenseQueryOptions, UseInfiniteQueryOptions, InfiniteData, UseSuspenseInfiniteQueryOptions, UseMutationOptions } from '@tanstack/react-query';
 import { ModelMeta } from '@zenstackhq/runtime/cross';
-import { A as APIContext, F as FetchFn } from './common-ZSgIGN1q.js';
+import { A as APIContext, F as FetchFn, a as ExtraQueryOptions, E as ExtraMutationOptions } from './common--_wRp2eo.js';
 
 /**
  * Context for configuring react hooks.
@@ -28,10 +28,9 @@ declare const Provider: react.Provider<APIContext>;
  * @param args The request args object, URL-encoded and appended as "?q=" parameter
  * @param options The react-query options object
  * @param fetch The fetch function to use for sending the HTTP request
- * @param optimisticUpdate Whether to enable automatic optimistic update
  * @returns useQuery hook
  */
-declare function useModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'>, fetch?: FetchFn, optimisticUpdate?: boolean): _tanstack_react_query_v5_build_legacy_types.UseQueryResult<TData, TError>;
+declare function useModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'> & ExtraQueryOptions, fetch?: FetchFn): _tanstack_react_query_v5_build_legacy_types.UseQueryResult<TData, TError>;
 /**
  * Creates a react-query suspense query.
  *
@@ -40,10 +39,9 @@ declare function useModelQuery<TQueryFnData, TData, TError>(model: string, url:
  * @param args The request args object, URL-encoded and appended as "?q=" parameter
  * @param options The react-query options object
  * @param fetch The fetch function to use for sending the HTTP request
- * @param optimisticUpdate Whether to enable automatic optimistic update
  * @returns useSuspenseQuery hook
  */
-declare function useSuspenseModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseSuspenseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'>, fetch?: FetchFn, optimisticUpdate?: boolean): _tanstack_react_query_v5_build_legacy_types.UseSuspenseQueryResult<TData, TError>;
+declare function useSuspenseModelQuery<TQueryFnData, TData, TError>(model: string, url: string, args?: unknown, options?: Omit<UseSuspenseQueryOptions<TQueryFnData, TError, TData>, 'queryKey'> & ExtraQueryOptions, fetch?: FetchFn): _tanstack_react_query_v5_build_legacy_types.UseSuspenseQueryResult<TData, TError>;
 /**
  * Creates a react-query infinite query.
  *
@@ -75,10 +73,8 @@ declare function useSuspenseInfiniteModelQuery<TQueryFnData, TData, TError>(mode
  * @param modelMeta The model metadata.
  * @param options The react-query options.
  * @param fetch The fetch function to use for sending the HTTP request
- * @param invalidateQueries Whether to invalidate queries after mutation.
  * @param checkReadBack Whether to check for read back errors and return undefined if found.
- * @param optimisticUpdate Whether to enable automatic optimistic update
  */
-declare function useModelMutation<TArgs, TError, R = any, C extends boolean = boolean, Result = C extends true ? R | undefined : R>(model: string, method: 'POST' | 'PUT' | 'DELETE', url: string, modelMeta: ModelMeta, options?: Omit<UseMutationOptions<Result, TError, TArgs>, 'mutationFn'>, fetch?: FetchFn, invalidateQueries?: boolean, checkReadBack?: C, optimisticUpdate?: boolean): _tanstack_react_query_v5_build_legacy_types.UseMutationResult<Result, TError, TArgs, unknown>;
+declare function useModelMutation<TArgs, TError, R = any, C extends boolean = boolean, Result = C extends true ? R | undefined : R>(model: string, method: 'POST' | 'PUT' | 'DELETE', url: string, modelMeta: ModelMeta, options?: Omit<UseMutationOptions<Result, TError, TArgs>, 'mutationFn'> & ExtraMutationOptions, fetch?: FetchFn, checkReadBack?: C): _tanstack_react_query_v5_build_legacy_types.UseMutationResult<Result, TError, TArgs, unknown>;
 
 export { Provider, RequestHandlerContext, getHooksContext, useInfiniteModelQuery, useModelMutation, useModelQuery, useSuspenseInfiniteModelQuery, useSuspenseModelQuery };

package/runtime-v5/react.js

@@ -122,11 +122,13 @@ function fetcher(url, options, fetch2, checkReadBack) {
     }
   });
 }
-function getQueryKey(model, urlOrOperation, args, infinite = false, optimisticUpdate2 = false) {
+function getQueryKey(model, urlOrOperation, args, options = { infinite: false, optimisticUpdate: true }) {
   if (!urlOrOperation) {
     throw new Error("Invalid urlOrOperation");
   }
   const operation = urlOrOperation.split("/").pop();
+  const infinite = options.infinite;
+  const optimisticUpdate2 = options.infinite ? false : options.optimisticUpdate;
   return [QUERY_KEY_PREFIX, model, operation, args, { infinite, optimisticUpdate: optimisticUpdate2 }];
 }
 function marshal(value) {
@@ -211,6 +213,7 @@ function setupOptimisticUpdate(model, operation, modelMeta, options, queryCache,
       model,
       operation,
       variables,
+      options,
       modelMeta,
       queryCache,
       setCache,
@@ -233,7 +236,7 @@ function setupOptimisticUpdate(model, operation, modelMeta, options, queryCache,
     return origOnSettled == null ? void 0 : origOnSettled(...args);
   });
 }
-function optimisticUpdate(mutationModel, mutationOp, mutationArgs, modelMeta, queryCache, setCache, logging = false) {
+function optimisticUpdate(mutationModel, mutationOp, mutationArgs, options, modelMeta, queryCache, setCache, logging = false) {
   return __async(this, null, function* () {
     for (const cacheItem of queryCache) {
       const {
@@ -246,16 +249,37 @@ function optimisticUpdate(mutationModel, mutationOp, mutationArgs, modelMeta, qu
         }
         continue;
       }
-      const [_, queryModel, queryOp, _queryArgs, { optimisticUpdate: optimisticUpdate2 }] = queryKey;
+      const [_, queryModel, queryOperation, queryArgs, { optimisticUpdate: optimisticUpdate2 }] = queryKey;
       if (!optimisticUpdate2) {
         if (logging) {
           console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to opt-out`);
         }
         continue;
       }
+      if (options.optimisticDataProvider) {
+        const providerResult = yield options.optimisticDataProvider({
+          queryModel,
+          queryOperation,
+          queryArgs,
+          currentData: data,
+          mutationArgs
+        });
+        if ((providerResult == null ? void 0 : providerResult.kind) === "Skip") {
+          if (logging) {
+            console.log(`Skipping optimistic update for ${JSON.stringify(queryKey)} due to provider`);
+          }
+          continue;
+        } else if ((providerResult == null ? void 0 : providerResult.kind) === "Update") {
+          if (logging) {
+            console.log(`Optimistically updating query ${JSON.stringify(queryKey)} due to provider`);
+          }
+          setCache(queryKey, providerResult.data);
+          continue;
+        }
+      }
       const mutatedData = yield (0, import_cross.applyMutation)(
         queryModel,
-        queryOp,
+        queryOperation,
         data,
         mutationModel,
         mutationOp,
@@ -287,23 +311,29 @@ function getHooksContext() {
   return __spreadValues({ endpoint: endpoint != null ? endpoint : DEFAULT_QUERY_ENDPOINT }, rest);
 }
 var Provider = RequestHandlerContext.Provider;
-function useModelQuery(model, url, args, options, fetch2, optimisticUpdate2 = false) {
+function useModelQuery(model, url, args, options, fetch2) {
   const reqUrl = makeUrl(url, args);
   return (0, import_react_query_v5.useQuery)(__spreadValues({
-    queryKey: getQueryKey(model, url, args, false, optimisticUpdate2),
+    queryKey: getQueryKey(model, url, args, {
+      infinite: false,
+      optimisticUpdate: (options == null ? void 0 : options.optimisticUpdate) !== false
+    }),
     queryFn: () => fetcher(reqUrl, void 0, fetch2, false)
   }, options));
 }
-function useSuspenseModelQuery(model, url, args, options, fetch2, optimisticUpdate2 = false) {
+function useSuspenseModelQuery(model, url, args, options, fetch2) {
   const reqUrl = makeUrl(url, args);
   return (0, import_react_query_v5.useSuspenseQuery)(__spreadValues({
-    queryKey: getQueryKey(model, url, args, false, optimisticUpdate2),
+    queryKey: getQueryKey(model, url, args, {
+      infinite: false,
+      optimisticUpdate: (options == null ? void 0 : options.optimisticUpdate) !== false
+    }),
     queryFn: () => fetcher(reqUrl, void 0, fetch2, false)
   }, options));
 }
 function useInfiniteModelQuery(model, url, args, options, fetch2) {
   return (0, import_react_query_v5.useInfiniteQuery)(__spreadValues({
-    queryKey: getQueryKey(model, url, args, true),
+    queryKey: getQueryKey(model, url, args, { infinite: true, optimisticUpdate: false }),
     queryFn: ({ pageParam }) => {
       return fetcher(makeUrl(url, pageParam != null ? pageParam : args), void 0, fetch2, false);
     }
@@ -311,13 +341,13 @@ function useInfiniteModelQuery(model, url, args, options, fetch2) {
 }
 function useSuspenseInfiniteModelQuery(model, url, args, options, fetch2) {
   return (0, import_react_query_v5.useSuspenseInfiniteQuery)(__spreadValues({
-    queryKey: getQueryKey(model, url, args, true),
+    queryKey: getQueryKey(model, url, args, { infinite: true, optimisticUpdate: false }),
     queryFn: ({ pageParam }) => {
       return fetcher(makeUrl(url, pageParam != null ? pageParam : args), void 0, fetch2, false);
     }
   }, options));
 }
-function useModelMutation(model, method, url, modelMeta, options, fetch2, invalidateQueries = true, checkReadBack, optimisticUpdate2 = false) {
+function useModelMutation(model, method, url, modelMeta, options, fetch2, checkReadBack) {
   const queryClient = (0, import_react_query_v5.useQueryClient)();
   const mutationFn = (data) => {
     const reqUrl = method === "DELETE" ? makeUrl(url, data) : url;
@@ -333,6 +363,8 @@ function useModelMutation(model, method, url, modelMeta, options, fetch2, invali
   };
   const finalOptions = __spreadProps(__spreadValues({}, options), { mutationFn });
   const operation = url.split("/").pop();
+  const invalidateQueries = (options == null ? void 0 : options.invalidateQueries) !== false;
+  const optimisticUpdate2 = !!(options == null ? void 0 : options.optimisticUpdate);
   if (operation) {
     const { logging } = (0, import_react.useContext)(RequestHandlerContext);
     if (invalidateQueries) {