@mantiq/helpers 0.0.1

package/src/async.ts

@@ -0,0 +1,209 @@
+/**
+ * Async utility functions — retry, sleep, parallel, timeout, debounce, throttle.
+ *
+ * @example
+ * ```ts
+ * await sleep('2s')
+ * const data = await retry(3, () => fetchApi(), '500ms')
+ * const results = await parallel([fn1, fn2, fn3], { concurrency: 2 })
+ * const result = await timeout(fetchData(), '5s')
+ * ```
+ */
+
+/** Parse a human-readable duration string to milliseconds */
+export function parseDuration(duration: string | number): number {
+  if (typeof duration === 'number') return duration
+  const match = duration.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/i)
+  if (!match) throw new Error(`Invalid duration: ${duration}`)
+  const value = parseFloat(match[1]!)
+  const unit = (match[2] ?? 'ms').toLowerCase()
+  switch (unit) {
+    case 'ms': return value
+    case 's': return value * 1000
+    case 'm': return value * 60_000
+    case 'h': return value * 3_600_000
+    case 'd': return value * 86_400_000
+    default: return value
+  }
+}
+
+/** Sleep for a given duration */
+export function sleep(duration: string | number): Promise<void> {
+  const ms = parseDuration(duration)
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Retry a function up to N times with optional delay between attempts.
+ * Supports exponential backoff via callback delay.
+ */
+export async function retry<T>(
+  times: number,
+  callback: (attempt: number) => T | Promise<T>,
+  delay?: string | number | ((attempt: number) => string | number),
+): Promise<T> {
+  let lastError: Error | undefined
+  for (let attempt = 1; attempt <= times; attempt++) {
+    try {
+      return await callback(attempt)
+    } catch (e) {
+      lastError = e instanceof Error ? e : new Error(String(e))
+      if (attempt < times && delay !== undefined) {
+        const d = typeof delay === 'function' ? delay(attempt) : delay
+        await sleep(d)
+      }
+    }
+  }
+  throw lastError
+}
+
+/**
+ * Run multiple async functions with optional concurrency limit.
+ * Like Promise.all but with a concurrency pool.
+ */
+export async function parallel<T>(
+  tasks: Array<() => Promise<T>>,
+  options?: { concurrency?: number },
+): Promise<T[]> {
+  const concurrency = options?.concurrency ?? Infinity
+
+  if (concurrency >= tasks.length) {
+    return Promise.all(tasks.map((fn) => fn()))
+  }
+
+  const results: T[] = new Array(tasks.length)
+  let nextIndex = 0
+
+  async function runNext(): Promise<void> {
+    while (nextIndex < tasks.length) {
+      const idx = nextIndex++
+      results[idx] = await tasks[idx]!()
+    }
+  }
+
+  const workers = Array.from(
+    { length: Math.min(concurrency, tasks.length) },
+    () => runNext(),
+  )
+
+  await Promise.all(workers)
+  return results
+}
+
+/** Wrap a promise with a timeout — rejects if it doesn't resolve in time */
+export function timeout<T>(
+  promise: Promise<T>,
+  duration: string | number,
+  message?: string,
+): Promise<T> {
+  const ms = parseDuration(duration)
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(message ?? `Operation timed out after ${ms}ms`))
+    }, ms)
+
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value) },
+      (error) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+/**
+ * Create a debounced version of a function.
+ * The function will only execute after `wait` ms of no calls.
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  fn: T,
+  wait: string | number,
+): T & { cancel(): void; flush(): void } {
+  const ms = parseDuration(wait)
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let lastArgs: any[] | null = null
+  let lastThis: any = null
+
+  const debounced = function (this: any, ...args: any[]) {
+    lastArgs = args
+    lastThis = this
+    if (timer) clearTimeout(timer)
+    timer = setTimeout(() => {
+      timer = null
+      fn.apply(lastThis, lastArgs!)
+      lastArgs = null
+    }, ms)
+  } as any
+
+  debounced.cancel = () => {
+    if (timer) clearTimeout(timer)
+    timer = null
+    lastArgs = null
+  }
+
+  debounced.flush = () => {
+    if (timer && lastArgs) {
+      clearTimeout(timer)
+      timer = null
+      fn.apply(lastThis, lastArgs)
+      lastArgs = null
+    }
+  }
+
+  return debounced
+}
+
+/**
+ * Create a throttled version of a function.
+ * The function will execute at most once per `wait` ms.
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  fn: T,
+  wait: string | number,
+): T & { cancel(): void } {
+  const ms = parseDuration(wait)
+  let lastCall = 0
+  let timer: ReturnType<typeof setTimeout> | null = null
+
+  const throttled = function (this: any, ...args: any[]) {
+    const now = Date.now()
+    const remaining = ms - (now - lastCall)
+
+    if (remaining <= 0) {
+      if (timer) { clearTimeout(timer); timer = null }
+      lastCall = now
+      fn.apply(this, args)
+    } else if (!timer) {
+      timer = setTimeout(() => {
+        lastCall = Date.now()
+        timer = null
+        fn.apply(this, args)
+      }, remaining)
+    }
+  } as any
+
+  throttled.cancel = () => {
+    if (timer) clearTimeout(timer)
+    timer = null
+    lastCall = 0
+  }
+
+  return throttled
+}
+
+/**
+ * Run tasks in a waterfall: each task receives the result of the previous.
+ */
+export async function waterfall<T>(
+  initial: T,
+  tasks: Array<(value: T) => T | Promise<T>>,
+): Promise<T> {
+  let result = initial
+  for (const task of tasks) {
+    result = await task(result)
+  }
+  return result
+}
+
+/** Defer a function to the next microtask */
+export function defer(fn: () => void): void {
+  queueMicrotask(fn)
+}

package/src/functions.ts

@@ -0,0 +1,153 @@
+/**
+ * Function utilities — tap, pipe, pipeline, once, memoize, benchmark.
+ *
+ * @example
+ * ```ts
+ * const user = tap(new User(), (u) => { u.name = 'John' })
+ * const result = pipe(5, double, addOne, toString) // '11'
+ * const getValue = once(() => expensiveComputation())
+ * const cachedFetch = memoize(fetchUser, { ttl: 60_000 })
+ * ```
+ */
+
+import { parseDuration } from './async.ts'
+
+/** Pass a value through a callback and return the original value */
+export function tap<T>(value: T, callback: (value: T) => void): T {
+  callback(value)
+  return value
+}
+
+/**
+ * Pipe a value through a sequence of functions (left to right).
+ * Each function receives the return value of the previous.
+ */
+export function pipe<A, B>(value: A, fn1: (a: A) => B): B
+export function pipe<A, B, C>(value: A, fn1: (a: A) => B, fn2: (b: B) => C): C
+export function pipe<A, B, C, D>(value: A, fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D): D
+export function pipe<A, B, C, D, E>(value: A, fn1: (a: A) => B, fn2: (b: B) => C, fn3: (c: C) => D, fn4: (d: D) => E): E
+export function pipe(value: any, ...fns: Array<(arg: any) => any>): any {
+  return fns.reduce((acc, fn) => fn(acc), value)
+}
+
+/**
+ * Pipeline: pass a value through an array of functions.
+ * Same as pipe but takes an array instead of variadic args.
+ */
+export function pipeline<T>(value: T, fns: Array<(value: any) => any>): any {
+  return fns.reduce((acc, fn) => fn(acc), value as any)
+}
+
+/** Compose functions right to left */
+export function compose<T>(...fns: Array<(arg: any) => any>): (arg: T) => any {
+  return (arg: T) => fns.reduceRight((acc, fn) => fn(acc), arg as any)
+}
+
+/**
+ * Create a function that executes only once.
+ * Subsequent calls return the first result.
+ */
+export function once<T extends (...args: any[]) => any>(fn: T): T {
+  let called = false
+  let result: any
+
+  return ((...args: any[]) => {
+    if (called) return result
+    called = true
+    result = fn(...args)
+    return result
+  }) as T
+}
+
+/**
+ * Memoize a function with optional TTL.
+ * Cache key is derived from arguments (JSON serialized).
+ */
+export function memoize<T extends (...args: any[]) => any>(
+  fn: T,
+  options?: { ttl?: string | number; maxSize?: number },
+): T & { cache: Map<string, any>; clear(): void } {
+  const ttl = options?.ttl ? parseDuration(options.ttl) : null
+  const maxSize = options?.maxSize ?? 1000
+  const cache = new Map<string, { value: any; expiresAt: number | null }>()
+
+  const memoized = ((...args: any[]) => {
+    const key = JSON.stringify(args)
+    const entry = cache.get(key)
+
+    if (entry) {
+      if (entry.expiresAt === null || Date.now() < entry.expiresAt) {
+        return entry.value
+      }
+      cache.delete(key)
+    }
+
+    const result = fn(...args)
+    const expiresAt = ttl ? Date.now() + ttl : null
+
+    // Evict oldest if at capacity
+    if (cache.size >= maxSize) {
+      const firstKey = cache.keys().next().value
+      if (firstKey !== undefined) cache.delete(firstKey)
+    }
+
+    cache.set(key, { value: result, expiresAt })
+    return result
+  }) as any
+
+  memoized.cache = cache
+  memoized.clear = () => cache.clear()
+
+  return memoized
+}
+
+/**
+ * Benchmark a function's execution time.
+ * Returns [result, durationMs].
+ */
+export async function benchmark<T>(
+  fn: () => T | Promise<T>,
+): Promise<[T, number]> {
+  const start = performance.now()
+  const result = await fn()
+  const duration = performance.now() - start
+  return [result, duration]
+}
+
+/** No-op function */
+export function noop(): void {}
+
+/** Identity function — returns its argument unchanged */
+export function identity<T>(value: T): T {
+  return value
+}
+
+/**
+ * Create a function that always returns the same value.
+ */
+export function constant<T>(value: T): () => T {
+  return () => value
+}
+
+/**
+ * Wrap a value in a callback — useful for lazy evaluation.
+ */
+export function lazy<T>(fn: () => T): { value: T } {
+  let computed = false
+  let result: T
+
+  return {
+    get value(): T {
+      if (!computed) {
+        result = fn()
+        computed = true
+      }
+      return result
+    },
+  }
+}
+
+/** Times: execute a callback N times, collect results */
+export function times<T>(n: number, fn: (index: number) => T): T[] {
+  return Array.from({ length: n }, (_, i) => fn(i))
+}

package/src/index.ts

@@ -0,0 +1,65 @@
+// @mantiq/helpers — public API exports
+
+// ── Laravel-equivalent utilities ─────────────────────────────────
+export { Str, Stringable } from './Str.ts'
+export { Arr } from './Arr.ts'
+export { Num } from './Num.ts'
+export { Collection, LazyCollection, collect, lazy, generate, range } from './Collection.ts'
+
+// ── Beyond-Laravel utilities ─────────────────────────────────────
+export { Result } from './Result.ts'
+export type { Result as ResultType } from './Result.ts'
+export { match } from './match.ts'
+export { Duration } from './Duration.ts'
+export { is } from './is.ts'
+
+// ── HTTP client ──────────────────────────────────────────────────
+export { Http, PendingRequest } from './Http.ts'
+export type { HttpResponse, HttpError, HttpMiddleware, RetryConfig } from './Http.ts'
+export { HttpFake } from './HttpFake.ts'
+export type { StubResponse, StubHandler } from './HttpFake.ts'
+
+// ── Async utilities ──────────────────────────────────────────────
+export {
+  parseDuration,
+  sleep,
+  retry,
+  parallel,
+  timeout,
+  debounce,
+  throttle,
+  waterfall,
+  defer,
+} from './async.ts'
+
+// ── Object utilities ─────────────────────────────────────────────
+export {
+  deepClone,
+  deepMerge,
+  deepFreeze,
+  deepEqual,
+  pick,
+  omit,
+  diff,
+  mapValues,
+  mapKeys,
+  filterObject,
+  invert,
+  isPlainObject,
+} from './objects.ts'
+
+// ── Function utilities ───────────────────────────────────────────
+export {
+  tap,
+  pipe,
+  pipeline,
+  compose,
+  once,
+  memoize,
+  benchmark,
+  noop,
+  identity,
+  constant,
+  lazy as lazyValue,
+  times,
+} from './functions.ts'

package/src/is.ts

@@ -0,0 +1,195 @@
+/**
+ * Runtime type guards and predicates.
+ *
+ * @example
+ * ```ts
+ * is.string('hello')          // true
+ * is.empty([])                // true
+ * is.plainObject({})          // true
+ * is.between(5, 1, 10)        // true
+ * is.email('user@example.com') // true
+ * ```
+ */
+export const is = {
+  // ── Type checks ─────────────────────────────────────────────────
+
+  string(value: unknown): value is string {
+    return typeof value === 'string'
+  },
+
+  number(value: unknown): value is number {
+    return typeof value === 'number' && !Number.isNaN(value)
+  },
+
+  integer(value: unknown): value is number {
+    return typeof value === 'number' && Number.isInteger(value)
+  },
+
+  float(value: unknown): value is number {
+    return typeof value === 'number' && !Number.isInteger(value) && !Number.isNaN(value)
+  },
+
+  boolean(value: unknown): value is boolean {
+    return typeof value === 'boolean'
+  },
+
+  function(value: unknown): value is Function {
+    return typeof value === 'function'
+  },
+
+  symbol(value: unknown): value is symbol {
+    return typeof value === 'symbol'
+  },
+
+  bigint(value: unknown): value is bigint {
+    return typeof value === 'bigint'
+  },
+
+  array(value: unknown): value is any[] {
+    return Array.isArray(value)
+  },
+
+  object(value: unknown): value is object {
+    return value !== null && typeof value === 'object'
+  },
+
+  plainObject(value: unknown): value is Record<string, any> {
+    if (value === null || typeof value !== 'object') return false
+    const proto = Object.getPrototypeOf(value)
+    return proto === Object.prototype || proto === null
+  },
+
+  date(value: unknown): value is Date {
+    return value instanceof Date && !isNaN(value.getTime())
+  },
+
+  regExp(value: unknown): value is RegExp {
+    return value instanceof RegExp
+  },
+
+  promise(value: unknown): value is Promise<any> {
+    return value instanceof Promise || (
+      value !== null && typeof value === 'object' && typeof (value as any).then === 'function'
+    )
+  },
+
+  map(value: unknown): value is Map<any, any> {
+    return value instanceof Map
+  },
+
+  set(value: unknown): value is Set<any> {
+    return value instanceof Set
+  },
+
+  error(value: unknown): value is Error {
+    return value instanceof Error
+  },
+
+  // ── Nullish checks ──────────────────────────────────────────────
+
+  null(value: unknown): value is null {
+    return value === null
+  },
+
+  undefined(value: unknown): value is undefined {
+    return value === undefined
+  },
+
+  nullish(value: unknown): value is null | undefined {
+    return value === null || value === undefined
+  },
+
+  defined<T>(value: T | null | undefined): value is T {
+    return value !== null && value !== undefined
+  },
+
+  // ── Emptiness ───────────────────────────────────────────────────
+
+  /** Check if a value is "empty" (null, undefined, '', [], {}, Map(0), Set(0)) */
+  empty(value: unknown): boolean {
+    if (value === null || value === undefined) return true
+    if (typeof value === 'string') return value.length === 0
+    if (Array.isArray(value)) return value.length === 0
+    if (value instanceof Map || value instanceof Set) return value.size === 0
+    if (typeof value === 'object') return Object.keys(value).length === 0
+    return false
+  },
+
+  /** Opposite of empty */
+  notEmpty(value: unknown): boolean {
+    return !is.empty(value)
+  },
+
+  // ── String format checks ────────────────────────────────────────
+
+  email(value: string): boolean {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+  },
+
+  url(value: string): boolean {
+    try { new URL(value); return true } catch { return false }
+  },
+
+  uuid(value: string): boolean {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+  },
+
+  json(value: string): boolean {
+    try { JSON.parse(value); return true } catch { return false }
+  },
+
+  numeric(value: string): boolean {
+    return /^-?\d+(\.\d+)?$/.test(value)
+  },
+
+  alpha(value: string): boolean {
+    return /^[a-zA-Z]+$/.test(value)
+  },
+
+  alphanumeric(value: string): boolean {
+    return /^[a-zA-Z0-9]+$/.test(value)
+  },
+
+  ip(value: string): boolean {
+    // IPv4
+    if (/^(\d{1,3}\.){3}\d{1,3}$/.test(value)) {
+      return value.split('.').every((n) => parseInt(n, 10) <= 255)
+    }
+    // IPv6 (simplified check)
+    return /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/.test(value)
+  },
+
+  // ── Number checks ───────────────────────────────────────────────
+
+  positive(value: number): boolean {
+    return value > 0
+  },
+
+  negative(value: number): boolean {
+    return value < 0
+  },
+
+  zero(value: number): boolean {
+    return value === 0
+  },
+
+  between(value: number, min: number, max: number): boolean {
+    return value >= min && value <= max
+  },
+
+  even(value: number): boolean {
+    return value % 2 === 0
+  },
+
+  odd(value: number): boolean {
+    return value % 2 !== 0
+  },
+
+  finite(value: number): boolean {
+    return Number.isFinite(value)
+  },
+
+  nan(value: unknown): boolean {
+    return Number.isNaN(value)
+  },
+}

package/src/match.ts

@@ -0,0 +1,78 @@
+/**
+ * Functional pattern matching — an expressive alternative to switch/if-else chains.
+ *
+ * @example
+ * ```ts
+ * const label = match(statusCode)
+ *   .when(200, 'OK')
+ *   .when(404, 'Not Found')
+ *   .when((code) => code >= 500, 'Server Error')
+ *   .otherwise('Unknown')
+ *
+ * const result = match(user.role)
+ *   .when('admin', () => getAdminDashboard())
+ *   .when('editor', () => getEditorPanel())
+ *   .when(['viewer', 'guest'], () => getPublicView())
+ *   .otherwise(() => redirect('/login'))
+ * ```
+ */
+
+type MatchPredicate<T> = T | T[] | ((value: T) => boolean)
+type MatchResult<R> = R | (() => R)
+
+interface MatchBuilder<T, R = never> {
+  /** Match against a value, array of values, or predicate function */
+  when<U>(predicate: MatchPredicate<T>, result: MatchResult<U>): MatchBuilder<T, R | U>
+  /** Provide a default value if nothing matched */
+  otherwise<U>(result: MatchResult<U>): R | U
+  /** Execute without a default — throws if nothing matched */
+  exhaustive(): R
+}
+
+class MatchImpl<T, R> implements MatchBuilder<T, R> {
+  private arms: Array<{ predicate: MatchPredicate<T>; result: MatchResult<any> }> = []
+  private matched = false
+  private matchedResult: any = undefined
+
+  constructor(private readonly value: T) {}
+
+  when<U>(predicate: MatchPredicate<T>, result: MatchResult<U>): MatchBuilder<T, R | U> {
+    if (this.matched) return this as any
+
+    if (this.test(predicate)) {
+      this.matched = true
+      this.matchedResult = typeof result === 'function' ? (result as () => U)() : result
+    } else {
+      this.arms.push({ predicate, result })
+    }
+
+    return this as any
+  }
+
+  otherwise<U>(result: MatchResult<U>): R | U {
+    if (this.matched) return this.matchedResult
+    return typeof result === 'function' ? (result as () => U)() : result
+  }
+
+  exhaustive(): R {
+    if (this.matched) return this.matchedResult
+    throw new Error(`No match found for value: ${JSON.stringify(this.value)}`)
+  }
+
+  private test(predicate: MatchPredicate<T>): boolean {
+    if (typeof predicate === 'function') {
+      return (predicate as (value: T) => boolean)(this.value)
+    }
+    if (Array.isArray(predicate)) {
+      return predicate.includes(this.value)
+    }
+    return Object.is(this.value, predicate)
+  }
+}
+
+/**
+ * Start a pattern match on a value.
+ */
+export function match<T>(value: T): MatchBuilder<T> {
+  return new MatchImpl(value)
+}