houdini 1.5.4 → 2.0.0-next.0

package/build/runtime-esm/client/documentStore.js

@@ -13,9 +13,14 @@ class DocumentStore extends Writable {
   artifact;
   #client;
   #configFile;
+  // the list of instantiated plugins
   #plugins;
+  // we need to track the last set of variables used so we can
+  // detect if they have changed
   #lastVariables;
+  // we need the last context value we've seen in order to pass it during cleanup
   #lastContext = null;
+  // a reference to the earliest resolving open promise that the store has sent
   pendingPromise = null;
   serverSideFallback;
   controllerKey(variables) {
@@ -54,6 +59,7 @@ class DocumentStore extends Writable {
     this.#lastVariables = null;
     this.#configFile = getCurrentConfig();
     this.#plugins = pipeline ?? [
+      // cache policy needs to always come first so that it can be the first network to fire
       cachePolicy({
         cache,
         enabled: enableCache,
@@ -70,6 +76,7 @@ class DocumentStore extends Writable {
       ...plugins ?? []
     ];
   }
+  // used by the client to send a new set of variables to the pipeline
   async send({
     metadata,
     session,
@@ -136,6 +143,7 @@ class DocumentStore extends Writable {
           reject,
           then: (...args) => promise.then(...args)
         },
+        // patch the context with new variables
         context
       };
       if (this.pendingPromise === null) {
@@ -214,7 +222,14 @@ class DocumentStore extends Writable {
         marshalVariables,
         updateState: this.update.bind(this),
         next: (newContext) => {
-          const nextIndex = ["forward", "error"].includes(direction) ? index + 1 : index;
+          const nextIndex = ["forward", "error"].includes(direction) ? (
+            // if we're going forward, add one
+            index + 1
+          ) : (
+            // if we're moving backwards but called next, we
+            // we need to invoke the same hook
+            index
+          );
           const nextStep = ["backwards", "error"].includes(direction) ? 0 : ctx.currentStep;
           this.#step("forward", {
             ...ctx,
@@ -224,7 +239,14 @@ class DocumentStore extends Writable {
           });
         },
         resolve: (newContext, value2) => {
-          const nextIndex = direction === "backwards" ? index - 1 : index;
+          const nextIndex = direction === "backwards" ? (
+            // if we're going backwards, subtract one
+            index - 1
+          ) : (
+            // if we're moving forwards but then call resolve
+            // we need to visit the same hook
+            index
+          );
           this.#step(
             "backwards",
             {
@@ -321,6 +343,7 @@ class DocumentStore extends Writable {
   }
 }
 class ClientPluginContextWrapper {
+  // separate the last variables from what we pass to the user
   #context;
   #lastVariables;
   constructor({
@@ -333,6 +356,8 @@ class ClientPluginContextWrapper {
   get variables() {
     return this.#context.variables;
   }
+  // draft produces a wrapper over the context so users can mutate it without
+  // actually affecting the context values
   draft() {
     const ctx = {
       ...this.#context
@@ -400,6 +425,7 @@ class ClientPluginContextWrapper {
     };
     return ctx;
   }
+  // apply applies the draft value in a new context
   apply(values, newVariables) {
     if (newVariables) {
       values = this.applyVariables(this.#context, values);

package/build/runtime-esm/client/index.js

@@ -15,7 +15,9 @@ import pluginsFromPlugins from "./plugins/injectedPlugins";
 import { DocumentStore as DocumentStore2 } from "./documentStore";
 import { fetch, mutation, query, subscription } from "./plugins";
 class HoudiniClient {
+  // the URL of the api
   url;
+  // expose operations settings
   throwOnError_operations;
   cache = null;
   throwOnError;
@@ -23,7 +25,9 @@ class HoudiniClient {
   pipeline;
   extraPlugins;
   proxies = {};
+  // this is modified by page entries when they load in order to register the components source
   componentCache = {};
+  // we need the ability to link the client up with an external cache
   setCache(cache) {
     this.cache = cache;
   }
@@ -50,16 +54,24 @@ class HoudiniClient {
   get plugins() {
     return flatten(
       [].concat(
+        // if they specified a throw behavior
         this.throwOnError ? [throwOnErrorPlugin(this.throwOnError)] : [],
         fetchParamsPlugin(this.fetchParams),
-        this.pipeline ?? [
+        // if the user wants to specify the entire pipeline, let them do so
+        this.pipeline ?? // the user doesn't have a specific pipeline so we should just add their desired plugins
+        // to the standard set
+        [
           optimisticKeys(this.cache ?? cacheRef),
+          // make sure that documents always work
           queryPlugin(this.cache ?? cacheRef),
           mutationPlugin(this.cache ?? cacheRef),
           fragmentPlugin(this.cache ?? cacheRef)
         ].concat(
+          // add the specified middlewares
           this.extraPlugins ?? [],
+          // and any middlewares we got from plugins
           pluginsFromPlugins,
+          // if they provided a fetch function, use it as the body for the fetch middleware
           fetchPlugin()
         )
       )

package/build/runtime-esm/client/plugins/cache.js

@@ -20,7 +20,8 @@ const cachePolicy = ({
             variables: marshalVariables(ctx),
             fullCheck: true
           });
-          const allowed = !value.partial || artifact.kind === ArtifactKind.Query && artifact.partial;
+          const allowed = !value.partial || // or the artifact allows for partial responses
+          artifact.kind === ArtifactKind.Query && artifact.partial;
           if (policy === CachePolicy.CacheOnly) {
             return resolve(ctx, {
               fetching: false,
@@ -44,7 +45,8 @@ const cachePolicy = ({
               stale: value.stale
             });
           }
-          if (useCache && !value.partial && !value.stale && ctx.policy !== "CacheAndNetwork") {
+          if (useCache && !value.partial && !value.stale && // if the policy is CacheAndNetwork then we don't want to stop here regardless
+          ctx.policy !== "CacheAndNetwork") {
             return;
           }
         }

package/build/runtime-esm/client/plugins/fetch.js

@@ -25,6 +25,8 @@ const fetch = (target) => {
           }
         }
         const result = await fetchFn({
+          // wrap the user's fetch function so we can identify SSR by checking
+          // the response.url
           fetch: (url, args) => {
             const newArgs = handleMultipart(fetchParams, args) ?? args;
             return fetch2(url, {
@@ -117,8 +119,7 @@ function isExtractableFile(value) {
   return typeof File !== "undefined" && value instanceof File || typeof Blob !== "undefined" && value instanceof Blob;
 }
 function extractFiles(value) {
-  if (!arguments.length)
-    throw new TypeError("Argument 1 `value` is required.");
+  if (!arguments.length) throw new TypeError("Argument 1 `value` is required.");
   const clones = /* @__PURE__ */ new Map();
   const files = /* @__PURE__ */ new Map();
   function recurse(value2, path, recursed) {
@@ -133,8 +134,16 @@ function extractFiles(value) {
       let clone = clones.get(value2);
       const uncloned = !clone;
       if (uncloned) {
-        clone = valueIsList ? [] : value2 instanceof Object ? {} : /* @__PURE__ */ Object.create(null);
-        clones.set(value2, clone);
+        clone = valueIsList ? [] : (
+          // Replicate if the plain object is an `Object` instance.
+          value2 instanceof /** @type {any} */
+          Object ? {} : /* @__PURE__ */ Object.create(null)
+        );
+        clones.set(
+          value2,
+          /** @type {Clone} */
+          clone
+        );
       }
       if (!recursed.has(value2)) {
         const pathPrefix = path ? `${path}.` : "";
@@ -143,8 +152,7 @@ function extractFiles(value) {
           let index = 0;
           for (const item of value2) {
             const itemClone = recurse(item, pathPrefix + index++, recursedDeeper);
-            if (uncloned)
-              clone.push(itemClone);
+            if (uncloned) clone.push(itemClone);
           }
         } else
           for (const key in value2) {

package/build/runtime-esm/client/plugins/fetchParams.js

@@ -3,11 +3,13 @@ const fetchParams = (fn = () => ({})) => () => ({
     next({
       ...ctx,
       fetchParams: fn({
+        // most of the stuff comes straight from the context
         config: ctx.config,
         policy: ctx.policy,
         metadata: ctx.metadata,
         session: ctx.session,
         stuff: ctx.stuff,
+        // a few fields are renamed or modified
         document: ctx.artifact,
         variables: marshalVariables(ctx),
         text: ctx.text,

package/build/runtime-esm/client/plugins/fragment.js

@@ -5,6 +5,7 @@ const fragment = (cache) => documentPlugin(ArtifactKind.Fragment, function() {
   let subscriptionSpec = null;
   let lastReference = null;
   return {
+    // establish the cache subscription
     start(ctx, { next, resolve, variablesChanged, marshalVariables }) {
       if (!ctx.stuff.parentID) {
         return next(ctx);

package/build/runtime-esm/client/plugins/mutation.js

@@ -10,6 +10,7 @@ const mutation = (cache) => documentPlugin(ArtifactKind.Mutation, () => {
       if (optimisticResponse) {
         toNotify = cache.write({
           selection: ctx.artifact.selection,
+          // make sure that any scalar values get processed into something we can cache
           data: await marshalSelection({
             selection: ctx.artifact.selection,
             data: optimisticResponse
@@ -20,8 +21,13 @@ const mutation = (cache) => documentPlugin(ArtifactKind.Mutation, () => {
       }
       ctx.cacheParams = {
         ...ctx.cacheParams,
+        // write to the mutation's layer
         layer: layerOptimistic,
+        // notify any subscribers that we updated with the optimistic response
+        // in order to address situations where the optimistic update was wrong
         notifySubscribers: toNotify,
+        // make sure that we notify subscribers for any values that we compare
+        // in order to address any race conditions when comparing the previous value
         forceNotify: true
       };
       next(ctx);

package/build/runtime-esm/client/plugins/optimisticKeys.js

@@ -23,6 +23,8 @@ const optimisticKeys = (cache, callbackCache = callbacks, keyCache = keys, objec
       }
       next(newCtx);
     },
+    // if a request has variables that contain an optimistic key we need to block the
+    // request before it is sent to the server
     beforeNetwork(ctx, { next }) {
       if (Object.keys(keyCache).length === 0) {
         return next(ctx);
@@ -72,6 +74,7 @@ const optimisticKeys = (cache, callbackCache = callbacks, keyCache = keys, objec
       }
       resolve(ctx);
     },
+    // when the mutation ends, we no longer have any dependents that we have to track
     end(ctx, { resolve }) {
       if (typeof ctx.stuff.mutationID !== "undefined") {
         delete keyCache[ctx.stuff.mutationID];
@@ -270,13 +273,13 @@ function replaceKeyWithVariable(variables, keys2) {
 }
 function generateKey(type) {
   if (type === "Int") {
-    return new Date().getTime();
+    return (/* @__PURE__ */ new Date()).getTime();
   }
   if (type === "String") {
-    return new Date().getTime().toString();
+    return (/* @__PURE__ */ new Date()).getTime().toString();
   }
   if (type === "ID") {
-    return new Date().getTime().toString();
+    return (/* @__PURE__ */ new Date()).getTime().toString();
   }
   throw new Error(
     `unsupported type for optimistic key: ${type}. Please provide a value in your mutation arguments.`

package/build/runtime-esm/client/plugins/query.js

@@ -10,6 +10,8 @@ const query = (cache) => documentPlugin(ArtifactKind.Query, function() {
       };
       ctx.variables = {
         ...lastVariables,
+        // we need to evaluate any runtime scalars but allow the user to overwrite them
+        // by explicitly passing variables
         ...Object.fromEntries(
           Object.entries(ctx.artifact.input?.runtimeScalars ?? {}).map(
             ([field, type]) => {
@@ -25,6 +27,8 @@ const query = (cache) => documentPlugin(ArtifactKind.Query, function() {
       };
       next(ctx);
     },
+    // patch subscriptions on the way out so that we don't get a cache update
+    // before the promise resolves
     end(ctx, { resolve, marshalVariables, variablesChanged }) {
       if (variablesChanged(ctx) && !ctx.cacheParams?.disableSubscriptions) {
         if (subscriptionSpec) {

package/build/runtime-esm/lib/deepEquals.js

@@ -1,6 +1,5 @@
 function deepEquals(objA, objB, map = /* @__PURE__ */ new WeakMap()) {
-  if (Object.is(objA, objB))
-    return true;
+  if (Object.is(objA, objB)) return true;
   if (objA instanceof Date && objB instanceof Date) {
     return objA.getTime() === objB.getTime();
   }
@@ -10,8 +9,7 @@ function deepEquals(objA, objB, map = /* @__PURE__ */ new WeakMap()) {
   if (typeof objA !== "object" || objA === null || typeof objB !== "object" || objB === null) {
     return false;
   }
-  if (map.get(objA) === objB)
-    return true;
+  if (map.get(objA) === objB) return true;
   map.set(objA, objB);
   const keysA = Reflect.ownKeys(objA);
   const keysB = Reflect.ownKeys(objB);

package/build/runtime-esm/lib/pagination.js

@@ -119,7 +119,8 @@ function cursorHandlers({
       const queryVariables = {};
       const count = countPage(artifact.refetch.path.concat("edges"), getState()) || artifact.refetch.pageSize;
       if (count && count > artifact.refetch.pageSize) {
-        if (currentPageInfo.hasPreviousPage && currentPageInfo.hasNextPage && !(variables?.["first"] && variables?.["after"] || variables?.["last"] && variables?.["before"])) {
+        if (currentPageInfo.hasPreviousPage && currentPageInfo.hasNextPage && // only log if they haven't provided special parameters
+        !(variables?.["first"] && variables?.["after"] || variables?.["last"] && variables?.["before"])) {
           console.warn(`\u26A0\uFE0F Encountered a fetch() in the middle of the connection.
 Make sure to pass a cursor value by hand that includes the current set (ie the entry before startCursor)
 `);

package/build/runtime-esm/lib/types.js

@@ -31,8 +31,17 @@ const RefetchUpdateMode = {
   replace: "replace"
 };
 const DataSource = {
+  /**
+   * from the browser cache
+   */
   Cache: "cache",
+  /**
+   * from a browser side `fetch`
+   */
   Network: "network",
+  /**
+   * from a server side `fetch`
+   */
   Ssr: "ssr"
 };
 const fragmentKey = " $fragments";

package/build/runtime-esm/public/cache.js

@@ -6,6 +6,9 @@ class Cache {
   constructor(cache) {
     this._internal_unstable = cache;
   }
+  // if the user is using the imperative API, we want the ability to break the API
+  // with any minor version. In order to do this, we require them to accept this contract
+  // through their config file
   validateInstabilityWarning() {
     if (!this.config.acceptImperativeInstability && !this.config.features?.imperativeCache) {
       console.warn(`\u26A0\uFE0F  The imperative cache API is considered unstable and will change in any minor version release
@@ -13,6 +16,7 @@ Please acknowledge this by enabling the imperative cache feature flage in your c
 For more information: https://houdinigraphql.com/api/cache`);
     }
   }
+  // return the record proxy for the given type/id combo
   get(type, data) {
     this.validateInstabilityWarning();
     let recordID = this._internal_unstable._internal_unstable.id(type, data);
@@ -56,6 +60,7 @@ For more information: https://houdinigraphql.com/api/cache`);
     this.validateInstabilityWarning();
     this._internal_unstable.write({
       selection: query.artifact.selection,
+      // @ts-expect-error
       data,
       variables: marshalInputs({
         config: this.config,
@@ -65,9 +70,15 @@ For more information: https://houdinigraphql.com/api/cache`);
     });
     return;
   }
+  /**
+   * Mark some elements of the cache stale.
+   */
   markStale(type, options) {
     return this._internal_unstable.markTypeStale(type ? { ...options, type } : void 0);
   }
+  /**
+   * Reset the entire cache by clearing all records and lists
+   */
   reset() {
     return this._internal_unstable.reset();
   }

package/build/runtime-esm/public/record.js

@@ -54,6 +54,11 @@ class Record {
   delete() {
     this.#cache._internal_unstable.delete(this.#id);
   }
+  /**
+   * Mark some elements of the record stale in the cache.
+   * @param field
+   * @param when
+   */
   markStale(field, {
     when
   } = {}) {

package/build/runtime-esm/router/jwt.js

@@ -1,5 +1,6 @@
 function base64UrlParse(s) {
   return new Uint8Array(
+    // @ts-ignore
     Array.prototype.map.call(
       atob(s.replace(/-/g, "+").replace(/_/g, "/").replace(/\s/g, "")),
       (c) => c.charCodeAt(0)
@@ -52,20 +53,16 @@ function _decodePayload(raw) {
   }
 }
 async function encode(payload, secret, options = { algorithm: "HS256", header: { typ: "JWT" } }) {
-  if (typeof options === "string")
-    options = { algorithm: options, header: { typ: "JWT" } };
+  if (typeof options === "string") options = { algorithm: options, header: { typ: "JWT" } };
   options = { algorithm: "HS256", header: { typ: "JWT" }, ...options };
   if (payload === null || typeof payload !== "object")
     throw new Error("payload must be an object");
   if (typeof secret !== "string" && typeof secret !== "object")
     throw new Error("secret must be a string or a JWK object");
-  if (typeof options.algorithm !== "string")
-    throw new Error("options.algorithm must be a string");
+  if (typeof options.algorithm !== "string") throw new Error("options.algorithm must be a string");
   const algorithm = algorithms[options.algorithm];
-  if (!algorithm)
-    throw new Error("algorithm not found");
-  if (!payload.iat)
-    payload.iat = Math.floor(Date.now() / 1e3);
+  if (!algorithm) throw new Error("algorithm not found");
+  if (!payload.iat) payload.iat = Math.floor(Date.now() / 1e3);
   const payloadAsJSON = JSON.stringify(payload);
   const partialToken = `${base64UrlStringify(
     _utf8ToUint8Array(JSON.stringify({ ...options.header, alg: options.algorithm }))
@@ -80,42 +77,33 @@ async function encode(payload, secret, options = { algorithm: "HS256", header: {
     keyData = _str2ab(
       secret.replace(/-----BEGIN.*?-----/g, "").replace(/-----END.*?-----/g, "").replace(/\s/g, "")
     );
-  } else
-    keyData = _utf8ToUint8Array(secret);
+  } else keyData = _utf8ToUint8Array(secret);
   const key = await crypto.subtle.importKey(keyFormat, keyData, algorithm, false, ["sign"]);
   const signature = await crypto.subtle.sign(algorithm, key, _utf8ToUint8Array(partialToken));
   return `${partialToken}.${base64UrlStringify(new Uint8Array(signature))}`;
 }
 async function verify(token, secret, options = { algorithm: "HS256", throwError: false }) {
-  if (typeof options === "string")
-    options = { algorithm: options, throwError: false };
+  if (typeof options === "string") options = { algorithm: options, throwError: false };
   options = { algorithm: "HS256", throwError: false, ...options };
-  if (typeof token !== "string")
-    throw new Error("token must be a string");
+  if (typeof token !== "string") throw new Error("token must be a string");
   if (typeof secret !== "string" && typeof secret !== "object")
     throw new Error("secret must be a string or a JWK object");
-  if (typeof options.algorithm !== "string")
-    throw new Error("options.algorithm must be a string");
+  if (typeof options.algorithm !== "string") throw new Error("options.algorithm must be a string");
   const tokenParts = token.split(".");
-  if (tokenParts.length !== 3)
-    throw new Error("token must consist of 3 parts");
+  if (tokenParts.length !== 3) throw new Error("token must consist of 3 parts");
   const algorithm = algorithms[options.algorithm];
-  if (!algorithm)
-    throw new Error("algorithm not found");
+  if (!algorithm) throw new Error("algorithm not found");
   const { payload } = decode(token);
   if (!payload) {
-    if (options.throwError)
-      throw "PARSE_ERROR";
+    if (options.throwError) throw "PARSE_ERROR";
     return false;
   }
   if (payload.nbf && payload.nbf > Math.floor(Date.now() / 1e3)) {
-    if (options.throwError)
-      throw "NOT_YET_VALID";
+    if (options.throwError) throw "NOT_YET_VALID";
     return false;
   }
   if (payload.exp && payload.exp <= Math.floor(Date.now() / 1e3)) {
-    if (options.throwError)
-      throw "EXPIRED";
+    if (options.throwError) throw "EXPIRED";
     return false;
   }
   let keyFormat = "raw";
@@ -128,8 +116,7 @@ async function verify(token, secret, options = { algorithm: "HS256", throwError:
     keyData = _str2ab(
       secret.replace(/-----BEGIN.*?-----/g, "").replace(/-----END.*?-----/g, "").replace(/\s/g, "")
     );
-  } else
-    keyData = _utf8ToUint8Array(secret);
+  } else keyData = _utf8ToUint8Array(secret);
   const key = await crypto.subtle.importKey(keyFormat, keyData, algorithm, false, ["verify"]);
   return await crypto.subtle.verify(
     algorithm,

package/build/runtime-esm/router/match.js

@@ -112,14 +112,12 @@ function exec(match, params) {
     }
     buffered = "";
     if (value === void 0) {
-      if (param.rest)
-        result[param.name] = "";
+      if (param.rest) result[param.name] = "";
     } else {
       result[param.name] = decodeURIComponent(value);
     }
   }
-  if (buffered)
-    return;
+  if (buffered) return;
   return result;
 }
 function escape(str) {

package/build/runtime-esm/router/server.js

@@ -27,7 +27,12 @@ function _serverHandler({
   if (schema) {
     client.registerProxy(graphqlEndpoint, async ({ query, variables, session }) => {
       const parsed = parse(query);
-      return await execute(schema, parsed, null, session, variables);
+      return await execute({
+        schema,
+        document: parsed,
+        contextValue: session,
+        variableValues: variables
+      });
     });
   }
   return async (request) => {

package/build/runtime-esm/router/session.js

@@ -35,7 +35,7 @@ async function redirect_auth(args) {
 }
 const session_cookie_name = "__houdini__";
 async function set_session(req, response, value) {
-  const today = new Date();
+  const today = /* @__PURE__ */ new Date();
   const expires = new Date(today.getTime() + 7 * 24 * 60 * 60 * 1e3);
   const serialized = await encode(value, req.session_keys[0]);
   response.headers.set(