Recurring time window filter

package.json

@@ -18,7 +18,7 @@
     "dev": "rollup --config --watch",
     "lint": "eslint src/ test/ --ignore-pattern test/browser/testcases.js",
     "fix-lint": "eslint src/ test/ --fix --ignore-pattern test/browser/testcases.js",
-    "test": "mocha out/*.test.{js,cjs,mjs} --parallel",
+    "test": "mocha out/test/*.test.{js,cjs,mjs} --parallel",
     "test-browser": "npx playwright install chromium && npx playwright test"
   },
   "repository": {
@@ -44,6 +44,7 @@
     "rimraf": "^5.0.5",
     "rollup": "^4.22.4",
     "rollup-plugin-dts": "^6.1.0",
+    "sinon": "^18.0.0",
     "tslib": "^2.6.2",
     "typescript": "^5.3.3"
   },

src/featureManager.ts

@@ -1,11 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
-import { TimeWindowFilter } from "./filter/TimeWindowFilter.js";
-import { IFeatureFilter } from "./filter/FeatureFilter.js";
+import { TimeWindowFilter } from "./filter/timeWindowFilter.js";
+import { IFeatureFilter } from "./filter/featureFilter.js";
 import { RequirementType } from "./schema/model.js";
 import { IFeatureFlagProvider } from "./featureProvider.js";
-import { TargetingFilter } from "./filter/TargetingFilter.js";
+import { TargetingFilter } from "./filter/targetingFilter.js";
 
 export class FeatureManager {
     #provider: IFeatureFlagProvider;

src/filter/FeatureFilter.ts → src/filter/featureFilter.ts

@@ -1,12 +1,12 @@
-// Copyright (c) Microsoft Corporation.
-// Licensed under the MIT license.
-
-export interface IFeatureFilter {
-    name: string; // e.g. Microsoft.TimeWindow
-    evaluate(context: IFeatureFilterEvaluationContext, appContext?: unknown): boolean | Promise<boolean>;
-}
-
-export interface IFeatureFilterEvaluationContext {
-    featureName: string;
-    parameters?: unknown;
-}
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export interface IFeatureFilter {
+    name: string; // e.g. Microsoft.TimeWindow
+    evaluate(context: IFeatureFilterEvaluationContext, appContext?: unknown): boolean | Promise<boolean>;
+}
+
+export interface IFeatureFilterEvaluationContext {
+    featureName: string;
+    parameters?: unknown;
+}

src/filter/recurrence/evaluator.ts

@@ -0,0 +1,146 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { RecurrenceSpec, RecurrencePatternType, RecurrenceRangeType, DAYS_PER_WEEK, ONE_DAY_IN_MILLISECONDS } from "./model.js";
+import { calculateWeeklyDayOffset, sortDaysOfWeek, getDayOfWeek, addDays } from "./utils.js";
+
+type RecurrenceState = {
+    previousOccurrence: Date;
+    numberOfOccurrences: number;
+}
+
+/**
+ * Checks if a provided datetime is within any recurring time window specified by the recurrence information
+ * @param time A datetime
+ * @param recurrenceSpec The recurrence spcification
+ * @returns True if the given time is within any recurring time window; otherwise, false
+ */
+export function matchRecurrence(time: Date, recurrenceSpec: RecurrenceSpec): boolean {
+    const recurrenceState = FindPreviousRecurrence(time, recurrenceSpec);
+    if (recurrenceState) {
+        return time.getTime() < recurrenceState.previousOccurrence.getTime() + recurrenceSpec.duration;
+    }
+    return false;
+}
+
+/**
+ * Finds the closest previous recurrence occurrence before the given time according to the recurrence information
+ * @param time A datetime
+ * @param recurrenceSpec The recurrence specification
+ * @returns The recurrence state if any previous occurrence is found; otherwise, undefined
+ */
+function FindPreviousRecurrence(time: Date, recurrenceSpec: RecurrenceSpec): RecurrenceState | undefined {
+    if (time < recurrenceSpec.startTime) {
+        return undefined;
+    }
+    let result: RecurrenceState;
+    const pattern = recurrenceSpec.pattern;
+    if (pattern.type === RecurrencePatternType.Daily) {
+        result = FindPreviousDailyRecurrence(time, recurrenceSpec);
+    } else if (pattern.type === RecurrencePatternType.Weekly) {
+        result = FindPreviousWeeklyRecurrence(time, recurrenceSpec);
+    } else {
+        throw new Error("Unsupported recurrence pattern type.");
+    }
+    const { previousOccurrence, numberOfOccurrences } = result;
+
+    const range = recurrenceSpec.range;
+    if (range.type === RecurrenceRangeType.EndDate) {
+        if (previousOccurrence > range.endDate!) {
+            return undefined;
+        }
+    } else if (range.type === RecurrenceRangeType.Numbered) {
+        if (numberOfOccurrences > range.numberOfOccurrences!) {
+            return undefined;
+        }
+    }
+    return result;
+}
+
+function FindPreviousDailyRecurrence(time: Date, recurrenceSpec: RecurrenceSpec): RecurrenceState {
+    const startTime = recurrenceSpec.startTime;
+    const timeGap = time.getTime() - startTime.getTime();
+    const pattern = recurrenceSpec.pattern;
+    const numberOfIntervals = Math.floor(timeGap / (pattern.interval * ONE_DAY_IN_MILLISECONDS));
+    return {
+        previousOccurrence: addDays(startTime, numberOfIntervals * pattern.interval),
+        numberOfOccurrences: numberOfIntervals + 1
+    };
+}
+
+function FindPreviousWeeklyRecurrence(time: Date, recurrenceSpec: RecurrenceSpec): RecurrenceState {
+    /*
+     * Algorithm:
+     * 1. first find day 0 (d0), it's the day representing the start day on the week of `Start`.
+     * 2. find start day of the most recent occurring week d0 + floor((time - d0) / (interval * 7)) * (interval * 7)
+     * 3. if that's over 7 days ago, then previous occurence is the day with the max offset of the last occurring week
+     * 4. if gotten this far, then the current week is the most recent occurring week:
+         i. if time > day with min offset, then previous occurence is the day with max offset less than current
+        ii. if time < day with min offset, then previous occurence is the day with the max offset of previous occurring week
+     */
+    const startTime = recurrenceSpec.startTime;
+    const startDay = getDayOfWeek(startTime, recurrenceSpec.timezoneOffset);
+    const pattern = recurrenceSpec.pattern;
+    const sortedDaysOfWeek = sortDaysOfWeek(pattern.daysOfWeek!, pattern.firstDayOfWeek!);
+
+    /*
+     * Example:
+     * startTime = 2024-12-11 (Tue)
+     * pattern.interval = 2 pattern.firstDayOfWeek = Sun pattern.daysOfWeek = [Wed, Sun]
+     * sortedDaysOfWeek = [Sun, Wed]
+     * firstDayofStartWeek = 2024-12-08 (Sun)
+     *
+     * time = 2024-12-23 (Mon) timeGap = 15 days
+     * the most recent occurring week: 2024-12-22 ~ 2024-12-28
+     * number of intervals before the most recent occurring week = 15 / (2 * 7) = 1 (2024-12-08 ~ 2023-12-21)
+     * number of occurrences before the most recent occurring week = 1 * 2 - 1 = 1 (2024-12-11)
+     * firstDayOfLastOccurringWeek = 2024-12-22
+     */
+    const firstDayofStartWeek = addDays(startTime, -calculateWeeklyDayOffset(startDay, pattern.firstDayOfWeek!));
+    const timeGap = time.getTime() - firstDayofStartWeek.getTime();
+    // number of intervals before the most recent occurring week
+    const numberOfIntervals = Math.floor(timeGap / (pattern.interval * DAYS_PER_WEEK * ONE_DAY_IN_MILLISECONDS));
+    // number of occurrences before the most recent occurring week, it is possible to be negative
+    let numberOfOccurrences = numberOfIntervals * sortedDaysOfWeek.length - sortedDaysOfWeek.indexOf(startDay);
+    const firstDayOfLatestOccurringWeek = addDays(firstDayofStartWeek, numberOfIntervals * pattern.interval * DAYS_PER_WEEK);
+
+    // the current time is out of the last occurring week
+    if (time > addDays(firstDayOfLatestOccurringWeek, DAYS_PER_WEEK)) {
+        numberOfOccurrences += sortDaysOfWeek.length;
+        // day with max offset in the last occurring week
+        const previousOccurrence = addDays(firstDayOfLatestOccurringWeek, calculateWeeklyDayOffset(sortedDaysOfWeek.at(-1)!, pattern.firstDayOfWeek!));
+        return {
+            previousOccurrence: previousOccurrence,
+            numberOfOccurrences: numberOfOccurrences
+        };
+    }
+
+    let dayWithMinOffset = addDays(firstDayOfLatestOccurringWeek, calculateWeeklyDayOffset(sortedDaysOfWeek[0], pattern.firstDayOfWeek!));
+    if (dayWithMinOffset < startTime) {
+        numberOfOccurrences = 0;
+        dayWithMinOffset = startTime;
+    }
+    let previousOccurrence;
+    if (time >= dayWithMinOffset) {
+        // the previous occurence is the day with max offset less than current
+        previousOccurrence = dayWithMinOffset;
+        numberOfOccurrences += 1;
+        const dayWithMinOffsetIndex = sortedDaysOfWeek.indexOf(getDayOfWeek(dayWithMinOffset, recurrenceSpec.timezoneOffset));
+        for (let i = dayWithMinOffsetIndex + 1; i < sortedDaysOfWeek.length; i++) {
+            const day = addDays(firstDayOfLatestOccurringWeek, calculateWeeklyDayOffset(sortedDaysOfWeek[i], pattern.firstDayOfWeek!));
+            if (time < day) {
+                break;
+            }
+            previousOccurrence = day;
+            numberOfOccurrences += 1;
+        }
+    } else {
+        const firstDayOfPreviousOccurringWeek = addDays(firstDayOfLatestOccurringWeek, -pattern.interval * DAYS_PER_WEEK);
+        // the previous occurence is the day with the max offset of previous occurring week
+        previousOccurrence = addDays(firstDayOfPreviousOccurringWeek, calculateWeeklyDayOffset(sortedDaysOfWeek.at(-1)!, pattern.firstDayOfWeek!));
+    }
+    return {
+        previousOccurrence: previousOccurrence,
+        numberOfOccurrences: numberOfOccurrences
+    };
+}

src/filter/recurrence/model.ts

@@ -0,0 +1,113 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+export const DAYS_PER_WEEK = 7;
+export const ONE_DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+
+export enum DayOfWeek {
+    Sunday = 0,
+    Monday = 1,
+    Tuesday = 2,
+    Wednesday = 3,
+    Thursday = 4,
+    Friday = 5,
+    Saturday = 6
+}
+
+/**
+ * The recurrence pattern describes the frequency by which the time window repeats
+ */
+export enum RecurrencePatternType {
+    /**
+     * The pattern where the time window will repeat based on the number of days specified by interval between occurrences
+     */
+    Daily,
+    /**
+     * The pattern where the time window will repeat on the same day or days of the week, based on the number of weeks between each set of occurrences
+     */
+    Weekly
+}
+
+/**
+ * The recurrence range specifies the date range over which the time window repeats
+ */
+export enum RecurrenceRangeType {
+    /**
+     * The recurrence has no end and repeats on all the days that fit the corresponding pattern
+     */
+    NoEnd,
+    /**
+     * The recurrence repeats on all the days that fit the corresponding pattern until or on the specified end date
+     */
+    EndDate,
+    /**
+     * The recurrence repeats for the specified number of occurrences that match the pattern
+     */
+    Numbered
+}
+
+/**
+ * The recurrence pattern describes the frequency by which the time window repeats
+ */
+export type RecurrencePattern = {
+    /**
+     * The type of the recurrence pattern
+     */
+    type: RecurrencePatternType;
+    /**
+     * The number of units between occurrences, where units can be in days or weeks, depending on the pattern type
+     */
+    interval: number;
+    /**
+     * The days of the week when the time window occurs, which is only applicable for 'Weekly' pattern
+     */
+    daysOfWeek?: DayOfWeek[];
+    /**
+     * The first day of the week, which is only applicable for 'Weekly' pattern
+     */
+    firstDayOfWeek?: DayOfWeek;
+};
+
+/**
+ * The recurrence range describes a date range over which the time window repeats
+ */
+export type RecurrenceRange = {
+    /**
+     * The type of the recurrence range
+     */
+    type: RecurrenceRangeType;
+    /**
+     * The date to stop applying the recurrence pattern, which is only applicable for 'EndDate' range
+     */
+    endDate?: Date;
+    /**
+     * The number of times to repeat the time window, which is only applicable for 'Numbered' range
+     */
+    numberOfOccurrences?: number;
+};
+
+/**
+ * Specification defines the recurring time window
+ */
+export type RecurrenceSpec = {
+    /**
+     * The start time of the first/base time window
+     */
+    startTime: Date;
+    /**
+     * The duration of each time window in milliseconds
+     */
+    duration: number;
+    /**
+     * The recurrence pattern
+     */
+    pattern: RecurrencePattern;
+    /**
+     * The recurrence range
+     */
+    range: RecurrenceRange;
+    /**
+     * The timezone offset in milliseconds, which helps to determine the day of week of a given date
+     */
+    timezoneOffset: number;
+};