@f-o-t/datetime 0.1.0

package/src/plugins/plugin-base.ts

@@ -0,0 +1,104 @@
+import type { DateTimeClass, DateTimePlugin } from "../types.ts";
+
+/**
+ * Helper function to create a DateTime plugin
+ *
+ * @param name - Unique plugin name
+ * @param install - Installation function that extends the DateTime class
+ * @returns A DateTimePlugin object
+ *
+ * @example
+ * ```ts
+ * const myPlugin = createPlugin("myPlugin", (DateTimeClass, options) => {
+ *   // Extend DateTime prototype
+ *   DateTimeClass.prototype.myMethod = function() {
+ *     return this.valueOf();
+ *   };
+ *
+ *   // Add static methods
+ *   DateTimeClass.myStaticMethod = function() {
+ *     return new DateTimeClass();
+ *   };
+ * });
+ *
+ * // Register the plugin
+ * DateTime.extend(myPlugin);
+ * ```
+ */
+export function createPlugin(
+   name: string,
+   install: (
+      DateTimeClass: DateTimeClass,
+      options?: Record<string, unknown>,
+   ) => void,
+): DateTimePlugin {
+   if (!name || typeof name !== "string") {
+      throw new Error("Plugin name must be a non-empty string");
+   }
+
+   if (typeof install !== "function") {
+      throw new Error("Plugin install must be a function");
+   }
+
+   return {
+      name,
+      install,
+   };
+}
+
+/**
+ * Type guard to check if an object is a valid DateTimePlugin
+ *
+ * @param obj - Object to check
+ * @returns true if object is a valid DateTimePlugin
+ */
+export function isPlugin(obj: unknown): obj is DateTimePlugin {
+   if (!obj || typeof obj !== "object") {
+      return false;
+   }
+
+   const plugin = obj as Partial<DateTimePlugin>;
+
+   return (
+      typeof plugin.name === "string" &&
+      plugin.name.length > 0 &&
+      typeof plugin.install === "function"
+   );
+}
+
+/**
+ * Validates that a plugin name follows naming conventions
+ *
+ * @param name - Plugin name to validate
+ * @returns true if name is valid, false otherwise
+ *
+ * @remarks
+ * Valid plugin names:
+ * - Must be a non-empty string
+ * - Should use kebab-case or camelCase
+ * - Should not contain spaces or special characters (except hyphens)
+ * - Should be descriptive and unique
+ */
+export function isValidPluginName(name: string): boolean {
+   if (!name || typeof name !== "string") {
+      return false;
+   }
+
+   // Check for valid characters (alphanumeric, hyphens, underscores)
+   const validNamePattern = /^[a-zA-Z0-9-_]+$/;
+   if (!validNamePattern.test(name)) {
+      return false;
+   }
+
+   // Check minimum length
+   if (name.length < 2) {
+      return false;
+   }
+
+   // Should not start or end with special characters
+   if (/^[-_]|[-_]$/.test(name)) {
+      return false;
+   }
+
+   return true;
+}

package/src/plugins/relative-time/index.ts

@@ -0,0 +1,169 @@
+import type { DateTime } from "../../core/datetime";
+import type { DateTimeClass } from "../../types";
+import { createPlugin } from "../plugin-base";
+
+/**
+ * Time thresholds for relative time formatting (in seconds)
+ */
+const THRESHOLDS = {
+   second: 45, // 0-45 seconds
+   minute: 90, // 45-90 seconds
+   hour: 2700, // 45 minutes - 1.5 hours
+   day: 75600, // 21 hours threshold for switching to days
+   month: 2592000, // ~30 days
+   year: 31536000, // ~365 days
+};
+
+/**
+ * Formats a relative time string
+ * @param diff - Time difference in seconds
+ * @param isPast - Whether the time is in the past
+ * @returns Human-readable relative time string
+ */
+function formatRelativeTime(diff: number, isPast: boolean): string {
+   const absDiff = Math.abs(diff);
+
+   // Handle zero difference
+   if (absDiff === 0 || absDiff < THRESHOLDS.second) {
+      return isPast || diff === 0 ? "a few seconds ago" : "in a few seconds";
+   } else if (absDiff < THRESHOLDS.minute) {
+      return isPast ? "a minute ago" : "in a minute";
+   } else if (absDiff < THRESHOLDS.hour) {
+      const value = Math.round(absDiff / 60);
+      const unit = value === 1 ? "minute" : "minutes";
+      return isPast ? `${value} ${unit} ago` : `in ${value} ${unit}`;
+   } else if (absDiff < THRESHOLDS.day) {
+      const value = Math.round(absDiff / 3600);
+      if (value === 1) {
+         return isPast ? "an hour ago" : "in an hour";
+      }
+      const unit = "hours";
+      return isPast ? `${value} ${unit} ago` : `in ${value} ${unit}`;
+   } else if (absDiff < THRESHOLDS.month) {
+      const value = Math.round(absDiff / 86400);
+      if (value === 1) {
+         return isPast ? "a day ago" : "in a day";
+      }
+      const unit = "days";
+      return isPast ? `${value} ${unit} ago` : `in ${value} ${unit}`;
+   } else if (absDiff < THRESHOLDS.year) {
+      const value = Math.round(absDiff / 2592000);
+      if (value === 1) {
+         return isPast ? "a month ago" : "in a month";
+      }
+      const unit = "months";
+      return isPast ? `${value} ${unit} ago` : `in ${value} ${unit}`;
+   } else {
+      const value = Math.round(absDiff / 31536000);
+      if (value === 1) {
+         return isPast ? "a year ago" : "in a year";
+      }
+      const unit = "years";
+      return isPast ? `${value} ${unit} ago` : `in ${value} ${unit}`;
+   }
+}
+
+/**
+ * Extended DateTime interface with relative time methods
+ */
+declare module "../../core/datetime" {
+   interface DateTime {
+      /**
+       * Returns a human-readable string representing the time from now
+       * @returns Relative time string (e.g., "2 hours ago", "in 3 days")
+       *
+       * @example
+       * ```ts
+       * dt.fromNow() // "2 hours ago"
+       * dt.fromNow() // "in 3 days"
+       * ```
+       */
+      fromNow(): string;
+
+      /**
+       * Returns a human-readable string representing the time to now
+       * Opposite of fromNow()
+       * @returns Relative time string
+       *
+       * @example
+       * ```ts
+       * dt.toNow() // "in 2 hours"
+       * dt.toNow() // "3 days ago"
+       * ```
+       */
+      toNow(): string;
+
+      /**
+       * Returns a human-readable string representing the time from another DateTime
+       * @param other - DateTime instance to compare against
+       * @returns Relative time string
+       *
+       * @example
+       * ```ts
+       * dt1.from(dt2) // "2 hours ago"
+       * dt1.from(dt2) // "in 3 days"
+       * ```
+       */
+      from(other: DateTime): string;
+
+      /**
+       * Returns a human-readable string representing the time to another DateTime
+       * Opposite of from()
+       * @param other - DateTime instance to compare against
+       * @returns Relative time string
+       *
+       * @example
+       * ```ts
+       * dt1.to(dt2) // "in 2 hours"
+       * dt1.to(dt2) // "3 days ago"
+       * ```
+       */
+      to(other: DateTime): string;
+   }
+}
+
+/**
+ * Relative Time plugin for DateTime
+ * Adds methods for human-readable relative time formatting
+ */
+export const relativeTimePlugin = createPlugin(
+   "relative-time",
+   (DateTimeClass: DateTimeClass) => {
+      // Add instance methods
+      DateTimeClass.prototype.fromNow = function (): string {
+         const now = new DateTimeClass();
+         const diffMs = this.valueOf() - now.valueOf();
+         const diffSeconds = diffMs / 1000;
+         const isPast = diffSeconds < 0;
+
+         return formatRelativeTime(diffSeconds, isPast);
+      };
+
+      DateTimeClass.prototype.toNow = function (): string {
+         const now = new DateTimeClass();
+         const diffMs = this.valueOf() - now.valueOf();
+         const diffSeconds = diffMs / 1000;
+         const isPast = diffSeconds < 0;
+
+         // Reverse the direction for toNow
+         return formatRelativeTime(diffSeconds, !isPast);
+      };
+
+      DateTimeClass.prototype.from = function (other: DateTime): string {
+         const diffMs = this.valueOf() - other.valueOf();
+         const diffSeconds = diffMs / 1000;
+         const isPast = diffSeconds < 0;
+
+         return formatRelativeTime(diffSeconds, isPast);
+      };
+
+      DateTimeClass.prototype.to = function (other: DateTime): string {
+         const diffMs = this.valueOf() - other.valueOf();
+         const diffSeconds = diffMs / 1000;
+         const isPast = diffSeconds < 0;
+
+         // Reverse the direction for to
+         return formatRelativeTime(diffSeconds, !isPast);
+      };
+   },
+);

package/src/plugins/relative-time/relative-time.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from "bun:test";
+import { DateTime } from "../../core/datetime";
+import { relativeTimePlugin } from "./index";
+
+describe("Relative Time Plugin", () => {
+   // Install plugin before running tests
+   DateTime.extend(relativeTimePlugin);
+
+   // Use a fixed reference time for testing
+   const referenceTime = new DateTime("2024-01-15T12:00:00.000Z");
+
+   describe("from()", () => {
+      it("should return 'a few seconds ago' for recent past", () => {
+         const dt = new DateTime("2024-01-15T11:59:55.000Z"); // 5 seconds before
+         expect((dt as any).from(referenceTime)).toBe("a few seconds ago");
+      });
+
+      it("should return 'a minute ago' for 1 minute", () => {
+         const dt = new DateTime("2024-01-15T11:59:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("a minute ago");
+      });
+
+      it("should return 'X minutes ago' for multiple minutes", () => {
+         const dt = new DateTime("2024-01-15T11:45:00.000Z"); // 15 minutes before
+         expect((dt as any).from(referenceTime)).toBe("15 minutes ago");
+      });
+
+      it("should return 'an hour ago' for 1 hour", () => {
+         const dt = new DateTime("2024-01-15T11:00:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("an hour ago");
+      });
+
+      it("should return 'X hours ago' for multiple hours", () => {
+         const dt = new DateTime("2024-01-15T09:00:00.000Z"); // 3 hours before
+         expect((dt as any).from(referenceTime)).toBe("3 hours ago");
+      });
+
+      it("should return 'a day ago' for 1 day", () => {
+         const dt = new DateTime("2024-01-14T12:00:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("a day ago");
+      });
+
+      it("should return 'X days ago' for multiple days", () => {
+         const dt = new DateTime("2024-01-10T12:00:00.000Z"); // 5 days before
+         expect((dt as any).from(referenceTime)).toBe("5 days ago");
+      });
+
+      it("should return 'a month ago' for 1 month", () => {
+         const dt = new DateTime("2023-12-15T12:00:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("a month ago");
+      });
+
+      it("should return 'X months ago' for multiple months", () => {
+         const dt = new DateTime("2023-10-15T12:00:00.000Z"); // 3 months before
+         expect((dt as any).from(referenceTime)).toBe("3 months ago");
+      });
+
+      it("should return 'a year ago' for 1 year", () => {
+         const dt = new DateTime("2023-01-15T12:00:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("a year ago");
+      });
+
+      it("should return 'X years ago' for multiple years", () => {
+         const dt = new DateTime("2021-01-15T12:00:00.000Z"); // 3 years before
+         expect((dt as any).from(referenceTime)).toBe("3 years ago");
+      });
+
+      it("should return 'in a few seconds' for near future", () => {
+         const dt = new DateTime("2024-01-15T12:00:05.000Z"); // 5 seconds after
+         expect((dt as any).from(referenceTime)).toBe("in a few seconds");
+      });
+
+      it("should return 'in a minute' for 1 minute future", () => {
+         const dt = new DateTime("2024-01-15T12:01:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("in a minute");
+      });
+
+      it("should return 'in X minutes' for multiple minutes future", () => {
+         const dt = new DateTime("2024-01-15T12:15:00.000Z"); // 15 minutes after
+         expect((dt as any).from(referenceTime)).toBe("in 15 minutes");
+      });
+
+      it("should return 'in an hour' for 1 hour future", () => {
+         const dt = new DateTime("2024-01-15T13:00:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("in an hour");
+      });
+
+      it("should return 'in X hours' for multiple hours future", () => {
+         const dt = new DateTime("2024-01-15T15:00:00.000Z"); // 3 hours after
+         expect((dt as any).from(referenceTime)).toBe("in 3 hours");
+      });
+
+      it("should return 'in a day' for 1 day future", () => {
+         const dt = new DateTime("2024-01-16T12:00:00.000Z");
+         expect((dt as any).from(referenceTime)).toBe("in a day");
+      });
+
+      it("should return 'in X days' for multiple days future", () => {
+         const dt = new DateTime("2024-01-20T12:00:00.000Z"); // 5 days after
+         expect((dt as any).from(referenceTime)).toBe("in 5 days");
+      });
+
+      it("should handle same time", () => {
+         const dt1 = new DateTime("2024-01-15T12:00:00.000Z");
+         const dt2 = new DateTime("2024-01-15T12:00:00.000Z");
+         expect((dt1 as any).from(dt2)).toBe("a few seconds ago");
+      });
+
+      it("should handle days calculation", () => {
+         const dt1 = new DateTime("2024-01-15T12:00:00.000Z");
+         const dt2 = new DateTime("2024-01-10T12:00:00.000Z");
+         expect((dt2 as any).from(dt1)).toBe("5 days ago");
+      });
+   });
+
+   describe("to()", () => {
+      it("should return opposite of from() for past", () => {
+         const dt = new DateTime("2024-01-15T11:00:00.000Z"); // 1 hour before
+         expect((dt as any).to(referenceTime)).toBe("in an hour");
+      });
+
+      it("should return opposite of from() for future", () => {
+         const dt = new DateTime("2024-01-15T13:00:00.000Z"); // 1 hour after
+         expect((dt as any).to(referenceTime)).toBe("an hour ago");
+      });
+   });
+
+   describe("fromNow() and toNow()", () => {
+      it("should return a string for fromNow()", () => {
+         const dt = new DateTime("2024-01-01T12:00:00.000Z");
+         const result = (dt as any).fromNow();
+         expect(typeof result).toBe("string");
+         expect(result.length).toBeGreaterThan(0);
+      });
+
+      it("should return a string for toNow()", () => {
+         const dt = new DateTime("2024-01-01T12:00:00.000Z");
+         const result = (dt as any).toNow();
+         expect(typeof result).toBe("string");
+         expect(result.length).toBeGreaterThan(0);
+      });
+
+      it("fromNow and toNow should be opposites", () => {
+         const dt = new DateTime("2024-01-01T12:00:00.000Z");
+         const fromResult = (dt as any).fromNow();
+         const toResult = (dt as any).toNow();
+
+         // One should contain "ago" and the other "in", or both could be "a few seconds"
+         const hasAgo = fromResult.includes("ago");
+         const hasIn = toResult.includes("in");
+         expect(hasAgo || hasIn || fromResult.includes("few seconds")).toBe(
+            true,
+         );
+      });
+   });
+
+   describe("Chaining", () => {
+      it("should work with other DateTime methods", () => {
+         const dt = new DateTime("2024-01-15T11:00:00.000Z");
+         const relative = (dt.addHours(1) as any).from(referenceTime);
+         expect(relative).toBe("a few seconds ago");
+      });
+   });
+});

package/src/plugins/timezone/index.ts

@@ -0,0 +1,152 @@
+import type { DateTime } from "../../core/datetime";
+import type { DateTimeClass } from "../../types";
+import { createPlugin } from "../plugin-base";
+
+/**
+ * Validates a timezone string using Intl.DateTimeFormat
+ * @param timezone - IANA timezone string to validate
+ * @returns true if valid, false otherwise
+ */
+function isValidTimezone(timezone: string): boolean {
+   if (!timezone || typeof timezone !== "string") {
+      return false;
+   }
+
+   try {
+      // Use Intl.DateTimeFormat to validate timezone
+      new Intl.DateTimeFormat("en-US", { timeZone: timezone });
+      return true;
+   } catch {
+      return false;
+   }
+}
+
+/**
+ * Gets the system's local timezone
+ * @returns IANA timezone string for local timezone
+ */
+function getLocalTimezone(): string {
+   return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+
+/**
+ * Extended DateTime interface with timezone methods
+ */
+declare module "../../core/datetime" {
+   interface DateTime {
+      /**
+       * Sets the timezone for this DateTime instance
+       * @param timezone - IANA timezone string (e.g., "America/New_York")
+       * @returns New DateTime instance with timezone set
+       */
+      tz(timezone: string): DateTime;
+
+      /**
+       * Converts this DateTime to a different timezone
+       * @param timezone - IANA timezone string
+       * @returns New DateTime instance in the specified timezone
+       */
+      toTimezone(timezone: string): DateTime;
+
+      /**
+       * Converts this DateTime to UTC timezone
+       * @returns New DateTime instance in UTC
+       */
+      utc(): DateTime;
+
+      /**
+       * Converts this DateTime to local system timezone
+       * @returns New DateTime instance in local timezone
+       */
+      local(): DateTime;
+
+      /**
+       * Gets the current timezone of this DateTime instance
+       * @returns IANA timezone string
+       */
+      getTimezone(): string;
+
+      /**
+       * Internal timezone storage
+       * @private
+       */
+      _timezone?: string;
+   }
+}
+
+/**
+ * Extended DateTimeClass interface with static timezone method
+ */
+declare module "../../types" {
+   interface DateTimeClass {
+      /**
+       * Creates a DateTime instance in a specific timezone
+       * @param input - Date input
+       * @param timezone - IANA timezone string
+       * @returns DateTime instance in the specified timezone
+       */
+      tz(input: any, timezone: string): DateTime;
+   }
+}
+
+/**
+ * Timezone plugin for DateTime
+ * Adds timezone support using IANA timezone strings
+ */
+export const timezonePlugin = createPlugin(
+   "timezone",
+   (DateTimeClass: DateTimeClass) => {
+      // Add instance methods
+      DateTimeClass.prototype.tz = function (timezone: string): DateTime {
+         if (!isValidTimezone(timezone)) {
+            throw new Error(`Invalid timezone: ${timezone}`);
+         }
+
+         // Create new instance with same timestamp but different timezone
+         const newInstance = new DateTimeClass(this.valueOf());
+         (newInstance as any)._timezone = timezone;
+         return newInstance;
+      };
+
+      DateTimeClass.prototype.toTimezone = function (
+         timezone: string,
+      ): DateTime {
+         if (!isValidTimezone(timezone)) {
+            throw new Error(`Invalid timezone: ${timezone}`);
+         }
+
+         // Convert to the new timezone (same as tz for now, as we preserve moment in time)
+         const newInstance = new DateTimeClass(this.valueOf());
+         (newInstance as any)._timezone = timezone;
+         return newInstance;
+      };
+
+      DateTimeClass.prototype.utc = function (): DateTime {
+         const newInstance = new DateTimeClass(this.valueOf());
+         (newInstance as any)._timezone = "UTC";
+         return newInstance;
+      };
+
+      DateTimeClass.prototype.local = function (): DateTime {
+         const localTz = getLocalTimezone();
+         const newInstance = new DateTimeClass(this.valueOf());
+         (newInstance as any)._timezone = localTz;
+         return newInstance;
+      };
+
+      DateTimeClass.prototype.getTimezone = function (): string {
+         return (this as any)._timezone || "UTC";
+      };
+
+      // Add static method
+      (DateTimeClass as any).tz = (input: any, timezone: string): DateTime => {
+         if (!isValidTimezone(timezone)) {
+            throw new Error(`Invalid timezone: ${timezone}`);
+         }
+
+         const instance = new DateTimeClass(input);
+         (instance as any)._timezone = timezone;
+         return instance;
+      };
+   },
+);