@f-o-t/datetime 0.1.0

package/src/plugins/timezone/timezone.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "bun:test";
+import { DateTime } from "../../core/datetime";
+import { timezonePlugin } from "./index";
+
+describe("Timezone Plugin", () => {
+   // Install plugin before running tests
+   DateTime.extend(timezonePlugin);
+
+   describe("tz()", () => {
+      it("should set timezone and return DateTime instance", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).tz("America/New_York");
+
+         expect(result).toBeInstanceOf(DateTime);
+         expect((result as any)._timezone).toBe("America/New_York");
+      });
+
+      it("should handle valid IANA timezone strings", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+
+         expect(() => (dt as any).tz("America/New_York")).not.toThrow();
+         expect(() => (dt as any).tz("Europe/London")).not.toThrow();
+         expect(() => (dt as any).tz("Asia/Tokyo")).not.toThrow();
+         expect(() => (dt as any).tz("UTC")).not.toThrow();
+      });
+
+      it("should throw error for invalid timezone", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+
+         expect(() => (dt as any).tz("Invalid/Timezone")).toThrow();
+         expect(() => (dt as any).tz("")).toThrow();
+      });
+
+      it("should preserve the same moment in time", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const withTz = (dt as any).tz("America/New_York");
+
+         expect(withTz.valueOf()).toBe(dt.valueOf());
+      });
+   });
+
+   describe("toTimezone()", () => {
+      it("should convert to specified timezone", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).toTimezone("America/New_York");
+
+         expect(result).toBeInstanceOf(DateTime);
+         expect((result as any)._timezone).toBe("America/New_York");
+      });
+
+      it("should handle timezone conversion correctly", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const nyTime = (dt as any).toTimezone("America/New_York");
+
+         // UTC 12:00 should be 07:00 in NY (EST is UTC-5)
+         expect(nyTime.valueOf()).toBe(dt.valueOf());
+      });
+
+      it("should chain with other methods", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).toTimezone("America/New_York").addHours(2);
+
+         expect(result).toBeInstanceOf(DateTime);
+      });
+   });
+
+   describe("utc()", () => {
+      it("should set timezone to UTC", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).tz("America/New_York").utc();
+
+         expect(result).toBeInstanceOf(DateTime);
+         expect((result as any)._timezone).toBe("UTC");
+      });
+
+      it("should preserve timestamp", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const withTz = (dt as any).tz("America/New_York");
+         const backToUtc = withTz.utc();
+
+         expect(backToUtc.valueOf()).toBe(dt.valueOf());
+      });
+   });
+
+   describe("local()", () => {
+      it("should set timezone to local", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const result = (dt as any).local();
+
+         expect(result).toBeInstanceOf(DateTime);
+         expect((result as any)._timezone).toBeDefined();
+      });
+
+      it("should preserve timestamp", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const localTime = (dt as any).local();
+
+         expect(localTime.valueOf()).toBe(dt.valueOf());
+      });
+   });
+
+   describe("getTimezone()", () => {
+      it("should return current timezone", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+         const withTz = (dt as any).tz("America/New_York");
+
+         expect((withTz as any).getTimezone()).toBe("America/New_York");
+      });
+
+      it("should return UTC for default instances", () => {
+         const dt = new DateTime("2024-01-15T12:00:00.000Z");
+
+         expect((dt as any).getTimezone()).toBe("UTC");
+      });
+   });
+
+   describe("Static tz() method", () => {
+      it("should create DateTime in specified timezone", () => {
+         const dt = (DateTime as any).tz(
+            "2024-01-15T12:00:00",
+            "America/New_York",
+         );
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect((dt as any)._timezone).toBe("America/New_York");
+      });
+
+      it("should handle current time when no input provided", () => {
+         const dt = (DateTime as any).tz(undefined, "America/New_York");
+
+         expect(dt).toBeInstanceOf(DateTime);
+         expect((dt as any)._timezone).toBe("America/New_York");
+      });
+   });
+});

package/src/schemas.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it } from "bun:test";
+import {
+   DateInputSchema,
+   DateTimeConfigSchema,
+   DateTimePluginSchema,
+   FormatOptionsSchema,
+   ISODateOnlySchema,
+   ISODateSchema,
+   ISOTimeOnlySchema,
+   ParseOptionsSchema,
+   TimeUnitSchema,
+} from "./schemas";
+
+describe("TimeUnitSchema", () => {
+   it("should accept valid time units", () => {
+      expect(TimeUnitSchema.parse("millisecond")).toBe("millisecond");
+      expect(TimeUnitSchema.parse("second")).toBe("second");
+      expect(TimeUnitSchema.parse("minute")).toBe("minute");
+      expect(TimeUnitSchema.parse("hour")).toBe("hour");
+      expect(TimeUnitSchema.parse("day")).toBe("day");
+      expect(TimeUnitSchema.parse("week")).toBe("week");
+      expect(TimeUnitSchema.parse("month")).toBe("month");
+      expect(TimeUnitSchema.parse("year")).toBe("year");
+   });
+
+   it("should reject invalid time units", () => {
+      expect(() => TimeUnitSchema.parse("invalid")).toThrow();
+      expect(() => TimeUnitSchema.parse("seconds")).toThrow();
+      expect(() => TimeUnitSchema.parse("")).toThrow();
+   });
+});
+
+describe("DateInputSchema", () => {
+   it("should accept Date objects", () => {
+      const date = new Date();
+      expect(DateInputSchema.parse(date)).toBe(date);
+   });
+
+   it("should accept strings", () => {
+      expect(DateInputSchema.parse("2024-01-15")).toBe("2024-01-15");
+      expect(DateInputSchema.parse("2024-01-15T10:30:00Z")).toBe(
+         "2024-01-15T10:30:00Z",
+      );
+   });
+
+   it("should accept numbers", () => {
+      expect(DateInputSchema.parse(1705315200000)).toBe(1705315200000);
+      expect(DateInputSchema.parse(0)).toBe(0);
+   });
+
+   it("should accept DateTime-like objects", () => {
+      const dateTimeLike = {
+         toDate: () => new Date(),
+      } as any;
+      expect(DateInputSchema.parse(dateTimeLike)).toBe(dateTimeLike);
+   });
+
+   it("should reject invalid inputs", () => {
+      expect(() => DateInputSchema.parse(null)).toThrow();
+      expect(() => DateInputSchema.parse(undefined)).toThrow();
+      expect(() => DateInputSchema.parse({})).toThrow();
+      expect(() => DateInputSchema.parse([])).toThrow();
+      expect(() => DateInputSchema.parse({ notADateTime: true })).toThrow();
+   });
+});
+
+describe("DateTimeConfigSchema", () => {
+   it("should accept valid config objects", () => {
+      expect(
+         DateTimeConfigSchema.parse({
+            timezone: "America/New_York",
+            locale: "en-US",
+            utc: false,
+            strict: true,
+         }),
+      ).toEqual({
+         timezone: "America/New_York",
+         locale: "en-US",
+         utc: false,
+         strict: true,
+      });
+   });
+
+   it("should accept partial config objects", () => {
+      expect(DateTimeConfigSchema.parse({ timezone: "Europe/London" })).toEqual(
+         {
+            timezone: "Europe/London",
+         },
+      );
+      expect(DateTimeConfigSchema.parse({ utc: true })).toEqual({ utc: true });
+      expect(DateTimeConfigSchema.parse({})).toEqual({});
+   });
+
+   it("should reject invalid config objects", () => {
+      expect(() => DateTimeConfigSchema.parse({ timezone: 123 })).toThrow();
+      expect(() => DateTimeConfigSchema.parse({ locale: true })).toThrow();
+      expect(() => DateTimeConfigSchema.parse({ utc: "yes" })).toThrow();
+      expect(() => DateTimeConfigSchema.parse({ strict: 1 })).toThrow();
+   });
+});
+
+describe("FormatOptionsSchema", () => {
+   it("should accept valid format options", () => {
+      expect(
+         FormatOptionsSchema.parse({
+            locale: "en-US",
+            timezone: "America/New_York",
+         }),
+      ).toEqual({
+         locale: "en-US",
+         timezone: "America/New_York",
+      });
+   });
+
+   it("should accept partial format options", () => {
+      expect(FormatOptionsSchema.parse({ locale: "fr-FR" })).toEqual({
+         locale: "fr-FR",
+      });
+      expect(FormatOptionsSchema.parse({ timezone: "Asia/Tokyo" })).toEqual({
+         timezone: "Asia/Tokyo",
+      });
+      expect(FormatOptionsSchema.parse({})).toEqual({});
+   });
+
+   it("should reject invalid format options", () => {
+      expect(() => FormatOptionsSchema.parse({ locale: 123 })).toThrow();
+      expect(() => FormatOptionsSchema.parse({ timezone: false })).toThrow();
+   });
+});
+
+describe("ParseOptionsSchema", () => {
+   it("should accept valid parse options", () => {
+      expect(
+         ParseOptionsSchema.parse({
+            strict: true,
+            format: "YYYY-MM-DD",
+            timezone: "UTC",
+         }),
+      ).toEqual({
+         strict: true,
+         format: "YYYY-MM-DD",
+         timezone: "UTC",
+      });
+   });
+
+   it("should accept partial parse options", () => {
+      expect(ParseOptionsSchema.parse({ strict: false })).toEqual({
+         strict: false,
+      });
+      expect(ParseOptionsSchema.parse({ format: "DD/MM/YYYY" })).toEqual({
+         format: "DD/MM/YYYY",
+      });
+      expect(ParseOptionsSchema.parse({})).toEqual({});
+   });
+
+   it("should reject invalid parse options", () => {
+      expect(() => ParseOptionsSchema.parse({ strict: "yes" })).toThrow();
+      expect(() => ParseOptionsSchema.parse({ format: 123 })).toThrow();
+      expect(() => ParseOptionsSchema.parse({ timezone: true })).toThrow();
+   });
+});
+
+describe("ISODateSchema", () => {
+   it("should accept valid ISO 8601 datetime strings", () => {
+      expect(ISODateSchema.parse("2024-01-15T10:30:00Z")).toBe(
+         "2024-01-15T10:30:00Z",
+      );
+      expect(ISODateSchema.parse("2024-01-15T10:30:00.123Z")).toBe(
+         "2024-01-15T10:30:00.123Z",
+      );
+      expect(ISODateSchema.parse("2024-01-15T10:30:00.12Z")).toBe(
+         "2024-01-15T10:30:00.12Z",
+      );
+      expect(ISODateSchema.parse("2024-01-15T10:30:00.1Z")).toBe(
+         "2024-01-15T10:30:00.1Z",
+      );
+      expect(ISODateSchema.parse("2024-01-15T10:30:00+05:30")).toBe(
+         "2024-01-15T10:30:00+05:30",
+      );
+      expect(ISODateSchema.parse("2024-01-15T10:30:00-08:00")).toBe(
+         "2024-01-15T10:30:00-08:00",
+      );
+   });
+
+   it("should reject invalid ISO 8601 datetime strings", () => {
+      expect(() => ISODateSchema.parse("2024-01-15")).toThrow();
+      expect(() => ISODateSchema.parse("2024-01-15T10:30:00")).toThrow();
+      expect(() => ISODateSchema.parse("2024-01-15 10:30:00Z")).toThrow();
+      expect(() => ISODateSchema.parse("15-01-2024T10:30:00Z")).toThrow();
+      expect(() => ISODateSchema.parse("not a date")).toThrow();
+   });
+});
+
+describe("ISODateOnlySchema", () => {
+   it("should accept valid ISO 8601 date-only strings", () => {
+      expect(ISODateOnlySchema.parse("2024-01-15")).toBe("2024-01-15");
+      expect(ISODateOnlySchema.parse("2024-12-31")).toBe("2024-12-31");
+      expect(ISODateOnlySchema.parse("2000-01-01")).toBe("2000-01-01");
+   });
+
+   it("should reject invalid date-only strings", () => {
+      expect(() => ISODateOnlySchema.parse("2024-01-15T10:30:00Z")).toThrow();
+      expect(() => ISODateOnlySchema.parse("15-01-2024")).toThrow();
+      expect(() => ISODateOnlySchema.parse("2024-1-15")).toThrow();
+      expect(() => ISODateOnlySchema.parse("2024/01/15")).toThrow();
+      expect(() => ISODateOnlySchema.parse("not a date")).toThrow();
+   });
+});
+
+describe("ISOTimeOnlySchema", () => {
+   it("should accept valid ISO 8601 time-only strings", () => {
+      expect(ISOTimeOnlySchema.parse("10:30:00")).toBe("10:30:00");
+      expect(ISOTimeOnlySchema.parse("10:30:00.123")).toBe("10:30:00.123");
+      expect(ISOTimeOnlySchema.parse("23:59:59.999")).toBe("23:59:59.999");
+      expect(ISOTimeOnlySchema.parse("00:00:00")).toBe("00:00:00");
+   });
+
+   it("should reject invalid time-only strings", () => {
+      expect(() => ISOTimeOnlySchema.parse("10:30")).toThrow();
+      expect(() => ISOTimeOnlySchema.parse("10:30:00Z")).toThrow();
+      expect(() => ISOTimeOnlySchema.parse("10:30:00+05:30")).toThrow();
+      // Note: regex doesn't validate hour ranges, only format
+      expect(() => ISOTimeOnlySchema.parse("not a time")).toThrow();
+   });
+});
+
+describe("DateTimePluginSchema", () => {
+   it("should accept valid plugin objects", () => {
+      const plugin = {
+         name: "testPlugin",
+         install: () => {},
+      };
+      const result = DateTimePluginSchema.parse(plugin);
+      expect(result.name).toBe("testPlugin");
+      expect(typeof result.install).toBe("function");
+   });
+
+   it("should accept plugins with install function that takes parameters", () => {
+      const plugin = {
+         name: "configPlugin",
+         install: (DateTimeClass: unknown, options?: unknown) => {
+            // Plugin installation logic
+         },
+      };
+      const result = DateTimePluginSchema.parse(plugin);
+      expect(result.name).toBe("configPlugin");
+      expect(typeof result.install).toBe("function");
+   });
+
+   it("should reject plugins with empty names", () => {
+      expect(() =>
+         DateTimePluginSchema.parse({
+            name: "",
+            install: () => {},
+         }),
+      ).toThrow();
+   });
+
+   it("should reject plugins without install function", () => {
+      expect(() =>
+         DateTimePluginSchema.parse({
+            name: "testPlugin",
+         }),
+      ).toThrow();
+   });
+
+   it("should reject plugins with invalid install property", () => {
+      expect(() =>
+         DateTimePluginSchema.parse({
+            name: "testPlugin",
+            install: "not a function",
+         }),
+      ).toThrow();
+   });
+
+   it("should reject plugins without name", () => {
+      expect(() =>
+         DateTimePluginSchema.parse({
+            install: () => {},
+         }),
+      ).toThrow();
+   });
+});

package/src/schemas.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import type { DateTime } from "./types";
+
+/**
+ * Schema for time units
+ */
+export const TimeUnitSchema = z.enum([
+   "millisecond",
+   "second",
+   "minute",
+   "hour",
+   "day",
+   "week",
+   "month",
+   "year",
+]);
+
+/**
+ * Schema for DateTime input types
+ * Accepts Date, string, number, or DateTime instance
+ */
+export const DateInputSchema = z.union([
+   z.date(),
+   z.string(),
+   z.number(),
+   z.custom<DateTime>(
+      (val) =>
+         val !== null &&
+         typeof val === "object" &&
+         "toDate" in val &&
+         typeof val.toDate === "function",
+      {
+         message: "Expected DateTime instance",
+      },
+   ),
+]);
+
+/**
+ * Schema for DateTime configuration
+ */
+export const DateTimeConfigSchema = z.object({
+   timezone: z.string().optional(),
+   locale: z.string().optional(),
+   utc: z.boolean().optional(),
+   strict: z.boolean().optional(),
+});
+
+/**
+ * Schema for format options
+ */
+export const FormatOptionsSchema = z.object({
+   locale: z.string().optional(),
+   timezone: z.string().optional(),
+});
+
+/**
+ * Schema for parse options
+ */
+export const ParseOptionsSchema = z.object({
+   strict: z.boolean().optional(),
+   format: z.string().optional(),
+   timezone: z.string().optional(),
+});
+
+/**
+ * Schema for ISO 8601 date strings (full datetime with timezone)
+ * Matches: YYYY-MM-DDTHH:mm:ss.sssZ or YYYY-MM-DDTHH:mm:ss.sss±HH:mm
+ */
+export const ISODateSchema = z
+   .string()
+   .regex(
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})$/,
+      {
+         message:
+            "Invalid ISO 8601 datetime format. Expected: YYYY-MM-DDTHH:mm:ss.sssZ",
+      },
+   );
+
+/**
+ * Schema for ISO 8601 date-only strings
+ * Matches: YYYY-MM-DD
+ */
+export const ISODateOnlySchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, {
+   message: "Invalid ISO 8601 date format. Expected: YYYY-MM-DD",
+});
+
+/**
+ * Schema for ISO 8601 time-only strings
+ * Matches: HH:mm:ss or HH:mm:ss.sss
+ */
+export const ISOTimeOnlySchema = z
+   .string()
+   .regex(/^\d{2}:\d{2}:\d{2}(\.\d{1,3})?$/, {
+      message:
+         "Invalid ISO 8601 time format. Expected: HH:mm:ss or HH:mm:ss.sss",
+   });
+
+/**
+ * Schema for plugin definition
+ */
+export const DateTimePluginSchema = z.object({
+   name: z.string().min(1, "Plugin name cannot be empty"),
+   install: z.function(),
+});

package/src/types.ts

@@ -0,0 +1,122 @@
+import type { z } from "zod";
+import type { DateTime as DateTimeInstance } from "./core/datetime";
+
+/**
+ * Time units supported by the library
+ */
+export type TimeUnit =
+   | "millisecond"
+   | "second"
+   | "minute"
+   | "hour"
+   | "day"
+   | "week"
+   | "month"
+   | "year";
+
+/**
+ * DateTime instance type - re-exported from the class
+ */
+export type DateTime = DateTimeInstance;
+
+/**
+ * Input types that can be converted to DateTime
+ */
+export type DateInput = Date | string | number | DateTime;
+
+/**
+ * DateTime class type (used for plugin typing)
+ * Must be defined before DateTimePlugin to avoid forward reference
+ */
+export interface DateTimeClass {
+   new (input?: DateInput): DateTime;
+   prototype: DateTime;
+   extend: (plugin: DateTimePlugin, options?: Record<string, unknown>) => void;
+   hasPlugin: (name: string) => boolean;
+   getPlugin: (name: string) => DateTimePlugin | undefined;
+}
+
+/**
+ * Plugin definition
+ */
+export interface DateTimePlugin {
+   /**
+    * Plugin name (must be unique)
+    */
+   name: string;
+
+   /**
+    * Install function that extends the DateTime class
+    * @param DateTimeClass - The DateTime class to extend
+    * @param options - Optional plugin configuration
+    */
+   install: (
+      DateTimeClass: DateTimeClass,
+      options?: Record<string, unknown>,
+   ) => void;
+}
+
+/**
+ * Configuration options for DateTime instance creation
+ */
+export interface DateTimeConfig {
+   /**
+    * Timezone (IANA timezone string, e.g., "America/New_York")
+    * Defaults to system timezone
+    */
+   timezone?: string;
+
+   /**
+    * Locale for formatting (BCP 47 language tag, e.g., "en-US")
+    * Defaults to system locale
+    */
+   locale?: string;
+
+   /**
+    * Whether to use UTC mode
+    * @default false
+    */
+   utc?: boolean;
+
+   /**
+    * Whether parsing should be strict
+    * @default true
+    */
+   strict?: boolean;
+}
+
+/**
+ * Options for formatting dates
+ */
+export interface FormatOptions {
+   /**
+    * Locale for formatting (BCP 47 language tag)
+    */
+   locale?: string;
+
+   /**
+    * Timezone for formatting (IANA timezone string)
+    */
+   timezone?: string;
+}
+
+/**
+ * Options for parsing dates
+ */
+export interface ParseOptions {
+   /**
+    * Whether to use strict parsing
+    * @default true
+    */
+   strict?: boolean;
+
+   /**
+    * Expected format string
+    */
+   format?: string;
+
+   /**
+    * Timezone to parse in (IANA timezone string)
+    */
+   timezone?: string;
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "allowImportingTsExtensions": true,
+    "declaration": true,
+    "isolatedDeclarations": false,
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noPropertyAccessFromIndexSignature": false,
+    "noUncheckedIndexedAccess": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "skipLibCheck": true,
+    "strict": true,
+    "target": "ES2023",
+    "verbatimModuleSyntax": true
+  },
+  "exclude": [
+    "node_modules",
+    "dist",
+    "bunup.config.ts"
+  ],
+  "include": [
+    "src/**/*"
+  ]
+}