feat: add additional Imports config for flexible import sections

[vargaadam]

Add additionalImports Configuration Option for Flexible Import Sections

Problem

Currently, when using prisma-kysely to generate Kysely types, users have no way to import additional libraries that they might need in their generated TypeScript files. This is particularly problematic when:

1. Using Decimal types: Users working with financial data often need to import decimal libraries like decimal.js or big.js to handle precise decimal calculations
2. Using custom types: Users may need to import custom types or utilities that are referenced in their Prisma schema
3. Using multiple libraries: Users might need to import several different libraries for various data types or utilities
4. Different import syntaxes: Users might need different import patterns (default imports, named imports, namespace imports, etc.)

Without this feature, users have to manually edit the generated files after each regeneration, which is error-prone and not maintainable.

Solution

This PR introduces a new optional configuration option additionalImports that allows users to specify custom import sections in their generated Kysely type files.

Key Features

• Flexible Import Syntax: Supports all TypeScript import patterns:

  • Default imports: import Decimal from 'decimal.js'
  • Named imports: import { Big } from 'big.js'
  • Namespace imports: import * as moment from 'moment'
  • Renamed imports: import { v4 as uuid } from 'uuid'
  • Type imports: import type { SomeType } from './custom-types'

• Multiple Imports: Support for importing multiple libraries in a single configuration

• Optional: Completely backward compatible - feature is disabled by default

• Full Control: Users can write exactly the import statements they need

Configuration

generator kysely {
  provider = "prisma-kysely"
  output = "../src/db"
  fileName = "types.ts"
  
  // Single import
  additionalImports = "import Decimal from 'decimal.js';"
  
  // Multiple imports
  additionalImports = """
import Decimal from 'decimal.js';
import { Big } from 'big.js';
import * as moment from 'moment';
import { v4 as uuid } from 'uuid';
import type { SomeType } from './custom-types';
"""
}

Generated Output

The generated file will start with the custom imports followed by the standard Kysely imports:

import Decimal from 'decimal.js';
import { Big } from 'big.js';
import * as moment from 'moment';
import { v4 as uuid } from 'uuid';
import type { SomeType } from './custom-types';

import type { ColumnType } from "kysely";
// ... rest of generated types

Implementation Details

Files Modified

1. src/utils/validateConfig.ts: Added additionalImports to the configuration schema
2. src/helpers/generateFile.ts: Updated to conditionally include custom import sections
3. src/helpers/generateFiles.ts: Pass the additionalImports config to generateFile
4. src/generator.ts: Pass the additionalImports config through the generation pipeline
5. README.md: Added comprehensive documentation and examples
6. src/helpers/generateFile.test.ts: Added tests for all import scenarios

Use Cases

Financial Applications

generator kysely {
  provider = "prisma-kysely"
  additionalImports = "import Decimal from 'decimal.js';"
}

model Transaction {
  id      Int     @id @default(autoincrement())
  amount  Decimal @db.Decimal(10, 2)
  // ... other fields
}

Applications with Custom Types

generator kysely {
  provider = "prisma-kysely"
  additionalImports = """
import type { UserRole } from './types';
import { validateEmail } from './utils';
"""
}

Multi-library Applications

generator kysely {
  provider = "prisma-kysely"
  decimalTypeOverride = "Decimal"
  additionalImports = """
import Decimal from 'decimal.js';
import { v4 as uuid } from 'uuid';
import * as moment from 'moment';
import type { CustomType } from './types';
"""
}

Backward Compatibility

This feature is completely backward compatible:

• No breaking changes to existing functionality
• Feature is optional and disabled by default
• All existing configurations continue to work unchanged
• No impact on existing generated files

Benefits

1. Eliminates Manual Editing: Users no longer need to manually edit generated files
2. Maintainable: Import statements are preserved across regenerations
3. Flexible: Supports any import pattern users might need
4. Type Safe: Maintains full TypeScript type safety
5. Developer Experience: Improves workflow for users working with custom types and libraries

Future Considerations

This implementation provides a solid foundation that could be extended in the future with:

• Import path resolution
• Automatic import detection based on schema types
• Import optimization and deduplication

However, the current implementation provides maximum flexibility while keeping the feature simple and maintainable.

[alii]

Thanks for the contrib! This makes sense, I'm often doing something like:

/// @kyselyType(import('module').TheThing)
prop           String

I'll have a feel with this on the weekend and think it through a little. My gut feeling is that there might be a better, more generic way we could enable this.

Perhaps naming it something else like "filePrefix" even, since this is, in theory, unrelated to just imports.

[vargaadam]

Thanks for the quick feedback!

I completely agree that filePrefix is a better, more generic name. It makes the feature more flexible and not limited to just imports - users could add comments, pragma directives, or any other content they need at the top of the file.

I'm happy to update the PR to use filePrefix instead of additionalImports if you'd like, or I can wait for your thoughts after you've had more time to think it through over the weekend.

Let me know what you prefer!

[alii]

Feel free to iterate/update it some more, but will be able to provide something more concrete this weekend. Thanks again 🙂

[vargaadam]

Hi, I just wanted to check if you’ve had a chance to take a look at it. Thanks!

[alii]

Sorry! I did not get a chance to unfortunately, have had a busy week/weekend. Will aim to do so next weekend. I will soon upgrade the prisma version to be compatible with 6.17.

[shoxter]

This is exactly what we were looking for! Thanks!

[vargaadam]

I've gone ahead and implemented the filePrefix change you suggested. All the code, tests, and documentation have been updated to use the new naming, which makes it much clearer that the feature supports imports, pragma directives, comments, or any content at the top of generated files.

Have you had a chance to think through the feature further? Happy to make any additional changes you'd like!

Thanks for your feedback 🙂

[shoxter]

Any word on when this will be merged?