@makerx/graphql-core 3.0.0-beta.4 → 3.0.0-beta.6

package/User.d.cts

@@ -0,0 +1,13 @@
+import type { JwtPayload } from './context';
+export declare class User {
+    readonly token: string;
+    readonly claims: JwtPayload;
+    constructor(claims: JwtPayload, accessToken: string);
+    get email(): string | undefined;
+    get name(): string | undefined;
+    get id(): string;
+    get scopes(): string[];
+    get roles(): string[];
+    private first;
+    private firstOrThrow;
+}

package/User.d.mts

@@ -0,0 +1,13 @@
+import type { JwtPayload } from './context.js';
+export declare class User {
+    readonly token: string;
+    readonly claims: JwtPayload;
+    constructor(claims: JwtPayload, accessToken: string);
+    get email(): string | undefined;
+    get name(): string | undefined;
+    get id(): string;
+    get scopes(): string[];
+    get roles(): string[];
+    private first;
+    private firstOrThrow;
+}

package/context.d.cts

@@ -0,0 +1,67 @@
+import type { Logger } from '@makerx/node-common';
+import type { Request } from 'express';
+import { type BaseRequestInfo } from './request-info';
+import { User } from './User';
+export interface GraphQLContext<TLogger extends Logger = Logger, TRequestInfo extends BaseRequestInfo = RequestInfo, TUser = User | undefined> {
+    logger: TLogger;
+    requestInfo: TRequestInfo;
+    user: TUser;
+    started: number;
+}
+export type AnyGraphqlContext = GraphQLContext<any, any, any>;
+export interface LambdaContext {
+    functionName?: string;
+    awsRequestId?: string;
+}
+export type LambdaEvent = never;
+export type LambdaRequestInfo = BaseRequestInfo & LambdaContext;
+export type RequestInfo = BaseRequestInfo | LambdaRequestInfo;
+type KnownKeys<T> = keyof {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+export type RequestInfoLogKey = KnownKeys<BaseRequestInfo> | keyof LambdaContext | (string & {});
+export interface JwtPayload {
+    [key: string]: unknown;
+    name?: string | undefined;
+    email?: string | undefined;
+    given_name?: string | undefined;
+    family_name?: string | undefined;
+    preferred_username?: string | undefined;
+    upn?: string | undefined;
+    unique_name?: string | undefined;
+    oid?: string | undefined;
+    iss?: string | undefined;
+    sub?: string | undefined;
+    aud?: string | string[] | undefined;
+    roles?: string[] | undefined;
+    scp?: string | undefined;
+    exp?: number | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    jti?: string | undefined;
+}
+export type InferUserFromContext<TContext extends AnyGraphqlContext> = TContext extends GraphQLContext<any, any, infer TUser> ? TUser : never;
+export type CreateUser<T = User | undefined> = (input: Omit<ContextInput, 'createUser'>) => Promise<T> | T;
+export interface ContextInput {
+    req: Request;
+    claims?: JwtPayload;
+    context?: LambdaContext;
+    event?: LambdaEvent;
+}
+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 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>;
+} & ([User | undefined] extends [TUser] ? {
+    createUser?: CreateUser<TUser>;
+} : {
+    createUser: CreateUser<TUser>;
+});
+export declare const createContextFactory: <TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger>(config: CreateContextConfig<TUser, TAugment, TLogger>) => CreateContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment>;
+export declare const defaultCreateUser: CreateUser<User | undefined>;
+export {};

package/context.d.mts

@@ -0,0 +1,67 @@
+import type { Logger } from '@makerx/node-common';
+import type { Request } from 'express';
+import { type BaseRequestInfo } from './request-info.js';
+import { User } from './User.js';
+export interface GraphQLContext<TLogger extends Logger = Logger, TRequestInfo extends BaseRequestInfo = RequestInfo, TUser = User | undefined> {
+    logger: TLogger;
+    requestInfo: TRequestInfo;
+    user: TUser;
+    started: number;
+}
+export type AnyGraphqlContext = GraphQLContext<any, any, any>;
+export interface LambdaContext {
+    functionName?: string;
+    awsRequestId?: string;
+}
+export type LambdaEvent = never;
+export type LambdaRequestInfo = BaseRequestInfo & LambdaContext;
+export type RequestInfo = BaseRequestInfo | LambdaRequestInfo;
+type KnownKeys<T> = keyof {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+export type RequestInfoLogKey = KnownKeys<BaseRequestInfo> | keyof LambdaContext | (string & {});
+export interface JwtPayload {
+    [key: string]: unknown;
+    name?: string | undefined;
+    email?: string | undefined;
+    given_name?: string | undefined;
+    family_name?: string | undefined;
+    preferred_username?: string | undefined;
+    upn?: string | undefined;
+    unique_name?: string | undefined;
+    oid?: string | undefined;
+    iss?: string | undefined;
+    sub?: string | undefined;
+    aud?: string | string[] | undefined;
+    roles?: string[] | undefined;
+    scp?: string | undefined;
+    exp?: number | undefined;
+    nbf?: number | undefined;
+    iat?: number | undefined;
+    jti?: string | undefined;
+}
+export type InferUserFromContext<TContext extends AnyGraphqlContext> = TContext extends GraphQLContext<any, any, infer TUser> ? TUser : never;
+export type CreateUser<T = User | undefined> = (input: Omit<ContextInput, 'createUser'>) => Promise<T> | T;
+export interface ContextInput {
+    req: Request;
+    claims?: JwtPayload;
+    context?: LambdaContext;
+    event?: LambdaEvent;
+}
+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 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>;
+} & ([User | undefined] extends [TUser] ? {
+    createUser?: CreateUser<TUser>;
+} : {
+    createUser: CreateUser<TUser>;
+});
+export declare const createContextFactory: <TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger>(config: CreateContextConfig<TUser, TAugment, TLogger>) => CreateContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment>;
+export declare const defaultCreateUser: CreateUser<User | undefined>;
+export {};

package/index.d.cts

@@ -0,0 +1,8 @@
+export * from './context';
+export * from './logging';
+export * from './request-info';
+export * from './schema-util';
+export * from './type-utils';
+export * from './unauthorised';
+export * from './User';
+export * from './utils';

package/index.d.mts

@@ -0,0 +1,8 @@
+export * from './context.js';
+export * from './logging.js';
+export * from './request-info.js';
+export * from './schema-util.js';
+export * from './type-utils.js';
+export * from './unauthorised.js';
+export * from './User.js';
+export * from './utils.js';

package/logging.d.cts

@@ -0,0 +1,82 @@
+import type { Logger } from '@makerx/node-common';
+import type { ExecutionArgs, GraphQLFormattedError } from 'graphql';
+import { OperationTypeNode } from 'graphql';
+import type { ExecutionResult } from 'graphql-ws';
+import type { GraphQLContext } from './context';
+type LogFunction = Logger['info'];
+export type LoggerLogFunctions<T extends Logger> = {
+    [Property in keyof T]: LogFunction;
+};
+/**
+ * Info for logging a GraphQL operation in a consistent format with the option of including any additional data.
+ */
+export interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extends Record<string, unknown> {
+    /**
+     * The message to log, defaults to 'GraphQL operation'.
+     */
+    message?: string;
+    /**
+     * The timestamp when the operation started, if supplied, the duration will be logged.
+     */
+    started?: number;
+    /**
+     * The type of GraphQL operation.
+     */
+    type?: OperationTypeNode | null;
+    /**
+     * The name of the GraphQL operation.
+     */
+    operationName?: string | null;
+    /**
+     * The formatted GraphQL query.
+     */
+    query?: string | null;
+    /**
+     * The GraphQL variables.
+     */
+    variables?: Record<string, unknown> | null;
+    /**
+     * The result of the GraphQL operation.
+     * Generally, we don't log the data or extensions, just errors.
+     */
+    result?: {
+        data?: Record<string, unknown> | null;
+        errors?: readonly GraphQLFormattedError[] | null;
+        extensions?: Record<string, unknown> | null;
+        hasNext?: boolean;
+    };
+    /**
+     * Whether the operation is an introspection query.
+     */
+    isIntrospectionQuery?: boolean;
+    /**
+     * Whether the operation is part of an incremental response.
+     */
+    isIncrementalResponse?: boolean;
+    /**
+     * Whether the operation is a subsequent payload of an incremental response.
+     */
+    isSubsequentPayload?: boolean;
+    /**
+     * The logger to use.
+     */
+    logger: TLogger;
+    /**
+     * The logger function to use, defaults to 'info'.
+     */
+    logLevel?: keyof LoggerLogFunctions<TLogger>;
+}
+/**
+ * Logs a GraphQL operation in a consistent format with the option of including any additional data.
+ * Top level and result entries with null or undefined values will be omitted.
+ */
+export declare const logGraphQLOperation: <TLogger extends Logger = Logger>({ message, started, type, operationName, query, variables, result, logger, logLevel, ...rest }: GraphQLLogOperationInfo<TLogger>) => void;
+export declare const logSubscriptionOperation: <TLogger extends Logger = Logger>({ id, args, result, message, logLevel, resolveLogger, }: {
+    id?: string;
+    args: ExecutionArgs;
+    result?: ExecutionResult;
+    message?: string;
+    logLevel?: keyof LoggerLogFunctions<TLogger>;
+    resolveLogger?: (context: GraphQLContext) => TLogger;
+}) => void;
+export {};

package/logging.d.mts

@@ -0,0 +1,82 @@
+import type { Logger } from '@makerx/node-common';
+import type { ExecutionArgs, GraphQLFormattedError } from 'graphql';
+import { OperationTypeNode } from 'graphql';
+import type { ExecutionResult } from 'graphql-ws';
+import type { GraphQLContext } from './context.js';
+type LogFunction = Logger['info'];
+export type LoggerLogFunctions<T extends Logger> = {
+    [Property in keyof T]: LogFunction;
+};
+/**
+ * Info for logging a GraphQL operation in a consistent format with the option of including any additional data.
+ */
+export interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extends Record<string, unknown> {
+    /**
+     * The message to log, defaults to 'GraphQL operation'.
+     */
+    message?: string;
+    /**
+     * The timestamp when the operation started, if supplied, the duration will be logged.
+     */
+    started?: number;
+    /**
+     * The type of GraphQL operation.
+     */
+    type?: OperationTypeNode | null;
+    /**
+     * The name of the GraphQL operation.
+     */
+    operationName?: string | null;
+    /**
+     * The formatted GraphQL query.
+     */
+    query?: string | null;
+    /**
+     * The GraphQL variables.
+     */
+    variables?: Record<string, unknown> | null;
+    /**
+     * The result of the GraphQL operation.
+     * Generally, we don't log the data or extensions, just errors.
+     */
+    result?: {
+        data?: Record<string, unknown> | null;
+        errors?: readonly GraphQLFormattedError[] | null;
+        extensions?: Record<string, unknown> | null;
+        hasNext?: boolean;
+    };
+    /**
+     * Whether the operation is an introspection query.
+     */
+    isIntrospectionQuery?: boolean;
+    /**
+     * Whether the operation is part of an incremental response.
+     */
+    isIncrementalResponse?: boolean;
+    /**
+     * Whether the operation is a subsequent payload of an incremental response.
+     */
+    isSubsequentPayload?: boolean;
+    /**
+     * The logger to use.
+     */
+    logger: TLogger;
+    /**
+     * The logger function to use, defaults to 'info'.
+     */
+    logLevel?: keyof LoggerLogFunctions<TLogger>;
+}
+/**
+ * Logs a GraphQL operation in a consistent format with the option of including any additional data.
+ * Top level and result entries with null or undefined values will be omitted.
+ */
+export declare const logGraphQLOperation: <TLogger extends Logger = Logger>({ message, started, type, operationName, query, variables, result, logger, logLevel, ...rest }: GraphQLLogOperationInfo<TLogger>) => void;
+export declare const logSubscriptionOperation: <TLogger extends Logger = Logger>({ id, args, result, message, logLevel, resolveLogger, }: {
+    id?: string;
+    args: ExecutionArgs;
+    result?: ExecutionResult;
+    message?: string;
+    logLevel?: keyof LoggerLogFunctions<TLogger>;
+    resolveLogger?: (context: GraphQLContext) => TLogger;
+}) => void;
+export {};

package/logging.d.ts

@@ -71,7 +71,8 @@ export interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extend
  * Top level and result entries with null or undefined values will be omitted.
  */
 export declare const logGraphQLOperation: <TLogger extends Logger = Logger>({ message, started, type, operationName, query, variables, result, logger, logLevel, ...rest }: GraphQLLogOperationInfo<TLogger>) => void;
-export declare const logSubscriptionOperation: <TLogger extends Logger = Logger>({ args, result, message, logLevel, resolveLogger, }: {
+export declare const logSubscriptionOperation: <TLogger extends Logger = Logger>({ id, args, result, message, logLevel, resolveLogger, }: {
+    id?: string;
     args: ExecutionArgs;
     result?: ExecutionResult;
     message?: string;

package/logging.js

@@ -24,7 +24,7 @@ const logGraphQLOperation = ({ message = 'GraphQL operation', started, type, ope
         ...compat.omitBy(rest, utils.isNil),
     }, utils.isNil));
 };
-const logSubscriptionOperation = ({ args, result, message, logLevel, resolveLogger, }) => {
+const logSubscriptionOperation = ({ id, args, result, message, logLevel, resolveLogger, }) => {
     const logger = resolveLogger
         ? resolveLogger(args.contextValue)
         : args.contextValue.logger;
@@ -35,6 +35,7 @@ const logSubscriptionOperation = ({ args, result, message, logLevel, resolveLogg
     logGraphQLOperation({
         message,
         type: graphql.OperationTypeNode.SUBSCRIPTION,
+        subscriptionId: id,
         operationName,
         query: graphql.print(document),
         variables: variableValues,

package/logging.js.map

@@ -1 +1 @@
-{"version":3,"file":"logging.js","sources":["../src/logging.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { isLocalDev } from '@makerx/node-common'\nimport type { ExecutionArgs, GraphQLFormattedError } from 'graphql'\nimport { OperationTypeNode, print } from 'graphql'\nimport type { ExecutionResult } from 'graphql-ws'\nimport { omitBy } from 'es-toolkit/compat'\nimport type { GraphQLContext } from './context'\nimport { isIntrospectionQuery, isNil } from './utils'\n\ntype LogFunction = Logger['info']\nexport type LoggerLogFunctions<T extends Logger> = {\n  [Property in keyof T]: LogFunction\n}\n\n/**\n * Info for logging a GraphQL operation in a consistent format with the option of including any additional data.\n */\nexport interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extends Record<string, unknown> {\n  /**\n   * The message to log, defaults to 'GraphQL operation'.\n   */\n  message?: string\n  /**\n   * The timestamp when the operation started, if supplied, the duration will be logged.\n   */\n  started?: number\n  /**\n   * The type of GraphQL operation.\n   */\n  type?: OperationTypeNode | null\n  /**\n   * The name of the GraphQL operation.\n   */\n  operationName?: string | null\n  /**\n   * The formatted GraphQL query.\n   */\n  query?: string | null\n  /**\n   * The GraphQL variables.\n   */\n  variables?: Record<string, unknown> | null\n  /**\n   * The result of the GraphQL operation.\n   * Generally, we don't log the data or extensions, just errors.\n   */\n  result?: {\n    data?: Record<string, unknown> | null\n    errors?: readonly GraphQLFormattedError[] | null\n    extensions?: Record<string, unknown> | null\n    hasNext?: boolean\n  }\n  /**\n   * Whether the operation is an introspection query.\n   */\n  isIntrospectionQuery?: boolean\n  /**\n   * Whether the operation is part of an incremental response.\n   */\n  isIncrementalResponse?: boolean\n  /**\n   * Whether the operation is a subsequent payload of an incremental response.\n   */\n  isSubsequentPayload?: boolean\n  /**\n   * The logger to use.\n   */\n  logger: TLogger\n  /**\n   * The logger function to use, defaults to 'info'.\n   */\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n}\n\n/**\n * Logs a GraphQL operation in a consistent format with the option of including any additional data.\n * Top level and result entries with null or undefined values will be omitted.\n */\nexport const logGraphQLOperation = <TLogger extends Logger = Logger>({\n  message = 'GraphQL operation',\n  started,\n  type,\n  operationName,\n  query,\n  variables,\n  result,\n  logger,\n  logLevel = 'info',\n  ...rest\n}: GraphQLLogOperationInfo<TLogger>) => {\n  const isIntrospection = query && isIntrospectionQuery(query)\n  if (isLocalDev && isIntrospection) return\n  logger[logLevel as keyof Logger](\n    message,\n    omitBy(\n      {\n        type,\n        operationName,\n        query,\n        variables: variables && Object.keys(variables).length > 0 ? variables : undefined,\n        duration: started ? Date.now() - started : undefined,\n        result: result ? omitBy(result, isNil) : undefined,\n        isIntrospectionQuery: isIntrospection || undefined,\n        ...omitBy(rest, isNil),\n      },\n      isNil,\n    ),\n  )\n}\n\nexport const logSubscriptionOperation = <TLogger extends Logger = Logger>({\n  args,\n  result,\n  message,\n  logLevel,\n  resolveLogger,\n}: {\n  args: ExecutionArgs\n  result?: ExecutionResult\n  message?: string\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n  resolveLogger?: (context: GraphQLContext) => TLogger\n}) => {\n  const logger = resolveLogger\n    ? resolveLogger(args.contextValue as GraphQLContext)\n    : ((args.contextValue as GraphQLContext).logger as TLogger)\n  if (!logger) return\n\n  const { operationName, variableValues, document } = args\n  const { data, ...resultWithoutData } = result ?? {}\n\n  logGraphQLOperation({\n    message,\n    type: OperationTypeNode.SUBSCRIPTION,\n    operationName,\n    query: print(document),\n    variables: variableValues,\n    result: resultWithoutData,\n    logger,\n    logLevel,\n  })\n}\n"],"names":["isIntrospectionQuery","isLocalDev","omitBy","isNil","OperationTypeNode","print"],"mappings":";;;;;;;AA0EA;;;AAGG;AACI,MAAM,mBAAmB,GAAG,CAAkC,EACnE,OAAO,GAAG,mBAAmB,EAC7B,OAAO,EACP,IAAI,EACJ,aAAa,EACb,KAAK,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,QAAQ,GAAG,MAAM,EACjB,GAAG,IAAI,EAC0B,KAAI;IACrC,MAAM,eAAe,GAAG,KAAK,IAAIA,0BAAoB,CAAC,KAAK,CAAC;IAC5D,IAAIC,qBAAU,IAAI,eAAe;QAAE;AACnC,IAAA,MAAM,CAAC,QAAwB,CAAC,CAC9B,OAAO,EACPC,aAAM,CACJ;QACE,IAAI;QACJ,aAAa;QACb,KAAK;QACL,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,SAAS;AACjF,QAAA,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,SAAS;AACpD,QAAA,MAAM,EAAE,MAAM,GAAGA,aAAM,CAAC,MAAM,EAAEC,WAAK,CAAC,GAAG,SAAS;QAClD,oBAAoB,EAAE,eAAe,IAAI,SAAS;AAClD,QAAA,GAAGD,aAAM,CAAC,IAAI,EAAEC,WAAK,CAAC;KACvB,EACDA,WAAK,CACN,CACF;AACH;AAEO,MAAM,wBAAwB,GAAG,CAAkC,EACxE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,QAAQ,EACR,aAAa,GAOd,KAAI;IACH,MAAM,MAAM,GAAG;AACb,UAAE,aAAa,CAAC,IAAI,CAAC,YAA8B;AACnD,UAAI,IAAI,CAAC,YAA+B,CAAC,MAAkB;AAC7D,IAAA,IAAI,CAAC,MAAM;QAAE;IAEb,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI;IACxD,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,EAAE,GAAG,MAAM,IAAI,EAAE;AAEnD,IAAA,mBAAmB,CAAC;QAClB,OAAO;QACP,IAAI,EAAEC,yBAAiB,CAAC,YAAY;QACpC,aAAa;AACb,QAAA,KAAK,EAAEC,aAAK,CAAC,QAAQ,CAAC;AACtB,QAAA,SAAS,EAAE,cAAc;AACzB,QAAA,MAAM,EAAE,iBAAiB;QACzB,MAAM;QACN,QAAQ;AACT,KAAA,CAAC;AACJ;;;;;"}
+{"version":3,"file":"logging.js","sources":["../src/logging.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { isLocalDev } from '@makerx/node-common'\nimport type { ExecutionArgs, GraphQLFormattedError } from 'graphql'\nimport { OperationTypeNode, print } from 'graphql'\nimport type { ExecutionResult } from 'graphql-ws'\nimport { omitBy } from 'es-toolkit/compat'\nimport type { GraphQLContext } from './context'\nimport { isIntrospectionQuery, isNil } from './utils'\n\ntype LogFunction = Logger['info']\nexport type LoggerLogFunctions<T extends Logger> = {\n  [Property in keyof T]: LogFunction\n}\n\n/**\n * Info for logging a GraphQL operation in a consistent format with the option of including any additional data.\n */\nexport interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extends Record<string, unknown> {\n  /**\n   * The message to log, defaults to 'GraphQL operation'.\n   */\n  message?: string\n  /**\n   * The timestamp when the operation started, if supplied, the duration will be logged.\n   */\n  started?: number\n  /**\n   * The type of GraphQL operation.\n   */\n  type?: OperationTypeNode | null\n  /**\n   * The name of the GraphQL operation.\n   */\n  operationName?: string | null\n  /**\n   * The formatted GraphQL query.\n   */\n  query?: string | null\n  /**\n   * The GraphQL variables.\n   */\n  variables?: Record<string, unknown> | null\n  /**\n   * The result of the GraphQL operation.\n   * Generally, we don't log the data or extensions, just errors.\n   */\n  result?: {\n    data?: Record<string, unknown> | null\n    errors?: readonly GraphQLFormattedError[] | null\n    extensions?: Record<string, unknown> | null\n    hasNext?: boolean\n  }\n  /**\n   * Whether the operation is an introspection query.\n   */\n  isIntrospectionQuery?: boolean\n  /**\n   * Whether the operation is part of an incremental response.\n   */\n  isIncrementalResponse?: boolean\n  /**\n   * Whether the operation is a subsequent payload of an incremental response.\n   */\n  isSubsequentPayload?: boolean\n  /**\n   * The logger to use.\n   */\n  logger: TLogger\n  /**\n   * The logger function to use, defaults to 'info'.\n   */\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n}\n\n/**\n * Logs a GraphQL operation in a consistent format with the option of including any additional data.\n * Top level and result entries with null or undefined values will be omitted.\n */\nexport const logGraphQLOperation = <TLogger extends Logger = Logger>({\n  message = 'GraphQL operation',\n  started,\n  type,\n  operationName,\n  query,\n  variables,\n  result,\n  logger,\n  logLevel = 'info',\n  ...rest\n}: GraphQLLogOperationInfo<TLogger>) => {\n  const isIntrospection = query && isIntrospectionQuery(query)\n  if (isLocalDev && isIntrospection) return\n  logger[logLevel as keyof Logger](\n    message,\n    omitBy(\n      {\n        type,\n        operationName,\n        query,\n        variables: variables && Object.keys(variables).length > 0 ? variables : undefined,\n        duration: started ? Date.now() - started : undefined,\n        result: result ? omitBy(result, isNil) : undefined,\n        isIntrospectionQuery: isIntrospection || undefined,\n        ...omitBy(rest, isNil),\n      },\n      isNil,\n    ),\n  )\n}\n\nexport const logSubscriptionOperation = <TLogger extends Logger = Logger>({\n  id,\n  args,\n  result,\n  message,\n  logLevel,\n  resolveLogger,\n}: {\n  id?: string\n  args: ExecutionArgs\n  result?: ExecutionResult\n  message?: string\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n  resolveLogger?: (context: GraphQLContext) => TLogger\n}) => {\n  const logger = resolveLogger\n    ? resolveLogger(args.contextValue as GraphQLContext)\n    : ((args.contextValue as GraphQLContext).logger as TLogger)\n  if (!logger) return\n\n  const { operationName, variableValues, document } = args\n  const { data, ...resultWithoutData } = result ?? {}\n\n  logGraphQLOperation({\n    message,\n    type: OperationTypeNode.SUBSCRIPTION,\n    subscriptionId: id,\n    operationName,\n    query: print(document),\n    variables: variableValues,\n    result: resultWithoutData,\n    logger,\n    logLevel,\n  })\n}\n"],"names":["isIntrospectionQuery","isLocalDev","omitBy","isNil","OperationTypeNode","print"],"mappings":";;;;;;;AA0EA;;;AAGG;AACI,MAAM,mBAAmB,GAAG,CAAkC,EACnE,OAAO,GAAG,mBAAmB,EAC7B,OAAO,EACP,IAAI,EACJ,aAAa,EACb,KAAK,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,QAAQ,GAAG,MAAM,EACjB,GAAG,IAAI,EAC0B,KAAI;IACrC,MAAM,eAAe,GAAG,KAAK,IAAIA,0BAAoB,CAAC,KAAK,CAAC;IAC5D,IAAIC,qBAAU,IAAI,eAAe;QAAE;AACnC,IAAA,MAAM,CAAC,QAAwB,CAAC,CAC9B,OAAO,EACPC,aAAM,CACJ;QACE,IAAI;QACJ,aAAa;QACb,KAAK;QACL,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,SAAS;AACjF,QAAA,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,SAAS;AACpD,QAAA,MAAM,EAAE,MAAM,GAAGA,aAAM,CAAC,MAAM,EAAEC,WAAK,CAAC,GAAG,SAAS;QAClD,oBAAoB,EAAE,eAAe,IAAI,SAAS;AAClD,QAAA,GAAGD,aAAM,CAAC,IAAI,EAAEC,WAAK,CAAC;KACvB,EACDA,WAAK,CACN,CACF;AACH;AAEO,MAAM,wBAAwB,GAAG,CAAkC,EACxE,EAAE,EACF,IAAI,EACJ,MAAM,EACN,OAAO,EACP,QAAQ,EACR,aAAa,GAQd,KAAI;IACH,MAAM,MAAM,GAAG;AACb,UAAE,aAAa,CAAC,IAAI,CAAC,YAA8B;AACnD,UAAI,IAAI,CAAC,YAA+B,CAAC,MAAkB;AAC7D,IAAA,IAAI,CAAC,MAAM;QAAE;IAEb,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI;IACxD,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,EAAE,GAAG,MAAM,IAAI,EAAE;AAEnD,IAAA,mBAAmB,CAAC;QAClB,OAAO;QACP,IAAI,EAAEC,yBAAiB,CAAC,YAAY;AACpC,QAAA,cAAc,EAAE,EAAE;QAClB,aAAa;AACb,QAAA,KAAK,EAAEC,aAAK,CAAC,QAAQ,CAAC;AACtB,QAAA,SAAS,EAAE,cAAc;AACzB,QAAA,MAAM,EAAE,iBAAiB;QACzB,MAAM;QACN,QAAQ;AACT,KAAA,CAAC;AACJ;;;;;"}

package/logging.mjs

@@ -22,7 +22,7 @@ const logGraphQLOperation = ({ message = 'GraphQL operation', started, type, ope
         ...omitBy(rest, isNil),
     }, isNil));
 };
-const logSubscriptionOperation = ({ args, result, message, logLevel, resolveLogger, }) => {
+const logSubscriptionOperation = ({ id, args, result, message, logLevel, resolveLogger, }) => {
     const logger = resolveLogger
         ? resolveLogger(args.contextValue)
         : args.contextValue.logger;
@@ -33,6 +33,7 @@ const logSubscriptionOperation = ({ args, result, message, logLevel, resolveLogg
     logGraphQLOperation({
         message,
         type: OperationTypeNode.SUBSCRIPTION,
+        subscriptionId: id,
         operationName,
         query: print(document),
         variables: variableValues,

package/logging.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"logging.mjs","sources":["../src/logging.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { isLocalDev } from '@makerx/node-common'\nimport type { ExecutionArgs, GraphQLFormattedError } from 'graphql'\nimport { OperationTypeNode, print } from 'graphql'\nimport type { ExecutionResult } from 'graphql-ws'\nimport { omitBy } from 'es-toolkit/compat'\nimport type { GraphQLContext } from './context'\nimport { isIntrospectionQuery, isNil } from './utils'\n\ntype LogFunction = Logger['info']\nexport type LoggerLogFunctions<T extends Logger> = {\n  [Property in keyof T]: LogFunction\n}\n\n/**\n * Info for logging a GraphQL operation in a consistent format with the option of including any additional data.\n */\nexport interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extends Record<string, unknown> {\n  /**\n   * The message to log, defaults to 'GraphQL operation'.\n   */\n  message?: string\n  /**\n   * The timestamp when the operation started, if supplied, the duration will be logged.\n   */\n  started?: number\n  /**\n   * The type of GraphQL operation.\n   */\n  type?: OperationTypeNode | null\n  /**\n   * The name of the GraphQL operation.\n   */\n  operationName?: string | null\n  /**\n   * The formatted GraphQL query.\n   */\n  query?: string | null\n  /**\n   * The GraphQL variables.\n   */\n  variables?: Record<string, unknown> | null\n  /**\n   * The result of the GraphQL operation.\n   * Generally, we don't log the data or extensions, just errors.\n   */\n  result?: {\n    data?: Record<string, unknown> | null\n    errors?: readonly GraphQLFormattedError[] | null\n    extensions?: Record<string, unknown> | null\n    hasNext?: boolean\n  }\n  /**\n   * Whether the operation is an introspection query.\n   */\n  isIntrospectionQuery?: boolean\n  /**\n   * Whether the operation is part of an incremental response.\n   */\n  isIncrementalResponse?: boolean\n  /**\n   * Whether the operation is a subsequent payload of an incremental response.\n   */\n  isSubsequentPayload?: boolean\n  /**\n   * The logger to use.\n   */\n  logger: TLogger\n  /**\n   * The logger function to use, defaults to 'info'.\n   */\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n}\n\n/**\n * Logs a GraphQL operation in a consistent format with the option of including any additional data.\n * Top level and result entries with null or undefined values will be omitted.\n */\nexport const logGraphQLOperation = <TLogger extends Logger = Logger>({\n  message = 'GraphQL operation',\n  started,\n  type,\n  operationName,\n  query,\n  variables,\n  result,\n  logger,\n  logLevel = 'info',\n  ...rest\n}: GraphQLLogOperationInfo<TLogger>) => {\n  const isIntrospection = query && isIntrospectionQuery(query)\n  if (isLocalDev && isIntrospection) return\n  logger[logLevel as keyof Logger](\n    message,\n    omitBy(\n      {\n        type,\n        operationName,\n        query,\n        variables: variables && Object.keys(variables).length > 0 ? variables : undefined,\n        duration: started ? Date.now() - started : undefined,\n        result: result ? omitBy(result, isNil) : undefined,\n        isIntrospectionQuery: isIntrospection || undefined,\n        ...omitBy(rest, isNil),\n      },\n      isNil,\n    ),\n  )\n}\n\nexport const logSubscriptionOperation = <TLogger extends Logger = Logger>({\n  args,\n  result,\n  message,\n  logLevel,\n  resolveLogger,\n}: {\n  args: ExecutionArgs\n  result?: ExecutionResult\n  message?: string\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n  resolveLogger?: (context: GraphQLContext) => TLogger\n}) => {\n  const logger = resolveLogger\n    ? resolveLogger(args.contextValue as GraphQLContext)\n    : ((args.contextValue as GraphQLContext).logger as TLogger)\n  if (!logger) return\n\n  const { operationName, variableValues, document } = args\n  const { data, ...resultWithoutData } = result ?? {}\n\n  logGraphQLOperation({\n    message,\n    type: OperationTypeNode.SUBSCRIPTION,\n    operationName,\n    query: print(document),\n    variables: variableValues,\n    result: resultWithoutData,\n    logger,\n    logLevel,\n  })\n}\n"],"names":[],"mappings":";;;;;AA0EA;;;AAGG;AACI,MAAM,mBAAmB,GAAG,CAAkC,EACnE,OAAO,GAAG,mBAAmB,EAC7B,OAAO,EACP,IAAI,EACJ,aAAa,EACb,KAAK,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,QAAQ,GAAG,MAAM,EACjB,GAAG,IAAI,EAC0B,KAAI;IACrC,MAAM,eAAe,GAAG,KAAK,IAAI,oBAAoB,CAAC,KAAK,CAAC;IAC5D,IAAI,UAAU,IAAI,eAAe;QAAE;AACnC,IAAA,MAAM,CAAC,QAAwB,CAAC,CAC9B,OAAO,EACP,MAAM,CACJ;QACE,IAAI;QACJ,aAAa;QACb,KAAK;QACL,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,SAAS;AACjF,QAAA,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,SAAS;AACpD,QAAA,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,SAAS;QAClD,oBAAoB,EAAE,eAAe,IAAI,SAAS;AAClD,QAAA,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC;KACvB,EACD,KAAK,CACN,CACF;AACH;AAEO,MAAM,wBAAwB,GAAG,CAAkC,EACxE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,QAAQ,EACR,aAAa,GAOd,KAAI;IACH,MAAM,MAAM,GAAG;AACb,UAAE,aAAa,CAAC,IAAI,CAAC,YAA8B;AACnD,UAAI,IAAI,CAAC,YAA+B,CAAC,MAAkB;AAC7D,IAAA,IAAI,CAAC,MAAM;QAAE;IAEb,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI;IACxD,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,EAAE,GAAG,MAAM,IAAI,EAAE;AAEnD,IAAA,mBAAmB,CAAC;QAClB,OAAO;QACP,IAAI,EAAE,iBAAiB,CAAC,YAAY;QACpC,aAAa;AACb,QAAA,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;AACtB,QAAA,SAAS,EAAE,cAAc;AACzB,QAAA,MAAM,EAAE,iBAAiB;QACzB,MAAM;QACN,QAAQ;AACT,KAAA,CAAC;AACJ;;;;"}
+{"version":3,"file":"logging.mjs","sources":["../src/logging.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { isLocalDev } from '@makerx/node-common'\nimport type { ExecutionArgs, GraphQLFormattedError } from 'graphql'\nimport { OperationTypeNode, print } from 'graphql'\nimport type { ExecutionResult } from 'graphql-ws'\nimport { omitBy } from 'es-toolkit/compat'\nimport type { GraphQLContext } from './context'\nimport { isIntrospectionQuery, isNil } from './utils'\n\ntype LogFunction = Logger['info']\nexport type LoggerLogFunctions<T extends Logger> = {\n  [Property in keyof T]: LogFunction\n}\n\n/**\n * Info for logging a GraphQL operation in a consistent format with the option of including any additional data.\n */\nexport interface GraphQLLogOperationInfo<TLogger extends Logger = Logger> extends Record<string, unknown> {\n  /**\n   * The message to log, defaults to 'GraphQL operation'.\n   */\n  message?: string\n  /**\n   * The timestamp when the operation started, if supplied, the duration will be logged.\n   */\n  started?: number\n  /**\n   * The type of GraphQL operation.\n   */\n  type?: OperationTypeNode | null\n  /**\n   * The name of the GraphQL operation.\n   */\n  operationName?: string | null\n  /**\n   * The formatted GraphQL query.\n   */\n  query?: string | null\n  /**\n   * The GraphQL variables.\n   */\n  variables?: Record<string, unknown> | null\n  /**\n   * The result of the GraphQL operation.\n   * Generally, we don't log the data or extensions, just errors.\n   */\n  result?: {\n    data?: Record<string, unknown> | null\n    errors?: readonly GraphQLFormattedError[] | null\n    extensions?: Record<string, unknown> | null\n    hasNext?: boolean\n  }\n  /**\n   * Whether the operation is an introspection query.\n   */\n  isIntrospectionQuery?: boolean\n  /**\n   * Whether the operation is part of an incremental response.\n   */\n  isIncrementalResponse?: boolean\n  /**\n   * Whether the operation is a subsequent payload of an incremental response.\n   */\n  isSubsequentPayload?: boolean\n  /**\n   * The logger to use.\n   */\n  logger: TLogger\n  /**\n   * The logger function to use, defaults to 'info'.\n   */\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n}\n\n/**\n * Logs a GraphQL operation in a consistent format with the option of including any additional data.\n * Top level and result entries with null or undefined values will be omitted.\n */\nexport const logGraphQLOperation = <TLogger extends Logger = Logger>({\n  message = 'GraphQL operation',\n  started,\n  type,\n  operationName,\n  query,\n  variables,\n  result,\n  logger,\n  logLevel = 'info',\n  ...rest\n}: GraphQLLogOperationInfo<TLogger>) => {\n  const isIntrospection = query && isIntrospectionQuery(query)\n  if (isLocalDev && isIntrospection) return\n  logger[logLevel as keyof Logger](\n    message,\n    omitBy(\n      {\n        type,\n        operationName,\n        query,\n        variables: variables && Object.keys(variables).length > 0 ? variables : undefined,\n        duration: started ? Date.now() - started : undefined,\n        result: result ? omitBy(result, isNil) : undefined,\n        isIntrospectionQuery: isIntrospection || undefined,\n        ...omitBy(rest, isNil),\n      },\n      isNil,\n    ),\n  )\n}\n\nexport const logSubscriptionOperation = <TLogger extends Logger = Logger>({\n  id,\n  args,\n  result,\n  message,\n  logLevel,\n  resolveLogger,\n}: {\n  id?: string\n  args: ExecutionArgs\n  result?: ExecutionResult\n  message?: string\n  logLevel?: keyof LoggerLogFunctions<TLogger>\n  resolveLogger?: (context: GraphQLContext) => TLogger\n}) => {\n  const logger = resolveLogger\n    ? resolveLogger(args.contextValue as GraphQLContext)\n    : ((args.contextValue as GraphQLContext).logger as TLogger)\n  if (!logger) return\n\n  const { operationName, variableValues, document } = args\n  const { data, ...resultWithoutData } = result ?? {}\n\n  logGraphQLOperation({\n    message,\n    type: OperationTypeNode.SUBSCRIPTION,\n    subscriptionId: id,\n    operationName,\n    query: print(document),\n    variables: variableValues,\n    result: resultWithoutData,\n    logger,\n    logLevel,\n  })\n}\n"],"names":[],"mappings":";;;;;AA0EA;;;AAGG;AACI,MAAM,mBAAmB,GAAG,CAAkC,EACnE,OAAO,GAAG,mBAAmB,EAC7B,OAAO,EACP,IAAI,EACJ,aAAa,EACb,KAAK,EACL,SAAS,EACT,MAAM,EACN,MAAM,EACN,QAAQ,GAAG,MAAM,EACjB,GAAG,IAAI,EAC0B,KAAI;IACrC,MAAM,eAAe,GAAG,KAAK,IAAI,oBAAoB,CAAC,KAAK,CAAC;IAC5D,IAAI,UAAU,IAAI,eAAe;QAAE;AACnC,IAAA,MAAM,CAAC,QAAwB,CAAC,CAC9B,OAAO,EACP,MAAM,CACJ;QACE,IAAI;QACJ,aAAa;QACb,KAAK;QACL,SAAS,EAAE,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,SAAS;AACjF,QAAA,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,GAAG,SAAS;AACpD,QAAA,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,SAAS;QAClD,oBAAoB,EAAE,eAAe,IAAI,SAAS;AAClD,QAAA,GAAG,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC;KACvB,EACD,KAAK,CACN,CACF;AACH;AAEO,MAAM,wBAAwB,GAAG,CAAkC,EACxE,EAAE,EACF,IAAI,EACJ,MAAM,EACN,OAAO,EACP,QAAQ,EACR,aAAa,GAQd,KAAI;IACH,MAAM,MAAM,GAAG;AACb,UAAE,aAAa,CAAC,IAAI,CAAC,YAA8B;AACnD,UAAI,IAAI,CAAC,YAA+B,CAAC,MAAkB;AAC7D,IAAA,IAAI,CAAC,MAAM;QAAE;IAEb,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI;IACxD,MAAM,EAAE,IAAI,EAAE,GAAG,iBAAiB,EAAE,GAAG,MAAM,IAAI,EAAE;AAEnD,IAAA,mBAAmB,CAAC;QAClB,OAAO;QACP,IAAI,EAAE,iBAAiB,CAAC,YAAY;AACpC,QAAA,cAAc,EAAE,EAAE;QAClB,aAAa;AACb,QAAA,KAAK,EAAE,KAAK,CAAC,QAAQ,CAAC;AACtB,QAAA,SAAS,EAAE,cAAc;AACzB,QAAA,MAAM,EAAE,iBAAiB;QACzB,MAAM;QACN,QAAQ;AACT,KAAA,CAAC;AACJ;;;;"}

package/package.json

@@ -4,7 +4,7 @@
     "**"
   ],
   "name": "@makerx/graphql-core",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.6",
   "private": false,
   "description": "A set of core GraphQL utilities that MakerX uses to build GraphQL APIs",
   "author": "MakerX",
@@ -26,7 +26,7 @@
     "express": ">=4",
     "graphql": ">=16",
     "graphql-shield": ">=7",
-    "graphql-ws": ">=5",
+    "graphql-ws": ">=6",
     "ws": ">=8"
   },
   "peerDependenciesMeta": {
@@ -46,19 +46,34 @@
   "type": "commonjs",
   "exports": {
     ".": {
-      "types": "./index.d.ts",
-      "import": "./index.mjs",
-      "require": "./index.js"
+      "import": {
+        "types": "./index.d.mts",
+        "default": "./index.mjs"
+      },
+      "require": {
+        "types": "./index.d.cts",
+        "default": "./index.js"
+      }
     },
     "./shield": {
-      "types": "./shield.d.ts",
-      "import": "./shield.mjs",
-      "require": "./shield.js"
+      "import": {
+        "types": "./shield.d.mts",
+        "default": "./shield.mjs"
+      },
+      "require": {
+        "types": "./shield.d.cts",
+        "default": "./shield.js"
+      }
     },
     "./subscriptions": {
-      "types": "./subscriptions/index.d.ts",
-      "import": "./subscriptions/index.mjs",
-      "require": "./subscriptions/index.js"
+      "import": {
+        "types": "./subscriptions/index.d.mts",
+        "default": "./subscriptions/index.mjs"
+      },
+      "require": {
+        "types": "./subscriptions/index.d.cts",
+        "default": "./subscriptions/index.js"
+      }
     }
   }
 }

package/request-info.d.cts

@@ -0,0 +1,38 @@
+import type { Request } from 'express';
+import type { IncomingMessage } from 'http';
+export interface BaseRequestInfo extends Record<string, unknown> {
+    requestId: string;
+    source: 'http' | 'subscription';
+    protocol: 'http' | 'https' | 'ws' | 'wss';
+    host: string;
+    port?: number;
+    method: string;
+    baseUrl: string;
+    url: string;
+    origin: string;
+    referer?: string;
+    correlationId?: string;
+    arrLogId?: string;
+    clientIp?: string;
+    userAgent?: string;
+}
+/**
+ * Builds the base URL (`protocol://host[:port]`) for an Express HTTP request, using the request's
+ * protocol and resolving the host/port from forwarding headers with the Express hostname as fallback.
+ * The port is omitted when it matches the default for the protocol (80 for http, 443 for https).
+ * @param req The Express request.
+ * @returns The base URL string.
+ */
+export declare const requestBaseUrl: (req: Request) => string;
+/**
+ * Builds the base URL (`http(s)://host[:port]`) for a raw WebSocket upgrade (connect) request.
+ * Returns an `https` URL when the connection is TLS-encrypted or `x-forwarded-proto` indicates a
+ * secure scheme, otherwise `http`. Throws if no host can be determined from the request headers,
+ * since upgrade requests have no Express `hostname` fallback.
+ * @param req The incoming upgrade request.
+ * @returns The base URL string.
+ * @throws Error when the host cannot be resolved from the request.
+ */
+export declare const connectRequestBaseUrl: (req: IncomingMessage) => string;
+export declare const buildBaseRequestInfo: (req: Request) => BaseRequestInfo;
+export declare const buildConnectRequestInfo: (req: IncomingMessage) => BaseRequestInfo;

package/request-info.d.mts

@@ -0,0 +1,38 @@
+import type { Request } from 'express';
+import type { IncomingMessage } from 'http';
+export interface BaseRequestInfo extends Record<string, unknown> {
+    requestId: string;
+    source: 'http' | 'subscription';
+    protocol: 'http' | 'https' | 'ws' | 'wss';
+    host: string;
+    port?: number;
+    method: string;
+    baseUrl: string;
+    url: string;
+    origin: string;
+    referer?: string;
+    correlationId?: string;
+    arrLogId?: string;
+    clientIp?: string;
+    userAgent?: string;
+}
+/**
+ * Builds the base URL (`protocol://host[:port]`) for an Express HTTP request, using the request's
+ * protocol and resolving the host/port from forwarding headers with the Express hostname as fallback.
+ * The port is omitted when it matches the default for the protocol (80 for http, 443 for https).
+ * @param req The Express request.
+ * @returns The base URL string.
+ */
+export declare const requestBaseUrl: (req: Request) => string;
+/**
+ * Builds the base URL (`http(s)://host[:port]`) for a raw WebSocket upgrade (connect) request.
+ * Returns an `https` URL when the connection is TLS-encrypted or `x-forwarded-proto` indicates a
+ * secure scheme, otherwise `http`. Throws if no host can be determined from the request headers,
+ * since upgrade requests have no Express `hostname` fallback.
+ * @param req The incoming upgrade request.
+ * @returns The base URL string.
+ * @throws Error when the host cannot be resolved from the request.
+ */
+export declare const connectRequestBaseUrl: (req: IncomingMessage) => string;
+export declare const buildBaseRequestInfo: (req: Request) => BaseRequestInfo;
+export declare const buildConnectRequestInfo: (req: IncomingMessage) => BaseRequestInfo;

package/schema-util.d.cts

@@ -0,0 +1,9 @@
+import type { GraphQLSchema } from 'graphql';
+/**
+ * It is possible to register a custom scalar with apollo server without defining an explicit resolver (a default resolver is used in
+ * this case), but it is rarely desirable. This function, when provided with your built schema, will ensure any registered scalar types
+ * provide at least a base level of validation by failing to parse a Symbol instance. The default resolver does not pass this test
+ * meaning any scalars that are falling back to the default resolver will fail.
+ * @param schema A schema object, the result of calling `makeExecutableSchema` from `@graphql-tools/schema`
+ */
+export declare function requireExplicitResolversForScalars(schema: GraphQLSchema, ...scalarsToIgnore: string[]): void;

package/schema-util.d.mts

@@ -0,0 +1,9 @@
+import type { GraphQLSchema } from 'graphql';
+/**
+ * It is possible to register a custom scalar with apollo server without defining an explicit resolver (a default resolver is used in
+ * this case), but it is rarely desirable. This function, when provided with your built schema, will ensure any registered scalar types
+ * provide at least a base level of validation by failing to parse a Symbol instance. The default resolver does not pass this test
+ * meaning any scalars that are falling back to the default resolver will fail.
+ * @param schema A schema object, the result of calling `makeExecutableSchema` from `@graphql-tools/schema`
+ */
+export declare function requireExplicitResolversForScalars(schema: GraphQLSchema, ...scalarsToIgnore: string[]): void;

package/shield.d.cts

@@ -0,0 +1,122 @@
+import type { allow, and, chain, or, race } from 'graphql-shield';
+import { shield } from 'graphql-shield';
+import type { Primitive } from './type-utils';
+export type ShieldOptions = NonNullable<Parameters<typeof shield>[1]>;
+type RuleCombinator = typeof chain | typeof race | typeof or | typeof and;
+export type ShieldRule = ReturnType<(typeof allow)['getRules']>[number];
+/**
+ * Thin typed wrapper around graphql-shield's `rule(...)` for building ad-hoc shield rules.
+ *
+ * Lets you pass a plain predicate (sync or async, or returning an `Error`) and get back a
+ * {@link ShieldRule} with the `parent`, `args`, and `ctx` arguments typed to your generics —
+ * graphql-shield's native `rule` types these as `any`.
+ *
+ * Defaults the rule's cache to `'strict'`; use `'contextual'` when the result depends only on
+ * `ctx` (e.g. the current user), so it can be reused across fields in the same request.
+ *
+ * @param logic Predicate returning `true` to allow, `false` to deny, or an `Error` to deny with a specific error.
+ * @param cache graphql-shield cache strategy. `'strict'` (default) keys on parent+args+ctx; `'contextual'` keys on ctx only.
+ *
+ * Usage:
+ *
+ * const isOwner = createRule<GraphQLContext, { ownerId: string }>(
+ *   (parent, _, ctx) => parent.ownerId === ctx.user?.id,
+ * )
+ */
+export declare const createRule: <TContext, TParent = unknown, TArgs = unknown>(logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error, cache?: "contextual" | "strict") => ShieldRule;
+/**
+ * Combines a given rule with all existing defined rules using the provided combinator
+ * @param schema The existing shield schema with rules
+ * @param rule The rule to be combined with existing rules
+ * @param combinator The combinator to use. Eg. and | or | chain | race
+ *
+ * Usage:
+ *
+ * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)
+ */
+export declare function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T>;
+/**
+ * Creates graphql shield middleware making use of generics to type the definition of the rules.
+ * @param schema A mapping of schema objects to the shield rules that define the access to that object
+ * @param options Shield options forwarded to `shield`. Defaults `allowExternalErrors` to `true`.
+ *
+ * Usage:
+ * import { Resolvers } from '../generated/types'
+ *
+ * const isCoordinator = hasRoleRule(UserRoles.Coordinator)
+ * const isSystemAdmin = hasRoleRule(UserRoles.SystemAdmin)
+ * const isQualityAssurance = hasRoleRule(UserRoles.QualityAssurance)
+ *
+ * const isAuthorisedUser = or(isCoordinator, isSystemAdmin, isQualityAssurance)
+ * const isDataAuthor = or(isCoordinator, isSystemAdmin)
+ *
+ * const shieldSchema = createShieldSchema<Resolvers>({
+ *   Query: {
+ *     '*': isAuthorisedUser,
+ *     user: isCoordinator,
+ *     findUsers: isCoordinator,
+ *   },
+ *   Mutation: {
+ *     '*': isDataAuthor,
+ *     createUser: isCoordinator,
+ *   },
+ *   // specific rules for mutations, types, fields...
+ * }, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError()})
+ *
+ * const unprotected = makeExecutableSchema({...})
+ * return applyMiddleware(unprotected, shieldSchema)
+ */
+export declare function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, options?: ShieldOptions): import("graphql-middleware").IMiddlewareGenerator<any, any, any>;
+/**
+ * A shield rule tree typed against a resolver map (typically your generated `Resolvers` type).
+ *
+ * Mirrors the shape of `TResolver` so each type/field can be assigned a {@link ShieldRule}.
+ * Object levels may also include a `'*'` key — a fallback rule applied to any field at that
+ * level that doesn't have an explicit rule. Leaf (primitive) positions collapse to a single
+ * {@link ShieldRule}.
+ *
+ * Usage:
+ *
+ * const schema: ShieldSchema<Resolvers> = {
+ *   Query: {
+ *     '*': isAuthorisedUser,
+ *     publicThing: allow,
+ *   },
+ *   Mutation: { createUser: isCoordinator },
+ * }
+ */
+export type ShieldSchema<TResolver> = TResolver extends Primitive ? ShieldRule : {
+    [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule;
+} & {
+    '*'?: ShieldRule;
+};
+/**
+ * Shield rule that passes when the current user has the given role.
+ * @param role The role the user must have on `ctx.user.roles`.
+ * @param ruleName Optional override for the rule's cache key. Defaults to `hasRole-${role}`.
+ */
+export declare function hasRoleRule(role: string, ruleName?: string): ShieldRule;
+/**
+ * Shield rule that passes when the current user has at least one of the given roles.
+ * Rule name is derived from the roles; use {@link hasAnyRoleRuleWithName} to supply your own.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+export declare function hasAnyRoleRule(...roles: string[]): ShieldRule;
+/**
+ * Shield rule that passes when the current user has at least one of the given roles, with an explicit rule name.
+ * Prefer this over {@link hasAnyRoleRule} when the role list is large or dynamic and you want a stable cache key.
+ * @param ruleName The name (and cache key) for the rule.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+export declare function hasAnyRoleRuleWithName(ruleName: string, ...roles: string[]): ShieldRule;
+/**
+ * Shield rule that passes when the current user has the given scope.
+ * @param scope The scope the user must have on `ctx.user.scopes`.
+ */
+export declare function hasScopeRule(scope: string): ShieldRule;
+/**
+ * Shield rule that passes when the current user has at least one of the given scopes.
+ * @param scopes The set of scopes, any of which satisfies the rule.
+ */
+export declare function hasAnyScopeRule(...scopes: string[]): ShieldRule;
+export {};

package/shield.d.mts

@@ -0,0 +1,122 @@
+import type { allow, and, chain, or, race } from 'graphql-shield';
+import { shield } from 'graphql-shield';
+import type { Primitive } from './type-utils.js';
+export type ShieldOptions = NonNullable<Parameters<typeof shield>[1]>;
+type RuleCombinator = typeof chain | typeof race | typeof or | typeof and;
+export type ShieldRule = ReturnType<(typeof allow)['getRules']>[number];
+/**
+ * Thin typed wrapper around graphql-shield's `rule(...)` for building ad-hoc shield rules.
+ *
+ * Lets you pass a plain predicate (sync or async, or returning an `Error`) and get back a
+ * {@link ShieldRule} with the `parent`, `args`, and `ctx` arguments typed to your generics —
+ * graphql-shield's native `rule` types these as `any`.
+ *
+ * Defaults the rule's cache to `'strict'`; use `'contextual'` when the result depends only on
+ * `ctx` (e.g. the current user), so it can be reused across fields in the same request.
+ *
+ * @param logic Predicate returning `true` to allow, `false` to deny, or an `Error` to deny with a specific error.
+ * @param cache graphql-shield cache strategy. `'strict'` (default) keys on parent+args+ctx; `'contextual'` keys on ctx only.
+ *
+ * Usage:
+ *
+ * const isOwner = createRule<GraphQLContext, { ownerId: string }>(
+ *   (parent, _, ctx) => parent.ownerId === ctx.user?.id,
+ * )
+ */
+export declare const createRule: <TContext, TParent = unknown, TArgs = unknown>(logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error, cache?: "contextual" | "strict") => ShieldRule;
+/**
+ * Combines a given rule with all existing defined rules using the provided combinator
+ * @param schema The existing shield schema with rules
+ * @param rule The rule to be combined with existing rules
+ * @param combinator The combinator to use. Eg. and | or | chain | race
+ *
+ * Usage:
+ *
+ * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)
+ */
+export declare function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T>;
+/**
+ * Creates graphql shield middleware making use of generics to type the definition of the rules.
+ * @param schema A mapping of schema objects to the shield rules that define the access to that object
+ * @param options Shield options forwarded to `shield`. Defaults `allowExternalErrors` to `true`.
+ *
+ * Usage:
+ * import { Resolvers } from '../generated/types'
+ *
+ * const isCoordinator = hasRoleRule(UserRoles.Coordinator)
+ * const isSystemAdmin = hasRoleRule(UserRoles.SystemAdmin)
+ * const isQualityAssurance = hasRoleRule(UserRoles.QualityAssurance)
+ *
+ * const isAuthorisedUser = or(isCoordinator, isSystemAdmin, isQualityAssurance)
+ * const isDataAuthor = or(isCoordinator, isSystemAdmin)
+ *
+ * const shieldSchema = createShieldSchema<Resolvers>({
+ *   Query: {
+ *     '*': isAuthorisedUser,
+ *     user: isCoordinator,
+ *     findUsers: isCoordinator,
+ *   },
+ *   Mutation: {
+ *     '*': isDataAuthor,
+ *     createUser: isCoordinator,
+ *   },
+ *   // specific rules for mutations, types, fields...
+ * }, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError()})
+ *
+ * const unprotected = makeExecutableSchema({...})
+ * return applyMiddleware(unprotected, shieldSchema)
+ */
+export declare function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, options?: ShieldOptions): import("graphql-middleware").IMiddlewareGenerator<any, any, any>;
+/**
+ * A shield rule tree typed against a resolver map (typically your generated `Resolvers` type).
+ *
+ * Mirrors the shape of `TResolver` so each type/field can be assigned a {@link ShieldRule}.
+ * Object levels may also include a `'*'` key — a fallback rule applied to any field at that
+ * level that doesn't have an explicit rule. Leaf (primitive) positions collapse to a single
+ * {@link ShieldRule}.
+ *
+ * Usage:
+ *
+ * const schema: ShieldSchema<Resolvers> = {
+ *   Query: {
+ *     '*': isAuthorisedUser,
+ *     publicThing: allow,
+ *   },
+ *   Mutation: { createUser: isCoordinator },
+ * }
+ */
+export type ShieldSchema<TResolver> = TResolver extends Primitive ? ShieldRule : {
+    [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule;
+} & {
+    '*'?: ShieldRule;
+};
+/**
+ * Shield rule that passes when the current user has the given role.
+ * @param role The role the user must have on `ctx.user.roles`.
+ * @param ruleName Optional override for the rule's cache key. Defaults to `hasRole-${role}`.
+ */
+export declare function hasRoleRule(role: string, ruleName?: string): ShieldRule;
+/**
+ * Shield rule that passes when the current user has at least one of the given roles.
+ * Rule name is derived from the roles; use {@link hasAnyRoleRuleWithName} to supply your own.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+export declare function hasAnyRoleRule(...roles: string[]): ShieldRule;
+/**
+ * Shield rule that passes when the current user has at least one of the given roles, with an explicit rule name.
+ * Prefer this over {@link hasAnyRoleRule} when the role list is large or dynamic and you want a stable cache key.
+ * @param ruleName The name (and cache key) for the rule.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+export declare function hasAnyRoleRuleWithName(ruleName: string, ...roles: string[]): ShieldRule;
+/**
+ * Shield rule that passes when the current user has the given scope.
+ * @param scope The scope the user must have on `ctx.user.scopes`.
+ */
+export declare function hasScopeRule(scope: string): ShieldRule;
+/**
+ * Shield rule that passes when the current user has at least one of the given scopes.
+ * @param scopes The set of scopes, any of which satisfies the rule.
+ */
+export declare function hasAnyScopeRule(...scopes: string[]): ShieldRule;
+export {};

package/subscriptions/context.d.cts

@@ -0,0 +1,24 @@
+import type { Logger } from '@makerx/node-common';
+import type { IncomingMessage } from 'http';
+import { User } from '../User';
+import type { CreateRequestLogger, GraphQLContext, JwtPayload, RequestInfo, RequestInfoLogKey } from '../context';
+export interface SubscriptionContextInput {
+    connectRequest: IncomingMessage;
+    connectionParams?: Readonly<Record<string, unknown>>;
+    claims?: JwtPayload;
+}
+export type CreateSubscriptionUser<T = User | undefined> = (input: SubscriptionContextInput) => Promise<T> | T;
+export type CreateSubscriptionContext<TContext = GraphQLContext> = (input: SubscriptionContextInput) => Promise<TContext>;
+export type AugmentSubscriptionRequestInfo = (input: SubscriptionContextInput) => Record<string, unknown>;
+export type CreateSubscriptionContextConfig<TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger> = {
+    requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger;
+    augmentRequestInfo?: AugmentSubscriptionRequestInfo;
+    claimsToLog?: string[];
+    requestInfoToLog?: Array<RequestInfoLogKey>;
+    augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>;
+} & ([User | undefined] extends [TUser] ? {
+    createUser?: CreateSubscriptionUser<TUser>;
+} : {
+    createUser: CreateSubscriptionUser<TUser>;
+});
+export declare const createSubscriptionContextFactory: <TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger>(config: CreateSubscriptionContextConfig<TUser, TAugment, TLogger>) => CreateSubscriptionContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment>;

package/subscriptions/context.d.mts

@@ -0,0 +1,24 @@
+import type { Logger } from '@makerx/node-common';
+import type { IncomingMessage } from 'http';
+import { User } from '../User.js';
+import type { CreateRequestLogger, GraphQLContext, JwtPayload, RequestInfo, RequestInfoLogKey } from '../context.js';
+export interface SubscriptionContextInput {
+    connectRequest: IncomingMessage;
+    connectionParams?: Readonly<Record<string, unknown>>;
+    claims?: JwtPayload;
+}
+export type CreateSubscriptionUser<T = User | undefined> = (input: SubscriptionContextInput) => Promise<T> | T;
+export type CreateSubscriptionContext<TContext = GraphQLContext> = (input: SubscriptionContextInput) => Promise<TContext>;
+export type AugmentSubscriptionRequestInfo = (input: SubscriptionContextInput) => Record<string, unknown>;
+export type CreateSubscriptionContextConfig<TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger> = {
+    requestLogger: CreateRequestLogger<TUser, TLogger> | TLogger;
+    augmentRequestInfo?: AugmentSubscriptionRequestInfo;
+    claimsToLog?: string[];
+    requestInfoToLog?: Array<RequestInfoLogKey>;
+    augmentContext?: (context: GraphQLContext<TLogger, RequestInfo, TUser>) => TAugment | Promise<TAugment>;
+} & ([User | undefined] extends [TUser] ? {
+    createUser?: CreateSubscriptionUser<TUser>;
+} : {
+    createUser: CreateSubscriptionUser<TUser>;
+});
+export declare const createSubscriptionContextFactory: <TUser = User | undefined, TAugment extends Record<string, unknown> = Record<string, never>, TLogger extends Logger = Logger>(config: CreateSubscriptionContextConfig<TUser, TAugment, TLogger>) => CreateSubscriptionContext<GraphQLContext<TLogger, RequestInfo, TUser> & TAugment>;

package/subscriptions/index.d.cts

@@ -0,0 +1,3 @@
+export * from './context';
+export * from './server';
+export { extractTokenFromConnectionParams } from './utils';

package/subscriptions/index.d.mts

@@ -0,0 +1,3 @@
+export * from './context.js';
+export * from './server.js';
+export { extractTokenFromConnectionParams } from './utils.js';

package/subscriptions/server.d.cts

@@ -0,0 +1,17 @@
+import type { Logger } from '@makerx/node-common';
+import type { GraphQLSchema } from 'graphql';
+import type { Server } from 'http';
+import type { GraphQLContext, JwtPayload } from '../context';
+import type { CreateSubscriptionContext } from './context';
+export declare function useSubscriptionsServer<TLogger extends Logger = Logger>({ schema, httpServer, createSubscriptionContext, logger, operationLogLevel, path, verifyToken, requireAuth, jwtClaimsToLog, resolveSubscriptionOperationLogger, }: {
+    schema: GraphQLSchema;
+    httpServer: Server;
+    createSubscriptionContext: CreateSubscriptionContext;
+    logger: TLogger;
+    operationLogLevel?: keyof TLogger;
+    path?: string;
+    verifyToken?: (host: string, token: string) => Promise<JwtPayload>;
+    requireAuth?: boolean;
+    jwtClaimsToLog?: string[];
+    resolveSubscriptionOperationLogger?: (context: GraphQLContext) => TLogger;
+}): import("graphql-ws").Disposable;

package/subscriptions/server.d.mts

@@ -0,0 +1,17 @@
+import type { Logger } from '@makerx/node-common';
+import type { GraphQLSchema } from 'graphql';
+import type { Server } from 'http';
+import type { GraphQLContext, JwtPayload } from '../context.js';
+import type { CreateSubscriptionContext } from './context.js';
+export declare function useSubscriptionsServer<TLogger extends Logger = Logger>({ schema, httpServer, createSubscriptionContext, logger, operationLogLevel, path, verifyToken, requireAuth, jwtClaimsToLog, resolveSubscriptionOperationLogger, }: {
+    schema: GraphQLSchema;
+    httpServer: Server;
+    createSubscriptionContext: CreateSubscriptionContext;
+    logger: TLogger;
+    operationLogLevel?: keyof TLogger;
+    path?: string;
+    verifyToken?: (host: string, token: string) => Promise<JwtPayload>;
+    requireAuth?: boolean;
+    jwtClaimsToLog?: string[];
+    resolveSubscriptionOperationLogger?: (context: GraphQLContext) => TLogger;
+}): import("graphql-ws").Disposable;

package/subscriptions/server.js

@@ -1,8 +1,8 @@
 'use strict';
 
-var graphqlWs = require('graphql-ws');
-var ws$1 = require('graphql-ws/lib/use/ws');
 var compat = require('es-toolkit/compat');
+var graphqlWs = require('graphql-ws');
+var ws$1 = require('graphql-ws/use/ws');
 var ws = require('ws');
 var logging = require('../logging.js');
 var utils = require('./utils.js');
@@ -76,11 +76,11 @@ function useSubscriptionsServer({ schema, httpServer, createSubscriptionContext,
                 claims: ctx.extra.claims,
             });
         },
-        onOperation(_ctx, _message, args) {
-            logging.logSubscriptionOperation({ args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger });
+        onOperation(_ctx, id, _payload, args) {
+            logging.logSubscriptionOperation({ id, args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger });
         },
-        onNext(_ctx, _message, args, { data, ...result }) {
-            logging.logSubscriptionOperation({ args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger });
+        onNext(_ctx, id, _payload, args, { data, ...result }) {
+            logging.logSubscriptionOperation({ id, args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger });
         },
     }, wsServer);
 }

package/subscriptions/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sources":["../../src/subscriptions/server.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport type { GraphQLSchema } from 'graphql'\nimport { CloseCode } from 'graphql-ws'\nimport { useServer } from 'graphql-ws/lib/use/ws'\nimport type { Server } from 'http'\nimport { pick } from 'es-toolkit/compat'\nimport { WebSocketServer } from 'ws'\nimport type { GraphQLContext, JwtPayload } from '../context'\nimport { logSubscriptionOperation } from '../logging'\nimport type { CreateSubscriptionContext } from './context'\nimport { extractTokenFromConnectionParams, getHost } from './utils'\n\nexport function useSubscriptionsServer<TLogger extends Logger = Logger>({\n  schema,\n  httpServer,\n  createSubscriptionContext,\n  logger,\n  operationLogLevel = 'info',\n  path = '/graphql',\n  verifyToken,\n  requireAuth,\n  jwtClaimsToLog = ['oid', 'iss'],\n  resolveSubscriptionOperationLogger,\n}: {\n  schema: GraphQLSchema\n  httpServer: Server\n  createSubscriptionContext: CreateSubscriptionContext\n  logger: TLogger\n  operationLogLevel?: keyof TLogger\n  path?: string\n  verifyToken?: (host: string, token: string) => Promise<JwtPayload>\n  requireAuth?: boolean\n  jwtClaimsToLog?: string[]\n  resolveSubscriptionOperationLogger?: (context: GraphQLContext) => TLogger\n}) {\n  if (requireAuth && !verifyToken) throw new Error('verifyToken must be supplied when requireAuth is true')\n\n  const wsServer = new WebSocketServer({\n    server: httpServer,\n    path,\n  })\n\n  return useServer(\n    {\n      schema,\n      onError(_ctx, message, errors) {\n        logger.error('GraphQL subscriptions server error', { message, errors })\n      },\n      onConnect: async (ctx) => {\n        const connectionEstablished = 'Subscription connection established'\n        if (!verifyToken) {\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            return false\n          }\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        try {\n          const claims = await verifyToken(getHost(ctx.extra.request), token)\n          ctx.extra.claims = claims as unknown as undefined\n          logger.info(connectionEstablished, {\n            claims: pick(claims, jwtClaimsToLog),\n          })\n          return true\n        } catch (error) {\n          logger.error('Failed to verify subscription connection auth token', { error })\n          return false\n        }\n      },\n      onSubscribe: async (ctx) => {\n        if (!verifyToken) return\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n          }\n          return\n        }\n        try {\n          await verifyToken(getHost(ctx.extra.request), token)\n        } catch (error) {\n          logger.warn('Subscription connection auth token is no longer valid', { claims: pick(ctx.extra.claims, jwtClaimsToLog), error })\n          ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n        }\n      },\n      onDisconnect({ extra: { claims } }) {\n        logger.info('Subscription connection disconnected', { claims: pick(claims, jwtClaimsToLog) })\n      },\n      context: async (ctx) => {\n        return createSubscriptionContext({\n          connectRequest: ctx.extra.request,\n          connectionParams: ctx.connectionParams,\n          claims: ctx.extra.claims as JwtPayload | undefined,\n        })\n      },\n      onOperation(_ctx, _message, args) {\n        logSubscriptionOperation({ args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n      onNext(_ctx, _message, args, { data, ...result }) {\n        logSubscriptionOperation({ args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n    },\n    wsServer,\n  )\n}\n"],"names":["WebSocketServer","useServer","extractTokenFromConnectionParams","getHost","pick","CloseCode","logSubscriptionOperation"],"mappings":"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"}
+{"version":3,"file":"server.js","sources":["../../src/subscriptions/server.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { pick } from 'es-toolkit/compat'\nimport type { GraphQLSchema } from 'graphql'\nimport { CloseCode } from 'graphql-ws'\nimport { useServer } from 'graphql-ws/use/ws'\nimport type { Server } from 'http'\nimport { WebSocketServer } from 'ws'\nimport type { GraphQLContext, JwtPayload } from '../context'\nimport { logSubscriptionOperation } from '../logging'\nimport type { CreateSubscriptionContext } from './context'\nimport { extractTokenFromConnectionParams, getHost } from './utils'\n\nexport function useSubscriptionsServer<TLogger extends Logger = Logger>({\n  schema,\n  httpServer,\n  createSubscriptionContext,\n  logger,\n  operationLogLevel = 'info',\n  path = '/graphql',\n  verifyToken,\n  requireAuth,\n  jwtClaimsToLog = ['oid', 'iss'],\n  resolveSubscriptionOperationLogger,\n}: {\n  schema: GraphQLSchema\n  httpServer: Server\n  createSubscriptionContext: CreateSubscriptionContext\n  logger: TLogger\n  operationLogLevel?: keyof TLogger\n  path?: string\n  verifyToken?: (host: string, token: string) => Promise<JwtPayload>\n  requireAuth?: boolean\n  jwtClaimsToLog?: string[]\n  resolveSubscriptionOperationLogger?: (context: GraphQLContext) => TLogger\n}) {\n  if (requireAuth && !verifyToken) throw new Error('verifyToken must be supplied when requireAuth is true')\n\n  const wsServer = new WebSocketServer({\n    server: httpServer,\n    path,\n  })\n\n  return useServer(\n    {\n      schema,\n      onError(_ctx, message, errors) {\n        logger.error('GraphQL subscriptions server error', { message, errors })\n      },\n      onConnect: async (ctx) => {\n        const connectionEstablished = 'Subscription connection established'\n        if (!verifyToken) {\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            return false\n          }\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        try {\n          const claims = await verifyToken(getHost(ctx.extra.request), token)\n          ctx.extra.claims = claims as unknown as undefined\n          logger.info(connectionEstablished, {\n            claims: pick(claims, jwtClaimsToLog),\n          })\n          return true\n        } catch (error) {\n          logger.error('Failed to verify subscription connection auth token', { error })\n          return false\n        }\n      },\n      onSubscribe: async (ctx) => {\n        if (!verifyToken) return\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n          }\n          return\n        }\n        try {\n          await verifyToken(getHost(ctx.extra.request), token)\n        } catch (error) {\n          logger.warn('Subscription connection auth token is no longer valid', { claims: pick(ctx.extra.claims, jwtClaimsToLog), error })\n          ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n        }\n      },\n      onDisconnect({ extra: { claims } }) {\n        logger.info('Subscription connection disconnected', { claims: pick(claims, jwtClaimsToLog) })\n      },\n      context: async (ctx) => {\n        return createSubscriptionContext({\n          connectRequest: ctx.extra.request,\n          connectionParams: ctx.connectionParams,\n          claims: ctx.extra.claims as JwtPayload | undefined,\n        })\n      },\n      onOperation(_ctx, id, _payload, args) {\n        logSubscriptionOperation({ id, args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n      onNext(_ctx, id, _payload, args, { data, ...result }) {\n        logSubscriptionOperation({ id, args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n    },\n    wsServer,\n  )\n}\n"],"names":["WebSocketServer","useServer","extractTokenFromConnectionParams","getHost","pick","CloseCode","logSubscriptionOperation"],"mappings":"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"}

package/subscriptions/server.mjs

@@ -1,6 +1,6 @@
-import { CloseCode } from 'graphql-ws';
-import { useServer } from 'graphql-ws/lib/use/ws';
 import { pick } from 'es-toolkit/compat';
+import { CloseCode } from 'graphql-ws';
+import { useServer } from 'graphql-ws/use/ws';
 import { WebSocketServer } from 'ws';
 import { logSubscriptionOperation } from '../logging.mjs';
 import { extractTokenFromConnectionParams, getHost } from './utils.mjs';
@@ -74,11 +74,11 @@ function useSubscriptionsServer({ schema, httpServer, createSubscriptionContext,
                 claims: ctx.extra.claims,
             });
         },
-        onOperation(_ctx, _message, args) {
-            logSubscriptionOperation({ args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger });
+        onOperation(_ctx, id, _payload, args) {
+            logSubscriptionOperation({ id, args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger });
         },
-        onNext(_ctx, _message, args, { data, ...result }) {
-            logSubscriptionOperation({ args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger });
+        onNext(_ctx, id, _payload, args, { data, ...result }) {
+            logSubscriptionOperation({ id, args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger });
         },
     }, wsServer);
 }

package/subscriptions/server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"server.mjs","sources":["../../src/subscriptions/server.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport type { GraphQLSchema } from 'graphql'\nimport { CloseCode } from 'graphql-ws'\nimport { useServer } from 'graphql-ws/lib/use/ws'\nimport type { Server } from 'http'\nimport { pick } from 'es-toolkit/compat'\nimport { WebSocketServer } from 'ws'\nimport type { GraphQLContext, JwtPayload } from '../context'\nimport { logSubscriptionOperation } from '../logging'\nimport type { CreateSubscriptionContext } from './context'\nimport { extractTokenFromConnectionParams, getHost } from './utils'\n\nexport function useSubscriptionsServer<TLogger extends Logger = Logger>({\n  schema,\n  httpServer,\n  createSubscriptionContext,\n  logger,\n  operationLogLevel = 'info',\n  path = '/graphql',\n  verifyToken,\n  requireAuth,\n  jwtClaimsToLog = ['oid', 'iss'],\n  resolveSubscriptionOperationLogger,\n}: {\n  schema: GraphQLSchema\n  httpServer: Server\n  createSubscriptionContext: CreateSubscriptionContext\n  logger: TLogger\n  operationLogLevel?: keyof TLogger\n  path?: string\n  verifyToken?: (host: string, token: string) => Promise<JwtPayload>\n  requireAuth?: boolean\n  jwtClaimsToLog?: string[]\n  resolveSubscriptionOperationLogger?: (context: GraphQLContext) => TLogger\n}) {\n  if (requireAuth && !verifyToken) throw new Error('verifyToken must be supplied when requireAuth is true')\n\n  const wsServer = new WebSocketServer({\n    server: httpServer,\n    path,\n  })\n\n  return useServer(\n    {\n      schema,\n      onError(_ctx, message, errors) {\n        logger.error('GraphQL subscriptions server error', { message, errors })\n      },\n      onConnect: async (ctx) => {\n        const connectionEstablished = 'Subscription connection established'\n        if (!verifyToken) {\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            return false\n          }\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        try {\n          const claims = await verifyToken(getHost(ctx.extra.request), token)\n          ctx.extra.claims = claims as unknown as undefined\n          logger.info(connectionEstablished, {\n            claims: pick(claims, jwtClaimsToLog),\n          })\n          return true\n        } catch (error) {\n          logger.error('Failed to verify subscription connection auth token', { error })\n          return false\n        }\n      },\n      onSubscribe: async (ctx) => {\n        if (!verifyToken) return\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n          }\n          return\n        }\n        try {\n          await verifyToken(getHost(ctx.extra.request), token)\n        } catch (error) {\n          logger.warn('Subscription connection auth token is no longer valid', { claims: pick(ctx.extra.claims, jwtClaimsToLog), error })\n          ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n        }\n      },\n      onDisconnect({ extra: { claims } }) {\n        logger.info('Subscription connection disconnected', { claims: pick(claims, jwtClaimsToLog) })\n      },\n      context: async (ctx) => {\n        return createSubscriptionContext({\n          connectRequest: ctx.extra.request,\n          connectionParams: ctx.connectionParams,\n          claims: ctx.extra.claims as JwtPayload | undefined,\n        })\n      },\n      onOperation(_ctx, _message, args) {\n        logSubscriptionOperation({ args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n      onNext(_ctx, _message, args, { data, ...result }) {\n        logSubscriptionOperation({ args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n    },\n    wsServer,\n  )\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.mjs","sources":["../../src/subscriptions/server.ts"],"sourcesContent":["import type { Logger } from '@makerx/node-common'\nimport { pick } from 'es-toolkit/compat'\nimport type { GraphQLSchema } from 'graphql'\nimport { CloseCode } from 'graphql-ws'\nimport { useServer } from 'graphql-ws/use/ws'\nimport type { Server } from 'http'\nimport { WebSocketServer } from 'ws'\nimport type { GraphQLContext, JwtPayload } from '../context'\nimport { logSubscriptionOperation } from '../logging'\nimport type { CreateSubscriptionContext } from './context'\nimport { extractTokenFromConnectionParams, getHost } from './utils'\n\nexport function useSubscriptionsServer<TLogger extends Logger = Logger>({\n  schema,\n  httpServer,\n  createSubscriptionContext,\n  logger,\n  operationLogLevel = 'info',\n  path = '/graphql',\n  verifyToken,\n  requireAuth,\n  jwtClaimsToLog = ['oid', 'iss'],\n  resolveSubscriptionOperationLogger,\n}: {\n  schema: GraphQLSchema\n  httpServer: Server\n  createSubscriptionContext: CreateSubscriptionContext\n  logger: TLogger\n  operationLogLevel?: keyof TLogger\n  path?: string\n  verifyToken?: (host: string, token: string) => Promise<JwtPayload>\n  requireAuth?: boolean\n  jwtClaimsToLog?: string[]\n  resolveSubscriptionOperationLogger?: (context: GraphQLContext) => TLogger\n}) {\n  if (requireAuth && !verifyToken) throw new Error('verifyToken must be supplied when requireAuth is true')\n\n  const wsServer = new WebSocketServer({\n    server: httpServer,\n    path,\n  })\n\n  return useServer(\n    {\n      schema,\n      onError(_ctx, message, errors) {\n        logger.error('GraphQL subscriptions server error', { message, errors })\n      },\n      onConnect: async (ctx) => {\n        const connectionEstablished = 'Subscription connection established'\n        if (!verifyToken) {\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            return false\n          }\n          logger.info(connectionEstablished)\n          return true\n        }\n\n        try {\n          const claims = await verifyToken(getHost(ctx.extra.request), token)\n          ctx.extra.claims = claims as unknown as undefined\n          logger.info(connectionEstablished, {\n            claims: pick(claims, jwtClaimsToLog),\n          })\n          return true\n        } catch (error) {\n          logger.error('Failed to verify subscription connection auth token', { error })\n          return false\n        }\n      },\n      onSubscribe: async (ctx) => {\n        if (!verifyToken) return\n        const token = extractTokenFromConnectionParams(ctx.connectionParams)\n        if (!token) {\n          if (requireAuth) {\n            logger.error('No authorization parameter was supplied via websocket connection params')\n            ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n          }\n          return\n        }\n        try {\n          await verifyToken(getHost(ctx.extra.request), token)\n        } catch (error) {\n          logger.warn('Subscription connection auth token is no longer valid', { claims: pick(ctx.extra.claims, jwtClaimsToLog), error })\n          ctx.extra.socket.close(CloseCode.Forbidden, 'Forbidden')\n        }\n      },\n      onDisconnect({ extra: { claims } }) {\n        logger.info('Subscription connection disconnected', { claims: pick(claims, jwtClaimsToLog) })\n      },\n      context: async (ctx) => {\n        return createSubscriptionContext({\n          connectRequest: ctx.extra.request,\n          connectionParams: ctx.connectionParams,\n          claims: ctx.extra.claims as JwtPayload | undefined,\n        })\n      },\n      onOperation(_ctx, id, _payload, args) {\n        logSubscriptionOperation({ id, args, logLevel: operationLogLevel, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n      onNext(_ctx, id, _payload, args, { data, ...result }) {\n        logSubscriptionOperation({ id, args, logLevel: operationLogLevel, result, resolveLogger: resolveSubscriptionOperationLogger })\n      },\n    },\n    wsServer,\n  )\n}\n"],"names":[],"mappings":"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"}

package/subscriptions/utils.d.cts

@@ -0,0 +1,10 @@
+import type { IncomingMessage } from 'http';
+/**
+ * Extracts a token from a connection parameter named `authorization` or `Authorization`.
+ * The expected format of the parameter value is: Bearer <token>, consistent with an HTTP Authorization header.
+ * Apollo Sandbox sets an `Authorization` connection parameter when you specify an HTTP Authorization header via the UI.
+ * @param connectionParams
+ * @returns
+ */
+export declare function extractTokenFromConnectionParams(connectionParams?: Readonly<Record<string, unknown>>): string | undefined;
+export declare function getHost(request: IncomingMessage): string;

package/subscriptions/utils.d.mts

@@ -0,0 +1,10 @@
+import type { IncomingMessage } from 'http';
+/**
+ * Extracts a token from a connection parameter named `authorization` or `Authorization`.
+ * The expected format of the parameter value is: Bearer <token>, consistent with an HTTP Authorization header.
+ * Apollo Sandbox sets an `Authorization` connection parameter when you specify an HTTP Authorization header via the UI.
+ * @param connectionParams
+ * @returns
+ */
+export declare function extractTokenFromConnectionParams(connectionParams?: Readonly<Record<string, unknown>>): string | undefined;
+export declare function getHost(request: IncomingMessage): string;

package/type-utils.d.cts

@@ -0,0 +1,4 @@
+export type Primitive = string | number | symbol | bigint | boolean | null | undefined | Date;
+type ScalarPropsInternal<T, TKey extends keyof T, TAdditionalScalars = never> = TKey extends any ? T[TKey] extends Primitive | TAdditionalScalars ? TKey : never : never;
+export type ScalarProps<T, TAdditionalScalars = never> = Pick<T, ScalarPropsInternal<T, keyof T, TAdditionalScalars>>;
+export {};

package/type-utils.d.mts

@@ -0,0 +1,4 @@
+export type Primitive = string | number | symbol | bigint | boolean | null | undefined | Date;
+type ScalarPropsInternal<T, TKey extends keyof T, TAdditionalScalars = never> = TKey extends any ? T[TKey] extends Primitive | TAdditionalScalars ? TKey : never : never;
+export type ScalarProps<T, TAdditionalScalars = never> = Pick<T, ScalarPropsInternal<T, keyof T, TAdditionalScalars>>;
+export {};

package/unauthorised.d.cts

@@ -0,0 +1,30 @@
+import { GraphQLError } from 'graphql';
+/**
+ * Builds a `GraphQLError` representing an authorization failure.
+ *
+ * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and
+ * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.
+ *
+ * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.
+ */
+export declare const unauthorisedError: (message?: string) => GraphQLError;
+/**
+ * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.
+ * @param message Optional override for the error message.
+ */
+export declare function throwUnauthorised(message?: string): never;
+/**
+ * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.
+ *
+ * Use at the top of resolvers or services to fail fast on authorization checks while keeping
+ * the happy path unindented.
+ *
+ * @param hasPermission Boolean guard; the function returns normally only when this is `true`.
+ * @param message Optional override for the error message thrown on failure.
+ *
+ * Usage:
+ *
+ * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')
+ * // past this line, TypeScript knows the condition held
+ */
+export declare function permissionInvariant(hasPermission: boolean, message?: string): asserts hasPermission;

package/unauthorised.d.mts

@@ -0,0 +1,30 @@
+import { GraphQLError } from 'graphql';
+/**
+ * Builds a `GraphQLError` representing an authorization failure.
+ *
+ * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and
+ * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.
+ *
+ * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.
+ */
+export declare const unauthorisedError: (message?: string) => GraphQLError;
+/**
+ * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.
+ * @param message Optional override for the error message.
+ */
+export declare function throwUnauthorised(message?: string): never;
+/**
+ * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.
+ *
+ * Use at the top of resolvers or services to fail fast on authorization checks while keeping
+ * the happy path unindented.
+ *
+ * @param hasPermission Boolean guard; the function returns normally only when this is `true`.
+ * @param message Optional override for the error message thrown on failure.
+ *
+ * Usage:
+ *
+ * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')
+ * // past this line, TypeScript knows the condition held
+ */
+export declare function permissionInvariant(hasPermission: boolean, message?: string): asserts hasPermission;

package/utils.d.cts

@@ -0,0 +1,3 @@
+export declare const isIntrospectionQuery: (query?: string) => boolean | undefined;
+export declare const isNil: (value: unknown) => value is null | undefined;
+export declare const isNotNil: <T>(value: T) => value is Exclude<T, undefined | null>;

package/utils.d.mts

@@ -0,0 +1,3 @@
+export declare const isIntrospectionQuery: (query?: string) => boolean | undefined;
+export declare const isNil: (value: unknown) => value is null | undefined;
+export declare const isNotNil: <T>(value: T) => value is Exclude<T, undefined | null>;