@20syldev/api 4.0.0 → 4.1.0

package/src/modules/v4/encode.ts

@@ -0,0 +1,170 @@
+import { MAX_STRING_LENGTH } from '../../constants.js';
+
+const MORSE_TABLE: Record<string, string> = {
+    A: '.-',
+    B: '-...',
+    C: '-.-.',
+    D: '-..',
+    E: '.',
+    F: '..-.',
+    G: '--.',
+    H: '....',
+    I: '..',
+    J: '.---',
+    K: '-.-',
+    L: '.-..',
+    M: '--',
+    N: '-.',
+    O: '---',
+    P: '.--.',
+    Q: '--.-',
+    R: '.-.',
+    S: '...',
+    T: '-',
+    U: '..-',
+    V: '...-',
+    W: '.--',
+    X: '-..-',
+    Y: '-.--',
+    Z: '--..',
+    '0': '-----',
+    '1': '.----',
+    '2': '..---',
+    '3': '...--',
+    '4': '....-',
+    '5': '.....',
+    '6': '-....',
+    '7': '--...',
+    '8': '---..',
+    '9': '----.',
+    '.': '.-.-.-',
+    ',': '--..--',
+    '?': '..--..',
+    "'": '.----.',
+    '!': '-.-.--',
+    '/': '-..-.',
+    '(': '-.--.',
+    ')': '-.--.-',
+    '&': '.-...',
+    ':': '---...',
+    ';': '-.-.-.',
+    '=': '-...-',
+    '+': '.-.-.',
+    '-': '-....-',
+    _: '..--.-',
+    '"': '.-..-.',
+    $: '...-..-',
+    '@': '.--.-.',
+};
+
+const MORSE_REVERSE: Record<string, string> = Object.fromEntries(Object.entries(MORSE_TABLE).map(([k, v]) => [v, k]));
+
+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 function base64encode(value: string): string {
+    checkText(value);
+    return Buffer.from(value, 'utf-8').toString('base64');
+}
+
+export function base64decode(value: string): string {
+    checkText(value);
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value)) throw new Error('Invalid Base64 string');
+    return Buffer.from(value, 'base64').toString('utf-8');
+}
+
+export function urlencode(value: string): string {
+    checkText(value);
+    return encodeURIComponent(value);
+}
+
+export function urldecode(value: string): string {
+    checkText(value);
+    try {
+        return decodeURIComponent(value);
+    } catch {
+        throw new Error('Invalid URL-encoded string');
+    }
+}
+
+export function morse(value: string): string {
+    checkText(value);
+    return value
+        .toUpperCase()
+        .split(' ')
+        .map((word) =>
+            word
+                .split('')
+                .map((c) => {
+                    if (c === '\n' || c === '\t') return '';
+                    const code = MORSE_TABLE[c];
+                    if (!code) throw new Error(`Unsupported character in Morse code: '${c}'`);
+                    return code;
+                })
+                .filter(Boolean)
+                .join(' '),
+        )
+        .join(' / ');
+}
+
+export function unmorse(value: string): string {
+    checkText(value);
+    return value
+        .split(' / ')
+        .map((word) =>
+            word
+                .split(' ')
+                .map((code) => {
+                    if (!code) return '';
+                    const char = MORSE_REVERSE[code];
+                    if (!char) throw new Error(`Unsupported Morse sequence: '${code}'`);
+                    return char;
+                })
+                .join(''),
+        )
+        .join(' ');
+}
+
+export function rot13(value: string): string {
+    checkText(value);
+    return value.replace(/[a-zA-Z]/g, (c) => {
+        const base = c <= 'Z' ? 65 : 97;
+        return String.fromCharCode(((c.charCodeAt(0) - base + 13) % 26) + base);
+    });
+}
+
+export function caesar(value: string, shift: string): string {
+    checkText(value);
+    const n = Number(shift);
+    if (isNaN(n)) throw new Error('Shift must be a number');
+    const s = ((n % 26) + 26) % 26;
+    return value.replace(/[a-zA-Z]/g, (c) => {
+        const base = c <= 'Z' ? 65 : 97;
+        return String.fromCharCode(((c.charCodeAt(0) - base + s) % 26) + base);
+    });
+}
+
+export function binary(value: string): string {
+    checkText(value);
+    return value
+        .split('')
+        .map((c) => c.charCodeAt(0).toString(2).padStart(8, '0'))
+        .join(' ');
+}
+
+export function unbinary(value: string): string {
+    checkText(value);
+    if (!/^[01\s]+$/.test(value)) throw new Error('Invalid binary string');
+    return value
+        .trim()
+        .split(/\s+/)
+        .map((b) => {
+            if (b.length !== 8) throw new Error('Each binary group must contain 8 bits');
+            return String.fromCharCode(parseInt(b, 2));
+        })
+        .join('');
+}

package/src/modules/v4/geo.ts

@@ -0,0 +1,53 @@
+export interface GeoResult {
+    distance: { km: number; miles: number; nauticalMiles: number };
+    bearing: { degrees: number; cardinal: string };
+    from: { lat: number; lon: number };
+    to: { lat: number; lon: number };
+}
+
+const EARTH_RADIUS_KM = 6371;
+const CARDINALS = ['N', 'NNE', 'NE', 'ENE', 'E', 'ESE', 'SE', 'SSE', 'S', 'SSW', 'SW', 'WSW', 'W', 'WNW', 'NW', 'NNW'];
+
+function toRad(deg: number): number {
+    return (deg * Math.PI) / 180;
+}
+
+function toDeg(rad: number): number {
+    return (rad * 180) / Math.PI;
+}
+
+function parseCoord(value: string, name: string, min: number, max: number): number {
+    const n = Number(value);
+    if (isNaN(n)) throw new Error(`${name} must be a number`);
+    if (n < min || n > max) throw new Error(`${name} must be between ${min} and ${max}`);
+    return n;
+}
+
+export default function geo(lat1: string, lon1: string, lat2: string, lon2: string): GeoResult {
+    const a = parseCoord(lat1, 'lat1', -90, 90);
+    const b = parseCoord(lon1, 'lon1', -180, 180);
+    const c = parseCoord(lat2, 'lat2', -90, 90);
+    const d = parseCoord(lon2, 'lon2', -180, 180);
+
+    const dLat = toRad(c - a);
+    const dLon = toRad(d - b);
+    const sa = Math.sin(dLat / 2) ** 2 + Math.cos(toRad(a)) * Math.cos(toRad(c)) * Math.sin(dLon / 2) ** 2;
+    const distance = 2 * EARTH_RADIUS_KM * Math.asin(Math.sqrt(sa));
+
+    const y = Math.sin(toRad(d - b)) * Math.cos(toRad(c));
+    const x =
+        Math.cos(toRad(a)) * Math.sin(toRad(c)) - Math.sin(toRad(a)) * Math.cos(toRad(c)) * Math.cos(toRad(d - b));
+    const bearing = (toDeg(Math.atan2(y, x)) + 360) % 360;
+    const cardinal = CARDINALS[Math.round(bearing / 22.5) % 16]!;
+
+    return {
+        distance: {
+            km: +distance.toFixed(3),
+            miles: +(distance * 0.621371).toFixed(3),
+            nauticalMiles: +(distance * 0.539957).toFixed(3),
+        },
+        bearing: { degrees: +bearing.toFixed(2), cardinal },
+        from: { lat: a, lon: b },
+        to: { lat: c, lon: d },
+    };
+}

package/src/modules/v4/palette.ts

@@ -0,0 +1,103 @@
+export interface PaletteColor {
+    hex: string;
+    rgb: string;
+    hsl: string;
+}
+
+export interface PaletteResult {
+    base: PaletteColor;
+    type: string;
+    colors: PaletteColor[];
+}
+
+function hexToRgb(hex: string): [number, number, number] {
+    const clean = hex.replace('#', '');
+    if (!/^[0-9a-fA-F]{6}$/.test(clean)) throw new Error('Invalid HEX color (use #RRGGBB)');
+    return [parseInt(clean.slice(0, 2), 16), parseInt(clean.slice(2, 4), 16), parseInt(clean.slice(4, 6), 16)];
+}
+
+function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
+    const r1 = r / 255,
+        g1 = g / 255,
+        b1 = b / 255;
+    const max = Math.max(r1, g1, b1),
+        min = Math.min(r1, g1, b1);
+    const l = (max + min) / 2;
+
+    if (max === min) return [0, 0, l];
+
+    const d = max - min;
+    const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+    let h = 0;
+    if (max === r1) h = (g1 - b1) / d + (g1 < b1 ? 6 : 0);
+    else if (max === g1) h = (b1 - r1) / d + 2;
+    else h = (r1 - g1) / d + 4;
+
+    return [(h * 60 + 360) % 360, s, l];
+}
+
+function hslToRgb(h: number, s: number, l: number): [number, number, number] {
+    const c = (1 - Math.abs(2 * l - 1)) * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = l - c / 2;
+    let r1 = 0,
+        g1 = 0,
+        b1 = 0;
+    if (h < 60) [r1, g1, b1] = [c, x, 0];
+    else if (h < 120) [r1, g1, b1] = [x, c, 0];
+    else if (h < 180) [r1, g1, b1] = [0, c, x];
+    else if (h < 240) [r1, g1, b1] = [0, x, c];
+    else if (h < 300) [r1, g1, b1] = [x, 0, c];
+    else [r1, g1, b1] = [c, 0, x];
+    return [Math.round((r1 + m) * 255), Math.round((g1 + m) * 255), Math.round((b1 + m) * 255)];
+}
+
+function format(r: number, g: number, b: number): PaletteColor {
+    const [h, s, l] = rgbToHsl(r, g, b);
+    return {
+        hex: `#${[r, g, b].map((x) => x.toString(16).padStart(2, '0')).join('')}`,
+        rgb: `rgb(${r}, ${g}, ${b})`,
+        hsl: `hsl(${h.toFixed(1)}, ${(s * 100).toFixed(1)}%, ${(l * 100).toFixed(1)}%)`,
+    };
+}
+
+function fromHueShifts(base: [number, number, number], shifts: number[]): PaletteColor[] {
+    const [h, s, l] = base;
+    return shifts.map((shift) => {
+        const newH = (h + shift + 360) % 360;
+        const [r, g, b] = hslToRgb(newH, s, l);
+        return format(r, g, b);
+    });
+}
+
+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');
+
+    const [r, g, b] = hexToRgb(color);
+    const base = format(r, g, b);
+    const hsl = rgbToHsl(r, g, b);
+
+    let colors: PaletteColor[];
+    switch (type) {
+        case 'complementary':
+            colors = fromHueShifts(hsl, [0, 180]);
+            break;
+        case 'triadic':
+            colors = fromHueShifts(hsl, [0, 120, 240]);
+            break;
+        case 'analogous':
+            colors = fromHueShifts(hsl, [-60, -30, 0, 30, 60]);
+            break;
+        case 'tetradic':
+            colors = fromHueShifts(hsl, [0, 90, 180, 270]);
+            break;
+        case 'split-complementary':
+            colors = fromHueShifts(hsl, [0, 150, 210]);
+            break;
+        default:
+            throw new Error('Type must be one of: complementary, triadic, analogous, tetradic, split-complementary');
+    }
+
+    return { base, type, colors };
+}

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/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),
+    };
+}