Why should every Data Access Layer file begin with 'import server-only'?

The 'server-only' package triggers a compilation error if the file or any of its exports are imported into a Client Component ('use client'). This prevents database credentials, private ORM queries, and secret business logic from leaking into public client JavaScript bundles.

How do you test cache invalidation via revalidateTag() in Vitest?

Mock the 'next/cache' module using vi.mock('next/cache', () => ({ revalidateTag: vi.fn() })). Execute the mutation service or Server Action, then assert expect(revalidateTag).toHaveBeenCalledWith('expected-tag-name').

What is the fundamental difference between React.cache() and unstable_cache() in Next.js 15?

React.cache() is a native React utility for memoizing functions within the scope of a single server request, storing results in ephemeral memory during the render pass. unstable_cache() is a Next.js API that serializes and stores results in a persistent cross-request Data Cache shared across requests and users, supporting TTL expiration and tag-based invalidation via revalidateTag.

Why does passing object arguments into React.cache() wrapped functions require extreme caution?

React.cache() relies on Object.is() for argument comparison. When passing newly instantiated objects ({ id: '1' }), their memory references differ on every call, causing complete cache misses. Function arguments wrapped with React.cache() should be primitives (strings, numbers, booleans) or share strict referential identity.

How do you prevent cross-test contamination when testing cached data layers?

Reset mocks and modules in beforeEach using vi.clearAllMocks() and vi.resetModules(), generate unique IDs for test fixtures, and wrap database operations in rollback transactions so each test runs against a clean state.

How do you test that a query is immune to Cache Poisoning when using unstable_cache()?

The test executes two sequential invocations for different tenants (Tenant A and Tenant B) and asserts that the keyParts array passed into unstable_cache contains the tenant identifier. This verifies that distinct cache keys are generated, preventing one tenant from receiving cached data belonging to another.

How should database connection timeouts and driver errors be tested within the DAL?

Configure the ORM spy to reject with a connection error (e.g., vi.mocked(db.select).mockRejectedValue(new Error('Connection timeout'))). Assert that the DAL logs the incident appropriately, avoids caching corrupted empty data, and throws a strongly typed domain error.

Testing Data Access Layer (DAL) and Caching — Testing & QA Automation

Architectural Foundation#

In the architecture of modern Next.js 15 fullstack applications, moving away from intermediate REST/GraphQL API layers in favor of direct communication between React Server Components and the database introduced the risk of blurred separation of concerns: SQL queries, authorization checks, and caching semantics can easily scatter across pages and components.

The solution to this architectural risk is the Data Access Layer (DAL) pattern. The DAL consolidates all database interactions (Prisma, Drizzle, Redis) and serves as the single entry point for data retrieval.

A critical aspect of the DAL in Next.js is its two-tier caching model:

Per-Request Memoization (React.cache): Provides function call deduplication within a single server rendering cycle (a single incoming HTTP request). If a header, navigation sidebar, and primary view all request the same user record via getUser(id), the underlying physical database query executes exactly once.
Cross-Request Cache (unstable_cache): Persists serialized computation results inside the persistent Next.js Data Cache across distinct user requests, supporting on-demand invalidation via string tags (revalidateTag).

Testing the DAL ensures data integrity, prevents performance degradation caused by redundant SQL queries, and eliminates cross-tenant data leaks.

Mental Model#

In the mental model of testing the DAL and caching mechanisms, queries traverse a strict two-tier filter before hitting the physical database:

text

Incoming RSC Invocation
                                          │
                                          ▼
+-------------------------------------------------------------------------------+
| Tier 1: React.cache() (Per-Request Memoization)                               |
| Lifecycle: Single HTTP request. Deduplication by argument referential identity|
+-------------------------------------------------------------------------------+
     │ (Cache Miss)                                      │ (Cache Hit: same request)
     ▼                                                   ▼
+---------------------------------------------------+  Return from memory
| Tier 2: unstable_cache() (Next.js Data Cache)     |  without querying Tier 2
| Lifecycle: Cross-request, tags, TTL               |
+---------------------------------------------------+
     │ (Data Cache Miss)                                 │ (Cache Hit: by tags/keys)
     ▼                                                   ▼
+---------------------------------------------------+  Return from cache
| Physical Data Access Layer                        |  without executing SQL
| - Execute SQL / Drizzle / Prisma                  |
| - Verify current session permissions              |
+---------------------------------------------------+
     │
     ▼
[Physical Database: PostgreSQL / MySQL]

When authoring DAL test suites, you must verify:

That React.cache() avoids repeated physical invocations when called with identical arguments;
That unstable_cache() constructs deterministic and isolated cache keys (keyParts) incorporating tenant and user identifiers to prevent cross-user Cache Poisoning;
That revalidateTag() purges cache entries for matching domain entities.

Applied in Production#

Testing SQL Deduplication in Complex RSC Trees: Ensuring that concurrent rendering of layouts and pages does not emit redundant queries for organization profiles or global settings.
Validating Composite Cache Key Uniqueness: Preventing critical security vulnerabilities where data belonging to User A is served to User B due to a missing userId in keyParts.
Asserting Cascading Tag Invalidation: Confirming that entity mutation functions reliably trigger revalidateTag() with expected domain tag identifiers.
Enforcing Test Suite Cache Isolation: Guaranteeing that cache state from one unit or integration test does not contaminate subsequent tests running within the same Vitest worker.

How It Works#

1. Secure DAL Module Architecture#

Here is an organization lookup service using React.cache() for in-request deduplication and unstable_cache() for cross-request caching.

typescriptsrc/dal/organization.ts

import 'server-only';
import { cache } from 'react';
import { unstable_cache } from 'next/cache';
import { db } from '@/lib/db';
import { organizations } from '@/lib/schema';
import { eq } from 'drizzle-orm';

export interface OrganizationDTO {
  id: string;
  name: string;
  plan: 'free' | 'pro' | 'enterprise';
  createdAt: Date;
}

// Low-level database fetcher
async function fetchOrganizationFromDb(orgId: string): Promise<OrganizationDTO | null> {
  const [record] = await db
    .select({
      id: organizations.id,
      name: organizations.name,
      plan: organizations.plan,
      createdAt: organizations.createdAt,
    })
    .from(organizations)
    .where(eq(organizations.id, orgId))
    .limit(1);

  return record ?? null;
}

// Cross-request cache with invalidation tags
export const getCachedOrganization = (orgId: string) =>
  unstable_cache(
    async () => fetchOrganizationFromDb(orgId),
    ['organization-cache-key', orgId],
    {
      revalidate: 3600, // 1 hour
      tags: [`org:${orgId}`, 'organizations'],
    }
  )();

// Consolidated DAL accessor with in-request deduplication
export const getOrganization = cache(async (orgId: string): Promise<OrganizationDTO | null> => {
  if (!orgId || typeof orgId !== 'string') {
    throw new Error('Invalid organization identifier');
  }

  return getCachedOrganization(orgId);
});

2. Testing In-Request Deduplication via React.cache()#

To verify React.cache() in Vitest, we invoke the memoized function multiple times concurrently and assert against the invocation count of the underlying spy.

typescriptsrc/dal/organization.memo.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { cache } from 'react';

describe('React.cache (Per-Request Deduplication)', () => {
  it('deduplicates concurrent invocations with identical arguments', async () => {
    const rawFetcherMock = vi.fn().mockImplementation(async (id: string) => {
      return { id, name: `Organization ${id}`, plan: 'enterprise' as const };
    });

    // Wrap mock in native React.cache
    const memoizedFetcher = cache(rawFetcherMock);

    // Simulate concurrent requests from distinct server components in one render cycle
    const [result1, result2, result3] = await Promise.all([
      memoizedFetcher('org-123'),
      memoizedFetcher('org-123'),
      memoizedFetcher('org-123'),
    ]);

    // Assert return value equality
    expect(result1).toEqual(result2);
    expect(result2).toEqual(result3);
    expect(result1.name).toBe('Organization org-123');

    // KEY ASSERTION: physical fetcher executed exactly once
    expect(rawFetcherMock).toHaveBeenCalledTimes(1);
    expect(rawFetcherMock).toHaveBeenCalledWith('org-123');
  });

  it('executes separate queries for distinct arguments', async () => {
    const rawFetcherMock = vi.fn().mockImplementation(async (id: string) => ({ id }));
    const memoizedFetcher = cache(rawFetcherMock);

    await Promise.all([
      memoizedFetcher('org-A'),
      memoizedFetcher('org-B'),
    ]);

    expect(rawFetcherMock).toHaveBeenCalledTimes(2);
    expect(rawFetcherMock).toHaveBeenNthCalledWith(1, 'org-A');
    expect(rawFetcherMock).toHaveBeenNthCalledWith(2, 'org-B');
  });
});

3. Testing unstable_cache Configuration: Keys, TTL, and Tags#

Because unstable_cache is orchestrated by Next.js internal runtime mechanisms, in a DAL integration test we intercept and verify the registration parameters, ensuring key isolation and collision prevention.

typescriptsrc/dal/organization.cache.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { unstable_cache } from 'next/cache';
import * as dbModule from '@/lib/db';

// Mock unstable_cache to intercept configuration metadata
vi.mock('next/cache', () => ({
  unstable_cache: vi.fn((fn: () => Promise<unknown>, keyParts?: string[], options?: { revalidate?: number; tags?: string[] }) => {
    // Return wrapper function exposing registration metadata for inspection
    return Object.assign(fn, {
      __keyParts: keyParts,
      __options: options,
    });
  }),
  revalidateTag: vi.fn(),
}));

vi.mock('@/lib/db', () => ({
  db: {
    select: vi.fn(),
  },
}));

describe('DAL: unstable_cache Configuration & Security', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('registers cache with unique composite key and valid tag identifiers', async () => {
    const { getCachedOrganization } = await import('./organization');

    getCachedOrganization('org-prod-42');

    // Assert unstable_cache was registered with expected parameters
    expect(unstable_cache).toHaveBeenCalledWith(
      expect.any(Function),
      ['organization-cache-key', 'org-prod-42'],
      {
        revalidate: 3600,
        tags: ['org:org-prod-42', 'organizations'],
      }
    );
  });

  it('guarantees cache key isolation between distinct organizations', async () => {
    const { getCachedOrganization } = await import('./organization');

    getCachedOrganization('tenant-alpha');
    getCachedOrganization('tenant-beta');

    const calls = vi.mocked(unstable_cache).mock.calls;

    const keyAlpha = calls[0][1];
    const keyBeta = calls[1][1];

    expect(keyAlpha).toEqual(['organization-cache-key', 'tenant-alpha']);
    expect(keyBeta).toEqual(['organization-cache-key', 'tenant-beta']);
    expect(keyAlpha).not.toEqual(keyBeta);
  });
});

4. Testing Cache Purging via revalidateTag()#

We test the mutation service that updates database entities and triggers targeted cache invalidation.

typescriptsrc/dal/update-organization.test.ts

import { describe, it, expect, vi, beforeEach } from 'vitest';
import { updateOrganizationPlan } from './organization-mutations';
import { db } from '@/lib/db';
import { revalidateTag } from 'next/cache';

vi.mock('next/cache', () => ({
  revalidateTag: vi.fn(),
  revalidatePath: vi.fn(),
}));

vi.mock('@/lib/db', () => ({
  db: {
    update: vi.fn().mockReturnThis(),
    set: vi.fn().mockReturnThis(),
    where: vi.fn().mockResolvedValue([{ id: 'org-99' }]),
  },
}));

describe('updateOrganizationPlan Mutation', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('invalidates targeted organization tag upon successful update', async () => {
    await updateOrganizationPlan('org-99', 'enterprise');

    // Assert database update execution
    expect(db.update).toHaveBeenCalled();

    // Assert targeted tag invalidation in Data Cache
    expect(revalidateTag).toHaveBeenCalledWith('org:org-99');
    // Ensure broad global caches are not blindly cleared for individual plan updates
    expect(revalidateTag).not.toHaveBeenCalledWith('all-data');
  });
});

Common Pitfalls#

Ошибка: Cross-Tenant Data Leaks (Cache Poisoning) in unstable_cache

If a function wrapped inside unstable_cache retrieves private user records but omits userId from the keyParts array, the response for the first requesting user will be stored globally and served to subsequent users.

typescript

// ❌ CRITICAL SECURITY FLAW: Shared cache key, private data
export const getMyPrivateData = (userId: string) =>
  unstable_cache(
    async () => fetchPrivateProfile(userId),
    ['private-user-data'] // Missing userId in key!
  )();

// ✅ SECURE: Isolated composite key per tenant/user
export const getMyPrivateData = (userId: string) =>
  unstable_cache(
    async () => fetchPrivateProfile(userId),
    ['private-user-data', userId]
  )();

Ошибка: Confusing React.cache() with unstable_cache()

React.cache() is exclusively scoped to in-request deduplication for the lifecycle of a single incoming HTTP request (held in process memory for that specific render pass and destroyed upon completion). unstable_cache() persists serialized payloads to disk or external stores across multiple requests and users. Combining both yields optimal performance, but they cannot replace one another.

Ошибка: Omitting 'server-only' Directive in DAL Modules

If a DAL module is inadvertently imported into a Client Component ('use client'), sensitive environment variables, database connection strings, or ORM queries will leak into the client JavaScript bundle. Adding import 'server-only'; at the top of every DAL file causes the bundler to fail the build immediately if the file is imported into client code.

Ошибка: Test State Pollution in Vitest Suites

Because React.cache() binds to the global bundling context in testing environments, calling a memoized function across distinct it() blocks without clearing mocks or resetting module registries may return stale results from a prior test. Always invoke vi.clearAllMocks() in beforeEach() and re-instantiate function wrappers when needed.

Step-by-Step DAL Testing Workflow#

Verification phases for Data Access Layer and caching

Verify server-only IsolationSecurity

Ensure the module contains 'import server-only' and does not expose internal database internals.

Test React.cache() DeduplicationDeduplication

Invoke the method 3-5 times concurrently with identical parameters and assert exactly 1 database call.

Inspect unstable_cache KeysKey Isolation

Assert that keyParts contains all required dynamic parameters (userId, tenantId, filter keys).

Validate Cache TagsTags Assert

Ensure tags array contains granular entity identifiers (e.g., 'org:id') for precise invalidation.

Assert revalidateTag ExecutionInvalidation

Execute mutation methods and verify that revalidateTag is called with the exact tag string.

Clean State Between RunsCleanup

Clear mock spies and internal caches in beforeEach to avoid test pollution across workers.

Interview Questions#

Interview Questions7 questions

Testing Data Access Layer (DAL) and Caching

Architectural Foundation#

Mental Model#

Applied in Production#

How It Works#

1. Secure DAL Module Architecture#

2. Testing In-Request Deduplication via React.cache()#

3. Testing unstable_cache Configuration: Keys, TTL, and Tags#

4. Testing Cache Purging via revalidateTag()#

Common Pitfalls#

Ошибка: Cross-Tenant Data Leaks (Cache Poisoning) in unstable_cache

Ошибка: Confusing React.cache() with unstable_cache()

Ошибка: Omitting 'server-only' Directive in DAL Modules

Ошибка: Test State Pollution in Vitest Suites

Step-by-Step DAL Testing Workflow#

Interview Questions#

Related Topics#

Architectural Foundation#

Mental Model#

Applied in Production#

How It Works#

1. Secure DAL Module Architecture#

2. Testing In-Request Deduplication via React.cache()#

3. Testing unstable_cache Configuration: Keys, TTL, and Tags#

4. Testing Cache Purging via revalidateTag()#

Common Pitfalls#

Ошибка: Cross-Tenant Data Leaks (Cache Poisoning) in unstable_cache

Ошибка: Confusing React.cache() with unstable_cache()

Ошибка: Omitting 'server-only' Directive in DAL Modules

Ошибка: Test State Pollution in Vitest Suites

Step-by-Step DAL Testing Workflow#

Interview Questions#

Related Topics#