TypeScript MongoDB

Package name	Weekly Downloads	Version	License	Updated
`@graphql-codegen/typescript-mongodb`				Sep 25th, 2023

Installation

npm i @graphql-codegen/typescript-mongodb

⚠️

Don't install this plugin as devDependency, because you need to import the directives from it.

This plugin generates TypeScript types for MongoDB models, which makes it relevant for server-side development only. It uses GraphQL directives to declare the types you want to generate and use in your MongoDB backend.

What this plugin does?

Given the following GraphQL declaration:

type User @entity {
  id: String @id
  username: String! @column
  email: String @column
}

We can have the following TypeScript output:

import { ObjectId } from 'mongodb'
 
export interface UserDbObject {
  _id: ObjectId
  username: string
  email?: string | null
}

This interface can be used for db read/write purposes, thus making communication with the db much more consistent.

Config API Reference

`dbTypeSuffix`

type: string default: DbObject

Customize the suffix for the generated GraphQL types.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       // plugins...
       config: {
         dbTypeSuffix: 'MyType'
       },
     },
   },
 };
 export default config;

`dbInterfaceSuffix`

type: string default: DbObject

Customize the suffix for the generated GraphQL interfaces.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       // plugins...
       config: {
         dbInterfaceSuffix: 'MyInterface'
       },
     },
   },
 };
 export default config;

`objectIdType`

type: string default: mongodb#ObjectId

Customize the type of _id fields. You can either specify a type name, or specify module#type.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       // plugins...
       config: {
         objectIdType: './my-models.ts#MyIdType'
       },
     },
   },
 };
 export default config;

`idFieldName`

type: string default: _id

Customize the name of the id field generated after using @id directive over a GraphQL field.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       // plugins...
       config: {
         idFieldName: 'id'
       },
     },
   },
 };
 export default config;

`enumsAsString`

type: boolean default: true

Replaces generated enum values with string.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       // plugins...
       config: {
         enumsAsString: false
       },
     },
   },
 };
 export default config;

`avoidOptionals`

type: boolean default: false

This will cause the generator to avoid using TypeScript optionals (?), so the following definition: type A { myField: String } will output myField: Maybe<string> instead of myField?: Maybe<string>.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file.ts': {
       // plugins...
       config: {
         avoidOptionals: true
       },
     },
   },
 };
 export default config;

`strictScalars`

type: boolean default: false

Makes scalars strict.

If scalars are found in the schema that are not defined in scalars an error will be thrown during codegen.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         strictScalars: true,
       },
     },
   },
 };
 export default config;

`defaultScalarType`

type: string default: any

Allows you to override the type that unknown scalars will have.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         defaultScalarType: 'unknown'
       },
     },
   },
 };
 export default config;

`scalars`

type: ScalarsMap

Extends or overrides the built-in scalars and custom GraphQL scalars to a custom type.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         scalars: {
           DateTime: 'Date',
           JSON: '{ [key: string]: any }',
         }
       },
     },
   },
 };
 export default config;

`namingConvention`

type: NamingConvention default: change-case-all#pascalCase

Allow you to override the naming convention of the output. You can either override all namings, or specify an object with specific custom naming convention per output. The format of the converter must be a valid module#method. Allowed values for specific output are: typeNames, enumValues. You can also use "keep" to keep all GraphQL names as-is. Additionally, you can set transformUnderscore to true if you want to override the default behavior, which is to preserve underscores.

Available case functions in change-case-all are camelCase, capitalCase, constantCase, dotCase, headerCase, noCase, paramCase, pascalCase, pathCase, sentenceCase, snakeCase, lowerCase, localeLowerCase, lowerCaseFirst, spongeCase, titleCase, upperCase, localeUpperCase and upperCaseFirst See more

Usage Examples

Override All Names

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         namingConvention: 'change-case-all#lowerCase',
       },
     },
   },
 };
 export default config;

Upper-case enum values

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         namingConvention: {
           typeNames: 'change-case-all#pascalCase',
           enumValues: 'change-case-all#upperCase',
         }
       },
     },
   },
 };
 export default config;

Keep names as is

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
        namingConvention: 'keep',
       },
     },
   },
 };
 export default config;

Remove Underscores

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         namingConvention: {
           typeNames: 'change-case-all#pascalCase',
           transformUnderscore: true
         }
       },
     },
   },
 };
 export default config;

`typesPrefix`

type: string default: (empty)

Prefixes all the generated types.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         typesPrefix: 'I',
       },
     },
   },
 };
 export default config;

`typesSuffix`

type: string default: (empty)

Suffixes all the generated types.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         typesSuffix: 'I',
       },
     },
   },
 };
 export default config;

`skipTypename`

type: boolean default: false

Does not add __typename to the generated types, unless it was specified in the selection set.

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         skipTypename: true
       },
     },
   },
 };
 export default config;

`nonOptionalTypename`

type: boolean default: false

Automatically adds __typename field to the generated types, even when they are not specified in the selection set, and makes it non-optional

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         nonOptionalTypename: true
       },
     },
   },
 };
 export default config;

`useTypeImports`

type: boolean default: false

Will use import type {} rather than import {} when importing only types. This gives compatibility with TypeScript's "importsNotUsedAsValues": "error" option

Usage Examples

codegen.ts

 import type { CodegenConfig } from '@graphql-codegen/cli';
 
 const config: CodegenConfig = {
   // ...
   generates: {
     'path/to/file': {
       // plugins...
       config: {
         useTypeImports: true
       },
     },
   },
 };
 export default config;

`dedupeFragments`

type: boolean default: false

Removes fragment duplicates for reducing data transfer. It is done by removing sub-fragments imports from fragment definition Instead - all of them are imported to the Operation node.

`inlineFragmentTypes`

type: string default: inline

Whether fragment types should be inlined into other operations. "inline" is the default behavior and will perform deep inlining fragment types within operation type definitions. "combine" is the previous behavior that uses fragment type references without inlining the types (and might cause issues with deeply nested fragment that uses list types).

`emitLegacyCommonJSImports`

type: boolean default: true

Emit legacy common js imports. Default it will be true this way it ensure that generated code works with non-compliant bundlers.

Usage Example

Once installed, add the directives' declaration to your GraphQL Schema definition:

import { makeExecutableSchema } from '@graphql-tools/schema'
import { DIRECTIVES } from '@graphql-codegen/typescript-mongodb'
 
const schema = makeExecutableSchema({
  typeDefs: [
    DIRECTIVES
    // the rest of your GraphQL types
  ],
  resolvers
})

And generate code using gql-gen:

codegen.ts

import type { CodegenConfig } from '@graphql-codegen/cli'
 
const config: CodegenConfig = {
  schema: './src/my-schema.js',
  require: ['ts-node/register'],
  generates: {
    './src/generated/graphql.ts': {
      plugins: ['typescript', 'typescript-mongodb']
    }
  }
}
export default config

At this point, you can add the directives to your GraphQL definitions, and generate your MongoDB models file.

Directives

`@entity(additionalFields: [AdditionalEntityFields])` (on `OBJECT`)

Use this directive to specify which GraphQL type should have generated MongoDB models.

embedded: Boolean - use this option to declare target entity as child of a greater entity. For example, given the following structure { _id: string, username: string, profile: { name: string }}, the GraphQL type Profile should be declared as embedded.
additionalFields: [AdditionalEntityFields] - specify any additional fields that you would like to add to your MongoDB object, and are not a part of your public GraphQL schema.

type User
  @entity(
    additionalFields: [
      { path: "services.login.token", type: "string" }
      { path: "services.login.refreshToken?", type: "string" }
    ]
  ) {
  id: String @id
  email: String @column
}

`@column(overrideType: String)` (on `FIELD_DEFINITION`)

Use this directive to declare a specific GraphQL field as part of your generated MongoDB type.

overrideType: String - use this to override the type of the field; for example, if you store dates as Date but expose them as String.

⚠️

If target property is an embedded entity, you should use @embedded instead.

`@id` (on `FIELD_DEFINITION`)

Use this directive on the filed that should be mapped to a MongoDB _id. By default, it should be the id field of the GraphQL type.

`@link` (on `FIELD_DEFINITION`)

Use this directive to declare that a specific field is a link to another type in another table. This will use the ObjectId type in the generated result.

`@embedded` (on `FIELD_DEFINITION`)

use this option to declare target entity as child of a greater entity.

`@map(path: String)` (on `FIELD_DEFINITION`)

Use this directive to override the path or the name of the target field. This would come in handy whenever we would like to create a more complex object structure in the database; for example, if you wish to project a field as username on your schema, but store it as credentials.username in your DB. You can either specify the name of the field, or a path to which will lead to its corresponding field in the DB.

Given the following GraphQL schema:

type User @entity {
  username: String @column @map(path: "credentials.username")
}

The output should be:

export interface UserDbObject {
  credentials: {
    username: string
  }
}

`@abstractEntity(discriminatorField: String!)` (on `INTERFACE`)

Use this directive on a GraphQL interface to mark it as a basis for other database types. The discriminatorField argument is mandatory and will tell the generator what field name in the database determines what interface the target object is implementing.

For example:

interface BaseNotification @abstractEntity(discriminatorField: "notificationType") {
  id: ID! @id
  createdAt: String! @column(overrideType: "Date")
}
 
type TextNotification implements BaseNotification @entity {
  id: ID!
  createdAt: String!
  content: String! @column
}

This way, you will get:

export interface BaseNotificationDbInterface {
  notificationType: string
  _id: ObjectId
  createdAt: Date
}
 
export interface TextNotificationDbObject extends BaseNotificationDbInterface {
  content: string
}

`@union(discriminatorField: String)` (on `UNION`)

This directive is similar to @abstractEntity, but for unions (that don't necessarily have any common fields). The discriminatorField argument is mandatory and will tell the generator what field name in the database determines what interface the target object is implementing.

Given the following GraphQL schema:

type A @entity {
  fieldA: String @column
}
 
type B @entity {
  fieldB: String @column
}
 
union PossibleType @union(discriminatorField: "entityType") = A | B

The output should be:

export interface ADbObject {
  fieldA: string
}
 
export interface BDbObject {
  fieldB: string
}
 
export type PossibleType = { entityType: string } & (ADbObject | BDbObject)

Example

Given the following GraphQL types:

type User @entity {
  id: String! @id
  username: String! @column
  email: String! @column
  profile: Profile! @embedded
  friendsCount: Int! # this field won't get a generated MongoDB field
  friends: [User]! @link
}
 
type Profile @entity(embedded: true) {
  name: String! @column
  age: Int! @column
}

The generated MongoDB models should look like so:

import { ObjectId } from 'mongodb'
 
export interface UserDbObject {
  _id: ObjectId
  username: string
  email: string
  profile: ProfileDbObject
  friends: ObjectId[]
}
 
export interface ProfileDbObject {
  name: string
  age: string
}

graphql-request msw

TypeScript MongoDB

Installation

What this plugin does?

Config API Reference

dbTypeSuffix

Usage Examples

dbInterfaceSuffix

Usage Examples

objectIdType

Usage Examples

idFieldName

Usage Examples

enumsAsString

Usage Examples

avoidOptionals

Usage Examples

strictScalars

Usage Examples

defaultScalarType

Usage Examples

scalars

Usage Examples

namingConvention

Usage Examples

Override All Names

Upper-case enum values

Keep names as is

Remove Underscores

typesPrefix

Usage Examples

typesSuffix

Usage Examples

skipTypename

Usage Examples

nonOptionalTypename

Usage Examples

useTypeImports

Usage Examples

dedupeFragments

inlineFragmentTypes

emitLegacyCommonJSImports

Usage Example

Directives

@entity(additionalFields: [AdditionalEntityFields]) (on OBJECT)

@column(overrideType: String) (on FIELD_DEFINITION)

@id (on FIELD_DEFINITION)

@link (on FIELD_DEFINITION)

@embedded (on FIELD_DEFINITION)

@map(path: String) (on FIELD_DEFINITION)

@abstractEntity(discriminatorField: String!) (on INTERFACE)

@union(discriminatorField: String) (on UNION)

Example

`dbTypeSuffix`

`dbInterfaceSuffix`

`objectIdType`

`idFieldName`

`enumsAsString`

`avoidOptionals`

`strictScalars`

`defaultScalarType`

`scalars`

`namingConvention`

`typesPrefix`

`typesSuffix`

`skipTypename`

`nonOptionalTypename`

`useTypeImports`

`dedupeFragments`

`inlineFragmentTypes`

`emitLegacyCommonJSImports`

`@entity(additionalFields: [AdditionalEntityFields])` (on `OBJECT`)

`@column(overrideType: String)` (on `FIELD_DEFINITION`)

`@id` (on `FIELD_DEFINITION`)

`@link` (on `FIELD_DEFINITION`)

`@embedded` (on `FIELD_DEFINITION`)

`@map(path: String)` (on `FIELD_DEFINITION`)

`@abstractEntity(discriminatorField: String!)` (on `INTERFACE`)

`@union(discriminatorField: String)` (on `UNION`)