@samveys/graphql

# createMemoryCounter Function

A fixed-window counter in process memory: the fallback when no `rateLimitStore` or `'cache'` binding exists.

function createMemoryCounter(now?: () => number): RateLimitCounter;

Exported from packages/graphql/src/rate-limit.ts

# graphql Function

The `@samveys/graphql` plugin: serves `POST {path}` with depth, count and cost limits that run before execution, per-object-type rate limits, and batching refused for sensitive operations. Introspection and GraphiQL are available only when `app.env === 'local'`.

function graphql(options: GraphqlOptions): import("@samveys/core").Plugin<GraphqlOptions>;

Exported from packages/graphql/src/plugin.ts

# GraphqlOptions Interface

No documentation comment.

interface GraphqlOptions {
    readonly schema: GraphQLSchema;
    /** Default `/graphql`. */
    readonly path?: string;
    /** Deepest allowed field nesting. Default 10. */
    readonly maxDepth?: number;
    /** Most field selections per operation, fragments expanded. Default 200. */
    readonly maxCount?: number;
    /** Highest allowed total cost per operation. Default 1000. */
    readonly maxCost?: number;
  …

interface GraphqlOptions {
    readonly schema: GraphQLSchema;
    /** Default `/graphql`. */
    readonly path?: string;
    /** Deepest allowed field nesting. Default 10. */
    readonly maxDepth?: number;
    /** Most field selections per operation, fragments expanded. Default 200. */
    readonly maxCount?: number;
    /** Highest allowed total cost per operation. Default 1000. */
    readonly maxCost?: number;
    /** Cost per field by coordinate, e.g. `{ 'Query.reports': 10 }`. */
    readonly costs?: Readonly<Record<string, number>>;
    /** Cost of a field without an entry in `costs`. Default 1. */
    readonly defaultCost?: number;
    /** Arguments that set a list's size and so multiply the cost of its children. Default `['first', 'limit']`. */
    readonly listArguments?: readonly string[];
    /** List size assumed when no size argument is given. Default 10. */
    readonly defaultListSize?: number;
    /** Limits per object type name, counted per client address (`ctx.clientIp`). */
    readonly rateLimits?: Readonly<Record<string, RateLimit>>;
    /** Counter for `rateLimits`. Default: the `'cache'` binding when present, else process memory. */
    readonly rateLimitStore?: RateLimitCounter;
    /**
     * Operations that must not arrive in a batch: an operation name (`Login`) or a root field
     * coordinate (`Mutation.login`). A batch containing one is refused whole.
     */
    readonly sensitiveOperations?: readonly string[];
    /** Allow array bodies at all. Default true; sensitive operations are refused in a batch either way. */
    readonly batching?: boolean;
    /** Most operations in one batch. Default 10. */
    readonly maxBatchSize?: number;
    /** Serve the GraphiQL page on GET when `app.env === 'local'`. Default true. */
    readonly graphiql?: boolean;
    /** Builds the resolver context. Default `{ http: ctx }`. */
    readonly context?: (ctx: HttpContext) => unknown;

Exported from packages/graphql/src/contracts.ts

# RateLimit Interface

A fixed-window limit: at most `limit` hits per `windowMs` for one client and one object type.

interface RateLimit {
    readonly limit: number;
    readonly windowMs: number;
}

Exported from packages/graphql/src/contracts.ts

# RateLimitCounter Interface

The subset of `@samveys/cache` the rate limiter needs; any atomic counter works.

interface RateLimitCounter {
    /** Adds `by` to `key` and returns the new value; `ttlMs` applies only when the key is created. */
    increment(key: string, by?: number, ttlMs?: number): Promise<number>;
}

Exported from packages/graphql/src/contracts.ts

# GraphqlErrorCode Type

`extensions.code` values this package puts on its errors.

type GraphqlErrorCode = 'DEPTH_LIMIT' | 'COUNT_LIMIT' | 'COST_LIMIT' | 'RATE_LIMITED' | 'BATCHING_DISABLED' | 'INTROSPECTION_DISABLED' | 'GRAPHQL_PARSE_FAILED' | 'GRAPHQL_VALIDATION_FAILED' | 'BAD_REQUEST';

Exported from packages/graphql/src/contracts.ts