@uni2c/graphqlapi4mp 1.0.3 → 1.0.4

package/README.md

@@ -0,0 +1,360 @@
+# @uni2c/graphqlapi4mp
+
+一个轻量、零运行时依赖的 GraphQL SDL 解析与查询文本生成工具。它可以从 SDL 中提取 Query、Mutation、对象类型、标量和枚举，并根据配置生成 selection set 与完整的 GraphQL operation。
+
+适合需要在小程序、Node.js 或前端项目中根据既有 GraphQL Schema 动态构造查询，同时希望控制运行时代码体积的场景。
+
+## 特性
+
+- 解析 GraphQL SDL 中的 `type`、`scalar` 和 `enum`
+- 提取 `Query`、`Mutation` 根字段及参数类型
+- 自动选择标量和枚举字段
+- 按配置递归展开对象字段
+- 生成 Query 或 Mutation 文本
+- 同时支持 ESM 和 CommonJS
+- 内置 TypeScript 类型声明
+- 零运行时依赖
+
+## 安装
+
+```bash
+npm install @uni2c/graphqlapi4mp
+```
+
+也可以使用 pnpm 或 yarn：
+
+```bash
+pnpm add @uni2c/graphqlapi4mp
+# 或
+yarn add @uni2c/graphqlapi4mp
+```
+
+## 模块导入
+
+ESM / TypeScript：
+
+```ts
+import {
+  buildGraphQLQuery,
+  buildSelectionFields,
+  parseSDL,
+} from '@uni2c/graphqlapi4mp';
+```
+
+CommonJS：
+
+```js
+const {
+  buildGraphQLQuery,
+  buildSelectionFields,
+  parseSDL,
+} = require('@uni2c/graphqlapi4mp');
+```
+
+## 完整示例
+
+假设有以下 SDL：
+
+```graphql
+scalar DateTime
+
+enum UserStatus {
+  ACTIVE
+  DISABLED
+}
+
+type Query {
+  user(id: ID!, includeDisabled: Boolean = false): User
+}
+
+type User {
+  id: ID!
+  name: String!
+  status: UserStatus!
+  createdAt: DateTime!
+  profile: Profile
+}
+
+type Profile {
+  bio: String
+  website: String
+}
+```
+
+解析 SDL、选择返回字段并生成查询：
+
+```ts
+import {
+  buildGraphQLQuery,
+  buildSelectionFields,
+  parseSDL,
+  type GraphQLOperation,
+} from '@uni2c/graphqlapi4mp';
+
+const sdl = `
+  scalar DateTime
+  enum UserStatus { ACTIVE DISABLED }
+
+  type Query {
+    user(id: ID!, includeDisabled: Boolean = false): User
+  }
+
+  type User {
+    id: ID!
+    name: String!
+    status: UserStatus!
+    createdAt: DateTime!
+    profile: Profile
+  }
+
+  type Profile {
+    bio: String
+    website: String
+  }
+`;
+
+const schema = parseSDL(sdl);
+const sourceOperation = schema.query.user;
+
+if (!sourceOperation) {
+  throw new Error('Query.user 不存在');
+}
+
+const operation: GraphQLOperation = {
+  ...sourceOperation,
+  fields: buildSelectionFields(schema, sourceOperation, {
+    profile: {
+      website: false,
+    },
+  }),
+};
+
+const query = buildGraphQLQuery(operation, 'query');
+console.log(query);
+```
+
+输出：
+
+```graphql
+query user($id: ID!, $includeDisabled: Boolean) {
+  user(
+    id: $id
+    includeDisabled: $includeDisabled
+  ) {
+    id
+    name
+    status
+    createdAt
+    profile {
+      bio
+    }
+  }
+}
+```
+
+请求时将变量单独传给 GraphQL 客户端：
+
+```ts
+const variables = {
+  id: 'user-1',
+  includeDisabled: false,
+};
+
+await fetch('/graphql', {
+  method: 'POST',
+  headers: {
+    'content-type': 'application/json',
+  },
+  body: JSON.stringify({ query, variables }),
+});
+```
+
+## API
+
+### `parseSDL(sdl)`
+
+解析 SDL 字符串并返回 Schema 元数据。
+
+```ts
+const schema = parseSDL(sdl);
+
+schema.query;    // Query 根字段
+schema.mutation; // Mutation 根字段
+schema.types;    // 所有已解析的对象类型
+schema.scalars;  // 内置标量和自定义标量
+schema.enums;    // 枚举名称
+```
+
+返回类型：
+
+```ts
+interface SchemaMeta {
+  query: Record<string, SchemaField>;
+  mutation: Record<string, SchemaField>;
+  types: Record<string, SchemaType>;
+  scalars: Set<string>;
+  enums: Set<string>;
+}
+```
+
+字段的 `type` 会保留 GraphQL 类型修饰符，例如 `ID!`、`[User!]!`。
+
+### `buildSelectionFields(schema, operation, config?)`
+
+根据 operation 返回类型构造 selection set 字段树。
+
+规则：
+
+- 标量和枚举字段默认包含
+- 对象字段默认不展开
+- 对象字段配置为 `true` 时展开，并包含其直接标量/枚举字段
+- 对象字段配置为对象时，按该配置递归展开
+- 任意字段配置为 `false` 时排除
+
+```ts
+const fields = buildSelectionFields(schema, schema.query.user, {
+  name: false,
+  profile: {
+    bio: true,
+    website: false,
+  },
+});
+```
+
+返回值类似：
+
+```ts
+[
+  'id',
+  'status',
+  'createdAt',
+  {
+    name: 'profile',
+    fields: ['bio'],
+  },
+]
+```
+
+注意：对标量字段设置 `true` 不会改变行为，因为标量字段本来就会默认包含。
+
+### `buildGraphQLQuery(operation, operationType?)`
+
+将 operation 转换为完整 GraphQL 文本。
+
+```ts
+const query = buildGraphQLQuery(operation); // 默认为 query
+const mutation = buildGraphQLQuery(operation, 'mutation');
+```
+
+operation 的参数定义来自 SDL，生成器会同时生成变量声明和字段参数引用。它只生成查询文本，不负责提供实际变量值或发送网络请求。
+
+### `buildQuery(operation, operationType?)`
+
+`buildGraphQLQuery` 的兼容别名。新代码建议使用 `buildGraphQLQuery`。
+
+### `unwrapType(type)`
+
+移除 GraphQL 列表和非空修饰符，返回基础类型名称。
+
+```ts
+unwrapType('User');     // User
+unwrapType('User!');    // User
+unwrapType('[User!]!'); // User
+```
+
+## Mutation 示例
+
+```graphql
+type Mutation {
+  updateUser(id: ID!, name: String!): User
+}
+```
+
+```ts
+const sourceOperation = schema.mutation.updateUser;
+const mutation = buildGraphQLQuery(
+  {
+    ...sourceOperation,
+    fields: buildSelectionFields(schema, sourceOperation),
+  },
+  'mutation',
+);
+```
+
+输出：
+
+```graphql
+mutation updateUser($id: ID!, $name: String!) {
+  updateUser(
+    id: $id
+    name: $name
+  ) {
+    id
+    name
+    status
+    createdAt
+  }
+}
+```
+
+## 手动指定 selection set
+
+不使用 `buildSelectionFields` 时，也可以自行构造字段树：
+
+```ts
+const query = buildGraphQLQuery({
+  name: 'user',
+  type: 'User',
+  args: { id: 'ID!' },
+  fields: [
+    'id',
+    'name',
+    {
+      name: 'profile',
+      fields: ['bio'],
+    },
+  ],
+});
+```
+
+## 当前解析范围
+
+该库面向查询生成所需的轻量 SDL 元数据提取，并不是完整的 GraphQL 规范验证器。目前应注意：
+
+- 根类型按常规名称 `Query` 和 `Mutation` 识别
+- 解析对象 `type`、`scalar` 和 `enum`
+- 支持字段参数、列表类型、非空类型、默认值与指令的跳过处理
+- 不解析 `input`、`interface`、`union`、fragment 或 directive 定义为可查询对象
+- 不验证字段值，也不执行 GraphQL operation
+
+需要完整 Schema 校验、执行或 introspection 时，应配合标准 GraphQL 实现使用。
+
+## 发布产物
+
+包通过条件导出自动选择模块格式：
+
+- ESM：`dist/index.mjs`
+- CommonJS：`dist/index.cjs`
+- TypeScript 声明：`dist/index.d.ts`
+
+项目构建时会自动检查产物体积；超过预算或出现未登记文件时构建失败。
+
+## 开发
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+其他命令：
+
+```bash
+npm run build      # 构建 CJS、ESM 和类型声明，并检查体积
+npm run size       # 检查 dist 文件及体积预算
+npm run test:demo  # 使用项目内大型 SDL 运行演示脚本
+```
+
+## License
+
+ISC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uni2c/graphqlapi4mp",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Parse GraphQL SDL and build GraphQL operation documents.",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",