Skip to content

Commit 4c80b6e

Browse files
franky47franky47
committed
feat: Add loader feature for React Routers and Remix
1 parent 479d5ea commit 4c80b6e

File tree

5 files changed

+324
-1
lines changed

5 files changed

+324
-1
lines changed

‎packages/nuqs/package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@
186186
{
187187
"name": "Server",
188188
"path": "dist/server.js",
189-
"limit": "2 kB",
189+
"limit": "2.5 kB",
190190
"ignore": [
191191
"react",
192192
"next"

‎packages/nuqs/src/index.server.ts

+6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
export { createSearchParamsCache } from './cache'
22
export type { HistoryOptions, Nullable, Options, SearchParams } from './defs'
3+
export {
4+
createLoader,
5+
type LoaderFunction,
6+
type LoaderInput,
7+
type LoaderOptions
8+
} from './loader'
39
export * from './parsers'
410
export { createSerializer } from './serializer'

‎packages/nuqs/src/index.ts

+6
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,10 @@
11
export type { HistoryOptions, Nullable, Options, SearchParams } from './defs'
2+
export {
3+
createLoader,
4+
type LoaderFunction,
5+
type LoaderInput,
6+
type LoaderOptions
7+
} from './loader'
28
export * from './parsers'
39
export { createSerializer } from './serializer'
410
export * from './useQueryState'

‎packages/nuqs/src/loader.test.ts

+187
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
import { describe, expect, it } from 'vitest'
2+
import { createLoader } from './loader'
3+
import { parseAsInteger } from './parsers'
4+
5+
describe('loader', () => {
6+
describe('sync', () => {
7+
it('parses a URL object', () => {
8+
const load = createLoader({
9+
a: parseAsInteger,
10+
b: parseAsInteger
11+
})
12+
const result = load(new URL('http://example.com/?a=1&b=2'))
13+
expect(result).toEqual({
14+
a: 1,
15+
b: 2
16+
})
17+
})
18+
it('parses a Request object', () => {
19+
const load = createLoader({
20+
a: parseAsInteger,
21+
b: parseAsInteger
22+
})
23+
const result = load(new Request('http://example.com/?a=1&b=2'))
24+
expect(result).toEqual({
25+
a: 1,
26+
b: 2
27+
})
28+
})
29+
it('parses a URLSearchParams object', () => {
30+
const load = createLoader({
31+
a: parseAsInteger,
32+
b: parseAsInteger
33+
})
34+
const result = load(new URLSearchParams('a=1&b=2'))
35+
expect(result).toEqual({
36+
a: 1,
37+
b: 2
38+
})
39+
})
40+
it('parses a Record<string, string | string[] | undefined> object', () => {
41+
const load = createLoader({
42+
a: parseAsInteger,
43+
b: parseAsInteger
44+
})
45+
const result = load({
46+
a: '1',
47+
b: '2'
48+
})
49+
expect(result).toEqual({
50+
a: 1,
51+
b: 2
52+
})
53+
})
54+
it('parses a URL string', () => {
55+
const load = createLoader({
56+
a: parseAsInteger,
57+
b: parseAsInteger
58+
})
59+
const result = load('https://example.com/?a=1&b=2')
60+
expect(result).toEqual({
61+
a: 1,
62+
b: 2
63+
})
64+
})
65+
it('parses a search params string', () => {
66+
const load = createLoader({
67+
a: parseAsInteger,
68+
b: parseAsInteger
69+
})
70+
const result = load('?a=1&b=2')
71+
expect(result).toEqual({
72+
a: 1,
73+
b: 2
74+
})
75+
})
76+
it('supports urlKeys', () => {
77+
const load = createLoader(
78+
{
79+
urlKey: parseAsInteger
80+
},
81+
{
82+
urlKeys: {
83+
urlKey: 'a'
84+
}
85+
}
86+
)
87+
const result = load('?a=1')
88+
expect(result).toEqual({
89+
urlKey: 1
90+
})
91+
})
92+
})
93+
94+
describe('async', () => {
95+
it('parses a URL object', () => {
96+
const load = createLoader({
97+
a: parseAsInteger,
98+
b: parseAsInteger
99+
})
100+
const result = load(
101+
Promise.resolve(new URL('http://example.com/?a=1&b=2'))
102+
)
103+
return expect(result).resolves.toEqual({
104+
a: 1,
105+
b: 2
106+
})
107+
})
108+
it('parses a Request object', () => {
109+
const load = createLoader({
110+
a: parseAsInteger,
111+
b: parseAsInteger
112+
})
113+
const result = load(
114+
Promise.resolve(new Request('http://example.com/?a=1&b=2'))
115+
)
116+
return expect(result).resolves.toEqual({
117+
a: 1,
118+
b: 2
119+
})
120+
})
121+
it('parses a URLSearchParams object', () => {
122+
const load = createLoader({
123+
a: parseAsInteger,
124+
b: parseAsInteger
125+
})
126+
const result = load(Promise.resolve(new URLSearchParams('a=1&b=2')))
127+
return expect(result).resolves.toEqual({
128+
a: 1,
129+
b: 2
130+
})
131+
})
132+
it('parses a Record<string, string | string[] | undefined> object', () => {
133+
const load = createLoader({
134+
a: parseAsInteger,
135+
b: parseAsInteger
136+
})
137+
const result = load(
138+
Promise.resolve({
139+
a: '1',
140+
b: '2'
141+
})
142+
)
143+
return expect(result).resolves.toEqual({
144+
a: 1,
145+
b: 2
146+
})
147+
})
148+
it('parses a URL string', () => {
149+
const load = createLoader({
150+
a: parseAsInteger,
151+
b: parseAsInteger
152+
})
153+
const result = load(Promise.resolve('https://example.com/?a=1&b=2'))
154+
return expect(result).resolves.toEqual({
155+
a: 1,
156+
b: 2
157+
})
158+
})
159+
it('parses a search params string', () => {
160+
const load = createLoader({
161+
a: parseAsInteger,
162+
b: parseAsInteger
163+
})
164+
const result = load(Promise.resolve('?a=1&b=2'))
165+
return expect(result).resolves.toEqual({
166+
a: 1,
167+
b: 2
168+
})
169+
})
170+
it('supports urlKeys', () => {
171+
const load = createLoader(
172+
{
173+
urlKey: parseAsInteger
174+
},
175+
{
176+
urlKeys: {
177+
urlKey: 'a'
178+
}
179+
}
180+
)
181+
const result = load(Promise.resolve('?a=1'))
182+
return expect(result).resolves.toEqual({
183+
urlKey: 1
184+
})
185+
})
186+
})
187+
})

‎packages/nuqs/src/loader.ts

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
import type { UrlKeys } from './defs'
2+
import type { inferParserType, ParserMap } from './parsers'
3+
4+
export type LoaderInput =
5+
| URL
6+
| Request
7+
| URLSearchParams
8+
| Record<string, string | string[] | undefined>
9+
| string
10+
11+
export type LoaderOptions<Parsers extends ParserMap> = {
12+
urlKeys?: UrlKeys<Parsers>
13+
}
14+
15+
export type LoaderFunction<Parsers extends ParserMap> = ReturnType<
16+
typeof createLoader<Parsers>
17+
>
18+
19+
export function createLoader<Parsers extends ParserMap>(
20+
parsers: Parsers,
21+
{ urlKeys = {} }: LoaderOptions<Parsers> = {}
22+
) {
23+
type ParsedSearchParams = inferParserType<Parsers>
24+
25+
/**
26+
* Load & parse search params from (almost) any input.
27+
*
28+
* While loaders are typically used in the context of a React Router / Remix
29+
* loader function, it can also be used in Next.js API routes or
30+
* getServerSideProps functions, or even with the app router `searchParams`
31+
* page prop (sync or async), if you don't need the cache behaviours.
32+
*/
33+
function loadSearchParams(
34+
input: LoaderInput,
35+
options?: LoaderOptions<Parsers>
36+
): ParsedSearchParams
37+
38+
/**
39+
* Load & parse search params from (almost) any input.
40+
*
41+
* While loaders are typically used in the context of a React Router / Remix
42+
* loader function, it can also be used in Next.js API routes or
43+
* getServerSideProps functions, or even with the app router `searchParams`
44+
* page prop (sync or async), if you don't need the cache behaviours.
45+
*
46+
* Note: this async overload makes it easier to use against the `searchParams`
47+
* page prop in Next.js 15 app router:
48+
*
49+
* ```tsx
50+
* export default async function Page({ searchParams }) {
51+
* const parsedSearchParamsPromise = loadSearchParams(searchParams)
52+
* return (
53+
* // Pre-render & stream the shell immediately
54+
* <StaticShell>
55+
* <Suspense>
56+
* // Stream the Promise down
57+
* <DynamicComponent searchParams={parsedSearchParamsPromise} />
58+
* </Suspense>
59+
* </StaticShell>
60+
* )
61+
* }
62+
* ```
63+
*/
64+
function loadSearchParams(
65+
input: Promise<LoaderInput>,
66+
options?: LoaderOptions<Parsers>
67+
): Promise<ParsedSearchParams>
68+
69+
function loadSearchParams(input: LoaderInput | Promise<LoaderInput>) {
70+
if (input instanceof Promise) {
71+
return input.then(i => loadSearchParams(i))
72+
}
73+
const searchParams = extractSearchParams(input)
74+
const result = {} as any
75+
for (const [key, parser] of Object.entries(parsers)) {
76+
const urlKey = urlKeys[key] ?? key
77+
const value = searchParams.get(urlKey)
78+
result[key] = parser.parseServerSide(value ?? undefined)
79+
}
80+
return result
81+
}
82+
return loadSearchParams
83+
}
84+
85+
function extractSearchParams(input: LoaderInput): URLSearchParams {
86+
try {
87+
if (input instanceof Request) {
88+
if (input.url) {
89+
return new URL(input.url).searchParams
90+
} else {
91+
return new URLSearchParams()
92+
}
93+
}
94+
if (input instanceof URL) {
95+
return input.searchParams
96+
}
97+
if (input instanceof URLSearchParams) {
98+
return input
99+
}
100+
if (typeof input === 'object') {
101+
const entries = Object.entries(input)
102+
const searchParams = new URLSearchParams()
103+
for (const [key, value] of entries) {
104+
if (Array.isArray(value)) {
105+
for (const v of value) {
106+
searchParams.append(key, v)
107+
}
108+
} else if (value !== undefined) {
109+
searchParams.set(key, value)
110+
}
111+
}
112+
return searchParams
113+
}
114+
if (typeof input === 'string') {
115+
if ('canParse' in URL && URL.canParse(input)) {
116+
return new URL(input).searchParams
117+
}
118+
return new URLSearchParams(input)
119+
}
120+
} catch (e) {
121+
return new URLSearchParams()
122+
}
123+
return new URLSearchParams()
124+
}

0 commit comments

Comments
 (0)