@adonisjs/session 7.5.0 → 8.0.0-next.0

package/build/{dynamodb-3PG52TE3.js → dynamodb-PLZABBFD.js}

@@ -1,9 +1,9 @@
 import {
   debug_default
-} from "./chunk-ZVSEMDIC.js";
+} from "./chunk-SBOMJK4T.js";
 
 // src/stores/dynamodb.ts
-import string from "@poppinss/utils/string";
+import string from "@adonisjs/core/helpers/string";
 import { MessageBuilder } from "@adonisjs/core/helpers";
 import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
 import {
@@ -13,12 +13,39 @@ import {
   UpdateItemCommand
 } from "@aws-sdk/client-dynamodb";
 var DynamoDBStore = class {
+  /**
+   * DynamoDB client instance
+   */
   #client;
+  /**
+   * DynamoDB table name
+   */
   #tableName;
+  /**
+   * Attribute name for the session key
+   */
   #keyAttribute;
+  /**
+   * Time-to-live in seconds for session expiry
+   */
   #ttlSeconds;
+  /**
+   * Attribute name for the session value
+   */
   #valueAttribute = "value";
+  /**
+   * Attribute name for the expiry timestamp
+   */
   #expiresAtAttribute = "expires_at";
+  /**
+   * 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, age, options) {
     this.#client = client;
     this.#tableName = options?.tableName ?? "Session";
@@ -27,8 +54,12 @@ var DynamoDBStore = class {
     debug_default("initiating dynamodb store");
   }
   /**
-   * 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')
    */
   async read(sessionId) {
     debug_default("dynamodb store: reading session data %s", sessionId);
@@ -56,7 +87,13 @@ var DynamoDBStore = class {
     }
   }
   /**
-   * 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 })
    */
   async write(sessionId, values) {
     debug_default("dynamodb store: writing session data %s, %O", sessionId, values);
@@ -72,7 +109,12 @@ var DynamoDBStore = class {
     await this.#client.send(command);
   }
   /**
-   * Cleanup session item by removing it
+   * Removes session data from DynamoDB
+   *
+   * @param sessionId - Session identifier to remove
+   *
+   * @example
+   * await store.destroy('sess_abc123')
    */
   async destroy(sessionId) {
     debug_default("dynamodb store: destroying session data %s", sessionId);
@@ -83,7 +125,12 @@ var DynamoDBStore = class {
     await this.#client.send(command);
   }
   /**
-   * Updates the value expiry
+   * Updates the session expiry time in DynamoDB
+   *
+   * @param sessionId - Session identifier
+   *
+   * @example
+   * await store.touch('sess_abc123')
    */
   async touch(sessionId) {
     debug_default("dynamodb store: touching session data %s", sessionId);
@@ -104,4 +151,3 @@ var DynamoDBStore = class {
 export {
   DynamoDBStore
 };
-//# sourceMappingURL=dynamodb-3PG52TE3.js.map

package/build/factories/main.d.ts

@@ -1 +1 @@
-export { SessionMiddlewareFactory } from './session_middleware_factory.js';
+export { SessionMiddlewareFactory } from './session_middleware_factory.ts';

package/build/factories/main.js

@@ -1,12 +1,12 @@
 import {
   defineConfig
-} from "../chunk-WUWXIKIB.js";
+} from "../chunk-MVBWJOEG.js";
 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";
 
 // factories/session_middleware_factory.ts
 import { Emitter } from "@adonisjs/core/events";
@@ -47,4 +47,3 @@ var SessionMiddlewareFactory = class {
 export {
   SessionMiddlewareFactory
 };
-//# sourceMappingURL=main.js.map

package/build/factories/session_middleware_factory.d.ts

@@ -1,7 +1,7 @@
 import { Emitter } from '@adonisjs/core/events';
 import type { EventsList } from '@adonisjs/core/types';
-import SessionMiddleware from '../src/session_middleware.js';
-import type { SessionConfig, SessionStoreFactory } from '../src/types.js';
+import SessionMiddleware from '../src/session_middleware.ts';
+import type { SessionConfig, SessionStoreFactory } from '../src/types.ts';
 /**
  * Exposes the API to create an instance of the session middleware
  * without additional plumbing

package/build/{file-B6QKOZXW.js → file-CCJ5ESE2.js}

@@ -1,18 +1,26 @@
 import {
   debug_default
-} from "./chunk-ZVSEMDIC.js";
+} from "./chunk-SBOMJK4T.js";
 
 // src/stores/file.ts
-import { dirname, join } from "node:path";
-import string from "@poppinss/utils/string";
+import { dirname, join } from "path";
+import string from "@adonisjs/core/helpers/string";
 import { MessageBuilder } from "@adonisjs/core/helpers";
-import { access, mkdir, readFile, rm, writeFile, utimes, stat } from "node:fs/promises";
+import { access, mkdir, readFile, rm, writeFile, utimes, stat } from "fs/promises";
 var FileStore = class {
+  /**
+   * File store configuration
+   */
   #config;
+  /**
+   * Session age/expiry time
+   */
   #age;
   /**
-   * @param {FileStoreConfig} config
-   * @param {string|number}   The age must be in seconds or a time expression
+   * Creates a new file store instance
+   *
+   * @param config - File store configuration
+   * @param age - Session age in seconds or time expression (e.g. '2 hours')
    */
   constructor(config, age) {
     this.#config = config;
@@ -21,12 +29,16 @@ var FileStore = class {
   }
   /**
    * Returns an absolute path to the session id file
+   *
+   * @param sessionId - Session identifier
    */
   #getFilePath(sessionId) {
     return join(this.#config.location, `${sessionId}.txt`);
   }
   /**
-   * Check if a file exists at a given path or not
+   * Checks if a file exists at a given path
+   *
+   * @param path - File path to check
    */
   async #pathExists(path) {
     try {
@@ -37,8 +49,9 @@ var FileStore = class {
     }
   }
   /**
-   * Returns stats for a file and ignoring missing
-   * files.
+   * Returns file stats, ignoring missing files
+   *
+   * @param path - File path to get stats for
    */
   async #stats(path) {
     try {
@@ -49,7 +62,10 @@ var FileStore = class {
     }
   }
   /**
-   * Output file with contents to the given path
+   * Outputs file with contents to the given path, creating directories if needed
+   *
+   * @param path - File path to write to
+   * @param contents - File contents to write
    */
   async #outputFile(path, contents) {
     const pathDirname = dirname(path);
@@ -60,7 +76,12 @@ var FileStore = class {
     await writeFile(path, contents, "utf-8");
   }
   /**
-   * Reads the session data from the disk.
+   * Reads the session data from the disk
+   *
+   * @param sessionId - Session identifier
+   *
+   * @example
+   * const data = await store.read('sess_abc123')
    */
   async read(sessionId) {
     const filePath = this.#getFilePath(sessionId);
@@ -87,6 +108,12 @@ var FileStore = class {
   }
   /**
    * Writes the session data to the disk as a string
+   *
+   * @param sessionId - Session identifier
+   * @param values - Session data to store
+   *
+   * @example
+   * await store.write('sess_abc123', { userId: 123 })
    */
   async write(sessionId, values) {
     debug_default("file store: writing session data %s: %O", sessionId, values);
@@ -96,14 +123,23 @@ var FileStore = class {
   }
   /**
    * Removes the session file from the disk
+   *
+   * @param sessionId - Session identifier
+   *
+   * @example
+   * await store.destroy('sess_abc123')
    */
   async destroy(sessionId) {
     debug_default("file store: destroying session data %s", sessionId);
     await rm(this.#getFilePath(sessionId), { force: true });
   }
   /**
-   * Updates the session expiry by rewriting it to the
-   * persistence store
+   * Updates the session expiry by updating the file's modification time
+   *
+   * @param sessionId - Session identifier
+   *
+   * @example
+   * await store.touch('sess_abc123')
    */
   async touch(sessionId) {
     debug_default("file store: touching session data %s", sessionId);
@@ -113,4 +149,3 @@ var FileStore = class {
 export {
   FileStore
 };
-//# sourceMappingURL=file-B6QKOZXW.js.map

package/build/index.d.ts

@@ -6,9 +6,9 @@
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
-export * as errors from './src/errors.js';
-export { configure } from './configure.js';
-export { Session } from './src/session.js';
-export { stubsRoot } from './stubs/main.js';
-export { defineConfig, stores } from './src/define_config.js';
-export { ReadOnlyValuesStore, ValuesStore } from './src/values_store.js';
+export * as errors from './src/errors.ts';
+export { configure } from './configure.ts';
+export { Session } from './src/session.ts';
+export { stubsRoot } from './stubs/main.ts';
+export { defineConfig, stores } from './src/define_config.ts';
+export { ReadOnlyValuesStore, ValuesStore } from './src/values_store.ts';

package/build/index.js

@@ -3,16 +3,16 @@ import {
   defineConfig,
   stores,
   stubsRoot
-} from "./chunk-WUWXIKIB.js";
+} from "./chunk-MVBWJOEG.js";
 import {
   Session,
   errors_exports
-} from "./chunk-OCQGCVXK.js";
+} from "./chunk-SHD6OX52.js";
 import {
   ReadOnlyValuesStore,
   ValuesStore
-} from "./chunk-TE5JP3SX.js";
-import "./chunk-ZVSEMDIC.js";
+} from "./chunk-HAD4PFFM.js";
+import "./chunk-SBOMJK4T.js";
 export {
   ReadOnlyValuesStore,
   Session,
@@ -23,4 +23,3 @@ export {
   stores,
   stubsRoot
 };
-//# sourceMappingURL=index.js.map

package/build/providers/session_provider.d.ts

@@ -1,5 +1,5 @@
 import type { ApplicationService } from '@adonisjs/core/types';
-import type { Session } from '../src/session.js';
+import type { Session } from '../src/session.ts';
 /**
  * Events emitted by the session class
  */

package/build/providers/session_provider.js

@@ -1,13 +1,13 @@
 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";
 
 // providers/session_provider.ts
 import { configProvider } from "@adonisjs/core";
-import { RuntimeException } from "@poppinss/utils";
+import { RuntimeException } from "@adonisjs/core/exceptions";
 var SessionProvider = class {
   constructor(app) {
     this.app = app;
@@ -49,4 +49,3 @@ var SessionProvider = class {
 export {
   SessionProvider as default
 };
-//# sourceMappingURL=session_provider.js.map

package/build/{redis-CAY24YIA.js → redis-NXJWWWVB.js}

@@ -1,21 +1,37 @@
 import {
   debug_default
-} from "./chunk-ZVSEMDIC.js";
+} from "./chunk-SBOMJK4T.js";
 
 // src/stores/redis.ts
-import string from "@poppinss/utils/string";
+import string from "@adonisjs/core/helpers/string";
 import { MessageBuilder } from "@adonisjs/core/helpers";
 var RedisStore = class {
+  /**
+   * Redis connection instance
+   */
   #connection;
+  /**
+   * Time-to-live in seconds for session expiry
+   */
   #ttlSeconds;
+  /**
+   * 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, age) {
     this.#connection = connection;
     this.#ttlSeconds = string.seconds.parse(age);
     debug_default("initiating redis store");
   }
   /**
-   * Returns file contents. A new file will be created if it's
-   * missing.
+   * Reads session data from Redis
+   *
+   * @param sessionId - Session identifier
+   *
+   * @example
+   * const data = await store.read('sess_abc123')
    */
   async read(sessionId) {
     debug_default("redis store: reading session data %s", sessionId);
@@ -30,7 +46,13 @@ var RedisStore = class {
     }
   }
   /**
-   * Write session values to a file
+   * 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 })
    */
   async write(sessionId, values) {
     debug_default("redis store: writing session data %s, %O", sessionId, values);
@@ -38,14 +60,24 @@ var RedisStore = class {
     await this.#connection.setex(sessionId, this.#ttlSeconds, message);
   }
   /**
-   * Cleanup session file by removing it
+   * Removes session data from Redis
+   *
+   * @param sessionId - Session identifier to remove
+   *
+   * @example
+   * await store.destroy('sess_abc123')
    */
   async destroy(sessionId) {
     debug_default("redis store: destroying session data %s", sessionId);
     await this.#connection.del(sessionId);
   }
   /**
-   * Updates the value expiry
+   * Updates the session expiry time in Redis
+   *
+   * @param sessionId - Session identifier
+   *
+   * @example
+   * await store.touch('sess_abc123')
    */
   async touch(sessionId) {
     debug_default("redis store: touching session data %s", sessionId);
@@ -55,4 +87,3 @@ var RedisStore = class {
 export {
   RedisStore
 };
-//# sourceMappingURL=redis-CAY24YIA.js.map

package/build/src/client.d.ts

@@ -1,37 +1,73 @@
-import type { SessionData, SessionStoreContract } from './types.js';
+import type { SessionData, SessionStoreContract } from './types.ts';
 /**
- * Session client exposes the API to set session data as a client
+ * Session client exposes the API to set session data as a client.
+ * Useful for testing or programmatic session manipulation.
+ *
+ * @example
+ * const client = new SessionClient(store)
+ * client.merge({ userId: 123 })
+ * client.flash({ success: 'Login successful' })
+ * await client.commit()
  */
 export declare class SessionClient {
     #private;
     /**
-     * Session key for setting flash messages
+     * Session key used for storing flash messages
      */
     flashKey: string;
     /**
-     * Session to use when no explicit session id is
-     * defined
+     * Session ID to use when no explicit session id is defined
+     */
+    sessionId: `${string}-${string}-${string}-${string}-${string}`;
+    /**
+     * Creates a new session client
+     *
+     * @param store - Session store contract implementation
      */
-    sessionId: string;
     constructor(store: SessionStoreContract);
     /**
-     * Merge session data
+     * Merges session data with existing values
+     *
+     * @param values - Session data to merge
+     *
+     * @example
+     * client.merge({ userId: 123, theme: 'dark' })
      */
     merge(values: SessionData): this;
     /**
-     * Merge flash messages
+     * 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: SessionData): this;
     /**
-     * Commits data to the session store.
+     * Commits data to the session store
+     *
+     * @example
+     * await client.commit() // Saves all changes to the store
      */
     commit(): Promise<void>;
     /**
-     * Destroys the session data with the store
+     * 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
      */
     destroy(sessionId?: string): Promise<void>;
     /**
      * 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
      */
     load(sessionId?: string): Promise<{
         values: any;

package/build/src/client.js

@@ -1,9 +1,8 @@
 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";
 export {
   SessionClient
 };
-//# sourceMappingURL=client.js.map

package/build/src/define_config.d.ts

@@ -1,8 +1,8 @@
 import type { ConfigProvider } from '@adonisjs/core/types';
 import type { CookieOptions } from '@adonisjs/core/types/http';
-import type { SessionConfig, FileStoreConfig, RedisStoreConfig, SessionStoreFactory, DynamoDBStoreConfig } from './types.js';
+import type { SessionConfig, FileStoreConfig, RedisStoreConfig, SessionStoreFactory, DynamoDBStoreConfig } from './types.ts';
 /**
- * Resolved config with stores
+ * Resolved session configuration with all stores resolved
  */
 type ResolvedConfig<KnownStores extends Record<string, SessionStoreFactory>> = SessionConfig & {
     store: keyof KnownStores;
@@ -10,7 +10,24 @@ type ResolvedConfig<KnownStores extends Record<string, SessionStoreFactory>> = S
     cookie: Partial<CookieOptions>;
 };
 /**
- * Helper to normalize session config
+ * Defines and validates session configuration with store setup.
+ * Handles default values and store resolution.
+ *
+ * @param config - Session configuration with stores
+ *
+ * @example
+ * import { defineConfig, stores } from '@adonisjs/session'
+ *
+ * export default defineConfig({
+ *   enabled: true,
+ *   cookieName: 'adonis_session',
+ *   age: '2 hours',
+ *   store: 'cookie',
+ *   stores: {
+ *     cookie: stores.cookie(),
+ *     redis: stores.redis({ connection: 'main' })
+ *   }
+ * })
  */
 export declare function defineConfig<KnownStores extends Record<string, SessionStoreFactory | ConfigProvider<SessionStoreFactory>>>(config: Partial<SessionConfig> & {
     store: keyof KnownStores | 'memory';
@@ -19,7 +36,23 @@ export declare function defineConfig<KnownStores extends Record<string, SessionS
     [K in keyof KnownStores]: SessionStoreFactory;
 }>>;
 /**
- * Inbuilt stores to store the session data.
+ * Built-in session stores for different storage backends.
+ * Each store provides a different persistence mechanism for session data.
+ *
+ * @example
+ * import { stores } from '@adonisjs/session'
+ *
+ * // File store - stores on filesystem
+ * stores.file({ location: './tmp/sessions' })
+ *
+ * // Redis store - stores in Redis
+ * stores.redis({ connection: 'main' })
+ *
+ * // Cookie store - stores in encrypted cookies
+ * stores.cookie()
+ *
+ * // DynamoDB store - stores in AWS DynamoDB
+ * stores.dynamodb({ tableName: 'Sessions' })
  */
 export declare const stores: {
     file: (config: FileStoreConfig) => ConfigProvider<SessionStoreFactory>;

package/build/src/errors.d.ts

@@ -1,8 +1,24 @@
 /**
- * Raised when session store is not mutable
+ * Error thrown when attempting to mutate a readonly session store.
+ * This occurs when trying to write to a session that was initiated in readonly mode.
+ *
+ * @example
+ * // This will throw E_SESSION_NOT_MUTABLE
+ * await session.initiate(true) // readonly mode
+ * session.put('key', 'value')  // Throws error
  */
-export declare const E_SESSION_NOT_MUTABLE: new (args?: any, options?: ErrorOptions) => import("@poppinss/utils").Exception;
+export declare const E_SESSION_NOT_MUTABLE: new (args?: any, options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;
 /**
- * Raised when session store has been initiated
+ * Error thrown when attempting to use session before it's been initiated.
+ * This usually means the session middleware hasn't been registered or called.
+ *
+ * @example
+ * // This will throw E_SESSION_NOT_READY
+ * const session = new Session(config, storeFactory, emitter, ctx)
+ * session.put('key', 'value') // Throws error - need to call initiate first
+ *
+ * // Correct usage:
+ * await session.initiate(false)
+ * session.put('key', 'value') // Works fine
  */
-export declare const E_SESSION_NOT_READY: new (args?: any, options?: ErrorOptions) => import("@poppinss/utils").Exception;
+export declare const E_SESSION_NOT_READY: new (args?: any, options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;

package/build/src/plugins/edge.d.ts

@@ -1,6 +1,16 @@
 import type { PluginFn } from 'edge.js/types';
 /**
- * The edge plugin for AdonisJS Session adds tags to read
- * flash messages
+ * The edge plugin for AdonisJS Session adds template tags to read flash messages.
+ * Provides @flashMessage, @inputError, @error, and @errors tags for templates.
+ *
+ * @example
+ * // Register the plugin with Edge
+ * import { edgePluginSession } from '@adonisjs/session/plugins/edge'
+ * edge.use(edgePluginSession)
+ *
+ * // Use in templates
+ * @flashMessage('success')
+ *   <div class="alert alert-success">{{ $message }}</div>
+ * @end
  */
 export declare const edgePluginSession: PluginFn<undefined>;

package/build/src/plugins/edge.js

@@ -1,6 +1,6 @@
 import {
   debug_default
-} from "../../chunk-ZVSEMDIC.js";
+} from "../../chunk-SBOMJK4T.js";
 
 // src/plugins/edge.ts
 var edgePluginSession = (edge) => {
@@ -123,4 +123,3 @@ var edgePluginSession = (edge) => {
 export {
   edgePluginSession
 };
-//# sourceMappingURL=edge.js.map