Forge Database Utilities

Common errors

• TypeError: forge_database_utils__WEBPACK_IMPORTED_MODULE_0__.getSupportedFieldTypes is not a function

  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.
  fix Change `const { getSupportedFieldTypes } = require('forge-database-utils');` to `import { getSupportedFieldTypes } from 'forge-database-utils';`. Ensure your project and bundler are configured for ESM.

• Error: field_type must be a supported field type

  cause Attempted to use an unsupported or misspelled field type in a validation context, often when integrating with a validation library like `express-validator`.
  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.

• Argument of type '"CustomType"' is not assignable to parameter of type 'FieldType'.

  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.
  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.

Warnings

• gotcha 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.
  Fix: Ensure the second argument to `getPostgresColumnType` is a complete `fieldTypeProperties` object when `fieldType` is 'Generated'.
• gotcha 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.
  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.
• gotcha 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.
  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`.

Install

• npm install forge-database-utils npm
• yarn add forge-database-utils yarn
• pnpm add forge-database-utils pnpm

Imports

• getSupportedFieldTypes
  wrong:

  const { getSupportedFieldTypes } = require('forge-database-utils');

  correct:

  import { getSupportedFieldTypes } from 'forge-database-utils';

  Package primarily designed for ESM imports; CJS `require` might lead to issues in some environments or configurations due to mixed module types.
• SUPPORTED_FIELD_TYPES
  wrong:

  import SUPPORTED_FIELD_TYPES from 'forge-database-utils';

  correct:

  import { SUPPORTED_FIELD_TYPES } from 'forge-database-utils';

  Constants are exported as named exports; there is no default export from this package.
• FieldType

  import type { FieldType } from 'forge-database-utils';

  Always use `import type` for type-only imports to ensure they are stripped during compilation and prevent accidental runtime dependencies.

Quickstart

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.

import { 
  getSupportedFieldTypes,
  isSupportedFieldType,
  getPostgresColumnType,
  buildGeneratedColumnDefinition,
  generateBaseName,
  type FieldType 
} from 'forge-database-utils';

// 1. Get and process supported field types
const fieldTypes = getSupportedFieldTypes();
console.log('All supported field types:', fieldTypes.slice(0, 5).join(', ') + '...');

const exampleField: FieldType = 'ShortText';
if (isSupportedFieldType(exampleField)) {
  const columnType = getPostgresColumnType(exampleField);
  console.log(`'${exampleField}' maps to PostgreSQL type: ${columnType}`);
}

// 2. Handle 'Generated' field type with properties
const generatedFieldProps = {
  data_type: 'ShortText',
  generation_type: 'VIRTUAL',
  column_defn: "first_name || ' ' || last_name"
};
const generatedColumnDef = getPostgresColumnType('Generated', generatedFieldProps);
console.log(`'Generated' field type (full name) column definition: ${generatedColumnDef}`);

// 3. Generate a PostgreSQL-compatible base name
const instanceId = 'My New Service 2024-Q2';
const baseName = generateBaseName(instanceId);
console.log(`Base name for '${instanceId}': ${baseName}`);

// Example of using the FieldType type
function displayFieldInfo(fieldType: FieldType) {
  console.log(`Processing field: ${fieldType}`);
}
displayFieldInfo('Email');