feat: add support session typing (#13320)

* feat: add support session typing

* Add type tests

* Fix test

* Remove unused import

Author: ascorbic

.changeset/slimy-bulldogs-sell.md

@@ -0,0 +1,38 @@
+---
+'astro': patch
+---
+
+Adds support for typing experimental session data
+
+You can add optional types to your session data by creating a `src/env.d.ts` file in your project that extends the global `App.SessionData` interface. For example:
+
+```ts
+declare namespace App {
+  interface SessionData {
+    user: {
+      id: string;
+      email: string;
+    };
+    lastLogin: Date;
+  }
+}
+```
+
+Any keys not defined in this interface will be treated as `any`.
+
+Then when you access `Astro.session` in your components, any defined keys will be typed correctly:
+
+```astro
+---
+const user = await Astro.session.get('user');
+//    ^? const: user: { id: string; email: string; } | undefined
+
+const something = await Astro.session.get('something');
+//    ^? const: something: any
+
+Astro.session.set('user', 1);
+//    ^? Argument of type 'number' is not assignable to parameter of type '{ id: string; email: string; }'.
+---
+```
+
+See [the experimental session docs](https://docs.astro.build/en/reference/experimental-flags/sessions/) for more information.

packages/astro/src/core/session.ts

@@ -105,7 +105,11 @@ export class AstroSession<TDriver extends SessionDriverName = any> {
 	/**
 	 * Gets a session value. Returns `undefined` if the session or value does not exist.
 	 */
-	async get<T = any>(key: string): Promise<T | undefined> {
+	async get<T = void, K extends string = string>(
+		key: K,
+	): Promise<
+		(T extends void ? (K extends keyof App.SessionData ? App.SessionData[K] : any) : T) | undefined
+	> {
 		return (await this.#ensureData()).get(key)?.data;
 	}
 
@@ -152,7 +156,15 @@ export class AstroSession<TDriver extends SessionDriverName = any> {
 	 * Sets a session value. The session is created if it does not exist.
 	 */
 
-	set<T = any>(key: string, value: T, { ttl }: { ttl?: number } = {}) {
+	set<T = void, K extends string = string>(
+		key: K,
+		value: T extends void
+			? K extends keyof App.SessionData
+				? App.SessionData[K]
+				: any
+			: NoInfer<T>,
+		{ ttl }: { ttl?: number } = {},
+	) {
 		if (!key) {
 			throw new AstroError({
 				...SessionStorageSaveError,

packages/astro/src/types/public/extendables.ts

@@ -10,6 +10,11 @@ declare global {
 		 * Used by middlewares to store information, that can be read by the user via the global `Astro.locals`
 		 */
 		export interface Locals {}
+
+		/**
+		 * Optionally type the data stored in the session
+		 */
+		export interface SessionData {}
 	}
 
 	namespace Astro {

packages/astro/test/types/session-data.ts

@@ -0,0 +1,53 @@
+import "./session-env";
+import { describe, it } from 'node:test';
+import { expectTypeOf } from 'expect-type';
+import type { AstroCookies, ResolvedSessionConfig } from '../../dist/types/public/index.js';
+import { AstroSession } from '../../dist/core/session.js';
+
+const defaultMockCookies = {
+	set: () => {},
+	delete: () => {},
+	get: () => 'astro cookie',
+};
+
+
+const defaultConfig: ResolvedSessionConfig<'memory'> = {
+	driver: 'memory',
+	cookie: 'test-session',
+	ttl: 60,
+	options: {},
+};
+
+// Helper to create a new session instance with mocked dependencies
+function createSession() {
+	return new AstroSession(defaultMockCookies as unknown as AstroCookies, defaultConfig);
+}
+
+describe('Session', () => {
+	it('Types session.get return values', () => {
+		const session = createSession();
+		
+		expectTypeOf(session.get('value')).resolves.toEqualTypeOf<string | undefined>();
+
+		expectTypeOf(session.get('cart')).resolves.toEqualTypeOf<Array<string> | undefined>();
+
+		expectTypeOf(session.get('unknown')).resolves.toEqualTypeOf<any>();
+		
+	});
+
+	it('Types session.set arguments', () => {
+		const session = createSession();
+
+		expectTypeOf(session.set('value', 'test')).toEqualTypeOf<void>();
+		expectTypeOf(session.set('cart', ['item1', 'item2'])).toEqualTypeOf<void>();
+		expectTypeOf(session.set('unknown', {})).toEqualTypeOf<void>();
+
+		// Testing invalid types
+		// @ts-expect-error This should fail because the value is not a string
+		expectTypeOf(session.set('value', 1)).toEqualTypeOf<void>();	
+		// @ts-expect-error This should fail because the value is not an array
+		expectTypeOf(session.set('cart', 'invalid')).toEqualTypeOf<void>();	
+	});
+
+});
+	

packages/astro/test/types/session-env.d.ts

@@ -0,0 +1,11 @@
+declare namespace App {
+	interface SessionData {
+		value: string;
+		cart: Array<string>;
+		key: { value: 'none' | 'expected' | 'unexpected' };
+		user: {
+			id: string;
+			email: string;
+		};
+	}
+}