SDL Decompose


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.

Features

- 🎯 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

Installation

``bash


Global installation

npm install -g @jackchuka/sdl-decompose

Or use with npx (no installation required)

npx @jackchuka/sdl-decompose --help
`

CLI Usage

$3

`bash


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
`

$3

`
Usage: sdl-decompose [options]

Options:
-V, --version output the version number
-s, --sdl Path to SDL file (optional, reads from stdin if not provided)
-o, --operation Operation name to decompose (required)
-t, --type Operation type: query, mutation, subscription (default: "query")
--output 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
`

$3

#### Example 1: Basic Query Decomposition

Given this schema:

`graphql
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:

`bash
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser
`

Outputs:

`graphql
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!
}
`

#### Example 2: Mutation with Output File

`bash
npx @jackchuka/sdl-decompose --sdl schema.graphql --operation createUser --type mutation --output create-user.graphql
`

#### Example 3: Remove Comments from Output

`bash


Clean output without comments or descriptions


npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser --exclude-comments
`

#### Example 4: Include Deprecated Fields

`bash


Include deprecated fields in output (excluded by default)


npx @jackchuka/sdl-decompose --sdl schema.graphql --operation getUser --include-deprecated
`

#### Example 5: Using with Pipes

`bash


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
`

Programmatic API

$3

`bash
npm install @jackchuka/sdl-decompose
`

$3

`typescript
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);
`

$3

#### decomposeGraphQL(fullSDL, operationName, operationType?, options?)

Parameters:

- fullSDL (string): The complete GraphQL SDL
- operationName (string): Name of the operation to decompose
- operationType (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 to false
- excludeComments (boolean): Remove comments and descriptions from the output SDL. Defaults to false
- includeDeprecated (boolean): Include deprecated fields in the output SDL. Defaults to false

Returns:

`typescript
interface DecomposeResult {
sdl: string; // The decomposed SDL
collectedTypes: Set; // Set of type names that were collected
operationFound: boolean; // Whether the operation was found
}
`

$3

`typescript
interface DecomposeOptions {
includeBuiltinScalars?: boolean;
excludeComments?: boolean;
includeDeprecated?: boolean;
}

interface DecomposeResult {
sdl: string;
collectedTypes: Set;
operationFound: boolean;
}

type OperationType = "query" | "mutation" | "subscription";
``

Use Cases

- 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

How It Works

SDL Decompose analyzes your GraphQL schema and:

1. Finds the target operation in the appropriate root type (Query, Mutation, or Subscription)
2. Traverses the type graph starting from the operation's return type and arguments
3. Collects all referenced types including nested types, input types, and union/interface implementations
4. Reconstructs minimal SDL containing only the necessary types and the target operation

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © jackchuka

Related Projects

- GraphQL Tools - Comprehensive GraphQL utilities
- GraphQL Code Generator - Generate code from GraphQL schemas