@gqlkit-ts/cli 0.0.1 → 0.1.0

package/dist/type-extractor/validator/type-validator.js

@@ -0,0 +1,53 @@
+import { BUILT_IN_SCALARS } from "../../shared/constants.js";
+const PLACEHOLDER_TYPES = new Set(["__INLINE_OBJECT__"]);
+function isOptionsObject(arg) {
+    return !Array.isArray(arg) && "types" in arg;
+}
+export function validateTypes(typesOrOptions) {
+    const types = isOptionsObject(typesOrOptions)
+        ? typesOrOptions.types
+        : typesOrOptions;
+    const customScalarNames = isOptionsObject(typesOrOptions)
+        ? typesOrOptions.customScalarNames
+        : undefined;
+    const diagnostics = [];
+    const typeNames = new Set(types.map((t) => t.name));
+    const knownScalars = new Set([
+        ...BUILT_IN_SCALARS,
+        ...(customScalarNames ?? []),
+    ]);
+    for (const type of types) {
+        if (type.kind === "Object" && type.fields) {
+            for (const field of type.fields) {
+                const typeName = field.type.typeName;
+                if (!typeNames.has(typeName) &&
+                    !knownScalars.has(typeName) &&
+                    !PLACEHOLDER_TYPES.has(typeName)) {
+                    diagnostics.push({
+                        code: "UNRESOLVED_REFERENCE",
+                        message: `Field '${field.name}' references unresolved type '${typeName}'`,
+                        severity: "error",
+                        location: { file: type.sourceFile, line: 1, column: 1 },
+                    });
+                }
+            }
+        }
+        if (type.kind === "Union" && type.unionMembers) {
+            for (const member of type.unionMembers) {
+                if (!typeNames.has(member) && !knownScalars.has(member)) {
+                    diagnostics.push({
+                        code: "UNRESOLVED_REFERENCE",
+                        message: `Union '${type.name}' references unresolved type '${member}'`,
+                        severity: "error",
+                        location: { file: type.sourceFile, line: 1, column: 1 },
+                    });
+                }
+            }
+        }
+    }
+    return {
+        valid: diagnostics.length === 0,
+        diagnostics,
+    };
+}
+//# sourceMappingURL=type-validator.js.map

package/dist/type-extractor/validator/type-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-validator.js","sourceRoot":"","sources":["../../../src/type-extractor/validator/type-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAY7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;AAEzD,SAAS,eAAe,CACtB,GAA0D;IAE1D,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,OAAO,IAAI,GAAG,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,cAAqE;IAErE,MAAM,KAAK,GAAG,eAAe,CAAC,cAAc,CAAC;QAC3C,CAAC,CAAC,cAAc,CAAC,KAAK;QACtB,CAAC,CAAC,cAAc,CAAC;IACnB,MAAM,iBAAiB,GAAG,eAAe,CAAC,cAAc,CAAC;QACvD,CAAC,CAAC,cAAc,CAAC,iBAAiB;QAClC,CAAC,CAAC,SAAS,CAAC;IAEd,MAAM,WAAW,GAAiB,EAAE,CAAC;IAErC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC;QAC3B,GAAG,gBAAgB;QACnB,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC;KAC7B,CAAC,CAAC;IAEH,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;gBAChC,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;gBAErC,IACE,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC;oBACxB,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC;oBAC3B,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAChC,CAAC;oBACD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,sBAAsB;wBAC5B,OAAO,EAAE,UAAU,KAAK,CAAC,IAAI,iCAAiC,QAAQ,GAAG;wBACzE,QAAQ,EAAE,OAAO;wBACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;gBACvC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBACxD,WAAW,CAAC,IAAI,CAAC;wBACf,IAAI,EAAE,sBAAsB;wBAC5B,OAAO,EAAE,UAAU,IAAI,CAAC,IAAI,iCAAiC,MAAM,GAAG;wBACtE,QAAQ,EAAE,OAAO;wBACjB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;qBACxD,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,WAAW,CAAC,MAAM,KAAK,CAAC;QAC/B,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/docs/configuration.md

@@ -0,0 +1,163 @@
+# Configuration
+
+gqlkit can be configured via `gqlkit.config.ts` in your project root.
+
+## Basic Configuration
+
+```ts
+// gqlkit.config.ts
+import { defineConfig } from "@gqlkit-ts/cli";
+
+export default defineConfig({
+  // Source directory (default: "src/gqlkit/schema")
+  sourceDir: "src/gqlkit/schema",
+
+  // Glob patterns to exclude from scanning
+  sourceIgnoreGlobs: ["**/*.test.ts"],
+
+  // Custom scalar mappings (config-based approach)
+  scalars: [
+    {
+      name: "DateTime",
+      tsType: { from: "./src/gqlkit/schema/scalars", name: "DateTime" },
+      description: "ISO 8601 datetime",
+    },
+    {
+      name: "UUID",
+      tsType: { name: "string" }, // Global type
+    },
+  ],
+
+  // Output paths
+  output: {
+    typeDefsPath: "src/gqlkit/__generated__/typeDefs.ts",
+    resolversPath: "src/gqlkit/__generated__/resolvers.ts",
+    schemaPath: "src/gqlkit/__generated__/schema.graphql",
+    // Set to null to disable output:
+    // schemaPath: null,
+  },
+
+  // Hooks
+  hooks: {
+    // Run after all files are written (e.g., formatting)
+    afterAllFileWrite: "prettier --write",
+    // Or multiple commands:
+    // afterAllFileWrite: ["prettier --write", "eslint --fix"],
+  },
+});
+```
+
+## Custom Scalar Types
+
+Map TypeScript types to GraphQL custom scalars via config:
+
+```ts
+export default defineConfig({
+  scalars: [
+    {
+      name: "DateTime",
+      tsType: { from: "./src/gqlkit/schema/scalars", name: "DateTime" },
+      description: "ISO 8601 datetime string",
+    },
+    {
+      name: "UUID",
+      tsType: { name: "string" },
+      only: "input", // Input-only scalar
+    },
+  ],
+});
+```
+
+### Scalar Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `name` | `string` | The GraphQL scalar name |
+| `tsType.name` | `string` | The TypeScript type name |
+| `tsType.from` | `string` (optional) | Import path for the type (omit for global types) |
+| `description` | `string` (optional) | Description for the GraphQL schema |
+| `only` | `"input"` \| `"output"` (optional) | Restrict scalar to input or output positions |
+
+> [!TIP]
+>
+> You can also define custom scalars using the `GqlScalar` utility type directly in your schema files. See [Scalars](/schema/scalars) for more details.
+
+## Output Paths
+
+Customize output file locations or disable specific outputs:
+
+```ts
+export default defineConfig({
+  output: {
+    typeDefsPath: "generated/schema.ts", // Custom path
+    resolversPath: "generated/resolvers.ts",
+    schemaPath: null, // Disable SDL output
+  },
+});
+```
+
+### Output Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `typeDefsPath` | `string` \| `null` | `"src/gqlkit/__generated__/typeDefs.ts"` | Path for the TypeDefs output |
+| `resolversPath` | `string` \| `null` | `"src/gqlkit/__generated__/resolvers.ts"` | Path for the resolvers output |
+| `schemaPath` | `string` \| `null` | `"src/gqlkit/__generated__/schema.graphql"` | Path for the SDL output |
+
+Set any path to `null` to disable that output.
+
+## Hooks
+
+Execute commands after file generation:
+
+```ts
+export default defineConfig({
+  hooks: {
+    // Single command
+    afterAllFileWrite: "prettier --write",
+  },
+});
+```
+
+You can also specify multiple commands to run sequentially:
+
+```ts
+export default defineConfig({
+  hooks: {
+    // Multiple commands (executed sequentially)
+    afterAllFileWrite: ["prettier --write", "eslint --fix"],
+  },
+});
+```
+
+### Available Hooks
+
+| Hook | Description |
+|------|-------------|
+| `afterAllFileWrite` | Runs after all generated files are written. Receives the list of written file paths. |
+
+## Source Directory
+
+By default, gqlkit scans `src/gqlkit/schema` for types and resolvers.
+
+```ts
+export default defineConfig({
+  sourceDir: "src/graphql/schema", // Custom source directory
+});
+```
+
+All TypeScript files (`.ts`, `.cts`, `.mts`) under this directory are scanned.
+
+## Ignore Patterns
+
+Exclude files from scanning using glob patterns:
+
+```ts
+export default defineConfig({
+  sourceIgnoreGlobs: [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "**/testdata/**",
+  ],
+});
+```

package/docs/getting-started.md

@@ -0,0 +1,117 @@
+# Getting Started
+
+## Installation
+
+```sh filename="npm"
+npm install @gqlkit-ts/runtime @graphql-tools/schema graphql
+npm install -D @gqlkit-ts/cli
+```
+
+```sh filename="pnpm"
+pnpm add @gqlkit-ts/runtime @graphql-tools/schema graphql
+pnpm add -D @gqlkit-ts/cli
+```
+
+```sh filename="yarn"
+yarn add @gqlkit-ts/runtime @graphql-tools/schema graphql
+yarn add -D @gqlkit-ts/cli
+```
+
+## Project Structure
+
+gqlkit expects your types and resolvers to be in `src/gqlkit/schema/`:
+
+```
+src/
+└── gqlkit/
+    ├── context.ts       # Context type definition
+    ├── gqlkit.ts        # Resolver factories
+    └── schema/
+        ├── user.ts      # User type and resolvers
+        ├── post.ts      # Post type and resolvers
+        └── query.ts     # Query resolvers
+```
+
+## Set Up Context and Resolver Factories
+
+Create `src/gqlkit/context.ts` to define your context type:
+
+```typescript
+export type Context = {
+  currentUser: { id: string; name: string; email: string | null } | null;
+};
+```
+
+Create `src/gqlkit/gqlkit.ts` to export resolver factories:
+
+```typescript
+import { createGqlkitApis } from "@gqlkit-ts/runtime";
+import type { Context } from "./context";
+
+export const { defineQuery, defineMutation, defineField } =
+  createGqlkitApis<Context>();
+```
+
+## Define Your First Type
+
+Create a simple User type in `src/gqlkit/schema/user.ts`:
+
+```typescript
+export type User = {
+  id: string;
+  name: string;
+  email: string | null;
+};
+```
+
+## Define a Query
+
+Create a query resolver in `src/gqlkit/schema/query.ts`:
+
+```typescript
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { User } from "./user";
+
+export const me = defineQuery<NoArgs, User | null>(
+  (_root, _args, ctx) => ctx.currentUser
+);
+```
+
+## Generate Schema
+
+Run the generator:
+
+```sh filename="npm"
+npm exec gqlkit gen
+```
+
+```sh filename="pnpm"
+pnpm gqlkit gen
+```
+
+```sh filename="yarn"
+yarn gqlkit gen
+```
+
+This will create files in `src/gqlkit/__generated__/`:
+- `schema.ts` - GraphQL schema AST (DocumentNode)
+- `resolvers.ts` - Resolver map
+
+## Create GraphQL Schema
+
+Use `@graphql-tools/schema` to combine the generated outputs into an executable schema:
+
+```typescript
+import { makeExecutableSchema } from "@graphql-tools/schema";
+import { typeDefs } from "./gqlkit/__generated__/schema";
+import { resolvers } from "./gqlkit/__generated__/resolvers";
+
+export const schema = makeExecutableSchema({ typeDefs, resolvers });
+```
+
+## Next Steps
+
+- [HTTP Server Integration](./integration/yoga) - Connect your schema to graphql-yoga, Apollo Server, or other HTTP servers
+- [Object Types](./schema/objects) - Learn more about defining types
+- [Queries & Mutations](./schema/queries-mutations) - Advanced resolver patterns

package/docs/index.md

@@ -0,0 +1,32 @@
+# gqlkit
+
+> gqlkit is a convention-driven code generator for GraphQL servers in TypeScript. Define GraphQL types and resolver signatures in TypeScript, then `gqlkit gen` generates GraphQL schema AST and a resolver map from your codebase.
+
+## Documentation
+
+- [What is gqlkit?](./what-is-gqlkit.md): gqlkit is a convention-driven code generator for GraphQL servers in TypeScript.
+- [Getting Started](./getting-started.md): gqlkit expects your types and resolvers to be in `src/gqlkit/schema/`:
+
+## Schema Definition
+
+- [Schema Definition](./schema.md): gqlkit generates GraphQL schema from your TypeScript types. All exported types from `src/gqlkit/schema/` are automatically scanned and converted to GraphQL types.
+- [Object Types](./schema/objects.md): Plain TypeScript type exports become GraphQL Object types.
+- [Input Types](./schema/inputs.md): TypeScript types with `Input` suffix are treated as GraphQL input types.
+- [Queries & Mutations](./schema/queries-mutations.md): Define Query and Mutation fields using the `@gqlkit-ts/runtime` API.
+- [Field Resolvers](./schema/fields.md): Add computed fields to object types using `defineField`. Define them alongside the type.
+- [Scalar Types](./schema/scalars.md): gqlkit provides built-in scalar types and supports custom scalar definitions.
+- [Enum Types](./schema/enums.md): gqlkit converts TypeScript string literal unions and enums to GraphQL enum types.
+- [Union Types](./schema/unions.md): TypeScript union types of object types are converted to GraphQL union types.
+- [Interface Types](./schema/interfaces.md): Define GraphQL interface types using the `GqlInterface` utility type.
+- [Abstract Type Resolution](./schema/abstract-resolvers.md): GraphQL abstract types (unions and interfaces) require runtime type resolution to determine the concrete type of returned values. gqlkit provides `defineResolveType` and `defineIsTypeOf` to handle this.
+- [Documentation](./schema/documentation.md): gqlkit extracts TSDoc/JSDoc comments and converts them to GraphQL descriptions.
+- [Custom Directives](./schema/directives.md): Define custom directives using the `GqlDirective` utility type and attach them using `GqlField` or `GqlObject`.
+
+## Integration
+
+- [graphql-yoga](./integration/yoga.md): [graphql-yoga](https://the-guild.dev/graphql/yoga-server) is a batteries-included GraphQL server that works in any JavaScript runtime.
+- [Apollo Server](./integration/apollo.md): [Apollo Server](https://www.apollographql.com/docs/apollo-server/) is a popular GraphQL server with extensive features and ecosystem.
+
+## Guides
+
+- [Configuration](./configuration.md): gqlkit can be configured via `gqlkit.config.ts` in your project root.

package/docs/integration/apollo.md

@@ -0,0 +1,109 @@
+# Apollo Server
+
+[Apollo Server](https://www.apollographql.com/docs/apollo-server/) is a popular GraphQL server with extensive features and ecosystem.
+
+## Installation
+
+```sh filename="npm"
+npm install @apollo/server
+```
+
+```sh filename="pnpm"
+pnpm add @apollo/server
+```
+
+```sh filename="yarn"
+yarn add @apollo/server
+```
+
+## Creating the Schema
+
+First, create an executable schema using `makeExecutableSchema`:
+
+```typescript
+// src/schema.ts
+import { makeExecutableSchema } from "@graphql-tools/schema";
+import { typeDefs } from "./gqlkit/__generated__/schema";
+import { resolvers } from "./gqlkit/__generated__/resolvers";
+
+export const schema = makeExecutableSchema({ typeDefs, resolvers });
+```
+
+## Basic Server
+
+Using the standalone server:
+
+```typescript
+// src/server.ts
+import { ApolloServer } from "@apollo/server";
+import { startStandaloneServer } from "@apollo/server/standalone";
+import { schema } from "./schema";
+
+const server = new ApolloServer({ schema });
+
+const { url } = await startStandaloneServer(server, {
+  listen: { port: 4000 },
+});
+
+console.log(`Server is running on ${url}`);
+```
+
+## With Context
+
+If your resolvers use a context type, provide a context factory:
+
+```typescript
+// src/gqlkit/context.ts
+export type Context = {
+  currentUser: User | null;
+  db: Database;
+};
+```
+
+```typescript
+// src/gqlkit/gqlkit.ts
+import { createGqlkitApis } from "@gqlkit-ts/runtime";
+import type { Context } from "./context";
+
+export const { defineQuery, defineMutation, defineField } =
+  createGqlkitApis<Context>();
+```
+
+```typescript
+// src/gqlkit/schema/query.ts
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { User } from "./user";
+
+export const me = defineQuery<NoArgs, User | null>(
+  (_root, _args, ctx) => ctx.currentUser
+);
+```
+
+```typescript
+// src/server.ts
+import { ApolloServer } from "@apollo/server";
+import { startStandaloneServer } from "@apollo/server/standalone";
+import { schema } from "./schema";
+import type { Context } from "./gqlkit/context";
+
+const server = new ApolloServer<Context>({ schema });
+
+const { url } = await startStandaloneServer(server, {
+  listen: { port: 4000 },
+  context: async ({ req }) => {
+    const user = await getUserFromRequest(req);
+    return {
+      currentUser: user,
+      db: database,
+    };
+  },
+});
+
+console.log(`Server is running on ${url}`);
+```
+
+## Further Reading
+
+- [Apollo Server Documentation](https://www.apollographql.com/docs/apollo-server/)
+- [Apollo Server Plugins](https://www.apollographql.com/docs/apollo-server/builtin-plugins)

package/docs/integration/yoga.md

@@ -0,0 +1,108 @@
+# graphql-yoga
+
+[graphql-yoga](https://the-guild.dev/graphql/yoga-server) is a batteries-included GraphQL server that works in any JavaScript runtime.
+
+## Installation
+
+```sh filename="npm"
+npm install graphql-yoga
+```
+
+```sh filename="pnpm"
+pnpm add graphql-yoga
+```
+
+```sh filename="yarn"
+yarn add graphql-yoga
+```
+
+## Creating the Schema
+
+First, create an executable schema using `makeExecutableSchema`:
+
+```typescript
+// src/schema.ts
+import { makeExecutableSchema } from "@graphql-tools/schema";
+import { typeDefs } from "./gqlkit/__generated__/schema";
+import { resolvers } from "./gqlkit/__generated__/resolvers";
+
+export const schema = makeExecutableSchema({ typeDefs, resolvers });
+```
+
+## Basic Server
+
+```typescript
+// src/server.ts
+import { createServer } from "node:http";
+import { createYoga } from "graphql-yoga";
+import { schema } from "./schema";
+
+const yoga = createYoga({ schema });
+const server = createServer(yoga);
+
+server.listen(4000, () => {
+  console.log("Server is running on http://localhost:4000/graphql");
+});
+```
+
+## With Context
+
+If your resolvers use a context type, provide a context factory:
+
+```typescript
+// src/gqlkit/context.ts
+export type Context = {
+  currentUser: User | null;
+  db: Database;
+};
+```
+
+```typescript
+// src/gqlkit/gqlkit.ts
+import { createGqlkitApis } from "@gqlkit-ts/runtime";
+import type { Context } from "./context";
+
+export const { defineQuery, defineMutation, defineField } =
+  createGqlkitApis<Context>();
+```
+
+```typescript
+// src/gqlkit/schema/query.ts
+import { defineQuery } from "../gqlkit";
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import type { User } from "./user";
+
+export const me = defineQuery<NoArgs, User | null>(
+  (_root, _args, ctx) => ctx.currentUser
+);
+```
+
+```typescript
+// src/server.ts
+import { createServer } from "node:http";
+import { createYoga } from "graphql-yoga";
+import { schema } from "./schema";
+import type { Context } from "./gqlkit/context";
+
+const yoga = createYoga<{}, Context>({
+  schema,
+  context: async ({ request }) => {
+    const user = await getUserFromRequest(request);
+    return {
+      currentUser: user,
+      db: database,
+    };
+  },
+});
+
+const server = createServer(yoga);
+
+server.listen(4000, () => {
+  console.log("Server is running on http://localhost:4000/graphql");
+});
+```
+
+## Further Reading
+
+- [graphql-yoga Documentation](https://the-guild.dev/graphql/yoga-server/docs)
+- [Envelop Plugins](https://the-guild.dev/graphql/envelop/plugins)