@dereekb/date 9.24.47 → 9.25.0

package/src/lib/date/date.cell.index.d.ts

@@ -0,0 +1,375 @@
+import { Maybe, SortCompareFunction, RequiredOnKeys, ArrayOrValue, UniqueModel, IndexNumber, FactoryWithRequiredInput, DateRelativeState } from '@dereekb/util';
+import { DateCell, DateCellIndex, DateOrDateCellIndex } from './date.cell';
+import { DateRange } from './date.range';
+/**
+ * Represents a range of DateCell values.
+ */
+export interface DateCellRange extends DateCell {
+    /**
+     * Index this block ends at, inclusive. A block with i=0 and to=0 encompases only the block 0.
+     *
+     * If not provided, assumes this has no range and starts/ends at the same index, i.
+     */
+    to?: DateCellIndex;
+}
+export declare class DateCellRange extends DateCell {
+    to?: DateCellIndex;
+    constructor(template?: DateCellRange);
+}
+/**
+ * Returns true if the input is a DateCellRange.
+ *
+ * Does not check validity. Use isValidDateCellRange()
+ *
+ * @param input
+ * @returns
+ */
+export declare function isDateCellRange(input: unknown): input is DateCellRange;
+/**
+ * A DateCellIndex, DateCell, or DateCellRange
+ */
+export declare type DateCellOrDateCellIndexOrDateCellRange = DateCellIndex | DateCell | DateCellRange;
+/**
+ * Returns true if the input is a valid DateCellRange.
+ *
+ * @param input
+ * @returns
+ */
+export declare function isValidDateCellRange(input: DateCellRange): boolean;
+/**
+ * Returns true if the input is a sorted DateCellRange array and there are no repeat indexes.
+ *
+ * @param input
+ * @returns
+ */
+export declare function isValidDateCellRangeSeries(input: DateCellRange[]): boolean;
+/**
+ * Returns the lowest index between all the input date block ranges. Returns 0 by default if there is no minimum or input blocks.
+ *
+ * The input range is not expected to be sorted.
+ */
+export declare function getLeastDateCellIndexInDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellIndex;
+/**
+ * Returns the largest index between all the input date block ranges. Returns 0 by default.
+ *
+ * The input range is not expected to be sorted.
+ */
+export declare function getGreatestDateCellIndexInDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellIndex;
+export interface LeastAndGreatestDateCellIndexResult<T> {
+    leastIndex: number;
+    leastIndexItem: T;
+    greatestIndex: number;
+    greatestIndexItem: T;
+}
+/**
+ * Returns the largest index between all the input date block ranges. Returns null if the input is empty.
+ *
+ * The input range is not expected to be sorted.
+ */
+export declare function getLeastAndGreatestDateCellIndexInDateCellRanges<T extends DateCellRange>(input: T[]): Maybe<LeastAndGreatestDateCellIndexResult<T>>;
+/**
+ * Input type used for cases where a DateRange or a DateCellRange are allowed as input but used the start/end parameters in DateRange.
+ */
+export interface DateCellRangeOrDateRange {
+    start?: Maybe<DateOrDateCellIndex>;
+    end?: Maybe<DateOrDateCellIndex>;
+}
+export declare type DateOrDateCellIndexOrDateCellRange = DateOrDateCellIndex | DateCellRange;
+export declare type DateOrDateRangeOrDateCellIndexOrDateCellRange = DateRange | DateOrDateCellIndexOrDateCellRange;
+/**
+ * Creates a DateCellRange
+ *
+ * @param i
+ * @param to
+ * @returns
+ */
+export declare function dateCellRange(i: number, to?: number): DateCellRangeWithRange;
+/**
+ * Creates a DateCellRangeWithRange from the input DateCellIndex.
+ *
+ * @param dateCellIndex
+ * @returns
+ */
+export declare function dateCellRangeWithRangeFromIndex(dateCellIndex: DateCellIndex): DateCellRangeWithRange;
+/**
+ * Creates a DateCellRangeWithRange from the input DateCellIndex, DateCell, or DateCellRange.
+ *
+ * @param input
+ * @returns
+ */
+export declare function dateCellRangeWithRange(input: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeWithRange;
+/**
+ * Function that returns true if the input range covers the full range of the configured DateCellRange.
+ */
+export declare type DateCellRangeIncludedByRangeFunction = (range: DateCellOrDateCellIndexOrDateCellRange) => boolean;
+/**
+ * Creates a DateCellRangeIncludedByRangeFunction
+ *
+ * @param inputRange
+ * @returns
+ */
+export declare function dateCellRangeIncludedByRangeFunction(inputRange: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeIncludedByRangeFunction;
+/**
+ * Function that returns true if the input range overlaps the range of the configured DateCellRange.
+ */
+export declare type DateCellRangeOverlapsRangeFunction = (range: DateCellOrDateCellIndexOrDateCellRange) => boolean;
+/**
+ * Creates a DateCellRangeOverlapsRangeFunction
+ *
+ * @param inputRange
+ * @returns
+ */
+export declare function dateCellRangeOverlapsRangeFunction(inputRange: DateCellOrDateCellIndexOrDateCellRange): DateCellRangeOverlapsRangeFunction;
+/**
+ * Returns true if either of the ranges overlap eachother.
+ *
+ * @param rangeA
+ * @param rangeB
+ * @returns
+ */
+export declare function dateCellRangeOverlapsRange(rangeA: DateCellOrDateCellIndexOrDateCellRange, rangeB: DateCellOrDateCellIndexOrDateCellRange): boolean;
+/**
+ * Sorts the input ranges by index and distance (to values).
+ *
+ * In many cases sortAscendingIndexNumberRefFunction may be preferential since
+ *
+ * @returns
+ */
+export declare function sortDateCellRangeAndSizeFunction<T extends DateCellRange>(): SortCompareFunction<T>;
+/**
+ * Sorts the input date ranges. This will retain the before/after order while also sorting items by index.
+ *
+ * @param input
+ * @returns
+ */
+export declare function sortDateCellRanges<T extends DateCellRange>(input: T[]): T[];
+/**
+ * DateCellRange that is known to have a to value.
+ */
+export declare type DateCellRangeWithRange = RequiredOnKeys<DateCellRange, 'to'>;
+/**
+ * Groups the input values into DateCellRange values.
+ *
+ * @param input
+ */
+export declare function groupToDateCellRanges(input: (DateCell | DateCellRange)[]): DateCellRangeWithRange[];
+/**
+ * Returns an array containing all indexes in the date block range.
+ */
+export declare function allIndexesInDateCellRange(input: DateCellRange): DateCellIndex[];
+/**
+ * Returns the set of all indexes within the input.
+ *
+ * @param input
+ * @returns
+ */
+export declare function allIndexesInDateCellRanges(input: (DateCellIndex | DateCellRange)[]): Set<DateCellIndex>;
+/**
+ * Returns blocks that are only in the given DateCellRange.
+ *
+ * @param blocks
+ * @param range
+ * @returns
+ */
+export declare function filterDateCellsInDateCellRange<T extends DateCell | DateCellRange>(blocks: T[], range: DateCellRangeWithRange): T[];
+export declare type IsDateCellWithinDateCellRangeInput = DateCellOrDateCellIndexOrDateCellRange;
+/**
+ * Function that returns true if the input range is equal or falls within the configured DateCellRange.
+ */
+export declare type IsDateCellWithinDateCellRangeFunction = (input: IsDateCellWithinDateCellRangeInput) => boolean;
+export declare function isDateCellWithinDateCellRangeFunction(inputRange: IsDateCellWithinDateCellRangeInput): IsDateCellWithinDateCellRangeFunction;
+/**
+ * Returns true if the first DateCell or DateCellRange contains the second input.
+ *
+ * @param range
+ * @param isContainedWithin
+ * @returns
+ */
+export declare function isDateCellWithinDateCellRange(range: IsDateCellWithinDateCellRangeInput, contains: IsDateCellWithinDateCellRangeInput): boolean;
+export interface DateCellRangeBlockCountInfo {
+    /**
+     * Total number of blocks.
+     */
+    readonly count: number;
+    /**
+     * The "total" if all indexes were added together. Used for calculating the average.
+     */
+    readonly total: number;
+    /**
+     * The average block index
+     */
+    readonly average: number;
+}
+/**
+ * Counts the number of blocks in the input range.
+ *
+ * @param inputDateCellRange
+ * @returns
+ */
+export declare function dateCellRangeBlocksCountInfo(inputDateCellRange: ArrayOrValue<DateCell | DateCellRange>): DateCellRangeBlockCountInfo;
+/**
+ * Counts the number of blocks in the input range.
+ *
+ * @param inputDateCellRange
+ * @returns
+ */
+export declare function dateCellRangeBlocksCount(inputDateCellRange: ArrayOrValue<DateCell | DateCellRange>): number;
+/**
+ * Checks whether or not the input range is fully included by the configured ranges.
+ */
+export declare type DateCellRangesFullyCoverDateCellRangeFunction = (range: DateCellRange) => boolean;
+/**
+ * Creates a dateCellRangesFullyCoverDateCellRangeFunction
+ *
+ * @param ranges
+ * @returns
+ */
+export declare function dateCellRangesFullyCoverDateCellRangeFunction(ranges: ArrayOrValue<DateCellRange>): DateCellRangesFullyCoverDateCellRangeFunction;
+export interface GetNextDateCellTimingIndexInput<T extends DateCellRange> {
+    /**
+     * Relevant index for now.
+     */
+    readonly currentIndex: DateCellIndex;
+    /**
+     * All possible ranges to pick from.
+     */
+    readonly ranges: ArrayOrValue<T>;
+}
+export interface GetNextDateCellTimingIndexResult<T extends DateCellRange> {
+    /**
+     * The item that matches the current index first out of the options.
+     */
+    readonly currentResult: Maybe<T>;
+    /**
+     * The next picked index, if available.
+     */
+    readonly nextIndex: Maybe<DateCellIndex>;
+    /**
+     * The item that matches the next index first out of the options.
+     */
+    readonly nextResult: Maybe<T>;
+    /**
+     * All ranges that match/contain the current index.
+     */
+    readonly presentResults: T[];
+    /**
+     * All ranges that come before the current index.
+     */
+    readonly pastResults: T[];
+    /**
+     * All ranges that come after the current index.
+     */
+    readonly futureResults: T[];
+}
+/**
+ * Computes a GetNextDateCellTimingIndexResult from the input.
+ *
+ * @param input
+ */
+export declare function getNextDateCellTimingIndex<T extends DateCellRange>(input: GetNextDateCellTimingIndexInput<T>): GetNextDateCellTimingIndexResult<T>;
+/**
+ * Returns the DateRelativeState for the given index and range.
+ *
+ * @param nowIndex
+ * @param range
+ */
+export declare function dateRelativeStateForDateCellRangeComparedToIndex(range: DateCellRange, nowIndex: DateCellIndex): DateRelativeState;
+/**
+ * Expands a DateCellRange into an array of DateCell values.
+ *
+ * @param block
+ * @returns
+ */
+export declare function expandDateCellRange<B extends DateCellRange | DateCellRangeWithRange>(block: B): B[];
+/**
+ * A DateCell that also has the potential for a unique identifier.
+ */
+export interface UniqueDateCell extends DateCell, UniqueModel {
+}
+/**
+ * Represents a range of UniqueDateCell values keyed by a similar identifier (or lack of identifier).
+ */
+export interface UniqueDateCellRange extends UniqueDateCell, DateCellRange {
+}
+/**
+ * Returns true if the input DateCellRange is longer than 1 block (I.E. has a "to" value greater than it's "i" value).
+ *
+ * @param input
+ */
+export declare function dateCellRangeHasRange(input: DateCellRange | UniqueDateCell): input is DateCellRangeWithRange;
+/**
+ * Reads the to index if it exists, or returns the block's index itself.
+ *
+ * @param input
+ * @returns
+ */
+export declare function dateCellEndIndex(input: DateCellRange | UniqueDateCell): IndexNumber;
+/**
+ * A grouping of UniqueDateCell values, sorted by date range.
+ */
+export interface UniqueDateCellRangeGroup<B extends DateCellRange | UniqueDateCell> extends DateCellRange {
+    /**
+     * Blocks are sorted by index.
+     */
+    blocks: B[];
+}
+/**
+ * Groups all input DateCellRange or UniqueDateCell values into a UniqueDateCellRangeGroup value amd sorts the input.
+ */
+export declare function groupUniqueDateCells<B extends DateCellRange | UniqueDateCell>(input: B[]): UniqueDateCellRangeGroup<B>;
+/**
+ * Determines how to "fill" a DateRange when an empty range is detected.
+ * - extend: extends the previous block to fill the range.
+ * - fill: creates a new value using a factory.
+ */
+export declare type ExpandUniqueDateCellsFillOption = 'extend' | 'fill';
+/**
+ * Determines how overwrite block values that are completely overlapping eachother.
+ * - current: keeps the "current" value
+ * - next: the next/new value overwrites the previous one
+ */
+export declare type ExpandUniqueDateCellsRetainOverlapOption = 'current' | 'next';
+export interface ExpandUniqueDateCellsConfig<B extends DateCellRange | UniqueDateCell> {
+    /**
+     * The expected start index.
+     *
+     * If provided, will expand the first block to start at this index, and filter out any blocks that end before this index.
+     */
+    startAtIndex?: number;
+    /**
+     * The expected end index, inclusive.
+     *
+     * If provided, will expand the final block to end at this index, and filter out any blocks that start past this index.
+     */
+    endAtIndex?: number;
+    /**
+     * Determines how to fill empty ranges.
+     */
+    fillOption: ExpandUniqueDateCellsFillOption;
+    /**
+     * (Optional) Determines how to handle overwrites.
+     *
+     * - next: will retain the latest value (next) and overwrite the current value.
+     * - current: will retain the current value and ignore any future values at that index.
+     *
+     * Defaults to next
+     */
+    retainOnOverlap?: ExpandUniqueDateCellsRetainOverlapOption;
+    /**
+     * Used to create new items to fill empty block sets. Required when mode is set to "fill".
+     */
+    fillFactory?: FactoryWithRequiredInput<B, DateCellRangeWithRange>;
+}
+export interface ExpandUniqueDateCellsResult<B extends DateCellRange | UniqueDateCell> extends UniqueDateCellRangeGroup<B> {
+    /**
+     * Blocks that were competely removed. Some blocks stay partially retained.
+     */
+    discarded: B[];
+}
+/**
+ * Expansion function used to sort/merge/replace DateCellRange values by block.
+ *
+ * Can optionally specify a second array/group of blocks that are treated as "next" blocks which can take priority or not depending on the retain options.
+ */
+export declare type ExpandUniqueDateCellsFunction<B extends DateCellRange | UniqueDateCell> = (input: B[] | UniqueDateCellRangeGroup<B>, newBlocks?: B[] | UniqueDateCellRangeGroup<B>) => ExpandUniqueDateCellsResult<B>;
+export declare function expandUniqueDateCellsFunction<B extends DateCellRange | UniqueDateCell>(config: ExpandUniqueDateCellsConfig<B>): ExpandUniqueDateCellsFunction<B>;