{"id":16361,"library":"forge-database-utils","title":"Forge Database Utilities","description":"`forge-database-utils` is a JavaScript/TypeScript package designed to provide shared database utility functions specifically for Forge services. Currently at version 1.4.1, it centralizes common database-related logic to ensure consistency and reduce code duplication across various internal Forge components like control, authentication, metadata, and UI services. Key features include a centralized definition of supported field types, utility functions for validating and querying field type properties (e.g., `isSupportedFieldType`, `getPostgresColumnType`), and functions for generating PostgreSQL-compatible base names from instance IDs. The package is developed to align with the specific architectural needs of the Forge ecosystem, serving as a foundational library rather than a general-purpose database utility. Its release cadence is typically tied to internal project development cycles, ensuring tight integration and stability within the Forge suite.","status":"active","version":"1.4.1","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","forge","database","postgresql","utilities","typescript"],"install":[{"cmd":"npm install forge-database-utils","lang":"bash","label":"npm"},{"cmd":"yarn add forge-database-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add forge-database-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package primarily designed for ESM imports; CJS `require` might lead to issues in some environments or configurations due to mixed module types.","wrong":"const { getSupportedFieldTypes } = require('forge-database-utils');","symbol":"getSupportedFieldTypes","correct":"import { getSupportedFieldTypes } from 'forge-database-utils';"},{"note":"Constants are exported as named exports; there is no default export from this package.","wrong":"import SUPPORTED_FIELD_TYPES from 'forge-database-utils';","symbol":"SUPPORTED_FIELD_TYPES","correct":"import { SUPPORTED_FIELD_TYPES } from 'forge-database-utils';"},{"note":"Always use `import type` for type-only imports to ensure they are stripped during compilation and prevent accidental runtime dependencies.","symbol":"FieldType","correct":"import type { FieldType } from 'forge-database-utils';"}],"quickstart":{"code":"import { \n  getSupportedFieldTypes,\n  isSupportedFieldType,\n  getPostgresColumnType,\n  buildGeneratedColumnDefinition,\n  generateBaseName,\n  type FieldType \n} from 'forge-database-utils';\n\n// 1. Get and process supported field types\nconst fieldTypes = getSupportedFieldTypes();\nconsole.log('All supported field types:', fieldTypes.slice(0, 5).join(', ') + '...');\n\nconst exampleField: FieldType = 'ShortText';\nif (isSupportedFieldType(exampleField)) {\n  const columnType = getPostgresColumnType(exampleField);\n  console.log(`'${exampleField}' maps to PostgreSQL type: ${columnType}`);\n}\n\n// 2. Handle 'Generated' field type with properties\nconst generatedFieldProps = {\n  data_type: 'ShortText',\n  generation_type: 'VIRTUAL',\n  column_defn: \"first_name || ' ' || last_name\"\n};\nconst generatedColumnDef = getPostgresColumnType('Generated', generatedFieldProps);\nconsole.log(`'Generated' field type (full name) column definition: ${generatedColumnDef}`);\n\n// 3. Generate a PostgreSQL-compatible base name\nconst instanceId = 'My New Service 2024-Q2';\nconst baseName = generateBaseName(instanceId);\nconsole.log(`Base name for '${instanceId}': ${baseName}`);\n\n// Example of using the FieldType type\nfunction displayFieldInfo(fieldType: FieldType) {\n  console.log(`Processing field: ${fieldType}`);\n}\ndisplayFieldInfo('Email');\n","lang":"typescript","description":"Demonstrates importing various utility functions and types, using `getSupportedFieldTypes`, checking field type support, deriving PostgreSQL column types, handling 'Generated' field properties, and generating base names."},"warnings":[{"fix":"Ensure the second argument to `getPostgresColumnType` is a complete `fieldTypeProperties` object when `fieldType` is 'Generated'.","message":"When using `getPostgresColumnType` for the `Generated` field type, an explicit `fieldTypeProperties` object with `data_type`, `generation_type`, and `column_defn` is mandatory. Failing to provide this will result in an error or incorrect column definition.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Prefer `import` statements over `require()`. If using Node.js, ensure your `package.json` specifies `\"type\": \"module\"` or use a transpiler like Babel/TypeScript to convert to ESM.","message":"This package is designed for an ESM-first environment. While bundlers usually handle CommonJS compatibility, direct `require()` calls in Node.js projects not configured for ESM might lead to `TypeError: ... is not a function` errors due to differences in module resolution.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Regularly update `forge-database-utils` to benefit from new features and synchronize with the latest field type definitions across Forge services. Always validate user input against `isSupportedFieldType` or `SUPPORTED_FIELD_TYPES`.","message":"The `SUPPORTED_FIELD_TYPES` constant and `getSupportedFieldTypes()` function provide a list of currently supported types. If new field types are introduced in a newer version of `forge-database-utils`, consuming services must update their package version to correctly validate and utilize these new types.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change `const { getSupportedFieldTypes } = require('forge-database-utils');` to `import { getSupportedFieldTypes } from 'forge-database-utils';`. Ensure your project and bundler are configured for ESM.","cause":"Incorrect import syntax, typically when a bundler (like Webpack) processes a CJS `require` for an ESM-only package, or when trying to destructure a module object incorrectly.","error":"TypeError: forge_database_utils__WEBPACK_IMPORTED_MODULE_0__.getSupportedFieldTypes is not a function"},{"fix":"Verify the field type string against `SUPPORTED_FIELD_TYPES` or use `isSupportedFieldType()` to check validity before processing. Correct any typos or ensure the field type is part of the Forge system.","cause":"Attempted to use an unsupported or misspelled field type in a validation context, often when integrating with a validation library like `express-validator`.","error":"Error: field_type must be a supported field type"},{"fix":"Ensure the value passed is one of the types defined in the `FieldType` union. If it's a new custom type, it needs to be added to the internal Forge system and the `forge-database-utils` package.","cause":"TypeScript error indicating that a string literal or variable passed to a function expecting `FieldType` (a union of supported types) does not match any of the allowed types.","error":"Argument of type '\"CustomType\"' is not assignable to parameter of type 'FieldType'."}],"ecosystem":"npm"}