@adonisjs/session 7.5.0 → 8.0.0-next.0

package/build/src/plugins/japa/api_client.d.ts

@@ -1,7 +1,8 @@
+import '@japa/plugin-adonisjs';
 import type { PluginFn } from '@japa/runner/types';
 import type { ApplicationService } from '@adonisjs/core/types';
-import { SessionClient } from '../../client.js';
-import type { SessionData } from '../../types.js';
+import { SessionClient } from '../../client.ts';
+import type { SessionData } from '../../types.ts';
 declare module '@japa/api-client' {
     interface ApiRequest {
         sessionClient: SessionClient;
@@ -69,7 +70,24 @@ declare module '@japa/api-client' {
     }
 }
 /**
- * Hooks AdonisJS Session with the Japa API client
- * plugin
+ * Hooks AdonisJS Session with the Japa API client plugin.
+ * Provides session methods and assertions for API testing.
+ *
+ * @param app - AdonisJS application service
+ *
+ * @example
+ * // Register in test setup
+ * import { sessionApiClient } from '@adonisjs/session/plugins/japa/api_client'
+ *
+ * // Use in API tests
+ * test('can authenticate user', async ({ client }) => {
+ *   const response = await client
+ *     .post('/login')
+ *     .withSession({ remember: true })
+ *     .json({ email: 'user@example.com', password: 'secret' })
+ *
+ *   response.assertSession('userId', 123)
+ *   response.assertFlashMessage('success', 'Welcome back!')
+ * })
  */
 export declare const sessionApiClient: (app: ApplicationService) => PluginFn;

package/build/src/plugins/japa/api_client.js

@@ -1,13 +1,14 @@
 import {
   SessionClient
-} from "../../../chunk-GB5FBZCV.js";
-import "../../../chunk-TE5JP3SX.js";
-import "../../../chunk-ZVSEMDIC.js";
+} from "../../../chunk-Y566BNUT.js";
+import "../../../chunk-HAD4PFFM.js";
+import "../../../chunk-SBOMJK4T.js";
 
 // src/plugins/japa/api_client.ts
+import "@japa/plugin-adonisjs";
 import lodash from "@poppinss/utils/lodash";
 import { configProvider } from "@adonisjs/core";
-import { RuntimeException } from "@poppinss/utils";
+import { RuntimeException } from "@adonisjs/core/exceptions";
 import { ApiClient, ApiRequest, ApiResponse } from "@japa/api-client";
 var sessionApiClient = (app) => {
   const pluginFn = async function() {
@@ -97,4 +98,3 @@ var sessionApiClient = (app) => {
 export {
   sessionApiClient
 };
-//# sourceMappingURL=api_client.js.map

package/build/src/plugins/japa/browser_client.d.ts

@@ -1,8 +1,9 @@
+import '@japa/plugin-adonisjs';
 import type { PluginFn } from '@japa/runner/types';
 import type { ApplicationService } from '@adonisjs/core/types';
 import type { CookieOptions as AdonisCookieOptions } from '@adonisjs/core/types/http';
-import { SessionClient } from '../../client.js';
-import type { SessionData } from '../../types.js';
+import { SessionClient } from '../../client.ts';
+import type { SessionData } from '../../types.ts';
 declare module 'playwright' {
     interface BrowserContext {
         sessionClient: SessionClient;
@@ -30,7 +31,20 @@ declare module 'playwright' {
     }
 }
 /**
- * Hooks AdonisJS Session with the Japa browser client
- * plugin
+ * Hooks AdonisJS Session with the Japa browser client plugin.
+ * Provides session methods for browser testing context.
+ *
+ * @param app - AdonisJS application service
+ *
+ * @example
+ * // Register in test setup
+ * import { sessionBrowserClient } from '@adonisjs/session/plugins/japa/browser_client'
+ *
+ * // Use in browser tests
+ * test('can set session data', async ({ visit }) => {
+ *   await visit.context().setSession({ userId: 123 })
+ *   const response = await visit('/profile')
+ *   // Assert profile page shows user data
+ * })
  */
 export declare const sessionBrowserClient: (app: ApplicationService) => PluginFn;

package/build/src/plugins/japa/browser_client.js

@@ -1,13 +1,14 @@
 import {
   SessionClient
-} from "../../../chunk-GB5FBZCV.js";
-import "../../../chunk-TE5JP3SX.js";
-import "../../../chunk-ZVSEMDIC.js";
+} from "../../../chunk-Y566BNUT.js";
+import "../../../chunk-HAD4PFFM.js";
+import "../../../chunk-SBOMJK4T.js";
 
 // src/plugins/japa/browser_client.ts
+import "@japa/plugin-adonisjs";
 import { configProvider } from "@adonisjs/core";
-import { RuntimeException } from "@poppinss/utils";
 import { decoratorsCollection } from "@japa/browser-client";
+import { RuntimeException } from "@adonisjs/core/exceptions";
 function transformSameSiteOption(sameSite) {
   if (!sameSite) {
     return;
@@ -85,4 +86,3 @@ var sessionBrowserClient = (app) => {
 export {
   sessionBrowserClient
 };
-//# sourceMappingURL=browser_client.js.map

package/build/src/session.d.ts

@@ -2,169 +2,282 @@ import Macroable from '@poppinss/macroable';
 import type { HttpContext } from '@adonisjs/core/http';
 import type { EmitterService } from '@adonisjs/core/types';
 import type { HttpError } from '@adonisjs/core/types/http';
-import { ValuesStore } from './values_store.js';
-import type { SessionData, SessionConfig, SessionStoreFactory, AllowedSessionValues } from './types.js';
+import { ValuesStore } from './values_store.ts';
+import type { SessionData, SessionConfig, SessionStoreFactory, AllowedSessionValues } from './types.ts';
 /**
  * The session class exposes the API to read and write values to
  * the session store.
  *
  * A session instance is isolated between requests but
- * uses a centralized persistence store and
+ * uses a centralized persistence store.
+ *
+ * @example
+ * // Creating and using a session
+ * const session = new Session(config, storeFactory, emitter, ctx)
+ * await session.initiate(false)
+ *
+ * session.put('username', 'john')
+ * const username = session.get('username')
+ *
+ * await session.commit()
  */
 export declare class Session extends Macroable {
     #private;
     config: SessionConfig;
     /**
-     * Store of flash messages that be written during the
-     * HTTP request
+     * Store of flash messages that will be written during the HTTP request
      */
     responseFlashMessages: ValuesStore;
     /**
-     * Store of flash messages for the current HTTP request.
+     * Store of flash messages for the current HTTP request
      */
     flashMessages: ValuesStore;
     /**
-     * The key to use for storing flash messages inside
-     * the session store.
+     * The key used for storing flash messages inside the session store
      */
     flashKey: string;
     /**
-     * Session id for the current HTTP request
+     * Gets the session id for the current HTTP request
      */
     get sessionId(): string;
     /**
-     * A boolean to know if a fresh session is created during
-     * the request
+     * Returns true if a fresh session was created during the request
      */
     get fresh(): boolean;
     /**
-     * A boolean to know if session is in readonly
-     * state
+     * Returns true if the session is in readonly state
      */
     get readonly(): boolean;
     /**
-     * A boolean to know if session store has been initiated
+     * Returns true if the session store has been initiated
      */
     get initiated(): boolean;
     /**
-     * A boolean to know if the session id has been re-generated
-     * during the current request
+     * Returns true if the session id has been re-generated during the current request
      */
     get hasRegeneratedSession(): boolean;
     /**
-     * A boolean to know if the session store is empty
+     * Returns true if the session store is empty
      */
     get isEmpty(): boolean;
     /**
-     * A boolean to know if the session store has been
-     * modified
+     * Returns true if the session store has been modified
      */
     get hasBeenModified(): boolean;
+    /**
+     * Creates a new session instance
+     *
+     * @param config - Session configuration
+     * @param storeFactory - Factory function to create session store
+     * @param emitter - Event emitter service
+     * @param ctx - HTTP context
+     */
     constructor(config: SessionConfig, storeFactory: SessionStoreFactory, emitter: EmitterService, ctx: HttpContext);
     /**
-     * Initiates the session store. The method results in a noop
-     * when called multiple times
+     * Initiates the session store. The method results in a noop when called multiple times.
+     *
+     * @param readonly - Whether to initiate the session in readonly mode
+     *
+     * @example
+     * await session.initiate(false) // Read-write mode
+     * await session.initiate(true)  // Readonly mode
      */
     initiate(readonly: boolean): Promise<void>;
     /**
-     * Put a key-value pair to the session data store
+     * Puts a key-value pair to the session data store
+     *
+     * @param key - The key to store the value under
+     * @param value - The value to store
+     *
+     * @example
+     * session.put('username', 'john')
+     * session.put('user.preferences', { theme: 'dark' })
      */
     put(key: string, value: AllowedSessionValues): void;
     /**
-     * Check if a key exists inside the datastore
+     * Checks if a key exists inside the datastore
+     *
+     * @param key - The key to check for existence
+     *
+     * @example
+     * if (session.has('username')) {
+     *   console.log('User is logged in')
+     * }
      */
     has(key: string): boolean;
     /**
-     * Get the value of a key from the session datastore.
-     * You can specify a default value to use, when key
-     * does not exists or has undefined value.
+     * Gets the value of a key from the session datastore.
+     * You can specify a default value to use when key does not exist or has undefined value.
+     *
+     * @param key - The key to retrieve
+     * @param defaultValue - Default value to return if key doesn't exist
+     *
+     * @example
+     * const username = session.get('username', 'guest')
+     * const preferences = session.get('user.preferences', {})
      */
     get(key: string, defaultValue?: any): any;
     /**
-     * Get everything from the session store
+     * Gets everything from the session store
+     *
+     * @example
+     * const allData = session.all()
+     * console.log(allData) // { username: 'john', theme: 'dark' }
      */
     all(): any;
     /**
-     * Remove a key from the session datastore
+     * Removes a key from the session datastore
+     *
+     * @param key - The key to remove
+     *
+     * @example
+     * session.forget('temp_data')
+     * session.forget('user.cache')
      */
     forget(key: string): void;
     /**
-     * Read value for a key from the session datastore
-     * and remove it simultaneously.
+     * Reads value for a key from the session datastore and removes it simultaneously
+     *
+     * @param key - The key to pull
+     * @param defaultValue - Default value to return if key doesn't exist
+     *
+     * @example
+     * const message = session.pull('notification', 'No messages')
+     * // message contains the value, and it's removed from session
      */
     pull(key: string, defaultValue?: any): any;
     /**
-     * Increment the value of a key inside the session
-     * store.
+     * Increments the value of a key inside the session store.
+     * A new key will be defined if it doesn't exist already with value 1.
+     *
+     * @param key - The key to increment
+     * @param steps - Number of steps to increment (default: 1)
      *
-     * A new key will be defined if does not exists already.
-     * The value of a new key will be 1
+     * @example
+     * session.increment('page_views')     // Increments by 1
+     * session.increment('score', 10)      // Increments by 10
      */
     increment(key: string, steps?: number): void;
     /**
-     * Increment the value of a key inside the session
-     * store.
+     * Decrements the value of a key inside the session store.
+     * A new key will be defined if it doesn't exist already with value -1.
      *
-     * A new key will be defined if does not exists already.
-     * The value of a new key will be -1
+     * @param key - The key to decrement
+     * @param steps - Number of steps to decrement (default: 1)
+     *
+     * @example
+     * session.decrement('attempts')       // Decrements by 1
+     * session.decrement('credits', 5)     // Decrements by 5
      */
     decrement(key: string, steps?: number): void;
     /**
-     * Empty the session store
+     * Empties the session store
+     *
+     * @example
+     * session.clear() // Removes all session data
      */
     clear(): void;
     /**
-     * Add a key-value pair to flash messages
+     * Adds a key-value pair to flash messages
+     *
+     * @param key - The key or object of key-value pairs to flash
+     * @param value - The value to flash (when key is a string)
+     *
+     * @example
+     * session.flash('success', 'Data saved successfully!')
+     * session.flash({ error: 'Validation failed', info: 'Try again' })
      */
     flash(key: string, value: AllowedSessionValues): void;
     flash(keyValue: SessionData): void;
     /**
-     * Flash errors to the errorsBag. You can read these
-     * errors via the "@error" tag.
-     *
+     * Flashes errors to the errorsBag. You can read these errors via the "@error" tag.
      * Appends new messages to the existing collection.
+     *
+     * @param errorsCollection - Collection of error messages
+     *
+     * @example
+     * session.flashErrors({
+     *   general: 'Something went wrong',
+     *   validation: ['Name is required', 'Email is invalid']
+     * })
      */
     flashErrors(errorsCollection: Record<string, string | string[]>): void;
     /**
-     * Flash validation error messages. Make sure the error
-     * is an instance of VineJS ValidationException.
+     * Flashes validation error messages. Make sure the error is an instance of VineJS ValidationException.
+     * Overrides existing inputErrors.
+     *
+     * @param error - HTTP error containing validation messages
      *
-     * Overrides existing inputErrors
+     * @example
+     * try {
+     *   await request.validate(schema)
+     * } catch (error) {
+     *   session.flashValidationErrors(error)
+     * }
      */
-    flashValidationErrors(error: HttpError): void;
+    flashValidationErrors(error: HttpError, withInput?: boolean): void;
     /**
-     * Flash form input data to the flash messages store
+     * Flashes all form input data to the flash messages store
+     *
+     * @example
+     * session.flashAll() // Flashes all request input for next request
      */
     flashAll(): void;
     /**
-     * Flash form input data (except some keys) to the flash messages store
+     * Flashes form input data (except some keys) to the flash messages store
+     *
+     * @param keys - Array of keys to exclude from flashing
+     *
+     * @example
+     * session.flashExcept(['password', '_csrf'])
      */
     flashExcept(keys: string[]): void;
     /**
-     * Flash form input data (only some keys) to the flash messages store
+     * Flashes form input data (only some keys) to the flash messages store
+     *
+     * @param keys - Array of keys to include in flashing
+     *
+     * @example
+     * session.flashOnly(['name', 'email'])
      */
     flashOnly(keys: string[]): void;
     /**
-     * Reflash messages from the last request in the current response
+     * Reflashes messages from the last request in the current response
+     *
+     * @example
+     * session.reflash() // Keep all flash messages for another request
      */
     reflash(): void;
     /**
-     * Reflash messages (only some keys) from the last
-     * request in the current response
+     * Reflashes messages (only some keys) from the last request in the current response
+     *
+     * @param keys - Array of keys to reflash
+     *
+     * @example
+     * session.reflashOnly(['success', 'info'])
      */
     reflashOnly(keys: string[]): void;
     /**
-     * Reflash messages (except some keys) from the last
-     * request in the current response
+     * Reflashes messages (except some keys) from the last request in the current response
+     *
+     * @param keys - Array of keys to exclude from reflashing
+     *
+     * @example
+     * session.reflashExcept(['error', 'warning'])
      */
     reflashExcept(keys: string[]): void;
     /**
-     * Re-generate the session id and migrate data to it.
+     * Re-generates the session id and migrates data to it
+     *
+     * @example
+     * session.regenerate() // Generates new session ID for security
      */
     regenerate(): void;
     /**
-     * Commit session changes. No more mutations will be
-     * allowed after commit.
+     * Commits session changes. No more mutations will be allowed after commit.
+     *
+     * @example
+     * await session.commit() // Save all changes to the session store
      */
     commit(): Promise<void>;
 }

package/build/src/session_middleware.d.ts

@@ -1,8 +1,8 @@
-import { EmitterService } from '@adonisjs/core/types';
 import type { NextFn } from '@adonisjs/core/types/http';
-import { HttpContext } from '@adonisjs/core/http';
-import { Session } from './session.js';
-import type { SessionConfig, SessionStoreFactory } from './types.js';
+import { type EmitterService } from '@adonisjs/core/types';
+import { type HttpContext } from '@adonisjs/core/http';
+import { Session } from './session.ts';
+import type { SessionConfig, SessionStoreFactory } from './types.ts';
 /**
  * HttpContext augmentations
  */
@@ -13,13 +13,36 @@ declare module '@adonisjs/core/http' {
 }
 /**
  * Session middleware is used to initiate the session store
- * and commit its values during an HTTP request
+ * and commit its values during an HTTP request.
+ *
+ * @example
+ * // Register middleware in start/kernel.ts
+ * server.use([
+ *   () => import('#middleware/session_middleware')
+ * ])
+ *
+ * // Access session in route handler
+ * Route.get('/', ({ session }) => {
+ *   session.put('visited', true)
+ * })
  */
 export default class SessionMiddleware<KnownStores extends Record<string, SessionStoreFactory>> {
     #private;
+    /**
+     * Creates a new session middleware instance
+     *
+     * @param config - Session configuration with store settings
+     * @param emitter - Event emitter service
+     */
     constructor(config: SessionConfig & {
         store: keyof KnownStores;
         stores: KnownStores;
     }, emitter: EmitterService);
+    /**
+     * Handles the HTTP request by initializing session and committing changes
+     *
+     * @param ctx - HTTP context
+     * @param next - Next middleware function
+     */
     handle(ctx: HttpContext, next: NextFn): Promise<any>;
 }

package/build/src/session_middleware.js

@@ -1,10 +1,9 @@
 import {
   SessionMiddleware
-} from "../chunk-TZLOND27.js";
-import "../chunk-OCQGCVXK.js";
-import "../chunk-TE5JP3SX.js";
-import "../chunk-ZVSEMDIC.js";
+} from "../chunk-DFXWYDMY.js";
+import "../chunk-SHD6OX52.js";
+import "../chunk-HAD4PFFM.js";
+import "../chunk-SBOMJK4T.js";
 export {
   SessionMiddleware as default
 };
-//# sourceMappingURL=session_middleware.js.map

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

@@ -1,27 +1,61 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { CookieOptions } from '@adonisjs/core/types/http';
-import type { SessionData, SessionStoreContract } from '../types.js';
+import type { SessionData, SessionStoreContract } from '../types.ts';
 /**
- * Cookie store stores the session data inside an encrypted
- * cookie.
+ * Cookie store stores the session data inside an encrypted cookie.
+ * Best for simple applications with minimal session data.
+ *
+ * @example
+ * const cookieStore = new CookieStore({
+ *   httpOnly: true,
+ *   secure: true,
+ *   sameSite: 'strict'
+ * }, ctx)
  */
 export declare class CookieStore implements SessionStoreContract {
     #private;
+    /**
+     * Creates a new cookie store instance
+     *
+     * @param config - Cookie configuration options
+     * @param ctx - HTTP context
+     */
     constructor(config: Partial<CookieOptions>, ctx: HttpContext);
     /**
-     * Read session value from the cookie
+     * Reads session value from the encrypted cookie
+     *
+     * @param sessionId - Session identifier used as cookie name
+     *
+     * @example
+     * const data = store.read('sess_abc123')
      */
     read(sessionId: string): SessionData | null;
     /**
-     * Write session values to the cookie
+     * Writes session values to an encrypted cookie
+     *
+     * @param sessionId - Session identifier used as cookie name
+     * @param values - Session data to store
+     *
+     * @example
+     * store.write('sess_abc123', { userId: 123, theme: 'dark' })
      */
     write(sessionId: string, values: SessionData): void;
     /**
-     * Removes the session cookie
+     * Removes the session cookie from the client
+     *
+     * @param sessionId - Session identifier used as cookie name
+     *
+     * @example
+     * store.destroy('sess_abc123')
      */
     destroy(sessionId: string): void;
     /**
-     * Updates the cookie with existing cookie values
+     * Updates the cookie expiry by rewriting it with existing values
+     *
+     * @param sessionId - Session identifier used as cookie name
+     *
+     * @example
+     * store.touch('sess_abc123') // Refreshes cookie expiry
      */
     touch(sessionId: string): void;
 }

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

@@ -6,13 +6,29 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import type { SessionStoreContract, SessionData } from '../types.js';
+import { type DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import type { SessionStoreContract, SessionData } from '../types.ts';
 /**
- * DynamoDB store to read/write session to DynamoDB
+ * DynamoDB store to read/write session data to AWS DynamoDB.
+ * Provides highly scalable, managed session storage with automatic expiry.
+ *
+ * @example
+ * const dynamoStore = new DynamoDBStore(dynamoClient, '2 hours', {
+ *   tableName: 'Sessions',
+ *   keyAttribute: 'sessionId'
+ * })
  */
 export declare class DynamoDBStore implements SessionStoreContract {
     #private;
+    /**
+     * Creates a new DynamoDB store instance
+     *
+     * @param client - DynamoDB client instance
+     * @param age - Session age in seconds or time expression (e.g. '2 hours')
+     * @param options - Configuration options
+     * @param options.tableName - DynamoDB table name (defaults to "Session")
+     * @param options.keyAttribute - Key attribute name (defaults to "key")
+     */
     constructor(client: DynamoDBClient, age: string | number, options?: {
         /**
          * Defaults to "Session"
@@ -24,20 +40,40 @@ export declare class DynamoDBStore implements SessionStoreContract {
         keyAttribute?: string;
     });
     /**
-     * Returns session data. A new item will be created if it's
-     * missing.
+     * Reads session data from DynamoDB
+     *
+     * @param sessionId - Session identifier
+     *
+     * @example
+     * const data = await store.read('sess_abc123')
      */
     read(sessionId: string): Promise<SessionData | null>;
     /**
-     * Write session values to DynamoDB
+     * Writes session values to DynamoDB with expiry
+     *
+     * @param sessionId - Session identifier
+     * @param values - Session data to store
+     *
+     * @example
+     * await store.write('sess_abc123', { userId: 123 })
      */
     write(sessionId: string, values: Object): Promise<void>;
     /**
-     * Cleanup session item by removing it
+     * Removes session data from DynamoDB
+     *
+     * @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 DynamoDB
+     *
+     * @param sessionId - Session identifier
+     *
+     * @example
+     * await store.touch('sess_abc123')
      */
     touch(sessionId: string): Promise<void>;
 }