@fourtwelvelabs/fetch-contentful 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -130,6 +130,29 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * entry to stitch the result back onto.
      */
     autoSplitNestedCollections?: boolean;
+    /**
+     * When the outer query — after minification, and after the splitting
+     * above — still exceeds {@link FetchContentfulOptions.maxQuerySize}, keep
+     * peeling off the single largest remaining field (any field with a
+     * selection set, one-to-one references included, not just `*Collection`
+     * fields) into its own subquery until it fits or nothing splittable is
+     * left. Defaults to `true`.
+     *
+     * Independent of `autoSplitNestedCollections`: that option controls which
+     * fields split *by shape*, this one adds more splits *by measured size* as
+     * a last resort. A query that still doesn't fit after every splittable
+     * field has been removed is sent as-is — at that point there is nothing
+     * left for this library to do, and Contentful's own `QUERY_TOO_BIG` is the
+     * accurate error to see.
+     */
+    autoSplitOnSize?: boolean;
+    /**
+     * Byte budget that triggers {@link FetchContentfulOptions.autoSplitOnSize}.
+     * Defaults to `7500` — comfortably under Contentful's published 8 KB
+     * query size limit — or `15500` when `automaticPersistedQueries` is
+     * enabled, which raises Contentful's own ceiling to 16 KB.
+     */
+    maxQuerySize?: number;
     /** How many parent entry ids to resolve per subquery request. Defaults to `50`. */
     splitBatchSize?: number;
     /**
@@ -195,6 +218,29 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * on demand.
      */
     annotateQueryOnError?: boolean;
+    /**
+     * Strip insignificant whitespace from every outgoing query before it's
+     * sent — the same effect a tool like GQLMin has, applied automatically.
+     * Defaults to `true`; the only reason to disable it is to read a raw
+     * request off the wire while debugging, since {@link
+     * FetchContentfulError.query} and the annotated caret display always
+     * reflect whatever text was actually transmitted.
+     */
+    minifyQuery?: boolean;
+    /**
+     * Send every request as an Automatic Persisted Query: the optimistic first
+     * attempt sends only a hash of the query, and the query text itself is
+     * sent (once) only the first time Contentful reports that hash unknown.
+     * This is what actually lifts Contentful's query size ceiling from 8 KB to
+     * 16 KB, and every request after a query's first use no longer transmits
+     * the query text at all.
+     *
+     * **Requires the Premium plan or above** — see
+     * https://www.contentful.com/developers/docs/references/graphql/automatic-persisted-queries/.
+     * On any other plan this doubles every request's round trips for no
+     * benefit, which is why it defaults to `false`.
+     */
+    automaticPersistedQueries?: boolean;
     /** Custom fetch implementation (useful for tests). Defaults to `globalThis.fetch`. */
     fetch?: typeof fetch;
     /** AbortSignal forwarded to every underlying fetch call. */
@@ -468,6 +514,13 @@ declare function getLocales(context: LocalesContext): Promise<ContentfulLocale[]
 /** Clears the in-module locale cache (mainly useful in tests). */
 declare function clearLocaleCache(): void;
 
+/**
+ * Minifies an already-valid GraphQL document string to the shortest text
+ * that still lexes to the same tokens. Safe to call on `print()` output or
+ * on a hand-written query; comments are dropped either way.
+ */
+declare function minifyQuery(query: string): string;
+
 /**
  * Recursively rewrites Contentful collection wrappers:
  * `{ fooCollection: { items: [...] } }` becomes `{ foo: [...] }`.
@@ -676,4 +729,4 @@ declare function createFetchContentful<TDefaultVariables extends GraphQLVariable
     <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<OmitUnresolvedLinks<TData>>>>;
 };
 
-export { type AnnotateQueryOptions, type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type OmitUnresolvedLinks, type ShapeCollections, type TypedFetchContentfulOptions, UNRESOLVABLE_LINK_CODE, type UnresolvableLinkMode, type UnwrapSingleRoot, type VariablesOption, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };
+export { type AnnotateQueryOptions, type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type OmitUnresolvedLinks, type ShapeCollections, type TypedFetchContentfulOptions, UNRESOLVABLE_LINK_CODE, type UnresolvableLinkMode, type UnwrapSingleRoot, type VariablesOption, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, minifyQuery, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };

package/dist/index.d.ts

@@ -130,6 +130,29 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * entry to stitch the result back onto.
      */
     autoSplitNestedCollections?: boolean;
+    /**
+     * When the outer query — after minification, and after the splitting
+     * above — still exceeds {@link FetchContentfulOptions.maxQuerySize}, keep
+     * peeling off the single largest remaining field (any field with a
+     * selection set, one-to-one references included, not just `*Collection`
+     * fields) into its own subquery until it fits or nothing splittable is
+     * left. Defaults to `true`.
+     *
+     * Independent of `autoSplitNestedCollections`: that option controls which
+     * fields split *by shape*, this one adds more splits *by measured size* as
+     * a last resort. A query that still doesn't fit after every splittable
+     * field has been removed is sent as-is — at that point there is nothing
+     * left for this library to do, and Contentful's own `QUERY_TOO_BIG` is the
+     * accurate error to see.
+     */
+    autoSplitOnSize?: boolean;
+    /**
+     * Byte budget that triggers {@link FetchContentfulOptions.autoSplitOnSize}.
+     * Defaults to `7500` — comfortably under Contentful's published 8 KB
+     * query size limit — or `15500` when `automaticPersistedQueries` is
+     * enabled, which raises Contentful's own ceiling to 16 KB.
+     */
+    maxQuerySize?: number;
     /** How many parent entry ids to resolve per subquery request. Defaults to `50`. */
     splitBatchSize?: number;
     /**
@@ -195,6 +218,29 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * on demand.
      */
     annotateQueryOnError?: boolean;
+    /**
+     * Strip insignificant whitespace from every outgoing query before it's
+     * sent — the same effect a tool like GQLMin has, applied automatically.
+     * Defaults to `true`; the only reason to disable it is to read a raw
+     * request off the wire while debugging, since {@link
+     * FetchContentfulError.query} and the annotated caret display always
+     * reflect whatever text was actually transmitted.
+     */
+    minifyQuery?: boolean;
+    /**
+     * Send every request as an Automatic Persisted Query: the optimistic first
+     * attempt sends only a hash of the query, and the query text itself is
+     * sent (once) only the first time Contentful reports that hash unknown.
+     * This is what actually lifts Contentful's query size ceiling from 8 KB to
+     * 16 KB, and every request after a query's first use no longer transmits
+     * the query text at all.
+     *
+     * **Requires the Premium plan or above** — see
+     * https://www.contentful.com/developers/docs/references/graphql/automatic-persisted-queries/.
+     * On any other plan this doubles every request's round trips for no
+     * benefit, which is why it defaults to `false`.
+     */
+    automaticPersistedQueries?: boolean;
     /** Custom fetch implementation (useful for tests). Defaults to `globalThis.fetch`. */
     fetch?: typeof fetch;
     /** AbortSignal forwarded to every underlying fetch call. */
@@ -468,6 +514,13 @@ declare function getLocales(context: LocalesContext): Promise<ContentfulLocale[]
 /** Clears the in-module locale cache (mainly useful in tests). */
 declare function clearLocaleCache(): void;
 
+/**
+ * Minifies an already-valid GraphQL document string to the shortest text
+ * that still lexes to the same tokens. Safe to call on `print()` output or
+ * on a hand-written query; comments are dropped either way.
+ */
+declare function minifyQuery(query: string): string;
+
 /**
  * Recursively rewrites Contentful collection wrappers:
  * `{ fooCollection: { items: [...] } }` becomes `{ foo: [...] }`.
@@ -676,4 +729,4 @@ declare function createFetchContentful<TDefaultVariables extends GraphQLVariable
     <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<OmitUnresolvedLinks<TData>>>>;
 };
 
-export { type AnnotateQueryOptions, type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type OmitUnresolvedLinks, type ShapeCollections, type TypedFetchContentfulOptions, UNRESOLVABLE_LINK_CODE, type UnresolvableLinkMode, type UnwrapSingleRoot, type VariablesOption, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };
+export { type AnnotateQueryOptions, type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type OmitUnresolvedLinks, type ShapeCollections, type TypedFetchContentfulOptions, UNRESOLVABLE_LINK_CODE, type UnresolvableLinkMode, type UnwrapSingleRoot, type VariablesOption, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, minifyQuery, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { Kind, parse, print, visit } from 'graphql';
+import { TokenKind, Lexer, Source, Kind, parse, print, visit } from 'graphql';
 
 // src/index.ts
 
@@ -126,6 +126,48 @@ var FetchContentfulError = class extends Error {
 function isFetchContentfulError(value) {
   return value instanceof FetchContentfulError;
 }
+var WORD_LIKE = /* @__PURE__ */ new Set([TokenKind.NAME, TokenKind.INT, TokenKind.FLOAT]);
+function minifyQuery(query) {
+  const lexer = new Lexer(new Source(query));
+  let previousKind;
+  let out = "";
+  for (let token = lexer.advance(); token.kind !== TokenKind.EOF; token = lexer.advance()) {
+    if (previousKind && WORD_LIKE.has(previousKind) && WORD_LIKE.has(token.kind)) {
+      out += " ";
+    }
+    out += query.slice(token.start, token.end);
+    previousKind = token.kind;
+  }
+  return out;
+}
+
+// src/persisted-query.ts
+var PERSISTED_QUERY_VERSION = 1;
+function toHex(bytes) {
+  let hex = "";
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, "0");
+  }
+  return hex;
+}
+async function sha256Hex(query) {
+  const data = new TextEncoder().encode(query);
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) {
+    const digest = await subtle.digest("SHA-256", data);
+    return toHex(new Uint8Array(digest));
+  }
+  const { createHash } = await import('crypto');
+  return createHash("sha256").update(data).digest("hex");
+}
+function persistedQueryExtensions(sha256Hash) {
+  return { persistedQuery: { version: PERSISTED_QUERY_VERSION, sha256Hash } };
+}
+function isPersistedQueryNotFoundError(error) {
+  if (error.message === "PersistedQueryNotFound") return true;
+  const extensions = error.extensions;
+  return extensions?.code === "PERSISTED_QUERY_NOT_FOUND";
+}
 
 // src/retry.ts
 function defaultSleep(ms) {
@@ -192,6 +234,9 @@ function withDirective(field, name) {
 function responseKeyOf(field) {
   return field.alias?.value ?? field.name.value;
 }
+function hasResponseKey(selection, key) {
+  return selection.kind === Kind.FIELD && responseKeyOf(selection) === key;
+}
 function isCollectionField(field) {
   if (!field.name.value.endsWith(COLLECTION_SUFFIX) || field.name.value === COLLECTION_SUFFIX || !field.selectionSet) {
     return false;
@@ -322,13 +367,14 @@ function planSplits(document, options) {
       const field = selection;
       const isExplicitSplit = hasDirective(field, SPLIT_DIRECTIVE);
       const isAutoSplit = options.autoSplitNestedCollections && isCollectionField(field);
+      const isForcedSplit = options.forceSplit?.(field) ?? false;
       if (isExplicitSplit && depth === 0) {
         throw new FetchContentfulError(
           `Cannot split root field "${responseKeyOf(field)}": @split needs a parent entry to stitch the result back onto, and root fields have none. Move the directive to a nested field, or page through this field with its own \`limit\` and \`skip\` arguments.`,
           { code: "CONFIG" }
         );
       }
-      const shouldSplit = depth > 0 && field.selectionSet !== void 0 && !hasDirective(field, NO_SPLIT_DIRECTIVE) && (isExplicitSplit || isAutoSplit);
+      const shouldSplit = depth > 0 && field.selectionSet !== void 0 && !hasDirective(field, NO_SPLIT_DIRECTIVE) && (isExplicitSplit || isAutoSplit || isForcedSplit);
       if (shouldSplit) {
         const planned = withDirective(withoutDirective(field, SPLIT_DIRECTIVE), NO_SPLIT_DIRECTIVE);
         plans.push({
@@ -359,8 +405,11 @@ function planSplits(document, options) {
         selections.push(field);
       }
     }
-    if (needsMarkers) {
-      selections.push(sysIdMarker(), typenameMarker());
+    if (needsMarkers && !selections.some((s) => hasResponseKey(s, SYS_ID_ALIAS))) {
+      selections.push(sysIdMarker());
+    }
+    if (needsMarkers && !selections.some((s) => hasResponseKey(s, TYPENAME_ALIAS))) {
+      selections.push(typenameMarker());
     }
     return { ...selectionSet, selections };
   }
@@ -378,6 +427,49 @@ function planSplits(document, options) {
     plans
   };
 }
+function findSplitCandidates(document) {
+  const operation = getOperation(document);
+  const candidates = [];
+  function walk2(selectionSet, depth) {
+    for (const selection of selectionSet.selections) {
+      if (selection.kind === Kind.INLINE_FRAGMENT) {
+        walk2(selection.selectionSet, depth);
+        continue;
+      }
+      if (selection.kind !== Kind.FIELD || !selection.selectionSet) continue;
+      const isMarker = hasResponseKey(selection, SYS_ID_ALIAS) || hasResponseKey(selection, TYPENAME_ALIAS);
+      if (depth > 0 && selection.name.value !== "items" && !isMarker) {
+        candidates.push({ field: selection, size: print(selection).length });
+      }
+      walk2(selection.selectionSet, depth + 1);
+    }
+  }
+  walk2(operation.selectionSet, 0);
+  return candidates;
+}
+function planSplitsWithSizeBudget(document, options) {
+  const first = planSplits(document, {
+    autoSplitNestedCollections: options.autoSplitNestedCollections
+  });
+  if (!options.autoSplitOnSize) return first;
+  let outer = first.document;
+  const plans = [...first.plans];
+  let remainingIterations = findSplitCandidates(outer).length;
+  while (options.measure(outer) > options.maxQuerySize && remainingIterations-- > 0) {
+    const candidates = findSplitCandidates(outer);
+    if (candidates.length === 0) break;
+    const target = candidates.reduce(
+      (largest, candidate) => candidate.size > largest.size ? candidate : largest
+    );
+    const next = planSplits(outer, {
+      autoSplitNestedCollections: false,
+      forceSplit: (field) => field === target.field
+    });
+    outer = next.document;
+    plans.push(...next.plans);
+  }
+  return { document: outer, plans };
+}
 function stringArgument(name, value) {
   return {
     kind: Kind.ARGUMENT,
@@ -546,6 +638,10 @@ function graphqlEndpoint(space, environment) {
     space
   )}/environments/${encodeURIComponent(environment)}`;
 }
+function printOutgoingQuery(document, context) {
+  const printed = print(stripInternalDirectives(document));
+  return context.minifyQuery === false ? printed : minifyQuery(printed);
+}
 function parseRetryAfter(header) {
   if (!header) return void 0;
   const seconds = Number(header);
@@ -605,13 +701,17 @@ ${annotated}
 ` : message;
 }
 async function rawRequest(document, variables, context) {
-  const query = print(stripInternalDirectives(document));
-  const body = JSON.stringify({
-    query,
-    variables: pickDeclaredVariables(document, variables)
-  });
+  const query = printOutgoingQuery(document, context);
+  const pickedVariables = pickDeclaredVariables(document, variables);
   const url = graphqlEndpoint(context.space, context.environment);
-  return withRetries(async () => {
+  const usePersistedQuery = context.automaticPersistedQueries === true;
+  const sha256Hash = usePersistedQuery ? await sha256Hex(query) : void 0;
+  async function send(includeQuery) {
+    const body = JSON.stringify({
+      ...includeQuery ? { query } : {},
+      variables: pickedVariables,
+      ...sha256Hash ? { extensions: persistedQueryExtensions(sha256Hash) } : {}
+    });
     let response;
     try {
       const init = {
@@ -681,6 +781,21 @@ async function rawRequest(document, variables, context) {
       });
     }
     return payload.data;
+  }
+  let mustIncludeQuery = !usePersistedQuery;
+  return withRetries(async () => {
+    if (mustIncludeQuery) {
+      return send(true);
+    }
+    try {
+      return await send(false);
+    } catch (error) {
+      if (isFetchContentfulError(error) && error.code === "GRAPHQL" && error.errors?.some(isPersistedQueryNotFoundError)) {
+        mustIncludeQuery = true;
+        return await send(true);
+      }
+      throw error;
+    }
   }, context.retry);
 }
 
@@ -886,6 +1001,8 @@ var DEFAULT_RETRIES = 5;
 var DEFAULT_RETRY_DELAY_MS = 250;
 var DEFAULT_MAX_RETRY_DELAY_MS = 8e3;
 var DEFAULT_SPLIT_BATCH_SIZE = 50;
+var DEFAULT_MAX_QUERY_SIZE = 7500;
+var DEFAULT_MAX_QUERY_SIZE_WITH_APQ = 15500;
 function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -936,6 +1053,7 @@ function resolveContext(options) {
     maxDelayMs: options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS
   };
   const fetchImpl = options.fetch ?? globalThis.fetch;
+  const automaticPersistedQueries = options.automaticPersistedQueries ?? false;
   const context = {
     space,
     environment,
@@ -946,9 +1064,15 @@ function resolveContext(options) {
     fetch: fetchImpl,
     retry,
     autoSplitNestedCollections: options.autoSplitNestedCollections ?? true,
+    autoSplitOnSize: options.autoSplitOnSize ?? true,
+    // APQ lifts Contentful's size ceiling from 8 KB to 16 KB, so the budget
+    // that triggers a size-driven split follows suit unless overridden.
+    maxQuerySize: options.maxQuerySize ?? (automaticPersistedQueries ? DEFAULT_MAX_QUERY_SIZE_WITH_APQ : DEFAULT_MAX_QUERY_SIZE),
     splitBatchSize: options.splitBatchSize ?? DEFAULT_SPLIT_BATCH_SIZE,
     annotateQueryOnError: options.annotateQueryOnError ?? true,
-    unresolvableLinks: options.unresolvableLinks ?? "omit"
+    unresolvableLinks: options.unresolvableLinks ?? "omit",
+    minifyQuery: options.minifyQuery ?? true,
+    automaticPersistedQueries
   };
   if (options.onUnresolvableLink) {
     context.onUnresolvableLink = options.onUnresolvableLink;
@@ -1040,8 +1164,16 @@ function cleanupMarkers(data, plans) {
     }
   }
 }
+function byteLength(text) {
+  return new TextEncoder().encode(text).length;
+}
 async function executeDocument(document, variables, context) {
-  const { document: outer, plans } = planSplits(document, context);
+  const { document: outer, plans } = planSplitsWithSizeBudget(document, {
+    autoSplitNestedCollections: context.autoSplitNestedCollections,
+    autoSplitOnSize: context.autoSplitOnSize,
+    maxQuerySize: context.maxQuerySize,
+    measure: (doc) => byteLength(printOutgoingQuery(doc, context))
+  });
   const data = await rawRequest(outer, variables, context);
   await Promise.all(plans.map((plan) => resolvePlan(plan, data, variables, context)));
   cleanupMarkers(data, plans);
@@ -1119,6 +1251,6 @@ function createFetchContentful(defaults = {}) {
 }
 var index_default = fetchContentful;
 
-export { FetchContentfulError, UNRESOLVABLE_LINK_CODE, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, index_default as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };
+export { FetchContentfulError, UNRESOLVABLE_LINK_CODE, annotateQuery, clearLocaleCache, collectAtPath, createFetchContentful, index_default as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, isUnresolvableLinkError, minifyQuery, omitUnresolvedLinks, partitionUnresolvableLinks, readEnvSettings, shapeData, unwrapSingleRoot };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map