prisma-json-types-generator

Using this package? Please consider donating to support my open source work ❤️
^{Help prisma-json-types-generator grow! Star and share this amazing repository with your friends and co-workers!}

Prisma Json Types Generator

Generate your prisma client with strict JSON types and String literals!

• Installation
• Usage
• Typing JSON Fields
  • Example Schema
  • Example Type Declarations
  • Resulting Type Inference
• Configuration Options
• Limitations
• Advanced Usage
  • Monorepos
  • Inline Type Declarations
• How It Works
• License

Prisma JSON Types Generator enhances your @prisma/client by replacing all JSON types with your specified TypeScript types. This ensures a stricter type-checking layer, requiring your JSON types to conform to TypeScript rules before insertion into the database.

Installation

Install the package as a development dependency:

npm install -D prisma-json-types-generator

Usage

• Add the generator to your Prisma schema: Place the generator below the prisma-client-js generator in your schema.prisma:

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

• Define your JSON types: Create a TypeScript file containing the type declarations. This file must be included in your tsconfig.

  // types.ts
  
  declare global {
    namespace PrismaJson {
      // Define your custom types here!
    }
  }
  
  // The file MUST be a module! 
  export {};
  

Typing JSON Fields

This generator allows multiple approaches to type Json or String fields, avoiding circular dependencies between the Prisma schema and your codebase. Global namespaces (PrismaJson) provide a centralized location for your type definitions.

Example Schema

model Example {
  /// [MyType]
  normal Json

  /// [MyType] comments are allowed after the type definition!
  comment Json

  /// [MyType]
  optional Json?

  /// [MyType]
  array Json[]

  /// [ComplexType]
  complex Json

  /// !['A' | 'B']
  literal Json

  /// ![[('A' | 'B')[], number[][][][]]]
  literalArray Json

  /// ![PrismaJson.MyType | 'none']
  anything Json[]
}

Example Type Declarations

declare global {
  namespace PrismaJson {
    type MyType = boolean;
    type ComplexType = { foo: string; bar: number };
  }
}

Resulting Type Inference

import type { Example } from '@prisma/client';

// example.normal   -> boolean
// example.optional -> boolean | null
// example.array    -> boolean[]
// example.complex  -> { foo: string; bar: number }
// example.literal  -> 'A' | 'B'
// example.anything -> PrismaJson.MyType | 'none'

Configuration Options

generator json {
  provider = "prisma-json-types-generator"

  // Specify the namespace for type generation.
  // Default: "PrismaJson"
  // namespace = "PrismaJson"

  // Define the client output path.
  // Default: Automatically determined.
  // clientOutput = "automatic"

  // Add an index signature to a root type for dynamic JSON fields.
  // useType = "GlobalType"

  // Use `any` instead of `unknown` for untyped JSON fields.
  // allowAny = false
}

Limitations

• Complex Filters: Types like JsonFilter and JsonWithAggregatesFilter remain untyped to preserve functionality.
• Prisma v4 Support: Only Prisma v5+ and generator v3+ are supported.
• Known Gaps: If some JSON fields are missing types, open an issue in the repository.

Advanced Usage

Monorepos

In monorepos, ensure the file containing the PrismaJson namespace is part of the runtime imports. Otherwise, types will default to any.

// package1/src/types.ts

declare global {
  namespace PrismaJson {
    // Define types here
  }
}

// package2/src/client.ts

// Import the type definitions
import 'package1/types.ts';
import { PrismaClient } from '@prisma/client';

export const client = new PrismaClient();

Inline Type Declarations

Directly declare types in the schema:

model Example {
  /// ![Record<string, string>]
  map Json
}

How It Works

This generator leverages the TypeScript Compiler API to analyze the client's type definitions. It identifies Prisma.JsonValue (or related) types and replaces them with the specified types using AST transformations. For details, see the implementation.

License

Licensed under the MIT. See LICENSE for more informations.