@intech-software/chronera 0.1.3 → 0.1.5

package/dist/operations/timezone.d.ts

@@ -0,0 +1,28 @@
+import type { FormatInTimeZoneOptions, Instant, SameTimeZoneOptions, TimeZoneId, TimeZoneOffsetFormat, TimeZoneOffsetInfo } from "../public-types.js";
+/**
+ * Formats an Instant or Date in the specified IANA target time zone using a pattern string.
+ *
+ * @param instant - The source Instant or JavaScript Date.
+ * @param timeZone - The canonical or valid IANA time zone identifier (e.g. "Asia/Bangkok", "America/New_York").
+ * @param pattern - An LDML pattern string (e.g. "yyyy-MM-dd HH:mm:ss", "yyyy-MM-dd HH:mm:ss XXX", "hh:mm a zzz").
+ * @param optionsOrLocale - Optional locale string or FormatInTimeZoneOptions object.
+ * @returns The formatted date/time string.
+ */
+export declare function formatInTimeZone(instant: Instant | Date, timeZone: TimeZoneId, pattern: string, optionsOrLocale?: string | Readonly<FormatInTimeZoneOptions>): string;
+/**
+ * Computes the time zone offset at the given instant (or current time if omitted).
+ */
+export declare function getTimeZoneOffset(timeZone: TimeZoneId, instant?: Instant | Date, format?: "string"): string;
+export declare function getTimeZoneOffset(timeZone: TimeZoneId, instant: Instant | Date | undefined, format: "minutes"): number;
+export declare function getTimeZoneOffset(timeZone: TimeZoneId, instant: Instant | Date | undefined, format: "totalSeconds"): number;
+export declare function getTimeZoneOffset(timeZone: TimeZoneId, instant: Instant | Date | undefined, format: "object"): TimeZoneOffsetInfo;
+export declare function getTimeZoneOffset(timeZone: TimeZoneId, instant?: Instant | Date, format?: TimeZoneOffsetFormat): string | number | TimeZoneOffsetInfo;
+/**
+ * Checks whether two IANA time zone identifiers are equivalent.
+ *
+ * @param tz1 - The first time zone identifier.
+ * @param tz2 - The second time zone identifier.
+ * @param options - Mode ("canonical" | "offset") and optional reference instant for offset comparison.
+ * @returns true if equivalent according to the specified mode; otherwise false.
+ */
+export declare function isSameTimeZone(tz1: TimeZoneId, tz2: TimeZoneId, options?: "canonical" | "offset" | SameTimeZoneOptions): boolean;

package/dist/operations/timezone.js

@@ -0,0 +1,120 @@
+import { projectInstantToZonedFields, validateTimeZone, } from "../runtime/timezone.js";
+import { formatWithPatternWithRegistry } from "../format/format-pattern.js";
+import { defaultCalendarRegistry } from "../calendar/registry.js";
+import { instantFromDate } from "../core/instant.js";
+import { ChroneraError } from "../errors/errors.js";
+function toInstant(input) {
+    if (input instanceof Date) {
+        return instantFromDate(input);
+    }
+    if (typeof input === "object" &&
+        input !== null &&
+        "kind" in input &&
+        "epochMilliseconds" in input &&
+        input.kind === "instant" &&
+        typeof input.epochMilliseconds === "number") {
+        return input;
+    }
+    throw new ChroneraError("CHRONERA_INVALID_DATE", "Expected a valid Instant or Date object.");
+}
+/**
+ * Formats an Instant or Date in the specified IANA target time zone using a pattern string.
+ *
+ * @param instant - The source Instant or JavaScript Date.
+ * @param timeZone - The canonical or valid IANA time zone identifier (e.g. "Asia/Bangkok", "America/New_York").
+ * @param pattern - An LDML pattern string (e.g. "yyyy-MM-dd HH:mm:ss", "yyyy-MM-dd HH:mm:ss XXX", "hh:mm a zzz").
+ * @param optionsOrLocale - Optional locale string or FormatInTimeZoneOptions object.
+ * @returns The formatted date/time string.
+ */
+export function formatInTimeZone(instant, timeZone, pattern, optionsOrLocale) {
+    validateTimeZone(timeZone);
+    const targetInstant = toInstant(instant);
+    const options = typeof optionsOrLocale === "string"
+        ? { locale: optionsOrLocale }
+        : (optionsOrLocale ?? {});
+    return formatWithPatternWithRegistry(defaultCalendarRegistry, targetInstant, pattern, {
+        ...options,
+        timeZone,
+    });
+}
+export function getTimeZoneOffset(timeZone, instant, format) {
+    validateTimeZone(timeZone);
+    const targetInstant = instant === undefined
+        ? { kind: "instant", epochMilliseconds: Date.now() }
+        : toInstant(instant);
+    const fields = projectInstantToZonedFields(targetInstant, timeZone);
+    const zonedUtcMs = Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour, fields.minute, fields.second, fields.millisecond);
+    const offsetMs = zonedUtcMs - targetInstant.epochMilliseconds;
+    const minutes = Math.round(offsetMs / 60000);
+    const totalSeconds = Math.round(offsetMs / 1000);
+    const sign = minutes >= 0 ? "+" : "-";
+    const absMinutes = Math.abs(minutes);
+    const hours = Math.floor(absMinutes / 60);
+    const mins = absMinutes % 60;
+    const formatted = `${sign}${String(hours).padStart(2, "0")}:${String(mins).padStart(2, "0")}`;
+    const selectedFormat = format ?? "string";
+    if (selectedFormat === "string") {
+        return formatted;
+    }
+    if (selectedFormat === "minutes") {
+        return minutes;
+    }
+    if (selectedFormat === "totalSeconds") {
+        return totalSeconds;
+    }
+    // format === "object": determine DST
+    const janInstant = {
+        kind: "instant",
+        epochMilliseconds: Date.UTC(fields.year, 0, 1, 12, 0, 0),
+    };
+    const julInstant = {
+        kind: "instant",
+        epochMilliseconds: Date.UTC(fields.year, 6, 1, 12, 0, 0),
+    };
+    const janFields = projectInstantToZonedFields(janInstant, timeZone);
+    const julFields = projectInstantToZonedFields(julInstant, timeZone);
+    const janOffsetMs = Date.UTC(janFields.year, janFields.month - 1, janFields.day, janFields.hour, janFields.minute, janFields.second) - janInstant.epochMilliseconds;
+    const julOffsetMs = Date.UTC(julFields.year, julFields.month - 1, julFields.day, julFields.hour, julFields.minute, julFields.second) - julInstant.epochMilliseconds;
+    const standardOffsetMs = Math.min(janOffsetMs, julOffsetMs);
+    const isDst = offsetMs > standardOffsetMs && janOffsetMs !== julOffsetMs;
+    return {
+        formatted,
+        minutes,
+        totalSeconds,
+        isDst,
+    };
+}
+/**
+ * Checks whether two IANA time zone identifiers are equivalent.
+ *
+ * @param tz1 - The first time zone identifier.
+ * @param tz2 - The second time zone identifier.
+ * @param options - Mode ("canonical" | "offset") and optional reference instant for offset comparison.
+ * @returns true if equivalent according to the specified mode; otherwise false.
+ */
+export function isSameTimeZone(tz1, tz2, options) {
+    validateTimeZone(tz1);
+    validateTimeZone(tz2);
+    const mode = typeof options === "string" ? options : (options?.mode ?? "canonical");
+    if (mode === "canonical") {
+        const trimmed1 = tz1.trim();
+        const trimmed2 = tz2.trim();
+        if (trimmed1 === trimmed2)
+            return true;
+        const canonical1 = new Intl.DateTimeFormat(undefined, {
+            timeZone: trimmed1,
+        }).resolvedOptions().timeZone;
+        const canonical2 = new Intl.DateTimeFormat(undefined, {
+            timeZone: trimmed2,
+        }).resolvedOptions().timeZone;
+        return canonical1 === canonical2;
+    }
+    // mode === "offset"
+    const refInstant = typeof options === "object" && options?.instant !== undefined
+        ? options.instant
+        : undefined;
+    const offset1 = getTimeZoneOffset(tz1, refInstant, "minutes");
+    const offset2 = getTimeZoneOffset(tz2, refInstant, "minutes");
+    return offset1 === offset2;
+}
+//# sourceMappingURL=timezone.js.map

package/dist/operations/timezone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezone.js","sourceRoot":"","sources":["../../src/operations/timezone.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  projectInstantToZonedFields,\n  validateTimeZone,\n} from \"../runtime/timezone.js\";\nimport { formatWithPatternWithRegistry } from \"../format/format-pattern.js\";\nimport { defaultCalendarRegistry } from \"../calendar/registry.js\";\nimport { instantFromDate } from \"../core/instant.js\";\nimport { ChroneraError } from \"../errors/errors.js\";\n\nimport type {\n  FormatInTimeZoneOptions,\n  Instant,\n  SameTimeZoneOptions,\n  TimeZoneId,\n  TimeZoneOffsetFormat,\n  TimeZoneOffsetInfo,\n} from \"../public-types.js\";\n\nfunction toInstant(input: unknown): Instant {\n  if (input instanceof Date) {\n    return instantFromDate(input);\n  }\n  if (\n    typeof input === \"object\" &&\n    input !== null &&\n    \"kind\" in input &&\n    \"epochMilliseconds\" in input &&\n    (input as Record<string, unknown>).kind === \"instant\" &&\n    typeof (input as Record<string, unknown>).epochMilliseconds === \"number\"\n  ) {\n    return input as Instant;\n  }\n  throw new ChroneraError(\n    \"CHRONERA_INVALID_DATE\",\n    \"Expected a valid Instant or Date object.\",\n  );\n}\n\n/**\n * Formats an Instant or Date in the specified IANA target time zone using a pattern string.\n *\n * @param instant - The source Instant or JavaScript Date.\n * @param timeZone - The canonical or valid IANA time zone identifier (e.g. \"Asia/Bangkok\", \"America/New_York\").\n * @param pattern - An LDML pattern string (e.g. \"yyyy-MM-dd HH:mm:ss\", \"yyyy-MM-dd HH:mm:ss XXX\", \"hh:mm a zzz\").\n * @param optionsOrLocale - Optional locale string or FormatInTimeZoneOptions object.\n * @returns The formatted date/time string.\n */\nexport function formatInTimeZone(\n  instant: Instant | Date,\n  timeZone: TimeZoneId,\n  pattern: string,\n  optionsOrLocale?: string | Readonly<FormatInTimeZoneOptions>,\n): string {\n  validateTimeZone(timeZone);\n  const targetInstant = toInstant(instant);\n\n  const options: FormatInTimeZoneOptions =\n    typeof optionsOrLocale === \"string\"\n      ? { locale: optionsOrLocale }\n      : (optionsOrLocale ?? {});\n\n  return formatWithPatternWithRegistry(\n    defaultCalendarRegistry,\n    targetInstant,\n    pattern,\n    {\n      ...options,\n      timeZone,\n    },\n  );\n}\n\n/**\n * Computes the time zone offset at the given instant (or current time if omitted).\n */\nexport function getTimeZoneOffset(\n  timeZone: TimeZoneId,\n  instant?: Instant | Date,\n  format?: \"string\",\n): string;\nexport function getTimeZoneOffset(\n  timeZone: TimeZoneId,\n  instant: Instant | Date | undefined,\n  format: \"minutes\",\n): number;\nexport function getTimeZoneOffset(\n  timeZone: TimeZoneId,\n  instant: Instant | Date | undefined,\n  format: \"totalSeconds\",\n): number;\nexport function getTimeZoneOffset(\n  timeZone: TimeZoneId,\n  instant: Instant | Date | undefined,\n  format: \"object\",\n): TimeZoneOffsetInfo;\nexport function getTimeZoneOffset(\n  timeZone: TimeZoneId,\n  instant?: Instant | Date,\n  format?: TimeZoneOffsetFormat,\n): string | number | TimeZoneOffsetInfo;\nexport function getTimeZoneOffset(\n  timeZone: TimeZoneId,\n  instant?: Instant | Date,\n  format?: TimeZoneOffsetFormat,\n): string | number | TimeZoneOffsetInfo {\n  validateTimeZone(timeZone);\n\n  const targetInstant: Instant =\n    instant === undefined\n      ? { kind: \"instant\", epochMilliseconds: Date.now() }\n      : toInstant(instant);\n\n  const fields = projectInstantToZonedFields(targetInstant, timeZone);\n  const zonedUtcMs = Date.UTC(\n    fields.year,\n    fields.month - 1,\n    fields.day,\n    fields.hour,\n    fields.minute,\n    fields.second,\n    fields.millisecond,\n  );\n\n  const offsetMs = zonedUtcMs - targetInstant.epochMilliseconds;\n  const minutes = Math.round(offsetMs / 60000);\n  const totalSeconds = Math.round(offsetMs / 1000);\n\n  const sign = minutes >= 0 ? \"+\" : \"-\";\n  const absMinutes = Math.abs(minutes);\n  const hours = Math.floor(absMinutes / 60);\n  const mins = absMinutes % 60;\n  const formatted = `${sign}${String(hours).padStart(2, \"0\")}:${String(mins).padStart(2, \"0\")}`;\n\n  const selectedFormat = format ?? \"string\";\n  if (selectedFormat === \"string\") {\n    return formatted;\n  }\n  if (selectedFormat === \"minutes\") {\n    return minutes;\n  }\n  if (selectedFormat === \"totalSeconds\") {\n    return totalSeconds;\n  }\n\n  // format === \"object\": determine DST\n  const janInstant: Instant = {\n    kind: \"instant\",\n    epochMilliseconds: Date.UTC(fields.year, 0, 1, 12, 0, 0),\n  };\n  const julInstant: Instant = {\n    kind: \"instant\",\n    epochMilliseconds: Date.UTC(fields.year, 6, 1, 12, 0, 0),\n  };\n\n  const janFields = projectInstantToZonedFields(janInstant, timeZone);\n  const julFields = projectInstantToZonedFields(julInstant, timeZone);\n\n  const janOffsetMs =\n    Date.UTC(\n      janFields.year,\n      janFields.month - 1,\n      janFields.day,\n      janFields.hour,\n      janFields.minute,\n      janFields.second,\n    ) - janInstant.epochMilliseconds;\n\n  const julOffsetMs =\n    Date.UTC(\n      julFields.year,\n      julFields.month - 1,\n      julFields.day,\n      julFields.hour,\n      julFields.minute,\n      julFields.second,\n    ) - julInstant.epochMilliseconds;\n\n  const standardOffsetMs = Math.min(janOffsetMs, julOffsetMs);\n  const isDst = offsetMs > standardOffsetMs && janOffsetMs !== julOffsetMs;\n\n  return {\n    formatted,\n    minutes,\n    totalSeconds,\n    isDst,\n  };\n}\n\n/**\n * Checks whether two IANA time zone identifiers are equivalent.\n *\n * @param tz1 - The first time zone identifier.\n * @param tz2 - The second time zone identifier.\n * @param options - Mode (\"canonical\" | \"offset\") and optional reference instant for offset comparison.\n * @returns true if equivalent according to the specified mode; otherwise false.\n */\nexport function isSameTimeZone(\n  tz1: TimeZoneId,\n  tz2: TimeZoneId,\n  options?: \"canonical\" | \"offset\" | SameTimeZoneOptions,\n): boolean {\n  validateTimeZone(tz1);\n  validateTimeZone(tz2);\n\n  const mode =\n    typeof options === \"string\" ? options : (options?.mode ?? \"canonical\");\n\n  if (mode === \"canonical\") {\n    const trimmed1 = tz1.trim();\n    const trimmed2 = tz2.trim();\n    if (trimmed1 === trimmed2) return true;\n\n    const canonical1 = new Intl.DateTimeFormat(undefined, {\n      timeZone: trimmed1,\n    }).resolvedOptions().timeZone;\n    const canonical2 = new Intl.DateTimeFormat(undefined, {\n      timeZone: trimmed2,\n    }).resolvedOptions().timeZone;\n\n    return canonical1 === canonical2;\n  }\n\n  // mode === \"offset\"\n  const refInstant =\n    typeof options === \"object\" && options?.instant !== undefined\n      ? options.instant\n      : undefined;\n\n  const offset1 = getTimeZoneOffset(tz1, refInstant, \"minutes\");\n  const offset2 = getTimeZoneOffset(tz2, refInstant, \"minutes\");\n\n  return offset1 === offset2;\n}\n"]}

package/dist/public-types.d.ts

@@ -210,3 +210,19 @@ export interface ChroneraInstance {
     resolvedOptions(): ResolvedChroneraOptions;
 }
 export type { IsoWeekFields } from "./core/iso-week.js";
+export interface FormatInTimeZoneOptions {
+    readonly locale?: string;
+    readonly numberingSystem?: NumberingSystemId;
+    readonly calendar?: CalendarId;
+}
+export type TimeZoneOffsetFormat = "string" | "minutes" | "totalSeconds" | "object";
+export interface TimeZoneOffsetInfo {
+    readonly formatted: string;
+    readonly minutes: number;
+    readonly totalSeconds: number;
+    readonly isDst: boolean;
+}
+export interface SameTimeZoneOptions {
+    readonly instant?: Instant | Date;
+    readonly mode?: "canonical" | "offset";
+}

package/dist/public-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"public-types.js","sourceRoot":"","sources":["../src/public-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { DayOfYearFields } from \"./core/day-of-year.js\";\nimport type {\n  FiscalFields,\n  FiscalOptions,\n  QuarterNumber,\n} from \"./core/fiscal.js\";\nimport type { ChroneraErrorCode } from \"./errors/error-codes.js\";\nimport type { PresetName } from \"./format/presets/types.js\";\nimport type { Rfc2822Options } from \"./format/rfc2822.js\";\n\nexport type {\n  ChroneraErrorCode,\n  DayOfYearFields,\n  FiscalFields,\n  FiscalOptions,\n  PresetName,\n  QuarterNumber,\n  Rfc2822Options,\n};\n\nexport type BuiltInCalendarId =\n  | \"iso8601\"\n  | \"gregory\"\n  | \"buddhist\"\n  | \"islamic\"\n  | \"islamic-civil\"\n  | \"islamic-tbla\"\n  | \"islamic-umalqura\"\n  | \"persian\"\n  | \"hebrew\"\n  | \"japanese\"\n  | \"roc\"\n  | \"indian\"\n  | \"coptic\"\n  | \"ethiopic\"\n  | \"chinese\"\n  | \"dangi\";\n\ntype ExtensibleIdentifier = string & Record<never, never>;\n\nexport type CalendarId = BuiltInCalendarId | ExtensibleIdentifier;\n\nexport type LocaleId = string;\nexport type TimeZoneId = string;\nexport type NumberingSystemId = string;\nexport type EraId = string;\nexport type MonthCode = `M${string}`;\n\nexport interface Instant {\n  readonly kind: \"instant\";\n  readonly epochMilliseconds: number;\n}\n\nexport interface LocalDate {\n  readonly kind: \"local-date\";\n  readonly year: number;\n  readonly month: number;\n  readonly day: number;\n}\n\nexport interface LocalTime {\n  readonly kind: \"local-time\";\n  readonly hour: number;\n  readonly minute: number;\n  readonly second: number;\n  readonly millisecond: number;\n}\n\nexport interface LocalDateTime {\n  readonly kind: \"local-date-time\";\n  readonly date: LocalDate;\n  readonly time: LocalTime;\n}\n\nexport interface CalendarDate {\n  readonly kind: \"calendar-date\";\n  readonly calendar: CalendarId;\n  readonly era?: EraId;\n  readonly eraYear?: number;\n  readonly year: number;\n  readonly monthCode: MonthCode;\n  readonly month?: number;\n  readonly day: number;\n}\n\nexport interface ZonedDateTime {\n  readonly kind: \"zoned-date-time\";\n  readonly instant: Instant;\n  readonly timeZone: TimeZoneId;\n  readonly calendar: CalendarId;\n}\n\nexport type FormatDateInput = LocalDate | CalendarDate | Instant | Date;\nexport type DateOrCalendarDate = LocalDate | CalendarDate;\nexport type TimeOrDateTimeOrInstant = LocalTime | LocalDateTime | Instant;\nexport type IntervalInclusivity = \"()\" | \"[]\" | \"[)\" | \"(]\";\n\nexport interface Duration {\n  readonly years?: number;\n  readonly months?: number;\n  readonly weeks?: number;\n  readonly days?: number;\n  readonly hours?: number;\n  readonly minutes?: number;\n  readonly seconds?: number;\n  readonly milliseconds?: number;\n}\n\nexport interface DateRange<TDate> {\n  readonly start: TDate;\n  readonly end: TDate;\n  readonly startInclusive: boolean;\n  readonly endInclusive: boolean;\n}\n\nexport interface CalendarConversionMetadata {\n  readonly requestedCalendar: CalendarId;\n  readonly resolvedCalendar: CalendarId;\n  readonly engine: \"chronera\" | \"runtime-intl\" | \"custom\";\n  readonly algorithm: string;\n  readonly deterministic: boolean;\n  readonly dataVersion?: string;\n  readonly validFrom?: LocalDate;\n  readonly validTo?: LocalDate;\n}\n\nexport interface CalendarConversionResult {\n  readonly value: CalendarDate;\n  readonly metadata: CalendarConversionMetadata;\n}\n\nexport interface ChroneraIssue {\n  readonly code: ChroneraErrorCode;\n  readonly message: string;\n  readonly path?: readonly (string | number)[];\n}\n\nexport type SafeParseResult<T> =\n  | {\n      readonly success: true;\n      readonly value: T;\n    }\n  | {\n      readonly success: false;\n      readonly error: ChroneraIssue;\n    };\n\nexport type Comparison = -1 | 0 | 1;\n\nexport interface CalendarPlugin {\n  readonly id: CalendarId;\n  readonly algorithm: string;\n  readonly deterministic: boolean;\n  readonly validFrom: LocalDate;\n  readonly validTo: LocalDate;\n  toIsoDate(date: CalendarDate): LocalDate;\n  fromIsoDate(date: LocalDate): CalendarDate;\n  validate(date: CalendarDate): readonly ChroneraIssue[];\n}\n\nexport interface ChroneraConfig {\n  readonly locale?: LocaleId;\n  readonly calendar?: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n  readonly calendars?: readonly CalendarPlugin[];\n  readonly formatterCacheSize?: number;\n}\n\nexport interface ResolvedChroneraOptions {\n  readonly locale: LocaleId;\n  readonly calendar: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone: TimeZoneId;\n  readonly formatterCacheSize: number;\n}\n\nexport interface FormatDateBaseOptions {\n  readonly locale?: LocaleId;\n  readonly calendar?: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n  readonly fallback?: \"error\";\n}\n\nexport type FormatDateOptions = FormatDateBaseOptions &\n  (\n    | {\n        readonly style?: \"numeric\" | \"short\" | \"medium\" | \"long\" | \"full\";\n        readonly preset?: never;\n      }\n    | {\n        readonly style?: never;\n        readonly preset: PresetName;\n      }\n  );\n\nexport interface FormatTimeOptions {\n  readonly locale?: LocaleId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n  readonly style?: \"short\" | \"medium\" | \"long\" | \"full\";\n  readonly hourCycle?: \"h11\" | \"h12\" | \"h23\" | \"h24\";\n}\n\nexport interface FormatDateTimeOptions extends FormatDateBaseOptions {\n  readonly dateStyle?: \"short\" | \"medium\" | \"long\" | \"full\";\n  readonly timeStyle?: \"short\" | \"medium\" | \"long\" | \"full\";\n  readonly hourCycle?: \"h11\" | \"h12\" | \"h23\" | \"h24\";\n}\n\nexport type FormatDateRangeOptions = FormatDateOptions & {\n  readonly collapse?: \"auto\" | \"none\";\n};\n\nexport interface FormatRelativeOptions {\n  readonly relativeTo: Instant | LocalDate;\n  readonly locale?: LocaleId;\n  readonly numeric?: \"always\" | \"auto\";\n  readonly unit?:\n    \"second\" | \"minute\" | \"hour\" | \"day\" | \"week\" | \"month\" | \"year\";\n  readonly timeZone?: TimeZoneId;\n}\n\nexport interface PatternFormatOptions {\n  readonly locale?: LocaleId;\n  readonly calendar?: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n}\n\nexport interface ParseLocalDateOptions {\n  readonly pattern?: string;\n  readonly locale?: LocaleId;\n  readonly calendar?: \"gregory\" | \"iso8601\";\n  readonly numberingSystem?: NumberingSystemId;\n}\n\nexport interface ParseInstantOptions {\n  readonly excessFractionalSeconds?: \"reject\" | \"truncate\" | \"round\";\n}\n\nexport interface ConvertCalendarOptions {\n  readonly fallback?: \"error\";\n}\n\nexport interface CalendarCapabilities {\n  readonly calendar: CalendarId;\n  readonly maturity:\n    \"stable\" | \"experimental\" | \"runtime-dependent\" | \"planned\" | \"unsupported\";\n  readonly canFormat: boolean;\n  readonly canParse: boolean;\n  readonly canConvertFromAbsoluteDate: boolean;\n  readonly canConvertToAbsoluteDate: boolean;\n  readonly canValidate: boolean;\n  readonly canAddYears: boolean;\n  readonly canAddMonths: boolean;\n  readonly deterministic: boolean;\n  readonly algorithm?: string;\n  readonly dataVersion?: string;\n  readonly validFrom?: LocalDate;\n  readonly validTo?: LocalDate;\n}\n\nexport interface RuntimeCapabilities {\n  readonly hasDateTimeFormat: boolean;\n  readonly hasFormatToParts: boolean;\n  readonly hasFormatRange: boolean;\n  readonly hasRelativeTimeFormat: boolean;\n  readonly hasLocale: boolean;\n  readonly hasSupportedValuesOf: boolean;\n  readonly hasTemporal: boolean;\n  readonly calendars: Readonly<Record<string, boolean>>;\n  readonly timeZones: Readonly<Record<string, boolean>>;\n}\n\nexport interface ChroneraInstance {\n  formatDate(\n    input: FormatDateInput,\n    options?: Readonly<FormatDateOptions>,\n  ): string;\n  parseLocalDate(\n    input: string,\n    options?: Readonly<ParseLocalDateOptions>,\n  ): LocalDate;\n  convertCalendarDate(\n    source: CalendarDate,\n    targetCalendar: CalendarId,\n    options?: Readonly<ConvertCalendarOptions>,\n  ): CalendarConversionResult;\n  resolvedOptions(): ResolvedChroneraOptions;\n}\n\nexport type { IsoWeekFields } from \"./core/iso-week.js\";\n"]}
+{"version":3,"file":"public-types.js","sourceRoot":"","sources":["../src/public-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { DayOfYearFields } from \"./core/day-of-year.js\";\nimport type {\n  FiscalFields,\n  FiscalOptions,\n  QuarterNumber,\n} from \"./core/fiscal.js\";\nimport type { ChroneraErrorCode } from \"./errors/error-codes.js\";\nimport type { PresetName } from \"./format/presets/types.js\";\nimport type { Rfc2822Options } from \"./format/rfc2822.js\";\n\nexport type {\n  ChroneraErrorCode,\n  DayOfYearFields,\n  FiscalFields,\n  FiscalOptions,\n  PresetName,\n  QuarterNumber,\n  Rfc2822Options,\n};\n\nexport type BuiltInCalendarId =\n  | \"iso8601\"\n  | \"gregory\"\n  | \"buddhist\"\n  | \"islamic\"\n  | \"islamic-civil\"\n  | \"islamic-tbla\"\n  | \"islamic-umalqura\"\n  | \"persian\"\n  | \"hebrew\"\n  | \"japanese\"\n  | \"roc\"\n  | \"indian\"\n  | \"coptic\"\n  | \"ethiopic\"\n  | \"chinese\"\n  | \"dangi\";\n\ntype ExtensibleIdentifier = string & Record<never, never>;\n\nexport type CalendarId = BuiltInCalendarId | ExtensibleIdentifier;\n\nexport type LocaleId = string;\nexport type TimeZoneId = string;\nexport type NumberingSystemId = string;\nexport type EraId = string;\nexport type MonthCode = `M${string}`;\n\nexport interface Instant {\n  readonly kind: \"instant\";\n  readonly epochMilliseconds: number;\n}\n\nexport interface LocalDate {\n  readonly kind: \"local-date\";\n  readonly year: number;\n  readonly month: number;\n  readonly day: number;\n}\n\nexport interface LocalTime {\n  readonly kind: \"local-time\";\n  readonly hour: number;\n  readonly minute: number;\n  readonly second: number;\n  readonly millisecond: number;\n}\n\nexport interface LocalDateTime {\n  readonly kind: \"local-date-time\";\n  readonly date: LocalDate;\n  readonly time: LocalTime;\n}\n\nexport interface CalendarDate {\n  readonly kind: \"calendar-date\";\n  readonly calendar: CalendarId;\n  readonly era?: EraId;\n  readonly eraYear?: number;\n  readonly year: number;\n  readonly monthCode: MonthCode;\n  readonly month?: number;\n  readonly day: number;\n}\n\nexport interface ZonedDateTime {\n  readonly kind: \"zoned-date-time\";\n  readonly instant: Instant;\n  readonly timeZone: TimeZoneId;\n  readonly calendar: CalendarId;\n}\n\nexport type FormatDateInput = LocalDate | CalendarDate | Instant | Date;\nexport type DateOrCalendarDate = LocalDate | CalendarDate;\nexport type TimeOrDateTimeOrInstant = LocalTime | LocalDateTime | Instant;\nexport type IntervalInclusivity = \"()\" | \"[]\" | \"[)\" | \"(]\";\n\nexport interface Duration {\n  readonly years?: number;\n  readonly months?: number;\n  readonly weeks?: number;\n  readonly days?: number;\n  readonly hours?: number;\n  readonly minutes?: number;\n  readonly seconds?: number;\n  readonly milliseconds?: number;\n}\n\nexport interface DateRange<TDate> {\n  readonly start: TDate;\n  readonly end: TDate;\n  readonly startInclusive: boolean;\n  readonly endInclusive: boolean;\n}\n\nexport interface CalendarConversionMetadata {\n  readonly requestedCalendar: CalendarId;\n  readonly resolvedCalendar: CalendarId;\n  readonly engine: \"chronera\" | \"runtime-intl\" | \"custom\";\n  readonly algorithm: string;\n  readonly deterministic: boolean;\n  readonly dataVersion?: string;\n  readonly validFrom?: LocalDate;\n  readonly validTo?: LocalDate;\n}\n\nexport interface CalendarConversionResult {\n  readonly value: CalendarDate;\n  readonly metadata: CalendarConversionMetadata;\n}\n\nexport interface ChroneraIssue {\n  readonly code: ChroneraErrorCode;\n  readonly message: string;\n  readonly path?: readonly (string | number)[];\n}\n\nexport type SafeParseResult<T> =\n  | {\n      readonly success: true;\n      readonly value: T;\n    }\n  | {\n      readonly success: false;\n      readonly error: ChroneraIssue;\n    };\n\nexport type Comparison = -1 | 0 | 1;\n\nexport interface CalendarPlugin {\n  readonly id: CalendarId;\n  readonly algorithm: string;\n  readonly deterministic: boolean;\n  readonly validFrom: LocalDate;\n  readonly validTo: LocalDate;\n  toIsoDate(date: CalendarDate): LocalDate;\n  fromIsoDate(date: LocalDate): CalendarDate;\n  validate(date: CalendarDate): readonly ChroneraIssue[];\n}\n\nexport interface ChroneraConfig {\n  readonly locale?: LocaleId;\n  readonly calendar?: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n  readonly calendars?: readonly CalendarPlugin[];\n  readonly formatterCacheSize?: number;\n}\n\nexport interface ResolvedChroneraOptions {\n  readonly locale: LocaleId;\n  readonly calendar: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone: TimeZoneId;\n  readonly formatterCacheSize: number;\n}\n\nexport interface FormatDateBaseOptions {\n  readonly locale?: LocaleId;\n  readonly calendar?: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n  readonly fallback?: \"error\";\n}\n\nexport type FormatDateOptions = FormatDateBaseOptions &\n  (\n    | {\n        readonly style?: \"numeric\" | \"short\" | \"medium\" | \"long\" | \"full\";\n        readonly preset?: never;\n      }\n    | {\n        readonly style?: never;\n        readonly preset: PresetName;\n      }\n  );\n\nexport interface FormatTimeOptions {\n  readonly locale?: LocaleId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n  readonly style?: \"short\" | \"medium\" | \"long\" | \"full\";\n  readonly hourCycle?: \"h11\" | \"h12\" | \"h23\" | \"h24\";\n}\n\nexport interface FormatDateTimeOptions extends FormatDateBaseOptions {\n  readonly dateStyle?: \"short\" | \"medium\" | \"long\" | \"full\";\n  readonly timeStyle?: \"short\" | \"medium\" | \"long\" | \"full\";\n  readonly hourCycle?: \"h11\" | \"h12\" | \"h23\" | \"h24\";\n}\n\nexport type FormatDateRangeOptions = FormatDateOptions & {\n  readonly collapse?: \"auto\" | \"none\";\n};\n\nexport interface FormatRelativeOptions {\n  readonly relativeTo: Instant | LocalDate;\n  readonly locale?: LocaleId;\n  readonly numeric?: \"always\" | \"auto\";\n  readonly unit?:\n    \"second\" | \"minute\" | \"hour\" | \"day\" | \"week\" | \"month\" | \"year\";\n  readonly timeZone?: TimeZoneId;\n}\n\nexport interface PatternFormatOptions {\n  readonly locale?: LocaleId;\n  readonly calendar?: CalendarId;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly timeZone?: TimeZoneId;\n}\n\nexport interface ParseLocalDateOptions {\n  readonly pattern?: string;\n  readonly locale?: LocaleId;\n  readonly calendar?: \"gregory\" | \"iso8601\";\n  readonly numberingSystem?: NumberingSystemId;\n}\n\nexport interface ParseInstantOptions {\n  readonly excessFractionalSeconds?: \"reject\" | \"truncate\" | \"round\";\n}\n\nexport interface ConvertCalendarOptions {\n  readonly fallback?: \"error\";\n}\n\nexport interface CalendarCapabilities {\n  readonly calendar: CalendarId;\n  readonly maturity:\n    \"stable\" | \"experimental\" | \"runtime-dependent\" | \"planned\" | \"unsupported\";\n  readonly canFormat: boolean;\n  readonly canParse: boolean;\n  readonly canConvertFromAbsoluteDate: boolean;\n  readonly canConvertToAbsoluteDate: boolean;\n  readonly canValidate: boolean;\n  readonly canAddYears: boolean;\n  readonly canAddMonths: boolean;\n  readonly deterministic: boolean;\n  readonly algorithm?: string;\n  readonly dataVersion?: string;\n  readonly validFrom?: LocalDate;\n  readonly validTo?: LocalDate;\n}\n\nexport interface RuntimeCapabilities {\n  readonly hasDateTimeFormat: boolean;\n  readonly hasFormatToParts: boolean;\n  readonly hasFormatRange: boolean;\n  readonly hasRelativeTimeFormat: boolean;\n  readonly hasLocale: boolean;\n  readonly hasSupportedValuesOf: boolean;\n  readonly hasTemporal: boolean;\n  readonly calendars: Readonly<Record<string, boolean>>;\n  readonly timeZones: Readonly<Record<string, boolean>>;\n}\n\nexport interface ChroneraInstance {\n  formatDate(\n    input: FormatDateInput,\n    options?: Readonly<FormatDateOptions>,\n  ): string;\n  parseLocalDate(\n    input: string,\n    options?: Readonly<ParseLocalDateOptions>,\n  ): LocalDate;\n  convertCalendarDate(\n    source: CalendarDate,\n    targetCalendar: CalendarId,\n    options?: Readonly<ConvertCalendarOptions>,\n  ): CalendarConversionResult;\n  resolvedOptions(): ResolvedChroneraOptions;\n}\n\nexport type { IsoWeekFields } from \"./core/iso-week.js\";\n\nexport interface FormatInTimeZoneOptions {\n  readonly locale?: string;\n  readonly numberingSystem?: NumberingSystemId;\n  readonly calendar?: CalendarId;\n}\n\nexport type TimeZoneOffsetFormat =\n  \"string\" | \"minutes\" | \"totalSeconds\" | \"object\";\n\nexport interface TimeZoneOffsetInfo {\n  readonly formatted: string;\n  readonly minutes: number;\n  readonly totalSeconds: number;\n  readonly isDst: boolean;\n}\n\nexport interface SameTimeZoneOptions {\n  readonly instant?: Instant | Date;\n  readonly mode?: \"canonical\" | \"offset\";\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intech-software/chronera",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A universal, type-safe date, time, calendar, era, locale, and timezone toolkit for JavaScript and TypeScript.",
   "keywords": [
     "date",
@@ -53,6 +53,10 @@
     "./parse": {
       "types": "./dist/parse/index.d.ts",
       "import": "./dist/parse/index.js"
+    },
+    "./holidays": {
+      "types": "./dist/holidays/index.d.ts",
+      "import": "./dist/holidays/index.js"
     }
   },
   "files": [
@@ -98,6 +102,11 @@
       "name": "Parse (@intech-software/chronera/parse)",
       "path": "dist/parse/index.js",
       "limit": "10 KB"
+    },
+    {
+      "name": "Holidays (@intech-software/chronera/holidays)",
+      "path": "dist/holidays/index.js",
+      "limit": "10 KB"
     }
   ],
   "publishConfig": {