speexjs-core 0.7.0

package/SUMMARY.md

@@ -0,0 +1,321 @@
+# speedx-core — Ringkasan Fitur Lengkap
+
+> **Versi:** 0.4.4 | **License:** MIT | **Zero runtime dependencies**
+
+```
+npm install speedx-core
+```
+
+---
+
+## 1. CORE — Utility Functions
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `deepClone(value)` | Deep clone dengan circular reference, Date, RegExp, Map, Set support |
+| `deepMerge(...objects)` | Deep merge multiple objects, nested overwrite |
+| `deepEqual(a, b)` | Deep equality check — object, array, Date, Map, Set, RegExp |
+| `pipe(initial, ...fns)` | Function composition left-to-right |
+| `compose(...fns)` | Function composition right-to-left |
+| `debounce(fn, wait, options?)` | Debounce dengan leading/trailing/maxWait |
+| `throttle(fn, wait)` | Throttle execution |
+| `memoize(fn, resolver?)` | Memoize dengan custom cache key |
+| `retry(fn, options?)` | Retry dengan exponential backoff |
+| `noop()` | No-operation function |
+| `identity(value)` | Return input unchanged |
+| `once(fn)` | Execute function sekali doang |
+
+---
+
+## 2. MATH
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `add(a, b)` | Safe addition (0.1+0.2=0.3) |
+| `sub(a, b)` | Safe subtraction |
+| `mul(a, b)` | Safe multiplication |
+| `div(a, b)` | Safe division (throw kalo /0) |
+| `round(value, precision?)` | Round dengan floating-point fix |
+| `floor(value, precision?)` | Floor dengan precision |
+| `ceil(value, precision?)` | Ceil dengan precision |
+| `clamp(value, min, max)` | Clamp ke range |
+| `sum(values)` | Sum of array |
+| `average(values)` | Average (throw kalo kosong) |
+| `randomInt(min, max)` | Random integer dalam range |
+| `inRange(value, min, max)` | Cek apakah dalam range |
+| `median(values)` | Median dari array |
+| `stddev(values)` | Population standard deviation |
+| `sampleStddev(values)` | Sample standard deviation |
+| `percentile(values, p)` | Persentil (0-100) |
+| `correlation(x, y)` | Pearson correlation |
+| `formatCurrency(value, options?)` | Format mata uang locale-aware |
+
+---
+
+## 3. DATE & TIME
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `formatDate(date, format?)` | Format tanggal (YYYY-MM-DD, DD/MM/YYYY, dll) |
+| `parseDate(input)` | Parse string/number/Date |
+| `dateDiff(date1, date2)` | Selisih antar tanggal |
+| `addDays(date, days)` | Tambah/kurang hari |
+| `addMonths(date, months)` | Tambah/kurang bulan |
+| `addYears(date, years)` | Tambah/kurang tahun |
+| `startOfDay(date)` | Awal hari (00:00:00.000) |
+| `endOfDay(date)` | Akhir hari (23:59:59.999) |
+| `isWeekend(date)` | Sabtu atau Minggu |
+| `isLeapYear(year)` | Cek tahun kabisat |
+| `isBefore(date1, date2)`, `isAfter`, `isBetween` | Perbandingan tanggal |
+| `isBusinessDay(date)` | Senin-Jumat |
+| `addBusinessDays(date, days)` | Tambah hari kerja |
+| `calculateAge(birthDate)` | Hitung umur dalam tahun |
+| `timeAgo(date, options?)` | Waktu relatif ("5 detik yang lalu") |
+| `timeRemaining(target, options?)` | Waktu menuju tanggal masa depan |
+| `formatDuration(duration, options?)` | Format Duration object |
+| `toTimezone(date, offsetHours)` | Konversi date ke timezone tertentu |
+| `formatInTimezone(date, format, offset)` | Format tanggal di timezone tertentu |
+
+### Konstanta: `TIMEZONE_WIB` (7), `TIMEZONE_WITA` (8), `TIMEZONE_WIT` (9) 🇮🇩
+
+---
+
+## 4. COLLECTION — Array & Object Utilities
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `groupBy(items, keyFn)` | Grouping berdasarkan key |
+| `keyBy(items, keyFn)` | Indexing berdasarkan key |
+| `omit(obj, keys)` | Hapus keys tertentu |
+| `pick(obj, keys)` | Ambil keys tertentu |
+| `pluck(items, key)` | Extract property dari array |
+| `shuffle(items)` | Fisher-Yates shuffle |
+| `sample(items)` | Random element |
+| `sampleSize(items, size)` | N random elements |
+| `chunk(items, size)` | Potong array jadi chunk |
+| `sortBy(items, ...criteria)` | Multi-criteria sort |
+| `orderBy(items, key, dir?)` | Sort by key + direction |
+| `uniqueBy(items, keyFn)` | Unique by key function |
+| `flatten(items)` | Flatten satu level |
+| `uniq(items)` | Hapus duplicate |
+| `first(items)`, `last(items)` | Element pertama/terakhir |
+| `isEmpty(value)` | Cek kosong |
+| `topoSort(items)` | Topological sort (Kahn's algorithm) |
+| `slidingWindows(items, size, step?)` | Overlapping windows |
+| `tumblingWindows(items, size)` | Non-overlapping chunks |
+| `deepGet(obj, path, default?)` | Akses nested object pake path string |
+| `deepSet(obj, path, value)` | Set nested object pake path string |
+
+---
+
+## 5. STRING — Text Manipulation 🇮🇩
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `capitalize(str)` | Kapitalisasi huruf pertama |
+| `camelCase(str)` | Konversi ke camelCase |
+| `kebabCase(str)` | Konversi ke kebab-case |
+| `snakeCase(str)` | Konversi ke snake_case |
+| `pascalCase(str)` | Konversi ke PascalCase |
+| `truncate(str, max, suffix?)` | Potong string dengan suffix |
+| `template(str, data)` | Interpolasi string `{{key}}` |
+| `uuid()` | RFC 4122 v4 UUID |
+| `nanoid(size?, alphabet?)` | URL-safe random ID |
+| `escapeHtml(str)` | Escape HTML entities |
+| `unescapeHtml(str)` | Unescape HTML entities |
+| `levenshtein(a, b)` | Levenshtein distance |
+| `fuzzyMatch(str, query)` | Fuzzy string match |
+| `maskString(str, options?)` | Masking data sensitif |
+| `slugify(str)` | URL-friendly slug |
+| `formatBytes(bytes, options?)` | Format ukuran file ("1 MB") |
+| `randomString(length?)` | Random alphanumeric |
+| `randomBoolean()` | Random true/false |
+| `pluralize(count, singular)` | English pluralization |
+
+### 🇮🇩 Indonesian Locale
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `terbilang(value)` | **Angka ke kata** ("satu juta lima ratus ribu") |
+| `formatRupiah(value, options?)` | **Format Rupiah** ("Rp1.500.000") |
+
+---
+
+## 6. ASYNC
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `sleep(ms)` | Delay eksekusi |
+| `timeout(promise, ms)` | Reject kalo timeout |
+| `raceWithTimeout(promise, ms)` | Race promise vs timeout |
+| `allSettledMap(items, fn)` | Map dengan allSettled |
+| `parallelMap(items, fn, concurrency?)` | Concurrent map dengan limit |
+| `retryAsync(fn, options?)` | Retry dengan backoff |
+| `pipeline(initial, ...fns)` | Async function composition |
+| `deferred()` | Deferred promise |
+| `Queue(options?)` | Priority task queue dengan concurrency |
+| `Semaphore(concurrency)` | Semaphore buat resource control |
+| `memoizeAsync(fn, options?)` | Async memoize dengan TTL + stale-while-revalidate |
+
+---
+
+## 7. IO
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `parseCsv(input, options?)` | Parse CSV string |
+| `stringifyCsv(data, options?)` | Convert records ke CSV |
+| `safeJsonParse(input, default?)` | Safe JSON parse |
+| `env(name, default?)` | Baca environment variable |
+| `envInt(name, default?)` | Baca env var sebagai integer |
+| `envBool(name, default?)` | Baca env var sebagai boolean |
+
+---
+
+## 8. TYPE — Type Guards
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `isString`, `isNumber`, `isBoolean`, `isObject`, `isArray`, `isFunction` | Type checks |
+| `isDate`, `isRegExp`, `isMap`, `isSet`, `isPromise` | Instance checks |
+| `isNull`, `isUndefined`, `isNil` | Nullish checks |
+| `isEmpty(value)` | Empty/blank check |
+| `assertDefined(value, msg?)` | Runtime assertion |
+| `assertType(value, guard, msg?)` | Type assertion |
+| `ensureArray(value)` / `castArray(value)` | Wrap in array |
+| `getType(value)` | String type name |
+
+---
+
+## 9. CRYPTO
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `hash(str)` | djb2 hash (32-bit) |
+| `simpleHash(str)` | Simple hex hash |
+| `randomHex(size?)` | Random hex string |
+| `base64Encode(str)` | Base64 encode (UTF-8 safe) |
+| `base64Decode(str)` | Base64 decode |
+| `generateToken(bytes?)` | Crypto-random hex token |
+| `generateOTP(length?)` | Numeric OTP |
+| `xorCipher(str, key)` | ⚠️ XOR obfuscation (BUKAN encryption) |
+| `checksum(input)` | CRC-like checksum |
+| `constantTimeEqual(a, b)` | Timing-safe string comparison |
+
+---
+
+## 10. PATH
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `join(...segments)` | Gabung path segments |
+| `resolve(...segments)` | Resolve ke absolute path |
+| `basename(p, ext?)` | Ambil filename |
+| `dirname(p)` | Ambil directory |
+| `extname(p)` | Ambil extension |
+| `normalize(p)` | Normalize path |
+| `isAbsolute(p)` | Cek absolute path |
+| `relative(from, to)` | Relative path |
+| `parse(p)` | Parse path jadi components |
+| `format(parsed)` | Format parsed path |
+
+---
+
+## 11. VALIDATION — 🇮🇩 Khusus Indonesia
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `isNIK(value)` | **Validasi NIK** 16 digit + tanggal lahir |
+| `parseNIK(value)` | **Extract data dari NIK** — gender, provinsi, tanggal lahir |
+| `isNPWP(value)` | **Validasi NPWP** + checksum |
+| `isPlatNomor(value)` | **Validasi plat kendaraan** RI (B 1234 CD) |
+| `isPhone(value, country?)` | **Validasi nomor HP Indonesia** |
+| `isKodepos(value)` | **Validasi kode pos** 5 digit |
+| `isNoRekening(value)` | **Validasi nomor rekening** bank (8-16 digit) |
+| `isEmail(value)` | Validasi email RFC-compliant |
+| `isURL(value)` | Validasi URL (http/https) |
+
+---
+
+## 12. ERROR — Typed Errors
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `createError(code, message, options?)` | Bikin typed error dengan HTTP status |
+| `isTypedError(error)` | Type guard |
+| `TypedError` | Class dengan code + status + details + toJSON |
+| `MultiError` | Kumpulin multiple errors |
+| `collectErrors(fn)` | Jalanin function, kumpulin error yang ke-throw |
+
+### Error Codes: `BAD_REQUEST` (400), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404), `CONFLICT` (409), `VALIDATION_ERROR` (422), `TOO_MANY` (429), `INTERNAL` (500), `BAD_GATEWAY` (502), `UNAVAILABLE` (503)
+
+---
+
+## 13. LOGGER — Structured Logging
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `Logger(options?)` | Structured logger dengan level |
+| `logger` | Default singleton (info level) |
+| `createConsoleTransport(options?)` | Colored console output |
+| `createJsonTransport(options?)` | JSON-line output |
+| `createFileTransport(filename, options?)` | File appender |
+| `createBufferedTransport(transport, options?)` | Batched transport |
+
+### Log Levels: `debug`, `info`, `warn`, `error`
+
+---
+
+## 14. COLOR — Color Utilities
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `hexToRgb(hex)` | Convert hex ke RGB object |
+| `rgbToHex(r, g, b)` | Convert RGB ke hex string |
+| `lighten(hex, percent)` | Terangin warna (0-100%) |
+| `darken(hex, percent)` | Gelapin warna (0-100%) |
+| `contrastRatio(hex1, hex2)` | WCAG contrast ratio (1-21) |
+| `meetsWCAG(hex1, hex2, level?)` | Cek WCAG compliance (AA/AAA) |
+
+---
+
+## 15. DEP-EXRAY — Dependency Health Scanner
+
+| Fungsi | Deskripsi |
+|--------|-----------|
+| `scanProject(config)` | Scan project buat bloat + security issues |
+| `generateReport(result, json?)` | Generate scan report |
+| `analyzeUsage(projectPath, packageName)` | Deteksi pemakaian dependency |
+| `KNOWN_MAPPINGS` | 11 known replacement mappings |
+| `KNOWN_CVES` | CVE database untuk known packages |
+
+**CLI:** `npx dep-exray .`
+
+---
+
+## Statistik Test
+
+| Module | Test Files | Tests |
+|--------|-----------|-------|
+| Semua module | 19 | **828** ✅ |
+
+---
+
+## Referensi Cepat
+
+```bash
+npm install speedx-core
+
+# Import semua module
+import { deepClone, deepEqual, pipe } from 'speedx-core'
+import { formatDate, timeAgo, TIMEZONE_WIB } from 'speedx-core/date'
+import { groupBy, topoSort, deepGet } from 'speedx-core/collection'
+import { terbilang, formatRupiah, formatBytes } from 'speedx-core/string'
+import { Queue, Semaphore } from 'speedx-core/async'
+import { isNIK, isNPWP, isPhone } from 'speedx-core/validation'
+import { createError, MultiError } from 'speedx-core/error'
+import { Logger } from 'speedx-core/logger'
+import { hexToRgb, lighten, contrastRatio } from 'speedx-core/color'
+import { median, stddev, formatCurrency } from 'speedx-core/math'
+import { scanProject } from 'speedx-core/dep-exray'
+```

package/dist/async/index.d.ts

@@ -0,0 +1,232 @@
+import { RetryOptions } from '../core/index.js';
+
+interface QueueOptions {
+    concurrency?: number;
+}
+/**
+ * Priority-based async task queue with concurrency control.
+ *
+ * @example
+ * const queue = new Queue({ concurrency: 2 })
+ * const result = await queue.add(() => fetch('/api/data'))
+ */
+declare class Queue<T = unknown> {
+    private _tasks;
+    private _running;
+    private _paused;
+    private _idleResolve;
+    private _maxConcurrency;
+    constructor(options?: QueueOptions);
+    get pending(): number;
+    get running(): number;
+    add<R>(task: () => Promise<R>, options?: {
+        priority?: number;
+    }): Promise<R>;
+    pause(): void;
+    resume(): void;
+    clear(): void;
+    onIdle(): Promise<void>;
+    private _process;
+}
+
+/**
+ * Semaphore for controlling concurrent access to a resource.
+ *
+ * @example
+ * const sem = new Semaphore(2)
+ * await sem.use(async () => {
+ *   // Only 2 callers at a time
+ *   await doSomething()
+ * })
+ */
+declare class Semaphore {
+    private _available;
+    private _waiting;
+    constructor(concurrency: number);
+    get available(): number;
+    acquire(): Promise<() => void>;
+    use<T>(fn: () => Promise<T>): Promise<T>;
+    private _release;
+}
+
+/**
+ * Options for memoizeAsync.
+ */
+interface MemoizeAsyncOptions {
+    /** Time-to-live in milliseconds (default: 60000) */
+    ttl?: number;
+    /** Return stale value while fetching fresh data (default: false) */
+    staleWhileRevalidate?: boolean;
+    /** Maximum number of cached entries (default: 100) */
+    maxSize?: number;
+    /** Custom cache key resolver. Defaults to JSON.stringify of args. */
+    resolver?: (...args: unknown[]) => string;
+}
+interface CacheEntry {
+    value: unknown;
+    timestamp: number;
+    promise?: Promise<unknown>;
+}
+/**
+ * Memoizes an async function with TTL, stale-while-revalidate, and bounded cache.
+ *
+ * @example
+ * const fetchData = memoizeAsync(async (id: string) => {
+ *   return await api.fetch(id)
+ * }, { ttl: 5000, staleWhileRevalidate: true })
+ *
+ * const data = await fetchData('123') // cached for 5s
+ * const data2 = await fetchData('123') // returns cached, refreshes in bg
+ */
+declare function memoizeAsync<T extends (...args: unknown[]) => Promise<unknown>>(fn: T, options?: MemoizeAsyncOptions): T & {
+    cache: Map<string, CacheEntry>;
+    clear: () => void;
+};
+
+/**
+ * Rate limiter that restricts the number of requests within a sliding time window.
+ *
+ * @example
+ * const limiter = new RateLimiter({ maxRequests: 5, perWindow: 1000 })
+ * if (limiter.tryAcquire()) {
+ *   // Allowed
+ * }
+ *
+ * @example
+ * const limiter = new RateLimiter({ maxRequests: 2, perWindow: 1000 })
+ * await limiter.acquire()
+ * await limiter.acquire()
+ * // Third call waits until the window rolls
+ */
+declare class RateLimiter {
+    private _maxRequests;
+    private _perWindow;
+    private _timestamps;
+    constructor(options: {
+        maxRequests: number;
+        perWindow: number;
+    });
+    private _prune;
+    /**
+     * Check if a request is allowed without waiting.
+     */
+    tryAcquire(): boolean;
+    /**
+     * Wait until a request is allowed.
+     */
+    acquire(): Promise<void>;
+    /**
+     * Current number of pending requests in the window.
+     */
+    get pending(): number;
+}
+
+/**
+ * Mutex for exclusive access to a critical section.
+ *
+ * @example
+ * const mutex = new Mutex()
+ * const release = await mutex.acquire()
+ * try {
+ *   // Exclusive access
+ * } finally {
+ *   release()
+ * }
+ *
+ * @example
+ * const mutex = new Mutex()
+ * const result = await mutex.use(async () => {
+ *   return await fetch('/api/data')
+ * })
+ */
+declare class Mutex {
+    private _locked;
+    private _waiting;
+    /**
+     * Acquire the lock. Returns a release function to be called when done.
+     */
+    acquire(): Promise<() => void>;
+    /**
+     * Run a function with the lock held and automatically release it.
+     */
+    use<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Whether the mutex is currently locked.
+     */
+    get locked(): boolean;
+    private _release;
+}
+
+/**
+ * Process an array of items in sequential batches.
+ *
+ * @example
+ * const items = [1, 2, 3, 4, 5]
+ * const results = await batch(items, 2, async (batch) => {
+ *   return batch.map(n => n * 2)
+ * })
+ * // results = [2, 4, 6, 8, 10]
+ */
+declare function batch<T, R>(items: T[], batchSize: number, fn: (batch: T[]) => Promise<R[]>): Promise<R[]>;
+
+/**
+ * Execute async tasks in sequence, passing each result to the next task.
+ *
+ * @example
+ * const result = await waterfall([
+ *   async (n: number) => n + 1,
+ *   async (n: number) => n * 2,
+ *   async (n: number) => `Result: ${n}`,
+ * ], 1)
+ * // result = "Result: 4"
+ *
+ * @example
+ * const result = await waterfall([
+ *   async () => fetch('/api/data').then(r => r.json()),
+ *   async (data) => process(data),
+ * ])
+ */
+declare function waterfall(tasks: Array<(arg: any) => Promise<any>>, initial?: any): Promise<any>;
+
+/**
+ * Delays execution for the given number of milliseconds.
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Rejects a promise if it does not resolve within the specified timeout.
+ */
+declare function timeout<T>(promise: Promise<T>, ms: number, errorMessage?: string): Promise<T>;
+/**
+ * Races a promise against a timeout, returning 'timeout' if the timer wins.
+ */
+declare function raceWithTimeout<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'>;
+/**
+ * Maps over an array with an async function, using Promise.allSettled.
+ * Returns an array of PromiseSettledResult.
+ */
+declare function allSettledMap<T, R>(items: T[], fn: (item: T) => Promise<R>): Promise<PromiseSettledResult<R>[]>;
+/**
+ * Maps over an array with an async function, limiting concurrency.
+ *
+ * @param concurrency - Maximum number of concurrent operations (default Infinity)
+ */
+declare function parallelMap<T, R>(items: T[], fn: (item: T) => Promise<R>, concurrency?: number): Promise<R[]>;
+/**
+ * Retries an async function with exponential backoff.
+ */
+declare function retryAsync<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+/**
+ * Composes async functions, passing the result of each to the next.
+ */
+declare function pipeline<T>(initial: T, ...fns: Array<(arg: T) => Promise<T>>): Promise<T>;
+/**
+ * Creates a deferred promise with external resolve and reject methods.
+ */
+declare function deferred<T>(): Deferred<T>;
+interface Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+}
+
+export { type Deferred, type MemoizeAsyncOptions, Mutex, Queue, type QueueOptions, RateLimiter, Semaphore, allSettledMap, batch, deferred, memoizeAsync, parallelMap, pipeline, raceWithTimeout, retryAsync, sleep, timeout, waterfall };