fix(useStorageValue): type value by the resolved initializeWithValue

[xobotyi]

value carried a bogus undefined whenever initializeWithValue was left at its default, forcing null checks that
can never fire. The runtime has read storage on the first render since 17.0.1 (#1002); the type never followed.

Supersedes #1647, which reported the same defect and targets the same conditional.

Problem

const {value} = useSessionStorageValue('name', {defaultValue: 'anonymous'});
//     ^? string | undefined
const token = useLocalStorageValue<string>('token').value;
//     ^? string | undefined

Initialize is only inferable from a literal initializeWithValue in the options object. Anything else leaves it at
the type-parameter default boolean | undefined, and since it is the checked type of a conditional, it distributes:

U = Initialize extends false ? undefined | N : N
// true      extends false -> N
// false     extends false -> undefined | N   <- contributes the undefined
// undefined extends false -> N

Flipping the conditional to false extends Initialize, as #1647 does, yields the same union — false is assignable to
boolean | undefined, so the deferred branch is picked anyway. The two forms are in fact interchangeable for every
instantiation the hooks can produce; asserting mutual assignability across true, false, undefined, boolean and
boolean | undefined compiles clean, and they diverge only on never.

So the defect is in the signature, not in the conditional.

Nor is raising the default to true enough. TypeScript does not infer a trailing type parameter once an earlier one is
passed explicitly — omitted ones take their defaults — so Initialize is never inferred when Type is written out, and
the documented SSR form stops compiling:

useLocalStorageValue<string>('key', {initializeWithValue: false});
//                                   ^ Type 'false' is not assignable to type 'true'.

Change

Two overloads pick the result type, with the existing three-parameter signature kept as a third:

export function useStorageValue<Type, Default extends Type = Type>(
	storage: Storage, key: string, options: UseStorageValueDeferredOptions<Type>,
): UseStorageValueResult<Type, Default, false>;
export function useStorageValue<Type, Default extends Type = Type>(
	storage: Storage, key: string, options?: UseStorageValueOptions<Type, true | undefined>,
): UseStorageValueResult<Type, Default, true>;

UseStorageValueDeferredOptions is UseStorageValueOptions<T, false> with initializeWithValue required, so
{defaultValue: 'x'} cannot match the deferred overload and fall through it. Default is inert either way — it is
unreachable by inference — but it stays, along with the third overload, so useLocalStorageValue<string, string, false>
resolves exactly as before.

UseStorageValueValue is untouched. Given a literal Initialize, the original conditional is already right.

Both wrappers declare their own signatures, so both get the same overload set.

One runtime fix is required to make the second overload honest. Options were resolved as
{...DEFAULT_OPTIONS, ...options}, and a spread copies an own key even when its value is undefined — so
{initializeWithValue: undefined} overrode the true default and deferred the read, while {defaultValue: undefined}
replaced the null fallback handed to parse. Both now resolve with ??, the pattern useCookieValue and
useScreenOrientation already use.

Resulting types

Measured by assigning each call's value to string in a scratch consumer, against published 26.1.0 and against the
packed branch build.

Call	Before	After
useLocalStorageValue<string>('k')	string | undefined	string
useLocalStorageValue('k', {defaultValue: 'x'})	string | undefined	string
useLocalStorageValue<string>('k', {initializeWithValue: true})	string | undefined	string
useLocalStorageValue<string>('k', {initializeWithValue: undefined})	string | undefined	string
useLocalStorageValue<string>('k', {initializeWithValue: false})	string | undefined	string | undefined
useLocalStorageValue<string>('k', {initializeWithValue: flag})	string | undefined	string | undefined
useLocalStorageValue<string, string, true>('k')	string	string
useLocalStorageValue<string, string, false>('k')	string | undefined	string | undefined

Narrowing only, and never in the other direction. Every call that compiled before still compiles, so this is a patch,
not a break.

Tests

Type-level assertions in index.types.test.ts beside each of the three hooks — every overload, every
initializeWithValue form, a runtime boolean flag, set's previous-state parameter, and the explicit type-argument
calls. Each case is repeated with an explicit Type, which is the shape the defect hid in.

The name matches neither vitest project pattern, so nothing runs; vp lint's typeCheck pass is the gate. Verified by
breaking an assertion:

src/useLocalStorageValue/index.types.test.ts:12:72: error typescript(TS2344):
  Type 'string | undefined' does not satisfy the constraint
  '"Expected: string, Actual: never" | "Expected: undefined, Actual: never"'.

Two DOM tests cover the option resolution: initializeWithValue: undefined reads on the first render,
defaultValue: undefined yields null. The second needs @ts-expect-error — exactOptionalPropertyTypes rejects the
explicit undefined, but consumers without it, and every JS consumer, can still pass one.

Verification

vp fmt --check, vp lint, vp test --run and vp run build pass on both commits. Coverage on the wrappers is
unchanged at 75%; branch coverage on useStorageValue goes 91.52% -> 92.06%.

Packed the tarball and typechecked a scratch consumer against it (react@19, moduleResolution: NodeNext): the
reproduction above exits 0, and the legacy three-type-argument calls, the UseStorageValueResult hand annotation, the
barrel import and the @react-hookz/web/useStorageValue subpath all still resolve.

Scope

The result type still claims Type when no defaultValue is given, though a missing key yields null at runtime.
Default is unreachable by inference (defaultValue?: T, not ?: Default), so the null | Type branch of
UseStorageValueValue is dead. Fixing that means value: string | null for useLocalStorageValue<string>('key') — a
break that needs its own major. Left alone here.

Checklist

• Have you read contribution guideline?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Is there an existing issue for this PR?
  • Closes Storage hooks type value as T | undefined when initializeWithValue is unset #1697
• Have the files been linted and formatted?
• Have the docs been updated to match the changes in the PR?
  • n/a — the JSDoc on initializeWithValue already documents @default true; this makes the type agree with it
• Have the tests been updated to match the changes in the PR?
• Have you run the tests locally to confirm they pass?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.23%. Comparing base (564391a) to head (0e16ed4).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1698      +/-   ##
==========================================
- Coverage   83.25%   83.23%   -0.02%     
==========================================
  Files          62       62              
  Lines         842      841       -1     
  Branches      151      151              
==========================================
- Hits          701      700       -1     
  Misses         16       16              
  Partials      125      125              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[sridharkalaibala]

I checked two runtime cases worth covering before treating the initialized result as definitely string.

Against this PR's head 0e16ed4, these functions pass a strict TypeScript check:

function useMissing(storage: Storage): string {
  return useStorageValue<string>(storage, 'missing').value;
}
function useLocal(): string {
  return useLocalStorageValue('missing', {defaultValue: 'anonymous'}).value;
}

But running the actual PR source through React renderToString gives:

• useStorageValue<string>(storage, 'missing') with getItem() returning null and no default: null.
• useStorageValue(storage, 'missing', {defaultValue: 'anonymous'}): 'anonymous' (control).
• useLocalStorageValue and useSessionStorageValue with that same default during SSR: undefined, from their unavailable-storage branches.

The nullability of an absent key and the SSR/unavailable-storage result are separate from whether the initial read is deferred. These are existing runtime behaviors, not a claim that this PR introduced them. The new no-options toEqualTypeOf<string>() assertion codifies a guarantee the first case does not satisfy; the wrapper overloads have the SSR gap even with a default.

Could the regression coverage include these cases and preserve their possible result types, or explicitly change/document the runtime contract before narrowing? I used a storage fixture and real React SSR, plus a strict source-level typecheck against the PR worktree; no browser blocked-storage environment was simulated.