@ttt-productions/query-core 0.1.6

package/README.md

@@ -0,0 +1,10 @@
+# @ttt-productions/query-core
+
+Shared TanStack Query (React Query) setup for TTT Productions apps.
+
+- `createTTTQueryClient()` factory with safe defaults
+- `keys` query key helpers
+- invalidation + cache update helpers
+- `TTTQueryProvider` for Next.js/React apps
+
+No app business logic. No Firebase.

package/dist/cache-helpers.d.ts

@@ -0,0 +1,11 @@
+import type { QueryClient, QueryKey } from '@tanstack/react-query';
+/** Invalidate everything that matches a key prefix. */
+export declare function invalidateByPrefix(client: QueryClient, prefix: QueryKey): Promise<void>;
+/** Remove everything that matches a key prefix (drops cached data). */
+export declare function removeByPrefix(client: QueryClient, prefix: QueryKey): void;
+/**
+ * Generic cache update helper.
+ * Useful for optimistic updates without baking in business logic.
+ */
+export declare function updateQueryData<T>(client: QueryClient, key: QueryKey, updater: (prev: T | undefined) => T): void;
+//# sourceMappingURL=cache-helpers.d.ts.map

package/dist/cache-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-helpers.d.ts","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEnE,uDAAuD;AACvD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,iBAE7E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,QAEnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,QAGpC"}

package/dist/cache-helpers.js

@@ -0,0 +1,16 @@
+/** Invalidate everything that matches a key prefix. */
+export async function invalidateByPrefix(client, prefix) {
+    return client.invalidateQueries({ queryKey: prefix, exact: false });
+}
+/** Remove everything that matches a key prefix (drops cached data). */
+export function removeByPrefix(client, prefix) {
+    return client.removeQueries({ queryKey: prefix, exact: false });
+}
+/**
+ * Generic cache update helper.
+ * Useful for optimistic updates without baking in business logic.
+ */
+export function updateQueryData(client, key, updater) {
+    client.setQueryData(key, (prev) => updater(prev));
+}
+//# sourceMappingURL=cache-helpers.js.map

package/dist/cache-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-helpers.js","sourceRoot":"","sources":["../src/cache-helpers.ts"],"names":[],"mappings":"AAEA,uDAAuD;AACvD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,MAAmB,EAAE,MAAgB;IAC5E,OAAO,MAAM,CAAC,iBAAiB,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AACtE,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,cAAc,CAAC,MAAmB,EAAE,MAAgB;IAClE,OAAO,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAmB,EACnB,GAAa,EACb,OAAmC;IAEnC,MAAM,CAAC,YAAY,CAAI,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/defaults.d.ts

@@ -0,0 +1,8 @@
+import type { DefaultOptions, QueryClientConfig } from '@tanstack/react-query';
+/**
+ * Small, conservative defaults intended to work well across apps.
+ * Apps can override via `createTTTQueryClient({ defaultOptions: ... })`.
+ */
+export declare const tttDefaultOptions: DefaultOptions;
+export declare const tttQueryClientConfig: QueryClientConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,cAc/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,iBAElC,CAAC"}

package/dist/defaults.js

@@ -0,0 +1,21 @@
+/**
+ * Small, conservative defaults intended to work well across apps.
+ * Apps can override via `createTTTQueryClient({ defaultOptions: ... })`.
+ */
+export const tttDefaultOptions = {
+    queries: {
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: true,
+        refetchOnMount: false,
+        staleTime: 30_000, // 30s
+        gcTime: 5 * 60_000, // 5m
+        retry: (failureCount) => failureCount < 2,
+    },
+    mutations: {
+        retry: 0,
+    },
+};
+export const tttQueryClientConfig = {
+    defaultOptions: tttDefaultOptions,
+};
+//# sourceMappingURL=defaults.js.map

package/dist/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAmB;IAC/C,OAAO,EAAE;QACP,oBAAoB,EAAE,KAAK;QAC3B,kBAAkB,EAAE,IAAI;QACxB,cAAc,EAAE,KAAK;QAErB,SAAS,EAAE,MAAM,EAAE,MAAM;QACzB,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,KAAK;QAEzB,KAAK,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,YAAY,GAAG,CAAC;KAC1C;IACD,SAAS,EAAE;QACT,KAAK,EAAE,CAAC;KACT;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAsB;IACrD,cAAc,EAAE,iBAAiB;CAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { createTTTQueryClient } from './query-client';
+export type { CreateTTTQueryClientOptions } from './query-client';
+export { keys, createKeyScope } from './keys';
+export type { QueryKey } from './keys';
+export { invalidateByPrefix, removeByPrefix, updateQueryData } from './cache-helpers';
+export { TTTQueryProvider } from './provider';
+export type { TTTQueryProviderProps } from './provider';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EAAE,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC9C,YAAY,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createTTTQueryClient } from './query-client';
+export { keys, createKeyScope } from './keys';
+export { invalidateByPrefix, removeByPrefix, updateQueryData } from './cache-helpers';
+export { TTTQueryProvider } from './provider';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAGtD,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAG9C,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Lightweight, stable query key helpers.
+ *
+ * Convention:
+ * - `keys.user.all` => ['user']
+ * - `keys.user.detail(id)` => ['user', 'detail', id]
+ * - `keys.user.list(filters?)` => ['user', 'list', filters]
+ */
+type KeyPart = string | number | boolean | null | undefined | Record<string, unknown>;
+export type QueryKey = readonly unknown[];
+export declare const keys: {
+    readonly user: {
+        readonly all: QueryKey;
+        readonly detail: (id: string) => QueryKey;
+        readonly list: (params?: Record<string, unknown>) => QueryKey;
+    };
+    readonly project: {
+        readonly all: QueryKey;
+        readonly detail: (id: string) => QueryKey;
+        readonly list: (params?: Record<string, unknown>) => QueryKey;
+    };
+};
+/**
+ * Utility for apps that want to define their own scoped key sets
+ * while following the same conventions.
+ */
+export declare function createKeyScope(scope: string): {
+    readonly all: QueryKey;
+    readonly detail: (id: string) => QueryKey;
+    readonly list: (params?: Record<string, unknown>) => QueryKey;
+    readonly custom: (...parts: KeyPart[]) => QueryKey;
+};
+export {};
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,KAAK,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACtF,MAAM,MAAM,QAAQ,GAAG,SAAS,OAAO,EAAE,CAAC;AAO1C,eAAO,MAAM,IAAI;;;8BAGA,MAAM;iCACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;8BAI1B,MAAM;iCACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;CAEjC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM;;0BAG3B,MAAM;6BACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gCACpB,OAAO,EAAE;EAE/B"}

package/dist/keys.js

@@ -0,0 +1,37 @@
+/**
+ * Lightweight, stable query key helpers.
+ *
+ * Convention:
+ * - `keys.user.all` => ['user']
+ * - `keys.user.detail(id)` => ['user', 'detail', id]
+ * - `keys.user.list(filters?)` => ['user', 'list', filters]
+ */
+function withScope(scope, ...parts) {
+    const cleaned = parts.filter((p) => p !== undefined);
+    return [scope, ...cleaned];
+}
+export const keys = {
+    user: {
+        all: withScope('user'),
+        detail: (id) => withScope('user', 'detail', id),
+        list: (params) => withScope('user', 'list', params),
+    },
+    project: {
+        all: withScope('project'),
+        detail: (id) => withScope('project', 'detail', id),
+        list: (params) => withScope('project', 'list', params),
+    },
+};
+/**
+ * Utility for apps that want to define their own scoped key sets
+ * while following the same conventions.
+ */
+export function createKeyScope(scope) {
+    return {
+        all: withScope(scope),
+        detail: (id) => withScope(scope, 'detail', id),
+        list: (params) => withScope(scope, 'list', params),
+        custom: (...parts) => withScope(scope, ...parts),
+    };
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,SAAS,SAAS,CAAC,KAAa,EAAE,GAAG,KAAgB;IACnD,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACrD,OAAO,CAAC,KAAK,EAAE,GAAG,OAAO,CAAU,CAAC;AACtC,CAAC;AAED,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE;QACJ,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC;QACtB,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC;QACvD,IAAI,EAAE,CAAC,MAAgC,EAAE,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;KAC9E;IACD,OAAO,EAAE;QACP,GAAG,EAAE,SAAS,CAAC,SAAS,CAAC;QACzB,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC;QAC1D,IAAI,EAAE,CAAC,MAAgC,EAAE,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC;KACjF;CACO,CAAC;AAEX;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO;QACL,GAAG,EAAE,SAAS,CAAC,KAAK,CAAC;QACrB,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC;QACtD,IAAI,EAAE,CAAC,MAAgC,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC;QAC5E,MAAM,EAAE,CAAC,GAAG,KAAgB,EAAE,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC;KACnD,CAAC;AACb,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { type CreateTTTQueryClientOptions } from './query-client';
+export type TTTQueryProviderProps = React.PropsWithChildren<{
+    /** Optional overrides applied when the client is first created. */
+    clientOptions?: CreateTTTQueryClientOptions;
+}>;
+/**
+ * Client component wrapper for Next.js / React apps.
+ * Creates a single QueryClient per browser session.
+ */
+export declare function TTTQueryProvider({ children, clientOptions }: TTTQueryProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAwB,KAAK,2BAA2B,EAAE,MAAM,gBAAgB,CAAC;AAExF,MAAM,MAAM,qBAAqB,GAAG,KAAK,CAAC,iBAAiB,CAAC;IAC1D,mEAAmE;IACnE,aAAa,CAAC,EAAE,2BAA2B,CAAC;CAC7C,CAAC,CAAC;AAEH;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,qBAAqB,2CAGlF"}

package/dist/provider.js

@@ -0,0 +1,14 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { createTTTQueryClient } from './query-client';
+/**
+ * Client component wrapper for Next.js / React apps.
+ * Creates a single QueryClient per browser session.
+ */
+export function TTTQueryProvider({ children, clientOptions }) {
+    const [client] = React.useState(() => createTTTQueryClient(clientOptions));
+    return _jsx(QueryClientProvider, { client: client, children: children });
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,oBAAoB,EAAoC,MAAM,gBAAgB,CAAC;AAOxF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAyB;IACjF,MAAM,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,aAAa,CAAC,CAAC,CAAC;IAC3E,OAAO,KAAC,mBAAmB,IAAC,MAAM,EAAE,MAAM,YAAG,QAAQ,GAAuB,CAAC;AAC/E,CAAC"}

package/dist/query-client.d.ts

@@ -0,0 +1,8 @@
+import { QueryClient, type QueryClientConfig } from '@tanstack/react-query';
+export type CreateTTTQueryClientOptions = QueryClientConfig;
+/**
+ * Factory so every app uses the same baseline behavior.
+ * Pass overrides to adjust defaults without forking.
+ */
+export declare function createTTTQueryClient(overrides?: CreateTTTQueryClientOptions): QueryClient;
+//# sourceMappingURL=query-client.d.ts.map

package/dist/query-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-client.d.ts","sourceRoot":"","sources":["../src/query-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG5E,MAAM,MAAM,2BAA2B,GAAG,iBAAiB,CAAC;AAE5D;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,GAAE,2BAAgC,eAiB/E"}

package/dist/query-client.js

@@ -0,0 +1,25 @@
+import { QueryClient } from '@tanstack/react-query';
+import { tttQueryClientConfig } from './defaults';
+/**
+ * Factory so every app uses the same baseline behavior.
+ * Pass overrides to adjust defaults without forking.
+ */
+export function createTTTQueryClient(overrides = {}) {
+    return new QueryClient({
+        ...tttQueryClientConfig,
+        ...overrides,
+        defaultOptions: {
+            ...tttQueryClientConfig.defaultOptions,
+            ...overrides.defaultOptions,
+            queries: {
+                ...tttQueryClientConfig.defaultOptions?.queries,
+                ...overrides.defaultOptions?.queries,
+            },
+            mutations: {
+                ...tttQueryClientConfig.defaultOptions?.mutations,
+                ...overrides.defaultOptions?.mutations,
+            },
+        },
+    });
+}
+//# sourceMappingURL=query-client.js.map

package/dist/query-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-client.js","sourceRoot":"","sources":["../src/query-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA0B,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAIlD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAyC,EAAE;IAC9E,OAAO,IAAI,WAAW,CAAC;QACrB,GAAG,oBAAoB;QACvB,GAAG,SAAS;QACZ,cAAc,EAAE;YACd,GAAG,oBAAoB,CAAC,cAAc;YACtC,GAAG,SAAS,CAAC,cAAc;YAC3B,OAAO,EAAE;gBACP,GAAG,oBAAoB,CAAC,cAAc,EAAE,OAAO;gBAC/C,GAAG,SAAS,CAAC,cAAc,EAAE,OAAO;aACrC;YACD,SAAS,EAAE;gBACT,GAAG,oBAAoB,CAAC,cAAc,EAAE,SAAS;gBACjD,GAAG,SAAS,CAAC,cAAc,EAAE,SAAS;aACvC;SACF;KACF,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@ttt-productions/query-core",
+    "version": "0.1.6",
+    "description": "Shared TanStack Query (React Query) client defaults + query key helpers for TTT Productions apps",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "clean": "rm -rf dist *.tsbuildinfo",
+        "typecheck": "tsc --noEmit",
+        "prepublishOnly": "npm run clean && npm run build"
+    },
+    "peerDependencies": {
+        "@tanstack/react-query": "^5.0.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    },
+    "devDependencies": {
+        "@tanstack/react-query": "^5.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "react": "^19.2.0",
+        "react-dom": "^19.2.0",
+        "typescript": "^5.8.3"
+    },
+    "author": "DJ (TTT Productions)",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ttt-productions/ttt-packages.git",
+        "directory": "packages/query-core"
+    }
+}