@ptdgrp/typedgql 1.0.0-beta.8

package/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2024 tonitrnel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+MIT License
+
+Copyright (c) ChenTao (babyfish.ct@gmail.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# @ptdgrp/typedgql
+
+[![Release](https://github.com/tonitrnel/typedgql/actions/workflows/publish-npm.yml/badge.svg)](https://github.com/tonitrnel/typedgql/actions/workflows/publish-npm.yml)
+
+`typedgql` is a TypeScript-first GraphQL client codegen + runtime library focused on end-to-end type safety and a fluent query-building experience.
+
+For Chinese documentation, see [README.zh-CN.md](./README.zh-CN.md).
+
+## Features
+
+- Generate strongly typed client code from a GraphQL schema
+- Fluent DSL for queries and mutations, for example:
+  `G.query((q) => q.posts((p) => p.id.title))`
+- Decouple selection building from variable values:
+  build once, pass `variables` at `execute(...)` time
+- Zero third-party runtime dependency
+  (only depends on your GraphQL executor)
+- Supports ESM/CJS
+- Default output directory:
+  `node_modules/@ptdgrp/typedgql/__generated`
+
+## Installation
+
+```bash
+pnpm add @ptdgrp/typedgql
+pnpm add -D graphql typescript
+```
+
+## Usage
+
+For advanced usage (Subscription, directives, GraphQL mapping), see:
+
+- [Advanced Usage (Chinese)](./docs/advanced-usage.zh-CN.md)
+
+### 1. Vite Plugin (Recommended)
+
+Configure `vite.config.ts`:
+
+```ts
+import { defineConfig } from "vite";
+import { typedgql } from "@ptdgrp/typedgql/vite";
+
+export default defineConfig({
+  plugins: [
+    typedgql({ schema: "./schema.graphql" }),
+    // or remote schema:
+    // typedgql({ schema: "http://localhost:4000/graphql" }),
+  ],
+});
+```
+
+Codegen runs automatically when Vite starts, and re-runs when the schema changes.
+
+### 2. Manual Generation in Node
+
+```ts
+import { Generator, loadLocalSchema } from "@ptdgrp/typedgql/node";
+
+const generator = new Generator({
+  schemaLoader: () => loadLocalSchema("./schema.graphql"),
+});
+
+await generator.generate();
+```
+
+### 3. Runtime Execution (Basic Example)
+
+```ts
+import { G, execute, setGraphQLExecutor } from "@ptdgrp/typedgql";
+
+setGraphQLExecutor(async (request, variables) => {
+  const res = await fetch("http://localhost:8080/graphql", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query: request, variables }),
+  });
+  return res.json();
+});
+
+const selection = G.query((q) =>
+  q.posts((post) => post.id.title.author((author) => author.id.name)),
+);
+
+const data = await execute(selection);
+```
+
+### 4. Query With Variables (Recommended)
+
+Selections are reusable. Pass variables when calling `execute(...)`.
+
+```ts
+import { G, execute } from "@ptdgrp/typedgql";
+
+const selection = G.query((q) => q.post((post) => post.id.title.content));
+
+const data = await execute(selection, {
+  variables: { id: "p2" },
+});
+```
+
+### 5. Explicit Variable Placeholder (Optional)
+
+```ts
+import { G, execute, ParameterRef } from "@ptdgrp/typedgql";
+
+const selection = G.query((q) =>
+  q.post({ id: ParameterRef.of("postId") }, (post) => post.id.title),
+);
+
+const data = await execute(selection, {
+  variables: { postId: "p2" },
+});
+```
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## Credits
+
+This project evolves from ideas in [graphql-ts-client](https://github.com/babyfish-ct/graphql-ts-client). Thanks to [ChenTao](https://github.com/babyfish-ct) for the foundational work.

package/README.zh-CN.md

@@ -0,0 +1,113 @@
+# @ptdgrp/typedgql
+
+`typedgql` 是一个面向 TypeScript 的 GraphQL 客户端代码生成与运行时库，目标是提供“端到端类型安全 + 链式查询构建体验”。
+
+## 特性
+
+- 基于 GraphQL Schema 生成强类型客户端代码
+- 链式 DSL 构建查询与变更，例如 `G.query((q) => q.posts((p) => p.id.title))`
+- 查询选择与请求变量分离：先构建 selection，再在 `execute` 时传 `variables`
+- 零运行时三方依赖（仅依赖你提供的 GraphQL executor）
+- 支持 ESM/CJS
+- 默认生成到 `node_modules/@ptdgrp/typedgql/__generated`
+
+## 安装
+
+```bash
+pnpm add @ptdgrp/typedgql
+pnpm add -D graphql typescript
+```
+
+## 用法
+
+进阶内容（Subscription、指令、GraphQL 对照）见：
+
+- [typedgql 进阶用法（中文）](./docs/advanced-usage.zh-CN.md)
+
+### 1. Vite 插件方式（推荐）
+
+在 `vite.config.ts` 中配置：
+
+```ts
+import { defineConfig } from "vite";
+import { typedgql } from "@ptdgrp/typedgql/vite";
+
+export default defineConfig({
+  plugins: [
+    typedgql({ schema: "./schema.graphql" }),
+    // 或远程 schema:
+    // typedgql({ schema: "http://localhost:4000/graphql" }),
+  ],
+});
+```
+
+启动 Vite 时会自动生成代码；schema 变更后会自动重新生成。
+
+### 2. Node 手动生成
+
+```ts
+import { Generator, loadLocalSchema } from "@ptdgrp/typedgql/node";
+
+const generator = new Generator({
+  schemaLoader: () => loadLocalSchema("./schema.graphql"),
+});
+
+await generator.generate();
+```
+
+### 3. 运行时执行（基础示例）
+
+```ts
+import { G, execute, setGraphQLExecutor } from "@ptdgrp/typedgql";
+
+setGraphQLExecutor(async (request, variables) => {
+  const res = await fetch("http://localhost:8080/graphql", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query: request, variables }),
+  });
+  return res.json();
+});
+
+const selection = G.query((q) =>
+  q.posts((post) => post.id.title.author((author) => author.id.name)),
+);
+
+const data = await execute(selection);
+```
+
+### 4. 带变量查询（推荐写法）
+
+`selection` 与变量传值解耦：selection 可复用，变量在执行时传入。
+
+```ts
+import { G, execute } from "@ptdgrp/typedgql";
+
+const selection = G.query((q) => q.post((post) => post.id.title.content));
+
+const data = await execute(selection, {
+  variables: { id: "p2" },
+});
+```
+
+### 5. 显式变量占位（可选）
+
+```ts
+import { G, execute, ParameterRef } from "@ptdgrp/typedgql";
+
+const selection = G.query((q) =>
+  q.post({ id: ParameterRef.of("postId") }, (post) => post.id.title),
+);
+
+const data = await execute(selection, {
+  variables: { postId: "p2" },
+});
+```
+
+## License
+
+MIT，详见 [LICENSE](./LICENSE)。
+
+## Credits
+
+本项目基于 [graphql-ts-client](https://github.com/babyfish-ct/graphql-ts-client) 的设计思路演进，感谢 [ChenTao](https://github.com/babyfish-ct) 提供的优秀基础。