Skip to content

dogfood: package .d.ts files drift from runtime exports (many import type errors) #388

Description

@vivek7405

Problem

Many import { ... } from '@webjsdev/core' statements are red-squiggled by TypeScript ("no exported member") even though they work at runtime. Surfaced while dogfooding the webjs VSCode extension (#382), but reproduces with a plain tsconfig too: the hand-maintained index.d.ts files have drifted from the runtime index.js named exports. The signal import was the first example; the audit below shows it is systemic.

Root cause + full audit

The .d.ts is maintained by hand and is missing a large fraction of the real runtime exports.

@webjsdev/core — 36 of 82 runtime exports missing from index.d.ts

Grouped (every one is exported by packages/core/index.js but absent from index.d.ts):

  • Component: WebComponent (!).
  • Signals (default state primitive, invariant 5): signal, computed, effect, batch, isSignal, Signal.
  • Directives: watch, cache, guard, keyed, ref, createRef, until, templateContent, asyncAppend, asyncReplace, and the is* guards (isWatch, isCache, isGuard, isKeyed, isRef, isUntil, isTemplateContent, isAsyncAppend, isAsyncReplace).
  • Serializer: serialize, deserialize, parse, stringify.
  • Streaming / frames / misc: WebjsFrame, WebjsStream, renderStream, revalidate, cspNonce, setCspNonceProvider.

Verified live: node --input-type=module -e "import { signal, computed } from '@webjsdev/core'" resolves both as functions; grep of index.d.ts finds 0 top-level exports for them.

@webjsdev/server — 12 candidates missing from index.d.ts

actionEndpoint, cookiesToHeader, getCsrf, getSetCookies, invokeActionForTest, loginAndGetCookies, rawActionRequest, readCsrfCookie, testRequest, toRequest, withCookies, withSessionCookie. Most look like test-harness helpers that may legitimately belong to @webjsdev/server/testing; confirm which are genuinely public vs which should move/stay omitted.

Fix

  • Add the missing declarations to each index.d.ts with correct generic signatures (e.g. Signal<T>, signal<T>(v: T): Signal<T>, the directive return types).
  • Add a guard test (per published package) asserting the .d.ts exports are a SUPERSET of index.js's runtime named exports, with a counterfactual that fails when a real export is dropped from the .d.ts. There is meant to be lockstep enforcement (see agent-docs/testing.md); it clearly didn't cover named-export coverage. This guard is what prevents the drift from recurring.

Subpath type resolution (@webjsdev/core/directives, /context, /task, /client-router, ...) is a SEPARATE root cause; tracked separately.

Acceptance criteria

  • Every @webjsdev/core runtime named export type-checks from import { x } from '@webjsdev/core'.
  • @webjsdev/server audit resolved (each of the 12 either declared or intentionally scoped to /testing).
  • A per-package guard test asserts d.ts exports superset runtime exports (counterfactual proven).
  • No remaining red import squiggles in a scaffolded app or the example components.

Metadata

Metadata

Assignees

Labels

bugSomething isn't working

Type

No type

Fields

No fields configured for issues without a type.

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions