forge-database-utils

Shared database utility functions for Forge services.

This package provides common database-related logic to ensure consistency and reduce code duplication across Forge services (control, auth, metadata, ui).

Installation

npm install forge-database-utils

Features

Field Types

Centralized definition of supported field types across all Forge services.

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

// Get all supported field types
const fieldTypes = getSupportedFieldTypes();
// Returns: ['ShortText', 'Email', 'Dropdown', ...]

// Check if a field type is supported
if (isSupportedFieldType('ShortText')) {
  // Field type is valid
}

// Check if a field type requires a database column
if (fieldTypeRequiresColumn('ShortText')) {
  // This field type needs a database column
}

// Get PostgreSQL column type for a field
const columnType = getPostgresColumnType('ShortText');
// Returns: 'VARCHAR(255)'

const numberColumnType = getPostgresColumnType('Number');
// Returns: 'NUMERIC(10,4)'

// For Generated fields, pass field type properties
const generatedColumnType = getPostgresColumnType('Generated', {
  data_type: 'shortText',
  generation_type: 'VIRTUAL',
  column_defn: "first_name || ' ' || last_name"
});
// Returns: "VARCHAR(255) GENERATED ALWAYS AS (first_name || ' ' || last_name) VIRTUAL"

// Use the constant directly
console.log(SUPPORTED_FIELD_TYPES);
console.log(FIELD_TYPES_WITH_COLUMNS);

// Use the TypeScript type
function processField(fieldType: FieldType) {
  // fieldType is guaranteed to be a valid field type
}

Base Name Generation

Generate PostgreSQL-compatible base names from instance IDs.

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

const baseName = generateBaseName('My Instance 123');
// Returns: 'myinstance123'

Supported Field Types

The following field types are supported in the Forge system:

Field types with database columns:

• Checkbox
• DateTime
• Dropdown
• Email
• Generated
• LongText
• MultiDropdown
• Number
• Password
• PhoneNumber
• ShortText
• Time

Field types without database columns (UI-only):

• Button
• Calendar
• ChartBar
• ChartPie
• DynamicContent
• Grid
• Lanes
• List
• MainNavigation
• Tabs
• RecordLookup

Usage in Services

Metadata Service

import { 
  SUPPORTED_FIELD_TYPES,
  fieldTypeRequiresColumn,
  getPostgresColumnType
} from 'forge-database-utils';
import { body } from 'express-validator';

// Validation
export const validateCreateField = [
  body('field_type')
    .isIn(SUPPORTED_FIELD_TYPES)
    .withMessage('field_type must be a supported field type'),
];

// Schema management
if (fieldTypeRequiresColumn(fieldType)) {
  const columnType = getPostgresColumnType(fieldType, fieldTypeProperties);
  await schemaManager.addColumn(dbClient, tableName, columnName, columnType);
}

UI Service

import { 
  getSupportedFieldTypes, 
  isSupportedFieldType,
  getPostgresColumnType
} from 'forge-database-utils';

// Get field types for a dropdown
const fieldTypeOptions = getSupportedFieldTypes();

// Validate user input
if (!isSupportedFieldType(userInput)) {
  throw new Error('Invalid field type');
}

// Display column type information
const columnType = getPostgresColumnType('Email');
console.log(`This field will use column type: ${columnType}`);

Development

# Build the package
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

License

MIT