@idb-orm/react-query 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 > ## 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.
+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. This package is an extension of `@idb-orm/react`.
 
 ## Example
 
@@ -36,18 +36,30 @@ 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:
+Define your @idb-orm schema in any file. Then, call the factory function. This function will create a React Context, a Provider component for the context, and a series of hooks used to access the context's value.
 
 ```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 };
+import { queryClientProviderFactory } from "@idb-orm/react-query";
+
+// File that creates the @idb-orm database
+import { db } from "./db";
+
+export const {
+    // Primitive React Context object
+    Context,
+    // Hook to acquire the IDB-ORM client object
+    useDbClient,
+    // Hook to acquire the Tanstack-Query QueryClient object
+    useQueryClient,
+    // Hook to acquire the auto-generated query functions.
+    useQueryInterface,
+    // Hook to acquire the contents of the 3 hooks above in one.
+    useIDBQuery,
+    // Provider that will allow the above hooks to function and populate the context.
+    DbClientProvider,
+} = queryClientProviderFactory(db);
 ```
 
 Then, in your project's root, wrap your application in the provider:
@@ -55,52 +67,62 @@ Then, in your project's root, wrap your application in the provider:
 ```tsx
 // App.tsx
 
-import { Provider, queryClient } from "./idb-query";
+import { DbClientProvider } from "./idb-query";
 
 function App(){
     return (
-        <Provider client={queryClient}>
+        <DbClientProvider version={2} fallback={<>Waiting for client creation...</>}>
             {/* Appliation */}
-        <Provider>
+        <DbClientProvider>
     )
 }
 ```
 
+The fallback prop is an optional prop you can give to the provider to render while the client is building. Building the `@idb-orm` client is an asynchronous operation, so while that is being done its children are not rendered. This may be changed in a future update.
+
 ## Usage
 
 Anywhere inside a component, you can call one of three hooks for each store:
 
 ```ts
-// Will find all documents that matches the filter/selector
-stores.users.useFind({
-    query: {
-        /* Selector Object */
-    },
-    /* Additional options */
-});
-
-// Will find the first document that matches the filter/selector
-stores.users.useFindFirst({
-    query: {
-        /* Selector Object */
-    },
-    /* Additional options */
-});
+import { useQueryInterface } from "./idb-query";
+
+function MyComponent(){
+    const stores = useQueryInterface();
+
+    // Will find all documents that matches the filter/selector
+    stores.users.useFind({
+        query: {
+            /* Selector Object */
+        },
+        /* Additional options */
+    });
+
+    // Will find the first document that matches the filter/selector
+    stores.users.useFindFirst({
+        query: {
+            /* Selector Object */
+        },
+        /* Additional options */
+    });
+
+    // Will find the first document that matches the filter/selector
+    stores.users.useGet({
+        key: /* Primary Key */
+        /* Additional options */
+    });
+
+    return <>My Favorite Component</>
+}
 
-// Will find the first document that matches the filter/selector
-stores.users.useGet({
-    key: /* Primary Key */
-    /* Additional options */
-});
 ```
 
 These hooks return the same type as the result of the Tanstack [useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) hook. Check out their documentation for more information as well as additional options.
 
 Some things to note:
 
--   Fields passed into the `query` key of a hook input will be used to determine query invalidation. These query objects are serialized into JSON by Tanstack, so any TS/JS types that are not serializable into JSON (functions, files, undefined) will be omitted from the serialized representation. So if any of these types of values change, the query will **NOT** be automatically invalidated.
--   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!
+- Fields passed into the `query` key of a hook input will be used to determine query invalidation. These query objects are serialized into JSON by Tanstack, so any TS/JS types that are not serializable into JSON (functions, files, undefined) will be omitted from the serialized representation. So if any of these types of values change, the query will **NOT** be automatically invalidated.
+- The `DbClientProvider` component already has the Tanstack `QueryClientProvider` included, you do not need to add another!
 
 ## Disclaimer
 

package/dist/index.cjs.js

@@ -1 +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(),o=this.db.stores;for(const t of i)n[t]={useFind:(r,n=[])=>e.useQuery({...r,queryKey:[t,"find",r.query,...n],queryFn:()=>o[t].find(r.query)}),useFindFirst:(r,n=[])=>e.useQuery({...r,queryKey:[t,"findFirst",r.query,...n],queryFn:()=>o[t].findFirst(r.query)}),useGet:(r,n=[])=>{e.useQuery({...r,queryKey:[t,"get",r.key,...n],queryFn:()=>o[t].get(r.key)})}};return{...n,useClient:()=>{const e=t.useContext(r);if(!e)throw new Error("Query Context Not Found. Make sure you wrap your application in the <Provider/> Component.");return e}}}}exports.createIDBQueryClient=function(n,i){const o=new r(n,i),u=t.createContext({});return{queryClient:o,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 t.createElement(e.QueryClientProvider,{client:r},t.createElement(u.Provider,{value:i},n))},stores:o.createInterface(u)}};
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("@tanstack/react-query"),t=require("react"),r="Query Client Context not found. Please ensure this component is wrapped in a <DbClientProvider /> component.";class n extends e.QueryClient{constructor(e,t){super(t),this.db=e}createInterface(r){const n={},o=this.db.getStoreNames(),i=this.db.stores;for(const t of o)n[t]={useFind:(r,n=[])=>e.useQuery({...r,queryKey:[t,"find",r.query,...n],queryFn:()=>i[t].find(r.query)}),useFindFirst:(r,n=[])=>e.useQuery({...r,queryKey:[t,"findFirst",r.query,...n],queryFn:()=>i[t].findFirst(r.query)}),useGet:(r,n=[])=>{e.useQuery({...r,queryKey:[t,"get",r.key,...n],queryFn:()=>i[t].get(r.key)})}};return{...n,useClient:()=>{const e=t.useContext(r);if(!e)throw new Error("Query Context Not Found. Make sure you wrap your application in the <Provider/> Component.");return e}}}}exports.IDBQueryClient=n,exports.queryClientProviderFactory=function(o,i){const u=t.createContext(null);return{Context:u,useDbClient:()=>{const e=t.useContext(u);if(!e)throw new Error(r);return e.client},useQueryClient:()=>{const e=t.useContext(u);if(!e)throw new Error(r);return e.queryClient},useQueryInterface:()=>{const e=t.useContext(u);if(!e)throw new Error(r);return e.stores},useIDBQuery:()=>{const e=t.useContext(u);if(!e)throw new Error(r);return e},DbClientProvider:({fallback:r,children:s,version:a})=>{const[c,l]=t.useState(null);return t.useEffect(()=>{o.createClientAsync(a).then(e=>{const t=new n(e,i);function r(e){return{invalidate:()=>t.invalidateQueries({queryKey:e})}}const o=r([]),u=t.db.getStoreNames();for(const n of u)"invalidate"===n&&console.warn("Model name 'invalidate' causes the invalidate() function of useClient() to not work. Please fix by renaming the model."),o[n]={...r([n]),get:r([n,"get"]),find:r([n,"find"]),findFirst:r([n,"findFirst"])};l({client:e,queryClient:t,stores:o})}).catch(e=>{throw new Error(`@idb-orm Query Client Creation Failed: ${e}`)})},[a]),c?t.createElement(e.QueryClientProvider,{client:c.queryClient},t.createElement(u.Provider,{value:c},s)):r}}};

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { core, Model } from '@idb-orm/core';
 import { QueryClient, DefinedUseQueryResult, UndefinedInitialDataOptions, QueryClientConfig } from '@tanstack/react-query';
-import { default as React } from 'react';
-interface QueryOptions<O> extends Omit<UndefinedInitialDataOptions<O>, "queryFn" | "queryKey"> {
+import { default as React, Context, PropsWithChildren, ReactNode } from 'react';
+import { ClientProviderProps } from '@idb-orm/react';
+export interface QueryOptions<O> extends Omit<UndefinedInitialDataOptions<O>, "queryFn" | "queryKey"> {
 }
-interface ModelQueryInterface<Name extends Names, Names extends string, Models extends core.CollectionObject<Names>> {
+export interface ModelQueryInterface<Name extends Names, 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.
      */
@@ -17,7 +18,7 @@ interface ModelQueryInterface<Name extends Names, Names extends string, Models e
         query: I;
     }, deps?: React.DependencyList) => DefinedUseQueryResult<O | undefined>;
 }
-interface ModelQueryClient {
+export interface ModelQueryClient {
     invalidate(): Promise<void>;
 }
 type IDBClientInterface<Names extends string, _Models extends core.CollectionObject<Names>> = core.Simplify<{
@@ -27,21 +28,21 @@ type IDBClientInterface<Names extends string, _Models extends core.CollectionObj
         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: 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, }: React.PropsWithChildren<{
-        client: IDBQueryClient<Names, Models>;
-    }>) => React.JSX.Element;
-    stores: IDBQueryInterface<Names, Models>;
-};
-declare class IDBQueryClient<Names extends string, Models extends core.CollectionObject<Names>> extends QueryClient {
+export interface UseQueryClientReturn<Name extends string, ModelNames extends string, Models extends core.CollectionObject<ModelNames>> {
+    client: core.DbClient<Name, ModelNames, Models>;
+    queryClient: IDBQueryClient<ModelNames, Models>;
+    stores: IDBClientInterface<ModelNames, Models>;
+}
+export interface QueryClientProviderFactoryReturn<Name extends string, ModelNames extends string, Models extends core.CollectionObject<ModelNames>> {
+    Context: Context<UseQueryClientReturn<Name, ModelNames, Models> | null>;
+    useDbClient: () => core.DbClient<Name, ModelNames, Models>;
+    useQueryClient: () => IDBQueryClient<ModelNames, Models>;
+    useQueryInterface: () => IDBClientInterface<ModelNames, Models>;
+    useIDBQuery: () => UseQueryClientReturn<Name, ModelNames, Models>;
+    DbClientProvider: (props: PropsWithChildren<ClientProviderProps>) => ReactNode;
+}
+export declare function queryClientProviderFactory<Name extends string, ModelNames extends string, Models extends core.CollectionObject<ModelNames>>(db: core.CompiledDb<Name, ModelNames, Models>, config?: QueryClientConfig): QueryClientProviderFactoryReturn<Name, ModelNames, Models>;
+export 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>;

package/dist/index.es.js

@@ -1,2 +1 @@
-import{QueryClientProvider as e,QueryClient as t,useQuery as r}from"@tanstack/react-query";import n from"react";function o(t,r){const o=new i(t,r),s=n.createContext({});return{queryClient:o,context:s,Provider:({client:t,children:r})=>{const o=n.useMemo(()=>{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 n.createElement(e,{client:t},/* @__PURE__ */n.createElement(s.Provider,{value:o},r))},stores:o.createInterface(s)}}class i extends t{constructor(e,t){super(t),this.db=e}createInterface(e){const t={},o=this.db.getStoreNames(),i=this.db.stores;for(const n of o)t[n]={useFind:(e,t=[])=>r({...e,queryKey:[n,"find",e.query,...t],queryFn:()=>i[n].find(e.query)}),useFindFirst:(e,t=[])=>r({...e,queryKey:[n,"findFirst",e.query,...t],queryFn:()=>i[n].findFirst(e.query)}),useGet:(e,t=[])=>{r({...e,queryKey:[n,"get",e.key,...t],queryFn:()=>i[n].get(e.key)})}};return{...t,useClient:()=>{const t=n.useContext(e);if(!t)throw new Error("Query Context Not Found. Make sure you wrap your application in the <Provider/> Component.");return t}}}}export{o as createIDBQueryClient};
+import{QueryClientProvider as e,QueryClient as r,useQuery as t}from"@tanstack/react-query";import n,{createContext as o,useState as i,useEffect as s,useContext as u}from"react";const a="Query Client Context not found. Please ensure this component is wrapped in a <DbClientProvider /> component.";function c(r,t){const c=o(null);return{Context:c,useDbClient:()=>{const e=u(c);if(!e)throw new Error(a);return e.client},useQueryClient:()=>{const e=u(c);if(!e)throw new Error(a);return e.queryClient},useQueryInterface:()=>{const e=u(c);if(!e)throw new Error(a);return e.stores},useIDBQuery:()=>{const e=u(c);if(!e)throw new Error(a);return e},DbClientProvider:({fallback:o,children:u,version:a})=>{const[d,y]=i(null);return s(()=>{r.createClientAsync(a).then(e=>{const r=new l(e,t);function n(e){return{invalidate:()=>r.invalidateQueries({queryKey:e})}}const o=n([]),i=r.db.getStoreNames();for(const t of i)"invalidate"===t&&console.warn("Model name 'invalidate' causes the invalidate() function of useClient() to not work. Please fix by renaming the model."),o[t]={...n([t]),get:n([t,"get"]),find:n([t,"find"]),findFirst:n([t,"findFirst"])};y({client:e,queryClient:r,stores:o})}).catch(e=>{throw new Error(`@idb-orm Query Client Creation Failed: ${e}`)})},[a]),d?/* @__PURE__ */n.createElement(e,{client:d.queryClient},/* @__PURE__ */n.createElement(c.Provider,{value:d},u)):o}}}class l extends r{constructor(e,r){super(r),this.db=e}createInterface(e){const r={},o=this.db.getStoreNames(),i=this.db.stores;for(const n of o)r[n]={useFind:(e,r=[])=>t({...e,queryKey:[n,"find",e.query,...r],queryFn:()=>i[n].find(e.query)}),useFindFirst:(e,r=[])=>t({...e,queryKey:[n,"findFirst",e.query,...r],queryFn:()=>i[n].findFirst(e.query)}),useGet:(e,r=[])=>{t({...e,queryKey:[n,"get",e.key,...r],queryFn:()=>i[n].get(e.key)})}};return{...r,useClient:()=>{const r=n.useContext(e);if(!r)throw new Error("Query Context Not Found. Make sure you wrap your application in the <Provider/> Component.");return r}}}}export{l as IDBQueryClient,c as queryClientProviderFactory};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@idb-orm/react-query",
-    "version": "0.1.0",
+    "version": "0.2.0",
     "description": "An adapter for the Tanstack React-Query library for @idb-orm",
     "main": "dist/index.js",
     "scripts": {
@@ -25,6 +25,7 @@
     "peerDependencies": {
         "@idb-orm/core": "^1.0.7",
         "@tanstack/react-query": "^5.90.11",
+        "@idb-orm/react": "^0.0.1",
         "react": "^19.2.0"
     },
     "devDependencies": {