diff --git a/site/src/routes/api/fragments.svx b/site/src/routes/api/fragments.svx index 76a029c62..f45074817 100644 --- a/site/src/routes/api/fragments.svx +++ b/site/src/routes/api/fragments.svx @@ -124,14 +124,14 @@ Fragments may also contain a paginated field, similar to queries. A paginated fr ### Return Values -`paginatedQuery` returns a store that holds an object with the following keys: +`paginatedFragment` returns a store that holds an object with the following keys: - `data` contains the fragment's data - `loading` contains a boolean value that tracks the loading state of the pagination requests - `pageInfo` ts contains the page info (`hasPreviousPage`, `hasNextPage`, etc.) Only valid for cursor-based pagination. - `partial` contains a boolean that indicates if the result has a partial match -and has one of the following methods (depending on your fields pagination direction): +The store also has one of the following methods (depending on your fields pagination direction): - `loadNextPage` is an async function that loads the next page. It takes one optional argument: the page size to load for the next request. - `loadPreviousPage` is an async function that loads the previous page. It takes one optional argument: the page size to load for the next request. diff --git a/site/src/routes/api/routes.svx b/site/src/routes/api/query.svx similarity index 90% rename from site/src/routes/api/routes.svx rename to site/src/routes/api/query.svx index cef5a6a76..fb6da1c8c 100644 --- a/site/src/routes/api/routes.svx +++ b/site/src/routes/api/query.svx @@ -1,5 +1,5 @@ --- -title: Routes +title: Query index: 1 description: Queries in Houdini --- @@ -73,7 +73,7 @@ type MyFriendsStore = QueryStore & { ` -# Routes +# Query Load data from the server and subscribe to any changes of fields we detect from mutations, subscriptions, and other queries. @@ -206,7 +206,7 @@ Called after Houdini executes load queries against the server. You can expect th arguments as SvelteKit's [`load`](https://kit.svelte.dev/docs#loading) function, plus an additional `data` property referencing query result data. Keep in mind that if you define this hook, Houdini will have to block requests to the route in order to wait for the result. For more information about -blocking during navigation, check out [this section](/api/query/store#server-side-blocking) of the query store +blocking during navigation, check out the deep dive in [this section](/api/query#manual-loading) of the query store docs. ```javascript @@ -245,7 +245,7 @@ If defined, the load function will invoked this function instead of throwing an It receives three inputs: the load event, the inputs for each query, and the error that was encountered. Just like the other hooks, `onError` can return an object that provides props to the route. If you do define this hook, Houdini will have to block requests to the route in order to wait for the result. For more information about -blocking during navigation, check out [this section](/api/query/store#server-side-blocking) of the query store +blocking during navigation, check out the deep dive in [this section](/api/query#manual-loading) of the query store docs. ```javascript @@ -323,6 +323,23 @@ export async function load(event) { } ``` +If you are defining a manual load and need to look at the result of the fetch, we recommend _not_ using the `load_` +utility but instead defining your load explicitly: + +```javascript +import { MyQueryStore } from '$houdini' + +export async function load(event) { + const MyQuery = new MyQueryStore() + + const result = await MyQuery.fetch(event) + + console.log('do something with', result) + + return { MyQuery } +} +``` + Be careful when loading multiple stores at once. @@ -434,6 +451,36 @@ export async function get(event) { } ``` +## Passing Metadata + +Sometimes you need to do something very custom for a specific route. Maybe you need special headers or some other contextual information. +Whatever the case may be, you can pass a `metadata` parameter to fetch: + +```svelte + + + +``` + +This value will get forwarded to the network function in your client definition, usually found in `src/client.js`: + +```typescript +async function fetchQuery({ fetch, text, variables, session, metadata }) { + // do anything with metadata inside of here +} + +// Export the Houdini client +export default new HoudiniClient(fetchQuery) +``` + ## Paginated Queries If the query contains the pagination directive then the generated store will have extra fields/methods diff --git a/site/src/routes/api/subscription.svx b/site/src/routes/api/subscription.svx index 93a55da28..b95ce4634 100644 --- a/site/src/routes/api/subscription.svx +++ b/site/src/routes/api/subscription.svx @@ -16,48 +16,7 @@ Listen for real-time updates from your server using GraphQL Subscriptions. export let itemID // will start listening onMount (browser only) - subscription( - graphql` - subscription ItemUpdate($id: ID!) { - itemUpdate(id: $id) { - item { - id - completed - text - } - } - } - `, - { id: itemID } - ) - -``` - -### Inputs - -1. A string tagged with `graphql` containing a single document with one named subscription -2. An object containing any arguments for the subscription - -### Return Values - -`subscription` returns a store containing the latest version of the subscription value - -Note: mutations usually do best when combined with at least one fragment grabbing -the information needed for the mutation (for an example of this pattern, see below.) - -## External Documents - -Subscriptions defined in external documents can be trigger using the subscription store's `listen` method: - -```svelte - - - +latest value: {$updates.itemUpdate.item.text} ``` +Subscriptions can be defined like any other document and are triggered using the subscription store's `listen` method: + ## List Operations Subscription bodies can contain all of the list operations described in [this document](/api/mutation#lists). diff --git a/site/src/routes/api/welcome.svx b/site/src/routes/api/welcome.svx index 08f3751e6..2bf6d7d28 100644 --- a/site/src/routes/api/welcome.svx +++ b/site/src/routes/api/welcome.svx @@ -74,18 +74,14 @@ export default { # Houdini API Reference -Every GraphQL document in your Houdini application has two different ways of interacting with it. You can either define -your document inside of your svelte components or in an external file. While the approaches are equivalent, their APIs -do vary slightly for the situation. In order to accommodate this, each document page has a toggle in the top right to flip between the store -and inline APIs. For more information about the differences in the APIs, checkout out the -[Working With GraphQL](/guides/working-with-graphql) guide. +Every GraphQL document in your Houdini application is driven by a Svelte store with specific methods for performing each task. ## GraphQL Documents @@ -129,7 +125,7 @@ example={configExample} diff --git a/site/src/routes/guides/authentication.svx b/site/src/routes/guides/authentication.svx index 0a7237f19..adb005491 100644 --- a/site/src/routes/guides/authentication.svx +++ b/site/src/routes/guides/authentication.svx @@ -26,7 +26,7 @@ export async function handle({ event, resolve }) { } ``` -The only thing that's left is to use the `session` parameter passed to your client's network function to access the information: +Then, you can use the `session` parameter passed to your client's network function to access the information: ```typescript /// src/lib/client.ts diff --git a/site/src/routes/guides/caching-data.svx b/site/src/routes/guides/caching-data.svx index afe012135..e4b802006 100644 --- a/site/src/routes/guides/caching-data.svx +++ b/site/src/routes/guides/caching-data.svx @@ -40,8 +40,7 @@ A lot of the time we know the value that a mutation will trigger assuming everyt