prisma-generator-typescript-interfaces

Prisma TypeScript Interfaces Generator

prisma-generator-typescript-interfaces - A Prisma generator that creates zero-dependency TypeScript interfaces from Prisma schema.

Motivation

While Prisma client's generated types are sufficient for most use cases, there are some scenarios where using them is not convenient or possible, due to the fact that they rely on both the @prisma/client package and on the client generated from your Prisma schema. That is where this generator comes in. It generates a zero-dependency TypeScript file containing type definitions for all your models. This file will not contain any imports and can be used standalone in any TypeScript app. By default, the definitions are type-compatible with the Prisma client types, however this can be customized via the options, see below for more info.

Usage

To use this generator, first install the package:

npm install --save-dev prisma-generator-typescript-interfaces

Next add the generator to your Prisma schema:

generator typescriptInterfaces {
  provider = "prisma-generator-typescript-interfaces"
}

And finally generate your Prisma schema:

npx prisma generate

By default, that will output the TypeScript interface definitions to a file called interfaces.ts in your prisma folder, but this can be changed by specifying the output option. As mentioned above, the generated types will, by default, be type-compatible with the Prisma client types. If you instead want to generate types matching the JSON.stringify-ed versions of your models, you will need to change some of the options, like so:

generator typescriptInterfaces {
  provider    = "prisma-generator-typescript-interfaces"
  dateType    = "string"
  bigIntType  = "string"
  decimalType = "string"
  bytesType   = "number[]"
}

Note that bigint types don't have a default toJSON method, so the above assumes that you are converting them to strings somewhere along the line. It also assumes that the Uint8Array values from Bytes fields are being converted to number[] arrays.

Example

Here is an example of a configuration that generates two separate outputs, interfaces.ts with types compatible with the Prisma client types, and a second json-interfaces.ts file with types matching the output of JSON.stringify when run on the models (with the exception of Bytes and BigInt types, which will be number[] and string respectively). Both files are output to the src/dto folder (which will be created if it doesn't exist) and are formatted using Prettier. The models in json-interfaces.ts also get a Json suffix attached to them.

Input

prisma/schema.prisma

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

generator client {
  provider = "prisma-client-js"
}

generator typescriptInterfaces {
  provider = "prisma-generator-typescript-interfaces"
  output   = "../src/dto/interfaces.ts"
  prettier = true
}

generator typescriptInterfacesJson {
  provider    = "prisma-generator-typescript-interfaces"
  output      = "../src/dto/json-interfaces.ts"
  modelSuffix = "Json"
  dateType    = "string"
  bigIntType  = "string"
  decimalType = "string"
  bytesType   = "number[]"
  exportEnums = false
  prettier    = true
}

enum Gender {
  Male
  Female
  Other
}

model Person {
  id        Int      @id @default(autoincrement())
  name      String
  age       Int
  email     String?
  gender    Gender
  addressId Int
  address   Address  @relation(fields: [addressId], references: [id])
  friendsOf Person[] @relation("Friends")
  friends   Person[] @relation("Friends")
  data      Data?
}

model Address {
  id           Int      @id
  streetNumber Int
  streetName   String
  city         String
  isBilling    Boolean
  people       Person[]
}

model Data {
  id           String   @id @default(uuid()) @db.Uuid
  stringField  String
  booleanField Boolean
  intField     Int
  bigIntField  BigInt
  floatField   Float
  decimalField Decimal
  dateField    DateTime
  jsonField    Json
  bytesField   Bytes

  optionalStringField  String?
  optionalBooleanField Boolean?
  optionalIntField     Int?
  optionalBigIntField  BigInt?
  optionalFloatField   Float?
  optionalDecimalField Decimal?
  optionalDateField    DateTime?
  optionalJsonField    Json?
  optionalBytesField   Bytes?

  stringArrayField  String[]
  booleanArrayField Boolean[]
  intArrayField     Int[]
  bigIntArrayField  BigInt[]
  floatArrayField   Float[]
  decimalArrayField Decimal[]
  dateArrayField    DateTime[]
  jsonArrayField    Json[]
  bytesArrayField   Bytes[]

  personId Int    @unique
  person   Person @relation(fields: [personId], references: [id])
}

Output

src/dto/interfaces.ts

// This file was auto-generated by prisma-generator-typescript-interfaces

export type Gender = "Male" | "Female" | "Other";

export interface Person {
  id: number;
  name: string;
  age: number;
  email: string | null;
  gender: Gender;
  addressId: number;
  address?: Address;
  friendsOf?: Person[];
  friends?: Person[];
  data?: Data | null;
}

export interface Address {
  id: number;
  streetNumber: number;
  streetName: string;
  city: string;
  isBilling: boolean;
  people?: Person[];
}

export interface Data {
  id: string;
  stringField: string;
  booleanField: boolean;
  intField: number;
  bigIntField: bigint;
  floatField: number;
  decimalField: Decimal;
  dateField: Date;
  jsonField: JsonValue;
  bytesField: Uint8Array;
  optionalStringField: string | null;
  optionalBooleanField: boolean | null;
  optionalIntField: number | null;
  optionalBigIntField: bigint | null;
  optionalFloatField: number | null;
  optionalDecimalField: Decimal | null;
  optionalDateField: Date | null;
  optionalJsonField: JsonValue | null;
  optionalBytesField: Uint8Array | null;
  stringArrayField: string[];
  booleanArrayField: boolean[];
  intArrayField: number[];
  bigIntArrayField: bigint[];
  floatArrayField: number[];
  decimalArrayField: Decimal[];
  dateArrayField: Date[];
  jsonArrayField: JsonValue[];
  bytesArrayField: Uint8Array[];
  personId: number;
  person?: Person;
}

type Decimal = { valueOf(): string };

type JsonValue =
  | string
  | number
  | boolean
  | { [key in string]?: JsonValue }
  | Array<JsonValue>
  | null;

src/dto/json-interfaces.ts

// This file was auto-generated by prisma-generator-typescript-interfaces

type Gender = "Male" | "Female" | "Other";

export interface PersonJson {
  id: number;
  name: string;
  age: number;
  email: string | null;
  gender: Gender;
  addressId: number;
  address?: AddressJson;
  friendsOf?: PersonJson[];
  friends?: PersonJson[];
  data?: DataJson | null;
}

export interface AddressJson {
  id: number;
  streetNumber: number;
  streetName: string;
  city: string;
  isBilling: boolean;
  people?: PersonJson[];
}

export interface DataJson {
  id: string;
  stringField: string;
  booleanField: boolean;
  intField: number;
  bigIntField: string;
  floatField: number;
  decimalField: string;
  dateField: string;
  jsonField: JsonValue;
  bytesField: number[];
  optionalStringField: string | null;
  optionalBooleanField: boolean | null;
  optionalIntField: number | null;
  optionalBigIntField: string | null;
  optionalFloatField: number | null;
  optionalDecimalField: string | null;
  optionalDateField: string | null;
  optionalJsonField: JsonValue | null;
  optionalBytesField: number[] | null;
  stringArrayField: string[];
  booleanArrayField: boolean[];
  intArrayField: number[];
  bigIntArrayField: string[];
  floatArrayField: number[];
  decimalArrayField: string[];
  dateArrayField: string[];
  jsonArrayField: JsonValue[];
  bytesArrayField: number[][];
  personId: number;
  person?: PersonJson;
}

type JsonValue =
  | string
  | number
  | boolean
  | { [key in string]?: JsonValue }
  | Array<JsonValue>
  | null;

Options

Option(s)	Type	Default	Description
output	string	"interfaces.ts"	The output location for the generated TypeScript interfaces.
enumPrefix, enumSuffix	string	""	Prefix/suffix to add to enum types.
enumObjectPrefix, enumObjectSuffix	string	""	Prefix/suffix to add to enum objects. Only applies when enumType is object.
modelPrefix, modelSuffix	string	""	Prefix/suffix to add to model types.
typePrefix, typeSuffix	string	""	Prefix/suffix to add to type types (MongoDB only).
headerComment	string	"This file was auto-generated by prisma-generator-typescript-interfaces"	Sets the header comment added to the top of the generated file. Set this to an empty string to disable the header comment. Supports multiple lines with "\n".
modelType	"interface" | "type"	"interface"	Controls how model definitions are generated. "interface" will create TypeScript interfaces, "type" will create TypeScript types. If using MongoDB, this also affects type definitions.
enumType	"stringUnion" | "enum" | "object"	"stringUnion"	Controls how enums are generated. "object" will create an object and string union type like the Prisma client, "enum" will create TypeScript enums, "stringUnion" will just create a string union type.
relations	"required" | "optional" | "none"	"optional"	Controls how relation fields are generated. "required" will have them be required fields on the model, "optional" will have them be optional, and "none" will exclude relations entirely.
counts	"required" | "optional" | "none"	"none"	Controls the _count field for models with relations. "required" will make it and all counts in it be required, "optional" will have them be optional, and "none" will exclude counts entirely.
stringType, booleanType, intType, floatType, jsonType, dateType, bigIntType, decimalType, bytesType	string	See Custom Types	The TypeScript type to use for each Prisma type. See Custom Types for details.
typeImportPath	string	""	The path to import custom types from when using imported types or per-field-types.
perFieldTypes	boolean	true	Whether to enable per-field-types.
exportEnums	boolean	true	Controls whether enum definitions are exported. If false, enums will only be defined inside the generated file.
includeComments	boolean	true	Controls whether documentation from the schema (comments starting with ///) are copied into the generated output as /** ... */ documentation blocks.
optionalNullables	boolean	false	Controls whether nullable fields are optional. Nullable fields are always defined with | null in their type definition, but if this is true, they will also use ?:.
optionalDefaults	boolean	false	Controls whether fields with a default value are made optional. If true, then fields with a @default attribute will use ?: in their type definition.
prettier	boolean	false	Formats the output using Prettier. Setting this to true requires that the prettier package is available.
prettierConfigPath	string | null	""	Path to the Prettier config file. If this is an empty string, the Prettier config file will be resolved relative to the output location. If this is null, no Prettier config file will be used.

Issues

Please report any issues to the issues page. I am actively using this package, so I'll try my best to address any issues that are reported. Alternatively, feel free to submit a PR.

Developing

All the code for this generator is contained within the src directory. You can build the generator by running npm install then npm run build.

Tests

You can run tests with npm run test. Tests are run using a custom script, see test.ts for details. You can add new tests by placing a Prisma schema and the expected output in a folder under the tests directory, you may want to look at the tests/options-behavior test as an example.

You can run specific tests by passing them as arguments to the test command:

npm run test -- options-behavior validation-errors

When a test fails, you can see the generated output in the __TEST_TMP__ folder inside that test's directory. Compare this with the expected output to see why it failed.

Please ensure all tests are passing and that the code is properly linted (npm run lint) before submitting a PR, thanks!

Changelog

3.1.0

• Add optionalDefaults option to control whether fields with a default value are generated as optional or not (defaults to false).

BREAKING CHANGES:

• The omitRelations and optionalRelations options have been replaced with just relations, which can be set to either required, optional, or none.
• The BufferObject and ArrayObject built-in types have been removed from the bytesType option. Their behavior can be replicated using custom types: <!-- prettier-ignore -->

  generator typescriptInterfaces {
    provider = "prisma-generator-typescript-interfaces"
     
    // To get the old 'BufferObject' behavior:
    bytesType = "BufferObject:{ type: \"Buffer\"; data: number[] }"
     
    // To get the old 'ArrayObject' behavior:
    bytesType = "ArrayObject:{ [index: number]: number } & { length?: never }"
  }
  

• The resolvePrettierConfig option has been replaced with prettierConfigPath, which allows you to specify a specific Prettier config file. If this option is empty (the default), then the behavior will be the same as before, where the Prettier config file will be resolved relative to the output location. Set the option to null to disable using Prettier config files altogether.
• The new per-field types feature is enabled by default. If your Prisma schema contains compatible type annotations in your field documentation, they will be used and the output will be different from previous releases. If you don't want this behavior, set the perFieldTypes config option to false.

New Features:

• Allow full control over the types used during generation, including allowing per-field types. See Custom Types for details.
  • Thanks @helmturner for the initial per-field types work
• Add the includeComments option to include documentation from the schema in the generated output (thanks @samelie)
• Add the counts option to include the _count field on models with relations. It can be set to either required, optional, or none.
• Improve config validation and generator error messages. The generator name is now included in all errors since Prisma doesn't make it clear which generator an error is coming from.