@20syldev/api 4.6.0 → 4.8.0

package/src/modules/v4/password.ts

@@ -0,0 +1,379 @@
+import { randomInt } from 'crypto';
+
+import { MAX_PASSWORD_COUNT, MAX_PASSWORD_LENGTH, MIN_PASSWORD_LENGTH } from '../../constants.js';
+
+const UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const LOWER = 'abcdefghijklmnopqrstuvwxyz';
+const DIGITS = '0123456789';
+const SYMBOLS = '!@#$%^&*()-_=+[]{}|;:,.<>?';
+
+const WORDLIST = [
+    'apple',
+    'brave',
+    'chair',
+    'dance',
+    'eagle',
+    'fancy',
+    'grace',
+    'house',
+    'ivory',
+    'joker',
+    'kneel',
+    'lemon',
+    'maple',
+    'noble',
+    'ocean',
+    'piano',
+    'queen',
+    'river',
+    'stone',
+    'tiger',
+    'ultra',
+    'vivid',
+    'waste',
+    'xenon',
+    'yacht',
+    'zebra',
+    'amber',
+    'blaze',
+    'coral',
+    'drift',
+    'ember',
+    'flora',
+    'globe',
+    'haven',
+    'input',
+    'jumpy',
+    'karma',
+    'lunar',
+    'magic',
+    'night',
+    'optic',
+    'proxy',
+    'quirk',
+    'radar',
+    'solar',
+    'trace',
+    'umbra',
+    'vapor',
+    'witch',
+    'xylem',
+    'yield',
+    'zippy',
+    'alpha',
+    'brisk',
+    'crane',
+    'depth',
+    'event',
+    'frost',
+    'grime',
+    'harsh',
+    'index',
+    'joint',
+    'knack',
+    'level',
+    'minus',
+    'nerve',
+    'onset',
+    'phase',
+    'quest',
+    'ratio',
+    'scope',
+    'trend',
+    'union',
+    'valve',
+    'weary',
+    'young',
+    'blunt',
+    'clean',
+    'drive',
+    'earth',
+    'fiber',
+    'grain',
+    'grind',
+    'horse',
+    'ideal',
+    'issue',
+    'judge',
+    'juice',
+    'knave',
+    'large',
+    'laser',
+    'light',
+    'limit',
+    'media',
+    'merit',
+    'metal',
+    'model',
+    'money',
+    'month',
+    'motor',
+    'mount',
+    'music',
+    'nerve',
+    'noise',
+    'north',
+    'noted',
+    'novel',
+    'nurse',
+    'oasis',
+    'offer',
+    'olive',
+    'omega',
+    'other',
+    'outer',
+    'owner',
+    'oxide',
+    'ozone',
+    'paint',
+    'panel',
+    'paper',
+    'patch',
+    'pause',
+    'peace',
+    'pearl',
+    'pedal',
+    'plain',
+    'plank',
+    'plant',
+    'plate',
+    'plaza',
+    'pluck',
+    'plumb',
+    'plume',
+    'plunge',
+    'point',
+    'polar',
+    'power',
+    'press',
+    'pride',
+    'prime',
+    'print',
+    'prism',
+    'prize',
+    'probe',
+    'prone',
+    'proof',
+    'prose',
+    'proud',
+    'prove',
+    'prowl',
+    'pulse',
+    'punch',
+    'pupil',
+    'purge',
+    'swift',
+    'sword',
+    'table',
+    'taint',
+    'tally',
+    'taste',
+    'teach',
+    'teeth',
+    'tempo',
+    'tense',
+    'tenth',
+    'terms',
+    'terra',
+    'thick',
+    'thing',
+    'think',
+    'thorn',
+    'three',
+    'throw',
+    'thumb',
+    'tidal',
+    'tight',
+    'tilde',
+    'timer',
+    'title',
+    'token',
+    'torch',
+    'total',
+    'touch',
+    'tough',
+    'tower',
+    'track',
+    'trade',
+    'trail',
+    'train',
+    'trait',
+    'tramp',
+    'tread',
+    'treat',
+    'trees',
+    'trial',
+    'tribe',
+    'trick',
+    'tried',
+    'troop',
+    'trove',
+    'truce',
+    'truck',
+    'truly',
+    'trunk',
+    'truth',
+    'tulip',
+    'tumor',
+    'tuner',
+    'tunic',
+    'tweak',
+    'twice',
+    'twirl',
+    'twist',
+    'typed',
+    'under',
+    'unify',
+    'unite',
+    'unity',
+    'until',
+    'upper',
+    'upset',
+    'urban',
+    'usage',
+    'valid',
+    'value',
+    'visor',
+    'vital',
+    'vivid',
+    'vocab',
+    'vocal',
+    'voice',
+    'voter',
+    'vault',
+    'venue',
+    'verse',
+    'watch',
+    'water',
+    'weave',
+    'wedge',
+    'weird',
+    'wheel',
+    'where',
+    'which',
+    'while',
+    'white',
+    'whole',
+    'wider',
+    'windy',
+    'wired',
+    'world',
+    'worse',
+    'worth',
+    'would',
+    'wound',
+    'write',
+    'wrong',
+    'wrote',
+    'years',
+    'yield',
+    'yours',
+];
+
+export interface PasswordResult {
+    passwords: string[];
+    type: string;
+    length: number;
+    strength: string;
+    entropy: number;
+}
+
+function computeStrength(entropy: number): string {
+    if (entropy < 40) return 'weak';
+    if (entropy < 60) return 'moderate';
+    if (entropy < 80) return 'strong';
+    return 'very_strong';
+}
+
+function generateRandom(length: number, charset: string): string {
+    return Array.from({ length }, () => charset[randomInt(charset.length)]).join('');
+}
+
+function generatePassphrase(wordCount: number, separator: string): string {
+    return Array.from({ length: wordCount }, () => WORDLIST[randomInt(WORDLIST.length)]).join(separator);
+}
+
+/**
+ * Generates one or more passwords using random characters or passphrase mode.
+ *
+ * @param type - Generation mode: "random" or "passphrase"
+ * @param length - Password length for random mode (8–128), or word count for passphrase mode (3–10)
+ * @param options - Character set options: uppercase, lowercase, digits, symbols, exclude, count, separator
+ * @returns Generated passwords with type, length, strength and entropy
+ * @throws Error if no charset is active, length is out of range, or count exceeds the maximum
+ */
+export default function password(
+    type: string = 'random',
+    length: number = 16,
+    options: {
+        uppercase?: boolean;
+        lowercase?: boolean;
+        digits?: boolean;
+        symbols?: boolean;
+        exclude?: string;
+        count?: number;
+        separator?: string;
+    } = {},
+): PasswordResult {
+    const {
+        uppercase = true,
+        lowercase = true,
+        digits = true,
+        symbols = false,
+        exclude = '',
+        count = 1,
+        separator = '-',
+    } = options;
+
+    if (count < 1 || count > MAX_PASSWORD_COUNT) {
+        throw new Error(`Count must be between 1 and ${MAX_PASSWORD_COUNT}`);
+    }
+
+    if (type === 'passphrase') {
+        const wordCount = Math.max(3, Math.min(10, length));
+        const entropy = Math.log2(Math.pow(WORDLIST.length, wordCount));
+        const passwords = Array.from({ length: count }, () => generatePassphrase(wordCount, separator));
+        return {
+            passwords,
+            type: 'passphrase',
+            length: wordCount,
+            strength: computeStrength(entropy),
+            entropy: Math.round(entropy * 10) / 10,
+        };
+    }
+
+    if (type !== 'random') {
+        throw new Error('Type must be "random" or "passphrase"');
+    }
+
+    if (isNaN(length) || length < MIN_PASSWORD_LENGTH || length > MAX_PASSWORD_LENGTH) {
+        throw new Error(`Length must be between ${MIN_PASSWORD_LENGTH} and ${MAX_PASSWORD_LENGTH}`);
+    }
+
+    let charset = '';
+    if (uppercase) charset += UPPER;
+    if (lowercase) charset += LOWER;
+    if (digits) charset += DIGITS;
+    if (symbols) charset += SYMBOLS;
+
+    if (exclude) {
+        for (const char of exclude) {
+            charset = charset.replaceAll(char, '');
+        }
+    }
+
+    if (charset.length === 0) {
+        throw new Error('At least one character set must be enabled');
+    }
+
+    const entropy = Math.log2(Math.pow(charset.length, length));
+    const passwords = Array.from({ length: count }, () => generateRandom(length, charset));
+
+    return {
+        passwords,
+        type: 'random',
+        length,
+        strength: computeStrength(entropy),
+        entropy: Math.round(entropy * 10) / 10,
+    };
+}

package/src/modules/v4/personal.ts

@@ -1,4 +1,5 @@
 import { random, randomNumber } from '../../utils/helpers.js';
+import addressFn from './address.js';
 
 interface Person {
     name: string;
@@ -47,21 +48,6 @@ export default function personal(): Record<string, unknown> {
 
     const jobs = ['Writer', 'Artist', 'Musician', 'Explorer', 'Scientist', 'Engineer', 'Athlete', 'Doctor'];
     const hobbies = ['Reading', 'Traveling', 'Gaming', 'Cooking', 'Fitness', 'Music', 'Photography', 'Writing'];
-    const cities = [
-        'New York',
-        'Paris',
-        'London',
-        'Madrid',
-        'Berlin',
-        'Rome',
-        'Tokyo',
-        'Los Angeles',
-        'Sydney',
-        'São Paulo',
-        'Toronto',
-    ];
-    const streets = ['Main St', '2nd Ave', 'Broadway', 'Park Lane', 'Elm St', 'Sunset Blvd', 'Maple St', 'Highland Rd'];
-
     const card = Array.from({ length: 4 }, () => randomNumber(1000, 9999)).join(' ');
     const cvc = randomNumber(100, 999);
     const expiration = `${String(randomNumber(1, 12)).padStart(2, '0')}/${(new Date().getFullYear() + randomNumber(0, 3)).toString().slice(-2)}`;
@@ -69,6 +55,8 @@ export default function personal(): Record<string, unknown> {
     const person = random(people);
     const social = person.social;
     const country = person.country;
+    const countryCodes: Record<string, string> = { US: 'us', FR: 'fr', UK: 'uk', ES: 'es', DE: 'de' };
+    const addrCountry = countryCodes[country] ?? 'us';
     const countryInfo = countries[country]!;
     const phone = countryInfo.tel;
     const lang = countryInfo.lang;
@@ -129,7 +117,7 @@ export default function personal(): Record<string, unknown> {
         card,
         cvc,
         expiration,
-        address: `${randomNumber(1, 9999)} ${random(streets)}, ${random(cities)}`,
+        address: addressFn(addrCountry).addresses[0]!,
         birthday,
         civil_status: civilStatus,
         children,

package/src/modules/v4/qrcode.ts

@@ -1,6 +1,7 @@
 import { createCanvas, loadImage } from 'canvas';
 import { toBuffer, toCanvas as qrToCanvas, toDataURL } from 'qrcode';
 
+import { MAX_QRCODE_LOGO_BYTES } from '../../constants.js';
 import { normalizeColor } from '../../utils/colors.js';
 
 export interface QRCodeOptions {
@@ -24,7 +25,6 @@ export interface QRCodeResult {
 
 const CORRECTIONS = new Set(['L', 'M', 'Q', 'H']);
 const FORMATS = new Set(['png', 'base64']);
-const MAX_LOGO_BYTES = 2 * 1024 * 1024;
 
 function clamp(value: number | undefined, name: string, def: number, min: number, max: number): number {
     if (value === undefined) return def;
@@ -44,7 +44,7 @@ async function fetchIcon(url: string): Promise<Buffer> {
     if (!contentType.startsWith('image/')) throw new Error('Icon URL must point to an image');
 
     const buffer = Buffer.from(await response.arrayBuffer());
-    if (buffer.length > MAX_LOGO_BYTES) throw new Error('Icon must be under 2MB');
+    if (buffer.length > MAX_QRCODE_LOGO_BYTES) throw new Error('Icon must be under 2MB');
 
     return buffer;
 }

package/src/modules/v4/regex.ts

@@ -0,0 +1,67 @@
+import { MAX_PATTERN_LENGTH, MAX_REGEX_MATCHES, MAX_STRING_LENGTH } from '../../constants.js';
+
+const VALID_FLAGS = new Set(['g', 'i', 'm', 's', 'u']);
+
+export interface RegexMatch {
+    match: string;
+    index: number;
+    groups: string[];
+    namedGroups: Record<string, string>;
+}
+
+export interface RegexResult {
+    valid: boolean;
+    pattern: string;
+    flags: string;
+    matches: RegexMatch[];
+    count: number;
+}
+
+/**
+ * Tests a regular expression pattern against a text and returns structured match results.
+ *
+ * @param pattern - The regex pattern to test (max 200 characters)
+ * @param text - The text to match against (max 1000 characters)
+ * @param flags - Optional regex flags; only g, i, m, s, u are accepted (g is always forced)
+ * @returns Match results with groups and named groups, or { valid: false } if the pattern is invalid
+ * @throws Error if pattern or text is missing or exceeds the maximum length
+ */
+export default function regex(pattern: string, text: string, flags: string = 'g'): RegexResult {
+    if (!pattern) {
+        throw new Error('Please provide a pattern (?pattern={regex})');
+    }
+    if (!text) {
+        throw new Error('Please provide a text (&text={string})');
+    }
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        throw new Error(`Pattern must be under ${MAX_PATTERN_LENGTH} characters`);
+    }
+    if (text.length > MAX_STRING_LENGTH) {
+        throw new Error(`Text must be under ${MAX_STRING_LENGTH} characters`);
+    }
+
+    const cleanedFlags = [...new Set(['g', ...flags.split('').filter((f) => VALID_FLAGS.has(f))])].join('');
+
+    let re: RegExp;
+    try {
+        re = new RegExp(pattern, cleanedFlags);
+    } catch {
+        return { valid: false, pattern, flags: cleanedFlags, matches: [], count: 0 };
+    }
+
+    const matches: RegexMatch[] = [];
+    let result: RegExpExecArray | null;
+
+    while ((result = re.exec(text)) !== null && matches.length < MAX_REGEX_MATCHES) {
+        matches.push({
+            match: result[0],
+            index: result.index,
+            groups: result.slice(1).map((g) => g ?? ''),
+            namedGroups: result.groups ? { ...result.groups } : {},
+        });
+        // Prevent infinite loop on zero-length matches
+        if (result[0].length === 0) re.lastIndex++;
+    }
+
+    return { valid: true, pattern, flags: cleanedFlags, matches, count: matches.length };
+}

package/src/modules/v4/time.ts

@@ -1,4 +1,6 @@
-const validFormats = [
+import { MAX_COUNTDOWN_YEARS } from '../../constants.js';
+
+const VALID_FORMATS = [
     'iso',
     'utc',
     'timestamp',
@@ -19,21 +21,23 @@ const validFormats = [
     'timezoneOffset',
 ] as const;
 
-const validTimezones = ['UTC', 'America/New_York', 'Europe/Paris', 'Asia/Tokyo', 'Australia/Sydney'] as const;
+export const VALID_TIMEZONES = ['UTC', 'America/New_York', 'Europe/Paris', 'Asia/Tokyo', 'Australia/Sydney'] as const;
 
-type TimeFormat = (typeof validFormats)[number];
-type Timezone = (typeof validTimezones)[number];
+type TimeFormat = (typeof VALID_FORMATS)[number];
+type Timezone = (typeof VALID_TIMEZONES)[number];
 
 /**
- * Returns the current or a random date/time in various formats and timezones.
+ * Returns the current or a random date/time in various formats and timezones,
+ * or computes a countdown/elapsed time to/from a target date.
  *
- * @param type - "live" for the current time or "random" for a random date within a range
+ * @param type - "live" for the current time, "random" for a random date, or "countdown" for a time diff
  * @param start - Optional start date for random mode (YYYY-MM-DD)
  * @param end - Optional end date for random mode (YYYY-MM-DD)
  * @param format - Optional specific format to return (e.g. "iso", "timestamp", "year")
  * @param timezone - Optional timezone (e.g. "UTC", "Europe/Paris")
- * @returns Object containing all time formats, or a single format if specified
- * @throws Error if type, format, or timezone is invalid
+ * @param target - Required for countdown mode: target date in ISO 8601 or YYYY-MM-DD format
+ * @returns Object containing all time formats, a single format, or a countdown result
+ * @throws Error if type, format, timezone, or target is invalid
  */
 export default function time(
     type: string = 'live',
@@ -41,9 +45,55 @@ export default function time(
     end?: string,
     format?: string,
     timezone?: string,
+    target?: string,
 ): Record<string, unknown> {
-    if (type !== 'live' && type !== 'random') {
-        throw new Error('Please provide a valid type (live or random)');
+    if (type !== 'live' && type !== 'random' && type !== 'countdown') {
+        throw new Error('Please provide a valid type (live, random or countdown)');
+    }
+
+    if (timezone && !VALID_TIMEZONES.includes(timezone as Timezone)) {
+        throw new Error(`Please provide a valid timezone. Options: ${VALID_TIMEZONES.join(', ')}`);
+    }
+
+    if (type === 'countdown') {
+        if (!target) {
+            throw new Error('Please provide a target date (?target=YYYY-MM-DD)');
+        }
+
+        const targetDate = new Date(target);
+        if (isNaN(targetDate.getTime())) {
+            throw new Error('Please provide a valid target date (ISO 8601 or YYYY-MM-DD)');
+        }
+
+        const now = new Date();
+        const maxMs = MAX_COUNTDOWN_YEARS * 365.25 * 24 * 3600 * 1000;
+
+        if (Math.abs(targetDate.getTime() - now.getTime()) > maxMs) {
+            throw new Error(`Target date must be within ${MAX_COUNTDOWN_YEARS} years from now`);
+        }
+
+        const direction: 'future' | 'past' = targetDate > now ? 'future' : 'past';
+        const diffMs = Math.abs(targetDate.getTime() - now.getTime());
+        const total_seconds = Math.floor(diffMs / 1000);
+
+        const days = Math.floor(total_seconds / 86400);
+        const hours = Math.floor((total_seconds % 86400) / 3600);
+        const minutes = Math.floor((total_seconds % 3600) / 60);
+        const seconds = total_seconds % 60;
+
+        const parts: string[] = [];
+        if (days > 0) parts.push(`${days} day${days !== 1 ? 's' : ''}`);
+        if (hours > 0) parts.push(`${hours} hour${hours !== 1 ? 's' : ''}`);
+        if (minutes > 0) parts.push(`${minutes} minute${minutes !== 1 ? 's' : ''}`);
+        if (seconds > 0) parts.push(`${seconds} second${seconds !== 1 ? 's' : ''}`);
+
+        return {
+            target: targetDate.toISOString(),
+            now: now.toISOString(),
+            direction,
+            remaining: { total_seconds, days, hours, minutes, seconds },
+            human: parts.length > 0 ? parts.join(', ') : '0 seconds',
+        };
     }
 
     if (start && !Date.parse(start)) {
@@ -54,12 +104,8 @@ export default function time(
         throw new Error('Please provide a valid end date (YYYY-MM-DD)');
     }
 
-    if (format && !validFormats.includes(format as TimeFormat)) {
-        throw new Error(`Please provide a valid format. Options: ${validFormats.join(', ')}`);
-    }
-
-    if (timezone && !validTimezones.includes(timezone as Timezone)) {
-        throw new Error(`Please provide a valid timezone. Options: ${validTimezones.join(', ')}`);
+    if (format && !VALID_FORMATS.includes(format as TimeFormat)) {
+        throw new Error(`Please provide a valid format. Options: ${VALID_FORMATS.join(', ')}`);
     }
 
     const getTimeFormats = (date: Date, tz: string): Record<string, unknown> => {
@@ -89,7 +135,7 @@ export default function time(
         const startDate = start ? new Date(start).getTime() : new Date('1900-01-01').getTime();
         const endDate = end ? new Date(end).getTime() : new Date('2100-12-31').getTime();
         const randomDate = new Date(startDate + Math.random() * (endDate - startDate));
-        const tz = timezone || validTimezones[Math.floor(Math.random() * validTimezones.length)]!;
+        const tz = timezone || VALID_TIMEZONES[Math.floor(Math.random() * VALID_TIMEZONES.length)]!;
         const formats = getTimeFormats(randomDate, tz);
 
         return format ? { date: formats[format] } : formats;

package/src/modules/v4/token.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from 'crypto';
+import { randomBytes, randomInt } from 'crypto';
 import { v4 } from 'uuid';
 
 import { MAX_TOKEN_LENGTH, MIN_TOKEN_LENGTH } from '../../constants.js';
@@ -20,11 +20,8 @@ export default function token(len: number, type: string = 'alphanum'): string {
         throw new Error('Length cannot exceed 4096');
     }
 
-    const genToken = (chars: string, length: number): string => {
-        return Array.from({ length }, () => {
-            return chars[Math.floor(Math.random() * chars.length)];
-        }).join('');
-    };
+    const genToken = (chars: string, length: number): string =>
+        Array.from({ length }, () => chars[randomInt(chars.length)]).join('');
 
     const tokenTypes: Record<string, () => string> = {
         alpha: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', len),
@@ -40,7 +37,11 @@ export default function token(len: number, type: string = 'alphanum'): string {
         num: () => genToken('0123456789', len),
         punct: () => genToken('!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~', len),
         urlsafe: () => genToken('abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_', len),
-        uuid: () => v4().replace(/-/g, '').slice(0, len),
+        uuid: () => {
+            let result = '';
+            while (result.length < len) result += v4().replace(/-/g, '');
+            return result.slice(0, len);
+        },
     };
 
     const lowerType = type.toLowerCase();

package/src/modules/v4.ts

@@ -1,9 +1,11 @@
+export { default as address } from './v4/address.js';
 export { default as agent } from './v4/agent.js';
 export * as algorithms from './v4/algorithms.js';
 export { default as captcha } from './v4/captcha.js';
 export { default as chat } from './v4/chat.js';
 export { default as color } from './v4/color.js';
 export { default as convert } from './v4/convert.js';
+export { default as cron } from './v4/cron.js';
 export { default as dice } from './v4/dice.js';
 export { default as domain } from './v4/domain.js';
 export * as encode from './v4/encode.js';
@@ -13,9 +15,11 @@ export { default as hyperplanning } from './v4/hyperplanning.js';
 export { default as ip } from './v4/ip.js';
 export { default as levenshtein } from './v4/levenshtein.js';
 export { default as palette } from './v4/palette.js';
+export { default as password } from './v4/password.js';
 export { default as personal } from './v4/personal.js';
 export { default as placeholder } from './v4/placeholder.js';
 export { default as qrcode } from './v4/qrcode.js';
+export { default as regex } from './v4/regex.js';
 export { default as statistics } from './v4/statistics.js';
 export * as text from './v4/text.js';
 export { default as tic_tac_toe } from './v4/tic_tac_toe.js';