CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-prisma--internals

Comprehensive internal utility library for Prisma's CLI operations, schema management, generator handling, and engine interactions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

engine-commands.mddocs/

Engine Commands and Schema Operations

The engine commands domain provides comprehensive schema processing capabilities using WASM-based engines for formatting, validation, DMMF generation, and configuration extraction.

Functions

Schema Formatting

formatSchema(options, formattingOptions?)

Formats Prisma schema files using the WASM formatter with customizable formatting options.

function formatSchema(
  options: { schemas: MultipleSchemas },
  formattingOptions?: Partial<DocumentFormattingParams['options']>
): Promise<MultipleSchemas>

Parameters:

  • options: { schemas: MultipleSchemas } - Schemas to format
  • formattingOptions?: Partial<DocumentFormattingParams['options']> - Formatting configuration

DocumentFormattingParams Options:

interface DocumentFormattingParams {
  options?: {
    tabSize?: number        // Tab size (default: 2)
    insertSpaces?: boolean  // Use spaces instead of tabs (default: true)
  }
}

Returns: Promise<MultipleSchemas> - Formatted schemas

Example:

const formatted = await formatSchema(
  { schemas: loadedSchemas },
  { tabSize: 4, insertSpaces: true }
)

Configuration Extraction

getConfig(options)

Extracts and parses configuration from Prisma schema using the WASM engine.

function getConfig(options: GetConfigOptions): Promise<ConfigMetaFormat>

GetConfigOptions:

interface GetConfigOptions {
  schemas: SchemaFileInput     // Schema input
  cwd?: string                // Current working directory
  ignoreEnvVarErrors?: boolean // Ignore environment variable errors
}

Returns: Promise<ConfigMetaFormat> - Parsed configuration with datasources, generators, and warnings

Example:

const config = await getConfig({
  schemas: schemaResult.schemas,
  cwd: process.cwd(),
  ignoreEnvVarErrors: false
})

console.log(`Found ${config.datasources.length} datasources`)
console.log(`Found ${config.generators.length} generators`)
if (config.warnings.length > 0) {
  console.warn('Configuration warnings:', config.warnings)
}

getDirectUrl(ds)

Extracts the direct URL from a datasource configuration.

function getDirectUrl(ds: DataSource): EnvValue | undefined

Parameters:

  • ds: DataSource - Datasource object

Returns: EnvValue | undefined - Direct URL environment value if defined

getEffectiveUrl(ds)

Gets the effective URL from a datasource (direct URL takes precedence over regular URL).

function getEffectiveUrl(ds: DataSource): EnvValue

Parameters:

  • ds: DataSource - Datasource object

Returns: EnvValue - Effective URL environment value

resolveUrl(envValue?)

Resolves URL string from environment value configuration.

function resolveUrl(envValue?: EnvValue): string | undefined

Parameters:

  • envValue?: EnvValue - Environment value configuration

Returns: string | undefined - Resolved URL string

Example:

const config = await getConfig({ schemas })
for (const datasource of config.datasources) {
  const directUrl = getDirectUrl(datasource)
  const effectiveUrl = getEffectiveUrl(datasource)
  const resolvedUrl = resolveUrl(effectiveUrl)
  
  console.log(`Datasource: ${datasource.name}`)
  console.log(`Direct URL: ${directUrl ? 'defined' : 'not defined'}`)
  console.log(`Resolved URL: ${resolvedUrl}`)
}

DMMF Generation

getDMMF(options)

Generates Data Model Meta Format (DMMF) from Prisma schema using the WASM engine.

function getDMMF(options: GetDMMFOptions): Promise<DMMF.Document>

GetDMMFOptions:

interface GetDMMFOptions {
  datamodel: SchemaFileInput    // Schema input
  previewFeatures?: string[]    // Preview features to enable
}

Returns: Promise<DMMF.Document> - Generated DMMF document containing models, enums, types, and mappings

Example:

const dmmf = await getDMMF({
  datamodel: schemaResult.schemas,
  previewFeatures: ['typedSql', 'views']
})

console.log(`Models: ${dmmf.datamodel.models.length}`)
console.log(`Enums: ${dmmf.datamodel.enums.length}`)
console.log(`Types: ${dmmf.datamodel.types.length}`)

// Access model information
for (const model of dmmf.datamodel.models) {
  console.log(`Model ${model.name}: ${model.fields.length} fields`)
}

Schema Validation

validate(options)

Validates Prisma schema without generating DMMF, throwing error if validation fails.

function validate(options: ValidateOptions): void

ValidateOptions:

interface ValidateOptions {
  schemas: SchemaFileInput     // Schema input to validate
  cwd?: string                // Current working directory
}

Throws: Error if validation fails

Example:

try {
  validate({
    schemas: schemaResult.schemas,
    cwd: process.cwd()
  })
  console.log('Schema validation passed')
} catch (error) {
  console.error('Schema validation failed:', error.message)
}

Schema Linting

lintSchema(options)

Lints Prisma schema and returns array of diagnostics (warnings and errors).

function lintSchema(options: { schemas: MultipleSchemas }): LintDiagnostic[]

Parameters:

  • options: { schemas: MultipleSchemas } - Schemas to lint

Returns: LintDiagnostic[] - Array of lint diagnostics

getLintWarningsAsText(lintDiagnostics)

Converts lint diagnostics to formatted text warnings for display.

function getLintWarningsAsText(lintDiagnostics: LintDiagnostic[]): string

Parameters:

  • lintDiagnostics: LintDiagnostic[] - Lint diagnostics to format

Returns: string - Formatted warning text

handleLintPanic<T>(tryCb)

Handles panics during schema linting operations by converting them to RustPanic errors.

function handleLintPanic<T>(tryCb: () => T): T

Parameters:

  • tryCb: () => T - Callback function that might panic

Returns: T - Result or throws RustPanic

Example:

const diagnostics = lintSchema({ schemas: loadedSchemas })

const warnings = diagnostics.filter(d => d.is_warning)
const errors = diagnostics.filter(d => !d.is_warning)

if (warnings.length > 0) {
  console.warn('Lint warnings:')
  console.warn(getLintWarningsAsText(warnings))
}

if (errors.length > 0) {
  console.error('Lint errors:')
  console.error(getLintWarningsAsText(errors))
}

Schema Merging

mergeSchemas(options)

Merges multiple schema files into a single schema string.

function mergeSchemas(options: MergeSchemasOptions): string

MergeSchemasOptions:

interface MergeSchemasOptions {
  schemas: MultipleSchemas    // Multiple schema files to merge
}

Returns: string - Merged schema string

Example:

const mergedSchema = mergeSchemas({
  schemas: {
    'schema.prisma': schemaContent1,
    'models.prisma': schemaContent2,
    'enums.prisma': schemaContent3
  }
})

console.log('Merged schema length:', mergedSchema.length)

Engine Information

getEnginesInfo(enginesInfo)

Gets formatted engine information and collects any errors encountered.

function getEnginesInfo(enginesInfo: BinaryInfoMatrix): readonly [string, Error[]]

Parameters:

  • enginesInfo: BinaryInfoMatrix - Engine information matrix

Returns: readonly [string, Error[]] - Tuple of version message and array of errors

resolveEngine(binaryName)

Resolves engine path and version information for a specific binary type.

function resolveEngine(binaryName: BinaryType): Promise<EngineInfo>

Parameters:

  • binaryName: BinaryType - Type of binary to resolve

Returns: Promise<EngineInfo> - Engine information including path and version

getEngineVersion(enginePath?, binaryName?)

Gets version information from an engine binary.

function getEngineVersion(
  enginePath?: string,
  binaryName?: BinaryType
): Promise<string>

Parameters:

  • enginePath?: string - Optional engine path
  • binaryName?: BinaryType - Binary type

Returns: Promise<string> - Engine version string

Example:

// Get query engine information
const queryEngineInfo = await resolveEngine(BinaryType.QueryEngine)

if (queryEngineInfo.path._tag === 'Right') {
  console.log('Query engine path:', queryEngineInfo.path.right)
}

if (queryEngineInfo.version._tag === 'Right') {
  console.log('Query engine version:', queryEngineInfo.version.right)
}

// Get version directly
const version = await getEngineVersion()
console.log('Engine version:', version)

WASM Integration and Schema Engine Loading

WASM Namespace

wasm

WebAssembly integration namespace providing access to Prisma Schema WASM modules and Schema Engine WASM functionality.

namespace wasm {
  // WASM modules
  const prismaSchemaWasm: typeof import('@prisma/prisma-schema-wasm')
  type SchemaEngineWasm = import('@prisma/schema-engine-wasm').SchemaEngine
  
  // Version information  
  const prismaSchemaWasmVersion: string    // e.g. "4.3.0-18.a39215673171b87177b86233206a5d65f2558857"
  const schemaEngineWasmVersion: string    // e.g. "4.3.0-18.a39215673171b87177b86233206a5d65f2558857"
}

wasm.prismaSchemaWasm

Direct export of the Prisma Schema WASM module for schema processing operations.

const prismaSchemaWasm: typeof import('@prisma/prisma-schema-wasm')

Usage:

import { wasm } from '@prisma/internals'

// Use the Prisma Schema WASM module directly
const result = wasm.prismaSchemaWasm.format(schemaContent, formatOptions)

wasm.SchemaEngineWasm

Type export for the WASM-based schema engine.

type SchemaEngineWasm = import('@prisma/schema-engine-wasm').SchemaEngine

wasm.prismaSchemaWasmVersion

Version string for the Prisma Schema WASM package dependency.

const prismaSchemaWasmVersion: string

wasm.schemaEngineWasmVersion

Version string for the Schema Engine WASM package dependency.

const schemaEngineWasmVersion: string

Example:

import { wasm } from '@prisma/internals'

console.log('WASM Versions:')
console.log(`Prisma Schema WASM: ${wasm.prismaSchemaWasmVersion}`)
console.log(`Schema Engine WASM: ${wasm.schemaEngineWasmVersion}`)

WASM Schema Engine Loader

wasmSchemaEngineLoader

Singleton loader for WASM-based schema engine instances with efficient caching and WebAssembly integration.

const wasmSchemaEngineLoader: {
  loadSchemaEngine(
    input: ConstructorOptions,
    debug: (arg: string) => void,
    adapter: ErrorCapturingSqlDriverAdapterFactory
  ): Promise<SchemaEngineInstance>
}

wasmSchemaEngineLoader.loadSchemaEngine(input, debug, adapter)

Loads and initializes a WASM schema engine instance with caching for efficiency.

function loadSchemaEngine(
  input: ConstructorOptions,
  debug: (arg: string) => void,  
  adapter: ErrorCapturingSqlDriverAdapterFactory
): Promise<SchemaEngineInstance>

Parameters:

  • input: ConstructorOptions - Schema engine constructor options
  • debug: (arg: string) => void - Debug logging function
  • adapter: ErrorCapturingSqlDriverAdapterFactory - SQL driver adapter factory

Returns: Promise<SchemaEngineInstance> - Initialized schema engine instance

Caching Behavior:

  • Creates WASM instance only once for efficiency
  • Reuses cached instance across multiple calls
  • Prevents WebAssembly binding conflicts from multiple instantiations

Example:

import { wasmSchemaEngineLoader } from '@prisma/internals'

async function initializeSchemaEngine() {
  const debugLogger = (message: string) => {
    console.log(`[Schema Engine Debug]: ${message}`)
  }
  
  const constructorOptions = {
    // Schema engine configuration options
    datamodel: schemaContent,
    logQueries: true,
    logLevel: 'info'
  }
  
  const sqlAdapter = createSqlDriverAdapterFactory()
  
  try {
    const schemaEngine = await wasmSchemaEngineLoader.loadSchemaEngine(
      constructorOptions,
      debugLogger,
      sqlAdapter
    )
    
    console.log('WASM Schema Engine loaded successfully')
    return schemaEngine
  } catch (error) {
    console.error('Failed to load WASM Schema Engine:', error.message)
    throw error
  }
}

// Multiple calls will reuse the same WASM instance internally
const engine1 = await wasmSchemaEngineLoader.loadSchemaEngine(opts1, debug, adapter)
const engine2 = await wasmSchemaEngineLoader.loadSchemaEngine(opts2, debug, adapter)
// Both use the same underlying WASM module instance

Internal Architecture:

// Simplified internal structure
const wasmSchemaEngineLoader = {
  async loadSchemaEngine(input, debug, adapter) {
    // Singleton pattern - create WASM instance only once
    if (loadedWasmInstance === undefined) {
      const wasmModule = await getSchemaEngineWasModule()  // Load .wasm file
      const runtime = await import('@prisma/schema-engine-wasm/schema_engine_bg')
      
      // WebAssembly instantiation with wasm-bindgen integration
      const instance = new WebAssembly.Instance(wasmModule, {
        './schema_engine_bg.js': runtime
      })
      
      runtime.__wbg_set_wasm(instance.exports)
      const wbindgen_start = instance.exports.__wbindgen_start as () => void
      wbindgen_start()
      
      loadedWasmInstance = runtime.SchemaEngine
    }
    
    return await loadedWasmInstance.new(input, debug, adapter)
  }
}

Error Path Processing

relativizePathInPSLError(message)

Converts absolute paths in PSL (Prisma Schema Language) error messages to relative paths for better readability.

function relativizePathInPSLError(message: string): string

Parameters:

  • message: string - Error message containing absolute paths

Returns: string - Error message with relativized paths

Types and Interfaces

Configuration Types

ConfigMetaFormat

Complete configuration extracted from Prisma schema.

interface ConfigMetaFormat {
  datasources: DataSource[]     // Parsed datasources
  generators: GeneratorConfig[] // Parsed generators
  warnings: string[]           // Configuration warnings
}

GetDMMFOptions

Options for DMMF generation.

interface GetDMMFOptions {
  datamodel: SchemaFileInput    // Schema input
  previewFeatures?: string[]    // Preview features to enable
}

Engine Information Types

EngineInfo

Information about an engine binary including path and version.

interface EngineInfo {
  fromEnvVar: O.Option<string>      // Environment variable name if resolved from env
  path: E.Either<Error, string>     // Engine path or error
  version: E.Either<Error, string>  // Engine version or error
}

BinaryMatrix<T>

Type matrix for different binary types.

type BinaryMatrix<T> = {
  'query-engine': T
  'schema-engine': T
}

BinaryInfoMatrix

Engine information for each binary type.

type BinaryInfoMatrix = BinaryMatrix<EngineInfo>

Linting Types

LintDiagnostic

Union type representing lint warnings or errors.

type LintDiagnostic = LintWarning | LintError

LintWarning

Lint warning diagnostic information.

interface LintWarning {
  is_warning: true      // Indicates this is a warning
  start: number         // Start position in schema
  end: number          // End position in schema
  text: string         // Warning message text
}

LintError

Lint error diagnostic information.

interface LintError {
  is_warning: false     // Indicates this is an error
  start: number         // Start position in schema
  end: number          // End position in schema  
  text: string         // Error message text
}

Schema Input Types

SchemaFileInput

Input type for schema content that can be a string or MultipleSchemas.

type SchemaFileInput = string | MultipleSchemas

MultipleSchemas

Object representing multiple schema files with their content.

type MultipleSchemas = {
  [filename: string]: string  // Filename to content mapping
}

Examples

Complete Schema Processing Workflow

import {
  getConfig,
  validate,
  formatSchema,
  getDMMF,
  lintSchema,
  getLintWarningsAsText
} from '@prisma/internals'

async function processSchema(schemas: MultipleSchemas) {
  // 1. Validate schema
  try {
    validate({ schemas, cwd: process.cwd() })
    console.log('✓ Schema validation passed')
  } catch (error) {
    console.error('✗ Schema validation failed:', error.message)
    return
  }
  
  // 2. Lint schema
  const diagnostics = lintSchema({ schemas })
  if (diagnostics.length > 0) {
    const warnings = getLintWarningsAsText(diagnostics)
    console.warn('Lint diagnostics:\n', warnings)
  }
  
  // 3. Format schema
  const formatted = await formatSchema(
    { schemas },
    { tabSize: 2, insertSpaces: true }
  )
  console.log('✓ Schema formatted')
  
  // 4. Extract configuration
  const config = await getConfig({ 
    schemas: formatted,
    cwd: process.cwd() 
  })
  console.log(`✓ Found ${config.datasources.length} datasources, ${config.generators.length} generators`)
  
  // 5. Generate DMMF
  const dmmf = await getDMMF({
    datamodel: formatted,
    previewFeatures: ['typedSql']
  })
  console.log(`✓ Generated DMMF with ${dmmf.datamodel.models.length} models`)
  
  return {
    formatted,
    config,
    dmmf,
    diagnostics
  }
}

Engine Version Checking

import { 
  resolveEngine, 
  getEngineVersion, 
  getEnginesInfo,
  BinaryType 
} from '@prisma/internals'

async function checkEngineVersions() {
  const engines = ['query-engine', 'schema-engine'] as const
  const engineInfo: any = {}
  
  for (const engineType of engines) {
    try {
      const info = await resolveEngine(BinaryType[engineType])
      engineInfo[engineType] = info
      
      console.log(`${engineType}:`)
      if (info.path._tag === 'Right') {
        console.log(`  Path: ${info.path.right}`)
      }
      if (info.version._tag === 'Right') {
        console.log(`  Version: ${info.version.right}`)
      }
      if (info.fromEnvVar._tag === 'Some') {
        console.log(`  From env var: ${info.fromEnvVar.value}`)
      }
    } catch (error) {
      console.error(`Failed to resolve ${engineType}:`, error.message)
    }
  }
  
  // Get formatted summary
  const [summary, errors] = getEnginesInfo(engineInfo)
  console.log('\nEngine Summary:')
  console.log(summary)
  
  if (errors.length > 0) {
    console.error('Errors:', errors.map(e => e.message))
  }
}

URL Resolution from Datasources

import {
  getConfig,
  getDirectUrl,
  getEffectiveUrl,
  resolveUrl
} from '@prisma/internals'

async function analyzeDatasourceUrls(schemas: MultipleSchemas) {
  const config = await getConfig({ schemas })
  
  for (const datasource of config.datasources) {
    console.log(`\nDatasource: ${datasource.name}`)
    console.log(`Provider: ${datasource.provider}`)
    
    // Check for direct URL
    const directUrl = getDirectUrl(datasource)
    if (directUrl) {
      console.log('Direct URL configured: Yes')
      const resolvedDirectUrl = resolveUrl(directUrl)
      if (resolvedDirectUrl) {
        console.log(`Direct URL: ${resolvedDirectUrl}`)
      }
    } else {
      console.log('Direct URL configured: No')
    }
    
    // Get effective URL (direct takes precedence)
    const effectiveUrl = getEffectiveUrl(datasource)
    const resolvedUrl = resolveUrl(effectiveUrl)
    if (resolvedUrl) {
      console.log(`Effective URL: ${resolvedUrl}`)
    }
  }
}

Install with Tessl CLI

npx tessl i tessl/npm-prisma--internals

docs

binary-resolution.md

cli-utilities.md

database-operations.md

engine-commands.md

error-handling.md

generators.md

index.md

syntax-highlighting.md

tracing.md

utilities.md

tile.json