doc: update docblocks

Author: thetutlage

modules/access_tokens_guard/define_config.ts

@@ -21,6 +21,16 @@ import type {
 
 /**
  * Configures access tokens guard for authentication
+ *
+ * @param config - Configuration object containing the user provider
+ *
+ * @example
+ * const guard = tokensGuard({
+ *   provider: tokensUserProvider({
+ *     model: () => import('#models/user'),
+ *     tokens: 'accessTokens'
+ *   })
+ * })
  */
 export function tokensGuard<
   UserProvider extends AccessTokensUserProviderContract<unknown>,
@@ -40,6 +50,14 @@ export function tokensGuard<
 /**
  * Configures user provider that uses Lucid models to verify
  * access tokens and find users during authentication.
+ *
+ * @param config - Configuration options for the Lucid user provider
+ *
+ * @example
+ * const userProvider = tokensUserProvider({
+ *   model: () => import('#models/user'),
+ *   tokens: 'accessTokens'
+ * })
  */
 export function tokensUserProvider<
   TokenableProperty extends string,

modules/access_tokens_guard/types.ts

@@ -128,12 +128,16 @@ export type AccessTokenDbColumns = {
 }
 
 /**
- * Access token providers are used verify an access token
- * during authentication
+ * Access token providers are used to verify an access token
+ * during authentication and manage token lifecycle
  */
 export interface AccessTokensProviderContract<Tokenable extends LucidModel> {
   /**
    * Create a token for a given user
+   *
+   * @param user - The user instance to create a token for
+   * @param abilities - Optional array of abilities the token should have
+   * @param options - Optional token configuration including name and expiration
    */
   create(
     user: InstanceType<Tokenable>,
@@ -147,11 +151,15 @@ export interface AccessTokensProviderContract<Tokenable extends LucidModel> {
   /**
    * Verifies a publicly shared access token and returns an
    * access token for it.
+   *
+   * @param tokenValue - The token value to verify
    */
   verify(tokenValue: Secret<string>): Promise<AccessToken | null>
 
   /**
    * Invalidates a token identified by its publicly shared token
+   *
+   * @param tokenValue - The token value to invalidate
    */
   invalidate(tokenValue: Secret<string>): Promise<boolean>
 }
@@ -182,11 +190,18 @@ export type AccessTokensLucidUserProviderOptions<
  * and the guard.
  *
  * The guard is user provider agnostic and therefore it
- * needs a adapter to known some basic info about the
+ * needs an adapter to know some basic info about the
  * user.
  */
 export type AccessTokensGuardUser<RealUser> = {
+  /**
+   * Get the unique identifier for the user
+   */
   getId(): string | number | BigInt
+
+  /**
+   * Get the original user object from the provider
+   */
   getOriginal(): RealUser
 }
 
@@ -200,11 +215,17 @@ export interface AccessTokensUserProviderContract<RealUser> {
   /**
    * Create a user object that acts as an adapter between
    * the guard and real user value.
+   *
+   * @param user - The real user object from the provider
    */
   createUserForGuard(user: RealUser): Promise<AccessTokensGuardUser<RealUser>>
 
   /**
    * Create a token for a given user
+   *
+   * @param user - The user to create a token for
+   * @param abilities - Optional array of abilities the token should have
+   * @param options - Optional token configuration including name and expiration
    */
   createToken(
     user: RealUser,
@@ -217,16 +238,22 @@ export interface AccessTokensUserProviderContract<RealUser> {
 
   /**
    * Invalidates a token identified by its publicly shared token.
+   *
+   * @param tokenValue - The token value to invalidate
    */
   invalidateToken(tokenValue: Secret<string>): Promise<boolean>
 
   /**
    * Find a user by the user id.
+   *
+   * @param identifier - The unique identifier of the user
    */
   findById(identifier: string | number | BigInt): Promise<AccessTokensGuardUser<RealUser> | null>
 
   /**
    * Verify a token by its publicly shared value.
+   *
+   * @param tokenValue - The token value to verify
    */
   verifyToken(tokenValue: Secret<string>): Promise<AccessToken | null>
 }

modules/basic_auth_guard/define_config.ts

@@ -20,7 +20,16 @@ import type {
 } from './types.ts'
 
 /**
- * Configures basic auth guard for authentication
+ * Configures basic auth guard for authentication using HTTP Basic Authentication
+ *
+ * @param config - Configuration object containing the user provider
+ *
+ * @example
+ * const guard = basicAuthGuard({
+ *   provider: basicAuthUserProvider({
+ *     model: () => import('#models/user')
+ *   })
+ * })
  */
 export function basicAuthGuard<
   UserProvider extends BasicAuthUserProviderContract<unknown>,
@@ -39,7 +48,14 @@ export function basicAuthGuard<
 
 /**
  * Configures user provider that uses Lucid models to authenticate
- * users using basic auth
+ * users using basic auth credentials
+ *
+ * @param config - Configuration options for the Lucid user provider
+ *
+ * @example
+ * const userProvider = basicAuthUserProvider({
+ *   model: () => import('#models/user')
+ * })
  */
 export function basicAuthUserProvider<Model extends LucidAuthenticatable>(
   config: BasicAuthLucidUserProviderOptions<Model>

modules/basic_auth_guard/guard.ts

@@ -91,6 +91,22 @@ export class BasicAuthGuard<
    */
   user?: UserProvider[typeof PROVIDER_REAL_USER]
 
+  /**
+   * Creates a new BasicAuthGuard instance
+   *
+   * @param name - Unique name for the guard instance
+   * @param ctx - HTTP context for the current request
+   * @param emitter - Event emitter for guard events
+   * @param userProvider - User provider for credential verification
+   *
+   * @example
+   * const guard = new BasicAuthGuard(
+   *   'basic',
+   *   ctx,
+   *   emitter,
+   *   new BasicAuthLucidUserProvider()
+   * )
+   */
   constructor(
     name: string,
     ctx: HttpContext,
@@ -143,6 +159,12 @@ export class BasicAuthGuard<
   /**
    * Returns an instance of the authenticated user. Or throws
    * an exception if the request is not authenticated.
+   *
+   * @throws {E_UNAUTHORIZED_ACCESS} When user is not authenticated
+   *
+   * @example
+   * const user = guard.getUserOrFail()
+   * console.log('User:', user.email)
    */
   getUserOrFail(): UserProvider[typeof PROVIDER_REAL_USER] {
     if (!this.user) {
@@ -158,7 +180,15 @@ export class BasicAuthGuard<
    * Authenticates the incoming HTTP request by looking for BasicAuth
    * credentials inside the request authorization header.
    *
-   * Returns the authenticated user or throws an exception.
+   * @throws {E_UNAUTHORIZED_ACCESS} When authentication fails
+   *
+   * @example
+   * try {
+   *   const user = await guard.authenticate()
+   *   console.log('Authenticated as:', user.email)
+   * } catch (error) {
+   *   console.log('Authentication failed')
+   * }
    */
   async authenticate(): Promise<UserProvider[typeof PROVIDER_REAL_USER]> {
     /**
@@ -205,6 +235,12 @@ export class BasicAuthGuard<
    *
    * The method returns a boolean indicating if the authentication
    * succeeded or failed.
+   *
+   * @example
+   * const isAuthenticated = await guard.check()
+   * if (isAuthenticated) {
+   *   console.log('User is authenticated:', guard.user.email)
+   * }
    */
   async check(): Promise<boolean> {
     try {
@@ -220,8 +256,15 @@ export class BasicAuthGuard<
   }
 
   /**
-   * Does not support authenticating as client. Instead use "basicAuth"
-   * helper on Japa APIClient
+   * Returns the Authorization header clients can use to authenticate
+   * the request using basic auth.
+   *
+   * @param uid - The username or user identifier
+   * @param password - The user's password
+   *
+   * @example
+   * const clientAuth = await guard.authenticateAsClient('[email protected]', 'secret')
+   * // Use clientAuth.headers.authorization in API tests
    */
   async authenticateAsClient(uid: string, password: string): Promise<AuthClientResponse> {
     return {

modules/basic_auth_guard/types.ts

@@ -20,6 +20,9 @@ export type LucidAuthenticatable = LucidModel & {
   /**
    * Verify credentials method should return the user instance
    * or throw an exception
+   *
+   * @param uid - The username or user identifier
+   * @param password - The password to verify
    */
   verifyCredentials(uid: string, password: string): Promise<InstanceType<LucidAuthenticatable>>
 }
@@ -41,11 +44,18 @@ export type BasicAuthLucidUserProviderOptions<Model extends LucidAuthenticatable
  * and the guard.
  *
  * The guard is user provider agnostic and therefore it
- * needs a adapter to known some basic info about the
+ * needs an adapter to know some basic info about the
  * user.
  */
 export type BasicAuthGuardUser<RealUser> = {
+  /**
+   * Get the unique identifier for the user
+   */
   getId(): string | number | BigInt
+
+  /**
+   * Get the original user object from the provider
+   */
   getOriginal(): RealUser
 }
 
@@ -59,12 +69,17 @@ export interface BasicAuthUserProviderContract<RealUser> {
   /**
    * Create a user object that acts as an adapter between
    * the guard and real user value.
+   *
+   * @param user - The real user object from the provider
    */
   createUserForGuard(user: RealUser): Promise<BasicAuthGuardUser<RealUser>>
 
   /**
    * Verify user credentials and must return an instance of the
    * user back or null when the credentials are invalid
+   *
+   * @param uid - The username or user identifier
+   * @param password - The password to verify
    */
   verifyCredentials(uid: string, password: string): Promise<BasicAuthGuardUser<RealUser> | null>
 }

modules/basic_auth_guard/user_providers/lucid.ts

@@ -57,6 +57,10 @@ export class BasicAuthLucidUserProvider<
   /**
    * Imports the model from the provider, returns and caches it
    * for further operations.
+   *
+   * @example
+   * const UserModel = await provider.getModel()
+   * const user = await UserModel.find(1)
    */
   protected async getModel() {
     if (this.model && !('hot' in import.meta)) {
@@ -70,6 +74,12 @@ export class BasicAuthLucidUserProvider<
 
   /**
    * Creates an adapter user for the guard
+   *
+   * @param user - The user model instance
+   *
+   * @example
+   * const guardUser = await provider.createUserForGuard(user)
+   * console.log('User ID:', guardUser.getId())
    */
   async createUserForGuard(
     user: InstanceType<UserModel>
@@ -102,6 +112,15 @@ export class BasicAuthLucidUserProvider<
 
   /**
    * Verifies credentials using the underlying model
+   *
+   * @param uid - The username or user identifier
+   * @param password - The password to verify
+   *
+   * @example
+   * const guardUser = await provider.verifyCredentials('[email protected]', 'secret')
+   * if (guardUser) {
+   *   console.log('Valid credentials')
+   * }
    */
   async verifyCredentials(
     uid: string,

modules/session_guard/define_config.ts

@@ -22,7 +22,17 @@ import type {
 } from './types.ts'
 
 /**
- * Configures session tokens guard for authentication
+ * Configures session guard for authentication using HTTP sessions
+ *
+ * @param config - Configuration object containing the user provider and session options
+ *
+ * @example
+ * const guard = sessionGuard({
+ *   useRememberMeTokens: false,
+ *   provider: sessionUserProvider({
+ *     model: () => import('#models/user')
+ *   })
+ * })
  */
 export function sessionGuard<
   UseRememberTokens extends boolean,
@@ -47,6 +57,13 @@ export function sessionGuard<
 /**
  * Configures user provider that uses Lucid models to authenticate
  * users using sessions
+ *
+ * @param config - Configuration options for the Lucid user provider
+ *
+ * @example
+ * const userProvider = sessionUserProvider({
+ *   model: () => import('#models/user')
+ * })
  */
 export function sessionUserProvider<Model extends LucidAuthenticatable>(
   config: SessionLucidUserProviderOptions<Model>