fix(lit-query): polish package validation and examples

gauravchugh · gauravchugh · commit 35e3ec0fb64e · 2026-04-17T03:31:40.000+05:30
diff --git a/.changeset/lemon-memes-divide.md b/.changeset/lemon-memes-divide.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/lit-query': patch
+---
+
+Add initial @tanstack/lit-query package
diff --git a/.gitignore b/.gitignore
@@ -10,7 +10,9 @@ yarn.lock
 build
 coverage
 dist
+dist-cjs
 dist-ts
+packages/lit-query/examples/**/output/playwright/
 
 # misc
 .DS_Store
diff --git a/knip.json b/knip.json
@@ -19,6 +19,9 @@
       "entry": ["src/v4/**/*.cjs", "src/v5/**/*.cjs"],
       "ignore": ["**/__testfixtures__/**"]
     },
+    "packages/lit-query": {
+      "ignore": ["examples/**", "src/tests/**"]
+    },
     "packages/vue-query": {
       "ignoreDependencies": ["vue2", "vue2.7"]
     }
diff --git a/packages/lit-query/examples/lit-query-e2e-app/e2e/lib.mjs b/packages/lit-query/examples/lit-query-e2e-app/e2e/lib.mjs
@@ -12,7 +12,7 @@ export const host = '127.0.0.1'
 export const port = DEMO_PORT
 export const baseUrl = `http://${host}:${port}`
 
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const packageManagerCommand = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
 const projectDir = new URL('..', import.meta.url)
 const allowExistingServer = process.env.PW_ALLOW_EXISTING_SERVER === 'true'
 const strictPortErrorPattern =
@@ -78,7 +78,7 @@ function startServer() {
   let startupError
 
   const child = spawn(
-    npmCommand,
+    packageManagerCommand,
     [
       'run',
       'dev',
diff --git a/packages/lit-query/examples/lit-query-e2e-app/package.json b/packages/lit-query/examples/lit-query-e2e-app/package.json
@@ -14,8 +14,8 @@
     "e2e:refetch-button": "node ./e2e/refetch-button.mjs",
     "e2e:lifecycle-reconnect": "node ./e2e/lifecycle-reconnect.mjs",
     "e2e:lifecycle-contract": "node ./e2e/lifecycle-contract.mjs",
-    "e2e:all": "npm run e2e && npm run e2e:query-error && npm run e2e:mutation-error && npm run e2e:refetch-button && npm run e2e:lifecycle-reconnect && npm run e2e:lifecycle-contract",
-    "e2e:all:headed": "PW_HEADLESS=false npm run e2e:all"
+    "e2e:all": "pnpm run e2e && pnpm run e2e:query-error && pnpm run e2e:mutation-error && pnpm run e2e:refetch-button && pnpm run e2e:lifecycle-reconnect && pnpm run e2e:lifecycle-contract",
+    "e2e:all:headed": "PW_HEADLESS=false pnpm run e2e:all"
   },
   "dependencies": {
     "@tanstack/lit-query": "file:../..",
diff --git a/packages/lit-query/examples/lit-query-pagination-app/e2e/lib.mjs b/packages/lit-query/examples/lit-query-pagination-app/e2e/lib.mjs
@@ -12,7 +12,7 @@ export const host = '127.0.0.1'
 export const apiUrl = `http://${host}:${API_PORT}`
 export const baseUrl = `http://${host}:${DEMO_PORT}`
 
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const packageManagerCommand = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
 const projectDir = new URL('..', import.meta.url)
 const allowExistingServer = process.env.PW_ALLOW_EXISTING_SERVER === 'true'
 const strictPortErrorPattern =
@@ -77,7 +77,7 @@ async function captureFailureArtifacts(page, error) {
 function startProcess(name, args, extraEnv = {}) {
   let startupError
 
-  const child = spawn(npmCommand, args, {
+  const child = spawn(packageManagerCommand, args, {
     cwd: projectDir,
     env: {
       ...process.env,
diff --git a/packages/lit-query/examples/lit-query-pagination-app/package.json b/packages/lit-query/examples/lit-query-pagination-app/package.json
@@ -14,8 +14,8 @@
     "e2e:error": "node ./e2e/error-recovery.mjs",
     "e2e:mutations": "node ./e2e/mutations.mjs",
     "e2e:boundary": "node ./e2e/boundary.mjs",
-    "e2e:all": "npm run e2e && npm run e2e:prefetch && npm run e2e:error && npm run e2e:mutations && npm run e2e:boundary",
-    "e2e:all:headed": "PW_HEADLESS=false npm run e2e:all"
+    "e2e:all": "pnpm run e2e && pnpm run e2e:prefetch && pnpm run e2e:error && pnpm run e2e:mutations && pnpm run e2e:boundary",
+    "e2e:all:headed": "PW_HEADLESS=false pnpm run e2e:all"
   },
   "dependencies": {
     "@tanstack/lit-query": "file:../..",
diff --git a/packages/lit-query/examples/lit-query-pagination-app/scripts/dev.mjs b/packages/lit-query/examples/lit-query-pagination-app/scripts/dev.mjs
@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process'
 import { once } from 'node:events'
 import { API_PORT } from '../config/ports.js'
 
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const packageManagerCommand = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
 const cwd = new URL('..', import.meta.url)
 
 function forwardOutput(prefix, stream, output) {
@@ -12,7 +12,7 @@ function forwardOutput(prefix, stream, output) {
 }
 
 function start(name, args, extraEnv = {}) {
-  const child = spawn(npmCommand, args, {
+  const child = spawn(packageManagerCommand, args, {
     cwd,
     stdio: ['ignore', 'pipe', 'pipe'],
     env: {
diff --git a/packages/lit-query/examples/lit-query-pagination-app/src/api.ts b/packages/lit-query/examples/lit-query-pagination-app/src/api.ts
@@ -69,20 +69,19 @@ async function readJsonOrThrow<T>(
   response: Response,
   fallbackMessage: string,
 ): Promise<T> {
+  if (response.ok) {
+    return (await response.json()) as T
+  }
+
   const payload = (await response.json().catch(() => null)) as
     | { error?: string }
-    | T
     | null
 
-  if (!response.ok) {
-    throw new Error(
-      payload && typeof payload === 'object' && 'error' in payload
-        ? String(payload.error ?? fallbackMessage)
-        : fallbackMessage,
-    )
-  }
-
-  return payload as T
+  throw new Error(
+    payload && typeof payload === 'object' && 'error' in payload
+      ? String(payload.error ?? fallbackMessage)
+      : fallbackMessage,
+  )
 }
 
 async function requestJson<T>(
diff --git a/packages/lit-query/examples/lit-query-ssr-app/e2e/lib.mjs b/packages/lit-query/examples/lit-query-ssr-app/e2e/lib.mjs
@@ -8,7 +8,7 @@ import { fileURLToPath } from 'node:url'
 import { chromium } from 'playwright'
 import { SSR_BASE_URL } from '../config/ports.js'
 
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const packageManagerCommand = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
 const cwd = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const allowExistingServer = process.env.PW_ALLOW_EXISTING_SERVER === 'true'
 const strictPortErrorPattern =
@@ -23,7 +23,7 @@ const selectorTimeoutMs = 10_000
 export const baseUrl = SSR_BASE_URL
 
 export function runBuild() {
-  const result = spawnSync(npmCommand, ['run', 'build'], {
+  const result = spawnSync(packageManagerCommand, ['run', 'build'], {
     cwd,
     stdio: 'inherit',
   })
@@ -36,7 +36,7 @@ export function runBuild() {
 function startServer() {
   let startupError
 
-  const child = spawn(npmCommand, ['run', 'dev:server'], {
+  const child = spawn(packageManagerCommand, ['run', 'dev:server'], {
     cwd,
     env: {
       ...process.env,
diff --git a/packages/lit-query/examples/lit-query-ssr-app/package.json b/packages/lit-query/examples/lit-query-ssr-app/package.json
@@ -12,7 +12,7 @@
     "e2e:public-origin": "node ./scripts/run-script-with-public-origin.mjs e2e",
     "e2e:error": "node ./e2e/error-recovery.mjs",
     "e2e:refreshing": "node ./e2e/refreshing.mjs",
-    "e2e:all": "npm run e2e && npm run e2e:error && npm run e2e:refreshing",
+    "e2e:all": "pnpm run e2e && pnpm run e2e:error && pnpm run e2e:refreshing",
     "e2e:all:public-origin": "node ./scripts/run-script-with-public-origin.mjs e2e:all"
   },
   "dependencies": {
diff --git a/packages/lit-query/examples/lit-query-ssr-app/scripts/dev.mjs b/packages/lit-query/examples/lit-query-ssr-app/scripts/dev.mjs
@@ -34,8 +34,14 @@ async function run() {
   process.on('SIGINT', () => stopServer('SIGINT'))
   process.on('SIGTERM', () => stopServer('SIGTERM'))
 
-  const [code] = await once(server, 'exit')
-  process.exitCode = code ?? 0
+  const outcome = await Promise.race([
+    once(server, 'error').then(([error]) => {
+      throw error
+    }),
+    once(server, 'exit').then(([code]) => ({ code })),
+  ])
+
+  process.exitCode = outcome.code ?? 0
 }
 
 run().catch((error) => {
diff --git a/packages/lit-query/examples/lit-query-ssr-app/scripts/run-script-with-public-origin.mjs b/packages/lit-query/examples/lit-query-ssr-app/scripts/run-script-with-public-origin.mjs
@@ -3,15 +3,15 @@ import { once } from 'node:events'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-const npmCommand = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const packageManagerCommand = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm'
 const cwd = resolve(dirname(fileURLToPath(import.meta.url)), '..')
 const scriptName = process.argv[2]
 
 if (!scriptName) {
-  throw new Error('Missing npm script name for public-origin wrapper.')
+  throw new Error('Missing script name for public-origin wrapper.')
 }
 
-const child = spawn(npmCommand, ['run', scriptName], {
+const child = spawn(packageManagerCommand, ['run', scriptName], {
   cwd,
   env: {
     ...process.env,
diff --git a/packages/lit-query/examples/lit-query-ssr-app/server/index.mjs b/packages/lit-query/examples/lit-query-ssr-app/server/index.mjs
@@ -155,7 +155,7 @@ async function readTemplate() {
   } catch (error) {
     if (error && typeof error === 'object' && 'code' in error) {
       throw new Error(
-        'Missing built client assets. Run "npm run build" in examples/lit-query-ssr-app first.',
+        'Missing built client assets. Run "pnpm run build" in examples/lit-query-ssr-app first.',
       )
     }
 
diff --git a/packages/lit-query/package.json b/packages/lit-query/package.json
@@ -95,21 +95,21 @@
     "lit": "^3.3.1"
   },
   "peerDependencies": {
-    "lit": ">=2.8.0 <4",
-    "@tanstack/query-core": "^5.0.0"
+    "@tanstack/query-core": "^5.0.0",
+    "lit": ">=2.8.0 <4"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.15.3",
     "@eslint/js": "^9.36.0",
-    "@types/node": "^24.5.2",
+    "@types/node": "^22.15.3",
     "@vitest/eslint-plugin": "^1.4.0",
     "eslint": "^9.36.0",
     "globals": "^17.4.0",
-    "jsdom": "^26.1.0",
+    "jsdom": "^27.0.0",
     "prettier": "^3.7.4",
     "publint": "^0.3.13",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.56.1",
-    "vitest": "^3.2.4"
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
   }
 }
diff --git a/packages/lit-query/src/createInfiniteQueryController.ts b/packages/lit-query/src/createInfiniteQueryController.ts
@@ -137,6 +137,10 @@ class InfiniteQueryController<
       return
     }
 
+    if (typeof options === 'function') {
+      return
+    }
+
     const defaulted = this.defaultOptions(queryClient)
     const observer = new InfiniteQueryObserver(queryClient, defaulted)
     this.queryClient = queryClient
diff --git a/packages/lit-query/src/createMutationController.ts b/packages/lit-query/src/createMutationController.ts
@@ -61,6 +61,7 @@ function createIdleMutationResult<
     isError: false,
     isIdle: true,
     isPending: false,
+    isPaused: false,
     isSuccess: false,
     status: 'idle',
     submittedAt: 0,
@@ -114,6 +115,10 @@ class MutationController<
       return
     }
 
+    if (typeof options === 'function') {
+      return
+    }
+
     const observer = new MutationObserver(
       queryClient,
       this.defaultOptions(queryClient),
diff --git a/packages/lit-query/src/createQueriesController.ts b/packages/lit-query/src/createQueriesController.ts
@@ -228,6 +228,37 @@ function createPendingQueryObserverResult(): QueryObserverResult {
   } as unknown as QueryObserverResult
 }
 
+function createPlaceholderQueryObserverResult(
+  query: QueryObserverOptions,
+): QueryObserverResult {
+  const initialData =
+    typeof query.initialData === 'function'
+      ? query.initialData()
+      : query.initialData
+
+  if (initialData === undefined) {
+    return createPendingQueryObserverResult()
+  }
+
+  const data = query.select ? query.select(initialData) : initialData
+  const initialDataUpdatedAt =
+    typeof query.initialDataUpdatedAt === 'function'
+      ? query.initialDataUpdatedAt()
+      : query.initialDataUpdatedAt
+
+  return {
+    ...createPendingQueryObserverResult(),
+    data,
+    dataUpdatedAt: initialDataUpdatedAt ?? Date.now(),
+    isPending: false,
+    isInitialLoading: false,
+    isLoading: false,
+    isSuccess: true,
+    status: 'success',
+    promise: Promise.resolve(data as never),
+  } as QueryObserverResult
+}
+
 function resolveQueriesOptions<TCombinedResult>(
   optionsAccessor: Accessor<
     CreateQueriesControllerOptions<any, TCombinedResult>
@@ -286,6 +317,10 @@ class QueriesController<
       return
     }
 
+    if (this.shouldRefreshOnHostUpdate()) {
+      return
+    }
+
     const { queries, combine } = resolveQueriesOptions(options, queryClient)
     const observer = new QueriesObserver(queryClient, queries, {
       combine,
@@ -434,7 +469,9 @@ class QueriesController<
   ): TCombinedResult {
     const resolvedOptions = readAccessor(optionsAccessor)
     const queries = readAccessor(resolvedOptions.queries)
-    const placeholders = queries.map(() => createPendingQueryObserverResult())
+    const placeholders = queries.map((query) =>
+      createPlaceholderQueryObserverResult(query as QueryObserverOptions),
+    )
     return (
       resolvedOptions.combine
         ? resolvedOptions.combine(placeholders as never)
diff --git a/packages/lit-query/src/createQueryController.ts b/packages/lit-query/src/createQueryController.ts
@@ -102,6 +102,10 @@ class QueryController<
       return
     }
 
+    if (typeof options === 'function') {
+      return
+    }
+
     const defaulted = this.defaultOptions(initialClient)
     const observer = new QueryObserver(initialClient, defaulted)
     this.queryClient = initialClient
diff --git a/packages/lit-query/src/tests/infinite-and-options.test.ts b/packages/lit-query/src/tests/infinite-and-options.test.ts
@@ -301,6 +301,52 @@ describe('createInfiniteQueryController', () => {
 
     infinite.destroy()
   })
+
+  it('LC-INF-04: explicit-client infinite accessors defer until host fields are initialized', () => {
+    const client = new QueryClient()
+
+    class DeferredExplicitInfiniteHost implements ReactiveControllerHost {
+      private readonly controllers = new Set<ReactiveController>()
+
+      updatesRequested = 0
+      readonly updateComplete: Promise<boolean> = Promise.resolve(true)
+
+      readonly infinite = createInfiniteQueryController(
+        this,
+        () => ({
+          queryKey: ['deferred-explicit-infinite', this.id] as const,
+          initialPageParam: 0,
+          queryFn: async ({ pageParam }) => Number(pageParam),
+          getNextPageParam: (lastPage) =>
+            lastPage < 1 ? lastPage + 1 : undefined,
+          retry: false,
+        }),
+        client,
+      )
+
+      readonly firstRead = this.infinite()
+      readonly id = 'alpha'
+
+      addController(controller: ReactiveController): void {
+        this.controllers.add(controller)
+      }
+
+      removeController(controller: ReactiveController): void {
+        this.controllers.delete(controller)
+      }
+
+      requestUpdate(): void {
+        this.updatesRequested += 1
+      }
+    }
+
+    expect(() => new DeferredExplicitInfiniteHost()).not.toThrow()
+
+    const host = new DeferredExplicitInfiniteHost()
+    expect(host.infinite().status).toBe('pending')
+
+    host.infinite.destroy()
+  })
 })
 
 describe('options helpers integration', () => {
diff --git a/packages/lit-query/src/tests/mutation-controller.test.ts b/packages/lit-query/src/tests/mutation-controller.test.ts
diff --git a/packages/lit-query/src/tests/queries-controller.test.ts b/packages/lit-query/src/tests/queries-controller.test.ts
diff --git a/packages/lit-query/src/tests/query-controller.test.ts b/packages/lit-query/src/tests/query-controller.test.ts
diff --git a/packages/lit-query/src/types.ts b/packages/lit-query/src/types.ts
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@tanstack/lit-query': patch
 +---
++
 +Add initial @tanstack/lit-query package