@take-out/helpers 0.0.28

package/src/async/idle.ts

@@ -0,0 +1,68 @@
+import { AbortError } from '../error/errors'
+import { sleep } from './sleep'
+
+/**
+ * Two helpers wrapping requestIdleCallback in async, abortable.
+ */
+
+type CallbackFn = (...args: any[]) => any | (() => any)
+type CallbackerFn = (cb: CallbackFn) => void
+
+const idleCb: CallbackerFn =
+  typeof requestIdleCallback === 'undefined'
+    ? (cb: CallbackFn) => setTimeout(cb, 1)
+    : requestIdleCallback
+
+const idleAsync = () => {
+  return new Promise((res) => {
+    idleCb(res)
+  })
+}
+
+export type IdleOptions = {
+  max?: number
+  min?: number
+  fully?: boolean
+}
+
+export const idle = async (
+  options?: IdleOptions,
+  signal?: AbortSignal
+): Promise<void> => {
+  const { max, min, fully } = options || {}
+
+  const idleFn = fully ? fullyIdle : idleAsync
+
+  if (max && min && min < max) {
+    await Promise.race([Promise.all([idleFn(), sleep(min)]), sleep(max)])
+  } else if (max) {
+    await Promise.race([idleFn(), sleep(max)])
+  } else if (min) {
+    await Promise.all([idleFn(), sleep(min)])
+  } else {
+    await idleFn()
+  }
+
+  if (signal?.aborted) {
+    throw new AbortError()
+  }
+}
+
+const fullyIdle = async (signal?: AbortSignal): Promise<void> => {
+  while (true) {
+    const startTime = Date.now()
+    await idle({}, signal)
+    const endTime = Date.now()
+    const duration = endTime - startTime
+
+    // If idle callback took less than 15ms, consider it truly idle
+    if (duration < 15) {
+      break
+    }
+
+    // Check for abort signal after each iteration
+    if (signal?.aborted) {
+      throw new AbortError()
+    }
+  }
+}

package/src/async/interval.ts

@@ -0,0 +1,12 @@
+import { sleep } from './sleep'
+
+export const interval = async (
+  callback: () => void,
+  ms: number,
+  signal?: AbortSignal
+): Promise<never> => {
+  while (true) {
+    callback()
+    await sleep(ms, signal)
+  }
+}

package/src/async/isAborted.ts

@@ -0,0 +1,2 @@
+export const isAborted = (controller?: AbortController): boolean =>
+  !!controller?.signal.aborted

package/src/async/sleep.ts

@@ -0,0 +1,8 @@
+import { AbortError } from '../error/errors'
+
+export const sleep = async (ms: number, signal?: AbortSignal): Promise<void> => {
+  await new Promise((res) => setTimeout(res, ms))
+  if (signal?.aborted) {
+    throw new AbortError()
+  }
+}

package/src/async/useAsync.ts

@@ -0,0 +1,38 @@
+import { useState, useEffect } from 'react'
+
+export function useAsync<T>(
+  promiseFn: () => Promise<T>,
+  args: any[]
+): [T, 'loading' | 'idle' | 'error', Error | null] {
+  const [data, setData] = useState<T | null>(null)
+  const [error, setError] = useState<Error | null>(null)
+  const [loading, setLoading] = useState<boolean>(true)
+
+  useEffect(() => {
+    let isMounted = true
+
+    const fetchData = async () => {
+      try {
+        const result = await promiseFn()
+        if (isMounted) {
+          setData(result)
+          setLoading(false)
+        }
+      } catch (err) {
+        if (isMounted) {
+          setError(err as Error)
+          setLoading(false)
+        }
+      }
+    }
+
+    fetchData()
+
+    return () => {
+      isMounted = false
+    }
+    // biome-ignore lint/correctness/useExhaustiveDependencies: ignore
+  }, args)
+
+  return [data as T, error ? 'error' : loading ? 'loading' : 'idle', error]
+}

package/src/async/useAsyncEffect.ts

@@ -0,0 +1,120 @@
+// adopted from https://github.com/franciscop/use-async/blob/master/src/index.js
+
+import { useEffect, useId, useLayoutEffect } from 'react'
+import { EMPTY_OBJECT } from '../constants'
+import { handleAbortError } from './abortable'
+
+type Cleanup = () => void
+
+type AsyncEffectCallback = (
+  signal: AbortSignal,
+  ...deps: any[]
+) => Promise<Cleanup | void> | void
+
+type AsyncEffectOptions = {
+  circuitBreakAfter?: number
+  circuitBreakPeriod?: number
+  debug?: boolean
+}
+
+export function useAsyncEffect(
+  cb: AsyncEffectCallback,
+  deps: any[] = [],
+  options?: AsyncEffectOptions
+): void {
+  useAsyncEffectImpl(false, cb, deps, options)
+}
+
+export function useAsyncLayoutEffect(
+  cb: AsyncEffectCallback,
+  deps: any[] = [],
+  options?: AsyncEffectOptions
+): void {
+  useAsyncEffectImpl(true, cb, deps, options)
+}
+
+function useAsyncEffectImpl(
+  isLayoutEffect: boolean,
+  cb: AsyncEffectCallback,
+  deps: any[] = [],
+  options: AsyncEffectOptions = EMPTY_OBJECT
+): void {
+  const effectHook = isLayoutEffect ? useLayoutEffect : useEffect
+  // biome-ignore lint/correctness/useHookAtTopLevel: ignore
+  const effectId = process.env.NODE_ENV === 'development' ? useId() : ''
+
+  effectHook(() => {
+    // Generate a unique ID for this effect instance for loop detection
+    checkEffectLoop(effectId, options.circuitBreakAfter, options.circuitBreakPeriod)
+    const controller = new AbortController()
+    const signal = controller.signal
+
+    // wrap in try in case its not async (for simple use cases)
+    try {
+      const value = cb(signal, ...deps)
+
+      Promise.resolve(value)
+        .then(async (res) => {
+          if (res && typeof res === 'function') {
+            if (signal.aborted) return res()
+            signal.addEventListener('abort', res)
+          }
+        })
+        .catch(handleAbortError)
+    } catch (error) {
+      handleAbortError(error, options.debug)
+    }
+
+    return () => {
+      if (signal.aborted) return
+      controller.abort()
+    }
+  }, deps)
+}
+
+// loop detection in dev mode
+let effectRunCounts: Map<string, number[]>
+let checkEffectLoop: (
+  effectId: string,
+  circuitBreakAfter?: number,
+  circuitBreakPeriod?: number
+) => void
+
+if (process.env.NODE_ENV === 'development') {
+  effectRunCounts = new Map<string, number[]>()
+
+  checkEffectLoop = (
+    effectId: string,
+    circuitBreakAfter: number = 20,
+    circuitBreakPeriod: number = 1000
+  ) => {
+    const now = Date.now()
+    const runs = effectRunCounts.get(effectId) || []
+
+    runs.push(now)
+
+    // keep only runs from the specified period
+    const recentRuns = runs.filter((time) => now - time < circuitBreakPeriod)
+    effectRunCounts.set(effectId, recentRuns)
+
+    const runCount = recentRuns.length
+
+    if (runCount > circuitBreakAfter) {
+      const message = `🚨 useAsyncEffect infinite loop detected! Effect ran ${runCount} times in <${circuitBreakPeriod}ms`
+      if (process.env.NODE_ENV === 'development') {
+        console.error(message)
+        // biome-ignore lint/suspicious/noDebugger: ignore
+        debugger
+      } else {
+        alert(message)
+        throw new Error(message)
+      }
+    } else if (runCount > circuitBreakAfter / 2) {
+      console.warn(
+        `⚠️ useAsyncEffect potential loop: Effect ran ${runCount} times in <${circuitBreakPeriod}ms`
+      )
+    }
+  }
+} else {
+  checkEffectLoop = () => {}
+}

package/src/async/useLazyMount.ts

@@ -0,0 +1,32 @@
+import type React from 'react'
+import { startTransition, useState } from 'react'
+import { idle, type IdleOptions } from './idle'
+import { useAsyncEffect } from './useAsyncEffect'
+
+export type LazyMountProps = IdleOptions
+
+export const useLazyMount = (props: LazyMountProps = { max: 100 }): boolean => {
+  const [mounted, setMounted] = useState(false)
+
+  useAsyncEffect(
+    async (signal) => {
+      await idle(props, signal)
+      startTransition(() => {
+        setMounted(true)
+      })
+    },
+    [
+      // no need for deps it only ever mounts once
+    ]
+  )
+
+  return mounted
+}
+
+export const LazyMount = ({
+  children,
+  ...idleProps
+}: LazyMountProps & { children: any }): React.ReactNode => {
+  const mounted = useLazyMount(idleProps)
+  return mounted ? children : null
+}

package/src/async/useLazyValue.ts

@@ -0,0 +1,30 @@
+import { startTransition, useState } from 'react'
+import { idle, type IdleOptions } from './idle'
+import { useAsyncEffect } from './useAsyncEffect'
+
+export const useLazyValue = <T>(
+  value: T,
+  {
+    immediateFirstUpdate,
+    ...idleOptions
+  }: IdleOptions & { immediateFirstUpdate?: boolean } = {}
+): T => {
+  const [lazyValue, setLazyValue] = useState(value)
+
+  // first update to a real value immediate
+  if (value && lazyValue === undefined && lazyValue !== value && immediateFirstUpdate) {
+    setLazyValue(value)
+  }
+
+  useAsyncEffect(
+    async (signal) => {
+      await idle(idleOptions, signal)
+      startTransition(() => {
+        setLazyValue(value)
+      })
+    },
+    [value]
+  )
+
+  return lazyValue
+}

package/src/browser/clearIndexedDB.ts

@@ -0,0 +1,18 @@
+export async function clearIndexedDB(): Promise<void> {
+  if ('indexedDB' in window) {
+    const databases = await indexedDB.databases()
+    await Promise.all(
+      databases.map((db) => {
+        if (db.name) {
+          return new Promise<void>((resolve, reject) => {
+            const deleteReq = indexedDB.deleteDatabase(db.name!)
+            deleteReq.onsuccess = () => resolve()
+            deleteReq.onerror = () => reject(deleteReq.error)
+            deleteReq.onblocked = () => reject(new Error('database deletion blocked'))
+          })
+        }
+        return Promise.resolve()
+      })
+    )
+  }
+}

package/src/browser/isActiveElementFormField.ts

@@ -0,0 +1,10 @@
+export function isActiveElementFormField(): boolean {
+  return (
+    typeof document !== 'undefined' &&
+    document.activeElement !== null &&
+    (document.activeElement.tagName === 'INPUT' ||
+      document.activeElement.tagName === 'TEXTAREA' ||
+      document.activeElement.tagName === 'SELECT' ||
+      document.activeElement.tagName === 'FORM')
+  )
+}

package/src/browser/localStorage.ts

@@ -0,0 +1,311 @@
+const created = new Set<string>()
+
+const STORAGE_TRACKING_KEY = '__localStorage_tracking__'
+const STORAGE_ORDER_KEY = '__localStorage_order__'
+
+interface StorageTracking {
+  [key: string]: number // key -> size in bytes
+}
+
+interface LocalStorageOptions {
+  synced?: boolean
+  disableSetOnBlur?: boolean
+
+  /**
+   * Limit in kB
+   */
+  storageLimit?: number
+}
+
+export function createLocalStorage<K extends string, V>(
+  name: string,
+  { synced = false, disableSetOnBlur = false, storageLimit }: LocalStorageOptions = {}
+) {
+  if (created.has(name)) {
+    throw new Error(`Already defined this localStorage namespace: ${name}`)
+  }
+  created.add(name)
+
+  let isWindowActive = true
+  if (typeof window !== 'undefined' && disableSetOnBlur) {
+    const handleFocus = () => {
+      isWindowActive = true
+    }
+    const handleBlur = () => {
+      isWindowActive = false
+    }
+
+    window.addEventListener('focus', handleFocus)
+    window.addEventListener('blur', handleBlur)
+
+    isWindowActive = document.hasFocus()
+  }
+
+  const listeners = new Map<string, Set<(value: any) => void>>()
+
+  if (synced && typeof window !== 'undefined') {
+    const handleStorageChange = (event: StorageEvent) => {
+      if (event.key?.startsWith(`${name}:`) && event.storageArea === localStorage) {
+        const key = event.key.slice(name.length + 1)
+        const newValue = event.newValue ? JSON.parse(event.newValue) : undefined
+        const keyListeners = listeners.get(key)
+        if (keyListeners) {
+          keyListeners.forEach((listener) => listener(newValue))
+        }
+      }
+    }
+
+    window.addEventListener('storage', handleStorageChange)
+  }
+
+  const getFullKey = (key: string) => `${name}:${key}`
+
+  return {
+    get: (key: K): V | undefined => {
+      if (typeof localStorage === 'undefined') {
+        console.warn(`No localStorage`)
+        return
+      }
+
+      const fullKey = getFullKey(key)
+      const item = localStorage.getItem(fullKey)
+      if (item && storageLimit) {
+        updateKeyAccess(fullKey)
+      }
+      return item ? JSON.parse(item) : undefined
+    },
+
+    set: (key: K, value: V): void => {
+      if (typeof localStorage === 'undefined') {
+        console.warn(`No localStorage`)
+        return
+      }
+
+      if (disableSetOnBlur && !isWindowActive) {
+        return
+      }
+
+      const fullKey = getFullKey(key)
+      const serializedValue = JSON.stringify(value)
+
+      if (storageLimit) {
+        const newSize = getStringSizeInBytes(serializedValue)
+        enforceStorageLimit(fullKey, newSize, storageLimit)
+        const tracking = getStorageTracking()
+        tracking[fullKey] = newSize
+        setStorageTracking(tracking)
+        updateKeyAccess(fullKey)
+      }
+
+      localStorage.setItem(fullKey, serializedValue)
+    },
+
+    remove: (key: K): void => {
+      if (typeof localStorage === 'undefined') {
+        console.warn(`No localStorage`)
+        return
+      }
+
+      // don't remove if window is not active and disablesetonblur is true
+      if (disableSetOnBlur && !isWindowActive) {
+        return
+      }
+
+      const fullKey = getFullKey(key)
+      localStorage.removeItem(fullKey)
+
+      // clean up tracking data if storage limit is enabled
+      if (storageLimit) {
+        const tracking = getStorageTracking()
+        delete tracking[fullKey]
+        setStorageTracking(tracking)
+
+        const order = getStorageOrder()
+        const index = order.indexOf(fullKey)
+        if (index > -1) {
+          order.splice(index, 1)
+          setStorageOrder(order)
+        }
+      }
+    },
+
+    exists: (key: K): boolean => {
+      const fullKey = getFullKey(key)
+      return localStorage.getItem(fullKey) != null
+    },
+
+    clear: (): void => {
+      if (typeof localStorage === 'undefined') {
+        console.warn(`No localStorage`)
+        return
+      }
+
+      // Remove all keys with this namespace
+      const keysToRemove: string[] = []
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i)
+        if (key?.startsWith(`${name}:`)) {
+          keysToRemove.push(key)
+        }
+      }
+
+      keysToRemove.forEach((key) => localStorage.removeItem(key))
+
+      // Clean up tracking data
+      if (storageLimit) {
+        const tracking = getStorageTracking()
+        const order = getStorageOrder()
+
+        keysToRemove.forEach((key) => {
+          delete tracking[key]
+          const index = order.indexOf(key)
+          if (index > -1) {
+            order.splice(index, 1)
+          }
+        })
+
+        setStorageTracking(tracking)
+        setStorageOrder(order)
+      }
+    },
+
+    subscribe: (key: string, listener: (value: V | undefined) => void): (() => void) => {
+      if (!synced) {
+        console.warn(`Subscribe only works when synced option is enabled`)
+        return () => {}
+      }
+
+      if (!listeners.has(key)) {
+        listeners.set(key, new Set())
+      }
+      const keyListeners = listeners.get(key)!
+      keyListeners.add(listener)
+
+      return () => {
+        keyListeners.delete(listener)
+        if (keyListeners.size === 0) {
+          listeners.delete(key)
+        }
+      }
+    },
+
+    keys: (): string[] => {
+      if (typeof localStorage === 'undefined') {
+        return []
+      }
+
+      const keys: string[] = []
+      const prefix = `${name}:`
+
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i)
+        if (key?.startsWith(prefix)) {
+          keys.push(key.slice(prefix.length))
+        }
+      }
+
+      return keys
+    },
+  }
+}
+
+export function createLocalStorageValue<T>(
+  key: string,
+  options: LocalStorageOptions = {}
+) {
+  const storage = createLocalStorage<string, T>(`single:${key}`, options)
+  const storageKey = 'value'
+
+  return {
+    get: (): T | undefined => {
+      return storage.get(storageKey)
+    },
+
+    set: (value: T): void => {
+      storage.set(storageKey, value)
+    },
+
+    remove: (): void => {
+      storage.remove(storageKey)
+    },
+
+    exists: (): boolean => {
+      return storage.exists(storageKey)
+    },
+
+    clear: (): void => {
+      storage.clear()
+    },
+
+    subscribe: (listener: (value: T | undefined) => void): (() => void) => {
+      return storage.subscribe(storageKey, listener)
+    },
+  }
+}
+
+function getStorageTracking(): StorageTracking {
+  if (typeof localStorage === 'undefined') return {}
+  const tracking = localStorage.getItem(STORAGE_TRACKING_KEY)
+  return tracking ? JSON.parse(tracking) : {}
+}
+
+function setStorageTracking(tracking: StorageTracking): void {
+  if (typeof localStorage === 'undefined') return
+  localStorage.setItem(STORAGE_TRACKING_KEY, JSON.stringify(tracking))
+}
+
+function getStorageOrder(): string[] {
+  if (typeof localStorage === 'undefined') return []
+  const order = localStorage.getItem(STORAGE_ORDER_KEY)
+  return order ? JSON.parse(order) : []
+}
+
+function setStorageOrder(order: string[]): void {
+  if (typeof localStorage === 'undefined') return
+  localStorage.setItem(STORAGE_ORDER_KEY, JSON.stringify(order))
+}
+
+function getStringSizeInBytes(str: string): number {
+  return new Blob([str]).size
+}
+
+function updateKeyAccess(key: string): void {
+  const order = getStorageOrder()
+  const index = order.indexOf(key)
+  if (index > -1) {
+    order.splice(index, 1)
+  }
+  order.push(key) // move to end (most recent)
+  setStorageOrder(order)
+}
+
+function enforceStorageLimit(newKey: string, newSize: number, limitKB: number): void {
+  const tracking = getStorageTracking()
+  const order = getStorageOrder()
+
+  let totalSize = Object.values(tracking).reduce((sum, size) => sum + size, 0)
+  totalSize += newSize // add the new item size
+
+  const limitBytes = limitKB * 1024
+
+  while (totalSize > limitBytes && order.length > 0) {
+    const oldestKey = order.shift()!
+
+    if (
+      oldestKey === newKey ||
+      oldestKey === STORAGE_TRACKING_KEY ||
+      oldestKey === STORAGE_ORDER_KEY
+    ) {
+      continue
+    }
+
+    const oldSize = tracking[oldestKey] || 0
+    totalSize -= oldSize
+
+    localStorage.removeItem(oldestKey)
+    delete tracking[oldestKey]
+  }
+
+  setStorageTracking(tracking)
+  setStorageOrder(order)
+}

package/src/browser/openPopup.ts

@@ -0,0 +1,30 @@
+// note safari enhanced privacy will break this as it reports screen height as smaller
+
+export function openCenteredPopup(
+  url: string,
+  title: string,
+  width: number,
+  height: number
+) {
+  // availWidth/availHeight accounts for taskbars, docks, and other UI elements
+  const screenWidth = screen.availWidth || screen.width
+  const screenHeight = screen.availHeight || screen.height
+
+  const shouldGuess = screenHeight < height
+
+  // if we are guessing, at least make it a bit more likely to be centered
+  // and not just touching the top which looks broken
+  const left = Math.max(0, (screenWidth - width) / 2) + (shouldGuess ? 100 : 0)
+  const top = Math.max(150, shouldGuess ? 150 : Math.max(0, (screenHeight - height) / 2))
+
+  const windowFeatures = `
+    width=${width},
+    height=${height},
+    left=${left},
+    top=${top},
+    scrollbars=yes,
+    resizable=yes
+  `
+
+  return window.open(url, title, windowFeatures)
+}

package/src/client-only.ts

@@ -0,0 +1,3 @@
+if (process.env.VITE_ENVIRONMENT !== 'client') {
+  console.error(`This file should only be imported on the client!`)
+}