@h3ravel/session 0.1.0-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,774 @@
+/// <reference path="./app.globals.d.ts" />
+import * as _h3ravel_contracts0 from "@h3ravel/contracts";
+import { IApplication, IHttpContext, ISessionDriver, ISessionManager, SessionDriverBuilder, SessionDriverOption } from "@h3ravel/contracts";
+import { Command } from "@h3ravel/musket";
+import { ServiceProvider } from "@h3ravel/support";
+
+//#region src/adapters.d.ts
+/**
+ * FileDriver builder
+ * constructor(sessionId: string, sessionDir?: string, cwd?: string)
+ */
+declare const fileBuilder: SessionDriverBuilder;
+/**
+ * DatabaseDriver builder
+ * constructor(sessionId: string, table?: string)
+ */
+declare const dbBuilder: SessionDriverBuilder;
+/**
+ * MemoryDriver builder
+ * constructor(sessionId: string)
+ */
+declare const memoryBuilder: SessionDriverBuilder;
+/**
+ * RedisDriver builder
+ * constructor(sessionId: string, redisClient?: RedisClient, prefix?: string)
+ */
+declare const redisBuilder: SessionDriverBuilder;
+//#endregion
+//#region src/Commands/MakeSessionTableCommand.d.ts
+declare class MakeSessionTableCommand extends Command {
+  /**
+   * The name and signature of the console command.
+   *
+   * @var string
+   */
+  protected signature: string;
+  /**
+   * The console command description.
+   *
+   * @var string
+   */
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+//#region src/Encryption.d.ts
+declare class Encryption {
+  private key;
+  constructor();
+  /**
+   * Encrypt session data using AES-256-CBC and the APP_KEY.
+   */
+  encrypt(value: any): string;
+  /**
+   * Decrypt session data.
+   */
+  decrypt(value: any): any;
+}
+//#endregion
+//#region src/FlashBag.d.ts
+/**
+ * FlashBag
+ *
+ * Manages flash data for session management, handling temporary data
+ * that persists for one request cycle.
+ */
+declare class FlashBag {
+  /**
+   * Storage for flash data
+   *
+   * Structure:
+   * {
+   *   new: { key1: value1, key2: value2 },
+   *   old: { key3: value3, key4: value4 }
+   * }
+   */
+  private flashData;
+  /**
+   * Flash a value for the next request
+   *
+   * @param key Key to store in flash
+   * @param value Value to be flashed
+   */
+  flash(key: string, value: any): void;
+  /**
+   * Store a temporary value for the current request only
+   *
+   * @param key Key to store
+   * @param value Value to store
+   */
+  now(key: string, value: any): void;
+  /**
+   * Reflash all current flash data for another request cycle
+   */
+  reflash(): void;
+  /**
+   * Keep only specific flash keys for the next request
+   *
+   * @param keys Keys to keep
+   */
+  keep(keys: string[]): void;
+  /**
+   * Age flash data at the end of the request
+   *
+   * - Removes old flash data
+   * - Moves new flash data to old
+   * - Clears new flash data
+   */
+  ageFlashData(): void;
+  /**
+   * Get a flash value
+   *
+   * @param key Key to retrieve
+   * @param defaultValue Default value if key doesn't exist
+   * @returns Flash value or default
+   */
+  get(key: string, defaultValue?: any): any;
+  /**
+   * Check if a flash key exists
+   *
+   * @param key Key to check
+   * @returns Boolean indicating existence
+   */
+  has(key: string): boolean;
+  /**
+   * Get all flash data
+   *
+   * @returns Combined flash data
+   */
+  all(): Record<string, any>;
+  /**
+   * Get all flash data keys
+   *
+   * @returns Combined flash data
+   */
+  keys(): string[];
+  /**
+   * Get the raww flash data
+   *
+   * @returns raw flash data
+   */
+  raw(): Record<string, any>;
+  /**
+   * Clear all flash data
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/drivers/Driver.d.ts
+/**
+ * Driver
+ *
+ * Base Session driver.
+ */
+declare abstract class Driver extends ISessionDriver {
+  protected encryptor: Encryption;
+  protected sessionId: string;
+  flashBag: FlashBag;
+  /**
+   * Invalidate session completely and regenerate empty session.
+   */
+  abstract invalidate(): void;
+  /**
+   * Fetch current payload
+   *
+   * @returns
+   */
+  protected abstract fetchPayload<T extends Record<string, any>>(loadFlash?: boolean): T | Promise<T>;
+  /**
+   * Save updated payload
+   *
+   * @param payload
+   */
+  protected abstract savePayload(payload: Record<string, any>): void | Promise<void>;
+  /**
+   * Save the raw session payload (session + flash)
+   */
+  private saveRawPayload;
+  /**
+   * Retrieve all data from the session including flash
+   *
+   * @returns
+   */
+  getAll<T = any>(): T | Promise<T>;
+  /**
+   * Retrieve a value from the session
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  get<T = any>(key: string, defaultValue?: any): T | Promise<T>;
+  /**
+   * Store a value in the session
+   *
+   * @param key
+   * @param value
+   */
+  set(value: Record<string, any>): void | Promise<void>;
+  /**
+   * Store multiple key/value pairs
+   *
+   * @param values
+   */
+  put(key: string, value: any): void | Promise<void>;
+  /**
+   * Append a value to an array key
+   *
+   * @param key
+   * @param value
+   */
+  push(key: string, value: any): void | Promise<void>;
+  /**
+   * Remove a key from the session
+   *
+   * @param key
+   */
+  forget(key: string): void | Promise<void>;
+  /**
+   * Retrieve all session data
+   *
+   * @returns
+   */
+  all<T extends Record<string, any>>(): T | Promise<T>;
+  /**
+   * Determine if a key exists (even if null).
+   *
+   * @param key
+   * @returns
+   */
+  exists(key: string): boolean | Promise<boolean>;
+  /**
+   * Determine if a key has a non-null value.
+   *
+   * @param key
+   * @returns
+   */
+  has(key: string): boolean | Promise<boolean>;
+  /**
+   * Get only specific keys.
+   *
+   * @param keys
+   * @returns
+   */
+  only<T extends Record<string, any>>(keys: string[]): T | Promise<T>;
+  /**
+   * Return all keys except the specified ones.
+   *
+   * @param keys
+   * @returns
+   */
+  except<T extends Record<string, any>>(keys: string[]): T | Promise<T>;
+  /**
+   * Return and delete a key from the session.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  pull<T = any>(key: string, defaultValue?: any): T | Promise<T>;
+  /**
+   * Increment a numeric value by amount (default 1).
+   *
+   * @param key
+   * @param amount
+   * @returns
+   */
+  increment(key: string, amount?: number): number | Promise<number>;
+  /**
+   * Decrement a numeric value by amount (default 1).
+   *
+   * @param key
+   * @param amount
+   * @returns
+   */
+  decrement(key: string, amount?: number): number | Promise<number>;
+  /**
+   * Flash a value for next request only.
+   *
+   * @param key
+   * @param value
+   */
+  flash(key: string, value: any): void | Promise<void>;
+  /**
+   * Reflash all flash data for one more cycle.
+   *
+   * @returns
+   */
+  reflash(): void | Promise<void>;
+  /**
+   * Keep only selected flash data.
+   *
+   * @param keys
+   * @returns
+   */
+  keep(keys: string[]): void | Promise<void>;
+  /**
+   * Store a temporary value (flash) for this request only (not persisted)
+   *
+   * @param key
+   * @param value
+   */
+  now(key: string, value: any): void | Promise<void>;
+  /**
+   * Regenerate session ID and persist data under new ID.
+   */
+  regenerate(): void | Promise<void>;
+  /**
+   * Age flash data at the end of the request lifecycle.
+   */
+  ageFlashData(): void | Promise<void>;
+  /**
+   * Determine if an item is not present in the session.
+   *
+   * @param key
+   * @returns
+   */
+  missing(key: string): boolean | Promise<boolean>;
+  /**
+   * Flush all session data
+   */
+  flush(): void | Promise<void>;
+}
+//#endregion
+//#region src/drivers/DatabaseDriver.d.ts
+/**
+ * DatabaseDriver
+ *
+ * Stores sessions in a database table. Each session ID maps to a row.
+ * The `payload` column contains all session key/value pairs as JSON.
+ */
+declare class DatabaseDriver extends Driver implements ISessionDriver {
+  protected sessionId: string;
+  private table;
+  /**
+   *
+   * @param sessionId The current session ID
+   * @param table
+   */
+  constructor(sessionId: string, table?: string);
+  /**
+   * Get the query builder for this table
+   */
+  private query;
+  /**
+   * Fetch the session payload
+   */
+  protected fetchPayload<T extends Record<string, any>>(): Promise<T>;
+  /**
+   * Save the session payload back to DB
+   */
+  protected savePayload(payload: Record<string, any>): Promise<void>;
+  /**
+   * Retrieve all data from the session including flash
+   */
+  getAll<T = any>(): Promise<T>;
+  /**
+   * Get a value from the session
+   */
+  get<T = any>(key: string, defaultValue?: any): Promise<T>;
+  /**
+   * Set one or multiple session values
+   */
+  set(values: Record<string, any>): Promise<void>;
+  /**
+   * Store a single key/value pair
+   */
+  put(key: string, value: any): Promise<void>;
+  /**
+   * Append a value to an array key
+   */
+  push(key: string, value: any): Promise<void>;
+  /**
+   * Forget a session key
+   */
+  forget(key: string): Promise<void>;
+  /**
+   * Retrieve all session data (excluding flash)
+   */
+  all<T extends Record<string, any>>(): Promise<T>;
+  /**
+   * Determine if a key exists (even if null)
+   */
+  exists(key: string): Promise<boolean>;
+  /**
+   * Determine if a key has a non-null value
+   */
+  has(key: string): Promise<boolean>;
+  /**
+   * Get only specific keys
+   */
+  only<T extends Record<string, any>>(keys: string[]): Promise<T>;
+  /**
+   * Return all except specific keys
+   */
+  except<T extends Record<string, any>>(keys: string[]): Promise<T>;
+  /**
+   * Retrieve and delete a value
+   */
+  pull(key: string, defaultValue?: any): Promise<any>;
+  /**
+   * Increment a numeric value
+   */
+  increment(key: string, amount?: number): Promise<number>;
+  /**
+   * Decrement a numeric value
+   */
+  decrement(key: string, amount?: number): Promise<number>;
+  /**
+   * Flash a value for next request only
+   */
+  flash(key: string, value: any): Promise<void>;
+  /**
+   * Reflash all flash data for one more cycle
+   */
+  reflash(): Promise<void>;
+  /**
+   * Keep only specific flash keys
+   */
+  keep(keys: string[]): Promise<void>;
+  /**
+   * Store a temporary value (flash) for this request only (not persisted)
+   */
+  now(key: string, value: any): Promise<void>;
+  /**
+   * Regenerate session ID with same data
+   */
+  regenerate(): Promise<void>;
+  /**
+   * Check if a key is missing
+   */
+  missing(key: string): Promise<boolean>;
+  /**
+   * Flush all session data
+   */
+  flush(): Promise<void>;
+  /**
+   * Invalidate the session and regenerate
+   */
+  invalidate(): Promise<void>;
+  /**
+   * Age flash data at the end of the request lifecycle.
+   */
+  ageFlashData(): Promise<void>;
+}
+//#endregion
+//#region src/drivers/FileDriver.d.ts
+/**
+ * FileDriver
+ *
+ * Stores session data as encrypted JSON files.
+ * Each session is stored in its own file named after the session ID.
+ * Ideal for local development or low-scale deployments.
+ */
+declare class FileDriver extends Driver implements ISessionDriver {
+  protected sessionId: string;
+  private sessionDir;
+  private cwd;
+  constructor(sessionId: string, sessionDir?: string, cwd?: string);
+  /**
+   * Ensures the session file exists and is initialized.
+   */
+  private ensureSessionFile;
+  /**
+   * Get the absolute path for the current session file.
+   */
+  private sessionFilePath;
+  /**
+   * Read raw decrypted payload (including _flash).
+   */
+  private readRawPayload;
+  /**
+   * Fetch decrypted payload and strip out flash metadata.
+   */
+  protected fetchPayload<T extends Record<string, any>>(): T;
+  /**
+   * Write and encrypt session data to file.
+   * Always persists flash state.
+   *
+   * @param data
+   */
+  protected savePayload(payload: Record<string, any>): void;
+  /**
+   * Completely invalidate the current session and regenerate a new one.
+   */
+  invalidate(): void;
+}
+//#endregion
+//#region src/drivers/MemoryDriver.d.ts
+/**
+ * MemoryDriver
+ *
+ * Lightweight, ephemeral session storage.
+ * Intended for tests, local development, or short-lived apps.
+ */
+declare class MemoryDriver extends Driver implements ISessionDriver {
+  protected sessionId: string;
+  private static store;
+  constructor(sessionId: string);
+  /**
+   * Fetch and return session payload.
+   *
+   * @returns Decrypted and usable payload
+   */
+  protected fetchPayload<T extends Record<string, any>>(): T;
+  /**
+   * Persist session payload and flash bag state.
+   *
+   * @param data
+   */
+  protected savePayload(payload: Record<string, any>): void;
+  /**
+   * Invalidate current session and regenerate new session ID.
+   */
+  invalidate(): void;
+}
+//#endregion
+//#region src/drivers/RedisDriver.d.ts
+/**
+ * RedisDriver (placeholder)
+ */
+declare class RedisDriver extends Driver implements ISessionDriver {
+  /**
+   * The current session ID
+   */
+  protected sessionId: string;
+  protected redisClient?: "RedisClient" | undefined;
+  protected prefix?: string | undefined;
+  private static store;
+  constructor(
+  /**
+   * The current session ID
+   */
+  sessionId: string, redisClient?: "RedisClient" | undefined, prefix?: string | undefined);
+  /**
+   * Fetch and return session payload.
+   *
+   * @returns Decrypted and usable payload
+   */
+  protected fetchPayload<T extends Record<string, any>>(): T;
+  /**
+   * Persist session payload and flash bag state.
+   *
+   * @param data
+   */
+  protected savePayload(_payload: Record<string, any>): void;
+  /**
+   * Invalidate current session and regenerate new session ID.
+   */
+  invalidate(): void;
+}
+//#endregion
+//#region src/Providers/SessionServiceProvider.d.ts
+declare class SessionServiceProvider extends ServiceProvider {
+  static priority: number;
+  static order: string;
+  register(): void;
+}
+//#endregion
+//#region src/SessionManager.d.ts
+/**
+ * SessionManager
+ *
+ * Handles session initialization, ID generation, and encryption.
+ * Each request gets a unique session namespace tied to its ID.
+ */
+declare class SessionManager extends ISessionManager {
+  private app;
+  private ctx;
+  private driver;
+  private appKey;
+  private sessionId;
+  private request;
+  flashBag: FlashBag;
+  /**
+   * @param ctx - incoming request http context
+   * @param driverName - registered driver key ('file' | 'database' | 'memory' | 'redis')
+   * @param driverOptions - optional bag for driver-specific options
+   */
+  constructor(app?: IApplication, driverName?: 'file' | 'memory' | 'database' | 'redis', driverOptions?: SessionDriverOption);
+  constructor(app?: IHttpContext | IApplication, driverName?: 'file' | 'memory' | 'database' | 'redis', driverOptions?: SessionDriverOption);
+  /**
+   * Initialize the Session Manager
+   *
+   * @param ctx
+   * @returns
+   */
+  static init(app: IApplication): SessionManager;
+  /**
+   * Generate a secure session ID unique to the user device.
+   */
+  private generateSessionId;
+  /**
+   * Resolve the session ID from cookie, header, or create a new one.
+   */
+  private resolveSessionId;
+  /**
+   * Access the current session ID.
+   */
+  id(): string;
+  /**
+   * Get the current session driver
+   */
+  getDriver(): ISessionDriver;
+  /**
+   * Retrieve a value from the session
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  get(key: string, defaultValue?: any): Promise<any> | any;
+  /**
+   * Store a value in the session
+   *
+   * @param key
+   * @param value
+   */
+  set(value: Record<string, any>): Promise<void> | void;
+  /**
+   * Store multiple key/value pairs
+   *
+   * @param values
+   */
+  put(key: string, value: any): void | Promise<void>;
+  /**
+   * Append a value to an array key
+   *
+   * @param key
+   * @param value
+   */
+  push(key: string, value: any): void | Promise<void>;
+  /**
+   * Remove a key from the session
+   *
+   * @param key
+   */
+  forget(key: string): void | Promise<void>;
+  /**
+   * Retrieve all session data
+   *
+   * @returns
+   */
+  all(): Record<string, any> | Promise<Record<string, any>>;
+  /**
+   * Determine if a key exists (even if null).
+   *
+   * @param key
+   * @returns
+   */
+  exists(key: string): Promise<boolean> | boolean;
+  /**
+   * Determine if a key has a non-null value.
+   *
+   * @param key
+   * @returns
+   */
+  has(key: string): Promise<boolean> | boolean;
+  /**
+   * Get only specific keys.
+   *
+   * @param keys
+   * @returns
+   */
+  only(keys: string[]): Record<string, any> | Promise<Record<string, any>>;
+  /**
+   * Return all keys except the specified ones.
+   *
+   * @param keys
+   * @returns
+   */
+  except(keys: string[]): Record<string, any> | Promise<Record<string, any>>;
+  /**
+   * Return and delete a key from the session.
+   *
+   * @param key
+   * @param defaultValue
+   * @returns
+   */
+  pull(key: string, defaultValue?: any): any;
+  /**
+   * Increment a numeric value by amount (default 1).
+   *
+   * @param key
+   * @param amount
+   * @returns
+   */
+  increment(key: string, amount?: number): Promise<number> | number;
+  /**
+   * Decrement a numeric value by amount (default 1).
+   *
+   * @param key
+   * @param amount
+   * @returns
+   */
+  decrement(key: string, amount?: number): number | Promise<number>;
+  /**
+   * Flash a value for next request only.
+   *
+   * @param key
+   * @param value
+   */
+  flash(key: string, value: any): void | Promise<void>;
+  /**
+   * Reflash all flash data for one more cycle.
+   *
+   * @returns
+   */
+  reflash(): void | Promise<void>;
+  /**
+   * Keep only selected flash data.
+   *
+   * @param keys
+   * @returns
+   */
+  keep(keys: string[]): void | Promise<void>;
+  /**
+   * Store data only for current request cycle (not persisted).
+   *
+   * @param key
+   * @param value
+   */
+  now(key: string, value: any): void | Promise<void>;
+  /**
+   * Regenerate session ID and persist data under new ID.
+   */
+  regenerate(): void | Promise<void>;
+  /**
+   * Determine if an item is not present in the session.
+   *
+   * @param key
+   * @returns
+   */
+  missing(key: string): Promise<boolean> | boolean;
+  /**
+   * Flush all session data
+   */
+  flush(): void | Promise<void>;
+  /**
+   * Invalidate the session completely and regenerate ID.
+   *
+   * @returns
+   */
+  invalidate(): void | Promise<void>;
+  /**
+   * Age flash data at the end of the request lifecycle.
+   *
+   * @returns
+   */
+  ageFlashData(): void | Promise<void>;
+}
+//#endregion
+//#region src/SessionStore.d.ts
+/**
+ * SessionStore (Driver registry)
+ *
+ * Register driver builders under a name and then create instances using:
+ *   SessionStore.make('file', sessionId, options)
+ */
+declare class SessionStore {
+  private static registry;
+  /**
+   * Register a driver builder under a key (e.g. 'file', 'database', 'memory').
+   */
+  static register(name: 'file' | 'memory' | 'database' | 'redis', builder: SessionDriverBuilder): void;
+  /**
+   * Create a driver instance for the given sessionId using the named builder.
+   *
+   * If driver not found, throws. Options is a simple key/value bag passed to the builder.
+   */
+  static make(name: 'file' | 'memory' | 'database' | 'redis', sessionId: string, options?: SessionDriverOption): _h3ravel_contracts0.ISessionDriver;
+}
+//#endregion
+export { DatabaseDriver, Driver, Encryption, FileDriver, FlashBag, MakeSessionTableCommand, MemoryDriver, RedisDriver, SessionManager, SessionServiceProvider, SessionStore, dbBuilder, fileBuilder, memoryBuilder, redisBuilder };