dayjs-business-time-extended

v1.2.1

Published

25 days ago

A [Day.js](https://github.com/byndcloud/dayjs-business-time-extended#) plugin that allows you to work with Business Time.

0High
0Medium
0Low

luiz-albuquerque

dayjs date time business time business hours business days working time working hours working days rankmyapp

dayjs-business-time

A Day.js plugin that allows you to work with Business Time.

Fork

This repository is a fork of:

https://github.com/rankmyapp/dayjs-business-time

Original package on npm:

https://www.npmjs.com/package/dayjs-business-time

Roadmap

[x] Calculate the difference in seconds between dates considering business days
[x] Allow configuring time ranges for business days
[x] Fix bug when calculating the next business time
[x] Fix bug when calculating the last business time
[x] Prevent crashes when setting an invalid time range (start > end)
[x] Implement addBusinessSeconds, subtractBusinessSeconds, subtractBusinessTime (in seconds), businessTimeDiff (in seconds), addBusinessSeconds(in seconds)
[x] Consider timezone
[ ] Allow configuring business hours on non-business days (special service shifts).

Business Days
Business Hours
Business Minutes
Customize business days and hours
Customize Holidays to prevent them to be counted as Business Days

Getting Started

Instalation

With NPM

npm i dayjs-business-time

With Yarn

yarn add dayjs-business-time

Usage

NodeJS

// First of all, include dayjs
const dayjs = require('dayjs');

// Then, include dayjs-business-time
const dayjsBusinessTime = require('dayjs-business-time');

// Attach dayjs plugin
dayjs.extend(dayjsBusinessTime);

// Now you have all Business Time methods in dayjs

Typescript

// First of all, include dayjs
import dayjs from 'dayjs';

// Then, include dayjs-business-time
import dayjsBusinessTime from 'dayjs-business-time';

// Attach dayjs plugin
dayjs.extend(dayjsBusinessTime);

// Now you have all Business Time methods in dayjs

Setup

Setting Holidays

By default, holidays are empty!

// Create your holidays array as string array
const holidays: string[] = [
    '2021-01-01',
    '2021-01-25',
    '2021-06-03',
];

// Add holidays to dayjs
dayjs.setHolidays(holidays);

Getting Holidays

const holidays: string[] = dayjs.setHolidays(holidays);

console.log(holidays);
// Output: ['2021-01-01', '2021-01-25', '2021-06-03']

Setting Business Times

By default, Business Times are Monday-Friday, 9am - 5pm, but you can setup as many Business Segments you want in a day

// Create your Business Week definition
const businessTimes: BusinessHoursMap = {
  sunday: null,
  monday: [
    { start: '09:00:00', end: '17:00:00' }
  ],
  tuesday: [
    { start: '09:00:00', end: '12:00:00' },
    { start: '13:00:00', end: '18:00:00' }
  ],
  wednesday: [
    { start: '09:00:00', end: '12:00:00' },
    { start: '13:00:00', end: '16:00:00' },
    { start: '13:00:00', end: '17:00:00' }
  ],
  thursday: [
    { start: '09:00:00', end: '17:00:00' }
  ],
  friday: [
    { start: '09:00:00', end: '17:00:00' }
  ],
  saturday: null,
}

// Set Business Times in dayjs
dayjs.setBusinessTime(businessTimes);

Setting Timezone

Important: Timezone support ensures consistent business time calculations across different system timezones.

By default, all date and time calculations are performed in the system's local timezone. However, when working in distributed environments (e.g., Docker containers with UTC, local machines with different timezones), you may want to ensure all business time calculations are performed in a specific timezone.

The setTZBusinessTime() function allows you to configure a default timezone for all business time operations. When set, all dates passed to business time calculation methods (like businessMinutesDiff, businessHoursDiff, etc.) are automatically converted to the specified timezone before processing.

Basic Usage

// Configure the timezone (uses IANA timezone names)
dayjs.setTZBusinessTime('America/Sao_Paulo'); // UTC-3

// Now you can create dates in any format - they will be automatically converted
const start = dayjs('2026-01-02 08:00:00');
const end = dayjs(new Date());

// Business time calculations are performed in the configured timezone
const diff = start.businessMinutesDiff(end);

Why Use Timezone Configuration?

Problem: When you define business hours as { start: '13:00:00', end: '16:00:00' }, you typically mean these hours in your local business timezone. However, if your code runs in different environments:

Local machine (e.g., UTC-3): 08:00:00 is interpreted as 08:00 UTC-3 (11:00 UTC)
Docker container (e.g., UTC): 08:00:00 is interpreted as 08:00 UTC
This 3-hour difference causes inconsistent business time calculations!

Solution: Use setTZBusinessTime() to ensure all times are interpreted in your business timezone:

// Set your business timezone
dayjs.setTZBusinessTime('America/Sao_Paulo'); // UTC-3

// Define business hours (always in UTC-3 now)
dayjs.setBusinessTime({
  monday: [{ start: '13:00:00', end: '16:00:00' }],
  tuesday: [{ start: '13:00:00', end: '16:00:00' }],
  // ...
});

// All dates are automatically converted to UTC-3 before calculations
const start = dayjs('2026-01-02 08:00:00');
const end = dayjs(new Date());

const minutesDiff = start.businessMinutesDiff(end);
// Result is consistent regardless of system timezone!

Supported Input Formats

The automatic timezone conversion works with all common date formats:

dayjs.setTZBusinessTime('America/New_York');

// String without timezone
const date1 = dayjs('2026-01-02 14:00:00');

// ISO string with UTC
const date2 = dayjs('2026-01-02T17:00:00.000Z');

// JavaScript Date object
const date3 = dayjs(new Date());

// All of the above are automatically converted to America/New_York
// before business time calculations

Getting Current Timezone

// Set timezone
dayjs.setTZBusinessTime('Europe/London');

// Get currently configured timezone
const currentTz = dayjs.getTZBusinessTime();
console.log(currentTz); // 'Europe/London'

Common Timezone Examples

// Americas
dayjs.setTZBusinessTime('America/New_York');      // UTC-5/-4 (EST/EDT)
dayjs.setTZBusinessTime('America/Chicago');       // UTC-6/-5 (CST/CDT)
dayjs.setTZBusinessTime('America/Los_Angeles');   // UTC-8/-7 (PST/PDT)
dayjs.setTZBusinessTime('America/Sao_Paulo');     // UTC-3 (BRT)

// Europe
dayjs.setTZBusinessTime('Europe/London');         // UTC+0/+1 (GMT/BST)
dayjs.setTZBusinessTime('Europe/Paris');          // UTC+1/+2 (CET/CEST)
dayjs.setTZBusinessTime('Europe/Moscow');         // UTC+3 (MSK)

// Asia
dayjs.setTZBusinessTime('Asia/Tokyo');            // UTC+9 (JST)
dayjs.setTZBusinessTime('Asia/Shanghai');         // UTC+8 (CST)
dayjs.setTZBusinessTime('Asia/Kolkata');          // UTC+5:30 (IST)

// Australia
dayjs.setTZBusinessTime('Australia/Sydney');      // UTC+10/+11 (AEST/AEDT)

Complete Example

const dayjs = require('dayjs');
const businessTime = require('dayjs-business-time');

// Extend dayjs (UTC and timezone plugins are automatically included)
dayjs.extend(businessTime);

// Configure timezone for business operations
dayjs.setTZBusinessTime('America/Sao_Paulo');

// Configure business hours (in UTC-3)
dayjs.setBusinessTime({
  sunday: [{ start: '13:00:00', end: '16:00:00' }],
  monday: [{ start: '13:00:00', end: '16:00:00' }],
  tuesday: [{ start: '13:00:00', end: '16:00:00' }],
  wednesday: [{ start: '13:00:00', end: '16:00:00' }],
  thursday: [{ start: '13:00:00', end: '16:00:00' }],
  friday: [{ start: '13:00:00', end: '16:00:00' }],
  saturday: [{ start: '13:00:00', end: '16:00:00' }],
});

// Create dates (will be auto-converted to UTC-3 in calculations)
const start = dayjs('2026-01-02 08:00:00');
const end = dayjs(new Date());

// Calculate business time difference
const minutes = start.businessMinutesDiff(end);
const hours = start.businessHoursDiff(end);
const seconds = start.businessSecondsDiff(end);

console.log('Business Minutes:', minutes);
console.log('Business Hours:', hours);
console.log('Business Seconds:', seconds);
// Results are consistent across all environments!

Note: The UTC and timezone plugins from Day.js are automatically loaded when you extend dayjs-business-time, so you don't need to manually extend them.

Checking

Check if a date is a Holiday

According to holidays setup

const isHoliday = dayjs('2021-02-01').isHoliday();

console.log(isHoliday); // false

Check if a date is a Business Day

Bussiness Days are days with Business Hours settled, excluding Holidays.

const isBusinessDay = dayjs('2021-02-01').isBusinessDay();

console.log(isBusinessDay); // true

Check if a Time is Business Time

Bussiness Times are all minutes between Start and End of a Business Time Segment.

const isBusinessTime = dayjs('2021-02-01 10:00:00').isBusinessTime();

console.log(isBusinessTime); // true

Next and Last

Get Next Business Day

const nextBusinessDay = dayjs('2021-02-01').nextBusinessDay();

console.log(nextBusinessDay); // 2021-02-02

Get Last Business Day

const lastBusinessDay = dayjs('2021-02-01').lastBusinessDay();

console.log(nextBusinessDay); // 2021-01-29

Get Next Business Time

const nextBusinessTime = dayjs('2021-02-01 18:00:00').nextBusinessTime();

console.log(nextBusinessTime); // 2021-02-02 09:00:00

Get Last Business Time

const lastBusinessTime = dayjs('2021-02-01 08:00:00').lastBusinessTime();

console.log(lastBusinessTime); // 2021-01-29 17:00:00

Adding Business Time

Add Business Time

const day = dayjs('2021-02-01 10:00:00');
const timeToAdd: number = 2;

// Possible BusinessTimeUnit is 'day', 'days', 'hour', 'hours', 'minute', 'minutes'
const unit: BusinessTimeUnit = 'days';

const newBusinessTime: Dayjs = day.addBusinessTime(timeToAdd, unit);

console.log(newBusinessTime); // 2021-02-02 10:00:00

Add Business Days

This method is just an alias for .addBusinessTime(timeToAdd, 'days')

const day = dayjs('2021-02-01 10:00:00');
const timeToAdd: number = 2;

const newBusinessTime: Dayjs = day.addBusinessDays(timeToAdd);

console.log(newBusinessTime); // 2021-02-02 10:00:00

Add Business Hours

This method is just an alias for .addBusinessTime(timeToAdd, 'hours')

const day = dayjs('2021-02-01 10:00:00');
const timeToAdd: number = 2;

const newBusinessTime: Dayjs = day.addBusinessHours(timeToAdd);

console.log(newBusinessTime); // 2021-02-01 12:00:00

Add Business Minutes

This method is just an alias for .addBusinessTime(timeToAdd, 'minutes')

const day = dayjs('2021-02-01 10:00:00');
const timeToAdd: number = 30;

const newBusinessTime: Dayjs = day.addBusinessMinutes(timeToAdd);

console.log(newBusinessTime); // 2021-02-01 10:30:00

Subtracting Business Time

Subtract Business Time

const day = dayjs('2021-02-01 10:00:00');
const timeToSubtract: number = 2;

// Possible BusinessTimeUnit is 'day', 'days', 'hour', 'hours', 'minute', 'minutes'
const unit: BusinessTimeUnit = 'days';

const newBusinessTime: Dayjs = day.subtractBusinessTime(timeToSubtract, unit);

console.log(newBusinessTime); // 2021-01-28 10:00:00

Subtract Business Days

This method is just an alias for .subtractBusinessTime(timeToSubtract, 'days')

const day = dayjs('2021-02-01 10:00:00');
const timeToSubtract: number = 2;

const newBusinessTime: Dayjs = day.subtractBusinessDays(timeToSubtract);

console.log(newBusinessTime); // 2021-01-28 10:00:00

Subtract Business Hours

This method is just an alias for .subtractBusinessTime(timeToSubtract, 'hours')

const day = dayjs('2021-02-01 12:00:00');
const timeToSubtract: number = 2;

const newBusinessTime: Dayjs = day.subtractBusinessHours(timeToSubtract);

console.log(newBusinessTime); // 2021-02-01 10:00:00

Subtract Business Minutes

This method is just an alias for .subtractBusinessTime(timeToSubtract, 'minutes')

const day = dayjs('2021-02-01 10:00:00');
const timeToSubtract: number = 30;

const newBusinessTime: Dayjs = day.subtractBusinessMinutes(timeToSubtract);

console.log(newBusinessTime); // 2021-02-01 09:30:00

Diff

Business Time Diff

const start: Dayjs = dayjs('2021-02-01 10:00:00');
const end: Dayjs = dayjs('2021-02-04 10:00:00');

// Possible BusinessTimeUnit is 'day', 'days', 'hour', 'hours', 'minute', 'minutes'
const unit: BusinessTimeUnit = 'days';

const difference: number = start.businessTimeDiff(end, unit);

console.log(difference); // 3

Business Days Diff

This method is just an alias for .businessTimeDiff(dateToCompare, 'days')

const start: Dayjs = dayjs('2021-02-01 10:00:00');
const end: Dayjs = dayjs('2021-02-04 10:00:00');

const difference: number = start.businessDaysDiff(end);

console.log(difference); // 3

Business Hours Diff

This method is just an alias for .businessTimeDiff(dateToCompare, 'hours')

const start: Dayjs = dayjs('2021-02-01 10:00:00');
const end: Dayjs = dayjs('2021-02-01 15:00:00');

const difference: number = start.businessHoursDiff(end);

console.log(difference); // 5

Business Minutes Diff

This method is just an alias for .businessTimeDiff(dateToCompare, 'minutes')

const start: Dayjs = dayjs('2021-02-01 10:00:00');
const end: Dayjs = dayjs('2021-02-01 10:45:00');

const difference: number = start.businessMinutesDiff(end);

console.log(difference); // 45

Business Seconds Diff

This method calculates the difference in seconds between two dates considering only business time.

const start: Dayjs = dayjs('2025-12-01 20:00:00');
const end: Dayjs = dayjs('2025-12-02 11:01:01');

const difference: number = start.businessSecondsDiff(end);

console.log(difference);

You can also use the new holidays format (object map) to define time ranges that should NOT be counted as business time on a given date:

dayjs.setBusinessTime({
  sunday: null,
  monday: [{ start: '08:00:00', end: '18:00:00' }],
  tuesday: [{ start: '08:00:00', end: '18:00:00' }],
  wednesday: [{ start: '08:00:00', end: '18:00:00' }],
  thursday: [{ start: '08:00:00', end: '18:00:00' }],
  friday: [{ start: '08:00:00', end: '18:00:00' }],
  saturday: null,
});

dayjs.setHolidays({
  '2025-12-25': [
    { start: '12:00:00', end: '18:00:00' },
    { start: '09:00:00', end: '10:00:00' },
    { start: '02:00:00', end: '08:30:00' },
  ],
});

const inicio = dayjs('2025-12-24 20:00:00');
const fim = dayjs('2025-12-25 11:00:00');

const seconds = inicio.businessSecondsDiff(fim);
console.log(seconds); // 5400