Skip to content

Commit ecdd719

Browse files
author
devgioele
committed
document options and their default values
1 parent 4640931 commit ecdd719

7 files changed

Lines changed: 64 additions & 43 deletions

File tree

‎src/engine/pagination.ts‎

Lines changed: 29 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -8,24 +8,40 @@ import {
88
AbstractQueryOptions,
99
} from './query'
1010

11-
export type PaginationQuery = { page: number; size: number }
12-
13-
export type ChangeQueryOptions = { resetPage: boolean }
11+
export type PaginationQuery = {
12+
/**
13+
* The page index.
14+
*/
15+
page: number
16+
/**
17+
* The size of one page.
18+
*/
19+
size: number
20+
}
1421

1522
const DEFAULT_PAGINATION: PaginationQuery = {
1623
page: 0,
1724
size: 15,
1825
}
1926

27+
export type ChangeQueryOptions = {
28+
/**
29+
* Whether the page should be reset to its default value when the query is changed.
30+
*
31+
* @default `true`
32+
*/
33+
resetPage: boolean
34+
}
35+
36+
const DEFAULT_CHANGE_QUERY_OPTIONS: ChangeQueryOptions = { resetPage: true }
37+
2038
const parsePagination = (query: Query): Partial<PaginationQuery> => {
2139
return {
2240
page: queryValueToIntOrUndefined(query.page),
2341
size: queryValueToIntOrUndefined(query.size),
2442
}
2543
}
2644

27-
const DEFAULT_RESET_PAGE = true
28-
2945
export const useAbstractQueryAndPagination = <T extends AbstractQuery>(
3046
defaultQuery: T,
3147
parseQuery: ParseQuery<T>,
@@ -63,23 +79,21 @@ export const useAbstractQueryAndPagination = <T extends AbstractQuery>(
6379
return {
6480
query,
6581
setQuery: (query: Partial<T>, options?: Partial<ChangeQueryOptions>) => {
66-
const resetPage =
67-
options?.resetPage === undefined
68-
? DEFAULT_RESET_PAGE
69-
: options.resetPage
82+
const mergedOptions = { ...DEFAULT_CHANGE_QUERY_OPTIONS, ...options }
7083
setQuery({
7184
...query,
72-
page: resetPage ? mergedDefaultPagination.page : undefined,
85+
page: mergedOptions.resetPage
86+
? mergedDefaultPagination.page
87+
: undefined,
7388
})
7489
},
7590
resetQuery: (options?: Partial<ChangeQueryOptions>) => {
76-
const resetPage =
77-
options?.resetPage === undefined
78-
? DEFAULT_RESET_PAGE
79-
: options.resetPage
91+
const mergedOptions = { ...DEFAULT_CHANGE_QUERY_OPTIONS, ...options }
8092
setQuery({
8193
...defaultQuery,
82-
page: resetPage ? mergedDefaultPagination.page : undefined,
94+
page: mergedOptions.resetPage
95+
? mergedDefaultPagination.page
96+
: undefined,
8397
})
8498
},
8599
page: pagination.page,

‎src/engine/query.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ export const useQuery = <T extends Query>(defaultQuery: T, router: Router) => {
5050
}
5151

5252
export type AbstractQueryOptions = {
53+
/**
54+
* How the abstract query is converted to an actual query.
55+
*
56+
* @default Each value that is not undefined is converted to a string by calling `.toString()`.
57+
*/
5358
convertToQuery: (abstractQuery: Partial<AbstractQuery>) => Query
5459
}
5560

‎src/routers/nextRouter.ts‎

Lines changed: 6 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,17 +12,14 @@ import {
1212
PaginationQuery,
1313
useAbstractQueryAndPagination,
1414
} from '../engine/pagination'
15+
import { RouterWithHistoryOptions } from './shared'
1516

16-
export type NextRouterOptions = {
17-
setQueryMethod: 'replace' | 'push'
18-
}
19-
20-
const DEFAULT_NEXT_ROUTER_OPTIONS: NextRouterOptions = {
17+
const DEFAULT_NEXT_ROUTER_OPTIONS: RouterWithHistoryOptions = {
2118
setQueryMethod: 'replace',
2219
}
2320

2421
const useNextRouter = (
25-
options: undefined | Partial<NextRouterOptions>
22+
options: undefined | Partial<RouterWithHistoryOptions>
2623
): Router => {
2724
const nextRouter = useRouter()
2825

@@ -60,7 +57,7 @@ const useNextRouter = (
6057
export const useQuery = <T extends AbstractQuery>(
6158
defaultQuery: T,
6259
parseQuery: ParseQuery<T>,
63-
options?: Partial<AbstractQueryOptions & NextRouterOptions>
60+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
6461
) => {
6562
const router = useNextRouter(options)
6663
return useAbstractQuery(defaultQuery, parseQuery, router, options)
@@ -70,7 +67,7 @@ export const useQueryAndPagination = <T extends AbstractQuery>(
7067
defaultQuery: T,
7168
parseQuery: ParseQuery<T>,
7269
defaultPagination?: PaginationQuery,
73-
options?: Partial<AbstractQueryOptions & NextRouterOptions>
70+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
7471
) => {
7572
const router = useNextRouter(options)
7673
return useAbstractQueryAndPagination(
@@ -84,7 +81,7 @@ export const useQueryAndPagination = <T extends AbstractQuery>(
8481

8582
export const usePagination = (
8683
defaultPagination?: PaginationQuery,
87-
options?: Partial<AbstractQueryOptions & NextRouterOptions>
84+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
8885
) => {
8986
const { page, size, setPage, setSize, setPagination, resetPagination } =
9087
useQueryAndPagination({}, () => ({}), defaultPagination, options)

‎src/routers/reactRouter.ts‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,19 +10,14 @@ import {
1010
useAbstractQueryAndPagination,
1111
Router,
1212
} from '../engine'
13+
import { QUERY_ARRAY_SEPARATOR, RouterWithHistoryOptions } from './shared'
1314

14-
const QUERY_ARRAY_SEPARATOR = ','
15-
16-
export type ReactRouterOptions = {
17-
setQueryMethod: 'replace' | 'push'
18-
}
19-
20-
const DEFAULT_REACT_ROUTER_OPTIONS: ReactRouterOptions = {
15+
const DEFAULT_REACT_ROUTER_OPTIONS: RouterWithHistoryOptions = {
2116
setQueryMethod: 'replace',
2217
}
2318

2419
const useReactRouter = (
25-
options: undefined | Partial<ReactRouterOptions>
20+
options: undefined | Partial<RouterWithHistoryOptions>
2621
): Router => {
2722
const navigate = useNavigate()
2823
const { pathname, search } = useLocation()
@@ -75,7 +70,7 @@ const useReactRouter = (
7570
export const useQuery = <T extends AbstractQuery>(
7671
defaultQuery: T,
7772
parseQuery: ParseQuery<T>,
78-
options?: Partial<AbstractQueryOptions & ReactRouterOptions>
73+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
7974
) => {
8075
const router = useReactRouter(options)
8176
return useAbstractQuery(defaultQuery, parseQuery, router, options)
@@ -85,7 +80,7 @@ export const useQueryAndPagination = <T extends AbstractQuery>(
8580
defaultQuery: T,
8681
parseQuery: ParseQuery<T>,
8782
defaultPagination?: PaginationQuery,
88-
options?: Partial<AbstractQueryOptions & ReactRouterOptions>
83+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
8984
) => {
9085
const router = useReactRouter(options)
9186
return useAbstractQueryAndPagination(
@@ -99,7 +94,7 @@ export const useQueryAndPagination = <T extends AbstractQuery>(
9994

10095
export const usePagination = (
10196
defaultPagination?: PaginationQuery,
102-
options?: Partial<AbstractQueryOptions & ReactRouterOptions>
97+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
10398
) => {
10499
const { page, size, setPage, setSize, setPagination, resetPagination } =
105100
useQueryAndPagination({}, () => ({}), defaultPagination, options)

‎src/routers/shared.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
export const QUERY_ARRAY_SEPARATOR = ','
2+
3+
export type RouterWithHistoryOptions = {
4+
/**
5+
* Whether the router should push a new URL to the browser history or replace the current URL.
6+
*
7+
* @default 'replace'
8+
*/
9+
setQueryMethod: 'replace' | 'push'
10+
}

‎src/zod/routers/nextRouter.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ import {
88
useQuery as useQueryVanilla,
99
usePagination as usePaginationVanilla,
1010
useQueryAndPagination as useQueryAndPaginationVanilla,
11-
NextRouterOptions,
1211
} from '../../routers/nextRouter'
1312
import { zodParser } from '../util'
1413
import { NonNullableRecord } from '../../utils'
14+
import { RouterWithHistoryOptions } from '../../routers/shared'
1515

1616
export const useQuery = <
1717
TQuery extends NonNullableRecord<TSchemaOutput>,
@@ -21,7 +21,7 @@ export const useQuery = <
2121
>(
2222
defaultQuery: TQuery,
2323
schemaQuery: ZodType<TSchemaOutput, TSchemaDef, TSchemaInput>,
24-
options?: Partial<AbstractQueryOptions & NextRouterOptions>
24+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
2525
) => useQueryVanilla(defaultQuery, zodParser(schemaQuery), options)
2626

2727
export const useQueryAndPagination = <
@@ -33,7 +33,7 @@ export const useQueryAndPagination = <
3333
defaultQuery: TQuery,
3434
schemaQuery: ZodType<TSchemaOutput, TSchemaDef, TSchemaInput>,
3535
defaultPagination?: PaginationQuery,
36-
options?: Partial<AbstractQueryOptions & NextRouterOptions>
36+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
3737
) =>
3838
useQueryAndPaginationVanilla(
3939
defaultQuery,
@@ -44,5 +44,5 @@ export const useQueryAndPagination = <
4444

4545
export const usePagination = (
4646
defaultPagination?: PaginationQuery,
47-
options?: Partial<AbstractQueryOptions & NextRouterOptions>
47+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
4848
) => usePaginationVanilla(defaultPagination, options)

‎src/zod/routers/reactRouter.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ import {
88
useQuery as useQueryVanilla,
99
usePagination as usePaginationVanilla,
1010
useQueryAndPagination as useQueryAndPaginationVanilla,
11-
ReactRouterOptions,
1211
} from '../../routers/reactRouter'
1312
import { zodParser } from '../util'
1413
import { NonNullableRecord } from '../../utils'
14+
import { RouterWithHistoryOptions } from '../../routers/shared'
1515

1616
export const useQuery = <
1717
TQuery extends NonNullableRecord<TSchemaOutput>,
@@ -21,7 +21,7 @@ export const useQuery = <
2121
>(
2222
defaultQuery: TQuery,
2323
schemaQuery: ZodType<TSchemaOutput, TSchemaDef, TSchemaInput>,
24-
options?: Partial<AbstractQueryOptions & ReactRouterOptions>
24+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
2525
) => useQueryVanilla(defaultQuery, zodParser(schemaQuery), options)
2626

2727
export const useQueryAndPagination = <
@@ -33,7 +33,7 @@ export const useQueryAndPagination = <
3333
defaultQuery: TQuery,
3434
schemaQuery: ZodType<TSchemaOutput, TSchemaDef, TSchemaInput>,
3535
defaultPagination?: PaginationQuery,
36-
options?: Partial<AbstractQueryOptions & ReactRouterOptions>
36+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
3737
) =>
3838
useQueryAndPaginationVanilla(
3939
defaultQuery,
@@ -44,5 +44,5 @@ export const useQueryAndPagination = <
4444

4545
export const usePagination = (
4646
defaultPagination?: PaginationQuery,
47-
options?: Partial<AbstractQueryOptions & ReactRouterOptions>
47+
options?: Partial<AbstractQueryOptions & RouterWithHistoryOptions>
4848
) => usePaginationVanilla(defaultPagination, options)

0 commit comments

Comments
 (0)