@fourtwelvelabs/fetch-contentful 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# @fourtwelvelabs/fetch-contentful
+
+## 0.2.1
+
+### Patch Changes
+
+- 641367c: `@split` on a **root field** now throws instead of being silently ignored.
+
+  Root fields have no parent entry to stitch a result back onto, so they have
+  never been splittable — but the directive was quietly stripped before the
+  request went out, leaving the query just as expensive as before with nothing
+  to explain why. It now raises a `CONFIG` `FetchContentfulError` naming the
+  field.
+
+  **This can surface in existing queries.** If a query annotates a root field,
+  that call will now reject where it previously succeeded (having ignored the
+  directive). The fix is to remove the directive — it was never doing anything
+  — and page through the field with its own `limit` / `skip` arguments instead.
+  Nested `@split` annotations are unaffected.
+
+  Also clarifies and pins the relationship between `@split` and
+  `autoSplitNestedCollections`: the option gates **only** the automatic
+  detection of nested `*Collection` fields, while `@split` is an independent
+  explicit trigger that splits its field — collection or one-to-one reference —
+  regardless of the option. This enables a "manual mode"
+  (`autoSplitNestedCollections: false` plus targeted annotations) where only
+  the fields that actually exceed Contentful's complexity limit are split. That
+  behavior was already correct; it is now documented and covered by tests.
+
+## 0.2.0
+
+### Minor Changes
+
+- 9c9eef3: Add a gql.tada companion.
+
+  - **`@fourtwelvelabs/fetch-contentful/tada`** — a new type-only subpath export
+    providing `ContentfulScalars`, the scalar map for Contentful's GraphQL
+    Content API, for `initGraphQLTada<{ scalars: ContentfulScalars }>`. Nothing
+    in it imports gql.tada at runtime.
+  - **`tada-init` and `tada-refresh` CLI commands**, via a new
+    `fetch-contentful` binary. `tada-init` downloads the space's schema as SDL,
+    registers `@0no-co/graphqlsp` in the project's `tsconfig.json` (preserving
+    comments and formatting, and updating an existing entry rather than
+    duplicating it) and writes a `graphql.ts` bound to the schema and the scalar
+    map. `tada-refresh` re-downloads the schema only, leaving the file untouched
+    when nothing changed. Both support `--dry-run`, resolve credentials through
+    the same environment variables the library reads, and never print the access
+    token.
+  - **Typed document support in `fetchContentful`** — passing a
+    `TypedDocumentNode` (gql.tada, or graphql-codegen's client preset) infers
+    both the result and the variable types, with response shaping and single-root
+    unwrapping applied to the inferred type. `variables` is required exactly when
+    the document declares one the library does not inject itself, and unknown
+    variable names are rejected. Existing string and `DocumentNode` usage is
+    unchanged.
+
+  `gql.tada` and `@0no-co/graphqlsp` are optional peer dependencies, needed only
+  at author time.
+
+## 0.1.0
+
+### Minor Changes
+
+- b6e2577: Initial release. A type-safe GraphQL fetching utility for Contentful:
+
+  - Automatic query splitting for nested reference collections (and `@split`-annotated one-to-one references), fetched in id batches and stitched back into the original response shape.
+  - Automatic retries with exponential backoff and jitter, honouring `Retry-After`.
+  - Response shaping (`fooCollection.items` → `foo`) and single-root unwrapping, at runtime and in the return type.
+  - Automatic `preview` / `locale` argument injection, with optional locale validation against the space.
+  - Typed `FetchContentfulError` carrying an error code, HTTP status, and GraphQL errors.
+  - Next.js App Router support via `next.revalidate` / `next.tags` passthrough.

package/README.md

@@ -9,6 +9,7 @@ A foolproof, type-safe GraphQL fetching utility for Contentful. One function in,
 - **No preview/locale boilerplate** — `preview` and `locale` are injected as arguments onto your query's root fields automatically (Contentful cascades them to every nested field), so queries never need to declare or thread them.
 - **All-or-nothing promise** — resolves only when every request in the tree succeeded; rejects with a typed `FetchContentfulError` if anything fails.
 - **Locale awareness** — locales are fetched from Contentful once and cached in-module, so validation costs nothing per fetch.
+- **Inferred types, optionally** — pass a [gql.tada](https://gql-tada.0no.co) or graphql-codegen document and the result and variable types come from the query itself. One command (`tada-init`) sets gql.tada up against your space. See [Typed queries with gql.tada](#typed-queries-with-gqltada).
 - **ESM + CJS, Next.js-ready** — first-class App Router support (`next.revalidate` / `next.tags` passthrough), works in Pages Router and any Node ≥ 18 runtime.
 
 ## Install
@@ -101,6 +102,41 @@ const data = await fetchContentful<PagesQuery>(
 
 Notice there is no `$preview` or `$locale` anywhere in the query: the options are injected as `preview: true` / `locale: "en-US"` arguments on the root field before the query is sent, and Contentful cascades both to every nested field. Arguments you write explicitly are never overridden, so per-field overrides like `title(locale: "de-DE")` keep working. Set `autoInjectArgs: false` to opt out. (The older style still works too — `$preview: Boolean` / `$locale: String` variables are auto-filled whenever a query declares them.)
 
+## Typed queries with gql.tada
+
+Everything above types the response by hand (`fetchContentful<PagesQuery>`). You can instead have the types come from the query itself. Install the author-time peers, then run the setup command:
+
+```bash
+yarn add -D gql.tada @0no-co/graphqlsp
+npx @fourtwelvelabs/fetch-contentful tada-init
+```
+
+That downloads your space's schema as SDL, registers `@0no-co/graphqlsp` in your `tsconfig.json` and writes `src/graphql.ts`. It reads the same environment variables the library does, is safe to re-run, and takes `--dry-run`. Restart the TypeScript server afterwards, and queries type themselves:
+
+```ts
+import { fetchContentful } from '@fourtwelvelabs/fetch-contentful';
+import { graphql } from './graphql';
+
+const PageQuery = graphql(`
+  query Page($slug: String!) {
+    pageCollection(where: { slug: $slug }, limit: 1) {
+      items {
+        title
+        sectionsCollection { items { heading } }
+      }
+    }
+  }
+`);
+
+const pages = await fetchContentful(PageQuery, { variables: { slug: 'home' } });
+//    ^? Array<{ title: string | null;
+//               sections: Array<{ heading: string | null }> }> | null
+```
+
+No type argument, and `variables` is required exactly when the document declares one the library doesn't inject itself (`$preview` and `$locale` are filled in automatically). Response shaping and single-root unwrapping are applied to the inferred type, so what you see is what you get. After a content-model change, run `tada-refresh` to re-download the schema.
+
+**[Full gql.tada guide →](./docs/tada.md)** — the scalar map, manual setup without the CLI, the CLI reference, and a CI recipe that opens a PR when your content model changes.
+
 ## Next.js
 
 ### App Router (recommended)
@@ -167,7 +203,8 @@ fetchContentful(query, {
 
   // Query rewriting
   autoInjectArgs: true,             // inject preview/locale args on root fields
-  autoSplitNestedCollections: true, // split every non-root *Collection field
+  autoSplitNestedCollections: true, // auto-detect non-root *Collection fields
+                                    // (@split works regardless — see below)
   splitBatchSize: 50,               // parent ids per subquery
 });
 ```
@@ -226,7 +263,7 @@ The standalone `shapeData` / `ShapeCollections` exports exist only for advanced
 
 Contentful rejects queries whose complexity exceeds its limit — usually caused by nested reference fields multiplying. `fetch-contentful` avoids this transparently:
 
-1. Named fragments are inlined and the query is scanned. Every **nested** `*Collection` field (auto) and every field annotated **`@split`** (one-to-one references) is removed from the outer query and recorded as a plan.
+1. Named fragments are inlined and the query is scanned. Every **nested** `*Collection` field (auto) and every field annotated **`@split`** is removed from the outer query and recorded as a plan.
 2. The outer query runs with tiny markers (`sys { id }`, `__typename`) injected where fields were removed.
 3. Parents are grouped by their concrete `__typename`, and each split field is re-fetched via `"{typeName}Collection"(where: { sys: { id_in: [...] } })` in batches of `splitBatchSize`, in parallel. Subqueries go through the same pipeline, so splits nest recursively to any depth.
 4. Results are stitched back onto their parents by `sys.id`. If any entry can't be resolved, the whole promise rejects with a `STITCH` error — you never get silently incomplete data.
@@ -249,6 +286,59 @@ query {
 
 The `@split` directive is stripped before anything is sent to Contentful.
 
+### `@split` and `autoSplitNestedCollections` are independent
+
+`autoSplitNestedCollections` controls **only automatic detection** — whether nested `*Collection` fields are split without being asked. `@split` is an explicit instruction that always applies to the field it annotates, whatever the option is set to, and works on **nested collections just as well as one-to-one references**. An annotated collection takes exactly the same path as an auto-detected one: its arguments (`limit`, `where`, `order`, …) and selection set are re-selected verbatim in the subquery.
+
+The two triggers never double up — a field caught by both produces one subquery, not two.
+
+### Manual mode
+
+Turn auto-splitting off and annotate only the fields that actually blow the complexity limit. Everything else then runs as a single round trip, which is usually faster and always easier to reason about:
+
+```ts
+const data = await fetchContentful(QUERY, {
+  autoSplitNestedCollections: false,
+});
+```
+
+```graphql
+query {
+  pageCollection(limit: 10) {
+    items {
+      title
+      # Small and cheap: fetched inline, in the same request.
+      seo { description }
+      tagsCollection(limit: 5) { items { name } }
+
+      # The expensive one: fetched separately, batched by parent id.
+      sectionsCollection(limit: 50) @split {
+        items {
+          heading
+          mediaCollection(limit: 10) { items { url } }
+        }
+      }
+    }
+  }
+}
+```
+
+That sends two requests instead of the four auto mode would. Splits still nest recursively in manual mode: a `@split` inside a subquery is planned when that subquery runs, so you can annotate as deeply as you need.
+
+### Root fields cannot be split
+
+`@split` on a **root** field raises a `CONFIG` `FetchContentfulError` rather than being quietly ignored:
+
+```graphql
+query {
+  pageCollection @split {   # ✗ CONFIG error
+    items { title }
+  }
+}
+```
+
+A root field has no parent entry to stitch its result back onto, so there is nothing for the directive to do. Reach for `limit` and `skip` on the field itself instead. (Before 0.2.1 the directive was silently stripped here — if an existing query relies on that, remove the directive.)
+
 ## Error handling
 
 Every rejection is a `FetchContentfulError`:
@@ -280,6 +370,9 @@ import {
   injectRootArgs,    // the preview/locale argument injector (advanced AST use)
 } from '@fourtwelvelabs/fetch-contentful';
 import type { ShapeCollections, FetchContentfulOptions } from '@fourtwelvelabs/fetch-contentful';
+
+// Type-only subpath, for wiring gql.tada up by hand (see docs/tada.md).
+import type { ContentfulScalars, JsonValue } from '@fourtwelvelabs/fetch-contentful/tada';
 ```
 
 `ShapeCollections<T>` and `UnwrapSingleRoot<T>` are the type-level twins of `shapeData` and `unwrapSingleRoot`. Neither is needed alongside `fetchContentful` (shaping is built into it) — they're for shaping Contentful-shaped data that arrived some other way.