{"_id":"@alexkirsz/graphql-typescript-definitions","_rev":"1-94fb866e2fd25485402e228a2f1aac17","name":"@alexkirsz/graphql-typescript-definitions","dist-tags":{"latest":"0.16.0"},"versions":{"0.16.0":{"name":"@alexkirsz/graphql-typescript-definitions","version":"0.16.0","main":"lib/index.js","types":"lib","description":"Generate TypeScript definition files from .graphql documents","license":"MIT","publishConfig":{"access":"public","@shopify:registry":"https://registry.npmjs.org"},"bin":{"graphql-typescript-definitions":"./bin/graphql-typescript-definitions"},"author":{"name":"Shopify Inc."},"repository":{"type":"git","url":"git+https://github.com/Shopify/graphql-tools-web.git"},"bugs":{"url":"https://github.com/shopify/graphql-tools-web/issues"},"homepage":"https://github.com/shopify/graphql-tools-web/blob/master/packages/graphql-typescript-definitions","scripts":{"build":"tsc","pretest":"yarn build","prepublishOnly":"yarn build"},"devDependencies":{"@types/chalk":"^2.2.0","@types/common-tags":"^1.4.0","common-tags":"^1.7.2","ts-node":"^6.0.2","typescript":"^2.8.3"},"dependencies":{"@babel/generator":"^7.0.0-beta.46","@babel/types":"^7.0.0-beta.46","@types/babel-generator":"^6.25.1","@types/chokidar":"^1.7.0","chalk":"^2.4.1","change-case":"^3.0.1","chokidar":"^2.0.3","fs-extra":"^6.0.0","glob":"^7.1.2","graphql-tool-utilities":"^0.9.1"},"peerDependencies":{"graphql-typed":"^0.2.0"},"_id":"@alexkirsz/graphql-typescript-definitions@0.16.0","dist":{"shasum":"98f4619a5d38136b8d8f7932f0668348fd0752eb","tarball":"https://registry.npmjs.org/@alexkirsz/graphql-typescript-definitions/-/graphql-typescript-definitions-0.16.0.tgz","integrity":"sha512-2Lumvw/vh5276uDeSuoXf8xMUTaDenQJshcFwRNdioUiUFRj6yUtaYULEdnog1hDr8L5iH+lSucnLIwKAjwUhQ==","fileCount":30,"unpackedSize":61335,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJcf8/iCRA9TVsSAnZWagAA6BAP/iYL9Sh9oZs3ALyBbA1l\njN7mXmb7Nbv3zn1WEL22naTz7FHAysE4bdJHkkfyGaZFeY4FKoPZ1jOgvAes\nXuwENXkuajcTI9CM0E/gs05aPeF6LfZP3AyxjkzFGjitIVk5ERX3owFa6elO\ng0ns4gHEOBGWoxqE2SVEbB3rMrGp3og8SQW3ibc5q0Q+x3ob/XsJq/3SPwym\n79tc63lOyS6hfII3uIaKRm4YpfY5NXQ50vLl5mxd+LQeuzZ/WsTZXEcA5HMv\nA8h5pRbtFHwRIhfXrPJCEbyCeKlPrOObQTQvyNkPMI/ybz00qdj8IyfggSjZ\nEjDLqF598gdknvWzoCPoX5bwnCxo9ndg8bg1E/N/teRz3+J0qSXxrebFKZVh\nOVI0OdDuMuANPWzqline6Y0UVfSjz97mPcwva43I56L9jYxhBtEDqOQEPS6u\nyHDn1CXD5/1lkH23542EaHoU7Gmbgezc5ndp70dD7UX0Ta9U+Kg1PoWAr9Co\nVwQqShcV+WpvXJ1UwC7bFI3G8n+9P9dhrrfgz7K8iUqVGEgcqBZ/8QTUvgB3\n9CQf+a6hP5mYozU+Fa8rtU12X4NNOO1wo8TKSLQI/m1uKZ1FItPLk4rwk01c\nlYgHWgBdvgV1f4oNX+wwHfCv/G8VMoPr+OxnPapsHpuXuCl0g11kKIAEjrPb\nPnLp\r\n=drLC\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCSp9mqwO/REUf7njqHXOARF4J0EbavUY439yVzuHk27QIhAKL3y/0ywow/aShrXW+PFTbkIMMB2WREPtiCSlp2q/I1"}]},"maintainers":[{"name":"alexkirsz","email":"a.kirszenberg@gmail.com"}],"_npmUser":{"name":"alexkirsz","email":"a.kirszenberg@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/graphql-typescript-definitions_0.16.0_1551880162137_0.19901408780575558"},"_hasShrinkwrap":false}},"time":{"created":"2019-03-06T13:49:21.945Z","0.16.0":"2019-03-06T13:49:22.320Z","modified":"2022-04-04T12:40:58.470Z"},"maintainers":[{"name":"alexkirsz","email":"a.kirszenberg@gmail.com"}],"description":"Generate TypeScript definition files from .graphql documents","homepage":"https://github.com/shopify/graphql-tools-web/blob/master/packages/graphql-typescript-definitions","repository":{"type":"git","url":"git+https://github.com/Shopify/graphql-tools-web.git"},"author":{"name":"Shopify Inc."},"bugs":{"url":"https://github.com/shopify/graphql-tools-web/issues"},"license":"MIT","readme":"# `graphql-typescript-definitions`\n\n> Generate TypeScript definition files from .graphql documents\n\n## Installation\n\n```\nnpm install graphql-typescript-definitions --save-dev\n```\n\nor, with Yarn:\n\n```\nyarn add graphql-typescript-definitions --dev\n```\n\n## Usage\n\nThis package will generate matching `.d.ts` files for each `.graphql` file you specify. It will generate types in the following format:\n\n* A default export for the type that will be generated by a GraphQL loader (GraphQL’s `DocumentNode` type, but augmented as `graphql-typed`’s `DocumentNode` which includes additional type details about the operation).\n\n* An interface for each query, mutation, and fragment, named `<OpertionName><Query | Mutation | Fragment>Data`. For example, `query Home {}` becomes `export interface HomeQueryData {}`.\n\n* A namespace for each operation that includes any nested types. Nested types are named in pascal case using their keypath from the root of the operation. For example, if we imagine the following GraphQL schema (using the [GraphQL IDL](https://www.graph.cool/docs/faq/graphql-idl-schema-definition-language-kr84dktnp0/)):\n\n  ```graphql\n  type Person {\n    name: String!\n    relatives: [Person!]!\n  }\n\n  type Query {\n    person: Person\n  }\n  ```\n\n  and the following query:\n\n  ```graphql\n  query Someone {\n    person {\n      name\n      relatives {\n        name\n      }\n    }\n  }\n  ```\n\n  The following exports would be generated:\n\n  ```typescript\n  export interface SomeoneQueryData {\n    person?: SomeoneQueryData.Person | null;\n  }\n\n  export namespace SomeoneQueryData {\n    export interface Person {\n      name: string;\n      relatives: SomeoneQueryData.PersonRelatives[];\n    }\n\n    export interface PersonRelatives {\n      name: string;\n    }\n  }\n  ```\n\n  This allows you to use the full query’s type, as well as any of the subtypes that make up that query type. This is particularly useful for list or nullable types, where you can directly the access the underlying type without any additional help from TypeScript:\n\n  ```typescript\n  import someoneQueryDocument, {SomeoneQueryData} from './Someone.graphql';\n\n  let data: SomeoneQueryData;\n  let person: SomeoneQueryData.Person;\n  ```\n\n### Operation\n\nOn startup this tool performs the following actions:\n\n* Loads all schemas\n* Extracts all enums, input objects, and custom scalars as schema types\n* Writes the schema types to `types.ts` (or `${projectName}-types.ts` for named projects)\n  * Written in directory provided by `--schema-types-path` argument\n  * Override `--schema-types-path` per project with the `schemaTypesPath` extension\n\n### Configuration\n\nThis tool reads schema information from a [`.graphqlconfig`](https://github.com/Shopify/graphql-tools-web/tree/master/packages/graphql-tool-utilities#configuration) file in the project root.\n\n#### Examples\n\nA project configuration with a `schemaTypesPath` override\n\n```json\n{\n  \"schemaPath\": \"build/schema.json\",\n  \"includes\": \"app/**/*.graphql\",\n  \"extensions\": {\n    \"schemaTypesPath\": \"app/bar/types/graphql\"\n  }\n}\n```\n\n### Type Generation\n\n#### Nullability\n\nAs demonstrated in the root `person` field in the example above, nullable fields are represented as optional types, in a union with `null`. Nullable items in list fields (i.e., `[Person]!`) are represented as a union type with `null`.\n\n#### Interfaces and Unions\n\nInterface an union fields are represented as union types in cases where there are spreads that could result in different fields on different concrete types. The type names for these cases are named the same as the default naming (pascal case version of the keypath for the field), but with the type condition appended to the end. All cases not covered by fragments are extracted into a type with a postpended `Other` name.\n\n```graphql\n# Schema\ninterface Named {\n  name: String!\n}\n\ntype Person implements Named {\n  name: String!\n  occupation: String\n}\n\ntype Dog implements Named {\n  name: String!\n  legs: Int!\n}\n\ntype Cat implements Named {\n  name: String!\n  livesLeft: Int!\n}\n\ntype Horse implements Named {\n  name: String!\n  topSpeed: Float!\n}\n\ntype Query {\n  named: Named\n}\n```\n\n```graphql\n# Query\nquery SomeNamed {\n  named {\n    name\n    ... on Person {\n      occupation\n    }\n    ... on Dog {\n      legs\n    }\n  }\n}\n```\n\n```typescript\n// generated types\nexport interface SomeNamedData {\n  named?:\n    | SomeNamedData.NamedPerson\n    | SomeNamedData.NamedDog\n    | SomeNamedData.NamedOther\n    | null;\n}\n\nexport namespace SomeNamedData {\n  export interface NamedPerson {\n    __typename: 'Person';\n    name: string;\n    occupation?: string | null;\n  }\n  export interface NamedDog {\n    __typename: 'Dog';\n    name: string;\n    legs: number;\n  }\n  export interface NamedOther {\n    __typename: 'Cat' | 'Horse';\n    name: string;\n  }\n}\n```\n\nNote that the above example assumes that you specify the `--add-typename` argument. These types are only useful when a typename is included either explicitly or with this argument, as otherwise there is no simple way for TypeScript to disambiguate the union type.\n\n#### Schema Types\n\nInput types (enums, input objects, and custom scalars) are generated once, in a central location, and imported within each typing file. You can use these definitions to reference the schema types in other application code as well; in particular, GraphQL enums are turned into corresponding TypeScript `enum`s. The schema types directory is specified using the `--schema-types-path` argument (detailed below), and the format for the generated enums can be specified using the `--enum-format` option.\n\n### CLI\n\n```sh\ngraphql-typescript-definitions --schema-types-path app/types\n```\n\nAs noted above, the configuration of your schema and GraphQL documents is done via a `.graphqlconfig` file, as this allows configuration to shared between tools. The CLI does support a few additional options, though:\n\n* `--schema-types-path`: specifies a directory to write schema types (**REQUIRED**)\n* `--watch`: watches the include globbing patterns for changes and re-processes files (default = `false`)\n* `--cwd`: run tool for `.graphqlconfig` located in this directory (default = `process.cwd()`)\n* `--add-typename`: adds a `__typename` field to every object type (default = `true`)\n* `--enum-format`: specifies output format for enum types (default = `undefined`)\n  * Options: `camel-case`, `pascal-case`, `snake-case`, `screaming-snake-case`\n  * `undefined` results in using the unchanged name from the schema (verbatim)\n* `--custom-scalars`: specifies custom types to use in place of scalar types in your GraphQL schema. See below for details.\n\n#### Examples\n\n```sh\n# run tool for .graphqlconfig in current directory, produces ./app/graphql/types\ngraphql-typescript-definitions --schema-types-path app/graphql/types\n\n# run watcher for .graphqlconfig in current directory, produces ./app/graphql/types\ngraphql-typescript-definitions --schema-types-path app/graphql/types --watch\n\n# run tool for .graphqlconfig in a child directory, produces ./src/app/graphql/types\ngraphql-typescript-definitions --cwd src --schema-types-path app/graphql/types\n```\n\n#### `--custom-scalars`\n\nBy default, all custom scalars are exported as an alias for `string`. You can export a different type for these scalars by passing in a `--custom-scalars` option. This option is a JSON-serialized object that specifies what custom type to import from a package and re-export as the type for that scalar. For example, assuming the following schema:\n\n```graphql\nscalar HtmlString\n```\n\nYou may want a custom TypeScript type for any field of this GraphQL type (for example, to restrict functions to use only this type, and not any arbitrary string). Assuming you have an installed npm package by the name of `my-custom-type-package`, and this package exports a named `SafeString` type, you could pass the following `--custom-scalars` option:\n\n```sh\nyarn run graphql-typescript-definitions --schema-path 'build/schema.json' --schema-types-path 'src/schema' --custom-scalars '{\"HtmlString\": {\"name\": \"SafeString\", package: \"my-custom-type-package\"}}'\n```\n\nWith this configuration, your custom scalar would be exported roughly as follows:\n\n```ts\nimport {SafeString} from 'my-custom-type-package';\nexport type HtmlString = SafeString;\n```\n\n### Node\n\n```js\nconst {Builder} = require('graphql-typescript-definitions');\n\nconst builder = new Builder({\n  schemaTypesPath: 'app/graphql/types',\n});\n\nbuilder.on('build', (build) => {\n  // See the source file for details on the shape of the object returned here\n  console.log(build);\n});\n\nbuilder.on('error', (error) => {\n  console.error(error);\n});\n\n// Optionally, you can pass {watch: true} here to re-run on changes\nbuilder.run();\n```\n\nAs with the CLI, you can pass options to customize the build and behavior:\n\n* `watch`\n* `enumFormat` (use the exported `EnumFormat` enum)\n* `graphQLFiles`\n* `schemaPath`\n* `schemaTypesPath`\n* `customScalars`\n* `config` (custom `GraphQLConfig` instance)\n","readmeFilename":"README.md"}