Query Layer

Use this pattern when you need to:

• Create queries or mutations that consume services
• Transform service-layer errors into user-facing error types
• Implement runtime service selection based on user settings
• Add optimistic cache updates for instant UI feedback
• Understand the dual interface pattern (reactive vs imperative)

Core Architecture

┌─────────────┐     ┌─────────────┐     ┌──────────────┐
│     UI      │ --> │  RPC/Query  │ --> │   Services   │
│ Components  │     │    Layer    │     │    (Pure)    │
└─────────────┘     └─────────────┘     └──────────────┘
      ↑                    │
      └────────────────────┘
         Reactive Updates

Query Layer Responsibilities:

• Call services with injected settings/configuration
• Transform service errors to user-facing error types for display
• Manage TanStack Query cache for optimistic updates
• Provide dual interfaces: reactive (.options) and imperative (.execute())

Error Transformation Pattern

Critical: Service errors should be transformed to user-facing error types at the query layer boundary.

Three-Layer Error Flow

Service Layer         →  Query Layer           →  UI Layer
TaggedError<'Name'>   →  UserFacingError       →  Toast notification
(domain-specific)        (display-ready)          (display)

Standard Error Transformation

import { Err, Ok } from 'wellcrafted/result';

// In query layer - transform service error to user-facing error
const { data, error } = await services.recorder.startRecording(params);

if (error) {
	return Err({
		title: '❌ Failed to start recording',
		description: error.message,
		action: { type: 'more-details', error },
	});
}

return Ok(data);

Dual Interface Pattern

Every query/mutation provides two ways to use it:

Reactive Interface: .options

Use in Svelte components for automatic state management. Pass .options (a static object) inside an accessor function:

<script lang="ts">
	import { createQuery, createMutation } from '@tanstack/svelte-query';
	import { rpc } from '$lib/query';

	// Reactive query - wrap in accessor function, access .options (no parentheses)
	const recorderState = createQuery(() => rpc.recorder.getRecorderState.options);

	// Reactive mutation - same pattern
	const transformRecording = createMutation(
		rpc.transformer.transformRecording.options,
	);
</script>

{#if recorderState.isPending}
	<Spinner />
{:else if recorderState.error}
	<Error message={recorderState.error.description} />
{:else}
	<RecorderIndicator state={recorderState.data} />
{/if}

Imperative Interface: .execute() / .fetch()

Use in event handlers and workflows without reactive overhead:

// In an event handler or workflow
async function handleTransform(recordingId: string, transformation: Transformation) {
	const { error } = await rpc.transformer.transformRecording({
		recordingId,
		transformation,
	});
	if (error) {
		notify.error(error);
		return;
	}
	notify.success({ title: 'Transformation complete' });
}

// In a sequential workflow
async function stopAndTranscribe(toastId: string) {
	const { data: blobData, error: stopError } =
		await rpc.recorder.stopRecording({ toastId });

	if (stopError) {
		notify.error(stopError);
		return;
	}

	// Continue with transcription...
}

When to Use Each

Key Rules

1. Always transform errors at query boundary - Never return raw service errors
2. Use .options (no parentheses) - It's a static object, wrap in accessor for Svelte
3. Never double-wrap errors - Each error is wrapped exactly once
4. Services are pure, queries inject settings - Services take explicit params
5. Use imperative calls in .ts files - createMutation requires component context
6. Update cache optimistically - Better UX for mutations

References

Load these on demand based on what you're working on:

• If working with error transformation examples and anti-patterns, read references/error-transformation-patterns.md

• If working with runtime dependency injection and service selection, read references/runtime-dependency-injection.md

• If working with cache management, query definitions, RPC namespace, or notify coordination, read references/advanced-query-patterns.md

• See apps/whispering/src/lib/query/README.md for detailed architecture

• See the services-layer skill for how services are implemented

• See the error-handling skill for trySync/tryAsync patterns and toast-on-error conventions