@nhtio/lucid-resourceful

Appearance

ResourcefulStringType ​

The ResourcefulStringType class provides comprehensive string validation and schema generation for text-based fields. It supports length constraints, pattern matching, format specifications, and enumeration validation based on OpenAPI 3.0 specifications.

For complete API reference, see ResourcefulStringType.

Overview ​

ResourcefulStringType is the most versatile data type, supporting:

  • Length Validation: Configurable minimum and maximum length constraints
  • Pattern Matching: Regular expression validation for complex text patterns
  • Format Specification: OpenAPI format hints for specialized string types
  • Enumeration: Restrict values to a predefined set of valid strings
  • Type Safety: Full TypeScript support with validated configuration options

Basic Usage ​

Simple String Validation ​

typescript
import { ResourcefulStringType } from '@nhtio/lucid-resourceful/definitions'

// Basic string with length constraints
const nameType = ResourcefulStringType({
  minLength: 1,
  maxLength: 100
})

// String with pattern validation
const usernameType = ResourcefulStringType({
  minLength: 3,
  maxLength: 30,
  pattern: '^[a-zA-Z0-9_]+$'
})

With Decorators ​

typescript
import { resourcefulColumn } from '@nhtio/lucid-resourceful'

class User extends compose(BaseModel, withResourceful({ name: 'User' })) {
  @resourcefulColumn.string({
    type: ResourcefulStringType({ minLength: 2, maxLength: 50 }),
    nullable: false
  })
  declare name: string

  @resourcefulColumn.string({
    type: ResourcefulStringType({
      minLength: 5,
      maxLength: 100,
      pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'
    }),
    nullable: false
  })
  declare email: string
}

Configuration Options ​

Required Options ​

minLength ​

  • Type: number
  • Required: Yes

Minimum number of characters required in the string value.

typescript
const shortStringType = ResourcefulStringType({
  minLength: 1,
  maxLength: 10
})

maxLength ​

  • Type: number
  • Required: Yes

Maximum number of characters allowed in the string value.

typescript
const limitedStringType = ResourcefulStringType({
  minLength: 0,
  maxLength: 255
})

Optional Configuration ​

pattern ​

  • Type: string
  • Optional: Yes

Regular expression pattern that the string value must match.

typescript
// Email pattern validation
const emailType = ResourcefulStringType({
  minLength: 5,
  maxLength: 100,
  pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'
})

// Phone number pattern
const phoneType = ResourcefulStringType({
  minLength: 10,
  maxLength: 15,
  pattern: '^\\+?[1-9]\\d{1,14}$'
})

format ​

  • Type: ResourcefulStringFormat | string
  • Optional: Yes

OpenAPI format specification for the string. Supports predefined formats and custom format strings.

Predefined Formats:

  • 'password' - Password strings (typically hidden in UI)
  • 'byte' - Base64-encoded strings
typescript
// Password field
const passwordType = ResourcefulStringType({
  minLength: 8,
  maxLength: 128,
  format: 'password'
})

// Base64 encoded data
const encodedType = ResourcefulStringType({
  minLength: 1,
  maxLength: 1000,
  format: 'byte'
})

// Custom format
const customType = ResourcefulStringType({
  minLength: 1,
  maxLength: 50,
  format: 'custom-identifier'
})

enum ​

  • Type: string[]
  • Optional: Yes

Array of allowed string values for enumeration validation.

typescript
// Status enumeration
const statusType = ResourcefulStringType({
  minLength: 1,
  maxLength: 20,
  enum: ['draft', 'published', 'archived', 'deleted']
})

// Role enumeration
const roleType = ResourcefulStringType({
  minLength: 1,
  maxLength: 15,
  enum: ['admin', 'user', 'moderator']
})

Common Modifiers ​

All base interface modifiers are supported:

typescript
// Read-only string (like auto-generated IDs)
const readOnlyType = ResourcefulStringType({
  minLength: 1,
  maxLength: 36,
  readOnly: true
})

// Nullable string
const optionalType = ResourcefulStringType({
  minLength: 0,
  maxLength: 100,
  nullable: true
})

// Write-only string (like passwords)
const secretType = ResourcefulStringType({
  minLength: 8,
  maxLength: 128,
  writeOnly: true,
  format: 'password'
})

Common Patterns ​

Email Validation ​

typescript
const emailType = ResourcefulStringType({
  minLength: 5,
  maxLength: 254,
  pattern: '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'
})

@resourcefulColumn.string({
  type: emailType,
  nullable: false
})
declare email: string

URL Validation ​

typescript
const urlType = ResourcefulStringType({
  minLength: 1,
  maxLength: 2000,
  pattern: '^https?:\\/\\/(www\\.)?[-a-zA-Z0-9@:%._\\+~#=]{1,256}\\.[a-zA-Z0-9()]{1,6}\\b([-a-zA-Z0-9()@:%_\\+.~#?&//=]*)$'
})

@resourcefulColumn.string({
  type: urlType,
  nullable: true
})
declare website: string

Slug/Identifier Validation ​

typescript
const slugType = ResourcefulStringType({
  minLength: 1,
  maxLength: 100,
  pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$'
})

@resourcefulColumn.string({
  type: slugType,
  nullable: false
})
declare slug: string

UUID Validation ​

typescript
const uuidType = ResourcefulStringType({
  minLength: 36,
  maxLength: 36,
  pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$'
})

@resourcefulColumn.string({
  type: uuidType,
  nullable: false
})
declare uuid: string

Color Code Validation ​

typescript
const hexColorType = ResourcefulStringType({
  minLength: 4,
  maxLength: 7,
  pattern: '^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$'
})

@resourcefulColumn.string({
  type: hexColorType,
  nullable: true
})
declare color: string

Status Enumeration ​

typescript
const orderStatusType = ResourcefulStringType({
  minLength: 1,
  maxLength: 20,
  enum: [
    'pending',
    'confirmed', 
    'processing',
    'shipped',
    'delivered',
    'cancelled',
    'refunded'
  ]
})

@resourcefulColumn.string({
  type: orderStatusType,
  nullable: false
})
declare status: string

Password Fields ​

typescript
const passwordType = ResourcefulStringType({
  minLength: 8,
  maxLength: 128,
  format: 'password',
  writeOnly: true,
  pattern: '^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]+'
})

@resourcefulColumn.string({
  type: passwordType,
  nullable: false
})
declare password: string

Multi-language Content ​

typescript
const contentType = ResourcefulStringType({
  minLength: 0,
  maxLength: 10000,
  nullable: true
})

@resourcefulColumn.string({
  type: contentType,
  nullable: true
})
declare description: string

@resourcefulColumn.string({
  type: contentType,
  nullable: true
})
declare descriptionEs: string

Advanced Examples ​

Social Media Handles ​

typescript
const twitterHandleType = ResourcefulStringType({
  minLength: 1,
  maxLength: 15,
  pattern: '^[A-Za-z0-9_]{1,15}$'
})

const instagramHandleType = ResourcefulStringType({
  minLength: 1,
  maxLength: 30,
  pattern: '^[a-zA-Z0-9._]{1,30}$'
})

class SocialProfile extends compose(BaseModel, withResourceful({ name: 'SocialProfile' })) {
  @resourcefulColumn.string({
    type: twitterHandleType,
    nullable: true
  })
  declare twitterHandle: string

  @resourcefulColumn.string({
    type: instagramHandleType,
    nullable: true
  })
  declare instagramHandle: string
}

Product Codes and SKUs ​

typescript
const skuType = ResourcefulStringType({
  minLength: 3,
  maxLength: 20,
  pattern: '^[A-Z0-9-]+$'
})

const barcodeType = ResourcefulStringType({
  minLength: 8,
  maxLength: 13,
  pattern: '^[0-9]+$'
})

class Product extends compose(BaseModel, withResourceful({ name: 'Product' })) {
  @resourcefulColumn.string({
    type: skuType,
    nullable: false
  })
  declare sku: string

  @resourcefulColumn.string({
    type: barcodeType,
    nullable: true
  })
  declare barcode: string
}

Geographic Data ​

typescript
const countryCodeType = ResourcefulStringType({
  minLength: 2,
  maxLength: 2,
  pattern: '^[A-Z]{2}$',
  enum: ['US', 'CA', 'GB', 'DE', 'FR', 'AU', 'JP'] // Add more as needed
})

const timezoneType = ResourcefulStringType({
  minLength: 1,
  maxLength: 50,
  pattern: '^[A-Za-z]+\\/[A-Za-z_]+$'
})

class Location extends compose(BaseModel, withResourceful({ name: 'Location' })) {
  @resourcefulColumn.string({
    type: countryCodeType,
    nullable: false
  })
  declare countryCode: string

  @resourcefulColumn.string({
    type: timezoneType,
    nullable: true
  })
  declare timezone: string
}

Version Numbers ​

typescript
const semverType = ResourcefulStringType({
  minLength: 5,
  maxLength: 20,
  pattern: '^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$'
})

@resourcefulColumn.string({
  type: semverType,
  nullable: false
})
declare version: string

Validation Examples ​

Complex Text Validation ​

typescript
class Article extends compose(BaseModel, withResourceful({ name: 'Article' })) {
  // Title with reasonable constraints
  @resourcefulColumn.string({
    type: ResourcefulStringType({
      minLength: 1,
      maxLength: 200
    }),
    nullable: false
  })
  declare title: string

  // Content with large text support
  @resourcefulColumn.string({
    type: ResourcefulStringType({
      minLength: 0,
      maxLength: 100000
    }),
    nullable: true
  })
  declare content: string

  // Tags as comma-separated string
  @resourcefulColumn.string({
    type: ResourcefulStringType({
      minLength: 0,
      maxLength: 500,
      pattern: '^[a-zA-Z0-9, -]*$'
    }),
    nullable: true
  })
  declare tags: string

  // Publication status
  @resourcefulColumn.string({
    type: ResourcefulStringType({
      minLength: 1,
      maxLength: 15,
      enum: ['draft', 'review', 'published', 'archived']
    }),
    nullable: false
  })
  declare status: string
}

OpenAPI Schema Generation ​

ResourcefulStringType generates comprehensive OpenAPI 3.0 schemas:

typescript
const stringType = ResourcefulStringType({
  minLength: 1,
  maxLength: 100,
  pattern: '^[a-zA-Z0-9]+$',
  format: 'custom'
})

// Generated OpenAPI schema:
{
  "type": "string",
  "minLength": 1,
  "maxLength": 100,
  "pattern": "^[a-zA-Z0-9]+$",
  "format": "custom"
}

Best Practices ​

  1. Set reasonable length limits: Prevent abuse while allowing legitimate use cases
  2. Use specific patterns: Write clear, tested regular expressions for validation
  3. Validate patterns thoroughly: Test regex patterns with various inputs
  4. Use enums for fixed sets: Prefer enums over patterns for known value sets
  5. Consider database constraints: Align string lengths with database column limits
  6. Use appropriate formats: Leverage OpenAPI formats for better documentation
  7. Document complex patterns: Comment complex regular expressions for maintenance
  8. Handle internationalization: Consider Unicode and multi-byte characters
  9. Validate email carefully: Use established email validation patterns
  10. Security considerations: Sanitize and validate user input appropriately

Common Validation Patterns ​

Email Addresses ​

regex
^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Phone Numbers (International) ​

regex
^\+?[1-9]\d{1,14}$

URLs (HTTP/HTTPS) ​

regex
^https?:\/\/(www\.)?[-a-zA-Z0-9@:%._\+~#=]{1,256}\.[a-zA-Z0-9()]{1,6}\b([-a-zA-Z0-9()@:%_\+.~#?&//=]*)$

UUID v4 ​

regex
^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Slug/URL-safe strings ​

regex
^[a-z0-9]+(?:-[a-z0-9]+)*$

Hex color codes ​

regex
^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$

Copyright © 2025-present New Horizon Technology LTD