Agent skill

uuid

UUID generation skill - Universally Unique Identifiers v4 and v7 for entity IDs. For ng-events construction site progress tracking system.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/7spade/uuid

SKILL.md

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.

typescript
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.

typescript
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

typescript
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

typescript
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

typescript
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

typescript
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

typescript
// 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

typescript
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

typescript
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

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

❌ DON'T: Convert to binary in Firestore

typescript
// 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

bash
# 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:

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

✅ Use UUID:

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

❌ Parsing UUID Parts Manually:

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

✅ Use Library Functions:

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

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

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

✅ Generate Security Tokens Server-Side:

typescript
// 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: 1.0
Created: 2025-12-25
Maintainer: ng-events(GigHub) Development Team

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results