@gqlkit-ts/runtime 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,32 @@
+# @gqlkit-ts/runtime
+
+Runtime utilities for [gqlkit](https://gqlkit.izumin.dev) — type-safe resolver definitions with a thin API.
+
+```ts
+// src/gqlkit/gqlkit.ts
+import { createGqlkitApis, type IDString } from "@gqlkit-ts/runtime";
+import {} from "./context.js";
+
+export const { defineQuery, defineMutation, defineField } = createGqlkitApis<Context>();
+```
+
+```ts
+// src/gqlkit/schema/tasks.ts
+import type { NoArgs } from "@gqlkit-ts/runtime";
+import { defineField, defineQuery, defineMutation } from "../gqlkit.js";
+
+// Query
+export const tasks = defineQuery<NoArgs, Task[]>(() => fetchTasks());
+
+// Mutation
+export const createTask = defineMutation<{ input: CreateTaskInput }, Task>(
+  (_, { input }) => createNewTask(input)
+);
+
+// Field resolver
+export const taskAuthor = defineField<Task, NoArgs, User>(
+  (task) => fetchUser(task.authorId)
+);
+```
+
+For full documentation, visit [gqlkit.izumin.dev](https://gqlkit.izumin.dev).

package/dist/index.d.ts

@@ -133,16 +133,18 @@ export type GqlInterface<T extends Record<string, unknown>, Meta extends {
 };
 /**
  * Metadata structure for type-level GraphQL metadata.
- * Used to attach directives and other metadata to types.
+ * Used to attach directives, interface implementations, and field exclusions to types.
  *
  * @typeParam Meta - The metadata configuration object
  */
 export interface GqlTypeMetaShape<Meta extends {
     directives?: ReadonlyArray<GqlDirective<string, Record<string, unknown>, DirectiveLocation | DirectiveLocation[]>>;
     implements?: ReadonlyArray<GqlInterfaceMarker>;
+    ignoreFields?: string;
 }> {
     readonly directives?: Meta["directives"];
     readonly implements?: Meta["implements"];
+    readonly ignoreFields?: Meta["ignoreFields"];
 }
 /**
  * Attaches metadata to a type definition.
@@ -150,11 +152,11 @@ export interface GqlTypeMetaShape<Meta extends {
  * with the underlying type.
  *
  * The structure uses two properties:
- * - `$gqlkitTypeMeta`: Contains the metadata object with directives and implements
+ * - `$gqlkitTypeMeta`: Contains the metadata object with directives, implements, and ignoreFields
  * - `$gqlkitOriginalType`: Preserves the original type T to maintain nullability information
  *
  * @typeParam T - The base type to attach metadata to
- * @typeParam Meta - The metadata configuration object containing directives and/or implements
+ * @typeParam Meta - The metadata configuration object containing directives, implements, and/or ignoreFields
  *
  * @example
  * ```typescript
@@ -188,11 +190,33 @@ export interface GqlTypeMetaShape<Meta extends {
  *     directives: [CacheDirective<{ maxAge: 60 }>]
  *   }
  * >;
+ *
+ * // Type with ignoreFields to exclude fields from GraphQL schema
+ * type User = GqlObject<
+ *   {
+ *     id: IDString;
+ *     name: string;
+ *     internalId: string;
+ *   },
+ *   { ignoreFields: "internalId" }
+ * >;
+ *
+ * // Type with multiple ignored fields
+ * type User = GqlObject<
+ *   {
+ *     id: IDString;
+ *     name: string;
+ *     cacheKey: string;
+ *     internalId: string;
+ *   },
+ *   { ignoreFields: "cacheKey" | "internalId" }
+ * >;
  * ```
  */
 export type GqlObject<T, Meta extends {
     directives?: ReadonlyArray<GqlDirective<string, Record<string, unknown>, DirectiveLocation | DirectiveLocation[]>>;
     implements?: ReadonlyArray<GqlInterfaceMarker>;
+    ignoreFields?: keyof T & string;
 } = {
     directives: [];
 }> = T & {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,kBAAkB,GAClB,qBAAqB,GACrB,WAAW,GACX,OAAO,GACP,MAAM,GACN,YAAY,GACZ,cAAc,GACd,wBAAwB,CAAC;AAE7B;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,CACtB,IAAI,SAAS,MAAM,EACnB,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAC5D,QAAQ,SAAS,iBAAiB,GAAG,iBAAiB,EAAE,GAAG,iBAAiB,IAC1E;IACF,QAAQ,CAAC,iBAAiB,EAAE,IAAI,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,IAAI,CAAC;IACjC,QAAQ,CAAC,qBAAqB,EAAE,QAAQ,CAAC;CAC1C,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB,CAChC,IAAI,SAAS;IACX,UAAU,CAAC,EAAE,aAAa,CACxB,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,CAAC;IACF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;IAED,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,MAAM,QAAQ,CAClB,CAAC,EACD,IAAI,SAAS;IACX,UAAU,CAAC,EAAE,aAAa,CACxB,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,CAAC;IACF,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB,GAAG,MAAM,IACR,CAAC,GAAG;IACN,QAAQ,CAAC,mBAAmB,CAAC,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;CACrC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB,CACpC,IAAI,SAAS;IACX,UAAU,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAChD,GAAG,MAAM;IAEV,QAAQ,CAAC,mBAAmB,EAAE,IAAI,CAAC;IACnC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,MAAM,YAAY,CACtB,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,SAAS;IACX,UAAU,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;CAChD,GAAG,MAAM,IACR,CAAC,GAAG;IACN,QAAQ,CAAC,uBAAuB,CAAC,EAAE,qBAAqB,CAAC,IAAI,CAAC,CAAC;CAChE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB,CAC/B,IAAI,SAAS;IACX,UAAU,CAAC,EAAE,aAAa,CACxB,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,CAAC;IACF,UAAU,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;IAED,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AACH,MAAM,MAAM,SAAS,CACnB,CAAC,EACD,IAAI,SAAS;IACX,UAAU,CAAC,EAAE,aAAa,CACxB,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,CAAC;IACF,UAAU,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IAC/C,YAAY,CAAC,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC;CACjC,GAAG;IAAE,UAAU,EAAE,EAAE,CAAA;CAAE,IACpB,CAAC,GAAG;IACN,QAAQ,CAAC,kBAAkB,CAAC,EAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACrD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAAC;CACrC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,SAAS,CACnB,IAAI,SAAS,MAAM,EACnB,IAAI,EACJ,IAAI,SAAS,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,IACrD,IAAI,GAAG;IACT,gBAAgB,CAAC,EAAE;QACjB,IAAI,EAAE,IAAI,CAAC;QACX,IAAI,EAAE,IAAI,CAAC;KACZ,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAE/C;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,IAAI,CAChE,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,kBAAkB,KACrB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,IAAI,CACnE,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,kBAAkB,KACrB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,IAAI,CACzE,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,kBAAkB,KACrB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,OAAO,CAAC;AAE1D;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,UAAU,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,CAAC,SAAS,EAAE,QAAQ,GAAG,OAAO,IAAI,CACjE,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,kBAAkB,KACrB,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAE9B;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,QAAQ,GAAG,OAAO,IAAI,CACnD,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,EACjB,IAAI,EAAE,kBAAkB,KACrB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC;;;GAGG;AACH,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,mBAAmB,CAC7B,SAAS,EACT,QAAQ,GAAG,OAAO,IAChB,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,GAAG;IAC/C,0BAA0B,CAAC,EAAE;QAC3B,IAAI,EAAE,aAAa,CAAC;QACpB,UAAU,EAAE,SAAS,CAAC;KACvB,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,CAC1B,OAAO,EACP,QAAQ,GAAG,OAAO,IAChB,kBAAkB,CAAC,QAAQ,CAAC,GAAG;IACjC,0BAA0B,CAAC,EAAE;QAC3B,IAAI,EAAE,UAAU,CAAC;QACjB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CACH,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,aAAa,CACvB,KAAK,EACL,OAAO,EACP,QAAQ,GAAG,OAAO,EAClB,WAAW,SAAS,aAAa,CAC/B,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,GAAG,EAAE,IACJ,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG;IAC9C,kBAAkB,CAAC,EAAE;QACnB,IAAI,EAAE,OAAO,CAAC;QACd,IAAI,EAAE,KAAK,CAAC;QACZ,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,WAAW,CAAC;KACzB,CAAC;CACH,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,EACL,OAAO,EACP,QAAQ,GAAG,OAAO,EAClB,WAAW,SAAS,aAAa,CAC/B,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,GAAG,EAAE,IACJ,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG;IACjD,kBAAkB,CAAC,EAAE;QACnB,IAAI,EAAE,UAAU,CAAC;QACjB,IAAI,EAAE,KAAK,CAAC;QACZ,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,WAAW,CAAC;KACzB,CAAC;CACH,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,MAAM,aAAa,CACvB,OAAO,EACP,KAAK,EACL,OAAO,EACP,QAAQ,GAAG,OAAO,EAClB,WAAW,SAAS,aAAa,CAC/B,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,GAAG,EAAE,IACJ,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,GAAG;IACvD,kBAAkB,CAAC,EAAE;QACnB,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,OAAO,CAAC;QAChB,IAAI,EAAE,KAAK,CAAC;QACZ,MAAM,EAAE,OAAO,CAAC;QAChB,UAAU,EAAE,WAAW,CAAC;KACzB,CAAC;CACH,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,QAAQ;IAClC;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,EAAE,CACX,KAAK,EACL,OAAO,EACP,WAAW,SAAS,aAAa,CAC/B,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,GAAG,EAAE,EAEN,QAAQ,EAAE,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,KAChD,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAE1D;;;;;;;;;;;;;;;;;;OAkBG;IACH,cAAc,EAAE,CACd,KAAK,EACL,OAAO,EACP,WAAW,SAAS,aAAa,CAC/B,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,GAAG,EAAE,EAEN,QAAQ,EAAE,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,KACnD,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAE7D;;;;;;;;;;;;;;;;;;;OAmBG;IACH,WAAW,EAAE,CACX,OAAO,EACP,KAAK,EACL,OAAO,EACP,WAAW,SAAS,aAAa,CAC/B,YAAY,CACV,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACvB,iBAAiB,GAAG,iBAAiB,EAAE,CACxC,CACF,GAAG,EAAE,EAEN,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,KACzD,aAAa,CAAC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAC,CAAC;IAEnE;;;;;;;;;;;;;;;OAeG;IACH,iBAAiB,EAAE,CAAC,SAAS,EAC3B,QAAQ,EAAE,qBAAqB,CAAC,SAAS,EAAE,QAAQ,CAAC,KACjD,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAE9C;;;;;;;;;;;;;OAaG;IACH,cAAc,EAAE,CAAC,OAAO,EACtB,QAAQ,EAAE,kBAAkB,CAAC,QAAQ,CAAC,KACnC,gBAAgB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,GAAG,OAAO,KAAK,UAAU,CAAC,QAAQ,CAAC,CA2B3E"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAosBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG;QACX,WAAW,EAAE,CACX,QAAmD,EACnD,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,cAAc,EAAE,CACd,QAAsD,EACtD,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,WAAW,EAAE,CACX,QAA4D,EAC5D,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,iBAAiB,EAAE,CACjB,QAAoD,EACpD,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,cAAc,EAAE,CAAC,QAAsC,EAAE,EAAE;YACzD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;IACF,OAAO,IAAuC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4tBA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,IAAI,GAAG;QACX,WAAW,EAAE,CACX,QAAmD,EACnD,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,cAAc,EAAE,CACd,QAAsD,EACtD,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,WAAW,EAAE,CACX,QAA4D,EAC5D,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,iBAAiB,EAAE,CACjB,QAAoD,EACpD,EAAE;YACF,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,cAAc,EAAE,CAAC,QAAsC,EAAE,EAAE;YACzD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;IACF,OAAO,IAAuC,CAAC;AACjD,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gqlkit-ts/runtime",
-  "version": "0.1.0",
-  "description": "Runtime utilities for gqlkit - type-safe resolver definition functions",
+  "version": "0.2.0",
+  "description": "Runtime utilities for gqlkit — type-safe resolver definitions with a thin API",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,7 +12,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "keywords": [
     "graphql",

package/src/index.ts

@@ -0,0 +1,788 @@
+import type { GraphQLResolveInfo } from "graphql";
+
+/**
+ * Represents the locations where a directive can be applied.
+ * This corresponds to GraphQL Type System Directive Locations.
+ */
+export type DirectiveLocation =
+  | "SCHEMA"
+  | "SCALAR"
+  | "OBJECT"
+  | "FIELD_DEFINITION"
+  | "ARGUMENT_DEFINITION"
+  | "INTERFACE"
+  | "UNION"
+  | "ENUM"
+  | "ENUM_VALUE"
+  | "INPUT_OBJECT"
+  | "INPUT_FIELD_DEFINITION";
+
+/**
+ * Represents a GraphQL directive with name, arguments, and location.
+ * Used to define custom directives that can be attached to types and fields.
+ *
+ * @typeParam Name - The directive name (without @)
+ * @typeParam Args - The argument types for the directive
+ * @typeParam Location - The location(s) where the directive can be applied
+ *
+ * @example
+ * ```typescript
+ * type AuthDirective<R extends string[]> = GqlDirective<"auth", { roles: R }, "FIELD_DEFINITION">;
+ * type CacheDirective = GqlDirective<"cache", { maxAge: number }, "FIELD_DEFINITION" | "OBJECT">;
+ * ```
+ */
+export type GqlDirective<
+  Name extends string,
+  Args extends Record<string, unknown> = Record<string, never>,
+  Location extends DirectiveLocation | DirectiveLocation[] = DirectiveLocation,
+> = {
+  readonly " $directiveName": Name;
+  readonly " $directiveArgs": Args;
+  readonly " $directiveLocation": Location;
+};
+
+/**
+ * Metadata structure for field-level GraphQL metadata.
+ * Used to attach directives, default values, and other metadata to individual fields.
+ *
+ * @typeParam Meta - The metadata configuration object
+ */
+export interface GqlFieldMetaShape<
+  Meta extends {
+    directives?: ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    >;
+    defaultValue?: unknown;
+  },
+> {
+  readonly directives?: Meta["directives"];
+  readonly defaultValue?: Meta["defaultValue"];
+}
+
+/**
+ * Attaches metadata to a field type.
+ * The metadata is embedded as optional properties to maintain compatibility
+ * with the underlying type.
+ *
+ * The structure uses two properties:
+ * - `$gqlkitFieldMeta`: Contains the metadata object with directives and defaultValue
+ * - `$gqlkitOriginalType`: Preserves the original type T to maintain nullability information
+ *
+ * This design is necessary because TypeScript normalizes `(T | null) & { metadata }` to
+ * `(T & { metadata }) | never`, which loses the null part of the union. By storing
+ * the original type in `$gqlkitOriginalType`, we can recover the full type information
+ * during CLI analysis.
+ *
+ * @typeParam T - The base type to attach metadata to
+ * @typeParam Meta - The metadata configuration object containing directives and/or defaultValue
+ *
+ * @example
+ * ```typescript
+ * // With directives
+ * type User = {
+ *   id: GqlField<IDString, { directives: [AuthDirective<{ role: ["USER"] }>] }>;
+ *   bio: GqlField<string | null, { directives: [AuthDirective<{ role: ["ADMIN"] }>] }>;
+ * };
+ *
+ * // With default value
+ * type PaginationInput = {
+ *   limit: GqlField<Int, { defaultValue: 10 }>;
+ *   offset: GqlField<Int, { defaultValue: 0 }>;
+ * };
+ *
+ * // With both directives and default value
+ * type SearchInput = {
+ *   query: GqlField<string, { defaultValue: ""; directives: [SomeDirective] }>;
+ * };
+ * ```
+ */
+export type GqlField<
+  T,
+  Meta extends {
+    directives?: ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    >;
+    defaultValue?: unknown;
+  } = object,
+> = T & {
+  readonly " $gqlkitFieldMeta"?: GqlFieldMetaShape<Meta>;
+  readonly " $gqlkitOriginalType"?: T;
+};
+
+/**
+ * Marker type for GqlInterface - used internally for type discrimination.
+ */
+export type GqlInterfaceMarker = Record<string, unknown>;
+
+/**
+ * Interface metadata structure embedded in intersection types.
+ * Used by CLI to detect and identify interface types through type analysis.
+ *
+ * @typeParam Meta - The metadata configuration object containing implements
+ */
+export interface GqlInterfaceMetaShape<
+  Meta extends {
+    implements?: ReadonlyArray<GqlInterfaceMarker>;
+  } = object,
+> {
+  readonly " $gqlkitInterface": true;
+  readonly implements?: Meta["implements"];
+}
+
+/**
+ * GraphQL interface type definition utility.
+ * Use this to define GraphQL interface types that can be implemented by object types.
+ *
+ * @typeParam T - The interface field definitions as an object type
+ * @typeParam Meta - Optional metadata containing implements for interface inheritance
+ *
+ * @example
+ * ```typescript
+ * // Basic interface definition
+ * export type Node = GqlInterface<{
+ *   id: IDString;
+ * }>;
+ *
+ * export type Timestamped = GqlInterface<{
+ *   createdAt: DateTime;
+ *   updatedAt: DateTime;
+ * }>;
+ *
+ * // Interface inheriting other interfaces
+ * export type Entity = GqlInterface<
+ *   {
+ *     id: IDString;
+ *     createdAt: DateTime;
+ *     updatedAt: DateTime;
+ *   },
+ *   { implements: [Node, Timestamped] }
+ * >;
+ * ```
+ */
+export type GqlInterface<
+  T extends Record<string, unknown>,
+  Meta extends {
+    implements?: ReadonlyArray<GqlInterfaceMarker>;
+  } = object,
+> = T & {
+  readonly " $gqlkitInterfaceMeta"?: GqlInterfaceMetaShape<Meta>;
+};
+
+/**
+ * Metadata structure for type-level GraphQL metadata.
+ * Used to attach directives, interface implementations, and field exclusions to types.
+ *
+ * @typeParam Meta - The metadata configuration object
+ */
+export interface GqlTypeMetaShape<
+  Meta extends {
+    directives?: ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    >;
+    implements?: ReadonlyArray<GqlInterfaceMarker>;
+    ignoreFields?: string;
+  },
+> {
+  readonly directives?: Meta["directives"];
+  readonly implements?: Meta["implements"];
+  readonly ignoreFields?: Meta["ignoreFields"];
+}
+
+/**
+ * Attaches metadata to a type definition.
+ * The metadata is embedded as optional properties to maintain compatibility
+ * with the underlying type.
+ *
+ * The structure uses two properties:
+ * - `$gqlkitTypeMeta`: Contains the metadata object with directives, implements, and ignoreFields
+ * - `$gqlkitOriginalType`: Preserves the original type T to maintain nullability information
+ *
+ * @typeParam T - The base type to attach metadata to
+ * @typeParam Meta - The metadata configuration object containing directives, implements, and/or ignoreFields
+ *
+ * @example
+ * ```typescript
+ * // Type with directives only
+ * type User = GqlObject<
+ *   {
+ *     id: string;
+ *     name: string;
+ *   },
+ *   { directives: [CacheDirective<{ maxAge: 60 }>] }
+ * >;
+ *
+ * // Type implementing an interface
+ * type User = GqlObject<
+ *   {
+ *     id: IDString;
+ *     name: string;
+ *   },
+ *   { implements: [Node] }
+ * >;
+ *
+ * // Type with both directives and implements
+ * type Post = GqlObject<
+ *   {
+ *     id: IDString;
+ *     title: string;
+ *     createdAt: DateTime;
+ *   },
+ *   {
+ *     implements: [Node, Timestamped],
+ *     directives: [CacheDirective<{ maxAge: 60 }>]
+ *   }
+ * >;
+ *
+ * // Type with ignoreFields to exclude fields from GraphQL schema
+ * type User = GqlObject<
+ *   {
+ *     id: IDString;
+ *     name: string;
+ *     internalId: string;
+ *   },
+ *   { ignoreFields: "internalId" }
+ * >;
+ *
+ * // Type with multiple ignored fields
+ * type User = GqlObject<
+ *   {
+ *     id: IDString;
+ *     name: string;
+ *     cacheKey: string;
+ *     internalId: string;
+ *   },
+ *   { ignoreFields: "cacheKey" | "internalId" }
+ * >;
+ * ```
+ */
+export type GqlObject<
+  T,
+  Meta extends {
+    directives?: ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    >;
+    implements?: ReadonlyArray<GqlInterfaceMarker>;
+    ignoreFields?: keyof T & string;
+  } = { directives: [] },
+> = T & {
+  readonly " $gqlkitTypeMeta"?: GqlTypeMetaShape<Meta>;
+  readonly " $gqlkitOriginalType"?: T;
+};
+
+/**
+ * Scalar metadata structure embedded in intersection types.
+ * Used by CLI to detect and identify scalar types through type analysis.
+ *
+ * @example
+ * ```typescript
+ * // A type with scalar metadata
+ * type MyScalar = Base & { " $gqlkitScalar"?: ScalarMetadataShape };
+ * ```
+ */
+export interface ScalarMetadataShape {
+  readonly name: string;
+  readonly only?: "input" | "output";
+}
+
+/**
+ * Utility type for defining custom scalar types with metadata.
+ * The metadata is embedded as an optional property to maintain compatibility
+ * with the underlying base type.
+ *
+ * @typeParam Name - The GraphQL scalar name
+ * @typeParam Base - The underlying TypeScript type
+ * @typeParam Only - Usage constraint: "input" for input-only, "output" for output-only, undefined for both
+ *
+ * @example
+ * ```typescript
+ * // Basic custom scalar
+ * type DateTime = GqlScalar<"DateTime", Date>;
+ *
+ * // Input-only scalar
+ * type DateTimeInput = GqlScalar<"DateTime", Date, "input">;
+ *
+ * // Output-only scalar (can accept multiple base types)
+ * type DateTimeOutput = GqlScalar<"DateTime", Date | string, "output">;
+ * ```
+ */
+export type GqlScalar<
+  Name extends string,
+  Base,
+  Only extends "input" | "output" | undefined = undefined,
+> = Base & {
+  " $gqlkitScalar"?: {
+    name: Name;
+    only: Only;
+  };
+};
+
+/**
+ * GraphQL Int scalar type.
+ * Use this to explicitly mark a field as an integer.
+ * Includes metadata for CLI detection.
+ */
+export type Int = GqlScalar<"Int", number>;
+
+/**
+ * GraphQL Float scalar type.
+ * Use this to explicitly mark a field as a floating-point number.
+ * Note: Plain `number` type will also map to Float by default.
+ * Includes metadata for CLI detection.
+ */
+export type Float = GqlScalar<"Float", number>;
+
+/**
+ * GraphQL ID scalar type (string-based).
+ * Use this when the ID is represented as a string in your system.
+ * Includes metadata for CLI detection.
+ */
+export type IDString = GqlScalar<"ID", string>;
+
+/**
+ * GraphQL ID scalar type (number-based).
+ * Use this when the ID is represented as a number in your system.
+ * Includes metadata for CLI detection.
+ */
+export type IDNumber = GqlScalar<"ID", number>;
+
+/**
+ * Type alias representing no arguments for a resolver.
+ * Use this when defining resolvers that don't accept any arguments.
+ */
+export type NoArgs = Record<string, never>;
+
+/**
+ * Type for Query resolver functions.
+ * @typeParam TArgs - The type of arguments the resolver accepts
+ * @typeParam TResult - The return type of the resolver
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type QueryResolverFn<TArgs, TResult, TContext = unknown> = (
+  root: undefined,
+  args: TArgs,
+  context: TContext,
+  info: GraphQLResolveInfo,
+) => TResult | Promise<TResult>;
+
+/**
+ * Type for Mutation resolver functions.
+ * @typeParam TArgs - The type of arguments the resolver accepts
+ * @typeParam TResult - The return type of the resolver
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type MutationResolverFn<TArgs, TResult, TContext = unknown> = (
+  root: undefined,
+  args: TArgs,
+  context: TContext,
+  info: GraphQLResolveInfo,
+) => TResult | Promise<TResult>;
+
+/**
+ * Type for Field resolver functions.
+ * @typeParam TParent - The parent type this field belongs to
+ * @typeParam TArgs - The type of arguments the resolver accepts
+ * @typeParam TResult - The return type of the resolver
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type FieldResolverFn<TParent, TArgs, TResult, TContext = unknown> = (
+  parent: TParent,
+  args: TArgs,
+  context: TContext,
+  info: GraphQLResolveInfo,
+) => TResult | Promise<TResult>;
+
+/**
+ * The kind of resolver.
+ */
+export type ResolverKind = "query" | "mutation" | "field";
+
+/**
+ * The kind of abstract type resolver.
+ */
+export type AbstractResolverKind = "resolveType" | "isTypeOf";
+
+/**
+ * Type for resolveType resolver functions.
+ * Used to resolve the concrete type of a union or interface type at runtime.
+ * @typeParam TAbstract - The abstract type (union or interface) to resolve
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type ResolveTypeResolverFn<TAbstract, TContext = unknown> = (
+  value: TAbstract,
+  context: TContext,
+  info: GraphQLResolveInfo,
+) => string | Promise<string>;
+
+/**
+ * Type for isTypeOf resolver functions.
+ * Used to check if a value belongs to a specific object type.
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type IsTypeOfResolverFn<TContext = unknown> = (
+  value: unknown,
+  context: TContext,
+  info: GraphQLResolveInfo,
+) => boolean | Promise<boolean>;
+
+/**
+ * Abstract type resolver metadata structure embedded in intersection types.
+ * Used by CLI to detect and identify abstract type resolvers through type analysis.
+ */
+export interface AbstractResolverMetadataShape {
+  readonly kind: AbstractResolverKind;
+  readonly targetType: unknown;
+}
+
+/**
+ * resolveType resolver type with metadata.
+ * The metadata is embedded as an optional property with space-prefixed key
+ * to avoid collision with user-defined properties.
+ * @typeParam TAbstract - The abstract type (union or interface) to resolve
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type ResolveTypeResolver<
+  TAbstract,
+  TContext = unknown,
+> = ResolveTypeResolverFn<TAbstract, TContext> & {
+  " $gqlkitAbstractResolver"?: {
+    kind: "resolveType";
+    targetType: TAbstract;
+  };
+};
+
+/**
+ * isTypeOf resolver type with metadata.
+ * The metadata is embedded as an optional property with space-prefixed key
+ * to avoid collision with user-defined properties.
+ * @typeParam TObject - The object type to check
+ * @typeParam TContext - The context type (defaults to unknown)
+ */
+export type IsTypeOfResolver<
+  TObject,
+  TContext = unknown,
+> = IsTypeOfResolverFn<TContext> & {
+  " $gqlkitAbstractResolver"?: {
+    kind: "isTypeOf";
+    targetType: TObject;
+  };
+};
+
+/**
+ * Resolver metadata structure embedded in intersection types.
+ * Used by CLI to detect and identify resolver types through type analysis.
+ */
+export interface ResolverMetadataShape {
+  readonly kind: ResolverKind;
+  readonly args: unknown;
+  readonly result: unknown;
+  readonly parent?: unknown;
+}
+
+/**
+ * Query resolver type with metadata.
+ * The metadata is embedded as an optional property with space-prefixed key
+ * to avoid collision with user-defined properties.
+ * @typeParam TArgs - The type of arguments the resolver accepts
+ * @typeParam TResult - The return type of the resolver
+ * @typeParam TContext - The context type (defaults to unknown)
+ * @typeParam TDirectives - Array of directives to attach to this field (defaults to [])
+ */
+export type QueryResolver<
+  TArgs,
+  TResult,
+  TContext = unknown,
+  TDirectives extends ReadonlyArray<
+    GqlDirective<
+      string,
+      Record<string, unknown>,
+      DirectiveLocation | DirectiveLocation[]
+    >
+  > = [],
+> = QueryResolverFn<TArgs, TResult, TContext> & {
+  " $gqlkitResolver"?: {
+    kind: "query";
+    args: TArgs;
+    result: TResult;
+    directives: TDirectives;
+  };
+};
+
+/**
+ * Mutation resolver type with metadata.
+ * The metadata is embedded as an optional property with space-prefixed key
+ * to avoid collision with user-defined properties.
+ * @typeParam TArgs - The type of arguments the resolver accepts
+ * @typeParam TResult - The return type of the resolver
+ * @typeParam TContext - The context type (defaults to unknown)
+ * @typeParam TDirectives - Array of directives to attach to this field (defaults to [])
+ */
+export type MutationResolver<
+  TArgs,
+  TResult,
+  TContext = unknown,
+  TDirectives extends ReadonlyArray<
+    GqlDirective<
+      string,
+      Record<string, unknown>,
+      DirectiveLocation | DirectiveLocation[]
+    >
+  > = [],
+> = MutationResolverFn<TArgs, TResult, TContext> & {
+  " $gqlkitResolver"?: {
+    kind: "mutation";
+    args: TArgs;
+    result: TResult;
+    directives: TDirectives;
+  };
+};
+
+/**
+ * Field resolver type with metadata.
+ * The metadata is embedded as an optional property with space-prefixed key
+ * to avoid collision with user-defined properties.
+ * @typeParam TParent - The parent type this field belongs to
+ * @typeParam TArgs - The type of arguments the resolver accepts
+ * @typeParam TResult - The return type of the resolver
+ * @typeParam TContext - The context type (defaults to unknown)
+ * @typeParam TDirectives - Array of directives to attach to this field (defaults to [])
+ */
+export type FieldResolver<
+  TParent,
+  TArgs,
+  TResult,
+  TContext = unknown,
+  TDirectives extends ReadonlyArray<
+    GqlDirective<
+      string,
+      Record<string, unknown>,
+      DirectiveLocation | DirectiveLocation[]
+    >
+  > = [],
+> = FieldResolverFn<TParent, TArgs, TResult, TContext> & {
+  " $gqlkitResolver"?: {
+    kind: "field";
+    parent: TParent;
+    args: TArgs;
+    result: TResult;
+    directives: TDirectives;
+  };
+};
+
+/**
+ * The API set returned by createGqlkitApis.
+ * Contains typed define functions for Query, Mutation, and Field resolvers.
+ * @typeParam TContext - The context type for all resolvers in this API set
+ */
+export interface GqlkitApis<TContext> {
+  /**
+   * Defines a Query field resolver with the specified Context type.
+   * @typeParam TArgs - The type of arguments the resolver accepts
+   * @typeParam TResult - The return type of the resolver
+   * @typeParam TDirectives - Array of directives to attach to this field (defaults to [])
+   * @param resolver - The resolver function
+   * @returns The resolver with metadata for CLI detection
+   *
+   * @example
+   * ```typescript
+   * // Without directives
+   * export const users = defineQuery<NoArgs, User[]>(() => []);
+   *
+   * // With directives
+   * export const me = defineQuery<NoArgs, User, [AuthDirective<{ role: ["USER"] }>]>(
+   *   (root, args, ctx) => ctx.currentUser
+   * );
+   * ```
+   */
+  defineQuery: <
+    TArgs,
+    TResult,
+    TDirectives extends ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    > = [],
+  >(
+    resolver: QueryResolverFn<TArgs, TResult, TContext>,
+  ) => QueryResolver<TArgs, TResult, TContext, TDirectives>;
+
+  /**
+   * Defines a Mutation field resolver with the specified Context type.
+   * @typeParam TArgs - The type of arguments the resolver accepts
+   * @typeParam TResult - The return type of the resolver
+   * @typeParam TDirectives - Array of directives to attach to this field (defaults to [])
+   * @param resolver - The resolver function
+   * @returns The resolver with metadata for CLI detection
+   *
+   * @example
+   * ```typescript
+   * // Without directives
+   * export const createUser = defineMutation<CreateUserInput, User>((root, args) => ({ ... }));
+   *
+   * // With directives
+   * export const deleteUser = defineMutation<{ id: string }, boolean, [AuthDirective<{ role: ["ADMIN"] }>]>(
+   *   (root, args, ctx) => true
+   * );
+   * ```
+   */
+  defineMutation: <
+    TArgs,
+    TResult,
+    TDirectives extends ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    > = [],
+  >(
+    resolver: MutationResolverFn<TArgs, TResult, TContext>,
+  ) => MutationResolver<TArgs, TResult, TContext, TDirectives>;
+
+  /**
+   * Defines an object type field resolver with the specified Context type.
+   * @typeParam TParent - The parent type this field belongs to
+   * @typeParam TArgs - The type of arguments the resolver accepts
+   * @typeParam TResult - The return type of the resolver
+   * @typeParam TDirectives - Array of directives to attach to this field (defaults to [])
+   * @param resolver - The resolver function
+   * @returns The resolver with metadata for CLI detection
+   *
+   * @example
+   * ```typescript
+   * // Without directives
+   * export const userPosts = defineField<User, NoArgs, Post[]>((parent) => []);
+   *
+   * // With directives
+   * export const userEmail = defineField<User, NoArgs, string, [AuthDirective<{ role: ["ADMIN"] }>]>(
+   *   (parent) => parent.email
+   * );
+   * ```
+   */
+  defineField: <
+    TParent,
+    TArgs,
+    TResult,
+    TDirectives extends ReadonlyArray<
+      GqlDirective<
+        string,
+        Record<string, unknown>,
+        DirectiveLocation | DirectiveLocation[]
+      >
+    > = [],
+  >(
+    resolver: FieldResolverFn<TParent, TArgs, TResult, TContext>,
+  ) => FieldResolver<TParent, TArgs, TResult, TContext, TDirectives>;
+
+  /**
+   * Defines a resolveType resolver for union or interface types.
+   * Used to determine the concrete type of an abstract type at runtime.
+   * @typeParam TAbstract - The abstract type (union or interface) to resolve
+   * @param resolver - The resolver function that returns the concrete type name
+   * @returns The resolver with metadata for CLI detection
+   *
+   * @example
+   * ```typescript
+   * type Animal = Dog | Cat;
+   *
+   * export const animalResolveType = defineResolveType<Animal>((value) => {
+   *   return value.kind === "dog" ? "Dog" : "Cat";
+   * });
+   * ```
+   */
+  defineResolveType: <TAbstract>(
+    resolver: ResolveTypeResolverFn<TAbstract, TContext>,
+  ) => ResolveTypeResolver<TAbstract, TContext>;
+
+  /**
+   * Defines an isTypeOf resolver for object types.
+   * Used to check if a value belongs to a specific object type.
+   * @typeParam TObject - The object type to check
+   * @param resolver - The resolver function that returns true if the value is of this type
+   * @returns The resolver with metadata for CLI detection
+   *
+   * @example
+   * ```typescript
+   * export const dogIsTypeOf = defineIsTypeOf<Dog>((value) => {
+   *   return typeof value === "object" && value !== null && "kind" in value && value.kind === "dog";
+   * });
+   * ```
+   */
+  defineIsTypeOf: <TObject>(
+    resolver: IsTypeOfResolverFn<TContext>,
+  ) => IsTypeOfResolver<TObject, TContext>;
+}
+
+/**
+ * Creates a set of typed define functions for GraphQL resolvers.
+ * Use this factory to create API sets with custom Context types.
+ *
+ * @typeParam TContext - The context type for all resolvers (defaults to unknown)
+ * @returns An object containing defineQuery, defineMutation, and defineField functions
+ *
+ * @example
+ * ```typescript
+ * type MyContext = { userId: string; db: Database };
+ *
+ * const { defineQuery, defineMutation, defineField } = createGqlkitApis<MyContext>();
+ *
+ * export const me = defineQuery<NoArgs, User>(
+ *   (root, args, ctx, info) => ctx.db.findUser(ctx.userId)
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple schemas with different contexts
+ * type AdminContext = { adminId: string };
+ * type PublicContext = { sessionId: string };
+ *
+ * const adminApis = createGqlkitApis<AdminContext>();
+ * const publicApis = createGqlkitApis<PublicContext>();
+ * ```
+ */
+export function createGqlkitApis<TContext = unknown>(): GqlkitApis<TContext> {
+  const apis = {
+    defineQuery: <TArgs, TResult>(
+      resolver: QueryResolverFn<TArgs, TResult, TContext>,
+    ) => {
+      return resolver;
+    },
+    defineMutation: <TArgs, TResult>(
+      resolver: MutationResolverFn<TArgs, TResult, TContext>,
+    ) => {
+      return resolver;
+    },
+    defineField: <TParent, TArgs, TResult>(
+      resolver: FieldResolverFn<TParent, TArgs, TResult, TContext>,
+    ) => {
+      return resolver;
+    },
+    defineResolveType: <TAbstract>(
+      resolver: ResolveTypeResolverFn<TAbstract, TContext>,
+    ) => {
+      return resolver;
+    },
+    defineIsTypeOf: (resolver: IsTypeOfResolverFn<TContext>) => {
+      return resolver;
+    },
+  };
+  return apis as unknown as GqlkitApis<TContext>;
+}