added useEntity and useEntityQuery hooks

app/src/data/server/data-query-impl.ts

@@ -72,6 +72,6 @@ export const querySchema = Type.Object(
    }
 );
 
-export type RepoQueryIn = Simplify<Static<typeof querySchema>>;
+export type RepoQueryIn = Static<typeof querySchema>;
 export type RepoQuery = Required<StaticDecode<typeof querySchema>>;
 export const defaultQuerySchema = Value.Default(querySchema, {}) as RepoQuery;

app/src/modules/ModuleApi.ts

@@ -90,7 +90,9 @@ export abstract class ModuleApi<Options extends BaseModuleApiOptions = BaseModul
          headers
       });
 
-      return new FetchPromise(request, this.fetcher);
+      return new FetchPromise(request, {
+         fetcher: this.fetcher
+      });
    }
 
    get<Data = any>(
@@ -142,11 +144,13 @@ export class FetchPromise<T = ApiResponse<any>> implements Promise<T> {
 
    constructor(
       public request: Request,
-      protected fetcher?: typeof fetch
+      protected options?: {
+         fetcher?: typeof fetch;
+      }
    ) {}
 
-   async execute() {
+   async execute(): Promise<T> {
-      const fetcher = this.fetcher ?? fetch;
+      const fetcher = this.options?.fetcher ?? fetch;
       const res = await fetcher(this.request);
       let resBody: any;
       let resData: any;
@@ -167,7 +171,7 @@ export class FetchPromise<T = ApiResponse<any>> implements Promise<T> {
          body: resBody,
          data: resData,
          res
-      };
+      } as T;
    }
 
    // biome-ignore lint/suspicious/noThenProperty: it's a promise :)
@@ -197,8 +201,21 @@ export class FetchPromise<T = ApiResponse<any>> implements Promise<T> {
       );
    }
 
-   getKey(): string {
+   path(): string {
       const url = new URL(this.request.url);
-      return url.pathname + url.search;
+      return url.pathname;
+   }
+
+   key(options?: { search: boolean }): string {
+      const url = new URL(this.request.url);
+      return options?.search !== false ? this.path() + url.search : this.path();
+   }
+
+   keyArray(options?: { search: boolean }): string[] {
+      const url = new URL(this.request.url);
+      const path = this.path().split("/");
+      return (options?.search !== false ? [...path, url.searchParams.toString()] : path).filter(
+         Boolean
+      );
    }
 }

app/src/ui/client/ClientProvider.tsx

@@ -80,8 +80,6 @@ export const useClient = () => {
    if (!context) {
       throw new Error("useClient must be used within a ClientProvider");
    }
-
-   console.log("useClient", context.baseUrl);
    return context.client;
 };
 

app/src/ui/client/api/use-api.ts

@@ -0,0 +1,30 @@
+import type { Api } from "Api";
+import type { FetchPromise } from "modules/ModuleApi";
+import useSWR, { type SWRConfiguration, useSWRConfig } from "swr";
+import { useClient } from "ui/client/ClientProvider";
+
+export const useApi = () => {
+   const client = useClient();
+   return client.api;
+};
+
+export const useApiQuery = <Data, RefineFn extends (data: Data) => any = (data: Data) => Data>(
+   fn: (api: Api) => FetchPromise<Data>,
+   options?: SWRConfiguration & { enabled?: boolean; refine?: RefineFn }
+) => {
+   const api = useApi();
+   const promise = fn(api);
+   const refine = options?.refine ?? ((data: Data) => data);
+   const fetcher = () => promise.execute().then(refine);
+   const key = promise.key();
+
+   type RefinedData = RefineFn extends (data: Data) => infer R ? R : Data;
+
+   const swr = useSWR<RefinedData>(options?.enabled === false ? null : key, fetcher, options);
+   return {
+      ...swr,
+      promise,
+      key,
+      api
+   };
+};

app/src/ui/client/api/use-data.ts

@@ -0,0 +1,37 @@
+import type { DataApi } from "data/api/DataApi";
+import { useApi } from "ui/client";
+
+type OmitFirstArg<F> = F extends (x: any, ...args: infer P) => any
+   ? (...args: P) => ReturnType<F>
+   : never;
+
+/**
+ * Maps all DataApi functions and omits
+ * the first argument "entity" for convenience
+ * @param entity
+ */
+export const useData = <T extends keyof DataApi>(entity: string) => {
+   const api = useApi().data;
+   const methods = [
+      "readOne",
+      "readMany",
+      "readManyByReference",
+      "createOne",
+      "updateOne",
+      "deleteOne"
+   ] as const;
+
+   return methods.reduce(
+      (acc, method) => {
+         // @ts-ignore
+         acc[method] = (...params) => {
+            // @ts-ignore
+            return api[method](entity, ...params);
+         };
+         return acc;
+      },
+      {} as {
+         [K in (typeof methods)[number]]: OmitFirstArg<(typeof api)[K]>;
+      }
+   );
+};

app/src/ui/client/api/use-entity.ts

@@ -0,0 +1,76 @@
+import type { PrimaryFieldType } from "core";
+import { objectTransform } from "core/utils";
+import type { EntityData, RepoQuery } from "data";
+import useSWR, { type SWRConfiguration } from "swr";
+import { useApi } from "ui/client";
+
+export const useEntity = <
+   Entity extends string,
+   Id extends PrimaryFieldType | undefined = undefined
+>(
+   entity: Entity,
+   id?: Id
+) => {
+   const api = useApi().data;
+
+   return {
+      create: async (input: EntityData) => {
+         const res = await api.createOne(entity, input);
+         return res.data;
+      },
+      read: async (query: Partial<RepoQuery> = {}) => {
+         const res = id ? await api.readOne(entity, id!, query) : await api.readMany(entity, query);
+         return res.data;
+      },
+      update: async (input: Partial<EntityData>, _id: PrimaryFieldType | undefined = id) => {
+         if (!_id) {
+            throw new Error("id is required");
+         }
+         const res = await api.updateOne(entity, _id, input);
+         return res.data;
+      },
+      _delete: async (_id: PrimaryFieldType | undefined = id) => {
+         if (!_id) {
+            throw new Error("id is required");
+         }
+
+         const res = await api.deleteOne(entity, _id);
+         return res.data;
+      }
+   };
+};
+
+export const useEntityQuery = <
+   Entity extends string,
+   Id extends PrimaryFieldType | undefined = undefined
+>(
+   entity: Entity,
+   id?: Id,
+   query?: Partial<RepoQuery>,
+   options?: SWRConfiguration
+) => {
+   const api = useApi().data;
+   const key = [...(api.options?.basepath?.split("/") ?? []), entity, ...(id ? [id] : [])].filter(
+      Boolean
+   );
+   const { read, ...actions } = useEntity(entity, id) as any;
+   const fetcher = id ? () => read(query) : () => null;
+   const swr = useSWR<EntityData>(id ? key : null, fetcher, options);
+
+   const mapped = objectTransform(actions, (action) => {
+      if (action === "read") return;
+
+      return async (...args) => {
+         return swr.mutate(async () => {
+            const res = await action(...args);
+            return res;
+         });
+      };
+   }) as Omit<ReturnType<typeof useEntity<Entity, Id>>, "read">;
+
+   return {
+      ...swr,
+      ...mapped,
+      key
+   };
+};

app/src/ui/client/index.ts

@@ -6,6 +6,8 @@ export {
    useBaseUrl
 } from "./ClientProvider";
 
-export { useApi, useApiQuery } from "./use-api";
+export * from "./api/use-api";
+export * from "./api/use-data";
+export * from "./api/use-entity";
 export { useAuth } from "./schema/auth/use-auth";
 export { Api } from "../../Api";

app/src/ui/client/use-api.ts

@@ -1,18 +0,0 @@
-import type { Api } from "Api";
-import type { FetchPromise } from "modules/ModuleApi";
-import useSWR, { type SWRConfiguration } from "swr";
-import { useClient } from "ui/client/ClientProvider";
-
-export const useApi = () => {
-   const client = useClient();
-   return client.api;
-};
-
-export const useApiQuery = <T = any>(
-   fn: (api: Api) => FetchPromise<T>,
-   options?: SWRConfiguration & { enabled?: boolean }
-) => {
-   const api = useApi();
-   const p = fn(api);
-   return useSWR<T>(options?.enabled === false ? null : p.getKey(), () => p, options);
-};

app/src/ui/routes/test/index.tsx

@@ -1,6 +1,7 @@
 import AppShellAccordionsTest from "ui/routes/test/tests/appshell-accordions-test";
 import SwaggerTest from "ui/routes/test/tests/swagger-test";
 import SWRAndAPI from "ui/routes/test/tests/swr-and-api";
+import SwrAndDataApi from "ui/routes/test/tests/swr-and-data-api";
 import { Route, useParams } from "wouter";
 import { Empty } from "../../components/display/Empty";
 import { Link } from "../../components/wouter/Link";
@@ -39,7 +40,8 @@ const tests = {
    FlowsTest,
    AppShellAccordionsTest,
    SwaggerTest,
-   SWRAndAPI
+   SWRAndAPI,
+   SwrAndDataApi
 } as const;
 
 export default function TestRoutes() {

app/src/ui/routes/test/tests/swr-and-api.tsx

@@ -1,20 +1,45 @@
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { useApiQuery } from "ui/client";
 import { Scrollable } from "ui/layouts/AppShell/AppShell";
 
 export default function SWRAndAPI() {
-   const [enabled, setEnabled] = useState(false);
+   const [text, setText] = useState("");
-   const { data, error, isLoading } = useApiQuery(({ data }) => data.readMany("posts"), {
+   const { data, ...r } = useApiQuery((api) => api.data.readOne("comments", 1), {
-      enabled,
+      refine: (data) => data.data,
       revalidateOnFocus: true
    });
+   const comment = data ? data : null;
+
+   useEffect(() => {
+      setText(comment?.content ?? "");
+   }, [comment]);
 
    return (
       <Scrollable>
-         <button onClick={() => setEnabled((p) => !p)}>{enabled ? "disable" : "enable"}</button>
+         <pre>{JSON.stringify(r.promise.keyArray({ search: false }))}</pre>
-         {error && <div>failed to load</div>}
+         {r.error && <div>failed to load</div>}
-         {isLoading && <div>loading...</div>}
+         {r.isLoading && <div>loading...</div>}
          {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+         {data && (
+            <form
+               onSubmit={async (e) => {
+                  e.preventDefault();
+                  if (!comment) return;
+
+                  await r.mutate(async () => {
+                     const res = await r.api.data.updateOne("comments", comment.id, {
+                        content: text
+                     });
+                     return res.data;
+                  });
+
+                  return false;
+               }}
+            >
+               <input type="text" value={text} onChange={(e) => setText(e.target.value)} />
+               <button type="submit">submit</button>
+            </form>
+         )}
       </Scrollable>
    );
 }

app/src/ui/routes/test/tests/swr-and-data-api.tsx

@@ -0,0 +1,55 @@
+import { useEffect, useState } from "react";
+import { useEntity, useEntityQuery } from "ui/client/api/use-entity";
+import { Scrollable } from "ui/layouts/AppShell/AppShell";
+
+export default function SwrAndDataApi() {
+   return (
+      <div>
+         <DirectDataApi />
+         <QueryDataApi />
+      </div>
+   );
+}
+
+function QueryDataApi() {
+   const [text, setText] = useState("");
+   const { data, update, ...r } = useEntityQuery("comments", 1, {});
+   const comment = data ? data : null;
+
+   useEffect(() => {
+      setText(comment?.content ?? "");
+   }, [comment]);
+
+   return (
+      <Scrollable>
+         <pre>{JSON.stringify(r.key)}</pre>
+         {r.error && <div>failed to load</div>}
+         {r.isLoading && <div>loading...</div>}
+         {data && <pre>{JSON.stringify(data, null, 2)}</pre>}
+         {data && (
+            <form
+               onSubmit={async (e) => {
+                  e.preventDefault();
+                  if (!comment) return;
+                  await update({ content: text });
+                  return false;
+               }}
+            >
+               <input type="text" value={text} onChange={(e) => setText(e.target.value)} />
+               <button type="submit">submit</button>
+            </form>
+         )}
+      </Scrollable>
+   );
+}
+
+function DirectDataApi() {
+   const [data, setData] = useState<any>();
+   const { create, read, update, _delete } = useEntity("comments", 1);
+
+   useEffect(() => {
+      read().then(setData);
+   }, []);
+
+   return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}

docs/mint.json

@@ -61,7 +61,7 @@
   "navigation": [
     {
       "group": "Getting Started",
-      "pages": ["introduction", "setup", "sdk", "cli"]
+      "pages": ["introduction", "setup", "sdk", "react", "cli"]
     },
     {
       "group": "Modules",

docs/react.mdx

@@ -0,0 +1,194 @@
+---
+title: 'SDK (React)'
+description: 'Use the bknd SDK for React'
+---
+
+For all SDK options targeting React, you always have 2 options:
+1. use simple hooks which are solely based on the [API](/sdk)
+2. use the query hook that makes wraps the API in [SWR](https://swr.vercel.app/)
+
+To use the simple hook that returns the Api, you can use:
+```tsx
+import { useApi } from "bknd/client";
+
+export default function App() {
+   const api = useApi();
+   // ...
+}
+```
+
+## `useApiQuery([selector], [options])`
+This hook wraps the API class in an SWR hook for convenience. You can use any API endpoint
+supported, like so:
+```tsx
+import { useApiQuery } from "bknd/client";
+
+export default function App() {
+   const { data, ...swr } = useApiQuery((api) => api.data.readMany("comments"));
+
+   if (swr.error) return <div>Error</div>
+   if (swr.isLoading) return <div>Loading...</div>
+
+   return <pre>{JSON.stringify(data, null, 2)}</pre>
+}
+```
+
+### Props
+* `selector: (api: Api) => FetchPromise`
+
+   The first parameter is a selector function that provides an Api instance and expects an
+   endpoint function to be returned.
+
+* `options`: optional object that inherits from `SWRConfiguration`
+
+   ```ts
+   type Options<Data> = SWRConfiguration & {
+      enabled?: boolean;
+      refine?: (data: Data) => Data | any;
+   }
+   ```
+
+      * `enabled`: Determines whether this hook should trigger a fetch of the data or not.
+      * `refine`: Optional refinement that is called after a response from the API has been
+  received. Useful to omit irrelevant data from the response (see example below).
+
+### Using mutations
+To query and mutate data using this hook, you can leverage the parameters returned. In the
+following example we'll also use a `refine` function as well as `revalidateOnFocus` (option from
+`SWRConfiguration`) so that our data keeps updating on window focus change.
+
+```tsx
+import { useState } from "react";
+import { useApiQuery } from "bknd/client";
+
+export default function App() {
+   const [text, setText] = useState("");
+   const { data, api, mutate, ...q } = useApiQuery(
+      (api) => api.data.readOne("comments", 1),
+      {
+         // filter to a subset of the response
+         refine: (data) => data.data,
+         revalidateOnFocus: true
+      }
+   );
+
+   const comment = data ? data : null;
+
+   useEffect(() => {
+      setText(comment?.content ?? "");
+   }, [comment]);
+
+   if (q.error) return <div>Error</div>
+   if (q.isLoading) return <div>Loading...</div>
+
+   return (
+      <form
+         onSubmit={async (e) => {
+            e.preventDefault();
+            if (!comment) return;
+
+            // this will automatically revalidate the query
+            await mutate(async () => {
+               const res = await api.data.updateOne("comments", comment.id, {
+                  content: text
+               });
+               return res.data;
+            });
+
+            return false;
+         }}
+      >
+         <input type="text" value={text} onChange={(e) => setText(e.target.value)} />
+         <button type="submit">Update</button>
+      </form>
+   );
+}
+```
+
+## `useEntity()`
+This hook wraps the endpoints of `DataApi` and returns CRUD options as parameters:
+```tsx
+import { useState } from "react",
+import { useEntity } from "bknd/client";
+
+export default function App() {
+   const [data, setData] = useState<any>();
+   const { create, read, update, _delete } = useEntity("comments", 1);
+
+   useEffect(() => {
+      read().then(setData);
+   }, []);
+
+   return <pre>{JSON.stringify(data, null, 2)}</pre>
+}
+```
+If you only supply the entity name as string without an ID, the `read` method will fetch a list
+of entities instead of a single entry.
+
+### Props
+Following props are available when using `useEntityQuery([entity], [id?])`:
+- `entity: string`: Specify the table name of the entity
+- `id?: number | string`: If an id given, it will fetch a single entry, otherwise a list
+
+### Returned actions
+The following actions are returned from this hook:
+- `create: (input: object)`: Create a new entry
+- `read: (query: Partial<RepoQuery> = {})`: If an id was given,
+it returns a single item, otherwise a list
+- `update: (input: object, id?: number | string)`: If an id was given, the id parameter is
+optional. Updates the given entry partially.
+- `_delete: (id?: number | string)`: If an id was given, the id parameter is
+optional. Deletes the given entry.
+
+## `useEntityQuery()`
+This hook wraps the actions from `useEntity` around `SWR`. The previous example would look like
+this:
+```tsx
+import { useState } from "react",
+import { useEntityQuery } from "bknd/client";
+
+export default function App() {
+   const { data } = useEntityQuery("comments", 1);
+
+   return <pre>{JSON.stringify(data, null, 2)}</pre>
+}
+```
+
+### Using mutations
+All actions returned from `useEntityQuery` are conveniently wrapped around the `mutate` function,
+so you don't have think about this:
+```tsx
+import { useState } from "react";
+import { useEntityQuery } from "bknd/client";
+
+export default function App() {
+   const [text, setText] = useState("");
+   const { data, update, ...q } = useEntityQuery("comments", 1);
+
+   const comment = data ? data : null;
+
+   useEffect(() => {
+      setText(comment?.content ?? "");
+   }, [comment]);
+
+   if (q.error) return <div>Error</div>
+   if (q.isLoading) return <div>Loading...</div>
+
+   return (
+      <form
+         onSubmit={async (e) => {
+            e.preventDefault();
+            if (!comment) return;
+
+            // this will automatically revalidate the query
+            await update({ content: text });
+
+            return false;
+         }}
+      >
+         <input type="text" value={text} onChange={(e) => setText(e.target.value)} />
+         <button type="submit">Update</button>
+      </form>
+   );
+}
+```