@idb-orm/react-query 0.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright 2025 jtb
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @idb-orm/react-query
+
+> ## THIS PACKAGE IS BRAND-NEW AND UNSTABLE. DO NOT USE
+
+A React adapter for [Tanstack's Query library](https://tanstack.com/query/latest) for @idb-orm. It essentially offers easy to use shortcuts to manage querying idb-orm data and caching.
+
+## Example
+
+Here's an example comparison on how to do a `find` query on a `users` document collection in traditional Tanstack-query and with this package.
+
+```tsx
+// How to do it in Tanstack-query
+useQuery({
+    queryKey: ["users", "find", userId],
+    queryFn: () => client.stores.users.find({ where: { id: userId } }),
+});
+
+// How to do it in this package
+stores.users.useFind({ where: { id: userId } }, [userId]);
+```
+
+The package manages the internal query keys to ensure there is no overlap, and you can state an optional dependency array similar to traditiona react hooks like `useMemo` and `useEffect`.
+
+## Installation
+
+This package does not come bundled with Tanstack-query or react, they are both expected to already be installed. To install the adapter package, use:
+
+```
+npm i @idb-orm/react-query
+```
+
+## Getting Started
+
+Define your @idb-orm schema in any file. Then, create the provider and client object like so:
+
+```tsx
+// idb-query.ts
+
+import { createIDBClient } from "@idb-orm/react-query";
+
+// File that creates the @idb-orm database client
+import { client } from "./db-client";
+
+const { queryClient, Provider, stores } = createIDBQueryClient(client);
+export { queryClient, Provider, stores };
+```
+
+Then, in your project's root, wrap your application in the provider:
+
+```tsx
+// App.tsx
+
+import { Provider, queryClient } from "./idb-query";
+
+function App(){
+    return (
+        <Provider client={queryClient}>
+            {/* Appliation */}
+        <Provider>
+    )
+}
+
+```
+
+Some things to note:
+
+-   The `stores` field should be exported for use throughout your app. That is what provides the shortcut functions for each store.
+-   The provider component already has the Tanstack `QueryClientProvider` included!
+
+
+## Disclaimer
+This project is still in the **very** early stages. Bugs will occur as I work on this package. Sorry in advance.

package/dist/index.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("@tanstack/react-query"),t=require("react");class r extends e.QueryClient{constructor(e,t){super(t),this.db=e}createInterface(r){const n={},i=this.db.getStoreNames(),s=this.db.stores;for(const t of i)n[t]={useFind:(r,n=[])=>e.useQuery({...r,queryKey:[t,"find",...n],queryFn:()=>s[t].find(r.query)}),useFindFirst:(r,n=[])=>e.useQuery({...r,queryKey:[t,"findFirst",...n],queryFn:()=>s[t].findFirst(r.query)}),useGet:r=>{e.useQuery({...r,queryKey:[t,"get",r.key],queryFn:()=>s[t].get(r.key)})}};return{...n,useClient:()=>t.useContext(r)}}}exports.createIDBQueryClient=function(n,i){const s=new r(n,i),u=t.createContext({});return{queryClient:s,context:u,Provider:({client:r,children:n})=>{const i=t.useMemo(()=>{function e(e){return{invalidate:()=>r.invalidateQueries({queryKey:e})}}const t=e([]),n=r.db.getStoreNames();for(const r of n)"invalidate"===r&&console.warn("Model name 'invalidate' causes the invalidate() function of useClient() to not work. Please fix by renaming the model."),t[r]={...e([r]),get:e([r,"get"]),find:e([r,"find"]),findFirst:e([r,"findFirst"])};return t},[r]);return React.createElement(e.QueryClientProvider,{client:r},React.createElement(u.Provider,{value:i},n))},stores:s.createInterface(u)}};

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { core, Model } from '@idb-orm/core';
+import { QueryClient, DefinedUseQueryResult, UndefinedInitialDataOptions, QueryClientConfig } from '@tanstack/react-query';
+import { DependencyList, PropsWithChildren } from 'react';
+type QueryOptions<O> = Omit<UndefinedInitialDataOptions<O>, "queryFn" | "queryKey">;
+interface ModelQueryInterface<M extends Model<any, any, any>, Names extends string, Models extends core.CollectionObject<Names>> {
+    /**
+     * Query instance on a particular primary key. This query will acquire **only** the given document and no related documents.
+     */
+    useGet: M extends Model<any, infer Fields, any> ? <O = core.Simplify<core.ModelStructure<Fields, Models>>>(primaryKey: {
+        key: core.PrimaryKeyType<M>;
+    } & QueryOptions<O>) => DefinedUseQueryResult<O | undefined> : never;
+    useFind: <I extends core.FindInput<Names, M, Models>, O = core.Simplify<NonNullable<core.FindOutput<Names, M, Models, I>>>[]>(options: QueryOptions<O> & {
+        query: I;
+    }, deps?: DependencyList) => DefinedUseQueryResult<O | undefined>;
+    useFindFirst: <I extends core.FindInput<Names, M, Models>, O = core.Simplify<core.FindOutput<Names, M, Models, I>>>(options: QueryOptions<O> & {
+        query: I;
+    }, deps?: DependencyList) => DefinedUseQueryResult<O | undefined>;
+}
+interface ModelQueryClient {
+    invalidate(): Promise<void>;
+}
+type IDBClientInterface<Names extends string, _Models extends core.CollectionObject<Names>> = core.Simplify<{
+    [K in Names]: {
+        get: ModelQueryClient;
+        findFirst: ModelQueryClient;
+        find: ModelQueryClient;
+    } & core.Simplify<ModelQueryClient>;
+} & ModelQueryClient>;
+export declare function createIDBQueryClient<Names extends string, Models extends core.CollectionObject<Names>>(client: core.DbClient<string, Names, Models>, config?: QueryClientConfig): {
+    queryClient: IDBQueryClient<Names, Models>;
+    context: import('react').Context<{ [K_1 in Names]: {
+        get: ModelQueryClient;
+        findFirst: ModelQueryClient;
+        find: ModelQueryClient;
+    } & {
+        invalidate: () => Promise<void>;
+    }; } & ModelQueryClient extends infer T ? { [K in keyof T]: T[K]; } : never>;
+    Provider: ({ client, children, }: PropsWithChildren<{
+        client: IDBQueryClient<Names, Models>;
+    }>) => import("react").JSX.Element;
+    stores: IDBQueryInterface<Names, Models>;
+};
+declare class IDBQueryClient<Names extends string, Models extends core.CollectionObject<Names>> extends QueryClient {
+    readonly db: core.DbClient<string, Names, Models>;
+    constructor(db: core.DbClient<string, Names, Models>, config?: QueryClientConfig);
+    createInterface(context: React.Context<IDBClientInterface<Names, Models>>): IDBQueryInterface<Names, Models>;
+}
+export type IDBQueryInterface<Names extends string, Models extends core.CollectionObject<Names>> = {
+    useClient(): IDBClientInterface<Names, Models>;
+} & {
+    [K in Names]: ModelQueryInterface<Models[K], Names, Models>;
+};
+export {};

package/dist/index.es.js

@@ -0,0 +1,2 @@
+import{QueryClientProvider as e,QueryClient as t,useQuery as r}from"@tanstack/react-query";import{createContext as n,useMemo as i,useContext as s}from"react";function o(t,r){const s=new a(t,r),o=n({});return{queryClient:s,context:o,Provider:({client:t,children:r})=>{const n=i(()=>{function e(e){return{invalidate:()=>t.invalidateQueries({queryKey:e})}}const r=e([]),n=t.db.getStoreNames();for(const t of n)"invalidate"===t&&console.warn("Model name 'invalidate' causes the invalidate() function of useClient() to not work. Please fix by renaming the model."),r[t]={...e([t]),get:e([t,"get"]),find:e([t,"find"]),findFirst:e([t,"findFirst"])};return r},[t]);/* @__PURE__ */
+return React.createElement(e,{client:t},/* @__PURE__ */React.createElement(o.Provider,{value:n},r))},stores:s.createInterface(o)}}class a extends t{constructor(e,t){super(t),this.db=e}createInterface(e){const t={},n=this.db.getStoreNames(),i=this.db.stores;for(const s of n)t[s]={useFind:(e,t=[])=>r({...e,queryKey:[s,"find",...t],queryFn:()=>i[s].find(e.query)}),useFindFirst:(e,t=[])=>r({...e,queryKey:[s,"findFirst",...t],queryFn:()=>i[s].findFirst(e.query)}),useGet:e=>{r({...e,queryKey:[s,"get",e.key],queryFn:()=>i[s].get(e.key)})}};return{...t,useClient:()=>s(e)}}}export{o as createIDBQueryClient};

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@idb-orm/react-query",
+    "version": "0.0.0",
+    "description": "An adapter for the Tanstack React-Query library for @idb-orm",
+    "main": "dist/index.js",
+    "scripts": {
+        "build": "vite build",
+        "build-test": "vite --config vite.config-test.ts build"
+    },
+    "keywords": [
+        "typescript",
+        "react-query",
+        "tanstack-query",
+        "idb-orm"
+    ],
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.es.js",
+            "require": "./dist/index.cjs.js"
+        }
+    },
+    "author": "jtb",
+    "license": "ISC",
+    "peerDependencies": {
+        "@idb-orm/core": "^1.0.7",
+        "@tanstack/react-query": "^5.90.11",
+        "react": "^19.2.0"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.38.0",
+        "@rollup/plugin-alias": "^6.0.0",
+        "@rollup/plugin-node-resolve": "^16.0.3",
+        "@rollup/plugin-terser": "^0.4.4",
+        "@rollup/plugin-typescript": "^12.1.4",
+        "@types/node": "^24.9.1",
+        "@types/react": "^19.2.7",
+        "eslint": "^9.38.0",
+        "rollup": "^4.52.4",
+        "serve": "^14.2.5",
+        "tslib": "^2.8.1",
+        "typescript": "^5.9.3",
+        "typescript-eslint": "^8.46.2",
+        "vite": "^7.2.4",
+        "vite-plugin-dts": "^4.5.4"
+    }
+}