Skip to content

feat: add defaultDate option to parse/isValid for partial date string support #124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
knowledgecode merged 4 commits into from
May 6, 2026
Merged

feat: add defaultDate option to parse/isValid for partial date string support #124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
862161f
feat: add defaultDate option to parse/isValid for partial date string…
knowledgecode May 6, 2026
1c0ddeb
test: add tests for defaultDate option in parse() and isValid()
knowledgecode May 6, 2026
a231669
docs: document defaultDate option and add inline interface definitions
knowledgecode May 6, 2026
702ef4c
chore: bump version to 4.5.0 and update dev dependencies
knowledgecode May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/api/format.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,18 @@ For available plugins, see the [`plugins`](#plugins) option in FormatterOptions.

The `FormatterOptions` object allows you to customize the formatting behavior:

```typescript
interface FormatterOptions {
locale?: Locale;
timeZone?: TimeZone | string;
numeral?: Numeral;
calendar?: 'gregory' | 'buddhist';
hour12?: 'h11' | 'h12';
hour24?: 'h23' | 'h24';
plugins?: FormatterPlugin[];
}
```

### locale

**Type**: `Locale`
Expand Down
82 changes: 0 additions & 82 deletions docs/api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,88 +73,6 @@ format(new Date(), 'YYYY年M月D日(ddd) HH:mm', {
// => 2025年8月23日(土) 23:30
```

## Types and Interfaces

### Option Types

#### FormatterOptions

```typescript
interface FormatterOptions {
locale?: Locale; // Locale object for localized formatting
timeZone?: TimeZone | string; // Timezone object or IANA timezone name string
numeral?: Numeral; // Numeral system for number formatting
calendar?: 'gregory' | 'buddhist'; // Calendar system
hour12?: 'h11' | 'h12'; // 12-hour format type
hour24?: 'h23' | 'h24'; // 24-hour format type
}
```

#### ParserOptions

```typescript
interface ParserOptions {
locale?: Locale; // Locale object for localized parsing
timeZone?: TimeZone | string; // Timezone object or IANA timezone name string
numeral?: Numeral; // Numeral system for number parsing
calendar?: 'gregory' | 'buddhist'; // Calendar system
hour12?: 'h11' | 'h12'; // 12-hour format type
hour24?: 'h23' | 'h24'; // 24-hour format type
ignoreCase?: boolean; // Case-insensitive parsing
}
```

## Format Tokens

### Date Tokens

| Token | Meaning | Output Examples |
|--------|----------------------------|-------------------|
| `YYYY` | 4-digit year | 0999, 2015 |
| `YY` | 2-digit year | 99, 01, 15 |
| `Y` | Year without zero padding | 2, 44, 888, 2015 |
| `MMMM` | Full month name | January, December |
| `MMM` | Short month name | Jan, Dec |
| `MM` | Month | 01, 12 |
| `M` | Month without zero padding | 1, 12 |
| `DD` | Day | 02, 31 |
| `D` | Day without zero padding | 2, 31 |

### Time Tokens

| Token | Meaning | Output Examples |
|-------|---------------------------------------------|-----------------|
| `HH` | Hour in 24-hour format | 23, 08 |
| `H` | Hour in 24-hour format without zero padding | 23, 8 |
| `hh` | Hour in 12-hour format | 11, 08 |
| `h` | Hour in 12-hour format without zero padding | 11, 8 |
| `mm` | Minutes | 14, 07 |
| `m` | Minutes without zero padding | 14, 7 |
| `ss` | Seconds | 05, 10 |
| `s` | Seconds without zero padding | 5, 10 |
| `SSS` | 3-digit milliseconds | 753, 022 |
| `SS` | 2-digit milliseconds | 75, 02 |
| `S` | 1-digit milliseconds | 7, 0 |

### Day of Week Tokens

| Token | Meaning | Output Examples |
|--------|---------------------|-----------------|
| `dddd` | Full day name | Friday, Sunday |
| `ddd` | Short day name | Fri, Sun |
| `dd` | Very short day name | Fr, Su |

### AM/PM and Timezone Tokens

| Token | Meaning | Output Examples |
|-------|--------------------------------|-----------------|
| `A` | Uppercase AM/PM | AM, PM |
| `AA` | Uppercase AM/PM (with periods) | A.M., P.M. |
| `a` | Lowercase AM/PM | am, pm |
| `aa` | Lowercase AM/PM (with periods) | a.m., p.m. |
| `Z` | Timezone offset | +0100, -0800 |
| `ZZ` | Timezone offset with colon | +01:00, -08:00 |

## Supported Locales

date-and-time supports 40+ locales. Import only the ones you need:
Expand Down
19 changes: 19 additions & 0 deletions docs/api/isValid.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,6 +72,25 @@ isValid('august 23, 2025', 'MMMM D, YYYY', { ignoreCase: true }); // => true
isValid('August 23, 2025', 'MMMM D, YYYY'); // => true (correct case)
```

### defaultDate Validation

Use `defaultDate` to provide context for validation of partial date strings. The most practical use case is leap year-aware validation of month-day strings.

```typescript
import { isValid } from 'date-and-time';

// Leap day validation — result depends on the year
isValid('02-29', 'MM-DD', { defaultDate: { Y: 2024 } }); // => true (2024 is a leap year)
isValid('02-29', 'MM-DD', { defaultDate: { Y: 2023 } }); // => false (2023 is not a leap year)
isValid('02-29', 'MM-DD'); // => false (default year 1970 is not a leap year)

// Day range validation — depends on both year and month
isValid('29', 'D', { defaultDate: { Y: 2024, M: 2 } }); // => true (Feb 2024 has 29 days)
isValid('31', 'D', { defaultDate: { Y: 2024, M: 4 } }); // => false (April has 30 days)
```

**Note**: Values provided in `defaultDate` are also subject to range validation. For example, an out-of-range `H` value in `defaultDate` will cause `isValid()` to return `false`.

## Advanced Validation Patterns

### Multiple Format Validation
Expand Down
106 changes: 84 additions & 22 deletions docs/api/parse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,22 @@ For available plugins, see the [`plugins`](#plugins) option in ParserOptions.

## ParserOptions

The `ParserOptions` object allows you to customize the parsing behavior:

```typescript
interface ParserOptions {
locale?: Locale;
timeZone?: TimeZone | string;
numeral?: Numeral;
calendar?: 'gregory' | 'buddhist';
hour12?: 'h11' | 'h12';
hour24?: 'h23' | 'h24';
ignoreCase?: boolean;
defaultDate?: ParsedComponents;
plugins?: ParserPlugin[];
}
```

### locale

**Type**: `Locale`
Expand Down Expand Up @@ -220,28 +236,6 @@ parse('August 23, 2568', 'MMMM D, YYYY', { calendar: 'buddhist' });
// => Fri Aug 23 2025 00:00:00 GMT-0700
```

### ignoreCase

**Type**: `boolean`
**Default**: `false`

Enables case-insensitive parsing for text elements.

```typescript
import { parse } from 'date-and-time';

// Case-sensitive (default)
parse('august 23, 2025', 'MMMM D, YYYY');
// => Invalid Date

// Case-insensitive
parse('AUGUST 23, 2025', 'MMMM D, YYYY', { ignoreCase: true });
// => Fri Aug 23 2025 00:00:00 GMT-0700

parse('fri aug 23 2025', 'ddd MMM DD YYYY', { ignoreCase: true });
// => Fri Aug 23 2025 00:00:00 GMT-0700
```

### hour12

**Type**: `"h11" | "h12"`
Expand Down Expand Up @@ -280,6 +274,72 @@ parse('24:30', 'H:mm', { hour24: 'h24' });
// => Thu Jan 01 1970 00:30:00 GMT-0800
```

### ignoreCase

**Type**: `boolean`
**Default**: `false`

Enables case-insensitive parsing for text elements.

```typescript
import { parse } from 'date-and-time';

// Case-sensitive (default)
parse('august 23, 2025', 'MMMM D, YYYY');
// => Invalid Date

// Case-insensitive
parse('AUGUST 23, 2025', 'MMMM D, YYYY', { ignoreCase: true });
// => Fri Aug 23 2025 00:00:00 GMT-0700

parse('fri aug 23 2025', 'ddd MMM DD YYYY', { ignoreCase: true });
// => Fri Aug 23 2025 00:00:00 GMT-0700
```

### defaultDate

**Type**: `ParsedComponents`
**Default**: `{ Y: 1970, M: 1, D: 1, m: 0, s: 0, S: 0 }`

Specifies default values for date/time components that are missing from the format string. This is useful when parsing partial strings such as time-only or month-day formats.

```typescript
interface ParsedComponents {
Y?: number; // Year
M?: number; // Month (1-12)
D?: number; // Day
H?: number; // Hour (24-hour)
A?: number; // Meridiem (0: AM, 1: PM)
h?: number; // Hour (12-hour)
m?: number; // Minute
s?: number; // Second
S?: number; // Millisecond
Z?: number; // Timezone offset in minutes (e.g., UTC+9 = -540)
}
```

**Note**: If `defaultDate.Z` is set, it takes precedence over the `timeZone` option. `Z` is in minutes, using the same sign convention as the `Z` / `ZZ` format tokens (e.g., UTC+9 = `-540`).

```typescript
import { parse } from 'date-and-time';

// Parse time-only string — fill in date from defaultDate
parse('12:30', 'HH:mm', { defaultDate: { Y: 2024, M: 3, D: 15 } });
// => Fri Mar 15 2024 12:30:00

// Parse month-day only — fill in year from defaultDate
parse('03-15', 'MM-DD', { defaultDate: { Y: 2024 } });
// => Fri Mar 15 2024 00:00:00

// Fill in time components for a date-only format
parse('2024-03-15', 'YYYY-MM-DD', { defaultDate: { H: 10, m: 30, s: 45 } });
// => Fri Mar 15 2024 10:30:45

// defaultDate.Z takes precedence over timeZone option
parse('12:30', 'HH:mm', { defaultDate: { Y: 2024, M: 3, D: 15, Z: -540 }, timeZone: 'UTC' });
// => Fri Mar 15 2024 03:30:00 UTC (interpreted as UTC+9; timeZone: 'UTC' is ignored)
```

### plugins

**Type**: `ParserPlugin[]`
Expand Down Expand Up @@ -340,6 +400,8 @@ parse('2025', 'YYYY');
// => Wed Jan 01 2025 00:00:00 GMT-0800
```

To customize these defaults, use the [`defaultDate`](#defaultdate) option.

### Date Range Limitations

The parsable maximum date is `December 31, 9999`, and the minimum date is `January 1, 0001`.
Expand Down
4 changes: 2 additions & 2 deletions docs/api/preparse.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ preparse(dateString, formatString[, options])
|----------------|----------------------------|----------|--------------------------------------------------------------------------|
| `dateString` | `string` | Yes | The date string to parse |
| `formatString` | `string \| CompiledObject` | Yes | Format pattern string or compiled object |
| `options` | `ParserOptions` | No | Parsing options for customization (see [`parse()`](./parse) for details) |
| `options` | `ParserOptions` | No | Parsing options for customization (see [`parse()`](./parse#parseroptions) for details) |

### Returns

Expand Down Expand Up @@ -94,7 +94,7 @@ console.log(result);

## ParserOptions

The `options` parameter accepts the same `ParserOptions` as the [`parse()`](./parse#parseroptions) function. This includes locale, timezone, numeral system, calendar, case sensitivity, and hour format settings. Refer to the parse documentation for complete details on all available options.
The `options` parameter accepts the same `ParserOptions` as the [`parse()`](./parse#parseroptions) function. This includes locale, timezone, numeral system, calendar, case sensitivity, hour format settings, and `defaultDate`. Refer to the parse documentation for complete details on all available options.

## Use Cases

Expand Down
Loading
Loading