DEV Community: Chukwuemeka Maduekwe

Securing Your App with Access and Refresh Tokens: A Practical Guide

Chukwuemeka Maduekwe — Thu, 19 Feb 2026 09:25:47 +0000

My Journey: From Naive to Secure Authentication
Let me be honest about how I handled authentication early in my career. Like many developers, I started with approaches that seemed reasonable but had serious flaws.

The Sessions I Built (And Why They Failed)
Approach #1: The Stateless Session
I would normally issue a token when users logged in, store it in session storage, and call it a day. The moment they closed the tab, poof! Session gone, everyone is happy (actually only the developer — myself). My server never tracked anything. Clean and simple, right? Wrong. Users couldn’t stay logged in across devices. Opening the app on mobile after using it on desktop meant logging in again. The experience was frustrating, and I knew something was off.

Approach #2: The Single Token
Then I switched gears. One token per user, stored server-side with an expiration that refreshed on each API call. Users could reuse this token across multiple devices. For some projects, I’d create a JWT signed with a session ID, valid for 180 days. So once a user is created a token or what I call session is generated and inserted into the users table (wrong place to be to begin with).

Better, but this approach was still problematic and worse — incriminating. If that token ever get leaked or stolen, the attacker or malicious user would have access for months. Revoking it meant forcing users to log in again everywhere. There had to be a better way I said to myself? That better way exists, and it’s what major platforms like GitHub, Google, Spotify and many more websites use: the access and refresh token pattern. Once I understood it, I slept better knowing my users’ accounts were truly protected, at least for the moment.

Understanding the Two-Token System
Rather than drown you in theory, let me explain this through real-world analogies that finally made it click for me.

Access Token: Your Temporary Badge
Think of an access token as biometric verification at a bank. When you walk up to a teller or customer service rep, they scan your fingerprint. For the next few minutes you’ll be with them while you’re conducting business with that specific bank staff, they don’t need to re-verify you. They know who you are. So for every question/request you ask/make they do not need re-scan your fingerprint before providing an answer.

But the moment you dare move to a different teller who wasn’t part of that initial verification, the verification process starts over — fraustrating? Yes, I know, but simpley put your “access” has expired.

So technically, an access token is a short-lived credential (typically 5–30 minutes) that proves you’re authorized to access protected resources. It’s issued by an authentication server and contains minimal information about the user, in most cases, its usually just a user ID and a token version. Each API request includes this token in the Authorization: Bearer <token> header, more like a standard way in my opinion to pass this token to the server.

Refresh Token: Your Driver’s License
Now imagine getting your driver’s license. You take tests, prove you can drive, and receive a license valid for several years. When a police officer stops you, they don’t reassess your driving skills (though in most cases I think they should), they simply verify your license is valid.

When your license expires after, let say 5 years, you don’t retake all the tests. You renew it. Your name, date of birth, and other core details stay the same, but you get a new expiration date and license number. The old number is effectively revoked.

That’s exactly how refresh tokens work. They’re long-lived credentials (days to months) used exclusively to obtain new access tokens. When your access token expires, you present your refresh token to get a new one, no password required. The refresh token is only sent to the authentication server, never to resource APIs.

Just a brief note before we go ahead, I would like to point out the difference between an authentication and resource server.

Authentication or Auth Server: Think of it as the bouncer at a club Its only job is to check who you are. You show your ID (username/password, OTP, token). If everything is correct, the bouncer gives you a stamp or wristband (a token). It does NOT serve you drinks, food, or anything else, it only verifies your identity. Examples would Auth0, Keycloak, Firebase Auth, or your own login service. In simple terms its more like a “Who are you?” server that assigns tokens.

Resource Server: Think of it as the bartender inside the club. It doesn’t check your identity; it checks the stamp the bouncer gave you. If your stamp/token is valid, it lets you access the resources inside (Which in this case would be your data, API routes, files, etc.). If the stamp has expired or is fake, the bartender says “No access.”. Example would be an API that returns user profile, payments, dashboard data, etc. We can call this an “Are you allowed to see this?” server that verifies tokens and gives data.

Also note that in today’s world a single server can serve both purposes as we would see in this guide. This was one of the excuse I gave my self initially when I started reading about access/refresh tokens that only big companies use this pattern since it entails running two servers simultaneously

Why Two Tokens Instead of One?

Back to business? You might be still be wondering why this is better than a single token? right, I get that. This is the question I wrestled with for weeks. If both tokens are sent with requests (one in a cookie, one in a header, which we would get to), what’s the point? The answer lies in blast radius and revocation granularity.

  A[User Logs In] --> B[Auth Server Issues Both Tokens]
  B --> C[Access Token: 15 min lifetime]
  B --> D[Refresh Token: 90 day lifetime]
  C --> E[Sent with Every API Request]
  D --> F[Sent Only to Token Endpoint]
  E --> G{Token Stolen via XSS?}
  G --> | Single Token System | H[Attacker Has Access for 90 Days]
  G --> | Two Token System | I[Attacker Has Access for 15 Minutes Max]
  F --> J{Refresh Token Stolen?}
  J --> K[Token Rotation Detects Theft]
  K --> L[Revoke Entire Token Family]

The Security Advantages:

The two-token pattern also dramatically improves user experience. Users stay logged in for weeks without re-entering credentials, while you maintain tight security controls.

Building the System: A Deep Dive

Just to reiterate — everything in this tutorial is framework-agnostic and can be implemented in any tech stack. For context, my personal stack of choice is MongoDB, Rust (Axum), Next.js (React) + TypeScript, and Redis. However, for this article, I’ll be focusing mainly on the backend implementation. In a separate article, we’ll dive into the frontend consumption and the MongoDB schema design.

Having said that, A single server acts as both authentication and resource server, which is the reality for most applications. I would try as much to present this in a Q/A Session format to improve understanding and practicality.

Do You Need to Track Refresh Tokens?

Yes, absolutely. Here’s what you must store:

// models/session.rs

use mongodb::bson::{DateTime, doc, oid::ObjectId};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Session {
    #[serde(rename = "_id", default, skip_serializing_if = "Option::is_none")]
    pub id: Option<ObjectId>,      // MongoDB document ID
    pub token: String,             // SHA-256 hash of the token - no need to indicate token_hash, we don't do password_hash
    pub user_id: String,           // Reference to User's ID in our users collection
    pub family_id: String,         // Groups tokens from same login
    pub create_date: DateTime,     // When the token was created
    pub expiry_date: DateTime,     // When the token expires
    pub revoked: bool,             // If the token has been revoked
    pub used_at: Option<DateTime>, // Detects reuse attacks, easy way to sparate re-used tokens from revoked ones
    pub device_info: String,       // Optional just for logging purposes
}

This gives you:

Security: Hash tokens before storage (like passwords, but with SHA-256)
Revocation: Immediately invalidate compromised tokens
Audit trail: Track when and how tokens are used
Theft detection: Identify when revoked tokens are reused

What do you mean by Token Rotation:

In simple terms its like a key defense that every time someone uses a refresh token:

Issue a new access token and a new refresh token
Mark the old refresh token as “used”
If a used token is presented again, someone is replaying it — revoke the entire token family

1. Access token expires
2. POST /refresh with refresh_token cookie
3. Look up token_hash
4. Found, not used, not expired
5. Mark old token as used_at = now
6. Create new refresh token
7. Return new access token + Set new refresh_token cookie

> Note: If attacker tries to reuse old token...

2. POST /refresh with OLD token
3. Look up token_hash
4. Token marked as used!
5. Revoke entire token family
6. 401 Unauthorized - Re-login required

// utils/auth_utils.rs

pub fn generate_jwt_token(secret: &String, sub: &String, domain: &String, purpose: TokenPurpose) -> Result<(String, Claims), String> {
    let scope = match purpose {
        TokenPurpose::AccessToken => "openid profile read:posts write:comments".to_string(),
        TokenPurpose::EmailVerification => "email-verification".to_string(),
        TokenPurpose::PasswordRecovery => "password-recovery".to_string(),
    };

    let claims = Claims {
        scope,
        sub: sub.to_string(), // User ID (never changes) + token version (Increment on password change/sign out from all devices to invalidate all tokens)
        aud: domain.to_string(), // Audience
        iss: domain.to_string(), // Issuer
        iat: Utc::now().timestamp(), // Issued at
        jti: Uuid::new_v4().to_string(), // Unique token ID
        exp: (Utc::now() + get_jwt_expiry(purpose)).timestamp(), // Expiry
    };

    match encode(
        &Header::new(Algorithm::HS256), // or RS256 if you use RSA keys (recommended in prod)
        &claims,
        &EncodingKey::from_secret(&secret.as_ref()),
    ) {
        Ok(r) => Ok((r, claims)),
        Err(_) => Err("Failed to Generate Token".to_string()),
    }
}

Notice what’s not included: name, email, role. These can change in your database, but JWTs are stateless. Including them creates a security hole that the token won’t reflect updates until it expires. Keep it minimal and lightweight.

Refresh Token (Opaque Random String):

pub fn generate_refresh_token() -> String {
    // For URL-safe Base64, we need: bytes = ceil(char_length * 3 / 4)
    // let byte_size = (char_length * 3 + 3) / 4;
    // let mut raw_bytes = vec![0u8; byte_size];


    // let mut raw_token = [0u8; 48]; // without the vec! the value "48" if coming from a variable must be a constant
    let mut raw_bytes = vec![0u8; 48]; // 384 bits of pure entropy
    // ? Note: rand::thread_rng() is deprecated
    rand::rng().fill_bytes(&mut raw_bytes); // Cryptographically secure

    general_purpose::URL_SAFE_NO_PAD.encode(raw_bytes)

    // Truncate to exact length
    // let encoded = general_purpose::URL_SAFE_NO_PAD.encode(raw_bytes);
    // encoded.chars().take(char_length).collect()
}

This produces 384 bits of randomness, i.e 2³⁸⁴ possible combinations. Even checking a trillion tokens per second, brute-forcing would take longer than the age of the universe.

Why Not UUID?

Many developers reach for UUID v4, but it’s weaker:

xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx

The 4 is always 4 (version indicator): 4 bits wasted
The y is constrained to 8, 9, a, or b: 2 bits wasted
Hyphens add zero entropy
Result: Only 122 bits of actual randomness

That’s 2²⁶² times fewer possibilities than our 384-bit approach. While 122 bits is still large, authentication tokens deserve maximum unpredictability.

Hashing Tokens: SHA-256, Not Bcrypt

In a previous tutorial you might have seen me use Bcrypt to hash user’s password? Yes. You hash passwords with bcrypt or Argon2 because even weak passwords need computational slowness to resist brute-force attacks. Even though we have other mechanism in place to reduce the effectiveness of brute-force attacks by implementing account lockouts. Tokens are different and you’ll see why in a moment.

// utils/auth_utils.rs

// Hash any refresh token (raw Base64 string)
pub fn hash_token(token: &str) -> String {
    // Decode the Base64 back to raw bytes first!
    let raw_bytes = general_purpose::URL_SAFE_NO_PAD.decode(token).expect("Invalid refresh token format"); // or return Result<String>

    let mut hasher = Sha256::new();
    hasher.update(&raw_bytes);
    hex::encode(hasher.finalize())
    // → 64-char hex string ready for DB storage
}

Use SHA-256 because:

Tokens already have 384 bits of entropy — they’re unguessable by design
Database lookups need to be fast because you’re checking this hash on every refresh request
Deterministic: Same input always produces the same hash for database queries, unlike password hashing.

Slow hashing like bcrypt would only hurt performance without adding much security.

The Cookie Question: Is It Safe?

Here’s where confusion peaks. If refresh tokens are in HttpOnly cookies, aren’t they sent with every request? Yes, and that’s completely normal. Every production system that I know of works this way.

Cookie Security Breakdown

// utils/auth_utils.rs

pub fn save_refresh_token_to_cookie(refresh_token: &String) -> String {
    Cookie::build(("SSID", refresh_token))
        .path("/auth/refresh") // Only sent to refresh endpoint not every request
        .secure(true) // Only sent over HTTPS
        .http_only(true) // JavaScript cannot read it
        .same_site(cookie::SameSite::Strict) // Blocks CSRF attacks
        .max_age(CookieDuration::days(REFRESH_TOKEN_EXPIRES_IN)) // cookie Expiry
        .build()
        .to_string()
}

This configuration protects against:

XSS: HttpOnly prevents JavaScript access, even if an attacker injects code.
CSRF: SameSite=Strict ensures cookies only go to your domain
Network sniffing: Secure flag mandates HTTPS
Accidental exposure: Path restriction limits where the cookie travels

Why Not Just Use One Token If Both Are Sent?

This question kept me up at night. Here’s the critical insight I missed: The point isn’t which token travels, it’s how long each one lives and what happens when stolen, moreover refresh only goes to the auth/refresh endpoint.

The Flow in Practice

Let me walk you through exactly what happens in a real session.

What should my Initial Login look like?

1. Enter credentials
2. POST /auth/login
3. alidate Login credentials
4. Find user in by email in database
5. User valid; retruns user data
6. Check if email is verified (returned user data)
7. Get device_info if available in header (optional during session collection insert)
8. Generate refresh token (random)
9. Insert refresh into session collection
10. Generate refresh_token cookie
11. Check if user info is in redis cache 
12. Add user to redis cache (user_id, role, token_version)
13. Generate signed access_token claims (note that you can choose not to have token_version in claims sub)
14. Set cookie (refresh token) in header
15. Add bearer to header (access token) in header
16. Return headers, bearer, name (optional) avatar(optional) to login handler

// services/auth/login_service.rs

pub async fn login_service(state: &AppState, payload: LoginPayload, headers: HeaderMap) -> Result<LoginServiceResponse, String> {
    if let Err(err) = payload.validate() {
        return Err(err.to_string());
    }

    let user_repo = UserRepo::new(&state.database);
    let user = user_repo.find_by_mail(&payload.email).await.map_err(|_| "Invalid Username/Password".to_string())?;

    if let Err(_err) = bcrypt::verify(&payload.password, &user.password) {
        return Err("Invalid Username/Password".to_string());
    }

    if user.email_verified_at.is_none() {
        return Err("Kindly verify your email to proceed".to_string());
    }

    let device_info = auth_utils::get_device_info(&headers);
    let session_repo = SessionRepo::new(&state.database);

    let refresh_token = session_repo
        .insert(&device_info, &user.user_id)
        .await
        .map_err(|_err| "Suspicious activity detected".to_string())?;

    let refresh_token_cookie = auth_utils::save_refresh_token_to_cookie(&refresh_token);

    let cache_user = match redis_utils::get_user(&state.redis, &state.config.app.id, &user.user_id).await {
        Ok(cache_user) => redis_utils::AuthUser {
            role: user.role,
            id: user.user_id.to_string(),
            token_version: cache_user.token_version,
        },

        Err(_) => redis_utils::AuthUser {
            id: user.user_id.to_string(),
            role: user.role,
            token_version: 0,
        },
    };

    redis_utils::set_user(&state.redis, &state.config.app.id, &cache_user).await?;

    let access_token_sub = json!(AccessTokenSubject {
        ssid: cache_user.id,
        token_version: cache_user.token_version,
    })
    .to_string();

    let (access_token, _) = auth_utils::generate_jwt_token(&state.config.app.secret, &access_token_sub, &state.config.client.host, TokenPurpose::AccessToken)
        .map_err(|_| "Failed to generate access token".to_string())?;

    let mut headers = HeaderMap::new();
    headers.insert(header::SET_COOKIE, HeaderValue::from_str(&refresh_token_cookie).unwrap());
    headers.insert(header::AUTHORIZATION, HeaderValue::from_str(&format!("Bearer {}", access_token)).unwrap());

    Ok(LoginServiceResponse {
        headers,
        access_token,
        name: user.name,
        avatar: user.avatar,
    })
}

The refresh token cookie travels along automatically (because SameSite allows same-domain requests), but it’s ignored by resource endpoints. Only the /auth/refresh endpoint cares about it.

So now, what happens when my access token expires?

Generating a new access token is quite similar to the login service with minor tweaks to improve security and better safeguard user’s account. Also,

1. GET or POST /auth/refresh
2. Extract current refresh_token in user's cookie
3. Fetch refresh_token info from session collection
4. Verify that refresh_token has not  expired, been used, or revoked 
5. Generate new refresh_token tied to same family_id and user (notice we did not enforce device info to be the same)
6. Get user data, so we can update user's role in our cache if it has changed (better way to handle it would have been at the time of role update, but this acts like a fallback in case of a direct DB update)
7. Update redis cache
8. Generate access token sub with cached token_version
9. Generate signed access_token claims based on the token sub
10. Generate refresh_token cookie
11. Insert Cookie and Bearer into Headers
12. Return headers and access_token to refresh handler

// services/auth/login_service.rs

let user_repo = UserRepo::new(&state.database);
let session_repo = SessionRepo::new(&state.database);
let refresh_token = auth_utils::get_cookie(&headers, "SSID").ok_or("Missing authorization credentials, Kindly signin to regain access".to_string())?;
let session = session_repo
    .get_by_token(&refresh_token)
    .await
    .map_err(|_| "Token verification failed: Invalid or mismatched token.".to_string())?;

let refresh_has_expired = Utc::now().timestamp_millis() > session.expiry_date.timestamp_millis();
if session.used_at.is_some() || session.revoked || refresh_has_expired {
    session_repo.revoke_token_family(&session.family_id).await?;
    return Err("Token refresh request is blocked by our security policy".to_string());
}

let refresh_token = session_repo
    .refresh_existing_token(&auth_utils::get_device_info(&headers), &session)
    .await
    .map_err(|_err| "Something went wrong. Token refresh failed".to_string())?;

let user = user_repo.find_by_user_id(&session.user_id).await.map_err(|_err| "Failed to retrieve User's info")?;

let cache_user = match redis_utils::get_user(&state.redis, &state.config.app.id, &user.user_id).await {
    Ok(cache_user) => redis_utils::AuthUser {
        role: user.role,
        id: user.user_id.to_string(),
        token_version: cache_user.token_version,
    },

    Err(_) => redis_utils::AuthUser {
        id: user.user_id.to_string(),
        role: user.role,
        token_version: 0,
    },
};

redis_utils::set_user(&state.redis, &state.config.app.id, &cache_user).await?;

let access_token_sub = json!(AccessTokenSubject {
    ssid: cache_user.id,
    token_version: cache_user.token_version,
})
.to_string();

let (access_token, _) = auth_utils::generate_jwt_token(&state.config.app.secret, &access_token_sub, &state.config.client.host, TokenPurpose::AccessToken)
    .map_err(|_| "Failed to generate access token".to_string())?;

let refresh_token_cookie = auth_utils::save_refresh_token_to_cookie(&refresh_token);

let mut headers = HeaderMap::new();
headers.insert(header::SET_COOKIE, HeaderValue::from_str(&refresh_token_cookie).unwrap());
headers.insert(header::AUTHORIZATION, HeaderValue::from_str(&format!("Bearer {}", access_token)).unwrap());

Ok(RefreshServiceResponse { headers, access_token })

Key point: The old refresh token is marked as “used.” If someone tries to reuse it (indicating token theft), the entire token family gets revoked. Both the attacker and the legitimate user must log in again. Annoying for the real user? Yes, but it instantly contains the breach.

Addressing Common Concerns

Can I Store the Access Token in an HttpOnly Cookie Too?

Yes, but this breaks compatibility with: Mobile apps (iOS, Android), Desktop applications, Command-line tools (curl, Postman), Third-party API integrations, GraphQL clients, Server-to-server calls

These clients need to read the access token and manually include it in the Authorization header. HttpOnly cookies are invisible to application code, making this impossible.

The only scenario where access tokens in HttpOnly cookies work is when you control 100% of the client code like a traditional server-rendered web app. For any modern architecture, it’s likely to break.

*When the User Refreshes the Browser, How Do They Get the Access Token?
*

We have three approaches:

Memory + Automatic Refresh (Most Secure): Access token lives only in JavaScript memory (or React state in my case), So on page refresh, it’s gone and the client immediately calls “/auth/refresh” using the HttpOnly cookie, to which the Server returns a new access token and the User never notices the delay
LocalStorage (Accept the XSS Risk): Store access token using localStorage.setItem(‘access_token’, token). Persists across page refreshes. Risk: If an attacker injects JavaScript, they can read it Mitigate with Content Security Policy and Subresource Integrity
Encrypted Session Cookie (Seems like what GitHub uses from my investigation): Single HttpOnly cookie called user_session that contains an encrypted blob with both access and refresh tokens. Every request, the server decrypts and validates the token. If access token expired, the server silently issues a new one and the frontend JavaScript never touches any token.

Personally, I prefer Option 1 for SPAs and mobile apps. Option 3 should work well for traditional web apps with server-side rendering.

Does Every Refresh Call Issue a New Access Token?
Yes, and that’s intentional. Every call to /auth/refresh issues a brand-new access token (new jti, new iat, new exp), a brand-new refresh token, marks the old refresh token as “used”, and stores the new refresh token in the database. This rotation enables theft detection. If a revoked token suddenly reappears, you know something is wrong.

Will Users Stay Logged In Indefinitely?

Sort of, depending on how you look at it. If your refresh token is valid for 90 days and the user logs in at least once before it expires, they get a new 90-day refresh token. This creates a rolling expiration window. As long as the user stays active (even if it’s just one API call every 89 days), they remain logged in indefinitely; until:

They explicitly log out, You revoke their token family (e.g., password change or signout from all devices) or you detect suspicious activity and revoke tokens. I believe this is exactly how Spotify, and Gmail work. You’re not re-entering your password every month unless something unusual happens.

Final Thoughts
The access and refresh token pattern isn’t just about following best practices, it’s about limiting damage. When (not if) something goes wrong, you want the blast radius to be measured in minutes, not months.
It took me years to fully appreciate this pattern. I hope this guide shortcuts that journey for you. Build systems that let you sleep at night, knowing that even if an attacker gets in, they won’t get far.

If you found this helpful, drop a comment with your own authentication war stories. We’ve all been there, and we all learned the hard way. I’m also putting together a GitHub repo with the full codebase.

Happy Hacking ✌

A Practical Example Using MongoDB Atlas Search

Chukwuemeka Maduekwe — Thu, 13 Feb 2025 04:46:00 +0000

Let’s say you’re about to build a project that has lots of stuff in it, for example, a blog, the collections in your database might be ‘users’ and ‘posts’, and that alone is enough for your database. Now, as your site grows, you might want to:

Implement a function that fetches similar posts to what the user has just read based on keywords, in a bid to keep the user on your site.
You would also love a situation where your users can easily search for a topic and get a result that is highly related to what they want.
You want an auto-complete as users type their search phrase.
All this and more can be done, but in a situation where you have a narrow timeframe, will you be able to implement all this perfectly and also be able to add taste to it like Highlighting user's search phrase, autocomplete in the search box, fuzzy search(A situation whereby you match wrong spellings, synonyms and more), not to discourage you a bit will it be a full-text search and not just a search where you match keywords, ID’s, or the whole string, bear in mind that when a user is searching, it’s quite different from when you are comparing password for authentication (where you don’t give room for error), users are likely to make mistakes or use the wrong phrase in their search, will your functions be scalable and performant, all this should dawn on you, before you engage in an endless task that might not bear the fruit you envision.

Allow me to introduce you to Atlas Search: Atlas Search is an embedded full-text search in MongoDB Atlas that gives you a seamless, scalable experience for building relevance-based app features.

MongoDB Atlas Search or Atlas Search for short as we would use in this post is an embedded full-text search that gives you a seamless, scalable experience for building relevance-based app features. You might be wondering like I was, when I was first introduced to Atlas Search by Marcus, who is a Senior Product Manager of Atlas Search at MongoDB, I felt nostalgic, that this would be a whole new database different from the popular document-oriented, NoSQL MongoDB I know, and this, kind of, discouraged me from even trying it out, probably as a result of not knowing what it offers at the outset. But I can tell you there’s a whole lot more to Atlas Search and this is a feature that companies will be willing to spend a fortune to have and it comes to us at no cost.

Let’s dive in, To keep this simple we’ll be working on a basic app, we can call it Transearch, this app serves as an account manager where users can add transactions such as debit or credit, title, description, and amount, it also saves a current balance from all transactions. The key here is to show how fast and easy it can be to locate any transaction with the little detail you have concerning the transaction.

A live version of this app can be found here and the full source code can be gotten from Github, here and here, the former being the client and the latter being the server code. More details can be found in the README.md section of their respective Github repo.

I used Next.js to build the frontend and other tools included are Material-UI, Redux, and SASS, While on the backend, I used Node.js, Express, MongoDB, Mongoose, and bcryptjs. The main point of this app is to show how easy it is to integrate Atlas Search into your app, be it a new or an existing app. Read the docs for a quick intro and after you have cloned the project and created a database on MongoDB, I’ll explain the search functions:

const fetchTransWithoutSearchPhrase = async (id) => {
  await API("post", `transaction/defaultSearchTransaction`, { searchPhrase, company: id })
    .then((res) => {
      if (res) setSearchResult(res);
    })
    .catch((err) => {
      // console.log(err);
      throw "Server failed to process data";
    });
};

const fetchTransWithSearchPhrase = async (id) => {
  await API("post", `transaction/atlasSearchTransaction`, { searchPhrase, company: id })
    .then((res) => {
      if (res) setSearchResult(res);
    })
    .catch((err) => {
      // console.log(err);
      throw "Server failed to process data";
    });
};

const searchHandler = () => {
  if (searchPhrase.length) return fetchTransWithSearchPhrase(id);
  fetchTransWithoutSearchPhrase(id);
};

As you already guessed and that you did right, what this search handler does in the client app can divide into two, the first being the basic ‘.find({})’ while the second is where we call the powerful ‘$search’ API from our server. Mind you, we call atlasSearch API from our server only when we have a search phrase, as this will throw an error. When the transactions page load initially, we call fetchTransWithSearchPhrase(id), the id parameter we pass to fetchTransWithSearchPhrase is our auth ID. Other times when a search phrase is not defined we call fetchTransWithoutSearchPhrase (id).

We call the atlasSearchTransaction handler only when a valid Search phrase is passed to it. Explanation of code, based on line numbers in the below picture:

exports.atlasSearchTransaction = async (req, res) => {
  try {
    const { searchPhrase, company } = req.body;

    const agg = [
      {
        $search: {
          text: {
            query: searchPhrase,
            path: ["title", "keywords", "description"],
            fuzzy: {},
          },
        },
      },
      {
        $project: {
          title: 1,
          date: 1,
          description: 1,
          credit: 1,
          company: 1,
          amount: 1,
          balance: 1,
          score: {
            $meta: "searchScore",
          },
        },
      },
      {
        $match: {
          company,
        },
      },
      {
        $sort: {
          _id: -1,
        },
      },
      {
        $limit: 10,
      },
    ];

    await Transaction.aggregate(agg, (err, searchResult) => {
      if (err) {
        throw err;
      } else {
        res.status(200).json(searchResult);
      }
    });
  } catch (err) {
    return catchError({ res, err, message: "unable to locate masses" });
  }
};

On line 3, we destructure the searchPhrase and company in the req.body, i.e. the data coming from our client fetchTransWithSearchPhrase handler.
On line 5, we define our aggregation, $search is where the magic happens. In-text object, we describe what our search is all about. We pass searchPhrase to query, i.e. what our user is searching for, path refers to the fields in our document we want to search against; When it just one field, you can pass it as a single text, else it an array like so: [“title”, “keywords”, “description”], ‘fuzzy: {}’ refers to the fact that a user might make a spelling error, and the great thing that fuzzy does is make that searchPhrase right and also return similar words.
On line 16, $project refers to the field we want to return from the aggregation.
On line 30, we used $match, we did this because we are storing all transactions in one collection which might not be ideal, what we could do is create a unique collection for each user. In our transaction schema, we have a path for a company or rather a user, and what we are doing with the match is to make sure we are fetching from the right owner of the transaction. Mind you, $match or $sort can’t come before $search.
On line 35, what ‘$sort: { _id: -1 }’ does is to reverse the order of the result, i.e. a kind of stack data structure, so the last item added becomes the first item in the returned array
On line 40, the $limit is used to set the max number of documents that can be returned.
On line 44, we pass the aggregate option to the collection and call the aggregate method which either returns an error or result.
On line 48, we send the result back to the client.

That marks the end of this section, I hope you’ve seen how easy it is to use Atlas Search in a new or an existing project.

Using Multiple MongoDB Databases in a Single Server with Node.js and TypeScript

Chukwuemeka Maduekwe — Wed, 12 Feb 2025 22:43:00 +0000

Setting up multiple MongoDB databases in a single Typescript Nodejs Server somes with a lot of advantages, ranging from:

Data segregation
Scalability and performance
Security and access control
Data isolation
Third-party integration
Testing and development
Future-proofing and modularity

NB: Here's a link to the repo where I'm actively using multiple databases in production WaveRD just in case you need a reference to learn from.
In this application what I did was to create a separate databases for Accounts (profile creation, signin signup, etc.), Managers (club, player, manager data in WaveRD - Soccer Manager) Console (App logs, contact messages, advertisment, error logs, etc. ) and ApiHub (Data for all public endpoints).
In this application I used mongoose as the ORM, but just in case you need to use MongoDB methods directly, that should also work.

// profile schema

import bcrypt from "bcryptjs";
import { Schema } from "mongoose";

import { accountsDatabase } from "../database";
import { generateSession } from "../../utils/handlers";

const ProfileSchema = new Schema(
  {
    name: { type: String, required: true },
    created: { type: Date, default: Date.now() },
    email: { type: String, unique: true, lowercase: true, trim: true, required: false },
    role: { type: String, default: "user" }, // ? user || admin
    status: { type: String, default: "active" }, // ? active || suspended
    avatar: { type: String, default: "/images/layout/profile.webp" }, // ? avatar web location
    handle: { type: String, required: true }, // ? Unique but we don't want index created on this
    theme: { type: String, required: true },
    auth: {
      session: { type: String },
      locked: { type: Date, default: null },
      deletion: { type: Date, default: null },
      password: { type: String, required: true },
      inactivity: { type: Date, default: null },

      failedAttempts: {
        counter: { type: Number, default: 0 },
        lastAttempt: { type: Date, default: null },
      },
      lastLogin: {
        counter: { type: Number, default: 0 },
        lastAttempt: { type: Date, default: Date.now() },
      },
      otp: {
        code: { type: String, default: null },
        purpose: { type: String, default: "" },
        time: { type: Date, default: "" },
      },
      verification: {
        email: { type: Date, default: null },
      },
    },
  },
  {
    statics: {
      async comparePassword(attempt: string, password: string) {
        return await bcrypt.compare(attempt, password);
      },
      async hashPassword(password: string) {
        return await bcrypt.hash(password, 10);
      },
    },
  }
);

ProfileSchema.pre("save", async function (next) {
  try {
    if (this.auth && this.auth.otp && this.isModified("auth.password")) {
      this.auth.session = generateSession(this.id); // <= generate login session
      this.auth.otp = { code: generateSession(this.id), purpose: "email verification", time: new Date() };
      this.auth.password = await bcrypt.hash(this.auth.password, 10); // <= Hash password if its a new account
    }
    return next();
  } catch (err: any) {
    return next(err);
  }
});

const ProfileModel = accountsDatabase.model("Profiles", ProfileSchema);

export default ProfileModel;

We create our schema using mongoose like in most app, the code is self explanatory, but just to higlight a few stuff. ProfileSchema describes the structure of our data in Profile collection, while all methods in profile schema statics can be called directly from using the profile model. The pre method attached to ProfileSchema intercepts all records and can manipulate them before they are saved to the database. Finally we export our model for use in our app. The code above can be found on github here just in case its updated in the future.
You can find more Schemas and Models in the models folder inside the src file.

// database.ts

import mongoose from "mongoose";

mongoose.Promise = global.Promise;

mongoose.set({
  // useNewUrlParser: true,
  // useUnifiedTopology: true,
  strictQuery: true,
  debug: false, // ? <= hide console messages

  // keepAlive: true,
  // useNewUrlParser: true,
  // useUnifiedTopology: true,
  // useFindAndModify: false,
});

interface IConnectionEvents {
  all: string;
  open: string;
  close: string;
  error: string;
  connected: string;
  fullsetup: string;
  connecting: string;
  reconnected: string;
  disconnected: string;
  disconnecting: string;
}

const connectionEvents: IConnectionEvents = {
  connecting: "Emitted when Mongoose starts making its initial connection to the MongoDB server",
  connected:
    "Emitted when Mongoose successfully makes its initial connection to the MongoDB server, or when Mongoose reconnects after losing connectivity. May be emitted multiple times if Mongoose loses connectivity.",
  open: "Emitted after 'connected' and onOpen is executed on all of this connection's models.",
  disconnecting: "Your app called Connection#close() to disconnect from MongoDB",
  disconnected:
    "Emitted when Mongoose lost connection to the MongoDB server. This event may be due to your code explicitly closing the connection, the database server crashing, or network connectivity issues.",
  close:
    "Emitted after Connection#close() successfully closes the connection. If you call conn.close(), you'll get both a 'disconnected' event and a 'close' event.",
  reconnected:
    "Emitted if Mongoose lost connectivity to MongoDB and successfully reconnected. Mongoose attempts to automatically reconnect when it loses connection to the database.",
  error: "Emitted if an error occurs on a connection, like a parseError due to malformed data or a data larger than 16MB.",
  fullsetup: "Emitted when you're connecting to a replica set and Mongoose has successfully connected to the primary and at least one secondary.",
  all: "Emitted when you're connecting to a replica set and Mongoose has successfully connected to all servers specified in your connection string.",
};

type LogMessage = { label: string; event: string };
const logMessage = ({ label, event }: LogMessage) =>
  `MongoDB ${label} Database Connection Events} ::: ${connectionEvents[event as keyof IConnectionEvents]}`;

type ModelGenerator = { label: string; db: string };
const modelGenerator = ({ label, db }: ModelGenerator) => {
  return mongoose
    .createConnection(<string>process.env[`${label}_MONGODB_URI`], { dbName: db })
    .on("all", () => logMessage({ label, event: "all" }))
    .on("open", () => logMessage({ label, event: "open" }))
    .on("error", () => logMessage({ label, event: "error" }))
    .on("close", () => logMessage({ label, event: "close" }))
    .on("connected", () => logMessage({ label, event: "connected" }))
    .on("fullsetup", () => logMessage({ label, event: "fullsetup" }))
    .on("connecting", () => logMessage({ label, event: "connecting" }))
    .on("reconnected", () => logMessage({ label, event: "reconnected" }))
    .on("disconnected", () => logMessage({ label, event: "disconnected" }))
    .on("disconnecting", () => logMessage({ label, event: "disconnecting" }));
};

const infoDatabase = modelGenerator({ label: "INFO", db: "info" }); // ? <= Client Database
const gamesDatabase = modelGenerator({ label: "GAMES", db: "games" }); // ? <= Games Database
const apihubDatabase = modelGenerator({ label: "APIHUB", db: "apihub" }); // ? <= API Hub Database
const accountsDatabase = modelGenerator({ label: "ACCOUNTS", db: "accounts" }); // ? <= Auth/Accounts  Database
const federatedDatabase = modelGenerator({ label: "FEDERATED", db: "WaveRD" }); // ? <= Federation Instance Database

export { accountsDatabase, infoDatabase, apihubDatabase, gamesDatabase, federatedDatabase };

This code actually creates a connection event for our databases, and can also be used to log data here. Inside the snippet above we connect to our different databases and export them for use in our app. The code can be found here.

VS Code Extensions to make our development easier

Chukwuemeka Maduekwe — Sat, 08 Feb 2025 20:39:53 +0000

VS Code is my preferred IDE, one that I have spent a lot of time trying to master including its shortcuts, another advantage of VS Code is that its lightweight and supports a wide range of extension which would make our work a lot easier without impacting performance. Another reason why I have grown fond of VS Code aside JavaScript is due to the fact that it supports Rust, a language I'm currently exploring though little progress. Here is a list of extensions We would be using while working on WaveRD in no particular order.

Better Comments

This extention does not directly affect our code but helps with comment visibility and it is something I use often. Instead of having the default dark color for comments, this extension offers different colors based on annotation used.

Code Spell Checker

The goal of this spell checker is to help catch common spelling errors while keeping the number of false positives low. My favorite thing about this extention is its support for different naming conventions ranging from snake case. This extention does not modify your code, but rather it highlights spelling errors and you can choose to ignore certain words.

Dictionary Completion

Another speeling extention but this is different. Dictionary completion allows user to get a list of keywords, based off of the current word at the cursor. This extention works like search suggestion.

Adds formatting and syntax highlighting support for env files (.env) to Visual Studio Code

ES7+ React/Redux/React-Native snippets

This is a popular extention among react developers, though my frequent use of it is rafce snippet. It provides JavaScript and React/Redux snippets in ES7+ with Babel plugin features for VS Code

filesize

This might sound weird as there is no clear productivity from this extention, but like other developers, I love to see the size of any file I am currently working at the status bar of VS Code.

Git LastAuthor

Just like filesize, I love to see information about who last modified a file in the status bar of VS Code. Git LastAuthor works with both Github and Bitbucket repositories.

GitHub Actions

The GitHub Actions extension lets you manage your workflows, view the workflow run history, and helps with authoring workflows. Just to note that we would be working with Github Actions in case you're wondering.

GitLens — Git supercharged

Visualize code authorship at a glance via Git blame annotations and CodeLens, seamlessly navigate and explore Git repositories, gain valuable insights via rich visualizations and powerful comparison commands, and so much more

Last Modified Date & Time

Show the last modified date for the current file in the status bar.

Markdown Preview Enhanced

Markdown Preview Enhanced ported to vscode

MongoDB for VS Code

It helps to have this extention, though for majority of the time we would be working with MongoDB compass.

One Dark Pro

Atom's iconic One Dark theme for Visual Studio Code. Just thought of adding this as for the duration of this series I would be uploading code snippets and aside aesthetics it aids readability

Peacock

Subtly change the workspace color of your workspace. Ideal when you have multiple VS Code instances and you want to quickly identify which is which. This extension would prove useful once we start switching between frontend and backend workspace as you would see.

Playwright Test for VSCode

This extension would be used to run Playwright Test tests in Visual Studio Code.

Postman

Not one we might use often. Streamline API development and testing with the power of Postman, directly in your favorite IDE.

Prettier - Code formatter

Code formatter using prettier. Aside having code formatting set to 'on save', another usefulness of this is that it does not format when there is a syntax error, so in a way it serves as a reminder that something is not right.

Tailwind CSS IntelliSense

Intelligent Tailwind CSS tooling for VS Code. Tailwind CSS IntelliSense enhances the Tailwind development experience by providing Visual Studio Code users with advanced features such as autocomplete, syntax highlighting, and linting.

vscode-faker

Generate fake data for name, address, lorem ipsum, commerce and much more

vscode-icons

Icons for Visual Studio Code

WakaTime

Metrics, insights, and time tracking automatically generated from your programming activity. I love this extention for so many reason, one of it being I can easily tell when I have spent a lot of time trying to resolve a bug and then knowing when I have done quite enough for the day

Happy hacking...