UUID - Universally Unique Identifiers

Trigger patterns: "UUID", "unique ID", "identifier", "v4", "v7", "uuidv4", "uuidv7"

Overview

UUID library for generating RFC9562-compliant unique identifiers in JavaScript/TypeScript applications.

Package: uuid@13.0.0
Standard: RFC9562 (formerly RFC4122)

Core Functions

1. v4() - Random UUID (Most Common)

Generates a version 4 UUID using cryptographically secure random values.

import { v4 as uuidv4 } from 'uuid';

// Generate random UUID
const taskId = uuidv4();
// '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

// Use in entity creation
interface Task {
  id: string;
  title: string;
  createdAt: Date;
}

function createTask(title: string): Task {
  return {
    id: uuidv4(),
    title,
    createdAt: new Date()
  };
}

When to use:

• Entity IDs (tasks, users, blueprints)
• Session IDs
• Request tracking IDs
• File upload IDs
• Any unique identifier needs

2. v7() - Timestamp-based UUID (Sortable)

Generates a version 7 UUID with Unix epoch timestamp for natural chronological sorting.

import { v7 as uuidv7 } from 'uuid';

// Generate timestamp-based UUID
const orderId = uuidv7();
// '019a26ab-9a66-71a9-a89e-63c35fce4a5a'

// Multiple UUIDs are naturally sortable
const ids = Array.from({ length: 5 }, () => uuidv7());
// All IDs will be in chronological order

// Use for database primary keys
interface Order {
  id: string; // v7 UUID - sortable by creation time
  customerId: string;
  createdAt: Date;
}

When to use:

• Database primary keys requiring chronological sorting
• Event IDs in time-series data
• Log entry IDs
• Audit trail records
• Any scenario where temporal ordering matters

Advantages:

• Natural sort order by creation time
• Better database index performance
• Reduced fragmentation in B-tree indexes
• Compatible with UUID v4 in storage/APIs

Real-World Examples

Task Repository with UUID

import { Injectable, inject } from '@angular/core';
import { Firestore, collection, doc, setDoc, getDoc } from '@angular/fire/firestore';
import { v4 as uuidv4 } from 'uuid';

export interface Task {
  id: string;
  blueprintId: string;
  title: string;
  description: string;
  status: 'pending' | 'in-progress' | 'completed';
  createdAt: Date;
  updatedAt: Date;
}

@Injectable({ providedIn: 'root' })
export class TaskRepository {
  private firestore = inject(Firestore);
  private tasksCollection = collection(this.firestore, 'tasks');

  /**
   * Create task with UUID v4
   */
  async create(task: Omit<Task, 'id' | 'createdAt' | 'updatedAt'>): Promise<Task> {
    const id = uuidv4(); // Generate unique ID
    const now = new Date();

    const newTask: Task = {
      ...task,
      id,
      createdAt: now,
      updatedAt: now
    };

    const docRef = doc(this.tasksCollection, id);
    await setDoc(docRef, newTask);

    return newTask;
  }

  /**
   * Get task by UUID
   */
  async findById(id: string): Promise<Task | null> {
    const docRef = doc(this.tasksCollection, id);
    const snapshot = await getDoc(docRef);

    if (!snapshot.exists()) {
      return null;
    }

    return { id: snapshot.id, ...snapshot.data() } as Task;
  }
}

Audit Log with UUID v7

import { Injectable, inject } from '@angular/core';
import { Firestore, collection, doc, setDoc } from '@angular/fire/firestore';
import { v7 as uuidv7 } from 'uuid';

export interface AuditLog {
  id: string; // v7 UUID for chronological sorting
  userId: string;
  action: string;
  resource: string;
  resourceId: string;
  timestamp: Date;
  metadata?: Record<string, any>;
}

@Injectable({ providedIn: 'root' })
export class AuditLogRepository {
  private firestore = inject(Firestore);
  private logsCollection = collection(this.firestore, 'auditLogs');

  /**
   * Create audit log with v7 UUID (sortable by time)
   */
  async log(
    userId: string,
    action: string,
    resource: string,
    resourceId: string,
    metadata?: Record<string, any>
  ): Promise<AuditLog> {
    const id = uuidv7(); // Timestamp-based UUID

    const log: AuditLog = {
      id,
      userId,
      action,
      resource,
      resourceId,
      timestamp: new Date(),
      metadata
    };

    const docRef = doc(this.logsCollection, id);
    await setDoc(docRef, log);

    return log;
  }
}

Session Management

import { Injectable } from '@angular/core';
import { v4 as uuidv4 } from 'uuid';

export interface Session {
  id: string;
  userId: string;
  token: string;
  createdAt: Date;
  expiresAt: Date;
}

@Injectable({ providedIn: 'root' })
export class SessionService {
  private sessions = new Map<string, Session>();

  /**
   * Create new session with UUID
   */
  createSession(userId: string, expiresInMs: number = 3600000): Session {
    const sessionId = uuidv4();
    const now = new Date();

    const session: Session = {
      id: sessionId,
      userId,
      token: this.generateToken(),
      createdAt: now,
      expiresAt: new Date(now.getTime() + expiresInMs)
    };

    this.sessions.set(sessionId, session);
    return session;
  }

  /**
   * Get session by ID
   */
  getSession(sessionId: string): Session | null {
    return this.sessions.get(sessionId) || null;
  }

  private generateToken(): string {
    return uuidv4(); // Use UUID as token
  }
}

File Upload Tracking

import { Injectable, signal } from '@angular/core';
import { v4 as uuidv4 } from 'uuid';

export interface FileUpload {
  id: string;
  fileName: string;
  fileSize: number;
  uploadedBy: string;
  uploadedAt: Date;
  status: 'pending' | 'uploading' | 'completed' | 'failed';
  progress: number;
  url?: string;
}

@Injectable({ providedIn: 'root' })
export class FileUploadService {
  private uploads = signal<Map<string, FileUpload>>(new Map());

  /**
   * Start file upload with UUID tracking
   */
  startUpload(file: File, userId: string): string {
    const uploadId = uuidv4();

    const upload: FileUpload = {
      id: uploadId,
      fileName: file.name,
      fileSize: file.size,
      uploadedBy: userId,
      uploadedAt: new Date(),
      status: 'pending',
      progress: 0
    };

    this.uploads.update(map => {
      map.set(uploadId, upload);
      return new Map(map);
    });

    return uploadId;
  }

  /**
   * Update upload progress
   */
  updateProgress(uploadId: string, progress: number): void {
    this.uploads.update(map => {
      const upload = map.get(uploadId);
      if (upload) {
        upload.progress = progress;
        upload.status = progress === 100 ? 'completed' : 'uploading';
        map.set(uploadId, upload);
      }
      return new Map(map);
    });
  }

  /**
   * Get upload by ID
   */
  getUpload(uploadId: string): FileUpload | undefined {
    return this.uploads().get(uploadId);
  }
}

Best Practices

1. v4 for General Use, v7 for Time-Series

✅ DO: Choose based on use case

// General entity IDs - use v4
const taskId = uuidv4();
const userId = uuidv4();

// Time-series or sortable IDs - use v7
const logId = uuidv7();
const eventId = uuidv7();

2. Use TypeScript Types

✅ DO: Define UUID brand types for safety

type UUID = string & { readonly __brand: unique symbol };

interface Task {
  id: UUID;
  title: string;
}

function createTaskId(): UUID {
  return uuidv4() as UUID;
}

3. Validate UUIDs

✅ DO: Validate UUID format

import { validate as uuidValidate, version as uuidVersion } from 'uuid';

function isValidUUID(id: string): boolean {
  return uuidValidate(id);
}

function isV4UUID(id: string): boolean {
  return uuidValidate(id) && uuidVersion(id) === 4;
}

function isV7UUID(id: string): boolean {
  return uuidValidate(id) && uuidVersion(id) === 7;
}

4. Don't Store UUIDs as Binary (Firestore)

✅ DO: Store as string in Firestore

// Firestore automatically indexes string IDs
await setDoc(doc(collection, taskId), { /* data */ });

❌ DON'T: Convert to binary in Firestore

// Unnecessary complexity in Firestore
const binaryId = Buffer.from(taskId.replace(/-/g, ''), 'hex');

Performance Considerations

1. Generation Speed: v4 is slightly faster than v7
2. Index Performance: v7 provides better database index locality
3. Storage: Both require 36 bytes as string (128-bit + hyphens)
4. Collision Probability: Effectively zero for both versions

CLI Usage

# Generate v4 UUID
$ npx uuid
ddeb27fb-d9a0-4624-be4d-4615062daed4

# Generate v7 UUID
$ npx uuid v7
019a26ab-9a66-71a9-a89e-63c35fce4a5a

# Generate multiple UUIDs
$ npx uuid && npx uuid && npx uuid

Integration Checklist

• [ ] Install uuid@13.0.0
• [ ] Import v4 or v7 based on use case
• [ ] Use for entity IDs in repositories
• [ ] Validate UUIDs when receiving from external sources
• [ ] Store as strings in Firestore
• [ ] Add TypeScript types for type safety
• [ ] Document UUID version choice in code comments

Anti-Patterns

❌ Using Sequential IDs in Distributed Systems:

let counter = 0;
const id = `task-${++counter}`; // Race conditions, not globally unique

✅ Use UUID:

const id = uuidv4(); // Globally unique, no coordination needed

---

❌ Parsing UUID Parts Manually:

const timestamp = parseInt(uuid.substring(0, 8), 16); // Fragile

✅ Use Library Functions:

import { parse, version } from 'uuid';
const ver = version(uuid); // Proper parsing

---

❌ Generating UUIDs Client-Side for Security-Critical Operations:

const sessionToken = uuidv4(); // Predictable if not properly seeded

✅ Generate Security Tokens Server-Side:

// Firebase Auth handles token generation securely
const token = await auth.currentUser.getIdToken();

Cross-References

• firebase-repository - UUID for entity IDs
• blueprint-integration - Blueprint and member IDs
• event-bus-integration - Event ID generation
• angular-component - UUID in component state

Package Information

• Version: 13.0.0
• Repository: https://github.com/uuidjs/uuid
• RFC: RFC9562 (UUID v7), RFC4122 (UUID v4)

---

Version: 1.0
Created: 2025-12-25
Maintainer: ng-events(GigHub) Development Team