V2: Introduce connect-query-core package (#357)

A dedicated connect-query-core package makes it much easier to integrate
non-react integrations.

The public API of `@connectrpc/connect-query` hasn't changed at all, all
the same methods and types are exposed, we've just separated them into a
distinct package that gets reexported from `@connectrpc/connect-query`.

This change allows others to depend on connect-query without necessarily
depending on react and react-query.

Partially addresses #324

---------

Signed-off-by: Paul Sachs <[email protected]>
Co-authored-by: Timo Stamm <[email protected]>

.eslintrc.js

@@ -99,7 +99,7 @@ const config = {
       },
     },
     {
-      files: ["**/eliza/*", "**/gen/**", "**/snapshots/**"], // generated code
+      files: ["**/eliza/*", "gen/**", "**/gen/**", "**/snapshots/**"], // generated code
       rules: {
         "eslint-comments/no-unused-enable": "off",
         "eslint-comments/no-unused-disable": "off",

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "git.enableCommitSigning": true,
+  "git.alwaysSignOff": true,
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

packages/connect-query-core/.eslintignore

@@ -0,0 +1,2 @@
+dist
+coverage

packages/connect-query-core/README.md

@@ -0,0 +1,3 @@
+# @connectrpc/connect-query-core
+
+This package provides the core functionality for the Connect-Query API. It exposes all the necessary functions to use with the different variants of the tanstack/query packages. Documentation for these APIs can be found in the main repo readme at https://github.com/connectrpc/connect-query-es and covers any non-hook functions (anything that doesn't start with `use`).

packages/connect-query-core/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@connectrpc/connect-query-core",
+  "version": "2.0.0-rc.2",
+  "description": "Core of Connect-Query, framework agnostic helpers for type-safe queries.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/connectrpc/connect-query-es.git",
+    "directory": "packages/connect-query-core"
+  },
+  "scripts": {
+    "clean": "rm -rf ./dist/*",
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "tsc --project tsconfig.build.json --module commonjs --moduleResolution node10 --verbatimModuleSyntax false --outDir ./dist/cjs --declarationDir ./dist/cjs && echo >./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
+    "build:esm": "tsc --project tsconfig.build.json",
+    "test": "vitest --run",
+    "test:watch": "vitest --watch",
+    "format": "prettier . --write --ignore-path ./.eslintignore && eslint . --fix && license-header",
+    "attw": "attw --pack"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/cjs/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.15.2",
+    "@bufbuild/buf": "1.43.0",
+    "@bufbuild/jest-environment-jsdom": "^0.1.1",
+    "@bufbuild/protobuf": "^2.2.0",
+    "@bufbuild/protoc-gen-es": "^2.2.0",
+    "@connectrpc/connect": "^2.0.0-rc.1",
+    "@connectrpc/connect-web": "^2.0.0-rc.1",
+    "test-utils": "workspace:*",
+    "typescript": "^5.5.4"
+  },
+  "peerDependencies": {
+    "@bufbuild/protobuf": "2.x",
+    "@connectrpc/connect": "^2.0.0-rc.1",
+    "@tanstack/query-core": "5.x"
+  },
+  "files": [
+    "dist/**"
+  ]
+}

packages/connect-query/src/connect-query-key.test.ts → packages/connect-query-core/src/connect-query-key.test.ts

@@ -14,12 +14,12 @@
 
 import { create } from "@bufbuild/protobuf";
 import type { Transport } from "@connectrpc/connect";
-import { skipToken } from "@tanstack/react-query";
+import { ElizaService, SayRequestSchema } from "test-utils/gen/eliza_pb.js";
+import { ListRequestSchema, ListService } from "test-utils/gen/list_pb.js";
 import { describe, expect, it } from "vitest";
 
 import { createConnectQueryKey } from "./connect-query-key.js";
-import { ElizaService, SayRequestSchema } from "./gen/eliza_pb.js";
-import { ListRequestSchema, ListService } from "./gen/list_pb.js";
+import { skipToken } from "./index.js";
 import { createMessageKey } from "./message-key.js";
 import { createTransportKey } from "./transport-key.js";
 

packages/connect-query/src/connect-query-key.ts → packages/connect-query-core/src/connect-query-key.ts

@@ -18,7 +18,7 @@ import type {
   MessageInitShape,
 } from "@bufbuild/protobuf";
 import type { Transport } from "@connectrpc/connect";
-import type { SkipToken } from "@tanstack/react-query";
+import type { SkipToken } from "@tanstack/query-core";
 
 import { createMessageKey } from "./message-key.js";
 import { createTransportKey } from "./transport-key.js";

packages/connect-query/src/create-infinite-query-options.ts → packages/connect-query-core/src/create-infinite-query-options.ts

@@ -23,8 +23,8 @@ import type {
   GetNextPageParamFunction,
   QueryFunction,
   SkipToken,
-} from "@tanstack/react-query";
-import { skipToken } from "@tanstack/react-query";
+} from "@tanstack/query-core";
+import { skipToken } from "@tanstack/query-core";
 
 import { callUnaryMethod } from "./call-unary-method.js";
 import {

packages/connect-query/src/create-query-options.test.ts → packages/connect-query-core/src/create-query-options.test.ts

@@ -12,13 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { skipToken } from "@tanstack/react-query";
+import { skipToken as tanstackSkipToken } from "@tanstack/query-core";
+import { mockEliza } from "test-utils";
+import { ElizaService } from "test-utils/gen/eliza_pb.js";
 import { describe, expect, expectTypeOf, it } from "vitest";
 
 import { createConnectQueryKey } from "./connect-query-key.js";
 import { createQueryOptions } from "./create-query-options.js";
-import { ElizaService } from "./gen/eliza_pb.js";
-import { mockEliza } from "./test/test-utils.js";
+import { skipToken } from "./index.js";
 
 // TODO: maybe create a helper to take a service and method and generate this.
 const sayMethodDescriptor = ElizaService.method.say;
@@ -33,6 +34,14 @@ describe("createQueryOptions", () => {
     expect(opt.queryFn).toBe(skipToken);
     expectTypeOf(opt.queryFn).toEqualTypeOf(skipToken);
   });
+
+  it("honors skipToken directly from tanstack", () => {
+    const opt = createQueryOptions(sayMethodDescriptor, tanstackSkipToken, {
+      transport: mockedElizaTransport,
+    });
+    expect(opt.queryFn).toBe(tanstackSkipToken);
+  });
+
   it("sets queryKey", () => {
     const want = createConnectQueryKey({
       schema: sayMethodDescriptor,

packages/connect-query/src/create-query-options.ts → packages/connect-query-core/src/create-query-options.ts

@@ -20,8 +20,8 @@ import type {
 } from "@bufbuild/protobuf";
 import { create } from "@bufbuild/protobuf";
 import type { Transport } from "@connectrpc/connect";
-import type { QueryFunction, SkipToken } from "@tanstack/react-query";
-import { skipToken } from "@tanstack/react-query";
+import type { QueryFunction, SkipToken } from "@tanstack/query-core";
+import { skipToken } from "@tanstack/query-core";
 
 import { callUnaryMethod } from "./call-unary-method.js";
 import type { ConnectQueryKey } from "./connect-query-key.js";

packages/connect-query-core/src/index.ts

@@ -0,0 +1,25 @@
+// Copyright 2021-2023 The Connect Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export type { ConnectQueryKey } from "./connect-query-key.js";
+export { createConnectQueryKey } from "./connect-query-key.js";
+export { createProtobufSafeUpdater } from "./utils.js";
+export type { ConnectUpdater } from "./utils.js";
+export { callUnaryMethod } from "./call-unary-method.js";
+export { createInfiniteQueryOptions } from "./create-infinite-query-options.js";
+export type { ConnectInfiniteQueryOptions } from "./create-infinite-query-options.js";
+export { createQueryOptions } from "./create-query-options.js";
+export { addStaticKeyToTransport } from "./transport-key.js";
+export type { SkipToken } from "@tanstack/query-core";
+export { skipToken } from "@tanstack/query-core";

packages/connect-query/src/message-key.test.ts → packages/connect-query-core/src/message-key.test.ts

@@ -13,10 +13,10 @@
 // limitations under the License.
 
 import { create } from "@bufbuild/protobuf";
+import { Proto2MessageSchema } from "test-utils/gen/proto2_pb.js";
+import { Proto3Enum, Proto3MessageSchema } from "test-utils/gen/proto3_pb.js";
 import { describe, expect, it } from "vitest";
 
-import { Proto2MessageSchema } from "./gen/proto2_pb.js";
-import { Proto3Enum, Proto3MessageSchema } from "./gen/proto3_pb.js";
 import { createMessageKey } from "./message-key.js";
 
 describe("message key", () => {

packages/connect-query/src/structural-sharing.test.ts → packages/connect-query-core/src/structural-sharing.test.ts

@@ -13,9 +13,12 @@
 // limitations under the License.
 
 import { create } from "@bufbuild/protobuf";
+import {
+  SayRequestSchema,
+  SayResponseSchema,
+} from "test-utils/gen/eliza_pb.js";
 import { describe, expect, it } from "vitest";
 
-import { SayRequestSchema, SayResponseSchema } from "./gen/eliza_pb.js";
 import { createStructuralSharing } from "./structural-sharing.js";
 
 describe("structural sharing", () => {

packages/connect-query/src/utils.test.ts → packages/connect-query-core/src/utils.test.ts

@@ -13,9 +13,9 @@
 // limitations under the License.
 
 import { create, isFieldSet, isMessage } from "@bufbuild/protobuf";
+import { Proto2MessageSchema } from "test-utils/gen/proto2_pb.js";
 import { describe, expect, it } from "vitest";
 
-import { Proto2MessageSchema } from "./gen/proto2_pb.js";
 import {
   assert,
   createProtobufSafeUpdater,

packages/connect-query-core/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "declaration": true,
+    "declarationDir": "./dist/esm",
+    "outDir": "./dist/esm"
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["**/*.test.ts", "**/*.test.tsx", "src/test/**"]
+}

packages/connect-query-core/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noUnusedLocals": false, // necessary for TypeScript type tests, but since this is not enabled for build, unused variables have no risk of leaking into the build output
+    "lib": ["DOM", "ESNext"],
+    "noEmit": true,
+    "verbatimModuleSyntax": false
+  },
+  "exclude": ["coverage", "dist"],
+  "include": ["src", "./*.config.ts"]
+}

packages/connect-query-core/vite.config.ts

@@ -0,0 +1,36 @@
+// Copyright 2021-2023 The Connect Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { defineConfig } from "vitest/config";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  test: {
+    environment: "jsdom",
+    typecheck: {
+      enabled: true,
+      // Modified to typecheck definition files as well as source files
+      include: ["**/*.{test,spec}?(-d).?(c|m)[jt]s?(x)"],
+    },
+    coverage: {
+      provider: "istanbul",
+      thresholds: {
+        branches: 100,
+        functions: 100,
+        lines: 100,
+        statements: 100,
+      },
+    },
+  },
+});

packages/connect-query/package.json

@@ -13,7 +13,6 @@
     "build": "npm run build:cjs && npm run build:esm",
     "build:cjs": "tsc --project tsconfig.build.json --module commonjs --moduleResolution node10 --verbatimModuleSyntax false --outDir ./dist/cjs --declarationDir ./dist/cjs && echo >./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
     "build:esm": "tsc --project tsconfig.build.json",
-    "generate": "buf generate",
     "test": "vitest --run",
     "test:watch": "vitest --watch",
     "format": "prettier . --write --ignore-path ./.eslintignore && eslint . --fix && license-header",
@@ -28,6 +27,9 @@
       "require": "./dist/cjs/index.js"
     }
   },
+  "dependencies": {
+    "@connectrpc/connect-query-core": "workspace:*"
+  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.15.4",
     "@bufbuild/buf": "1.43.0",
@@ -42,6 +44,7 @@
     "@types/react-dom": "^18.3.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "test-utils": "workspace:*",
     "typescript": "^5.5.4"
   },
   "peerDependencies": {

packages/connect-query/src/call-unary-method.test.ts

@@ -13,17 +13,20 @@
 // limitations under the License.
 
 import { create } from "@bufbuild/protobuf";
+import type { ConnectQueryKey } from "@connectrpc/connect-query-core";
+import {
+  callUnaryMethod,
+  createConnectQueryKey,
+} from "@connectrpc/connect-query-core";
 import type { QueryFunctionContext } from "@tanstack/react-query";
 import { useQueries } from "@tanstack/react-query";
 import { renderHook, waitFor } from "@testing-library/react";
+import { mockEliza } from "test-utils";
+import type { SayRequest } from "test-utils/gen/eliza_pb.js";
+import { ElizaService, SayRequestSchema } from "test-utils/gen/eliza_pb.js";
 import { describe, expect, it } from "vitest";
 
-import { callUnaryMethod } from "./call-unary-method.js";
-import type { ConnectQueryKey } from "./connect-query-key.js";
-import { createConnectQueryKey } from "./connect-query-key.js";
-import type { SayRequest } from "./gen/eliza_pb.js";
-import { ElizaService, SayRequestSchema } from "./gen/eliza_pb.js";
-import { mockEliza, wrapper } from "./test/test-utils.js";
+import { wrapper } from "./test/test-wrapper.js";
 
 describe("callUnaryMethod", () => {
   it("can be used with useQueries", async () => {

packages/connect-query/src/index.ts

@@ -12,9 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-export type { ConnectQueryKey } from "./connect-query-key.js";
-export { createConnectQueryKey } from "./connect-query-key.js";
-export { createProtobufSafeUpdater } from "./utils.js";
+export * from "@connectrpc/connect-query-core";
 export { useTransport, TransportProvider } from "./use-transport.js";
 export {
   useInfiniteQuery,
@@ -23,10 +21,5 @@ export {
 export { useQuery, useSuspenseQuery } from "./use-query.js";
 export type { UseMutationOptions } from "./use-mutation.js";
 export { useMutation } from "./use-mutation.js";
-export type { ConnectUpdater } from "./utils.js";
-export { callUnaryMethod } from "./call-unary-method.js";
-export { createInfiniteQueryOptions } from "./create-infinite-query-options.js";
-export { createQueryOptions } from "./create-query-options.js";
 export type { UseInfiniteQueryOptions } from "./use-infinite-query.js";
 export type { UseQueryOptions } from "./use-query.js";
-export { addStaticKeyToTransport } from "./transport-key.js";