graphql-persisted 0.0.1

package/cjs/errors.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertOperationHash = exports.ExpectedPreloadedQueryError = exports.MissingNormalizeMetaError = exports.UnknownOperationError = exports.MissingMetaError = exports.GraphQLQueryError = void 0;
+class GraphQLQueryError extends Error {
+}
+exports.GraphQLQueryError = GraphQLQueryError;
+/**
+ * Thrown in situations where we are expecting graphql-normalize metadata
+ * to be available, but it isn't yet available.
+ */
+class MissingMetaError extends Error {
+    constructor(queryName) {
+        super(`Cannot readQuery('${queryName}') without graphql-normalize metadata.`);
+    }
+}
+exports.MissingMetaError = MissingMetaError;
+class UnknownOperationError extends Error {
+    constructor(operationName, operationType) {
+        super(`Unknown ${operationType} operation ${operationName}, not found in the hash of operations`);
+    }
+}
+exports.UnknownOperationError = UnknownOperationError;
+class MissingNormalizeMetaError extends Error {
+    constructor(operationName, operationType) {
+        super(`extensions.graphqlNormalizeMeta is was expected for the ${operationName} ${operationType}.\n You must configure your GraphQLQueryCache with the "meta" property, or add this as part of your repsonse payload`);
+    }
+}
+exports.MissingNormalizeMetaError = MissingNormalizeMetaError;
+class ExpectedPreloadedQueryError extends GraphQLQueryError {
+    constructor(queryName) {
+        super(`Expected query ${queryName} to be preloaded with preloadQuery`);
+    }
+}
+exports.ExpectedPreloadedQueryError = ExpectedPreloadedQueryError;
+function assertOperationHash(hash, operationType, operationName) {
+    if (!hash) {
+        throw new UnknownOperationError(operationName, operationType);
+    }
+}
+exports.assertOperationHash = assertOperationHash;

package/cjs/fragmentData.d.ts

@@ -0,0 +1,12 @@
+export type FragmentType<Frag extends keyof GraphQLQuery.FragmentRegistry> = GraphQLQuery.FragmentRegistry[Frag] extends infer FragType ? FragType extends {
+    ' $fragmentName'?: infer TKey;
+} ? TKey extends string ? {
+    ' $fragmentRefs'?: {
+        [key in TKey]: FragType;
+    };
+} : never : never : never;
+export declare function unwrapFragment<Frag extends keyof GraphQLQuery.FragmentRegistry>(_fragmentName: Frag, fragmentType: FragmentType<Frag>): GraphQLQuery.FragmentRegistry[Frag];
+export declare function unwrapFragment<Frag extends keyof GraphQLQuery.FragmentRegistry>(_fragmentName: Frag, fragmentType: FragmentType<Frag> | null | undefined): GraphQLQuery.FragmentRegistry[Frag] | null | undefined;
+export declare function unwrapFragment<Frag extends keyof GraphQLQuery.FragmentRegistry>(_fragmentName: Frag, fragmentType: ReadonlyArray<FragmentType<Frag>>): ReadonlyArray<GraphQLQuery.FragmentRegistry[Frag]>;
+export declare function unwrapFragment<Frag extends keyof GraphQLQuery.FragmentRegistry>(_fragmentName: Frag, fragmentType: ReadonlyArray<FragmentType<Frag>> | null | undefined): ReadonlyArray<GraphQLQuery.FragmentRegistry[Frag]> | null | undefined;
+export declare function castFragmentData<F extends keyof GraphQLQuery.FragmentRegistry, FT extends GraphQLQuery.FragmentRegistry[F]>(_fragmentName: F, data: FT): FragmentType<F>;

package/cjs/fragmentData.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.castFragmentData = exports.unwrapFragment = void 0;
+function unwrapFragment(_fragmentName, fragmentType) {
+    return fragmentType;
+}
+exports.unwrapFragment = unwrapFragment;
+function castFragmentData(_fragmentName, data) {
+    return data;
+}
+exports.castFragmentData = castFragmentData;

package/cjs/graphqlHooks.d.ts

@@ -0,0 +1,48 @@
+import type { GraphQLPreloadedQueryResult, GraphQLQueryLazyResult, GraphQLQueryResult, ExecutionOptions, PersistedQueryOptions, QueryVariables, GraphQLMutationResult, ExecuteMutationOptions } from './types';
+/**
+ * Loads a preloaded query. Like useQuery, except it throws if the
+ * query does not already exist in the cache.
+ *
+ * This hook keeps track of the value of the last render, so we're always guaranteed
+ * to have data here, even if it's potentially stale.
+ */
+export declare const usePreloadedPersistedQuery: <QueryName extends never>(query: QueryName, options: PersistedQueryOptions & QueryVariables<QueryName>) => GraphQLPreloadedQueryResult<QueryName>;
+/**
+ * Retrieves the persisted query from the cache,
+ * creating it from the cache if we don't have a mounted version
+ *
+ * Fetches the query if:
+ *
+ * 1. We don't already have the operation fetched in the cache
+ * 2. The query is considered stale based on:
+ *    a) The TTL setting
+ *    b) A mutation which invalidates the query
+ */
+export declare const usePersistedQuery: <QueryName extends never>(queryName: QueryName, options: PersistedQueryOptions & QueryVariables<QueryName>) => GraphQLQueryResult<QueryName>;
+/**
+ * TODO: Not working yet
+ * Creates a container for a query that isn't fetched immediately,
+ * but provides a loadQuery function to call
+ */
+export declare const useLazyPersistedQuery: <QueryName extends never>(query: QueryName) => GraphQLQueryLazyResult<QueryName>;
+/**
+ * Executes a persisted mutation, keeping track of mutations in-flight to ensure
+ * we don't execute the same mutation multiple times with the same values
+ * in the same component
+ */
+export declare const usePersistedMutation: <MutationName extends never>(mutationName: MutationName, options?: ExecutionOptions) => {
+    execute: (vars: GraphQLQuery.OperationVariables[MutationName], opts?: ExecuteMutationOptions) => Promise<GraphQLMutationResult<MutationName>>;
+    isExecuting: boolean;
+};
+/**
+ * TODO: Subscription management
+ */
+export declare const usePersistedSubscription: <SubscriptionName extends never>(subscriptionName: SubscriptionName) => never;
+type UseOnMutationFn<M> = () => void;
+/**
+ * Hook called when a mutation is issued, anywhere in the application.
+ * Useful for one-off situations where we want to subscribe and refetch something
+ * based on a mutation event
+ */
+export declare const useOnMutation: <M extends "*">(mutation: M | M[], fn: UseOnMutationFn<M>) => void;
+export {};

package/cjs/graphqlHooks.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOnMutation = exports.usePersistedSubscription = exports.usePersistedMutation = exports.useLazyPersistedQuery = exports.usePersistedQuery = exports.usePreloadedPersistedQuery = void 0;
+const context_1 = require("./context");
+const react_1 = require("react");
+const errors_1 = require("./errors");
+const helpers_1 = require("./helpers");
+/**
+ * Loads a preloaded query. Like useQuery, except it throws if the
+ * query does not already exist in the cache.
+ *
+ * This hook keeps track of the value of the last render, so we're always guaranteed
+ * to have data here, even if it's potentially stale.
+ */
+const usePreloadedPersistedQuery = (query, options) => {
+    const result = (0, exports.usePersistedQuery)(query, options);
+    const lastData = (0, react_1.useRef)(result.data);
+    const data = result.data ?? lastData.current;
+    if (!data) {
+        throw new errors_1.ExpectedPreloadedQueryError(query);
+    }
+    (0, react_1.useEffect)(() => {
+        if (result.data) {
+            lastData.current = result.data;
+        }
+    }, [result.data]);
+    return { ...result, data };
+};
+exports.usePreloadedPersistedQuery = usePreloadedPersistedQuery;
+/**
+ * Retrieves the persisted query from the cache,
+ * creating it from the cache if we don't have a mounted version
+ *
+ * Fetches the query if:
+ *
+ * 1. We don't already have the operation fetched in the cache
+ * 2. The query is considered stale based on:
+ *    a) The TTL setting
+ *    b) A mutation which invalidates the query
+ */
+const usePersistedQuery = (queryName, options) => {
+    const cache = (0, context_1.useGraphQLQueryCache)();
+    const optionsRef = (0, react_1.useRef)(options);
+    // Ensure we always have the latest options in the optionsRef
+    (0, react_1.useEffect)(() => {
+        optionsRef.current = options;
+    });
+    // We need the variables stringified anyway to persist in the cache
+    // simplest to just stringify them here
+    const variableString = (0, react_1.useMemo)(() => (0, helpers_1.serializeVariables)(options.variables ?? {}), [options.variables]);
+    // Read the query result from the cache
+    const readQueryResult = (0, react_1.useMemo)(() => {
+        return cache.tryReadQuery({
+            queryName,
+            variables: variableString,
+            options: optionsRef.current,
+        });
+    }, [queryName, variableString, cache]);
+    const [queryResult, setQueryResult] = (0, react_1.useState)(readQueryResult);
+    (0, react_1.useEffect)(() => {
+        setQueryResult(readQueryResult);
+    }, [readQueryResult]);
+    // If we don't have the query on mount, we fetch it.
+    // We "subscribe" to the query so we'll receive
+    // updates when the query values change, it becomes stale,
+    // or it is refetched
+    (0, react_1.useEffect)(() => {
+        return cache.subscribeToQuery({
+            queryName,
+            variables: variableString,
+            onUpdate: setQueryResult,
+            options: optionsRef.current,
+        });
+    }, [queryName, cache, queryResult, variableString]);
+    return {
+        ...queryResult,
+        fetched: Boolean(queryResult),
+    }; // GraphQLQuery.QueryRegistry[QueryName];
+};
+exports.usePersistedQuery = usePersistedQuery;
+/**
+ * TODO: Not working yet
+ * Creates a container for a query that isn't fetched immediately,
+ * but provides a loadQuery function to call
+ */
+const useLazyPersistedQuery = (query) => {
+    const data = (0, react_1.useRef)(undefined);
+    const cache = (0, context_1.useGraphQLQueryCache)();
+    // const state = useState<'pending' | 'fetched' | 'loading' | 'stale'>('pending')
+    const [stale, setIsStale] = (0, react_1.useState)(false);
+    const [fetched, setIsFetched] = (0, react_1.useState)(false);
+    const [loading, setIsLoading] = (0, react_1.useState)(false);
+    const loadQuery = (0, react_1.useCallback)((variables) => {
+        return new Promise((resolve) => {
+            cache.readOrFetchQuery({ queryName: query, variables: (0, helpers_1.serializeVariables)(variables), options: {} });
+        });
+    }, [cache, query]);
+    const errors = undefined;
+    return {
+        data: data.current,
+        errors,
+        loadQuery,
+        loading,
+        stale,
+        fetched,
+    };
+};
+exports.useLazyPersistedQuery = useLazyPersistedQuery;
+/**
+ * Executes a persisted mutation, keeping track of mutations in-flight to ensure
+ * we don't execute the same mutation multiple times with the same values
+ * in the same component
+ */
+const usePersistedMutation = (mutationName, options) => {
+    const cache = (0, context_1.useGraphQLQueryCache)();
+    // Keeps track of whether we're executing the mutation or not, useful
+    // for showing loading states when we know the mutation is in-flight
+    const [isExecuting, setIsExecuting] = (0, react_1.useState)(0);
+    const executingRef = (0, react_1.useRef)(new Map());
+    const optionsRef = (0, react_1.useRef)(options);
+    (0, react_1.useEffect)(() => {
+        optionsRef.current = options;
+    });
+    const execute = (0, react_1.useCallback)(async (vars, opts = {}) => {
+        const { skipDedupeGuard = false } = opts;
+        setIsExecuting((v) => v + 1);
+        const inFlightVars = (0, helpers_1.serializeVariables)(vars);
+        const executing = executingRef.current.get(inFlightVars);
+        if (executing && !skipDedupeGuard) {
+            return executing;
+        }
+        const inFlight = cache.executeMutation(mutationName, vars, optionsRef.current).finally(() => {
+            if (!skipDedupeGuard) {
+                executingRef.current.delete(inFlightVars);
+            }
+            setIsExecuting((v) => v - 1);
+        });
+        if (!skipDedupeGuard) {
+            executingRef.current.set(inFlightVars, inFlight);
+        }
+        return inFlight;
+    }, [cache, mutationName]);
+    return {
+        execute,
+        isExecuting: Boolean(isExecuting > 0),
+    };
+};
+exports.usePersistedMutation = usePersistedMutation;
+/**
+ * TODO: Subscription management
+ */
+const usePersistedSubscription = (subscriptionName) => {
+    throw new Error(`usePersistedSubscription(${subscriptionName}) not yet supported`);
+};
+exports.usePersistedSubscription = usePersistedSubscription;
+/**
+ * Hook called when a mutation is issued, anywhere in the application.
+ * Useful for one-off situations where we want to subscribe and refetch something
+ * based on a mutation event
+ */
+const useOnMutation = (mutation, fn) => {
+    const fnRef = (0, react_1.useRef)(fn);
+    const cache = (0, context_1.useGraphQLQueryCache)();
+    (0, react_1.useEffect)(() => {
+        fnRef.current = fn;
+    });
+    const mutationDeps = Array.isArray(mutation) ? mutation : [mutation];
+    (0, react_1.useEffect)(() => {
+        return () => {
+            //
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [cache, ...mutationDeps]);
+};
+exports.useOnMutation = useOnMutation;

package/cjs/helpers.d.ts

@@ -0,0 +1,4 @@
+import type { SerializedVariables } from './types';
+export declare function serializeVariables(vars: object): SerializedVariables;
+export declare function variableString(val: SerializedVariables | object): SerializedVariables;
+export declare function variableObject(val: SerializedVariables | object): any;

package/cjs/helpers.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.variableObject = exports.variableString = exports.serializeVariables = void 0;
+const graphql_normalize_1 = require("graphql-normalize");
+function serializeVariables(vars) {
+    return (0, graphql_normalize_1.stringifyVariables)(vars);
+}
+exports.serializeVariables = serializeVariables;
+function variableString(val) {
+    return typeof val === 'string' ? val : serializeVariables(val);
+}
+exports.variableString = variableString;
+function variableObject(val) {
+    return typeof val === 'string' ? JSON.parse(val) : val;
+}
+exports.variableObject = variableObject;

package/cjs/index.d.ts

@@ -0,0 +1,8 @@
+export { usePersistedQuery, usePersistedMutation, usePreloadedPersistedQuery, useOnMutation, usePersistedSubscription, } from './graphqlHooks.js';
+export { unwrapFragment, castFragmentData } from './fragmentData.js';
+export type { FragmentType } from './fragmentData.js';
+export { GraphQLQueryCache } from './GraphQLQueryCache.js';
+export { useGraphQLQueryCache, GraphQLQueryProvider } from './context.js';
+export type { GraphQLPreloadedQueryResult, GraphQLQueryResult, GraphQLQueryCacheConfig } from './types.js';
+import type * as GraphQLQueryTypes from './types.js';
+export type { GraphQLQueryTypes };

package/cjs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphQLQueryProvider = exports.useGraphQLQueryCache = exports.GraphQLQueryCache = exports.castFragmentData = exports.unwrapFragment = exports.usePersistedSubscription = exports.useOnMutation = exports.usePreloadedPersistedQuery = exports.usePersistedMutation = exports.usePersistedQuery = void 0;
+var graphqlHooks_js_1 = require("./graphqlHooks.js");
+Object.defineProperty(exports, "usePersistedQuery", { enumerable: true, get: function () { return graphqlHooks_js_1.usePersistedQuery; } });
+Object.defineProperty(exports, "usePersistedMutation", { enumerable: true, get: function () { return graphqlHooks_js_1.usePersistedMutation; } });
+Object.defineProperty(exports, "usePreloadedPersistedQuery", { enumerable: true, get: function () { return graphqlHooks_js_1.usePreloadedPersistedQuery; } });
+Object.defineProperty(exports, "useOnMutation", { enumerable: true, get: function () { return graphqlHooks_js_1.useOnMutation; } });
+Object.defineProperty(exports, "usePersistedSubscription", { enumerable: true, get: function () { return graphqlHooks_js_1.usePersistedSubscription; } });
+var fragmentData_js_1 = require("./fragmentData.js");
+Object.defineProperty(exports, "unwrapFragment", { enumerable: true, get: function () { return fragmentData_js_1.unwrapFragment; } });
+Object.defineProperty(exports, "castFragmentData", { enumerable: true, get: function () { return fragmentData_js_1.castFragmentData; } });
+var GraphQLQueryCache_js_1 = require("./GraphQLQueryCache.js");
+Object.defineProperty(exports, "GraphQLQueryCache", { enumerable: true, get: function () { return GraphQLQueryCache_js_1.GraphQLQueryCache; } });
+var context_js_1 = require("./context.js");
+Object.defineProperty(exports, "useGraphQLQueryCache", { enumerable: true, get: function () { return context_js_1.useGraphQLQueryCache; } });
+Object.defineProperty(exports, "GraphQLQueryProvider", { enumerable: true, get: function () { return context_js_1.GraphQLQueryProvider; } });

package/cjs/types.d.ts

@@ -0,0 +1,205 @@
+import type { NormalizeMetaShape } from 'graphql-normalize';
+import type { FormattedExecutionResult, GraphQLFormattedError } from 'graphql';
+import type { GraphQLQueryError } from './errors';
+declare global {
+    namespace GraphQLQuery {
+        interface QueryRegistry {
+        }
+        interface MutationRegistry {
+        }
+        interface SubscriptionRegistry {
+        }
+        interface OperationVariables {
+        }
+        interface FragmentRegistry {
+        }
+    }
+}
+export interface GraphQLOperationStoreShape<TData = unknown> {
+    operationType: 'query' | 'mutation' | 'subscription';
+    operationName: string;
+    meta: NormalizeMetaShape;
+    data?: TData | null;
+    errors?: ReadonlyArray<GraphQLFormattedError>;
+    extensions?: Record<string, unknown>;
+    variableValues: object;
+    lastFetchedAt?: Date;
+    stale: boolean;
+}
+export interface GraphQLCacheShape {
+    /**
+     * Normalized representation of the values for fields across all operations
+     */
+    fields: Record<string, unknown>;
+    /**
+     * Mapping of the operations we've seen
+     */
+    operations: Record<string, GraphQLOperationStoreShape<any>>;
+    /**
+     * "OperationName:meta" mapping
+     */
+    meta: Record<string, NormalizeMetaShape>;
+}
+export interface GraphQLHydratedCacheShape extends GraphQLCacheShape {
+    hydrated: Record<string, Record<string, string>>;
+}
+export interface GraphQLQueryCacheConfig {
+    /**
+     * The endpoint of our GraphQL Application
+     * @default /graphql
+     */
+    endpoint?: string;
+    /**
+     * Allows providing our own implementation of "fetch"
+     */
+    fetcher?: typeof fetch;
+    /**
+     * If we're Server-Side Rendering this code, we can serialize
+     * the GraphQLQueryCache and send down with the client bundle,
+     * so clients are able to re-hydrate and skip refetching
+     */
+    hydratedCache?: GraphQLCacheShape;
+    /**
+     * A mapping of graphql-normalize metadata, if we decide to provide
+     * it rather than sending it down alongside the query
+     *
+     * https://github.com/tgriesser/graphql-normalize
+     */
+    meta?: Record<string, any>;
+    /**
+     * Mapping of Query Name to hash of the query to execute
+     */
+    persistedOperations: Record<string, string>;
+    /**
+     * Reverse mapping of hashes to documents, useful in development situations
+     * where we might not have the hashes persisted on the server yet
+     */
+    persistedDocuments?: Record<string, string>;
+    /**
+     * Rather than having a mutation keep track of the queries it needs to invalidate,
+     * the invalidateOnMutation can specify that this query becomes "invalidated" when,
+     * a mutation, or specific mutation occurs, meaning the next time it's mounted,
+     * it'll be refetched
+     */
+    queryInvalidation?: Partial<{
+        [Q in keyof GraphQLQuery.QueryRegistry]: QueryInvalidationFn<Q>;
+    }>;
+    /**
+     * When the mutation executes and returns, allows us to invalidate queries,
+     * meaning they will be marked as "stale" and will be lazily refetched
+     * on subsequent renders.
+     */
+    mutationInvalidation?: Partial<{
+        [M in keyof GraphQLQuery.MutationRegistry]: MutationInvalidationFn<M>;
+    }>;
+    /**
+     * When an error happens in the query layer, it will run through this error handler.
+     */
+    globalOnError?: (e: GraphQLQueryError) => void;
+}
+export type QueryInvalidationFn<Q extends keyof GraphQLQuery.QueryRegistry = keyof GraphQLQuery.QueryRegistry> = <M extends keyof GraphQLQuery.MutationRegistry>(mutationName: M, mutationVariables: GraphQLQuery.OperationVariables[M], queryVariables: GraphQLQuery.OperationVariables[Q]) => boolean;
+export type MutationInvalidationFn<M extends keyof GraphQLQuery.MutationRegistry = keyof GraphQLQuery.MutationRegistry> = <Q extends keyof GraphQLQuery.QueryRegistry>(queryName: Q, queryVariables: GraphQLQuery.OperationVariables[Q], mutationVariables: GraphQLQuery.OperationVariables[M]) => boolean;
+export interface FetchError {
+    name: string;
+    message: string;
+    stack?: string;
+    status?: number;
+    statusText?: string;
+}
+export interface GraphQLOperationResult<Result> extends FormattedExecutionResult<Result> {
+    fetchError?: FetchError;
+}
+export type GraphQLMutationResult<MutationName extends keyof GraphQLQuery.MutationRegistry> = GraphQLOperationResult<GraphQLQuery.MutationRegistry[MutationName]>;
+export interface GraphQLQueryResult<QueryName extends keyof GraphQLQuery.QueryRegistry> extends GraphQLOperationResult<GraphQLQuery.QueryRegistry[QueryName]> {
+    fetched: boolean;
+}
+export interface GraphQLQueryLazyResult<QueryName extends keyof GraphQLQuery.QueryRegistry> extends GraphQLQueryResult<QueryName> {
+    stale: boolean;
+    loading: boolean;
+    loadQuery: (variables: GraphQLQuery.OperationVariables[QueryName]) => Promise<FormattedExecutionResult<GraphQLQuery.QueryRegistry[QueryName]>>;
+}
+export interface GraphQLPreloadedQueryResult<QueryName extends keyof GraphQLQuery.QueryRegistry> extends GraphQLQueryResult<QueryName> {
+    data: GraphQLQuery.QueryRegistry[QueryName];
+}
+export type MaybePromise<T> = T | Promise<T>;
+export interface GraphQLRequestBody {
+    query?: string;
+    variables: any;
+    operationName?: string;
+    extensions?: Record<string, any>;
+}
+export interface ExecutionOptions {
+    onError?: (e: GraphQLQueryError) => void;
+}
+export type QueryVariables<QueryName extends keyof GraphQLQuery.QueryRegistry> = QueryName extends keyof GraphQLQuery.OperationVariables ? GraphQLQuery.OperationVariables[QueryName] extends {
+    [key: string]: never;
+} ? {
+    variables?: unknown;
+} : {
+    variables: GraphQLQuery.OperationVariables[QueryName];
+} : never;
+export interface PersistedQueryOptions extends ExecutionOptions {
+    /**
+     * TTL in milliseconds for the query, after this we'll mark the query
+     * as "stale" and revalidate
+     */
+    ttl?: number;
+    /**
+     * Poll interval to refetch the query, in milliseconds.
+     */
+    pollInterval?: number;
+}
+export interface ReadQueryArgs<Q extends keyof GraphQLQuery.QueryRegistry> {
+    /**
+     *
+     */
+    queryName: Q;
+    /**
+     *
+     */
+    variables: SerializedVariables | GraphQLQuery.OperationVariables[Q];
+    /**
+     *
+     */
+    options: PersistedQueryOptions;
+}
+export interface SubscribeToQueryArgs<Q extends keyof GraphQLQuery.QueryRegistry> extends ReadQueryArgs<Q> {
+    /**
+     * The result of readQuery, used to check whether the query is stale
+     */
+    queryResult?: GraphQLQuery.QueryRegistry[Q];
+    /**
+     * Invoked when the values for this query are updated
+     */
+    onUpdate: (nextVal: GraphQLOperationResult<Q>) => any;
+}
+export type InvalidateQueryArgs = keyof GraphQLQuery.QueryRegistry | Array<keyof GraphQLQuery.QueryRegistry>;
+export type SerializedVariables = string & {
+    __brand: 'SerializedVariables';
+};
+export type MutationTuple = {
+    [K in keyof GraphQLQuery.MutationRegistry]: [K, GraphQLQuery.OperationVariables[K]];
+}[keyof GraphQLQuery.MutationRegistry];
+export type SubscriptionTuple = {
+    [K in keyof GraphQLQuery.SubscriptionRegistry]: [K, GraphQLQuery.OperationVariables[K]];
+}[keyof GraphQLQuery.SubscriptionRegistry];
+export interface ExecuteMutationOptions {
+    /**
+     * By default, we check to ensure the mutation isn't already in-flight with the
+     * same variables
+     */
+    skipDedupeGuard?: boolean;
+}
+export type PreloadQueryOptions<Q extends keyof GraphQLQuery.QueryRegistry = keyof GraphQLQuery.QueryRegistry> = {
+    /**
+     * If we have the operation, but we know it's stale, we'll typically refetch
+     * and return the promise for the refetch. if "blockIfStale" is false, we will
+     * resolve immediately and refetch in the background
+     *
+     * @default true
+     */
+    blockIfStale?: boolean;
+} & QueryVariables<Q>;
+export type HasVariables<V extends keyof GraphQLQuery.OperationVariables> = {
+    [K in keyof GraphQLQuery.OperationVariables[V]]: GraphQLQuery.OperationVariables[V][K];
+}[keyof GraphQLQuery.OperationVariables[V]] extends never ? false : true;

package/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/mjs/GraphQLQueryCache.d.ts

@@ -0,0 +1,62 @@
+import type { GraphQLCacheShape, GraphQLMutationResult, GraphQLOperationResult, GraphQLQueryCacheConfig, GraphQLQueryResult, InvalidateQueryArgs, MaybePromise, ExecutionOptions, ReadQueryArgs, SerializedVariables, SubscribeToQueryArgs, PreloadQueryOptions } from './types';
+/**
+ * Manages the cached normalized state, and the execution of
+ * data accessed by different components
+ */
+export declare class GraphQLQueryCache {
+    #private;
+    constructor(config: GraphQLQueryCacheConfig);
+    /**
+     * Invalidates a query by name or predicate fn
+     */
+    invalidateQuery(toInvalidate: InvalidateQueryArgs): void;
+    /**
+     * Invalidates a query by name or predicate fn
+     */
+    refetchQuery(toRefetch: InvalidateQueryArgs): void;
+    /**
+     * JSON.stringify(queryCache) produces the data we need
+     * to rehydrate the Client
+     */
+    toJSON(): GraphQLCacheShape;
+    /**
+     * Attempts to read a query from the cache, returning undefined
+     * if we are unable to for any reason. Used in initial hook execution
+     * where we don't want any side-effects, incase we're doing SSR
+     */
+    tryReadQuery<Q extends keyof GraphQLQuery.QueryRegistry>(args: ReadQueryArgs<Q>): GraphQLOperationResult<Q> | undefined;
+    /**
+     * Reads the query from the cache. Throws an error if we are unable
+     * to read the data, due to an incomplete result or lack of operation
+     * metadata
+     */
+    readQuery<Q extends keyof GraphQLQuery.QueryRegistry>(args: ReadQueryArgs<Q>): GraphQLOperationResult<Q>;
+    /**
+     * Reads the query from the cache if any of the following conditions are met:
+     *  a) We already have the result of this query in the operation cache
+     *  b) We have the necessary metadata, as well as all of the necessary fields info to complete
+     *     this query from the field cache
+     */
+    readOrFetchQuery<Q extends keyof GraphQLQuery.QueryRegistry>(args: ReadQueryArgs<Q>): GraphQLOperationResult<Q> | Promise<GraphQLOperationResult<Q>>;
+    /**
+     * Loads the query if it's not already in the cache,
+     * useful when hydrating the cache outside of a component
+     */
+    preloadQuery<Q extends keyof GraphQLQuery.QueryRegistry>(queryName: Q, options: PreloadQueryOptions<Q>): MaybePromise<GraphQLOperationResult<Q>>;
+    fetchQuery<Q extends keyof GraphQLQuery.QueryRegistry>(args: ReadQueryArgs<Q>): Promise<GraphQLOperationResult<Q>>;
+    /**
+     * Executes a mutation, returning the result of that mutation
+     */
+    executeMutation<M extends keyof GraphQLQuery.MutationRegistry>(mutationName: M, variables: SerializedVariables | object, options?: ExecutionOptions): Promise<GraphQLMutationResult<M>>;
+    /**
+     * Executes a query, returning the result of that query
+     */
+    executeQuery<Q extends keyof GraphQLQuery.QueryRegistry>(queryName: Q, variables: SerializedVariables | GraphQLQuery.OperationVariables[Q]): Promise<GraphQLQueryResult<Q>>;
+    executeSubscription(): Promise<void>;
+    /**
+     * "Subscribes" to a query, meaning that when there are updates to fields in the
+     * field cache, we'll re-materialize the known value of the query. We'll also
+     * process based on configuration options, such as TTL, invalidateOnMutation
+     */
+    subscribeToQuery<Q extends keyof GraphQLQuery.QueryRegistry>(args: SubscribeToQueryArgs<Q>): () => void;
+}