The best way to control Claude Code, Codex and more from any computer or phone
| 1 | /** |
| 2 | * Generates typed GraphQL modules and diagnostics without writing to disk. |
| 3 | * The CLI uses {@link generate} to write, check or watch the output. |
| 4 | * |
| 5 | * @since 4.0.0 |
| 6 | */ |
| 7 | import type * as Effect from "effect/Effect" |
| 8 | import type * as FileSystem from "effect/FileSystem" |
| 9 | import type * as Path from "effect/Path" |
| 10 | import type { PlatformError } from "effect/PlatformError" |
| 11 | import type { Config } from "./Config.ts" |
| 12 | import * as Generate from "./internal/Generate.ts" |
| 13 | |
| 14 | /** |
| 15 | * A generated file: an absolute path and the full contents to write there. |
| 16 | * |
| 17 | * @stability experimental |
| 18 | * @category models |
| 19 | * @since 4.0.0 |
| 20 | */ |
| 21 | export interface GeneratedFile { |
| 22 | readonly path: string |
| 23 | readonly contents: string |
| 24 | } |
| 25 | |
| 26 | /** |
| 27 | * A problem found while generating. |
| 28 | * |
| 29 | * - `path` is relative to the `cwd` passed to {@link generate}, with `/` |
| 30 | * separators. |
| 31 | * - `line` and `column` are 1-based. They, and `codeFrame`, are `undefined` |
| 32 | * for diagnostics about the run as a whole, such as the unmapped-scalars |
| 33 | * warning, which is reported against the schema file. |
| 34 | * - Any `"error"` means the output must not be written. Warnings don't stop |
| 35 | * generation. |
| 36 | * |
| 37 | * @stability experimental |
| 38 | * @category models |
| 39 | * @since 4.0.0 |
| 40 | */ |
| 41 | export interface Diagnostic { |
| 42 | readonly severity: "error" | "warning" |
| 43 | readonly path: string |
| 44 | readonly line: number | undefined |
| 45 | readonly column: number | undefined |
| 46 | readonly message: string |
| 47 | readonly codeFrame: string | undefined |
| 48 | } |
| 49 | |
| 50 | /** |
| 51 | * The result of {@link generate}. `files` and `deletes` are empty when |
| 52 | * `diagnostics` holds an error. |
| 53 | * |
| 54 | * `deletes` lists stale `*.graphql.ts` and `*.gql.ts` files by absolute path. |
| 55 | * A file qualifies only under a `documents` glob root, with a generator |
| 56 | * header naming a missing sibling source, and when absent from `files`. |
| 57 | * Shared modules and files without a matching document header are excluded. |
| 58 | * |
| 59 | * @stability experimental |
| 60 | * @category models |
| 61 | * @since 4.0.0 |
| 62 | */ |
| 63 | export interface GenerateResult { |
| 64 | readonly files: ReadonlyArray<GeneratedFile> |
| 65 | readonly deletes: ReadonlyArray<string> |
| 66 | readonly diagnostics: ReadonlyArray<Diagnostic> |
| 67 | } |
| 68 | |
| 69 | /** |
| 70 | * The config cannot be used with this schema, e.g. a `scalars` key that |
| 71 | * isn't a custom scalar or a built-in `Int`, `Float` or `ID`, or an absolute |
| 72 | * `documents` pattern. |
| 73 | * |
| 74 | * @stability experimental |
| 75 | * @category errors |
| 76 | * @since 4.0.0 |
| 77 | */ |
| 78 | export { ConfigError } from "./internal/Generate.ts" |
| 79 | |
| 80 | /** |
| 81 | * Generates the `.graphql.ts` module for every document file and the shared |
| 82 | * module, in memory. |
| 83 | * |
| 84 | * **Details** |
| 85 | * |
| 86 | * - Relative paths in the config, and the `documents` globs, resolve against |
| 87 | * `options.cwd`, which is normally the config file's directory. |
| 88 | * - `foo.graphql` generates `foo.graphql.ts` next to it, and `foo.gql` |
| 89 | * generates `foo.gql.ts`. |
| 90 | * - The shared module goes to `config.shared`, or next to the schema as |
| 91 | * `<schema name>.graphql.ts`, and holds only the scalars, enums, input |
| 92 | * objects and possible `__typename` unions the operations reach. A `shared` |
| 93 | * path equal to the schema, a document or a document's output is an error |
| 94 | * diagnostic. |
| 95 | * - Entries under a glob root that can't be read, such as dangling symlinks, |
| 96 | * are skipped. |
| 97 | * - Custom scalars named `DateTime` and `URI` default to |
| 98 | * `Schema.DateTimeUtcFromString` and `Schema.String`. Configured `scalars` |
| 99 | * override these defaults. Other unmapped custom scalars decode as |
| 100 | * `Schema.Json`, and one warning lists every one the operations reach. |
| 101 | * - A selection on an interface or union decodes as a `Schema.Union` |
| 102 | * discriminated by `__typename`, which is added to the document. Types the |
| 103 | * selection doesn't name, including ones the server adds later, fall into |
| 104 | * a last member built with `GraphQL.otherTypename`. |
| 105 | * - `@skip` / `@include` with a variable condition make the fields they cover |
| 106 | * optional keys; literal conditions are folded. |
| 107 | * - Input objects on a cycle, such as filters with `and` / `or`, are |
| 108 | * `Schema.Codec` consts annotated with written-out Type and Encoded |
| 109 | * interfaces, and reference the cycle through `Schema.suspend`. |
| 110 | * |
| 111 | * @stability experimental |
| 112 | * @category generation |
| 113 | * @since 4.0.0 |
| 114 | */ |
| 115 | export const generate: ( |
| 116 | config: Config, |
| 117 | options: { readonly cwd: string } |
| 118 | ) => Effect.Effect<GenerateResult, Generate.ConfigError | PlatformError, FileSystem.FileSystem | Path.Path> = ( |
| 119 | config, |
| 120 | options |
| 121 | ) => Generate.generate(config, { cwd: options.cwd }) |