@makerx/graphql-core 3.2.0 → 3.4.0

package/README.md

@@ -137,15 +137,15 @@ By default, if `claims` (decoded token `JwtPayload`) are available, the `GraphQL
 
 The User class adds some handy getters over raw claims (decodedJWT payload) and provides access to the JWT (access token) for on-behalf-of downstream authentication flows. Note this may represent a user or service principal (system) identity.
 
-| Property | Description                                                                                                         |
-| -------- | ------------------------------------------------------------------------------------------------------------------- |
-| claims   | The decoded JWT payload, set via the RequestInput.user field.                                                       |
-| token    | The bearer token from the request authorization header.                                                             |
-| email    | The user's email via coalesced claim values: email, emails, preferred_username, unique_name, upn.                   |
-| name     | The user's name (via the name or given_name and family_name claims).                                                |
-| id       | The user's unique and immutable ID, useful for contextual differentiation e.g. session keys (the oid or sub claim). |
-| scopes   | The user's scopes, via the scp claim split into an array of scopes.                                                 |
-| roles    | The user's roles (via the roles claim).                                                                             |
+| Property | Description                                                                                                                 |
+| -------- | --------------------------------------------------------------------------------------------------------------------------- |
+| claims   | The decoded JWT payload, set via the RequestInput.user field.                                                               |
+| token    | The access token. By default, the bearer token from the `Authorization` header (see [Token extraction](#token-extraction)). |
+| email    | The user's email via coalesced claim values: email, emails, preferred_username, unique_name, upn.                           |
+| name     | The user's name (via the name or given_name and family_name claims).                                                        |
+| id       | The user's unique and immutable ID, useful for contextual differentiation e.g. session keys (the oid or sub claim).         |
+| scopes   | The user's scopes, via the scp claim split into an array of scopes.                                                         |
+| roles    | The user's roles (via the roles claim).                                                                                     |
 
 ### Custom user
 
@@ -163,6 +163,19 @@ const graphqlServer = createServer({
 })
 ```
 
+### Token extraction
+
+The default `createUser` sets `User.token` to the bearer token from the `Authorization` header. If clients authenticate another way, for example with a JWT assertion header that a proxy adds to the request, supply `extractToken` to return the token:
+
+```ts
+const createContext = createContextFactory({
+  requestLogger,
+  extractToken: ({ req }) => req.headers['x-goog-iap-jwt-assertion'] as string | undefined,
+})
+```
+
+`extractToken` is not called when you supply `createUser`. For subscriptions, see [GraphQL subscriptions](#graphql-subscriptions).
+
 ## Shield (authorization)
 
 The `shield` module provides typed helpers around [graphql-shield](https://the-guild.dev/graphql/shield) for defining authorization middleware against your generated `Resolvers` type.
@@ -281,6 +294,38 @@ Refer to the `GraphQLLogOperationInfo` type for the definition of input.
 
 This function can be used across implementations, e.g. in a [GraphQL Envelop plugin](https://www.envelop.dev/docs/plugins) or [ApolloServer plugin](https://github.com/MakerXStudio/graphql-apollo-server/blob/main/src/plugins/graphql-operation-logging-plugin.ts).
 
+## Deprecation usage
+
+### collectDeprecatedElementUsage
+
+Reports every `@deprecated` schema element an operation uses, so you can tell whether a deprecated element is safe to remove.
+
+```ts
+const { elements, truncated } = collectDeprecatedElementUsage({ schema, document, operation, operationName, variables })
+// elements:  [{ kind: 'input-field', name: 'WidgetFilterInput.legacyId', path: '$input.legacyId' }]
+// truncated: false
+```
+
+Five kinds are detected: `output-field`, `argument`, `directive-argument`, `input-field` and `enum-value`.
+
+Output fields and arguments are named in the operation document, so an AST walk finds them. Input fields and enum values are data the caller _supplies_ rather than selects, and can arrive either as a document literal or inside a variable — where the name appears nowhere in the AST — so the supplied variable values are walked too, against their declared input types.
+
+Consumers generally don't call this directly. It is wired into `useSubscriptionsServer` via `includeDeprecatedElements` (below), and into Apollo Server by the `includeDeprecatedElements` option of [`graphqlOperationLoggingPlugin`](https://github.com/MakerXStudio/graphql-apollo-server), which adds the result to the operation log entry as `deprecatedElements`.
+
+Behaviour worth knowing:
+
+- **Results are deduplicated** on kind and name, and sorted. One request produces at most one entry per distinct element, so a 40-element list carrying the same deprecated field yields one record, not 40.
+- **Only the executed operation counts.** A document may hold several operations but only one runs, so the others — and any fragments only they reach — are excluded.
+- **Presence is the signal, explicit `null` included.** A client still sending a field would break if it were removed.
+- **It never throws on malformed variables.** The walk runs before graphql-js coerces variables, so a payload whose shape contradicts its declared type reaches it; such values yield no records rather than an error.
+- **Work is bounded** by `maxVariableDepth` (default 25), `maxVariableNodes` (default 10,000) and `maxElements` (default 50). Whenever any of them stops collection early, `truncated` is `true`.
+- **`truncated` guards against a false negative.** Absence from `elements` only means an element went unused when `truncated` is `false`; on a truncated result the walk stopped before it finished. This matters because reading "nothing uses this" off an incomplete result is exactly how a still-used element gets deleted. Deduplication and null values do not set it — nothing is lost in either case.
+
+Two limitations to design around:
+
+- **This is request-side telemetry.** It observes values a caller _sends_, never values the server returns. A deprecated enum value that only ever appears in responses reads as unused however often the server returns it.
+- **`path` is a best-effort debugging aid, not an aggregation key.** Aggregate on `name`. A field selected inside a fragment definition has no enclosing field in its ancestry, so its path is relative to the fragment rather than the operation — which is the common case for clients that use generated fragments.
+
 ## GraphQL subscriptions
 
 This library includes a `subscriptions` module to provide simple setup using the [GraphQL WS](https://the-guild.dev/graphql/ws) package.
@@ -331,10 +376,12 @@ This library includes a `subscriptions` module to provide simple setup using the
 1. Create a subscriptions server, using the ws-server cleanup function in your server lifecycle.
 
    The `useSubscriptionsServer` function sets up:
-   - Auth token validation as part of establishing (or rejecting) the connection (behaviour defined by `verifyToken` and `requireAuth` args)
+   - Auth token validation as part of establishing (or rejecting) the connection (behaviour defined by `verifyToken`, `extractToken` and `requireAuth` args)
    - GraphQL context creation
    - Logging from the server `onConnect`, `onDisconnect`, `onOperation`, `onNext` and `onError` callbacks
 
+   Pass `includeDeprecatedElements: true` to add [deprecation usage](#collectdeprecatedelementusage) to the operation log entry as `deprecatedElements`. It is collected once, when the subscription is established, rather than per emitted payload — the usage is a property of the operation, not of each event.
+
    Example for Apollo Server (`wsServerCleanup` called in the `drainServer` plugin callback):
 
    ```ts
@@ -366,6 +413,17 @@ This library includes a `subscriptions` module to provide simple setup using the
 
 1. For authorisation, clients can include a connection parameter named `authorization` or `Authorization` using the HTTP header format `Bearer <token>`. Note: [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer) will include an `Authorization` connection parameter when you specify an HTTP `Authorization` header via the UI.
 
+   If the token arrives another way, supply an `extractToken` function to both `useSubscriptionsServer` (which passes the token to `verifyToken`) and `createSubscriptionContextFactory` (which sets it as `User.token`). It receives the `connectRequest` (the HTTP upgrade request) and the `connectionParams`, and returns the token or `undefined`. For example, to read a JWT assertion header that a proxy adds to the upgrade request (browsers cannot set custom headers on a websocket request):
+
+   ```ts
+   const extractToken: ExtractSubscriptionToken = ({ connectRequest }) =>
+     connectRequest.headers['x-goog-iap-jwt-assertion'] as string | undefined
+
+   const createSubscriptionContext = createSubscriptionContextFactory({ requestLogger, extractToken })
+
+   useSubscriptionsServer({ schema, httpServer, logger, createSubscriptionContext, extractToken, requireAuth: true, verifyToken })
+   ```
+
 ### wrapSubscriptionIterator
 
 Wraps an `AsyncIterableIterator` (e.g. one returned by a pubsub `asyncIterableIterator(...)` call) with two optional behaviours:

package/context.d.cts

@@ -51,12 +51,19 @@ export interface ContextInput {
 export type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>;
 export type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (requestMetadata: Record<string, unknown>, user: TUser) => TLogger;
 export type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>;
+export type ExtractToken = (input: ContextInput) => string | undefined;
 export type CreateContextConfig<TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger> = {
     requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger;
     augmentRequestInfo?: AugmentRequestInfo;
     claimsToLog?: string[];
     requestInfoToLog?: Array<RequestInfoLogKey>;
     augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>;
+    /**
+     * Returns the token that the default `createUser` sets as `User.token`, e.g. from a JWT assertion
+     * header. Not called when you supply `createUser`. Defaults to the bearer token in the
+     * `Authorization` header.
+     */
+    extractToken?: ExtractToken;
 } & ([User | undefined] extends [TUser] ? {
     createUser?: CreateUser<TUser>;
 } : {

package/context.d.mts

@@ -51,12 +51,19 @@ export interface ContextInput {
 export type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>;
 export type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (requestMetadata: Record<string, unknown>, user: TUser) => TLogger;
 export type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>;
+export type ExtractToken = (input: ContextInput) => string | undefined;
 export type CreateContextConfig<TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger> = {
     requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger;
     augmentRequestInfo?: AugmentRequestInfo;
     claimsToLog?: string[];
     requestInfoToLog?: Array<RequestInfoLogKey>;
     augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>;
+    /**
+     * Returns the token that the default `createUser` sets as `User.token`, e.g. from a JWT assertion
+     * header. Not called when you supply `createUser`. Defaults to the bearer token in the
+     * `Authorization` header.
+     */
+    extractToken?: ExtractToken;
 } & ([User | undefined] extends [TUser] ? {
     createUser?: CreateUser<TUser>;
 } : {

package/context.d.ts

@@ -51,12 +51,19 @@ export interface ContextInput {
 export type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>;
 export type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (requestMetadata: Record<string, unknown>, user: TUser) => TLogger;
 export type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>;
+export type ExtractToken = (input: ContextInput) => string | undefined;
 export type CreateContextConfig<TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger> = {
     requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger;
     augmentRequestInfo?: AugmentRequestInfo;
     claimsToLog?: string[];
     requestInfoToLog?: Array<RequestInfoLogKey>;
     augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>;
+    /**
+     * Returns the token that the default `createUser` sets as `User.token`, e.g. from a JWT assertion
+     * header. Not called when you supply `createUser`. Defaults to the bearer token in the
+     * `Authorization` header.
+     */
+    extractToken?: ExtractToken;
 } & ([User | undefined] extends [TUser] ? {
     createUser?: CreateUser<TUser>;
 } : {

package/context.js

@@ -8,7 +8,7 @@ const createContextFactory = (config) => {
     const { requestLogger, augmentRequestInfo, claimsToLog, requestInfoToLog, augmentContext } = config;
     // The conditional type on CreateContextConfig guarantees `createUser` is provided when TUser is
     // narrower than `User | undefined`, so defaulting to defaultCreateUser is sound here.
-    const createUser = (config.createUser ?? defaultCreateUser);
+    const createUser = (config.createUser ?? buildDefaultCreateUser(config.extractToken ?? defaultExtractToken));
     return async (input) => {
         const { req, claims, context } = input;
         // build base request info from the request
@@ -57,12 +57,13 @@ const createContextFactory = (config) => {
         return augmentedGraphQLContext;
     };
 };
-const defaultCreateUser = ({ req, claims }) => {
-    if (!claims)
+const defaultExtractToken = ({ req }) => req.headers.authorization?.startsWith('Bearer') ? req.headers.authorization.substring(7) : undefined;
+const buildDefaultCreateUser = (extractToken) => (input) => {
+    if (!input.claims)
         return Promise.resolve(undefined);
-    const accessToken = req.headers.authorization?.startsWith('Bearer') ? (req.headers.authorization?.substring(7) ?? '') : '';
-    return Promise.resolve(new User.User(claims, accessToken));
+    return Promise.resolve(new User.User(input.claims, extractToken(input) ?? ''));
 };
+const defaultCreateUser = buildDefaultCreateUser(defaultExtractToken);
 
 exports.createContextFactory = createContextFactory;
 exports.defaultCreateUser = defaultCreateUser;

package/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sources":["../src/context.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { pick } from 'es-toolkit/compat'\nimport type { Request } from 'express'\nimport { buildBaseRequestInfo, type BaseRequestInfo } from './request-info'\nimport { User } from './User'\n\nexport interface GraphQLContext<\n  TLogger extends Logger = Logger,\n  TRequestInfo extends BaseRequestInfo = RequestInfo,\n  TUser = User | undefined,\n> {\n  logger: TLogger\n  requestInfo: TRequestInfo\n  user: TUser\n  started: number\n}\n\nexport type AnyGraphqlContext = GraphQLContext<any, any, any>\n\nexport interface LambdaContext {\n  functionName?: string\n  awsRequestId?: string\n}\nexport type LambdaEvent = never\nexport type LambdaRequestInfo = BaseRequestInfo & LambdaContext\nexport type RequestInfo = BaseRequestInfo | LambdaRequestInfo\n\n// Strips the `[key: string]: unknown` index signature so `keyof` returns only the declared keys.\ntype KnownKeys<T> = keyof {\n  [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]\n}\n// Known keys for autocomplete, plus `(string & {})` to keep arbitrary augmented fields assignable.\nexport type RequestInfoLogKey = KnownKeys<BaseRequestInfo> | keyof LambdaContext | (string & {})\n\n// standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1\nexport interface JwtPayload {\n  [key: string]: unknown\n  name?: string | undefined\n  email?: string | undefined\n  given_name?: string | undefined\n  family_name?: string | undefined\n  preferred_username?: string | undefined\n  upn?: string | undefined\n  unique_name?: string | undefined\n  oid?: string | undefined\n  iss?: string | undefined\n  sub?: string | undefined\n  aud?: string | string[] | undefined\n  roles?: string[] | undefined\n  scp?: string | undefined\n  exp?: number | undefined\n  nbf?: number | undefined\n  iat?: number | undefined\n  jti?: string | undefined\n}\n\nexport type InferUserFromContext<TContext extends AnyGraphqlContext> =\n  TContext extends GraphQLContext<any, any, infer TUser> ? TUser : never\nexport type CreateUser<T = User | undefined> = (input: Omit<ContextInput, 'createUser'>) => Promise<T> | T\nexport interface ContextInput {\n  req: Request\n  claims?: JwtPayload\n  context?: LambdaContext\n  event?: LambdaEvent\n}\nexport type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>\nexport type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (\n  requestMetadata: Record<string, unknown>,\n  user: TUser,\n) => TLogger\nexport type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>\n\n// `createUser` is optional when TUser is compatible with the default `User | undefined`\n// (i.e. `defaultCreateUser` can satisfy it), and required when TUser is narrower.\nexport type CreateContextConfig<\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n> = {\n  requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger\n  augmentRequestInfo?: AugmentRequestInfo\n  claimsToLog?: string[]\n  requestInfoToLog?: Array<RequestInfoLogKey>\n  augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>\n} & ([User | undefined] extends [TUser] ? { createUser?: CreateUser<TUser> } : { createUser: CreateUser<TUser> })\n\nexport const createContextFactory = <\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n>(\n  config: CreateContextConfig<TUser, TAugment, TLogger>,\n): CreateContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment> => {\n  const { requestLogger, augmentRequestInfo, claimsToLog, requestInfoToLog, augmentContext } = config\n  // The conditional type on CreateContextConfig guarantees `createUser` is provided when TUser is\n  // narrower than `User | undefined`, so defaulting to defaultCreateUser is sound here.\n  const createUser = (config.createUser ?? defaultCreateUser) as CreateUser<TUser>\n\n  return async (input: ContextInput) => {\n    const { req, claims, context } = input\n\n    // build base request info from the request\n    const baseRequestInfo: BaseRequestInfo = buildBaseRequestInfo(req)\n\n    // add lambda info from the context, if present\n    let lambdaRequestInfo: LambdaRequestInfo | undefined\n    if (context) {\n      const { awsRequestId, functionName } = context\n      lambdaRequestInfo = {\n        awsRequestId,\n        functionName,\n        ...baseRequestInfo,\n      }\n    }\n\n    // augment request info with the supplied function, if present\n    let requestInfo: RequestInfo = lambdaRequestInfo ?? baseRequestInfo\n    if (augmentRequestInfo)\n      requestInfo = {\n        ...requestInfo,\n        ...augmentRequestInfo(input),\n      }\n\n    const user = await createUser(input)\n\n    // create request logger\n    let logger: TLogger\n    if (typeof requestLogger === 'function') {\n      // build request logger metadata\n      const requestLoggerMetadata: Record<string, unknown> = {}\n      // add request info to log\n      if (requestInfoToLog?.length) requestLoggerMetadata.request = pick(requestInfo, requestInfoToLog)\n      // add user claims to log\n      if (claims && claimsToLog?.length) requestLoggerMetadata.user = pick(claims, claimsToLog)\n      // build the request logger\n      logger = requestLogger(requestLoggerMetadata, user)\n    } else logger = requestLogger\n\n    const graphqlContext: GraphQLContext<TLogger, RequestInfo, TUser> = {\n      requestInfo,\n      logger,\n      user,\n      started: Date.now(),\n    }\n\n    const augmentedGraphQLContext = augmentContext ? { ...graphqlContext, ...(await augmentContext(graphqlContext)) } : graphqlContext\n\n    return augmentedGraphQLContext as GraphQLContext<TLogger, RequestInfo, TUser> & TAugment\n  }\n}\n\nexport const defaultCreateUser: CreateUser<User | undefined> = ({ req, claims }) => {\n  if (!claims) return Promise.resolve(undefined)\n  const accessToken = req.headers.authorization?.startsWith('Bearer') ? (req.headers.authorization?.substring(7) ?? '') : ''\n  return Promise.resolve(new User(claims, accessToken))\n}\n"],"names":["buildBaseRequestInfo","requestInfo","pick","User"],"mappings":";;;;;;AAsFO,MAAM,oBAAoB,GAAG,CAKlC,MAAqD,KACoB;AACzE,IAAA,MAAM,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,GAAG,MAAM;;;IAGnG,MAAM,UAAU,IAAI,MAAM,CAAC,UAAU,IAAI,iBAAiB,CAAsB;AAEhF,IAAA,OAAO,OAAO,KAAmB,KAAI;QACnC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK;;AAGtC,QAAA,MAAM,eAAe,GAAoBA,gCAAoB,CAAC,GAAG,CAAC;;AAGlE,QAAA,IAAI,iBAAgD;QACpD,IAAI,OAAO,EAAE;AACX,YAAA,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO;AAC9C,YAAA,iBAAiB,GAAG;gBAClB,YAAY;gBACZ,YAAY;AACZ,gBAAA,GAAG,eAAe;aACnB;QACH;;AAGA,QAAA,IAAIC,aAAW,GAAgB,iBAAiB,IAAI,eAAe;AACnE,QAAA,IAAI,kBAAkB;AACpB,YAAAA,aAAW,GAAG;AACZ,gBAAA,GAAGA,aAAW;gBACd,GAAG,kBAAkB,CAAC,KAAK,CAAC;aAC7B;AAEH,QAAA,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC;;AAGpC,QAAA,IAAI,MAAe;AACnB,QAAA,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE;;YAEvC,MAAM,qBAAqB,GAA4B,EAAE;;YAEzD,IAAI,gBAAgB,EAAE,MAAM;gBAAE,qBAAqB,CAAC,OAAO,GAAGC,WAAI,CAACD,aAAW,EAAE,gBAAgB,CAAC;;AAEjG,YAAA,IAAI,MAAM,IAAI,WAAW,EAAE,MAAM;gBAAE,qBAAqB,CAAC,IAAI,GAAGC,WAAI,CAAC,MAAM,EAAE,WAAW,CAAC;;AAEzF,YAAA,MAAM,GAAG,aAAa,CAAC,qBAAqB,EAAE,IAAI,CAAC;QACrD;;YAAO,MAAM,GAAG,aAAa;AAE7B,QAAA,MAAM,cAAc,GAAgD;yBAClED,aAAW;YACX,MAAM;YACN,IAAI;AACJ,YAAA,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;SACpB;QAED,MAAM,uBAAuB,GAAG,cAAc,GAAG,EAAE,GAAG,cAAc,EAAE,IAAI,MAAM,cAAc,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,cAAc;AAElI,QAAA,OAAO,uBAAiF;AAC1F,IAAA,CAAC;AACH;AAEO,MAAM,iBAAiB,GAAiC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAI;AACjF,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;AAC9C,IAAA,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE;AAC1H,IAAA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAIE,SAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AACvD;;;;;"}
+{"version":3,"file":"context.js","sources":["../src/context.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { pick } from 'es-toolkit/compat'\nimport type { Request } from 'express'\nimport { buildBaseRequestInfo, type BaseRequestInfo } from './request-info'\nimport { User } from './User'\n\nexport interface GraphQLContext<\n  TLogger extends Logger = Logger,\n  TRequestInfo extends BaseRequestInfo = RequestInfo,\n  TUser = User | undefined,\n> {\n  logger: TLogger\n  requestInfo: TRequestInfo\n  user: TUser\n  started: number\n}\n\nexport type AnyGraphqlContext = GraphQLContext<any, any, any>\n\nexport interface LambdaContext {\n  functionName?: string\n  awsRequestId?: string\n}\nexport type LambdaEvent = never\nexport type LambdaRequestInfo = BaseRequestInfo & LambdaContext\nexport type RequestInfo = BaseRequestInfo | LambdaRequestInfo\n\n// Strips the `[key: string]: unknown` index signature so `keyof` returns only the declared keys.\ntype KnownKeys<T> = keyof {\n  [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]\n}\n// Known keys for autocomplete, plus `(string & {})` to keep arbitrary augmented fields assignable.\nexport type RequestInfoLogKey = KnownKeys<BaseRequestInfo> | keyof LambdaContext | (string & {})\n\n// standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1\nexport interface JwtPayload {\n  [key: string]: unknown\n  name?: string | undefined\n  email?: string | undefined\n  given_name?: string | undefined\n  family_name?: string | undefined\n  preferred_username?: string | undefined\n  upn?: string | undefined\n  unique_name?: string | undefined\n  oid?: string | undefined\n  iss?: string | undefined\n  sub?: string | undefined\n  aud?: string | string[] | undefined\n  roles?: string[] | undefined\n  scp?: string | undefined\n  exp?: number | undefined\n  nbf?: number | undefined\n  iat?: number | undefined\n  jti?: string | undefined\n}\n\nexport type InferUserFromContext<TContext extends AnyGraphqlContext> =\n  TContext extends GraphQLContext<any, any, infer TUser> ? TUser : never\nexport type CreateUser<T = User | undefined> = (input: Omit<ContextInput, 'createUser'>) => Promise<T> | T\nexport interface ContextInput {\n  req: Request\n  claims?: JwtPayload\n  context?: LambdaContext\n  event?: LambdaEvent\n}\nexport type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>\nexport type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (\n  requestMetadata: Record<string, unknown>,\n  user: TUser,\n) => TLogger\nexport type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>\nexport type ExtractToken = (input: ContextInput) => string | undefined\n\n// `createUser` is optional when TUser is compatible with the default `User | undefined`\n// (i.e. `defaultCreateUser` can satisfy it), and required when TUser is narrower.\nexport type CreateContextConfig<\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n> = {\n  requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger\n  augmentRequestInfo?: AugmentRequestInfo\n  claimsToLog?: string[]\n  requestInfoToLog?: Array<RequestInfoLogKey>\n  augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>\n  /**\n   * Returns the token that the default `createUser` sets as `User.token`, e.g. from a JWT assertion\n   * header. Not called when you supply `createUser`. Defaults to the bearer token in the\n   * `Authorization` header.\n   */\n  extractToken?: ExtractToken\n} & ([User | undefined] extends [TUser] ? { createUser?: CreateUser<TUser> } : { createUser: CreateUser<TUser> })\n\nexport const createContextFactory = <\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n>(\n  config: CreateContextConfig<TUser, TAugment, TLogger>,\n): CreateContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment> => {\n  const { requestLogger, augmentRequestInfo, claimsToLog, requestInfoToLog, augmentContext } = config\n  // The conditional type on CreateContextConfig guarantees `createUser` is provided when TUser is\n  // narrower than `User | undefined`, so defaulting to defaultCreateUser is sound here.\n  const createUser = (config.createUser ?? buildDefaultCreateUser(config.extractToken ?? defaultExtractToken)) as CreateUser<TUser>\n\n  return async (input: ContextInput) => {\n    const { req, claims, context } = input\n\n    // build base request info from the request\n    const baseRequestInfo: BaseRequestInfo = buildBaseRequestInfo(req)\n\n    // add lambda info from the context, if present\n    let lambdaRequestInfo: LambdaRequestInfo | undefined\n    if (context) {\n      const { awsRequestId, functionName } = context\n      lambdaRequestInfo = {\n        awsRequestId,\n        functionName,\n        ...baseRequestInfo,\n      }\n    }\n\n    // augment request info with the supplied function, if present\n    let requestInfo: RequestInfo = lambdaRequestInfo ?? baseRequestInfo\n    if (augmentRequestInfo)\n      requestInfo = {\n        ...requestInfo,\n        ...augmentRequestInfo(input),\n      }\n\n    const user = await createUser(input)\n\n    // create request logger\n    let logger: TLogger\n    if (typeof requestLogger === 'function') {\n      // build request logger metadata\n      const requestLoggerMetadata: Record<string, unknown> = {}\n      // add request info to log\n      if (requestInfoToLog?.length) requestLoggerMetadata.request = pick(requestInfo, requestInfoToLog)\n      // add user claims to log\n      if (claims && claimsToLog?.length) requestLoggerMetadata.user = pick(claims, claimsToLog)\n      // build the request logger\n      logger = requestLogger(requestLoggerMetadata, user)\n    } else logger = requestLogger\n\n    const graphqlContext: GraphQLContext<TLogger, RequestInfo, TUser> = {\n      requestInfo,\n      logger,\n      user,\n      started: Date.now(),\n    }\n\n    const augmentedGraphQLContext = augmentContext ? { ...graphqlContext, ...(await augmentContext(graphqlContext)) } : graphqlContext\n\n    return augmentedGraphQLContext as GraphQLContext<TLogger, RequestInfo, TUser> & TAugment\n  }\n}\n\nconst defaultExtractToken: ExtractToken = ({ req }) =>\n  req.headers.authorization?.startsWith('Bearer') ? req.headers.authorization.substring(7) : undefined\n\nconst buildDefaultCreateUser =\n  (extractToken: ExtractToken): CreateUser<User | undefined> =>\n  (input) => {\n    if (!input.claims) return Promise.resolve(undefined)\n    return Promise.resolve(new User(input.claims, extractToken(input) ?? ''))\n  }\n\nexport const defaultCreateUser = buildDefaultCreateUser(defaultExtractToken)\n"],"names":["buildBaseRequestInfo","requestInfo","pick","User"],"mappings":";;;;;;AA6FO,MAAM,oBAAoB,GAAG,CAKlC,MAAqD,KACoB;AACzE,IAAA,MAAM,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,GAAG,MAAM;;;AAGnG,IAAA,MAAM,UAAU,IAAI,MAAM,CAAC,UAAU,IAAI,sBAAsB,CAAC,MAAM,CAAC,YAAY,IAAI,mBAAmB,CAAC,CAAsB;AAEjI,IAAA,OAAO,OAAO,KAAmB,KAAI;QACnC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK;;AAGtC,QAAA,MAAM,eAAe,GAAoBA,gCAAoB,CAAC,GAAG,CAAC;;AAGlE,QAAA,IAAI,iBAAgD;QACpD,IAAI,OAAO,EAAE;AACX,YAAA,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO;AAC9C,YAAA,iBAAiB,GAAG;gBAClB,YAAY;gBACZ,YAAY;AACZ,gBAAA,GAAG,eAAe;aACnB;QACH;;AAGA,QAAA,IAAIC,aAAW,GAAgB,iBAAiB,IAAI,eAAe;AACnE,QAAA,IAAI,kBAAkB;AACpB,YAAAA,aAAW,GAAG;AACZ,gBAAA,GAAGA,aAAW;gBACd,GAAG,kBAAkB,CAAC,KAAK,CAAC;aAC7B;AAEH,QAAA,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC;;AAGpC,QAAA,IAAI,MAAe;AACnB,QAAA,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE;;YAEvC,MAAM,qBAAqB,GAA4B,EAAE;;YAEzD,IAAI,gBAAgB,EAAE,MAAM;gBAAE,qBAAqB,CAAC,OAAO,GAAGC,WAAI,CAACD,aAAW,EAAE,gBAAgB,CAAC;;AAEjG,YAAA,IAAI,MAAM,IAAI,WAAW,EAAE,MAAM;gBAAE,qBAAqB,CAAC,IAAI,GAAGC,WAAI,CAAC,MAAM,EAAE,WAAW,CAAC;;AAEzF,YAAA,MAAM,GAAG,aAAa,CAAC,qBAAqB,EAAE,IAAI,CAAC;QACrD;;YAAO,MAAM,GAAG,aAAa;AAE7B,QAAA,MAAM,cAAc,GAAgD;yBAClED,aAAW;YACX,MAAM;YACN,IAAI;AACJ,YAAA,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;SACpB;QAED,MAAM,uBAAuB,GAAG,cAAc,GAAG,EAAE,GAAG,cAAc,EAAE,IAAI,MAAM,cAAc,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,cAAc;AAElI,QAAA,OAAO,uBAAiF;AAC1F,IAAA,CAAC;AACH;AAEA,MAAM,mBAAmB,GAAiB,CAAC,EAAE,GAAG,EAAE,KAChD,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;AAEtG,MAAM,sBAAsB,GAC1B,CAAC,YAA0B,KAC3B,CAAC,KAAK,KAAI;IACR,IAAI,CAAC,KAAK,CAAC,MAAM;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;AACpD,IAAA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAIE,SAAI,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3E,CAAC;MAEU,iBAAiB,GAAG,sBAAsB,CAAC,mBAAmB;;;;;"}

package/context.mjs

@@ -6,7 +6,7 @@ const createContextFactory = (config) => {
     const { requestLogger, augmentRequestInfo, claimsToLog, requestInfoToLog, augmentContext } = config;
     // The conditional type on CreateContextConfig guarantees `createUser` is provided when TUser is
     // narrower than `User | undefined`, so defaulting to defaultCreateUser is sound here.
-    const createUser = (config.createUser ?? defaultCreateUser);
+    const createUser = (config.createUser ?? buildDefaultCreateUser(config.extractToken ?? defaultExtractToken));
     return async (input) => {
         const { req, claims, context } = input;
         // build base request info from the request
@@ -55,12 +55,13 @@ const createContextFactory = (config) => {
         return augmentedGraphQLContext;
     };
 };
-const defaultCreateUser = ({ req, claims }) => {
-    if (!claims)
+const defaultExtractToken = ({ req }) => req.headers.authorization?.startsWith('Bearer') ? req.headers.authorization.substring(7) : undefined;
+const buildDefaultCreateUser = (extractToken) => (input) => {
+    if (!input.claims)
         return Promise.resolve(undefined);
-    const accessToken = req.headers.authorization?.startsWith('Bearer') ? (req.headers.authorization?.substring(7) ?? '') : '';
-    return Promise.resolve(new User(claims, accessToken));
+    return Promise.resolve(new User(input.claims, extractToken(input) ?? ''));
 };
+const defaultCreateUser = buildDefaultCreateUser(defaultExtractToken);
 
 export { createContextFactory, defaultCreateUser };
 //# sourceMappingURL=context.mjs.map

package/context.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"context.mjs","sources":["../src/context.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { pick } from 'es-toolkit/compat'\nimport type { Request } from 'express'\nimport { buildBaseRequestInfo, type BaseRequestInfo } from './request-info'\nimport { User } from './User'\n\nexport interface GraphQLContext<\n  TLogger extends Logger = Logger,\n  TRequestInfo extends BaseRequestInfo = RequestInfo,\n  TUser = User | undefined,\n> {\n  logger: TLogger\n  requestInfo: TRequestInfo\n  user: TUser\n  started: number\n}\n\nexport type AnyGraphqlContext = GraphQLContext<any, any, any>\n\nexport interface LambdaContext {\n  functionName?: string\n  awsRequestId?: string\n}\nexport type LambdaEvent = never\nexport type LambdaRequestInfo = BaseRequestInfo & LambdaContext\nexport type RequestInfo = BaseRequestInfo | LambdaRequestInfo\n\n// Strips the `[key: string]: unknown` index signature so `keyof` returns only the declared keys.\ntype KnownKeys<T> = keyof {\n  [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]\n}\n// Known keys for autocomplete, plus `(string & {})` to keep arbitrary augmented fields assignable.\nexport type RequestInfoLogKey = KnownKeys<BaseRequestInfo> | keyof LambdaContext | (string & {})\n\n// standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1\nexport interface JwtPayload {\n  [key: string]: unknown\n  name?: string | undefined\n  email?: string | undefined\n  given_name?: string | undefined\n  family_name?: string | undefined\n  preferred_username?: string | undefined\n  upn?: string | undefined\n  unique_name?: string | undefined\n  oid?: string | undefined\n  iss?: string | undefined\n  sub?: string | undefined\n  aud?: string | string[] | undefined\n  roles?: string[] | undefined\n  scp?: string | undefined\n  exp?: number | undefined\n  nbf?: number | undefined\n  iat?: number | undefined\n  jti?: string | undefined\n}\n\nexport type InferUserFromContext<TContext extends AnyGraphqlContext> =\n  TContext extends GraphQLContext<any, any, infer TUser> ? TUser : never\nexport type CreateUser<T = User | undefined> = (input: Omit<ContextInput, 'createUser'>) => Promise<T> | T\nexport interface ContextInput {\n  req: Request\n  claims?: JwtPayload\n  context?: LambdaContext\n  event?: LambdaEvent\n}\nexport type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>\nexport type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (\n  requestMetadata: Record<string, unknown>,\n  user: TUser,\n) => TLogger\nexport type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>\n\n// `createUser` is optional when TUser is compatible with the default `User | undefined`\n// (i.e. `defaultCreateUser` can satisfy it), and required when TUser is narrower.\nexport type CreateContextConfig<\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n> = {\n  requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger\n  augmentRequestInfo?: AugmentRequestInfo\n  claimsToLog?: string[]\n  requestInfoToLog?: Array<RequestInfoLogKey>\n  augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>\n} & ([User | undefined] extends [TUser] ? { createUser?: CreateUser<TUser> } : { createUser: CreateUser<TUser> })\n\nexport const createContextFactory = <\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n>(\n  config: CreateContextConfig<TUser, TAugment, TLogger>,\n): CreateContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment> => {\n  const { requestLogger, augmentRequestInfo, claimsToLog, requestInfoToLog, augmentContext } = config\n  // The conditional type on CreateContextConfig guarantees `createUser` is provided when TUser is\n  // narrower than `User | undefined`, so defaulting to defaultCreateUser is sound here.\n  const createUser = (config.createUser ?? defaultCreateUser) as CreateUser<TUser>\n\n  return async (input: ContextInput) => {\n    const { req, claims, context } = input\n\n    // build base request info from the request\n    const baseRequestInfo: BaseRequestInfo = buildBaseRequestInfo(req)\n\n    // add lambda info from the context, if present\n    let lambdaRequestInfo: LambdaRequestInfo | undefined\n    if (context) {\n      const { awsRequestId, functionName } = context\n      lambdaRequestInfo = {\n        awsRequestId,\n        functionName,\n        ...baseRequestInfo,\n      }\n    }\n\n    // augment request info with the supplied function, if present\n    let requestInfo: RequestInfo = lambdaRequestInfo ?? baseRequestInfo\n    if (augmentRequestInfo)\n      requestInfo = {\n        ...requestInfo,\n        ...augmentRequestInfo(input),\n      }\n\n    const user = await createUser(input)\n\n    // create request logger\n    let logger: TLogger\n    if (typeof requestLogger === 'function') {\n      // build request logger metadata\n      const requestLoggerMetadata: Record<string, unknown> = {}\n      // add request info to log\n      if (requestInfoToLog?.length) requestLoggerMetadata.request = pick(requestInfo, requestInfoToLog)\n      // add user claims to log\n      if (claims && claimsToLog?.length) requestLoggerMetadata.user = pick(claims, claimsToLog)\n      // build the request logger\n      logger = requestLogger(requestLoggerMetadata, user)\n    } else logger = requestLogger\n\n    const graphqlContext: GraphQLContext<TLogger, RequestInfo, TUser> = {\n      requestInfo,\n      logger,\n      user,\n      started: Date.now(),\n    }\n\n    const augmentedGraphQLContext = augmentContext ? { ...graphqlContext, ...(await augmentContext(graphqlContext)) } : graphqlContext\n\n    return augmentedGraphQLContext as GraphQLContext<TLogger, RequestInfo, TUser> & TAugment\n  }\n}\n\nexport const defaultCreateUser: CreateUser<User | undefined> = ({ req, claims }) => {\n  if (!claims) return Promise.resolve(undefined)\n  const accessToken = req.headers.authorization?.startsWith('Bearer') ? (req.headers.authorization?.substring(7) ?? '') : ''\n  return Promise.resolve(new User(claims, accessToken))\n}\n"],"names":[],"mappings":";;;;AAsFO,MAAM,oBAAoB,GAAG,CAKlC,MAAqD,KACoB;AACzE,IAAA,MAAM,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,GAAG,MAAM;;;IAGnG,MAAM,UAAU,IAAI,MAAM,CAAC,UAAU,IAAI,iBAAiB,CAAsB;AAEhF,IAAA,OAAO,OAAO,KAAmB,KAAI;QACnC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK;;AAGtC,QAAA,MAAM,eAAe,GAAoB,oBAAoB,CAAC,GAAG,CAAC;;AAGlE,QAAA,IAAI,iBAAgD;QACpD,IAAI,OAAO,EAAE;AACX,YAAA,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO;AAC9C,YAAA,iBAAiB,GAAG;gBAClB,YAAY;gBACZ,YAAY;AACZ,gBAAA,GAAG,eAAe;aACnB;QACH;;AAGA,QAAA,IAAI,WAAW,GAAgB,iBAAiB,IAAI,eAAe;AACnE,QAAA,IAAI,kBAAkB;AACpB,YAAA,WAAW,GAAG;AACZ,gBAAA,GAAG,WAAW;gBACd,GAAG,kBAAkB,CAAC,KAAK,CAAC;aAC7B;AAEH,QAAA,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC;;AAGpC,QAAA,IAAI,MAAe;AACnB,QAAA,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE;;YAEvC,MAAM,qBAAqB,GAA4B,EAAE;;YAEzD,IAAI,gBAAgB,EAAE,MAAM;gBAAE,qBAAqB,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAC;;AAEjG,YAAA,IAAI,MAAM,IAAI,WAAW,EAAE,MAAM;gBAAE,qBAAqB,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC;;AAEzF,YAAA,MAAM,GAAG,aAAa,CAAC,qBAAqB,EAAE,IAAI,CAAC;QACrD;;YAAO,MAAM,GAAG,aAAa;AAE7B,QAAA,MAAM,cAAc,GAAgD;YAClE,WAAW;YACX,MAAM;YACN,IAAI;AACJ,YAAA,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;SACpB;QAED,MAAM,uBAAuB,GAAG,cAAc,GAAG,EAAE,GAAG,cAAc,EAAE,IAAI,MAAM,cAAc,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,cAAc;AAElI,QAAA,OAAO,uBAAiF;AAC1F,IAAA,CAAC;AACH;AAEO,MAAM,iBAAiB,GAAiC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAI;AACjF,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;AAC9C,IAAA,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE;AAC1H,IAAA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;AACvD;;;;"}
+{"version":3,"file":"context.mjs","sources":["../src/context.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { pick } from 'es-toolkit/compat'\nimport type { Request } from 'express'\nimport { buildBaseRequestInfo, type BaseRequestInfo } from './request-info'\nimport { User } from './User'\n\nexport interface GraphQLContext<\n  TLogger extends Logger = Logger,\n  TRequestInfo extends BaseRequestInfo = RequestInfo,\n  TUser = User | undefined,\n> {\n  logger: TLogger\n  requestInfo: TRequestInfo\n  user: TUser\n  started: number\n}\n\nexport type AnyGraphqlContext = GraphQLContext<any, any, any>\n\nexport interface LambdaContext {\n  functionName?: string\n  awsRequestId?: string\n}\nexport type LambdaEvent = never\nexport type LambdaRequestInfo = BaseRequestInfo & LambdaContext\nexport type RequestInfo = BaseRequestInfo | LambdaRequestInfo\n\n// Strips the `[key: string]: unknown` index signature so `keyof` returns only the declared keys.\ntype KnownKeys<T> = keyof {\n  [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K]\n}\n// Known keys for autocomplete, plus `(string & {})` to keep arbitrary augmented fields assignable.\nexport type RequestInfoLogKey = KnownKeys<BaseRequestInfo> | keyof LambdaContext | (string & {})\n\n// standard claims https://datatracker.ietf.org/doc/html/rfc7519#section-4.1\nexport interface JwtPayload {\n  [key: string]: unknown\n  name?: string | undefined\n  email?: string | undefined\n  given_name?: string | undefined\n  family_name?: string | undefined\n  preferred_username?: string | undefined\n  upn?: string | undefined\n  unique_name?: string | undefined\n  oid?: string | undefined\n  iss?: string | undefined\n  sub?: string | undefined\n  aud?: string | string[] | undefined\n  roles?: string[] | undefined\n  scp?: string | undefined\n  exp?: number | undefined\n  nbf?: number | undefined\n  iat?: number | undefined\n  jti?: string | undefined\n}\n\nexport type InferUserFromContext<TContext extends AnyGraphqlContext> =\n  TContext extends GraphQLContext<any, any, infer TUser> ? TUser : never\nexport type CreateUser<T = User | undefined> = (input: Omit<ContextInput, 'createUser'>) => Promise<T> | T\nexport interface ContextInput {\n  req: Request\n  claims?: JwtPayload\n  context?: LambdaContext\n  event?: LambdaEvent\n}\nexport type CreateContext<TContext = GraphQLContext> = (input: ContextInput) => Promise<TContext>\nexport type CreateRequestLogger<TUser = User | undefined, TLogger extends Logger = Logger> = (\n  requestMetadata: Record<string, unknown>,\n  user: TUser,\n) => TLogger\nexport type AugmentRequestInfo = (input: ContextInput) => Record<string, unknown>\nexport type ExtractToken = (input: ContextInput) => string | undefined\n\n// `createUser` is optional when TUser is compatible with the default `User | undefined`\n// (i.e. `defaultCreateUser` can satisfy it), and required when TUser is narrower.\nexport type CreateContextConfig<\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n> = {\n  requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger\n  augmentRequestInfo?: AugmentRequestInfo\n  claimsToLog?: string[]\n  requestInfoToLog?: Array<RequestInfoLogKey>\n  augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>\n  /**\n   * Returns the token that the default `createUser` sets as `User.token`, e.g. from a JWT assertion\n   * header. Not called when you supply `createUser`. Defaults to the bearer token in the\n   * `Authorization` header.\n   */\n  extractToken?: ExtractToken\n} & ([User | undefined] extends [TUser] ? { createUser?: CreateUser<TUser> } : { createUser: CreateUser<TUser> })\n\nexport const createContextFactory = <\n  TUser = User | undefined,\n  TAugment extends Record<string, unknown> = Record<string, never>,\n  TLogger extends Logger = Logger,\n>(\n  config: CreateContextConfig<TUser, TAugment, TLogger>,\n): CreateContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment> => {\n  const { requestLogger, augmentRequestInfo, claimsToLog, requestInfoToLog, augmentContext } = config\n  // The conditional type on CreateContextConfig guarantees `createUser` is provided when TUser is\n  // narrower than `User | undefined`, so defaulting to defaultCreateUser is sound here.\n  const createUser = (config.createUser ?? buildDefaultCreateUser(config.extractToken ?? defaultExtractToken)) as CreateUser<TUser>\n\n  return async (input: ContextInput) => {\n    const { req, claims, context } = input\n\n    // build base request info from the request\n    const baseRequestInfo: BaseRequestInfo = buildBaseRequestInfo(req)\n\n    // add lambda info from the context, if present\n    let lambdaRequestInfo: LambdaRequestInfo | undefined\n    if (context) {\n      const { awsRequestId, functionName } = context\n      lambdaRequestInfo = {\n        awsRequestId,\n        functionName,\n        ...baseRequestInfo,\n      }\n    }\n\n    // augment request info with the supplied function, if present\n    let requestInfo: RequestInfo = lambdaRequestInfo ?? baseRequestInfo\n    if (augmentRequestInfo)\n      requestInfo = {\n        ...requestInfo,\n        ...augmentRequestInfo(input),\n      }\n\n    const user = await createUser(input)\n\n    // create request logger\n    let logger: TLogger\n    if (typeof requestLogger === 'function') {\n      // build request logger metadata\n      const requestLoggerMetadata: Record<string, unknown> = {}\n      // add request info to log\n      if (requestInfoToLog?.length) requestLoggerMetadata.request = pick(requestInfo, requestInfoToLog)\n      // add user claims to log\n      if (claims && claimsToLog?.length) requestLoggerMetadata.user = pick(claims, claimsToLog)\n      // build the request logger\n      logger = requestLogger(requestLoggerMetadata, user)\n    } else logger = requestLogger\n\n    const graphqlContext: GraphQLContext<TLogger, RequestInfo, TUser> = {\n      requestInfo,\n      logger,\n      user,\n      started: Date.now(),\n    }\n\n    const augmentedGraphQLContext = augmentContext ? { ...graphqlContext, ...(await augmentContext(graphqlContext)) } : graphqlContext\n\n    return augmentedGraphQLContext as GraphQLContext<TLogger, RequestInfo, TUser> & TAugment\n  }\n}\n\nconst defaultExtractToken: ExtractToken = ({ req }) =>\n  req.headers.authorization?.startsWith('Bearer') ? req.headers.authorization.substring(7) : undefined\n\nconst buildDefaultCreateUser =\n  (extractToken: ExtractToken): CreateUser<User | undefined> =>\n  (input) => {\n    if (!input.claims) return Promise.resolve(undefined)\n    return Promise.resolve(new User(input.claims, extractToken(input) ?? ''))\n  }\n\nexport const defaultCreateUser = buildDefaultCreateUser(defaultExtractToken)\n"],"names":[],"mappings":";;;;AA6FO,MAAM,oBAAoB,GAAG,CAKlC,MAAqD,KACoB;AACzE,IAAA,MAAM,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,gBAAgB,EAAE,cAAc,EAAE,GAAG,MAAM;;;AAGnG,IAAA,MAAM,UAAU,IAAI,MAAM,CAAC,UAAU,IAAI,sBAAsB,CAAC,MAAM,CAAC,YAAY,IAAI,mBAAmB,CAAC,CAAsB;AAEjI,IAAA,OAAO,OAAO,KAAmB,KAAI;QACnC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK;;AAGtC,QAAA,MAAM,eAAe,GAAoB,oBAAoB,CAAC,GAAG,CAAC;;AAGlE,QAAA,IAAI,iBAAgD;QACpD,IAAI,OAAO,EAAE;AACX,YAAA,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,OAAO;AAC9C,YAAA,iBAAiB,GAAG;gBAClB,YAAY;gBACZ,YAAY;AACZ,gBAAA,GAAG,eAAe;aACnB;QACH;;AAGA,QAAA,IAAI,WAAW,GAAgB,iBAAiB,IAAI,eAAe;AACnE,QAAA,IAAI,kBAAkB;AACpB,YAAA,WAAW,GAAG;AACZ,gBAAA,GAAG,WAAW;gBACd,GAAG,kBAAkB,CAAC,KAAK,CAAC;aAC7B;AAEH,QAAA,MAAM,IAAI,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC;;AAGpC,QAAA,IAAI,MAAe;AACnB,QAAA,IAAI,OAAO,aAAa,KAAK,UAAU,EAAE;;YAEvC,MAAM,qBAAqB,GAA4B,EAAE;;YAEzD,IAAI,gBAAgB,EAAE,MAAM;gBAAE,qBAAqB,CAAC,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,gBAAgB,CAAC;;AAEjG,YAAA,IAAI,MAAM,IAAI,WAAW,EAAE,MAAM;gBAAE,qBAAqB,CAAC,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC;;AAEzF,YAAA,MAAM,GAAG,aAAa,CAAC,qBAAqB,EAAE,IAAI,CAAC;QACrD;;YAAO,MAAM,GAAG,aAAa;AAE7B,QAAA,MAAM,cAAc,GAAgD;YAClE,WAAW;YACX,MAAM;YACN,IAAI;AACJ,YAAA,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE;SACpB;QAED,MAAM,uBAAuB,GAAG,cAAc,GAAG,EAAE,GAAG,cAAc,EAAE,IAAI,MAAM,cAAc,CAAC,cAAc,CAAC,CAAC,EAAE,GAAG,cAAc;AAElI,QAAA,OAAO,uBAAiF;AAC1F,IAAA,CAAC;AACH;AAEA,MAAM,mBAAmB,GAAiB,CAAC,EAAE,GAAG,EAAE,KAChD,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,QAAQ,CAAC,GAAG,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS;AAEtG,MAAM,sBAAsB,GAC1B,CAAC,YAA0B,KAC3B,CAAC,KAAK,KAAI;IACR,IAAI,CAAC,KAAK,CAAC,MAAM;AAAE,QAAA,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;AACpD,IAAA,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAC3E,CAAC;MAEU,iBAAiB,GAAG,sBAAsB,CAAC,mBAAmB;;;;"}

package/deprecation.d.cts

@@ -0,0 +1,81 @@
+import type { DocumentNode, GraphQLSchema, OperationDefinitionNode } from 'graphql';
+/**
+ * Safety valve for the variable walk. Recursion follows the schema's input types, which may be
+ * mutually recursive, and variables are walked before graphql-js coerces them — so nothing else
+ * bounds how deep a hand-crafted payload can go. Far above any real operation's nesting.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_VARIABLE_DEPTH = 25;
+/**
+ * Bounds the *breadth* of the variable walk, which the depth cap does not: a single large array of
+ * small input objects is shallow but arbitrarily wide.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_VARIABLE_NODES = 10000;
+/**
+ * Caps the collected result so one hostile document cannot blow up a log entry.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_ELEMENTS = 50;
+export type DeprecatedElementKind = 'output-field' | 'argument' | 'directive-argument' | 'input-field' | 'enum-value';
+export interface DeprecatedElementUsage {
+    kind: DeprecatedElementKind;
+    /**
+     * Stable key for aggregating usage, formatted per kind:
+     * `Type.field`, `Type.field(arg)`, `@directive(arg)`, `InputType.field`, `EnumType.VALUE`.
+     */
+    name: string;
+    /**
+     * Best-effort location, for debugging a single record — not an aggregation key. A field selected
+     * inside a fragment definition has no enclosing field in its ancestry, so its path is relative to
+     * the fragment rather than the operation.
+     */
+    path?: string;
+}
+export interface CollectDeprecatedElementUsageOptions {
+    schema: GraphQLSchema;
+    document: DocumentNode;
+    /**
+     * The executed operation. Resolved from `document` and `operationName` when omitted.
+     */
+    operation?: OperationDefinitionNode | null;
+    operationName?: string | null;
+    /**
+     * Raw request variables, as supplied by the client and before graphql-js coerces them.
+     */
+    variables?: Record<string, unknown> | null;
+    maxVariableDepth?: number;
+    maxVariableNodes?: number;
+    maxElements?: number;
+}
+export interface CollectDeprecatedElementUsageResult {
+    elements: DeprecatedElementUsage[];
+    /**
+     * True when a limit — `maxElements`, `maxVariableDepth` or `maxVariableNodes` — stopped
+     * collection before it finished, so `elements` may be missing elements the operation really used.
+     * Absence from a truncated result is not evidence that an element is unused.
+     */
+    truncated: boolean;
+}
+/**
+ * Reports every `@deprecated` schema element an operation uses, across both the document and the
+ * supplied variables.
+ *
+ * Output fields and arguments are named in the document, so an AST walk finds them. Input fields
+ * and enum values are data the caller *supplies* rather than selects: they can arrive as a document
+ * literal, or inside a variable where the name appears nowhere in the AST, so both routes are
+ * walked and the results deduplicated.
+ *
+ * Results are deduplicated on kind and name — at most one entry per distinct element per request,
+ * bounded by the size of the schema rather than the size of the request — and sorted, so records
+ * are stable across requests.
+ *
+ * Returns `truncated` when any limit stopped collection. Absence from `elements` is only evidence
+ * that an element went unused when `truncated` is false — which matters, because concluding
+ * "nothing uses this" from a truncated result is how a still-used element gets deleted.
+ *
+ * The variable walk reads untrusted input before coercion, so a payload whose shape contradicts its
+ * declared type reaches it. Every shape it depends on is guarded: malformed variables yield no
+ * records rather than an error.
+ *
+ * This is request-side telemetry — it observes values a caller *sends*, never values the server
+ * returns. A deprecated element that only ever appears in responses reads as unused.
+ */
+export declare function collectDeprecatedElementUsage({ schema, document, operation, operationName, variables, maxVariableDepth, maxVariableNodes, maxElements, }: CollectDeprecatedElementUsageOptions): CollectDeprecatedElementUsageResult;

package/deprecation.d.mts

@@ -0,0 +1,81 @@
+import type { DocumentNode, GraphQLSchema, OperationDefinitionNode } from 'graphql';
+/**
+ * Safety valve for the variable walk. Recursion follows the schema's input types, which may be
+ * mutually recursive, and variables are walked before graphql-js coerces them — so nothing else
+ * bounds how deep a hand-crafted payload can go. Far above any real operation's nesting.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_VARIABLE_DEPTH = 25;
+/**
+ * Bounds the *breadth* of the variable walk, which the depth cap does not: a single large array of
+ * small input objects is shallow but arbitrarily wide.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_VARIABLE_NODES = 10000;
+/**
+ * Caps the collected result so one hostile document cannot blow up a log entry.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_ELEMENTS = 50;
+export type DeprecatedElementKind = 'output-field' | 'argument' | 'directive-argument' | 'input-field' | 'enum-value';
+export interface DeprecatedElementUsage {
+    kind: DeprecatedElementKind;
+    /**
+     * Stable key for aggregating usage, formatted per kind:
+     * `Type.field`, `Type.field(arg)`, `@directive(arg)`, `InputType.field`, `EnumType.VALUE`.
+     */
+    name: string;
+    /**
+     * Best-effort location, for debugging a single record — not an aggregation key. A field selected
+     * inside a fragment definition has no enclosing field in its ancestry, so its path is relative to
+     * the fragment rather than the operation.
+     */
+    path?: string;
+}
+export interface CollectDeprecatedElementUsageOptions {
+    schema: GraphQLSchema;
+    document: DocumentNode;
+    /**
+     * The executed operation. Resolved from `document` and `operationName` when omitted.
+     */
+    operation?: OperationDefinitionNode | null;
+    operationName?: string | null;
+    /**
+     * Raw request variables, as supplied by the client and before graphql-js coerces them.
+     */
+    variables?: Record<string, unknown> | null;
+    maxVariableDepth?: number;
+    maxVariableNodes?: number;
+    maxElements?: number;
+}
+export interface CollectDeprecatedElementUsageResult {
+    elements: DeprecatedElementUsage[];
+    /**
+     * True when a limit — `maxElements`, `maxVariableDepth` or `maxVariableNodes` — stopped
+     * collection before it finished, so `elements` may be missing elements the operation really used.
+     * Absence from a truncated result is not evidence that an element is unused.
+     */
+    truncated: boolean;
+}
+/**
+ * Reports every `@deprecated` schema element an operation uses, across both the document and the
+ * supplied variables.
+ *
+ * Output fields and arguments are named in the document, so an AST walk finds them. Input fields
+ * and enum values are data the caller *supplies* rather than selects: they can arrive as a document
+ * literal, or inside a variable where the name appears nowhere in the AST, so both routes are
+ * walked and the results deduplicated.
+ *
+ * Results are deduplicated on kind and name — at most one entry per distinct element per request,
+ * bounded by the size of the schema rather than the size of the request — and sorted, so records
+ * are stable across requests.
+ *
+ * Returns `truncated` when any limit stopped collection. Absence from `elements` is only evidence
+ * that an element went unused when `truncated` is false — which matters, because concluding
+ * "nothing uses this" from a truncated result is how a still-used element gets deleted.
+ *
+ * The variable walk reads untrusted input before coercion, so a payload whose shape contradicts its
+ * declared type reaches it. Every shape it depends on is guarded: malformed variables yield no
+ * records rather than an error.
+ *
+ * This is request-side telemetry — it observes values a caller *sends*, never values the server
+ * returns. A deprecated element that only ever appears in responses reads as unused.
+ */
+export declare function collectDeprecatedElementUsage({ schema, document, operation, operationName, variables, maxVariableDepth, maxVariableNodes, maxElements, }: CollectDeprecatedElementUsageOptions): CollectDeprecatedElementUsageResult;

package/deprecation.d.ts

@@ -0,0 +1,81 @@
+import type { DocumentNode, GraphQLSchema, OperationDefinitionNode } from 'graphql';
+/**
+ * Safety valve for the variable walk. Recursion follows the schema's input types, which may be
+ * mutually recursive, and variables are walked before graphql-js coerces them — so nothing else
+ * bounds how deep a hand-crafted payload can go. Far above any real operation's nesting.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_VARIABLE_DEPTH = 25;
+/**
+ * Bounds the *breadth* of the variable walk, which the depth cap does not: a single large array of
+ * small input objects is shallow but arbitrarily wide.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_VARIABLE_NODES = 10000;
+/**
+ * Caps the collected result so one hostile document cannot blow up a log entry.
+ */
+export declare const DEFAULT_DEPRECATION_MAX_ELEMENTS = 50;
+export type DeprecatedElementKind = 'output-field' | 'argument' | 'directive-argument' | 'input-field' | 'enum-value';
+export interface DeprecatedElementUsage {
+    kind: DeprecatedElementKind;
+    /**
+     * Stable key for aggregating usage, formatted per kind:
+     * `Type.field`, `Type.field(arg)`, `@directive(arg)`, `InputType.field`, `EnumType.VALUE`.
+     */
+    name: string;
+    /**
+     * Best-effort location, for debugging a single record — not an aggregation key. A field selected
+     * inside a fragment definition has no enclosing field in its ancestry, so its path is relative to
+     * the fragment rather than the operation.
+     */
+    path?: string;
+}
+export interface CollectDeprecatedElementUsageOptions {
+    schema: GraphQLSchema;
+    document: DocumentNode;
+    /**
+     * The executed operation. Resolved from `document` and `operationName` when omitted.
+     */
+    operation?: OperationDefinitionNode | null;
+    operationName?: string | null;
+    /**
+     * Raw request variables, as supplied by the client and before graphql-js coerces them.
+     */
+    variables?: Record<string, unknown> | null;
+    maxVariableDepth?: number;
+    maxVariableNodes?: number;
+    maxElements?: number;
+}
+export interface CollectDeprecatedElementUsageResult {
+    elements: DeprecatedElementUsage[];
+    /**
+     * True when a limit — `maxElements`, `maxVariableDepth` or `maxVariableNodes` — stopped
+     * collection before it finished, so `elements` may be missing elements the operation really used.
+     * Absence from a truncated result is not evidence that an element is unused.
+     */
+    truncated: boolean;
+}
+/**
+ * Reports every `@deprecated` schema element an operation uses, across both the document and the
+ * supplied variables.
+ *
+ * Output fields and arguments are named in the document, so an AST walk finds them. Input fields
+ * and enum values are data the caller *supplies* rather than selects: they can arrive as a document
+ * literal, or inside a variable where the name appears nowhere in the AST, so both routes are
+ * walked and the results deduplicated.
+ *
+ * Results are deduplicated on kind and name — at most one entry per distinct element per request,
+ * bounded by the size of the schema rather than the size of the request — and sorted, so records
+ * are stable across requests.
+ *
+ * Returns `truncated` when any limit stopped collection. Absence from `elements` is only evidence
+ * that an element went unused when `truncated` is false — which matters, because concluding
+ * "nothing uses this" from a truncated result is how a still-used element gets deleted.
+ *
+ * The variable walk reads untrusted input before coercion, so a payload whose shape contradicts its
+ * declared type reaches it. Every shape it depends on is guarded: malformed variables yield no
+ * records rather than an error.
+ *
+ * This is request-side telemetry — it observes values a caller *sends*, never values the server
+ * returns. A deprecated element that only ever appears in responses reads as unused.
+ */
+export declare function collectDeprecatedElementUsage({ schema, document, operation, operationName, variables, maxVariableDepth, maxVariableNodes, maxElements, }: CollectDeprecatedElementUsageOptions): CollectDeprecatedElementUsageResult;