Helpers and utility types
Import these through @khanglvm/react/helpers; they are not exported from the package root.
Copying, comparison, and caching
deepClone(value, cache?)
Use this when copying a nested value with the same rules the state utility uses for partial updates. It handles cycles, arrays, plain objects, Date, RegExp, Map, Set, ArrayBuffer and typed arrays. Functions, AbortSignal, and FormData are retained by reference. An optional WeakMap tracks copies during recursion.
Any other object type throws Unsupported type, including Error, Promise, WeakMap, WeakSet, URL and Blob. A class instance is copied as a plain object, so its methods and prototype are lost.
Own JSON keys such as __proto__ are copied as data properties without changing the clone's prototype.
import { deepClone } from '@khanglvm/react/helpers'
const original = { tags: ['react'], createdAt: new Date('2026-01-01') }
const copy = deepClone(original)
copy.tags.push('typescript') // original.tags is unchangedAn object spread only copies one level; this function descends into nested data. A typical use is handing out a copy of live state, such as an export snapshot, that the caller can change without touching the store. For standard structured-clone-compatible data, consider the platform's structuredClone first. This helper is not a universal clone: it drops custom object prototypes and symbol properties, and typed-array views are rebuilt from their entire backing buffer without preserving their original offset or length. It also expects AbortSignal and FormData globals to exist.
deepEqual(a, b)
Use this for value comparison of acyclic objects, arrays, Maps, and Sets when reference equality is insufficient. It also compares Date timestamps, RegExp strings, constructors, and NaN; React element _owner fields are skipped.
Typical uses: skip copying a prop into local state when the new prop has a new reference but the same content, and return the previous object from an immutable update when nothing changed, so memoized consumers keep their reference.
import { deepEqual } from '@khanglvm/react/helpers'
deepEqual({ tags: ['react'] }, { tags: ['react'] }) // trueMaps compare their size, keys, and values. Keys use native Map identity, and values are compared recursively. Sets compare size and membership using native Set identity. Insertion order does not matter. Object keys and Set members must be the same references; matching object contents alone are insufficient.
There is no cycle detection. Symbol and non-enumerable properties are not included. Use a comparator designed for those cases when they are part of your data.
createCacheStorage(id?)
Use this to retain the previous reference for an equivalent value, keyed by a cache entry and optional group path. Unlike a one-time memoized calculation, callers provide the newly computed value; the cache compares it with the previous one.
import { createCacheStorage } from '@khanglvm/react/helpers'
const { cache, clear, uid } = createCacheStorage()
const group = uid()
const first = cache({ count: 1 }, 'summary', group)
const second = cache({ count: 1 }, 'summary', group)
console.log(first === second) // true
clear(group)cache(value, entryId, ...groupKeys) returns the earlier value when deepEqual says they match. clear(...groupKeys) removes a group path; uid() returns a new symbol. All equality limitations above apply. A cached undefined counts as empty, so the next call stores its value without comparing.
A typical use is a selector for an external store that maps raw data into a new object on every read: passing the result through cache returns the same reference while the content is unchanged, which useSyncExternalStore requires to avoid rerendering in a loop. The state utility uses it this way for selected values.
There is no whole-cache clear: clear() with no keys does nothing. Supplying a factory ID fixes the entry ID, but its bound clear() does not reliably remove the resulting entry. Prefer the unbound factory with explicit groups, as above, and clear groups when their owner is done. Skip this helper when a stable reference or React useMemo already solves the problem.
Memo comparison
comparePropsForMemo(keys) builds a comparator for named props. compareAllPropsForMemo(previous, next) compares the keys present in the previous props object. Both use deepEqual.
import { memo } from 'react'
import { comparePropsForMemo } from '@khanglvm/react/helpers'
type LabelProps = { label: string }
export const Label = memo(
function Label({ label }: LabelProps) { return <span>{label}</span> },
comparePropsForMemo<LabelProps>('label'),
)For all existing keys, memo(Component, compareAllPropsForMemo) is the companion shorthand; note the added-prop limitation below.
These save writing a custom comparator when bounded nested props need value comparison. Default memo is usually the simpler starting point. Include every prop that affects output or behavior, including callbacks; an ignored callback can retain stale data. compareAllPropsForMemo can miss a newly added prop because it only visits the previous keys. Both follow the collection identity rules of deepEqual and do not support cyclic values.
React's memo documentation explains custom comparator costs and the need to compare function props. These helpers do not promise a faster render.
Children
The child helpers package repeated checks into named functions. Use them only when their exact rules match your component; most components can simply render children.
filterComponentFromChildren lets a compound component pick its slots out of children, such as <Row><Row.Avatar />...<Row.Tags /></Row>, and render each slot in its own place.
import {
isEmptyChildren,
isPrimitiveChildren,
isReactFragmentChildren,
filterComponentFromChildren,
} from '@khanglvm/react/helpers'
isEmptyChildren(null) // true
isPrimitiveChildren('Hello') // true
isReactFragmentChildren(<>Hello</>) // true
function Tab({ title }: { title: string }) { return <span>{title}</span> }
const tabs = filterComponentFromChildren(
[<Tab key="a" title="Overview" />, <span key="b">Other</span>],
Tab,
) // only the Tab element| Helper | Useful check | Exact behavior and limit |
|---|---|---|
isIterableChildren(children) | More than one child slot | Checks Children.count > 1; a one-item array returns false. The name does not mean general JavaScript iterability. |
isSingleReactElementChildren(child) | One non-primitive child slot | Excludes strings, numbers, booleans, null, and undefined. It does not call isValidElement; a one-item array can pass. Use React isValidElement for element validation. |
isReactFragmentChildren(child) | A fragment wrapper | Adds a fragment-type string check to the single-child check. It does not inspect the fragment's contents. |
isHTMLElementChildren(child) | A single non-fragment child | Also accepts custom React components; it does not prove a host HTML element. For that, check isValidElement(child) && typeof child.type === 'string'. |
isEmptyChildren(children) | Absent value | True only for null or undefined; false, an empty string, and an empty array do not pass. |
isPrimitiveChildren(children) | Text, number, or boolean | Booleans pass even though React does not render them as visible text. |
filterComponentFromChildren(children, Component) | Direct children of a chosen component type | Uses Children.toArray, filters valid elements, and checks exact child.type identity. It does not search inside fragments or rendered components. |
React documents these traversal boundaries in Children. These predicates are convenience checks, not validators for all ReactNode shapes.
Types
These exports affect TypeScript only. Use them to reduce repeated type expressions; they do not validate or change runtime values.
| Type | Use and example | Limit |
|---|---|---|
TAssertFunction<T> | A generic identity signature preserving a subtype: TAssertFunction<{ id: string }> | Declares a function type, not an assertion implementation |
MapKeyType<T> | Extract a Map key: MapKeyType<Map<string, number>> is string | Non-Map inputs resolve to never |
MapValueType<T> | Extract a Map value: MapValueType<Map<string, number>> is number | Non-Map inputs resolve to never |
ExtractValue<T, V> | Retain a constrained member: ExtractValue<'a' | 'b', 'a'> is 'a' | Returns V; it is not the built-in Extract filter |
TDeepReadonly<T> | Recursive readonly object/array view: TDeepReadonly<{ tags: string[] }> | No runtime freeze; collection handling omits some methods but does not recursively freeze entries or remove every mutator, such as Set.add |
TDeepMutable<T> | Remove readonly from nested objects/arrays: TDeepMutable<Readonly<{ count: number }>> | Built-ins and collection types are largely preserved |
DistributiveOmit<T, K> | Apply Omit to each union member: DistributiveOmit<{ kind: 'a'; x: number } | { kind: 'b'; y: string }, 'kind'> | A compile-time union transformation |
Prettify<T> | Expand an object intersection for easier type inspection: Prettify<{ a: string } & { b: number }> | Does not transform values |
Root exports also include TContextState and TStateManager, return-type aliases for their factories, plus LocalizedString and TranslationNamespace, described in the translation guide.
Next.js App Router
The package works in the App Router with one rule: hooks and stores run in client components, and plain functions run anywhere. This page lists what runs where and the setup that follows from it. The Next.js example puts it all together.
Use with coding agents
The repository includes an agent skill with the setup recipes, API rules and known pitfalls. Install it into your project with: