Add API reference for Astro.cookies #1637
Conversation
✅ Deploy Preview for astro-docs-2 ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
sarah11918
added
add new content
| | `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()`. | |
There was a problem hiding this comment.
| | `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()`. | | |
| Marks the cookie to be deleted. Deleting a cookie means sending out a header as part of the response. | |
I'm a little unclear about the second sentence. delete marks the cookie for deletion. Is there a more direct way of saying how the cookie is deleted? What action deletes it, or after which event it is deleted?
OR, is the sentence necessary at all?
Marks the cookie to be deleted. Once a cookie is deleted it will return
falseviaAstro.cookies.has().
Does that tell enough about what is happening? Would someone need to know/understand what happens in between marking the cookie for deletion, and then after it has been deleted? (Is there a special timing consideration for an in-between state that it's important to address?)
There was a problem hiding this comment.
So technically what is happening is when you "delete" a cookie you are really just sending a Set-Cookie: key=value; expires=Thu, 01 Jan 1970 00:00:00 GMT. Note here that expires is in the past, this tells the browser that the cookie has expired so it deletes it.
So you're really just telling the browser that the cookie is no longer valid.
I'm not sure if we need to explain that part to the user here? I will defer to your judgement on that.
What I was trying to convey here is that, from the context of the Astro.cookies API, once you call delete(key) that cookie no longer exists, you cannot do get(key) or has(key) to get its value. It's "deleted" from memory, if you will.
There was a problem hiding this comment.
I might be tempted to say something like:
Marks the cookie as deleted. Once a cookie is deleted,
Astro.cookies.has()will return false andAstro.cookies.get()will .... . (throw an error/return null.. whatever it does)
Would that describe it well enough? (Using "as" to imply that it "takes effect" immediately as far as the user is concerned? Could also say "as expired" or "as invalid") Then, describe what the other functions will return?
I'll leave the final wording, or whether or not to make any changes up to you, though. If that second sentence as it currently is would be clear in context to the general reader, then it's fine by me!
There was a problem hiding this comment.
Yeah I like this, it skips over the "how" which is not important from the API perspective and just focuses on how Astro.cookies will work after deletion. I'll update with something like this.
| | `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<string>` | Gets the header values for `Set-Cookie` that will be sent out with the response. | |
There was a problem hiding this comment.
no comment! Just can't delete this.
Co-authored-by: Sarah Rainsberger <[email protected]>
|
Just reminding you @matthewp that this is your PR to merge when you're happy with it! (In Docs, we always leave it up to the author to merge, if they have maintainer authority.) |
Co-authored-by: Chris Swithinbank <[email protected]>
* Add API reference for Astro.cookies * Update src/pages/en/reference/api-reference.md Co-authored-by: Sarah Rainsberger <[email protected]> * Add link to cookie library * Update src/pages/en/reference/api-reference.md Co-authored-by: Chris Swithinbank <[email protected]> * Clarify what delete does Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]>
sarah11918
added
the
minor-release
What kind of changes does this PR include?
Docs for
Astro.cookiesDescription
Docs for withastro/astro#4876