@ptdgrp/typedgql 1.0.0-beta.15 → 1.0.0-beta.20

package/README.md

@@ -30,8 +30,38 @@ pnpm add -D graphql typescript
 
 For advanced usage (Subscription, directives, GraphQL mapping), see:
 
-- [Advanced Usage (Chinese)](./docs/advanced-usage.zh-CN.md)
-- [Runtime Integration Guide (Chinese)](./docs/runtime-integration.zh-CN.md)
+- [Configuration Guide](./docs/configuration.md) - **NEW: Configuration file support**
+- [Advanced Usage](./docs/advanced-usage.md)
+- [Runtime Integration Guide](./docs/runtime-integration.md)
+- [Quickstart](./docs/quickstart.md)
+- [API Map](./docs/api-map.md)
+- [Variables Semantics](./docs/variables.md)
+- [Fragments Guide](./docs/fragments.md)
+- [Runtime Integration Guide](./docs/runtime-integration.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Generated Files Guide](./docs/generated-files.md)
+
+### 0. Configuration File (Optional)
+
+Create a `.typedgqlrc.toml` file in your project root:
+
+```toml
+# GraphQL schema source
+schema = "./schema.graphql"
+
+# Output directory for generated files
+outputDir = "./src/__generated"
+
+# Indentation (optional)
+indent = "  "
+
+# Scalar type mapping (optional)
+[scalarTypeMap]
+DateTime = "string"
+JSON = "JsonObject"
+```
+
+See [Configuration Guide](./docs/configuration.md) for all available options.
 
 ### 1. Vite Plugin (Recommended)
 
@@ -43,9 +73,12 @@ import { typedgql } from "@ptdgrp/typedgql/vite";
 
 export default defineConfig({
   plugins: [
+    // With inline options
     typedgql({ schema: "./schema.graphql" }),
     // or remote schema:
     // typedgql({ schema: "http://localhost:4000/graphql" }),
+    // or use .typedgqlrc.toml config file:
+    // typedgql(),
   ],
 });
 ```
@@ -55,16 +88,43 @@ 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";
+import { Generator, loadLocalSchema, loadConfig } from "@ptdgrp/typedgql/node";
+
+// Option 1: Use configuration file
+const config = await loadConfig();
+const generator = new Generator({
+  ...config,
+  schemaLoader: () => loadLocalSchema(config.schema),
+});
 
+// Option 2: Programmatic configuration
 const generator = new Generator({
   schemaLoader: () => loadLocalSchema("./schema.graphql"),
+  targetDir: "./src/__generated",
 });
 
 await generator.generate();
 ```
 
-### 3. Runtime Execution (Basic Example)
+### 3. CLI Tool
+
+If you have a `.typedgqlrc.toml` configuration file, you can use the CLI:
+
+```bash
+# Run code generation
+npx typedgql
+
+# Or add to package.json scripts
+{
+  "scripts": {
+    "codegen": "typedgql"
+  }
+}
+```
+
+The CLI will automatically read your `.typedgqlrc.toml` configuration and generate types accordingly.
+
+### 4. Runtime Execution (Basic Example)
 
 ```ts
 import { G, execute, setGraphQLExecutor } from "@ptdgrp/typedgql";

package/README.zh-CN.md

@@ -22,8 +22,38 @@ pnpm add -D graphql typescript
 
 进阶内容（Subscription、指令、GraphQL 对照）见：
 
+- [配置指南（英文）](./docs/configuration.md) - **新增：配置文件支持**
 - [typedgql 进阶用法（中文）](./docs/advanced-usage.zh-CN.md)
 - [typedgql 运行时接入指南（中文）](./docs/runtime-integration.zh-CN.md)
+- [typedgql Quickstart（英文）](./docs/quickstart.md)
+- [typedgql API 地图（英文）](./docs/api-map.md)
+- [typedgql 参数语义（英文）](./docs/variables.md)
+- [typedgql Fragment 指南（英文）](./docs/fragments.md)
+- [typedgql 运行时接入（英文）](./docs/runtime-integration.md)
+- [typedgql 常见问题（英文）](./docs/troubleshooting.md)
+- [typedgql 生成文件说明（英文）](./docs/generated-files.md)
+
+### 0. 配置文件（可选）
+
+在项目根目录创建 `.typedgqlrc.toml` 文件：
+
+```toml
+# GraphQL schema 源
+schema = "./schema.graphql"
+
+# 生成文件的输出目录（可选）
+outputDir = "./src/__generated"
+
+# 缩进（可选）
+indent = "  "
+
+# 标量类型映射（可选）
+[scalarTypeMap]
+DateTime = "string"
+JSON = "JsonObject"
+```
+
+查看[配置指南](./docs/configuration.md)了解所有可用选项。
 
 ### 1. Vite 插件方式（推荐）
 
@@ -35,9 +65,12 @@ import { typedgql } from "@ptdgrp/typedgql/vite";
 
 export default defineConfig({
   plugins: [
+    // 使用内联选项
     typedgql({ schema: "./schema.graphql" }),
     // 或远程 schema:
     // typedgql({ schema: "http://localhost:4000/graphql" }),
+    // 或使用 .typedgqlrc.toml 配置文件:
+    // typedgql(),
   ],
 });
 ```
@@ -47,16 +80,43 @@ export default defineConfig({
 ### 2. Node 手动生成
 
 ```ts
-import { Generator, loadLocalSchema } from "@ptdgrp/typedgql/node";
+import { Generator, loadLocalSchema, loadConfig } from "@ptdgrp/typedgql/node";
 
+// 方式 1: 使用配置文件
+const config = await loadConfig();
+const generator = new Generator({
+  ...config,
+  schemaLoader: () => loadLocalSchema(config.schema),
+});
+
+// 方式 2: 编程式配置
 const generator = new Generator({
   schemaLoader: () => loadLocalSchema("./schema.graphql"),
+  targetDir: "./src/__generated",
 });
 
 await generator.generate();
 ```
 
-### 3. 运行时执行（基础示例）
+### 3. CLI 命令行工具
+
+如果你有 `.typedgqlrc.toml` 配置文件，可以使用 CLI：
+
+```bash
+# 运行代码生成
+npx typedgql
+
+# 或添加到 package.json scripts
+{
+  "scripts": {
+    "codegen": "typedgql"
+  }
+}
+```
+
+CLI 会自动读取 `.typedgqlrc.toml` 配置并生成类型。
+
+### 4. 运行时执行（基础示例）
 
 ```ts
 import { G, execute, setGraphQLExecutor } from "@ptdgrp/typedgql";
@@ -77,7 +137,7 @@ const selection = G.query((q) =>
 const data = await execute(selection);
 ```
 
-### 4. 带变量查询（推荐写法）
+### 5. 带变量查询（推荐写法）
 
 `selection` 与变量传值解耦：selection 可复用，变量在执行时传入。
 
@@ -91,7 +151,7 @@ const data = await execute(selection, {
 });
 ```
 
-### 5. 显式变量占位（可选）
+### 6. 显式变量占位（可选）
 
 ```ts
 import { G, execute, ParameterRef } from "@ptdgrp/typedgql";

package/dist/cli.cjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+const require_config_loader = require('./config-loader-Bxj44SGD.cjs');
+
+//#region src/cli.ts
+/**
+* TypedGQL CLI
+* 
+* Simple command-line tool to generate TypeScript types from GraphQL schema
+* using configuration from .typedgqlrc.toml
+*/
+const isRemote = (schema) => {
+	return /^https?:\/\//.test(schema);
+};
+async function main() {
+	try {
+		console.log("[typedgql] Loading configuration from .typedgqlrc.toml...");
+		const config = await require_config_loader.loadConfig();
+		if (!config) {
+			console.error("[typedgql] Error: No .typedgqlrc.toml configuration file found.\nPlease create a .typedgqlrc.toml file in your project root.\nSee: https://github.com/tonitrnel/typedgql#configuration");
+			process.exit(1);
+			return;
+		}
+		if (!config.schema) {
+			console.error("[typedgql] Error: 'schema' option is required in .typedgqlrc.toml\nPlease specify a schema source:\n  schema = \"./schema.graphql\"  # Local file\n  schema = \"http://localhost:4000/graphql\"  # Remote endpoint");
+			process.exit(1);
+			return;
+		}
+		console.log(`[typedgql] Schema source: ${config.schema}`);
+		if (config.targetDir || config.outputDir) console.log(`[typedgql] Output directory: ${config.targetDir || config.outputDir}`);
+		const schemaLoader = isRemote(config.schema) ? () => require_config_loader.loadRemoteSchema(config.schema, config.schemaHeaders) : () => require_config_loader.loadLocalSchema(config.schema);
+		const generator = new require_config_loader.Generator({
+			...config,
+			schemaLoader
+		});
+		console.log("[typedgql] Generating TypeScript types...");
+		await generator.generate();
+		console.log("[typedgql] ✓ Generation complete!");
+		process.exit(0);
+	} catch (error) {
+		console.error("[typedgql] Error:", error.message);
+		if (process.env.DEBUG) console.error(error.stack);
+		process.exit(1);
+	}
+}
+main();
+
+//#endregion

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/cli.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { a as Generator, i as loadRemoteSchema, r as loadLocalSchema, t as loadConfig } from "./config-loader-DZ7d_CWR.mjs";
+
+//#region src/cli.ts
+/**
+* TypedGQL CLI
+* 
+* Simple command-line tool to generate TypeScript types from GraphQL schema
+* using configuration from .typedgqlrc.toml
+*/
+const isRemote = (schema) => {
+	return /^https?:\/\//.test(schema);
+};
+async function main() {
+	try {
+		console.log("[typedgql] Loading configuration from .typedgqlrc.toml...");
+		const config = await loadConfig();
+		if (!config) {
+			console.error("[typedgql] Error: No .typedgqlrc.toml configuration file found.\nPlease create a .typedgqlrc.toml file in your project root.\nSee: https://github.com/tonitrnel/typedgql#configuration");
+			process.exit(1);
+			return;
+		}
+		if (!config.schema) {
+			console.error("[typedgql] Error: 'schema' option is required in .typedgqlrc.toml\nPlease specify a schema source:\n  schema = \"./schema.graphql\"  # Local file\n  schema = \"http://localhost:4000/graphql\"  # Remote endpoint");
+			process.exit(1);
+			return;
+		}
+		console.log(`[typedgql] Schema source: ${config.schema}`);
+		if (config.targetDir || config.outputDir) console.log(`[typedgql] Output directory: ${config.targetDir || config.outputDir}`);
+		const schemaLoader = isRemote(config.schema) ? () => loadRemoteSchema(config.schema, config.schemaHeaders) : () => loadLocalSchema(config.schema);
+		const generator = new Generator({
+			...config,
+			schemaLoader
+		});
+		console.log("[typedgql] Generating TypeScript types...");
+		await generator.generate();
+		console.log("[typedgql] ✓ Generation complete!");
+		process.exit(0);
+	} catch (error) {
+		console.error("[typedgql] Error:", error.message);
+		if (process.env.DEBUG) console.error(error.stack);
+		process.exit(1);
+	}
+}
+main();
+
+//#endregion
+export {  };
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * TypedGQL CLI\n * \n * Simple command-line tool to generate TypeScript types from GraphQL schema\n * using configuration from .typedgqlrc.toml\n */\n\nimport { Generator } from \"./codegen/generator\";\nimport { loadConfig } from \"./codegen/config-loader\";\nimport { loadLocalSchema, loadRemoteSchema } from \"./codegen/schema-loader\";\n\nconst isRemote = (schema: string): boolean => {\n  return /^https?:\\/\\//.test(schema);\n};\n\nasync function main() {\n  try {\n    console.log(\"[typedgql] Loading configuration from .typedgqlrc.toml...\");\n    \n    // Load configuration file\n    const config = await loadConfig();\n    \n    if (!config) {\n      console.error(\n        \"[typedgql] Error: No .typedgqlrc.toml configuration file found.\\n\" +\n        \"Please create a .typedgqlrc.toml file in your project root.\\n\" +\n        \"See: https://github.com/tonitrnel/typedgql#configuration\"\n      );\n      process.exit(1);\n      return;\n    }\n\n    if (!config.schema) {\n      console.error(\n        \"[typedgql] Error: 'schema' option is required in .typedgqlrc.toml\\n\" +\n        \"Please specify a schema source:\\n\" +\n        '  schema = \"./schema.graphql\"  # Local file\\n' +\n        '  schema = \"http://localhost:4000/graphql\"  # Remote endpoint'\n      );\n      process.exit(1);\n      return;\n    }\n\n    console.log(`[typedgql] Schema source: ${config.schema}`);\n    \n    if (config.targetDir || config.outputDir) {\n      console.log(`[typedgql] Output directory: ${config.targetDir || config.outputDir}`);\n    }\n\n    // Create schema loader\n    const schemaLoader = isRemote(config.schema)\n      ? () => loadRemoteSchema(config.schema!, config.schemaHeaders)\n      : () => loadLocalSchema(config.schema!);\n\n    // Create generator\n    const generator = new Generator({\n      ...config,\n      schemaLoader,\n    });\n\n    console.log(\"[typedgql] Generating TypeScript types...\");\n    \n    // Run generation\n    await generator.generate();\n\n    console.log(\"[typedgql] ✓ Generation complete!\");\n    process.exit(0);\n  } catch (error) {\n    console.error(\"[typedgql] Error:\", (error as Error).message);\n    if (process.env.DEBUG) {\n      console.error((error as Error).stack);\n    }\n    process.exit(1);\n  }\n}\n\n// Run CLI\nmain();\n"],"mappings":";;;;;;;;;;AAaA,MAAM,YAAY,WAA4B;AAC5C,QAAO,eAAe,KAAK,OAAO;;AAGpC,eAAe,OAAO;AACpB,KAAI;AACF,UAAQ,IAAI,4DAA4D;EAGxE,MAAM,SAAS,MAAM,YAAY;AAEjC,MAAI,CAAC,QAAQ;AACX,WAAQ,MACN,yLAGD;AACD,WAAQ,KAAK,EAAE;AACf;;AAGF,MAAI,CAAC,OAAO,QAAQ;AAClB,WAAQ,MACN,qNAID;AACD,WAAQ,KAAK,EAAE;AACf;;AAGF,UAAQ,IAAI,6BAA6B,OAAO,SAAS;AAEzD,MAAI,OAAO,aAAa,OAAO,UAC7B,SAAQ,IAAI,gCAAgC,OAAO,aAAa,OAAO,YAAY;EAIrF,MAAM,eAAe,SAAS,OAAO,OAAO,SAClC,iBAAiB,OAAO,QAAS,OAAO,cAAc,SACtD,gBAAgB,OAAO,OAAQ;EAGzC,MAAM,YAAY,IAAI,UAAU;GAC9B,GAAG;GACH;GACD,CAAC;AAEF,UAAQ,IAAI,4CAA4C;AAGxD,QAAM,UAAU,UAAU;AAE1B,UAAQ,IAAI,oCAAoC;AAChD,UAAQ,KAAK,EAAE;UACR,OAAO;AACd,UAAQ,MAAM,qBAAsB,MAAgB,QAAQ;AAC5D,MAAI,QAAQ,IAAI,MACd,SAAQ,MAAO,MAAgB,MAAM;AAEvC,UAAQ,KAAK,EAAE;;;AAKnB,MAAM"}