Custom Date Parser (date-time-per)

A simple and robust TypeScript-first package to parse custom-formatted date strings (DD Mon YY, HH:mm) into standard JavaScript Date objects.

Features

UTC First: All dates are parsed as UTC to prevent timezone-related bugs.

Robust Error Handling: Throws descriptive errors for invalid inputs.

Smart Year Parsing: Correctly handles two-digit years from 1950 to 2049.

Fully Typed: Written in TypeScript for excellent editor support and type safety.

Installation

Install the package using npm or your favorite package manager:

npm install date-time-per

Usage

Import the functions and use them in your project. Because the parsing function can fail, it's best practice to wrap it in a try...catch block.

Basic Example

import { dateconvert } from 'date-time-per';

result.formattedDate result.formattedTime

try { // 1. Parse the custom string into a Date object const dateObject = parseCustomDate(myDateString);

// 2. The object is a standard JavaScript Date object, parsed in UTC console.log(dateObject); // Expected Output: 2025-06-06T14:25:00.000Z (as a Date object)

// 3. You can format it back to a standard string if needed const isoString = toISO(dateObject); console.log(isoString); // Expected Output: "2025-06-06T14:25:00.000Z"

} catch (error) { console.error("Failed to parse date:", error.message); }

try { const dateObject = parseCustomDate(badDateString); console.log(toISO(dateObject)); } catch (error) { // The error thrown by the package will be caught here console.error("Failed to parse date:", error.message); // Expected Output: Failed to parse date: Invalid format. Expected "DD Mon YY, HH:mm", but received "This is not a date". }

API Reference

parseCustomDate(dateString) Parses a custom date string and converts it into a standard JavaScript Date object.

dateString: string

The date string to parse.

Required Format: "DD Mon YY, HH:mm" (e.g., "06 Jun 25, 14:25")

Returns: Date

A standard JavaScript Date object representing the date and time in UTC.

Throws: Error

If the input is not a string, is empty, or does not match the expected format.

toISO(dateObject) Converts a Date object into a standard ISO 8601 string format.

dateObject: Date

A valid JavaScript Date object.

Returns: string

An ISO 8601 formatted string (e.g., "2025-06-06T14:25:00.000Z").

Throws: Error

If the input is not a valid Date object.

License MIT