ResourcefulDateTimeType

The ResourcefulDateTimeType class provides ISO 8601 date-time validation and schema generation for timestamp fields. It automatically formats values as date-time for OpenAPI compatibility and ensures proper date-time handling.

For complete API reference, see ResourcefulDateTimeType.

Overview

ResourcefulDateTimeType is designed for date-time values, supporting:

• ISO 8601 Format: Automatic date-time format for OpenAPI schemas
• Timezone Support: Full timezone-aware date-time handling
• Type Safety: Full TypeScript support with validated configuration
• Common Modifiers: Support for nullable, readOnly, and writeOnly properties

Basic Usage

Simple DateTime Validation

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

// Basic date-time type
const timestampType = ResourcefulDateTimeType()

// Nullable date-time
const optionalTimestampType = ResourcefulDateTimeType({
  nullable: true
})

With Decorators

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

class Article extends compose(BaseModel, withResourceful({ name: 'Article' })) {
  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      readOnly: true
    }),
    autoCreate: true
  })
  declare createdAt: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      readOnly: true
    }),
    autoCreate: true,
    autoUpdate: true
  })
  declare updatedAt: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare publishedAt: DateTime | null
}

Configuration Options

No Specific Options

ResourcefulDateTimeType has no type-specific configuration options as it follows the ISO 8601 date-time format standard.

// Simple date-time - no additional configuration needed
const basicType = ResourcefulDateTimeType()

// The empty object is optional
const explicitType = ResourcefulDateTimeType({})

Common Modifiers

Nullable DateTimes

const nullableDateTimeType = ResourcefulDateTimeType({
  nullable: true
})

@resourcefulColumn.dateTime({
  type: nullableDateTimeType
})
declare optionalTimestamp: DateTime | null

Read-Only DateTimes

const readOnlyType = ResourcefulDateTimeType({
  readOnly: true
})

@resourcefulColumn.dateTime({
  type: readOnlyType,
  autoCreate: true
})
declare createdAt: DateTime

Common Patterns

Audit Timestamps

class AuditableModel extends compose(BaseModel, withResourceful({ name: 'AuditableModel' })) {
  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      readOnly: true
    }),
    autoCreate: true
  })
  declare createdAt: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      readOnly: true
    }),
    autoCreate: true,
    autoUpdate: true
  })
  declare updatedAt: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true,
      readOnly: true
    })
  })
  declare deletedAt: DateTime | null
}

Content Management

class BlogPost extends compose(BaseModel, withResourceful({ name: 'BlogPost' })) {
  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare publishedAt: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare scheduledAt: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare archivedAt: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      readOnly: true
    }),
    autoCreate: true
  })
  declare createdAt: DateTime
}

Event Scheduling

class Event extends compose(BaseModel, withResourceful({ name: 'Event' })) {
  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType(),
    nullable: false
  })
  declare startTime: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType(),
    nullable: false
  })
  declare endTime: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare registrationDeadline: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare cancellationDeadline: DateTime | null
}

Advanced Examples

Subscription Management

class Subscription extends compose(BaseModel, withResourceful({ name: 'Subscription' })) {
  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType(),
    nullable: false
  })
  declare startDate: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare endDate: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare trialEndDate: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare nextBillingDate: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare cancelledAt: DateTime | null
}

Order Processing

class Order extends compose(BaseModel, withResourceful({ name: 'Order' })) {
  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      readOnly: true
    }),
    autoCreate: true
  })
  declare orderedAt: DateTime

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare confirmedAt: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare shippedAt: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare deliveredAt: DateTime | null

  @resourcefulColumn.dateTime({
    type: ResourcefulDateTimeType({
      nullable: true
    })
  })
  declare estimatedDelivery: DateTime | null
}

OpenAPI Schema Generation

ResourcefulDateTimeType generates OpenAPI 3.0 schemas with date-time format:

const dateTimeType = ResourcefulDateTimeType()

// Generated OpenAPI schema:
{
  "type": "string",
  "format": "date-time"
}

// With nullable:
const nullableType = ResourcefulDateTimeType({ nullable: true })
// Generated schema:
{
  "type": "string",
  "format": "date-time",
  "nullable": true
}

Best Practices

1. Use ISO 8601 format: Always store and transmit dates in ISO 8601 format
2. Handle timezones properly: Store dates in UTC when possible
3. Use nullable for optional dates: Mark optional timestamps as nullable
4. Mark system timestamps as read-only: Created/updated timestamps should be read-only
5. Consider date vs datetime: Use ResourcefulDateType for date-only values
6. Validate date ranges: Ensure start dates are before end dates in business logic
7. Use consistent naming: Follow conventions like createdAt, updatedAt, publishedAt
8. Handle null values: Properly handle null dates in your application logic
9. Consider default values: Set appropriate defaults for nullable date fields
10. Document timezone assumptions: Make timezone handling clear in your API documentation

Common DateTime Field Names

Audit Fields

• createdAt, updatedAt, deletedAt
• modifiedAt, archivedAt, restoredAt

Scheduling Fields

• startDate, endDate, scheduledAt
• publishedAt, expiresAt, availableFrom

Process Tracking

• submittedAt, approvedAt, rejectedAt
• processedAt, completedAt, cancelledAt

Business Events

• orderedAt, shippedAt, deliveredAt
• billedAt, paidAt, refundedAt