@adonisjs/session 7.5.1 → 8.0.0-next.0

package/build/{chunk-OCQGCVXK.js → chunk-SHD6OX52.js}

@@ -1,11 +1,11 @@
 import {
   ReadOnlyValuesStore,
   ValuesStore
-} from "./chunk-TE5JP3SX.js";
+} from "./chunk-HAD4PFFM.js";
 import {
   __export,
   debug_default
-} from "./chunk-ZVSEMDIC.js";
+} from "./chunk-SBOMJK4T.js";
 
 // src/errors.ts
 var errors_exports = {};
@@ -13,7 +13,7 @@ __export(errors_exports, {
   E_SESSION_NOT_MUTABLE: () => E_SESSION_NOT_MUTABLE,
   E_SESSION_NOT_READY: () => E_SESSION_NOT_READY
 });
-import { createError } from "@poppinss/utils";
+import { createError } from "@adonisjs/core/exceptions";
 var E_SESSION_NOT_MUTABLE = createError(
   "Session store is in readonly mode and cannot be mutated",
   "E_SESSION_NOT_MUTABLE",
@@ -26,10 +26,18 @@ var E_SESSION_NOT_READY = createError(
 );
 
 // src/session.ts
+import { randomUUID } from "crypto";
 import Macroable from "@poppinss/macroable";
 import lodash from "@poppinss/utils/lodash";
-import { cuid } from "@adonisjs/core/helpers";
 var Session = class extends Macroable {
+  /**
+   * 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, storeFactory, emitter, ctx) {
     super();
     this.config = config;
@@ -37,93 +45,83 @@ var Session = class extends Macroable {
     this.#emitter = emitter;
     this.#store = storeFactory(ctx, config);
     this.#sessionIdFromCookie = ctx.request.cookie(config.cookieName, void 0);
-    this.#sessionId = this.#sessionIdFromCookie || cuid();
+    this.#sessionId = this.#sessionIdFromCookie || randomUUID();
   }
   #store;
   #emitter;
   #ctx;
   #readonly = false;
   /**
-   * Session values store
+   * Session values store that holds the actual session data
    */
   #valuesStore;
   /**
-   * Session id refers to the session id that will be committed
-   * as a cookie during the response.
+   * Session id that will be committed as a cookie during the response
    */
   #sessionId;
   /**
-   * Session id from cookie refers to the value we read from the
-   * cookie during the HTTP request.
-   *
-   * This only might not exist during the first request. Also during
-   * session id re-generation, this value will be different from
-   * the session id.
+   * Session id read from the cookie during the HTTP request.
+   * May not exist during the first request or will differ from sessionId during regeneration.
    */
   #sessionIdFromCookie;
   /**
-   * Store of flash messages that be written during the
-   * HTTP request
+   * Store of flash messages that will be written during the HTTP request
    */
   responseFlashMessages = new ValuesStore({});
   /**
-   * Store of flash messages for the current HTTP request.
+   * Store of flash messages for the current HTTP request
    */
   flashMessages = new 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 = "__flash__";
   /**
-   * Session id for the current HTTP request
+   * Gets the session id for the current HTTP request
    */
   get sessionId() {
     return this.#sessionId;
   }
   /**
-   * 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() {
     return this.#sessionIdFromCookie === void 0;
   }
   /**
-   * A boolean to know if session is in readonly
-   * state
+   * Returns true if the session is in readonly state
    */
   get readonly() {
     return this.#readonly;
   }
   /**
-   * A boolean to know if session store has been initiated
+   * Returns true if the session store has been initiated
    */
   get initiated() {
     return !!this.#valuesStore;
   }
   /**
-   * 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() {
     return !!(this.#sessionIdFromCookie && this.#sessionIdFromCookie !== this.#sessionId);
   }
   /**
-   * A boolean to know if the session store is empty
+   * Returns true if the session store is empty
    */
   get isEmpty() {
     return this.#valuesStore?.isEmpty ?? true;
   }
   /**
-   * A boolean to know if the session store has been
-   * modified
+   * Returns true if the session store has been modified
    */
   get hasBeenModified() {
     return this.#valuesStore?.hasBeenModified ?? false;
   }
   /**
-   * Returns the flash messages store for a given
-   * mode
+   * Returns the flash messages store for a given mode
+   *
+   * @param mode - Access mode ('write' or 'read')
    */
   #getFlashStore(mode) {
     if (!this.#valuesStore) {
@@ -136,6 +134,8 @@ var Session = class extends Macroable {
   }
   /**
    * Returns the store instance for a given mode
+   *
+   * @param mode - Access mode ('write' or 'read')
    */
   #getValuesStore(mode) {
     if (!this.#valuesStore) {
@@ -147,8 +147,13 @@ var Session = class extends Macroable {
     return this.#valuesStore;
   }
   /**
-   * 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
    */
   async initiate(readonly) {
     if (this.#valuesStore) {
@@ -178,66 +183,113 @@ var Session = class extends Macroable {
     this.#emitter.emit("session:initiated", { session: this });
   }
   /**
-   * 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, value) {
     this.#getValuesStore("write").set(key, value);
   }
   /**
-   * 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) {
     return this.#getValuesStore("read").has(key);
   }
   /**
-   * 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, defaultValue) {
     return this.#getValuesStore("read").get(key, defaultValue);
   }
   /**
-   * 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() {
     return this.#getValuesStore("read").all();
   }
   /**
-   * 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) {
     return this.#getValuesStore("write").unset(key);
   }
   /**
-   * 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, defaultValue) {
     return this.#getValuesStore("write").pull(key, defaultValue);
   }
   /**
-   * 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, steps = 1) {
     return this.#getValuesStore("write").increment(key, steps);
   }
   /**
-   * 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, steps = 1) {
     return this.#getValuesStore("write").decrement(key, steps);
   }
   /**
-   * Empty the session store
+   * Empties the session store
+   *
+   * @example
+   * session.clear() // Removes all session data
    */
   clear() {
     return this.#getValuesStore("write").clear();
@@ -252,21 +304,34 @@ var Session = class extends Macroable {
     }
   }
   /**
-   * 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) {
     this.flash({ errorsBag: errorsCollection });
   }
   /**
-   * 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.
    *
-   * Overrides existing inputErrors
-   */
-  flashValidationErrors(error) {
+   * @param error - HTTP error containing validation messages
+   *
+   * @example
+   * try {
+   *   await request.validate(schema)
+   * } catch (error) {
+   *   session.flashValidationErrors(error)
+   * }
+   */
+  flashValidationErrors(error, withInput = true) {
     const errorsBag = error.messages.reduce((result, message) => {
       if (result[message.field]) {
         result[message.field].push(message.message);
@@ -275,7 +340,9 @@ var Session = class extends Macroable {
       }
       return result;
     }, {});
-    this.flashExcept(["_csrf", "_method", "password", "password_confirmation"]);
+    if (withInput) {
+      this.flashExcept(["_csrf", "_method", "password", "password_confirmation"]);
+    }
     let summary = "The form could not be saved. Please check the errors below.";
     if ("i18n" in this.#ctx) {
       summary = this.#ctx.i18n.t(
@@ -290,55 +357,83 @@ var Session = class extends Macroable {
       [String(error.code)]: summary
     });
     this.flash("inputErrorsBag", errorsBag);
-    this.flash("errors", errorsBag);
   }
   /**
-   * 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() {
     return this.#getFlashStore("write").set("input", this.#ctx.request.original());
   }
   /**
-   * 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) {
     this.#getFlashStore("write").set("input", lodash.omit(this.#ctx.request.original(), keys));
   }
   /**
-   * 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) {
     this.#getFlashStore("write").set("input", lodash.pick(this.#ctx.request.original(), keys));
   }
   /**
-   * 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() {
     this.#getFlashStore("write").set("reflashed", this.flashMessages.all());
   }
   /**
-   * 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) {
     this.#getFlashStore("write").set("reflashed", lodash.pick(this.flashMessages.all(), keys));
   }
   /**
-   * 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) {
     this.#getFlashStore("write").set("reflashed", lodash.omit(this.flashMessages.all(), keys));
   }
   /**
-   * 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() {
-    this.#sessionId = cuid();
+    this.#sessionId = randomUUID();
   }
   /**
-   * 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
    */
   async commit() {
     if (!this.#valuesStore || this.readonly) {
@@ -391,4 +486,3 @@ export {
   errors_exports,
   Session
 };
-//# sourceMappingURL=chunk-OCQGCVXK.js.map

package/build/chunk-Y566BNUT.js

@@ -0,0 +1,113 @@
+import {
+  ValuesStore
+} from "./chunk-HAD4PFFM.js";
+import {
+  debug_default
+} from "./chunk-SBOMJK4T.js";
+
+// src/client.ts
+import { randomUUID } from "crypto";
+var SessionClient = class {
+  /**
+   * Internal data store for session values
+   */
+  #valuesStore = new ValuesStore({});
+  /**
+   * Internal store for flash messages
+   */
+  #flashMessagesStore = new ValuesStore({});
+  /**
+   * The session store contract for reading and writing session data
+   */
+  #store;
+  /**
+   * Session key used for storing flash messages
+   */
+  flashKey = "__flash__";
+  /**
+   * Session ID to use when no explicit session id is defined
+   */
+  sessionId = randomUUID();
+  /**
+   * Creates a new session client
+   *
+   * @param store - Session store contract implementation
+   */
+  constructor(store) {
+    this.#store = store;
+  }
+  /**
+   * Merges session data with existing values
+   *
+   * @param values - Session data to merge
+   *
+   * @example
+   * client.merge({ userId: 123, theme: 'dark' })
+   */
+  merge(values) {
+    this.#valuesStore.merge(values);
+    return this;
+  }
+  /**
+   * Merges flash messages with existing flash data
+   *
+   * @param values - Flash message data to merge
+   *
+   * @example
+   * client.flash({ success: 'Operation completed', info: 'Check your email' })
+   */
+  flash(values) {
+    this.#flashMessagesStore.merge(values);
+    return this;
+  }
+  /**
+   * Commits data to the session store
+   *
+   * @example
+   * await client.commit() // Saves all changes to the store
+   */
+  async commit() {
+    if (!this.#flashMessagesStore.isEmpty) {
+      this.#valuesStore.set(this.flashKey, this.#flashMessagesStore.toJSON());
+    }
+    debug_default("committing session data during api request");
+    if (!this.#valuesStore.isEmpty) {
+      this.#store.write(this.sessionId, this.#valuesStore.toJSON());
+    }
+  }
+  /**
+   * Destroys the session data from the store
+   *
+   * @param sessionId - Optional session ID to destroy (defaults to current session)
+   *
+   * @example
+   * await client.destroy()           // Destroy current session
+   * await client.destroy('abc123')   // Destroy specific session
+   */
+  async destroy(sessionId) {
+    debug_default("destroying session data during api request");
+    this.#store.destroy(sessionId || this.sessionId);
+  }
+  /**
+   * Loads session data from the session store
+   *
+   * @param sessionId - Optional session ID to load (defaults to current session)
+   *
+   * @example
+   * const { values, flashMessages } = await client.load()
+   * const data = await client.load('abc123') // Load specific session
+   */
+  async load(sessionId) {
+    const contents = await this.#store.read(sessionId || this.sessionId);
+    const store = new ValuesStore(contents);
+    const flashMessages = store.pull(this.flashKey, {});
+    return {
+      values: store.all(),
+      flashMessages
+    };
+  }
+};
+
+export {
+  SessionClient
+};

package/build/{cookie-WBWYVEDW.js → cookie-YBBGLCO5.js}

@@ -1,18 +1,35 @@
 import {
   debug_default
-} from "./chunk-ZVSEMDIC.js";
+} from "./chunk-SBOMJK4T.js";
 
 // src/stores/cookie.ts
 var CookieStore = class {
+  /**
+   * HTTP context for request/response operations
+   */
   #ctx;
+  /**
+   * Cookie configuration options
+   */
   #config;
+  /**
+   * Creates a new cookie store instance
+   *
+   * @param config - Cookie configuration options
+   * @param ctx - HTTP context
+   */
   constructor(config, ctx) {
     this.#config = config;
     this.#ctx = ctx;
     debug_default("initiating cookie store %O", this.#config);
   }
   /**
-   * 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) {
     debug_default("cookie store: reading session data %s", sessionId);
@@ -23,14 +40,25 @@ var CookieStore = class {
     return cookieValue;
   }
   /**
-   * 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, values) {
     debug_default("cookie store: writing session data %s: %O", sessionId, values);
     this.#ctx.response.encryptedCookie(sessionId, values, this.#config);
   }
   /**
-   * 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) {
     debug_default("cookie store: destroying session data %s", sessionId);
@@ -39,7 +67,12 @@ var CookieStore = class {
     }
   }
   /**
-   * 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) {
     const value = this.read(sessionId);
@@ -53,4 +86,3 @@ var CookieStore = class {
 export {
   CookieStore
 };
-//# sourceMappingURL=cookie-WBWYVEDW.js.map