@f-o-t/datetime 0.1.0

package/src/core/factory.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "bun:test";
+import { InvalidDateError } from "../errors";
+import type { DateInput } from "../types";
+import { DateTime } from "./datetime";
+import { datetime } from "./factory";
+
+describe("datetime factory function", () => {
+   describe("basic usage", () => {
+      test("creates DateTime instance without arguments (current time)", () => {
+         const dt = datetime();
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(true);
+
+         // Should be close to current time (within 100ms)
+         const now = Date.now();
+         expect(Math.abs(dt.valueOf() - now)).toBeLessThan(100);
+      });
+
+      test("creates DateTime from Date object", () => {
+         const date = new Date("2024-01-15T10:30:00Z");
+         const dt = datetime(date);
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(true);
+         expect(dt.toISO()).toBe("2024-01-15T10:30:00.000Z");
+      });
+
+      test("creates DateTime from ISO string", () => {
+         const dt = datetime("2024-01-15T10:30:00Z");
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(true);
+         expect(dt.toISO()).toBe("2024-01-15T10:30:00.000Z");
+      });
+
+      test("creates DateTime from timestamp", () => {
+         const timestamp = 1705315800000; // 2024-01-15T10:30:00Z
+         const dt = datetime(timestamp);
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(true);
+         expect(dt.valueOf()).toBe(timestamp);
+      });
+
+      test("creates DateTime from another DateTime", () => {
+         const dt1 = datetime("2024-01-15T10:30:00Z");
+         const dt2 = datetime(dt1);
+
+         expect(dt2).toBeInstanceOf(DateTime);
+         expect(dt2.isValid()).toBe(true);
+         expect(dt2.toISO()).toBe(dt1.toISO());
+         expect(dt2.valueOf()).toBe(dt1.valueOf());
+      });
+   });
+
+   describe("edge cases", () => {
+      test("creates invalid DateTime from invalid date string", () => {
+         const dt = datetime("invalid");
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(false);
+      });
+
+      test("creates invalid DateTime from NaN", () => {
+         const dt = datetime(NaN);
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(false);
+      });
+
+      test("creates invalid DateTime from invalid Date object", () => {
+         const dt = datetime(new Date("invalid"));
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect(dt.isValid()).toBe(false);
+      });
+
+      test("throws InvalidDateError for non-DateInput types", () => {
+         expect(() => datetime({} as any)).toThrow(InvalidDateError);
+         expect(() => datetime([] as any)).toThrow(InvalidDateError);
+         expect(() => datetime(true as any)).toThrow(InvalidDateError);
+         expect(() => datetime(null as any)).toThrow(InvalidDateError);
+      });
+   });
+
+   describe("immutability", () => {
+      test("creates independent instances", () => {
+         const dt1 = datetime("2024-01-15T10:30:00Z");
+         const dt2 = datetime(dt1);
+         const dt3 = dt2.addDays(1);
+
+         expect(dt1.toISO()).toBe("2024-01-15T10:30:00.000Z");
+         expect(dt2.toISO()).toBe("2024-01-15T10:30:00.000Z");
+         expect(dt3.toISO()).toBe("2024-01-16T10:30:00.000Z");
+      });
+
+      test("does not mutate input Date object", () => {
+         const date = new Date("2024-01-15T10:30:00Z");
+         const originalTime = date.getTime();
+         const dt = datetime(date);
+
+         dt.addDays(1);
+
+         expect(date.getTime()).toBe(originalTime);
+      });
+   });
+
+   describe("equivalence to constructor", () => {
+      test("produces same result as constructor", () => {
+         const inputs: Array<DateInput | undefined> = [
+            undefined,
+            new Date("2024-01-15T10:30:00Z"),
+            "2024-01-15T10:30:00Z",
+            1705315800000,
+         ];
+
+         for (const input of inputs) {
+            const factory = datetime(input);
+            const constructor = new DateTime(input);
+
+            expect(factory.valueOf()).toBe(constructor.valueOf());
+            expect(factory.isValid()).toBe(constructor.isValid());
+         }
+      });
+
+      test("throws same errors as constructor", () => {
+         const invalidInputs = [{}, [], true, null];
+
+         for (const input of invalidInputs) {
+            expect(() => datetime(input as any)).toThrow(InvalidDateError);
+            expect(() => new DateTime(input as any)).toThrow(InvalidDateError);
+         }
+      });
+   });
+
+   describe("chaining", () => {
+      test("can chain operations after factory creation", () => {
+         const dt = datetime("2024-01-15T10:30:00Z")
+            .addDays(5)
+            .addHours(3)
+            .subtractMinutes(15);
+
+         expect(dt.toISO()).toBe("2024-01-20T13:15:00.000Z");
+      });
+
+      test("can use comparison methods", () => {
+         const dt1 = datetime("2024-01-15T10:30:00Z");
+         const dt2 = datetime("2024-01-16T10:30:00Z");
+
+         expect(dt1.isBefore(dt2)).toBe(true);
+         expect(dt2.isAfter(dt1)).toBe(true);
+         expect(dt1.isSame(dt1)).toBe(true);
+      });
+
+      test("can use getter methods", () => {
+         const dt = datetime("2024-01-15T10:30:45.123Z");
+
+         expect(dt.year()).toBe(2024);
+         expect(dt.month()).toBe(0); // January is 0
+         expect(dt.date()).toBe(15);
+         expect(dt.hour()).toBe(10);
+         expect(dt.minute()).toBe(30);
+         expect(dt.second()).toBe(45);
+         expect(dt.millisecond()).toBe(123);
+      });
+   });
+});

package/src/core/factory.ts

@@ -0,0 +1,32 @@
+import type { DateInput } from "../types.ts";
+import { DateTime } from "./datetime.ts";
+
+/**
+ * Factory function to create a DateTime instance
+ * Provides a convenient alternative to using the constructor
+ *
+ * @param input - Date input (Date, ISO string, timestamp, DateTime, or undefined for current time)
+ * @returns A new DateTime instance
+ * @throws {InvalidDateError} When input fails validation
+ *
+ * @example
+ * ```ts
+ * // Create with current time
+ * const now = datetime();
+ *
+ * // Create from Date object
+ * const dt1 = datetime(new Date());
+ *
+ * // Create from ISO string
+ * const dt2 = datetime("2024-01-15T10:30:00Z");
+ *
+ * // Create from timestamp
+ * const dt3 = datetime(1705315800000);
+ *
+ * // Create from another DateTime
+ * const dt4 = datetime(dt1);
+ * ```
+ */
+export function datetime(input?: DateInput): DateTime {
+   return new DateTime(input);
+}

package/src/errors.ts

@@ -0,0 +1,82 @@
+/**
+ * Base error class for all DateTime-related errors
+ */
+export class DateTimeError extends Error {
+   constructor(message: string) {
+      super(message);
+      this.name = "DateTimeError";
+      // Maintains proper stack trace for where our error was thrown (only available on V8)
+      if (Error.captureStackTrace) {
+         Error.captureStackTrace(this, this.constructor);
+      }
+   }
+}
+
+/**
+ * Error thrown when an invalid date is provided
+ */
+export class InvalidDateError extends DateTimeError {
+   constructor(
+      message = "Invalid date",
+      public readonly input?: unknown,
+   ) {
+      super(message);
+      this.name = "InvalidDateError";
+   }
+}
+
+/**
+ * Error thrown when a date string doesn't match the expected format
+ */
+export class InvalidFormatError extends DateTimeError {
+   constructor(
+      message: string,
+      public readonly input?: string,
+      public readonly expectedFormat?: string,
+   ) {
+      super(message);
+      this.name = "InvalidFormatError";
+   }
+}
+
+/**
+ * Error thrown when an invalid timezone is specified
+ */
+export class InvalidTimezoneError extends DateTimeError {
+   constructor(
+      message: string,
+      public readonly timezone?: string,
+   ) {
+      super(message);
+      this.name = "InvalidTimezoneError";
+   }
+}
+
+/**
+ * Error thrown when a plugin operation fails
+ */
+export class PluginError extends DateTimeError {
+   constructor(
+      message: string,
+      public readonly pluginName?: string,
+   ) {
+      super(message);
+      this.name = "PluginError";
+   }
+}
+
+/**
+ * Error thrown when attempting to use functionality that requires a plugin that isn't installed
+ */
+export class MissingPluginError extends PluginError {
+   constructor(
+      public readonly requiredPlugin: string,
+      message?: string,
+   ) {
+      super(
+         message || `Missing required plugin: ${requiredPlugin}`,
+         requiredPlugin,
+      );
+      this.name = "MissingPluginError";
+   }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// Core exports
+export { DateTime } from "./core/datetime.ts";
+export { datetime } from "./core/factory.ts";
+// Error exports
+export { InvalidDateError, PluginError } from "./errors.ts";
+// Plugin utilities
+export { createPlugin, isPlugin, isValidPluginName } from "./plugins/index.ts";
+
+// Schema exports
+export { DateInputSchema } from "./schemas.ts";
+// Type exports
+export type {
+   DateInput,
+   DateTimeClass,
+   DateTimeConfig,
+   DateTimePlugin,
+   FormatOptions,
+   ParseOptions,
+   TimeUnit,
+} from "./types.ts";

package/src/plugins/business-days/business-days.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, it } from "bun:test";
+import { DateTime } from "../../core/datetime";
+import { businessDaysPlugin } from "./index";
+
+describe("Business Days Plugin", () => {
+   // Install plugin before running tests
+   DateTime.extend(businessDaysPlugin);
+
+   describe("isWeekday()", () => {
+      it("should return true for Monday", () => {
+         // 2024-01-15 is a Monday
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(true);
+      });
+
+      it("should return true for Tuesday", () => {
+         // 2024-01-16 is a Tuesday
+         const dt = new DateTime("2024-01-16T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(true);
+      });
+
+      it("should return true for Wednesday", () => {
+         // 2024-01-17 is a Wednesday
+         const dt = new DateTime("2024-01-17T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(true);
+      });
+
+      it("should return true for Thursday", () => {
+         // 2024-01-18 is a Thursday
+         const dt = new DateTime("2024-01-18T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(true);
+      });
+
+      it("should return true for Friday", () => {
+         // 2024-01-19 is a Friday
+         const dt = new DateTime("2024-01-19T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(true);
+      });
+
+      it("should return false for Saturday", () => {
+         // 2024-01-20 is a Saturday
+         const dt = new DateTime("2024-01-20T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(false);
+      });
+
+      it("should return false for Sunday", () => {
+         // 2024-01-21 is a Sunday
+         const dt = new DateTime("2024-01-21T12:00:00.000Z");
+         expect((dt as any).isWeekday()).toBe(false);
+      });
+   });
+
+   describe("isWeekend()", () => {
+      it("should return false for Monday", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((dt as any).isWeekend()).toBe(false);
+      });
+
+      it("should return false for Friday", () => {
+         const dt = new DateTime("2024-01-19T12:00:00.000Z");
+         expect((dt as any).isWeekend()).toBe(false);
+      });
+
+      it("should return true for Saturday", () => {
+         const dt = new DateTime("2024-01-20T12:00:00.000Z");
+         expect((dt as any).isWeekend()).toBe(true);
+      });
+
+      it("should return true for Sunday", () => {
+         const dt = new DateTime("2024-01-21T12:00:00.000Z");
+         expect((dt as any).isWeekend()).toBe(true);
+      });
+   });
+
+   describe("addBusinessDays()", () => {
+      it("should add business days correctly", () => {
+         // Monday + 1 business day = Tuesday
+         const monday = new DateTime("2024-01-15T12:00:00.000Z");
+         const tuesday = (monday as any).addBusinessDays(1);
+         expect(tuesday.date()).toBe(16);
+      });
+
+      it("should skip weekends when adding business days", () => {
+         // Friday + 1 business day = Monday
+         const friday = new DateTime("2024-01-19T12:00:00.000Z");
+         const monday = (friday as any).addBusinessDays(1);
+         expect(monday.date()).toBe(22);
+      });
+
+      it("should handle multiple business days across weekends", () => {
+         // Friday + 3 business days = Wednesday (skip Sat, Sun, Mon, Tue, Wed)
+         const friday = new DateTime("2024-01-19T12:00:00.000Z");
+         const wednesday = (friday as any).addBusinessDays(3);
+         expect(wednesday.date()).toBe(24);
+      });
+
+      it("should handle adding from Saturday", () => {
+         // Saturday + 1 business day = Monday
+         const saturday = new DateTime("2024-01-20T12:00:00.000Z");
+         const monday = (saturday as any).addBusinessDays(1);
+         expect(monday.date()).toBe(22);
+      });
+
+      it("should handle adding from Sunday", () => {
+         // Sunday + 1 business day = Monday
+         const sunday = new DateTime("2024-01-21T12:00:00.000Z");
+         const monday = (sunday as any).addBusinessDays(1);
+         expect(monday.date()).toBe(22);
+      });
+
+      it("should handle adding 0 business days", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).addBusinessDays(0);
+         expect(result.valueOf()).toBe(dt.valueOf());
+      });
+
+      it("should preserve time when adding business days", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         const result = (dt as any).addBusinessDays(1);
+         expect(result.hour()).toBe(14);
+         expect(result.minute()).toBe(30);
+         expect(result.second()).toBe(45);
+         expect(result.millisecond()).toBe(123);
+      });
+   });
+
+   describe("subtractBusinessDays()", () => {
+      it("should subtract business days correctly", () => {
+         // Tuesday - 1 business day = Monday
+         const tuesday = new DateTime("2024-01-16T12:00:00.000Z");
+         const monday = (tuesday as any).subtractBusinessDays(1);
+         expect(monday.date()).toBe(15);
+      });
+
+      it("should skip weekends when subtracting business days", () => {
+         // Monday - 1 business day = Friday
+         const monday = new DateTime("2024-01-22T12:00:00.000Z");
+         const friday = (monday as any).subtractBusinessDays(1);
+         expect(friday.date()).toBe(19);
+      });
+
+      it("should handle multiple business days across weekends", () => {
+         // Wednesday - 3 business days = Friday (previous week)
+         const wednesday = new DateTime("2024-01-24T12:00:00.000Z");
+         const friday = (wednesday as any).subtractBusinessDays(3);
+         expect(friday.date()).toBe(19);
+      });
+
+      it("should handle subtracting from Saturday", () => {
+         // Saturday - 1 business day = Friday
+         const saturday = new DateTime("2024-01-20T12:00:00.000Z");
+         const friday = (saturday as any).subtractBusinessDays(1);
+         expect(friday.date()).toBe(19);
+      });
+
+      it("should handle subtracting from Sunday", () => {
+         // Sunday - 1 business day = Friday
+         const sunday = new DateTime("2024-01-21T12:00:00.000Z");
+         const friday = (sunday as any).subtractBusinessDays(1);
+         expect(friday.date()).toBe(19);
+      });
+
+      it("should handle subtracting 0 business days", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).subtractBusinessDays(0);
+         expect(result.valueOf()).toBe(dt.valueOf());
+      });
+   });
+
+   describe("diffBusinessDays()", () => {
+      it("should calculate business days between two weekdays", () => {
+         // Monday to Friday = 4 business days
+         const monday = new DateTime("2024-01-15T12:00:00.000Z");
+         const friday = new DateTime("2024-01-19T12:00:00.000Z");
+         expect((monday as any).diffBusinessDays(friday)).toBe(4);
+      });
+
+      it("should exclude weekends in calculation", () => {
+         // Friday to next Monday = 1 business day
+         const friday = new DateTime("2024-01-19T12:00:00.000Z");
+         const monday = new DateTime("2024-01-22T12:00:00.000Z");
+         expect((friday as any).diffBusinessDays(monday)).toBe(1);
+      });
+
+      it("should return negative values when going backwards", () => {
+         const friday = new DateTime("2024-01-19T12:00:00.000Z");
+         const monday = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((friday as any).diffBusinessDays(monday)).toBe(-4);
+      });
+
+      it("should return 0 for same day", () => {
+         const dt1 = new DateTime("2024-01-15T12:00:00.000Z");
+         const dt2 = new DateTime("2024-01-15T18:00:00.000Z");
+         expect((dt1 as any).diffBusinessDays(dt2)).toBe(0);
+      });
+
+      it("should handle weekend dates", () => {
+         // Saturday to Sunday = 0 business days
+         const saturday = new DateTime("2024-01-20T12:00:00.000Z");
+         const sunday = new DateTime("2024-01-21T12:00:00.000Z");
+         expect((saturday as any).diffBusinessDays(sunday)).toBe(0);
+      });
+
+      it("should handle crossing multiple weeks", () => {
+         // Monday to Monday (2 weeks) = 10 business days
+         const monday1 = new DateTime("2024-01-15T12:00:00.000Z");
+         const monday2 = new DateTime("2024-01-29T12:00:00.000Z");
+         expect((monday1 as any).diffBusinessDays(monday2)).toBe(10);
+      });
+   });
+
+   describe("Chaining", () => {
+      it("should chain business day methods with other DateTime methods", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).addBusinessDays(5).addHours(2);
+         expect(result).toBeInstanceOf(DateTime);
+      });
+
+      it("should work with arithmetic operations", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).addBusinessDays(3).subtractBusinessDays(1);
+         expect((dt as any).diffBusinessDays(result)).toBe(2);
+      });
+   });
+});

package/src/plugins/business-days/index.ts

@@ -0,0 +1,126 @@
+import type { DateTime } from "../../core/datetime";
+import type { DateTimeClass } from "../../types";
+import { createPlugin } from "../plugin-base";
+
+/**
+ * Checks if a given day of week is a weekday (Monday-Friday)
+ * @param dayOfWeek - Day of week (0=Sunday, 6=Saturday)
+ * @returns true if weekday, false otherwise
+ */
+function isWeekdayDay(dayOfWeek: number): boolean {
+   return dayOfWeek >= 1 && dayOfWeek <= 5;
+}
+
+/**
+ * Extended DateTime interface with business days methods
+ */
+declare module "../../core/datetime" {
+   interface DateTime {
+      /**
+       * Checks if this date is a weekday (Monday-Friday)
+       * @returns true if weekday, false otherwise
+       */
+      isWeekday(): boolean;
+
+      /**
+       * Checks if this date is a weekend (Saturday-Sunday)
+       * @returns true if weekend, false otherwise
+       */
+      isWeekend(): boolean;
+
+      /**
+       * Adds business days to this date
+       * Skips weekends (Saturday and Sunday)
+       * @param n - Number of business days to add
+       * @returns New DateTime instance with business days added
+       */
+      addBusinessDays(n: number): DateTime;
+
+      /**
+       * Subtracts business days from this date
+       * Skips weekends (Saturday and Sunday)
+       * @param n - Number of business days to subtract
+       * @returns New DateTime instance with business days subtracted
+       */
+      subtractBusinessDays(n: number): DateTime;
+
+      /**
+       * Calculates the number of business days between this date and another
+       * Excludes weekends from the calculation
+       * @param other - DateTime instance to compare against
+       * @returns Number of business days (positive if other is after, negative if before)
+       */
+      diffBusinessDays(other: DateTime): number;
+   }
+}
+
+/**
+ * Business Days plugin for DateTime
+ * Adds methods for working with business days (weekdays only)
+ * Week is defined as Monday-Friday (weekdays), Saturday-Sunday (weekend)
+ */
+export const businessDaysPlugin = createPlugin(
+   "business-days",
+   (DateTimeClass: DateTimeClass) => {
+      // Add instance methods
+      DateTimeClass.prototype.isWeekday = function (): boolean {
+         const dayOfWeek = this.day(); // 0=Sunday, 6=Saturday
+         return isWeekdayDay(dayOfWeek);
+      };
+
+      DateTimeClass.prototype.isWeekend = function (): boolean {
+         const dayOfWeek = this.day();
+         return dayOfWeek === 0 || dayOfWeek === 6;
+      };
+
+      DateTimeClass.prototype.addBusinessDays = function (n: number): DateTime {
+         if (n === 0) {
+            return this;
+         }
+
+         let current = new DateTimeClass(this.valueOf());
+         let daysToAdd = Math.abs(n);
+         const direction = n > 0 ? 1 : -1;
+
+         while (daysToAdd > 0) {
+            // Move one day in the specified direction
+            current = current.addDays(direction);
+
+            // Only count weekdays
+            if ((current as any).isWeekday()) {
+               daysToAdd--;
+            }
+         }
+
+         return current;
+      };
+
+      DateTimeClass.prototype.subtractBusinessDays = function (
+         n: number,
+      ): DateTime {
+         return (this as any).addBusinessDays(-n);
+      };
+
+      DateTimeClass.prototype.diffBusinessDays = function (
+         other: DateTime,
+      ): number {
+         // Get start and end dates (normalized to start of day for consistency)
+         const start = this.valueOf() < other.valueOf() ? this : other;
+         const end = this.valueOf() < other.valueOf() ? other : this;
+         const isReversed = this.valueOf() > other.valueOf();
+
+         let businessDays = 0;
+         let current = new DateTimeClass(start.valueOf());
+
+         // Iterate through each day and count weekdays
+         while (current.startOfDay().valueOf() < end.startOfDay().valueOf()) {
+            if ((current as any).isWeekday()) {
+               businessDays++;
+            }
+            current = current.addDays(1);
+         }
+
+         return isReversed ? -businessDays : businessDays;
+      };
+   },
+);