@20syldev/api 4.5.0 → 4.7.0

package/src/modules/v4/ip.ts

@@ -0,0 +1,134 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+export interface IpResult {
+    ip: string;
+    version: 'IPv4' | 'IPv6';
+    type: 'public' | 'private' | 'loopback' | 'link-local' | 'multicast' | 'broadcast';
+    class?: 'A' | 'B' | 'C' | 'D' | 'E';
+    range?: string;
+    binary: string;
+    decimal?: number;
+    reverse: string;
+}
+
+/**
+ * Parses and analyzes an IPv4 address.
+ *
+ * @param raw - The IPv4 address string (e.g. "192.168.1.1")
+ * @returns Detailed information about the address
+ * @throws Error if the address is malformed
+ */
+function parseIPv4(raw: string): IpResult {
+    const parts = raw.split('.');
+    if (parts.length !== 4) throw new Error('Invalid IPv4 address');
+    const octets = parts.map(Number);
+    if (octets.some((o) => isNaN(o) || !Number.isInteger(o) || o < 0 || o > 255))
+        throw new Error('Invalid IPv4 address');
+
+    const [a, b, c, d] = octets as [number, number, number, number];
+
+    let cls: 'A' | 'B' | 'C' | 'D' | 'E';
+    if (a < 128) cls = 'A';
+    else if (a < 192) cls = 'B';
+    else if (a < 224) cls = 'C';
+    else if (a < 240) cls = 'D';
+    else cls = 'E';
+
+    let type: IpResult['type'] = 'public';
+    let range: string | undefined;
+
+    if (a === 127) {
+        type = 'loopback';
+        range = '127.0.0.0/8';
+    } else if (a === 10) {
+        type = 'private';
+        range = '10.0.0.0/8';
+    } else if (a === 172 && b >= 16 && b <= 31) {
+        type = 'private';
+        range = '172.16.0.0/12';
+    } else if (a === 192 && b === 168) {
+        type = 'private';
+        range = '192.168.0.0/16';
+    } else if (a === 169 && b === 254) {
+        type = 'link-local';
+        range = '169.254.0.0/16';
+    } else if (a >= 224 && a <= 239) {
+        type = 'multicast';
+        range = '224.0.0.0/4';
+    } else if (raw === '255.255.255.255') {
+        type = 'broadcast';
+    }
+
+    const binary = octets.map((o) => o.toString(2).padStart(8, '0')).join('.');
+    const decimal = ((a << 24) | (b << 16) | (c << 8) | d) >>> 0;
+    const reverse = [...octets].reverse().join('.') + '.in-addr.arpa';
+
+    const result: IpResult = { ip: raw, version: 'IPv4', type, class: cls, binary, decimal, reverse };
+    if (range) result.range = range;
+    return result;
+}
+
+/**
+ * Parses and analyzes an IPv6 address, expanding :: shorthand.
+ *
+ * @param raw - The IPv6 address string (e.g. "::1" or "fe80::1")
+ * @returns Detailed information about the address
+ * @throws Error if the address is malformed
+ */
+function parseIPv6(raw: string): IpResult {
+    let expanded = raw;
+    if (raw.includes('::')) {
+        const halves = raw.split('::');
+        const left = halves[0] ? halves[0].split(':') : [];
+        const right = halves[1] ? halves[1].split(':') : [];
+        const fill = Array(8 - left.length - right.length).fill('0');
+        expanded = [...left, ...fill, ...right].join(':');
+    }
+
+    const groups = expanded.split(':');
+    if (groups.length !== 8) throw new Error('Invalid IPv6 address');
+    const values = groups.map((g) => parseInt(g || '0', 16));
+    if (values.some((v) => isNaN(v) || v < 0 || v > 0xffff)) throw new Error('Invalid IPv6 address');
+
+    let type: IpResult['type'] = 'public';
+    let range: string | undefined;
+
+    if (raw === '::1' || values.every((v, i) => (i < 7 ? v === 0 : v === 1))) {
+        type = 'loopback';
+        range = '::1/128';
+    } else if ((values[0]! & 0xfe00) === 0xfc00) {
+        type = 'private';
+        range = 'fc00::/7';
+    } else if ((values[0]! & 0xffc0) === 0xfe80) {
+        type = 'link-local';
+        range = 'fe80::/10';
+    } else if ((values[0]! & 0xff00) === 0xff00) {
+        type = 'multicast';
+        range = 'ff00::/8';
+    }
+
+    const binary = values.map((v) => v.toString(2).padStart(16, '0')).join(':');
+    const hex = values.map((v) => v.toString(16).padStart(4, '0')).join('');
+    const reverse = hex.split('').reverse().join('.') + '.ip6.arpa';
+
+    const result: IpResult = { ip: expanded, version: 'IPv6', type, binary, reverse };
+    if (range) result.range = range;
+    return result;
+}
+
+/**
+ * Analyzes an IPv4 or IPv6 address and returns its type, class, binary
+ * representation, decimal value, and reverse DNS notation.
+ *
+ * @param address - The IP address to analyze
+ * @returns Detailed breakdown of the address
+ * @throws Error if the address is missing or invalid
+ */
+export default function ip(address: string): IpResult {
+    if (!address || typeof address !== 'string') throw new Error('An IP address is required');
+    if (address.length > MAX_STRING_LENGTH) throw new Error('Address is too long');
+
+    if (address.includes(':')) return parseIPv6(address);
+    if (address.includes('.')) return parseIPv4(address);
+    throw new Error('Invalid IP address format');
+}

package/src/modules/v4/levenshtein.ts

@@ -1,5 +1,13 @@
 import { MAX_LEVENSHTEIN_LENGTH } from '../../constants.js';
 
+/**
+ * Computes the Levenshtein edit distance between two strings.
+ *
+ * @param str1 - First string
+ * @param str2 - Second string
+ * @returns Object containing both strings and the minimum number of single-character edits to transform one into the other
+ * @throws Error if either string is missing, not a string, or exceeds the maximum length
+ */
 export default function levenshtein(str1: string, str2: string): { str1: string; str2: string; distance: number } {
     if (!str1 || typeof str1 !== 'string') {
         throw new Error('Please provide a valid first string');

package/src/modules/v4/palette.ts

@@ -1,4 +1,4 @@
-import { hexToRgb, rgbToHsl, hslToRgb, rgbToHex } from '../../utils/colors.js';
+import { hexToRgb, hslToRgb, rgbToHex, rgbToHsl } from '../../utils/colors.js';
 
 export interface PaletteColor {
     hex: string;
@@ -30,6 +30,14 @@ function fromHueShifts(base: [number, number, number], shifts: number[]): Palett
     });
 }
 
+/**
+ * Generates a color palette from a base hex color using a specified harmony type.
+ *
+ * @param color - Base hex color (e.g. "#ff5733")
+ * @param type - Palette type: "complementary", "triadic", "analogous", "tetradic", or "split-complementary"
+ * @returns Object containing the base color and the derived palette colors in hex, RGB, and HSL
+ * @throws Error if color or type is missing, or the type is not one of the accepted values
+ */
 export default function palette(color: string, type: string): PaletteResult {
     if (!color) throw new Error('A base color is required');
     if (!type) throw new Error('A palette type is required');

package/src/modules/v4/password.ts

@@ -0,0 +1,381 @@
+import { randomInt } from 'crypto';
+
+const MIN_LENGTH = 8;
+const MAX_LENGTH = 128;
+const MAX_COUNT = 20;
+
+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_COUNT) {
+        throw new Error(`Count must be between 1 and ${MAX_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_LENGTH || length > MAX_LENGTH) {
+        throw new Error(`Length must be between ${MIN_LENGTH} and ${MAX_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;
@@ -13,6 +14,11 @@ interface CountryInfo {
     lang: string;
 }
 
+/**
+ * Generates a fictional personal profile with realistic demographic and contact data.
+ *
+ * @returns Object containing name, email, phone, address, job, hobbies, and other personal attributes
+ */
 export default function personal(): Record<string, unknown> {
     const people: Person[] = [
         { name: 'John Doe', social: 'john_doe', email: 'john@example.com', country: 'US' },
@@ -42,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)}`;
@@ -64,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;
@@ -124,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/placeholder.ts

@@ -157,6 +157,14 @@ function parseAnimate(value: string | undefined): AnimateMode {
     throw new Error('animate must be one of: shimmer, pulse, none');
 }
 
+/**
+ * Generates an SVG placeholder image or skeleton loader with configurable dimensions and style.
+ *
+ * @param type - Placeholder type: "image" or "skeleton"
+ * @param query - Query parameters including width, height, bg, color, text, rows, avatar, animate, speed, and radius
+ * @returns Object containing the SVG body, content type, and placeholder type
+ * @throws Error if any parameter is invalid or out of range
+ */
 export default function placeholder(type: string, query: Record<string, string | undefined>): PlaceholderResult {
     const speed = query.speed ? parseFloat(query.speed) : 1.5;
     if (isNaN(speed) || speed < 0.1 || speed > 10) throw new Error('speed must be between 0.1 and 10');

package/src/modules/v4/qrcode.ts

@@ -1,5 +1,6 @@
-import { toBuffer, toDataURL, toCanvas as qrToCanvas } from 'qrcode';
 import { createCanvas, loadImage } from 'canvas';
+import { toBuffer, toCanvas as qrToCanvas, toDataURL } from 'qrcode';
+
 import { normalizeColor } from '../../utils/colors.js';
 
 export interface QRCodeOptions {
@@ -48,6 +49,13 @@ async function fetchIcon(url: string): Promise<Buffer> {
     return buffer;
 }
 
+/**
+ * Generates a QR code image for a given URL, with optional icon overlay and color customization.
+ *
+ * @param options - QR code generation options including URL, size, margin, correction level, colors, and optional icon
+ * @returns Object containing the QR code as a PNG buffer or Base64 string, and the content type
+ * @throws Error if the URL is missing, any option is invalid, or the icon URL cannot be fetched
+ */
 export default async function qrcode(options: QRCodeOptions): Promise<QRCodeResult> {
     const { url } = options;
     if (!url || typeof url !== 'string') throw new Error('Please provide a valid URL');

package/src/modules/v4/statistics.ts

@@ -13,6 +13,13 @@ export interface StatisticsResult {
     stddev: number;
 }
 
+/**
+ * Computes descriptive statistics for a comma-separated list of numbers.
+ *
+ * @param values - Comma-separated numeric string (e.g. "1,2,3,4,5")
+ * @returns Object containing count, sum, min, max, range, mean, median, mode, variance, and standard deviation
+ * @throws Error if values is missing, contains non-numeric entries, or exceeds the maximum count
+ */
 export default function statistics(values: string): StatisticsResult {
     if (!values) throw new Error('A list of values is required');
     if (typeof values !== 'string') throw new Error('Values must be a comma-separated string');