Skip to content

README: fix docs around parse() / stringify() function names #255

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
getify wants to merge 2 commits into
base: master
Choose a base branch
from
Open

README: fix docs around parse() / stringify() function names #255

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37cfaea
README: fix rename of stringify() to stringifyCookie()
getify Dec 28, 2025
dffa450
adding notes about deprecated aliases
getify Dec 28, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ const cookie = require("cookie");

### cookie.parseCookie(str, options)

Alias: `parse()` (deprecated)
Copy link
Member

@blakeembrey blakeembrey Dec 29, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you share more context around adding the deprecated names? I can guess it’s for quick lookup from a previous version, but would like to understand more.

WDYT about making a “deprecated” section at the bottom and using that instead to point to the new methods? It could contain more information about the old function format too (three args vs one for stringify).

Copy link
Author

@getify getify Dec 29, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I upgraded from version 1.0.2 to 1.1.1, and as I was checking the docs, was confused by the new names... it felt at first like it had been a breaking change, even though it was only a minor version update.

I didn't see that the old names were still there for several minutes (where I was searching through the commit history to find out when that "breaking change" had happened), and then found the aliases were included down at the bottom of the file.

So my goal in adding them to the documentation is to prevent others' confusion. I made the "assumption" of deprecation given the name change but if there's no intent to actually deprecate, that part could be taken out from the names.

If you're intending to deprecate (and eventually break, on a semver major) the arguments, I agree those changes should also be noted in the docs, and indeed maybe a "Deprecation" section is appropriate.

But even still, I think to prevent confusion for others, like I had, I think having some note like my "Alias: .." in each section is helpful (at least for the rest of the 1.x branch) so people upgrading can see that they used to call parse() and can still do so, but should update to the parseCookie() name, or whatever).

If you have other thoughts on how best to document, I'm happy to update the PR... or you can do so. Either way, was just trying to help others not hit my confusion. :)


Parse an HTTP `Cookie` header string and return an [object](#cookie-object) of all cookie name-value pairs.
The `str` argument is the string representing a `Cookie` header value and `options` is an
optional object containing additional parsing options.
Expand All @@ -37,10 +39,12 @@ const cookieObject = cookie.parseCookie("foo=bar; equation=E%3Dmc%5E2");

### cookie.stringifyCookie(cookieObj, options)

Alias: `stringify()` (deprecated)

Stringifies a [cookie object](#cookie-object) into an HTTP `Cookie` header.

```js
const cookieHeader = cookie.stringify({ a: "foo", b: "bar" });
const cookieHeader = cookie.stringifyCookie({ a: "foo", b: "bar" });
// a=foo; b=bar
```

Expand Down