or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

datetime.mdduration.mdindex.mdinfo-settings.mdinterval.mdzones.md
tile.json

tessl/npm-luxon

Immutable date wrapper library for JavaScript with comprehensive date/time manipulation, timezone support, and internationalization capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/luxon@2.5.x

To install, run

npx @tessl/cli install tessl/npm-luxon@2.5.0

index.mddocs/

Luxon

Luxon is a comprehensive JavaScript library for working with dates and times, designed as a modern successor to Moment.js. It provides immutable DateTime, Duration, and Interval classes with extensive timezone support, internationalization, and parsing/formatting capabilities.

Package Information

  • Package Name: luxon
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install luxon

Core Imports

import { 
  DateTime, 
  Duration, 
  Interval, 
  Info, 
  Settings, 
  Zone,
  FixedOffsetZone,
  IANAZone,
  SystemZone,
  InvalidZone,
  VERSION,
  lowOrderMatrix
} from "luxon";

For CommonJS:

const { 
  DateTime, 
  Duration, 
  Interval, 
  Info, 
  Settings, 
  Zone,
  FixedOffsetZone,
  IANAZone,
  SystemZone,
  InvalidZone,
  VERSION,
  lowOrderMatrix
} = require("luxon");

Basic Usage

import { DateTime, Duration } from "luxon";

// Create current DateTime
const now = DateTime.now();

// Create specific dates
const dt = DateTime.local(2023, 10, 25, 14, 30);
const utcTime = DateTime.utc(2023, 10, 25, 14, 30);

// Parse from strings
const fromISO = DateTime.fromISO("2023-10-25T14:30:00");
const fromFormat = DateTime.fromFormat("25/10/2023", "dd/MM/yyyy");

// Format dates
console.log(dt.toISO()); // "2023-10-25T14:30:00.000-07:00"
console.log(dt.toFormat("yyyy LLL dd")); // "2023 Oct 25"

// Work with durations
const duration = Duration.fromObject({ hours: 2, minutes: 30 });
const later = dt.plus(duration);

// Date arithmetic
const diff = later.diff(dt, 'minutes');
console.log(diff.minutes); // 150

Architecture

Luxon is built around several key immutable classes:

  • DateTime: Primary date/time class with comprehensive formatting, parsing, and manipulation methods
  • Duration: Represents time periods with units from milliseconds to years
  • Interval: Represents time ranges between two DateTimes with set operations
  • Zone Classes: Multiple timezone implementations (IANA, fixed offset, system, invalid)
  • Info: Static utility class for locale and timezone information
  • Settings: Global configuration for default timezone, locale, and behavior

All classes follow an immutable pattern where operations return new instances rather than modifying existing ones.

Capabilities

Date and Time Manipulation

Core functionality for creating, parsing, formatting, and manipulating dates and times with full timezone and locale support.

class DateTime {
  // Factory methods
  static now(): DateTime;
  static local(year?, month?, day?, hour?, minute?, second?, millisecond?, opts?): DateTime;
  static utc(year?, month?, day?, hour?, minute?, second?, millisecond?, opts?): DateTime;
  static fromISO(text: string, opts?): DateTime;
  static fromFormat(text: string, fmt: string, opts?): DateTime;
  
  // Core properties
  year: number;
  month: number;
  day: number;
  hour: number;
  minute: number;
  second: number;
  
  // Manipulation
  plus(duration: Duration): DateTime;
  minus(duration: Duration): DateTime;
  set(values: object): DateTime;
  
  // Formatting
  toISO(opts?): string;
  toFormat(fmt: string, opts?): string;
  toLocaleString(formatOpts?, opts?): string;
}

DateTime API

Duration and Time Periods

Represents and manipulates time periods with support for multiple units and conversion between different time representations.

class Duration {
  static fromObject(obj: object, opts?): Duration;
  static fromISO(text: string, opts?): Duration;
  static fromMillis(count: number, opts?): Duration;
  
  // Properties
  years: number;
  months: number;
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  milliseconds: number;
  
  // Operations
  plus(duration: Duration): Duration;
  minus(duration: Duration): Duration;
  as(unit: string): number;
  shiftTo(...units: string[]): Duration;
}

Duration API

Time Intervals and Ranges

Represents time ranges between two DateTimes with support for set operations, splitting, and interval relationships.

class Interval {
  static fromDateTimes(start: DateTime, end: DateTime): Interval;
  static after(start: DateTime, duration: Duration): Interval;
  static before(end: DateTime, duration: Duration): Interval;
  
  start: DateTime;
  end: DateTime;
  
  // Relationships
  contains(dateTime: DateTime): boolean;
  overlaps(other: Interval): boolean;
  intersection(other: Interval): Interval;
  union(other: Interval): Interval;
  
  // Operations
  length(unit?: string): number;
  splitBy(duration: Duration): Interval[];
  toDuration(unit?: string): Duration;
}

Interval API

Timezone Management

Comprehensive timezone support including IANA timezone database, fixed offset zones, and system timezone handling.

abstract class Zone {
  abstract type: string;
  abstract name: string;
  abstract offset(ts: number): number;
}

class IANAZone extends Zone {
  static create(name: string): IANAZone;
  static isValidZone(zone: string): boolean;
}

class FixedOffsetZone extends Zone {
  static instance(offset: number): FixedOffsetZone;
  static utcInstance: FixedOffsetZone;
}

Timezone API

Locale and Settings

Global configuration and locale information utilities for customizing behavior and accessing internationalization data.

class Settings {
  static defaultZone: Zone;
  static defaultLocale: string;
  static throwOnInvalid: boolean;
}

class Info {
  static months(length?: string, opts?): string[];
  static weekdays(length?: string, opts?): string[];
  static isValidIANAZone(zone: string): boolean;
  static features(): object;
}

Info & Settings API

Types

interface DateTimeOptions {
  zone?: string | Zone;
  locale?: string;
  numberingSystem?: string;
  outputCalendar?: string;
}

interface DurationOptions {
  locale?: string;
  numberingSystem?: string;
  conversionAccuracy?: string;
}

interface ToISOOptions {
  suppressMilliseconds?: boolean;
  suppressSeconds?: boolean;
  includeOffset?: boolean;
  format?: string;
}

interface ValidationError {
  reason: string;
  explanation?: string;
}

Constants

/**
 * Library version string
 */
const VERSION: string; // "2.5.2"

/**
 * Time unit conversion matrix for precise duration calculations
 * Contains conversion factors between time units (weeks, days, hours, minutes, seconds, milliseconds)
 */
const lowOrderMatrix: object;