@gqloom/core 0.2.0 → 0.2.2

package/README.md

@@ -1,24 +1,24 @@
-# GQLoom
+![GQLoom Logo](https://github.com/modevol-com/gqloom/blob/main/gqloom.svg?raw=true)
 
-English | [简体中文](./README.zh-CN.md)
+# GQLoom
 
-GQLoom is a GraphQL weaver for TypeScript/JavaScript, using Zod, Yup, or Valibot to easily weave GraphQL schemas, providing the best development experience with complete type inference.
+GQLoom is a GraphQL weaver for TypeScript/JavaScript that weaves GraphQL Schema using Valibot, Zod, or Yup, and supports sophisticated type inference to provide the best development experience.
 
-GQLoom is inspired by [tRPC](https://trpc.io/), [TypeGraphQL](https://typegraphql.com/), and [Pothos](https://pothos-graphql.dev/).
+The design of GQLoom is inspired by [tRPC](https://trpc.io/), [TypeGraphQL](https://typegraphql.com/), [Pothos](https://pothos-graphql.dev/).
 
 ## Features
 
-- 📦 Use popular pattern libraries (Zod, Yup, Valibot) to build and validate GraphQL schemas.
-- 🔒 Complete type safety, discover potential issues during compilation.
-- 🧩 Classic middleware system: authentication, caching, logging, etc.
-- 🪄 Accessible Context and DataLoader everywhere.
-- 🔮 No code generation and experimental decorator features.
+- 🚀 GraphQL: flexible and efficient, reducing redundant data transfers;
+- 🔒 Robust type safety: enjoy smart hints during development and spot potential problems during editing;
+- 🔋 Ready to go: middleware, contexts, subscriptions, federated graphs are ready to go;
+- 🔮 No extra magic: no decorators, no metadata and reflection, no code generation, you just need JavaScript/TypeScript;
+- 🧩 Familiar schema libraries: use the schema libraries you already know (Zod, Yup, Valibot) to build GraphQL Schema and validate inputs;
+- 🧑‍💻 Develop happily: highly readable and semantic APIs designed to keep your code tidy;
 
-## Hello, World!
+## Hello World
 
 ```ts
-import { weave } from "@gqloom/core"
-import { resolver, query } from "@gqloom/valibot"
+import { resolver, query, weave } from "@gqloom/valibot"
 import * as v from "valibot"
 
 const HelloResolver = resolver({
@@ -27,3 +27,9 @@ const HelloResolver = resolver({
 
 export const schema = weave(HelloResolver)
 ```
+
+Read [Introduction](https://gqloom.dev/guide/introduction.html) to learn more about GQLoom.
+
+## Getting Started
+
+See [Getting Started](https://gqloom.dev/guide/getting-started.html) to learn how to use GQLoom.

package/dist/index.d.cts

@@ -205,9 +205,13 @@ declare function getSubscriptionOptions(subscribeOrOptions: (() => any) | Subscr
 declare function getFieldOptions({ description, deprecationReason, extensions, }: GraphQLFieldOptions): GraphQLFieldOptions;
 
 interface MiddlewarePayload<TField extends GenericFieldOrOperation = FieldOrOperation<any, any, any, any>> {
+    /** The Output Silk of the field */
     outputSilk: InferSilkO<InferFieldOutput<TField>>;
+    /** The previous object, which for a field on the root Query type is often not used. */
     parent: TField extends FieldOrOperation<infer TParent, any, any, any> ? TParent extends undefined ? undefined : InferSilkO<NonNullable<TParent>> : never;
+    /** A function to parse the input of the field */
     parseInput: TField extends FieldOrOperation<any, any, infer TInput, any> ? CallableInputParser<TInput> : undefined;
+    /** The type of the field: `query`, `mutation`, `subscription` or `field` */
     type: FieldOrOperationType;
 }
 type Middleware<TField extends GenericFieldOrOperation = FieldOrOperation<any, any, any, any>> = (next: () => MayPromise<InferSilkO<InferFieldOutput<TField>>>, payload: MiddlewarePayload<TField>) => MayPromise<InferSilkO<InferFieldOutput<TField>>>;
@@ -223,7 +227,7 @@ interface ResolverPayload<TContext extends object = object, TField extends Field
      */
     readonly root: any;
     /**
-     * The payload provided to the field in the GraphQL query.
+     * The arguments provided to the field in the GraphQL query.
      */
     readonly args: Record<string, any>;
     /**
@@ -231,7 +235,7 @@ interface ResolverPayload<TContext extends object = object, TField extends Field
      */
     readonly context: TContext;
     /**
-     * The source object that contains the field in the parent type.
+     * A custom object each resolver can read from/write to.
      */
     readonly info: GraphQLResolveInfo;
     /**
@@ -557,7 +561,7 @@ declare function inputToArgs(input: InputSchema<GraphQLSilk>): GraphQLFieldConfi
 declare function ensureInputType(silkOrType: GraphQLType | GraphQLSilk): GraphQLInputType;
 declare function ensureInputObjectType(object: GraphQLObjectType | GraphQLInterfaceType | GraphQLInputObjectType): GraphQLInputObjectType;
 
-declare function ensureInterfaceType(gqlType: GraphQLOutputType, interfaceConfig?: GraphQLInterfaceTypeConfig<any, any>): GraphQLInterfaceType;
+declare function ensureInterfaceType(gqlType: GraphQLOutputType, interfaceConfig?: Partial<GraphQLInterfaceTypeConfig<any, any>>): GraphQLInterfaceType;
 
 interface GQLoomExtensions {
     defaultValue?: any;

package/dist/index.d.ts

@@ -205,9 +205,13 @@ declare function getSubscriptionOptions(subscribeOrOptions: (() => any) | Subscr
 declare function getFieldOptions({ description, deprecationReason, extensions, }: GraphQLFieldOptions): GraphQLFieldOptions;
 
 interface MiddlewarePayload<TField extends GenericFieldOrOperation = FieldOrOperation<any, any, any, any>> {
+    /** The Output Silk of the field */
     outputSilk: InferSilkO<InferFieldOutput<TField>>;
+    /** The previous object, which for a field on the root Query type is often not used. */
     parent: TField extends FieldOrOperation<infer TParent, any, any, any> ? TParent extends undefined ? undefined : InferSilkO<NonNullable<TParent>> : never;
+    /** A function to parse the input of the field */
     parseInput: TField extends FieldOrOperation<any, any, infer TInput, any> ? CallableInputParser<TInput> : undefined;
+    /** The type of the field: `query`, `mutation`, `subscription` or `field` */
     type: FieldOrOperationType;
 }
 type Middleware<TField extends GenericFieldOrOperation = FieldOrOperation<any, any, any, any>> = (next: () => MayPromise<InferSilkO<InferFieldOutput<TField>>>, payload: MiddlewarePayload<TField>) => MayPromise<InferSilkO<InferFieldOutput<TField>>>;
@@ -223,7 +227,7 @@ interface ResolverPayload<TContext extends object = object, TField extends Field
      */
     readonly root: any;
     /**
-     * The payload provided to the field in the GraphQL query.
+     * The arguments provided to the field in the GraphQL query.
      */
     readonly args: Record<string, any>;
     /**
@@ -231,7 +235,7 @@ interface ResolverPayload<TContext extends object = object, TField extends Field
      */
     readonly context: TContext;
     /**
-     * The source object that contains the field in the parent type.
+     * A custom object each resolver can read from/write to.
      */
     readonly info: GraphQLResolveInfo;
     /**
@@ -557,7 +561,7 @@ declare function inputToArgs(input: InputSchema<GraphQLSilk>): GraphQLFieldConfi
 declare function ensureInputType(silkOrType: GraphQLType | GraphQLSilk): GraphQLInputType;
 declare function ensureInputObjectType(object: GraphQLObjectType | GraphQLInterfaceType | GraphQLInputObjectType): GraphQLInputObjectType;
 
-declare function ensureInterfaceType(gqlType: GraphQLOutputType, interfaceConfig?: GraphQLInterfaceTypeConfig<any, any>): GraphQLInterfaceType;
+declare function ensureInterfaceType(gqlType: GraphQLOutputType, interfaceConfig?: Partial<GraphQLInterfaceTypeConfig<any, any>>): GraphQLInterfaceType;
 
 interface GQLoomExtensions {
     defaultValue?: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gqloom/core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Create GraphQL schema and resolvers with TypeScript.",
   "type": "module",
   "main": "./dist/index.js",
@@ -26,7 +26,15 @@
   "peerDependencies": {
     "graphql": ">= 16.8.0"
   },
-  "keywords": [],
+  "keywords": [
+    "gqloom",
+    "graphql",
+    "schema",
+    "typescript",
+    "valibot",
+    "zod",
+    "yup"
+  ],
   "author": "xcfox",
   "license": "MIT",
   "publishConfig": {

package/README.zh-CN.md

@@ -1,267 +0,0 @@
-# [GQLoom](../../README.zh-CN.md)
-
-[English](./README.md) | 简体中文
-
-[GQLoom](../../README.zh-CN.md) 是一个用于 TypeScript/JavaScript 的 GraphQL 编织器，使用 Zod、Yup 或者 Valibot 来愉快地编织 GraphQL Schema, 支持完善的类型推断以提供最好的开发体验。
-
-## 你好，世界！
-
-```ts
-import { weave, loom, silk } from "@gqloom/core"
-import { GraphQLString } from "graphql"
-
-const HelloResolver = loom.resolver({
-  hello: loom.query(silk(GraphQLString), () => "world"),
-})
-
-export const schema = weave(HelloResolver)
-```
-
-# GQLoom Core
-
-GQLoom Core 是 GQLoom 的核心库，提供了 GQLoom 的基础功能。
-
-## 概念
-
-GQLoom 意为 GraphQL 的织布机（Loom），其核心理念是从各式Schema 编织出 GraphQL Schema。
-
-### 丝线｜Silk
-
-丝线是 GQLoom 的基础单位，它同时反应 GraphQL 类型和 TypeScript 类型。
-我们可以通过 `silk` 函数创建丝线：
-
-##### 简单的标量丝线
-
-```ts
-import { silk } from "@gqloom/core"
-import { GraphQLString, GraphQLInt } from "graphql"
-
-const StringSilk = silk(GraphQLString)
-const IntSilk = silk(GraphQLInt)
-```
-
-##### 携带类型的对象丝线
-
-```ts
-import { silk } from "@gqloom/core"
-import {
-  GraphQLObjectType,
-  GraphQLNonNull,
-  GraphQLString,
-  GraphQLInt,
-} from "graphql"
-
-interface ICat {
-  name: string
-  age: number
-}
-
-// 这里我们使用 `silk`的泛型参数将 Cat 的类型标记为 ICat
-export const Cat = silk<ICat>(
-  new GraphQLObjectType({
-    name: "Cat",
-    fields: {
-      name: { type: new GraphQLNonNull(GraphQLString) },
-      age: { type: new GraphQLNonNull(GraphQLInt) },
-    },
-  })
-)
-```
-
-直接使用 [graphql.js](https://graphql.org/graphql-js/constructing-types/) 构造 GraphQL 类型可能导致冗长的代码，并且需要手动为丝线添加类型声明。
-使用 Zod、Valibot 可以更轻松地创建丝线。
-
-##### 使用 Zod 创建丝线
-
-```ts
-import { zodSilk } from "@gqloom/zod"
-import { z } from "zod"
-
-const Cat = zodSilk(
-  z.object({
-    __typename: z.literal("Cat").nullish(), // 定义 GraphQL Object 的名称
-    name: z.string(),
-    age: z.number(),
-  })
-)
-```
-
-##### 使用 Valibot 创建丝线
-
-```ts
-import { valibotSilk } from "@gqloom/valibot"
-import * as v from "valibot"
-
-const Cat = valibotSilk(
-  v.object({
-    __typename: v.nullish(v.literal("Cat")), // 定义 GraphQL Object 的名称
-    name: v.string(),
-    age: v.number(),
-  })
-)
-```
-
-### 解析器｜Resolver
-
-解析器是放置 GraphQL 操作（Query、Mutation、Subscription）的地方，GQLoom 会将各个解析器汇总编织成 GraphQL Schema。
-
-```ts
-import { loom, silk } from "@gqloom/core"
-import { GraphQLString } from "graphql"
-
-const { resolver, query, mutation } = loom
-
-const HelloResolver = resolver({
-  hello: query(silk(GraphQLString), () => "world"),
-  bye: mutation(silk(GraphQLString), {
-    description: "say bye",
-    resolve: () => "see you later",
-  }),
-})
-```
-
-解析器内可以存放多个操作。操作通过 `query`、`mutation`或`subscription` 函数创建，它们接受两个参数：
-
-- 1. 丝线：定义了操作返回值的类型；
-- 2. 解析函数以及更多配置：定义了操作的具体逻辑、输入类型及其他配置。
-
-#### 带输入的解析操作
-
-为 GraphQL 操作添加输入类型，只需要在解析函数中添加一个 `input` 参数即可。
-
-```ts
-import { loom, silk } from "@gqloom/core"
-import { GraphQLString } from "graphql"
-
-const { resolver, query } = loom
-
-const GreetingResolver = resolver({
-  greet: query(silk(GraphQLString), {
-    input: { name: silk(GraphQLString) },
-    resolve: ({ name }) => `Hello, ${name}!`,
-  }),
-})
-```
-
-在以上代码中，我们定义了一个 `greet` 操作，它接受一个 `name` 作为输入，然后我们可以在 `resolve` 函数中轻松获取到 `name` 的值。
-
-#### 为对象添加更多字段
-
-我们可以使用 `field` 函数在解析器内为对象添加额外的字段。
-
-```ts
-import { loom, silk } from "@gqloom/core"
-import { GraphQLInt } from "graphql"
-import { Cat } from "./schemas"
-
-const CatResolver = resolver.of(Cat, {
-  cat: query(Cat, () => ({
-    name: "Tom",
-    birthday: "2020-01-01",
-  })),
-
-  // 我们可以在解析函数的第一个参数获取到 `Cat` 实例的值
-  age: field(silk(GraphQLInt), (cat) => {
-    return new Date().getFullYear() - new Date(cat.birthday).getFullYear()
-  }),
-
-  ageAt: field(silk(GraphQLInt), {
-    input: { year: silk(GraphQLInt) },
-    // 当字段包含输入时，我们可以在第二个参数中获取到输入的值
-    resolve: (cat, { year }) => {
-      return year - new Date(cat.birthday).getFullYear()
-    },
-  }),
-
-  // 在对象之间建立关联
-  friend: field(Cat, () => ({
-    name: "Jerry",
-    birthday: "2020-01-01",
-  })),
-})
-```
-
-### 编织器｜Weaver
-
-使用 `weave` 函数将解析器编织成 GraphQL Schema。
-`weave` 能够接受解析器、丝线、中间件、各式配置作为输入，将在之后介绍。
-
-```ts
-import { weave } from "@gqloom/core"
-import { HelloResolver } from "./resolvers"
-
-export const schema = weave(HelloResolver, GreetingResolver)
-```
-
-### 中间件｜Middleware
-
-GQLoom 提供了洋葱式中间件机制，可以在解析器执行之前或之后执行逻辑。
-
-##### 声明一个简单中间件
-
-```ts
-import { Middleware } from "@gqloom/core"
-
-const simpleMiddleware: Middleware = async (next) => {
-  console.log("Before resolve")
-  const result = await next()
-  console.log("After resolve")
-  return result
-}
-```
-
-### 上下文｜Context
-
-使用 `useContext` 函数随处获取上下文。
-
-##### 在解析器中
-
-```ts
-import { loom, silk, useContext } from "@gqloom/core"
-import { GraphQLString } from "graphql"
-
-const { query, mutation } = loom
-
-const HelloResolver = resolver({
-  hello: query(silk(GraphQLString), () => {
-    const name = useContext().info.name
-    return `Hello, ${name}!`
-  }),
-})
-```
-
-##### 在中间件中
-
-```ts
-import { Middleware, useContext } from "@gqloom/core"
-
-const simpleMiddleware: Middleware = async (next) => {
-  const context = useContext()
-  console.log(`Hello, ${context.info.name}!`)
-  return next()
-}
-```
-
-Context 的内容取决于你选择的适配器。
-
-#### 上下文记忆｜Context Memoization
-
-我们有时需要在上下文中设置一些内容，并且在同一个上下文的中间件或解析器中获取同样的值，例如当前访问用户、DataLoader。
-GQLoom 提供了上下文记忆来便捷地实现这一点。
-
-```ts
-import { createMemoization, useContext } from "@gqloom/core"
-
-// 创建一个上下文记忆
-const useVisitor = createMemoization(async () => {
-  const context = useContext()
-  return await fetchVisitor(context.info.visitorId)
-})
-
-// 在中间件中使用上下文记忆
-const AllowAdmin: Middleware = async (next) => {
-  const visitor = await useVisitor()
-  if (visitor.role !== "admin") throw new Error("Forbidden")
-  return next()
-}
-```