iron-session 9.0.0-beta.1 → 9.0.1

package/MIGRATION.md

@@ -2,15 +2,19 @@
 
 ## v8 to v9
 
+```sh
+pnpm add iron-session
+```
+
 Most apps need two changes: Node 22 and one line if you store a `Date` in the
 session. Everything else below is either a type error TypeScript will point at,
 or a bug fix you want.
 
 ### Requirements
 
-- **Node 22.12 or later.** Node 20 reached end of life in April 2026.
+- **Node 22.13 or later.** Node 20 reached end of life in April 2026.
 - **The package is ESM-only.** There is no CommonJS build. `require()` still
-  works on Node 22.12+, which supports `require()` of an ES module, so most CJS
+  works on Node 22.13+, which supports `require()` of an ES module, so most CJS
   code keeps working. If you are bundling for an older target, keep v8.
 
 ### Do this

package/README.md

@@ -14,6 +14,7 @@ The session data is stored in signed and encrypted cookies which are decoded by
 
 - [Table of Contents](#table-of-contents)
 - [Installation](#installation)
+- [Upgrading to v9](#upgrading-to-v9)
 - [Usage](#usage)
 - [Examples](#examples)
 - [Runtimes](#runtimes)
@@ -25,6 +26,7 @@ The session data is stored in signed and encrypted cookies which are decoded by
 - [API](#api)
   - [`getIronSession<T>(req, res, sessionOptions): Promise<IronSession<T>>`](#getironsessiontreq-res-sessionoptions-promiseironsessiont)
   - [`getIronSession<T>(cookieStore, sessionOptions): Promise<IronSession<T>>`](#getironsessiontcookiestore-sessionoptions-promiseironsessiont)
+  - [`nodeCookies`, `webCookies`, `nextProxyCookies`](#nodecookiesreq-res-webcookiesrequest-responseorheaders-nextproxycookiesrequest-response)
   - [`session.save(): Promise<void>`](#sessionsave-promisevoid)
   - [`session.destroy(): void`](#sessiondestroy-void)
   - [`session.updateConfig(sessionOptions: SessionOptions): void`](#sessionupdateconfigsessionoptions-sessionoptions-void)
@@ -44,6 +46,51 @@ The session data is stored in signed and encrypted cookies which are decoded by
 pnpm add iron-session
 ```
 
+v9 needs **Node 22.13 or later** and is **ESM-only**. `require()` still works on
+Node 22.13+, which supports `require()` of an ES module. If you are stuck on an
+older Node, stay on v8: `pnpm add iron-session@8`.
+
+## Upgrading to v9
+
+Most apps change two things. Both are things v8 got wrong quietly.
+
+**1. Store timestamps, not `Date` objects.**
+
+```diff
+- session.lastSeen = new Date();
++ session.lastSeen = Date.now();
+```
+
+v8 turned a `Date` into a string when sealing, so the type you wrote was not the
+type you read back. v9 throws and names the field.
+
+**2. Handle a session that does not exist yet.**
+
+```diff
+- const userId = session.user.id;
++ const userId = session.user?.id;
+```
+
+Reads are typed as `Partial<T>` now. A first visit, an expired cookie and a
+`destroy()` all leave you an empty object, so the old type let this compile and
+then throw at runtime.
+
+Nothing else is required. `getIronSession(req, res, options)` and
+`getIronSession(await cookies(), options)` both still work, v9 reads v8 cookies
+and v8 reads v9 cookies, so you can roll a deploy back without signing everyone
+out. If you had `as any` on `await cookies()`, delete it.
+
+Worth adopting while you are here:
+
+- [`nextProxyCookies`](#runtimes) if you ever tried to save a session in Next.js
+  middleware and it did not stick.
+- [`onUnsealError`](#watching-for-unreadable-cookies) to see why cookies get
+  rejected instead of guessing.
+- [`chunk: true`](#session-size) if your session outgrew one cookie.
+
+The full guide, including the removed APIs and the security fix that signs pre-v8
+cookies out once, is in [MIGRATION.md](./MIGRATION.md).
+
 ## Usage
 
 _We have extensive examples here too: https://get-iron-session.vercel.app/._
@@ -258,7 +305,21 @@ type SessionData = {
   // Your data
 };
 
-const session = await getIronSession<SessionData>(cookies(), sessionOptions);
+const session = await getIronSession<SessionData>(await cookies(), sessionOptions);
+```
+
+Reads are typed as `Partial<T>`, because a session that does not exist yet is an
+empty object. Use optional chaining, or narrow once and pass the result around.
+
+### `nodeCookies(req, res)`, `webCookies(request, responseOrHeaders)`, `nextProxyCookies(request, response)`
+
+Cookie jars you pass in place of `req, res`, for when the shorthand cannot tell
+what your framework wants. See [Runtimes](#runtimes).
+
+```ts
+import { getIronSession, nextProxyCookies } from "iron-session";
+
+const session = await getIronSession(nextProxyCookies(request, response), sessionOptions);
 ```
 
 ### `session.save(): Promise<void>`
@@ -283,6 +344,8 @@ session.destroy();
 
 Updates the configuration of the session with new session options. You still need to call save() if you want them to be applied.
 
+It rebuilds the whole configuration, including the password, so this is what you use to rotate a password mid-request. In v8 a new password passed here was ignored.
+
 ### `sealData(data: unknown, { password, ttl }): Promise<string>`
 
 This is the underlying method and seal mechanism that powers `iron-session`. You can use it to seal any `data` you want and pass it around. One usecase are magic links: you generate a seal that contains a user id to login and send it to a route on your website (like `/magic-login`). Once received, you can safely decode the seal with `unsealData` and log the user in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iron-session",
-  "version": "9.0.0-beta.1",
+  "version": "9.0.1",
   "description": "Secure, stateless, and cookie-based session library for JavaScript",
   "keywords": [
     "cookie",
@@ -15,7 +15,10 @@
   "bugs": "https://github.com/vvo/iron-session/issues",
   "license": "MIT",
   "author": "Vincent Voyer <vincent@codeagain.com> (https://github.com/vvo)",
-  "repository": "github:vvo/iron-session",
+  "repository": {
+    "type": "git",
+    "url": "github:vvo/iron-session"
+  },
   "funding": [
     "https://github.com/sponsors/vvo",
     "https://github.com/sponsors/brc-dd"
@@ -35,20 +38,6 @@
     "provenance": true,
     "registry": "https://registry.npmjs.org"
   },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "pnpm build && concurrently \"pnpm build --watch\" \"pnpm --filter=next-example dev\" ",
-    "format": "oxfmt .",
-    "format:check": "oxfmt --check .",
-    "lint": "oxlint --type-aware && tsc --noEmit && pnpm build && publint && attw --pack . --ignore-rules cjs-resolves-to-esm && pnpm lint:types",
-    "lint:types": "tsdown && tsc --noEmit -p type-tests/tsconfig.json",
-    "pretest": "node -e \"require('node:fs').mkdirSync('coverage',{recursive:true})\"",
-    "size": "size-limit",
-    "start": "pnpm --filter=next-example start",
-    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --import tsx src/*.test.ts",
-    "test:e2e": "playwright test",
-    "test:watch": "node --import tsx --test --watch src/*.test.ts"
-  },
   "dependencies": {
     "cookie": "^2.0.1",
     "iron-webcrypto": "^2.0.0"
@@ -59,7 +48,7 @@
     "@size-limit/preset-small-lib": "13.0.3",
     "@types/node": "26.4.0",
     "@types/react": "19.2.7",
-    "concurrently": "9.2.1",
+    "concurrently": "10.0.5",
     "next": "16.3.3",
     "oxfmt": "0.65.0",
     "oxlint": "1.80.0",
@@ -95,5 +84,18 @@
   "engines": {
     "node": ">=22.13.0"
   },
-  "packageManager": "pnpm@11.24.0"
-}
+  "scripts": {
+    "build": "tsdown",
+    "dev": "pnpm build && concurrently \"pnpm build --watch\" \"pnpm --filter=next-example dev\" ",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "lint": "oxlint --type-aware && tsc --noEmit && pnpm build && publint && attw --pack . --ignore-rules cjs-resolves-to-esm && pnpm lint:types",
+    "lint:types": "tsdown && tsc --noEmit -p type-tests/tsconfig.json",
+    "pretest": "node -e \"require('node:fs').mkdirSync('coverage',{recursive:true})\"",
+    "size": "size-limit",
+    "start": "pnpm --filter=next-example start",
+    "test": "node --test --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --import tsx src/*.test.ts",
+    "test:e2e": "playwright test",
+    "test:watch": "node --import tsx --test --watch src/*.test.ts"
+  }
+}