@f-o-t/datetime 0.1.0

package/src/plugins/format/format.test.ts

@@ -0,0 +1,173 @@
+import { describe, expect, it } from "bun:test";
+import { DateTime } from "../../core/datetime";
+import { formatPlugin } from "./index";
+
+describe("Format Plugin", () => {
+   // Install plugin before running tests
+   DateTime.extend(formatPlugin);
+
+   describe("format()", () => {
+      it("should format year tokens", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("YYYY")).toBe("2024");
+         expect((dt as any).format("YY")).toBe("24");
+      });
+
+      it("should format month tokens", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("MM")).toBe("01");
+         expect((dt as any).format("M")).toBe("1");
+      });
+
+      it("should format day tokens", () => {
+         const dt = new DateTime("2024-01-05T14:30:45.123Z");
+         expect((dt as any).format("DD")).toBe("05");
+         expect((dt as any).format("D")).toBe("5");
+      });
+
+      it("should format hour tokens (24-hour)", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("HH")).toBe("14");
+         expect((dt as any).format("H")).toBe("14");
+      });
+
+      it("should format hour tokens (12-hour)", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("hh")).toBe("02");
+         expect((dt as any).format("h")).toBe("2");
+
+         const dtAM = new DateTime("2024-01-15T09:30:45.123Z");
+         expect((dtAM as any).format("hh")).toBe("09");
+         expect((dtAM as any).format("h")).toBe("9");
+      });
+
+      it("should handle midnight and noon in 12-hour format", () => {
+         const midnight = new DateTime("2024-01-15T00:00:00.000Z");
+         expect((midnight as any).format("h")).toBe("12");
+
+         const noon = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((noon as any).format("h")).toBe("12");
+      });
+
+      it("should format minute tokens", () => {
+         const dt = new DateTime("2024-01-15T14:05:45.123Z");
+         expect((dt as any).format("mm")).toBe("05");
+         expect((dt as any).format("m")).toBe("5");
+      });
+
+      it("should format second tokens", () => {
+         const dt = new DateTime("2024-01-15T14:30:05.123Z");
+         expect((dt as any).format("ss")).toBe("05");
+         expect((dt as any).format("s")).toBe("5");
+      });
+
+      it("should format millisecond tokens", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("SSS")).toBe("123");
+
+         const dtZero = new DateTime("2024-01-15T14:30:45.000Z");
+         expect((dtZero as any).format("SSS")).toBe("000");
+      });
+
+      it("should format AM/PM tokens", () => {
+         const dtAM = new DateTime("2024-01-15T09:30:45.123Z");
+         expect((dtAM as any).format("A")).toBe("AM");
+         expect((dtAM as any).format("a")).toBe("am");
+
+         const dtPM = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dtPM as any).format("A")).toBe("PM");
+         expect((dtPM as any).format("a")).toBe("pm");
+      });
+
+      it("should format day of week tokens", () => {
+         // 2024-01-15 is a Monday
+         const monday = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((monday as any).format("dddd")).toBe("Monday");
+         expect((monday as any).format("ddd")).toBe("Mon");
+         expect((monday as any).format("dd")).toBe("Mo");
+         expect((monday as any).format("d")).toBe("1");
+
+         // Sunday should be 0
+         const sunday = new DateTime("2024-01-21T12:00:00.000Z");
+         expect((sunday as any).format("d")).toBe("0");
+      });
+
+      it("should format month name tokens", () => {
+         const january = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((january as any).format("MMMM")).toBe("January");
+         expect((january as any).format("MMM")).toBe("Jan");
+
+         const december = new DateTime("2024-12-15T12:00:00.000Z");
+         expect((december as any).format("MMMM")).toBe("December");
+         expect((december as any).format("MMM")).toBe("Dec");
+      });
+
+      it("should format complex format strings", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("YYYY-MM-DD")).toBe("2024-01-15");
+         expect((dt as any).format("MM/DD/YYYY")).toBe("01/15/2024");
+         expect((dt as any).format("YYYY-MM-DD HH:mm:ss")).toBe(
+            "2024-01-15 14:30:45",
+         );
+         expect((dt as any).format("YYYY-MM-DD HH:mm:ss.SSS")).toBe(
+            "2024-01-15 14:30:45.123",
+         );
+      });
+
+      it("should format with text separators", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("MMMM D, YYYY")).toBe("January 15, 2024");
+         expect((dt as any).format("dddd, MMMM D, YYYY")).toBe(
+            "Monday, January 15, 2024",
+         );
+         expect((dt as any).format("h:mm A")).toBe("2:30 PM");
+         expect((dt as any).format("hh:mm:ss a")).toBe("02:30:45 pm");
+      });
+
+      it("should handle escaped characters in brackets", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("[Year:] YYYY")).toBe("Year: 2024");
+         expect((dt as any).format("YYYY [escaped] MM")).toBe(
+            "2024 escaped 01",
+         );
+         expect((dt as any).format("[YYYY] YYYY")).toBe("YYYY 2024");
+      });
+
+      it("should return default format when no format string provided", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         const result = (dt as any).format();
+         // Should return ISO string or a default format
+         expect(result).toBeDefined();
+         expect(typeof result).toBe("string");
+      });
+
+      it("should handle edge cases", () => {
+         // Midnight
+         const midnight = new DateTime("2024-01-15T00:00:00.000Z");
+         expect((midnight as any).format("HH:mm:ss")).toBe("00:00:00");
+         expect((midnight as any).format("hh:mm:ss A")).toBe("12:00:00 AM");
+
+         // Single digit values
+         const dt = new DateTime("2024-01-05T09:05:05.005Z");
+         expect((dt as any).format("M/D/YY h:m:s")).toBe("1/5/24 9:5:5");
+      });
+
+      it("should preserve literal text", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         expect((dt as any).format("[Today is] YYYY-MM-DD")).toBe(
+            "Today is 2024-01-15",
+         );
+         expect((dt as any).format("[The time is] HH:mm")).toBe(
+            "The time is 14:30",
+         );
+      });
+   });
+
+   describe("Chaining", () => {
+      it("should work with other DateTime methods", () => {
+         const dt = new DateTime("2024-01-15T14:30:45.123Z");
+         const formatted = (dt.addDays(1) as any).format("YYYY-MM-DD");
+         expect(formatted).toBe("2024-01-16");
+      });
+   });
+});

package/src/plugins/format/index.ts

@@ -0,0 +1,78 @@
+import type { DateTime } from "../../core/datetime";
+import type { DateTimeClass } from "../../types";
+import { createPlugin } from "../plugin-base";
+import { parseFormat } from "./tokens";
+
+/**
+ * Default format string
+ */
+const DEFAULT_FORMAT = "YYYY-MM-DDTHH:mm:ss.SSSZ";
+
+/**
+ * Extended DateTime interface with format method
+ */
+declare module "../../core/datetime" {
+   interface DateTime {
+      /**
+       * Formats the date using a format string
+       * @param formatStr - Format string with tokens (default: ISO format)
+       * @returns Formatted date string
+       *
+       * @example
+       * ```ts
+       * dt.format("YYYY-MM-DD") // "2024-01-15"
+       * dt.format("MM/DD/YYYY") // "01/15/2024"
+       * dt.format("MMMM D, YYYY") // "January 15, 2024"
+       * dt.format("h:mm A") // "2:30 PM"
+       * dt.format("[Year:] YYYY") // "Year: 2024"
+       * ```
+       *
+       * Available tokens:
+       * - YYYY: 4-digit year
+       * - YY: 2-digit year
+       * - MMMM: Full month name
+       * - MMM: Abbreviated month name
+       * - MM: 2-digit month
+       * - M: Month number
+       * - DD: 2-digit day of month
+       * - D: Day of month
+       * - dddd: Full day name
+       * - ddd: Abbreviated day name
+       * - dd: Min day name
+       * - d: Day of week (0-6)
+       * - HH: 2-digit hour (24-hour)
+       * - H: Hour (24-hour)
+       * - hh: 2-digit hour (12-hour)
+       * - h: Hour (12-hour)
+       * - mm: 2-digit minute
+       * - m: Minute
+       * - ss: 2-digit second
+       * - s: Second
+       * - SSS: Millisecond
+       * - A: AM/PM (uppercase)
+       * - a: am/pm (lowercase)
+       * - [text]: Escaped text (literal)
+       */
+      format(formatStr?: string): string;
+   }
+}
+
+/**
+ * Format plugin for DateTime
+ * Adds format() method for custom date formatting
+ */
+export const formatPlugin = createPlugin(
+   "format",
+   (DateTimeClass: DateTimeClass) => {
+      // Add instance method
+      DateTimeClass.prototype.format = function (formatStr?: string): string {
+         // If no format string provided, return ISO string
+         if (!formatStr) {
+            return this.toISO();
+         }
+
+         // Parse the format string and replace tokens
+         return parseFormat(this, formatStr);
+      };
+   },
+);

package/src/plugins/format/tokens.ts

@@ -0,0 +1,153 @@
+import type { DateTime } from "../../core/datetime";
+
+/**
+ * Pads a number with leading zeros
+ */
+function pad(num: number, length: number): string {
+   return num.toString().padStart(length, "0");
+}
+
+/**
+ * Month names (full)
+ */
+const MONTH_NAMES = [
+   "January",
+   "February",
+   "March",
+   "April",
+   "May",
+   "June",
+   "July",
+   "August",
+   "September",
+   "October",
+   "November",
+   "December",
+];
+
+/**
+ * Month names (abbreviated)
+ */
+const MONTH_NAMES_SHORT = [
+   "Jan",
+   "Feb",
+   "Mar",
+   "Apr",
+   "May",
+   "Jun",
+   "Jul",
+   "Aug",
+   "Sep",
+   "Oct",
+   "Nov",
+   "Dec",
+];
+
+/**
+ * Day of week names (full)
+ */
+const DAY_NAMES = [
+   "Sunday",
+   "Monday",
+   "Tuesday",
+   "Wednesday",
+   "Thursday",
+   "Friday",
+   "Saturday",
+];
+
+/**
+ * Day of week names (abbreviated)
+ */
+const DAY_NAMES_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+/**
+ * Day of week names (two letters)
+ */
+const DAY_NAMES_MIN = ["Su", "Mo", "Tu", "We", "Th", "Fr", "Sa"];
+
+/**
+ * Format token definitions
+ * Maps token strings to functions that extract the value from a DateTime instance
+ */
+export const FORMAT_TOKENS: Record<string, (dt: DateTime) => string> = {
+   // Year
+   YYYY: (dt) => dt.year().toString(),
+   YY: (dt) => pad(dt.year() % 100, 2),
+
+   // Month
+   MMMM: (dt) => MONTH_NAMES[dt.month()]!,
+   MMM: (dt) => MONTH_NAMES_SHORT[dt.month()]!,
+   MM: (dt) => pad(dt.month() + 1, 2),
+   M: (dt) => (dt.month() + 1).toString(),
+
+   // Day of Month
+   DD: (dt) => pad(dt.date(), 2),
+   D: (dt) => dt.date().toString(),
+
+   // Day of Week
+   dddd: (dt) => DAY_NAMES[dt.day()]!,
+   ddd: (dt) => DAY_NAMES_SHORT[dt.day()]!,
+   dd: (dt) => DAY_NAMES_MIN[dt.day()]!,
+
+   // Hour (24-hour)
+   HH: (dt) => pad(dt.hour(), 2),
+   H: (dt) => dt.hour().toString(),
+
+   // Hour (12-hour)
+   hh: (dt) => {
+      const hour = dt.hour();
+      const hour12 = hour % 12 || 12;
+      return pad(hour12, 2);
+   },
+   h: (dt) => {
+      const hour = dt.hour();
+      const hour12 = hour % 12 || 12;
+      return hour12.toString();
+   },
+
+   // Minute
+   mm: (dt) => pad(dt.minute(), 2),
+   m: (dt) => dt.minute().toString(),
+
+   // Second
+   ss: (dt) => pad(dt.second(), 2),
+   s: (dt) => dt.second().toString(),
+
+   // Millisecond
+   SSS: (dt) => pad(dt.millisecond(), 3),
+
+   // AM/PM
+   A: (dt) => (dt.hour() >= 12 ? "PM" : "AM"),
+   a: (dt) => (dt.hour() >= 12 ? "pm" : "am"),
+
+   // Day of week number
+   d: (dt) => dt.day().toString(),
+};
+
+/**
+ * Regular expression to match format tokens
+ * Matches escaped text first, then longest tokens to avoid partial matches
+ * Order is critical: longer tokens must come before shorter ones
+ */
+export const TOKEN_REGEX =
+   /\[([^\]]+)\]|YYYY|MMMM|MMM|MM|M|dddd|ddd|DD|dd|D|d|HH|hh|H|h|mm|m|ss|s|SSS|YY|A|a/g;
+
+/**
+ * Parses a format string and replaces tokens with actual values
+ * @param dt - DateTime instance
+ * @param formatStr - Format string with tokens
+ * @returns Formatted date string
+ */
+export function parseFormat(dt: DateTime, formatStr: string): string {
+   return formatStr.replace(TOKEN_REGEX, (match, escapedText) => {
+      // If it's escaped text in brackets, return without brackets
+      if (escapedText !== undefined) {
+         return escapedText;
+      }
+
+      // Otherwise, look up the token and apply it
+      const tokenFn = FORMAT_TOKENS[match];
+      return tokenFn ? tokenFn(dt) : match;
+   });
+}

package/src/plugins/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Plugin utilities for extending DateTime functionality
+ *
+ * This module provides helpers for creating and validating DateTime plugins.
+ * Plugins allow extending the DateTime class with custom methods and functionality.
+ *
+ * @module plugins
+ */
+
+export { businessDaysPlugin } from "./business-days/index.ts";
+export { formatPlugin } from "./format/index.ts";
+export { createPlugin, isPlugin, isValidPluginName } from "./plugin-base.ts";
+export { relativeTimePlugin } from "./relative-time/index.ts";
+// Core plugins
+export { timezonePlugin } from "./timezone/index.ts";

package/src/plugins/plugin-base.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, test } from "bun:test";
+import { DateTime } from "../core/datetime.ts";
+import type { DateTimeClass } from "../types.ts";
+import { createPlugin, isPlugin, isValidPluginName } from "./plugin-base.ts";
+
+describe("createPlugin", () => {
+   test("creates a valid plugin object", () => {
+      const plugin = createPlugin("test-plugin", (DateTimeClass) => {
+         // Plugin logic
+      });
+
+      expect(plugin).toHaveProperty("name", "test-plugin");
+      expect(plugin).toHaveProperty("install");
+      expect(typeof plugin.install).toBe("function");
+   });
+
+   test("throws error for empty name", () => {
+      expect(() => {
+         createPlugin("", () => {});
+      }).toThrow("Plugin name must be a non-empty string");
+   });
+
+   test("throws error for non-string name", () => {
+      expect(() => {
+         createPlugin(123 as any, () => {});
+      }).toThrow("Plugin name must be a non-empty string");
+
+      expect(() => {
+         createPlugin(null as any, () => {});
+      }).toThrow("Plugin name must be a non-empty string");
+
+      expect(() => {
+         createPlugin(undefined as any, () => {});
+      }).toThrow("Plugin name must be a non-empty string");
+   });
+
+   test("throws error for non-function install", () => {
+      expect(() => {
+         createPlugin("test", "not-a-function" as any);
+      }).toThrow("Plugin install must be a function");
+
+      expect(() => {
+         createPlugin("test", null as any);
+      }).toThrow("Plugin install must be a function");
+
+      expect(() => {
+         createPlugin("test", undefined as any);
+      }).toThrow("Plugin install must be a function");
+   });
+
+   test("creates plugin with various name formats", () => {
+      const plugins = [
+         createPlugin("camelCase", () => {}),
+         createPlugin("kebab-case", () => {}),
+         createPlugin("snake_case", () => {}),
+         createPlugin("with123numbers", () => {}),
+      ];
+
+      plugins.forEach((plugin, i) => {
+         expect(plugin).toHaveProperty("name");
+         expect(plugin).toHaveProperty("install");
+         expect(typeof plugin.install).toBe("function");
+      });
+   });
+});
+
+describe("isPlugin", () => {
+   test("returns true for valid plugin objects", () => {
+      const plugin = createPlugin("test", () => {});
+      expect(isPlugin(plugin)).toBe(true);
+
+      const manualPlugin = {
+         name: "manual-plugin",
+         install: () => {},
+      };
+      expect(isPlugin(manualPlugin)).toBe(true);
+   });
+
+   test("returns false for invalid objects", () => {
+      expect(isPlugin(null)).toBe(false);
+      expect(isPlugin(undefined)).toBe(false);
+      expect(isPlugin("string")).toBe(false);
+      expect(isPlugin(123)).toBe(false);
+      expect(isPlugin([])).toBe(false);
+   });
+
+   test("returns false for objects missing required properties", () => {
+      expect(isPlugin({ name: "test" })).toBe(false);
+      expect(isPlugin({ install: () => {} })).toBe(false);
+      expect(isPlugin({})).toBe(false);
+   });
+
+   test("returns false for objects with invalid property types", () => {
+      expect(
+         isPlugin({
+            name: 123,
+            install: () => {},
+         }),
+      ).toBe(false);
+
+      expect(
+         isPlugin({
+            name: "test",
+            install: "not-a-function",
+         }),
+      ).toBe(false);
+
+      expect(
+         isPlugin({
+            name: "",
+            install: () => {},
+         }),
+      ).toBe(false);
+   });
+});
+
+describe("isValidPluginName", () => {
+   test("returns true for valid plugin names", () => {
+      expect(isValidPluginName("test")).toBe(true);
+      expect(isValidPluginName("test-plugin")).toBe(true);
+      expect(isValidPluginName("testPlugin")).toBe(true);
+      expect(isValidPluginName("test_plugin")).toBe(true);
+      expect(isValidPluginName("test123")).toBe(true);
+      expect(isValidPluginName("TEST")).toBe(true);
+      expect(isValidPluginName("my-awesome-plugin")).toBe(true);
+   });
+
+   test("returns false for invalid plugin names", () => {
+      expect(isValidPluginName("")).toBe(false);
+      expect(isValidPluginName("a")).toBe(false); // Too short
+      expect(isValidPluginName("test plugin")).toBe(false); // Space
+      expect(isValidPluginName("test@plugin")).toBe(false); // Special char
+      expect(isValidPluginName("test.plugin")).toBe(false); // Period
+      expect(isValidPluginName("test/plugin")).toBe(false); // Slash
+      expect(isValidPluginName("-test")).toBe(false); // Starts with hyphen
+      expect(isValidPluginName("test-")).toBe(false); // Ends with hyphen
+      expect(isValidPluginName("_test")).toBe(false); // Starts with underscore
+      expect(isValidPluginName("test_")).toBe(false); // Ends with underscore
+   });
+
+   test("returns false for non-string values", () => {
+      expect(isValidPluginName(null as any)).toBe(false);
+      expect(isValidPluginName(undefined as any)).toBe(false);
+      expect(isValidPluginName(123 as any)).toBe(false);
+      expect(isValidPluginName({} as any)).toBe(false);
+      expect(isValidPluginName([] as any)).toBe(false);
+   });
+});
+
+describe("plugin integration", () => {
+   test("createPlugin works with DateTime.extend", () => {
+      const plugin = createPlugin("test-integration", (DateTimeClass) => {
+         // Add a test method to the prototype
+         (DateTimeClass.prototype as any).testMethod = () => "test-result";
+      });
+
+      // Register the plugin
+      DateTime.extend(plugin);
+
+      // Check that plugin is registered
+      expect(DateTime.hasPlugin("test-integration")).toBe(true);
+
+      // Check that method was added
+      const dt = new DateTime();
+      expect((dt as any).testMethod()).toBe("test-result");
+   });
+
+   test("plugin install function receives options", () => {
+      let receivedOptions: Record<string, unknown> | undefined;
+
+      const plugin = createPlugin("test-options", (DateTimeClass, options) => {
+         receivedOptions = options;
+      });
+
+      const options = { foo: "bar", baz: 123 };
+      DateTime.extend(plugin, options);
+
+      expect(receivedOptions).toEqual(options);
+   });
+
+   test("plugin can add static methods", () => {
+      const plugin = createPlugin("test-static", (DateTimeClass) => {
+         (DateTimeClass as any).staticMethod = () => new DateTimeClass();
+      });
+
+      DateTime.extend(plugin);
+
+      expect(typeof (DateTime as any).staticMethod).toBe("function");
+      expect((DateTime as any).staticMethod()).toBeInstanceOf(DateTime);
+   });
+
+   test("multiple plugins can be registered", () => {
+      const plugin1 = createPlugin("multi-plugin-1", (DateTimeClass) => {
+         (DateTimeClass.prototype as any).method1 = () => "method1";
+      });
+
+      const plugin2 = createPlugin("multi-plugin-2", (DateTimeClass) => {
+         (DateTimeClass.prototype as any).method2 = () => "method2";
+      });
+
+      DateTime.extend(plugin1);
+      DateTime.extend(plugin2);
+
+      expect(DateTime.hasPlugin("multi-plugin-1")).toBe(true);
+      expect(DateTime.hasPlugin("multi-plugin-2")).toBe(true);
+
+      const dt = new DateTime();
+      expect((dt as any).method1()).toBe("method1");
+      expect((dt as any).method2()).toBe("method2");
+   });
+});