Prefixes

Learn how to use prefixes effectively to organize and identify different types of IDs.

What are Prefixes?

Prefixes are optional labels that help you categorize and identify different types of IDs in your application.

import { generateId } from '@aexoo-ai/spark-id'

// Without prefix
const id = generateId() // "YBNDRFG8EJKMCPQXOT1UWISZA345H769"

// With prefix
const userId = generateId('USER') // "USER_YBNDRFG8EJKMCPQXOT1UWISZA345H769"

Why Use Prefixes?

1. Organization

Prefixes help you organize different types of entities:

const userId = generateId('USER')     // User accounts
const txnId = generateId('TXN')       // Transactions
const orderId = generateId('ORDER')   // Orders
const commentId = generateId('COMMENT') // Comments

2. Debugging

Prefixes make it easier to identify ID types in logs and databases:

console.log('Processing user:', userId) // "Processing user: USER_YBNDRFG8EJKMCPQXOT1UWISZA345H769"
console.log('Transaction ID:', txnId)   // "Transaction ID: TXN_YBNDRFG8EJKMCPQXOT1UWISZA345H769"

3. Database Queries

Prefixes enable efficient filtering and searching:

-- Find all users
SELECT * FROM entities WHERE id LIKE 'USER_%'

-- Find all transactions
SELECT * FROM entities WHERE id LIKE 'TXN_%'

Common Prefix Patterns

Entity Types

// User management
const userId = generateId('USER')
const adminId = generateId('ADMIN')
const guestId = generateId('GUEST')

// E-commerce
const productId = generateId('PRODUCT')
const orderId = generateId('ORDER')
const cartId = generateId('CART')
const paymentId = generateId('PAYMENT')

// Content management
const postId = generateId('POST')
const commentId = generateId('COMMENT')
const categoryId = generateId('CATEGORY')
const tagId = generateId('TAG')

Business Domains

// Financial
const txnId = generateId('TXN')
const invoiceId = generateId('INVOICE')
const receiptId = generateId('RECEIPT')

// Communication
const messageId = generateId('MSG')
const emailId = generateId('EMAIL')
const notificationId = generateId('NOTIF')

// System
const sessionId = generateId('SESSION')
const tokenId = generateId('TOKEN')
const logId = generateId('LOG')

Prefix Naming Conventions

Best Practices

// ✅ Prefer UPPERCASE (default output casing can be configured)
const userId = generateId('USER')
const txnId = generateId('TXN')

// ✅ Use descriptive names
const orderId = generateId('ORDER')
const commentId = generateId('COMMENT')

// ✅ Keep prefixes short but clear
const productId = generateId('PRODUCT') // Good
const productItemId = generateId('PRODUCT_ITEM') // Too long

Avoid These Patterns

// ❌ Don't use lowercase (inconsistent)
const userId = generateId('user')

// ❌ Don't use generic names
const id1 = generateId('ID')
const obj1 = generateId('OBJ')

// ❌ Don't use abbreviations without context
const usrId = generateId('USR') // Unclear
const tId = generateId('T')     // Too short

Working with Prefixed IDs

Parsing

import { parseId } from '@aexoo-ai/spark-id'

const prefixedId = 'USER_YBNDRFG8EJKMCPQXOT1UWISZA345H769'
const parsed = parseId(prefixedId)

console.log(parsed.prefix) // "USER"
console.log(parsed.id)     // "YBNDRFG8EJKMCPQXOT1UWISZA345H769"
console.log(parsed.full)   // "USER_YBNDRFG8EJKMCPQXOT1UWISZA345H769"

Validation

import { isValidId } from '@aexoo-ai/spark-id'

// Validate prefixed IDs
console.log(isValidId('USER_YBNDRFG8EJKMCPQXOT1UWISZA345H769')) // true
console.log(isValidId('TXN_YBNDRFG8EJKMCPQXOT1UWISZA345H769'))  // true
console.log(isValidId('INVALID_YBNDRFG8EJKMCPQXOT1UWISZA345H769')) // false (invalid characters)

Filtering by Prefix

// Filter IDs by prefix
const ids = [
  'USER_YBNDRFG8EJKMCPQXOT1UWISZA345H769',
  'TXN_YBNDRFG8EJKMCPQXOT1UWISZA345H769',
  'ORDER_YBNDRFG8EJKMCPQXOT1UWISZA345H769'
]

const userIds = ids.filter(id => id.startsWith('USER_'))
const txnIds = ids.filter(id => id.startsWith('TXN_'))

Advanced Prefix Patterns

Hierarchical Prefixes

// Use underscores for hierarchy
const productId = generateId('PRODUCT')
const productVariantId = generateId('PRODUCT_VARIANT')
const productImageId = generateId('PRODUCT_IMAGE')

// Database queries become more specific
// SELECT * FROM entities WHERE id LIKE 'PRODUCT_%'
// SELECT * FROM entities WHERE id LIKE 'PRODUCT_VARIANT_%'

Environment-Specific Prefixes

// Different prefixes for different environments
const devUserId = generateId('DEV_USER')
const testUserId = generateId('TEST_USER')
const prodUserId = generateId('PROD_USER')

Version Prefixes

// Version your prefixes
const v1UserId = generateId('V1_USER')
const v2UserId = generateId('V2_USER')

Database Integration

Indexing

-- Create indexes for efficient prefix queries
CREATE INDEX idx_entity_prefix ON entities (id) WHERE id LIKE 'USER_%';
CREATE INDEX idx_entity_prefix ON entities (id) WHERE id LIKE 'TXN_%';

Partitioning

-- Partition tables by prefix
CREATE TABLE entities (
  id VARCHAR(50) PRIMARY KEY,
  data JSONB
) PARTITION BY LIST (LEFT(id, 5));

CREATE TABLE entities_user PARTITION OF entities
  FOR VALUES IN ('USER_');

CREATE TABLE entities_txn PARTITION OF entities
  FOR VALUES IN ('TXN_');

Performance Considerations

Prefix Length

// ✅ Good: Short, clear prefixes
const userId = generateId('USER')
const txnId = generateId('TXN')

// ❌ Avoid: Very long prefixes
const veryLongPrefixId = generateId('VERY_LONG_PREFIX_NAME')

Query Optimization

// Efficient prefix queries
const userIds = entities.filter(entity => entity.id.startsWith('USER_'))

// Less efficient (requires full scan)
const userIds = entities.filter(entity => entity.id.includes('USER'))

Related

• ID Generation - Learn about generating IDs
• Validation - Validate prefixed IDs
• Examples - See real-world prefix usage
• API Reference - Complete API documentation