@sometic/query

Portable server-state query client for Sometic: keys, cache, observers, mutations, and invalidation.

createQueryClient holds an in-memory cache keyed by query keys, with observers (createQueryObserver, createMutationObserver), invalidation, retries, and garbage collection options. Optional @sometic/query/http bridges @sometic/http via createHttpQueryFn so AbortSignals and safe URLs stay consistent.

Why it exists: UI client state belongs in @sometic/store; form values belong in @sometic/forms; session identity belongs in @sometic/auth. Server lists and detail payloads need a cache that can clear on session epoch changes. @sometic/app-shell binds query to auth for that wipe/refetch behavior.

Standout features: hashQueryKey / partialMatchKey, observer result shapes familiar to modern query libraries, mutation observers, and an HTTP helper that forwards context.signal. Framework hooks live in adapter packages (@sometic/react/query, @sometic/vue/query), keeping this core framework-free.

Depends on @sometic/core; optional peer @sometic/http. Docs: introduction and query utilities.

Install

pnpm add @sometic/query

npm install @sometic/query

yarn add @sometic/query

Optional HTTP bridge:

pnpm add @sometic/http

Usage

Create a client and observe a query:

import { createQueryClient, createQueryObserver } from "@sometic/query";

const query = createQueryClient({
    defaultOptions: { queries: { staleTime: 30_000 } },
});

const observer = createQueryObserver(query, {
    queryKey: ["users", "me"],
    queryFn: async ({ signal }) => {
        const response = await fetch("/api/users/me", { signal });
        return response.json();
    },
});

const stop = observer.subscribe(() => {
    console.log(observer.getCurrentResult().status);
});

Bridge @sometic/http into a query function:

import { createHttp } from "@sometic/http";
import { createHttpQueryFn, createQueryClient } from "@sometic/query";

const http = createHttp({ baseUrl: "https://api.example.com" });
const query = createQueryClient();

const queryFn = createHttpQueryFn<{ id: string }>({
    client: http,
    path: "/users/me",
});

await query.fetchQuery({ queryKey: ["users", "me"], queryFn });

CDN

Docs: https://sometic.dev/utilities/query.

Simple script

<script src="https://cdn.jsdelivr.net/npm/@sometic/[email protected]/dist/cdn/sometic-query.iife.js"></script>
<script>
    const client = SometicQuery.createQueryClient();
</script>

Module script

<script type="module">
    import { createQueryClient } from "https://cdn.jsdelivr.net/npm/@sometic/[email protected]/dist/cdn/sometic-query.esm.js";

    const client = createQueryClient();
</script>

Peers / when not to use

Optional peer: @sometic/http. Depends on @sometic/core.

Prefer TanStack Query when you need its plugin/devtools depth and are React-only. Prefer SWR for a React SWR mental model. Do not store session tokens or form drafts in the query cache; clear privileged caches on logout via app-shell / bindQueryToAuth.

Docs

• Introduction
• Query utilities
• HTTP
• App shell

License

MIT