@adonisjs/session 7.0.0-2 → 7.0.0-3

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>;
 }