@adonisjs/session 7.7.0 → 8.0.0-next.1

package/build/src/stores/memory.d.ts

@@ -6,35 +6,52 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import type { SessionData, SessionStoreWithTaggingContract, TaggedSession } from '../types.js';
+import type { SessionData, SessionStoreContract } from '../types.ts';
 /**
  * Memory store is meant to be used for writing tests.
+ * All session data is stored in memory and will be lost when the process restarts.
+ *
+ * @example
+ * const memoryStore = new MemoryStore()
+ * memoryStore.write('sess_abc123', { userId: 123 })
  */
-export declare class MemoryStore implements SessionStoreWithTaggingContract {
-    static sessions: Map<string, SessionData>;
+export declare class MemoryStore implements SessionStoreContract {
     /**
-     * Maps session IDs to user IDs (for tagging)
+     * Static map to store all session data in memory
      */
-    static tags: Map<string, string>;
+    static sessions: Map<string, SessionData>;
     /**
-     * Read session id value from the memory
+     * Reads session value from memory
+     *
+     * @param sessionId - Session identifier
+     *
+     * @example
+     * const data = store.read('sess_abc123')
      */
     read(sessionId: string): SessionData | null;
     /**
-     * Save in memory value for a given session id
+     * Saves session value in memory for a given session id
+     *
+     * @param sessionId - Session identifier
+     * @param values - Session data to store
+     *
+     * @example
+     * store.write('sess_abc123', { userId: 123, theme: 'dark' })
      */
     write(sessionId: string, values: SessionData): void;
     /**
-     * Cleanup for a single session
+     * Removes a single session from memory
+     *
+     * @param sessionId - Session identifier to remove
+     *
+     * @example
+     * store.destroy('sess_abc123')
      */
     destroy(sessionId: string): void;
-    touch(): void;
-    /**
-     * Tag a session with a user ID
-     */
-    tag(sessionId: string, userId: string): Promise<void>;
     /**
-     * Get all sessions for a given user ID (tag)
+     * No-op for memory store as there's no expiry mechanism
+     *
+     * @param sessionId - Session identifier (unused)
      */
-    tagged(userId: string): Promise<TaggedSession[]>;
+    touch(_?: string): void;
 }

package/build/src/stores/redis.d.ts

@@ -7,35 +7,58 @@
  * file that was distributed with this source code.
  */
 import type { Connection } from '@adonisjs/redis/types';
-import type { SessionStoreWithTaggingContract, SessionData, TaggedSession } from '../types.js';
+import type { SessionStoreContract, SessionData } from '../types.ts';
 /**
- * Redis store to read/write session to Redis
+ * Redis store to read/write session data to Redis server.
+ * Provides fast, scalable session storage with automatic expiry.
+ *
+ * @example
+ * const redisStore = new RedisStore(redisConnection, '2 hours')
  */
-export declare class RedisStore implements SessionStoreWithTaggingContract {
+export declare class RedisStore implements SessionStoreContract {
     #private;
+    /**
+     * Creates a new Redis store instance
+     *
+     * @param connection - Redis connection instance
+     * @param age - Session age in seconds or time expression (e.g. '2 hours')
+     */
     constructor(connection: Connection, age: string | number);
     /**
-     * Returns session data
+     * Reads session data from Redis
+     *
+     * @param sessionId - Session identifier
+     *
+     * @example
+     * const data = await store.read('sess_abc123')
      */
     read(sessionId: string): Promise<SessionData | null>;
     /**
-     * Write session values to redis
+     * Writes session values to Redis with expiry
+     *
+     * @param sessionId - Session identifier
+     * @param values - Session data to store
+     *
+     * @example
+     * await store.write('sess_abc123', { userId: 123 })
      */
-    write(sessionId: string, values: Record<string, any>): Promise<void>;
+    write(sessionId: string, values: Object): Promise<void>;
     /**
-     * Cleanup session by removing it
+     * Removes session data from Redis
+     *
+     * @param sessionId - Session identifier to remove
+     *
+     * @example
+     * await store.destroy('sess_abc123')
      */
     destroy(sessionId: string): Promise<void>;
     /**
-     * Updates the value expiry
+     * Updates the session expiry time in Redis
+     *
+     * @param sessionId - Session identifier
+     *
+     * @example
+     * await store.touch('sess_abc123')
      */
     touch(sessionId: string): Promise<void>;
-    /**
-     * Tag a session with a user ID
-     */
-    tag(sessionId: string, userId: string): Promise<void>;
-    /**
-     * Get all sessions for a given user ID (tag)
-     */
-    tagged(userId: string): Promise<TaggedSession[]>;
 }

package/build/src/types.d.ts

@@ -1,143 +1,212 @@
-import { HttpContext } from '@adonisjs/core/http';
-import { RedisConnections } from '@adonisjs/redis/types';
+import { type HttpContext } from '@adonisjs/core/http';
+import { type RedisConnections } from '@adonisjs/redis/types';
 import type { CookieOptions } from '@adonisjs/core/types/http';
 import type { DynamoDBClient, DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
 /**
- * The values allowed by the `session.put` method
+ * Union type of all values that can be stored in session data.
+ * These types are JSON serializable and safe for session storage.
+ *
+ * @example
+ * // All valid session values
+ * const stringVal: AllowedSessionValues = 'hello'
+ * const numberVal: AllowedSessionValues = 42
+ * const boolVal: AllowedSessionValues = true
+ * const objectVal: AllowedSessionValues = { key: 'value' }
+ * const dateVal: AllowedSessionValues = new Date()
+ * const arrayVal: AllowedSessionValues = [1, 2, 3]
  */
 export type AllowedSessionValues = string | boolean | number | object | Date | Array<any>;
-export type SessionData = Record<string, AllowedSessionValues>;
 /**
- * Represents a tagged session with its ID and data
+ * Shape of session data as a record of key-value pairs.
+ * The session data must be JSON serializable for persistence.
+ *
+ * @example
+ * const sessionData: SessionData = {
+ *   userId: 123,
+ *   username: 'john_doe',
+ *   preferences: { theme: 'dark', language: 'en' },
+ *   loginAt: new Date(),
+ *   roles: ['user', 'editor']
+ * }
  */
-export interface TaggedSession {
-    id: string;
-    data: SessionData;
-}
+export type SessionData = Record<string, AllowedSessionValues>;
 /**
- * Session stores must implement the session store contract.
+ * Contract interface that every session store implementation must follow.
+ * Defines the basic CRUD operations for session data persistence.
+ *
+ * @example
+ * class CustomStore implements SessionStoreContract {
+ *   async read(sessionId: string) {
+ *     // Read session data from your storage
+ *     return await this.storage.get(sessionId)
+ *   }
+ *
+ *   async write(sessionId: string, data: SessionData) {
+ *     // Write session data to your storage
+ *     await this.storage.set(sessionId, data)
+ *   }
+ *
+ *   async destroy(sessionId: string) {
+ *     // Remove session data from storage
+ *     await this.storage.delete(sessionId)
+ *   }
+ *
+ *   async touch(sessionId: string) {
+ *     // Update expiry/last accessed time
+ *     await this.storage.touch(sessionId)
+ *   }
+ * }
  */
 export interface SessionStoreContract {
     /**
-     * The read method is used to read the data from the persistence
-     * store and return it back as an object
+     * Reads session data for a given session ID from the persistence store
+     *
+     * @param sessionId - Unique identifier for the session
      */
     read(sessionId: string): Promise<SessionData | null> | SessionData | null;
     /**
-     * The write method is used to write the session data into the
-     * persistence store.
+     * Writes session data for a given session ID to the persistence store
+     *
+     * @param sessionId - Unique identifier for the session
+     * @param data - Session data to store
      */
     write(sessionId: string, data: SessionData): Promise<void> | void;
     /**
-     * The destroy method is used to destroy the session by removing
-     * its data from the persistence store
+     * Removes session data for a given session ID from the persistence store
+     *
+     * @param sessionId - Unique identifier for the session to remove
      */
     destroy(sessionId: string): Promise<void> | void;
     /**
-     * The touch method should update the lifetime of session id without
-     * making changes to the session data.
+     * Updates the lifetime/expiry of a session without modifying the session data
+     *
+     * @param sessionId - Unique identifier for the session to touch
      */
     touch(sessionId: string): Promise<void> | void;
 }
 /**
- * Extended interface for stores that support tagging sessions
- * (linking sessions to user IDs for example)
- */
-export interface SessionStoreWithTaggingContract extends SessionStoreContract {
-    /**
-     * Tag a session with a user ID
-     */
-    tag(sessionId: string, userId: string): Promise<void>;
-    /**
-     * Get all sessions for a given user ID (tag)
-     */
-    tagged(userId: string): Promise<TaggedSession[]>;
-}
-/**
- * Base configuration for managing sessions without
- * stores.
+ * Base configuration interface for session management.
+ * Used by the session manager and middleware to control session behavior.
+ *
+ * @example
+ * const config: SessionConfig = {
+ *   enabled: true,
+ *   cookieName: 'my_app_session',
+ *   age: '2 hours',
+ *   cookie: {
+ *     httpOnly: true,
+ *     secure: true,
+ *     sameSite: 'strict'
+ *   }
+ * }
  */
 export interface SessionConfig {
     /**
-     * Enable/disable sessions temporarily
+     * Whether session management is enabled for the application
      */
     enabled: boolean;
     /**
-     * The name of the cookie for storing the session id.
+     * Name of the cookie used to store the session ID
      */
     cookieName: string;
     /**
-     * When set to true, the session id cookie will be removed
-     * when the user closes the browser.
-     *
-     * However, the persisted data will continue to exist until
-     * it gets expired.
-     */
-    clearWithBrowser: boolean;
-    /**
-     * How long the session data should be kept alive without any
-     * activity.
-     *
-     * The session id cookie will also live for the same duration, unless
-     * "clearWithBrowser" is enabled
-     *
-     * The value should be a time expression or a number in seconds
+     * Maximum age of the session data and session ID cookie.
+     * Session data is automatically cleaned up after this duration of inactivity.
+     * Value can be a time expression (e.g. '2 hours') or number of seconds.
+     * Cookie duration is also set to this value unless clearWithBrowser is enabled.
      */
     age: string | number;
     /**
-     * Configuration used by the cookie driver and for storing the
-     * session id cookie.
+     * Additional cookie options for the session ID cookie.
+     * Excludes maxAge and expires as they're controlled by age and clearWithBrowser.
      */
-    cookie: Omit<Partial<CookieOptions>, 'maxAge' | 'expires'>;
+    cookie: Partial<CookieOptions>;
 }
 /**
- * Configuration used by the file store.
+ * Configuration for file-based session storage.
+ * Sessions are stored as individual files on the filesystem.
+ *
+ * @example
+ * const fileConfig: FileStoreConfig = {
+ *   location: './tmp/sessions'
+ * }
  */
 export type FileStoreConfig = {
+    /**
+     * Directory path where session files should be stored
+     */
     location: string;
 };
 /**
- * Configuration used by the redis store.
+ * Configuration for Redis-based session storage.
+ * Sessions are stored in a Redis database with automatic expiry.
+ *
+ * @example
+ * const redisConfig: RedisStoreConfig = {
+ *   connection: 'main' // Redis connection name from config/redis.ts
+ * }
  */
 export type RedisStoreConfig = {
+    /**
+     * Name of the Redis connection to use (must match connection name in config/redis.ts)
+     */
     connection: keyof RedisConnections;
 };
 /**
- * Configuration used by the dynamodb store.
+ * Configuration for AWS DynamoDB-based session storage.
+ * Sessions are stored in a DynamoDB table with TTL support.
+ * Supports either providing a DynamoDB client instance or client configuration.
+ *
+ * @example
+ * // Using existing client
+ * const configWithClient: DynamoDBStoreConfig = {
+ *   client: dynamoClient,
+ *   tableName: 'UserSessions',
+ *   keyAttribute: 'sessionId'
+ * }
+ *
+ * // Using client configuration
+ * const configWithClientConfig: DynamoDBStoreConfig = {
+ *   clientConfig: {
+ *     region: 'us-east-1',
+ *     credentials: { ... }
+ *   },
+ *   tableName: 'Sessions'
+ * }
  */
 export type DynamoDBStoreConfig = ({
+    /**
+     * Pre-configured DynamoDB client instance
+     */
     client: DynamoDBClient;
 } | {
+    /**
+     * Configuration options for creating a new DynamoDB client
+     */
     clientConfig: DynamoDBClientConfig;
 }) & {
-    tableName?: string;
-    keyAttribute?: string;
-};
-/**
- * Configuration used by the database store.
- */
-export interface DatabaseStoreConfig {
-    connectionName?: string;
+    /**
+     * DynamoDB table name for storing sessions (defaults to "Session")
+     */
     tableName?: string;
     /**
-     * The probability (in percent) that garbage collection of expired
-     * sessions will be triggered on any given request.
-     *
-     * For example, 2 means 2% chance.
-     * Set to 0 to disable garbage collection.
-     *
-     * Defaults to 2 (2% chance)
+     * Attribute name for the session ID in the table (defaults to "key")
      */
-    gcProbability?: number;
-}
+    keyAttribute?: string;
+};
 /**
- * Factory function to instantiate session store
+ * Factory function type for creating session store instances.
+ * Used by the session manager to instantiate stores per HTTP request.
+ *
+ * @param ctx - HTTP context for the current request
+ * @param sessionConfig - Session configuration
+ *
+ * @example
+ * const storeFactory: SessionStoreFactory = (ctx, sessionConfig) => {
+ *   return new CustomStore({
+ *     connection: ctx.database,
+ *     maxAge: sessionConfig.age
+ *   })
+ * }
  */
 export type SessionStoreFactory = (ctx: HttpContext, sessionConfig: SessionConfig) => SessionStoreContract;
-/**
- * Resolved session config after processing by defineConfig
- */
-export interface ResolvedSessionConfig extends SessionConfig {
-    store: string;
-    stores: Record<string, SessionStoreFactory>;
-}

package/build/src/types.js

@@ -1 +1 @@
-//# sourceMappingURL=types.js.map
+export {};

package/build/src/values_store.d.ts

@@ -1,91 +1,183 @@
-import type { AllowedSessionValues, SessionData } from './types.js';
+import type { AllowedSessionValues, SessionData } from './types.ts';
 /**
- * Readonly session store
+ * Readonly session store that provides read-only access to session values.
+ * Used for sharing session data with templates and other readonly contexts.
+ *
+ * @example
+ * const readOnlyStore = new ReadOnlyValuesStore({ user: 'john', theme: 'dark' })
+ * const user = readOnlyStore.get('user')
+ * const hasTheme = readOnlyStore.has('theme')
  */
 export declare class ReadOnlyValuesStore {
     /**
-     * Underlying store values
+     * Underlying store values containing session data
      */
     protected values: SessionData;
     /**
-     * Find if store is empty or not
+     * Returns true if the store is empty
      */
     get isEmpty(): boolean;
+    /**
+     * Creates a new readonly values store
+     *
+     * @param values - Initial session data or null
+     */
     constructor(values: SessionData | null);
     /**
-     * Get value for a given key
+     * Gets value for a given key
+     *
+     * @param key - The key or key path to retrieve
+     * @param defaultValue - Default value if key doesn't exist
+     *
+     * @example
+     * store.get('username', 'guest')
+     * store.get(['user', 'preferences', 'theme'], 'light')
      */
     get(key: string | string[], defaultValue?: any): any;
     /**
-     * A boolean to know if value exists. Extra guards to check
-     * arrays for it's length as well.
+     * Checks if a value exists. Includes extra guards to check arrays for length.
+     *
+     * @param key - The key or key path to check
+     * @param checkForArraysLength - Whether to check array length (default: true)
+     *
+     * @example
+     * store.has('username')                    // Check if key exists
+     * store.has(['user', 'roles'])            // Check nested key
+     * store.has('items', false)               // Don't check array length
      */
     has(key: string | string[], checkForArraysLength?: boolean): boolean;
     /**
-     * Get all values
+     * Gets all values from the store
+     *
+     * @example
+     * const allData = store.all()
      */
     all(): any;
     /**
      * Returns object representation of values
+     *
+     * @example
+     * const obj = store.toObject()
      */
     toObject(): any;
     /**
-     * Returns the store values
+     * Returns the store values as JSON-serializable data
+     *
+     * @example
+     * const json = store.toJSON()
      */
     toJSON(): any;
     /**
      * Returns string representation of the store
+     *
+     * @example
+     * const str = store.toString()
      */
     toString(): string;
 }
 /**
  * Session store encapsulates the session data and offers a
  * declarative API to mutate it.
+ *
+ * @example
+ * const store = new ValuesStore({ counter: 0 })
+ * store.set('username', 'john')
+ * store.increment('counter')
+ * const hasData = store.hasBeenModified
  */
 export declare class ValuesStore extends ReadOnlyValuesStore {
     #private;
+    /**
+     * Creates a new values store
+     *
+     * @param values - Initial session data or null
+     */
     constructor(values: SessionData | null);
     /**
-     * Find if the store has been modified.
+     * Returns true if the store has been modified
      */
     get hasBeenModified(): boolean;
     /**
-     * Set key/value pair
+     * Sets a key/value pair in the store
+     *
+     * @param key - The key or key path to set
+     * @param value - The value to set
+     *
+     * @example
+     * store.set('username', 'john')
+     * store.set(['user', 'preferences'], { theme: 'dark' })
      */
     set(key: string | string[], value: AllowedSessionValues): void;
     /**
-     * Remove key
+     * Removes a key from the store
+     *
+     * @param key - The key or key path to remove
+     *
+     * @example
+     * store.unset('temp_data')
+     * store.unset(['user', 'cache'])
      */
     unset(key: string | string[]): void;
     /**
-     * Pull value from the store. It is same as calling
-     * store.get and then store.unset
+     * Pulls value from the store. Same as calling store.get then store.unset.
+     *
+     * @param key - The key or key path to pull
+     * @param defaultValue - Default value if key doesn't exist
+     *
+     * @example
+     * const message = store.pull('notification', 'No messages')
+     * const data = store.pull(['temp', 'data'])
      */
     pull(key: string | string[], defaultValue?: any): any;
     /**
-     * Increment number. The method raises an error when
-     * nderlying value is not a number
+     * Increments a numeric value. Raises an error when underlying value is not a number.
+     *
+     * @param key - The key or key path to increment
+     * @param steps - Number of steps to increment (default: 1)
+     *
+     * @example
+     * store.increment('page_views')     // Increments by 1
+     * store.increment('score', 10)      // Increments by 10
      */
     increment(key: string | string[], steps?: number): void;
     /**
-     * Increment number. The method raises an error when
-     * nderlying value is not a number
+     * Decrements a numeric value. Raises an error when underlying value is not a number.
+     *
+     * @param key - The key or key path to decrement
+     * @param steps - Number of steps to decrement (default: 1)
+     *
+     * @example
+     * store.decrement('attempts')       // Decrements by 1
+     * store.decrement('credits', 5)     // Decrements by 5
      */
     decrement(key: string | string[], steps?: number): void;
     /**
-     * Overwrite existing store data with new values.
+     * Overwrites existing store data with new values
+     *
+     * @param values - New values to replace existing data
+     *
+     * @example
+     * store.update({ username: 'jane', theme: 'light' })
      */
     update(values: {
         [key: string]: any;
     }): void;
     /**
-     * Update to merge values
+     * Merges values with existing store data
+     *
+     * @param values - Values to merge with existing data
+     *
+     * @example
+     * store.merge({ newField: 'value', existingField: 'updated' })
      */
     merge(values: {
         [key: string]: any;
     }): any;
     /**
-     * Reset store by clearing it's values.
+     * Resets store by clearing all values
+     *
+     * @example
+     * store.clear() // Removes all data from store
      */
     clear(): void;
 }