shishantbiswas/bknd
1
0
Fork 0
mirror of https://github.com/shishantbiswas/bknd.git synced 2026-03-16 04:27:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

added useEntity and useEntityQuery hooks

Browse Source
This commit is contained in:
dswbx
2024-12-12 17:00:10 +01:00
parent 9d9aa7b7a5
commit 50c5adce0c
13 changed files with 456 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
app/src/data/server/data-query-impl.ts
View File

@@ -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;

31
app/src/modules/ModuleApi.ts
View File

@@ -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() {
const fetcher = this.fetcher ?? fetch;
async execute(): Promise<T> {
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
);
}
}

2
app/src/ui/client/ClientProvider.tsx
View File

@@ -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;
};

30
app/src/ui/client/api/use-api.ts Normal file
View File

@@ -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
};
};

37
app/src/ui/client/api/use-data.ts Normal file
View File

@@ -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]>;
}
);
};

76
app/src/ui/client/api/use-entity.ts Normal file
View File

@@ -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
};
};

4
app/src/ui/client/index.ts
View File

@@ -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";

18
app/src/ui/client/use-api.ts
View File

@@ -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);
};

4
app/src/ui/routes/test/index.tsx
View File

@@ -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() {

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

@@ -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 { data, error, isLoading } = useApiQuery(({ data }) => data.readMany("posts"), {
enabled,
const [text, setText] = useState("");
const { data, ...r } = useApiQuery((api) => api.data.readOne("comments", 1), {
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>
{error && <div>failed to load</div>}
{isLoading && <div>loading...</div>}
<pre>{JSON.stringify(r.promise.keyArray({ search: false }))}</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 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>
);
}

55
app/src/ui/routes/test/tests/swr-and-data-api.tsx Normal file
View File

@@ -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>;
}

2
docs/mint.json
View File

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

194
docs/react.mdx Normal file
View File

@@ -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>
);
}
```