import { type MapFunction, type Maybe } from '@dereekb/util';
import { type DateRange } from './date.range';
import { DateTimezoneUtcNormalInstance, type DateTimezoneUtcNormalInstanceInput } from './date.timezone';
/**
 * A Week/Year number combination used to refer to a specific Week on a specific Year.
 *
 * 202201 is January 2022
 *
 * @semanticType
 * @semanticTopic date
 * @semanticTopic numeric
 */
export type YearWeekCode = number;
/**
 * String-version of a YearWeekCode. Usually used as a
 *
 * @semanticType
 * @semanticTopic date
 * @semanticTopic string
 */
export type YearWeekCodeString = string;
/**
 * Used for default YearWeekCode values
 */
export declare const UNKNOWN_YEAR_WEEK_CODE = 0;
export type UnknownYearWeekCode = typeof UNKNOWN_YEAR_WEEK_CODE;
/**
 * The week in the year. Starts from 1.
 *
 * @semanticType
 * @semanticTopic date
 * @semanticTopic numeric
 */
export type YearWeekCodeIndex = number;
/**
 * Extracts the week-of-year index (1-52) from a {@link YearWeekCode}.
 *
 * @param yearWeekCode - The encoded year+week code (e.g. 202401 = week 1 of 2024)
 * @returns The week index portion.
 *
 * @example
 * ```ts
 * yearWeekCodeIndex(202415); // 15
 * ```
 */
export declare function yearWeekCodeIndex(yearWeekCode: YearWeekCode): YearWeekCodeIndex;
/**
 * Pair of the YearWeekCodeIndex and the year.
 */
export interface YearWeekCodePair {
    week: YearWeekCodeIndex;
    year: number;
}
/**
 * Decodes a {@link YearWeekCode} into its year and week components.
 *
 * @param yearWeekCode - The encoded year+week code.
 * @returns The decoded pair with year and week.
 *
 * @example
 * ```ts
 * yearWeekCodePair(202415); // { year: 2024, week: 15 }
 * ```
 */
export declare function yearWeekCodePair(yearWeekCode: YearWeekCode): YearWeekCodePair;
/**
 * Creates a {@link YearWeekCodePair} from a Date using the system timezone.
 *
 * Handles year-boundary weeks correctly (e.g. Dec 31 that falls in week 1 of the next year).
 *
 * @param date - Moment whose year/week pair should be resolved.
 * @returns Year plus week-of-year derived from the moment.
 *
 * @example
 * ```ts
 * yearWeekCodePairFromDate(new Date('2024-04-15'));
 * // { year: 2024, week: 16 }
 * ```
 */
export declare function yearWeekCodePairFromDate(date: Date): YearWeekCodePair;
/**
 * Encodes a {@link YearWeekCodePair} into a single {@link YearWeekCode} number.
 *
 * @param pair - The year and week to encode.
 * @returns The encoded code (e.g. { year: 2024, week: 15 } => 202415)
 *
 * @example
 * ```ts
 * yearWeekCodeFromPair({ year: 2024, week: 15 }); // 202415
 * ```
 */
export declare function yearWeekCodeFromPair(pair: YearWeekCodePair): YearWeekCode;
/**
 * Computes the {@link YearWeekCode} for a Date, optionally in a specific timezone.
 *
 * @param date - Moment to encode.
 * @param timezone - Optional timezone (defaults to system timezone).
 * @returns Encoded year+week code.
 *
 * @example
 * ```ts
 * yearWeekCodeFromDate(new Date('2024-04-15')); // 202416
 * ```
 */
export declare function yearWeekCodeFromDate(date: Date, timezone?: YearWeekCodeDateTimezoneInput): YearWeekCode;
/**
 * A function that computes a {@link YearWeekCode} from either a Date or explicit year+week values.
 */
export type YearWeekCodeFactory = ((dateOrYear: Date | number, inputWeek?: YearWeekCodeIndex) => YearWeekCode) & {
    _normal: DateTimezoneUtcNormalInstance;
};
export type YearWeekCodeDateTimezoneInput = DateTimezoneUtcNormalInstanceInput | DateTimezoneUtcNormalInstance;
export interface YearWeekCodeConfig {
    /**
     * (Optional) Input timezone configuration for a DateTimezoneUtcNormalInstance.
     *
     * Configured to use the system timezone by default.
     */
    readonly timezone?: YearWeekCodeDateTimezoneInput;
}
/**
 * Resolves a timezone input into a {@link DateTimezoneUtcNormalInstance} for use with YearWeekCode calculations.
 *
 * Falls back to the system timezone instance if the input is falsy.
 *
 * @param input - Timezone string, config, or instance.
 * @returns The resolved normal instance.
 */
export declare function yearWeekCodeDateTimezoneInstance(input: YearWeekCodeDateTimezoneInput): DateTimezoneUtcNormalInstance;
/**
 * Computes the {@link YearWeekCode} from a Date (using system timezone) or from explicit year and week values.
 *
 * @param date - the date to compute the week code for
 * @returns the encoded year+week code
 *
 * @example
 * ```ts
 * yearWeekCode(new Date('2024-04-15')); // 202416
 * yearWeekCode(2024, 15);               // 202415
 * ```
 */
export declare function yearWeekCode(date: Date): YearWeekCode;
export declare function yearWeekCode(year: number, week: YearWeekCodeIndex): YearWeekCode;
/**
 * Creates a {@link YearWeekCodeFactory} that computes YearWeekCode values in the configured timezone.
 *
 * The factory accepts either a Date or explicit year+week values.
 *
 * @param config - Optional timezone configuration (defaults to system timezone)
 * @returns A factory function for computing YearWeekCode values.
 *
 * @example
 * ```ts
 * const factory = yearWeekCodeFactory({ timezone: 'America/Chicago' });
 * factory(new Date('2024-04-15')); // 202416
 * factory(2024, 15);               // 202415
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function yearWeekCodeFactory(config?: YearWeekCodeConfig): YearWeekCodeFactory;
/**
 * Used for returning an array of YearWeekCode values for a pre-configured date range.
 */
export type YearWeekCodeForDateRangeFactory = (dateRange: DateRange) => YearWeekCode[];
/**
 * Returns all {@link YearWeekCode} values that overlap with the given date range, using the system timezone.
 *
 * @param dateRange - Range whose covered weeks should be enumerated.
 * @returns Year/week codes for every week the range touches.
 */
export declare function yearWeekCodeForDateRange(dateRange: DateRange): YearWeekCode[];
/**
 * Returns all {@link YearWeekCode} values that overlap with the given date range, evaluated in the specified timezone.
 *
 * @param dateRange - Range whose covered weeks should be enumerated.
 * @param dateRangeTimezone - Timezone context governing week boundary calculations.
 * @returns Year/week codes for every week the range touches in the given timezone.
 */
export declare function yearWeekCodeForDateRangeInTimezone(dateRange: DateRange, dateRangeTimezone: YearWeekCodeDateTimezoneInput): YearWeekCode[];
/**
 * Creates a {@link YearWeekCodeForDateRangeFactory} that computes all week codes overlapping a date range.
 *
 * @param factory - YearWeekCodeFactory to use (defaults to system timezone).
 * @returns Factory that resolves overlapping YearWeekCode values for a DateRange.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function yearWeekCodeForDateRangeFactory(factory?: YearWeekCodeFactory): YearWeekCodeForDateRangeFactory;
/**
 * Used for returning an array of YearWeekCode values for a pre-configured date range.
 */
export type YearWeekCodeForCalendarMonthFactory = (date: Date) => YearWeekCode[];
/**
 * Returns all {@link YearWeekCode} values for the calendar month containing the given date, using the system timezone.
 *
 * @param date - Any moment inside the target calendar month.
 * @returns Year/week codes for every week the month touches.
 */
export declare function yearWeekCodeForCalendarMonth(date: Date): YearWeekCode[];
/**
 * Creates a {@link YearWeekCodeForCalendarMonthFactory} that computes all week codes for a calendar month.
 *
 * @param factory - The YearWeekCodeFactory to use (defaults to system timezone)
 * @returns A factory that accepts a Date and returns YearWeekCode values for that month.
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function yearWeekCodeForCalendarMonthFactory(factory?: YearWeekCodeFactory): YearWeekCodeForCalendarMonthFactory;
/**
 * A function that converts a {@link YearWeekCode} back to the start-of-week Date.
 */
export type YearWeekCodeDateFactory = (yearWeekCode: YearWeekCode) => Date;
export type YearWeekCodeDateConfig = Pick<YearWeekCodeConfig, 'timezone'>;
/**
 * Creates a factory that converts a {@link YearWeekCode} back into the start-of-week Date for that week.
 *
 * @param config - Optional timezone configuration.
 * @returns Resolver that maps each YearWeekCode to its corresponding start-of-week Date.
 *
 * @example
 * ```ts
 * const toDate = yearWeekCodeDateFactory({ timezone: 'America/Chicago' });
 * const weekStart = toDate(202415); // Sunday of week 15, 2024
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function yearWeekCodeDateFactory(config?: YearWeekCodeDateConfig): YearWeekCodeDateFactory;
/**
 * Returns the start-of-week Date for the given {@link YearWeekCode}, optionally in a specific timezone.
 *
 * @param yearWeekCode - The encoded year+week code.
 * @param timezone - Optional timezone (defaults to system timezone)
 * @returns Moment at the start of the specified week.
 *
 * @example
 * ```ts
 * startOfWeekForYearWeekCode(202415); // Sunday of week 15, 2024
 * ```
 */
export declare function startOfWeekForYearWeekCode(yearWeekCode: YearWeekCode, timezone?: YearWeekCodeDateTimezoneInput): Date;
/**
 * Values grouped by a YearWeekCode value.
 */
export interface YearWeekCodeGroup<B> {
    readonly items: B[];
    readonly week: YearWeekCode;
}
/**
 * Used to group the input items into an array of YearWeekCodeGroup values.
 */
export type YearWeekCodeGroupFactory<B> = (items: B[]) => YearWeekCodeGroup<B>[];
/**
 * MapFunction that reads the relevant date to use for the YearWeekCode calculation from the input item.
 */
export type YearWeekCodeDateReader<B> = MapFunction<B, Maybe<Date | YearWeekCode | YearWeekCodeString>>;
export type YearWeekCodeReader = MapFunction<YearWeekCode | YearWeekCodeString, YearWeekCode>;
export interface YearWeekCodeGroupFactoryConfig<B> {
    readonly yearWeekCodeFactory?: YearWeekCodeFactory | YearWeekCodeConfig;
    readonly yearWeekCodeReader?: YearWeekCodeReader;
    readonly dateReader: YearWeekCodeDateReader<B>;
}
/**
 * Creates a {@link YearWeekCodeGroupFactory} that groups items by their {@link YearWeekCode}.
 *
 * Uses the configured date reader to extract a date or week code from each item, then groups items that share the same week.
 *
 * @param config - Reader and factory configuration.
 * @returns A factory that groups input items by YearWeekCode.
 *
 * @example
 * ```ts
 * const group = yearWeekCodeGroupFactory({
 *   dateReader: (item) => item.date,
 * });
 * const groups = group([{ date: new Date('2024-04-15') }, { date: new Date('2024-04-16') }]);
 * // groups[0].week === 202416, groups[0].items has both items
 * ```
 *
 * @__NO_SIDE_EFFECTS__
 */
export declare function yearWeekCodeGroupFactory<B>(config: YearWeekCodeGroupFactoryConfig<B>): YearWeekCodeGroupFactory<B>;