CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-prisma--get-platform

Platform detection utility for Prisma's internal use that detects operating system, architecture, and Linux distribution information to determine appropriate binary targets for Prisma engines.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

node-api-support.mddocs/

Node API Support

Node.js API compatibility validation utilities for ensuring proper engine type selection based on platform capabilities. This module provides functions to validate Node API support and generate platform-specific library names.

Capabilities

Assert Node API Support

Validates whether Node API is supported on the current platform and throws an error if not supported.

/**
 * Determines whether Node API is supported on the current platform and throws if not
 * @throws Error if Node API is not supported (specifically on 32-bit platforms)
 */
function assertNodeAPISupported(): void;

Usage Examples:

import { assertNodeAPISupported } from "@prisma/get-platform";

try {
  assertNodeAPISupported();
  console.log("Node API is supported on this platform");
  // Proceed with Node API engine type
} catch (error) {
  console.error("Node API not supported:", error.message);
  // Fall back to binary engine type
}

Error Conditions:

The function throws an error in the following cases:

  • 32-bit Node.js: When process.arch === 'ia32' and no custom library path is set
  • Custom library missing: When PRISMA_QUERY_ENGINE_LIBRARY is set but the file doesn't exist

Error Message:

The default query engine type (Node-API, "library") is currently not supported for 32bit Node. Please set `engineType = "binary"` in the "generator" block of your "schema.prisma" file (or use the environment variables "PRISMA_CLIENT_ENGINE_TYPE=binary" and/or "PRISMA_CLI_QUERY_ENGINE_TYPE=binary".)

Get Node API Library Name

Gets the Node-API library filename based on the binary target and intended usage (filesystem or URL).

/**
 * Gets Node-API Library name depending on the binary target
 * @param binaryTarget - The target platform identifier
 * @param type - 'fs' for filesystem usage, 'url' for S3 download URLs
 * @returns Platform-specific library filename
 */
function getNodeAPIName(binaryTarget: BinaryTarget, type: 'url' | 'fs'): string;

Usage Examples:

import { getNodeAPIName, getBinaryTargetForCurrentPlatform } from "@prisma/get-platform";

const target = await getBinaryTargetForCurrentPlatform();

// Get filename for filesystem usage
const fsName = getNodeAPIName(target, 'fs');
console.log(fsName);
// Examples:
// "libquery_engine-darwin-arm64.dylib.node" (macOS ARM64)
// "libquery_engine-debian-openssl-1.1.x.so.node" (Linux)
// "query_engine-windows.dll.node" (Windows)

// Get filename for download URLs
const urlName = getNodeAPIName(target, 'url');
console.log(urlName);
// Examples:
// "libquery_engine.dylib.node" (macOS)
// "libquery_engine.so.node" (Linux)
// "query_engine.dll.node" (Windows)

Platform-Specific Naming:

The function generates names based on platform conventions:

Windows platforms (target.includes('windows')):

  • Filesystem: query_engine-${binaryTarget}.dll.node
  • URL: query_engine.dll.node

macOS platforms (target.includes('darwin')):

  • Filesystem: libquery_engine-${binaryTarget}.dylib.node
  • URL: libquery_engine.dylib.node

Linux and other platforms:

  • Filesystem: libquery_engine-${binaryTarget}.so.node
  • URL: libquery_engine.so.node

Environment Variables

The Node API support system recognizes these environment variables:

PRISMA_QUERY_ENGINE_LIBRARY

Path to a custom query engine library file. When set and the file exists, Node API support validation is bypassed.

export PRISMA_QUERY_ENGINE_LIBRARY="/path/to/custom/libquery_engine.so.node"

Usage in validation:

const customLibraryPath = process.env.PRISMA_QUERY_ENGINE_LIBRARY;
const customLibraryExists = customLibraryPath && fs.existsSync(customLibraryPath);

if (!customLibraryExists && process.arch === 'ia32') {
  throw new Error(/* ... */);
}

Engine Type Selection Variables

While not directly used by this module, these environment variables control engine type selection:

  • PRISMA_CLIENT_ENGINE_TYPE: Controls client engine type ("library" or "binary")
  • PRISMA_CLI_QUERY_ENGINE_TYPE: Controls CLI engine type ("library" or "binary")

When Node API is not supported, these should be set to "binary".

Integration with Platform Detection

Node API support works together with platform detection:

import { 
  assertNodeAPISupported, 
  getNodeAPIName, 
  getBinaryTargetForCurrentPlatform 
} from "@prisma/get-platform";

async function setupQueryEngine() {
  try {
    // Check if Node API is supported
    assertNodeAPISupported();
    
    // Get the binary target for current platform
    const binaryTarget = await getBinaryTargetForCurrentPlatform();
    
    // Generate the appropriate library name
    const libraryName = getNodeAPIName(binaryTarget, 'fs');
    
    console.log(`Using Node API library: ${libraryName}`);
    return { engineType: 'library', libraryName };
    
  } catch (error) {
    console.warn("Node API not supported, falling back to binary engine");
    return { engineType: 'binary', libraryName: null };
  }
}

Compatibility Notes

  • 32-bit Node.js: Not supported for Node API engines due to technical limitations
  • Custom engines: Can bypass validation by setting PRISMA_QUERY_ENGINE_LIBRARY
  • Platform coverage: Node API libraries are available for all supported binary targets
  • Filename consistency: URL names are simplified for S3 distribution, filesystem names include full target specification

Install with Tessl CLI

npx tessl i tessl/npm-prisma--get-platform

docs

binary-targets.md

index.md

node-api-support.md

platform-detection.md

test-utilities.md

tile.json