@effector-tanstack-query/core 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilya Agarkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -5,6 +5,7 @@ var createInfiniteQuery_cjs = require('./createInfiniteQuery.cjs');
 var createMutation_cjs = require('./createMutation.cjs');
 var createInvalidate_cjs = require('./createInvalidate.cjs');
 var queryClient_cjs = require('./queryClient.cjs');
+var prefetchQueries_cjs = require('./prefetchQueries.cjs');
 
 
 
@@ -32,5 +33,9 @@ Object.defineProperty(exports, "setQueryClient", {
   enumerable: true,
   get: function () { return queryClient_cjs.setQueryClient; }
 });
+Object.defineProperty(exports, "prefetchQueries", {
+  enumerable: true,
+  get: function () { return prefetchQueries_cjs.prefetchQueries; }
+});
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -3,6 +3,7 @@ export { createInfiniteQuery } from './createInfiniteQuery.cjs';
 export { createMutation } from './createMutation.cjs';
 export { CreateInvalidateOptions, createInvalidate } from './createInvalidate.cjs';
 export { $queryClient, setQueryClient } from './queryClient.cjs';
+export { PrefetchQueriesConfig, PrefetchableQuery, prefetchQueries } from './prefetchQueries.cjs';
 export { CreateInfiniteQueryOptions, CreateMutationOptions, CreateQueryOptions, EffectorQueryKey, InfiniteQueryResult, MutationResult, MutationStatus, QueryResult, StoreOrValue } from './types.cjs';
 import '@tanstack/query-core';
 import 'effector';

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export { createInfiniteQuery } from './createInfiniteQuery.js';
 export { createMutation } from './createMutation.js';
 export { CreateInvalidateOptions, createInvalidate } from './createInvalidate.js';
 export { $queryClient, setQueryClient } from './queryClient.js';
+export { PrefetchQueriesConfig, PrefetchableQuery, prefetchQueries } from './prefetchQueries.js';
 export { CreateInfiniteQueryOptions, CreateMutationOptions, CreateQueryOptions, EffectorQueryKey, InfiniteQueryResult, MutationResult, MutationStatus, QueryResult, StoreOrValue } from './types.js';
 import '@tanstack/query-core';
 import 'effector';

package/dist/index.js

@@ -3,5 +3,6 @@ export { createInfiniteQuery } from './createInfiniteQuery.js';
 export { createMutation } from './createMutation.js';
 export { createInvalidate } from './createInvalidate.js';
 export { $queryClient, setQueryClient } from './queryClient.js';
+export { prefetchQueries } from './prefetchQueries.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/prefetchQueries.cjs

@@ -0,0 +1,14 @@
+'use strict';
+
+var effector = require('effector');
+
+// src/prefetchQueries.ts
+async function prefetchQueries(queries, config) {
+  const { scope } = config;
+  await Promise.all(queries.map((q) => effector.allSettled(q.prefetch, { scope })));
+  await Promise.all(queries.map((q) => effector.allSettled(q.mounted, { scope })));
+}
+
+exports.prefetchQueries = prefetchQueries;
+//# sourceMappingURL=prefetchQueries.cjs.map
+//# sourceMappingURL=prefetchQueries.cjs.map

package/dist/prefetchQueries.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/prefetchQueries.ts"],"names":["allSettled"],"mappings":";;;;;AA2DA,eAAsB,eAAA,CACpB,SACA,MAAA,EACe;AACf,EAAA,MAAM,EAAE,OAAM,GAAI,MAAA;AAClB,EAAA,MAAM,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAMA,mBAAA,CAAW,CAAA,CAAE,QAAA,EAAU,EAAE,KAAA,EAAO,CAAC,CAAC,CAAA;AACvE,EAAA,MAAM,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAMA,mBAAA,CAAW,CAAA,CAAE,OAAA,EAAS,EAAE,KAAA,EAAO,CAAC,CAAC,CAAA;AACxE","file":"prefetchQueries.cjs","sourcesContent":["import { allSettled } from 'effector'\nimport type { EventCallable, Scope } from 'effector'\n\n/**\n * Structural shape of any factory result that exposes the two SSR\n * lifecycle events. Both `QueryResult` and `InfiniteQueryResult` satisfy\n * this without forcing the caller to widen their `TData` / `TError` type\n * parameters.\n */\nexport interface PrefetchableQuery {\n  prefetch: EventCallable<void>\n  mounted: EventCallable<void>\n}\n\nexport interface PrefetchQueriesConfig {\n  /** Scope to run the lifecycle events in. Required — `allSettled` cannot\n   * await unit triggers outside of a scope. */\n  scope: Scope\n}\n\n/**\n * Server-side helper that fills **both** SSR layers for a set of queries:\n *\n *   1. `await allSettled(q.prefetch, { scope })` for each query — awaits\n *      `queryClient.fetchQuery(...)` so by the time the promise resolves\n *      the cache holds the data.\n *   2. `await allSettled(q.mounted, { scope })` for each query — creates\n *      the per-scope observer; its synchronous `getCurrentResult()`\n *      dispatch reads from the now-populated cache and writes into the\n *      effector stores (`$data`, `$status`, …). This is what makes\n *      `serialize(scope)` ship populated stores, which in turn lets the\n *      server-rendered HTML show data on first paint.\n *\n * Skipping step 2 (calling only `prefetch`) leaves the effector stores at\n * their defaults — `serialize(scope)` returns nothing useful, the\n * server-rendered HTML shows loading, and the user sees a flash on\n * hydration. This helper exists so that bug is impossible to write.\n *\n * Both phases run in parallel within themselves (`Promise.all`) but\n * sequentially across phases (`mounted` must see a populated cache).\n *\n * Snapshot the layers yourself afterwards — `dehydrate(queryClient)` for\n * the cache and `serialize(scope)` for the stores — and ship both to the\n * client (e.g. via `<HydrationBoundary state={...}>` + `<EffectorNext\n * values={...}>` or `fork({ values: ... })`).\n *\n * @example\n * ```ts\n * const queryClient = new QueryClient()\n * const scope = fork({ values: [[$queryClient, queryClient]] })\n *\n * await prefetchQueries([listQuery, pokemonQuery], { scope })\n *\n * return {\n *   dehydratedQueryClient: dehydrate(queryClient),\n *   serializedScope: serialize(scope),\n * }\n * ```\n */\nexport async function prefetchQueries(\n  queries: ReadonlyArray<PrefetchableQuery>,\n  config: PrefetchQueriesConfig,\n): Promise<void> {\n  const { scope } = config\n  await Promise.all(queries.map((q) => allSettled(q.prefetch, { scope })))\n  await Promise.all(queries.map((q) => allSettled(q.mounted, { scope })))\n}\n"]}

package/dist/prefetchQueries.d.cts

@@ -0,0 +1,59 @@
+import { Scope, EventCallable } from 'effector';
+
+/**
+ * Structural shape of any factory result that exposes the two SSR
+ * lifecycle events. Both `QueryResult` and `InfiniteQueryResult` satisfy
+ * this without forcing the caller to widen their `TData` / `TError` type
+ * parameters.
+ */
+interface PrefetchableQuery {
+    prefetch: EventCallable<void>;
+    mounted: EventCallable<void>;
+}
+interface PrefetchQueriesConfig {
+    /** Scope to run the lifecycle events in. Required — `allSettled` cannot
+     * await unit triggers outside of a scope. */
+    scope: Scope;
+}
+/**
+ * Server-side helper that fills **both** SSR layers for a set of queries:
+ *
+ *   1. `await allSettled(q.prefetch, { scope })` for each query — awaits
+ *      `queryClient.fetchQuery(...)` so by the time the promise resolves
+ *      the cache holds the data.
+ *   2. `await allSettled(q.mounted, { scope })` for each query — creates
+ *      the per-scope observer; its synchronous `getCurrentResult()`
+ *      dispatch reads from the now-populated cache and writes into the
+ *      effector stores (`$data`, `$status`, …). This is what makes
+ *      `serialize(scope)` ship populated stores, which in turn lets the
+ *      server-rendered HTML show data on first paint.
+ *
+ * Skipping step 2 (calling only `prefetch`) leaves the effector stores at
+ * their defaults — `serialize(scope)` returns nothing useful, the
+ * server-rendered HTML shows loading, and the user sees a flash on
+ * hydration. This helper exists so that bug is impossible to write.
+ *
+ * Both phases run in parallel within themselves (`Promise.all`) but
+ * sequentially across phases (`mounted` must see a populated cache).
+ *
+ * Snapshot the layers yourself afterwards — `dehydrate(queryClient)` for
+ * the cache and `serialize(scope)` for the stores — and ship both to the
+ * client (e.g. via `<HydrationBoundary state={...}>` + `<EffectorNext
+ * values={...}>` or `fork({ values: ... })`).
+ *
+ * @example
+ * ```ts
+ * const queryClient = new QueryClient()
+ * const scope = fork({ values: [[$queryClient, queryClient]] })
+ *
+ * await prefetchQueries([listQuery, pokemonQuery], { scope })
+ *
+ * return {
+ *   dehydratedQueryClient: dehydrate(queryClient),
+ *   serializedScope: serialize(scope),
+ * }
+ * ```
+ */
+declare function prefetchQueries(queries: ReadonlyArray<PrefetchableQuery>, config: PrefetchQueriesConfig): Promise<void>;
+
+export { type PrefetchQueriesConfig, type PrefetchableQuery, prefetchQueries };

package/dist/prefetchQueries.d.ts

@@ -0,0 +1,59 @@
+import { Scope, EventCallable } from 'effector';
+
+/**
+ * Structural shape of any factory result that exposes the two SSR
+ * lifecycle events. Both `QueryResult` and `InfiniteQueryResult` satisfy
+ * this without forcing the caller to widen their `TData` / `TError` type
+ * parameters.
+ */
+interface PrefetchableQuery {
+    prefetch: EventCallable<void>;
+    mounted: EventCallable<void>;
+}
+interface PrefetchQueriesConfig {
+    /** Scope to run the lifecycle events in. Required — `allSettled` cannot
+     * await unit triggers outside of a scope. */
+    scope: Scope;
+}
+/**
+ * Server-side helper that fills **both** SSR layers for a set of queries:
+ *
+ *   1. `await allSettled(q.prefetch, { scope })` for each query — awaits
+ *      `queryClient.fetchQuery(...)` so by the time the promise resolves
+ *      the cache holds the data.
+ *   2. `await allSettled(q.mounted, { scope })` for each query — creates
+ *      the per-scope observer; its synchronous `getCurrentResult()`
+ *      dispatch reads from the now-populated cache and writes into the
+ *      effector stores (`$data`, `$status`, …). This is what makes
+ *      `serialize(scope)` ship populated stores, which in turn lets the
+ *      server-rendered HTML show data on first paint.
+ *
+ * Skipping step 2 (calling only `prefetch`) leaves the effector stores at
+ * their defaults — `serialize(scope)` returns nothing useful, the
+ * server-rendered HTML shows loading, and the user sees a flash on
+ * hydration. This helper exists so that bug is impossible to write.
+ *
+ * Both phases run in parallel within themselves (`Promise.all`) but
+ * sequentially across phases (`mounted` must see a populated cache).
+ *
+ * Snapshot the layers yourself afterwards — `dehydrate(queryClient)` for
+ * the cache and `serialize(scope)` for the stores — and ship both to the
+ * client (e.g. via `<HydrationBoundary state={...}>` + `<EffectorNext
+ * values={...}>` or `fork({ values: ... })`).
+ *
+ * @example
+ * ```ts
+ * const queryClient = new QueryClient()
+ * const scope = fork({ values: [[$queryClient, queryClient]] })
+ *
+ * await prefetchQueries([listQuery, pokemonQuery], { scope })
+ *
+ * return {
+ *   dehydratedQueryClient: dehydrate(queryClient),
+ *   serializedScope: serialize(scope),
+ * }
+ * ```
+ */
+declare function prefetchQueries(queries: ReadonlyArray<PrefetchableQuery>, config: PrefetchQueriesConfig): Promise<void>;
+
+export { type PrefetchQueriesConfig, type PrefetchableQuery, prefetchQueries };

package/dist/prefetchQueries.js

@@ -0,0 +1,12 @@
+import { allSettled } from 'effector';
+
+// src/prefetchQueries.ts
+async function prefetchQueries(queries, config) {
+  const { scope } = config;
+  await Promise.all(queries.map((q) => allSettled(q.prefetch, { scope })));
+  await Promise.all(queries.map((q) => allSettled(q.mounted, { scope })));
+}
+
+export { prefetchQueries };
+//# sourceMappingURL=prefetchQueries.js.map
+//# sourceMappingURL=prefetchQueries.js.map

package/dist/prefetchQueries.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/prefetchQueries.ts"],"names":[],"mappings":";;;AA2DA,eAAsB,eAAA,CACpB,SACA,MAAA,EACe;AACf,EAAA,MAAM,EAAE,OAAM,GAAI,MAAA;AAClB,EAAA,MAAM,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAM,UAAA,CAAW,CAAA,CAAE,QAAA,EAAU,EAAE,KAAA,EAAO,CAAC,CAAC,CAAA;AACvE,EAAA,MAAM,OAAA,CAAQ,GAAA,CAAI,OAAA,CAAQ,GAAA,CAAI,CAAC,CAAA,KAAM,UAAA,CAAW,CAAA,CAAE,OAAA,EAAS,EAAE,KAAA,EAAO,CAAC,CAAC,CAAA;AACxE","file":"prefetchQueries.js","sourcesContent":["import { allSettled } from 'effector'\nimport type { EventCallable, Scope } from 'effector'\n\n/**\n * Structural shape of any factory result that exposes the two SSR\n * lifecycle events. Both `QueryResult` and `InfiniteQueryResult` satisfy\n * this without forcing the caller to widen their `TData` / `TError` type\n * parameters.\n */\nexport interface PrefetchableQuery {\n  prefetch: EventCallable<void>\n  mounted: EventCallable<void>\n}\n\nexport interface PrefetchQueriesConfig {\n  /** Scope to run the lifecycle events in. Required — `allSettled` cannot\n   * await unit triggers outside of a scope. */\n  scope: Scope\n}\n\n/**\n * Server-side helper that fills **both** SSR layers for a set of queries:\n *\n *   1. `await allSettled(q.prefetch, { scope })` for each query — awaits\n *      `queryClient.fetchQuery(...)` so by the time the promise resolves\n *      the cache holds the data.\n *   2. `await allSettled(q.mounted, { scope })` for each query — creates\n *      the per-scope observer; its synchronous `getCurrentResult()`\n *      dispatch reads from the now-populated cache and writes into the\n *      effector stores (`$data`, `$status`, …). This is what makes\n *      `serialize(scope)` ship populated stores, which in turn lets the\n *      server-rendered HTML show data on first paint.\n *\n * Skipping step 2 (calling only `prefetch`) leaves the effector stores at\n * their defaults — `serialize(scope)` returns nothing useful, the\n * server-rendered HTML shows loading, and the user sees a flash on\n * hydration. This helper exists so that bug is impossible to write.\n *\n * Both phases run in parallel within themselves (`Promise.all`) but\n * sequentially across phases (`mounted` must see a populated cache).\n *\n * Snapshot the layers yourself afterwards — `dehydrate(queryClient)` for\n * the cache and `serialize(scope)` for the stores — and ship both to the\n * client (e.g. via `<HydrationBoundary state={...}>` + `<EffectorNext\n * values={...}>` or `fork({ values: ... })`).\n *\n * @example\n * ```ts\n * const queryClient = new QueryClient()\n * const scope = fork({ values: [[$queryClient, queryClient]] })\n *\n * await prefetchQueries([listQuery, pokemonQuery], { scope })\n *\n * return {\n *   dehydratedQueryClient: dehydrate(queryClient),\n *   serializedScope: serialize(scope),\n * }\n * ```\n */\nexport async function prefetchQueries(\n  queries: ReadonlyArray<PrefetchableQuery>,\n  config: PrefetchQueriesConfig,\n): Promise<void> {\n  const { scope } = config\n  await Promise.all(queries.map((q) => allSettled(q.prefetch, { scope })))\n  await Promise.all(queries.map((q) => allSettled(q.mounted, { scope })))\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effector-tanstack-query/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Effector bindings for TanStack Query — core factories (createQuery, createMutation, createInfiniteQuery)",
   "license": "MIT",
   "author": "Ilya Agarkov <ilya.al.ag@gmail.com>",
@@ -43,6 +43,12 @@
     "!src/__tests__"
   ],
   "sideEffects": false,
+  "dependencies": {
+    "@tanstack/query-core": "^5.0.0"
+  },
+  "peerDependencies": {
+    "effector": ">=23.0.0"
+  },
   "scripts": {
     "build": "tsup",
     "build:watch": "tsup --watch",
@@ -50,11 +56,5 @@
     "test": "vitest --run",
     "test:watch": "vitest",
     "test:types": "tsc --noEmit"
-  },
-  "dependencies": {
-    "@tanstack/query-core": "^5.0.0"
-  },
-  "peerDependencies": {
-    "effector": ">=23.0.0"
   }
-}
+}

package/src/index.ts

@@ -4,6 +4,11 @@ export { createMutation } from './createMutation'
 export { createInvalidate } from './createInvalidate'
 export type { CreateInvalidateOptions } from './createInvalidate'
 export { $queryClient, setQueryClient } from './queryClient'
+export { prefetchQueries } from './prefetchQueries'
+export type {
+  PrefetchableQuery,
+  PrefetchQueriesConfig,
+} from './prefetchQueries'
 export type {
   CreateInfiniteQueryOptions,
   CreateMutationOptions,

package/src/prefetchQueries.ts

@@ -0,0 +1,67 @@
+import { allSettled } from 'effector'
+import type { EventCallable, Scope } from 'effector'
+
+/**
+ * Structural shape of any factory result that exposes the two SSR
+ * lifecycle events. Both `QueryResult` and `InfiniteQueryResult` satisfy
+ * this without forcing the caller to widen their `TData` / `TError` type
+ * parameters.
+ */
+export interface PrefetchableQuery {
+  prefetch: EventCallable<void>
+  mounted: EventCallable<void>
+}
+
+export interface PrefetchQueriesConfig {
+  /** Scope to run the lifecycle events in. Required — `allSettled` cannot
+   * await unit triggers outside of a scope. */
+  scope: Scope
+}
+
+/**
+ * Server-side helper that fills **both** SSR layers for a set of queries:
+ *
+ *   1. `await allSettled(q.prefetch, { scope })` for each query — awaits
+ *      `queryClient.fetchQuery(...)` so by the time the promise resolves
+ *      the cache holds the data.
+ *   2. `await allSettled(q.mounted, { scope })` for each query — creates
+ *      the per-scope observer; its synchronous `getCurrentResult()`
+ *      dispatch reads from the now-populated cache and writes into the
+ *      effector stores (`$data`, `$status`, …). This is what makes
+ *      `serialize(scope)` ship populated stores, which in turn lets the
+ *      server-rendered HTML show data on first paint.
+ *
+ * Skipping step 2 (calling only `prefetch`) leaves the effector stores at
+ * their defaults — `serialize(scope)` returns nothing useful, the
+ * server-rendered HTML shows loading, and the user sees a flash on
+ * hydration. This helper exists so that bug is impossible to write.
+ *
+ * Both phases run in parallel within themselves (`Promise.all`) but
+ * sequentially across phases (`mounted` must see a populated cache).
+ *
+ * Snapshot the layers yourself afterwards — `dehydrate(queryClient)` for
+ * the cache and `serialize(scope)` for the stores — and ship both to the
+ * client (e.g. via `<HydrationBoundary state={...}>` + `<EffectorNext
+ * values={...}>` or `fork({ values: ... })`).
+ *
+ * @example
+ * ```ts
+ * const queryClient = new QueryClient()
+ * const scope = fork({ values: [[$queryClient, queryClient]] })
+ *
+ * await prefetchQueries([listQuery, pokemonQuery], { scope })
+ *
+ * return {
+ *   dehydratedQueryClient: dehydrate(queryClient),
+ *   serializedScope: serialize(scope),
+ * }
+ * ```
+ */
+export async function prefetchQueries(
+  queries: ReadonlyArray<PrefetchableQuery>,
+  config: PrefetchQueriesConfig,
+): Promise<void> {
+  const { scope } = config
+  await Promise.all(queries.map((q) => allSettled(q.prefetch, { scope })))
+  await Promise.all(queries.map((q) => allSettled(q.mounted, { scope })))
+}