@remix-run/cookie 0.4.1 → 0.5.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Michael Jackson
+Copyright (c) 2025 Shopify Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -57,7 +57,7 @@ let sessionCookie = createCookie('session', {
   secrets: ['secret1'],
 })
 
-console.log(sessionCookie.isSigned) // true
+console.log(sessionCookie.signed) // true
 
 let response = new Response('Hello, world!', {
   headers: {
@@ -86,7 +86,7 @@ let response = new Response('Hello, world!', {
 
 ### Custom Encoding
 
-By default, the library will use `encodeURIComponent` and `decodeURIComponent` to encode and decode the cookie value. This is suitable for most use cases, but you can provide your own functions to customize the encoding and decoding of the cookie value.
+By default, [`encodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) and [`decodeURIComponent`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent) are used to encode and decode the cookie value. This is suitable for most use cases, but you can provide your own functions to customize the encoding and decoding of the cookie value.
 
 ```tsx
 let sessionCookie = createCookie('session', {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { type Cookie, type CookieOptions, createCookie } from './lib/cookie.ts';
+export { type CookieOptions, Cookie, createCookie } from './lib/cookie.ts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA"}

package/dist/index.js

@@ -1 +1 @@
-export { createCookie } from "./lib/cookie.js";
+export { Cookie, createCookie } from "./lib/cookie.js";

package/dist/lib/cookie-signing.js

@@ -27,7 +27,7 @@ export async function unsign(cookie, secret) {
         return false;
     }
 }
-async function createKey(secret, usages) {
+function createKey(secret, usages) {
     return crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, usages);
 }
 function byteStringToArray(byteString) {

package/dist/lib/cookie.d.ts

@@ -1,4 +1,36 @@
 import { type CookieProperties } from '@remix-run/headers';
+/**
+ * Options for creating a cookie.
+ */
+export interface CookieOptions extends CookieProperties {
+    /**
+     * A function that decodes the cookie value. Decodes any URL-encoded sequences into their
+     * original characters.
+     *
+     * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
+     *
+     * @default decodeURIComponent
+     */
+    decode?: (value: string) => string;
+    /**
+     * A function that encodes the cookie value. Percent-encodes all characters that are not allowed
+     * in a cookie value.
+     *
+     * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
+     *
+     * @default encodeURIComponent
+     */
+    encode?: (value: string) => string;
+    /**
+     * An array of secrets that may be used to sign/unsign the value of a cookie.
+     *
+     * The array makes it easy to rotate secrets. New secrets should be added to
+     * the beginning of the array. `cookie.serialize()` will always use the first
+     * value in the array, but `cookie.parse()` may use any of them so that
+     * cookies that were signed with older secrets still work.
+     */
+    secrets?: string[];
+}
 type SameSiteValue = 'Strict' | 'Lax' | 'None';
 /**
  * Represents a HTTP cookie.
@@ -8,39 +40,48 @@ type SameSiteValue = 'Strict' | 'Lax' | 'None';
  * Also supports cryptographic signing of the cookie value to ensure it's not tampered with, and
  * secret rotation to easily rotate secrets without breaking existing cookies.
  */
-export interface Cookie {
+export declare class Cookie implements CookieProperties {
+    #private;
+    /**
+     * @param name The name of the cookie
+     * @param options Options for the cookie
+     */
+    constructor(name: string, options?: CookieOptions);
     /**
      * The domain of the cookie.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#domaindomain-value)
      */
-    readonly domain: string | undefined;
+    get domain(): string | undefined;
     /**
      * The expiration date of the cookie.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#expiresdate)
      */
-    readonly expires: Date | undefined;
+    get expires(): Date | undefined;
     /**
      * True if the cookie is HTTP-only.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#httponly)
+     *
+     * @default false
      */
-    readonly httpOnly: boolean;
+    get httpOnly(): boolean;
     /**
      * The maximum age of the cookie in seconds.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#max-agenumber)
      */
-    readonly maxAge: number | undefined;
+    get maxAge(): number | undefined;
     /**
      * The name of the cookie.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#cookie-namecookie-value)
      */
-    readonly name: string;
+    get name(): string;
     /**
      * Extracts the value of this cookie from a `Cookie` header value.
+     *
      * @param headerValue The `Cookie` header to parse
      * @returns The value of this cookie, or `null` if it's not present
      */
@@ -49,72 +90,53 @@ export interface Cookie {
      * True if the cookie is partitioned.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#partitioned)
+     *
+     * @default false
      */
-    readonly partitioned: boolean;
+    get partitioned(): boolean;
     /**
-     * The path of the cookie. Defaults to `/`.
+     * The path of the cookie.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value)
+     *
+     * @default '/'
      */
-    readonly path: string;
+    get path(): string;
     /**
-     * The `SameSite` attribute of the cookie. Defaults to `Lax`.
+     * The `SameSite` attribute of the cookie.
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
+     *
+     * @default 'Lax'
      */
-    readonly sameSite: SameSiteValue;
+    get sameSite(): SameSiteValue;
     /**
      * True if the cookie is secure (only sent over HTTPS).
      *
      * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure)
+     *
+     * @default false
      */
-    readonly secure: boolean;
+    get secure(): boolean;
     /**
      * Returns the value to use in a `Set-Cookie` header for this cookie.
+     *
      * @param value The value to serialize
-     * @param props (optional) Additional properties to use when serializing the cookie
-     * @returns The `Set-Cookie` header for this cookie
+     * @param props Additional properties to use when serializing the cookie
+     * @returns The `Set-Cookie` header value for this cookie
      */
     serialize(value: string, props?: CookieProperties): Promise<string>;
     /**
      * True if this cookie uses one or more secrets for verification.
      */
-    readonly signed: boolean;
-}
-export interface CookieOptions extends CookieProperties {
-    /**
-     * A function that decodes the cookie value.
-     *
-     * Defaults to `decodeURIComponent`, which decodes any URL-encoded sequences into their original
-     * characters.
-     *
-     * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
-     */
-    decode?: (value: string) => string;
-    /**
-     * A function that encodes the cookie value.
-     *
-     * Defaults to `encodeURIComponent`, which percent-encodes all characters that are not allowed
-     * in a cookie value.
-     *
-     * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
-     */
-    encode?: (value: string) => string;
-    /**
-     * An array of secrets that may be used to sign/unsign the value of a cookie.
-     *
-     * The array makes it easy to rotate secrets. New secrets should be added to
-     * the beginning of the array. `cookie.serialize()` will always use the first
-     * value in the array, but `cookie.parse()` may use any of them so that
-     * cookies that were signed with older secrets still work.
-     */
-    secrets?: string[];
+    get signed(): boolean;
 }
 /**
  * Creates a new cookie object.
+ *
  * @param name The name of the cookie
- * @param options (optional) Additional options for the cookie
- * @returns A cookie object
+ * @param options Options for the cookie
+ * @returns A new `Cookie` object
  */
 export declare function createCookie(name: string, options?: CookieOptions): Cookie;
 export {};

package/dist/lib/cookie.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/lib/cookie.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAA;AAI3B,KAAK,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;AAE9C;;;;;;;GAOG;AACH,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,IAAI,GAAG,SAAS,CAAA;IAClC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACzD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAA;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB;;;;;OAKG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAkF1E"}
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/lib/cookie.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAA;AAI3B;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,gBAAgB;IACrD;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,KAAK,aAAa,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAA;AAG9C;;;;;;;GAOG;AACH,qBAAa,MAAO,YAAW,gBAAgB;;IAc7C;;;OAGG;IACH,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,EAiChD;IAED;;;;OAIG;IACH,IAAI,MAAM,IAAI,MAAM,GAAG,SAAS,CAE/B;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,IAAI,GAAG,SAAS,CAE9B;IAED;;;;;;OAMG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;OAIG;IACH,IAAI,MAAM,IAAI,MAAM,GAAG,SAAS,CAE/B;IAED;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;OAKG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW9D;IAED;;;;;;OAMG;IACH,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED;;;;;;OAMG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,IAAI,QAAQ,IAAI,aAAa,CAE5B;IAED;;;;;;OAMG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;;;OAMG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBxE;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;CACF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAE1E"}

package/dist/lib/cookie.js

@@ -1,78 +1,189 @@
 import { Cookie as CookieHeader, SetCookie as SetCookieHeader, } from '@remix-run/headers';
 import { sign, unsign } from "./cookie-signing.js";
+/**
+ * Represents a HTTP cookie.
+ *
+ * Supports parsing and serializing the cookie to/from `Cookie` and `Set-Cookie` headers.
+ *
+ * Also supports cryptographic signing of the cookie value to ensure it's not tampered with, and
+ * secret rotation to easily rotate secrets without breaking existing cookies.
+ */
+export class Cookie {
+    #name;
+    #decode;
+    #encode;
+    #secrets;
+    #domain;
+    #expires;
+    #httpOnly;
+    #maxAge;
+    #partitioned;
+    #path;
+    #sameSite;
+    #secure;
+    /**
+     * @param name The name of the cookie
+     * @param options Options for the cookie
+     */
+    constructor(name, options) {
+        let { decode = decodeURIComponent, encode = encodeURIComponent, secrets = [], domain, expires, httpOnly, maxAge, path = '/', partitioned, secure, sameSite = 'Lax', } = options ?? {};
+        if (partitioned === true) {
+            // Partitioned cookies must be set with Secure
+            // See https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies
+            secure = true;
+        }
+        this.#name = name;
+        this.#decode = decode;
+        this.#encode = encode;
+        this.#secrets = secrets;
+        this.#domain = domain;
+        this.#expires = expires;
+        this.#httpOnly = httpOnly;
+        this.#maxAge = maxAge;
+        this.#partitioned = partitioned;
+        this.#path = path;
+        this.#sameSite = sameSite;
+        this.#secure = secure;
+    }
+    /**
+     * The domain of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#domaindomain-value)
+     */
+    get domain() {
+        return this.#domain;
+    }
+    /**
+     * The expiration date of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#expiresdate)
+     */
+    get expires() {
+        return this.#expires;
+    }
+    /**
+     * True if the cookie is HTTP-only.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#httponly)
+     *
+     * @default false
+     */
+    get httpOnly() {
+        return this.#httpOnly ?? false;
+    }
+    /**
+     * The maximum age of the cookie in seconds.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#max-agenumber)
+     */
+    get maxAge() {
+        return this.#maxAge;
+    }
+    /**
+     * The name of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#cookie-namecookie-value)
+     */
+    get name() {
+        return this.#name;
+    }
+    /**
+     * Extracts the value of this cookie from a `Cookie` header value.
+     *
+     * @param headerValue The `Cookie` header to parse
+     * @returns The value of this cookie, or `null` if it's not present
+     */
+    async parse(headerValue) {
+        if (!headerValue)
+            return null;
+        let header = new CookieHeader(headerValue);
+        if (!header.has(this.#name))
+            return null;
+        let value = header.get(this.#name);
+        if (value === '')
+            return '';
+        let decoded = await decodeCookieValue(value, this.#secrets, this.#decode);
+        return decoded;
+    }
+    /**
+     * True if the cookie is partitioned.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#partitioned)
+     *
+     * @default false
+     */
+    get partitioned() {
+        return this.#partitioned ?? false;
+    }
+    /**
+     * The path of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value)
+     *
+     * @default '/'
+     */
+    get path() {
+        return this.#path;
+    }
+    /**
+     * The `SameSite` attribute of the cookie.
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
+     *
+     * @default 'Lax'
+     */
+    get sameSite() {
+        return this.#sameSite;
+    }
+    /**
+     * True if the cookie is secure (only sent over HTTPS).
+     *
+     * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure)
+     *
+     * @default false
+     */
+    get secure() {
+        return this.#secure ?? false;
+    }
+    /**
+     * Returns the value to use in a `Set-Cookie` header for this cookie.
+     *
+     * @param value The value to serialize
+     * @param props Additional properties to use when serializing the cookie
+     * @returns The `Set-Cookie` header value for this cookie
+     */
+    async serialize(value, props) {
+        let header = new SetCookieHeader({
+            name: this.#name,
+            value: value === '' ? '' : await encodeCookieValue(value, this.#secrets, this.#encode),
+            domain: this.#domain,
+            expires: this.#expires,
+            httpOnly: this.#httpOnly,
+            maxAge: this.#maxAge,
+            partitioned: this.#partitioned,
+            path: this.#path,
+            sameSite: this.#sameSite,
+            secure: this.#secure,
+            ...props,
+        });
+        return header.toString();
+    }
+    /**
+     * True if this cookie uses one or more secrets for verification.
+     */
+    get signed() {
+        return this.#secrets.length > 0;
+    }
+}
 /**
  * Creates a new cookie object.
+ *
  * @param name The name of the cookie
- * @param options (optional) Additional options for the cookie
- * @returns A cookie object
+ * @param options Options for the cookie
+ * @returns A new `Cookie` object
  */
 export function createCookie(name, options) {
-    let { decode = decodeURIComponent, encode = encodeURIComponent, secrets = [], domain, expires, httpOnly, maxAge, path = '/', partitioned, secure, sameSite = 'Lax', } = options ?? {};
-    if (partitioned === true) {
-        // Partitioned cookies must be set with Secure
-        // See https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies
-        secure = true;
-    }
-    return {
-        get domain() {
-            return domain;
-        },
-        get expires() {
-            return expires;
-        },
-        get httpOnly() {
-            return httpOnly ?? false;
-        },
-        get maxAge() {
-            return maxAge;
-        },
-        get name() {
-            return name;
-        },
-        async parse(headerValue) {
-            if (!headerValue)
-                return null;
-            let header = new CookieHeader(headerValue);
-            if (!header.has(name))
-                return null;
-            let value = header.get(name);
-            if (value === '')
-                return '';
-            let decoded = await decodeCookieValue(value, secrets, decode);
-            return decoded;
-        },
-        get partitioned() {
-            return partitioned ?? false;
-        },
-        get path() {
-            return path;
-        },
-        get sameSite() {
-            return sameSite;
-        },
-        get secure() {
-            return secure ?? false;
-        },
-        async serialize(value, props) {
-            let header = new SetCookieHeader({
-                name: name,
-                value: value === '' ? '' : await encodeCookieValue(value, secrets, encode),
-                domain,
-                expires,
-                httpOnly,
-                maxAge,
-                partitioned,
-                path,
-                sameSite,
-                secure,
-                ...props,
-            });
-            return header.toString();
-        },
-        get signed() {
-            return secrets.length > 0;
-        },
-    };
+    return new Cookie(name, options);
 }
 async function decodeCookieValue(value, secrets, decode) {
     if (secrets.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remix-run/cookie",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "A toolkit for working with cookies in JavaScript",
   "author": "Michael Jackson <mjijackson@gmail.com>",
   "license": "MIT",
@@ -26,10 +26,11 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@types/node": "^24.6.0"
+    "@types/node": "^24.6.0",
+    "@typescript/native-preview": "7.0.0-dev.20251125.1"
   },
-  "peerDependencies": {
-    "@remix-run/headers": "^0.17.0"
+  "dependencies": {
+    "@remix-run/headers": "^0.19.0"
   },
   "keywords": [
     "http",
@@ -39,9 +40,9 @@
     "set-cookie"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsgo -p tsconfig.build.json",
     "clean": "git clean -fdX",
-    "test": "node --disable-warning=ExperimentalWarning --test './src/**/*.test.ts'",
-    "typecheck": "tsc --noEmit"
+    "test": "node --disable-warning=ExperimentalWarning --test",
+    "typecheck": "tsgo --noEmit"
   }
 }

package/src/index.ts

@@ -1 +1 @@
-export { type Cookie, type CookieOptions, createCookie } from './lib/cookie.ts'
+export { type CookieOptions, Cookie, createCookie } from './lib/cookie.ts'

package/src/lib/cookie-signing.ts

@@ -34,7 +34,7 @@ export async function unsign(cookie: string, secret: string): Promise<string | f
   }
 }
 
-async function createKey(secret: string, usages: CryptoKey['usages']): Promise<CryptoKey> {
+function createKey(secret: string, usages: CryptoKey['usages']): Promise<CryptoKey> {
   return crypto.subtle.importKey(
     'raw',
     encoder.encode(secret),

package/src/lib/cookie.ts

@@ -6,7 +6,41 @@ import {
 
 import { sign, unsign } from './cookie-signing.ts'
 
+/**
+ * Options for creating a cookie.
+ */
+export interface CookieOptions extends CookieProperties {
+  /**
+   * A function that decodes the cookie value. Decodes any URL-encoded sequences into their
+   * original characters.
+   *
+   * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
+   *
+   * @default decodeURIComponent
+   */
+  decode?: (value: string) => string
+  /**
+   * A function that encodes the cookie value. Percent-encodes all characters that are not allowed
+   * in a cookie value.
+   *
+   * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
+   *
+   * @default encodeURIComponent
+   */
+  encode?: (value: string) => string
+  /**
+   * An array of secrets that may be used to sign/unsign the value of a cookie.
+   *
+   * The array makes it easy to rotate secrets. New secrets should be added to
+   * the beginning of the array. `cookie.serialize()` will always use the first
+   * value in the array, but `cookie.parse()` may use any of them so that
+   * cookies that were signed with older secrets still work.
+   */
+  secrets?: string[]
+}
+
 type SameSiteValue = 'Strict' | 'Lax' | 'None'
+type Coder = (value: string) => string
 
 /**
  * Represents a HTTP cookie.
@@ -16,202 +50,213 @@ type SameSiteValue = 'Strict' | 'Lax' | 'None'
  * Also supports cryptographic signing of the cookie value to ensure it's not tampered with, and
  * secret rotation to easily rotate secrets without breaking existing cookies.
  */
-export interface Cookie {
+export class Cookie implements CookieProperties {
+  #name: string
+  #decode: Coder
+  #encode: Coder
+  #secrets: string[]
+  #domain: string | undefined
+  #expires: Date | undefined
+  #httpOnly: boolean | undefined
+  #maxAge: number | undefined
+  #partitioned: boolean | undefined
+  #path: string
+  #sameSite: SameSiteValue
+  #secure: boolean | undefined
+
+  /**
+   * @param name The name of the cookie
+   * @param options Options for the cookie
+   */
+  constructor(name: string, options?: CookieOptions) {
+    let {
+      decode = decodeURIComponent,
+      encode = encodeURIComponent,
+      secrets = [],
+      domain,
+      expires,
+      httpOnly,
+      maxAge,
+      path = '/',
+      partitioned,
+      secure,
+      sameSite = 'Lax',
+    } = options ?? {}
+
+    if (partitioned === true) {
+      // Partitioned cookies must be set with Secure
+      // See https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies
+      secure = true
+    }
+
+    this.#name = name
+    this.#decode = decode
+    this.#encode = encode
+    this.#secrets = secrets
+    this.#domain = domain
+    this.#expires = expires
+    this.#httpOnly = httpOnly
+    this.#maxAge = maxAge
+    this.#partitioned = partitioned
+    this.#path = path
+    this.#sameSite = sameSite
+    this.#secure = secure
+  }
+
   /**
    * The domain of the cookie.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#domaindomain-value)
    */
-  readonly domain: string | undefined
+  get domain(): string | undefined {
+    return this.#domain
+  }
+
   /**
    * The expiration date of the cookie.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#expiresdate)
    */
-  readonly expires: Date | undefined
+  get expires(): Date | undefined {
+    return this.#expires
+  }
+
   /**
    * True if the cookie is HTTP-only.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#httponly)
+   *
+   * @default false
    */
-  readonly httpOnly: boolean
+  get httpOnly(): boolean {
+    return this.#httpOnly ?? false
+  }
+
   /**
    * The maximum age of the cookie in seconds.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#max-agenumber)
    */
-  readonly maxAge: number | undefined
+  get maxAge(): number | undefined {
+    return this.#maxAge
+  }
+
   /**
    * The name of the cookie.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Set-Cookie#cookie-namecookie-value)
    */
-  readonly name: string
+  get name(): string {
+    return this.#name
+  }
+
   /**
    * Extracts the value of this cookie from a `Cookie` header value.
+   *
    * @param headerValue The `Cookie` header to parse
    * @returns The value of this cookie, or `null` if it's not present
    */
-  parse(headerValue: string | null): Promise<string | null>
+  async parse(headerValue: string | null): Promise<string | null> {
+    if (!headerValue) return null
+
+    let header = new CookieHeader(headerValue)
+    if (!header.has(this.#name)) return null
+
+    let value = header.get(this.#name)!
+    if (value === '') return ''
+
+    let decoded = await decodeCookieValue(value, this.#secrets, this.#decode)
+    return decoded
+  }
+
   /**
    * True if the cookie is partitioned.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#partitioned)
+   *
+   * @default false
    */
-  readonly partitioned: boolean
+  get partitioned(): boolean {
+    return this.#partitioned ?? false
+  }
+
   /**
-   * The path of the cookie. Defaults to `/`.
+   * The path of the cookie.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#pathpath-value)
+   *
+   * @default '/'
    */
-  readonly path: string
+  get path(): string {
+    return this.#path
+  }
+
   /**
-   * The `SameSite` attribute of the cookie. Defaults to `Lax`.
+   * The `SameSite` attribute of the cookie.
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/Web/HTTP/Headers/Set-Cookie#samesitesamesite-value)
+   *
+   * @default 'Lax'
    */
-  readonly sameSite: SameSiteValue
+  get sameSite(): SameSiteValue {
+    return this.#sameSite
+  }
+
   /**
    * True if the cookie is secure (only sent over HTTPS).
    *
    * [MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#secure)
+   *
+   * @default false
    */
-  readonly secure: boolean
+  get secure(): boolean {
+    return this.#secure ?? false
+  }
+
   /**
    * Returns the value to use in a `Set-Cookie` header for this cookie.
+   *
    * @param value The value to serialize
-   * @param props (optional) Additional properties to use when serializing the cookie
-   * @returns The `Set-Cookie` header for this cookie
-   */
-  serialize(value: string, props?: CookieProperties): Promise<string>
-  /**
-   * True if this cookie uses one or more secrets for verification.
+   * @param props Additional properties to use when serializing the cookie
+   * @returns The `Set-Cookie` header value for this cookie
    */
-  readonly signed: boolean
-}
+  async serialize(value: string, props?: CookieProperties): Promise<string> {
+    let header = new SetCookieHeader({
+      name: this.#name,
+      value: value === '' ? '' : await encodeCookieValue(value, this.#secrets, this.#encode),
+      domain: this.#domain,
+      expires: this.#expires,
+      httpOnly: this.#httpOnly,
+      maxAge: this.#maxAge,
+      partitioned: this.#partitioned,
+      path: this.#path,
+      sameSite: this.#sameSite,
+      secure: this.#secure,
+      ...props,
+    })
+
+    return header.toString()
+  }
 
-export interface CookieOptions extends CookieProperties {
-  /**
-   * A function that decodes the cookie value.
-   *
-   * Defaults to `decodeURIComponent`, which decodes any URL-encoded sequences into their original
-   * characters.
-   *
-   * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
-   */
-  decode?: (value: string) => string
-  /**
-   * A function that encodes the cookie value.
-   *
-   * Defaults to `encodeURIComponent`, which percent-encodes all characters that are not allowed
-   * in a cookie value.
-   *
-   * See [RFC 6265](https://tools.ietf.org/html/rfc6265#section-4.1.1) for more details.
-   */
-  encode?: (value: string) => string
   /**
-   * An array of secrets that may be used to sign/unsign the value of a cookie.
-   *
-   * The array makes it easy to rotate secrets. New secrets should be added to
-   * the beginning of the array. `cookie.serialize()` will always use the first
-   * value in the array, but `cookie.parse()` may use any of them so that
-   * cookies that were signed with older secrets still work.
+   * True if this cookie uses one or more secrets for verification.
    */
-  secrets?: string[]
+  get signed(): boolean {
+    return this.#secrets.length > 0
+  }
 }
 
 /**
  * Creates a new cookie object.
+ *
  * @param name The name of the cookie
- * @param options (optional) Additional options for the cookie
- * @returns A cookie object
+ * @param options Options for the cookie
+ * @returns A new `Cookie` object
  */
 export function createCookie(name: string, options?: CookieOptions): Cookie {
-  let {
-    decode = decodeURIComponent,
-    encode = encodeURIComponent,
-    secrets = [],
-    domain,
-    expires,
-    httpOnly,
-    maxAge,
-    path = '/',
-    partitioned,
-    secure,
-    sameSite = 'Lax',
-  } = options ?? {}
-
-  if (partitioned === true) {
-    // Partitioned cookies must be set with Secure
-    // See https://developer.mozilla.org/en-US/docs/Web/Privacy/Guides/Privacy_sandbox/Partitioned_cookies
-    secure = true
-  }
-
-  return {
-    get domain() {
-      return domain
-    },
-    get expires() {
-      return expires
-    },
-    get httpOnly() {
-      return httpOnly ?? false
-    },
-    get maxAge() {
-      return maxAge
-    },
-    get name() {
-      return name
-    },
-    async parse(headerValue: string | null): Promise<string | null> {
-      if (!headerValue) return null
-
-      let header = new CookieHeader(headerValue)
-      if (!header.has(name)) return null
-
-      let value = header.get(name)!
-      if (value === '') return ''
-
-      let decoded = await decodeCookieValue(value, secrets, decode)
-      return decoded
-    },
-    get partitioned() {
-      return partitioned ?? false
-    },
-    get path() {
-      return path
-    },
-    get sameSite() {
-      return sameSite
-    },
-    get secure() {
-      return secure ?? false
-    },
-    async serialize(value: string, props?: CookieProperties): Promise<string> {
-      let header = new SetCookieHeader({
-        name: name,
-        value: value === '' ? '' : await encodeCookieValue(value, secrets, encode),
-        domain,
-        expires,
-        httpOnly,
-        maxAge,
-        partitioned,
-        path,
-        sameSite,
-        secure,
-        ...props,
-      })
-
-      return header.toString()
-    },
-    get signed() {
-      return secrets.length > 0
-    },
-  }
+  return new Cookie(name, options)
 }
 
-type Coder = (value: string) => string
-
 async function decodeCookieValue(
   value: string,
   secrets: string[],