@burglekitt/gmt/skills/_artifacts/domain_map.yaml

Temporal-based date and time utilities with timezone support and polyfill integration

# domain_map.yaml
# Generated by skill-domain-discovery
# Library: @burglekitt/gmt
# Version: 1.14.0
# Date: 2026-08-23
# Status: reviewed

library:
  name: '@burglekitt/gmt'
  version: 1.14.0
  repository: https://github.com/burglekitt/gmt.git
  description: Temporal-based date and time utilities with timezone support and polyfill integration
  primary_framework: framework-agnostic

domains:
  - name: Core Date Operations
    slug: core-date-operations
    description: Basic date/time operations using plain (timezone-free) Temporal types
  - name: Zoned Date Operations
    slug: zoned-date-operations
    description: IANA timezone-aware date operations
  - name: Conversion
    slug: conversion
    description: Converting between temporal types, unix time, and UTC
  - name: Integration
    slug: integration
    description: Integrating gmt with application frameworks and linting tools

  - name: Interval Operations
    slug: interval-operations
    description: Range math over two-point intervals — validation, containment, overlap, intersection, union, difference, xor, adjacency, engulfing, splitting by duration unit, and counting calendar-unit boundaries across plain, zoned, unix, and utc namespaces

skills:
  - name: Get Current Date/Time
    slug: get-current
    domain: core-date-operations
    description: Get the current date, time, or timestamp as ISO 8601 strings
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - getNow
      - getToday
      - getSystemTimeZone
      - getTimeZones
      - getUnixNow
      - getUtcNow
    tasks:
      - Get current date as ISO string
      - Get current time as ISO string
      - Get current unix timestamp
      - Get current UTC time
      - Get system timezone name
      - Get all available IANA timezones

  - name: Parse Date/Time
    slug: parse-date-time
    domain: core-date-operations
    description: Parse individual components from date/time strings; also decode fixed interchange grammars (email Date headers, HTTP headers, SQL datetime literals, RFC 3339)
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - parseYearFromDate
      - parseMonthFromDate
      - parseDayFromDate
      - parseHourFromTime
      - parseMinuteFromTime
      - parseSecondFromTime
      - parseRfc2822
      - parseHttp
      - parseSql
      - parseRfc3339
    tasks:
      - Extract year from date string
      - Extract month from date string
      - Extract day from date string
      - Parse time components
      - Decode an email Date: header (RFC 2822/5322)
      - Decode an HTTP Last-Modified/Date/Expires header (RFC 7231)
      - Decode a SQL datetime literal
      - Decode a strict RFC 3339 datetime string

  - name: Format Date/Time
    slug: format-date-time
    domain: core-date-operations
    description: Format date/time values for display with locale support; includes standalone locale calendar-name lookups and fixed-grammar named machine formats (email, HTTP, SQL, RFC 3339)
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - formatDate
      - formatTime
      - formatDateTime
      - formatRelativeDate
      - formatRelativeTime
      - formatRelativeDateTime
      - getLocaleEraNames
      - getLocaleMonthNames
      - getLocaleWeekdayNames
      - getLocaleMeridiems
      - formatRfc2822
      - formatHttp
      - formatSql
      - formatRfc3339
    tasks:
      - Format date for display
      - Format time for display
      - Format datetime with locale
      - Produce an email Date: header (RFC 2822/5322)
      - Produce an HTTP Last-Modified/Date/Expires header (RFC 7231)
      - Produce a SQL datetime literal
      - Produce a strict RFC 3339 datetime string
      - Format relative date ("yesterday", "in 2 days")
      - Format relative time ("30 minutes ago")
      - Format relative datetime with reference
      - Get locale era names (getLocaleEraNames)
      - Get locale month names (getLocaleMonthNames)
      - Get locale weekday names (getLocaleWeekdayNames)
      - Get locale AM/PM labels (getLocaleMeridiems)

  - name: Format Relative Time
    slug: format-relative-time
    domain: core-date-operations
    description: Produce human-friendly relative strings across plain, zoned, unix, and utc values
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - formatRelativeDate
      - formatRelativeTime
      - formatRelativeDateTime
      - formatRelativeZoned
      - formatRelativeUnix
      - formatRelativeUtc
    tasks:
      - Pick the correct relative formatter for an input shape
      - Configure numeric and style options
      - Override largestUnit for explicit unit bucketing
      - Format DST-safe relative spans for zoned values

  - name: Calculate Dates
    slug: calculate-dates
    domain: core-date-operations
    description: Add or subtract time from dates; add*/subtract* accept an optional overflow option, addBusinessDays/subtractBusinessDays skip weekends for Mon–Fri arithmetic, diff* accept optional rounding options, clampDate restricts a date to a range, closestDateTo finds the nearest candidate by calendar distance, getLocaleStartOfWeek/getLocaleEndOfWeek compute locale-driven week boundaries
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - addBusinessDays
      - addDays
      - addMonths
      - addYears
      - subtractBusinessDays
      - subtractTime
      - clampDate
      - closestDateTo
      - overflow
      - smallestUnit
      - roundingIncrement
      - roundingMode
      - getLocaleStartOfWeek
      - getLocaleEndOfWeek
      - cycleDate
      - cycleDateTime
      - cycleTime
    tasks:
      - Add days to a date
      - Subtract months from a date
      - Calculate date difference
      - Add or subtract business days, skipping weekends
      - Reject out-of-range add/subtract results instead of clamping
      - Round a diff result to a coarser unit
      - Clamp a date to a min/max range
      - Find the nearest date to a target from a list of candidates
      - Get locale-aware week boundaries instead of ISO-Monday defaults
      - Cycle (wrap) a single field without changing its neighbors, e.g. for datepicker segment editing

  - name: Durations
    slug: durations
    domain: core-date-operations
    description: Parse, validate, combine, rebalance, and format ISO 8601 duration strings; bridge diff* functions to duration strings
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - isValidDuration
      - parseDuration
      - addDuration
      - subtractDuration
      - normalizeDuration
      - formatDuration
      - diffDateAsDuration
      - diffDateTimeAsDuration
      - diffZonedAsDuration
      - diffUnixAsDuration
      - diffUtcAsDuration
    tasks:
      - Validate an ISO 8601 duration string
      - Normalize a duration string
      - Round a duration string's output precision
      - Combine two duration strings by addition or subtraction
      - Roll a duration string's small units into larger ones
      - Format a duration string as human-readable, locale-aware text
      - Get the difference between two dates/times as an ISO duration string instead of a single-unit number

  - name: Compare Dates
    slug: compare-dates
    domain: core-date-operations
    description: Compare date values for ordering; use isWeekend/isZonedWeekend for locale-aware weekend checks and getLocaleDayOfWeek/getLocaleZonedDayOfWeek for locale-relative day-of-week indices
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - isAfterDate
      - isBeforeDate
      - areDatesEqual
      - isWeekend
      - isZonedWeekend
      - isBusinessDay
      - getLocaleDayOfWeek
      - getLocaleZonedDayOfWeek
    tasks:
      - Check if date is after another
      - Check if date is before another
      - Check date equality
      - Check if a date falls on a weekend (locale-aware)
      - Check if a date falls on a Mon–Fri business day (fixed ISO boundary)
      - Get the locale-relative day-of-week index

  - name: Validate Dates
    slug: validate-dates
    domain: core-date-operations
    description: Validate date/time strings, timezone identifiers, intervals, and ranges; check whether a timezone observes daylight saving time; list DST transition instants for a timezone in a given year; check point-in-interval and interval-in-interval containment; merge overlapping or adjacent intervals; split intervals into sub-intervals by duration unit
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - isValidDate
      - isValidTime
      - isValidDateTime
      - isValidDateInterval
      - isValidTimeInterval
      - isValidDateTimeInterval
      - isValidUtcInterval
      - isValidUnixInterval
      - isValidZonedInterval
      - hasDaylightSaving
      - getDstTransitions
      - intervalContainsDate
      - intervalContainsTime
      - intervalContainsDateTime
      - intervalContainsUtc
      - intervalContainsUnix
      - intervalContainsZoned
      - intervalUnionDate
      - intervalUnionTime
      - intervalUnionDateTime
      - intervalUnionUtc
      - intervalUnionUnix
      - intervalUnionZoned
      - splitIntervalByUnitDate
      - splitIntervalByUnitTime
      - splitIntervalByUnitDateTime
      - splitIntervalByUnitUtc
      - splitIntervalByUnitUnix
      - splitIntervalByUnitZoned
      - isValidDateRange
      - isValidDateTimeRange
      - isValidTimeRange
      - isValidUtcRange
      - isValidUnixRange
      - isValidZonedRange
    tasks:
      - Validate ISO date string
      - Validate time string
      - Validate datetime string
      - Validate date interval (start <= end)
      - Validate time interval
      - Validate datetime interval
      - Validate UTC interval
      - Validate Unix interval
      - Validate zoned interval
      - Check whether an IANA timezone observes daylight saving time
      - List DST transition instants for a timezone in a given year
      - Check if a point falls within an interval (3-arg)
      - Check if an inner interval is fully contained within an outer interval (4-arg)
      - Merge two overlapping or adjacent intervals into their combined span
      - Split an interval into sub-intervals of amount × unit
      - Validate date range (object-param shape)
      - Validate time range
      - Validate datetime range
      - Validate UTC range
      - Validate Unix range
      - Validate zoned range

  - name: Zoned Date Operations
    slug: zoned-date-ops
    domain: zoned-date-operations
    description: Work with timezone-aware dates and times
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - getZonedNow
      - formatZonedDateTime
      - formatZonedRange
      - formatRelativeZoned
      - isValidTimeZone
      - convertPlainDateTimeToZoned
      - convertZonedToUtc
      - addZoned
      - subtractZoned
      - startOfZoned
      - endOfZoned
      - startOfQuarterForZoned
      - endOfQuarterForZoned
      - mapZonedHoursInDay
      - startOfUnix
      - endOfUnix
      - startOfQuarterForUnix
      - endOfQuarterForUnix
      - getLocaleZonedStartOfWeek
      - getLocaleZonedEndOfWeek
      - getLocaleZonedDayOfWeek
      - clampZoned
      - closestZonedTo
      - cycleZoned
    tasks:
      - Get current time in timezone
      - Format datetime in timezone
      - Format zoned datetime range
      - Format DST-safe relative zoned spans
      - Validate timezone
      - Convert between timezones
      - Add or subtract a duration from a zoned datetime, with overlap-only DST disambiguation control
      - Attach a timezone to a plain datetime with explicit DST disambiguation
      - Jump to the start or end of a unit/quarter/hours-in-day for a zoned or unix timestamp, with full DST disambiguation and offset control
      - Get locale-aware week boundaries for a zoned datetime, with full DST disambiguation and offset control
      - Get the locale-relative day-of-week index for a zoned datetime
      - Clamp a zoned datetime to a min/max range
      - Find the nearest zoned datetime to a target from a list of candidates
      - Cycle (wrap) a single zoned field without changing its neighbors, with full DST disambiguation and offset control

  - name: Convert Temporal Types
    slug: convert-types
    domain: conversion
    description: Convert between plain and zoned (with DST disambiguation control), or unix/utc representations; convertDateToCalendar expresses a date in a non-Gregorian CalendarSystem (gregorian, hebrew, islamic-civil, islamic-tabular, islamic-umalqura, japanese, buddhist, taiwan, persian, indian, ethiopic, ethiopic-amete-alem, coptic)
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - convertPlainDateTimeToZoned
      - convertZonedToPlainDateTime
      - convertUtcToUnix
      - convertUnixToUtc
      - convertDateToCalendar
    tasks:
      - Convert plain to zoned
      - Convert zoned to plain
      - Convert UTC to unix epoch
      - Convert unix to UTC
      - Convert a date to a non-Gregorian calendar system (Hebrew, Islamic civil/tabular/Umm al-Qura, Japanese, Buddhist, Taiwan, Persian, Indian, Ethiopic, Ethiopic Amete Alem, Coptic)

  - name: App Integration
    slug: app-integration
    domain: integration
    description: Integrate gmt with application frameworks
    type: composition
    packages:
      - '@burglekitt/gmt'
    tasks:
      - Create stable cache keys
      - Use with routers
      - Use with table libraries
      - Use with state management

  - name: Lint Package Suggestion
    slug: lint-package-suggestion
    domain: integration
    description: Recommend appropriate lint packages
    type: composition
    packages:
      - '@burglekitt/gmt'
      - '@burglekitt/gmt-eslint'
      - '@burglekitt/gmt-biome'
      - '@burglekitt/gmt-oxlint'
    tasks:
      - Choose ESLint config
      - Choose Biome config
      - Choose Oxlint config

  - name: Issue Creation
    slug: issue-creation
    domain: core-date-operations
    description: Create feature requests with proper details for maintainers
    type: lifecycle
    packages:
      - '@burglekitt/gmt'
    tasks:
      - Report missing functionality
      - Request new methods
      - Include proper context in issues

  - name: PR Contribution
    slug: pr-contribution
    domain: integration
    description: Contribute improvements via pull requests
    type: lifecycle
    packages:
      - '@burglekitt/gmt'
    tasks:
      - Open PR with new method
      - Follow contribution guidelines
      - Add tests with PR

  - name: Interval Operations
    slug: interval-ops
    domain: interval-operations
    description: Range math over two-point intervals — validate, contain, overlap, intersect, union, difference, xor, abut, engulf, construct from a point + duration, split by duration unit, and count calendar-unit boundaries across plain, zoned, unix, and utc
    type: core
    packages:
      - '@burglekitt/gmt'
    covers:
      - isValidDateInterval
      - isValidTimeInterval
      - isValidDateTimeInterval
      - isValidUtcInterval
      - isValidUnixInterval
      - isValidZonedInterval
      - intervalContainsDate
      - intervalContainsTime
      - intervalContainsDateTime
      - intervalContainsUtc
      - intervalContainsUnix
      - intervalContainsZoned
      - intervalsOverlapDate
      - intervalsOverlapTime
      - intervalsOverlapDateTime
      - intervalsOverlapUtc
      - intervalsOverlapUnix
      - intervalsOverlapZoned
      - intervalIntersectionDate
      - intervalIntersectionTime
      - intervalIntersectionDateTime
      - intervalIntersectionUtc
      - intervalIntersectionUnix
      - intervalIntersectionZoned
      - intervalUnionDate
      - intervalUnionTime
      - intervalUnionDateTime
      - intervalUnionUtc
      - intervalUnionUnix
      - intervalUnionZoned
      - intervalDifferenceDate
      - intervalDifferenceTime
      - intervalDifferenceDateTime
      - intervalDifferenceUtc
      - intervalDifferenceUnix
      - intervalDifferenceZoned
      - intervalXorDate
      - intervalXorTime
      - intervalXorDateTime
      - intervalXorUtc
      - intervalXorUnix
      - intervalXorZoned
      - intervalAbutsDate
      - intervalAbutsTime
      - intervalAbutsDateTime
      - intervalAbutsUtc
      - intervalAbutsUnix
      - intervalAbutsZoned
      - intervalEngulfsDate
      - intervalEngulfsTime
      - intervalEngulfsDateTime
      - intervalEngulfsUtc
      - intervalEngulfsUnix
      - intervalEngulfsZoned
      - intervalFromDurationDate
      - intervalFromDurationTime
      - intervalFromDurationDateTime
      - intervalFromDurationUtc
      - intervalFromDurationUnix
      - intervalFromDurationZoned
      - splitIntervalByUnitDate
      - splitIntervalByUnitTime
      - splitIntervalByUnitDateTime
      - splitIntervalByUnitUtc
      - splitIntervalByUnitUnix
      - splitIntervalByUnitZoned
      - intervalCountDate
      - intervalCountTime
      - intervalCountDateTime
      - intervalCountUtc
      - intervalCountUnix
      - intervalCountZoned
    tasks:
      - Validate a start/end interval
      - Check if a point or inner interval is contained
      - Check if two intervals overlap
      - Get the overlapping span of two intervals
      - Merge overlapping or adjacent intervals
      - Subtract one interval from another
      - Get the symmetric difference of two intervals
      - Check if two intervals are exactly adjacent
      - Check if one interval fully contains another
      - Construct an interval from a point and a duration, anchored at either end
      - Split an interval into sub-intervals by duration unit
      - Count how many calendar-unit boundaries an interval crosses

failure_modes: []

tensions: []

cross_references:
  - from: get-current
    to: calculate-dates
    reason: Getting current date is often first step before calculating future/past dates
  - from: convert-types
    to: zoned-date-ops
    reason: Conversions often needed when working with timezones
  - from: issue-creation
    to: new-method-implementation
    reason: Issue is first step; implementation skill guides actual code
  - from: format-date-time
    to: format-relative-time
    reason: Relative formatters cover the same display use case but for human-friendly diff output; switch when the user wants "yesterday" instead of "March 14"
  - from: zoned-date-ops
    to: format-relative-time
    reason: formatRelativeZoned is DST-safe; the relative-time skill explains shared option semantics across all six relative formatters
  - from: calculate-dates
    to: durations
    reason: diff* functions return a single-unit number; the durations skill's *AsDuration siblings return a full multi-unit ISO duration string instead
  - from: calculate-dates
    to: compare-dates
    reason: addBusinessDays/subtractBusinessDays use a fixed ISO Mon–Fri boundary; isBusinessDay checks whether a date is itself a business day before doing arithmetic
  - from: calculate-dates
    to: interval-ops
    reason: splitIntervalByUnit* splits by duration unit; add*/subtract* move a single point by duration — use together for range + arithmetic
  - from: compare-dates
    to: interval-ops
    reason: isBetween* checks a single point; intervalContains* / intervalsOverlap* test whole ranges
  - from: durations
    to: interval-ops
    reason: isValidDuration validates the ISO 8601 duration string that intervalFromDuration* consumes to construct an interval from a single point

gaps: []