@akatan/date-to-festive 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AkatanHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# Date To Festive
+
+A standalone, reusable module for resolving themes based on dates. Zero dependencies, simple API.
+
+## Installation
+
+```bash
+npm install @akatan/date-to-festive
+```
+
+## Usage
+
+### Simple Example
+
+```typescript
+import { resolvePrimaryThemeForDate } from '@akatanhq/date-to-festive';
+
+// Get today's theme
+const theme = resolvePrimaryThemeForDate(new Date());
+console.log(theme);
+// { name: 'winter', category: 'seasonal', metadata: { description: '...' } }
+```
+
+### Get All Matching Themes
+
+```typescript
+import { resolveThemesForDate } from '@akatan/date-to-festive';
+
+// Get all themes for Christmas
+const themes = resolveThemesForDate(new Date('2025-12-25'));
+// [{ name: 'christmas', category: 'seasonal', metadata: {...} }]
+```
+
+### With Cultural Themes
+
+```typescript
+const themes = resolveThemesForDate(
+  new Date('2025-10-23'),
+  {
+    enabledCultures: ['diwali'],
+    userRegion: 'india'
+  }
+);
+// [{ name: 'diwali', category: 'cultural', ... }, ...]
+```
+
+## API
+
+### `resolvePrimaryThemeForDate(date, options?)`
+
+Returns the most specific theme for a given date.
+
+**Parameters:**
+- `date: Date` - The date to resolve
+- `options?: ResolverOptions`
+  - `enabledCultures?: string[]` - Cultural themes to enable
+  - `userRegion?: string` - User's region
+
+**Returns:** `ResolvedTheme | null`
+
+### `resolveThemesForDate(date, options?)`
+
+Returns all matching themes for a given date, sorted by specificity.
+
+**Parameters:** Same as above
+
+**Returns:** `ResolvedTheme[]`
+
+## Theme Types
+
+The module includes:
+- **Seasonal**: winter, spring, summer, autumn, etc.
+- **Holidays**: christmas, halloween, easter, thanksgiving, etc.
+- **Cultural**: diwali, chinese-new-year, hanukkah, ramadan, etc. (opt-in)
+- **Everyday**: fallback theme when nothing matches
+
+## Features
+
+- ✅ Zero dependencies
+- ✅ TypeScript support
+- ✅ Simple API - just pass a date
+- ✅ Handles year wrap-around (e.g., New Year)
+- ✅ Calculated holidays (Easter, Thanksgiving)
+- ✅ Cultural theme support with opt-in
+- ✅ Specificity sorting (shorter duration = higher priority)
+
+## License
+
+MIT
+
+## Repository
+
+https://github.com/akatanhq/date-to-festive

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Theme Resolver Per Day
+ *
+ * A standalone, reusable module for resolving themes based on dates.
+ * Just pass a date and get matching themes - configuration is handled internally.
+ */
+export * from './resolver';

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * Theme Resolver Per Day
+ *
+ * A standalone, reusable module for resolving themes based on dates.
+ * Just pass a date and get matching themes - configuration is handled internally.
+ */
+export * from './resolver';

package/dist/resolver.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Theme Resolver Per Day - Standalone Module
+ *
+ * A reusable module for resolving themes based on dates.
+ * Configuration is included internally - just pass a date and get themes.
+ */
+export type DateRule = {
+    kind: 'range';
+    from: string;
+    to: string;
+} | {
+    kind: 'holiday-offset';
+    holiday: 'easter';
+    start: number;
+    end: number;
+} | {
+    kind: 'nth-weekday';
+    month: number;
+    weekday: number;
+    n: number;
+    duration?: number;
+} | {
+    kind: 'always';
+};
+export interface ThemeRule {
+    name: string;
+    rule: DateRule;
+    enabled?: boolean;
+    region?: string[];
+    metadata?: {
+        actualDate?: string;
+        description?: string;
+    };
+}
+export interface ThemeRulesConfig {
+    seasonal: ThemeRule[];
+    holidays: ThemeRule[];
+    cultural: ThemeRule[];
+    everyday: ThemeRule[];
+}
+export interface ResolverOptions {
+    enabledCultures?: string[];
+    userRegion?: string;
+}
+export interface ResolvedTheme {
+    name: string;
+    category: 'seasonal' | 'holidays' | 'cultural' | 'everyday';
+    rule: DateRule;
+    metadata?: {
+        actualDate?: string;
+        description?: string;
+    };
+}
+/**
+ * Resolve themes for a specific date
+ *
+ * @param date - The date to resolve themes for
+ * @param options - Optional filters for cultural themes and region
+ * @returns Array of resolved themes, sorted by specificity (shortest duration first)
+ *
+ * @example
+ * ```typescript
+ * const themes = resolveThemesForDate(
+ *   new Date('2025-12-25'),
+ *   { enabledCultures: ['diwali'], userRegion: 'india' }
+ * );
+ * // Returns: [{ name: 'christmas', category: 'seasonal', metadata: {...} }]
+ * ```
+ */
+export declare function resolveThemesForDate(date: Date, options?: ResolverOptions): ResolvedTheme[];
+/**
+ * Get the primary (most specific) theme for a date
+ *
+ * @param date - The date to resolve theme for
+ * @param options - Optional filters for cultural themes and region
+ * @returns The most specific matching theme, or null if none found
+ *
+ * @example
+ * ```typescript
+ * const theme = resolvePrimaryThemeForDate(new Date('2025-10-31'));
+ * // Returns: { name: 'halloween', category: 'holidays', metadata: {...} }
+ * ```
+ */
+export declare function resolvePrimaryThemeForDate(date: Date, options?: ResolverOptions): ResolvedTheme | null;

package/dist/resolver.js

@@ -0,0 +1,237 @@
+/**
+ * Theme Resolver Per Day - Standalone Module
+ *
+ * A reusable module for resolving themes based on dates.
+ * Configuration is included internally - just pass a date and get themes.
+ */
+import themeRulesConfigJson from './themeRules.json';
+const themeRulesConfig = themeRulesConfigJson;
+/**
+ * Resolve themes for a specific date
+ *
+ * @param date - The date to resolve themes for
+ * @param options - Optional filters for cultural themes and region
+ * @returns Array of resolved themes, sorted by specificity (shortest duration first)
+ *
+ * @example
+ * ```typescript
+ * const themes = resolveThemesForDate(
+ *   new Date('2025-12-25'),
+ *   { enabledCultures: ['diwali'], userRegion: 'india' }
+ * );
+ * // Returns: [{ name: 'christmas', category: 'seasonal', metadata: {...} }]
+ * ```
+ */
+export function resolveThemesForDate(date, options = {}) {
+    const { enabledCultures = [], userRegion } = options;
+    const year = date.getFullYear();
+    // Use internal config and flatten with category
+    const config = themeRulesConfig;
+    const allRules = [
+        ...config.seasonal.map(rule => ({ ...rule, category: 'seasonal' })),
+        ...config.holidays.map(rule => ({ ...rule, category: 'holidays' })),
+        ...config.cultural.map(rule => ({ ...rule, category: 'cultural' })),
+        ...config.everyday.map(rule => ({ ...rule, category: 'everyday' }))
+    ];
+    // Filter available themes based on enabled cultures and region
+    const availableRules = allRules.filter(rule => {
+        // Skip everyday theme in first pass
+        if (rule.name === 'everyday') {
+            return false;
+        }
+        // Always include non-cultural themes (enabled undefined or true)
+        if (rule.enabled === undefined || rule.enabled === true) {
+            return true;
+        }
+        // For cultural themes, check if they're enabled
+        if (rule.enabled === false) {
+            return enabledCultures.includes(rule.name) ||
+                (rule.region && userRegion && rule.region.includes(userRegion));
+        }
+        return false;
+    });
+    // Find all matching themes
+    const matchingThemes = [];
+    for (const rule of availableRules) {
+        if (isRuleActive(rule.rule, date, year)) {
+            matchingThemes.push({
+                name: rule.name,
+                category: rule.category,
+                rule: rule.rule,
+                metadata: rule.metadata
+            });
+        }
+    }
+    // Sort by duration (shortest first = most specific)
+    matchingThemes.sort((a, b) => {
+        const ruleA = allRules.find(r => r.name === a.name);
+        const ruleB = allRules.find(r => r.name === b.name);
+        const durationA = getThemeDuration(ruleA.rule, year);
+        const durationB = getThemeDuration(ruleB.rule, year);
+        return durationA - durationB;
+    });
+    // If no themes match, return everyday theme
+    if (matchingThemes.length === 0) {
+        const everydayRule = config.everyday.find(r => r.name === 'everyday');
+        if (everydayRule) {
+            matchingThemes.push({
+                name: 'everyday',
+                category: 'everyday',
+                rule: everydayRule.rule,
+                metadata: everydayRule.metadata
+            });
+        }
+    }
+    return matchingThemes;
+}
+/**
+ * Get the primary (most specific) theme for a date
+ *
+ * @param date - The date to resolve theme for
+ * @param options - Optional filters for cultural themes and region
+ * @returns The most specific matching theme, or null if none found
+ *
+ * @example
+ * ```typescript
+ * const theme = resolvePrimaryThemeForDate(new Date('2025-10-31'));
+ * // Returns: { name: 'halloween', category: 'holidays', metadata: {...} }
+ * ```
+ */
+export function resolvePrimaryThemeForDate(date, options = {}) {
+    const themes = resolveThemesForDate(date, options);
+    return themes.length > 0 ? themes[0] : null;
+}
+/**
+ * Check if a date rule is active for a given date
+ */
+function isRuleActive(rule, date, year) {
+    switch (rule.kind) {
+        case 'range':
+            return isInRange(rule.from, rule.to, date);
+        case 'holiday-offset':
+            return isHolidayOffsetActive(rule.holiday, rule.start, rule.end, date, year);
+        case 'nth-weekday':
+            return isNthWeekdayActive(rule.month, rule.weekday, rule.n, rule.duration || 1, date);
+        case 'always':
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * Check if a date falls within a range
+ */
+function isInRange(from, to, date) {
+    const month = date.getMonth() + 1;
+    const day = date.getDate();
+    const currentDate = `${month.toString().padStart(2, '0')}-${day.toString().padStart(2, '0')}`;
+    // Handle year wrap-around (e.g., Christmas: 12-26 to 01-07)
+    if (from <= to) {
+        return currentDate >= from && currentDate <= to;
+    }
+    else {
+        return currentDate >= from || currentDate <= to;
+    }
+}
+/**
+ * Check if a date is within a holiday offset range
+ */
+function isHolidayOffsetActive(holiday, startOffset, endOffset, date, year) {
+    let holidayDate;
+    switch (holiday) {
+        case 'easter':
+            holidayDate = calculateEaster(year);
+            break;
+        default:
+            return false;
+    }
+    const startDate = new Date(holidayDate);
+    startDate.setDate(startDate.getDate() + startOffset);
+    const endDate = new Date(holidayDate);
+    endDate.setDate(endDate.getDate() + endOffset);
+    return date >= startDate && date <= endDate;
+}
+/**
+ * Check if a date matches the nth weekday of a month
+ */
+function isNthWeekdayActive(month, weekday, n, duration = 1, date) {
+    const year = date.getFullYear();
+    // Find the nth occurrence of the weekday in the month
+    let count = 0;
+    let targetDate = null;
+    for (let day = 1; day <= 31; day++) {
+        const testDate = new Date(year, month - 1, day);
+        if (testDate.getMonth() !== month - 1)
+            break;
+        if (testDate.getDay() === weekday) {
+            count++;
+            if (count === n) {
+                targetDate = testDate;
+                break;
+            }
+        }
+    }
+    if (!targetDate)
+        return false;
+    // If duration is specified, check if date is within the duration window
+    if (duration > 1) {
+        const halfDuration = Math.floor(duration / 2);
+        const startDate = new Date(targetDate);
+        startDate.setDate(startDate.getDate() - halfDuration);
+        const endDate = new Date(targetDate);
+        endDate.setDate(endDate.getDate() + (duration - halfDuration - 1));
+        return date >= startDate && date <= endDate;
+    }
+    // Single day event - exact match
+    return date.toDateString() === targetDate.toDateString();
+}
+/**
+ * Calculate Easter date using Gauss algorithm
+ */
+function calculateEaster(year) {
+    const a = year % 19;
+    const b = Math.floor(year / 100);
+    const c = year % 100;
+    const d = Math.floor(b / 4);
+    const e = b % 4;
+    const f = Math.floor((b + 8) / 25);
+    const g = Math.floor((b - f + 1) / 3);
+    const h = (19 * a + b - d - g + 15) % 30;
+    const i = Math.floor(c / 4);
+    const k = c % 4;
+    const l = (32 + 2 * e + 2 * i - h - k) % 7;
+    const m = Math.floor((a + 11 * h + 22 * l) / 451);
+    const month = Math.floor((h + l - 7 * m + 114) / 31);
+    const day = ((h + l - 7 * m + 114) % 31) + 1;
+    return new Date(year, month - 1, day);
+}
+/**
+ * Calculate theme duration in days
+ */
+function getThemeDuration(rule, year) {
+    switch (rule.kind) {
+        case 'range': {
+            const [fromMonth, fromDay] = rule.from.split('-').map(Number);
+            const [toMonth, toDay] = rule.to.split('-').map(Number);
+            const startDate = new Date(year, fromMonth - 1, fromDay);
+            const endDate = new Date(year, toMonth - 1, toDay);
+            // Handle year wrap-around
+            if (endDate < startDate) {
+                endDate.setFullYear(year + 1);
+            }
+            const diffTime = endDate.getTime() - startDate.getTime();
+            return Math.ceil(diffTime / (1000 * 60 * 60 * 24)) + 1;
+        }
+        case 'holiday-offset': {
+            return Math.abs(rule.end - rule.start) + 1;
+        }
+        case 'nth-weekday': {
+            return rule.duration || 1;
+        }
+        case 'always': {
+            return Infinity;
+        }
+        default:
+            return Infinity;
+    }
+}

package/dist/themeRules.json

@@ -0,0 +1,247 @@
+{
+    "seasonal": [
+        {
+            "name": "new-year",
+            "rule": {
+                "kind": "range",
+                "from": "12-26",
+                "to": "01-07"
+            },
+            "metadata": {
+                "actualDate": "01-01",
+                "description": "New Year celebration period"
+            }
+        },
+        {
+            "name": "christmas",
+            "rule": {
+                "kind": "range",
+                "from": "11-25",
+                "to": "12-25"
+            },
+            "metadata": {
+                "actualDate": "12-25",
+                "description": "Christmas season"
+            }
+        },
+        {
+            "name": "winter",
+            "rule": {
+                "kind": "range",
+                "from": "01-08",
+                "to": "02-28"
+            },
+            "metadata": {
+                "description": "Winter season after New Year"
+            }
+        },
+        {
+            "name": "spring-beginning",
+            "rule": {
+                "kind": "range",
+                "from": "03-01",
+                "to": "03-20"
+            },
+            "metadata": {
+                "description": "Early spring period"
+            }
+        },
+        {
+            "name": "spring",
+            "rule": {
+                "kind": "range",
+                "from": "03-21",
+                "to": "05-31"
+            },
+            "metadata": {
+                "description": "Spring season"
+            }
+        },
+        {
+            "name": "summer-beginning",
+            "rule": {
+                "kind": "range",
+                "from": "06-01",
+                "to": "06-20"
+            },
+            "metadata": {
+                "description": "Early summer period"
+            }
+        },
+        {
+            "name": "summer-holiday",
+            "rule": {
+                "kind": "range",
+                "from": "06-21",
+                "to": "08-31"
+            },
+            "metadata": {
+                "description": "Summer vacation period"
+            }
+        },
+        {
+            "name": "back-to-school",
+            "rule": {
+                "kind": "range",
+                "from": "08-15",
+                "to": "09-15"
+            },
+            "metadata": {
+                "description": "Back to school season"
+            }
+        },
+        {
+            "name": "autumn",
+            "rule": {
+                "kind": "range",
+                "from": "09-16",
+                "to": "11-24"
+            },
+            "metadata": {
+                "description": "Autumn/Fall season"
+            }
+        }
+    ],
+    "holidays": [
+        {
+            "name": "halloween",
+            "rule": {
+                "kind": "range",
+                "from": "10-20",
+                "to": "10-31"
+            },
+            "metadata": {
+                "actualDate": "10-31",
+                "description": "Halloween celebration"
+            }
+        },
+        {
+            "name": "thanksgiving",
+            "rule": {
+                "kind": "nth-weekday",
+                "month": 11,
+                "weekday": 4,
+                "n": 4,
+                "duration": 7
+            },
+            "metadata": {
+                "description": "Thanksgiving (4th Thursday of November)"
+            }
+        },
+        {
+            "name": "easter",
+            "rule": {
+                "kind": "holiday-offset",
+                "holiday": "easter",
+                "start": -7,
+                "end": 1
+            },
+            "metadata": {
+                "description": "Easter celebration (calculated date)"
+            }
+        },
+        {
+            "name": "carnival",
+            "rule": {
+                "kind": "holiday-offset",
+                "holiday": "easter",
+                "start": -49,
+                "end": -46
+            },
+            "metadata": {
+                "description": "Carnival/Mardi Gras (before Easter)"
+            }
+        }
+    ],
+    "cultural": [
+        {
+            "name": "diwali",
+            "rule": {
+                "kind": "range",
+                "from": "10-20",
+                "to": "10-25"
+            },
+            "enabled": false,
+            "region": ["india", "global"],
+            "metadata": {
+                "description": "Festival of Lights (approximate dates)"
+            }
+        },
+        {
+            "name": "chinese-new-year",
+            "rule": {
+                "kind": "range",
+                "from": "01-21",
+                "to": "02-20"
+            },
+            "enabled": false,
+            "region": ["china", "global"],
+            "metadata": {
+                "description": "Chinese New Year (approximate dates)"
+            }
+        },
+        {
+            "name": "hanukkah",
+            "rule": {
+                "kind": "range",
+                "from": "11-25",
+                "to": "12-31"
+            },
+            "enabled": false,
+            "region": ["global"],
+            "metadata": {
+                "description": "Hanukkah (approximate dates)"
+            }
+        },
+        {
+            "name": "ramadan",
+            "rule": {
+                "kind": "range",
+                "from": "03-01",
+                "to": "04-30"
+            },
+            "enabled": false,
+            "region": ["global"],
+            "metadata": {
+                "description": "Ramadan (approximate dates, varies by lunar calendar)"
+            }
+        },
+        {
+            "name": "eid-celebration",
+            "rule": {
+                "kind": "range",
+                "from": "04-01",
+                "to": "05-15"
+            },
+            "enabled": false,
+            "region": ["global"],
+            "metadata": {
+                "description": "Eid celebration (approximate dates)"
+            }
+        },
+        {
+            "name": "holi",
+            "rule": {
+                "kind": "range",
+                "from": "02-25",
+                "to": "03-25"
+            },
+            "enabled": false,
+            "region": ["india", "global"],
+            "metadata": {
+                "description": "Holi - Festival of Colors (approximate dates)"
+            }
+        }
+    ],
+    "everyday": [
+        {
+            "name": "everyday",
+            "rule": {
+                "kind": "always"
+            },
+            "metadata": {
+                "description": "Default fallback theme"
+            }
+        }
+    ]
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@akatan/date-to-festive",
+  "version": "1.0.6",
+  "description": "A standalone, reusable module for resolving themes based on dates",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "keywords": [
+    "theme",
+    "date",
+    "resolver",
+    "seasonal",
+    "holidays",
+    "cultural"
+  ],
+  "author": "AkatanHQ",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/AkatanHQ/date-to-festive.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AkatanHQ/date-to-festive/issues"
+  },
+  "homepage": "https://github.com/AkatanHQ/date-to-festive#readme",
+  "devDependencies": {
+    "rimraf": "^6.1.3",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}