commit 47c34c4134c3bba74c78db5b1ebc3fa021e1942d · kitten.sh/urql

.changeset/lucky-months-fail.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       '@urql/core': patch

     

       3
       3
       +
       ---

     

       4
       4
       +
       

     

       5
       5
       +
       Add missing type exports of SSR-related types (`SerializedResult`, `SSRExchangeParams`, `SSRExchange`, and `SSRData`) to `@urql/core`'s type exports.

.changeset/strong-shirts-hear.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       '@urql/introspection': patch

     

       3
       3
       +
       '@urql/storage-rn': patch

     

       4
       4
       +
       'next-urql': patch

     

       5
       5
       +
       ---

     

       6
       6
       +
       

     

       7
       7
       +
       Add TSDocs to `@urql/*` packages.

.changeset/tricky-cherries-glow.md

···

       1
       1
       +
       ---

     

       2
       2
       +
       '@urql/preact': patch

     

       3
       3
       +
       '@urql/svelte': patch

     

       4
       4
       +
       'urql': patch

     

       5
       5
       +
       '@urql/vue': patch

     

       6
       6
       +
       ---

     

       7
       7
       +
       

     

       8
       8
       +
       Add TSDocs to all `urql` bindings packages.

packages/core/src/exchanges/index.ts

···

       7
       7
        
       export { composeExchanges } from './compose';

     

       8
       8
        
       

     

       9
       9
        
       export type {

     

       10
       10
       +
         SerializedResult,

     

       11
       11
       +
         SSRExchangeParams,

     

       12
       12
       +
         SSRExchange,

     

       13
       13
       +
         SSRData,

     

       14
       14
       +
       } from './ssr';

     

       15
       15
       +
       

     

       16
       16
       +
       export type {

     

       10
       17
        
         SubscriptionOperation,

     

       11
       18
        
         SubscriptionForwarder,

     

       12
       19
        
         SubscriptionExchangeOpts,

+15

packages/introspection/src/getIntrospectedSchema.ts

···

       7
       7
        
         getIntrospectionQuery,

     

       8
       8
        
       } from 'graphql';

     

       9
       9
        
       

     

       10
       10
       +
       /** Returns an {@link IntrospectionQuery} result for a given GraphQL schema.

     

       11
       11
       +
        *

     

       12
       12
       +
        * @param input - A GraphQL schema, either as an SDL string, or a {@link GraphQLSchema} object.

     

       13
       13
       +
        * @returns an {@link IntrospectionQuery} result.

     

       14
       14
       +
        *

     

       15
       15
       +
        * @remarks

     

       16
       16
       +
        * `getIntrospectedSchema` can be used to get a Schema Introspection result from

     

       17
       17
       +
        * a given GraphQL schema. The schema can be passed as an SDL string or a

     

       18
       18
       +
        * {@link GraphQLSchema} object. If an {@link IntrospectionQuery} object is

     

       19
       19
       +
        * passed, it'll be passed through.

     

       20
       20
       +
        *

     

       21
       21
       +
        * @throws

     

       22
       22
       +
        * If `input` cannot be parsed or converted into a {@link GraphQLSchema} then

     

       23
       23
       +
        * a {@link TypeError} will be thrown.

     

       24
       24
       +
        */

     

       10
       25
        
       export const getIntrospectedSchema = (

     

       11
       26
        
         input: string | IntrospectionQuery | GraphQLSchema

     

       12
       27
        
       ): IntrospectionQuery => {

+39 -5

packages/introspection/src/minifyIntrospectionQuery.ts

···

       156
       156
        
         }

     

       157
       157
        
       };

     

       158
       158
        
       

     

       159
       159
       +
       /** Input parameters for the {@link minifyIntrospectionQuery} function. */

     

       159
       160
        
       export interface MinifySchemaOptions {

     

       160
       160
       -
         /** Includes scalar names (instead of an `Any` replacement) in the output when enabled. */

     

       161
       161
       +
         /** Includes scalars instead of removing them.

     

       162
       162
       +
          *

     

       163
       163
       +
          * @remarks

     

       164
       164
       +
          * By default, all scalars will be replaced by a single scalar called `Any`

     

       165
       165
       +
          * in the output, unless this option is set to `true`.

     

       166
       166
       +
          */

     

       161
       167
        
         includeScalars?: boolean;

     

       162
       162
       -
         /** Includes enums (instead of an `Any` replacement) in the output when enabled. */

     

       168
       168
       +
         /** Includes enums instead of removing them.

     

       169
       169
       +
          *

     

       170
       170
       +
          * @remarks

     

       171
       171
       +
          * By default, all enums will be replaced by a single scalar called `Any`

     

       172
       172
       +
          * in the output, unless this option is set to `true`.

     

       173
       173
       +
          */

     

       163
       174
        
         includeEnums?: boolean;

     

       164
       164
       -
         /** Includes all input objects (instead of an `Any` replacement) in the output when enabled. */

     

       175
       175
       +
         /** Includes inputs instead of removing them.

     

       176
       176
       +
          *

     

       177
       177
       +
          * @remarks

     

       178
       178
       +
          * By default, all inputs will be replaced by a single scalar called `Any`

     

       179
       179
       +
          * in the output, unless this option is set to `true`.

     

       180
       180
       +
          */

     

       165
       181
        
         includeInputs?: boolean;

     

       166
       166
       -
         /** Includes all directives in the output when enabled. */

     

       182
       182
       +
         /** Includes directives instead of removing them. */

     

       167
       183
        
         includeDirectives?: boolean;

     

       168
       184
        
       }

     

       169
       185
        
       

     

       170
       170
       -
       /** Removes extraneous information from introspected schema data to minify it and prepare it for use on the client-side. */

     

       186
       186
       +
       /** Minifies an {@link IntrospectionQuery} for use with Graphcache or the `populateExchange`.

     

       187
       187
       +
        *

     

       188
       188
       +
        * @param schema - An {@link IntrospectionQuery} object to be minified.

     

       189
       189
       +
        * @param opts - An optional {@link MinifySchemaOptions} configuration object.

     

       190
       190
       +
        * @returns the minified {@link IntrospectionQuery} object.

     

       191
       191
       +
        *

     

       192
       192
       +
        * @remarks

     

       193
       193
       +
        * `minifyIntrospectionQuery` reduces the size of an {@link IntrospectionQuery} by

     

       194
       194
       +
        * removing data and information that a client-side consumer, like Graphcache or the

     

       195
       195
       +
        * `populateExchange`, may not require.

     

       196
       196
       +
        *

     

       197
       197
       +
        * At the very least, it will remove system types, descriptions, depreactions,

     

       198
       198
       +
        * and source locations. Unless disabled via the options passed, it will also

     

       199
       199
       +
        * by default remove all scalars, enums, inputs, and directives.

     

       200
       200
       +
        *

     

       201
       201
       +
        * @throws

     

       202
       202
       +
        * If `schema` receives an object that isn’t an {@link IntrospectionQuery}, a

     

       203
       203
       +
        * {@link TypeError} will be thrown.

     

       204
       204
       +
        */

     

       171
       205
        
       export const minifyIntrospectionQuery = (

     

       172
       206
        
         schema: IntrospectionQuery,

     

       173
       207
        
         opts: MinifySchemaOptions = {}

+25 -1

packages/next-urql/src/init-urql-client.ts

···

       2
       2
        
       

     

       3
       3
        
       let urqlClient: Client | null = null;

     

       4
       4
        
       

     

       5
       5
       +
       /** Resets the `Client` that {@link initUrqlClient} returns.

     

       6
       6
       +
        *

     

       7
       7
       +
        * @remarks

     

       8
       8
       +
        * `resetClient` will force {@link initUrqlClient} to create a new

     

       9
       9
       +
        * {@link Client}, rather than reusing the same `Client` it already

     

       10
       10
       +
        * created on the client-side.

     

       11
       11
       +
        *

     

       12
       12
       +
        * This may be used to force the cache and any state in the `Client`

     

       13
       13
       +
        * to be cleared and reset.

     

       14
       14
       +
        */

     

       5
       15
        
       export function resetClient() {

     

       6
       16
        
         urqlClient = null;

     

       7
       17
        
       }

     

       8
       18
        
       

     

       19
       19
       +
       /** Creates a {@link Client} the given options.

     

       20
       20
       +
        *

     

       21
       21
       +
        * @param clientOptions - {@link ClientOptions} to create the `Client` with.

     

       22
       22
       +
        * @param canEnableSuspense - Enables React Suspense on the server-side for `react-ssr-prepass`.

     

       23
       23
       +
        * @returns the created {@link Client}

     

       24
       24
       +
        *

     

       25
       25
       +
        * @remarks

     

       26
       26
       +
        * `initUrqlClient` creates a {@link Client} with the given options,

     

       27
       27
       +
        * like {@link createClient} does, but reuses the same client when

     

       28
       28
       +
        * run on the client-side.

     

       29
       29
       +
        *

     

       30
       30
       +
        * As long as `canEnableSuspense` is set to `true`, it enables React Suspense

     

       31
       31
       +
        * mode on the server-side for `react-ssr-prepass`.

     

       32
       32
       +
        */

     

       9
       33
        
       export function initUrqlClient(

     

       10
       34
        
         clientOptions: ClientOptions,

     

       11
       35
        
         canEnableSuspense: boolean

     

       12
       12
       -
       ): Client | null {

     

       36
       36
       +
       ): Client {

     

       13
       37
        
         // Create a new Client for every server-side rendered request.

     

       14
       38
        
         // This ensures we reset the state for each rendered page.

     

       15
       39
        
         // If there is an exising client instance on the client-side, use it.

+76 -32

packages/next-urql/src/types.ts

···

       1
       1
       -
       import { GraphQLError } from 'graphql';

     

       2
       2
       -
       import { ClientOptions, Exchange, Client } from 'urql';

     

       3
       3
       -
       import { NextPageContext } from 'next';

     

       4
       4
       -
       import { AppContext } from 'next/app';

     

       1
       1
       +
       import type { ClientOptions, Client, SSRExchange, SSRData } from '@urql/core';

     

       2
       2
       +
       import type { NextPageContext } from 'next';

     

       3
       3
       +
       import type { AppContext } from 'next/app';

     

       5
       4
        
       

     

       5
       5
       +
       /** The Next.js {@link NextPageContext}, as modified by `next-urql`. */

     

       6
       6
        
       export interface NextUrqlPageContext extends NextPageContext {

     

       7
       7
        
         urqlClient: Client;

     

       8
       8
        
       }

     

       9
       9
        
       

     

       10
       10
       +
       /** The Next.js {@link AppContext}, as modified by `next-urql`. */

     

       10
       11
        
       export interface NextUrqlAppContext extends AppContext {

     

       11
       12
        
         urqlClient: Client;

     

       12
       13
        
       }

     

       13
       14
        
       

     

       14
       15
        
       export type NextUrqlContext = NextUrqlPageContext | NextUrqlAppContext;

     

       15
       16
        
       

     

       17
       17
       +
       /** Passed to {@link withUrqlClient} returning the options a {@link Client} is created with.

     

       18
       18
       +
        *

     

       19
       19
       +
        * @param ssrExchange - the `ssrExchange` you must use in your `exchanges` array.

     

       20
       20
       +
        * @param ctx - Passed when `getInitialProps` is used and set to Next.js’ {@link NextPageContext}.

     

       21
       21
       +
        * @returns a {@link ClientOptions} configuration object to create a {@link Client} with.

     

       22
       22
       +
        *

     

       23
       23
       +
        * @remarks

     

       24
       24
       +
        * You must define a `getClientConfig` function and pass it to {@link withUrqlClient}.

     

       25
       25
       +
        *

     

       26
       26
       +
        * This function defines the options passed to {@link initUrqlClient}.

     

       27
       27
       +
        * It passes you an `ssrExchange` that you must use in your `exchanges` array.

     

       28
       28
       +
        *

     

       29
       29
       +
        * @example

     

       30
       30
       +
        * ```ts

     

       31
       31
       +
        * import { cacheExchange, fetchExchange } from '@urql/core';

     

       32
       32
       +
        * import { withUrqlClient } from 'next-urql';

     

       33
       33
       +
        *

     

       34
       34
       +
        * const WrappedPage = withUrqlClient(

     

       35
       35
       +
        *   (ssrExchange) => ({

     

       36
       36
       +
        *     url: 'https://YOUR_API',

     

       37
       37
       +
        *     exchanges: [cacheExchange, ssrExchange, fetchExchange],

     

       38
       38
       +
        *   })

     

       39
       39
       +
        * )(Page);

     

       40
       40
       +
        * ```

     

       41
       41
       +
        */

     

       16
       42
        
       export type NextUrqlClientConfig = (

     

       17
       43
        
         ssrExchange: SSRExchange,

     

       18
       44
        
         ctx?: NextPageContext

     

       19
       45
        
       ) => ClientOptions;

     

       20
       46
        
       

     

       21
       21
       -
       export interface WithUrqlState {

     

       22
       22
       -
         urqlState?: SSRData;

     

       23
       23
       -
       }

     

       24
       24
       -
       

     

       25
       25
       -
       export interface WithUrqlClient {

     

       47
       47
       +
       /** Props that {@link withUrqlClient} components pass on to your component. */

     

       48
       48
       +
       export interface WithUrqlProps {

     

       49
       49
       +
         /** The {@link Client} that {@link withUrqlClient} created for your component. */

     

       26
       50
        
         urqlClient?: Client;

     

       27
       27
       -
       }

     

       28
       28
       -
       

     

       29
       29
       -
       export interface WithUrqlProps extends WithUrqlClient, WithUrqlState {

     

       30
       30
       -
         resetUrqlClient?: () => void;

     

       51
       51
       +
         /** Next.js’ `pageProps` prop, as passed to it by Next.js. */

     

       31
       52
        
         pageProps: any;

     

       53
       53
       +
         /** The SSR data that {@link withUrqlClient} created for your component. */

     

       54
       54
       +
         urqlState?: SSRData;

     

       55
       55
       +
         /** Resets the `Client` that on the client-side.

     

       56
       56
       +
          *

     

       57
       57
       +
          * @remarks

     

       58
       58
       +
          * `resetUrqlClient` will force a new {@link Client} to be created

     

       59
       59
       +
          * on the client-side, rather than the same `Client` with the same

     

       60
       60
       +
          * server-side data to be reused.

     

       61
       61
       +
          *

     

       62
       62
       +
          * This may be used to force the cache and any state in the `Client`

     

       63
       63
       +
          * to be cleared and reset.

     

       64
       64
       +
          */

     

       65
       65
       +
         resetUrqlClient?(): void;

     

       32
       66
        
         [key: string]: any;

     

       33
       67
        
       }

     

       34
       68
        
       

     

       35
       35
       -
       export interface SerializedResult {

     

       36
       36
       -
         data?: any;

     

       37
       37
       -
         error?: {

     

       38
       38
       -
           graphQLErrors: Array<Partial<GraphQLError> | string>;

     

       39
       39
       -
           networkError?: string;

     

       40
       40
       -
         };

     

       41
       41
       -
       }

     

       42
       42
       -
       

     

       43
       43
       -
       export interface SSRData {

     

       44
       44
       -
         [key: string]: SerializedResult;

     

       45
       45
       -
       }

     

       46
       46
       -
       

     

       47
       47
       -
       export interface SSRExchange extends Exchange {

     

       48
       48
       -
         /** Rehydrates cached data */

     

       49
       49
       -
         restoreData(data: SSRData): void;

     

       50
       50
       -
         /** Extracts cached data */

     

       51
       51
       -
         extractData(): SSRData;

     

       52
       52
       -
       }

     

       53
       53
       -
       

     

       69
       69
       +
       /** Options that may be passed to the {@link withUrqlClient} wrapper function. */

     

       54
       70
        
       export interface WithUrqlClientOptions {

     

       71
       71
       +
         /** Enables automatic server-side rendering mode.

     

       72
       72
       +
          *

     

       73
       73
       +
          * @remarks

     

       74
       74
       +
          * When enabled, {@link withUrqlClient} will add a `getInitialProps`

     

       75
       75
       +
          * function to the resulting component, even if you haven't defined

     

       76
       76
       +
          * one.

     

       77
       77
       +
          *

     

       78
       78
       +
          * This function will automatically capture `urql`'s SSR state on the

     

       79
       79
       +
          * server-side and rehydrate it on the client-side, unless

     

       80
       80
       +
          * {@link WithUrqlClientOptions.neverSuspend} is `true`.

     

       81
       81
       +
          */

     

       55
       82
        
         ssr?: boolean;

     

       83
       83
       +
         /** Disables automatic server-side rendering, even if a `getInitialProps` function is defined.

     

       84
       84
       +
          *

     

       85
       85
       +
          * @remarks

     

       86
       86
       +
          * When enabled, {@link withUrqlClient} will never execute queries

     

       87
       87
       +
          * on the server-side automatically, and will instead rely on you

     

       88
       88
       +
          * to do so manually.

     

       89
       89
       +
          */

     

       56
       90
        
         neverSuspend?: boolean;

     

       91
       91
       +
         /** Enables reexecuting operations on the client-side after rehydration.

     

       92
       92
       +
          *

     

       93
       93
       +
          * @remarks

     

       94
       94
       +
          * When enabled, `staleWhileRevalidate` will reexecute GraphQL queries on

     

       95
       95
       +
          * the client-side, if they’ve been rehydrated from SSR state.

     

       96
       96
       +
          *

     

       97
       97
       +
          * This is useful if you, for instance, cache your server-side rendered

     

       98
       98
       +
          * pages, or if you use `getStaticProps` and wish to get this data

     

       99
       99
       +
          * updated.

     

       100
       100
       +
          */

     

       57
       101
        
         staleWhileRevalidate?: boolean;

     

       58
       102
        
       }

+40 -17

packages/next-urql/src/with-urql-client.ts

···

       6
       6
        
         ReactNode,

     

       7
       7
        
         ReactElement,

     

       8
       8
        
       } from 'react';

     

       9
       9
       -
       import ssrPrepass from 'react-ssr-prepass';

     

       10
       10
       -
       import { NextComponentType, NextPage, NextPageContext } from 'next';

     

       11
       11
       -
       import NextApp, { AppContext } from 'next/app';

     

       12
       9
        
       

     

       13
       10
        
       import {

     

       14
       11
        
         Provider,

     

       12
       12
       +
         SSRExchange,

     

       15
       13
        
         ssrExchange,

     

       16
       16
       -
         dedupExchange,

     

       17
       14
        
         cacheExchange,

     

       18
       15
        
         fetchExchange,

     

       19
       16
        
       } from 'urql';

     

       20
       17
        
       

     

       18
       18
       +
       import ssrPrepass from 'react-ssr-prepass';

     

       19
       19
       +
       import { NextComponentType, NextPage, NextPageContext } from 'next';

     

       20
       20
       +
       import NextApp, { AppContext } from 'next/app';

     

       21
       21
       +
       

     

       21
       22
        
       import { initUrqlClient, resetClient } from './init-urql-client';

     

       22
       23
        
       

     

       23
       24
        
       import {

     
···

       25
       26
        
         NextUrqlContext,

     

       26
       27
        
         WithUrqlProps,

     

       27
       28
        
         WithUrqlClientOptions,

     

       28
       28
       -
         SSRExchange,

     

       29
       29
        
       } from './types';

     

       30
       30
        
       

     

       31
       31
        
       let ssr: SSRExchange;

     
···

       33
       33
        
         getLayout?: (page: ReactElement) => ReactNode;

     

       34
       34
        
       };

     

       35
       35
        
       

     

       36
       36
       +
       /** Creates a wrapper for Next.js Page, App, or Document components that rehydrates `urql` state.

     

       37
       37
       +
        *

     

       38
       38
       +
        * @param getClientConfig - function used to create the {@link Client}

     

       39
       39
       +
        * @param options - optional {@link WithUrqlClientOptions} configuration options

     

       40
       40
       +
        * @returns a higher-order component function, which you can pass a Next.js page or app component.

     

       41
       41
       +
        *

     

       42
       42
       +
        * @remarks

     

       43
       43
       +
        * Used to wrap a Next.js page or app component. It will create a {@link Client} and passes

     

       44
       44
       +
        * it on to the child component and adds a React Provider for it.

     

       45
       45
       +
        *

     

       46
       46
       +
        * It will restore any page’s `pageProps.urqlState` with the {@link SSRExchange} and also

     

       47
       47
       +
        * supports doing this automatically when the {@link WithUrqlClientOptions.ssr} option

     

       48
       48
       +
        * is enabled.

     

       49
       49
       +
        *

     

       50
       50
       +
        * If you don’t define the above option, you will have to write `getServerSideProps` or

     

       51
       51
       +
        * `getStaticProps` methods on your component manually.

     

       52
       52
       +
        *

     

       53
       53
       +
        * @see {@link https://urql.dev/goto/docs/advanced/server-side-rendering/#nextjs} for more documentation.

     

       54
       54
       +
        *

     

       55
       55
       +
        * @example

     

       56
       56
       +
        * ```ts

     

       57
       57
       +
        * import { cacheExchange, fetchExchange } from '@urql/core';

     

       58
       58
       +
        * import { withUrqlClient } from 'next-urql';

     

       59
       59
       +
        *

     

       60
       60
       +
        * const WrappedPage = withUrqlClient(

     

       61
       61
       +
        *   (ssrExchange) => ({

     

       62
       62
       +
        *     url: 'https://YOUR_API',

     

       63
       63
       +
        *     exchanges: [cacheExchange, ssrExchange, fetchExchange],

     

       64
       64
       +
        *   }),

     

       65
       65
       +
        *   { ssr: true },

     

       66
       66
       +
        * )(Page);

     

       67
       67
       +
        * ```

     

       68
       68
       +
        */

     

       36
       69
        
       export function withUrqlClient(

     

       37
       70
        
         getClientConfig: NextUrqlClientConfig,

     

       38
       71
        
         options?: WithUrqlClientOptions

     
···

       77
       110
        
               const clientConfig = getClientConfig(ssr);

     

       78
       111
        
               if (!clientConfig.exchanges) {

     

       79
       112
        
                 // When the user does not provide exchanges we make the default assumption.

     

       80
       80
       -
                 clientConfig.exchanges = [

     

       81
       81
       -
                   dedupExchange,

     

       82
       82
       -
                   cacheExchange,

     

       83
       83
       -
                   ssr,

     

       84
       84
       -
                   fetchExchange,

     

       85
       85
       -
                 ];

     

       113
       113
       +
                 clientConfig.exchanges = [cacheExchange, ssr, fetchExchange];

     

       86
       114
        
               }

     

       87
       115
        
       

     

       88
       116
        
               return initUrqlClient(clientConfig, shouldEnableSuspense)!;

     
···

       129
       157
        
               const clientConfig = getClientConfig(ssrCache, ctx);

     

       130
       158
        
               if (!clientConfig.exchanges) {

     

       131
       159
        
                 // When the user does not provide exchanges we make the default assumption.

     

       132
       132
       -
                 clientConfig.exchanges = [

     

       133
       133
       -
                   dedupExchange,

     

       134
       134
       -
                   cacheExchange,

     

       135
       135
       -
                   ssrCache,

     

       136
       136
       -
                   fetchExchange,

     

       137
       137
       -
                 ];

     

       160
       160
       +
                 clientConfig.exchanges = [cacheExchange, ssrCache, fetchExchange];

     

       138
       161
        
               }

     

       139
       162
        
       

     

       140
       163
        
               const urqlClient = initUrqlClient(clientConfig, !options!.neverSuspend);

+30 -12

packages/preact-urql/src/components/Mutation.ts

···

       1
       1
        
       import { VNode } from 'preact';

     

       2
       2
        
       import { DocumentNode } from 'graphql';

     

       3
       3
       -
       import {

     

       4
       4
       -
         AnyVariables,

     

       5
       5
       -
         TypedDocumentNode,

     

       6
       6
       -
         OperationResult,

     

       7
       7
       -
         OperationContext,

     

       8
       8
       -
       } from '@urql/core';

     

       9
       9
       -
       import { useMutation, UseMutationState } from '../hooks';

     

       3
       3
       +
       import { AnyVariables, TypedDocumentNode } from '@urql/core';

     

       4
       4
       +
       

     

       5
       5
       +
       import { useMutation, UseMutationState, UseMutationExecute } from '../hooks';

     

       10
       6
        
       

     

       7
       7
       +
       /** Props accepted by {@link Mutation}.

     

       8
       8
       +
        *

     

       9
       9
       +
        * @remarks

     

       10
       10
       +
        * `MutationProps` are the props accepted by the {@link Mutation} component.

     

       11
       11
       +
        *

     

       12
       12
       +
        * The result, the {@link MutationState} object, will be passed to

     

       13
       13
       +
        * a {@link MutationProps.children} function, passed as children

     

       14
       14
       +
        * to the `Mutation` component.

     

       15
       15
       +
        */

     

       11
       16
        
       export interface MutationProps<

     

       12
       17
        
         Data = any,

     

       13
       18
        
         Variables extends AnyVariables = AnyVariables

     

       14
       19
        
       > {

     

       20
       20
       +
         /* The GraphQL mutation document that {@link useMutation} will execute. */

     

       15
       21
        
         query: DocumentNode | TypedDocumentNode<Data, Variables> | string;

     

       16
       16
       -
         children: (arg: MutationState<Data, Variables>) => VNode<any>;

     

       22
       22
       +
         children(arg: MutationState<Data, Variables>): VNode<any>;

     

       17
       23
        
       }

     

       18
       24
        
       

     

       25
       25
       +
       /** Object that {@link MutationProps.children} is called with.

     

       26
       26
       +
        *

     

       27
       27
       +
        * @remarks

     

       28
       28
       +
        * This is an extented {@link UseMutationstate} with an added

     

       29
       29
       +
        * {@link MutationState.executeMutation} method, which is usually

     

       30
       30
       +
        * part of a tuple returned by {@link useMutation}.

     

       31
       31
       +
        */

     

       19
       32
        
       export interface MutationState<

     

       20
       33
        
         Data = any,

     

       21
       34
        
         Variables extends AnyVariables = AnyVariables

     

       22
       35
        
       > extends UseMutationState<Data, Variables> {

     

       23
       23
       -
         executeMutation: (

     

       24
       24
       -
           variables: Variables,

     

       25
       25
       -
           context?: Partial<OperationContext>

     

       26
       26
       -
         ) => Promise<OperationResult<Data, Variables>>;

     

       36
       36
       +
         /** Alias to {@link useMutation}’s `executeMutation` function. */

     

       37
       37
       +
         executeMutation: UseMutationExecute<Data, Variables>;

     

       27
       38
        
       }

     

       28
       39
        
       

     

       40
       40
       +
       /** Component Wrapper around {@link useMutation} to run a GraphQL query.

     

       41
       41
       +
        *

     

       42
       42
       +
        * @remarks

     

       43
       43
       +
        * `Mutation` is a component wrapper around the {@link useMutation} hook

     

       44
       44
       +
        * that calls the {@link MutationProps.children} prop, as a function,

     

       45
       45
       +
        * with the {@link MutationState} object.

     

       46
       46
       +
        */

     

       29
       47
        
       export function Mutation<

     

       30
       48
        
         Data = any,

     

       31
       49
        
         Variables extends AnyVariables = AnyVariables

+35 -4

packages/preact-urql/src/components/Query.ts

···

       1
       1
        
       import { VNode } from 'preact';

     

       2
       2
       -
       import { AnyVariables, OperationContext } from '@urql/core';

     

       3
       3
       -
       import { useQuery, UseQueryArgs, UseQueryState } from '../hooks';

     

       2
       2
       +
       import { AnyVariables } from '@urql/core';

     

       3
       3
       +
       

     

       4
       4
       +
       import {

     

       5
       5
       +
         useQuery,

     

       6
       6
       +
         UseQueryArgs,

     

       7
       7
       +
         UseQueryState,

     

       8
       8
       +
         UseQueryExecute,

     

       9
       9
       +
       } from '../hooks';

     

       4
       10
        
       

     

       11
       11
       +
       /** Props accepted by {@link Query}.

     

       12
       12
       +
        *

     

       13
       13
       +
        * @remarks

     

       14
       14
       +
        * `QueryProps` are the props accepted by the {@link Query} component,

     

       15
       15
       +
        * which is identical to {@link UseQueryArgs}.

     

       16
       16
       +
        *

     

       17
       17
       +
        * The result, the {@link QueryState} object, will be passed to

     

       18
       18
       +
        * a {@link QueryProps.children} function, passed as children

     

       19
       19
       +
        * to the `Query` component.

     

       20
       20
       +
        */

     

       5
       21
        
       export type QueryProps<

     

       6
       22
        
         Data = any,

     

       7
       23
        
         Variables extends AnyVariables = AnyVariables

     

       8
       24
        
       > = UseQueryArgs<Variables, Data> & {

     

       9
       9
       -
         children: (arg: QueryState<Data, Variables>) => VNode<any>;

     

       25
       25
       +
         children(arg: QueryState<Data, Variables>): VNode<any>;

     

       10
       26
        
       };

     

       11
       27
        
       

     

       28
       28
       +
       /** Object that {@link QueryProps.children} is called with.

     

       29
       29
       +
        *

     

       30
       30
       +
        * @remarks

     

       31
       31
       +
        * This is an extented {@link UseQueryState} with an added

     

       32
       32
       +
        * {@link QueryState.executeQuery} method, which is usually

     

       33
       33
       +
        * part of a tuple returned by {@link useQuery}.

     

       34
       34
       +
        */

     

       12
       35
        
       export interface QueryState<

     

       13
       36
        
         Data = any,

     

       14
       37
        
         Variables extends AnyVariables = AnyVariables

     

       15
       38
        
       > extends UseQueryState<Data, Variables> {

     

       16
       16
       -
         executeQuery: (opts?: Partial<OperationContext>) => void;

     

       39
       39
       +
         /** Alias to {@link useQuery}’s `executeQuery` function. */

     

       40
       40
       +
         executeQuery: UseQueryExecute;

     

       17
       41
        
       }

     

       18
       42
        
       

     

       43
       43
       +
       /** Component Wrapper around {@link useQuery} to run a GraphQL query.

     

       44
       44
       +
        *

     

       45
       45
       +
        * @remarks

     

       46
       46
       +
        * `Query` is a component wrapper around the {@link useQuery} hook

     

       47
       47
       +
        * that calls the {@link QueryProps.children} prop, as a function,

     

       48
       48
       +
        * with the {@link QueryState} object.

     

       49
       49
       +
        */

     

       19
       50
        
       export function Query<

     

       20
       51
        
         Data = any,

     

       21
       52
        
         Variables extends AnyVariables = AnyVariables

+32 -3

packages/preact-urql/src/components/Subscription.ts

···

       1
       1
        
       import { VNode } from 'preact';

     

       2
       2
       -
       import { AnyVariables, OperationContext } from '@urql/core';

     

       2
       2
       +
       import { AnyVariables } from '@urql/core';

     

       3
       3
        
       

     

       4
       4
        
       import {

     

       5
       5
        
         useSubscription,

     

       6
       6
        
         UseSubscriptionArgs,

     

       7
       7
        
         UseSubscriptionState,

     

       8
       8
       +
         UseSubscriptionExecute,

     

       8
       9
        
         SubscriptionHandler,

     

       9
       10
        
       } from '../hooks';

     

       10
       11
        
       

     

       12
       12
       +
       /** Props accepted by {@link Subscription}.

     

       13
       13
       +
        *

     

       14
       14
       +
        * @remarks

     

       15
       15
       +
        * `SubscriptionProps` are the props accepted by the {@link Subscription} component,

     

       16
       16
       +
        * which is identical to {@link UseSubscriptionArgs} with an added

     

       17
       17
       +
        * {@link SubscriptionProps.handler} prop, which {@link useSubscription} usually

     

       18
       18
       +
        * accepts as an additional argument.

     

       19
       19
       +
        *

     

       20
       20
       +
        * The result, the {@link SubscriptionState} object, will be passed to

     

       21
       21
       +
        * a {@link SubscriptionProps.children} function, passed as children

     

       22
       22
       +
        * to the `Subscription` component.

     

       23
       23
       +
        */

     

       11
       24
        
       export type SubscriptionProps<

     

       12
       25
        
         Data = any,

     

       13
       26
        
         Result = Data,

     

       14
       27
        
         Variables extends AnyVariables = AnyVariables

     

       15
       28
        
       > = UseSubscriptionArgs<Variables, Data> & {

     

       29
       29
       +
         /** Accepts the {@link SubscriptionHandler} as a prop. */

     

       16
       30
        
         handler?: SubscriptionHandler<Data, Result>;

     

       17
       17
       -
         children: (arg: SubscriptionState<Result, Variables>) => VNode<any>;

     

       31
       31
       +
         children(arg: SubscriptionState<Result, Variables>): VNode<any>;

     

       18
       32
        
       };

     

       19
       33
        
       

     

       34
       34
       +
       /** Object that {@link SubscriptionProps.children} is called with.

     

       35
       35
       +
        *

     

       36
       36
       +
        * @remarks

     

       37
       37
       +
        * This is an extented {@link UseSubscriptionState} with an added

     

       38
       38
       +
        * {@link SubscriptionState.executeSubscription} method, which is usually

     

       39
       39
       +
        * part of a tuple returned by {@link useSubscription}.

     

       40
       40
       +
        */

     

       20
       41
        
       export interface SubscriptionState<

     

       21
       42
        
         Data = any,

     

       22
       43
        
         Variables extends AnyVariables = AnyVariables

     

       23
       44
        
       > extends UseSubscriptionState<Data, Variables> {

     

       24
       24
       -
         executeSubscription: (opts?: Partial<OperationContext>) => void;

     

       45
       45
       +
         /** Alias to {@link useSubscription}’s `executeMutation` function. */

     

       46
       46
       +
         executeSubscription: UseSubscriptionExecute;

     

       25
       47
        
       }

     

       26
       48
        
       

     

       49
       49
       +
       /** Component Wrapper around {@link useSubscription} to run a GraphQL subscription.

     

       50
       50
       +
        *

     

       51
       51
       +
        * @remarks

     

       52
       52
       +
        * `Subscription` is a component wrapper around the {@link useSubscription} hook

     

       53
       53
       +
        * that calls the {@link SubscriptionProps.children} prop, as a function,

     

       54
       54
       +
        * with the {@link SubscriptionState} object.

     

       55
       55
       +
        */

     

       27
       56
        
       export function Subscription<

     

       28
       57
        
         Data = any,

     

       29
       58
        
         Result = Data,

+54

packages/preact-urql/src/context.ts

···

       3
       3
        
       import { Client } from '@urql/core';

     

       4
       4
        
       

     

       5
       5
        
       const OBJ = {};

     

       6
       6
       +
       

     

       7
       7
       +
       /** `@urql/preact`'s Preact Context.

     

       8
       8
       +
        *

     

       9
       9
       +
        * @remarks

     

       10
       10
       +
        * The Preact Context that `urql`’s {@link Client} will be provided with.

     

       11
       11
       +
        * You may use the reexported {@link Provider} to provide a `Client` as well.

     

       12
       12
       +
        */

     

       6
       13
        
       export const Context: import('preact').Context<Client | object> =

     

       7
       14
        
         createContext(OBJ);

     

       15
       15
       +
       

     

       16
       16
       +
       /** Provider for `urql`’s {@link Client} to GraphQL hooks.

     

       17
       17
       +
        *

     

       18
       18
       +
        * @remarks

     

       19
       19
       +
        * `Provider` accepts a {@link Client} and provides it to all GraphQL hooks,

     

       20
       20
       +
        * and {@link useClient}.

     

       21
       21
       +
        *

     

       22
       22
       +
        * You should make sure to create a {@link Client} and provide it with the

     

       23
       23
       +
        * `Provider` to parts of your component tree that use GraphQL hooks.

     

       24
       24
       +
        *

     

       25
       25
       +
        * @example

     

       26
       26
       +
        * ```tsx

     

       27
       27
       +
        * import { Provider } from '@urql/preact';

     

       28
       28
       +
        * // All of `@urql/core` is also re-exported by `@urql/preact`:

     

       29
       29
       +
        * import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       30
       30
       +
        *

     

       31
       31
       +
        * const client = new Client({

     

       32
       32
       +
        *   url: 'https://API',

     

       33
       33
       +
        *   exchanges: [cacheExchange, fetchExchange],

     

       34
       34
       +
        * });

     

       35
       35
       +
        *

     

       36
       36
       +
        * const App = () => (

     

       37
       37
       +
        *   <Provider value={client}>

     

       38
       38
       +
        *     <Component />

     

       39
       39
       +
        *   </Provider>

     

       40
       40
       +
        * );

     

       41
       41
       +
        * ```

     

       42
       42
       +
        */

     

       43
       43
       +
       

     

       8
       44
        
       export const Provider: import('preact').Provider<Client | object> =

     

       9
       45
        
         Context.Provider;

     

       46
       46
       +
       

     

       47
       47
       +
       /** Preact Consumer component, providing the {@link Client} provided on a parent component.

     

       48
       48
       +
        * @remarks

     

       49
       49
       +
        * This is an alias for {@link Context.Consumer}.

     

       50
       50
       +
        */

     

       10
       51
        
       export const Consumer: import('preact').Consumer<Client | object> =

     

       11
       52
        
         Context.Consumer;

     

       12
       53
        
       

     

       13
       54
        
       Context.displayName = 'UrqlContext';

     

       14
       55
        
       

     

       56
       56
       +
       /** Hook returning a {@link Client} from {@link Context}.

     

       57
       57
       +
        *

     

       58
       58
       +
        * @remarks

     

       59
       59
       +
        * `useClient` is a convenience hook, which accesses `@urql/preact`'s {@link Context}

     

       60
       60
       +
        * and returns the {@link Client} defined on it.

     

       61
       61
       +
        *

     

       62
       62
       +
        * This will be the {@link Client} you passed to a {@link Provider}

     

       63
       63
       +
        * you wrapped your elements containing this hook with.

     

       64
       64
       +
        *

     

       65
       65
       +
        * @throws

     

       66
       66
       +
        * In development, if the component you call `useClient()` in is

     

       67
       67
       +
        * not wrapped in a {@link Provider}, an error is thrown.

     

       68
       68
       +
        */

     

       15
       69
        
       export const useClient = (): Client => {

     

       16
       70
        
         const client = useContext(Context);

     

       17
       71

+110 -7

packages/preact-urql/src/hooks/useMutation.ts

···

       15
       15
        
       import { useClient } from '../context';

     

       16
       16
        
       import { initialState } from './constants';

     

       17
       17
        
       

     

       18
       18
       +
       /** State of the last mutation executed by your {@link useMutation} hook.

     

       19
       19
       +
        *

     

       20
       20
       +
        * @remarks

     

       21
       21
       +
        * `UseMutationState` is returned (in a tuple) by {@link useMutation} and

     

       22
       22
       +
        * gives you the {@link OperationResult} of the last mutation executed

     

       23
       23
       +
        * with {@link UseMutationExecute}.

     

       24
       24
       +
        *

     

       25
       25
       +
        * Even if the mutation document passed to {@link useMutation} changes,

     

       26
       26
       +
        * the state isn’t reset, so you can keep displaying the previous result.

     

       27
       27
       +
        */

     

       18
       28
        
       export interface UseMutationState<

     

       19
       29
        
         Data = any,

     

       20
       30
        
         Variables extends AnyVariables = AnyVariables

     

       21
       31
        
       > {

     

       32
       32
       +
         /** Indicates whether `useMutation` is currently executing a mutation. */

     

       22
       33
        
         fetching: boolean;

     

       34
       34
       +
         /** Indicates that the mutation result is not fresh.

     

       35
       35
       +
          *

     

       36
       36
       +
          * @remarks

     

       37
       37
       +
          * The `stale` flag is set to `true` when a new result for the mutation

     

       38
       38
       +
          * is expected.

     

       39
       39
       +
          * This is mostly unused for mutations and will rarely affect you, and

     

       40
       40
       +
          * is more relevant for queries.

     

       41
       41
       +
          *

     

       42
       42
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       43
       43
       +
          */

     

       23
       44
        
         stale: boolean;

     

       45
       45
       +
         /** The {@link OperationResult.data} for the executed mutation. */

     

       24
       46
        
         data?: Data;

     

       47
       47
       +
         /** The {@link OperationResult.error} for the executed mutation. */

     

       25
       48
        
         error?: CombinedError;

     

       49
       49
       +
         /** The {@link OperationResult.extensions} for the executed mutation. */

     

       26
       50
        
         extensions?: Record<string, any>;

     

       51
       51
       +
         /** The {@link Operation} that the current state is for.

     

       52
       52
       +
          *

     

       53
       53
       +
          * @remarks

     

       54
       54
       +
          * This is the mutation {@link Operation} that has last been executed.

     

       55
       55
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       56
       56
       +
          * last `Operation` that the current state was for.

     

       57
       57
       +
          */

     

       27
       58
        
         operation?: Operation<Data, Variables>;

     

       28
       59
        
       }

     

       29
       60
        
       

     

       61
       61
       +
       /** Triggers {@link useMutation} to execute its GraphQL mutation operation.

     

       62
       62
       +
        *

     

       63
       63
       +
        * @param variables - variables using which the mutation will be executed.

     

       64
       64
       +
        * @param context - optionally, context options that will be merged with the hook's

     

       65
       65
       +
        * {@link UseQueryArgs.context} options and the `Client`’s options.

     

       66
       66
       +
        * @returns the {@link OperationResult} of the mutation.

     

       67
       67
       +
        *

     

       68
       68
       +
        * @remarks

     

       69
       69
       +
        * When called, {@link useMutation} will start the GraphQL mutation

     

       70
       70
       +
        * it currently holds and use the `variables` passed to it.

     

       71
       71
       +
        *

     

       72
       72
       +
        * Once the mutation response comes back from the API, its

     

       73
       73
       +
        * returned promise will resolve to the mutation’s {@link OperationResult}

     

       74
       74
       +
        * and the {@link UseMutationState} will be updated with the result.

     

       75
       75
       +
        *

     

       76
       76
       +
        * @example

     

       77
       77
       +
        * ```ts

     

       78
       78
       +
        * const [result, executeMutation] = useMutation(UpdateTodo);

     

       79
       79
       +
        * const start = async ({ id, title }) => {

     

       80
       80
       +
        *   const result = await executeMutation({ id, title });

     

       81
       81
       +
        * };

     

       82
       82
       +
        */

     

       83
       83
       +
       export type UseMutationExecute<

     

       84
       84
       +
         Data = any,

     

       85
       85
       +
         Variables extends AnyVariables = AnyVariables

     

       86
       86
       +
       > = (

     

       87
       87
       +
         variables: Variables,

     

       88
       88
       +
         context?: Partial<OperationContext>

     

       89
       89
       +
       ) => Promise<OperationResult<Data, Variables>>;

     

       90
       90
       +
       

     

       91
       91
       +
       /** Result tuple returned by the {@link useMutation} hook.

     

       92
       92
       +
        *

     

       93
       93
       +
        * @remarks

     

       94
       94
       +
        * Similarly to a `useState` hook’s return value,

     

       95
       95
       +
        * the first element is the {@link useMutation}’s state, updated

     

       96
       96
       +
        * as mutations are executed with the second value, which is

     

       97
       97
       +
        * used to start mutations and is a {@link UseMutationExecute}

     

       98
       98
       +
        * function.

     

       99
       99
       +
        */

     

       30
       100
        
       export type UseMutationResponse<

     

       31
       101
        
         Data = any,

     

       32
       102
        
         Variables extends AnyVariables = AnyVariables

     

       33
       33
       -
       > = [

     

       34
       34
       -
         UseMutationState<Data, Variables>,

     

       35
       35
       -
         (

     

       36
       36
       -
           variables: Variables,

     

       37
       37
       -
           context?: Partial<OperationContext>

     

       38
       38
       -
         ) => Promise<OperationResult<Data, Variables>>

     

       39
       39
       -
       ];

     

       103
       103
       +
       > = [UseMutationState<Data, Variables>, UseMutationExecute<Data, Variables>];

     

       40
       104
        
       

     

       105
       105
       +
       /** Hook to create a GraphQL mutation, run by passing variables to the returned execute function.

     

       106
       106
       +
        *

     

       107
       107
       +
        * @param query - a GraphQL mutation document which `useMutation` will execute.

     

       108
       108
       +
        * @returns a {@link UseMutationResponse} tuple of a {@link UseMutationState} result,

     

       109
       109
       +
        * and an execute function to start the mutation.

     

       110
       110
       +
        *

     

       111
       111
       +
        * @remarks

     

       112
       112
       +
        * `useMutation` allows GraphQL mutations to be defined and keeps its state

     

       113
       113
       +
        * after the mutation is started with the returned execute function.

     

       114
       114
       +
        *

     

       115
       115
       +
        * Given a GraphQL mutation document it returns state to keep track of the

     

       116
       116
       +
        * mutation state and a {@link UseMutationExecute} function, which accepts

     

       117
       117
       +
        * variables for the mutation to be executed.

     

       118
       118
       +
        * Once called, the mutation executes and the state will be updated with

     

       119
       119
       +
        * the mutation’s result.

     

       120
       120
       +
        *

     

       121
       121
       +
        * @see {@link https://urql.dev/goto/docs/basics/react-preact/#mutations} for `useMutation` docs.

     

       122
       122
       +
        *

     

       123
       123
       +
        * @example

     

       124
       124
       +
        * ```ts

     

       125
       125
       +
        * import { gql, useMutation } from '@urql/preact';

     

       126
       126
       +
        *

     

       127
       127
       +
        * const UpdateTodo = gql`

     

       128
       128
       +
        *   mutation ($id: ID!, $title: String!) {

     

       129
       129
       +
        *     updateTodo(id: $id, title: $title) {

     

       130
       130
       +
        *       id, title

     

       131
       131
       +
        *     }

     

       132
       132
       +
        *   }

     

       133
       133
       +
        * `;

     

       134
       134
       +
        *

     

       135
       135
       +
        * const UpdateTodo = () => {

     

       136
       136
       +
        *   const [result, executeMutation] = useMutation(UpdateTodo);

     

       137
       137
       +
        *   const start = async ({ id, title }) => {

     

       138
       138
       +
        *     const result = await executeMutation({ id, title });

     

       139
       139
       +
        *   };

     

       140
       140
       +
        *   // ...

     

       141
       141
       +
        * };

     

       142
       142
       +
        * ```

     

       143
       143
       +
        */

     

       41
       144
        
       export function useMutation<

     

       42
       145
        
         Data = any,

     

       43
       146
        
         Variables extends AnyVariables = AnyVariables

+159 -5

packages/preact-urql/src/hooks/useQuery.ts

···

       28
       28
        
       import { useRequest } from './useRequest';

     

       29
       29
        
       import { initialState } from './constants';

     

       30
       30
        
       

     

       31
       31
       +
       /** Input arguments for the {@link useQuery} hook.

     

       32
       32
       +
        *

     

       33
       33
       +
        * @param query - The GraphQL query that `useQuery` executes.

     

       34
       34
       +
        * @param variables - The variables for the GraphQL query that `useQuery` executes.

     

       35
       35
       +
        */

     

       31
       36
        
       export type UseQueryArgs<

     

       32
       37
        
         Variables extends AnyVariables = AnyVariables,

     

       33
       38
        
         Data = any

     

       34
       39
        
       > = {

     

       40
       40
       +
         /** Updates the {@link RequestPolicy} for the executed GraphQL query operation.

     

       41
       41
       +
          *

     

       42
       42
       +
          * @remarks

     

       43
       43
       +
          * `requestPolicy` modifies the {@link RequestPolicy} of the GraphQL query operation

     

       44
       44
       +
          * that `useQuery` executes, and indicates a caching strategy for cache exchanges.

     

       45
       45
       +
          *

     

       46
       46
       +
          * For example, when set to `'cache-and-network'`, {@link useQuery} will

     

       47
       47
       +
          * receive a cached result with `stale: true` and an API request will be

     

       48
       48
       +
          * sent in the background.

     

       49
       49
       +
          *

     

       50
       50
       +
          * @see {@link OperationContext.requestPolicy} for where this value is set.

     

       51
       51
       +
          */

     

       35
       52
        
         requestPolicy?: RequestPolicy;

     

       53
       53
       +
         /** Updates the {@link OperationContext} for the executed GraphQL query operation.

     

       54
       54
       +
          *

     

       55
       55
       +
          * @remarks

     

       56
       56
       +
          * `context` may be passed to {@link useQuery}, to update the {@link OperationContext}

     

       57
       57
       +
          * of a query operation. This may be used to update the `context` that exchanges

     

       58
       58
       +
          * will receive for a single hook.

     

       59
       59
       +
          *

     

       60
       60
       +
          * Hint: This should be wrapped in a `useMemo` hook, to make sure that your

     

       61
       61
       +
          * component doesn’t infinitely update.

     

       62
       62
       +
          *

     

       63
       63
       +
          * @example

     

       64
       64
       +
          * ```ts

     

       65
       65
       +
          * const [result, reexecute] = useQuery({

     

       66
       66
       +
          *   query,

     

       67
       67
       +
          *   context: useMemo(() => ({

     

       68
       68
       +
          *     additionalTypenames: ['Item'],

     

       69
       69
       +
          *   }), [])

     

       70
       70
       +
          * });

     

       71
       71
       +
          * ```

     

       72
       72
       +
          */

     

       36
       73
        
         context?: Partial<OperationContext>;

     

       74
       74
       +
         /** Prevents {@link useQuery} from automatically executing GraphQL query operations.

     

       75
       75
       +
          *

     

       76
       76
       +
          * @remarks

     

       77
       77
       +
          * `pause` may be set to `true` to stop {@link useQuery} from executing

     

       78
       78
       +
          * automatically. The hook will stop receiving updates from the {@link Client}

     

       79
       79
       +
          * and won’t execute the query operation, until either it’s set to `false`

     

       80
       80
       +
          * or the {@link UseQueryExecute} function is called.

     

       81
       81
       +
          *

     

       82
       82
       +
          * @see {@link https://urql.dev/goto/docs/basics/react-preact/#pausing-usequery} for

     

       83
       83
       +
          * documentation on the `pause` option.

     

       84
       84
       +
          */

     

       37
       85
        
         pause?: boolean;

     

       38
       86
        
       } & GraphQLRequestParams<Data, Variables>;

     

       39
       87
        
       

     

       88
       88
       +
       /** State of the current query, your {@link useQuery} hook is executing.

     

       89
       89
       +
        *

     

       90
       90
       +
        * @remarks

     

       91
       91
       +
        * `UseQueryState` is returned (in a tuple) by {@link useQuery} and

     

       92
       92
       +
        * gives you the updating {@link OperationResult} of GraphQL queries.

     

       93
       93
       +
        *

     

       94
       94
       +
        * Even when the query and variables passed to {@link useQuery} change,

     

       95
       95
       +
        * this state preserves the prior state and sets the `fetching` flag to

     

       96
       96
       +
        * `true`.

     

       97
       97
       +
        * This allows you to display the previous state, while implementing

     

       98
       98
       +
        * a separate loading indicator separately.

     

       99
       99
       +
        */

     

       40
       100
        
       export interface UseQueryState<

     

       41
       101
        
         Data = any,

     

       42
       102
        
         Variables extends AnyVariables = AnyVariables

     

       43
       103
        
       > {

     

       104
       104
       +
         /** Indicates whether `useQuery` is waiting for a new result.

     

       105
       105
       +
          *

     

       106
       106
       +
          * @remarks

     

       107
       107
       +
          * When `useQuery` is passed a new query and/or variables, it will

     

       108
       108
       +
          * start executing the new query operation and `fetching` is set to

     

       109
       109
       +
          * `true` until a result arrives.

     

       110
       110
       +
          *

     

       111
       111
       +
          * Hint: This is subtly different than whether the query is actually

     

       112
       112
       +
          * fetching, and doesn’t indicate whether a query is being re-executed

     

       113
       113
       +
          * in the background. For this, see {@link UseQueryState.stale}.

     

       114
       114
       +
          */

     

       44
       115
        
         fetching: boolean;

     

       116
       116
       +
         /** Indicates that the state is not fresh and a new result will follow.

     

       117
       117
       +
          *

     

       118
       118
       +
          * @remarks

     

       119
       119
       +
          * The `stale` flag is set to `true` when a new result for the query

     

       120
       120
       +
          * is expected and `useQuery` is waiting for it. This may indicate that

     

       121
       121
       +
          * a new request is being requested in the background.

     

       122
       122
       +
          *

     

       123
       123
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       124
       124
       +
          */

     

       45
       125
        
         stale: boolean;

     

       126
       126
       +
         /** The {@link OperationResult.data} for the executed query. */

     

       46
       127
        
         data?: Data;

     

       128
       128
       +
         /** The {@link OperationResult.error} for the executed query. */

     

       47
       129
        
         error?: CombinedError;

     

       130
       130
       +
         /** The {@link OperationResult.extensions} for the executed query. */

     

       48
       131
        
         extensions?: Record<string, any>;

     

       132
       132
       +
         /** The {@link Operation} that the current state is for.

     

       133
       133
       +
          *

     

       134
       134
       +
          * @remarks

     

       135
       135
       +
          * This is the {@link Operation} that is currently being executed.

     

       136
       136
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       137
       137
       +
          * last `Operation` that the current state was for.

     

       138
       138
       +
          */

     

       49
       139
        
         operation?: Operation<Data, Variables>;

     

       50
       140
        
       }

     

       51
       141
        
       

     

       142
       142
       +
       /** Triggers {@link useQuery} to execute a new GraphQL query operation.

     

       143
       143
       +
        *

     

       144
       144
       +
        * @remarks

     

       145
       145
       +
        * When called, {@link useQuery} will re-execute the GraphQL query operation

     

       146
       146
       +
        * it currently holds, even if {@link UseQueryArgs.pause} is set to `true`.

     

       147
       147
       +
        *

     

       148
       148
       +
        * This is useful for executing a paused query or re-executing a query

     

       149
       149
       +
        * and get a new network result, by passing a new request policy.

     

       150
       150
       +
        *

     

       151
       151
       +
        * ```ts

     

       152
       152
       +
        * const [result, reexecuteQuery] = useQuery({ query });

     

       153
       153
       +
        *

     

       154
       154
       +
        * const refresh = () => {

     

       155
       155
       +
        *   // Re-execute the query with a network-only policy, skipping the cache

     

       156
       156
       +
        *   reexecuteQuery({ requestPolicy: 'network-only' });

     

       157
       157
       +
        * };

     

       158
       158
       +
        * ```

     

       159
       159
       +
        */

     

       160
       160
       +
       export type UseQueryExecute = (opts?: Partial<OperationContext>) => void;

     

       161
       161
       +
       

     

       162
       162
       +
       /** Result tuple returned by the {@link useQuery} hook.

     

       163
       163
       +
        *

     

       164
       164
       +
        * @remarks

     

       165
       165
       +
        * Similarly to a `useState` hook’s return value,

     

       166
       166
       +
        * the first element is the {@link useQuery}’s result and state,

     

       167
       167
       +
        * a {@link UseQueryState} object,

     

       168
       168
       +
        * and the second is used to imperatively re-execute the query

     

       169
       169
       +
        * via a {@link UseQueryExecute} function.

     

       170
       170
       +
        */

     

       52
       171
        
       export type UseQueryResponse<

     

       53
       172
        
         Data = any,

     

       54
       173
        
         Variables extends AnyVariables = AnyVariables

     

       55
       55
       -
       > = [

     

       56
       56
       -
         UseQueryState<Data, Variables>,

     

       57
       57
       -
         (opts?: Partial<OperationContext>) => void

     

       58
       58
       -
       ];

     

       174
       174
       +
       > = [UseQueryState<Data, Variables>, UseQueryExecute];

     

       59
       175
        
       

     

       60
       60
       -
       /** Convert the Source to a React Suspense source on demand */

     

       176
       176
       +
       /** Convert the Source to a React Suspense source on demand

     

       177
       177
       +
        * @internal

     

       178
       178
       +
        */

     

       61
       179
        
       function toSuspenseSource<T>(source: Source<T>): Source<T> {

     

       62
       180
        
         const shared = share(source);

     

       63
       181
        
         let cache: T | void;

     
···

       98
       216
        
       

     

       99
       217
        
       const sources = new Map<number, Source<OperationResult>>();

     

       100
       218
        
       

     

       219
       219
       +
       /** Hook to run a GraphQL query and get updated GraphQL results.

     

       220
       220
       +
        *

     

       221
       221
       +
        * @param args - a {@link UseQueryArgs} object, to pass a `query`, `variables`, and options.

     

       222
       222
       +
        * @returns a {@link UseQueryResponse} tuple of a {@link UseQueryState} result, and re-execute function.

     

       223
       223
       +
        *

     

       224
       224
       +
        * @remarks

     

       225
       225
       +
        * `useQuery` allows GraphQL queries to be defined and executed.

     

       226
       226
       +
        * Given {@link UseQueryArgs.query}, it executes the GraphQL query with the

     

       227
       227
       +
        * context’s {@link Client}.

     

       228
       228
       +
        *

     

       229
       229
       +
        * The returned result updates when the `Client` has new results

     

       230
       230
       +
        * for the query, and changes when your input `args` change.

     

       231
       231
       +
        *

     

       232
       232
       +
        * Additionally, if the `suspense` option is enabled on the `Client`,

     

       233
       233
       +
        * the `useQuery` hook will suspend instead of indicating that it’s

     

       234
       234
       +
        * waiting for a result via {@link UseQueryState.fetching}.

     

       235
       235
       +
        *

     

       236
       236
       +
        * @see {@link https://urql.dev/goto/docs/basics/react-preact/#queries} for `useQuery` docs.

     

       237
       237
       +
        *

     

       238
       238
       +
        * @example

     

       239
       239
       +
        * ```ts

     

       240
       240
       +
        * import { gql, useQuery } from '@urql/preact';

     

       241
       241
       +
        *

     

       242
       242
       +
        * const TodosQuery = gql`

     

       243
       243
       +
        *   query { todos { id, title } }

     

       244
       244
       +
        * `;

     

       245
       245
       +
        *

     

       246
       246
       +
        * const Todos = () => {

     

       247
       247
       +
        *   const [result, reexecuteQuery] = useQuery({

     

       248
       248
       +
        *     query: TodosQuery,

     

       249
       249
       +
        *     variables: {},

     

       250
       250
       +
        *   });

     

       251
       251
       +
        *   // ...

     

       252
       252
       +
        * };

     

       253
       253
       +
        * ```

     

       254
       254
       +
        */

     

       101
       255
        
       export function useQuery<

     

       102
       256
        
         Data = any,

     

       103
       257
        
         Variables extends AnyVariables = AnyVariables

+3 -1

packages/preact-urql/src/hooks/useRequest.ts

···

       7
       7
        
         createRequest,

     

       8
       8
        
       } from '@urql/core';

     

       9
       9
        
       

     

       10
       10
       -
       /** Creates a request from a query and variables but preserves reference equality if the key isn't changing */

     

       10
       10
       +
       /** Creates a request from a query and variables but preserves reference equality if the key isn't changing

     

       11
       11
       +
        * @internal

     

       12
       12
       +
        */

     

       11
       13
        
       export function useRequest<

     

       12
       14
        
         Data = any,

     

       13
       15
        
         Variables extends AnyVariables = AnyVariables

+175 -4

packages/preact-urql/src/hooks/useSubscription.ts

···

       14
       14
        
       import { useRequest } from './useRequest';

     

       15
       15
        
       import { initialState } from './constants';

     

       16
       16
        
       

     

       17
       17
       +
       /** Input arguments for the {@link useSubscription} hook.

     

       18
       18
       +
        *

     

       19
       19
       +
        * @param query - The GraphQL subscription document that `useSubscription` executes.

     

       20
       20
       +
        * @param variables - The variables for the GraphQL subscription that `useSubscription` executes.

     

       21
       21
       +
        */

     

       17
       22
        
       export type UseSubscriptionArgs<

     

       18
       23
        
         Variables extends AnyVariables = AnyVariables,

     

       19
       24
        
         Data = any

     

       20
       25
        
       > = {

     

       26
       26
       +
         /** Prevents {@link useSubscription} from automatically starting GraphQL subscriptions.

     

       27
       27
       +
          *

     

       28
       28
       +
          * @remarks

     

       29
       29
       +
          * `pause` may be set to `true` to stop {@link useSubscription} from starting its subscription

     

       30
       30
       +
          * automatically. The hook will stop receiving updates from the {@link Client}

     

       31
       31
       +
          * and won’t start the subscription operation, until either it’s set to `false`

     

       32
       32
       +
          * or the {@link UseSubscriptionExecute} function is called.

     

       33
       33
       +
          */

     

       21
       34
        
         pause?: boolean;

     

       35
       35
       +
         /** Updates the {@link OperationContext} for the executed GraphQL subscription operation.

     

       36
       36
       +
          *

     

       37
       37
       +
          * @remarks

     

       38
       38
       +
          * `context` may be passed to {@link useSubscription}, to update the {@link OperationContext}

     

       39
       39
       +
          * of a subscription operation. This may be used to update the `context` that exchanges

     

       40
       40
       +
          * will receive for a single hook.

     

       41
       41
       +
          *

     

       42
       42
       +
          * Hint: This should be wrapped in a `useMemo` hook, to make sure that your

     

       43
       43
       +
          * component doesn’t infinitely update.

     

       44
       44
       +
          *

     

       45
       45
       +
          * @example

     

       46
       46
       +
          * ```ts

     

       47
       47
       +
          * const [result, reexecute] = useSubscription({

     

       48
       48
       +
          *   query,

     

       49
       49
       +
          *   context: useMemo(() => ({

     

       50
       50
       +
          *     additionalTypenames: ['Item'],

     

       51
       51
       +
          *   }), [])

     

       52
       52
       +
          * });

     

       53
       53
       +
          * ```

     

       54
       54
       +
          */

     

       22
       55
        
         context?: Partial<OperationContext>;

     

       23
       56
        
       } & GraphQLRequestParams<Data, Variables>;

     

       24
       57
        
       

     

       58
       58
       +
       /** Combines previous data with an incoming subscription result’s data.

     

       59
       59
       +
        *

     

       60
       60
       +
        * @remarks

     

       61
       61
       +
        * A `SubscriptionHandler` may be passed to {@link useSubscription} to

     

       62
       62
       +
        * aggregate subscription results into a combined {@link UseSubscriptionState.data}

     

       63
       63
       +
        * value.

     

       64
       64
       +
        *

     

       65
       65
       +
        * This is useful when a subscription event delivers a single item, while

     

       66
       66
       +
        * you’d like to display a list of events.

     

       67
       67
       +
        *

     

       68
       68
       +
        * @example

     

       69
       69
       +
        * ```ts

     

       70
       70
       +
        * const NotificationsSubscription = gql`

     

       71
       71
       +
        *   subscription { newNotification { id, text } }

     

       72
       72
       +
        * `;

     

       73
       73
       +
        *

     

       74
       74
       +
        * const combineNotifications = (notifications = [], data) => {

     

       75
       75
       +
        *   return [...notifications, data.newNotification];

     

       76
       76
       +
        * };

     

       77
       77
       +
        *

     

       78
       78
       +
        * const [result, executeSubscription] = useSubscription(

     

       79
       79
       +
        *   { query: NotificationsSubscription },

     

       80
       80
       +
        *   combineNotifications,

     

       81
       81
       +
        * );

     

       82
       82
       +
        * ```

     

       83
       83
       +
        */

     

       25
       84
        
       export type SubscriptionHandler<T, R> = (prev: R | undefined, data: T) => R;

     

       26
       85
        
       

     

       86
       86
       +
       /** State of the current subscription, your {@link useSubscription} hook is executing.

     

       87
       87
       +
        *

     

       88
       88
       +
        * @remarks

     

       89
       89
       +
        * `UseSubscriptionState` is returned (in a tuple) by {@link useSubscription} and

     

       90
       90
       +
        * gives you the updating {@link OperationResult} of GraphQL subscriptions.

     

       91
       91
       +
        *

     

       92
       92
       +
        * If a {@link SubscriptionHandler} has been passed to `useSubscription` then

     

       93
       93
       +
        * {@link UseSubscriptionState.data} is instead the updated data as returned

     

       94
       94
       +
        * by the handler, otherwise it’s the latest result’s data.

     

       95
       95
       +
        *

     

       96
       96
       +
        * Hint: Even when the query and variables passed to {@link useSubscription} change,

     

       97
       97
       +
        * this state preserves the prior state.

     

       98
       98
       +
        */

     

       27
       99
        
       export interface UseSubscriptionState<

     

       28
       100
        
         Data = any,

     

       29
       101
        
         Variables extends AnyVariables = AnyVariables

     

       30
       102
        
       > {

     

       103
       103
       +
         /** Indicates whether `useSubscription`’s subscription is active.

     

       104
       104
       +
          *

     

       105
       105
       +
          * @remarks

     

       106
       106
       +
          * When `useSubscription` starts a subscription, the `fetching` flag

     

       107
       107
       +
          * is set to `true` and will remain `true` until the subscription

     

       108
       108
       +
          * completes on the API, or the {@link UseSubscriptionArgs.pause}

     

       109
       109
       +
          * flag is set to `true`.

     

       110
       110
       +
          */

     

       31
       111
        
         fetching: boolean;

     

       112
       112
       +
         /** Indicates that the subscription result is not fresh.

     

       113
       113
       +
          *

     

       114
       114
       +
          * @remarks

     

       115
       115
       +
          * This is mostly unused for subscriptions and will rarely affect you, and

     

       116
       116
       +
          * is more relevant for queries.

     

       117
       117
       +
          *

     

       118
       118
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       119
       119
       +
          */

     

       32
       120
        
         stale: boolean;

     

       121
       121
       +
         /** The {@link OperationResult.data} for the executed subscription, or data returned by a handler.

     

       122
       122
       +
          *

     

       123
       123
       +
          * @remarks

     

       124
       124
       +
          * `data` will be set to the last {@link OperationResult.data} value

     

       125
       125
       +
          * received for the subscription.

     

       126
       126
       +
          *

     

       127
       127
       +
          * It will instead be set to the values that {@link SubscriptionHandler}

     

       128
       128
       +
          * returned, if a handler has been passed to {@link useSubscription}.

     

       129
       129
       +
          */

     

       33
       130
        
         data?: Data;

     

       131
       131
       +
         /** The {@link OperationResult.error} for the executed subscription. */

     

       34
       132
        
         error?: CombinedError;

     

       133
       133
       +
         /** The {@link OperationResult.extensions} for the executed mutation. */

     

       35
       134
        
         extensions?: Record<string, any>;

     

       135
       135
       +
         /** The {@link Operation} that the current state is for.

     

       136
       136
       +
          *

     

       137
       137
       +
          * @remarks

     

       138
       138
       +
          * This is the subscription {@link Operation} that is currently active.

     

       139
       139
       +
          * When {@link UseSubscriptionState.fetching} is `true`, this is the

     

       140
       140
       +
          * last `Operation` that the current state was for.

     

       141
       141
       +
          */

     

       36
       142
        
         operation?: Operation<Data, Variables>;

     

       37
       143
        
       }

     

       38
       144
        
       

     

       145
       145
       +
       /** Triggers {@link useSubscription} to reexecute a GraphQL subscription operation.

     

       146
       146
       +
        *

     

       147
       147
       +
        * @param opts - optionally, context options that will be merged with the hook's

     

       148
       148
       +
        * {@link UseSubscriptionArgs.context} options and the `Client`’s options.

     

       149
       149
       +
        *

     

       150
       150
       +
        * @remarks

     

       151
       151
       +
        * When called, {@link useSubscription} will restart the GraphQL subscription

     

       152
       152
       +
        * operation it currently holds. If {@link UseSubscriptionArgs.pause} is set

     

       153
       153
       +
        * to `true`, it will start executing the subscription.

     

       154
       154
       +
        *

     

       155
       155
       +
        * ```ts

     

       156
       156
       +
        * const [result, executeSubscription] = useSubscription({

     

       157
       157
       +
        *   query,

     

       158
       158
       +
        *   pause: true,

     

       159
       159
       +
        * });

     

       160
       160
       +
        *

     

       161
       161
       +
        * const start = () => {

     

       162
       162
       +
        *   executeSubscription();

     

       163
       163
       +
        * };

     

       164
       164
       +
        * ```

     

       165
       165
       +
        */

     

       166
       166
       +
       export type UseSubscriptionExecute = (opts?: Partial<OperationContext>) => void;

     

       167
       167
       +
       

     

       168
       168
       +
       /** Result tuple returned by the {@link useSubscription} hook.

     

       169
       169
       +
        *

     

       170
       170
       +
        * @remarks

     

       171
       171
       +
        * Similarly to a `useState` hook’s return value,

     

       172
       172
       +
        * the first element is the {@link useSubscription}’s state,

     

       173
       173
       +
        * a {@link UseSubscriptionState} object,

     

       174
       174
       +
        * and the second is used to imperatively re-execute or start the subscription

     

       175
       175
       +
        * via a {@link UseMutationExecute} function.

     

       176
       176
       +
        */

     

       39
       177
        
       export type UseSubscriptionResponse<

     

       40
       178
        
         Data = any,

     

       41
       179
        
         Variables extends AnyVariables = AnyVariables

     

       42
       42
       -
       > = [

     

       43
       43
       -
         UseSubscriptionState<Data, Variables>,

     

       44
       44
       -
         (opts?: Partial<OperationContext>) => void

     

       45
       45
       -
       ];

     

       180
       180
       +
       > = [UseSubscriptionState<Data, Variables>, UseSubscriptionExecute];

     

       46
       181
        
       

     

       182
       182
       +
       /** Hook to run a GraphQL subscription and get updated GraphQL results.

     

       183
       183
       +
        *

     

       184
       184
       +
        * @param args - a {@link UseSubscriptionArgs} object, to pass a `query`, `variables`, and options.

     

       185
       185
       +
        * @param handler - optionally, a {@link SubscriptionHandler} function to combine multiple subscription results.

     

       186
       186
       +
        * @returns a {@link UseSubscriptionResponse} tuple of a {@link UseSubscriptionState} result, and an execute function.

     

       187
       187
       +
        *

     

       188
       188
       +
        * @remarks

     

       189
       189
       +
        * `useSubscription` allows GraphQL subscriptions to be defined and executed.

     

       190
       190
       +
        * Given {@link UseSubscriptionArgs.query}, it executes the GraphQL subscription with the

     

       191
       191
       +
        * context’s {@link Client}.

     

       192
       192
       +
        *

     

       193
       193
       +
        * The returned result updates when the `Client` has new results

     

       194
       194
       +
        * for the subscription, and `data` is updated with the result’s data

     

       195
       195
       +
        * or with the `data` that a `handler` returns.

     

       196
       196
       +
        *

     

       197
       197
       +
        * @example

     

       198
       198
       +
        * ```ts

     

       199
       199
       +
        * import { gql, useSubscription } from '@urql/preact';

     

       200
       200
       +
        *

     

       201
       201
       +
        * const NotificationsSubscription = gql`

     

       202
       202
       +
        *   subscription { newNotification { id, text } }

     

       203
       203
       +
        * `;

     

       204
       204
       +
        *

     

       205
       205
       +
        * const combineNotifications = (notifications = [], data) => {

     

       206
       206
       +
        *   return [...notifications, data.newNotification];

     

       207
       207
       +
        * };

     

       208
       208
       +
        *

     

       209
       209
       +
        * const Notifications = () => {

     

       210
       210
       +
        *   const [result, executeSubscription] = useSubscription(

     

       211
       211
       +
        *     { query: NotificationsSubscription },

     

       212
       212
       +
        *     combineNotifications,

     

       213
       213
       +
        *   );

     

       214
       214
       +
        *   // ...

     

       215
       215
       +
        * };

     

       216
       216
       +
        * ```

     

       217
       217
       +
        */

     

       47
       218
        
       export function useSubscription<

     

       48
       219
        
         Data = any,

     

       49
       220
        
         Result = Data,

+30 -12

packages/react-urql/src/components/Mutation.ts

···

       1
       1
        
       import { DocumentNode } from 'graphql';

     

       2
       2
        
       import { ReactElement } from 'react';

     

       3
       3
       -
       import {

     

       4
       4
       -
         AnyVariables,

     

       5
       5
       -
         TypedDocumentNode,

     

       6
       6
       -
         OperationResult,

     

       7
       7
       -
         OperationContext,

     

       8
       8
       -
       } from '@urql/core';

     

       9
       9
       -
       import { useMutation, UseMutationState } from '../hooks';

     

       3
       3
       +
       import { AnyVariables, TypedDocumentNode } from '@urql/core';

     

       4
       4
       +
       

     

       5
       5
       +
       import { useMutation, UseMutationState, UseMutationExecute } from '../hooks';

     

       10
       6
        
       

     

       7
       7
       +
       /** Props accepted by {@link Mutation}.

     

       8
       8
       +
        *

     

       9
       9
       +
        * @remarks

     

       10
       10
       +
        * `MutationProps` are the props accepted by the {@link Mutation} component.

     

       11
       11
       +
        *

     

       12
       12
       +
        * The result, the {@link MutationState} object, will be passed to

     

       13
       13
       +
        * a {@link MutationProps.children} function, passed as children

     

       14
       14
       +
        * to the `Mutation` component.

     

       15
       15
       +
        */

     

       11
       16
        
       export interface MutationProps<

     

       12
       17
        
         Data = any,

     

       13
       18
        
         Variables extends AnyVariables = AnyVariables

     

       14
       19
        
       > {

     

       20
       20
       +
         /* The GraphQL mutation document that {@link useMutation} will execute. */

     

       15
       21
        
         query: DocumentNode | TypedDocumentNode<Data, Variables> | string;

     

       16
       16
       -
         children: (arg: MutationState<Data, Variables>) => ReactElement<any>;

     

       22
       22
       +
         children(arg: MutationState<Data, Variables>): ReactElement<any>;

     

       17
       23
        
       }

     

       18
       24
        
       

     

       25
       25
       +
       /** Object that {@link MutationProps.children} is called with.

     

       26
       26
       +
        *

     

       27
       27
       +
        * @remarks

     

       28
       28
       +
        * This is an extented {@link UseMutationstate} with an added

     

       29
       29
       +
        * {@link MutationState.executeMutation} method, which is usually

     

       30
       30
       +
        * part of a tuple returned by {@link useMutation}.

     

       31
       31
       +
        */

     

       19
       32
        
       export interface MutationState<

     

       20
       33
        
         Data = any,

     

       21
       34
        
         Variables extends AnyVariables = AnyVariables

     

       22
       35
        
       > extends UseMutationState<Data, Variables> {

     

       23
       23
       -
         executeMutation: (

     

       24
       24
       -
           variables: Variables,

     

       25
       25
       -
           context?: Partial<OperationContext>

     

       26
       26
       -
         ) => Promise<OperationResult<Data, Variables>>;

     

       36
       36
       +
         /** Alias to {@link useMutation}’s `executeMutation` function. */

     

       37
       37
       +
         executeMutation: UseMutationExecute<Data, Variables>;

     

       27
       38
        
       }

     

       28
       39
        
       

     

       40
       40
       +
       /** Component Wrapper around {@link useMutation} to run a GraphQL query.

     

       41
       41
       +
        *

     

       42
       42
       +
        * @remarks

     

       43
       43
       +
        * `Mutation` is a component wrapper around the {@link useMutation} hook

     

       44
       44
       +
        * that calls the {@link MutationProps.children} prop, as a function,

     

       45
       45
       +
        * with the {@link MutationState} object.

     

       46
       46
       +
        */

     

       29
       47
        
       export function Mutation<

     

       30
       48
        
         Data = any,

     

       31
       49
        
         Variables extends AnyVariables = AnyVariables

+35 -4

packages/react-urql/src/components/Query.ts

···

       1
       1
        
       import { ReactElement } from 'react';

     

       2
       2
       -
       import { AnyVariables, OperationContext } from '@urql/core';

     

       3
       3
       -
       import { useQuery, UseQueryArgs, UseQueryState } from '../hooks';

     

       2
       2
       +
       import { AnyVariables } from '@urql/core';

     

       3
       3
       +
       

     

       4
       4
       +
       import {

     

       5
       5
       +
         useQuery,

     

       6
       6
       +
         UseQueryArgs,

     

       7
       7
       +
         UseQueryState,

     

       8
       8
       +
         UseQueryExecute,

     

       9
       9
       +
       } from '../hooks';

     

       4
       10
        
       

     

       11
       11
       +
       /** Props accepted by {@link Query}.

     

       12
       12
       +
        *

     

       13
       13
       +
        * @remarks

     

       14
       14
       +
        * `QueryProps` are the props accepted by the {@link Query} component,

     

       15
       15
       +
        * which is identical to {@link UseQueryArgs}.

     

       16
       16
       +
        *

     

       17
       17
       +
        * The result, the {@link QueryState} object, will be passed to

     

       18
       18
       +
        * a {@link QueryProps.children} function, passed as children

     

       19
       19
       +
        * to the `Query` component.

     

       20
       20
       +
        */

     

       5
       21
        
       export type QueryProps<

     

       6
       22
        
         Data = any,

     

       7
       23
        
         Variables extends AnyVariables = AnyVariables

     

       8
       24
        
       > = UseQueryArgs<Variables, Data> & {

     

       9
       9
       -
         children: (arg: QueryState<Data, Variables>) => ReactElement<any>;

     

       25
       25
       +
         children(arg: QueryState<Data, Variables>): ReactElement<any>;

     

       10
       26
        
       };

     

       11
       27
        
       

     

       28
       28
       +
       /** Object that {@link QueryProps.children} is called with.

     

       29
       29
       +
        *

     

       30
       30
       +
        * @remarks

     

       31
       31
       +
        * This is an extented {@link UseQueryState} with an added

     

       32
       32
       +
        * {@link QueryState.executeQuery} method, which is usually

     

       33
       33
       +
        * part of a tuple returned by {@link useQuery}.

     

       34
       34
       +
        */

     

       12
       35
        
       export interface QueryState<

     

       13
       36
        
         Data = any,

     

       14
       37
        
         Variables extends AnyVariables = AnyVariables

     

       15
       38
        
       > extends UseQueryState<Data, Variables> {

     

       16
       16
       -
         executeQuery: (opts?: Partial<OperationContext>) => void;

     

       39
       39
       +
         /** Alias to {@link useQuery}’s `executeQuery` function. */

     

       40
       40
       +
         executeQuery: UseQueryExecute;

     

       17
       41
        
       }

     

       18
       42
        
       

     

       43
       43
       +
       /** Component Wrapper around {@link useQuery} to run a GraphQL query.

     

       44
       44
       +
        *

     

       45
       45
       +
        * @remarks

     

       46
       46
       +
        * `Query` is a component wrapper around the {@link useQuery} hook

     

       47
       47
       +
        * that calls the {@link QueryProps.children} prop, as a function,

     

       48
       48
       +
        * with the {@link QueryState} object.

     

       49
       49
       +
        */

     

       19
       50
        
       export function Query<

     

       20
       51
        
         Data = any,

     

       21
       52
        
         Variables extends AnyVariables = AnyVariables

+31 -3

packages/react-urql/src/components/Subscription.ts

···

       1
       1
        
       import { ReactElement } from 'react';

     

       2
       2
       -
       import { AnyVariables, OperationContext } from '@urql/core';

     

       2
       2
       +
       import { AnyVariables } from '@urql/core';

     

       3
       3
        
       

     

       4
       4
        
       import {

     

       5
       5
        
         useSubscription,

     

       6
       6
        
         UseSubscriptionArgs,

     

       7
       7
        
         UseSubscriptionState,

     

       8
       8
       +
         UseSubscriptionExecute,

     

       8
       9
        
         SubscriptionHandler,

     

       9
       10
        
       } from '../hooks';

     

       10
       11
        
       

     

       12
       12
       +
       /** Props accepted by {@link Subscription}.

     

       13
       13
       +
        *

     

       14
       14
       +
        * @remarks

     

       15
       15
       +
        * `SubscriptionProps` are the props accepted by the {@link Subscription} component,

     

       16
       16
       +
        * which is identical to {@link UseSubscriptionArgs} with an added

     

       17
       17
       +
        * {@link SubscriptionProps.handler} prop, which {@link useSubscription} usually

     

       18
       18
       +
        * accepts as an additional argument.

     

       19
       19
       +
        *

     

       20
       20
       +
        * The result, the {@link SubscriptionState} object, will be passed to

     

       21
       21
       +
        * a {@link SubscriptionProps.children} function, passed as children

     

       22
       22
       +
        * to the `Subscription` component.

     

       23
       23
       +
        */

     

       11
       24
        
       export type SubscriptionProps<

     

       12
       25
        
         Data = any,

     

       13
       26
        
         Result = Data,

     

       14
       27
        
         Variables extends AnyVariables = AnyVariables

     

       15
       28
        
       > = UseSubscriptionArgs<Variables, Data> & {

     

       16
       29
        
         handler?: SubscriptionHandler<Data, Result>;

     

       17
       17
       -
         children: (arg: SubscriptionState<Result, Variables>) => ReactElement<any>;

     

       30
       30
       +
         children(arg: SubscriptionState<Result, Variables>): ReactElement<any>;

     

       18
       31
        
       };

     

       19
       32
        
       

     

       33
       33
       +
       /** Object that {@link SubscriptionProps.children} is called with.

     

       34
       34
       +
        *

     

       35
       35
       +
        * @remarks

     

       36
       36
       +
        * This is an extented {@link UseSubscriptionState} with an added

     

       37
       37
       +
        * {@link SubscriptionState.executeSubscription} method, which is usually

     

       38
       38
       +
        * part of a tuple returned by {@link useSubscription}.

     

       39
       39
       +
        */

     

       20
       40
        
       export interface SubscriptionState<

     

       21
       41
        
         Data = any,

     

       22
       42
        
         Variables extends AnyVariables = AnyVariables

     

       23
       43
        
       > extends UseSubscriptionState<Data, Variables> {

     

       24
       24
       -
         executeSubscription: (opts?: Partial<OperationContext>) => void;

     

       44
       44
       +
         /** Alias to {@link useSubscription}’s `executeMutation` function. */

     

       45
       45
       +
         executeSubscription: UseSubscriptionExecute;

     

       25
       46
        
       }

     

       26
       47
        
       

     

       48
       48
       +
       /** Component Wrapper around {@link useSubscription} to run a GraphQL subscription.

     

       49
       49
       +
        *

     

       50
       50
       +
        * @remarks

     

       51
       51
       +
        * `Subscription` is a component wrapper around the {@link useSubscription} hook

     

       52
       52
       +
        * that calls the {@link SubscriptionProps.children} prop, as a function,

     

       53
       53
       +
        * with the {@link SubscriptionState} object.

     

       54
       54
       +
        */

     

       27
       55
        
       export function Subscription<

     

       28
       56
        
         Data = any,

     

       29
       57
        
         Result = Data,

+53

packages/react-urql/src/context.ts

···

       2
       2
        
       import { Client } from '@urql/core';

     

       3
       3
        
       

     

       4
       4
        
       const OBJ = {};

     

       5
       5
       +
       

     

       6
       6
       +
       /** `urql`'s React Context.

     

       7
       7
       +
        *

     

       8
       8
       +
        * @remarks

     

       9
       9
       +
        * The React Context that `urql`’s {@link Client} will be provided with.

     

       10
       10
       +
        * You may use the reexported {@link Provider} to provide a `Client` as well.

     

       11
       11
       +
        */

     

       5
       12
        
       export const Context: import('react').Context<Client | object> =

     

       6
       13
        
         createContext(OBJ);

     

       14
       14
       +
       

     

       15
       15
       +
       /** Provider for `urql`'s {@link Client} to GraphQL hooks.

     

       16
       16
       +
        *

     

       17
       17
       +
        * @remarks

     

       18
       18
       +
        * `Provider` accepts a {@link Client} and provides it to all GraphQL hooks,

     

       19
       19
       +
        * and {@link useClient}.

     

       20
       20
       +
        *

     

       21
       21
       +
        * You should make sure to create a {@link Client} and provide it with the

     

       22
       22
       +
        * `Provider` to parts of your component tree that use GraphQL hooks.

     

       23
       23
       +
        *

     

       24
       24
       +
        * @example

     

       25
       25
       +
        * ```tsx

     

       26
       26
       +
        * import { Provider } from 'urql';

     

       27
       27
       +
        * // All of `@urql/core` is also re-exported by `urql`:

     

       28
       28
       +
        * import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       29
       29
       +
        *

     

       30
       30
       +
        * const client = new Client({

     

       31
       31
       +
        *   url: 'https://API',

     

       32
       32
       +
        *   exchanges: [cacheExchange, fetchExchange],

     

       33
       33
       +
        * });

     

       34
       34
       +
        *

     

       35
       35
       +
        * const App = () => (

     

       36
       36
       +
        *   <Provider value={client}>

     

       37
       37
       +
        *     <Component />

     

       38
       38
       +
        *   </Provider>

     

       39
       39
       +
        * );

     

       40
       40
       +
        * ```

     

       41
       41
       +
        */

     

       7
       42
        
       export const Provider: import('react').Provider<Client | object> =

     

       8
       43
        
         Context.Provider;

     

       44
       44
       +
       

     

       45
       45
       +
       /** React Consumer component, providing the {@link Client} provided on a parent component.

     

       46
       46
       +
        * @remarks

     

       47
       47
       +
        * This is an alias for {@link Context.Consumer}.

     

       48
       48
       +
        */

     

       9
       49
        
       export const Consumer: import('react').Consumer<Client | object> =

     

       10
       50
        
         Context.Consumer;

     

       11
       51
        
       

     

       12
       52
        
       Context.displayName = 'UrqlContext';

     

       13
       53
        
       

     

       54
       54
       +
       /** Hook returning a {@link Client} from {@link Context}.

     

       55
       55
       +
        *

     

       56
       56
       +
        * @remarks

     

       57
       57
       +
        * `useClient` is a convenience hook, which accesses `urql`'s {@link Context}

     

       58
       58
       +
        * and returns the {@link Client} defined on it.

     

       59
       59
       +
        *

     

       60
       60
       +
        * This will be the {@link Client} you passed to a {@link Provider}

     

       61
       61
       +
        * you wrapped your elements containing this hook with.

     

       62
       62
       +
        *

     

       63
       63
       +
        * @throws

     

       64
       64
       +
        * In development, if the component you call `useClient()` in is

     

       65
       65
       +
        * not wrapped in a {@link Provider}, an error is thrown.

     

       66
       66
       +
        */

     

       14
       67
        
       export const useClient = (): Client => {

     

       15
       68
        
         const client = useContext(Context);

     

       16
       69

+110 -7

packages/react-urql/src/hooks/useMutation.ts

···

       15
       15
        
       import { useClient } from '../context';

     

       16
       16
        
       import { initialState } from './state';

     

       17
       17
        
       

     

       18
       18
       +
       /** State of the last mutation executed by your {@link useMutation} hook.

     

       19
       19
       +
        *

     

       20
       20
       +
        * @remarks

     

       21
       21
       +
        * `UseMutationState` is returned (in a tuple) by {@link useMutation} and

     

       22
       22
       +
        * gives you the {@link OperationResult} of the last mutation executed

     

       23
       23
       +
        * with {@link UseMutationExecute}.

     

       24
       24
       +
        *

     

       25
       25
       +
        * Even if the mutation document passed to {@link useMutation} changes,

     

       26
       26
       +
        * the state isn’t reset, so you can keep displaying the previous result.

     

       27
       27
       +
        */

     

       18
       28
        
       export interface UseMutationState<

     

       19
       29
        
         Data = any,

     

       20
       30
        
         Variables extends AnyVariables = AnyVariables

     

       21
       31
        
       > {

     

       32
       32
       +
         /** Indicates whether `useMutation` is currently executing a mutation. */

     

       22
       33
        
         fetching: boolean;

     

       34
       34
       +
         /** Indicates that the mutation result is not fresh.

     

       35
       35
       +
          *

     

       36
       36
       +
          * @remarks

     

       37
       37
       +
          * The `stale` flag is set to `true` when a new result for the mutation

     

       38
       38
       +
          * is expected.

     

       39
       39
       +
          * This is mostly unused for mutations and will rarely affect you, and

     

       40
       40
       +
          * is more relevant for queries.

     

       41
       41
       +
          *

     

       42
       42
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       43
       43
       +
          */

     

       23
       44
        
         stale: boolean;

     

       45
       45
       +
         /** The {@link OperationResult.data} for the executed mutation. */

     

       24
       46
        
         data?: Data;

     

       47
       47
       +
         /** The {@link OperationResult.error} for the executed mutation. */

     

       25
       48
        
         error?: CombinedError;

     

       49
       49
       +
         /** The {@link OperationResult.extensions} for the executed mutation. */

     

       26
       50
        
         extensions?: Record<string, any>;

     

       51
       51
       +
         /** The {@link Operation} that the current state is for.

     

       52
       52
       +
          *

     

       53
       53
       +
          * @remarks

     

       54
       54
       +
          * This is the mutation {@link Operation} that has last been executed.

     

       55
       55
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       56
       56
       +
          * last `Operation` that the current state was for.

     

       57
       57
       +
          */

     

       27
       58
        
         operation?: Operation<Data, Variables>;

     

       28
       59
        
       }

     

       29
       60
        
       

     

       61
       61
       +
       /** Triggers {@link useMutation} to execute its GraphQL mutation operation.

     

       62
       62
       +
        *

     

       63
       63
       +
        * @param variables - variables using which the mutation will be executed.

     

       64
       64
       +
        * @param context - optionally, context options that will be merged with the hook's

     

       65
       65
       +
        * {@link UseQueryArgs.context} options and the `Client`’s options.

     

       66
       66
       +
        * @returns the {@link OperationResult} of the mutation.

     

       67
       67
       +
        *

     

       68
       68
       +
        * @remarks

     

       69
       69
       +
        * When called, {@link useMutation} will start the GraphQL mutation

     

       70
       70
       +
        * it currently holds and use the `variables` passed to it.

     

       71
       71
       +
        *

     

       72
       72
       +
        * Once the mutation response comes back from the API, its

     

       73
       73
       +
        * returned promise will resolve to the mutation’s {@link OperationResult}

     

       74
       74
       +
        * and the {@link UseMutationState} will be updated with the result.

     

       75
       75
       +
        *

     

       76
       76
       +
        * @example

     

       77
       77
       +
        * ```ts

     

       78
       78
       +
        * const [result, executeMutation] = useMutation(UpdateTodo);

     

       79
       79
       +
        * const start = async ({ id, title }) => {

     

       80
       80
       +
        *   const result = await executeMutation({ id, title });

     

       81
       81
       +
        * };

     

       82
       82
       +
        */

     

       83
       83
       +
       export type UseMutationExecute<

     

       84
       84
       +
         Data = any,

     

       85
       85
       +
         Variables extends AnyVariables = AnyVariables

     

       86
       86
       +
       > = (

     

       87
       87
       +
         variables: Variables,

     

       88
       88
       +
         context?: Partial<OperationContext>

     

       89
       89
       +
       ) => Promise<OperationResult<Data, Variables>>;

     

       90
       90
       +
       

     

       91
       91
       +
       /** Result tuple returned by the {@link useMutation} hook.

     

       92
       92
       +
        *

     

       93
       93
       +
        * @remarks

     

       94
       94
       +
        * Similarly to a `useState` hook’s return value,

     

       95
       95
       +
        * the first element is the {@link useMutation}’s state, updated

     

       96
       96
       +
        * as mutations are executed with the second value, which is

     

       97
       97
       +
        * used to start mutations and is a {@link UseMutationExecute}

     

       98
       98
       +
        * function.

     

       99
       99
       +
        */

     

       30
       100
        
       export type UseMutationResponse<

     

       31
       101
        
         Data = any,

     

       32
       102
        
         Variables extends AnyVariables = AnyVariables

     

       33
       33
       -
       > = [

     

       34
       34
       -
         UseMutationState<Data, Variables>,

     

       35
       35
       -
         (

     

       36
       36
       -
           variables: Variables,

     

       37
       37
       -
           context?: Partial<OperationContext>

     

       38
       38
       -
         ) => Promise<OperationResult<Data, Variables>>

     

       39
       39
       -
       ];

     

       103
       103
       +
       > = [UseMutationState<Data, Variables>, UseMutationExecute<Data, Variables>];

     

       40
       104
        
       

     

       105
       105
       +
       /** Hook to create a GraphQL mutation, run by passing variables to the returned execute function.

     

       106
       106
       +
        *

     

       107
       107
       +
        * @param query - a GraphQL mutation document which `useMutation` will execute.

     

       108
       108
       +
        * @returns a {@link UseMutationResponse} tuple of a {@link UseMutationState} result,

     

       109
       109
       +
        * and an execute function to start the mutation.

     

       110
       110
       +
        *

     

       111
       111
       +
        * @remarks

     

       112
       112
       +
        * `useMutation` allows GraphQL mutations to be defined and keeps its state

     

       113
       113
       +
        * after the mutation is started with the returned execute function.

     

       114
       114
       +
        *

     

       115
       115
       +
        * Given a GraphQL mutation document it returns state to keep track of the

     

       116
       116
       +
        * mutation state and a {@link UseMutationExecute} function, which accepts

     

       117
       117
       +
        * variables for the mutation to be executed.

     

       118
       118
       +
        * Once called, the mutation executes and the state will be updated with

     

       119
       119
       +
        * the mutation’s result.

     

       120
       120
       +
        *

     

       121
       121
       +
        * @see {@link https://urql.dev/goto/urql/docs/basics/react-preact/#mutations} for `useMutation` docs.

     

       122
       122
       +
        *

     

       123
       123
       +
        * @example

     

       124
       124
       +
        * ```ts

     

       125
       125
       +
        * import { gql, useMutation } from 'urql';

     

       126
       126
       +
        *

     

       127
       127
       +
        * const UpdateTodo = gql`

     

       128
       128
       +
        *   mutation ($id: ID!, $title: String!) {

     

       129
       129
       +
        *     updateTodo(id: $id, title: $title) {

     

       130
       130
       +
        *       id, title

     

       131
       131
       +
        *     }

     

       132
       132
       +
        *   }

     

       133
       133
       +
        * `;

     

       134
       134
       +
        *

     

       135
       135
       +
        * const UpdateTodo = () => {

     

       136
       136
       +
        *   const [result, executeMutation] = useMutation(UpdateTodo);

     

       137
       137
       +
        *   const start = async ({ id, title }) => {

     

       138
       138
       +
        *     const result = await executeMutation({ id, title });

     

       139
       139
       +
        *   };

     

       140
       140
       +
        *   // ...

     

       141
       141
       +
        * };

     

       142
       142
       +
        * ```

     

       143
       143
       +
        */

     

       41
       144
        
       export function useMutation<

     

       42
       145
        
         Data = any,

     

       43
       146
        
         Variables extends AnyVariables = AnyVariables

+159 -4

packages/react-urql/src/hooks/useQuery.ts

···

       19
       19
        
       import { getCacheForClient } from './cache';

     

       20
       20
        
       import { initialState, computeNextState, hasDepsChanged } from './state';

     

       21
       21
        
       

     

       22
       22
       +
       /** Input arguments for the {@link useQuery} hook.

     

       23
       23
       +
        *

     

       24
       24
       +
        * @param query - The GraphQL query that `useQuery` executes.

     

       25
       25
       +
        * @param variables - The variables for the GraphQL query that `useQuery` executes.

     

       26
       26
       +
        */

     

       22
       27
        
       export type UseQueryArgs<

     

       23
       28
        
         Variables extends AnyVariables = AnyVariables,

     

       24
       29
        
         Data = any

     

       25
       30
        
       > = {

     

       31
       31
       +
         /** Updates the {@link RequestPolicy} for the executed GraphQL query operation.

     

       32
       32
       +
          *

     

       33
       33
       +
          * @remarks

     

       34
       34
       +
          * `requestPolicy` modifies the {@link RequestPolicy} of the GraphQL query operation

     

       35
       35
       +
          * that `useQuery` executes, and indicates a caching strategy for cache exchanges.

     

       36
       36
       +
          *

     

       37
       37
       +
          * For example, when set to `'cache-and-network'`, {@link useQuery} will

     

       38
       38
       +
          * receive a cached result with `stale: true` and an API request will be

     

       39
       39
       +
          * sent in the background.

     

       40
       40
       +
          *

     

       41
       41
       +
          * @see {@link OperationContext.requestPolicy} for where this value is set.

     

       42
       42
       +
          */

     

       26
       43
        
         requestPolicy?: RequestPolicy;

     

       44
       44
       +
         /** Updates the {@link OperationContext} for the executed GraphQL query operation.

     

       45
       45
       +
          *

     

       46
       46
       +
          * @remarks

     

       47
       47
       +
          * `context` may be passed to {@link useQuery}, to update the {@link OperationContext}

     

       48
       48
       +
          * of a query operation. This may be used to update the `context` that exchanges

     

       49
       49
       +
          * will receive for a single hook.

     

       50
       50
       +
          *

     

       51
       51
       +
          * Hint: This should be wrapped in a `useMemo` hook, to make sure that your

     

       52
       52
       +
          * component doesn’t infinitely update.

     

       53
       53
       +
          *

     

       54
       54
       +
          * @example

     

       55
       55
       +
          * ```ts

     

       56
       56
       +
          * const [result, reexecute] = useQuery({

     

       57
       57
       +
          *   query,

     

       58
       58
       +
          *   context: useMemo(() => ({

     

       59
       59
       +
          *     additionalTypenames: ['Item'],

     

       60
       60
       +
          *   }), [])

     

       61
       61
       +
          * });

     

       62
       62
       +
          * ```

     

       63
       63
       +
          */

     

       27
       64
        
         context?: Partial<OperationContext>;

     

       65
       65
       +
         /** Prevents {@link useQuery} from automatically executing GraphQL query operations.

     

       66
       66
       +
          *

     

       67
       67
       +
          * @remarks

     

       68
       68
       +
          * `pause` may be set to `true` to stop {@link useQuery} from executing

     

       69
       69
       +
          * automatically. The hook will stop receiving updates from the {@link Client}

     

       70
       70
       +
          * and won’t execute the query operation, until either it’s set to `false`

     

       71
       71
       +
          * or the {@link UseQueryExecute} function is called.

     

       72
       72
       +
          *

     

       73
       73
       +
          * @see {@link https://urql.dev/goto/docs/basics/react-preact/#pausing-usequery} for

     

       74
       74
       +
          * documentation on the `pause` option.

     

       75
       75
       +
          */

     

       28
       76
        
         pause?: boolean;

     

       29
       77
        
       } & GraphQLRequestParams<Data, Variables>;

     

       30
       78
        
       

     

       79
       79
       +
       /** State of the current query, your {@link useQuery} hook is executing.

     

       80
       80
       +
        *

     

       81
       81
       +
        * @remarks

     

       82
       82
       +
        * `UseQueryState` is returned (in a tuple) by {@link useQuery} and

     

       83
       83
       +
        * gives you the updating {@link OperationResult} of GraphQL queries.

     

       84
       84
       +
        *

     

       85
       85
       +
        * Even when the query and variables passed to {@link useQuery} change,

     

       86
       86
       +
        * this state preserves the prior state and sets the `fetching` flag to

     

       87
       87
       +
        * `true`.

     

       88
       88
       +
        * This allows you to display the previous state, while implementing

     

       89
       89
       +
        * a separate loading indicator separately.

     

       90
       90
       +
        */

     

       31
       91
        
       export interface UseQueryState<

     

       32
       92
        
         Data = any,

     

       33
       93
        
         Variables extends AnyVariables = AnyVariables

     

       34
       94
        
       > {

     

       95
       95
       +
         /** Indicates whether `useQuery` is waiting for a new result.

     

       96
       96
       +
          *

     

       97
       97
       +
          * @remarks

     

       98
       98
       +
          * When `useQuery` is passed a new query and/or variables, it will

     

       99
       99
       +
          * start executing the new query operation and `fetching` is set to

     

       100
       100
       +
          * `true` until a result arrives.

     

       101
       101
       +
          *

     

       102
       102
       +
          * Hint: This is subtly different than whether the query is actually

     

       103
       103
       +
          * fetching, and doesn’t indicate whether a query is being re-executed

     

       104
       104
       +
          * in the background. For this, see {@link UseQueryState.stale}.

     

       105
       105
       +
          */

     

       35
       106
        
         fetching: boolean;

     

       107
       107
       +
         /** Indicates that the state is not fresh and a new result will follow.

     

       108
       108
       +
          *

     

       109
       109
       +
          * @remarks

     

       110
       110
       +
          * The `stale` flag is set to `true` when a new result for the query

     

       111
       111
       +
          * is expected and `useQuery` is waiting for it. This may indicate that

     

       112
       112
       +
          * a new request is being requested in the background.

     

       113
       113
       +
          *

     

       114
       114
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       115
       115
       +
          */

     

       36
       116
        
         stale: boolean;

     

       117
       117
       +
         /** The {@link OperationResult.data} for the executed query. */

     

       37
       118
        
         data?: Data;

     

       119
       119
       +
         /** The {@link OperationResult.error} for the executed query. */

     

       38
       120
        
         error?: CombinedError;

     

       121
       121
       +
         /** The {@link OperationResult.extensions} for the executed query. */

     

       39
       122
        
         extensions?: Record<string, any>;

     

       123
       123
       +
         /** The {@link Operation} that the current state is for.

     

       124
       124
       +
          *

     

       125
       125
       +
          * @remarks

     

       126
       126
       +
          * This is the {@link Operation} that is currently being executed.

     

       127
       127
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       128
       128
       +
          * last `Operation` that the current state was for.

     

       129
       129
       +
          */

     

       40
       130
        
         operation?: Operation<Data, Variables>;

     

       41
       131
        
       }

     

       42
       132
        
       

     

       133
       133
       +
       /** Triggers {@link useQuery} to execute a new GraphQL query operation.

     

       134
       134
       +
        *

     

       135
       135
       +
        * @param opts - optionally, context options that will be merged with the hook's

     

       136
       136
       +
        * {@link UseQueryArgs.context} options and the `Client`’s options.

     

       137
       137
       +
        *

     

       138
       138
       +
        * @remarks

     

       139
       139
       +
        * When called, {@link useQuery} will re-execute the GraphQL query operation

     

       140
       140
       +
        * it currently holds, even if {@link UseQueryArgs.pause} is set to `true`.

     

       141
       141
       +
        *

     

       142
       142
       +
        * This is useful for executing a paused query or re-executing a query

     

       143
       143
       +
        * and get a new network result, by passing a new request policy.

     

       144
       144
       +
        *

     

       145
       145
       +
        * ```ts

     

       146
       146
       +
        * const [result, reexecuteQuery] = useQuery({ query });

     

       147
       147
       +
        *

     

       148
       148
       +
        * const refresh = () => {

     

       149
       149
       +
        *   // Re-execute the query with a network-only policy, skipping the cache

     

       150
       150
       +
        *   reexecuteQuery({ requestPolicy: 'network-only' });

     

       151
       151
       +
        * };

     

       152
       152
       +
        * ```

     

       153
       153
       +
        */

     

       154
       154
       +
       export type UseQueryExecute = (opts?: Partial<OperationContext>) => void;

     

       155
       155
       +
       

     

       156
       156
       +
       /** Result tuple returned by the {@link useQuery} hook.

     

       157
       157
       +
        *

     

       158
       158
       +
        * @remarks

     

       159
       159
       +
        * Similarly to a `useState` hook’s return value,

     

       160
       160
       +
        * the first element is the {@link useQuery}’s result and state,

     

       161
       161
       +
        * a {@link UseQueryState} object,

     

       162
       162
       +
        * and the second is used to imperatively re-execute the query

     

       163
       163
       +
        * via a {@link UseQueryExecute} function.

     

       164
       164
       +
        */

     

       43
       165
        
       export type UseQueryResponse<

     

       44
       166
        
         Data = any,

     

       45
       167
        
         Variables extends AnyVariables = AnyVariables

     

       46
       46
       -
       > = [

     

       47
       47
       -
         UseQueryState<Data, Variables>,

     

       48
       48
       -
         (opts?: Partial<OperationContext>) => void

     

       49
       49
       -
       ];

     

       168
       168
       +
       > = [UseQueryState<Data, Variables>, UseQueryExecute];

     

       50
       169
        
       

     

       51
       170
        
       const isSuspense = (client: Client, context?: Partial<OperationContext>) =>

     

       52
       171
        
         client.suspense && (!context || context.suspense !== false);

     

       53
       172
        
       

     

       173
       173
       +
       /** Hook to run a GraphQL query and get updated GraphQL results.

     

       174
       174
       +
        *

     

       175
       175
       +
        * @param args - a {@link UseQueryArgs} object, to pass a `query`, `variables`, and options.

     

       176
       176
       +
        * @returns a {@link UseQueryResponse} tuple of a {@link UseQueryState} result, and re-execute function.

     

       177
       177
       +
        *

     

       178
       178
       +
        * @remarks

     

       179
       179
       +
        * `useQuery` allows GraphQL queries to be defined and executed.

     

       180
       180
       +
        * Given {@link UseQueryArgs.query}, it executes the GraphQL query with the

     

       181
       181
       +
        * context’s {@link Client}.

     

       182
       182
       +
        *

     

       183
       183
       +
        * The returned result updates when the `Client` has new results

     

       184
       184
       +
        * for the query, and changes when your input `args` change.

     

       185
       185
       +
        *

     

       186
       186
       +
        * Additionally, if the `suspense` option is enabled on the `Client`,

     

       187
       187
       +
        * the `useQuery` hook will suspend instead of indicating that it’s

     

       188
       188
       +
        * waiting for a result via {@link UseQueryState.fetching}.

     

       189
       189
       +
        *

     

       190
       190
       +
        * @see {@link https://urql.dev/goto/urql/docs/basics/react-preact/#queries} for `useQuery` docs.

     

       191
       191
       +
        *

     

       192
       192
       +
        * @example

     

       193
       193
       +
        * ```ts

     

       194
       194
       +
        * import { gql, useQuery } from 'urql';

     

       195
       195
       +
        *

     

       196
       196
       +
        * const TodosQuery = gql`

     

       197
       197
       +
        *   query { todos { id, title } }

     

       198
       198
       +
        * `;

     

       199
       199
       +
        *

     

       200
       200
       +
        * const Todos = () => {

     

       201
       201
       +
        *   const [result, reexecuteQuery] = useQuery({

     

       202
       202
       +
        *     query: TodosQuery,

     

       203
       203
       +
        *     variables: {},

     

       204
       204
       +
        *   });

     

       205
       205
       +
        *   // ...

     

       206
       206
       +
        * };

     

       207
       207
       +
        * ```

     

       208
       208
       +
        */

     

       54
       209
        
       export function useQuery<

     

       55
       210
        
         Data = any,

     

       56
       211
        
         Variables extends AnyVariables = AnyVariables

+3 -1

packages/react-urql/src/hooks/useRequest.ts

···

       7
       7
        
         createRequest,

     

       8
       8
        
       } from '@urql/core';

     

       9
       9
        
       

     

       10
       10
       -
       /** Creates a request from a query and variables but preserves reference equality if the key isn't changing */

     

       10
       10
       +
       /** Creates a request from a query and variables but preserves reference equality if the key isn't changing

     

       11
       11
       +
        * @internal

     

       12
       12
       +
        */

     

       11
       13
        
       export function useRequest<

     

       12
       14
        
         Data = any,

     

       13
       15
        
         Variables extends AnyVariables = AnyVariables

+175 -4

packages/react-urql/src/hooks/useSubscription.ts

···

       15
       15
        
       import { useRequest } from './useRequest';

     

       16
       16
        
       import { initialState, computeNextState, hasDepsChanged } from './state';

     

       17
       17
        
       

     

       18
       18
       +
       /** Input arguments for the {@link useSubscription} hook.

     

       19
       19
       +
        *

     

       20
       20
       +
        * @param query - The GraphQL subscription document that `useSubscription` executes.

     

       21
       21
       +
        * @param variables - The variables for the GraphQL subscription that `useSubscription` executes.

     

       22
       22
       +
        */

     

       18
       23
        
       export type UseSubscriptionArgs<

     

       19
       24
        
         Variables extends AnyVariables = AnyVariables,

     

       20
       25
        
         Data = any

     

       21
       26
        
       > = {

     

       27
       27
       +
         /** Prevents {@link useSubscription} from automatically starting GraphQL subscriptions.

     

       28
       28
       +
          *

     

       29
       29
       +
          * @remarks

     

       30
       30
       +
          * `pause` may be set to `true` to stop {@link useSubscription} from starting its subscription

     

       31
       31
       +
          * automatically. The hook will stop receiving updates from the {@link Client}

     

       32
       32
       +
          * and won’t start the subscription operation, until either it’s set to `false`

     

       33
       33
       +
          * or the {@link UseSubscriptionExecute} function is called.

     

       34
       34
       +
          */

     

       22
       35
        
         pause?: boolean;

     

       36
       36
       +
         /** Updates the {@link OperationContext} for the executed GraphQL subscription operation.

     

       37
       37
       +
          *

     

       38
       38
       +
          * @remarks

     

       39
       39
       +
          * `context` may be passed to {@link useSubscription}, to update the {@link OperationContext}

     

       40
       40
       +
          * of a subscription operation. This may be used to update the `context` that exchanges

     

       41
       41
       +
          * will receive for a single hook.

     

       42
       42
       +
          *

     

       43
       43
       +
          * Hint: This should be wrapped in a `useMemo` hook, to make sure that your

     

       44
       44
       +
          * component doesn’t infinitely update.

     

       45
       45
       +
          *

     

       46
       46
       +
          * @example

     

       47
       47
       +
          * ```ts

     

       48
       48
       +
          * const [result, reexecute] = useSubscription({

     

       49
       49
       +
          *   query,

     

       50
       50
       +
          *   context: useMemo(() => ({

     

       51
       51
       +
          *     additionalTypenames: ['Item'],

     

       52
       52
       +
          *   }), [])

     

       53
       53
       +
          * });

     

       54
       54
       +
          * ```

     

       55
       55
       +
          */

     

       23
       56
        
         context?: Partial<OperationContext>;

     

       24
       57
        
       } & GraphQLRequestParams<Data, Variables>;

     

       25
       58
        
       

     

       59
       59
       +
       /** Combines previous data with an incoming subscription result’s data.

     

       60
       60
       +
        *

     

       61
       61
       +
        * @remarks

     

       62
       62
       +
        * A `SubscriptionHandler` may be passed to {@link useSubscription} to

     

       63
       63
       +
        * aggregate subscription results into a combined {@link UseSubscriptionState.data}

     

       64
       64
       +
        * value.

     

       65
       65
       +
        *

     

       66
       66
       +
        * This is useful when a subscription event delivers a single item, while

     

       67
       67
       +
        * you’d like to display a list of events.

     

       68
       68
       +
        *

     

       69
       69
       +
        * @example

     

       70
       70
       +
        * ```ts

     

       71
       71
       +
        * const NotificationsSubscription = gql`

     

       72
       72
       +
        *   subscription { newNotification { id, text } }

     

       73
       73
       +
        * `;

     

       74
       74
       +
        *

     

       75
       75
       +
        * const combineNotifications = (notifications = [], data) => {

     

       76
       76
       +
        *   return [...notifications, data.newNotification];

     

       77
       77
       +
        * };

     

       78
       78
       +
        *

     

       79
       79
       +
        * const [result, executeSubscription] = useSubscription(

     

       80
       80
       +
        *   { query: NotificationsSubscription },

     

       81
       81
       +
        *   combineNotifications,

     

       82
       82
       +
        * );

     

       83
       83
       +
        * ```

     

       84
       84
       +
        */

     

       26
       85
        
       export type SubscriptionHandler<T, R> = (prev: R | undefined, data: T) => R;

     

       27
       86
        
       

     

       87
       87
       +
       /** State of the current subscription, your {@link useSubscription} hook is executing.

     

       88
       88
       +
        *

     

       89
       89
       +
        * @remarks

     

       90
       90
       +
        * `UseSubscriptionState` is returned (in a tuple) by {@link useSubscription} and

     

       91
       91
       +
        * gives you the updating {@link OperationResult} of GraphQL subscriptions.

     

       92
       92
       +
        *

     

       93
       93
       +
        * If a {@link SubscriptionHandler} has been passed to `useSubscription` then

     

       94
       94
       +
        * {@link UseSubscriptionState.data} is instead the updated data as returned

     

       95
       95
       +
        * by the handler, otherwise it’s the latest result’s data.

     

       96
       96
       +
        *

     

       97
       97
       +
        * Hint: Even when the query and variables passed to {@link useSubscription} change,

     

       98
       98
       +
        * this state preserves the prior state.

     

       99
       99
       +
        */

     

       28
       100
        
       export interface UseSubscriptionState<

     

       29
       101
        
         Data = any,

     

       30
       102
        
         Variables extends AnyVariables = AnyVariables

     

       31
       103
        
       > {

     

       104
       104
       +
         /** Indicates whether `useSubscription`’s subscription is active.

     

       105
       105
       +
          *

     

       106
       106
       +
          * @remarks

     

       107
       107
       +
          * When `useSubscription` starts a subscription, the `fetching` flag

     

       108
       108
       +
          * is set to `true` and will remain `true` until the subscription

     

       109
       109
       +
          * completes on the API, or the {@link UseSubscriptionArgs.pause}

     

       110
       110
       +
          * flag is set to `true`.

     

       111
       111
       +
          */

     

       32
       112
        
         fetching: boolean;

     

       113
       113
       +
         /** Indicates that the subscription result is not fresh.

     

       114
       114
       +
          *

     

       115
       115
       +
          * @remarks

     

       116
       116
       +
          * This is mostly unused for subscriptions and will rarely affect you, and

     

       117
       117
       +
          * is more relevant for queries.

     

       118
       118
       +
          *

     

       119
       119
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       120
       120
       +
          */

     

       33
       121
        
         stale: boolean;

     

       122
       122
       +
         /** The {@link OperationResult.data} for the executed subscription, or data returned by a handler.

     

       123
       123
       +
          *

     

       124
       124
       +
          * @remarks

     

       125
       125
       +
          * `data` will be set to the last {@link OperationResult.data} value

     

       126
       126
       +
          * received for the subscription.

     

       127
       127
       +
          *

     

       128
       128
       +
          * It will instead be set to the values that {@link SubscriptionHandler}

     

       129
       129
       +
          * returned, if a handler has been passed to {@link useSubscription}.

     

       130
       130
       +
          */

     

       34
       131
        
         data?: Data;

     

       132
       132
       +
         /** The {@link OperationResult.error} for the executed subscription. */

     

       35
       133
        
         error?: CombinedError;

     

       134
       134
       +
         /** The {@link OperationResult.extensions} for the executed mutation. */

     

       36
       135
        
         extensions?: Record<string, any>;

     

       136
       136
       +
         /** The {@link Operation} that the current state is for.

     

       137
       137
       +
          *

     

       138
       138
       +
          * @remarks

     

       139
       139
       +
          * This is the subscription {@link Operation} that is currently active.

     

       140
       140
       +
          * When {@link UseSubscriptionState.fetching} is `true`, this is the

     

       141
       141
       +
          * last `Operation` that the current state was for.

     

       142
       142
       +
          */

     

       37
       143
        
         operation?: Operation<Data, Variables>;

     

       38
       144
        
       }

     

       39
       145
        
       

     

       146
       146
       +
       /** Triggers {@link useSubscription} to reexecute a GraphQL subscription operation.

     

       147
       147
       +
        *

     

       148
       148
       +
        * @param opts - optionally, context options that will be merged with the hook's

     

       149
       149
       +
        * {@link UseSubscriptionArgs.context} options and the `Client`’s options.

     

       150
       150
       +
        *

     

       151
       151
       +
        * @remarks

     

       152
       152
       +
        * When called, {@link useSubscription} will restart the GraphQL subscription

     

       153
       153
       +
        * operation it currently holds. If {@link UseSubscriptionArgs.pause} is set

     

       154
       154
       +
        * to `true`, it will start executing the subscription.

     

       155
       155
       +
        *

     

       156
       156
       +
        * ```ts

     

       157
       157
       +
        * const [result, executeSubscription] = useSubscription({

     

       158
       158
       +
        *   query,

     

       159
       159
       +
        *   pause: true,

     

       160
       160
       +
        * });

     

       161
       161
       +
        *

     

       162
       162
       +
        * const start = () => {

     

       163
       163
       +
        *   executeSubscription();

     

       164
       164
       +
        * };

     

       165
       165
       +
        * ```

     

       166
       166
       +
        */

     

       167
       167
       +
       export type UseSubscriptionExecute = (opts?: Partial<OperationContext>) => void;

     

       168
       168
       +
       

     

       169
       169
       +
       /** Result tuple returned by the {@link useSubscription} hook.

     

       170
       170
       +
        *

     

       171
       171
       +
        * @remarks

     

       172
       172
       +
        * Similarly to a `useState` hook’s return value,

     

       173
       173
       +
        * the first element is the {@link useSubscription}’s state,

     

       174
       174
       +
        * a {@link UseSubscriptionState} object,

     

       175
       175
       +
        * and the second is used to imperatively re-execute or start the subscription

     

       176
       176
       +
        * via a {@link UseMutationExecute} function.

     

       177
       177
       +
        */

     

       40
       178
        
       export type UseSubscriptionResponse<

     

       41
       179
        
         Data = any,

     

       42
       180
        
         Variables extends AnyVariables = AnyVariables

     

       43
       43
       -
       > = [

     

       44
       44
       -
         UseSubscriptionState<Data, Variables>,

     

       45
       45
       -
         (opts?: Partial<OperationContext>) => void

     

       46
       46
       -
       ];

     

       181
       181
       +
       > = [UseSubscriptionState<Data, Variables>, UseSubscriptionExecute];

     

       47
       182
        
       

     

       183
       183
       +
       /** Hook to run a GraphQL subscription and get updated GraphQL results.

     

       184
       184
       +
        *

     

       185
       185
       +
        * @param args - a {@link UseSubscriptionArgs} object, to pass a `query`, `variables`, and options.

     

       186
       186
       +
        * @param handler - optionally, a {@link SubscriptionHandler} function to combine multiple subscription results.

     

       187
       187
       +
        * @returns a {@link UseSubscriptionResponse} tuple of a {@link UseSubscriptionState} result, and an execute function.

     

       188
       188
       +
        *

     

       189
       189
       +
        * @remarks

     

       190
       190
       +
        * `useSubscription` allows GraphQL subscriptions to be defined and executed.

     

       191
       191
       +
        * Given {@link UseSubscriptionArgs.query}, it executes the GraphQL subscription with the

     

       192
       192
       +
        * context’s {@link Client}.

     

       193
       193
       +
        *

     

       194
       194
       +
        * The returned result updates when the `Client` has new results

     

       195
       195
       +
        * for the subscription, and `data` is updated with the result’s data

     

       196
       196
       +
        * or with the `data` that a `handler` returns.

     

       197
       197
       +
        *

     

       198
       198
       +
        * @example

     

       199
       199
       +
        * ```ts

     

       200
       200
       +
        * import { gql, useSubscription } from 'urql';

     

       201
       201
       +
        *

     

       202
       202
       +
        * const NotificationsSubscription = gql`

     

       203
       203
       +
        *   subscription { newNotification { id, text } }

     

       204
       204
       +
        * `;

     

       205
       205
       +
        *

     

       206
       206
       +
        * const combineNotifications = (notifications = [], data) => {

     

       207
       207
       +
        *   return [...notifications, data.newNotification];

     

       208
       208
       +
        * };

     

       209
       209
       +
        *

     

       210
       210
       +
        * const Notifications = () => {

     

       211
       211
       +
        *   const [result, executeSubscription] = useSubscription(

     

       212
       212
       +
        *     { query: NotificationsSubscription },

     

       213
       213
       +
        *     combineNotifications,

     

       214
       214
       +
        *   );

     

       215
       215
       +
        *   // ...

     

       216
       216
       +
        * };

     

       217
       217
       +
        * ```

     

       218
       218
       +
        */

     

       48
       219
        
       export function useSubscription<

     

       49
       220
        
         Data = any,

     

       50
       221
        
         Result = Data,

+27 -3

packages/storage-rn/src/makeAsyncStorage.ts

···

       2
       2
        
       import AsyncStorage from '@react-native-async-storage/async-storage';

     

       3
       3
        
       import NetInfo from '@react-native-community/netinfo';

     

       4
       4
        
       

     

       5
       5
       -
       export type StorageOptions = {

     

       5
       5
       +
       export interface StorageOptions {

     

       6
       6
       +
         /** Name of the `AsyncStorage` key that’s used for persisted data.

     

       7
       7
       +
          * @defaultValue `'graphcache-data'`

     

       8
       8
       +
          */

     

       6
       9
        
         dataKey?: string;

     

       10
       10
       +
         /** Name of the `AsyncStorage` key that’s used for persisted metadata.

     

       11
       11
       +
          * @defaultValue `'graphcache-metadata'`

     

       12
       12
       +
          */

     

       7
       13
        
         metadataKey?: string;

     

       8
       8
       -
         maxAge?: number; // Number of days

     

       9
       9
       -
       };

     

       14
       14
       +
         /** Maximum age of cache entries (in days) after which data is discarded.

     

       15
       15
       +
          * @defaultValue `7` days

     

       16
       16
       +
          */

     

       17
       17
       +
         maxAge?: number;

     

       18
       18
       +
       }

     

       10
       19
        
       

     

       11
       20
        
       const parseData = (persistedData: any, fallback: any) => {

     

       12
       21
        
         try {

     
···

       20
       29
        
       

     

       21
       30
        
       let disconnect;

     

       22
       31
        
       

     

       32
       32
       +
       /** React Native storage adapter persisting to `AsyncStorage`. */

     

       23
       33
        
       export interface DefaultAsyncStorage extends StorageAdapter {

     

       34
       34
       +
         /** Clears the entire `AsyncStorage`. */

     

       24
       35
        
         clear(): Promise<any>;

     

       25
       36
        
       }

     

       26
       37
        
       

     

       38
       38
       +
       /** Creates a {@link StorageAdapter} which uses React Native’s `AsyncStorage`.

     

       39
       39
       +
        *

     

       40
       40
       +
        * @param opts - A {@link StorageOptions} configuration object.

     

       41
       41
       +
        * @returns the created {@link DefaultAsyncStorage} adapter.

     

       42
       42
       +
        *

     

       43
       43
       +
        * @remarks

     

       44
       44
       +
        * `makeAsyncStorage` creates a storage adapter for React Native,

     

       45
       45
       +
        * which persisted to `AsyncStorage` via the `@react-native-async-storage/async-storage`

     

       46
       46
       +
        * package.

     

       47
       47
       +
        *

     

       48
       48
       +
        * Note: We have no data on stability of this storage and our Offline Support

     

       49
       49
       +
        * for large APIs or longterm use. Proceed with caution.

     

       50
       50
       +
        */

     

       27
       51
        
       export const makeAsyncStorage: (

     

       28
       52
        
         ops?: StorageOptions

     

       29
       53
        
       ) => DefaultAsyncStorage = ({

+64 -1

packages/svelte-urql/src/common.ts

···

       2
       2
        
       import type { AnyVariables, OperationResult } from '@urql/core';

     

       3
       3
        
       import { Source, make } from 'wonka';

     

       4
       4
        
       

     

       5
       5
       +
       /** An {@link OperationResult} with an added {@link OperationResultState.fetching} flag.

     

       6
       6
       +
        *

     

       7
       7
       +
        * @remarks

     

       8
       8
       +
        * Stores will contain a readable state based on {@link OperationResult | OperationResults}

     

       9
       9
       +
        * they received.

     

       10
       10
       +
        */

     

       5
       11
        
       export interface OperationResultState<

     

       6
       12
        
         Data = any,

     

       7
       13
        
         Variables extends AnyVariables = AnyVariables

     

       8
       14
        
       > extends OperationResult<Data, Variables> {

     

       15
       15
       +
         /** Indicates whether the store is waiting for a new {@link OperationResult}.

     

       16
       16
       +
          *

     

       17
       17
       +
          * @remarks

     

       18
       18
       +
          * When a store starts executing a GraphQL operation, `fetching` is

     

       19
       19
       +
          * set to `true` until a result arrives.

     

       20
       20
       +
          *

     

       21
       21
       +
          * Hint: This is subtly different than whether the operation is actually

     

       22
       22
       +
          * fetching, and doesn’t indicate whether an operation is being re-executed

     

       23
       23
       +
          * in the background. For this, see {@link OperationResult.stale}.

     

       24
       24
       +
          */

     

       9
       25
        
         fetching: boolean;

     

       10
       26
        
       }

     

       11
       27
        
       

     

       12
       12
       -
       /** A Readable containing an `OperationResult` with a fetching flag. */

     

       28
       28
       +
       /** A Readable store of {@link OperationResultState}. */

     

       13
       29
        
       export type OperationResultStore<

     

       14
       30
        
         Data = any,

     

       15
       31
        
         Variables extends AnyVariables = AnyVariables

     

       16
       32
        
       > = Readable<OperationResultState<Data, Variables>>;

     

       17
       33
        
       

     

       34
       34
       +
       /** Consumes a {@link Readable} as a {@link Source}.

     

       35
       35
       +
        * @internal

     

       36
       36
       +
        */

     

       18
       37
        
       export const fromStore = <T>(store$: Readable<T>): Source<T> =>

     

       19
       38
        
         make(observer => store$.subscribe(observer.next));

     

       20
       39
        
       

     
···

       28
       47
        
         stale: false,

     

       29
       48
        
       };

     

       30
       49
        
       

     

       50
       50
       +
       /** A pausable Svelte store.

     

       51
       51
       +
        *

     

       52
       52
       +
        * @remarks

     

       53
       53
       +
        * The {@link queryStore} and {@link useSubscription} store allow

     

       54
       54
       +
        * you to pause execution and resume it later on, which is managed

     

       55
       55
       +
        * by a `pause` option passed to them.

     

       56
       56
       +
        *

     

       57
       57
       +
        * A `Pauseable` allows execution of GraphQL operations to be paused,

     

       58
       58
       +
        * which means a {@link OperationResultStore} won’t update with new

     

       59
       59
       +
        * results or execute new operations, and to be resumed later on.

     

       60
       60
       +
        */

     

       31
       61
        
       export interface Pausable {

     

       62
       62
       +
         /** Indicates whether a store is currently paused.

     

       63
       63
       +
          *

     

       64
       64
       +
          * @remarks

     

       65
       65
       +
          * When a {@link OperationResultStore} has been paused, it will stop

     

       66
       66
       +
          * receiving updates from the {@link Client} and won’t execute GraphQL

     

       67
       67
       +
          * operations, until this writable becomes `true` or

     

       68
       68
       +
          * {@link Pausable.resume} is called.

     

       69
       69
       +
          *

     

       70
       70
       +
          * @see {@link https://urql.dev/goto/docs/basics/svelte#pausing-queries} for

     

       71
       71
       +
          * documentation on the `Pausable`.

     

       72
       72
       +
          */

     

       32
       73
        
         isPaused$: Writable<boolean>;

     

       74
       74
       +
         /** Pauses a GraphQL operation to stop it from executing.

     

       75
       75
       +
          *

     

       76
       76
       +
          * @remarks

     

       77
       77
       +
          * Pauses an {@link OperationResultStore}’s GraphQL operation, which

     

       78
       78
       +
          * stops it from receiving updates from the {@link Client} and to stop

     

       79
       79
       +
          * an ongoing operation.

     

       80
       80
       +
          *

     

       81
       81
       +
          * @see {@link https://urql.dev/goto/docs/basics/svelte#pausing-queries} for

     

       82
       82
       +
          * documentation on the `Pausable`.

     

       83
       83
       +
          */

     

       33
       84
        
         pause(): void;

     

       85
       85
       +
         /** Resumes a paused GraphQL operation if it’s currently paused.

     

       86
       86
       +
          *

     

       87
       87
       +
          * @remarks

     

       88
       88
       +
          * Resumes or starts {@link OperationResultStore}’s GraphQL operation,

     

       89
       89
       +
          * if it’s currently paused.

     

       90
       90
       +
          *

     

       91
       91
       +
          * @see {@link https://urql.dev/goto/docs/basics/svelte#pausing-queries} for

     

       92
       92
       +
          * documentation on the `Pausable`.

     

       93
       93
       +
          */

     

       34
       94
        
         resume(): void;

     

       35
       95
        
       }

     

       36
       96
        
       

     

       97
       97
       +
       /** Creates a {@link Pausable}.

     

       98
       98
       +
        * @internal

     

       99
       99
       +
        */

     

       37
       100
        
       export const createPausable = (isPaused$: Writable<boolean>): Pausable => ({

     

       38
       101
        
         isPaused$,

     

       39
       102
        
         pause() {

+32 -3

packages/svelte-urql/src/context.ts

···

       3
       3
        
       

     

       4
       4
        
       const _contextKey = '$$_urql';

     

       5
       5
        
       

     

       6
       6
       -
       /** Retrieves a Client from Svelte's context */

     

       6
       6
       +
       /** Returns a provided {@link Client}.

     

       7
       7
       +
        *

     

       8
       8
       +
        * @remarks

     

       9
       9
       +
        * `getContextClient` returns the {@link Client} that’s previously

     

       10
       10
       +
        * been provided on Svelte’s context with {@link setContextClient}.

     

       11
       11
       +
        *

     

       12
       12
       +
        * This is useful to create a `Client` on Svelte’s context once, and

     

       13
       13
       +
        * then pass it to all GraphQL store functions without importing it

     

       14
       14
       +
        * from a singleton export.

     

       15
       15
       +
        *

     

       16
       16
       +
        * @throws

     

       17
       17
       +
        * In development, if `getContextClient` can’t get a {@link Client}

     

       18
       18
       +
        * from Svelte’s context, an error will be thrown.

     

       19
       19
       +
        */

     

       7
       20
        
       export const getContextClient = (): Client => {

     

       8
       21
        
         const client = getContext(_contextKey);

     

       9
       22
        
         if (process.env.NODE_ENV !== 'production' && !client) {

     
···

       15
       28
        
         return client as Client;

     

       16
       29
        
       };

     

       17
       30
        
       

     

       18
       18
       -
       /** Sets a Client on Svelte's context */

     

       31
       31
       +
       /** Provides a {@link Client} to a component’s children.

     

       32
       32
       +
        *

     

       33
       33
       +
        * @remarks

     

       34
       34
       +
        * `setContextClient` updates the Svelte context to provide

     

       35
       35
       +
        * a {@link Client} to be later retrieved using the

     

       36
       36
       +
        * {@link getContextClient} function.

     

       37
       37
       +
        */

     

       19
       38
        
       export const setContextClient = (client: Client): void => {

     

       20
       39
        
         setContext(_contextKey, client);

     

       21
       40
        
       };

     

       22
       41
        
       

     

       23
       23
       -
       /** Creates Client and adds it to Svelte's context */

     

       42
       42
       +
       /** Creates a {@link Client} and provides it to a component’s children.

     

       43
       43
       +
        *

     

       44
       44
       +
        * @param args - a {@link ClientOptions} object to create a `Client` with.

     

       45
       45
       +
        * @returns the created {@link Client}.

     

       46
       46
       +
        *

     

       47
       47
       +
        * @remarks

     

       48
       48
       +
        * `initContextClient` is a convenience wrapper around

     

       49
       49
       +
        * `setContextClient` that accepts {@link ClientOptions},

     

       50
       50
       +
        * creates a {@link Client} and provides it to be later

     

       51
       51
       +
        * retrieved using the {@link getContextClient} function.

     

       52
       52
       +
        */

     

       24
       53
        
       export const initContextClient = (args: ClientOptions): Client => {

     

       25
       54
        
         const client = new Client(args);

     

       26
       55
        
         setContextClient(client);

packages/svelte-urql/src/index.ts

···

       1
       1
        
       export * from '@urql/core';

     

       2
       2
       +
       

     

       3
       3
       +
       export type {

     

       4
       4
       +
         Pausable,

     

       5
       5
       +
         OperationResultStore,

     

       6
       6
       +
         OperationResultState,

     

       7
       7
       +
       } from './common';

     

       8
       8
       +
       

     

       2
       9
        
       export * from './queryStore';

     

       3
       10
        
       export * from './mutationStore';

     

       4
       11
        
       export * from './subscriptionStore';

+67

packages/svelte-urql/src/mutationStore.ts

···

       15
       15
        
         initialResult,

     

       16
       16
        
       } from './common';

     

       17
       17
        
       

     

       18
       18
       +
       /** Input arguments for the {@link mutationStore} function.

     

       19
       19
       +
        *

     

       20
       20
       +
        * @param query - The GraphQL mutation that the `mutationStore` executes.

     

       21
       21
       +
        * @param variables - The variables for the GraphQL mutation that `mutationStore` executes.

     

       22
       22
       +
        */

     

       18
       23
        
       export type MutationArgs<

     

       19
       24
        
         Data = any,

     

       20
       25
        
         Variables extends AnyVariables = AnyVariables

     

       21
       26
        
       > = {

     

       27
       27
       +
         /** The {@link Client} using which the subscription will be started.

     

       28
       28
       +
          *

     

       29
       29
       +
          * @remarks

     

       30
       30
       +
          * If you’ve previously provided a {@link Client} on Svelte’s context

     

       31
       31
       +
          * this can be set to {@link getContextClient}’s return value.

     

       32
       32
       +
          */

     

       22
       33
        
         client: Client;

     

       34
       34
       +
         /** Updates the {@link OperationContext} for the GraphQL mutation operation.

     

       35
       35
       +
          *

     

       36
       36
       +
          * @remarks

     

       37
       37
       +
          * `context` may be passed to {@link mutationStore}, to update the

     

       38
       38
       +
          * {@link OperationContext} of a mutation operation. This may be used to update

     

       39
       39
       +
          * the `context` that exchanges will receive for a single hook.

     

       40
       40
       +
          *

     

       41
       41
       +
          * @example

     

       42
       42
       +
          * ```ts

     

       43
       43
       +
          * mutationStore({

     

       44
       44
       +
          *   query,

     

       45
       45
       +
          *   context: {

     

       46
       46
       +
          *     additionalTypenames: ['Item'],

     

       47
       47
       +
          *   },

     

       48
       48
       +
          * });

     

       49
       49
       +
          * ```

     

       50
       50
       +
          */

     

       23
       51
        
         context?: Partial<OperationContext>;

     

       24
       52
        
       } & GraphQLRequestParams<Data, Variables>;

     

       25
       53
        
       

     

       54
       54
       +
       /** Function to create a `mutationStore` that runs a GraphQL mutation and updates with a GraphQL result.

     

       55
       55
       +
        *

     

       56
       56
       +
        * @param args - a {@link MutationArgs} object, to pass a `query`, `variables`, and options.

     

       57
       57
       +
        * @returns a {@link OperationResultStore} of the mutation’s result.

     

       58
       58
       +
        *

     

       59
       59
       +
        * @remarks

     

       60
       60
       +
        * `mutationStore` allows a GraphQL mutation to be defined as a Svelte store.

     

       61
       61
       +
        * Given {@link MutationArgs.query}, it executes the GraphQL mutation on the

     

       62
       62
       +
        * {@link MutationArgs.client}.

     

       63
       63
       +
        *

     

       64
       64
       +
        * The returned store updates with an {@link OperationResult} when

     

       65
       65
       +
        * the `Client` returns a result for the mutation.

     

       66
       66
       +
        *

     

       67
       67
       +
        * Hint: It’s often easier to use {@link Client.mutation} if you’re

     

       68
       68
       +
        * creating a mutation imperatively and don’t need a store.

     

       69
       69
       +
        *

     

       70
       70
       +
        * @see {@link https://urql.dev/goto/docs/basics/svelte#mutations} for

     

       71
       71
       +
        * `mutationStore` docs.

     

       72
       72
       +
        *

     

       73
       73
       +
        * @example

     

       74
       74
       +
        * ```ts

     

       75
       75
       +
        * import { mutationStore, gql, getContextClient } from '@urql/svelte';

     

       76
       76
       +
        *

     

       77
       77
       +
        * const client = getContextClient();

     

       78
       78
       +
        *

     

       79
       79
       +
        * let result;

     

       80
       80
       +
        * function updateTodo({ id, title }) {

     

       81
       81
       +
        *   result = queryStore({

     

       82
       82
       +
        *     client,

     

       83
       83
       +
        *     query: gql`

     

       84
       84
       +
        *       mutation($id: ID!, $title: String!) {

     

       85
       85
       +
        *         updateTodo(id: $id, title: $title) { id, title }

     

       86
       86
       +
        *       }

     

       87
       87
       +
        *     `,

     

       88
       88
       +
        *     variables: { id, title },

     

       89
       89
       +
        *   });

     

       90
       90
       +
        * }

     

       91
       91
       +
        * ```

     

       92
       92
       +
        */

     

       26
       93
        
       export function mutationStore<

     

       27
       94
        
         Data = any,

     

       28
       95
        
         Variables extends AnyVariables = AnyVariables

+76

packages/svelte-urql/src/queryStore.ts

···

       30
       30
        
         fromStore,

     

       31
       31
        
       } from './common';

     

       32
       32
        
       

     

       33
       33
       +
       /** Input arguments for the {@link queryStore} function.

     

       34
       34
       +
        *

     

       35
       35
       +
        * @param query - The GraphQL query that the `queryStore` executes.

     

       36
       36
       +
        * @param variables - The variables for the GraphQL query that `queryStore` executes.

     

       37
       37
       +
        */

     

       33
       38
        
       export type QueryArgs<

     

       34
       39
        
         Data = any,

     

       35
       40
        
         Variables extends AnyVariables = AnyVariables

     

       36
       41
        
       > = {

     

       42
       42
       +
         /** The {@link Client} using which the query will be executed.

     

       43
       43
       +
          *

     

       44
       44
       +
          * @remarks

     

       45
       45
       +
          * If you’ve previously provided a {@link Client} on Svelte’s context

     

       46
       46
       +
          * this can be set to {@link getContextClient}’s return value.

     

       47
       47
       +
          */

     

       37
       48
        
         client: Client;

     

       49
       49
       +
         /** Updates the {@link OperationContext} for the executed GraphQL query operation.

     

       50
       50
       +
          *

     

       51
       51
       +
          * @remarks

     

       52
       52
       +
          * `context` may be passed to {@link queryStore}, to update the {@link OperationContext}

     

       53
       53
       +
          * of a query operation. This may be used to update the `context` that exchanges

     

       54
       54
       +
          * will receive for a single hook.

     

       55
       55
       +
          *

     

       56
       56
       +
          * @example

     

       57
       57
       +
          * ```ts

     

       58
       58
       +
          * queryStore({

     

       59
       59
       +
          *   query,

     

       60
       60
       +
          *   context: {

     

       61
       61
       +
          *     additionalTypenames: ['Item'],

     

       62
       62
       +
          *   },

     

       63
       63
       +
          * });

     

       64
       64
       +
          * ```

     

       65
       65
       +
          */

     

       38
       66
        
         context?: Partial<OperationContext>;

     

       67
       67
       +
         /** Sets the {@link RequestPolicy} for the executed GraphQL query operation.

     

       68
       68
       +
          *

     

       69
       69
       +
          * @remarks

     

       70
       70
       +
          * `requestPolicy` modifies the {@link RequestPolicy} of the GraphQL query operation

     

       71
       71
       +
          * that the {@link queryStore} executes, and indicates a caching strategy for cache exchanges.

     

       72
       72
       +
          *

     

       73
       73
       +
          * For example, when set to `'cache-and-network'`, the `queryStore` will

     

       74
       74
       +
          * receive a cached result with `stale: true` and an API request will be

     

       75
       75
       +
          * sent in the background.

     

       76
       76
       +
          *

     

       77
       77
       +
          * @see {@link OperationContext.requestPolicy} for where this value is set.

     

       78
       78
       +
          */

     

       39
       79
        
         requestPolicy?: RequestPolicy;

     

       80
       80
       +
         /** Prevents the {@link queryStore} from automatically executing GraphQL query operations.

     

       81
       81
       +
          *

     

       82
       82
       +
          * @remarks

     

       83
       83
       +
          * `pause` may be set to `true` to stop the {@link queryStore} from executing

     

       84
       84
       +
          * automatically. The store will stop receiving updates from the {@link Client}

     

       85
       85
       +
          * and won’t execute the query operation, until either it’s set to `false`

     

       86
       86
       +
          * or {@link Pausable.resume} is called.

     

       87
       87
       +
          *

     

       88
       88
       +
          * @see {@link https://urql.dev/goto/docs/basics/svelte#pausing-queries} for

     

       89
       89
       +
          * documentation on the `pause` option.

     

       90
       90
       +
          */

     

       40
       91
        
         pause?: boolean;

     

       41
       92
        
       } & GraphQLRequestParams<Data, Variables>;

     

       42
       93
        
       

     

       94
       94
       +
       /** Function to create a `queryStore` that runs a GraphQL query and updates with GraphQL results.

     

       95
       95
       +
        *

     

       96
       96
       +
        * @param args - a {@link QueryArgs} object, to pass a `query`, `variables`, and options.

     

       97
       97
       +
        * @returns a {@link OperationResultStore} of query results, which implements {@link Pausable}.

     

       98
       98
       +
        *

     

       99
       99
       +
        * @remarks

     

       100
       100
       +
        * `queryStore` allows GraphQL queries to be defined as Svelte stores.

     

       101
       101
       +
        * Given {@link QueryArgs.query}, it executes the GraphQL query on the

     

       102
       102
       +
        * {@link QueryArgs.client}.

     

       103
       103
       +
        *

     

       104
       104
       +
        * The returned store updates with {@link OperationResult} values when

     

       105
       105
       +
        * the `Client` has new results for the query.

     

       106
       106
       +
        *

     

       107
       107
       +
        * @see {@link https://urql.dev/goto/docs/basics/svelte#queries} for `queryStore` docs.

     

       108
       108
       +
        *

     

       109
       109
       +
        * @example

     

       110
       110
       +
        * ```ts

     

       111
       111
       +
        * import { queryStore, gql, getContextClient } from '@urql/svelte';

     

       112
       112
       +
        *

     

       113
       113
       +
        * const todos = queryStore({

     

       114
       114
       +
        *   client: getContextClient(),

     

       115
       115
       +
        *   query: gql`{ todos { id, title } }`,

     

       116
       116
       +
        * });

     

       117
       117
       +
        * ```

     

       118
       118
       +
        */

     

       43
       119
        
       export function queryStore<

     

       44
       120
        
         Data = any,

     

       45
       121
        
         Variables extends AnyVariables = AnyVariables

+93

packages/svelte-urql/src/subscriptionStore.ts

···

       29
       29
        
         fromStore,

     

       30
       30
        
       } from './common';

     

       31
       31
        
       

     

       32
       32
       +
       /** Combines previous data with an incoming subscription result’s data.

     

       33
       33
       +
        *

     

       34
       34
       +
        * @remarks

     

       35
       35
       +
        * A `SubscriptionHandler` may be passed to {@link subscriptionStore} to

     

       36
       36
       +
        * aggregate subscription results into a combined `data` value on the

     

       37
       37
       +
        * {@link OperationResultStore}.

     

       38
       38
       +
        *

     

       39
       39
       +
        * This is useful when a subscription event delivers a single item, while

     

       40
       40
       +
        * you’d like to display a list of events.

     

       41
       41
       +
        *

     

       42
       42
       +
        * @example

     

       43
       43
       +
        * ```ts

     

       44
       44
       +
        * const NotificationsSubscription = gql`

     

       45
       45
       +
        *   subscription { newNotification { id, text } }

     

       46
       46
       +
        * `;

     

       47
       47
       +
        *

     

       48
       48
       +
        * subscriptionStore(

     

       49
       49
       +
        *   { query: NotificationsSubscription },

     

       50
       50
       +
        *   function combineNotifications(notifications = [], data) {

     

       51
       51
       +
        *     return [...notifications, data.newNotification];

     

       52
       52
       +
        *   },

     

       53
       53
       +
        * );

     

       54
       54
       +
        * ```

     

       55
       55
       +
        */

     

       32
       56
        
       export type SubscriptionHandler<T, R> = (prev: R | undefined, data: T) => R;

     

       33
       57
        
       

     

       58
       58
       +
       /** Input arguments for the {@link subscriptionStore} function.

     

       59
       59
       +
        *

     

       60
       60
       +
        * @param query - The GraphQL subscription that the `subscriptionStore` executes.

     

       61
       61
       +
        * @param variables - The variables for the GraphQL subscription that `subscriptionStore` executes.

     

       62
       62
       +
        */

     

       34
       63
        
       export type SubscriptionArgs<

     

       35
       64
        
         Data = any,

     

       36
       65
        
         Variables extends AnyVariables = AnyVariables

     

       37
       66
        
       > = {

     

       67
       67
       +
         /** The {@link Client} using which the subscription will be started.

     

       68
       68
       +
          *

     

       69
       69
       +
          * @remarks

     

       70
       70
       +
          * If you’ve previously provided a {@link Client} on Svelte’s context

     

       71
       71
       +
          * this can be set to {@link getContextClient}’s return value.

     

       72
       72
       +
          */

     

       38
       73
        
         client: Client;

     

       74
       74
       +
         /** Updates the {@link OperationContext} for the GraphQL subscription operation.

     

       75
       75
       +
          *

     

       76
       76
       +
          * @remarks

     

       77
       77
       +
          * `context` may be passed to {@link subscriptionStore}, to update the

     

       78
       78
       +
          * {@link OperationContext} of a subscription operation. This may be used to update

     

       79
       79
       +
          * the `context` that exchanges will receive for a single hook.

     

       80
       80
       +
          *

     

       81
       81
       +
          * @example

     

       82
       82
       +
          * ```ts

     

       83
       83
       +
          * subscriptionStore({

     

       84
       84
       +
          *   query,

     

       85
       85
       +
          *   context: {

     

       86
       86
       +
          *     additionalTypenames: ['Item'],

     

       87
       87
       +
          *   },

     

       88
       88
       +
          * });

     

       89
       89
       +
          * ```

     

       90
       90
       +
          */

     

       39
       91
        
         context?: Partial<OperationContext>;

     

       92
       92
       +
         /** Prevents the {@link subscriptionStore} from automatically starting the GraphQL subscription.

     

       93
       93
       +
          *

     

       94
       94
       +
          * @remarks

     

       95
       95
       +
          * `pause` may be set to `true` to stop the {@link subscriptionStore} from starting

     

       96
       96
       +
          * its subscription automatically. The store won't execute the subscription operation,

     

       97
       97
       +
          * until either it’s set to `false` or {@link Pausable.resume} is called.

     

       98
       98
       +
          */

     

       40
       99
        
         pause?: boolean;

     

       41
       100
        
       } & GraphQLRequestParams<Data, Variables>;

     

       42
       101
        
       

     

       102
       102
       +
       /** Function to create a `subscriptionStore` that starts a GraphQL subscription.

     

       103
       103
       +
        *

     

       104
       104
       +
        * @param args - a {@link QueryArgs} object, to pass a `query`, `variables`, and options.

     

       105
       105
       +
        * @param handler - optionally, a {@link SubscriptionHandler} function to combine multiple subscription results.

     

       106
       106
       +
        * @returns a {@link OperationResultStore} of subscription results, which implements {@link Pausable}.

     

       107
       107
       +
        *

     

       108
       108
       +
        * @remarks

     

       109
       109
       +
        * `subscriptionStore` allows GraphQL subscriptions to be defined as Svelte stores.

     

       110
       110
       +
        * Given {@link SubscriptionArgs.query}, it executes the GraphQL subsription on the

     

       111
       111
       +
        * {@link SubscriptionArgs.client}.

     

       112
       112
       +
        *

     

       113
       113
       +
        * The returned store updates with {@link OperationResult} values when

     

       114
       114
       +
        * the `Client` has new results for the subscription.

     

       115
       115
       +
        *

     

       116
       116
       +
        * @see {@link https://urql.dev/goto/docs/advanced/subscriptions#svelte} for

     

       117
       117
       +
        * `subscriptionStore` docs.

     

       118
       118
       +
        *

     

       119
       119
       +
        * @example

     

       120
       120
       +
        * ```ts

     

       121
       121
       +
        * import { subscriptionStore, gql, getContextClient } from '@urql/svelte';

     

       122
       122
       +
        *

     

       123
       123
       +
        * const todos = subscriptionStore({

     

       124
       124
       +
        *   client: getContextClient(),

     

       125
       125
       +
        *   query: gql`

     

       126
       126
       +
        *     subscription {

     

       127
       127
       +
        *       newNotification { id, text }

     

       128
       128
       +
        *     }

     

       129
       129
       +
        *   `,

     

       130
       130
       +
        *   function combineNotifications(notifications = [], data) {

     

       131
       131
       +
        *     return [...notifications, data.newNotification];

     

       132
       132
       +
        *   },

     

       133
       133
       +
        * });

     

       134
       134
       +
        * ```

     

       135
       135
       +
        */

     

       43
       136
        
       export function subscriptionStore<

     

       44
       137
        
         Data,

     

       45
       138
        
         Result = Data,

+1 -2

packages/vue-urql/src/index.ts

···

       12
       12
        
       export type {

     

       13
       13
        
         UseSubscriptionArgs,

     

       14
       14
        
         UseSubscriptionResponse,

     

       15
       15
       -
         UseSubscriptionState,

     

       16
       15
        
         SubscriptionHandlerArg,

     

       17
       16
        
         SubscriptionHandler,

     

       18
       17
        
       } from './useSubscription';

     

       19
       18
        
       

     

       20
       19
        
       export { useMutation } from './useMutation';

     

       21
       20
        
       

     

       22
       22
       -
       export type { UseMutationResponse, UseMutationState } from './useMutation';

     

       21
       21
       +
       export type { UseMutationResponse } from './useMutation';

     

       23
       22
        
       

     

       24
       23
        
       import { install } from './useClient';

     

       25
       24

+65

packages/vue-urql/src/useClient.ts

···

       3
       3
        
       

     

       4
       4
        
       const clientsPerInstance = new WeakMap<{}, Ref<Client>>();

     

       5
       5
        
       

     

       6
       6
       +
       /** Provides a {@link Client} to a component’s children.

     

       7
       7
       +
        *

     

       8
       8
       +
        * @param opts - {@link ClientOptions}, a {@link Client}, or a reactive ref object of a `Client`.

     

       9
       9
       +
        *

     

       10
       10
       +
        * @remarks

     

       11
       11
       +
        * `provideClient` provides a {@link Client} to `@urql/vue`’s GraphQL

     

       12
       12
       +
        * functions in children components.

     

       13
       13
       +
        *

     

       14
       14
       +
        * Hint: GraphQL functions and {@link useClient} will see the

     

       15
       15
       +
        * provided `Client`, even if `provideClient` has been called

     

       16
       16
       +
        * in the same component’s `setup` function.

     

       17
       17
       +
        *

     

       18
       18
       +
        * @example

     

       19
       19
       +
        * ```ts

     

       20
       20
       +
        * import { provideClient } from '@urql/vue';

     

       21
       21
       +
        * // All of `@urql/core` is also re-exported by `@urql/vue`:

     

       22
       22
       +
        * import { Client, cacheExchange, fetchExchange } from '@urql/core';

     

       23
       23
       +
        *

     

       24
       24
       +
        * export default {

     

       25
       25
       +
        *   setup() {

     

       26
       26
       +
        *     provideClient(new Client({

     

       27
       27
       +
        *       url: 'https://API',

     

       28
       28
       +
        *       exchanges: [cacheExchange, fetchExchange],

     

       29
       29
       +
        *     }));

     

       30
       30
       +
        *   },

     

       31
       31
       +
        * };

     

       32
       32
       +
        * ```

     

       33
       33
       +
        */

     

       6
       34
        
       export function provideClient(opts: ClientOptions | Client | Ref<Client>) {

     

       7
       35
        
         let client: Ref<Client>;

     

       8
       36
        
         if (!isRef(opts)) {

     
···

       20
       48
        
         return client.value;

     

       21
       49
        
       }

     

       22
       50
        
       

     

       51
       51
       +
       /** Provides a {@link Client} to a Vue app.

     

       52
       52
       +
        *

     

       53
       53
       +
        * @param app - the Vue {@link App}

     

       54
       54
       +
        * @param opts - {@link ClientOptions}, a {@link Client}, or a reactive ref object of a `Client`.

     

       55
       55
       +
        *

     

       56
       56
       +
        * @remarks

     

       57
       57
       +
        * `install` provides a {@link Client} to `@urql/vue`’s GraphQL

     

       58
       58
       +
        * functions in a Vue app.

     

       59
       59
       +
        *

     

       60
       60
       +
        * @example

     

       61
       61
       +
        * ```ts

     

       62
       62
       +
        * import * as urql from '@urql/vue';

     

       63
       63
       +
        * // All of `@urql/core` is also re-exported by `@urql/vue`:

     

       64
       64
       +
        * import { cacheExchange, fetchExchange } from '@urql/core';

     

       65
       65
       +
        *

     

       66
       66
       +
        * import { createApp } from 'vue';

     

       67
       67
       +
        * import Root from './App.vue';

     

       68
       68
       +
        *

     

       69
       69
       +
        * const app = createApp(Root);

     

       70
       70
       +
        * app.use(urql, {

     

       71
       71
       +
        *   url: 'http://localhost:3000/graphql',

     

       72
       72
       +
        *   exchanges: [cacheExchange, fetchExchange],

     

       73
       73
       +
        * });

     

       74
       74
       +
        * ```

     

       75
       75
       +
        */

     

       23
       76
        
       export function install(app: App, opts: ClientOptions | Client | Ref<Client>) {

     

       24
       77
        
         let client: Ref<Client>;

     

       25
       78
        
         if (!isRef(opts)) {

     
···

       30
       83
        
         app.provide('$urql', client);

     

       31
       84
        
       }

     

       32
       85
        
       

     

       86
       86
       +
       /** Returns a provided reactive ref object of a {@link Client}.

     

       87
       87
       +
        *

     

       88
       88
       +
        * @remarks

     

       89
       89
       +
        * `useClient` may be called in Vue `setup` functions to retrieve a

     

       90
       90
       +
        * reactive rev object of a {@link Client} that’s previously been

     

       91
       91
       +
        * provided with {@link provideClient} in the current or a parent’s

     

       92
       92
       +
        * `setup` function.

     

       93
       93
       +
        *

     

       94
       94
       +
        * @throws

     

       95
       95
       +
        * In development, if `useClient` is called outside of a Vue `setup`

     

       96
       96
       +
        * function or no {@link Client} was provided, an error will be thrown.

     

       97
       97
       +
        */

     

       33
       98
        
       export function useClient(): Ref<Client> {

     

       34
       99
        
         const instance = getCurrentInstance();

     

       35
       100
        
         if (process.env.NODE_ENV !== 'production' && !instance) {

+92

packages/vue-urql/src/useClientHandle.ts

···

       20
       20
        
         UseSubscriptionResponse,

     

       21
       21
        
       } from './useSubscription';

     

       22
       22
        
       

     

       23
       23
       +
       /** Handle to create GraphQL operations outside of Vue’s `setup` functions.

     

       24
       24
       +
        *

     

       25
       25
       +
        * @remarks

     

       26
       26
       +
        * The `ClientHandle` object is created inside a Vue `setup` function but

     

       27
       27
       +
        * allows its methods to be called outside of `setup` functions, delaying

     

       28
       28
       +
        * the creation of GraphQL operations, as an alternative to pausing queries

     

       29
       29
       +
        * or subscriptions.

     

       30
       30
       +
        *

     

       31
       31
       +
        * This is also important when chaining multiple functions inside an

     

       32
       32
       +
        * `async setup()` function.

     

       33
       33
       +
        *

     

       34
       34
       +
        * Hint: If you only need a single, non-updating result and want to execute

     

       35
       35
       +
        * queries programmatically, it may be easier to call the {@link Client.query}

     

       36
       36
       +
        * method.

     

       37
       37
       +
        */

     

       23
       38
        
       export interface ClientHandle {

     

       39
       39
       +
         /** The {@link Client} that’ll be used to execute GraphQL operations. */

     

       24
       40
        
         client: Client;

     

       25
       41
        
       

     

       42
       42
       +
         /** Calls {@link useQuery} outside of a synchronous Vue `setup` function.

     

       43
       43
       +
          *

     

       44
       44
       +
          * @param args - a {@link UseQueryArgs} object, to pass a `query`, `variables`, and options.

     

       45
       45
       +
          * @returns a {@link UseQueryResponse} object.

     

       46
       46
       +
          *

     

       47
       47
       +
          * @remarks

     

       48
       48
       +
          * Creates a {@link UseQueryResponse} outside of a synchronous Vue `setup`

     

       49
       49
       +
          * function or when chained in an `async setup()` function.

     

       50
       50
       +
          */

     

       26
       51
        
         useQuery<T = any, V extends AnyVariables = AnyVariables>(

     

       27
       52
        
           args: UseQueryArgs<T, V>

     

       28
       53
        
         ): UseQueryResponse<T, V>;

     

       29
       54
        
       

     

       55
       55
       +
         /** Calls {@link useSubscription} outside of a synchronous Vue `setup` function.

     

       56
       56
       +
          *

     

       57
       57
       +
          * @param args - a {@link UseSubscriptionArgs} object, to pass a `query`, `variables`, and options.

     

       58
       58
       +
          * @param handler - optionally, a {@link SubscriptionHandler} function to combine multiple subscription results.

     

       59
       59
       +
          * @returns a {@link UseSubscriptionResponse} object.

     

       60
       60
       +
          *

     

       61
       61
       +
          * @remarks

     

       62
       62
       +
          * Creates a {@link UseSubscriptionResponse} outside of a synchronous Vue `setup`

     

       63
       63
       +
          * function or when chained in an `async setup()` function.

     

       64
       64
       +
          */

     

       30
       65
        
         useSubscription<T = any, R = T, V extends AnyVariables = AnyVariables>(

     

       31
       66
        
           args: UseSubscriptionArgs<T, V>,

     

       32
       67
        
           handler?: SubscriptionHandlerArg<T, R>

     

       33
       68
        
         ): UseSubscriptionResponse<T, R, V>;

     

       34
       69
        
       

     

       70
       70
       +
         /** Calls {@link useMutation} outside of a synchronous Vue `setup` function.

     

       71
       71
       +
          *

     

       72
       72
       +
          * @param query - a GraphQL mutation document which `useMutation` will execute.

     

       73
       73
       +
          * @returns a {@link UseMutationResponse} object.

     

       74
       74
       +
          *

     

       75
       75
       +
          * @remarks

     

       76
       76
       +
          * Creates a {@link UseMutationResponse} outside of a synchronous Vue `setup`

     

       77
       77
       +
          * function or when chained in an `async setup()` function.

     

       78
       78
       +
          */

     

       35
       79
        
         useMutation<T = any, V extends AnyVariables = AnyVariables>(

     

       36
       80
        
           query: TypedDocumentNode<T, V> | DocumentNode | string

     

       37
       81
        
         ): UseMutationResponse<T, V>;

     

       38
       82
        
       }

     

       39
       83
        
       

     

       84
       84
       +
       /** Creates a {@link ClientHandle} inside a Vue `setup` function.

     

       85
       85
       +
        *

     

       86
       86
       +
        * @remarks

     

       87
       87
       +
        * `useClientHandle` creates and returns a {@link ClientHandle}

     

       88
       88
       +
        * when called in a Vue `setup` function, which allows queries,

     

       89
       89
       +
        * mutations, and subscriptions to be created _outside_ of

     

       90
       90
       +
        * `setup` functions.

     

       91
       91
       +
        *

     

       92
       92
       +
        * This is also important when chaining multiple functions inside an

     

       93
       93
       +
        * `async setup()` function.

     

       94
       94
       +
        *

     

       95
       95
       +
        * {@link useQuery} and other GraphQL functions must usually

     

       96
       96
       +
        * be created in Vue `setup` functions so they can stop GraphQL

     

       97
       97
       +
        * operations when your component unmounts. However, while they

     

       98
       98
       +
        * queries and subscriptions can be paused, sometimes it’s easier

     

       99
       99
       +
        * to delay the creation of their response objects.

     

       100
       100
       +
        *

     

       101
       101
       +
        *

     

       102
       102
       +
        * @example

     

       103
       103
       +
        * ```ts

     

       104
       104
       +
        * import { ref, computed } from 'vue';

     

       105
       105
       +
        * import { gql, useClientHandle } from '@urql/vue';

     

       106
       106
       +
        *

     

       107
       107
       +
        * export default {

     

       108
       108
       +
        *   async setup() {

     

       109
       109
       +
        *     const handle = useClientHandle();

     

       110
       110
       +
        *

     

       111
       111
       +
        *     const pokemons = await handle.useQuery({

     

       112
       112
       +
        *       query: gql`{ pokemons(limit: 10) { id, name } }`,

     

       113
       113
       +
        *     });

     

       114
       114
       +
        *

     

       115
       115
       +
        *     const index = ref(0);

     

       116
       116
       +
        *

     

       117
       117
       +
        *     // The `handle` allows another `useQuery` call to now be setup again

     

       118
       118
       +
        *     const pokemon = await handle.useQuery({

     

       119
       119
       +
        *       query: gql`

     

       120
       120
       +
        *         query ($id: ID!) {

     

       121
       121
       +
        *           pokemon(id: $id) { id, name }

     

       122
       122
       +
        *         }

     

       123
       123
       +
        *       `,

     

       124
       124
       +
        *       variables: computed(() => ({

     

       125
       125
       +
        *         id: pokemons.data.value.pokemons[index.value].id,

     

       126
       126
       +
        *       }),

     

       127
       127
       +
        *     });

     

       128
       128
       +
        *   }

     

       129
       129
       +
        * };

     

       130
       130
       +
        * ```

     

       131
       131
       +
        */

     

       40
       132
        
       export function useClientHandle(): ClientHandle {

     

       41
       133
        
         const client = useClient();

     

       42
       134
        
         const stops: WatchStopHandle[] = [];

+95 -8

packages/vue-urql/src/useMutation.ts

···

       18
       18
        
       import { useClient } from './useClient';

     

       19
       19
        
       import { unwrapPossibleProxy } from './utils';

     

       20
       20
        
       

     

       21
       21
       -
       export interface UseMutationState<T, V extends AnyVariables = AnyVariables> {

     

       21
       21
       +
       /** State of the last mutation executed by {@link useMutation}.

     

       22
       22
       +
        *

     

       23
       23
       +
        * @remarks

     

       24
       24
       +
        * `UseMutationResponse` is returned by {@link useMutation} and

     

       25
       25
       +
        * gives you the {@link OperationResult} of the last executed mutation,

     

       26
       26
       +
        * and a {@link UseMutationResponse.executeMutation} method to

     

       27
       27
       +
        * start mutations.

     

       28
       28
       +
        *

     

       29
       29
       +
        * Even if the mutation document passed to {@link useMutation} changes,

     

       30
       30
       +
        * the state isn’t reset, so you can keep displaying the previous result.

     

       31
       31
       +
        */

     

       32
       32
       +
       export interface UseMutationResponse<T, V extends AnyVariables = AnyVariables> {

     

       33
       33
       +
         /** Indicates whether `useMutation` is currently executing a mutation. */

     

       22
       34
        
         fetching: Ref<boolean>;

     

       35
       35
       +
         /** Indicates that the mutation result is not fresh.

     

       36
       36
       +
          *

     

       37
       37
       +
          * @remarks

     

       38
       38
       +
          * The `stale` flag is set to `true` when a new result for the mutation

     

       39
       39
       +
          * is expected.

     

       40
       40
       +
          * This is mostly unused for mutations and will rarely affect you, and

     

       41
       41
       +
          * is more relevant for queries.

     

       42
       42
       +
          *

     

       43
       43
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       44
       44
       +
          */

     

       23
       45
        
         stale: Ref<boolean>;

     

       46
       46
       +
         /** Reactive {@link OperationResult.data} for the executed mutation. */

     

       24
       47
        
         data: Ref<T | undefined>;

     

       48
       48
       +
         /** Reactive {@link OperationResult.error} for the executed mutation. */

     

       25
       49
        
         error: Ref<CombinedError | undefined>;

     

       50
       50
       +
         /** Reactive {@link OperationResult.extensions} for the executed mutation. */

     

       26
       51
        
         extensions: Ref<Record<string, any> | undefined>;

     

       52
       52
       +
         /** Reactive {@link Operation} that the current state is for.

     

       53
       53
       +
          *

     

       54
       54
       +
          * @remarks

     

       55
       55
       +
          * This is the mutation {@link Operation} that has last been executed.

     

       56
       56
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       57
       57
       +
          * last `Operation` that the current state was for.

     

       58
       58
       +
          */

     

       27
       59
        
         operation: Ref<Operation<T, V> | undefined>;

     

       28
       28
       -
         executeMutation: (

     

       60
       60
       +
         /** Triggers {@link useMutation} to execute its GraphQL mutation operation.

     

       61
       61
       +
          *

     

       62
       62
       +
          * @param variables - variables using which the mutation will be executed.

     

       63
       63
       +
          * @param context - optionally, context options that will be merged with

     

       64
       64
       +
          * {@link UseMutationArgs.context} and the `Client`’s options.

     

       65
       65
       +
          * @returns the {@link OperationResult} of the mutation.

     

       66
       66
       +
          *

     

       67
       67
       +
          * @remarks

     

       68
       68
       +
          * When called, {@link useMutation} will start the GraphQL mutation

     

       69
       69
       +
          * it currently holds and use the `variables` passed to it.

     

       70
       70
       +
          *

     

       71
       71
       +
          * Once the mutation response comes back from the API, its

     

       72
       72
       +
          * returned promise will resolve to the mutation’s {@link OperationResult}

     

       73
       73
       +
          * and the {@link UseMutationResponse} will be updated with the result.

     

       74
       74
       +
          *

     

       75
       75
       +
          * @example

     

       76
       76
       +
          * ```ts

     

       77
       77
       +
          * const result = useMutation(UpdateTodo);

     

       78
       78
       +
          * const start = async ({ id, title }) => {

     

       79
       79
       +
          *   const result = await result.executeMutation({ id, title });

     

       80
       80
       +
          * };

     

       81
       81
       +
          */

     

       82
       82
       +
         executeMutation(

     

       29
       83
        
           variables: V,

     

       30
       84
        
           context?: Partial<OperationContext>

     

       31
       31
       -
         ) => Promise<OperationResult<T>>;

     

       85
       85
       +
         ): Promise<OperationResult<T>>;

     

       32
       86
        
       }

     

       33
       87
        
       

     

       34
       34
       -
       export type UseMutationResponse<

     

       35
       35
       -
         T,

     

       36
       36
       -
         V extends AnyVariables = AnyVariables

     

       37
       37
       -
       > = UseMutationState<T, V>;

     

       38
       38
       -
       

     

       88
       88
       +
       /** Function to create a GraphQL mutation, run by passing variables to {@link UseMutationResponse.executeMutation}

     

       89
       89
       +
        *

     

       90
       90
       +
        * @param query - a GraphQL mutation document which `useMutation` will execute.

     

       91
       91
       +
        * @returns a {@link UseMutationResponse} object.

     

       92
       92
       +
        *

     

       93
       93
       +
        * @remarks

     

       94
       94
       +
        * `useMutation` allows GraphQL mutations to be defined inside Vue `setup` functions,

     

       95
       95
       +
        * and keeps its state after the mutation is started. Mutations can be started by calling

     

       96
       96
       +
        * {@link UseMutationResponse.executeMutation} with variables.

     

       97
       97
       +
        *

     

       98
       98
       +
        * The returned result updates when a mutation is executed and keeps

     

       99
       99
       +
        * track of the last mutation result.

     

       100
       100
       +
        *

     

       101
       101
       +
        * @see {@link https://urql.dev/goto/docs/basics/vue#mutations} for `useMutation` docs.

     

       102
       102
       +
        *

     

       103
       103
       +
        * @example

     

       104
       104
       +
        * ```ts

     

       105
       105
       +
        * import { gql, useMutation } from '@urql/vue';

     

       106
       106
       +
        *

     

       107
       107
       +
        * const UpdateTodo = gql`

     

       108
       108
       +
        *   mutation ($id: ID!, $title: String!) {

     

       109
       109
       +
        *     updateTodo(id: $id, title: $title) {

     

       110
       110
       +
        *       id, title

     

       111
       111
       +
        *     }

     

       112
       112
       +
        *   }

     

       113
       113
       +
        * `;

     

       114
       114
       +
        *

     

       115
       115
       +
        * export default {

     

       116
       116
       +
        *   setup() {

     

       117
       117
       +
        *     const result = useMutation(UpdateTodo);

     

       118
       118
       +
        *     const start = async ({ id, title }) => {

     

       119
       119
       +
        *       const result = await result.executeMutation({ id, title });

     

       120
       120
       +
        *     };

     

       121
       121
       +
        *     // ...

     

       122
       122
       +
        *   },

     

       123
       123
       +
        * };

     

       124
       124
       +
        * ```

     

       125
       125
       +
        */

     

       39
       126
        
       export function useMutation<T = any, V extends AnyVariables = AnyVariables>(

     

       40
       127
        
         query: TypedDocumentNode<T, V> | DocumentNode | string

     

       41
       128
        
       ): UseMutationResponse<T, V> {

+180 -5

packages/vue-urql/src/useQuery.ts

···

       23
       23
        
       type MaybeRef<T> = T | Ref<T>;

     

       24
       24
        
       type MaybeRefObj<T extends {}> = { [K in keyof T]: MaybeRef<T[K]> };

     

       25
       25
        
       

     

       26
       26
       +
       /** Input arguments for the {@link useQuery} function.

     

       27
       27
       +
        *

     

       28
       28
       +
        * @param query - The GraphQL query that `useQuery` executes.

     

       29
       29
       +
        * @param variables - The variables for the GraphQL query that `useQuery` executes.

     

       30
       30
       +
        */

     

       26
       31
        
       export type UseQueryArgs<

     

       27
       32
        
         Data = any,

     

       28
       33
        
         Variables extends AnyVariables = AnyVariables

     

       29
       34
        
       > = {

     

       35
       35
       +
         /** Updates the {@link RequestPolicy} for the executed GraphQL query operation.

     

       36
       36
       +
          *

     

       37
       37
       +
          * @remarks

     

       38
       38
       +
          * `requestPolicy` modifies the {@link RequestPolicy} of the GraphQL query operation

     

       39
       39
       +
          * that `useQuery` executes, and indicates a caching strategy for cache exchanges.

     

       40
       40
       +
          *

     

       41
       41
       +
          * For example, when set to `'cache-and-network'`, {@link useQuery} will

     

       42
       42
       +
          * receive a cached result with `stale: true` and an API request will be

     

       43
       43
       +
          * sent in the background.

     

       44
       44
       +
          *

     

       45
       45
       +
          * @see {@link OperationContext.requestPolicy} for where this value is set.

     

       46
       46
       +
          */

     

       30
       47
        
         requestPolicy?: MaybeRef<RequestPolicy>;

     

       48
       48
       +
         /** Updates the {@link OperationContext} for the executed GraphQL query operation.

     

       49
       49
       +
          *

     

       50
       50
       +
          * @remarks

     

       51
       51
       +
          * `context` may be passed to {@link useQuery}, to update the {@link OperationContext}

     

       52
       52
       +
          * of a query operation. This may be used to update the `context` that exchanges

     

       53
       53
       +
          * will receive for a single hook.

     

       54
       54
       +
          *

     

       55
       55
       +
          * @example

     

       56
       56
       +
          * ```ts

     

       57
       57
       +
          * const result = useQuery({

     

       58
       58
       +
          *   query,

     

       59
       59
       +
          *   context: {

     

       60
       60
       +
          *     additionalTypenames: ['Item'],

     

       61
       61
       +
          *   },

     

       62
       62
       +
          * });

     

       63
       63
       +
          * ```

     

       64
       64
       +
          */

     

       31
       65
        
         context?: MaybeRef<Partial<OperationContext>>;

     

       66
       66
       +
         /** Prevents {@link useQuery} from automatically executing GraphQL query operations.

     

       67
       67
       +
          *

     

       68
       68
       +
          * @remarks

     

       69
       69
       +
          * `pause` may be set to `true` to stop {@link useQuery} from executing

     

       70
       70
       +
          * automatically. This will pause the query until {@link UseQueryState.resume}

     

       71
       71
       +
          * is called, or, if `pause` is a reactive ref of a boolean, until this

     

       72
       72
       +
          * ref changes to `true`.

     

       73
       73
       +
          *

     

       74
       74
       +
          * @see {@link https://urql.dev/goto/docs/basics/vue#pausing-usequery} for

     

       75
       75
       +
          * documentation on the `pause` option.

     

       76
       76
       +
          */

     

       32
       77
        
         pause?: MaybeRef<boolean>;

     

       33
       78
        
       } & MaybeRefObj<GraphQLRequestParams<Data, Variables>>;

     

       34
       79
        
       

     

       35
       35
       -
       export type QueryPartialState<

     

       36
       36
       -
         T = any,

     

       37
       37
       -
         V extends AnyVariables = AnyVariables

     

       38
       38
       -
       > = Partial<OperationResult<T, V>> & { fetching?: boolean };

     

       39
       39
       -
       

     

       80
       80
       +
       /** State of the current query, your {@link useQuery} function is executing.

     

       81
       81
       +
        *

     

       82
       82
       +
        * @remarks

     

       83
       83
       +
        * `UseQueryState` is returned by {@link useQuery} and

     

       84
       84
       +
        * gives you the updating {@link OperationResult} of

     

       85
       85
       +
        * GraphQL queries.

     

       86
       86
       +
        *

     

       87
       87
       +
        * Each value that is part of the result is wrapped in a reactive ref

     

       88
       88
       +
        * and updates as results come in.

     

       89
       89
       +
        *

     

       90
       90
       +
        * Hint: Even when the query and variables update, the previous state of

     

       91
       91
       +
        * the last result is preserved, which allows you to display the

     

       92
       92
       +
        * previous state, while implementing a loading indicator separately.

     

       93
       93
       +
        */

     

       40
       94
        
       export interface UseQueryState<T = any, V extends AnyVariables = AnyVariables> {

     

       95
       95
       +
         /** Indicates whether `useQuery` is waiting for a new result.

     

       96
       96
       +
          *

     

       97
       97
       +
          * @remarks

     

       98
       98
       +
          * When `useQuery` receives a new query and/or variables, it will

     

       99
       99
       +
          * start executing the new query operation and `fetching` is set to

     

       100
       100
       +
          * `true` until a result arrives.

     

       101
       101
       +
          *

     

       102
       102
       +
          * Hint: This is subtly different than whether the query is actually

     

       103
       103
       +
          * fetching, and doesn’t indicate whether a query is being re-executed

     

       104
       104
       +
          * in the background. For this, see {@link UseQueryState.stale}.

     

       105
       105
       +
          */

     

       41
       106
        
         fetching: Ref<boolean>;

     

       107
       107
       +
         /** Indicates that the state is not fresh and a new result will follow.

     

       108
       108
       +
          *

     

       109
       109
       +
          * @remarks

     

       110
       110
       +
          * The `stale` flag is set to `true` when a new result for the query

     

       111
       111
       +
          * is expected and `useQuery` is waiting for it. This may indicate that

     

       112
       112
       +
          * a new request is being requested in the background.

     

       113
       113
       +
          *

     

       114
       114
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       115
       115
       +
          */

     

       42
       116
        
         stale: Ref<boolean>;

     

       117
       117
       +
         /** Reactive {@link OperationResult.data} for the executed query. */

     

       43
       118
        
         data: Ref<T | undefined>;

     

       119
       119
       +
         /** Reactive {@link OperationResult.error} for the executed query. */

     

       44
       120
        
         error: Ref<CombinedError | undefined>;

     

       121
       121
       +
         /** Reactive {@link OperationResult.extensions} for the executed query. */

     

       45
       122
        
         extensions: Ref<Record<string, any> | undefined>;

     

       123
       123
       +
         /** Reactive {@link Operation} that the current state is for.

     

       124
       124
       +
          *

     

       125
       125
       +
          * @remarks

     

       126
       126
       +
          * This is the {@link Operation} that is currently being executed.

     

       127
       127
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       128
       128
       +
          * last `Operation` that the current state was for.

     

       129
       129
       +
          */

     

       46
       130
        
         operation: Ref<Operation<T, V> | undefined>;

     

       131
       131
       +
         /** Indicates whether {@link useQuery} is currently paused.

     

       132
       132
       +
          *

     

       133
       133
       +
          * @remarks

     

       134
       134
       +
          * When `useQuery` has been paused, it will stop receiving updates

     

       135
       135
       +
          * from the {@link Client} and won’t execute query operations, until

     

       136
       136
       +
          * {@link UseQueryArgs.pause} becomes `true` or {@link UseQueryState.resume}

     

       137
       137
       +
          * is called.

     

       138
       138
       +
          *

     

       139
       139
       +
          * @see {@link https://urql.dev/goto/docs/basics/vue#pausing-usequery} for

     

       140
       140
       +
          * documentation on the `pause` option.

     

       141
       141
       +
          */

     

       47
       142
        
         isPaused: Ref<boolean>;

     

       143
       143
       +
         /** Resumes {@link useQuery} if it’s currently paused.

     

       144
       144
       +
          *

     

       145
       145
       +
          * @remarks

     

       146
       146
       +
          * Resumes or starts {@link useQuery}’s query, if it’s currently paused.

     

       147
       147
       +
          *

     

       148
       148
       +
          * @see {@link https://urql.dev/goto/docs/basics/vue#pausing-usequery} for

     

       149
       149
       +
          * documentation on the `pause` option.

     

       150
       150
       +
          */

     

       48
       151
        
         resume(): void;

     

       152
       152
       +
         /** Pauses {@link useQuery} to stop it from executing the query.

     

       153
       153
       +
          *

     

       154
       154
       +
          * @remarks

     

       155
       155
       +
          * Pauses {@link useQuery}’s query, which stops it from receiving updates

     

       156
       156
       +
          * from the {@link Client} and to stop the ongoing query operation.

     

       157
       157
       +
          *

     

       158
       158
       +
          * @see {@link https://urql.dev/goto/docs/basics/vue#pausing-usequery} for

     

       159
       159
       +
          * documentation on the `pause` option.

     

       160
       160
       +
          */

     

       49
       161
        
         pause(): void;

     

       162
       162
       +
         /** Triggers {@link useQuery} to execute a new GraphQL query operation.

     

       163
       163
       +
          *

     

       164
       164
       +
          * @param opts - optionally, context options that will be merged with

     

       165
       165
       +
          * {@link UseQueryArgs.context} and the `Client`’s options.

     

       166
       166
       +
          *

     

       167
       167
       +
          * @remarks

     

       168
       168
       +
          * When called, {@link useQuery} will re-execute the GraphQL query operation

     

       169
       169
       +
          * it currently holds, unless it’s currently paused.

     

       170
       170
       +
          *

     

       171
       171
       +
          * This is useful for re-executing a query and get a new network result,

     

       172
       172
       +
          * by passing a new request policy.

     

       173
       173
       +
          *

     

       174
       174
       +
          * ```ts

     

       175
       175
       +
          * const result = useQuery({ query });

     

       176
       176
       +
          *

     

       177
       177
       +
          * const refresh = () => {

     

       178
       178
       +
          *   // Re-execute the query with a network-only policy, skipping the cache

     

       179
       179
       +
          *   result.executeQuery({ requestPolicy: 'network-only' });

     

       180
       180
       +
          * };

     

       181
       181
       +
          * ```

     

       182
       182
       +
          */

     

       50
       183
        
         executeQuery(opts?: Partial<OperationContext>): UseQueryResponse<T, V>;

     

       51
       184
        
       }

     

       52
       185
        
       

     

       186
       186
       +
       /** Return value of {@link useQuery}, which is an awaitable {@link UseQueryState}.

     

       187
       187
       +
        *

     

       188
       188
       +
        * @remarks

     

       189
       189
       +
        * {@link useQuery} returns a {@link UseQueryState} but may also be

     

       190
       190
       +
        * awaited inside a Vue `async setup()` function. If it’s awaited

     

       191
       191
       +
        * the query is executed before resolving.

     

       192
       192
       +
        */

     

       53
       193
        
       export type UseQueryResponse<

     

       54
       194
        
         T,

     

       55
       195
        
         V extends AnyVariables = AnyVariables

     
···

       59
       199
        
         flush: 'pre' as const,

     

       60
       200
        
       };

     

       61
       201
        
       

     

       202
       202
       +
       /** Function to run a GraphQL query and get reactive GraphQL results.

     

       203
       203
       +
        *

     

       204
       204
       +
        * @param args - a {@link UseQueryArgs} object, to pass a `query`, `variables`, and options.

     

       205
       205
       +
        * @returns a {@link UseQueryResponse} object.

     

       206
       206
       +
        *

     

       207
       207
       +
        * @remarks

     

       208
       208
       +
        * `useQuery` allows GraphQL queries to be defined and executed inside

     

       209
       209
       +
        * Vue `setup` functions.

     

       210
       210
       +
        * Given {@link UseQueryArgs.query}, it executes the GraphQL query with the

     

       211
       211
       +
        * provided {@link Client}.

     

       212
       212
       +
        *

     

       213
       213
       +
        * The returned result’s reactive values update when the `Client` has

     

       214
       214
       +
        * new results for the query, and changes when your input `args` change.

     

       215
       215
       +
        *

     

       216
       216
       +
        * Additionally, `useQuery` may also be awaited inside an `async setup()`

     

       217
       217
       +
        * function to use Vue’s Suspense feature.

     

       218
       218
       +
        *

     

       219
       219
       +
        * @see {@link https://urql.dev/goto/docs/basics/vue#queries} for `useQuery` docs.

     

       220
       220
       +
        *

     

       221
       221
       +
        * @example

     

       222
       222
       +
        * ```ts

     

       223
       223
       +
        * import { gql, useQuery } from '@urql/vue';

     

       224
       224
       +
        *

     

       225
       225
       +
        * const TodosQuery = gql`

     

       226
       226
       +
        *   query { todos { id, title } }

     

       227
       227
       +
        * `;

     

       228
       228
       +
        *

     

       229
       229
       +
        * export default {

     

       230
       230
       +
        *   setup() {

     

       231
       231
       +
        *     const result = useQuery({ query: TodosQuery });

     

       232
       232
       +
        *     return { data: result.data };

     

       233
       233
       +
        *   },

     

       234
       234
       +
        * };

     

       235
       235
       +
        * ```

     

       236
       236
       +
        */

     

       62
       237
        
       export function useQuery<T = any, V extends AnyVariables = AnyVariables>(

     

       63
       238
        
         args: UseQueryArgs<T, V>

     

       64
       239
        
       ): UseQueryResponse<T, V> {

+174 -11

packages/vue-urql/src/useSubscription.ts

···

       22
       22
        
       type MaybeRef<T> = Exclude<T, void> | Ref<Exclude<T, void>>;

     

       23
       23
        
       type MaybeRefObj<T extends {}> = { [K in keyof T]: MaybeRef<T[K]> };

     

       24
       24
        
       

     

       25
       25
       +
       /** Input arguments for the {@link useSubscription} function.

     

       26
       26
       +
        *

     

       27
       27
       +
        * @param query - The GraphQL subscription document that `useSubscription` executes.

     

       28
       28
       +
        * @param variables - The variables for the GraphQL subscription that `useSubscription` executes.

     

       29
       29
       +
        */

     

       25
       30
        
       export type UseSubscriptionArgs<

     

       26
       31
        
         Data = any,

     

       27
       32
        
         Variables extends AnyVariables = AnyVariables

     

       28
       33
        
       > = {

     

       34
       34
       +
         /** Prevents {@link useSubscription} from automatically executing GraphQL subscription operations.

     

       35
       35
       +
          *

     

       36
       36
       +
          * @remarks

     

       37
       37
       +
          * `pause` may be set to `true` to stop {@link useSubscription} from starting

     

       38
       38
       +
          * its subscription automatically. This will pause the subscription until

     

       39
       39
       +
          * {@link UseSubscriptonState.resume} is called, or, if `pause` is a reactive

     

       40
       40
       +
          * ref of a boolean, until this ref changes to `true`.

     

       41
       41
       +
          */

     

       29
       42
        
         pause?: MaybeRef<boolean>;

     

       43
       43
       +
         /** Updates the {@link OperationContext} for the executed GraphQL subscription operation.

     

       44
       44
       +
          *

     

       45
       45
       +
          * @remarks

     

       46
       46
       +
          * `context` may be passed to {@link useSubscription}, to update the {@link OperationContext}

     

       47
       47
       +
          * of a subscription operation. This may be used to update the `context` that exchanges

     

       48
       48
       +
          * will receive for a single hook.

     

       49
       49
       +
          *

     

       50
       50
       +
          * @example

     

       51
       51
       +
          * ```ts

     

       52
       52
       +
          * const result = useQuery({

     

       53
       53
       +
          *   query,

     

       54
       54
       +
          *   context: {

     

       55
       55
       +
          *     additionalTypenames: ['Item'],

     

       56
       56
       +
          *   },

     

       57
       57
       +
          * });

     

       58
       58
       +
          * ```

     

       59
       59
       +
          */

     

       30
       60
        
         context?: MaybeRef<Partial<OperationContext>>;

     

       31
       61
        
       } & MaybeRefObj<GraphQLRequestParams<Data, Variables>>;

     

       32
       62
        
       

     

       63
       63
       +
       /** Combines previous data with an incoming subscription result’s data.

     

       64
       64
       +
        *

     

       65
       65
       +
        * @remarks

     

       66
       66
       +
        * A `SubscriptionHandler` may be passed to {@link useSubscription} to

     

       67
       67
       +
        * aggregate subscription results into a combined {@link UseSubscriptionResponse.data}

     

       68
       68
       +
        * value.

     

       69
       69
       +
        *

     

       70
       70
       +
        * This is useful when a subscription event delivers a single item, while

     

       71
       71
       +
        * you’d like to display a list of events.

     

       72
       72
       +
        *

     

       73
       73
       +
        * @example

     

       74
       74
       +
        * ```ts

     

       75
       75
       +
        * const NotificationsSubscription = gql`

     

       76
       76
       +
        *   subscription { newNotification { id, text } }

     

       77
       77
       +
        * `;

     

       78
       78
       +
        *

     

       79
       79
       +
        * const combineNotifications = (notifications = [], data) => {

     

       80
       80
       +
        *   return [...notifications, data.newNotification];

     

       81
       81
       +
        * };

     

       82
       82
       +
        *

     

       83
       83
       +
        * const result = useSubscription(

     

       84
       84
       +
        *   { query: NotificationsSubscription },

     

       85
       85
       +
        *   combineNotifications,

     

       86
       86
       +
        * );

     

       87
       87
       +
        * ```

     

       88
       88
       +
        */

     

       33
       89
        
       export type SubscriptionHandler<T, R> = (prev: R | undefined, data: T) => R;

     

       90
       90
       +
       

     

       91
       91
       +
       /** A {@link SubscriptionHandler} or a reactive ref of one. */

     

       34
       92
        
       export type SubscriptionHandlerArg<T, R> = MaybeRef<SubscriptionHandler<T, R>>;

     

       35
       93
        
       

     

       36
       36
       -
       export interface UseSubscriptionState<

     

       94
       94
       +
       /** State of the current query, your {@link useSubscription} function is executing.

     

       95
       95
       +
        *

     

       96
       96
       +
        * @remarks

     

       97
       97
       +
        * `UseSubscriptionResponse` is returned by {@link useSubscription} and

     

       98
       98
       +
        * gives you the updating {@link OperationResult} of GraphQL subscriptions.

     

       99
       99
       +
        *

     

       100
       100
       +
        * Each value that is part of the result is wrapped in a reactive ref

     

       101
       101
       +
        * and updates as results come in.

     

       102
       102
       +
        *

     

       103
       103
       +
        * Hint: Even when the query and variables update, the prior state of

     

       104
       104
       +
        * the last result is preserved.

     

       105
       105
       +
        */

     

       106
       106
       +
       export interface UseSubscriptionResponse<

     

       37
       107
        
         T = any,

     

       38
       108
        
         R = T,

     

       39
       109
        
         V extends AnyVariables = AnyVariables

     

       40
       110
        
       > {

     

       111
       111
       +
         /** Indicates whether `useSubscription`’s subscription is active.

     

       112
       112
       +
          *

     

       113
       113
       +
          * @remarks

     

       114
       114
       +
          * When `useSubscription` starts a subscription, the `fetching` flag

     

       115
       115
       +
          * is set to `true` and will remain `true` until the subscription

     

       116
       116
       +
          * completes on the API, or `useSubscription` is paused.

     

       117
       117
       +
          */

     

       41
       118
        
         fetching: Ref<boolean>;

     

       119
       119
       +
         /** Indicates that the subscription result is not fresh.

     

       120
       120
       +
          *

     

       121
       121
       +
          * @remarks

     

       122
       122
       +
          * This is mostly unused for subscriptions and will rarely affect you, and

     

       123
       123
       +
          * is more relevant for queries.

     

       124
       124
       +
          *

     

       125
       125
       +
          * @see {@link OperationResult.stale} for the source of this value.

     

       126
       126
       +
          */

     

       42
       127
        
         stale: Ref<boolean>;

     

       128
       128
       +
         /** Reactive {@link OperationResult.data} for the executed subscription, or data returned by the handler.

     

       129
       129
       +
          *

     

       130
       130
       +
          * @remarks

     

       131
       131
       +
          * `data` will be set to the last {@link OperationResult.data} value

     

       132
       132
       +
          * received for the subscription.

     

       133
       133
       +
          *

     

       134
       134
       +
          * It will instead be set to the values that {@link SubscriptionHandler}

     

       135
       135
       +
          * returned, if a handler has been passed to {@link useSubscription}.

     

       136
       136
       +
          */

     

       43
       137
        
         data: Ref<R | undefined>;

     

       138
       138
       +
         /** Reactive {@link OperationResult.error} for the executed subscription. */

     

       44
       139
        
         error: Ref<CombinedError | undefined>;

     

       140
       140
       +
         /** Reactive {@link OperationResult.extensions} for the executed mutation. */

     

       45
       141
        
         extensions: Ref<Record<string, any> | undefined>;

     

       142
       142
       +
         /** Reactive {@link Operation} that the current state is for.

     

       143
       143
       +
          *

     

       144
       144
       +
          * @remarks

     

       145
       145
       +
          * This is the subscription {@link Operation} that is currently active.

     

       146
       146
       +
          * When {@link UseQueryState.fetching} is `true`, this is the

     

       147
       147
       +
          * last `Operation` that the current state was for.

     

       148
       148
       +
          */

     

       46
       149
        
         operation: Ref<Operation<T, V> | undefined>;

     

       150
       150
       +
         /** Indicates whether {@link useSubscription} is currently paused.

     

       151
       151
       +
          *

     

       152
       152
       +
          * @remarks

     

       153
       153
       +
          * When `useSubscription` has been paused, it will stop receiving updates

     

       154
       154
       +
          * from the {@link Client} and won’t execute the subscription, until

     

       155
       155
       +
          * {@link UseSubscriptionArgs.pause} becomes true or

     

       156
       156
       +
          * {@link UseSubscriptionResponse.resume} is called.

     

       157
       157
       +
          */

     

       47
       158
        
         isPaused: Ref<boolean>;

     

       159
       159
       +
         /** Resumes {@link useSubscription} if it’s currently paused.

     

       160
       160
       +
          *

     

       161
       161
       +
          * @remarks

     

       162
       162
       +
          * Resumes or starts {@link useSubscription}’s subscription, if it’s currently paused.

     

       163
       163
       +
          */

     

       48
       164
        
         resume(): void;

     

       165
       165
       +
         /** Pauses {@link useSubscription} to stop the subscription.

     

       166
       166
       +
          *

     

       167
       167
       +
          * @remarks

     

       168
       168
       +
          * Pauses {@link useSubscription}’s subscription, which stops it

     

       169
       169
       +
          * from receiving updates from the {@link Client} and to stop executing

     

       170
       170
       +
          * the subscription operation.

     

       171
       171
       +
          */

     

       49
       172
        
         pause(): void;

     

       173
       173
       +
         /** Triggers {@link useQuery} to reexecute a GraphQL subscription operation.

     

       174
       174
       +
          *

     

       175
       175
       +
          * @param opts - optionally, context options that will be merged with

     

       176
       176
       +
          * {@link UseQueryArgs.context} and the `Client`’s options.

     

       177
       177
       +
          *

     

       178
       178
       +
          * @remarks

     

       179
       179
       +
          * When called, {@link useSubscription} will re-execute the GraphQL subscription

     

       180
       180
       +
          * operation it currently holds, unless it’s currently paused.

     

       181
       181
       +
          */

     

       50
       182
        
         executeSubscription(opts?: Partial<OperationContext>): void;

     

       51
       183
        
       }

     

       52
       184
        
       

     

       53
       53
       -
       export type UseSubscriptionResponse<

     

       54
       54
       -
         T = any,

     

       55
       55
       -
         R = T,

     

       56
       56
       -
         V extends AnyVariables = AnyVariables

     

       57
       57
       -
       > = UseSubscriptionState<T, R, V>;

     

       58
       58
       -
       

     

       59
       185
        
       const watchOptions = {

     

       60
       186
        
         flush: 'pre' as const,

     

       61
       187
        
       };

     

       62
       188
        
       

     

       189
       189
       +
       /** Function to run a GraphQL subscription and get reactive GraphQL results.

     

       190
       190
       +
        *

     

       191
       191
       +
        * @param args - a {@link UseSubscriptionArgs} object, to pass a `query`, `variables`, and options.

     

       192
       192
       +
        * @param handler - optionally, a {@link SubscriptionHandler} function to combine multiple subscription results.

     

       193
       193
       +
        * @returns a {@link UseSubscriptionResponse} object.

     

       194
       194
       +
        *

     

       195
       195
       +
        * @remarks

     

       196
       196
       +
        * `useSubscription` allows GraphQL subscriptions to be defined and executed inside

     

       197
       197
       +
        * Vue `setup` functions.

     

       198
       198
       +
        * Given {@link UseSubscriptionArgs.query}, it executes the GraphQL subscription with the

     

       199
       199
       +
        * provided {@link Client}.

     

       200
       200
       +
        *

     

       201
       201
       +
        * The returned result updates when the `Client` has new results

     

       202
       202
       +
        * for the subscription, and `data` is updated with the result’s data

     

       203
       203
       +
        * or with the `data` that a `handler` returns.

     

       204
       204
       +
        *

     

       205
       205
       +
        * @example

     

       206
       206
       +
        * ```ts

     

       207
       207
       +
        * import { gql, useSubscription } from '@urql/vue';

     

       208
       208
       +
        *

     

       209
       209
       +
        * const NotificationsSubscription = gql`

     

       210
       210
       +
        *   subscription { newNotification { id, text } }

     

       211
       211
       +
        * `;

     

       212
       212
       +
        *

     

       213
       213
       +
        * export default {

     

       214
       214
       +
        *   setup() {

     

       215
       215
       +
        *     const result = useSubscription(

     

       216
       216
       +
        *       { query: NotificationsSubscription },

     

       217
       217
       +
        *       function combineNotifications(notifications = [], data) {

     

       218
       218
       +
        *         return [...notifications, data.newNotification];

     

       219
       219
       +
        *       },

     

       220
       220
       +
        *     );

     

       221
       221
       +
        *     // ...

     

       222
       222
       +
        *   },

     

       223
       223
       +
        * };

     

       224
       224
       +
        * ```

     

       225
       225
       +
        */

     

       63
       226
        
       export function useSubscription<

     

       64
       227
        
         T = any,

     

       65
       228
        
         R = T,

     

       66
       229
        
         V extends AnyVariables = AnyVariables

     

       67
       230
        
       >(

     

       68
       231
        
         args: UseSubscriptionArgs<T, V>,

     

       69
       69
       -
         handler?: SubscriptionHandlerArg<T, R>

     

       232
       232
       +
         handler?: MaybeRef<SubscriptionHandler<T, R>>

     

       70
       233
        
       ): UseSubscriptionResponse<T, R, V> {

     

       71
       234
        
         return callUseSubscription(args, handler);

     

       72
       235
        
       }

     
···

       77
       240
        
         V extends AnyVariables = AnyVariables

     

       78
       241
        
       >(

     

       79
       242
        
         _args: UseSubscriptionArgs<T, V>,

     

       80
       80
       -
         handler?: SubscriptionHandlerArg<T, R>,

     

       243
       243
       +
         handler?: MaybeRef<SubscriptionHandler<T, R>>,

     

       81
       244
        
         client: Ref<Client> = useClient(),

     

       82
       245
        
         stops: WatchStopHandle[] = []

     

       83
       246
        
       ): UseSubscriptionResponse<T, R, V> {

     
···

       159
       322
        
           }, watchOptions)

     

       160
       323
        
         );

     

       161
       324
        
       

     

       162
       162
       -
         const state: UseSubscriptionState<T, R, V> = {

     

       325
       325
       +
         const state: UseSubscriptionResponse<T, R, V> = {

     

       163
       326
        
           data,

     

       164
       327
        
           stale,

     

       165
       328
        
           error,

     
···

       169
       332
        
           isPaused,

     

       170
       333
        
           executeSubscription(

     

       171
       334
        
             opts?: Partial<OperationContext>

     

       172
       172
       -
           ): UseSubscriptionState<T, R, V> {

     

       335
       335
       +
           ): UseSubscriptionResponse<T, R, V> {

     

       173
       336
        
             source.value = client.value.executeSubscription<T, V>(request.value, {

     

       174
       337
        
               ...unwrapPossibleProxy(args.context),

     

       175
       338
        
               ...opts,