@microsoft/feature-management 2.1.0 → 2.3.0

package/dist/esm/featureManager.js.map

@@ -1 +1 @@
-{"version":3,"file":"featureManager.js","sources":["../../src/featureManager.ts"],"sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { TimeWindowFilter } from \"./filter/TimeWindowFilter.js\";\nimport { IFeatureFilter } from \"./filter/FeatureFilter.js\";\nimport { FeatureFlag, RequirementType, VariantDefinition } from \"./schema/model.js\";\nimport { IFeatureFlagProvider } from \"./featureProvider.js\";\nimport { TargetingFilter } from \"./filter/TargetingFilter.js\";\nimport { Variant } from \"./variant/Variant.js\";\nimport { IFeatureManager } from \"./IFeatureManager.js\";\nimport { ITargetingContext, ITargetingContextAccessor } from \"./common/targetingContext.js\";\nimport { isTargetedGroup, isTargetedPercentile, isTargetedUser } from \"./common/targetingEvaluator.js\";\n\nexport class FeatureManager implements IFeatureManager {\n    readonly #provider: IFeatureFlagProvider;\n    readonly #featureFilters: Map<string, IFeatureFilter> = new Map();\n    readonly #onFeatureEvaluated?: (event: EvaluationResult) => void;\n    readonly #targetingContextAccessor?: ITargetingContextAccessor;\n\n    constructor(provider: IFeatureFlagProvider, options?: FeatureManagerOptions) {\n        this.#provider = provider;\n        this.#onFeatureEvaluated = options?.onFeatureEvaluated;\n        this.#targetingContextAccessor = options?.targetingContextAccessor;\n\n        const builtinFilters = [new TimeWindowFilter(), new TargetingFilter(options?.targetingContextAccessor)];\n        // If a custom filter shares a name with an existing filter, the custom filter overrides the existing one.\n        for (const filter of [...builtinFilters, ...(options?.customFilters ?? [])]) {\n            this.#featureFilters.set(filter.name, filter);\n        }\n    }\n\n    async listFeatureNames(): Promise<string[]> {\n        const features = await this.#provider.getFeatureFlags();\n        const featureNameSet = new Set(features.map((feature) => feature.id));\n        return Array.from(featureNameSet);\n    }\n\n    // If multiple feature flags are found, the first one takes precedence.\n    async isEnabled(featureName: string, context?: unknown): Promise<boolean> {\n        const result = await this.#evaluateFeature(featureName, context);\n        return result.enabled;\n    }\n\n    async getVariant(featureName: string, context?: ITargetingContext): Promise<Variant | undefined> {\n        const result = await this.#evaluateFeature(featureName, context);\n        return result.variant;\n    }\n\n    async #assignVariant(featureFlag: FeatureFlag, context: ITargetingContext): Promise<VariantAssignment> {\n        // user allocation\n        if (featureFlag.allocation?.user !== undefined) {\n            for (const userAllocation of featureFlag.allocation.user) {\n                if (isTargetedUser(context.userId, userAllocation.users)) {\n                    return getVariantAssignment(featureFlag, userAllocation.variant, VariantAssignmentReason.User);\n                }\n            }\n        }\n\n        // group allocation\n        if (featureFlag.allocation?.group !== undefined) {\n            for (const groupAllocation of featureFlag.allocation.group) {\n                if (isTargetedGroup(context.groups, groupAllocation.groups)) {\n                    return getVariantAssignment(featureFlag, groupAllocation.variant, VariantAssignmentReason.Group);\n                }\n            }\n        }\n\n        // percentile allocation\n        if (featureFlag.allocation?.percentile !== undefined) {\n            for (const percentileAllocation of featureFlag.allocation.percentile) {\n                const hint = featureFlag.allocation.seed ?? `allocation\\n${featureFlag.id}`;\n                if (await isTargetedPercentile(context.userId, hint, percentileAllocation.from, percentileAllocation.to)) {\n                    return getVariantAssignment(featureFlag, percentileAllocation.variant, VariantAssignmentReason.Percentile);\n                }\n            }\n        }\n\n        return { variant: undefined, reason: VariantAssignmentReason.None };\n    }\n\n    async #isEnabled(featureFlag: FeatureFlag, appContext?: unknown): Promise<boolean> {\n        if (featureFlag.enabled !== true) {\n            // If the feature is not explicitly enabled, then it is disabled by default.\n            return false;\n        }\n\n        const clientFilters = featureFlag.conditions?.client_filters;\n        if (clientFilters === undefined || clientFilters.length <= 0) {\n            // If there are no client filters, then the feature is enabled.\n            return true;\n        }\n\n        const requirementType: RequirementType = featureFlag.conditions?.requirement_type ?? \"Any\"; // default to any.\n\n        /**\n         * While iterating through the client filters, we short-circuit the evaluation based on the requirement type.\n         * - When requirement type is \"All\", the feature is enabled if all client filters are matched. If any client filter is not matched, the feature is disabled, otherwise it is enabled. `shortCircuitEvaluationResult` is false.\n         * - When requirement type is \"Any\", the feature is enabled if any client filter is matched. If any client filter is matched, the feature is enabled, otherwise it is disabled. `shortCircuitEvaluationResult` is true.\n         */\n        const shortCircuitEvaluationResult: boolean = requirementType === \"Any\";\n\n        for (const clientFilter of clientFilters) {\n            const matchedFeatureFilter = this.#featureFilters.get(clientFilter.name);\n            const contextWithFeatureName = { featureName: featureFlag.id, parameters: clientFilter.parameters };\n            if (matchedFeatureFilter === undefined) {\n                console.warn(`Feature filter ${clientFilter.name} is not found.`);\n                return false;\n            }\n            if (await matchedFeatureFilter.evaluate(contextWithFeatureName, appContext) === shortCircuitEvaluationResult) {\n                return shortCircuitEvaluationResult;\n            }\n        }\n\n        // If we get here, then we have not found a client filter that matches the requirement type.\n        return !shortCircuitEvaluationResult;\n    }\n\n    async #evaluateFeature(featureName: string, appContext: unknown): Promise<EvaluationResult> {\n        const featureFlag = await this.#provider.getFeatureFlag(featureName);\n        const result = new EvaluationResult(featureFlag);\n\n        if (featureFlag === undefined) {\n            return result;\n        }\n\n        // Ensure that the feature flag is in the correct format. Feature providers should validate the feature flags, but we do it here as a safeguard.\n        // TODO: move to the feature flag provider implementation.\n        validateFeatureFlagFormat(featureFlag);\n\n        // Evaluate if the feature is enabled.\n        result.enabled = await this.#isEnabled(featureFlag, appContext);\n\n        // Get targeting context from the app context or the targeting context accessor\n        const targetingContext = this.#getTargetingContext(appContext);\n        result.targetingId = targetingContext?.userId;\n\n        // Determine Variant\n        let variantDef: VariantDefinition | undefined;\n        let reason: VariantAssignmentReason = VariantAssignmentReason.None;\n\n        // featureFlag.variant not empty\n        if (featureFlag.variants !== undefined && featureFlag.variants.length > 0) {\n            if (!result.enabled) {\n                // not enabled, assign default if specified\n                if (featureFlag.allocation?.default_when_disabled !== undefined) {\n                    variantDef = featureFlag.variants.find(v => v.name == featureFlag.allocation?.default_when_disabled);\n                    reason = VariantAssignmentReason.DefaultWhenDisabled;\n                } else {\n                    // no default specified\n                    variantDef = undefined;\n                    reason = VariantAssignmentReason.DefaultWhenDisabled;\n                }\n            } else {\n                // enabled, assign based on allocation\n                if (targetingContext !== undefined && featureFlag.allocation !== undefined) {\n                    const variantAndReason = await this.#assignVariant(featureFlag, targetingContext);\n                    variantDef = variantAndReason.variant;\n                    reason = variantAndReason.reason;\n                }\n\n                // allocation failed, assign default if specified\n                if (variantDef === undefined && reason === VariantAssignmentReason.None) {\n                    if (featureFlag.allocation?.default_when_enabled !== undefined) {\n                        variantDef = featureFlag.variants.find(v => v.name == featureFlag.allocation?.default_when_enabled);\n                        reason = VariantAssignmentReason.DefaultWhenEnabled;\n                    } else {\n                        variantDef = undefined;\n                        reason = VariantAssignmentReason.DefaultWhenEnabled;\n                    }\n                }\n            }\n        }\n\n        result.variant = variantDef !== undefined ? new Variant(variantDef.name, variantDef.configuration_value) : undefined;\n        result.variantAssignmentReason = reason;\n\n        // Status override for isEnabled\n        if (variantDef !== undefined && featureFlag.enabled) {\n            if (variantDef.status_override === \"Enabled\") {\n                result.enabled = true;\n            } else if (variantDef.status_override === \"Disabled\") {\n                result.enabled = false;\n            }\n        }\n\n        // The callback will only be executed if telemetry is enabled for the feature flag\n        if (featureFlag.telemetry?.enabled && this.#onFeatureEvaluated !== undefined) {\n            this.#onFeatureEvaluated(result);\n        }\n\n        return result;\n    }\n\n    #getTargetingContext(context: unknown): ITargetingContext | undefined {\n        let targetingContext: ITargetingContext | undefined = context as ITargetingContext;\n        if (targetingContext?.userId === undefined &&\n            targetingContext?.groups === undefined &&\n            this.#targetingContextAccessor !== undefined) {\n            targetingContext = this.#targetingContextAccessor.getTargetingContext();\n        }\n        return targetingContext;\n    }\n}\n\nexport interface FeatureManagerOptions {\n    /**\n     * The custom filters to be used by the feature manager.\n     */\n    customFilters?: IFeatureFilter[];\n\n    /**\n     * The callback function that is called when a feature flag is evaluated.\n     * The callback function is called only when telemetry is enabled for the feature flag.\n     */\n    onFeatureEvaluated?: (event: EvaluationResult) => void;\n\n    /**\n     * The accessor function that provides the @see ITargetingContext for targeting evaluation.\n     */\n    targetingContextAccessor?: ITargetingContextAccessor;\n}\n\nexport class EvaluationResult {\n    constructor(\n        // feature flag definition\n        public readonly feature: FeatureFlag | undefined,\n\n        // enabled state\n        public enabled: boolean = false,\n\n        // variant assignment\n        public targetingId: string | undefined = undefined,\n        public variant: Variant | undefined = undefined,\n        public variantAssignmentReason: VariantAssignmentReason = VariantAssignmentReason.None\n    ) { }\n}\n\nexport enum VariantAssignmentReason {\n    /**\n     * Variant allocation did not happen. No variant is assigned.\n     */\n    None = \"None\",\n\n    /**\n     * The default variant is assigned when a feature flag is disabled.\n     */\n    DefaultWhenDisabled = \"DefaultWhenDisabled\",\n\n    /**\n     * The default variant is assigned because of no applicable user/group/percentile allocation when a feature flag is enabled.\n     */\n    DefaultWhenEnabled = \"DefaultWhenEnabled\",\n\n    /**\n     * The variant is assigned because of the user allocation when a feature flag is enabled.\n     */\n    User = \"User\",\n\n    /**\n     * The variant is assigned because of the group allocation when a feature flag is enabled.\n     */\n    Group = \"Group\",\n\n    /**\n     * The variant is assigned because of the percentile allocation when a feature flag is enabled.\n     */\n    Percentile = \"Percentile\"\n}\n\n/**\n * Validates the format of the feature flag definition.\n *\n * FeatureFlag data objects are from IFeatureFlagProvider, depending on the implementation.\n * Thus the properties are not guaranteed to have the expected types.\n *\n * @param featureFlag The feature flag definition to validate.\n */\nfunction validateFeatureFlagFormat(featureFlag: any): void {\n    if (featureFlag.enabled !== undefined && typeof featureFlag.enabled !== \"boolean\") {\n        throw new Error(`Feature flag ${featureFlag.id} has an invalid 'enabled' value.`);\n    }\n    // TODO: add more validations.\n    // TODO: should be moved to the feature flag provider.\n}\n\n/**\n * Try to get the variant assignment for the given variant name. If the variant is not found, override the reason with VariantAssignmentReason.None.\n *\n * @param featureFlag feature flag definition\n * @param variantName variant name\n * @param reason variant assignment reason\n * @returns variant assignment containing the variant definition and the reason\n */\nfunction getVariantAssignment(featureFlag: FeatureFlag, variantName: string, reason: VariantAssignmentReason): VariantAssignment {\n    const variant = featureFlag.variants?.find(v => v.name == variantName);\n    if (variant !== undefined) {\n        return { variant, reason };\n    } else {\n        console.warn(`Variant ${variantName} not found for feature ${featureFlag.id}.`);\n        return { variant: undefined, reason: VariantAssignmentReason.None };\n    }\n}\n\ntype VariantAssignment = {\n    variant: VariantDefinition | undefined;\n    reason: VariantAssignmentReason;\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"featureManager.js","sources":["../../src/featureManager.ts"],"sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { TimeWindowFilter } from \"./filter/timeWindowFilter.js\";\nimport { IFeatureFilter } from \"./filter/featureFilter.js\";\nimport { FeatureFlag, RequirementType, VariantDefinition } from \"./schema/model.js\";\nimport { IFeatureFlagProvider, IFeatureManager } from \"./model.js\";\nimport { TargetingFilter } from \"./filter/targetingFilter.js\";\nimport { Variant } from \"./variant/variant.js\";\nimport { ITargetingContext, ITargetingContextAccessor } from \"./common/targetingContext.js\";\nimport { isTargetedGroup, isTargetedPercentile, isTargetedUser } from \"./common/targetingEvaluator.js\";\n\nexport class FeatureManager implements IFeatureManager {\n    readonly #provider: IFeatureFlagProvider;\n    readonly #featureFilters: Map<string, IFeatureFilter> = new Map();\n    readonly #onFeatureEvaluated?: (event: EvaluationResult) => void;\n    readonly #targetingContextAccessor?: ITargetingContextAccessor;\n\n    constructor(provider: IFeatureFlagProvider, options?: FeatureManagerOptions) {\n        this.#provider = provider;\n        this.#onFeatureEvaluated = options?.onFeatureEvaluated;\n        this.#targetingContextAccessor = options?.targetingContextAccessor;\n\n        const builtinFilters = [new TimeWindowFilter(), new TargetingFilter(options?.targetingContextAccessor)];\n        // If a custom filter shares a name with an existing filter, the custom filter overrides the existing one.\n        for (const filter of [...builtinFilters, ...(options?.customFilters ?? [])]) {\n            this.#featureFilters.set(filter.name, filter);\n        }\n    }\n\n    async listFeatureNames(): Promise<string[]> {\n        const features = await this.#provider.getFeatureFlags();\n        const featureNameSet = new Set(features.map((feature) => feature.id));\n        return Array.from(featureNameSet);\n    }\n\n    // If multiple feature flags are found, the first one takes precedence.\n    async isEnabled(featureName: string, context?: unknown): Promise<boolean> {\n        const result = await this.#evaluateFeature(featureName, context);\n        return result.enabled;\n    }\n\n    async getVariant(featureName: string, context?: ITargetingContext): Promise<Variant | undefined> {\n        const result = await this.#evaluateFeature(featureName, context);\n        return result.variant;\n    }\n\n    async #assignVariant(featureFlag: FeatureFlag, context: ITargetingContext): Promise<VariantAssignment> {\n        // user allocation\n        if (featureFlag.allocation?.user !== undefined) {\n            for (const userAllocation of featureFlag.allocation.user) {\n                if (isTargetedUser(context.userId, userAllocation.users)) {\n                    return getVariantAssignment(featureFlag, userAllocation.variant, VariantAssignmentReason.User);\n                }\n            }\n        }\n\n        // group allocation\n        if (featureFlag.allocation?.group !== undefined) {\n            for (const groupAllocation of featureFlag.allocation.group) {\n                if (isTargetedGroup(context.groups, groupAllocation.groups)) {\n                    return getVariantAssignment(featureFlag, groupAllocation.variant, VariantAssignmentReason.Group);\n                }\n            }\n        }\n\n        // percentile allocation\n        if (featureFlag.allocation?.percentile !== undefined) {\n            for (const percentileAllocation of featureFlag.allocation.percentile) {\n                const hint = featureFlag.allocation.seed ?? `allocation\\n${featureFlag.id}`;\n                if (await isTargetedPercentile(context.userId, hint, percentileAllocation.from, percentileAllocation.to)) {\n                    return getVariantAssignment(featureFlag, percentileAllocation.variant, VariantAssignmentReason.Percentile);\n                }\n            }\n        }\n\n        return { variant: undefined, reason: VariantAssignmentReason.None };\n    }\n\n    async #isEnabled(featureFlag: FeatureFlag, appContext?: unknown): Promise<boolean> {\n        if (featureFlag.enabled !== true) {\n            // If the feature is not explicitly enabled, then it is disabled by default.\n            return false;\n        }\n\n        const clientFilters = featureFlag.conditions?.client_filters;\n        if (clientFilters === undefined || clientFilters.length <= 0) {\n            // If there are no client filters, then the feature is enabled.\n            return true;\n        }\n\n        const requirementType: RequirementType = featureFlag.conditions?.requirement_type ?? \"Any\"; // default to any.\n\n        /**\n         * While iterating through the client filters, we short-circuit the evaluation based on the requirement type.\n         * - When requirement type is \"All\", the feature is enabled if all client filters are matched. If any client filter is not matched, the feature is disabled, otherwise it is enabled. `shortCircuitEvaluationResult` is false.\n         * - When requirement type is \"Any\", the feature is enabled if any client filter is matched. If any client filter is matched, the feature is enabled, otherwise it is disabled. `shortCircuitEvaluationResult` is true.\n         */\n        const shortCircuitEvaluationResult: boolean = requirementType === \"Any\";\n\n        for (const clientFilter of clientFilters) {\n            const matchedFeatureFilter = this.#featureFilters.get(clientFilter.name);\n            const contextWithFeatureName = { featureName: featureFlag.id, parameters: clientFilter.parameters };\n            if (matchedFeatureFilter === undefined) {\n                console.warn(`Feature filter ${clientFilter.name} is not found.`);\n                return false;\n            }\n            if (await matchedFeatureFilter.evaluate(contextWithFeatureName, appContext) === shortCircuitEvaluationResult) {\n                return shortCircuitEvaluationResult;\n            }\n        }\n\n        // If we get here, then we have not found a client filter that matches the requirement type.\n        return !shortCircuitEvaluationResult;\n    }\n\n    async #evaluateFeature(featureName: string, appContext: unknown): Promise<EvaluationResult> {\n        const featureFlag = await this.#provider.getFeatureFlag(featureName);\n        const result = new EvaluationResult(featureFlag);\n\n        if (featureFlag === undefined) {\n            return result;\n        }\n\n        // Ensure that the feature flag is in the correct format. Feature providers should validate the feature flags, but we do it here as a safeguard.\n        // TODO: move to the feature flag provider implementation.\n        validateFeatureFlagFormat(featureFlag);\n\n        // Evaluate if the feature is enabled.\n        result.enabled = await this.#isEnabled(featureFlag, appContext);\n\n        // Get targeting context from the app context or the targeting context accessor\n        const targetingContext = this.#getTargetingContext(appContext);\n        result.targetingId = targetingContext?.userId;\n\n        // Determine Variant\n        let variantDef: VariantDefinition | undefined;\n        let reason: VariantAssignmentReason = VariantAssignmentReason.None;\n\n        // featureFlag.variant not empty\n        if (featureFlag.variants !== undefined && featureFlag.variants.length > 0) {\n            if (!result.enabled) {\n                // not enabled, assign default if specified\n                if (featureFlag.allocation?.default_when_disabled !== undefined) {\n                    variantDef = featureFlag.variants.find(v => v.name == featureFlag.allocation?.default_when_disabled);\n                    reason = VariantAssignmentReason.DefaultWhenDisabled;\n                } else {\n                    // no default specified\n                    variantDef = undefined;\n                    reason = VariantAssignmentReason.DefaultWhenDisabled;\n                }\n            } else {\n                // enabled, assign based on allocation\n                if (targetingContext !== undefined && featureFlag.allocation !== undefined) {\n                    const variantAndReason = await this.#assignVariant(featureFlag, targetingContext);\n                    variantDef = variantAndReason.variant;\n                    reason = variantAndReason.reason;\n                }\n\n                // allocation failed, assign default if specified\n                if (variantDef === undefined && reason === VariantAssignmentReason.None) {\n                    if (featureFlag.allocation?.default_when_enabled !== undefined) {\n                        variantDef = featureFlag.variants.find(v => v.name == featureFlag.allocation?.default_when_enabled);\n                        reason = VariantAssignmentReason.DefaultWhenEnabled;\n                    } else {\n                        variantDef = undefined;\n                        reason = VariantAssignmentReason.DefaultWhenEnabled;\n                    }\n                }\n            }\n        }\n\n        result.variant = variantDef !== undefined ? new Variant(variantDef.name, variantDef.configuration_value) : undefined;\n        result.variantAssignmentReason = reason;\n\n        // Status override for isEnabled\n        if (variantDef !== undefined && featureFlag.enabled) {\n            if (variantDef.status_override === \"Enabled\") {\n                result.enabled = true;\n            } else if (variantDef.status_override === \"Disabled\") {\n                result.enabled = false;\n            }\n        }\n\n        // The callback will only be executed if telemetry is enabled for the feature flag\n        if (featureFlag.telemetry?.enabled && this.#onFeatureEvaluated !== undefined) {\n            this.#onFeatureEvaluated(result);\n        }\n\n        return result;\n    }\n\n    #getTargetingContext(context: unknown): ITargetingContext | undefined {\n        let targetingContext: ITargetingContext | undefined = context as ITargetingContext;\n        if (targetingContext?.userId === undefined &&\n            targetingContext?.groups === undefined &&\n            this.#targetingContextAccessor !== undefined) {\n            targetingContext = this.#targetingContextAccessor.getTargetingContext();\n        }\n        return targetingContext;\n    }\n}\n\nexport interface FeatureManagerOptions {\n    /**\n     * The custom filters to be used by the feature manager.\n     */\n    customFilters?: IFeatureFilter[];\n\n    /**\n     * The callback function that is called when a feature flag is evaluated.\n     * The callback function is called only when telemetry is enabled for the feature flag.\n     */\n    onFeatureEvaluated?: (event: EvaluationResult) => void;\n\n    /**\n     * The accessor function that provides the @see ITargetingContext for targeting evaluation.\n     */\n    targetingContextAccessor?: ITargetingContextAccessor;\n}\n\nexport class EvaluationResult {\n    constructor(\n        // feature flag definition\n        public readonly feature: FeatureFlag | undefined,\n\n        // enabled state\n        public enabled: boolean = false,\n\n        // variant assignment\n        public targetingId: string | undefined = undefined,\n        public variant: Variant | undefined = undefined,\n        public variantAssignmentReason: VariantAssignmentReason = VariantAssignmentReason.None\n    ) { }\n}\n\nexport enum VariantAssignmentReason {\n    /**\n     * Variant allocation did not happen. No variant is assigned.\n     */\n    None = \"None\",\n\n    /**\n     * The default variant is assigned when a feature flag is disabled.\n     */\n    DefaultWhenDisabled = \"DefaultWhenDisabled\",\n\n    /**\n     * The default variant is assigned because of no applicable user/group/percentile allocation when a feature flag is enabled.\n     */\n    DefaultWhenEnabled = \"DefaultWhenEnabled\",\n\n    /**\n     * The variant is assigned because of the user allocation when a feature flag is enabled.\n     */\n    User = \"User\",\n\n    /**\n     * The variant is assigned because of the group allocation when a feature flag is enabled.\n     */\n    Group = \"Group\",\n\n    /**\n     * The variant is assigned because of the percentile allocation when a feature flag is enabled.\n     */\n    Percentile = \"Percentile\"\n}\n\n/**\n * Validates the format of the feature flag definition.\n *\n * FeatureFlag data objects are from IFeatureFlagProvider, depending on the implementation.\n * Thus the properties are not guaranteed to have the expected types.\n *\n * @param featureFlag The feature flag definition to validate.\n */\nfunction validateFeatureFlagFormat(featureFlag: any): void {\n    if (featureFlag.enabled !== undefined && typeof featureFlag.enabled !== \"boolean\") {\n        throw new Error(`Feature flag ${featureFlag.id} has an invalid 'enabled' value.`);\n    }\n    // TODO: add more validations.\n    // TODO: should be moved to the feature flag provider.\n}\n\n/**\n * Try to get the variant assignment for the given variant name. If the variant is not found, override the reason with VariantAssignmentReason.None.\n *\n * @param featureFlag feature flag definition\n * @param variantName variant name\n * @param reason variant assignment reason\n * @returns variant assignment containing the variant definition and the reason\n */\nfunction getVariantAssignment(featureFlag: FeatureFlag, variantName: string, reason: VariantAssignmentReason): VariantAssignment {\n    const variant = featureFlag.variants?.find(v => v.name == variantName);\n    if (variant !== undefined) {\n        return { variant, reason };\n    } else {\n        console.warn(`Variant ${variantName} not found for feature ${featureFlag.id}.`);\n        return { variant: undefined, reason: VariantAssignmentReason.None };\n    }\n}\n\ntype VariantAssignment = {\n    variant: VariantDefinition | undefined;\n    reason: VariantAssignmentReason;\n};\n"],"names":[],"mappings":"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"}

package/dist/esm/featureProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"featureProvider.js","sources":["../../src/featureProvider.ts"],"sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { IGettable } from \"./gettable.js\";\nimport { FeatureFlag, FeatureManagementConfiguration, FEATURE_MANAGEMENT_KEY, FEATURE_FLAGS_KEY } from \"./schema/model.js\";\nimport { validateFeatureFlag } from \"./schema/validator.js\";\n\nexport interface IFeatureFlagProvider {\n    /**\n     * Get all feature flags.\n     */\n    getFeatureFlags(): Promise<FeatureFlag[]>;\n\n    /**\n     * Get a feature flag by name.\n     * @param featureName The name of the feature flag.\n     */\n    getFeatureFlag(featureName: string): Promise<FeatureFlag | undefined>;\n}\n\n/**\n * A feature flag provider that uses a map-like configuration to provide feature flags.\n */\nexport class ConfigurationMapFeatureFlagProvider implements IFeatureFlagProvider {\n    #configuration: IGettable;\n\n    constructor(configuration: IGettable) {\n        this.#configuration = configuration;\n    }\n    async getFeatureFlag(featureName: string): Promise<FeatureFlag | undefined> {\n        const featureConfig = this.#configuration.get<FeatureManagementConfiguration>(FEATURE_MANAGEMENT_KEY);\n        const featureFlag = featureConfig?.[FEATURE_FLAGS_KEY]?.findLast((feature) => feature.id === featureName);\n        validateFeatureFlag(featureFlag);\n        return featureFlag;\n    }\n\n    async getFeatureFlags(): Promise<FeatureFlag[]> {\n        const featureConfig = this.#configuration.get<FeatureManagementConfiguration>(FEATURE_MANAGEMENT_KEY);\n        const featureFlags = featureConfig?.[FEATURE_FLAGS_KEY] ?? [];\n        featureFlags.forEach(featureFlag => {\n            validateFeatureFlag(featureFlag);\n        });\n        return featureFlags;\n    }\n}\n\n/**\n * A feature flag provider that uses an object-like configuration to provide feature flags.\n */\nexport class ConfigurationObjectFeatureFlagProvider implements IFeatureFlagProvider {\n    #configuration: Record<string, unknown>;\n\n    constructor(configuration: Record<string, unknown>) {\n        this.#configuration = configuration;\n    }\n\n    async getFeatureFlag(featureName: string): Promise<FeatureFlag | undefined> {\n        const featureFlags = this.#configuration[FEATURE_MANAGEMENT_KEY]?.[FEATURE_FLAGS_KEY];\n        const featureFlag = featureFlags?.findLast((feature: FeatureFlag) => feature.id === featureName);\n        validateFeatureFlag(featureFlag);\n        return featureFlag;\n    }\n\n    async getFeatureFlags(): Promise<FeatureFlag[]> {\n        const featureFlags = this.#configuration[FEATURE_MANAGEMENT_KEY]?.[FEATURE_FLAGS_KEY] ?? [];\n        featureFlags.forEach(featureFlag => {\n            validateFeatureFlag(featureFlag);\n        });\n        return featureFlags;\n    }\n}\n"],"names":[],"mappings":";;;AAAA;AACA;AAmBA;;AAEG;MACU,mCAAmC,CAAA;AAC5C,IAAA,cAAc,CAAY;AAE1B,IAAA,WAAA,CAAY,aAAwB,EAAA;AAChC,QAAA,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;KACvC;IACD,MAAM,cAAc,CAAC,WAAmB,EAAA;QACpC,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAiC,sBAAsB,CAAC,CAAC;QACtG,MAAM,WAAW,GAAG,aAAa,GAAG,iBAAiB,CAAC,EAAE,QAAQ,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,EAAE,KAAK,WAAW,CAAC,CAAC;QAC1G,mBAAmB,CAAC,WAAW,CAAC,CAAC;AACjC,QAAA,OAAO,WAAW,CAAC;KACtB;AAED,IAAA,MAAM,eAAe,GAAA;QACjB,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAiC,sBAAsB,CAAC,CAAC;QACtG,MAAM,YAAY,GAAG,aAAa,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC;AAC9D,QAAA,YAAY,CAAC,OAAO,CAAC,WAAW,IAAG;YAC/B,mBAAmB,CAAC,WAAW,CAAC,CAAC;AACrC,SAAC,CAAC,CAAC;AACH,QAAA,OAAO,YAAY,CAAC;KACvB;AACJ,CAAA;AAED;;AAEG;MACU,sCAAsC,CAAA;AAC/C,IAAA,cAAc,CAA0B;AAExC,IAAA,WAAA,CAAY,aAAsC,EAAA;AAC9C,QAAA,IAAI,CAAC,cAAc,GAAG,aAAa,CAAC;KACvC;IAED,MAAM,cAAc,CAAC,WAAmB,EAAA;AACpC,QAAA,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,sBAAsB,CAAC,GAAG,iBAAiB,CAAC,CAAC;AACtF,QAAA,MAAM,WAAW,GAAG,YAAY,EAAE,QAAQ,CAAC,CAAC,OAAoB,KAAK,OAAO,CAAC,EAAE,KAAK,WAAW,CAAC,CAAC;QACjG,mBAAmB,CAAC,WAAW,CAAC,CAAC;AACjC,QAAA,OAAO,WAAW,CAAC;KACtB;AAED,IAAA,MAAM,eAAe,GAAA;AACjB,QAAA,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,sBAAsB,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE,CAAC;AAC5F,QAAA,YAAY,CAAC,OAAO,CAAC,WAAW,IAAG;YAC/B,mBAAmB,CAAC,WAAW,CAAC,CAAC;AACrC,SAAC,CAAC,CAAC;AACH,QAAA,OAAO,YAAY,CAAC;KACvB;AACJ;;;;"}
+{"version":3,"file":"featureProvider.js","sources":["../../src/featureProvider.ts"],"sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { IGettable } from \"./gettable.js\";\nimport { FeatureFlag, FeatureManagementConfiguration, FEATURE_MANAGEMENT_KEY, FEATURE_FLAGS_KEY } from \"./schema/model.js\";\nimport { IFeatureFlagProvider } from \"./model.js\";\nimport { validateFeatureFlag } from \"./schema/validator.js\";\n\n/**\n * A feature flag provider that uses a map-like configuration to provide feature flags.\n */\nexport class ConfigurationMapFeatureFlagProvider implements IFeatureFlagProvider {\n    #configuration: IGettable;\n\n    constructor(configuration: IGettable) {\n        this.#configuration = configuration;\n    }\n    async getFeatureFlag(featureName: string): Promise<FeatureFlag | undefined> {\n        const featureConfig = this.#configuration.get<FeatureManagementConfiguration>(FEATURE_MANAGEMENT_KEY);\n        const featureFlag = featureConfig?.[FEATURE_FLAGS_KEY]?.findLast((feature) => feature.id === featureName);\n        validateFeatureFlag(featureFlag);\n        return featureFlag;\n    }\n\n    async getFeatureFlags(): Promise<FeatureFlag[]> {\n        const featureConfig = this.#configuration.get<FeatureManagementConfiguration>(FEATURE_MANAGEMENT_KEY);\n        const featureFlags = featureConfig?.[FEATURE_FLAGS_KEY] ?? [];\n        featureFlags.forEach(featureFlag => {\n            validateFeatureFlag(featureFlag);\n        });\n        return featureFlags;\n    }\n}\n\n/**\n * A feature flag provider that uses an object-like configuration to provide feature flags.\n */\nexport class ConfigurationObjectFeatureFlagProvider implements IFeatureFlagProvider {\n    #configuration: Record<string, unknown>;\n\n    constructor(configuration: Record<string, unknown>) {\n        this.#configuration = configuration;\n    }\n\n    async getFeatureFlag(featureName: string): Promise<FeatureFlag | undefined> {\n        const featureFlags = this.#configuration[FEATURE_MANAGEMENT_KEY]?.[FEATURE_FLAGS_KEY];\n        const featureFlag = featureFlags?.findLast((feature: FeatureFlag) => feature.id === featureName);\n        validateFeatureFlag(featureFlag);\n        return featureFlag;\n    }\n\n    async getFeatureFlags(): Promise<FeatureFlag[]> {\n        const featureFlags = this.#configuration[FEATURE_MANAGEMENT_KEY]?.[FEATURE_FLAGS_KEY] ?? [];\n        featureFlags.forEach(featureFlag => {\n            validateFeatureFlag(featureFlag);\n        });\n        return featureFlags;\n    }\n}\n"],"names":[],"mappings":";;;AAAA;AACA;AAOA;;AAEG;MACU,mCAAmC,CAAA;AAC5C,IAAA,cAAc;AAEd,IAAA,WAAA,CAAY,aAAwB,EAAA;AAChC,QAAA,IAAI,CAAC,cAAc,GAAG,aAAa;IACvC;IACA,MAAM,cAAc,CAAC,WAAmB,EAAA;QACpC,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAiC,sBAAsB,CAAC;QACrG,MAAM,WAAW,GAAG,aAAa,GAAG,iBAAiB,CAAC,EAAE,QAAQ,CAAC,CAAC,OAAO,KAAK,OAAO,CAAC,EAAE,KAAK,WAAW,CAAC;QACzG,mBAAmB,CAAC,WAAW,CAAC;AAChC,QAAA,OAAO,WAAW;IACtB;AAEA,IAAA,MAAM,eAAe,GAAA;QACjB,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,CAAC,GAAG,CAAiC,sBAAsB,CAAC;QACrG,MAAM,YAAY,GAAG,aAAa,GAAG,iBAAiB,CAAC,IAAI,EAAE;AAC7D,QAAA,YAAY,CAAC,OAAO,CAAC,WAAW,IAAG;YAC/B,mBAAmB,CAAC,WAAW,CAAC;AACpC,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,YAAY;IACvB;AACH;AAED;;AAEG;MACU,sCAAsC,CAAA;AAC/C,IAAA,cAAc;AAEd,IAAA,WAAA,CAAY,aAAsC,EAAA;AAC9C,QAAA,IAAI,CAAC,cAAc,GAAG,aAAa;IACvC;IAEA,MAAM,cAAc,CAAC,WAAmB,EAAA;AACpC,QAAA,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,sBAAsB,CAAC,GAAG,iBAAiB,CAAC;AACrF,QAAA,MAAM,WAAW,GAAG,YAAY,EAAE,QAAQ,CAAC,CAAC,OAAoB,KAAK,OAAO,CAAC,EAAE,KAAK,WAAW,CAAC;QAChG,mBAAmB,CAAC,WAAW,CAAC;AAChC,QAAA,OAAO,WAAW;IACtB;AAEA,IAAA,MAAM,eAAe,GAAA;AACjB,QAAA,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,CAAC,sBAAsB,CAAC,GAAG,iBAAiB,CAAC,IAAI,EAAE;AAC3F,QAAA,YAAY,CAAC,OAAO,CAAC,WAAW,IAAG;YAC/B,mBAAmB,CAAC,WAAW,CAAC;AACpC,QAAA,CAAC,CAAC;AACF,QAAA,OAAO,YAAY;IACvB;AACH;;;;"}

package/dist/esm/filter/recurrence/evaluator.js

@@ -0,0 +1,140 @@
+import { RecurrencePatternType, RecurrenceRangeType, ONE_DAY_IN_MILLISECONDS, DAYS_PER_WEEK } from './model.js';
+import { addDays, getDayOfWeek, sortDaysOfWeek, calculateWeeklyDayOffset } from './utils.js';
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+/**
+ * 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
+ */
+function matchRecurrence(time, recurrenceSpec) {
+    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, recurrenceSpec) {
+    if (time < recurrenceSpec.startTime) {
+        return undefined;
+    }
+    let result;
+    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, recurrenceSpec) {
+    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, recurrenceSpec) {
+    /*
+     * 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
+    };
+}
+
+export { matchRecurrence };
+//# sourceMappingURL=evaluator.js.map

package/dist/esm/filter/recurrence/evaluator.js.map

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

package/dist/esm/filter/recurrence/model.js

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+const DAYS_PER_WEEK = 7;
+const ONE_DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;
+var DayOfWeek;
+(function (DayOfWeek) {
+    DayOfWeek[DayOfWeek["Sunday"] = 0] = "Sunday";
+    DayOfWeek[DayOfWeek["Monday"] = 1] = "Monday";
+    DayOfWeek[DayOfWeek["Tuesday"] = 2] = "Tuesday";
+    DayOfWeek[DayOfWeek["Wednesday"] = 3] = "Wednesday";
+    DayOfWeek[DayOfWeek["Thursday"] = 4] = "Thursday";
+    DayOfWeek[DayOfWeek["Friday"] = 5] = "Friday";
+    DayOfWeek[DayOfWeek["Saturday"] = 6] = "Saturday";
+})(DayOfWeek || (DayOfWeek = {}));
+/**
+ * The recurrence pattern describes the frequency by which the time window repeats
+ */
+var RecurrencePatternType;
+(function (RecurrencePatternType) {
+    /**
+     * The pattern where the time window will repeat based on the number of days specified by interval between occurrences
+     */
+    RecurrencePatternType[RecurrencePatternType["Daily"] = 0] = "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
+     */
+    RecurrencePatternType[RecurrencePatternType["Weekly"] = 1] = "Weekly";
+})(RecurrencePatternType || (RecurrencePatternType = {}));
+/**
+ * The recurrence range specifies the date range over which the time window repeats
+ */
+var RecurrenceRangeType;
+(function (RecurrenceRangeType) {
+    /**
+     * The recurrence has no end and repeats on all the days that fit the corresponding pattern
+     */
+    RecurrenceRangeType[RecurrenceRangeType["NoEnd"] = 0] = "NoEnd";
+    /**
+     * The recurrence repeats on all the days that fit the corresponding pattern until or on the specified end date
+     */
+    RecurrenceRangeType[RecurrenceRangeType["EndDate"] = 1] = "EndDate";
+    /**
+     * The recurrence repeats for the specified number of occurrences that match the pattern
+     */
+    RecurrenceRangeType[RecurrenceRangeType["Numbered"] = 2] = "Numbered";
+})(RecurrenceRangeType || (RecurrenceRangeType = {}));
+
+export { DAYS_PER_WEEK, DayOfWeek, ONE_DAY_IN_MILLISECONDS, RecurrencePatternType, RecurrenceRangeType };
+//# sourceMappingURL=model.js.map

package/dist/esm/filter/recurrence/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sources":["../../../../src/filter/recurrence/model.ts"],"sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nexport const DAYS_PER_WEEK = 7;\nexport const ONE_DAY_IN_MILLISECONDS = 24 * 60 * 60 * 1000;\n\nexport enum DayOfWeek {\n    Sunday = 0,\n    Monday = 1,\n    Tuesday = 2,\n    Wednesday = 3,\n    Thursday = 4,\n    Friday = 5,\n    Saturday = 6\n}\n\n/**\n * The recurrence pattern describes the frequency by which the time window repeats\n */\nexport enum RecurrencePatternType {\n    /**\n     * The pattern where the time window will repeat based on the number of days specified by interval between occurrences\n     */\n    Daily,\n    /**\n     * 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\n     */\n    Weekly\n}\n\n/**\n * The recurrence range specifies the date range over which the time window repeats\n */\nexport enum RecurrenceRangeType {\n    /**\n     * The recurrence has no end and repeats on all the days that fit the corresponding pattern\n     */\n    NoEnd,\n    /**\n     * The recurrence repeats on all the days that fit the corresponding pattern until or on the specified end date\n     */\n    EndDate,\n    /**\n     * The recurrence repeats for the specified number of occurrences that match the pattern\n     */\n    Numbered\n}\n\n/**\n * The recurrence pattern describes the frequency by which the time window repeats\n */\nexport type RecurrencePattern = {\n    /**\n     * The type of the recurrence pattern\n     */\n    type: RecurrencePatternType;\n    /**\n     * The number of units between occurrences, where units can be in days or weeks, depending on the pattern type\n     */\n    interval: number;\n    /**\n     * The days of the week when the time window occurs, which is only applicable for 'Weekly' pattern\n     */\n    daysOfWeek?: DayOfWeek[];\n    /**\n     * The first day of the week, which is only applicable for 'Weekly' pattern\n     */\n    firstDayOfWeek?: DayOfWeek;\n};\n\n/**\n * The recurrence range describes a date range over which the time window repeats\n */\nexport type RecurrenceRange = {\n    /**\n     * The type of the recurrence range\n     */\n    type: RecurrenceRangeType;\n    /**\n     * The date to stop applying the recurrence pattern, which is only applicable for 'EndDate' range\n     */\n    endDate?: Date;\n    /**\n     * The number of times to repeat the time window, which is only applicable for 'Numbered' range\n     */\n    numberOfOccurrences?: number;\n};\n\n/**\n * Specification defines the recurring time window\n */\nexport type RecurrenceSpec = {\n    /**\n     * The start time of the first/base time window\n     */\n    startTime: Date;\n    /**\n     * The duration of each time window in milliseconds\n     */\n    duration: number;\n    /**\n     * The recurrence pattern\n     */\n    pattern: RecurrencePattern;\n    /**\n     * The recurrence range\n     */\n    range: RecurrenceRange;\n    /**\n     * The timezone offset in milliseconds, which helps to determine the day of week of a given date\n     */\n    timezoneOffset: number;\n};\n"],"names":[],"mappings":"AAAA;AACA;AAEO,MAAM,aAAa,GAAG;AACtB,MAAM,uBAAuB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG;IAE1C;AAAZ,CAAA,UAAY,SAAS,EAAA;AACjB,IAAA,SAAA,CAAA,SAAA,CAAA,QAAA,CAAA,GAAA,CAAA,CAAA,GAAA,QAAU;AACV,IAAA,SAAA,CAAA,SAAA,CAAA,QAAA,CAAA,GAAA,CAAA,CAAA,GAAA,QAAU;AACV,IAAA,SAAA,CAAA,SAAA,CAAA,SAAA,CAAA,GAAA,CAAA,CAAA,GAAA,SAAW;AACX,IAAA,SAAA,CAAA,SAAA,CAAA,WAAA,CAAA,GAAA,CAAA,CAAA,GAAA,WAAa;AACb,IAAA,SAAA,CAAA,SAAA,CAAA,UAAA,CAAA,GAAA,CAAA,CAAA,GAAA,UAAY;AACZ,IAAA,SAAA,CAAA,SAAA,CAAA,QAAA,CAAA,GAAA,CAAA,CAAA,GAAA,QAAU;AACV,IAAA,SAAA,CAAA,SAAA,CAAA,UAAA,CAAA,GAAA,CAAA,CAAA,GAAA,UAAY;AAChB,CAAC,EARW,SAAS,KAAT,SAAS,GAAA,EAAA,CAAA,CAAA;AAUrB;;AAEG;IACS;AAAZ,CAAA,UAAY,qBAAqB,EAAA;AAC7B;;AAEG;AACH,IAAA,qBAAA,CAAA,qBAAA,CAAA,OAAA,CAAA,GAAA,CAAA,CAAA,GAAA,OAAK;AACL;;AAEG;AACH,IAAA,qBAAA,CAAA,qBAAA,CAAA,QAAA,CAAA,GAAA,CAAA,CAAA,GAAA,QAAM;AACV,CAAC,EATW,qBAAqB,KAArB,qBAAqB,GAAA,EAAA,CAAA,CAAA;AAWjC;;AAEG;IACS;AAAZ,CAAA,UAAY,mBAAmB,EAAA;AAC3B;;AAEG;AACH,IAAA,mBAAA,CAAA,mBAAA,CAAA,OAAA,CAAA,GAAA,CAAA,CAAA,GAAA,OAAK;AACL;;AAEG;AACH,IAAA,mBAAA,CAAA,mBAAA,CAAA,SAAA,CAAA,GAAA,CAAA,CAAA,GAAA,SAAO;AACP;;AAEG;AACH,IAAA,mBAAA,CAAA,mBAAA,CAAA,UAAA,CAAA,GAAA,CAAA,CAAA,GAAA,UAAQ;AACZ,CAAC,EAbW,mBAAmB,KAAnB,mBAAmB,GAAA,EAAA,CAAA,CAAA;;;;"}

package/dist/esm/filter/recurrence/utils.js

@@ -0,0 +1,48 @@
+import { DAYS_PER_WEEK } from './model.js';
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+/**
+ * Calculates the offset in days between two given days of the week.
+ * @param day1 A day of week
+ * @param day2 A day of week
+ * @returns The number of days to be added to day2 to reach day1
+ */
+function calculateWeeklyDayOffset(day1, day2) {
+    return (day1 - day2 + DAYS_PER_WEEK) % DAYS_PER_WEEK;
+}
+/**
+ * Sorts a collection of days of week based on their offsets from a specified first day of week.
+ * @param daysOfWeek A collection of days of week
+ * @param firstDayOfWeek The first day of week which will be the first element in the sorted result
+ * @returns The sorted days of week
+ */
+function sortDaysOfWeek(daysOfWeek, firstDayOfWeek) {
+    const sortedDaysOfWeek = daysOfWeek.slice();
+    sortedDaysOfWeek.sort((x, y) => calculateWeeklyDayOffset(x, firstDayOfWeek) - calculateWeeklyDayOffset(y, firstDayOfWeek));
+    return sortedDaysOfWeek;
+}
+/**
+ * Gets the day of week of a given date based on the timezone offset.
+ * @param date A UTC date
+ * @param timezoneOffsetInMs The timezone offset in milliseconds
+ * @returns The day of week (0 for Sunday, 1 for Monday, ..., 6 for Saturday)
+ */
+function getDayOfWeek(date, timezoneOffsetInMs) {
+    const alignedDate = new Date(date.getTime() + timezoneOffsetInMs);
+    return alignedDate.getUTCDay();
+}
+/**
+ * Adds a specified number of days to a given date.
+ * @param date The date to add days to
+ * @param days The number of days to add
+ * @returns The new date
+ */
+function addDays(date, days) {
+    const result = new Date(date);
+    result.setDate(result.getDate() + days);
+    return result;
+}
+
+export { addDays, calculateWeeklyDayOffset, getDayOfWeek, sortDaysOfWeek };
+//# sourceMappingURL=utils.js.map

package/dist/esm/filter/recurrence/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sources":["../../../../src/filter/recurrence/utils.ts"],"sourcesContent":["// Copyright (c) Microsoft Corporation.\n// Licensed under the MIT license.\n\nimport { DayOfWeek, DAYS_PER_WEEK } from \"./model.js\";\n\n/**\n * Calculates the offset in days between two given days of the week.\n * @param day1 A day of week\n * @param day2 A day of week\n * @returns The number of days to be added to day2 to reach day1\n */\nexport function calculateWeeklyDayOffset(day1: DayOfWeek, day2: DayOfWeek): number {\n    return (day1 - day2 + DAYS_PER_WEEK) % DAYS_PER_WEEK;\n}\n\n/**\n * Sorts a collection of days of week based on their offsets from a specified first day of week.\n * @param daysOfWeek A collection of days of week\n * @param firstDayOfWeek The first day of week which will be the first element in the sorted result\n * @returns The sorted days of week\n */\nexport function sortDaysOfWeek(daysOfWeek: DayOfWeek[], firstDayOfWeek: DayOfWeek): DayOfWeek[] {\n    const sortedDaysOfWeek = daysOfWeek.slice();\n    sortedDaysOfWeek.sort((x, y) => calculateWeeklyDayOffset(x, firstDayOfWeek) - calculateWeeklyDayOffset(y, firstDayOfWeek));\n    return sortedDaysOfWeek;\n}\n\n/**\n * Gets the day of week of a given date based on the timezone offset.\n * @param date A UTC date\n * @param timezoneOffsetInMs The timezone offset in milliseconds\n * @returns The day of week (0 for Sunday, 1 for Monday, ..., 6 for Saturday)\n */\nexport function getDayOfWeek(date: Date, timezoneOffsetInMs: number): number {\n    const alignedDate = new Date(date.getTime() + timezoneOffsetInMs);\n    return alignedDate.getUTCDay();\n}\n\n/**\n * Adds a specified number of days to a given date.\n * @param date The date to add days to\n * @param days The number of days to add\n * @returns The new date\n */\nexport function addDays(date: Date, days: number): Date {\n    const result = new Date(date);\n    result.setDate(result.getDate() + days);\n    return result;\n}\n"],"names":[],"mappings":";;AAAA;AACA;AAIA;;;;;AAKG;AACG,SAAU,wBAAwB,CAAC,IAAe,EAAE,IAAe,EAAA;IACrE,OAAO,CAAC,IAAI,GAAG,IAAI,GAAG,aAAa,IAAI,aAAa;AACxD;AAEA;;;;;AAKG;AACG,SAAU,cAAc,CAAC,UAAuB,EAAE,cAAyB,EAAA;AAC7E,IAAA,MAAM,gBAAgB,GAAG,UAAU,CAAC,KAAK,EAAE;IAC3C,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,wBAAwB,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG,wBAAwB,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC;AAC1H,IAAA,OAAO,gBAAgB;AAC3B;AAEA;;;;;AAKG;AACG,SAAU,YAAY,CAAC,IAAU,EAAE,kBAA0B,EAAA;AAC/D,IAAA,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,kBAAkB,CAAC;AACjE,IAAA,OAAO,WAAW,CAAC,SAAS,EAAE;AAClC;AAEA;;;;;AAKG;AACG,SAAU,OAAO,CAAC,IAAU,EAAE,IAAY,EAAA;AAC5C,IAAA,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC;IAC7B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC;AACvC,IAAA,OAAO,MAAM;AACjB;;;;"}

package/dist/esm/filter/recurrence/validator.js

@@ -0,0 +1,184 @@
+import { buildInvalidParameterErrorMessage, REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE, VALUE_OUT_OF_RANGE_ERROR_MESSAGE, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE } from '../utils.js';
+import { ONE_DAY_IN_MILLISECONDS, RecurrenceRangeType, RecurrencePatternType, DayOfWeek, DAYS_PER_WEEK } from './model.js';
+import { getDayOfWeek, sortDaysOfWeek, calculateWeeklyDayOffset } from './utils.js';
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+const START_NOT_MATCHED_ERROR_MESSAGE = "Start date is not a valid first occurrence.";
+const TIME_WINDOW_DURATION_OUT_OF_RANGE_ERROR_MESSAGE = "Time window duration cannot be longer than how frequently it occurs or be longer than 10 years.";
+const PATTERN = "Recurrence.Pattern";
+const PATTERN_TYPE = "Recurrence.Pattern.Type";
+const INTERVAL = "Recurrence.Pattern.Interval";
+const DAYS_OF_WEEK = "Recurrence.Pattern.DaysOfWeek";
+const FIRST_DAY_OF_WEEK = "Recurrence.Pattern.FirstDayOfWeek";
+const RANGE = "Recurrence.Range";
+const RANGE_TYPE = "Recurrence.Range.Type";
+const END_DATE = "Recurrence.Range.EndDate";
+const NUMBER_OF_OCCURRENCES = "Recurrence.Range.NumberOfOccurrences";
+/**
+ * Parses @see RecurrenceParameters into a @see RecurrenceSpec object. If the parameter is invalid, an error will be thrown.
+ * @param startTime The start time of the base time window
+ * @param day2 The end time of the base time window
+ * @param recurrenceParameters The @see RecurrenceParameters to parse
+ * @param TimeZoneOffset The time zone offset in milliseconds, by default 0
+ * @returns A @see RecurrenceSpec object
+ */
+function parseRecurrenceParameter(startTime, endTime, recurrenceParameters, TimeZoneOffset = 0) {
+    if (startTime === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage("Start", REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+    }
+    if (endTime === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage("End", REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+    }
+    if (startTime >= endTime) {
+        throw new Error(buildInvalidParameterErrorMessage("End", VALUE_OUT_OF_RANGE_ERROR_MESSAGE));
+    }
+    const timeWindowDuration = endTime.getTime() - startTime.getTime();
+    if (timeWindowDuration > 10 * 365 * ONE_DAY_IN_MILLISECONDS) { // time window duration cannot be longer than 10 years
+        throw new Error(buildInvalidParameterErrorMessage("End", TIME_WINDOW_DURATION_OUT_OF_RANGE_ERROR_MESSAGE));
+    }
+    return {
+        startTime: startTime,
+        duration: timeWindowDuration,
+        pattern: parseRecurrencePattern(startTime, endTime, recurrenceParameters, TimeZoneOffset),
+        range: parseRecurrenceRange(startTime, recurrenceParameters),
+        timezoneOffset: TimeZoneOffset
+    };
+}
+function parseRecurrencePattern(startTime, endTime, recurrenceParameters, timeZoneOffset) {
+    const rawPattern = recurrenceParameters.Pattern;
+    if (rawPattern === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage(PATTERN, REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+    }
+    if (rawPattern.Type === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage(PATTERN_TYPE, REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+    }
+    const patternType = RecurrencePatternType[rawPattern.Type];
+    if (patternType === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage(PATTERN_TYPE, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+    }
+    let interval = rawPattern.Interval;
+    if (interval !== undefined) {
+        if (typeof interval !== "number") {
+            throw new Error(buildInvalidParameterErrorMessage(INTERVAL, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+        }
+        else if (interval <= 0 || !Number.isInteger(interval)) {
+            throw new Error(buildInvalidParameterErrorMessage(INTERVAL, VALUE_OUT_OF_RANGE_ERROR_MESSAGE));
+        }
+    }
+    else {
+        interval = 1;
+    }
+    const parsedPattern = {
+        type: patternType,
+        interval: interval
+    };
+    const timeWindowDuration = endTime.getTime() - startTime.getTime();
+    if (patternType === RecurrencePatternType.Daily) {
+        if (timeWindowDuration > interval * ONE_DAY_IN_MILLISECONDS) {
+            throw new Error(buildInvalidParameterErrorMessage("End", TIME_WINDOW_DURATION_OUT_OF_RANGE_ERROR_MESSAGE));
+        }
+    }
+    else if (patternType === RecurrencePatternType.Weekly) {
+        let firstDayOfWeek;
+        if (rawPattern.FirstDayOfWeek !== undefined) {
+            firstDayOfWeek = DayOfWeek[rawPattern.FirstDayOfWeek];
+            if (firstDayOfWeek === undefined) {
+                throw new Error(buildInvalidParameterErrorMessage(FIRST_DAY_OF_WEEK, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+            }
+        }
+        else {
+            firstDayOfWeek = DayOfWeek.Sunday;
+        }
+        parsedPattern.firstDayOfWeek = firstDayOfWeek;
+        if (rawPattern.DaysOfWeek === undefined || rawPattern.DaysOfWeek.length === 0) {
+            throw new Error(buildInvalidParameterErrorMessage(DAYS_OF_WEEK, REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+        }
+        if (!Array.isArray(rawPattern.DaysOfWeek)) {
+            throw new Error(buildInvalidParameterErrorMessage(DAYS_OF_WEEK, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+        }
+        const daysOfWeek = [...new Set(rawPattern.DaysOfWeek.map(day => DayOfWeek[day]))]; // dedup array
+        if (daysOfWeek.some(day => day === undefined)) {
+            throw new Error(buildInvalidParameterErrorMessage(DAYS_OF_WEEK, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+        }
+        if (timeWindowDuration > interval * DAYS_PER_WEEK * ONE_DAY_IN_MILLISECONDS ||
+            !isDurationCompliantWithDaysOfWeek(timeWindowDuration, interval, daysOfWeek, firstDayOfWeek)) {
+            throw new Error(buildInvalidParameterErrorMessage("End", TIME_WINDOW_DURATION_OUT_OF_RANGE_ERROR_MESSAGE));
+        }
+        parsedPattern.daysOfWeek = daysOfWeek;
+        // check whether "Start" is a valid first occurrence
+        const alignedStartDay = getDayOfWeek(startTime, timeZoneOffset);
+        if (!daysOfWeek.find(day => day === alignedStartDay)) {
+            throw new Error(buildInvalidParameterErrorMessage("Start", START_NOT_MATCHED_ERROR_MESSAGE));
+        }
+    }
+    return parsedPattern;
+}
+function parseRecurrenceRange(startTime, recurrenceParameters) {
+    const rawRange = recurrenceParameters.Range;
+    if (rawRange === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage(RANGE, REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+    }
+    if (rawRange.Type === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage(RANGE_TYPE, REQUIRED_PARAMETER_MISSING_ERROR_MESSAGE));
+    }
+    const rangeType = RecurrenceRangeType[rawRange.Type];
+    if (rangeType === undefined) {
+        throw new Error(buildInvalidParameterErrorMessage(RANGE_TYPE, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+    }
+    const parsedRange = { type: rangeType };
+    if (rangeType === RecurrenceRangeType.EndDate) {
+        let endDate;
+        if (rawRange.EndDate !== undefined) {
+            endDate = new Date(rawRange.EndDate);
+            if (isNaN(endDate.getTime())) {
+                throw new Error(buildInvalidParameterErrorMessage(END_DATE, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+            }
+            if (endDate < startTime) {
+                throw new Error(buildInvalidParameterErrorMessage(END_DATE, VALUE_OUT_OF_RANGE_ERROR_MESSAGE));
+            }
+        }
+        else {
+            endDate = new Date(8.64e15); // the maximum date in ECMAScript: https://262.ecma-international.org/5.1/#sec-15.9.1.1
+        }
+        parsedRange.endDate = endDate;
+    }
+    else if (rangeType === RecurrenceRangeType.Numbered) {
+        let numberOfOccurrences = rawRange.NumberOfOccurrences;
+        if (numberOfOccurrences !== undefined) {
+            if (typeof numberOfOccurrences !== "number") {
+                throw new Error(buildInvalidParameterErrorMessage(NUMBER_OF_OCCURRENCES, UNRECOGNIZABLE_VALUE_ERROR_MESSAGE));
+            }
+            else if (numberOfOccurrences <= 0 || !Number.isInteger(numberOfOccurrences)) {
+                throw new Error(buildInvalidParameterErrorMessage(NUMBER_OF_OCCURRENCES, VALUE_OUT_OF_RANGE_ERROR_MESSAGE));
+            }
+        }
+        else {
+            numberOfOccurrences = Number.MAX_SAFE_INTEGER;
+        }
+        parsedRange.numberOfOccurrences = numberOfOccurrences;
+    }
+    return parsedRange;
+}
+function isDurationCompliantWithDaysOfWeek(duration, interval, daysOfWeek, firstDayOfWeek) {
+    if (daysOfWeek.length === 1) {
+        return true;
+    }
+    const sortedDaysOfWeek = sortDaysOfWeek(daysOfWeek, firstDayOfWeek);
+    let prev = sortedDaysOfWeek[0]; // the closest occurrence day to the first day of week
+    let minGap = DAYS_PER_WEEK * ONE_DAY_IN_MILLISECONDS;
+    for (let i = 1; i < sortedDaysOfWeek.length; i++) { // skip the first day
+        const gap = calculateWeeklyDayOffset(sortedDaysOfWeek[i], prev) * ONE_DAY_IN_MILLISECONDS;
+        minGap = gap < minGap ? gap : minGap;
+        prev = sortedDaysOfWeek[i];
+    }
+    // It may across weeks. Check the next week if the interval is one week.
+    if (interval == 1) {
+        const gap = calculateWeeklyDayOffset(sortedDaysOfWeek[0], prev) * ONE_DAY_IN_MILLISECONDS;
+        minGap = gap < minGap ? gap : minGap;
+    }
+    return minGap >= duration;
+}
+
+export { DAYS_OF_WEEK, END_DATE, FIRST_DAY_OF_WEEK, INTERVAL, NUMBER_OF_OCCURRENCES, PATTERN, PATTERN_TYPE, RANGE, RANGE_TYPE, START_NOT_MATCHED_ERROR_MESSAGE, TIME_WINDOW_DURATION_OUT_OF_RANGE_ERROR_MESSAGE, parseRecurrenceParameter };
+//# sourceMappingURL=validator.js.map