ReviewOS

stacks/stx

useCookie is auto-imported but has no ambient declaration (TS2304 on correct code)

#1808
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

Verified against @stacksjs/stx at 0.2.153 (local build of main, HEAD 0dcb6fbd0e).

TL;DR

useCookie is in the auto-import list, so a <script client> block can call it as a bare global — but it has no ambient declaration, unlike every other entry in that list. Correct code fails to type-check.

Evidence

In the auto-import list — packages/stx/src/client-script.ts:322:

'useLocalStorage', 'useSessionStorage', 'useCookie',

Ambient declarations for these globals live in packages/stx/stx.d.ts (copied verbatim to dist/stx.d.ts), which declares useLocalStorage, useSessionStorage, useSearchParams, navigate, useColorMode and the rest. It declares useCookie zero times:

$ grep -c 'declare function useCookie' packages/stx/stx.d.ts
0

Why it matters

The composable works at runtime. The only thing missing is the type, so the failure lands entirely on correct code:

// <script client>
const token = useCookie('session', { maxAge: 2592000, sameSite: 'Lax' })
//            ^^^^^^^^^ TS2304: Cannot find name 'useCookie'.

An app either suppresses the error or hand-writes a local declaration — and a local ambient declaration for a symbol upstream later declares does not collide, it merges, so a stale local copy silently widens the real shape with no diagnostic.

One more wrinkle worth capturing in the same fix

useCookie appears to be the only entry in STX_AUTO_IMPORTS that is not also assigned as a bare property on window; it is reachable at window.stx.useCookie. That distinction does not matter inside a <script client> block, which gets the auto-import destructuring, but it does in a store module (storesDir) — store bundles are injected raw with no auto-import pass, so a bare useCookie(...) there is a ReferenceError while useLocalStorage(...) beside it works. Reaching it as window.stx.useCookie is the workaround.

If the declaration is added, it would be worth having it reflect that reachability difference, or making the assignment uniform with the rest of the list.

Suggested fix

Add a declaration to packages/stx/stx.d.ts matching the composable at packages/stx/src/composables/use-cookie.ts, returning the signal shape the runtime template produces rather than the module composable's CookieRef — the two already differ, which is #1710.

  • #1710 — two useCookie implementations that diverge
  • #1707 — CookieOptions shadowed by an unrelated re-export

Both are about which useCookie you get; this one is about there being no declaration at all for the auto-imported global. Filed alongside two other declaration/implementation mismatches (navigate, useSearchParams).

22 days ago

Fixed in 80101bf418.

Confirmed, and it wasn't only useCookie — five names were auto-imported and present on window.stx with no ambient declaration: useCookie, useId, useReactiveProp, definePageMeta, registerStoresClient. All five now declared.

useCookie returns the runtime's StxSignal<string>, not the module's CookieRef, per your suggestion — with a note on the one place they still differ: the module accepts a wider expires (Date, epoch ms, parseable string) while the runtime calls .toUTCString() on it, so only a Date works there. That's #1710 territory.

Your point about the workaround is the reason this needed a guard rather than just a fix: a hand-written local ambient declaration merges with the real one when it lands rather than colliding, so a stale local copy silently widens the true shape with no diagnostic. There's now a test checking both directions — every auto-imported name is declared, and no retired name creeps back in. It's structural (parsing the .d.ts) rather than type-level, because the defect was that the file said things the runtime doesn't do, which a type-level test would have inherited.

On your secondary observation — useCookie reachable only at window.stx.useCookie — that's now moot for the store case: it's in the shared runtime-globals list, which is what store and setup scripts destructure. See #1804.

Sign in to comment on this issue.