You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A comprehensive date manipulation library for the Betterez ecosystem, providing timezone-aware date operations and formatting capabilities.
Overview
bz-date is a JavaScript date library that extends native Date functionality with timezone support, formatting options, and specialized date operations. It includes support for 40+ timezones with Daylight Saving Time (DST) handling.
Installation
npm install bz-date
Quick start
constBzDate=require('bz-date');// Create a new dateconstdate=newBzDate();// Parse a date stringconstparsed=newBzDate('2023-12-25');// Format a dateconstformatted=date.toString('dd/mm/yyyy');
Complete API reference
Constructors
Constructor
Description
new BzDate()
Current date
new BzDate(dateObject)
From a JavaScript Date object
new BzDate(bzDateObject)
Clone of an existing BzDate instance
new BzDate(literal)
From a literal object { value: Date, offset: number }
new BzDate(dateString)
Parses a date string
new BzDate(dateString, format)
Parses a string with a specific format
new BzDate(dateString, offset)
String with timezone offset
new BzDate(year, month, day, hour, min, sec, msec, offset)
Returns IANA timezone name (fallback: "America/Toronto")
Formatting System
Feature
Description
Predefined masks
dd/mm/yyyy, yyyy-mm-dd, etc.
Available tokens
d, dd, ddd, dddd, m, mm, mmm, mmmm, yy, yyyy, h, hh, H, HH, M, MM, s, ss, etc.
Internationalization
English names for days and months
NullBzDate
Feature
Description
Null date representation
Special class to represent null/empty dates
Neutral return values
All methods return neutral values or this
Error handling
Setters throw explicit errors
Safety guidelines
After thorough research, several critical issues have been identified in the timezone handling system. The development team is currently working on addressing these problems.
Known issues
Hardcoded DST dates - DST transitions are still hardcoded (generic US table through 2036)
Incorrect timezone rules - Some timezones use incorrect DST transition dates for their regions
No effective-from dates - A zone that became permanent mid-year cannot express "permanent after date X". Offsets for dates before the switch can be one hour off (e.g. past winters for Alberta, Manitoba and B.C.). That only matters when something recalculates those old dates — reports, manifests, reprints — not for new sales after the permanent cutover
Time-ignorant DST transitions - BzDate only checks dates, not the specific hour when DST changes occur
Missing IANA database integration - Returns IANA timezone names but relies on manually maintained timezone data instead of the standard IANA timezone database
Recommendations
Until these issues are resolved:
Safe Operations: Basic date arithmetic, comparison, and formatting without timezone offsets
Use with Caution: Any operations involving timezone offsets or DST-dependent calculations
Avoid: Manual timezone offset management and operations that rely on DST transition accuracy
Development
# Run tests
npm test# Run tests in watch mode
npm run tdd