@fourtwelvelabs/fetch-contentful 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { TypedDocumentNode } from '@graphql-typed-document-node/core';
 import { DocumentNode } from 'graphql';
 
 /**
@@ -51,8 +52,13 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * query fields (see {@link FetchContentfulOptions.autoInjectArgs}),
      * auto-fills a `$locale: String` variable when your query declares one,
      * and is applied to generated subqueries.
+     *
+     * Defaults to `"en-US"`. Pass `null` to send no `locale` at all, which
+     * lets Contentful serve whichever locale the space itself defaults to —
+     * useful for a space whose default locale is not `en-US`, and the
+     * behavior this option had before a default existed.
      */
-    locale?: string;
+    locale?: string | null;
     /**
      * Automatically add `preview: true` / `locale: "..."` arguments to the
      * root fields of your query based on the `preview` and `locale` options,
@@ -85,7 +91,16 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
      * Automatically split nested reference collections (any `*Collection`
      * field that is not a root query field) into their own subqueries to stay
      * under Contentful's query complexity limits. Defaults to `true`.
-     * One-to-one references can be split by annotating them with `@split`.
+     *
+     * This gates **automatic detection only**. The `@split` directive is an
+     * independent, explicit trigger: it always splits the field it annotates —
+     * a nested collection just as much as a one-to-one reference — whatever
+     * this option is set to. Setting it to `false` and annotating only the
+     * fields that actually exceed the limit gives you a manual mode in which
+     * every other query is a single round trip.
+     *
+     * `@split` on a root field throws a `CONFIG` error: there is no parent
+     * entry to stitch the result back onto.
      */
     autoSplitNestedCollections?: boolean;
     /** How many parent entry ids to resolve per subquery request. Defaults to `50`. */
@@ -114,6 +129,51 @@ interface FetchContentfulOptions<TVariables extends GraphQLVariables = GraphQLVa
     /** Standard fetch cache mode, forwarded to fetch. */
     cache?: RequestCache;
 }
+/**
+ * Variables {@link FetchContentfulOptions.autoInjectArgs} fills in on the
+ * caller's behalf, so a typed document that declares `$preview` / `$locale`
+ * never forces the caller to pass them.
+ */
+type AutoInjectedVariable = 'preview' | 'locale';
+/** The variables a caller still has to supply for a typed document. */
+type CallerVariables<TVariables> = Omit<TVariables, AutoInjectedVariable>;
+/** `true` when nothing is left for the caller to pass. */
+type VariablesAreOptional<TVariables> = Record<string, never> extends CallerVariables<TVariables> ? true : false;
+/**
+ * Makes `variables` required exactly when the document declares one the
+ * caller must provide, and optional otherwise (including when every
+ * remaining variable is nullable, or when the only ones left are
+ * auto-injected).
+ *
+ * The conditional deliberately sits in *key* position rather than wrapping
+ * the whole object. TypeScript skips excess-property checks when a
+ * parameter's type is a conditional over a type argument it is still
+ * inferring, so `{ variables: { slgu: '…' } }` would slip through a
+ * `… ? { variables: T } : { variables?: T }` formulation. Selecting the key
+ * instead keeps the property's type a plain `TVariables`, and typos are
+ * caught.
+ */
+type VariablesOption<TVariables> = {
+    [K in VariablesAreOptional<TVariables> extends true ? never : 'variables']: TVariables;
+} & {
+    [K in VariablesAreOptional<TVariables> extends true ? 'variables' : never]?: TVariables;
+};
+/**
+ * {@link FetchContentfulOptions} for a call that passes a typed document:
+ * identical, except `variables` is typed by — and required by — the
+ * document itself.
+ */
+type TypedFetchContentfulOptions<TVariables> = Omit<FetchContentfulOptions<GraphQLVariables>, 'variables'> & VariablesOption<TVariables>;
+/**
+ * The result type a document carries, falling back to the historical
+ * default for a plain, untyped `DocumentNode`.
+ *
+ * `TypedDocumentNode`'s type brand is an optional property, so an untyped
+ * `DocumentNode` structurally satisfies it and infers `unknown`. Mapping
+ * that back to `Record<string, unknown>` keeps pre-existing
+ * `fetchContentful(parse(query))` calls typed exactly as they were.
+ */
+type DocumentResult<TResult> = unknown extends TResult ? Record<string, unknown> : TResult;
 /** A single locale as configured in Contentful. */
 interface ContentfulLocale {
     code: string;
@@ -278,18 +338,33 @@ declare function collectAtPath(data: unknown, path: string[]): Record<string, un
  *   query has succeeded.
  * - Shapes the response so every `fooCollection.items` becomes `foo`
  *   (disable with `shapeResponseData: false` to receive the raw wire shape).
+ *
+ * Pass a typed document — from gql.tada, graphql-codegen's client preset, or
+ * anything else producing a `TypedDocumentNode` — and both the result and
+ * the variables are inferred, with no type arguments to write by hand.
  */
-declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+    unwrapRootField: false;
+}): Promise<DocumentResult<TResult>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    shapeResponseData: false;
+}): Promise<UnwrapSingleRoot<DocumentResult<TResult>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+    unwrapRootField: false;
+}): Promise<ShapeCollections<DocumentResult<TResult>>>;
+declare function fetchContentful<TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, ...args: Record<string, never> extends CallerVariables<TVariables> ? [options?: TypedFetchContentfulOptions<TVariables>] : [options: TypedFetchContentfulOptions<TVariables>]): Promise<UnwrapSingleRoot<ShapeCollections<DocumentResult<TResult>>>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
     shapeResponseData: false;
     unwrapRootField: false;
 }): Promise<TData>;
-declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
     shapeResponseData: false;
 }): Promise<UnwrapSingleRoot<TData>>;
-declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
     unwrapRootField: false;
 }): Promise<ShapeCollections<TData>>;
-declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+declare function fetchContentful<TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
 /**
  * Creates a `fetchContentful` bound to default options — the recommended way
  * to configure the utility once per project:
@@ -298,7 +373,7 @@ declare function fetchContentful<TData = Record<string, unknown>, TVariables ext
  * // lib/contentful.ts
  * export const fetchContentful = createFetchContentful({
  *   space: 'abc123',
- *   locale: 'en-US',
+ *   locale: 'de-DE', // overrides the 'en-US' default for the whole project
  *   retries: 3,
  * });
  * ```
@@ -308,17 +383,28 @@ declare function fetchContentful<TData = Record<string, unknown>, TVariables ext
  * the call itself, so prefer setting it per call.
  */
 declare function createFetchContentful<TDefaultVariables extends GraphQLVariables = GraphQLVariables>(defaults?: FetchContentfulOptions<TDefaultVariables>): {
-    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+        unwrapRootField: false;
+    }): Promise<DocumentResult<TResult>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        shapeResponseData: false;
+    }): Promise<UnwrapSingleRoot<DocumentResult<TResult>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, options: TypedFetchContentfulOptions<TVariables> & {
+        unwrapRootField: false;
+    }): Promise<ShapeCollections<DocumentResult<TResult>>>;
+    <TResult, TVariables = GraphQLVariables>(document: TypedDocumentNode<TResult, TVariables>, ...args: Record<string, never> extends CallerVariables<TVariables> ? [options?: TypedFetchContentfulOptions<TVariables>] : [options: TypedFetchContentfulOptions<TVariables>]): Promise<UnwrapSingleRoot<ShapeCollections<DocumentResult<TResult>>>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
         shapeResponseData: false;
         unwrapRootField: false;
     }): Promise<TData>;
-    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
         shapeResponseData: false;
     }): Promise<UnwrapSingleRoot<TData>>;
-    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options: FetchContentfulOptions<TVariables> & {
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options: FetchContentfulOptions<TVariables> & {
         unwrapRootField: false;
     }): Promise<ShapeCollections<TData>>;
-    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string | DocumentNode, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
+    <TData = Record<string, unknown>, TVariables extends GraphQLVariables = GraphQLVariables>(query: string, options?: FetchContentfulOptions<TVariables>): Promise<UnwrapSingleRoot<ShapeCollections<TData>>>;
 };
 
-export { type ContentfulGraphQLError, type ContentfulLocale, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type ShapeCollections, type UnwrapSingleRoot, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, readEnvSettings, shapeData, unwrapSingleRoot };
+export { type AutoInjectedVariable, type CallerVariables, type ContentfulGraphQLError, type ContentfulLocale, type DocumentResult, FetchContentfulError, type FetchContentfulErrorCode, type FetchContentfulOptions, type GraphQLVariables, type NextFetchOptions, type ShapeCollections, type TypedFetchContentfulOptions, type UnwrapSingleRoot, type VariablesOption, clearLocaleCache, collectAtPath, createFetchContentful, fetchContentful as default, fetchContentful, getLocales, injectRootArgs, inlineFragments, isFetchContentfulError, readEnvSettings, shapeData, unwrapSingleRoot };

package/dist/index.mjs

@@ -228,7 +228,15 @@ function planSplits(document, options) {
         );
       }
       const field = selection;
-      const shouldSplit = depth > 0 && field.selectionSet !== void 0 && !hasDirective(field, NO_SPLIT_DIRECTIVE) && (hasDirective(field, SPLIT_DIRECTIVE) || options.autoSplitNestedCollections && isCollectionField(field));
+      const isExplicitSplit = hasDirective(field, SPLIT_DIRECTIVE);
+      const isAutoSplit = options.autoSplitNestedCollections && isCollectionField(field);
+      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);
       if (shouldSplit) {
         const planned = withDirective(
           withoutDirective(field, SPLIT_DIRECTIVE),
@@ -701,6 +709,7 @@ function unwrapSingleRoot(data) {
 }
 
 // src/index.ts
+var DEFAULT_LOCALE = "en-US";
 var DEFAULT_RETRIES = 5;
 var DEFAULT_RETRY_DELAY_MS = 250;
 var DEFAULT_MAX_RETRY_DELAY_MS = 8e3;
@@ -760,7 +769,8 @@ function resolveContext(options) {
     environment,
     token,
     preview,
-    locale: options.locale,
+    // `null` is the opt-out; `undefined` (or absent) takes the default.
+    locale: options.locale === null ? void 0 : options.locale ?? DEFAULT_LOCALE,
     fetch: fetchImpl,
     retry,
     autoSplitNestedCollections: options.autoSplitNestedCollections ?? true,
@@ -867,12 +877,15 @@ async function executeDocument(document, variables, context) {
   cleanupMarkers(data, plans);
   return data;
 }
+function isDocumentNode(query) {
+  return typeof query === "object" && query !== null && query.kind === Kind.DOCUMENT && Array.isArray(query.definitions);
+}
 function toDocument(query) {
-  if (typeof query !== "string") {
+  if (isDocumentNode(query)) {
     return query;
   }
   try {
-    return parse(query);
+    return parse(typeof query === "string" ? query : String(query));
   } catch (cause) {
     throw new FetchContentfulError(
       `Failed to parse GraphQL query: ${String(cause)}`,
@@ -895,7 +908,7 @@ function withAutoVariables(document, variables, context) {
   }
   return merged;
 }
-async function fetchContentful(query, options = {}) {
+async function runFetchContentful(query, options) {
   const context = resolveContext(options);
   let document = inlineFragments(toDocument(query));
   if (options.autoInjectArgs ?? true) {
@@ -925,32 +938,15 @@ async function fetchContentful(query, options = {}) {
   }
   return unwrapSingleRoot(result);
 }
+async function fetchContentful(query, options = {}) {
+  return runFetchContentful(query, options);
+}
 function createFetchContentful(defaults = {}) {
   function bound(query, options = {}) {
-    const merged = {
+    return runFetchContentful(query, {
       ...defaults,
       ...options
-    };
-    if (merged.shapeResponseData === false) {
-      if (merged.unwrapRootField === false) {
-        return fetchContentful(query, {
-          ...merged,
-          shapeResponseData: false,
-          unwrapRootField: false
-        });
-      }
-      return fetchContentful(query, {
-        ...merged,
-        shapeResponseData: false
-      });
-    }
-    if (merged.unwrapRootField === false) {
-      return fetchContentful(query, {
-        ...merged,
-        unwrapRootField: false
-      });
-    }
-    return fetchContentful(query, merged);
+    });
   }
   return bound;
 }