graphql-safe-guards 1.1.2 → 1.2.1

package/CHANGELOG.md

@@ -2,34 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ---
 
 ## [Unreleased]
 
+- Internal improvements and documentation refinements.
+
+---
+
 ## [1.1.2] – 2026-01-22
 
+### Fixed
+
+- Corrected edge cases where GraphQL introspection queries were still
+  partially evaluated under certain validation paths.
+- Improved consistency when `ignoreIntrospection` is enabled to ensure
+  introspection queries fully bypass depth and complexity validation.
+
+_No breaking changes._
+
+---
+
 ## [1.1.0] – 2026-01-22
 
 ### Added
 
 - `ignoreIntrospection` option to allow GraphQL introspection queries
   without applying depth and complexity validation.
-- Documentation explaining how to use `ignoreIntrospection` with
-  GraphQL Playground and Apollo Sandbox.
-- Security guidelines for private APIs with introspection enabled.
+- Security documentation explaining safe introspection usage for
+  private APIs and development tools (GraphQL Playground, Apollo Sandbox).
 
 ### Changed
 
-- `ignoreIntrospection` option to exclude GraphQL introspection queries
-  from depth and complexity validation.
+- Introspection queries are now explicitly detected and handled
+  during validation rather than relying on implicit field checks.
 
 ### Fixed
 
-- Ensured GraphQL introspection queries are excluded from depth and
-  complexity validation when `ignoreIntrospection` is enabled.
+- Prevented false positives when validating introspection-related fields
+  in schemas with strict depth or complexity limits.
+
+_No breaking changes._
 
 ---
 
@@ -37,9 +53,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- Preset-based configuration (`strict`, `balanced`, `relaxed`)
+- Preset-based configuration (`strict`, `balanced`, `relaxed`) for
+  common production use cases.
 - Integration tests validating combined depth and complexity limits
+  using native `graphql-js` validation.
 
 ### Fixed
 
-- Type-safe preset resolution
+- Type-safe preset resolution to ensure predictable configuration behavior.
+
+---
+
+## [1.0.0]
+
+### Added
+
+- Initial release.
+- Unified depth limiting and query complexity validation.
+- Native GraphQL validation rule integration.
+- Framework-agnostic design compatible with `graphql-js` and major servers.

package/README.md

@@ -4,12 +4,58 @@
 ![license](https://img.shields.io/npm/l/graphql-safe-guards)
 ![typescript](https://img.shields.io/badge/TypeScript-Ready-blue)
 
-# graphql-safe-guards
+# graphql-safe-guards 🛡️
 
-Protect your GraphQL API with a single import.
+Protect your GraphQL API from **deep, expensive, and abusive queries**
+by enforcing **query depth** and **query complexity limits before execution**.
 
-A tiny utility that **combines depth limiting and query complexity validation**
-using **native GraphQL validation rules**.
+A tiny, framework-agnostic utility that combines **depth limiting** and
+**query complexity validation** using **native GraphQL validation rules**.
+
+> Designed for production GraphQL APIs, public endpoints, and high-traffic systems.
+
+---
+
+## 🚨 The Problem
+
+GraphQL gives clients a lot of power — sometimes **too much**.
+
+Without safeguards, a single query can:
+
+- Exhaust database connections
+- Cause CPU spikes
+- Trigger accidental or malicious DoS attacks
+- Degrade performance for all users
+
+This is especially dangerous in **public APIs** or **high-traffic applications**.
+
+---
+
+## ✅ The Solution
+
+`graphql-safe-guards` acts as a **logical firewall** for GraphQL queries.
+
+Before **any resolver executes**, it:
+
+- Validates query depth
+- Calculates query complexity
+- Rejects unsafe operations early
+
+No resolvers are executed.  
+No database calls are made.
+
+---
+
+## ✨ Features
+
+- ✅ Limit query depth
+- ✅ Limit query complexity
+- ✅ Blocks abusive or accidental DoS-style queries
+- ✅ Uses native GraphQL validation (AST-based)
+- ✅ No schema directives
+- ✅ No runtime execution cost
+- ✅ Framework-agnostic
+- ✅ Production-ready presets
 
 ---
 
@@ -17,11 +63,13 @@ using **native GraphQL validation rules**.
 
 ```bash
 npm install graphql-safe-guards
+# or
+yarn add graphql-safe-guards
 ```
 
 ---
 
-## Usage (Apollo Server)
+## 🚀 Quick Start (Apollo Server)
 
 ```ts
 import { ApolloServer } from "@apollo/server";
@@ -36,7 +84,31 @@ const server = new ApolloServer({
 });
 ```
 
----
+Any query exceeding the limits will be rejected before execution.
+
+## Presets (Recommended)
+
+graphql-safe-guards includes opinionated, production-ready presets for common use cases.
+
+```ts
+createSafeGuards({ preset: "strict" });
+createSafeGuards({ preset: "balanced" });
+createSafeGuards({ preset: "relaxed" });
+```
+
+| Preset   | Depth | Complexity | Use case                    |
+| -------- | ----- | ---------- | --------------------------- |
+| strict   | 3     | 50         | Public APIs, read-only APIs |
+| balanced | 4     | 100        | Private frontends           |
+| relaxed  | 6     | 200        | Admin / internal tools      |
+
+Environment-based setup
+
+```ts
+createSafeGuards({
+  preset: process.env.NODE_ENV === "production" ? "strict" : "balanced",
+});
+```
 
 ## Configuration
 
@@ -55,7 +127,9 @@ createSafeGuards({
 });
 ```
 
-Security Note ⚠️
+---
+
+## 🔐 Security Note — Introspection⚠️
 
 - This library does not enable or disable GraphQL introspection
 
@@ -74,39 +148,61 @@ const server = new ApolloServer({
 });
 ```
 
-## Presets (Recommended)
+---
 
-graphql-safe-guards includes opinionated, production-ready presets for common use cases.
+### 🔥 What It Protects Against
+
+Deeply nested queries
 
 ```ts
-createSafeGuards({ preset: "strict" });
-createSafeGuards({ preset: "balanced" });
-createSafeGuards({ preset: "relaxed" });
+a {
+  b {
+    c {
+      d {
+        e {
+          f {
+            g
+          }
+        }
+      }
+    }
+  }
+}
 ```
 
-| Preset   | Depth | Complexity | Use case                    |
-| -------- | ----- | ---------- | --------------------------- |
-| strict   | 3     | 50         | Public APIs, read-only APIs |
-| balanced | 4     | 100        | Private frontends           |
-| relaxed  | 6     | 200        | Admin / internal tools      |
+High-cost queries
+
+```ts
+posts(limit: 100) {
+  comments(limit: 100) {
+    author {
+      posts(limit: 100)
+    }
+  }
+}
+```
 
 ---
 
-## What It Does
+## 🧠 How It Works
 
-- Limits query depth
-- Limits query complexity
-- Uses native GraphQL validation
-- No schema directives
-- No runtime execution cost
-- Framework agnostic
+- Parses the GraphQL AST
+- Computes depth and complexity
+- Runs during the validation phase
+- Blocks unsafe queries before execution
 
-Internally, this package composes:
+Fast, predictable, and scalable.
+
+---
+
+## 🧩 Internals
+
+This package composes and unifies:
 
 - `graphql-safe-depth`
 - `graphql-complexity-validation`
 
-The combination is validated through integration tests using native GraphQL validation.
+Validated through integration tests using native graphql-js validation.
 
 ---
 
@@ -120,21 +216,13 @@ The combination is validated through integration tests using native GraphQL vali
 
 ---
 
-## Why this exists
-
-Depth limiting and complexity analysis solve **different problems**.
-Most GraphQL servers need **both**, but wiring them together is repetitive.
+## 📊 Production Recommendations
 
-`graphql-safe-guards` provides a **single, predictable entry point**
-for GraphQL query safety.
-
-### Environment-based setup
-
-```ts
-createSafeGuards({
-  preset: process.env.NODE_ENV === "production" ? "strict" : "balanced",
-});
-```
+- For best results, combine this library with:
+- DataLoader (avoid N+1 queries)
+- Pagination on list fields
+- HTTP caching / CDN
+- Persisted queries (hash-based)
 
 ---
 
@@ -150,6 +238,11 @@ createSafeGuards({
 
 > Roadmap items may change based on feedback and real-world usage.
 
+## ⭐ Support
+
+If this library helped you secure your GraphQL API,
+please consider giving it a ⭐ on GitHub.
+
 ## License
 
 MIT © Mateo Diaz

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "graphql-safe-guards",
-  "version": "1.1.2",
-  "description": "Opinionated GraphQL security guards (depth + complexity) in one import",
+  "version": "1.2.1",
+  "description": "Protect GraphQL APIs from deep and expensive queries using depth and complexity limits",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -16,7 +16,6 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "-": "^0.0.1",
     "graphql-complexity-validation": "^1.0.4",
     "graphql-safe-depth": "^1.0.0"
   },
@@ -25,12 +24,18 @@
   },
   "keywords": [
     "graphql",
-    "security",
-    "depth",
-    "complexity",
-    "apollo",
-    "nest",
-    "yoga"
+    "graphql-security",
+    "graphql-validation",
+    "graphql-query",
+    "graphql-depth-limit",
+    "graphql-complexity",
+    "query-complexity",
+    "depth-limit",
+    "dos-protection",
+    "api-security",
+    "apollo-server",
+    "nestjs",
+    "graphql-yoga"
   ],
   "author": "Mateo diaz lopez <mateodiaz401@gmail.com>",
   "license": "MIT",