feat(api): document the API composition group (Wave 3)

Ships the generated reference for @imqueue/graphql-dependency 3.1.0 and
@imqueue/type-graphql-dependency 3.0.3 — 43 pages, the last two entries
in the API composition group.

Both were proof-read first, which is what the wave was gated on:
type-graphql-dependency had 7 of its 9 exported symbols carrying no doc
comment at all, so shipping as-is would have published pages of bare type
signatures. Summary coverage went 73% -> 100% and 13% -> 100%, and all
ten documented packages now report 100%.

The proof-read also turned up a crash in graphql-dependency:
defineInitializer() threw before any loader ran, making one of the three
features its README documents unusable. Fixed and covered by tests in
that repo and released as 3.1.0, which is why this is a minor there.

Site-side changes are the usual wave shape: two `status` flips in
scripts/lib/api-packages.js, which is what adds the /api/ list entries,
the two JSON-LD SoftwareSourceCode graph members and the Pages Functions.
Placeholder blurbs replaced with real ones, since they render both on
/api/ and as the graph descriptions.

Verified: all four guards pass on a clean build, sitemap-api.xml 239 ->
263, the search index 672 -> 715 entries with no empty summaries and no
table-markup leaks, both landing pages carry their @packageDocumentation
summary rather than a generated fallback, and the fenced decorator
examples render with a literal @.

Author: Mikhus

functions/api/graphql-dependency/[[path]].js

@@ -0,0 +1,7 @@
+// GENERATED by scripts/build-api-docs.js — do not edit by hand.
+// Cloudflare Pages Function — /api/graphql-dependency/*
+// Resolves retired @imqueue/graphql-dependency version URLs onto the kept version trees.
+// See lib/api-redirects.js for the policy and why this is not in _redirects.
+import { handleApiRequest } from "../../../lib/api-handler.js";
+
+export const onRequest = handleApiRequest;

functions/api/type-graphql-dependency/[[path]].js

@@ -0,0 +1,7 @@
+// GENERATED by scripts/build-api-docs.js — do not edit by hand.
+// Cloudflare Pages Function — /api/type-graphql-dependency/*
+// Resolves retired @imqueue/type-graphql-dependency version URLs onto the kept version trees.
+// See lib/api-redirects.js for the policy and why this is not in _redirects.
+import { handleApiRequest } from "../../../lib/api-handler.js";
+
+export const onRequest = handleApiRequest;

lib/api-versions.js

@@ -11,5 +11,7 @@ export const API_VERSIONS = {
   "tag-cache": { "latest": "3.0.3", "archives": [] },
   "async-logger": { "latest": "3.2.0", "archives": [] },
   "opentelemetry-instrumentation-imqueue": { "latest": "3.3.1", "archives": [] },
-  "dd-trace": { "latest": "3.1.0", "archives": [] }
+  "dd-trace": { "latest": "3.1.0", "archives": [] },
+  "graphql-dependency": { "latest": "3.1.0", "archives": [] },
+  "type-graphql-dependency": { "latest": "3.0.3", "archives": [] }
 };

scripts/lib/api-packages.js

@@ -199,21 +199,23 @@ const PACKAGES = [
     tier: 2,
     group: 'API composition',
     tags: [],
-    blurb: 'Cross-service GraphQL dependencies for underlying @imqueue services.',
+    blurb:
+      'Declarative cross-service dependency loading for GraphQL — nested data in bulk instead of one call per resolved object.',
     cliId: 'graphql-dependency',
     latestOnly: true,
-    status: 'planned',
+    status: 'shipped',
     wave: 3,
   },
   {
     name: 'type-graphql-dependency',
     tier: 2,
     group: 'API composition',
     tags: [],
-    blurb: 'Adoption of @imqueue/graphql-dependency for use with type-graphql.',
+    blurb:
+      'The same dependency loading for type-graphql — declared on your decorated classes rather than on raw GraphQL types.',
     cliId: 'type-graphql-dependency',
     latestOnly: true,
-    status: 'planned',
+    status: 'shipped',
     wave: 3,
   },
 

src/_data/apiVersions.json

@@ -36,5 +36,13 @@
   "dd-trace": {
     "latest": "3.1.0",
     "archives": []
+  },
+  "graphql-dependency": {
+    "latest": "3.1.0",
+    "archives": []
+  },
+  "type-graphql-dependency": {
+    "latest": "3.0.3",
+    "archives": []
   }
 }

src/org/api/graphql-dependency/latest/graphql-dependency.datainitializer.md

@@ -0,0 +1,23 @@
+---
+title: "DataInitializer type · @imqueue/graphql-dependency"
+description: "An async routine that fills extra fields onto a type's own objects before its dependencies load, registered with defineInitializer()."
+apiCrumbs: [{"name":"API reference","url":"/api/"},{"name":"@imqueue/graphql-dependency","url":"/api/graphql-dependency/latest/"},{"name":"DataInitializer","url":"/api/graphql-dependency/latest/graphql-dependency.datainitializer/"}]
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# DataInitializer type
+
+An async routine that fills extra fields onto a type's own objects before its dependencies load, registered with `defineInitializer()`<!-- -->.
+
+**Signature:**
+
+```typescript
+export type DataInitializer<T> = (context: any, result: T, fields?: any) => Promise<DataInitializerResult>;
+```
+**References:** [DataInitializerResult](/api/graphql-dependency/latest/graphql-dependency.datainitializerresult/)
+
+## Remarks
+
+Its job is to supply what a dependency filter needs but the initial result does not carry — foreign ids that have to be fetched or derived first, for instance. It is handed the resolver context, the objects loaded so far, and the fields the request asked for, and returns a map keyed by object id.
+

src/org/api/graphql-dependency/latest/graphql-dependency.datainitializerresult.md

@@ -0,0 +1,22 @@
+---
+title: "DataInitializerResult interface · @imqueue/graphql-dependency"
+description: "What an initializer gives back: the extra fields to merge onto each object, keyed by that object's id."
+apiCrumbs: [{"name":"API reference","url":"/api/"},{"name":"@imqueue/graphql-dependency","url":"/api/graphql-dependency/latest/"},{"name":"DataInitializerResult","url":"/api/graphql-dependency/latest/graphql-dependency.datainitializerresult/"}]
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# DataInitializerResult interface
+
+What an initializer gives back: the extra fields to merge onto each object, keyed by that object's `id`<!-- -->.
+
+**Signature:**
+
+```typescript
+export interface DataInitializerResult 
+```
+
+## Remarks
+
+Each value is merged onto the matching object with `Object.assign`<!-- -->, so it holds only the fields being added — not a replacement object. An id with no matching object is ignored, and an object whose id is absent here is left exactly as it was.
+

src/org/api/graphql-dependency/latest/graphql-dependency.dataloader.md

@@ -0,0 +1,24 @@
+---
+title: "DataLoader type · @imqueue/graphql-dependency"
+description: "A bulk fetch for one entity type, registered with defineLoader() and called whenever that type is needed as another type's dependency."
+apiCrumbs: [{"name":"API reference","url":"/api/"},{"name":"@imqueue/graphql-dependency","url":"/api/graphql-dependency/latest/"},{"name":"DataLoader","url":"/api/graphql-dependency/latest/graphql-dependency.dataloader/"}]
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# DataLoader type
+
+A bulk fetch for one entity type, registered with `defineLoader()` and called whenever that type is needed as another type's dependency.
+
+**Signature:**
+
+```typescript
+export type DataLoader<T> = (context: any, filter: any, fields?: any) => Promise<T[]>;
+```
+
+## Remarks
+
+Every object returned must carry an `id`<!-- -->: results are keyed by it and attached to their parents by it, and one without an `id` is silently unreachable.
+
+`filter` arrives with a \*set\* of values under each key rather than one value, because a whole level of parent objects is fetched in a single call — so the implementation has to treat every key as a list. Its shape is decided by the `require()` calls that point at this type.
+

src/org/api/graphql-dependency/latest/graphql-dependency.dependency.md

@@ -0,0 +1,37 @@
+---
+title: "Dependency variable · @imqueue/graphql-dependency"
+description: "The dependency description for a GraphQL object type — an alias for GraphQLDependency.create(), and the intended way to reach every method on this package's…"
+apiCrumbs: [{"name":"API reference","url":"/api/"},{"name":"@imqueue/graphql-dependency","url":"/api/graphql-dependency/latest/"},{"name":"Dependency","url":"/api/graphql-dependency/latest/graphql-dependency.dependency/"}]
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# Dependency variable
+
+The dependency description for a GraphQL object type — an alias for [GraphQLDependency.create()](/api/graphql-dependency/latest/graphql-dependency.graphqldependency.create/)<!-- -->, and the intended way to reach every method on this package's API.
+
+**Signature:**
+
+```typescript
+Dependency: typeof GraphQLDependency.create
+```
+
+## Remarks
+
+Reads as a static constructor at the call site, but it is a lookup: the description is created on first use and the same one is returned afterwards. That is what allows `Dependency(SomeType)` to appear in as many modules as is convenient — a loader beside the type, requirements beside the relation, a `load()` in the resolver — and still describe one type once.
+
+## Example
+
+
+```typescript
+Dependency(UserType).require(CompanyType, () => ({
+    as: UserType.getFields().company,
+    filter: {
+        // the key belongs to CompanyType's loader filter, the value is the
+        // field on UserType whose values fill it
+        [CompanyType.getFields().id.name]:
+            UserType.getFields().companyId,
+    },
+}));
+```
+

src/org/api/graphql-dependency/latest/graphql-dependency.dependencyfieldsgetter.md

@@ -0,0 +1,17 @@
+---
+title: "DependencyFieldsGetter type · @imqueue/graphql-dependency"
+description: "A single field supplied as a thunk, used to name the fields an initializer fills. Deferred for the same reason as DependencyOptionsGetter."
+apiCrumbs: [{"name":"API reference","url":"/api/"},{"name":"@imqueue/graphql-dependency","url":"/api/graphql-dependency/latest/"},{"name":"DependencyFieldsGetter","url":"/api/graphql-dependency/latest/graphql-dependency.dependencyfieldsgetter/"}]
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# DependencyFieldsGetter type
+
+A single field supplied as a thunk, used to name the fields an initializer fills. Deferred for the same reason as [DependencyOptionsGetter](/api/graphql-dependency/latest/graphql-dependency.dependencyoptionsgetter/)<!-- -->.
+
+**Signature:**
+
+```typescript
+export type DependencyFieldsGetter = () => GraphQLField<any, any, any>;
+```