houdini 0.10.7 → 0.11.1

package/README.md

@@ -11,9 +11,6 @@
   <br />
 </div>
 
-NOTE: Houdini is in the early phases of development. Please create an issue or start a discussion if you run into problems. For more information on what's coming for this project, you can visit the
-[roadmap](https://github.com/AlecAivazis/houdini/projects/1).
-
 If you are interested in helping out, the [contributing guide](./CONTRIBUTING.md) should provide some guidance. If you need something more
 specific, feel free to reach out to @AlecAivazis on the Svelte discord. There's lots to do regardless of how deep you want to dive 🙂
 
@@ -45,8 +42,11 @@ for the generation of an incredibly lean GraphQL abstraction for your applicatio
 1. [Fetching Data](#fetching-data)
     1. [Query variables and page data](#query-variables-and-page-data)
     1. [Loading State](#loading-state)
-    1. [Refetching Data](#refetching-data)
     1. [Additional Logic](#additional-logic)
+    1. [Refetching Data](#refetching-data)
+    1. [Cache policy](#cache-policy)
+        1. [Data Retention](#data-retention)
+        1. [Changing default cache policy](#changing-default-cache-policy)
     1. [What about load?](#what-about-load)
 1. [Fragments](#fragments)
     1. [Fragment Arguments](#fragment-arguments)
@@ -90,18 +90,19 @@ npm install --save-dev houdini houdini-preprocess
 
 Adding houdini to an existing project can easily be done with the provided command-line tool.
 If you don't already have an existing app, visit [this link](https://kit.svelte.dev/docs)
-for help setting one up. Once you have a project and want to add houdini, execute the following command:
+for help setting one up. Once you have a project and want to add houdini, execute the following command which will create a few necessary files, as well as pull down a json
+representation of your API's schema.
 
 ```sh
 npx houdini init
 ```
 
-This will create a few necessary files, as well as pull down a json representation of
-your API's schema. Next, generate your runtime:
-
-```sh
-npx houdini generate
-```
+> This will send a request to your API to download your schema definition. If you need
+> headers to authenticate this request, you can pass them in with the `--pull-header`
+> flag (abbreviated `-ph`). For example,
+> `npx houdini init -ph Authorization="Bearer MyToken"`.
+> You will also need to provide the same flag to `generate` when using the
+> `--pull-schema` flag.
 
 Finally, follow the steps appropriate for your framework.
 
@@ -115,7 +116,7 @@ import houdini from 'houdini-preprocess'
 
 {
     preprocess: [houdini()],
-    
+
     kit: {
         vite: {
             resolve: {
@@ -328,9 +329,9 @@ the result of query:
 
 ### Additional logic
 
-Sometimes you will need to add additional logic to a component's query. For example, you might want to 
+Sometimes you will need to add additional logic to a component's query. For example, you might want to
 check if the current session is valid before a query is sent to the server. In order to support this,
-houdini will look for a function called `onLoad` defined in the module context which can be used to perform 
+houdini will look for a function called `onLoad` defined in the module context which can be used to perform
 any logic you need. If you return a value from this function, it will be passed as props to your component:
 
 ```svelte
@@ -340,11 +341,11 @@ any logic you need. If you return a value from this function, it will be passed
         if(!session.authenticated){
             return this.redirect(302, '/login')
         }
-	
+
 	return {
 	    message: "There are this many items"
         }
-    } 
+    }
 </script>
 
 <script>
@@ -392,6 +393,64 @@ Refetching data is done with the `refetch` function provided from the result of
 <input type=checkbox bind:checked={completed}>
 ```
 
+### Cache policy
+
+By default, houdini will only try to load queries against its local cache when you indicate it is safe to do so.
+This can be done with the `@cache` directive:
+
+```graphql
+query AllItems @cache(policy: CacheOrNetwork) {
+    items {
+        id
+        text
+    }
+}
+```
+
+There are 3 different policies that can be specified:
+
+- **CacheOrNetwork** will first check if a query can be resolved from the cache. If it can, it will return the cached value and only send a network request if data was missing.
+- **CacheAndNetwork** will use cached data if it exists and always send a network request after the component has mounted to retrieve the latest data from the server
+- **NetworkOnly** will never check if the data exists in the cache and always send a network request
+
+#### Data Retention
+
+Houdini will retain a query's data for a configurable number of queries (default 10).
+For a concrete example, consider an example app that has 3 routes. If you load one of the
+routes and then click between the other two 5 times, the first route's data will still be
+resolvable (and the counter will reset if you visit it).
+If you then toggle between the other routes 10 times and then try to load the first
+route, a network request will be sent. This number is configurable with the
+`cacheBufferSize` value in your config file:
+
+```js
+// houdini.config.js
+
+export default {
+    // ...
+    cacheBufferSize: 5,
+}
+```
+
+#### Changing default cache policy
+
+As previously mentioned, the default cache policy is `CacheOrNetwork`. This can be changed
+by setting the `defaultCachePolicy` config value:
+
+```js
+// houdini.config.js
+
+import { CachePolicy } from '$houdini'
+
+export default {
+    // ...
+
+    // note: if you are upgrading from a previous version of houdini, you might
+    // have to generate your runtime for this type to be defined.
+    defaultCachePolicy: CachePolicy.NetworkOnly,
+}
+```
+
 ### What about `load`?
 
 Don't worry - that's where the preprocessor comes in. One of its responsibilities is moving the actual
@@ -975,7 +1034,7 @@ export default new Environment(async function ({ text, variables = {} }, session
 
 ## 🚦&nbsp;&nbsp;Persisted Queries
 
-Sometimes you want to confine an API to only fire a set of pre-defined queries. This 
+Sometimes you want to confine an API to only fire a set of pre-defined queries. This
 can be useful to not only reduce the amount of information transferred over the write
 but also act as a list of approved queries, providing additional security. Regardless of
 your motivation, the approach involves associating a known string with a particular query
@@ -984,10 +1043,10 @@ houdini passes a queries hash to the fetch function for you to use.
 
 ### Automatic Persisted Queries
 
-An approach to Persisted Queries, popularized by Apollo, is known as 
-[Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/). 
+An approach to Persisted Queries, popularized by Apollo, is known as
+[Automatic Persisted Queries](https://www.apollographql.com/docs/apollo-server/performance/apq/).
 This involves first sending a queries hash and if its unrecognized, sending the full
-query string. This might look something like: 
+query string. This might look something like:
 
 ```typescript
 /// src/environment.ts
@@ -1023,7 +1082,7 @@ export default new Environment(async function({ text, variables = {}, hash }){
 		return response
 	}
 
-	// there were errors, send the hash and the query to associate the two for 
+	// there were errors, send the hash and the query to associate the two for
 	// future requests
 	return await sendFetch.call(this, { variables, hash, text })
 })
@@ -1044,7 +1103,7 @@ npx houdini generate -po ./path/to/persisted-queries.json
 
 Once this map has been created, you will have to make it available to your server.
 
-Now, instead of sending the full operation text with every request, you can now simply 
+Now, instead of sending the full operation text with every request, you can now simply
 pass the hash under whatever field name you prefer:
 
 ```typescript

package/build/cmd/generate.js

@@ -66,6 +66,8 @@ var promises_1 = __importDefault(require("fs/promises"));
 var graphql = __importStar(require("graphql"));
 var util_1 = require("util");
 var houdini_common_1 = require("houdini-common");
+// locals
+var types_1 = require("./types");
 var transforms = __importStar(require("./transforms"));
 var generators = __importStar(require("./generators"));
 var validators = __importStar(require("./validators"));
@@ -199,9 +201,30 @@ function collectDocuments(config) {
                                                                         throw new Error('Fragment documents can only have one fragment');
                                                                     }
                                                                 }
+                                                                // figure out the document kind
+                                                                var kind = types_1.ArtifactKind.Fragment;
+                                                                if (operations.length === 1) {
+                                                                    // the document kind depends on the artifact
+                                                                    // query
+                                                                    if (operations[0].kind === 'OperationDefinition' &&
+                                                                        operations[0].operation === 'query') {
+                                                                        kind = types_1.ArtifactKind.Query;
+                                                                    }
+                                                                    // mutation
+                                                                    else if (operations[0].kind === 'OperationDefinition' &&
+                                                                        operations[0].operation === 'mutation') {
+                                                                        kind = types_1.ArtifactKind.Mutation;
+                                                                    }
+                                                                    // subscription
+                                                                    else if (operations[0].kind === 'OperationDefinition' &&
+                                                                        operations[0].operation === 'subscription') {
+                                                                        kind = types_1.ArtifactKind.Subcription;
+                                                                    }
+                                                                }
                                                                 // add it to the list
                                                                 documents.push({
                                                                     name: config.documentName(parsedDoc),
+                                                                    kind: kind,
                                                                     document: parsedDoc,
                                                                     filename: filePath,
                                                                     originalDocument: parsedDoc,

package/build/cmd/generators/artifacts/index.js

@@ -103,7 +103,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // externals
 var houdini_common_1 = require("houdini-common");
 var graphql = __importStar(require("graphql"));
-var types_1 = require("../../types");
 var recast = __importStar(require("recast"));
 // locals
 var utils_1 = require("../../utils");
@@ -112,6 +111,7 @@ var operations_1 = require("./operations");
 var indexFile_1 = __importDefault(require("./indexFile"));
 var inputs_1 = require("./inputs");
 var utils_2 = require("./utils");
+var types_1 = require("../../../runtime/types");
 var AST = recast.types.builders;
 // the artifact generator creates files in the runtime directory for each
 // document containing meta data that the preprocessor might use
@@ -185,10 +185,10 @@ function artifactGenerator(config, docs) {
                         ].concat(
                         // and an artifact for every document
                         docs.map(function (doc) { return __awaiter(_this, void 0, void 0, function () {
-                            var document, name, generate, rawString, docKind, operations, fragments, operation, rootType, selectionSet, operation, matchingFragment, inputs, artifact, file;
-                            var _a, _b, _c, _d;
-                            return __generator(this, function (_e) {
-                                switch (_e.label) {
+                            var document, name, generate, rawString, docKind, operations, fragments, rootType, selectionSet, operation, matchingFragment, inputs, artifact, cacheDirective, policy, file;
+                            var _a, _b, _c, _d, _e, _f;
+                            return __generator(this, function (_g) {
+                                switch (_g.label) {
                                     case 0:
                                         document = doc.document, name = doc.name, generate = doc.generate;
                                         // if the document is generated, don't write it to disk - it's use is to provide definitions
@@ -204,7 +204,7 @@ function artifactGenerator(config, docs) {
                                                 }
                                             },
                                         }));
-                                        docKind = null;
+                                        docKind = doc.kind;
                                         operations = document.definitions.filter(function (_a) {
                                             var kind = _a.kind;
                                             return kind === graphql.Kind.OPERATION_DEFINITION;
@@ -213,33 +213,9 @@ function artifactGenerator(config, docs) {
                                             var kind = _a.kind;
                                             return kind === graphql.Kind.FRAGMENT_DEFINITION;
                                         });
-                                        // if there are operations in the document
-                                        if (operations.length > 0 && operations[0].kind === 'OperationDefinition') {
-                                            operation = operations[0].operation;
-                                            // figure out if its a query
-                                            if (operation === 'query') {
-                                                docKind = types_1.CompiledQueryKind;
-                                            }
-                                            // or a mutation
-                                            else if (operation === 'mutation') {
-                                                docKind = types_1.CompiledMutationKind;
-                                            }
-                                            // or a subscription
-                                            else if (operation === 'subscription') {
-                                                docKind = types_1.CompiledSubscriptionKind;
-                                            }
-                                        }
-                                        // if there are operations in the document
-                                        else if (fragments.length > 0) {
-                                            docKind = types_1.CompiledFragmentKind;
-                                        }
-                                        // if we couldn't figure out the kind
-                                        if (!docKind) {
-                                            throw new Error('Could not figure out what kind of document we were given');
-                                        }
                                         rootType = '';
                                         // if we are generating the artifact for an operation
-                                        if (docKind !== 'HoudiniFragment') {
+                                        if (docKind !== types_1.ArtifactKind.Fragment) {
                                             operation = operations[0];
                                             if (operation.operation === 'query') {
                                                 rootType = (_a = config.schema.getQueryType()) === null || _a === void 0 ? void 0 : _a.name;
@@ -278,7 +254,7 @@ function artifactGenerator(config, docs) {
                                             selection: selection_1.default({
                                                 config: config,
                                                 rootType: rootType,
-                                                selectionSet: selectionSet,
+                                                selections: selectionSet.selections,
                                                 operations: operations_1.operationsByPath(config, operations[0], filterTypes),
                                                 // do not include used fragments if we are rendering the selection
                                                 // for a fragment document
@@ -291,6 +267,22 @@ function artifactGenerator(config, docs) {
                                         if (inputs && inputs.length > 0) {
                                             artifact.input = inputs_1.inputObject(config, inputs);
                                         }
+                                        // add the cache policy to query documents
+                                        if (docKind === 'HoudiniQuery') {
+                                            cacheDirective = (_e = operations[0].directives) === null || _e === void 0 ? void 0 : _e.find(function (directive) { return directive.name.value === config.cacheDirective; });
+                                            if (cacheDirective) {
+                                                policy = (_f = cacheDirective.arguments) === null || _f === void 0 ? void 0 : _f.find(function (arg) { return arg.name.value === config.cachePolicyArg; });
+                                                if (policy && policy.value.kind === 'EnumValue') {
+                                                    artifact.policy = policy.value.value;
+                                                }
+                                                else {
+                                                    artifact.policy = config.defaultCachePolicy;
+                                                }
+                                            }
+                                            else {
+                                                artifact.policy = config.defaultCachePolicy;
+                                            }
+                                        }
                                         file = AST.program([
                                             utils_1.moduleExport(config, 'default', utils_2.serializeValue(artifact)),
                                         ]);
@@ -300,7 +292,7 @@ function artifactGenerator(config, docs) {
                                         ];
                                     case 1:
                                         // write the result to the artifact path we're configured to write to
-                                        _e.sent();
+                                        _g.sent();
                                         // log the file location to confirm
                                         if (!config.quiet) {
                                             console.log(name);

package/build/cmd/generators/artifacts/selection.d.ts

@@ -2,10 +2,10 @@ import { Config } from 'houdini-common';
 import * as graphql from 'graphql';
 import { CollectedGraphQLDocument } from '../../types';
 import type { MutationOperation, SubscriptionSelection } from '../../../runtime';
-export default function selection({ config, rootType, selectionSet, operations, path, includeFragments, document, markEdges, }: {
+export default function selection({ config, rootType, selections, operations, path, includeFragments, document, markEdges, }: {
     config: Config;
     rootType: string;
-    selectionSet: graphql.SelectionSetNode;
+    selections: readonly graphql.SelectionNode[];
     operations: {
         [path: string]: MutationOperation[];
     };

package/build/cmd/generators/artifacts/selection.js

@@ -56,7 +56,7 @@ var AST = recast.types.builders;
 function selection(_a) {
     var e_1, _b;
     var _c, _d, _e, _f, _g, _h, _j;
-    var config = _a.config, rootType = _a.rootType, selectionSet = _a.selectionSet, operations = _a.operations, _k = _a.path, path = _k === void 0 ? [] : _k, includeFragments = _a.includeFragments, document = _a.document, markEdges = _a.markEdges;
+    var config = _a.config, rootType = _a.rootType, selections = _a.selections, operations = _a.operations, _k = _a.path, path = _k === void 0 ? [] : _k, includeFragments = _a.includeFragments, document = _a.document, markEdges = _a.markEdges;
     // we need to build up an object that contains every field in the selection
     var object = {};
     var _loop_1 = function (field) {
@@ -72,7 +72,7 @@ function selection(_a) {
                 config: config,
                 rootType: fragmentDefinition.typeCondition.name.value,
                 operations: operations,
-                selectionSet: fragmentDefinition.selectionSet,
+                selections: fragmentDefinition.selectionSet.selections,
                 path: path,
                 includeFragments: includeFragments,
                 document: document,
@@ -84,7 +84,7 @@ function selection(_a) {
                 config: config,
                 rootType: ((_c = field.typeCondition) === null || _c === void 0 ? void 0 : _c.name.value) || rootType,
                 operations: operations,
-                selectionSet: field.selectionSet,
+                selections: field.selectionSet.selections,
                 path: path,
                 includeFragments: includeFragments,
                 document: document,
@@ -156,7 +156,7 @@ function selection(_a) {
                 fieldObj.fields = selection({
                     config: config,
                     rootType: typeName,
-                    selectionSet: field.selectionSet,
+                    selections: field.selectionSet.selections,
                     operations: operations,
                     path: pathSoFar,
                     includeFragments: includeFragments,
@@ -180,15 +180,15 @@ function selection(_a) {
         }
     };
     try {
-        for (var _l = __values(selectionSet.selections), _m = _l.next(); !_m.done; _m = _l.next()) {
-            var field = _m.value;
+        for (var selections_1 = __values(selections), selections_1_1 = selections_1.next(); !selections_1_1.done; selections_1_1 = selections_1.next()) {
+            var field = selections_1_1.value;
             _loop_1(field);
         }
     }
     catch (e_1_1) { e_1 = { error: e_1_1 }; }
     finally {
         try {
-            if (_m && !_m.done && (_b = _l.return)) _b.call(_l);
+            if (selections_1_1 && !selections_1_1.done && (_b = selections_1.return)) _b.call(selections_1);
         }
         finally { if (e_1) throw e_1.error; }
     }

package/build/cmd/generators/runtime/adapter.js

@@ -65,6 +65,6 @@ function generateAdapter(config) {
     });
 }
 exports.default = generateAdapter;
-var sapperAdapter = "import { stores, goto as go } from '@sapper/app'\n\nexport function getSession() {\n    return stores().session\n}\n\nexport function goTo(location, options) {\n    go(location, options)\n}\n";
-var sveltekitAdapter = "import { goto as go } from '$app/navigation'\nimport { getStores } from '$app/stores'\n\nexport function getSession() {\n    return getStores().session\n}\n\nexport function goTo(location, options) {\n    go(location, options)\n}\n";
-var svelteAdapter = "\nexport function getSession() {\n\treturn {}\n}\n\nexport function goTo(location, options) {\n\twindow.location = location\n}\n";
+var sapperAdapter = "import { stores, goto as go } from '@sapper/app'\n\nexport function getSession() {\n    return stores().session\n}\n\nexport function goTo(location, options) {\n    go(location, options)\n}\n\nexport const isBrowser = process.browser\n";
+var sveltekitAdapter = "import { goto as go } from '$app/navigation'\nimport { getStores } from '$app/stores'\nimport { browser } from '$app/env'\n\nexport function getSession() {\n    return getStores().session\n}\n\nexport function goTo(location, options) {\n    go(location, options)\n}\n\nexport const isBrowser = browser\n";
+var svelteAdapter = "\nexport function getSession() {\n\treturn {}\n}\n\nexport function goTo(location, options) {\n\twindow.location = location\n}\n\nexport const isBrowser = true\n";