feat(TypeScript): Add session to handler req + example (#356)

Co-authored-by: Vandivier <john@afterecon.com>

Author: vvo

.eslintignore

@@ -1,3 +1,4 @@
 examples/next.js/
+examples/next-typescript/
 examples/express/node_modules
 dist/

.gitignore

@@ -13,3 +13,4 @@ yarn-debug.log*
 yarn-error.log*
 
 .now
+.next

README.md

@@ -27,6 +27,7 @@ _Table of contents:_
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [TypeScript usage](#typescript-usage)
 - [Examples](#examples)
   - [Handle password rotation/update the password](#handle-password-rotationupdate-the-password)
   - [Express / Connect middleware: `ironSession`](#express--connect-middleware-ironsession)
@@ -58,15 +59,15 @@ yarn add next-iron-session
 
 ## Usage
 
-You can find real-world examples (Next.js, Express) in the [examples folder](./examples/).
+You can find full featured examples (Next.js, Express) in the [examples folder](./examples/).
 
 The password is a private key you must pass at runtime, it has to be at least 32 characters long. Use https://1password.com/password-generator/ to generate strong passwords.
 
 ⚠️ Always store passwords in secret environment variables on your platform.
 
-**pages/api/login.js**:
-
 ```js
+// pages/api/login.js
+
 import { withIronSession } from "next-iron-session";
 
 async function handler(req, res) {
@@ -89,9 +90,9 @@ export default withIronSession(handler, {
 });
 ```
 
-**pages/api/user.js**:
-
 ```js
+// pages/api/user.js
+
 import { withIronSession } from "next-iron-session";
 
 function handler(req, res, session) {
@@ -109,9 +110,9 @@ export default withIronSession(handler, {
 });
 ```
 
-**pages/api/logout.js**:
-
 ```js
+// pages/api/logout.js
+
 import { withIronSession } from "next-iron-session";
 
 function handler(req, res, session) {
@@ -135,6 +136,39 @@ export default withIronSession(handler, {
 - a wrong password was used
 - we can't find back the password id in the current list
 
+## TypeScript usage
+
+Also see the [full TypeScript example](./examples/next-typescript).
+
+```ts
+// pages/api/login.ts
+import { NextApiRequest, NextApiResponse } from "next";
+import { withIronSession, Session } from "next-iron-session";
+type NextIronRequest = NextApiRequest & { session: Session };
+
+async function handler(
+  req: NextIronRequest,
+  res: NextApiResponse,
+): Promise<void> {
+  // get user from database then:
+  req.session.set("user", {
+    id: 230,
+    admin: true,
+  });
+  await req.session.save();
+  res.send("Logged in");
+}
+
+export default withIronSession(handler, {
+  password: "complex_password_at_least_32_characters_long",
+  cookieName: "myapp_cookiename",
+  // if your localhost is served on http:// then disable the secure flag
+  cookieOptions: {
+    secure: process.env.NODE_ENV === "production",
+  },
+});
+```
+
 ## Examples
 
 ### Handle password rotation/update the password

examples/express/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "express",
+  "name": "next-iron-session-express-example",
   "version": "0.0.0",
   "private": true,
   "scripts": {

examples/next-typescript/.env.development

@@ -0,0 +1,6 @@
+# ⚠️ The SECRET_COOKIE_PASSWORD should never be inside your repository directly, it's here only to ease
+# the example deployment
+# For local development, you should store it inside a `.env.local` gitignored file
+# See https://nextjs.org/docs/basic-features/environment-variables#loading-environment-variables
+
+SECRET_COOKIE_PASSWORD=2gyZ3GDw3LHZQKDhPmPDL3sjREVRXPr8

examples/next-typescript/.env.production

@@ -0,0 +1,6 @@
+# ⚠️ The SECRET_COOKIE_PASSWORD should never be inside your repository directly, it's here only to ease
+# the example deployment
+# For production you should use https://vercel.com/blog/environment-variables-ui if you're hosted on Vercel or
+# any other secret environment variable mean
+
+SECRET_COOKIE_PASSWORD=2gyZ3GDw3LHZQKDhPmPDL3sjREVRXPr8