@gqloom/core 0.2.0

package/README.md

@@ -0,0 +1,29 @@
+# GQLoom
+
+English | [简体中文](./README.zh-CN.md)
+
+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 inspired by [tRPC](https://trpc.io/), [TypeGraphQL](https://typegraphql.com/), and [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.
+
+## Hello, World!
+
+```ts
+import { weave } from "@gqloom/core"
+import { resolver, query } from "@gqloom/valibot"
+import * as v from "valibot"
+
+const HelloResolver = resolver({
+  hello: query(v.string(), () => "world"),
+})
+
+export const schema = weave(HelloResolver)
+```

package/README.zh-CN.md

@@ -0,0 +1,267 @@
+# [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()
+}
+```