@20syldev/api 3.5.0 → 4.1.0

package/src/modules/v4/placeholder.ts

@@ -0,0 +1,122 @@
+import { createCanvas } from 'canvas';
+
+export interface PlaceholderOptions {
+    width: number;
+    height: number;
+    bg?: string;
+    color?: string;
+    text?: string;
+    rows?: number;
+    avatar?: boolean;
+}
+
+function parseSize(value: string | undefined, name: string, def: number): number {
+    if (value === undefined) return def;
+    const n = Number(value);
+    if (isNaN(n)) throw new Error(`${name} must be a number`);
+    if (n < 1 || n > 4000) throw new Error(`${name} must be between 1 and 4000`);
+    return Math.floor(n);
+}
+
+function normalizeColor(value: string | undefined, def: string): string {
+    if (!value) return def;
+    const clean = value.startsWith('#') ? value : `#${value}`;
+    if (!/^#[0-9a-fA-F]{3,6}$/.test(clean)) throw new Error('Invalid color (use hex like #ff6600)');
+    return clean;
+}
+
+function generateImage(opts: PlaceholderOptions): Buffer {
+    const { width, height } = opts;
+    const bg = normalizeColor(opts.bg, '#cccccc');
+    const color = normalizeColor(opts.color, '#333333');
+    const text = opts.text ?? `${width}×${height}`;
+
+    const canvas = createCanvas(width, height);
+    const ctx = canvas.getContext('2d');
+
+    ctx.fillStyle = bg;
+    ctx.fillRect(0, 0, width, height);
+
+    const fontSize = Math.max(12, Math.min(width, height) / 8);
+    ctx.font = `bold ${fontSize}px sans-serif`;
+    ctx.fillStyle = color;
+    ctx.textAlign = 'center';
+    ctx.textBaseline = 'middle';
+    ctx.fillText(text, width / 2, height / 2);
+
+    return canvas.toBuffer('image/png');
+}
+
+function generateSkeleton(opts: PlaceholderOptions): string {
+    const { width, height } = opts;
+    const bg = normalizeColor(opts.bg, '#e2e8f0');
+    const shimmer = normalizeColor(opts.color, '#f1f5f9');
+    const rows = Math.max(1, Math.min(20, opts.rows ?? 3));
+    const avatar = !!opts.avatar;
+
+    const padding = Math.min(width, height) * 0.05;
+    const avatarSize = avatar ? Math.min(width, height) * 0.2 : 0;
+    const lineHeight = (height - padding * 2 - avatarSize - (avatar ? padding : 0)) / rows;
+    const lineThickness = Math.max(8, lineHeight * 0.5);
+    const radius = lineThickness / 2;
+
+    const lines: string[] = [];
+    const startY = padding + (avatar ? avatarSize + padding : 0);
+    for (let i = 0; i < rows; i++) {
+        const y = startY + i * lineHeight + (lineHeight - lineThickness) / 2;
+        const lineWidth = (width - padding * 2) * (i === rows - 1 ? 0.6 : 0.95);
+        lines.push(
+            `<rect x="${padding}" y="${y}" width="${lineWidth}" height="${lineThickness}" rx="${radius}" fill="url(#shimmer)" />`,
+        );
+    }
+
+    const avatarShape = avatar
+        ? `<circle cx="${padding + avatarSize / 2}" cy="${padding + avatarSize / 2}" r="${avatarSize / 2}" fill="url(#shimmer)" />`
+        : '';
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
+  <defs>
+    <linearGradient id="shimmer" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" stop-color="${bg}">
+        <animate attributeName="offset" values="-2; 1" dur="1.5s" repeatCount="indefinite" />
+      </stop>
+      <stop offset="50%" stop-color="${shimmer}">
+        <animate attributeName="offset" values="-1.5; 1.5" dur="1.5s" repeatCount="indefinite" />
+      </stop>
+      <stop offset="100%" stop-color="${bg}">
+        <animate attributeName="offset" values="-1; 2" dur="1.5s" repeatCount="indefinite" />
+      </stop>
+    </linearGradient>
+  </defs>
+  <rect width="${width}" height="${height}" fill="${bg}" />
+  ${avatarShape}
+  ${lines.join('\n  ')}
+</svg>`;
+}
+
+export interface PlaceholderResult {
+    type: string;
+    contentType: string;
+    body: Buffer | string;
+}
+
+export default function placeholder(type: string, query: Record<string, string | undefined>): PlaceholderResult {
+    const opts: PlaceholderOptions = {
+        width: parseSize(query.width, 'width', 800),
+        height: parseSize(query.height, 'height', 600),
+        bg: query.bg,
+        color: query.color,
+        text: query.text,
+        rows: query.rows ? parseInt(query.rows, 10) : undefined,
+        avatar: query.avatar === 'true' || query.avatar === '1',
+    };
+
+    switch (type) {
+        case 'image':
+            return { type, contentType: 'image/png', body: generateImage(opts) };
+        case 'skeleton':
+            return { type, contentType: 'image/svg+xml', body: generateSkeleton(opts) };
+        default:
+            throw new Error('Type must be one of: image, skeleton');
+    }
+}

package/src/modules/v4/qrcode.ts

@@ -0,0 +1,11 @@
+import { toDataURL } from 'qrcode';
+
+export default async function qrcode(url: string): Promise<string> {
+    if (!url || typeof url !== 'string') throw new Error('Please provide a valid URL');
+
+    try {
+        return await toDataURL(url);
+    } catch (error) {
+        throw new Error(`Failed to generate QR code: ${(error as Error).message}`);
+    }
+}

package/src/modules/v4/statistics.ts

@@ -0,0 +1,55 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+export interface StatisticsResult {
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    range: number;
+    mean: number;
+    median: number;
+    mode: number[];
+    variance: number;
+    stddev: number;
+}
+
+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');
+
+    const arr = values.split(',').map((v) => Number(v.trim()));
+
+    if (arr.some(isNaN)) throw new Error('Values must contain only numbers');
+    if (arr.length < 1) throw new Error('At least one value is required');
+    if (arr.length > MAX_STRING_LENGTH) throw new Error(`Cannot process more than ${MAX_STRING_LENGTH} values`);
+
+    const count = arr.length;
+    const sum = arr.reduce((a, b) => a + b, 0);
+    const min = Math.min(...arr);
+    const max = Math.max(...arr);
+    const mean = sum / count;
+
+    const sorted = [...arr].sort((a, b) => a - b);
+    const median = count % 2 === 0 ? (sorted[count / 2 - 1]! + sorted[count / 2]!) / 2 : sorted[Math.floor(count / 2)]!;
+
+    const counts = new Map<number, number>();
+    for (const n of arr) counts.set(n, (counts.get(n) ?? 0) + 1);
+    const maxCount = Math.max(...counts.values());
+    const mode = maxCount === 1 ? [] : [...counts.entries()].filter(([, c]) => c === maxCount).map(([n]) => n);
+
+    const variance = arr.reduce((acc, n) => acc + (n - mean) ** 2, 0) / count;
+    const stddev = Math.sqrt(variance);
+
+    return {
+        count,
+        sum: +sum.toFixed(6),
+        min,
+        max,
+        range: max - min,
+        mean: +mean.toFixed(6),
+        median: +median.toFixed(6),
+        mode,
+        variance: +variance.toFixed(6),
+        stddev: +stddev.toFixed(6),
+    };
+}

package/src/modules/v4/text.ts

@@ -0,0 +1,300 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+const LOREM_WORDS = [
+    'lorem',
+    'ipsum',
+    'dolor',
+    'sit',
+    'amet',
+    'consectetur',
+    'adipiscing',
+    'elit',
+    'sed',
+    'do',
+    'eiusmod',
+    'tempor',
+    'incididunt',
+    'ut',
+    'labore',
+    'et',
+    'dolore',
+    'magna',
+    'aliqua',
+    'enim',
+    'ad',
+    'minim',
+    'veniam',
+    'quis',
+    'nostrud',
+    'exercitation',
+    'ullamco',
+    'laboris',
+    'nisi',
+    'aliquip',
+    'ex',
+    'ea',
+    'commodo',
+    'consequat',
+    'duis',
+    'aute',
+    'irure',
+    'in',
+    'reprehenderit',
+    'voluptate',
+    'velit',
+    'esse',
+    'cillum',
+    'eu',
+    'fugiat',
+    'nulla',
+    'pariatur',
+    'excepteur',
+    'sint',
+    'occaecat',
+    'cupidatat',
+    'non',
+    'proident',
+    'sunt',
+    'culpa',
+    'qui',
+    'officia',
+    'deserunt',
+    'mollit',
+    'anim',
+    'id',
+    'est',
+    'laborum',
+];
+
+const FR_UNITS = [
+    'zéro',
+    'un',
+    'deux',
+    'trois',
+    'quatre',
+    'cinq',
+    'six',
+    'sept',
+    'huit',
+    'neuf',
+    'dix',
+    'onze',
+    'douze',
+    'treize',
+    'quatorze',
+    'quinze',
+    'seize',
+    'dix-sept',
+    'dix-huit',
+    'dix-neuf',
+];
+const FR_TENS = [
+    '',
+    '',
+    'vingt',
+    'trente',
+    'quarante',
+    'cinquante',
+    'soixante',
+    'soixante',
+    'quatre-vingt',
+    'quatre-vingt',
+];
+
+const EN_UNITS = [
+    'zero',
+    'one',
+    'two',
+    'three',
+    'four',
+    'five',
+    'six',
+    'seven',
+    'eight',
+    'nine',
+    'ten',
+    'eleven',
+    'twelve',
+    'thirteen',
+    'fourteen',
+    'fifteen',
+    'sixteen',
+    'seventeen',
+    'eighteen',
+    'nineteen',
+];
+const EN_TENS = ['', '', 'twenty', 'thirty', 'forty', 'fifty', 'sixty', 'seventy', 'eighty', 'ninety'];
+
+function checkText(value: string): void {
+    if (!value) throw new Error('A value is required');
+    if (typeof value !== 'string') throw new Error('Value must be a string');
+    if (value.length > MAX_STRING_LENGTH)
+        throw new Error(`Value must be less than ${MAX_STRING_LENGTH} characters long`);
+}
+
+export interface TextStats {
+    characters: number;
+    charactersNoSpaces: number;
+    words: number;
+    sentences: number;
+    paragraphs: number;
+    readingTime: string;
+    mostFrequentChar: string;
+}
+
+export function stats(value: string): TextStats {
+    checkText(value);
+
+    const characters = value.length;
+    const charactersNoSpaces = value.replace(/\s/g, '').length;
+    const words = value.trim().split(/\s+/).filter(Boolean).length;
+    const sentences = value.split(/[.!?]+/).filter((s) => s.trim().length > 0).length;
+    const paragraphs = value.split(/\n\s*\n/).filter((p) => p.trim().length > 0).length || 1;
+
+    const minutes = words / 200;
+    const readingTime = minutes < 1 ? `${Math.ceil(minutes * 60)}s` : `${Math.round(minutes)}min`;
+
+    const counts = new Map<string, number>();
+    for (const c of value.replace(/\s/g, '').toLowerCase()) counts.set(c, (counts.get(c) ?? 0) + 1);
+    let mostFrequentChar = '';
+    let maxCount = 0;
+    for (const [char, count] of counts) {
+        if (count > maxCount) {
+            mostFrequentChar = char;
+            maxCount = count;
+        }
+    }
+
+    return { characters, charactersNoSpaces, words, sentences, paragraphs, readingTime, mostFrequentChar };
+}
+
+export function slug(value: string): string {
+    checkText(value);
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-]/g, '')
+        .trim()
+        .replace(/[\s-]+/g, '-');
+}
+
+export function lorem(type: string, count: string): string {
+    const n = Number(count) || 5;
+    if (n < 1 || n > 500) throw new Error('Count must be between 1 and 500');
+
+    const randomWord = (): string => LOREM_WORDS[Math.floor(Math.random() * LOREM_WORDS.length)]!;
+    const randomSentence = (): string => {
+        const length = 5 + Math.floor(Math.random() * 10);
+        const words = Array.from({ length }, randomWord);
+        words[0] = words[0]!.charAt(0).toUpperCase() + words[0]!.slice(1);
+        return words.join(' ') + '.';
+    };
+    const randomParagraph = (): string => {
+        const length = 3 + Math.floor(Math.random() * 5);
+        return Array.from({ length }, randomSentence).join(' ');
+    };
+
+    switch (type) {
+        case 'words':
+            return Array.from({ length: n }, randomWord).join(' ');
+        case 'sentences':
+            return Array.from({ length: n }, randomSentence).join(' ');
+        case 'paragraphs':
+            return Array.from({ length: n }, randomParagraph).join('\n\n');
+        default:
+            throw new Error('Type must be one of: words, sentences, paragraphs');
+    }
+}
+
+function frBelowHundred(n: number): string {
+    if (n < 20) return FR_UNITS[n]!;
+    const t = Math.floor(n / 10);
+    const u = n % 10;
+    if (t === 7 || t === 9) {
+        const base = FR_TENS[t]!;
+        const sub = 10 + u;
+        return base + (base.endsWith('-') ? '' : '-') + FR_UNITS[sub];
+    }
+    if (t === 8 && u === 0) return 'quatre-vingts';
+    if (u === 0) return FR_TENS[t]!;
+    if (u === 1 && t < 8) return FR_TENS[t] + ' et un';
+    return FR_TENS[t] + '-' + FR_UNITS[u];
+}
+
+function frBelowThousand(n: number): string {
+    if (n < 100) return frBelowHundred(n);
+    const h = Math.floor(n / 100);
+    const r = n % 100;
+    let result = '';
+    if (h === 1) result = 'cent';
+    else result = FR_UNITS[h] + ' cent' + (r === 0 ? 's' : '');
+    if (r > 0) result += ' ' + frBelowHundred(r);
+    return result;
+}
+
+function numberToFrench(n: number): string {
+    if (n === 0) return 'zéro';
+    if (n < 0) return 'moins ' + numberToFrench(-n);
+    if (n < 1000) return frBelowThousand(n);
+    if (n < 1_000_000) {
+        const t = Math.floor(n / 1000);
+        const r = n % 1000;
+        const thousands = t === 1 ? 'mille' : frBelowThousand(t) + ' mille';
+        return r === 0 ? thousands : thousands + ' ' + frBelowThousand(r);
+    }
+    if (n < 1_000_000_000) {
+        const m = Math.floor(n / 1_000_000);
+        const r = n % 1_000_000;
+        const millions = m === 1 ? 'un million' : frBelowThousand(m) + ' millions';
+        return r === 0 ? millions : millions + ' ' + numberToFrench(r);
+    }
+    throw new Error('Number must be less than 1 billion');
+}
+
+function enBelowHundred(n: number): string {
+    if (n < 20) return EN_UNITS[n]!;
+    const t = Math.floor(n / 10);
+    const u = n % 10;
+    return u === 0 ? EN_TENS[t]! : EN_TENS[t] + '-' + EN_UNITS[u];
+}
+
+function enBelowThousand(n: number): string {
+    if (n < 100) return enBelowHundred(n);
+    const h = Math.floor(n / 100);
+    const r = n % 100;
+    return r === 0 ? EN_UNITS[h] + ' hundred' : EN_UNITS[h] + ' hundred ' + enBelowHundred(r);
+}
+
+function numberToEnglish(n: number): string {
+    if (n === 0) return 'zero';
+    if (n < 0) return 'minus ' + numberToEnglish(-n);
+    if (n < 1000) return enBelowThousand(n);
+    if (n < 1_000_000) {
+        const t = Math.floor(n / 1000);
+        const r = n % 1000;
+        return r === 0 ? enBelowThousand(t) + ' thousand' : enBelowThousand(t) + ' thousand ' + enBelowThousand(r);
+    }
+    if (n < 1_000_000_000) {
+        const m = Math.floor(n / 1_000_000);
+        const r = n % 1_000_000;
+        return r === 0 ? enBelowThousand(m) + ' million' : enBelowThousand(m) + ' million ' + numberToEnglish(r);
+    }
+    throw new Error('Number must be less than 1 billion');
+}
+
+export function number(value: string, lang: string): string {
+    const n = Number(value);
+    if (isNaN(n)) throw new Error('Value must be a number');
+    if (!Number.isInteger(n)) throw new Error('Value must be an integer');
+    if (Math.abs(n) >= 1_000_000_000) throw new Error('Number must be less than 1 billion');
+
+    switch (lang) {
+        case 'fr':
+            return numberToFrench(n);
+        case 'en':
+            return numberToEnglish(n);
+        default:
+            throw new Error('Lang must be one of: fr, en');
+    }
+}