@20syldev/api 4.8.0 → 5.0.0

package/src/modules/v4/placeholder.ts

@@ -1,197 +0,0 @@
-import { normalizeColor } from '../../utils/colors.js';
-
-type AvatarShape = 'circle' | 'rounded' | 'square';
-type AnimateMode = 'shimmer' | 'pulse' | 'none';
-
-export interface PlaceholderOptions {
-    width: number;
-    height: number;
-    bg?: string;
-    color?: string;
-    text?: string;
-    rows?: number;
-    avatar?: AvatarShape;
-    lines?: number;
-    animate?: AnimateMode;
-    speed?: number;
-    radius?: number;
-}
-
-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 escapeXml(str: string): string {
-    return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-}
-
-function generateImage(opts: PlaceholderOptions): string {
-    const { width, height } = opts;
-    const bg = normalizeColor(opts.bg, '#cccccc');
-    const color = normalizeColor(opts.color, '#333333');
-    const text = escapeXml(opts.text ?? `${width}\u00d7${height}`);
-    const fontSize = Math.max(12, Math.min(width, height) / 8);
-
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
-  <rect width="${width}" height="${height}" fill="${bg}" rx="4" />
-  <text x="50%" y="50%" dominant-baseline="central" text-anchor="middle" font-family="system-ui,-apple-system,sans-serif" font-weight="600" font-size="${fontSize}" fill="${color}">${text}</text>
-</svg>`;
-}
-
-function avatarShape(shape: AvatarShape, x: number, y: number, size: number): string {
-    const r = size / 2;
-    switch (shape) {
-        case 'circle':
-            return `<circle cx="${x + r}" cy="${y + r}" r="${r}" />`;
-        case 'rounded':
-            return `<rect x="${x}" y="${y}" width="${size}" height="${size}" rx="${Math.round(size * 0.25)}" />`;
-        case 'square':
-            return `<rect x="${x}" y="${y}" width="${size}" height="${size}" rx="2" />`;
-    }
-}
-
-function animationDefs(mode: AnimateMode, bg: string, highlight: string, speed: number): string {
-    if (mode === 'none') return '';
-
-    if (mode === 'pulse') {
-        return `<style>
-      @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.5; } }
-      .sk { animation: pulse ${speed}s cubic-bezier(0.4, 0, 0.6, 1) infinite; }
-    </style>`;
-    }
-
-    return `<linearGradient id="g">
-      <stop offset="0.1" stop-color="${bg}" />
-      <stop offset="0.5" stop-color="${highlight}" />
-      <stop offset="0.9" stop-color="${bg}" />
-      <animateTransform attributeName="gradientTransform" type="translate" values="-2 0; 2 0" dur="${speed}s" repeatCount="indefinite" />
-    </linearGradient>`;
-}
-
-function generateSkeleton(opts: PlaceholderOptions): string {
-    const { width, height } = opts;
-    const bg = normalizeColor(opts.bg, '#e5e5e5');
-    const highlight = normalizeColor(opts.color, '#f5f5f5');
-    const rows = Math.max(0, Math.min(20, opts.rows ?? 3));
-    const avatar = opts.avatar;
-    const animate = opts.animate ?? 'shimmer';
-    const speed = opts.speed ?? 1.5;
-    const rx = opts.radius ?? 4;
-
-    const pad = Math.round(width * 0.06);
-    const slots = rows + (avatar ? 4 : 0);
-    const available = height - pad * 2;
-    const lineH = Math.round(Math.max(8, (available / Math.max(1, slots)) * 0.65));
-    const gap = Math.round(Math.max(6, (available / Math.max(1, slots)) * 0.35));
-
-    const shapes: string[] = [];
-    let y = pad;
-
-    if (avatar) {
-        const size = Math.round(Math.min(width * 0.14, height * 0.24, 48));
-        shapes.push(avatarShape(avatar, pad, y, size));
-
-        const lx = pad + size + gap;
-        const lw = width - lx - pad;
-        const count = Math.max(0, Math.min(2, opts.lines ?? 2));
-
-        if (count === 2) {
-            const nameY = Math.max(pad, Math.round(y + size / 2 - (lineH * 2 + gap) / 2));
-            shapes.push(`<rect x="${lx}" y="${nameY}" width="${lw * 0.55}" height="${lineH}" rx="${rx}" />`);
-            shapes.push(
-                `<rect x="${lx}" y="${nameY + lineH + gap}" width="${lw * 0.35}" height="${lineH}" rx="${rx}" />`,
-            );
-        } else if (count === 1) {
-            const nameY = Math.max(pad, Math.round(y + size / 2 - lineH / 2));
-            shapes.push(`<rect x="${lx}" y="${nameY}" width="${lw * 0.55}" height="${lineH}" rx="${rx}" />`);
-        }
-
-        y += size + gap * 2;
-    }
-
-    for (let i = 0; i < rows; i++) {
-        const ratio = i === rows - 1 && rows > 1 ? 0.55 : i % 2 === 0 ? 0.92 : 0.78;
-        const w = Math.round((width - pad * 2) * ratio);
-        shapes.push(`<rect x="${pad}" y="${y}" width="${w}" height="${lineH}" rx="${rx}" />`);
-        y += lineH + gap;
-    }
-
-    const defs = animationDefs(animate, bg, highlight, speed);
-    const fill = animate === 'shimmer' ? 'url(#g)' : bg;
-    const cls = animate === 'pulse' ? ' class="sk"' : '';
-
-    return `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}">
-  <defs>
-    <clipPath id="c">
-      ${shapes.join('\n      ')}
-    </clipPath>
-    ${defs}
-  </defs>
-  <rect width="${width}" height="${height}" clip-path="url(#c)" fill="${fill}"${cls} />
-</svg>`;
-}
-
-export interface PlaceholderResult {
-    type: string;
-    contentType: string;
-    body: string;
-}
-
-const AVATAR_SHAPES = new Set(['circle', 'rounded', 'square']);
-const ANIMATE_MODES = new Set(['shimmer', 'pulse', 'none']);
-
-function parseAvatar(value: string | undefined): AvatarShape | undefined {
-    if (!value) return undefined;
-    if (value === 'true' || value === '1') return 'circle';
-    if (AVATAR_SHAPES.has(value)) return value as AvatarShape;
-    throw new Error('avatar must be one of: circle, rounded, square');
-}
-
-function parseAnimate(value: string | undefined): AnimateMode {
-    if (!value) return 'shimmer';
-    if (ANIMATE_MODES.has(value)) return value as 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');
-
-    const radius = query.radius ? parseInt(query.radius, 10) : 4;
-    if (isNaN(radius) || radius < 0 || radius > 50) throw new Error('radius must be between 0 and 50');
-
-    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: parseAvatar(query.avatar),
-        lines: query.lines ? parseInt(query.lines, 10) : 2,
-        animate: parseAnimate(query.animate),
-        speed,
-        radius,
-    };
-
-    switch (type) {
-        case 'image':
-            return { type, contentType: 'image/svg+xml', 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

@@ -1,121 +0,0 @@
-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 {
-    url: string;
-    size?: number;
-    margin?: number;
-    correction?: 'L' | 'M' | 'Q' | 'H';
-    dark?: string;
-    light?: string;
-    icon?: string;
-    iconSize?: number;
-    iconPadding?: number;
-    iconRadius?: number;
-    format?: 'png' | 'base64';
-}
-
-export interface QRCodeResult {
-    contentType: string;
-    body: Buffer | string;
-}
-
-const CORRECTIONS = new Set(['L', 'M', 'Q', 'H']);
-const FORMATS = new Set(['png', 'base64']);
-
-function clamp(value: number | undefined, name: string, def: number, min: number, max: number): number {
-    if (value === undefined) return def;
-    if (isNaN(value)) throw new Error(`${name} must be a number`);
-    if (value < min || value > max) throw new Error(`${name} must be between ${min} and ${max}`);
-    return Math.floor(value);
-}
-
-async function fetchIcon(url: string): Promise<Buffer> {
-    if (!/^https:\/\//i.test(url)) throw new Error('Icon URL must use HTTPS');
-
-    const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
-
-    if (!response.ok) throw new Error(`Failed to fetch icon: HTTP ${response.status}`);
-
-    const contentType = response.headers.get('content-type') ?? '';
-    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_QRCODE_LOGO_BYTES) throw new Error('Icon must be under 2MB');
-
-    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');
-
-    const format = options.format ?? 'png';
-    if (!FORMATS.has(format)) throw new Error('format must be one of: png, base64');
-
-    const size = clamp(options.size, 'size', 200, 50, 2000);
-    const margin = clamp(options.margin, 'margin', 4, 0, 10);
-    const dark = normalizeColor(options.dark, '#000000');
-    const light = normalizeColor(options.light, '#ffffff');
-
-    let correction = options.correction ?? 'M';
-    if (!CORRECTIONS.has(correction)) throw new Error('correction must be one of: L, M, Q, H');
-    if (options.icon) correction = 'H';
-
-    const qrOpts = {
-        width: size,
-        margin,
-        errorCorrectionLevel: correction as 'L' | 'M' | 'Q' | 'H',
-        color: { dark, light },
-    };
-
-    if (!options.icon) {
-        if (format === 'base64') {
-            return { contentType: 'application/json', body: await toDataURL(url, qrOpts) };
-        }
-        return { contentType: 'image/png', body: await toBuffer(url, qrOpts) };
-    }
-
-    const canvas = createCanvas(size, size);
-    await qrToCanvas(canvas as unknown as HTMLCanvasElement, url, qrOpts);
-
-    const iconBuffer = await fetchIcon(options.icon);
-    const iconImg = await loadImage(iconBuffer);
-
-    const iconSize = clamp(options.iconSize, 'iconSize', Math.round(size * 0.2), 10, Math.round(size * 0.4));
-    const iconPadding = clamp(options.iconPadding, 'iconPadding', 5, 0, 50);
-    const maxRadius = Math.floor((iconSize + iconPadding * 2) / 2);
-    const iconRadius = clamp(options.iconRadius, 'iconRadius', 0, 0, maxRadius);
-
-    const ctx = canvas.getContext('2d');
-    const totalSize = iconSize + iconPadding * 2;
-    const x = (canvas.width - totalSize) / 2;
-    const y = (canvas.height - totalSize) / 2;
-
-    ctx.beginPath();
-    ctx.roundRect(x, y, totalSize, totalSize, iconRadius);
-    ctx.fillStyle = light;
-    ctx.fill();
-
-    ctx.save();
-    ctx.beginPath();
-    ctx.roundRect(x + iconPadding, y + iconPadding, iconSize, iconSize, Math.max(0, iconRadius - iconPadding));
-    ctx.clip();
-    ctx.drawImage(iconImg, x + iconPadding, y + iconPadding, iconSize, iconSize);
-    ctx.restore();
-
-    if (format === 'base64') {
-        return { contentType: 'application/json', body: canvas.toDataURL('image/png') };
-    }
-    return { contentType: 'image/png', body: canvas.toBuffer('image/png') };
-}

package/src/modules/v4/regex.ts

@@ -1,67 +0,0 @@
-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/statistics.ts

@@ -1,62 +0,0 @@
-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;
-}
-
-/**
- * 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');
-
-    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),
-    };
-}