@take-out/helpers 0.0.28

package/src/index.ts

@@ -0,0 +1,103 @@
+export * from './constants'
+export * from './emitter'
+
+// array
+export * from './array/fuzzy'
+export * from './array/getRandomItem'
+export * from './array/takeLast'
+export * from './array/uniqBy'
+
+// assert
+export * from './assert'
+
+// async
+export * from './async/abortable'
+export * from './async/asyncContext'
+export * from './async/idle'
+export * from './async/interval'
+export * from './async/isAborted'
+export * from './async/sleep'
+export * from './async/useAsync'
+export * from './async/useAsyncEffect'
+export * from './async/useLazyMount'
+export * from './async/useLazyValue'
+
+// browser
+export * from './browser/clearIndexedDB'
+export * from './browser/isActiveElementFormField'
+export * from './browser/localStorage'
+export * from './browser/openPopup'
+
+// debug
+export * from './debug/debugLog'
+export * from './debug/debugUseState'
+
+// ensure
+export * from './ensure/ensure'
+export * from './ensure/ensureOne'
+
+// error
+export * from './error/errors'
+
+// files
+
+// function
+export * from './function/emptyFn'
+export * from './function/identityFn'
+export * from './function/throttle'
+
+// global
+export * from './global/globalEffect'
+export * from './global/globalValue'
+
+// number
+export * from './number/formatNumber'
+
+// object
+export * from './object/decorateObject'
+export * from './object/isEqualDeep'
+export { isEqualDeepLite } from './object/isEqualDeep'
+export * from './object/isEqualIdentity'
+export * from './object/isEqualJSON'
+export * from './object/isEqualNever'
+export * from './object/mapObject'
+export * from './object/object'
+export * from './object/objectUniqueKey'
+
+// react
+export * from './react/createGlobalContext'
+export * from './react/getCurrentComponentStack'
+
+// server
+export * from './server/ensureEnv'
+export * from './server/getHeaders'
+export * from './server/prettyPrintRequest'
+export * from './server/prettyPrintResponse'
+export * from './server/streamToString'
+
+// string
+export * from './string/dedent'
+export * from './string/ellipsis'
+export * from './string/hash'
+export * from './string/insertAtIndex'
+export * from './string/pickLast'
+export * from './string/pluralize'
+export * from './string/randomId'
+export * from './string/slugify'
+export * from './string/truncateList'
+
+// time
+export * from './time/formatDate'
+export * from './time/formatDateRelative'
+export * from './time/time'
+
+// types
+export type * from './types/NullToOptional'
+export type * from './types/object'
+export type * from './types/react'
+export type * from './types/timer'
+export type * from './types/tuple'
+
+// url
+export * from './url/urlSanitize'
+export * from './url/urlValidate'

package/src/number/formatNumber.ts

@@ -0,0 +1,40 @@
+export interface FormatNumberOptions {
+  locale?: string
+  maximumFractionDigits?: number
+  minimumFractionDigits?: number
+  forceCompact?: boolean
+}
+
+export function formatNumber(value: number, options: FormatNumberOptions = {}): string {
+  const {
+    locale = 'en-US',
+    maximumFractionDigits = 1,
+    minimumFractionDigits = 0,
+    forceCompact = false,
+  } = options
+
+  if (!forceCompact && Math.abs(value) < 1000) {
+    return new Intl.NumberFormat(locale, {
+      maximumFractionDigits,
+      minimumFractionDigits,
+    }).format(value)
+  }
+
+  return new Intl.NumberFormat(locale, {
+    notation: 'compact',
+    compactDisplay: 'short',
+    maximumFractionDigits,
+    minimumFractionDigits,
+  }).format(value)
+}
+
+export function abbreviateNumber(value: number): string {
+  return formatNumber(value, { maximumFractionDigits: 1 })
+}
+
+export function formatCount(value: number): string {
+  return formatNumber(value, {
+    maximumFractionDigits: 0,
+    forceCompact: value >= 1000,
+  })
+}

package/src/object/decorateObject.ts

@@ -0,0 +1,16 @@
+export function decorateObject<T extends Record<string, any>>(
+  obj: T,
+  decorator: (fn: Function) => Function
+): T {
+  const decorated = {} as T
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (typeof value === 'function') {
+      ;(decorated as any)[key] = decorator(value)
+    } else {
+      ;(decorated as any)[key] = value
+    }
+  }
+
+  return decorated
+}

package/src/object/isEqualDeep.ts

@@ -0,0 +1,7 @@
+import { dequal } from 'dequal'
+import { dequal as dequalLite } from 'dequal/lite'
+
+type EqualityFn = (foo: any, bar: any) => boolean
+
+export const isEqualDeep = dequal as any as EqualityFn
+export const isEqualDeepLite = dequalLite as any as EqualityFn

package/src/object/isEqualIdentity.ts

@@ -0,0 +1 @@
+export const isEqualIdentity = (a: any, b: any): boolean => a === b

package/src/object/isEqualJSON.ts

@@ -0,0 +1,2 @@
+export const isEqualJSON = (a: any, b: any): boolean =>
+  JSON.stringify(a) === JSON.stringify(b)

package/src/object/isEqualNever.ts

@@ -0,0 +1 @@
+export const isEqualNever = (a: any, b: any) => false

package/src/object/mapObject.ts

@@ -0,0 +1,14 @@
+export function mapObject<T extends Record<string, any>, R>(
+  obj: T,
+  fn: <K extends keyof T>(value: T[K], key: K) => R
+): { [K in keyof T]: R } {
+  const result = {} as { [K in keyof T]: R }
+
+  for (const key in obj) {
+    if (Object.hasOwn(obj, key)) {
+      result[key] = fn(obj[key], key)
+    }
+  }
+
+  return result
+}

package/src/object/object.ts

@@ -0,0 +1,33 @@
+import type {
+  EntriesToObject,
+  EntriesType,
+  ObjectEntries,
+  ObjectType,
+} from '../types/object'
+
+export function postfixObjKeys<A extends { [key: string]: string }, B extends string>(
+  obj: A,
+  postfix: B
+): {
+  [Key in `${keyof A extends string ? keyof A : never}${B}`]: string
+} {
+  return Object.fromEntries(
+    Object.entries(obj).map(([k, v]) => [`${k}${postfix}`, v])
+  ) as any
+}
+
+export function objectFromEntries<ARR_T extends EntriesType>(
+  arr: ARR_T
+): EntriesToObject<ARR_T> {
+  return Object.fromEntries(arr) as EntriesToObject<ARR_T>
+}
+
+export function objectKeys<O extends Object>(obj: O) {
+  return Object.keys(obj) as Array<keyof O>
+}
+
+export function objectEntries<OBJ_T extends ObjectType>(
+  obj: OBJ_T
+): ObjectEntries<OBJ_T> {
+  return Object.entries(obj) as ObjectEntries<OBJ_T>
+}

package/src/object/objectUniqueKey.ts

@@ -0,0 +1,12 @@
+const w = new WeakMap<any, string>()
+
+export const objectUniqueKey = (item: any): string => {
+  return (
+    w.get(item) ??
+    (() => {
+      const k = `${Math.random()}`
+      w.set(item, k)
+      return k
+    })()
+  )
+}

package/src/react/createGlobalContext.ts

@@ -0,0 +1,9 @@
+import { type Context, createContext } from 'react'
+import { globalValue } from '../global/globalValue'
+
+// create or retrieve a React context that is stored on `globalThis`.
+// this ensures a stable singleton that survives hot-reloads during development.
+
+export function createGlobalContext<T>(key: string, defaultValue: T): Context<T> {
+  return globalValue(key, () => createContext<T>(defaultValue))
+}

package/src/react/getCurrentComponentStack.ts

@@ -0,0 +1,56 @@
+import React from 'react'
+
+export const getCurrentComponentStack = (format?: 'short'): string => {
+  if (process.env.NODE_ENV === 'development') {
+    const stack =
+      // @ts-expect-error its ok
+      React[
+        '__CLIENT_INTERNALS_DO_NOT_USE_OR_WARN_USERS_THEY_CANNOT_UPGRADE'
+      ].getCurrentStack()
+
+    if (format === 'short') {
+      return formatStackToShort(stack)
+    }
+
+    return stack
+  }
+
+  return `(prod, no stack)`
+}
+
+const formatStackToShort = (stack: string): string => {
+  if (process.env.NODE_ENV === 'development') {
+    const lines = stack
+      // huge stack was causing issues
+      .slice(0, 6000)
+      .split('\n')
+
+    const componentNames: string[] = []
+
+    for (const line of lines) {
+      // Extract component names from patterns like "at ComponentName ("
+      // Also handle cases like "at Route((chat))" or "Route() ("
+      const match = line.match(/\s*at\s+([A-Z][a-zA-Z0-9_]*)\s*\(/)
+      if (match) {
+        const componentName = match[1]
+        // Filter out framework internals and keep user components
+        if (
+          componentName &&
+          componentName !== 'Array' &&
+          componentName !== 'Root' &&
+          componentName !== 'Route'
+        ) {
+          componentNames.push(componentName)
+          if (componentNames.length > 10) {
+            // avoid too many
+            break
+          }
+        }
+      }
+    }
+
+    return componentNames.join(' < ')
+  }
+
+  return stack
+}

package/src/server/ensureEnv.ts

@@ -0,0 +1,18 @@
+// note doesnt work on client because Vite injects process.env
+
+export function ensureEnv(name: string, defaultValue?: string): string {
+  if (typeof process.env[name] === 'string') {
+    return process.env[name] || defaultValue || ''
+  }
+  if (defaultValue) {
+    return defaultValue
+  }
+  if (process.env.ALLOW_MISSING_ENV) {
+    return ''
+  }
+  if (process.env.NODE_ENV === 'development' || process.env.NODE_ENV === 'test') {
+    console.warn(` - missing env ${name}`)
+    return ''
+  }
+  throw new Error(`Environment variable ${name} not set.`)
+}

package/src/server/getHeaders.ts

@@ -0,0 +1,7 @@
+export function getHeaders(headers: Headers): Record<string, unknown> {
+  const headersOut: Record<string, unknown> = {}
+  headers.forEach((value, key) => {
+    headersOut[key] = value
+  })
+  return headersOut
+}

package/src/server/prettyPrintRequest.ts

@@ -0,0 +1,16 @@
+// import { getHeaders } from './getHeaders'
+// import { streamToString } from './streamToString'
+
+export async function prettyPrintRequest(request: Request): Promise<void> {
+  // one bug potentially, clone casues: Unhandled rejection at [object Promise] TypeError: unusable
+  // const request = requestIn.clone()
+
+  // const requestDetails = {
+  //   method: request.method,
+  //   url: request.url,
+  //   headers: getHeaders(requestIn.headers),
+  //   body: request.body ? await streamToString(request.body) : null,
+  // }
+
+  console.info(request)
+}

package/src/server/prettyPrintResponse.ts

@@ -0,0 +1,15 @@
+import { getHeaders } from './getHeaders'
+import { streamToString } from './streamToString'
+
+export async function prettyPrintResponse(responseIn: Response): Promise<void> {
+  const response = responseIn.clone()
+
+  const responseDetails = {
+    status: response.status,
+    statusText: response.statusText,
+    headers: getHeaders(responseIn.headers),
+    body: response.body ? await streamToString(response.body) : null,
+  }
+
+  console.info(responseDetails)
+}

package/src/server/streamToString.ts

@@ -0,0 +1,19 @@
+export async function streamToString(stream: ReadableStream): Promise<string> {
+  const reader = stream.getReader()
+  const decoder = new TextDecoder()
+  let result = ''
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      result += decoder.decode(value, { stream: true })
+    }
+  } catch (error) {
+    console.error('Error reading the stream:', error)
+  } finally {
+    reader.releaseLock()
+  }
+
+  return result
+}

package/src/server-only.ts

@@ -0,0 +1,3 @@
+if (process.env.VITE_ENVIRONMENT !== 'ssr') {
+  throw new Error(`This file should only be imported on the server!`)
+}

package/src/string/dedent.ts

@@ -0,0 +1,30 @@
+export function dedent(strings: TemplateStringsArray | string, ...values: any[]): string {
+  // If called as a normal function with a string
+  if (typeof strings === 'string') {
+    return dedentString(strings)
+  }
+
+  // If called as a template tag
+  const result = strings.reduce((acc, str, i) => {
+    return acc + str + (values[i] !== undefined ? values[i] : '')
+  }, '')
+
+  return dedentString(result)
+}
+
+function dedentString(text: string): string {
+  let lines = text.replace(/^\n/, '').split('\n')
+
+  // Find common indentation from non-empty lines
+  const indentLengths = lines
+    .filter((line) => line.trim().length > 0)
+    .map((line) => line.match(/^[ \t]*/)?.[0].length ?? 0)
+
+  const minIndent = indentLengths.length > 0 ? Math.min(...indentLengths) : 0
+
+  if (minIndent > 0) {
+    lines = lines.map((line) => line.slice(minIndent))
+  }
+
+  return lines.join('\n').trimEnd()
+}

package/src/string/ellipsis.ts

@@ -0,0 +1,9 @@
+export const ellipsis = (str: string, maxLength: number): string => {
+  // avoid running replace on huge string if its long
+  const shortened = str.length > 500 ? str.slice(0, 500) : str
+  const cleaned = shortened.replace(/\s+/g, ' ').trim()
+  if (cleaned.length > maxLength) {
+    return cleaned.substring(0, maxLength - 3) + '…'
+  }
+  return cleaned
+}

package/src/string/hash.ts

@@ -0,0 +1,19 @@
+// simple reversible encoding - alphanumeric only
+
+export function hashString(str: string) {
+  // convert to hex (0-9a-f)
+  return str
+    .split('')
+    .map((c) => c.charCodeAt(0).toString(16).padStart(2, '0'))
+    .join('')
+}
+
+export function unhashString(encoded: string) {
+  // convert from hex back to string
+  return (
+    encoded
+      .match(/.{2}/g)
+      ?.map((h) => String.fromCharCode(parseInt(h, 16)))
+      .join('') || ''
+  )
+}

package/src/string/insertAtIndex.ts

@@ -0,0 +1,7 @@
+export function insertAtIndex(original: string, index: number, toInsert: string): string {
+  if (index < 0 || index > original.length) {
+    throw new Error('Index out of bounds')
+  }
+
+  return original.slice(0, index) + toInsert + original.slice(index)
+}

package/src/string/pickLast.ts

@@ -0,0 +1,10 @@
+export function pickLast<T extends string | null | undefined>(
+  a: T,
+  b: T
+): T extends string ? string : T {
+  if (a == null && b == null) return undefined as any
+  if (a == null) return b as any
+  if (b == null) return a as any
+
+  return (b.localeCompare(a) > 0 ? b : a) as any
+}

package/src/string/pluralize.native.ts

@@ -0,0 +1,6 @@
+import type { PluralizeFn } from './pluralize'
+
+export const pluralize: PluralizeFn = (count, singular, plural) => {
+  console.info('pluralize.native.ts: TODO', count, singular, plural)
+  return plural
+}

package/src/string/pluralize.ts

@@ -0,0 +1,21 @@
+let pluralRules = new Intl.PluralRules('en-US')
+
+export function pluralize(count: number, singular: string, plural: string) {
+  const grammaticalNumber = pluralRules.select(count)
+  switch (grammaticalNumber) {
+    case 'one':
+      return `${count} ${singular}`
+    case 'other':
+      return `${count} ${plural}`
+    default:
+      throw new Error(
+        `Can't pluralize: ${grammaticalNumber} for ${count} / ${singular} / ${plural}`
+      )
+  }
+}
+
+export function setPluralizeLocale(locale: Intl.LocalesArgument) {
+  pluralRules = new Intl.PluralRules(locale)
+}
+
+export type PluralizeFn = typeof pluralize

package/src/string/randomId.ts

@@ -0,0 +1 @@
+export const randomId = (): string => Math.random().toString(36).slice(2)

package/src/string/slugify.ts

@@ -0,0 +1,7 @@
+export const slugify = (input: string): string =>
+  input
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-') // convert spaces and underscores to dashes
+    .replace(/[^a-z0-9-]/g, '') // remove all non-alphanumeric except dashes
+    .replace(/-+/g, '-') // replace multiple dashes with single dash
+    .replace(/^-|-$/g, '') // remove leading/trailing dashes

package/src/string/truncateList.ts

@@ -0,0 +1,28 @@
+/**
+ * Truncates a list of strings to show only the first N items,
+ * with a "+X" indicator for any remaining items.
+ *
+ * @param items - Array of strings to truncate
+ * @param maxItems - Maximum number of items to show before truncating
+ * @param separator - String to use between items (default: ', ')
+ * @returns Formatted string with truncation indicator if needed
+ *
+ * @example
+ * truncateList(['jon', 'sal', 'bob', 'ted'], 3) // "jon, sal, bob +1"
+ * truncateList(['alice', 'bob'], 3) // "alice, bob"
+ * truncateList(['a', 'b', 'c', 'd', 'e'], 2) // "a, b +3"
+ */
+export const truncateList = (
+  items: string[],
+  maxItems: number,
+  separator: string = ', '
+): string => {
+  if (items.length <= maxItems) {
+    return items.join(separator)
+  }
+
+  const visibleItems = items.slice(0, maxItems)
+  const remainingCount = items.length - maxItems
+
+  return `${visibleItems.join(separator)} +${remainingCount}`
+}

package/src/time/formatDate.tsx

@@ -0,0 +1,47 @@
+const currentYear = new Date().getFullYear()
+
+export function formatDate(
+  date: Date,
+  options?: { daySuffix?: boolean }
+): [string, string] | [string, string, string] {
+  const months = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+  ]
+
+  const day = date.getDate()
+  const month = months[date.getMonth()]
+  const year = date.getFullYear()
+
+  const dayString = options?.daySuffix ? getOrdinalSuffix(day) : `${day}`
+
+  if (year === currentYear) {
+    return [`${month}`, dayString]
+  }
+
+  return [`${month}`, dayString, `${year}`]
+}
+
+const getOrdinalSuffix = (n: number) => {
+  if (n >= 11 && n <= 13) return 'th'
+  switch (n % 10) {
+    case 1:
+      return 'st'
+    case 2:
+      return 'nd'
+    case 3:
+      return 'rd'
+    default:
+      return 'th'
+  }
+}

package/src/time/formatDateRelative.ts

@@ -0,0 +1,72 @@
+/**
+ * Formats a date relative to the current time:
+ * - If within the last month: just show time (e.g., "5:50pm")
+ * - If this year but older than a month: show "Jun 2, 5:50pm"
+ * - If before this year: show "Jun 2, 2025, 5:50pm"
+ */
+
+function lowerCaseTime(formatted: string): string {
+  return formatted.replace(/\s?(AM|PM)/g, (_, ampm) => ampm.toLowerCase())
+}
+
+export function formatDateRelative(date: Date | string | number): string {
+  const messageDate = new Date(date)
+  const now = new Date()
+
+  // if it's today
+  const isToday =
+    messageDate.getFullYear() === now.getFullYear() &&
+    messageDate.getMonth() === now.getMonth() &&
+    messageDate.getDate() === now.getDate()
+
+  // check if it's within the last month
+  const oneMonthAgo = new Date(now)
+  oneMonthAgo.setMonth(oneMonthAgo.getMonth() - 1)
+  const isWithinLastMonth = messageDate >= oneMonthAgo
+
+  // if it's this year
+  const isThisYear = messageDate.getFullYear() === now.getFullYear()
+
+  if (isToday) {
+    // just time for today
+    return lowerCaseTime(
+      new Intl.DateTimeFormat('en', {
+        hour: 'numeric',
+        minute: 'numeric',
+      }).format(messageDate)
+    )
+  }
+
+  if (isWithinLastMonth) {
+    // just time for dates within the last month
+    return lowerCaseTime(
+      new Intl.DateTimeFormat('en', {
+        hour: 'numeric',
+        minute: 'numeric',
+      }).format(messageDate)
+    )
+  }
+
+  if (isThisYear) {
+    // Show "Jun 2, 5:50pm" for this year
+    return lowerCaseTime(
+      new Intl.DateTimeFormat('en', {
+        month: 'short',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+      }).format(messageDate)
+    )
+  }
+
+  // Show "Jun 2, 2025, 5:50pm" for previous years
+  return lowerCaseTime(
+    new Intl.DateTimeFormat('en', {
+      month: 'short',
+      day: 'numeric',
+      year: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+    }).format(messageDate)
+  )
+}