@graphql-schema-filter/core

中文文档
0.3.0发布于 2025/11/29MITTypeScriptESM + CJS零依赖近 30 天下载 9万

GraphQL schema filtering library with @expose directive support for target-based access control

原始使用文档
文档目录13 节
  1. Features
  2. Installation
  3. Quick Start
  4. API
  5. filterSchema(schema, options)
  6. Exported Types
  7. FormatSchemaOptions
  8. Directive Definitions
  9. Directives
  10. @expose(tags: [String!]!)
  11. @disableAutoExpose
  12. Documentation
  13. License

@graphql-schema-filter/core

GraphQL schema filtering library with @expose directive support for target-based access control.

Features

  • Target-based filtering: Filter GraphQL schemas based on @expose directives with tag-based access control
  • Smart defaults: Auto-expose output type fields, permissive input type handling, explicit Query/Mutation field control
  • Type-safe: Full TypeScript support with comprehensive type definitions
  • Zero config: Simple API with sensible defaults
  • Production-ready: Dual format (ESM + CJS) with source maps and declaration files

Installation

npm install @graphql-schema-filter/core graphql

Quick Start

import { buildSchema } from "graphql";
import { filterSchema } from "@graphql-schema-filter/core";

const schema = buildSchema(`
  directive @expose(tags: [String!]!) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION

  type Query {
    users: [User!]! @expose(tags: ["readonly", "admin"])
    adminUsers: [User!]! @expose(tags: ["admin"])
  }

  type User {
    id: ID!
    name: String!
    email: String!
    salary: Float @expose(tags: ["admin"])
  }
`);

// Filter for readonly users
const readonlySchema = filterSchema(schema, {
  target: "readonly",
});

// Filter for admin users
const adminSchema = filterSchema(schema, {
  target: "admin",
});

API

filterSchema(schema, options)

Main entry point for filtering GraphQL schemas.

Parameters:

  • schema: GraphQLSchema - The GraphQL schema to filter
  • options: FilterSchemaOptions
    • target: string - The target tag for filtering (e.g., "admin", "readonly")
    • logLevel?: LogLevel - Log level (e.g., "debug", "info", "warn", "none") (default: "none")
    • formatOptions?: FormatSchemaOptions - Schema formatting options (default: alphabetical sorting)

Returns: GraphQLSchema - Filtered schema

Exported Types

import type {
  FilterSchemaOptions,
  FormatSchemaOptions,
  DefinitionsSortOptions,
  SortFieldsOptions,
} from "@graphql-schema-filter/core";

FormatSchemaOptions

Controls the formatting of the filtered schema output.

interface FormatSchemaOptions {
  definitionsSort: DefinitionsSortOptions;
  fieldsSort: SortFieldsOptions;
}

type DefinitionsSortOptions =
  | { type: "alphabetical" }  // Sort by group then alphabetically
  | { type: "none" };         // Preserve original order

type SortFieldsOptions =
  | { type: "alphabetical" }  // Sort fields alphabetically
  | { type: "none" };         // Preserve original order

Definition Groups (in order):

  1. Root types (Query, Mutation, Subscription)
  2. Scalars
  3. Directives
  4. Named types (Object, Interface, Input, Union, Enum - sorted alphabetically)

Directive Definitions

The package includes a directives.graphql file at dist/directives.graphql. You can symlink this file to your project or copy the definitions to your schema as needed:

ln -s node_modules/@graphql-schema-filter/core/dist/directives.graphql src/graphql/directives.graphql

Directives

@expose(tags: [String!]!)

Mark fields as exposed to specific targets.

directive @expose(
  tags: [String!]!
) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION

@disableAutoExpose

Disable automatic field exposure for a type (treat like Query/Mutation).

directive @disableAutoExpose on OBJECT | INTERFACE

Documentation

For detailed documentation, examples, and advanced usage, please visit the GitHub repository.

License

MIT

版本与发布记录

@graphql-schema-filter/core 共发布 5 个版本,首次发布于 2025/11/29;过去 12 个月发布了 5 个版本。

版本发布日期距今
0.3.0latest2025/11/2911 个月前
0.2.02025/11/2911 个月前
0.1.12025/11/2911 个月前
0.1.02025/11/2911 个月前
0.0.12025/11/2911 个月前

关于 @graphql-schema-filter/core 的常见问题

@graphql-schema-filter/core 是什么?

GraphQL schema filtering library with @expose directive support for target-based access control

如何安装 @graphql-schema-filter/core?

在项目目录运行 npm install @graphql-schema-filter/core,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:graphql(^16.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@graphql-schema-filter/core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@graphql-schema-filter/core 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@graphql-schema-filter/core 可以商用吗?

@graphql-schema-filter/core 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@graphql-schema-filter/core 的下载量有多少?

根据 npm 官方下载统计,@graphql-schema-filter/core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 89,945 次,日均约 2,998 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@graphql-schema-filter/core 还在维护吗?

最新版本 0.3.0 发布于 2025/11/29(11 个月前);至今共发布 5 个版本,其中过去 12 个月发布了 5 个;首次发布于 2025/11/29。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。