@adonisjs/session 7.0.0-1 → 7.0.0-11

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

@@ -0,0 +1,75 @@
+import type { PluginFn } from '@japa/runner/types';
+import type { ApplicationService } from '@adonisjs/core/types';
+import { SessionClient } from '../../client.js';
+import type { SessionData } from '../../types/main.js';
+declare module '@japa/api-client' {
+    interface ApiRequest {
+        sessionClient: SessionClient;
+        /**
+         * Make HTTP request along with the provided session data
+         */
+        withSession(values: SessionData): this;
+        /**
+         * Make HTTP request along with the provided session flash
+         * messages.
+         */
+        withFlashMessages(values: SessionData): this;
+    }
+    interface ApiResponse {
+        sessionBag: {
+            values: SessionData;
+            flashMessages: SessionData;
+        };
+        /**
+         * Get session data from the HTTP response
+         */
+        session(key?: string): any;
+        /**
+         * Get flash messages from the HTTP response
+         */
+        flashMessages(): SessionData;
+        /**
+         * Get flash messages for a specific key from the HTTP response
+         */
+        flashMessage(key: string): SessionData;
+        /**
+         * Assert session key-value pair exists
+         */
+        assertSession(key: string, value?: any): void;
+        /**
+         * Assert key is missing in session store
+         */
+        assertSessionMissing(key: string): void;
+        /**
+         * Assert flash message key-value pair exists
+         */
+        assertFlashMessage(key: string, value?: any): void;
+        /**
+         * Assert key is missing flash messages store
+         */
+        assertFlashMissing(key: string): void;
+        /**
+         * Assert flash messages has validation errors for
+         * the given field
+         */
+        assertHasValidationError(field: string): void;
+        /**
+         * Assert flash messages does not have validation errors
+         * for the given field
+         */
+        assertDoesNotHaveValidationError(field: string): void;
+        /**
+         * Assert error message for a given field
+         */
+        assertValidationError(field: string, message: string): void;
+        /**
+         * Assert all error messages for a given field
+         */
+        assertValidationErrors(field: string, messages: string[]): void;
+    }
+}
+/**
+ * Hooks AdonisJS Session with the Japa API Client
+ * plugin
+ */
+export declare const sessionApiClient: (app: ApplicationService) => PluginFn;

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

@@ -0,0 +1,145 @@
+/*
+ * @adonisjs/session
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import lodash from '@poppinss/utils/lodash';
+import { RuntimeException } from '@poppinss/utils';
+import { ApiClient, ApiRequest, ApiResponse } from '@japa/api-client';
+import { SessionClient } from '../../client.js';
+import { registerSessionDriver } from '../../helpers.js';
+import sessionDriversList from '../../drivers_collection.js';
+/**
+ * Hooks AdonisJS Session with the Japa API Client
+ * plugin
+ */
+export const sessionApiClient = (app) => {
+    const pluginFn = async function () {
+        const config = app.config.get('session');
+        /**
+         * Disallow usage of driver other than memory during testing
+         */
+        if (config.driver !== 'memory') {
+            throw new RuntimeException(`Cannot use session driver "${config.driver}" during testing. Switch to memory driver`);
+        }
+        /**
+         * Register the memory driver if not already registered
+         */
+        await registerSessionDriver(app, 'memory');
+        /**
+         * Stick an singleton session client to APIRequest. The session
+         * client is used to keep a track of session data we have
+         * to send during the request.
+         */
+        ApiRequest.getter('sessionClient', function () {
+            return new SessionClient(sessionDriversList.create('memory', config));
+        }, true);
+        /**
+         * Define session data
+         */
+        ApiRequest.macro('withSession', function (data) {
+            this.sessionClient.merge(data);
+            return this;
+        });
+        /**
+         * Define flash messages
+         */
+        ApiRequest.macro('withFlashMessages', function (data) {
+            this.sessionClient.flash(data);
+            return this;
+        });
+        /**
+         * Get session data
+         */
+        ApiResponse.macro('session', function (key) {
+            return key ? lodash.get(this.sessionBag.values, key) : this.sessionBag.values;
+        });
+        /**
+         * Get flash messages
+         */
+        ApiResponse.macro('flashMessages', function () {
+            return this.sessionBag.flashMessages;
+        });
+        ApiResponse.macro('flashMessage', function (key) {
+            return lodash.get(this.sessionBag.flashMessages, key);
+        });
+        /**
+         * Response session assertions
+         */
+        ApiResponse.macro('assertSession', function (key, value) {
+            this.assert.property(this.session(), key);
+            if (value !== undefined) {
+                this.assert.deepEqual(this.session(key), value);
+            }
+        });
+        ApiResponse.macro('assertSessionMissing', function (key) {
+            this.assert.notProperty(this.session(), key);
+        });
+        ApiResponse.macro('assertFlashMessage', function (key, value) {
+            this.assert.property(this.flashMessages(), key);
+            if (value !== undefined) {
+                this.assert.deepEqual(this.flashMessage(key), value);
+            }
+        });
+        ApiResponse.macro('assertFlashMissing', function (key) {
+            this.assert.notProperty(this.flashMessages(), key);
+        });
+        ApiResponse.macro('assertHasValidationError', function (field) {
+            this.assert.property(this.flashMessage('errors'), field);
+        });
+        ApiResponse.macro('assertDoesNotHaveValidationError', function (field) {
+            this.assert.notProperty(this.flashMessage('errors'), field);
+        });
+        ApiResponse.macro('assertValidationError', function (field, message) {
+            this.assert.include(this.flashMessage('errors')?.[field] || [], message);
+        });
+        ApiResponse.macro('assertValidationErrors', function (field, messages) {
+            this.assert.deepEqual(this.flashMessage('errors')?.[field] || [], messages);
+        });
+        /**
+         * We define the hook using the "request.setup" method because we
+         * want to allow other Japa hooks to mutate the session store
+         * without running into race conditions
+         */
+        ApiClient.onRequest((request) => {
+            request.setup(async () => {
+                /**
+                 * Set cookie
+                 */
+                request.withCookie(config.cookieName, request.sessionClient.sessionId);
+                /**
+                 * Persist data
+                 */
+                await request.sessionClient.commit();
+                /**
+                 * Cleanup if request fails
+                 */
+                return async (error) => {
+                    if (error) {
+                        await request.sessionClient.destroy();
+                    }
+                };
+            });
+            request.teardown(async (response) => {
+                const sessionId = response.cookie(config.cookieName);
+                /**
+                 * Reading session data from the response cookie
+                 */
+                response.sessionBag = sessionId
+                    ? await response.request.sessionClient.load(sessionId.value)
+                    : {
+                        values: {},
+                        flashMessages: {},
+                    };
+                /**
+                 * Cleanup state
+                 */
+                await request.sessionClient.destroy(sessionId?.value);
+            });
+        });
+    };
+    return pluginFn;
+};

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

@@ -0,0 +1,36 @@
+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/main.js';
+declare module 'playwright' {
+    interface BrowserContext {
+        sessionClient: SessionClient;
+        /**
+         * Initiate session. The session id cookie will be defined
+         * if missing
+         */
+        initiateSession(options?: Partial<AdonisCookieOptions>): Promise<void>;
+        /**
+         * Returns data from the session store
+         */
+        getSession(): Promise<any>;
+        /**
+         * Returns data from the session store
+         */
+        getFlashMessages(): Promise<any>;
+        /**
+         * Set session data
+         */
+        setSession(values: SessionData): Promise<void>;
+        /**
+         * Set flash messages
+         */
+        setFlashMessages(values: SessionData): Promise<void>;
+    }
+}
+/**
+ * Hooks AdonisJS Session with the Japa API Client
+ * plugin
+ */
+export declare const sessionBrowserClient: (app: ApplicationService) => PluginFn;

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

@@ -0,0 +1,119 @@
+/*
+ * @adonisjs/session
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { RuntimeException } from '@poppinss/utils';
+import { decoratorsCollection } from '@japa/browser-client';
+import { SessionClient } from '../../client.js';
+import { registerSessionDriver } from '../../helpers.js';
+import sessionDriversList from '../../drivers_collection.js';
+/**
+ * Transforming AdonisJS same site option to playwright
+ * same site option.
+ */
+function transformSameSiteOption(sameSite) {
+    if (!sameSite) {
+        return;
+    }
+    if (sameSite === true || sameSite === 'strict') {
+        return 'Strict';
+    }
+    if (sameSite === 'lax') {
+        return 'Lax';
+    }
+    if (sameSite === 'none') {
+        return 'None';
+    }
+}
+/**
+ * Transforming AdonisJS session config to playwright cookie options.
+ */
+function getSessionCookieOptions(config, cookieOptions) {
+    const options = { ...config.cookie, ...cookieOptions };
+    return {
+        ...options,
+        expires: undefined,
+        sameSite: transformSameSiteOption(options.sameSite),
+    };
+}
+/**
+ * Hooks AdonisJS Session with the Japa API Client
+ * plugin
+ */
+export const sessionBrowserClient = (app) => {
+    const pluginFn = async function () {
+        const config = app.config.get('session');
+        /**
+         * Disallow usage of driver other than memory during testing
+         */
+        if (config.driver !== 'memory') {
+            throw new RuntimeException(`Cannot use session driver "${config.driver}" during testing. Switch to memory driver`);
+        }
+        /**
+         * Register the memory driver if not already registered
+         */
+        await registerSessionDriver(app, 'memory');
+        decoratorsCollection.register({
+            context(context) {
+                /**
+                 * Reference to session client per browser context
+                 */
+                context.sessionClient = new SessionClient(sessionDriversList.create('memory', config));
+                /**
+                 * Initiating session store
+                 */
+                context.initiateSession = async function (options) {
+                    const sessionId = await context.getCookie(config.cookieName);
+                    if (sessionId) {
+                        context.sessionClient.sessionId = sessionId;
+                        return;
+                    }
+                    await context.setCookie(config.cookieName, context.sessionClient.sessionId, getSessionCookieOptions(config, options));
+                };
+                /**
+                 * Returns session data
+                 */
+                context.getSession = async function () {
+                    await context.initiateSession();
+                    const sessionData = await context.sessionClient.load();
+                    return sessionData.values;
+                };
+                /**
+                 * Returns flash messages from the data store
+                 */
+                context.getFlashMessages = async function () {
+                    await context.initiateSession();
+                    const sessionData = await context.sessionClient.load();
+                    return sessionData.flashMessages;
+                };
+                /**
+                 * Set session data
+                 */
+                context.setSession = async function (values) {
+                    await context.initiateSession();
+                    context.sessionClient.merge(values);
+                    await context.sessionClient.commit();
+                };
+                /**
+                 * Set flash messages
+                 */
+                context.setFlashMessages = async function (values) {
+                    await context.initiateSession();
+                    context.sessionClient.flash(values);
+                    await context.sessionClient.commit();
+                };
+                /**
+                 * Destroy session when context is closed
+                 */
+                context.on('close', async function () {
+                    await context.sessionClient.destroy();
+                });
+            },
+        });
+    };
+    return pluginFn;
+};

package/build/src/session.d.ts

@@ -1,132 +1,159 @@
-import type { SessionConfig, SessionDriverContract, AllowedSessionValues } from './types.js';
+import { EmitterService } from '@adonisjs/core/types';
 import type { HttpContext } from '@adonisjs/core/http';
 import { Store } from './store.js';
+import type { SessionData, SessionConfig, AllowedSessionValues, SessionDriverContract } from './types/main.js';
+import { HttpError } from '@adonisjs/core/types/http';
 /**
- * Session class exposes the API to read/write values to the session for
- * a given request.
+ * 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
  */
 export declare class Session {
     #private;
     /**
-     * Set to true inside the `initiate` method
+     * Store of flash messages that be written during the
+     * HTTP request
      */
-    initiated: boolean;
+    responseFlashMessages: Store;
     /**
-     * A boolean to know if it's a fresh session or not. Fresh
-     * sessions are those, whose session id is not present
-     * in cookie
+     * Store of flash messages for the current HTTP request.
      */
-    fresh: boolean;
+    flashMessages: Store;
     /**
-     * A boolean to know if store is initiated in readonly mode
-     * or not. This is done during Websocket requests
+     * The key to use for storing flash messages inside
+     * the session store.
      */
-    readonly: boolean;
+    flashKey: string;
     /**
-     * Session id for the given request. A new session id is only
-     * generated when the cookie for the session id is missing
+     * Session id for the current HTTP request
      */
-    sessionId: string;
+    get sessionId(): string;
     /**
-     * A copy of previously set flash messages
+     * A boolean to know if a fresh session is created during
+     * the request
      */
-    flashMessages: Store;
+    get fresh(): boolean;
     /**
-     * A copy of flash messages. The `input` messages
-     * are overwritten when any of the input related
-     * methods are used.
-     *
-     * The `others` object is expanded with each call.
+     * A boolean to know if session is in readonly
+     * state
      */
-    responseFlashMessages: Store;
-    constructor(ctx: HttpContext, config: SessionConfig, driver: SessionDriverContract);
+    get readonly(): boolean;
     /**
-     * Initiating the session by reading it's value from the
-     * driver and feeding it to a store.
-     *
-     * Multiple calls to `initiate` results in a noop.
+     * A boolean to know if session store has been initiated
      */
-    initiate(readonly: boolean): Promise<void>;
+    get initiated(): boolean;
     /**
-     * Re-generates the session id. This can is used to avoid
-     * session fixation attacks.
+     * A boolean to know if the session id has been re-generated
+     * during the current request
      */
-    regenerate(): void;
+    get hasRegeneratedSession(): boolean;
+    /**
+     * A boolean to know if the session store is empty
+     */
+    get isEmpty(): boolean;
+    /**
+     * A boolean to know if the session store has been
+     * modified
+     */
+    get hasBeenModified(): boolean;
+    constructor(config: SessionConfig, driver: SessionDriverContract, emitter: EmitterService, ctx: HttpContext);
+    /**
+     * Initiates the session store. The method results in a noop
+     * when called multiple times
+     */
+    initiate(readonly: boolean): Promise<void>;
     /**
-     * Set/update session value
+     * Put a key-value pair to the session data store
      */
     put(key: string, value: AllowedSessionValues): void;
     /**
-     * Find if the value exists in the session
+     * Check if a key exists inside the datastore
      */
     has(key: string): boolean;
     /**
-     * Get value from the session. The default value is returned
-     * when actual value is `undefined`
+     * 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.
      */
     get(key: string, defaultValue?: any): any;
     /**
-     * Returns everything from the session
+     * Get everything from the session store
      */
     all(): any;
     /**
-     * Remove value for a given key from the session
+     * Remove a key from the session datastore
      */
     forget(key: string): void;
     /**
-     * The method is equivalent to calling `session.get` followed
-     * by `session.forget`
+     * Read value for a key from the session datastore
+     * and remove it simultaneously.
      */
     pull(key: string, defaultValue?: any): any;
     /**
-     * Increment value for a number inside the session store. The
-     * method raises an error when underlying value is not
-     * a number
+     * Increment the value of a key inside the session
+     * store.
+     *
+     * A new key will be defined if does not exists already.
+     * The value of a new key will be 1
      */
     increment(key: string, steps?: number): void;
     /**
-     * Decrement value for a number inside the session store. The
-     * method raises an error when underlying value is not
-     * a number
+     * Increment the value of a key inside the session
+     * store.
+     *
+     * A new key will be defined if does not exists already.
+     * The value of a new key will be -1
      */
     decrement(key: string, steps?: number): void;
     /**
-     * Remove everything from the session
+     * Empty the session store
      */
     clear(): void;
     /**
-     * Add a new flash message
+     * Flash validation error messages. Make sure the error
+     * is an instance of VineJS ValidationException
      */
-    flash(key: string | {
-        [key: string]: AllowedSessionValues;
-    }, value?: AllowedSessionValues): void;
+    flashValidationErrors(error: HttpError): void;
     /**
-     * Flash all form values
+     * Add a key-value pair to flash messages
+     */
+    flash(key: string, value: AllowedSessionValues): void;
+    flash(keyValue: SessionData): void;
+    /**
+     * Flash form input data to the flash messages store
      */
     flashAll(): void;
     /**
-     * Flash all form values except mentioned keys
+     * Flash form input data (except some keys) to the flash messages store
      */
     flashExcept(keys: string[]): void;
     /**
-     * Flash only defined keys from the form values
+     * Flash form input data (only some keys) to the flash messages store
      */
     flashOnly(keys: string[]): void;
     /**
-     * Reflash existing flash messages
+     * Reflash messages from the last request in the current response
      */
     reflash(): void;
     /**
-     * Reflash selected keys from the existing flash messages
+     * Reflash messages (only some keys) from the last
+     * request in the current response
      */
     reflashOnly(keys: string[]): void;
     /**
-     * Omit selected keys from the existing flash messages
-     * and flash the rest of values
+     * Reflash messages (except some keys) from the last
+     * request in the current response
      */
     reflashExcept(keys: string[]): void;
     /**
-     * Writes value to the underlying session driver.
+     * Re-generate the session id and migrate data to it.
+     */
+    regenerate(): void;
+    /**
+     * Commit session changes. No more mutations will be
+     * allowed after commit.
      */
     commit(): Promise<void>;
 }