diff --git a/packages/docs/content/docs/parsers/built-in.mdx b/packages/docs/content/docs/parsers/built-in.mdx
index 3afb7618..9dda246b 100644
--- a/packages/docs/content/docs/parsers/built-in.mdx
+++ b/packages/docs/content/docs/parsers/built-in.mdx
@@ -12,6 +12,7 @@ import {
BooleanParserDemo,
StringLiteralParserDemo,
DateISOParserDemo,
+ DatetimeISOParserDemo,
DateTimestampParserDemo,
JsonParserDemo
} from '@/content/docs/parsers/demos'
@@ -29,8 +30,8 @@ This is where **parsers** come in.
import { parseAsString } from 'nuqs'
```
-}>
-
+}>
+
@@ -39,6 +40,7 @@ and will accept **any** value.
If you're expecting a certain set of string values, like `'foo' | 'bar'{:ts}`,
see [Literals](#literals) for ensuring type-runtime safety.
+
If search params are strings by default, what's the point of this _"parser"_ ?
@@ -67,11 +69,10 @@ import { parseAsInteger } from 'nuqs'
useQueryState('int', parseAsInteger.withDefault(0))
```
-}>
-
+}>
+
-
### Floating point
Same as integer, but uses `parseFloat` under the hood.
@@ -82,11 +83,10 @@ import { parseAsFloat } from 'nuqs'
useQueryState('float', parseAsFloat.withDefault(0))
```
-}>
-
+}>
+
-
### Hexadecimal
Encodes integers in hexadecimal.
@@ -97,12 +97,12 @@ import { parseAsHex } from 'nuqs'
useQueryState('hex', parseAsHex.withDefault(0x00))
```
-}>
-
+}>
+
- Check out the [Hex Colors](/playground/hex-colors) playground for a demo.
+ Check out the [Hex Colors](/playground/hex-colors) playground for a demo.
## Boolean
@@ -113,8 +113,8 @@ import { parseAsBoolean } from 'nuqs'
useQueryState('bool', parseAsBoolean.withDefault(false))
```
-}>
-
+}>
+
## Literals
@@ -138,14 +138,13 @@ const sortOrder = ['asc', 'desc'] as const
parseAsStringLiteral(sortOrder)
// Optional: extract the type from them
-type SortOrder = (typeof sortOrder)[number]; // 'asc' | 'desc'
+type SortOrder = (typeof sortOrder)[number] // 'asc' | 'desc'
```
-}>
-
+}>
+
-
### Numeric literals
```ts /as const/
@@ -174,8 +173,8 @@ parseAsStringEnum(Object.values(Direction))
```
-The query string value will be the **value** of the enum, not its name
-(here: `?direction=UP`).
+ The query string value will be the **value** of the enum, not its name (here:
+ `?direction=UP`).
## Dates & timestamps
@@ -183,14 +182,26 @@ The query string value will be the **value** of the enum, not its name
There are two parsers that give you a `Date` object, their difference is
on how they encode the value into the query string.
-### ISO 8601
+### ISO 8601 Datetime
```ts
import { parseAsIsoDateTime } from 'nuqs'
```
-
+
+
+
+### ISO 8601 Date
+
+Note: the Date is parsed without the time zone offset, making it at GMT 00:00:00 UTC.
+
+```ts
+import { parseAsIsoDate } from 'nuqs'
+```
+
+
+
### Timestamp
@@ -202,7 +213,7 @@ import { parseAsTimestamp } from 'nuqs'
```
-
+
## Arrays
@@ -241,14 +252,14 @@ const schema = z.object({
const [json, setJson] = useQueryState('json', parseAsJson(schema.parse))
setJson({
- pkg: "nuqs",
+ pkg: 'nuqs',
version: 2,
- worksWith: ["Next.js", "React", "Remix", "React Router", "and more"],
-});
+ worksWith: ['Next.js', 'React', 'Remix', 'React Router', 'and more']
+})
```
-
+
Using other validation libraries is possible, as long as they throw an error
@@ -264,6 +275,6 @@ import { parseAsString } from 'nuqs/server'
```
-It used to be available under the alias import `nuqs/parsers`,
-which will be dropped in the next major version.
+ It used to be available under the alias import `nuqs/parsers`, which will be
+ dropped in the next major version.
diff --git a/packages/docs/content/docs/parsers/demos.tsx b/packages/docs/content/docs/parsers/demos.tsx
index fab14bcd..2429926d 100644
--- a/packages/docs/content/docs/parsers/demos.tsx
+++ b/packages/docs/content/docs/parsers/demos.tsx
@@ -14,6 +14,7 @@ import {
parseAsFloat,
parseAsHex,
parseAsInteger,
+ parseAsIsoDate,
parseAsIsoDateTime,
parseAsJson,
parseAsStringLiteral,
@@ -246,10 +247,12 @@ export function StringLiteralParserDemo() {
export function DateParserDemo({
queryKey,
- parser
+ parser,
+ type
}: {
queryKey: string
parser: ParserBuilder
+ type: 'date' | 'datetime-local'
}) {
const [value, setValue] = useQueryState(queryKey, parser)
return (
@@ -257,7 +260,7 @@ export function DateParserDemo({
{
@@ -290,12 +293,28 @@ export function DateParserDemo({
)
}
+export function DatetimeISOParserDemo() {
+ return (
+
+ )
+}
+
export function DateISOParserDemo() {
- return
+ return
}
export function DateTimestampParserDemo() {
- return
+ return (
+
+ )
}
const jsonParserSchema = z.object({
diff --git a/packages/nuqs/src/parsers.test.ts b/packages/nuqs/src/parsers.test.ts
index e2fb37ce..74d9d3d0 100644
--- a/packages/nuqs/src/parsers.test.ts
+++ b/packages/nuqs/src/parsers.test.ts
@@ -5,6 +5,7 @@ import {
parseAsHex,
parseAsInteger,
parseAsIsoDateTime,
+ parseAsIsoDate,
parseAsString,
parseAsTimestamp
} from './parsers'
@@ -48,6 +49,14 @@ describe('parsers', () => {
ref
)
})
+ test('parseAsIsoDate', () => {
+ expect(parseAsIsoDate.parse('')).toBeNull()
+ expect(parseAsIsoDate.parse('not-a-date')).toBeNull()
+ const moment = '2020-01-01'
+ const ref = new Date(moment)
+ expect(parseAsIsoDate.parse(moment)).toStrictEqual(ref)
+ expect(parseAsIsoDate.serialize(ref)).toEqual(moment)
+ })
test('parseAsArrayOf', () => {
const parser = parseAsArrayOf(parseAsString)
expect(parser.serialize([])).toBe('')
diff --git a/packages/nuqs/src/parsers.ts b/packages/nuqs/src/parsers.ts
index 22d45cc1..82973a60 100644
--- a/packages/nuqs/src/parsers.ts
+++ b/packages/nuqs/src/parsers.ts
@@ -215,6 +215,25 @@ export const parseAsIsoDateTime = createParser({
serialize: (v: Date) => v.toISOString()
})
+/**
+ * Querystring encoded as an ISO-8601 string (UTC)
+ * without the time zone offset, and returned as
+ * a Date object.
+ *
+ * The Date is parsed without the time zone offset,
+ * making it at 00:00:00 UTC.
+ */
+export const parseAsIsoDate = createParser({
+ parse: v => {
+ const date = new Date(v.slice(0, 10))
+ if (Number.isNaN(date.valueOf())) {
+ return null
+ }
+ return date
+ },
+ serialize: (v: Date) => v.toISOString().slice(0, 10)
+})
+
/**
* String-based enums provide better type-safety for known sets of values.
* You will need to pass the parseAsStringEnum function a list of your enum values