A powerful tool to decompose GraphQL SDL (Schema Definition Language) by operation name, producing a minimal SDL containing only the types and fields needed for a specific operation.
- 🎯 Precise decomposition: Extract only the types needed for a specific GraphQL operation
- 📁 File or stdin input: Read SDL from files or pipe it through stdin
- 🔄 All operation types: Support for queries, mutations, and subscriptions
- 📝 TypeScript support: Full TypeScript definitions included
- 🛠️ CLI and programmatic API: Use from command line or integrate into your code
- 🚫 Deprecated field filtering: Exclude deprecated fields by default
- ⚡ Fast and lightweight: Minimal dependencies, built on top of
graphql-js
# Global installation
npm install -g @jackchuka/sdl-decompose
# Or use with npx (no installation required)
npx @jackchuka/sdl-decompose --help
# From file
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser
# From stdin
cat schema.graphql | npx @jackchuka/sdl-decompose --operation getUser
# With mutation
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation createUser --type mutation
# Save to file
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser --output partial.graphql
Usage: sdl-decompose [options]
Options:
-V, --version output the version number
-s, --sdl <file> Path to SDL file (optional, reads from stdin if not provided)
-o, --operation <name> Operation name to decompose (required)
-t, --type <type> Operation type: query, mutation, subscription (default: "query")
--output <file> Output file path (optional, prints to stdout if not provided)
--include-builtins Include builtin scalar types in output (default: false)
--exclude-comments Remove comments and descriptions from output SDL (default: false)
--include-deprecated Include deprecated fields in output (default: false)
-h, --help display help for command
Given this schema:
type Query {
getUser(id: ID!): User
getPost(id: ID!): Post
}
type User {
id: ID!
name: String!
email: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
content: String!
author: User!
}
Running:
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser
Outputs:
type Query {
getUser(id: ID!): User
}
type User {
id: ID!
name: String!
email: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
content: String!
author: User!
}
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation createUser --type mutation --output create-user.graphql
# Clean output without comments or descriptions
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser --exclude-comments
# Include deprecated fields in output (excluded by default)
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser --include-deprecated
# Download schema and decompose in one command
curl -s https://api.example.com/graphql/schema | npx @jackchuka/sdl-decompose --operation getUser
# Process multiple operations
for op in getUser getPost; do
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation $op --output "${op}.graphql"
done
npm install @jackchuka/sdl-decompose
import { decomposeGraphQL } from '@jackchuka/sdl-decompose';
const fullSDL = `
type Query {
getUser(id: ID!): User
getPost(id: ID!): Post
}
type User {
id: ID!
name: String!
posts: [Post!]!
}
type Post {
id: ID!
title: String!
author: User!
}
`;
const result = decomposeGraphQL(fullSDL, 'getUser', 'query', {
includeBuiltinScalars: false,
excludeComments: true,
includeDeprecated: false
});
console.log(result.sdl);
console.log('Collected types:', Array.from(result.collectedTypes));
console.log('Operation found:', result.operationFound);
Parameters:
fullSDL
(string): The complete GraphQL SDLoperationName
(string): Name of the operation to decomposeoperationType
(string, optional): Type of operation -'query'
,'mutation'
, or'subscription'
. Defaults to'query'
options
(object, optional): Configuration options
Options:
includeBuiltinScalars
(boolean): Include built-in scalar types (String, Int, Float, Boolean, ID) in the output. Defaults tofalse
excludeComments
(boolean): Remove comments and descriptions from the output SDL. Defaults tofalse
includeDeprecated
(boolean): Include deprecated fields in the output SDL. Defaults tofalse
Returns:
interface DecomposeResult {
sdl: string; // The decomposed SDL
collectedTypes: Set<string>; // Set of type names that were collected
operationFound: boolean; // Whether the operation was found
}
interface DecomposeOptions {
includeBuiltinScalars?: boolean;
excludeComments?: boolean;
includeDeprecated?: boolean;
}
interface DecomposeResult {
sdl: string;
collectedTypes: Set<string>;
operationFound: boolean;
}
type OperationType = 'query' | 'mutation' | 'subscription';
- Schema Federation: Extract specific operations for federated services
- Code Generation: Generate types for specific operations only
- Testing: Create minimal schemas for testing specific functionality
- Documentation: Generate focused schema documentation
- Bundle Size Optimization: Include only necessary schema parts in client bundles
- API Development: Develop and test individual operations in isolation
SDL Decompose analyzes your GraphQL schema and:
- Finds the target operation in the appropriate root type (Query, Mutation, or Subscription)
- Traverses the type graph starting from the operation's return type and arguments
- Collects all referenced types including nested types, input types, and union/interface implementations
- Reconstructs minimal SDL containing only the necessary types and the target operation
Contributions are welcome! Please feel free to submit a Pull Request.
MIT © jackchuka
- GraphQL Tools - Comprehensive GraphQL utilities
- GraphQL Code Generator - Generate code from GraphQL schemas