@20syldev/api 4.6.0 → 4.8.0

package/src/modules/v4/address.ts

@@ -0,0 +1,412 @@
+import { MAX_ADDRESS_COUNT } from '../../constants.js';
+import { random, randomNumber } from '../../utils/helpers.js';
+
+interface CountryData {
+    name: string;
+    streetTypes: string[];
+    streetNames: string[];
+    cities: string[];
+    regions: string[];
+    zipFormat: () => string;
+}
+
+function randomChar(chars: string): string {
+    return chars[Math.floor(Math.random() * chars.length)]!;
+}
+
+const ALPHA = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+const countries: Record<string, CountryData> = {
+    fr: {
+        name: 'France',
+        streetTypes: ['Rue', 'Avenue', 'Boulevard', 'Allée', 'Impasse', 'Place', 'Chemin', 'Route', 'Voie', 'Passage'],
+        streetNames: [
+            'de la Paix',
+            'Victor Hugo',
+            'Jean Jaurès',
+            'de la République',
+            'du Général de Gaulle',
+            'de la Liberté',
+            'des Fleurs',
+            'du Moulin',
+            'de la Forêt',
+            'des Lilas',
+            'du Château',
+            'de la Mairie',
+            'de la Gare',
+            'du Commerce',
+            'de la Fontaine',
+            'de la Croix',
+            'des Vignes',
+            'du Marché',
+            "de l'Église",
+            'des Acacias',
+        ],
+        cities: [
+            'Paris',
+            'Lyon',
+            'Marseille',
+            'Toulouse',
+            'Nice',
+            'Nantes',
+            'Strasbourg',
+            'Montpellier',
+            'Bordeaux',
+            'Lille',
+            'Rennes',
+            'Reims',
+            'Le Havre',
+            'Saint-Étienne',
+            'Toulon',
+            'Grenoble',
+            'Dijon',
+            'Angers',
+            'Nîmes',
+            'Villeurbanne',
+        ],
+        regions: [
+            'Île-de-France',
+            'Auvergne-Rhône-Alpes',
+            "Provence-Alpes-Côte d'Azur",
+            'Occitanie',
+            'Hauts-de-France',
+            'Nouvelle-Aquitaine',
+            'Grand Est',
+            'Pays de la Loire',
+            'Bretagne',
+            'Normandie',
+            'Bourgogne-Franche-Comté',
+            'Centre-Val de Loire',
+        ],
+        zipFormat: () => String(randomNumber(10000, 99999)).padStart(5, '0'),
+    },
+    us: {
+        name: 'United States',
+        streetTypes: ['Street', 'Avenue', 'Boulevard', 'Drive', 'Road', 'Lane', 'Court', 'Way', 'Place', 'Circle'],
+        streetNames: [
+            'Main',
+            'Oak',
+            'Maple',
+            'Cedar',
+            'Pine',
+            'Elm',
+            'Washington',
+            'Lincoln',
+            'Park',
+            'Lake',
+            'Hill',
+            'River',
+            'Sunset',
+            'Forest',
+            'Meadow',
+            'Valley',
+            'Highland',
+            'Willow',
+            'Spring',
+            'Church',
+        ],
+        cities: [
+            'New York',
+            'Los Angeles',
+            'Chicago',
+            'Houston',
+            'Phoenix',
+            'Philadelphia',
+            'San Antonio',
+            'San Diego',
+            'Dallas',
+            'San Jose',
+            'Austin',
+            'Jacksonville',
+            'Fort Worth',
+            'Columbus',
+            'Charlotte',
+            'Indianapolis',
+            'San Francisco',
+            'Seattle',
+            'Denver',
+            'Nashville',
+        ],
+        regions: [
+            'California',
+            'Texas',
+            'Florida',
+            'New York',
+            'Pennsylvania',
+            'Illinois',
+            'Ohio',
+            'Georgia',
+            'North Carolina',
+            'Michigan',
+            'New Jersey',
+            'Virginia',
+            'Washington',
+            'Arizona',
+            'Massachusetts',
+            'Tennessee',
+            'Indiana',
+            'Colorado',
+            'Missouri',
+            'Maryland',
+        ],
+        zipFormat: () => String(randomNumber(10000, 99999)).padStart(5, '0'),
+    },
+    uk: {
+        name: 'United Kingdom',
+        streetTypes: ['Street', 'Road', 'Avenue', 'Lane', 'Close', 'Drive', 'Way', 'Court', 'Grove', 'Place'],
+        streetNames: [
+            'High',
+            'Church',
+            'Station',
+            'Park',
+            'Manor',
+            'Mill',
+            'Victoria',
+            'King',
+            'Queen',
+            'Albert',
+            'George',
+            'York',
+            'Oxford',
+            'Cambridge',
+            'Windsor',
+            'Richmond',
+            'Elm',
+            'Oak',
+            'Ash',
+            'Rose',
+        ],
+        cities: [
+            'London',
+            'Birmingham',
+            'Manchester',
+            'Glasgow',
+            'Liverpool',
+            'Bristol',
+            'Sheffield',
+            'Leeds',
+            'Edinburgh',
+            'Leicester',
+            'Coventry',
+            'Bradford',
+            'Cardiff',
+            'Belfast',
+            'Nottingham',
+            'Kingston upon Hull',
+            'Newcastle',
+            'Stoke-on-Trent',
+            'Southampton',
+            'Derby',
+        ],
+        regions: [
+            'England',
+            'Scotland',
+            'Wales',
+            'Northern Ireland',
+            'Greater London',
+            'South East',
+            'North West',
+            'East of England',
+            'West Midlands',
+            'South West',
+            'Yorkshire',
+            'East Midlands',
+            'North East',
+        ],
+        zipFormat: () =>
+            `${randomChar(ALPHA)}${randomChar(ALPHA)}${randomNumber(1, 9)} ${randomNumber(1, 9)}${randomChar(ALPHA)}${randomChar(ALPHA)}`,
+    },
+    de: {
+        name: 'Germany',
+        streetTypes: ['Straße', 'Allee', 'Weg', 'Platz', 'Gasse', 'Ring', 'Damm', 'Ufer', 'Stieg', 'Pfad'],
+        streetNames: [
+            'Haupt',
+            'Bahnhof',
+            'Schul',
+            'Kirch',
+            'Garten',
+            'Berg',
+            'Wald',
+            'Wiesen',
+            'Tal',
+            'See',
+            'Bismarck',
+            'Goethe',
+            'Schiller',
+            'Kant',
+            'Hegel',
+            'Mozart',
+            'Beethoven',
+            'Bach',
+            'Brahms',
+            'Handel',
+        ],
+        cities: [
+            'Berlin',
+            'Hamburg',
+            'Munich',
+            'Cologne',
+            'Frankfurt',
+            'Stuttgart',
+            'Düsseldorf',
+            'Leipzig',
+            'Dortmund',
+            'Essen',
+            'Bremen',
+            'Dresden',
+            'Hanover',
+            'Nuremberg',
+            'Duisburg',
+            'Bochum',
+            'Wuppertal',
+            'Bielefeld',
+            'Bonn',
+            'Münster',
+        ],
+        regions: [
+            'Bayern',
+            'Nordrhein-Westfalen',
+            'Baden-Württemberg',
+            'Niedersachsen',
+            'Hessen',
+            'Sachsen',
+            'Rheinland-Pfalz',
+            'Berlin',
+            'Schleswig-Holstein',
+            'Brandenburg',
+            'Sachsen-Anhalt',
+            'Thüringen',
+            'Hamburg',
+            'Mecklenburg-Vorpommern',
+            'Bremen',
+            'Saarland',
+        ],
+        zipFormat: () => String(randomNumber(10000, 99999)).padStart(5, '0'),
+    },
+    es: {
+        name: 'Spain',
+        streetTypes: [
+            'Calle',
+            'Avenida',
+            'Plaza',
+            'Paseo',
+            'Rambla',
+            'Carretera',
+            'Camino',
+            'Vía',
+            'Travesía',
+            'Callejón',
+        ],
+        streetNames: [
+            'Mayor',
+            'Real',
+            'Nueva',
+            'del Sol',
+            'de la Luna',
+            'del Rey',
+            'de la Reina',
+            'del Mar',
+            'de la Paz',
+            'de la Victoria',
+            'Cervantes',
+            'Goya',
+            'Velázquez',
+            'Picasso',
+            'Dalí',
+            'de España',
+            'de Colón',
+            'de la Constitución',
+            'del Prado',
+            'de las Flores',
+        ],
+        cities: [
+            'Madrid',
+            'Barcelona',
+            'Valencia',
+            'Seville',
+            'Zaragoza',
+            'Málaga',
+            'Murcia',
+            'Palma',
+            'Las Palmas',
+            'Bilbao',
+            'Alicante',
+            'Córdoba',
+            'Valladolid',
+            'Vigo',
+            'Gijón',
+            'Hospitalet',
+            'A Coruña',
+            'Granada',
+            'Vitoria',
+            'Elche',
+        ],
+        regions: [
+            'Andalucía',
+            'Cataluña',
+            'Madrid',
+            'Comunidad Valenciana',
+            'Galicia',
+            'Castilla y León',
+            'País Vasco',
+            'Castilla-La Mancha',
+            'Canarias',
+            'Murcia',
+            'Aragón',
+            'Extremadura',
+            'Asturias',
+            'Navarra',
+            'Cantabria',
+            'La Rioja',
+            'Baleares',
+        ],
+        zipFormat: () => String(randomNumber(10000, 52999)).padStart(5, '0'),
+    },
+};
+
+const COUNTRY_KEYS = Object.keys(countries);
+
+export interface Address {
+    street: string;
+    city: string;
+    zip: string;
+    state: string;
+    country: string;
+    countryCode: string;
+}
+
+export interface AddressResult {
+    addresses: Address[];
+}
+
+/**
+ * Generates one or more fictional postal addresses for a given country.
+ *
+ * @param countryCode - Country code: "fr", "us", "uk", "de", or "es" (random if omitted)
+ * @param count - Number of addresses to generate (1–10)
+ * @returns Array of addresses with street, city, zip, state, country, and countryCode
+ * @throws Error if the country code is invalid or count is out of range
+ */
+export default function address(countryCode?: string, count: number = 1): AddressResult {
+    if (count < 1 || count > MAX_ADDRESS_COUNT) {
+        throw new Error(`Count must be between 1 and ${MAX_ADDRESS_COUNT}`);
+    }
+
+    const code = (countryCode ?? random(COUNTRY_KEYS)).toLowerCase();
+    if (!countries[code]) {
+        throw new Error(`Unknown country code "${code}". Supported: ${COUNTRY_KEYS.join(', ')}`);
+    }
+
+    const data = countries[code]!;
+
+    const addresses: Address[] = Array.from({ length: count }, () => ({
+        street: `${randomNumber(1, 200)} ${random(data.streetTypes)} ${random(data.streetNames)}`,
+        city: random(data.cities),
+        zip: data.zipFormat(),
+        state: random(data.regions),
+        country: data.name,
+        countryCode: code.toUpperCase(),
+    }));
+
+    return { addresses };
+}

package/src/modules/v4/cron.ts

@@ -0,0 +1,221 @@
+import { MAX_CRON_ITERATIONS, MAX_CRON_RESULTS } from '../../constants.js';
+import { VALID_TIMEZONES } from './time.js';
+
+type Timezone = (typeof VALID_TIMEZONES)[number];
+
+const FIELD_RANGES = [
+    { min: 0, max: 59 }, // minute
+    { min: 0, max: 23 }, // hour
+    { min: 1, max: 31 }, // day of month
+    { min: 1, max: 12 }, // month
+    { min: 0, max: 7 }, // day of week (0 and 7 = Sunday)
+] as const;
+
+const DOW_NAMES: Record<string, number> = {
+    Sunday: 0,
+    Monday: 1,
+    Tuesday: 2,
+    Wednesday: 3,
+    Thursday: 4,
+    Friday: 5,
+    Saturday: 6,
+};
+
+const DOW_DISPLAY = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+export interface CronResult {
+    expression: string;
+    description: string;
+    next: string[];
+    timezone: string;
+}
+
+function parseField(field: string, range: { min: number; max: number }): Set<number> {
+    const result = new Set<number>();
+
+    for (const part of field.split(',')) {
+        if (part === '*') {
+            for (let i = range.min; i <= range.max; i++) result.add(i);
+        } else if (part.startsWith('*/')) {
+            const step = parseInt(part.slice(2), 10);
+            if (isNaN(step) || step < 1) throw new Error(`Invalid step in "${part}"`);
+            for (let i = range.min; i <= range.max; i += step) result.add(i);
+        } else if (part.includes('-')) {
+            const [s, e] = part.split('-');
+            const start = parseInt(s!, 10);
+            const end = parseInt(e!, 10);
+            if (isNaN(start) || isNaN(end) || start < range.min || end > range.max || start > end) {
+                throw new Error(`Invalid range "${part}" (valid: ${range.min}-${range.max})`);
+            }
+            for (let i = start; i <= end; i++) result.add(i);
+        } else {
+            const val = parseInt(part, 10);
+            if (isNaN(val) || val < range.min || val > range.max) {
+                throw new Error(`Invalid value "${part}" (valid: ${range.min}-${range.max})`);
+            }
+            result.add(val);
+        }
+    }
+
+    return result;
+}
+
+function getComponents(
+    date: Date,
+    formatter: Intl.DateTimeFormat,
+): { minute: number; hour: number; dom: number; month: number; dow: number } {
+    const parts = Object.fromEntries(formatter.formatToParts(date).map((p) => [p.type, p.value]));
+    return {
+        minute: parseInt(parts.minute!, 10),
+        hour: parseInt(parts.hour!, 10) % 24,
+        dom: parseInt(parts.day!, 10),
+        month: parseInt(parts.month!, 10),
+        dow: DOW_NAMES[parts.weekday!] ?? 0,
+    };
+}
+
+function pad(n: number): string {
+    return String(n).padStart(2, '0');
+}
+
+function formatDow(field: string): string {
+    if (field === '1-5') return 'Monday through Friday';
+    if (field === '0' || field === '7') return 'Sunday';
+    if (field === '6') return 'Saturday';
+    const n = parseInt(field, 10);
+    if (!isNaN(n)) return DOW_DISPLAY[n % 7] ?? field;
+    return field;
+}
+
+function describe(fields: string[]): string {
+    const [mF, hF, domF, monthF, dowF] = fields as [string, string, string, string, string];
+
+    const isAll = (f: string) => f === '*';
+    const isFixed = (f: string) => /^\d+$/.test(f);
+    const isStep = (f: string) => /^\*\/\d+$/.test(f);
+
+    // Every minute
+    if (isAll(mF) && isAll(hF) && isAll(domF) && isAll(monthF) && isAll(dowF)) {
+        return 'Every minute';
+    }
+
+    // Every N minutes (whole day, every day)
+    if (isStep(mF) && isAll(hF) && isAll(domF) && isAll(monthF) && isAll(dowF)) {
+        const n = mF.slice(2);
+        return `Every ${n} minute${n === '1' ? '' : 's'}`;
+    }
+
+    // Every hour at minute 0
+    if (mF === '0' && isAll(hF) && isAll(domF) && isAll(monthF) && isAll(dowF)) {
+        return 'Every hour';
+    }
+
+    // Every N hours at minute 0
+    if (mF === '0' && isStep(hF) && isAll(domF) && isAll(monthF) && isAll(dowF)) {
+        const n = hF.slice(2);
+        return `Every ${n} hour${n === '1' ? '' : 's'}`;
+    }
+
+    // At specific time daily
+    if (isFixed(mF) && isFixed(hF) && isAll(domF) && isAll(monthF) && isAll(dowF)) {
+        return `At ${pad(parseInt(hF))}:${pad(parseInt(mF))} daily`;
+    }
+
+    // At specific time on specific weekday(s)
+    if (isFixed(mF) && isFixed(hF) && isAll(domF) && isAll(monthF) && !isAll(dowF)) {
+        return `At ${pad(parseInt(hF))}:${pad(parseInt(mF))}, ${formatDow(dowF)}`;
+    }
+
+    // At specific time on specific day of month
+    if (isFixed(mF) && isFixed(hF) && isFixed(domF) && isAll(monthF) && isAll(dowF)) {
+        return `At ${pad(parseInt(hF))}:${pad(parseInt(mF))}, on day ${domF} of the month`;
+    }
+
+    // Every N minutes, within hour range, optionally filtered by weekday
+    if (isStep(mF) && !isAll(hF) && isAll(domF) && isAll(monthF)) {
+        const n = mF.slice(2);
+        const parts = [`Every ${n} minute${n === '1' ? '' : 's'}`];
+        if (hF.includes('-')) {
+            const [h1, h2] = hF.split('-');
+            parts.push(`between ${pad(parseInt(h1!))}:00 and ${pad(parseInt(h2!))}:59`);
+        }
+        if (!isAll(dowF)) parts.push(formatDow(dowF));
+        return parts.join(', ');
+    }
+
+    return `At cron schedule: ${fields.join(' ')}`;
+}
+
+/**
+ * Parses a cron expression and returns the next scheduled execution dates.
+ *
+ * @param expr - Cron expression with 5 space-separated fields (minute hour dom month dow)
+ * @param count - Number of next executions to return (1–20, default 5)
+ * @param from - Starting date in ISO 8601 format (defaults to now)
+ * @param timezone - Timezone to evaluate the expression in (default "UTC")
+ * @returns Parsed expression with description and list of next execution timestamps
+ * @throws Error if the expression is invalid, count is out of range, or timezone is unsupported
+ */
+export default function cron(expr: string, count: number = 5, from?: string, timezone: string = 'UTC'): CronResult {
+    if (!expr) throw new Error('Please provide a cron expression (?expr=* * * * *)');
+
+    if (!VALID_TIMEZONES.includes(timezone as Timezone)) {
+        throw new Error(`Please provide a valid timezone. Options: ${VALID_TIMEZONES.join(', ')}`);
+    }
+
+    const fields = expr.trim().split(/\s+/);
+    if (fields.length !== 5) {
+        throw new Error('Cron expression must have exactly 5 fields (minute hour dom month dow)');
+    }
+
+    if (count < 1 || count > MAX_CRON_RESULTS) {
+        throw new Error(`Count must be between 1 and ${MAX_CRON_RESULTS}`);
+    }
+
+    const fromMs = from ? new Date(from).getTime() : Date.now();
+    if (from && isNaN(fromMs)) throw new Error('Please provide a valid from date (ISO 8601)');
+
+    const sets = fields.map((f, i) => parseField(f, FIELD_RANGES[i]!));
+    const [minuteSet, hourSet, domSet, monthSet, dowSet] = sets as [
+        Set<number>,
+        Set<number>,
+        Set<number>,
+        Set<number>,
+        Set<number>,
+    ];
+
+    // Normalize DOW: treat 7 as Sunday (0)
+    if (dowSet.has(7)) {
+        dowSet.add(0);
+        dowSet.delete(7);
+    }
+
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        weekday: 'long',
+        hour12: false,
+    });
+
+    // Always start from the next minute (never include the current minute)
+    let currentMs = (Math.floor(fromMs / 60000) + 1) * 60000;
+
+    const next: string[] = [];
+    let iterations = 0;
+
+    while (next.length < count && iterations < MAX_CRON_ITERATIONS) {
+        const { minute, hour, dom, month, dow } = getComponents(new Date(currentMs), formatter);
+
+        if (minuteSet.has(minute) && hourSet.has(hour) && domSet.has(dom) && monthSet.has(month) && dowSet.has(dow)) {
+            next.push(new Date(currentMs).toISOString());
+        }
+
+        currentMs += 60000;
+        iterations++;
+    }
+
+    return { expression: expr.trim(), description: describe(fields), next, timezone };
+}

package/src/modules/v4/geo.ts

@@ -5,7 +5,8 @@ export interface GeoResult {
     to: { lat: number; lon: number };
 }
 
-const EARTH_RADIUS_KM = 6371;
+import { EARTH_RADIUS_KM } from '../../constants.js';
+
 const CARDINALS = ['N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW'];
 
 function toRad(deg: number): number {