([
+ { database: 'postgres' },
+ { database: 'postgres' },
+ { database: 'analytics' },
+ ]);
+ setDatabases = databases.set;
+ collection = createQueryCollection({
+ runtime,
+ query: schemaByDatabase,
+ inputs: databases,
+ key: ({ database }) => database,
+ concurrency: 2,
+ });
+
+ return {collection.entries.map(({ key }) => key).join(',')}
;
+ };
+
+ const { container, cleanup } = createTestContainer();
+ try {
+ createIsland({ root: container, component: App });
+ flushScheduler();
+ await settleCollection(collection);
+
+ expect(container.textContent).toBe('postgres,analytics');
+ expect(fetchCounts).toEqual(
+ new Map([
+ ['postgres', 1],
+ ['analytics', 1],
+ ])
+ );
+ const postgresQuery = collection.get('postgres')?.query;
+ const analyticsQuery = collection.get('analytics')?.query;
+
+ setDatabases([
+ { database: 'analytics' },
+ { database: 'postgres' },
+ { database: 'analytics' },
+ { database: 'warehouse' },
+ ]);
+ flushScheduler();
+ await settleCollection(collection);
+
+ expect(container.textContent).toBe('analytics,postgres,warehouse');
+ expect(collection.get('postgres')?.query).toBe(postgresQuery);
+ expect(collection.get('analytics')?.query).toBe(analyticsQuery);
+ expect(fetchCounts.get('warehouse')).toBe(1);
+
+ invalidate('schemas:analytics', { runtime });
+ await settleCollection(collection);
+ expect(fetchCounts.get('analytics')).toBe(2);
+
+ setDatabases([{ database: 'warehouse' }, { database: 'analytics' }]);
+ flushScheduler();
+
+ expect(runtime.queryCache.has('schemas:postgres')).toBe(false);
+ expect([...collection.results.keys()]).toEqual([
+ 'warehouse',
+ 'analytics',
+ ]);
+ } finally {
+ cleanup();
+ }
+ });
+
+ it('should share cache entries and request deduplication with createQuery', async () => {
+ const runtime = createDataRuntime();
+ const fetch = vi.fn(
+ async ({ id }: { id: string; signal: AbortSignal }) => ({
+ id,
+ })
+ );
+ const userById = defineQuery({
+ key: ({ id }: { id: string }) => `users:${id}`,
+ fetch,
+ });
+ let singleQuery!: Query<{ id: string }>;
+ let collection!: QueryCollection<{ id: string }, { id: string }, string>;
+
+ const App = (): JSXElement => {
+ singleQuery = createQuery(userById, { id: '123' }, { runtime });
+ collection = createQueryCollection({
+ runtime,
+ query: userById,
+ inputs: () => [{ id: '123' }],
+ key: ({ id }) => id,
+ });
+ return {collection.get('123')?.query.data?.id ?? 'loading'}
;
+ };
+
+ const { container, cleanup } = createTestContainer();
+ try {
+ createIsland({ root: container, component: App });
+ flushScheduler();
+ await settleCollection(collection);
+
+ expect(fetch).toHaveBeenCalledTimes(1);
+ expect(collection.get('123')?.query).toBe(singleQuery);
+ expect(container.textContent).toBe('123');
+ } finally {
+ cleanup();
+ }
+ });
+
+ it('should surface per-key errors and retry through the collection queue', async () => {
+ type RetryInput = { id: string };
+ const attempts = new Map();
+ const query = defineQuery({
+ key: ({ id }: RetryInput) => `retry:${id}`,
+ fetch: async ({ signal, id }) => {
+ signal.throwIfAborted();
+ const attempt = (attempts.get(id) ?? 0) + 1;
+ attempts.set(id, attempt);
+ if (id === 'failed' && attempt === 1) throw new Error('try again');
+ return { id, attempt };
+ },
+ });
+ let collection!: QueryCollection<
+ RetryInput,
+ { id: string; attempt: number },
+ string
+ >;
+
+ const App = (): JSXElement => {
+ collection = createQueryCollection({
+ query,
+ inputs: () => [{ id: 'failed' }, { id: 'healthy' }],
+ key: ({ id }) => id,
+ concurrency: 1,
+ });
+ return {collection.errors.size}
;
+ };
+
+ const { container, cleanup } = createTestContainer();
+ try {
+ createIsland({ root: container, component: App });
+ flushScheduler();
+ await settleCollection(collection);
+
+ expect(collection.errors.get('failed')).toBeInstanceOf(Error);
+ expect(collection.results.get('healthy')).toEqual({
+ id: 'healthy',
+ attempt: 1,
+ });
+
+ const retry = collection.retry('failed');
+ flushScheduler();
+ await settleCollection(collection);
+ await retry;
+
+ expect(collection.errors.has('failed')).toBe(false);
+ expect(collection.results.get('failed')).toEqual({
+ id: 'failed',
+ attempt: 2,
+ });
+ } finally {
+ cleanup();
+ }
+ });
+
+ it('should abort active work and discard queued work as keys leave or the owner unmounts', async () => {
+ const started: string[] = [];
+ const aborted: string[] = [];
+ type LifecycleInput = { id: string };
+ let setKeys!: (value: readonly LifecycleInput[]) => void;
+ let collection!: QueryCollection;
+
+ const query = defineQuery({
+ key: ({ id }: LifecycleInput) => `lifecycle:${id}`,
+ fetch: ({ signal, id }) => {
+ started.push(id);
+ return new Promise<{ id: string }>((_resolve, reject) => {
+ signal.addEventListener(
+ 'abort',
+ () => {
+ aborted.push(id);
+ reject(new DOMException('Aborted', 'AbortError'));
+ },
+ { once: true }
+ );
+ });
+ },
+ });
+
+ const App = (): JSXElement => {
+ const keys = state([
+ { id: 'first' },
+ { id: 'second' },
+ { id: 'third' },
+ ]);
+ setKeys = keys.set;
+ collection = createQueryCollection({
+ query,
+ inputs: keys,
+ key: ({ id }) => id,
+ concurrency: 1,
+ });
+ return {collection.entries.length}
;
+ };
+
+ const { container, cleanup } = createTestContainer();
+ try {
+ createIsland({ root: container, component: App });
+ flushScheduler();
+ await settle();
+ expect(started).toEqual(['first']);
+
+ setKeys([{ id: 'second' }, { id: 'third' }]);
+ flushScheduler();
+ await settle();
+
+ expect(aborted).toEqual(['first']);
+ expect(started).toEqual(['first', 'second']);
+
+ cleanup();
+ await Promise.resolve();
+
+ expect(aborted).toEqual(['first', 'second']);
+ expect(started).toEqual(['first', 'second']);
+ } finally {
+ cleanup();
+ }
+ });
+});
diff --git a/tests/types/data.test-d.ts b/tests/types/data.test-d.ts
index 1f66c02c..3bc110ec 100644
--- a/tests/types/data.test-d.ts
+++ b/tests/types/data.test-d.ts
@@ -3,6 +3,7 @@ import {
createDataRuntime,
createMutation,
createQuery,
+ createQueryCollection,
createQueryPrefetchContext,
defineServerQueries,
defineQuery,
@@ -23,6 +24,10 @@ import {
type Mutation,
type MutationOptions,
type Query,
+ type QueryCollection,
+ type QueryCollectionEntry,
+ type QueryCollectionKey,
+ type QueryCollectionOptions,
type QueryConsistency,
type QueryDefinition,
type QueryKeyPart,
@@ -59,6 +64,34 @@ const userDefinition = defineQuery({
});
expectType>(userDefinition);
+const userCollectionOptions: QueryCollectionOptions<
+ { id: string },
+ { id: string },
+ string
+> = {
+ runtime: dataRuntime,
+ query: userDefinition,
+ inputs: () => [{ id: '123' }, { id: '456' }] as const,
+ key: ({ id }) => id,
+ concurrency: 2,
+};
+const userCollection = createQueryCollection(userCollectionOptions);
+expectType>(
+ userCollection
+);
+expectType<
+ readonly QueryCollectionEntry<{ id: string }, { id: string }, string>[]
+>(userCollection.entries);
+expectType(userCollection.loading);
+expectType(userCollection.settled);
+expectType>(userCollection.results);
+expectType>(userCollection.errors);
+expectType<
+ QueryCollectionEntry<{ id: string }, { id: string }, string> | undefined
+>(userCollection.get('123'));
+expectType>(userCollection.retry('123'));
+expectAssignable('123');
+
const userHandler: ServerQueryHandler<{ id: string }, { id: string }> = ({
input,
signal,
@@ -305,6 +338,21 @@ expectError(scoped.invalidate('buckets'));
expectError(invalidateOnInterval('user:'));
expectError(invalidateOnInterval('user:', { activeOn: '/' }));
expectError(invalidateOnInterval('user:', { intervalMs: '1000' }));
+expectError(
+ createQueryCollection({
+ query: userDefinition,
+ inputs: () => [{ id: '123' }],
+ key: ({ id }) => ({ id }),
+ })
+);
+expectError(
+ createQueryCollection({
+ query: userDefinition,
+ inputs: () => [{ id: '123' }],
+ key: ({ id }) => id,
+ concurrency: '2',
+ })
+);
expectError(
createQuery({
key: 'bad',
diff --git a/tests/unit/data/query-collection.test.ts b/tests/unit/data/query-collection.test.ts
new file mode 100644
index 00000000..6fbb1c2e
--- /dev/null
+++ b/tests/unit/data/query-collection.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it, vi } from 'vite-plus/test';
+import {
+ createQueryCollection,
+ normalizeQueryCollectionConcurrency,
+} from '../../../src/data/query-collection';
+import { createDataRuntime } from '../../../src/data/data-runtime';
+import { defineQuery } from '../../../src/data/query-registry';
+import { renderToStringSync } from '../../../src/ssr';
+
+describe('query collection concurrency', () => {
+ it('should use a bounded default and accept positive integers', () => {
+ expect(normalizeQueryCollectionConcurrency(undefined)).toBe(4);
+ expect(normalizeQueryCollectionConcurrency(1)).toBe(1);
+ expect(normalizeQueryCollectionConcurrency(8)).toBe(8);
+ });
+
+ it.each([0, -1, 1.5, Number.NaN, Number.POSITIVE_INFINITY])(
+ 'should reject invalid concurrency %s',
+ (concurrency) => {
+ expect(() => normalizeQueryCollectionConcurrency(concurrency)).toThrow(
+ '[Askr] createQueryCollection() concurrency must be a positive integer.'
+ );
+ }
+ );
+
+ it('should consume hydrated data without starting fetches during SSR', () => {
+ const runtime = createDataRuntime();
+ runtime.queryData.set('ssr-schema:postgres', { database: 'postgres' });
+ const fetch = vi.fn(async ({ database }: { database: string }) => ({
+ database,
+ }));
+ const query = defineQuery({
+ key: ({ database }: { database: string }) => `ssr-schema:${database}`,
+ fetch,
+ });
+
+ const html = renderToStringSync(() => {
+ const collection = createQueryCollection({
+ runtime,
+ query,
+ inputs: () => [{ database: 'postgres' }],
+ key: ({ database }) => database,
+ });
+ return collection.results.get('postgres')?.database ?? 'loading';
+ });
+
+ expect(html).toContain('postgres');
+ expect(fetch).not.toHaveBeenCalled();
+ });
+});
diff --git a/tests/unit/utils/public-entrypoints-resolve.test.ts b/tests/unit/utils/public-entrypoints-resolve.test.ts
index 228070ce..c5a9a173 100644
--- a/tests/unit/utils/public-entrypoints-resolve.test.ts
+++ b/tests/unit/utils/public-entrypoints-resolve.test.ts
@@ -40,6 +40,7 @@ describe('public entrypoint resolution', () => {
expect(typeof control.Match).toBe('function');
expect(typeof data.createQuery).toBe('function');
+ expect(typeof data.createQueryCollection).toBe('function');
expect(typeof data.createMutation).toBe('function');
expect(typeof data.invalidate).toBe('function');