@veams/status-quo-query 0.1.0

package/eslint.config.mjs

@@ -0,0 +1,50 @@
+import { fileURLToPath } from 'node:url';
+
+import js from '@eslint/js';
+import { defineConfig } from 'eslint/config';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+const packageRoot = fileURLToPath(new URL('.', import.meta.url));
+const sourceFiles = ['src/**/*.ts'];
+const testFiles = ['src/**/*.{spec,test}.ts', 'src/**/__tests__/**/*.ts'];
+
+export default defineConfig(
+  {
+    ignores: ['coverage/**', 'dist/**'],
+  },
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  tseslint.configs.recommendedTypeChecked,
+  {
+    files: sourceFiles,
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+      parserOptions: {
+        project: './tsconfig.eslint.json',
+        tsconfigRootDir: packageRoot,
+      },
+      sourceType: 'module',
+    },
+    rules: {
+      '@typescript-eslint/consistent-type-imports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+    },
+  },
+  {
+    files: testFiles,
+    languageOptions: {
+      globals: {
+        ...globals.jest,
+      },
+    },
+  }
+);

package/jest.config.cjs

@@ -0,0 +1,22 @@
+module.exports = {
+  extensionsToTreatAsEsm: ['.ts'],
+  transformIgnorePatterns: [],
+  transform: {
+    '^.+\\.(t|j)sx?$': '@swc/jest',
+    '^.+\\.mjs$': '@swc/jest',
+  },
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+    '^(\\.{1,2}/.*)\\.mjs$': '$1',
+  },
+  verbose: false,
+  passWithNoTests: true,
+  clearMocks: true,
+  coverageDirectory: './coverage/',
+  coverageReporters: ['json-summary', ['text', { skipFull: true }], 'lcov'],
+  roots: ['<rootDir>/src'],
+  testMatch: ['**/__tests__/**/?(*.)+(spec|test).[jt]s?(x)'],
+  reporters: ['default'],
+  moduleFileExtensions: ['mjs', 'js', 'ts', 'jsx', 'tsx'],
+  testEnvironment: 'node',
+};

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@veams/status-quo-query",
+  "version": "0.1.0",
+  "description": "TanStack Query service layer for the VEAMS StatusQuo ecosystem.",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": "./dist/index.js"
+    },
+    "./mutation": {
+      "import": {
+        "types": "./dist/mutation.d.ts",
+        "default": "./dist/mutation.js"
+      },
+      "require": "./dist/mutation.js"
+    },
+    "./query": {
+      "import": {
+        "types": "./dist/query.d.ts",
+        "default": "./dist/query.js"
+      },
+      "require": "./dist/query.js"
+    },
+    "./cache": {
+      "import": {
+        "types": "./dist/cache.d.ts",
+        "default": "./dist/cache.js"
+      },
+      "require": "./dist/cache.js"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm-run-all compile",
+    "bundle:ts": "tsc --project tsconfig.json",
+    "check:types": "tsc --skipLibCheck --noEmit",
+    "compile": "npm-run-all bundle:ts",
+    "lint": "npm run lint:ts",
+    "lint:ts": "eslint --fix \"src/**/*.ts\"",
+    "test": "cross-env NODE_ENV=test jest --config jest.config.cjs",
+    "release": "npm run build && release-it"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@swc/core": "1.15.11",
+    "@swc/jest": "0.2.39",
+    "@tanstack/query-core": "5.91.2",
+    "@types/jest": "30.0.0",
+    "@types/node": "25.2.3",
+    "cross-env": "10.1.0",
+    "jest": "30.3.0",
+    "npm-run-all": "4.1.5",
+    "release-it": "19.2.4",
+    "tslib": "2.8.1",
+    "typescript": "5.9.3"
+  },
+  "keywords": [
+    "TanStack Query",
+    "StatusQuo",
+    "Service Layer"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Sebastian Fitzner",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Veams/veams.git",
+    "directory": "packages/status-quo-query"
+  },
+  "bugs": {
+    "url": "https://github.com/Veams/veams/issues"
+  }
+}

package/src/__tests__/cache.spec.ts

@@ -0,0 +1,32 @@
+import { QueryClient } from '@tanstack/query-core';
+
+import { setupCache } from '../cache';
+
+describe('Cache API', () => {
+  it('exposes cache-level query client operations', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const refetchQueriesSpy = jest.spyOn(queryClient, 'refetchQueries');
+    const cancelQueriesSpy = jest.spyOn(queryClient, 'cancelQueries');
+    const resetQueriesSpy = jest.spyOn(queryClient, 'resetQueries');
+    const removeQueriesSpy = jest.spyOn(queryClient, 'removeQueries');
+    const cache = setupCache(queryClient);
+
+    cache.setQueryData<{ id: number }>(['user', 42], { id: 42 });
+
+    expect(cache.getQueryData<{ id: number }>(['user', 42])).toEqual({ id: 42 });
+    expect(cache.unsafe_getClient()).toBe(queryClient);
+
+    await cache.invalidateQueries({ queryKey: ['user'] });
+    await cache.refetchQueries({ queryKey: ['user'] });
+    await cache.cancelQueries({ queryKey: ['user'] });
+    await cache.resetQueries({ queryKey: ['user'] });
+    cache.removeQueries({ queryKey: ['user'] });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
+    expect(refetchQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
+    expect(cancelQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
+    expect(resetQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
+    expect(removeQueriesSpy).toHaveBeenCalledWith({ queryKey: ['user'] });
+  });
+});

package/src/__tests__/mutation.spec.ts

@@ -0,0 +1,49 @@
+import { QueryClient } from '@tanstack/query-core';
+
+import { setupMutation } from '../mutation';
+
+describe('Mutation Service', () => {
+  it('tracks successful mutations', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { mutations: { retry: 0 } } });
+    const createMutation = setupMutation(queryClient);
+    let receivedPayload: { id: number } | undefined;
+    const mutationFn = jest.fn((payload: { id: number }) => {
+      receivedPayload = payload;
+      return Promise.resolve({ ok: true as const, id: payload.id });
+    });
+    const service = createMutation(mutationFn);
+
+    const statuses: string[] = [];
+    const unsubscribe = service.subscribe((snapshot) => {
+      statuses.push(snapshot.status);
+    });
+
+    expect(service.getSnapshot().status).toBe('idle');
+    expect(service.getSnapshot().isIdle).toBe(true);
+
+    const result = await service.mutate({ id: 42 });
+
+    unsubscribe();
+
+    expect(result).toEqual({ ok: true, id: 42 });
+    expect(receivedPayload).toEqual({ id: 42 });
+    expect(mutationFn).toHaveBeenCalledTimes(1);
+    expect(statuses).toContain('pending');
+    expect(statuses).toContain('success');
+    expect(service.getSnapshot().status).toBe('success');
+    expect(service.unsafe_getResult().data).toEqual({ ok: true, id: 42 });
+
+    service.reset();
+    expect(service.getSnapshot().status).toBe('idle');
+  });
+
+  it('tracks failed mutations', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { mutations: { retry: 0 } } });
+    const createMutation = setupMutation(queryClient);
+    const mutationFn = jest.fn().mockRejectedValue(new Error('boom'));
+    const service = createMutation(mutationFn);
+
+    await expect(service.mutate()).rejects.toThrow('boom');
+    expect(service.getSnapshot().status).toBe('error');
+  });
+});

package/src/__tests__/query.spec.ts

@@ -0,0 +1,80 @@
+import { QueryClient } from '@tanstack/query-core';
+
+import { isQueryLoading, setupQuery, toQueryMetaState } from '../query';
+
+describe('Query Service', () => {
+  it('returns data after refetch', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const queryFn = jest.fn().mockResolvedValue('hello');
+
+    const service = createQuery(['demo', 'query'], queryFn, { enabled: false });
+
+    expect(service.getSnapshot().data).toBeUndefined();
+
+    const result = await service.refetch();
+
+    expect(result.data).toBe('hello');
+    expect(service.getSnapshot().data).toBe('hello');
+    expect(service.unsafe_getResult().data).toBe('hello');
+    expect(queryFn).toHaveBeenCalledTimes(1);
+  });
+
+  it('notifies subscribers on updates', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const createQuery = setupQuery(queryClient);
+    const queryFn = jest.fn().mockResolvedValue('updated');
+    const service = createQuery(['demo', 'notify'], queryFn, { enabled: false });
+
+    const statuses: string[] = [];
+    const unsubscribe = service.subscribe((snapshot) => {
+      statuses.push(snapshot.status);
+    });
+
+    await service.refetch();
+    unsubscribe();
+
+    expect(statuses).toContain('pending');
+    expect(statuses).toContain('success');
+  });
+
+  it('invalidates its own query key exactly', async () => {
+    const queryClient = new QueryClient({ defaultOptions: { queries: { retry: 0 } } });
+    const invalidateQueriesSpy = jest.spyOn(queryClient, 'invalidateQueries');
+    const createQuery = setupQuery(queryClient);
+    const service = createQuery(['demo', 'invalidate'], jest.fn().mockResolvedValue('updated'), {
+      enabled: false,
+    });
+
+    await service.invalidate({ refetchType: 'none' });
+
+    expect(invalidateQueriesSpy).toHaveBeenCalledWith(
+      {
+        exact: true,
+        queryKey: ['demo', 'invalidate'],
+        refetchType: 'none',
+      },
+      undefined
+    );
+  });
+
+  it('derives loading state from query metadata', () => {
+    expect(
+      isQueryLoading(
+        toQueryMetaState({
+          fetchStatus: 'fetching',
+          status: 'pending',
+        })
+      )
+    ).toBe(true);
+
+    expect(
+      isQueryLoading(
+        toQueryMetaState({
+          fetchStatus: 'idle',
+          status: 'success',
+        })
+      )
+    ).toBe(false);
+  });
+});

package/src/cache.ts

@@ -0,0 +1,34 @@
+import {
+  type QueryClient,
+} from '@tanstack/query-core';
+
+import { type CreateMutation, setupMutation } from './mutation';
+import { type CreateQuery, setupQuery } from './query';
+
+export interface CacheApi {
+  createMutation: CreateMutation;
+  createQuery: CreateQuery;
+  cancelQueries: QueryClient['cancelQueries'];
+  getQueryData: QueryClient['getQueryData'];
+  invalidateQueries: QueryClient['invalidateQueries'];
+  refetchQueries: QueryClient['refetchQueries'];
+  removeQueries: QueryClient['removeQueries'];
+  resetQueries: QueryClient['resetQueries'];
+  setQueryData: QueryClient['setQueryData'];
+  unsafe_getClient: () => QueryClient;
+}
+
+export function setupCache(queryClient: QueryClient): CacheApi {
+  return {
+    createMutation: setupMutation(queryClient),
+    createQuery: setupQuery(queryClient),
+    cancelQueries: queryClient.cancelQueries.bind(queryClient),
+    getQueryData: queryClient.getQueryData.bind(queryClient),
+    invalidateQueries: queryClient.invalidateQueries.bind(queryClient),
+    refetchQueries: queryClient.refetchQueries.bind(queryClient),
+    removeQueries: queryClient.removeQueries.bind(queryClient),
+    resetQueries: queryClient.resetQueries.bind(queryClient),
+    setQueryData: queryClient.setQueryData.bind(queryClient),
+    unsafe_getClient: () => queryClient,
+  };
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './mutation';
+export * from './query';
+export * from './cache';

package/src/mutation.ts

@@ -0,0 +1,100 @@
+import {
+  MutationObserver,
+  type MutationFunction,
+  type MutateOptions,
+  type MutationObserverOptions,
+  type MutationObserverResult,
+  type MutationStatus as TanstackMutationStatus,
+  type QueryClient,
+} from '@tanstack/query-core';
+
+export type MutationStatus = TanstackMutationStatus;
+
+export interface MutationServiceSnapshot<TData = unknown, TError = Error, TVariables = void> {
+  data: TData | undefined;
+  error: TError | null;
+  status: MutationStatus;
+  variables: TVariables | undefined;
+  isError: boolean;
+  isIdle: boolean;
+  isPending: boolean;
+  isSuccess: boolean;
+}
+
+export interface MutationService<
+  TData = unknown,
+  TError = Error,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> {
+  getSnapshot: () => MutationServiceSnapshot<TData, TError, TVariables>;
+  subscribe: (
+    listener: (snapshot: MutationServiceSnapshot<TData, TError, TVariables>) => void
+  ) => () => void;
+  mutate: (
+    variables: TVariables,
+    options?: MutateOptions<TData, TError, TVariables, TOnMutateResult>
+  ) => Promise<TData>;
+  reset: () => void;
+  unsafe_getResult: () => MutationObserverResult<TData, TError, TVariables, TOnMutateResult>;
+}
+
+export type MutationServiceOptions<
+  TData = unknown,
+  TError = Error,
+  TVariables = void,
+  TOnMutateResult = unknown,
+> = Omit<MutationObserverOptions<TData, TError, TVariables, TOnMutateResult>, 'mutationFn'>;
+
+export interface CreateMutation {
+  <TData = unknown, TError = Error, TVariables = void, TOnMutateResult = unknown>(
+    mutationFn: MutationFunction<TData, TVariables>,
+    options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
+  ): MutationService<TData, TError, TVariables, TOnMutateResult>;
+}
+
+export function setupMutation(queryClient: QueryClient): CreateMutation {
+  return function createMutation<
+    TData = unknown,
+    TError = Error,
+    TVariables = void,
+    TOnMutateResult = unknown,
+  >(
+    mutationFn: MutationFunction<TData, TVariables>,
+    options?: MutationServiceOptions<TData, TError, TVariables, TOnMutateResult>
+  ): MutationService<TData, TError, TVariables, TOnMutateResult> {
+    const observer = new MutationObserver<TData, TError, TVariables, TOnMutateResult>(
+      queryClient,
+      {
+        ...options,
+        mutationFn,
+      }
+    );
+
+    return {
+      getSnapshot: () => toMutationServiceSnapshot(observer.getCurrentResult()),
+      subscribe: (listener) =>
+        observer.subscribe((result) => {
+          listener(toMutationServiceSnapshot(result));
+        }),
+      mutate: (variables, mutateOptions) => observer.mutate(variables, mutateOptions),
+      reset: () => observer.reset(),
+      unsafe_getResult: () => observer.getCurrentResult(),
+    };
+  };
+}
+
+function toMutationServiceSnapshot<TData, TError, TVariables, TOnMutateResult>(
+  result: MutationObserverResult<TData, TError, TVariables, TOnMutateResult>
+): MutationServiceSnapshot<TData, TError, TVariables> {
+  return {
+    data: result.data,
+    error: result.error,
+    status: result.status,
+    variables: result.variables,
+    isError: result.isError,
+    isIdle: result.isIdle,
+    isPending: result.isPending,
+    isSuccess: result.isSuccess,
+  };
+}

package/src/query.ts

@@ -0,0 +1,152 @@
+import {
+  type FetchStatus,
+  type InvalidateOptions,
+  type InvalidateQueryFilters,
+  type QueryClient,
+  type QueryFunction,
+  type QueryKey,
+  QueryObserver,
+  type QueryObserverOptions,
+  type QueryObserverResult,
+  type RefetchOptions,
+  type QueryStatus as TanstackQueryStatus,
+} from '@tanstack/query-core';
+
+export type QueryFetchStatus = FetchStatus;
+export type QueryStatus = TanstackQueryStatus;
+
+export interface QueryServiceSnapshot<TData, TError> {
+  data: TData | undefined;
+  error: TError | null;
+  fetchStatus: QueryFetchStatus;
+  status: QueryStatus;
+  isError: boolean;
+  isFetching: boolean;
+  isPending: boolean;
+  isSuccess: boolean;
+}
+
+export interface QueryMetaState {
+  fetchStatus: QueryFetchStatus;
+  status: QueryStatus;
+}
+
+export interface QueryService<TData, TError> {
+  getSnapshot: () => QueryServiceSnapshot<TData, TError>;
+  subscribe: (listener: (snapshot: QueryServiceSnapshot<TData, TError>) => void) => () => void;
+  refetch: (options?: RefetchOptions) => Promise<QueryServiceSnapshot<TData, TError>>;
+  invalidate: (options?: QueryInvalidateOptions) => Promise<void>;
+  unsafe_getResult: () => QueryObserverResult<TData, TError>;
+}
+
+export interface QueryInvalidateOptions
+  extends Pick<InvalidateOptions, 'cancelRefetch' | 'throwOnError'>,
+    Pick<InvalidateQueryFilters, 'refetchType'> {}
+
+export interface CreateQuery {
+  <
+    TQueryFnData = unknown,
+    TError = Error,
+    TData = TQueryFnData,
+    TQueryData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+  >(
+    queryKey: TQueryKey,
+    queryFn: QueryFunction<TQueryFnData, TQueryKey>,
+    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  ): QueryService<TData, TError>;
+}
+
+export type QueryServiceOptions<
+  TQueryFnData = unknown,
+  TError = Error,
+  TData = TQueryFnData,
+  TQueryData = TQueryFnData,
+  TQueryKey extends QueryKey = QueryKey,
+> = Omit<
+  QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
+  'queryFn' | 'queryKey'
+>;
+
+export function toQueryMetaState<TData, TError>(
+  snapshot: Pick<QueryServiceSnapshot<TData, TError>, 'fetchStatus' | 'status'>
+): QueryMetaState {
+  return {
+    fetchStatus: snapshot.fetchStatus,
+    status: snapshot.status,
+  };
+}
+
+export function isQueryLoading(query: QueryMetaState): boolean {
+  return query.status === 'pending' && query.fetchStatus === 'fetching';
+}
+
+export function setupQuery(queryClient: QueryClient): CreateQuery {
+  return function createQuery<
+    TQueryFnData = unknown,
+    TError = Error,
+    TData = TQueryFnData,
+    TQueryData = TQueryFnData,
+    TQueryKey extends QueryKey = QueryKey,
+  >(
+    queryKey: TQueryKey,
+    queryFn: QueryFunction<TQueryFnData, TQueryKey>,
+    options?: QueryServiceOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>
+  ): QueryService<TData, TError> {
+    const observer = new QueryObserver<TQueryFnData, TError, TData, TQueryData, TQueryKey>(
+      queryClient,
+      {
+        ...options,
+        queryFn,
+        queryKey,
+      }
+    );
+
+    return {
+      getSnapshot: () => toQueryServiceSnapshot(observer.getCurrentResult()),
+      subscribe: (listener) =>
+        observer.subscribe((result) => {
+          listener(toQueryServiceSnapshot(result));
+        }),
+      refetch: async (options) => toQueryServiceSnapshot(await observer.refetch(options)),
+      invalidate: (options) =>
+        queryClient.invalidateQueries(
+          {
+            exact: true,
+            queryKey,
+            ...(options?.refetchType === undefined ? {} : { refetchType: options.refetchType }),
+          },
+          toInvalidateOptions(options)
+        ),
+      unsafe_getResult: () => observer.getCurrentResult(),
+    };
+  };
+}
+
+function toQueryServiceSnapshot<TData, TError>(
+  result: QueryObserverResult<TData, TError>
+): QueryServiceSnapshot<TData, TError> {
+  return {
+    data: result.data,
+    error: result.error,
+    fetchStatus: result.fetchStatus,
+    status: result.status,
+    isError: result.isError,
+    isFetching: result.isFetching,
+    isPending: result.isPending,
+    isSuccess: result.isSuccess,
+  };
+}
+
+function toInvalidateOptions(options?: QueryInvalidateOptions): InvalidateOptions | undefined {
+  if (options === undefined) {
+    return undefined;
+  }
+
+  const invalidateOptions: InvalidateOptions = {
+    ...(options.cancelRefetch === undefined ? {} : { cancelRefetch: options.cancelRefetch }),
+    ...(options.throwOnError === undefined ? {} : { throwOnError: options.throwOnError }),
+  };
+
+  return Object.keys(invalidateOptions).length > 0 ? invalidateOptions : undefined;
+}

package/tsconfig.eslint.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "coverage",
+    "dist",
+    "node_modules",
+    "src/**/*.mock.ts"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "declaration": true,
+    "declarationDir": "dist",
+    "esModuleInterop": true,
+    "lib": [
+      "es2022"
+    ],
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "skipLibCheck": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "typeRoots": [
+      "../../node_modules/@types"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "coverage",
+    "dist",
+    "node_modules",
+    "src/**/__tests__/**",
+    "src/**/*.mock.ts",
+    "src/**/*.{spec,test}.ts"
+  ]
+}