#1707 · stacks/stx

TL;DR

packages/stx/src/index.ts:11 re-exports CookieOptions from ./route-middleware, but the actual useCookie composable in packages/stx/src/composables/use-cookie.ts:8 defines its own CookieOptions interface with completely different fields. Consumers writing import { CookieOptions } from 'stx' get the route-middleware type, not the composable's — so passing options that the composable expects becomes a TypeScript error, or worse, options that the composable doesn't recognize are silently accepted at runtime.

Repro

import { useCookie, CookieOptions } from '@stacksjs/stx'

// `CookieOptions` here points at the route-middleware type, NOT the
// composable's options interface. The fields don't match.
const opts: CookieOptions = {
  maxAge: 60 * 60 * 24 * 30,  // composable's field
  sameSite: 'Lax',            // composable's field
}

const token = useCookie('auth-token', opts)  // type error or silent miss

The two types

packages/stx/src/route-middleware.ts:23 (currently the canonical CookieOptions per index.ts):

exports a route-middleware-specific options interface

packages/stx/src/composables/use-cookie.ts:8 (the one the composable actually uses):

defines a richer interface with defaultValue, path, domain, maxAge, expires, sameSite, secure, encode, decode, plus advanced polling options

Both are exported from their own modules under the same name. The index.ts re-export picks the route-middleware one as the canonical name.

Proposed fix

Two options:

Option A — rename one

Rename the route-middleware version to RouteMiddlewareCookieOptions (or just keep it internal to the module) and re-export only the composable's CookieOptions from the package root.

Option B — re-export from composables

Change packages/stx/src/index.ts:11 to:

export { type CookieOptions } from './composables/use-cookie'

Either way, the useCookie() composable's options should be the type users get when they import CookieOptions from 'stx' — that's the only one that's user-facing API.

Why this matters

Found during a deep-scan audit. Every TypeScript consumer using useCookie() either:

Hits IDE / build errors when passing valid options
Casts to any to work around the mismatch
Imports from the submodule path ('@stacksjs/stx/composables/use-cookie') — which the package's exports map may not even expose

This is a pure type-export bug — runtime behavior is fine, but the public TypeScript surface lies to users.

🤖 Filed via Claude Code