date-form v0.2.0

date-form

Customizable date formatter with builtin presets.

npm

npm install date-form

yarn

yarn add date-form

Usage

Each preset listed below contains their own set of codes used for formatting. Each code will be replaced with its corresponding value. For example, the H code will be replaced with the hour.

With StrfDate

This preset is based off the strftime function from the c language and is interchangeable with it. It's also the same format used for python and ruby as well as GNU's date util.

import { StrfDate } from 'date-form';

console.log(StrfDate.format('%m/%d/%Y, %H:%M')); // 01/15/2022, 13:15
console.log(StrfDate.format('%-I:%M:%S %p', new Date('2020-01-01T15:42:19'))); // 3:42:19 PM

See the StrfDate Reference section for available formats.

With ExpressDate

This preset is a more expressive alternative to StrfDate and is easier to use without a reference.

import { ExpressDate } from 'date-form';

console.log(ExpressDate.format('%MM/%DD/%YYYY, %HH:%mm')); // 01/15/2022, 13:15
console.log(ExpressDate.format('%h:%mm:%ss %A', new Date('2020-01-01T15:42:19'))); // 3:42:19 PM

See the ExpressDate Reference section for available formats.

Flags

A flag lets you modify the output of a code used in your format. Here are the default flags used for both StrfDate and ExpressDate:

Padding

You can override the amount of padding used for a code by putting a number where the flags go, in between the % symbol and the code's letter. For example, you can use %4H to pad the output of the code with up to four zeros. If you did %_4h then the output would be padding with up to four spaces. Flags and pads do not need to be in a specific order. The only restriction is that the 0 flag should not be used right after the pad.

Caching

If you are constantly using the same format with different dates you can cache the format for the next run.

Use parseFormat to save the format.

const format = ExpressDate.parseFormat('%h:%mm:%ss %A');

Use applyFormat to use the format with a date.

setInterval(() => {
  console.log(ExpressDate.applyFormat(format, new Date()));
}, 1000);

Custom Preset

To create your own preset, extend the DateForm from this package. A preset involves defining the following components:

Codes

The codes are defined within your class as a static property.

import { DateForm, Codes } from 'date-form';

class MyDate extends DateForm {
  static codes: Codes = {
    h: { gen: (date) => date.getHours(), flag: '0' },
    m: { gen: (date) => date.getMinutes(), flag: '0', pad: 2 },
  };
}

This example defines a simple preset that lets you put the hours and the minutes in your format with the h and m codes respectively. The gen method within each code's object passes in the date as a parameter and the return value is used as the output. The flag property specifies the default flag used for the code. This is generally 0 for numbers and _ for words. The pad property specifies the default amount of padding for the code. In the example, the h code has a default flag of 0 but will not be padded automatically. The m code specifies both fields and will be padded automatically with zeros up to two digits.

Flags

The flags are also defined as a static property in your preset's class.

import { DateForm, Flags } from 'date-form';

class MyDate extends DateForm {
  static flags: Flags = {
    ...DateForm.flags,
    '*': '*',
    '!': (str, pad) => str.padEnd(pad ?? 0, '!'),
  };
}

This example extends the default flags with two extra flags. A * flag which pads a code with *'s and a ! flag which right pads the code with !'s. When a flag is just a string, it will automatically pad the start of the code. When a flag is a function, the code's output and padding are passed in as parameters. The return of the flag's function replaces the code's output.

Matches

Their are several regular expressions in a preset that can be modified.

import { DateForm } from 'date-form';

class MyDate extends DateForm {
  static codeMatch: RegExp = /^%([^%a-z]*)([%a-z]+)/i;
  static flagMatch: RegExp = /^([^%a-z])/i;
  static padMatch: RegExp = /^([1-9]\d*)/;
}

The codeMatch expression is used to find a code within a date format. The first match group is for flags and padding and is passed into the other regular expressions. The second match group is the code's ID. The flagMatch expression is used to search for flags within the first group from the first expression. The padMatch expression is used to search for pad specifiers within that same group.

The example shown above is used as the default values, you only need to specify these properties if you want to change them.

StrfDate Reference

ExpressDate Reference