@take-out/helpers 0.0.28

package/src/constants.ts

@@ -0,0 +1,34 @@
+import { isWeb } from '@tamagui/constants'
+
+export const isTauri: boolean =
+  typeof window !== 'undefined' &&
+  // @ts-expect-error
+  window['__TAURI__'] !== undefined
+
+export const isNative: boolean = !isWeb && !isTauri
+
+// TODO move to probably ~/interface/constants
+
+export const IS_MAC_DESKTOP: boolean =
+  typeof navigator !== 'undefined' && /Macintosh|MacIntel/.test(navigator.platform)
+
+export const IS_SAFARI: boolean =
+  isTauri ||
+  (typeof navigator !== 'undefined' &&
+    /Version\/[\d.]+.*Safari/.test(navigator.userAgent) &&
+    /Apple Computer/.test(navigator.vendor))
+
+export { isAndroid, isClient, isIos, isServer, isWeb } from '@tamagui/constants'
+
+export const EMPTY_ARRAY = [] as never
+export const EMPTY_OBJECT = {} as never
+
+const getDebugLevelFromUrl = (): number | null => {
+  if (typeof window === 'undefined') return null
+  const match = window.location?.search?.match(/debug=(\d+)/)
+  return match?.[1] ? parseInt(match[1], 10) : null
+}
+
+export const DEBUG_LEVEL: number = process.env.DEBUG_LEVEL
+  ? +process.env.DEBUG_LEVEL
+  : (getDebugLevelFromUrl() ?? (process.env.NODE_ENV === 'development' ? 1 : 0))

package/src/debug/debugLog.ts

@@ -0,0 +1,13 @@
+/**
+ * Debug utility that logs a value and passes it through unchanged.
+ * Useful for debugging chains of operations without breaking the flow.
+ *
+ * @param value - The value to log and pass through
+ * @param label - Optional label to prefix the log output
+ * @returns The original value unchanged
+ */
+export function debugLog<T>(value: T, label?: string): T {
+  const output = label ? `[${label}]` : '[DEBUG]'
+  console.info(output, value)
+  return value
+}

package/src/debug/debugUseState.ts

@@ -0,0 +1,35 @@
+import { useCallback } from 'react'
+
+export function debugUseState<T>(
+  useState: [T, React.Dispatch<React.SetStateAction<T>>]
+): [T, React.Dispatch<React.SetStateAction<T>>] {
+  const [state, setState] = useState
+
+  const wrappedSetState = useCallback(
+    (newValue: T | ((prevState: T) => T)) => {
+      if (typeof newValue === 'function') {
+        // Handle callback style
+        setState((prevState: T) => {
+          const nextState = (newValue as (prevState: T) => T)(prevState)
+          console.trace('State update (callback):', {
+            prevState,
+            nextState,
+            stack: new Error().stack,
+          })
+          return nextState
+        })
+      } else {
+        // Handle direct value style
+        console.trace('State update (direct):', {
+          prevState: state,
+          nextState: newValue,
+          stack: new Error().stack,
+        })
+        setState(newValue)
+      }
+    },
+    [setState, state]
+  )
+
+  return [state, wrappedSetState]
+}

package/src/emitter.tsx

@@ -0,0 +1,377 @@
+import { dequal } from 'dequal'
+import type { JSX, PropsWithChildren } from 'react'
+import * as React from 'react'
+import { use, useLayoutEffect, useState } from 'react'
+import { handleAbortError } from './async/abortable'
+import { DEBUG_LEVEL, EMPTY_ARRAY } from './constants'
+import { AbortError } from './error/errors'
+import { createGlobalContext } from './react/createGlobalContext'
+import { globalValue } from './global/globalValue'
+
+// keeps a reference to the current value easily
+
+// TODO can replace with useEffectEvent
+function useGet<A>(
+  currentValue: A,
+  initialValue?: any,
+  forwardToFunction?: boolean
+): () => A {
+  const curRef = React.useRef<any>(initialValue ?? currentValue)
+
+  useLayoutEffect(() => {
+    curRef.current = currentValue
+  })
+
+  return React.useCallback(
+    forwardToFunction
+      ? (...args) => curRef.current?.apply(null, args)
+      : () => curRef.current,
+    []
+  )
+}
+
+type EmitterOptions<T> = CreateEmitterOpts<T> & {
+  name: string
+}
+
+type CreateEmitterOpts<T> = {
+  silent?: boolean
+  comparator?: (a: T, b: T) => boolean
+}
+
+export class Emitter<const T> {
+  private disposables = new Set<(cb: any) => void>()
+  value: T
+  options?: EmitterOptions<T>
+
+  constructor(value: T, options?: EmitterOptions<T>) {
+    this.value = value
+    this.options = options
+  }
+
+  listen = (disposable: (cb: T) => void): (() => void) => {
+    this.disposables.add(disposable)
+    return (): void => {
+      this.disposables.delete(disposable)
+    }
+  }
+
+  emit = (next: T): void => {
+    if (process.env.NODE_ENV === 'development') {
+      setCache(this, next)
+    }
+    const compare = this.options?.comparator
+    if (compare) {
+      if (this.value && compare(this.value, next)) {
+        return
+      }
+    } else {
+      if (this.value === next) {
+        if (process.env.NODE_ENV === 'development') {
+          console.warn(
+            `[emitter] ${this.options?.name} no comparator option but received same value!
+            
+this will emit the same value again, which can be desirable, but we warn to ensure it's not unintended:
+
+- if you want this behavior, add { comparator: isEqualNever }
+- if you want only non-equal values: { comparator: isEqualIdentity }
+- if you want only deeply non-equal values: { comparator: isEqualDeep }`
+          )
+        }
+      }
+    }
+    this.value = next
+    if (DEBUG_LEVEL > 1) {
+      if (!this.options?.silent) {
+        const name = this.options?.name
+        console.groupCollapsed(`📣 ${name}`)
+        console.info(next)
+        console.trace(`trace >`)
+        console.groupEnd()
+      }
+    }
+    this.disposables.forEach((cb) => cb(next))
+  }
+
+  nextValue = (): Promise<T> => {
+    return new Promise<T>((res) => {
+      const dispose = this.listen((val) => {
+        dispose()
+        res(val)
+      })
+    })
+  }
+}
+
+// just createEmitter but ensures it doesn't mess up on HMR
+export function createGlobalEmitter<T>(
+  name: string,
+  defaultValue: T,
+  options?: CreateEmitterOpts<T>
+): Emitter<T> {
+  return globalValue(name, () => createEmitter(name, defaultValue, options))
+}
+
+export function createEmitter<T>(
+  name: string,
+  defaultValue: T,
+  options?: CreateEmitterOpts<T>
+): Emitter<T> {
+  const existing = createOrUpdateCache(name, defaultValue) as T
+  return new Emitter<T>(existing || defaultValue, { name, ...options })
+}
+
+export type EmitterType<E extends Emitter<any>> = E extends Emitter<infer Val>
+  ? Val
+  : never
+
+export const useEmitter = <E extends Emitter<any>>(
+  emitter: E,
+  cb: (cb: EmitterType<E>) => void,
+  args?: any[]
+): void => {
+  const getCallback = useGet(cb)
+
+  useLayoutEffect(() => {
+    return emitter.listen((val) => {
+      try {
+        getCallback()(val)
+      } catch (err) {
+        handleAbortError(err)
+      }
+    })
+  }, [emitter, getCallback])
+}
+
+export const useEmitterValue = <E extends Emitter<any>>(
+  emitter: E,
+  options?: { disable?: boolean }
+): EmitterType<E> => {
+  const [state, setState] = useState<EmitterType<E>>(emitter.value)
+  const disabled = options?.disable
+
+  useLayoutEffect(() => {
+    if (disabled) return
+    if (emitter.value !== state) {
+      setState(emitter.value)
+    }
+    return emitter.listen(setState)
+  }, [disabled, emitter, state])
+
+  return state
+}
+
+/**
+ * By default selectors run every render, as well as when emitters update. This is a change
+ * from the previous behavior where they only ran when emitters changed value.
+ *
+ * The reason for this is because emitters capture the variables in scope of the component
+ * each render already by using "useGet" by default, which makes them easier to use - you
+ * don't need to pass an args[] array except for edge cases.
+ *
+ * Before explaining why we switched to the default, understand the different uses:
+ *
+ * - Default behavior - selector is updated every render, and ran every render, as well as
+ *   when emitter value changes, so you basically are always up to date.
+ *
+ * - Set an args[] array as the fourth argument - this will stop the automatic capturing
+ *   and instead update selector only when you change args[] yourself. This is good for when you
+ *   want explicit control over re-selection and rendering.
+ *
+ * - With { lazy: true }, the selector only runs when the emitter value changes. If used with
+ *   args[], you capture the context of the selector based on args[], if not, it's based on the
+ *   current render.
+ *
+ * I made this change when we had 16 usages of useEmitterSelector and 100% of them are doing very
+ * cheap calculations, so this feels like the right pattern. For the rare case of a heavy selector,
+ * you have the option to control it.
+ *
+ */
+export const useEmitterSelector = <E extends Emitter<any>, T extends EmitterType<E>, R>(
+  emitter: E,
+  selector: (value: T) => R,
+  options?: {
+    disable?: boolean
+    lazy?: boolean
+  },
+  args: any[] = EMPTY_ARRAY
+): R => {
+  const [state, setState] = useState<R>(() => selector(emitter.value))
+  const disabled = options?.disable
+  const getSelector = useGet(selector)
+
+  if (options?.lazy !== true) {
+    const next = selector(emitter.value)
+    if (next !== state) {
+      setState(next)
+    }
+  }
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: we are using args fine
+  useLayoutEffect(() => {
+    if (disabled) return
+    return emitter.listen((val) => {
+      try {
+        const selectorFn = args !== EMPTY_ARRAY ? selector : getSelector()
+        const next = selectorFn(val)
+        setState(next)
+      } catch (error) {
+        if (error instanceof AbortError) {
+          return
+        }
+        throw error
+      }
+    })
+  }, [disabled, emitter, getSelector, ...args])
+
+  return state
+}
+
+export const useEmittersSelector = <const E extends readonly Emitter<any>[], R>(
+  emitters: E,
+  selector: (values: { [K in keyof E]: EmitterType<E[K]> }) => R,
+  options?: { disable?: boolean; isEqual?: (a: R, b: R) => boolean }
+): R => {
+  const getSelector = useGet(selector)
+  const disabled = options?.disable
+
+  const [state, setState] = useState<R>(() => {
+    const values = emitters.map((e) => e.value) as { [K in keyof E]: EmitterType<E[K]> }
+    return getSelector()(values)
+  })
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: ignore
+  useLayoutEffect(() => {
+    if (disabled) {
+      return
+    }
+
+    const handler = () => {
+      const values = emitters.map((e) => e.value) as {
+        [K in keyof E]: EmitterType<E[K]>
+      }
+      try {
+        const next = getSelector()(values)
+        setState((prev) => {
+          if (options?.isEqual?.(prev, next)) {
+            return prev
+          }
+          if (dequal(prev, next)) {
+            return prev
+          }
+          return next
+        })
+      } catch (error) {
+        if (error instanceof AbortError) {
+          return
+        }
+        throw error
+      }
+    }
+
+    const disposals = emitters.map((emitter) => emitter.listen(handler))
+
+    return () => {
+      disposals.forEach((d) => d())
+    }
+  }, [disabled, getSelector, ...emitters])
+
+  return state
+}
+
+export const createUseEmitter = <E extends Emitter<any>>(
+  emitter: E
+): ((cb: (val: EmitterType<E>) => void, args?: any[]) => void) => {
+  return (cb: (val: EmitterType<E>) => void, args?: any[]) =>
+    useEmitter(emitter, cb, args)
+}
+
+export const createUseSelector = <E extends Emitter<any>>(
+  emitter: E
+): (<R>(
+  selector: (value: EmitterType<E>) => R,
+  options?: { disable?: boolean; lazy?: boolean },
+  args?: any[]
+) => R) => {
+  return <R,>(
+    selector: (value: EmitterType<E>) => R,
+    options?: { disable?: boolean; lazy?: boolean },
+    args?: any[]
+  ): R => {
+    return useEmitterSelector(emitter, selector, options, args)
+  }
+}
+
+export function createContextualEmitter<T>(
+  name: string,
+  defaultValue: T,
+  defaultOptions?: Omit<EmitterOptions<T>, 'name'>
+): readonly [
+  () => Emitter<T>,
+  (props: PropsWithChildren<{ value?: T; silent?: boolean }>) => JSX.Element,
+] {
+  const id = Math.random().toString(36)
+  const EmitterContext = createGlobalContext<Emitter<T> | null>(
+    `contextual-emitter/${id}`,
+    null
+  )
+
+  const useContextEmitter = () => {
+    const emitter = use(EmitterContext)
+    if (!emitter) {
+      throw new Error('useContextEmitter must be used within an EmitterProvider')
+    }
+    return emitter
+  }
+
+  type ProvideEmitterProps = PropsWithChildren<{
+    value?: T
+    silent?: boolean
+  }>
+
+  const ProvideEmitter = (props: ProvideEmitterProps) => {
+    const { children, value, silent } = props
+    const [emitter] = useState(
+      () => new Emitter<T>(value ?? defaultValue, { name, silent, ...defaultOptions })
+    )
+
+    useLayoutEffect(() => {
+      if (value !== undefined && value !== emitter.value) {
+        emitter.emit(value)
+      }
+    }, [value, emitter])
+
+    return <EmitterContext.Provider value={emitter}>{children}</EmitterContext.Provider>
+  }
+
+  return [useContextEmitter, ProvideEmitter] as const
+}
+
+const HMRCache =
+  process.env.NODE_ENV === 'development'
+    ? new Map<string, { originalDefaultValue: unknown; currentValue: unknown }>()
+    : null
+
+function setCache(emitter: Emitter<any>, value: unknown) {
+  const name = emitter.options?.name
+  if (!name) return
+  const cache = HMRCache?.get(name)
+  if (!cache) return
+  cache.currentValue = value
+}
+
+function createOrUpdateCache(name: string, defaultValueProp: unknown) {
+  const existing = HMRCache?.get(name)
+  const defaultValue = dequal(existing?.originalDefaultValue, defaultValueProp)
+    ? existing?.currentValue
+    : defaultValueProp
+
+  if (!existing) {
+    HMRCache?.set(name, {
+      originalDefaultValue: defaultValueProp,
+      currentValue: defaultValue,
+    })
+  }
+
+  return defaultValue
+}

package/src/ensure/ensure.ts

@@ -0,0 +1,31 @@
+import { EnsureError } from '../error/errors'
+
+export function ensureExists<T>(
+  value: T | undefined | null,
+  msg = ''
+): asserts value is T {
+  if (value === undefined || value === null) {
+    throw new EnsureError(`Invalid nullish value (${value}): ${msg}`)
+  }
+}
+
+export function ensure<T>(
+  value: T,
+  msg = ''
+): asserts value is Exclude<T, null | undefined | false> {
+  if (!value) {
+    throw new EnsureError(`ensure() invalid: (${value}): ${msg} ${new Error().stack}`)
+  }
+}
+
+export function ensureError(val: unknown): asserts val is Error {
+  if (!(val instanceof Error)) {
+    throw val
+  }
+}
+
+export function ensureString(val: unknown, name = '(unnamed)'): asserts val is string {
+  if (typeof val !== 'string') {
+    throw new EnsureError(`No string ${name}`)
+  }
+}

package/src/ensure/ensureOne.ts

@@ -0,0 +1,17 @@
+// Ensures only one instance ever exists, but replaces it every time it's called
+
+const Controllers = new WeakMap<symbol, AbortController>()
+
+export function ensureOne<T>(key: string, factory: (signal: AbortSignal) => T): T {
+  const symbolKey = Symbol.for(key)
+  const g = globalThis as Record<symbol, unknown>
+
+  if (g[symbolKey]) {
+    Controllers.get(symbolKey)?.abort()
+  }
+
+  const controller = new AbortController()
+  g[symbolKey] = factory(controller.signal)
+
+  return g[symbolKey] as T
+}

package/src/error/errors.ts

@@ -0,0 +1,13 @@
+export class AbortError extends Error {
+  constructor(message = '') {
+    super(message)
+    this.name = 'AbortError'
+  }
+}
+
+export class EnsureError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'EnsureError'
+  }
+}

package/src/function/emptyFn.ts

@@ -0,0 +1 @@
+export const emptyFn = (): void => {}

package/src/function/identityFn.ts

@@ -0,0 +1 @@
+export const identityFn = <A>(item: A): A => item

package/src/function/throttle.ts

@@ -0,0 +1,73 @@
+// via @github/mini-throttle https://raw.githubusercontent.com/github/mini-throttle/refs/heads/main/index.ts
+
+import type { Timer } from '../types/timer'
+
+export interface ThrottleOptions {
+  /**
+   * Fire immediately on the first call.
+   */
+  start?: boolean
+  /**
+   * Fire as soon as `wait` has passed.
+   */
+  middle?: boolean
+  /**
+   * Cancel after the first successful call.
+   */
+  once?: boolean
+}
+
+interface Throttler<T extends unknown[]> {
+  (...args: T): void
+  cancel(): void
+}
+
+export function throttle<T extends unknown[]>(
+  callback: (...args: T) => unknown,
+  wait = 0,
+  { start = true, middle = true, once = false }: ThrottleOptions = {}
+): Throttler<T> {
+  let innerStart = start
+  let last = 0
+  let timer: Timer
+  let cancelled = false
+  function fn(this: unknown, ...args: T) {
+    if (cancelled) return
+    const delta = Date.now() - last
+    last = Date.now()
+
+    if (start && middle && delta >= wait) {
+      innerStart = true
+    }
+
+    if (innerStart) {
+      innerStart = false
+      callback.apply(this, args)
+      if (once) fn.cancel()
+    } else if ((middle && delta < wait) || !middle) {
+      clearTimeout(timer)
+      timer = setTimeout(
+        () => {
+          last = Date.now()
+          callback.apply(this, args)
+          if (once) fn.cancel()
+        },
+        !middle ? wait : wait - delta
+      )
+    }
+  }
+  fn.cancel = () => {
+    clearTimeout(timer)
+    cancelled = true
+  }
+  return fn
+}
+
+// we have debounce from tamagui already
+// export function debounce<T extends unknown[]>(
+//   callback: (...args: T) => unknown,
+//   wait = 0,
+//   { start = false, middle = false, once = false }: ThrottleOptions = {}
+// ): Throttler<T> {
+//   return throttle(callback, wait, { start, middle, once })
+// }

package/src/global/globalEffect.ts

@@ -0,0 +1,14 @@
+export function globalEffect(key: string, factory: () => void | (() => void)): void {
+  const disposeKey = Symbol.for(key)
+  const g = globalThis as Record<symbol, () => void>
+
+  if (g[disposeKey]) {
+    g[disposeKey]?.()
+  }
+
+  const dispose = factory()
+
+  if (dispose) {
+    g[disposeKey] = dispose
+  }
+}

package/src/global/globalValue.ts

@@ -0,0 +1,40 @@
+/**
+ * Helper to store a value that's not duplicated within the global context Uses
+ * a symbol stored on `globalThis` to achieve it.
+ *
+ * There's two main uses for this (for us, so far):
+ *
+ *   - in dev mode, HMR re-runs files, but you may want to preserve globals
+ *
+ *   - in published node modules, sometimes Vite or other bundlers can cause
+ *     duplicate dependencies either through bad setup or heuristics, they may
+ *     compile a module but then another code path doesn't compile it, so you
+ *     have duplicate modules. in this case it can be good to just use a
+ *     globalValue and warn the end-user. because you can't account for ever
+ *     possible weird configuration, and often fixing that config can be a
+ *     massive pain in the ass, it's better to retain functionality while
+ *     warning them so they can fix it at their own pace. this often happens
+ *     with WeakMaps.
+ *
+ */
+
+export function globalValue<T>(
+  key: string,
+  factory: () => T,
+  opts?: {
+    warnMessage?: string
+  }
+): T {
+  const symbolKey = Symbol.for(key)
+  const g = globalThis as Record<symbol, unknown>
+
+  if (!g[symbolKey]) {
+    g[symbolKey] = factory()
+  } else {
+    if (opts?.warnMessage) {
+      console.warn(`[globalValue] ${opts.warnMessage}`)
+    }
+  }
+
+  return g[symbolKey] as T
+}