From 09d28619061c05530fe470b9e27c059a84ee3a8a Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 28 Sep 2022 10:43:26 -0400 Subject: [PATCH 1/5] Add API reference for Astro.cookies --- src/pages/en/reference/api-reference.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/src/pages/en/reference/api-reference.md b/src/pages/en/reference/api-reference.md index 1ebe8e7e03546..192dae493322b 100644 --- a/src/pages/en/reference/api-reference.md +++ b/src/pages/en/reference/api-reference.md @@ -166,6 +166,31 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); --- ``` +### `Astro.cookies` + +`Astro.cookies` contains utilities for reading and manipulating cookies. + +| Name | Type | Description | +| :------------- | :------------------------------------------------ | :------------------------------------------------- | +| `get` | `(key: string) => AstroCookie` | Gets the cookie as an `AstroCookie` object, which contains the `value` and utility functions for converting the cookie to non-string types. | +| `has` | `(key: string) => boolean` | Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` this will return true, otherwise it will check cookies in the `Astro.request`. | +| `set` | `(key: string, value: string \| number \| boolean \| object, options?: CookieOptions) => void` | Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set cookie features, such as the `maxAge` or `httpOnly`. | +| `delete` | `(key: string) => void` | Marks the cookie to be deleted. Deleting a cookie means sending out a header as part of the response. Once a cookie is deleted it will return `false` via `Astro.cookies.has()`. | +| `headers` | `() => Iterator` | Gets the header values for `Set-Cookie` that will be sent out with the response. | + + +#### `AstroCookie` + +Getting a cookie via `Astro.cookies.get()` returns a `AstroCookie` type. It has the following structure. + +| Name | Type | Description | +| :------------- | :------------------------------------------------ | :------------------------------------------------- | +| `value` | `string` | The raw string value of the cookie. | +| `json` | `() => Record` | Parses the cookie value via `JSON.parse()`, returning an object. Throws if the cookie value is not valid JSON. | +| `number` | `() => number` | Parses the cookie value as a Number. Returns NaN if not a valid number. | +| `boolean` | `() => boolean` | Converts the cookie value to a boolean. | + + ### `Astro.canonicalURL` :::caution[Deprecated] From 3f312553a5ebc9ef265f6a5cbbd2c6e173fa95a8 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 28 Sep 2022 17:12:43 -0400 Subject: [PATCH 2/5] Update src/pages/en/reference/api-reference.md Co-authored-by: Sarah Rainsberger --- src/pages/en/reference/api-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/en/reference/api-reference.md b/src/pages/en/reference/api-reference.md index 192dae493322b..0a4bcc2eb4880 100644 --- a/src/pages/en/reference/api-reference.md +++ b/src/pages/en/reference/api-reference.md @@ -172,7 +172,7 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); | Name | Type | Description | | :------------- | :------------------------------------------------ | :------------------------------------------------- | -| `get` | `(key: string) => AstroCookie` | Gets the cookie as an `AstroCookie` object, which contains the `value` and utility functions for converting the cookie to non-string types. | +| `get` | `(key: string) => AstroCookie` | Gets the cookie as an `(AstroCookie)[#astrocookie]` object, which contains the `value` and utility functions for converting the cookie to non-string types. | | `has` | `(key: string) => boolean` | Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` this will return true, otherwise it will check cookies in the `Astro.request`. | | `set` | `(key: string, value: string \| number \| boolean \| object, options?: CookieOptions) => void` | Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set cookie features, such as the `maxAge` or `httpOnly`. | | `delete` | `(key: string) => void` | Marks the cookie to be deleted. Deleting a cookie means sending out a header as part of the response. Once a cookie is deleted it will return `false` via `Astro.cookies.has()`. | From 00d4b47299bce36dc44ced1452d502876cc3d7b1 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Wed, 28 Sep 2022 17:19:17 -0400 Subject: [PATCH 3/5] Add link to cookie library --- src/pages/en/reference/api-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/en/reference/api-reference.md b/src/pages/en/reference/api-reference.md index 0a4bcc2eb4880..d7a13f071d7c5 100644 --- a/src/pages/en/reference/api-reference.md +++ b/src/pages/en/reference/api-reference.md @@ -174,7 +174,7 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); | :------------- | :------------------------------------------------ | :------------------------------------------------- | | `get` | `(key: string) => AstroCookie` | Gets the cookie as an `(AstroCookie)[#astrocookie]` object, which contains the `value` and utility functions for converting the cookie to non-string types. | | `has` | `(key: string) => boolean` | Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` this will return true, otherwise it will check cookies in the `Astro.request`. | -| `set` | `(key: string, value: string \| number \| boolean \| object, options?: CookieOptions) => void` | Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set cookie features, such as the `maxAge` or `httpOnly`. | +| `set` | `(key: string, value: string \| number \| boolean \| object, options?: CookieOptions) => void` | Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set [cookie features](https://www.npmjs.com/package/cookie#options-1), such as the `maxAge` or `httpOnly`. | | `delete` | `(key: string) => void` | Marks the cookie to be deleted. Deleting a cookie means sending out a header as part of the response. Once a cookie is deleted it will return `false` via `Astro.cookies.has()`. | | `headers` | `() => Iterator` | Gets the header values for `Set-Cookie` that will be sent out with the response. | From eed84657a0ef123cd245d93b4852fe24c0fa0363 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 29 Sep 2022 09:10:24 -0400 Subject: [PATCH 4/5] Update src/pages/en/reference/api-reference.md Co-authored-by: Chris Swithinbank --- src/pages/en/reference/api-reference.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pages/en/reference/api-reference.md b/src/pages/en/reference/api-reference.md index d7a13f071d7c5..accaf6e19e857 100644 --- a/src/pages/en/reference/api-reference.md +++ b/src/pages/en/reference/api-reference.md @@ -168,6 +168,8 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); ### `Astro.cookies` + + `Astro.cookies` contains utilities for reading and manipulating cookies. | Name | Type | Description | From 83a896e8071a0fbc2c431d6173602a2eb323486d Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 29 Sep 2022 09:14:54 -0400 Subject: [PATCH 5/5] Clarify what delete does --- src/pages/en/reference/api-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/en/reference/api-reference.md b/src/pages/en/reference/api-reference.md index accaf6e19e857..704157e234ba0 100644 --- a/src/pages/en/reference/api-reference.md +++ b/src/pages/en/reference/api-reference.md @@ -177,7 +177,7 @@ Astro.response.headers.set('Set-Cookie', 'a=b; Path=/;'); | `get` | `(key: string) => AstroCookie` | Gets the cookie as an `(AstroCookie)[#astrocookie]` object, which contains the `value` and utility functions for converting the cookie to non-string types. | | `has` | `(key: string) => boolean` | Whether this cookie exists. If the cookie has been set via `Astro.cookies.set()` this will return true, otherwise it will check cookies in the `Astro.request`. | | `set` | `(key: string, value: string \| number \| boolean \| object, options?: CookieOptions) => void` | Sets the cookie `key` to the given value. This will attempt to convert the cookie value to a string. Options provide ways to set [cookie features](https://www.npmjs.com/package/cookie#options-1), such as the `maxAge` or `httpOnly`. | -| `delete` | `(key: string) => void` | Marks the cookie to be deleted. Deleting a cookie means sending out a header as part of the response. Once a cookie is deleted it will return `false` via `Astro.cookies.has()`. | +| `delete` | `(key: string) => void` | Marks the cookie as deleted. Once a cookie is deleted `Astro.cookies.has()` will return `false` and `Astro.cookies.get()` will return an `(AstroCookie)[#astrocookie]` with a `value` of `undefined`. | | `headers` | `() => Iterator` | Gets the header values for `Set-Cookie` that will be sent out with the response. |