@makerx/graphql-core 3.0.0-beta.3 → 3.0.0-beta.5

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,81 @@
+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>({ args, result, message, logLevel, resolveLogger, }: {
+    args: ExecutionArgs;
+    result?: ExecutionResult;
+    message?: string;
+    logLevel?: keyof LoggerLogFunctions<TLogger>;
+    resolveLogger?: (context: GraphQLContext) => TLogger;
+}) => void;
+export {};

package/logging.d.mts

@@ -0,0 +1,81 @@
+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>({ args, result, message, logLevel, resolveLogger, }: {
+    args: ExecutionArgs;
+    result?: ExecutionResult;
+    message?: string;
+    logLevel?: keyof LoggerLogFunctions<TLogger>;
+    resolveLogger?: (context: GraphQLContext) => TLogger;
+}) => void;
+export {};

package/package.json

@@ -4,7 +4,7 @@
     "**"
   ],
   "name": "@makerx/graphql-core",
-  "version": "3.0.0-beta.3",
+  "version": "3.0.0-beta.5",
   "private": false,
   "description": "A set of core GraphQL utilities that MakerX uses to build GraphQL APIs",
   "author": "MakerX",
@@ -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/shield.d.ts

@@ -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.js.map

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

package/shield.mjs.map

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

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/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>;