@dotdo/postgres 0.1.0

package/src/types/branded.ts

@@ -0,0 +1,1075 @@
+/**
+ * Branded Types for Domain-Specific Identifiers
+ *
+ * This module provides TypeScript branded types for domain-specific identifiers,
+ * preventing accidental mixing of incompatible values at compile time.
+ *
+ * ## What are Branded Types?
+ *
+ * Branded types use TypeScript's structural typing system to create nominal-like types.
+ * Each branded type carries a unique "brand" that makes it incompatible with other types,
+ * even if they have the same underlying primitive type.
+ *
+ * ## Why Use Branded Types?
+ *
+ * Without branded types, it's easy to accidentally pass the wrong ID:
+ *
+ * ```typescript
+ * // Without branding - compiles but has a bug!
+ * function getUser(userId: string) { ... }
+ * function getPage(pageId: string) { ... }
+ *
+ * const userId = 'user-123'
+ * const pageId = 'page-456'
+ * getUser(pageId)  // Compiles! But wrong.
+ * ```
+ *
+ * With branded types, the compiler catches these mistakes:
+ *
+ * ```typescript
+ * // With branding - compile error!
+ * function getUser(userId: TenantId) { ... }
+ * function getPage(pageId: BlockId) { ... }
+ *
+ * const userId = createTenantId('user-123')
+ * const pageId = createBlockId('HOT:page-456')
+ * getUser(pageId)  // Error! Type 'BlockId' is not assignable to type 'TenantId'
+ * ```
+ *
+ * @example Creating and using branded types
+ * ```typescript
+ * import { createTenantId, createPageNumber, TenantId, unwrap } from '@dotdo/postgres'
+ *
+ * // Create a branded value (validates input)
+ * const tenantId = createTenantId('acme-corp')
+ *
+ * // Use in type-safe functions
+ * function getTenantData(id: TenantId): Promise<TenantData> {
+ *   // id is guaranteed to be a valid tenant ID
+ * }
+ *
+ * // Unwrap to get the underlying value
+ * const rawValue: string = unwrap(tenantId)
+ * ```
+ *
+ * @module types/branded
+ */
+
+/**
+ * Internal brand symbol for nominal typing.
+ *
+ * This symbol is used as a key in branded types to make them incompatible
+ * with plain primitives and each other.
+ */
+declare const brand: unique symbol
+
+/**
+ * Generic branded type helper for creating nominal types from primitives.
+ *
+ * This utility type wraps a base type `T` with a unique brand, making it
+ * incompatible with plain `T` values and other branded types.
+ *
+ * @typeParam T - The underlying primitive type (string, number, etc.)
+ * @typeParam Brand - A unique string literal to identify this branded type
+ *
+ * @example Creating a custom branded type
+ * ```typescript
+ * type UserId = Branded<string, 'UserId'>
+ *
+ * function createUserId(value: string): UserId {
+ *   if (!value.startsWith('usr_')) {
+ *     throw new Error('User IDs must start with usr_')
+ *   }
+ *   return value as UserId
+ * }
+ * ```
+ */
+export type Branded<T, Brand extends string> = T & { readonly [brand]: Brand }
+
+// =============================================================================
+// Branded Type Definitions
+// =============================================================================
+
+/**
+ * Branded type for tenant identifiers.
+ *
+ * Used to uniquely identify tenants in multi-tenant deployments.
+ * Must match {@link TENANT_ID_PATTERN} and be at most {@link TENANT_ID_MAX_LENGTH} characters.
+ *
+ * @see {@link createTenantId} - Factory function with validation
+ * @see {@link isTenantId} - Type guard for runtime checking
+ */
+export type TenantId = Branded<string, 'TenantId'>
+
+/**
+ * Branded type for storage page numbers.
+ *
+ * Represents a page number in the tiered storage system (0 to {@link MAX_PAGE_NUMBER}).
+ *
+ * @see {@link createPageNumber} - Factory function with validation
+ * @see {@link isPageNumber} - Type guard for runtime checking
+ */
+export type PageNumber = Branded<number, 'PageNumber'>
+
+/**
+ * Branded type for database migration versions.
+ *
+ * Represents a sequential migration version number (must be >= 1).
+ *
+ * @see {@link createMigrationVersion} - Factory function with validation
+ */
+export type MigrationVersion = Branded<number, 'MigrationVersion'>
+
+/**
+ * Branded type for query identifiers.
+ *
+ * Used to uniquely identify and track queries for observability and cancellation.
+ *
+ * @see {@link createQueryId} - Factory function with validation
+ */
+export type QueryId = Branded<string, 'QueryId'>
+
+/**
+ * Branded type for snapshot identifiers.
+ *
+ * Represents a PostgreSQL snapshot ID (64-bit integer as string).
+ *
+ * @see {@link createSnapshotId} - Factory function with validation
+ */
+export type SnapshotId = Branded<string, 'SnapshotId'>
+
+/**
+ * Branded type for storage block identifiers.
+ *
+ * Identifies a block in the tiered storage system with format `{TIER}:{key}`.
+ *
+ * @example
+ * ```typescript
+ * const hotBlock = createBlockId('HOT:users/page-42')
+ * const coldBlock = createBlockId('COLD:archive/2024/data.bin')
+ * ```
+ *
+ * @see {@link createBlockId} - Factory function with validation
+ */
+export type BlockId = Branded<string, 'BlockId'>
+
+/**
+ * Branded type for shard identifiers.
+ *
+ * Identifies a data shard in horizontally partitioned deployments.
+ *
+ * @see {@link createShardId} - Factory function with validation
+ */
+export type ShardId = Branded<string, 'ShardId'>
+
+/**
+ * Branded type for ingest identifiers.
+ *
+ * Identifies an ingest operation or stream for data loading.
+ *
+ * @see {@link createIngestId} - Factory function with validation
+ */
+export type IngestId = Branded<string, 'IngestId'>
+
+/**
+ * Branded type for replica identifiers.
+ *
+ * Identifies a database replica in replicated deployments.
+ *
+ * @see {@link createReplicaId} - Factory function with validation
+ */
+export type ReplicaId = Branded<string, 'ReplicaId'>
+
+/**
+ * Branded type for batch operation identifiers.
+ *
+ * Identifies a batch of operations for bulk processing.
+ *
+ * @see {@link createBatchId} - Factory function with validation
+ */
+export type BatchId = Branded<string, 'BatchId'>
+
+// =============================================================================
+// Validation Constants
+// =============================================================================
+
+/**
+ * Common pattern for alphanumeric identifiers.
+ *
+ * Many ID types share this pattern: must start with an alphanumeric character
+ * and contain only alphanumeric characters, underscores, or hyphens.
+ *
+ * Used by: TenantId, QueryId, ShardId, IngestId, ReplicaId, BatchId
+ *
+ * @example Valid patterns
+ * - `'tenant1'` - starts with letter
+ * - `'123abc'` - starts with number
+ * - `'my-id'` - contains hyphens
+ * - `'my_id'` - contains underscores
+ *
+ * @example Invalid patterns
+ * - `'-invalid'` - starts with hyphen
+ * - `'_invalid'` - starts with underscore
+ * - `'has spaces'` - contains spaces
+ * - `'has.dots'` - contains dots
+ */
+export const ALPHANUMERIC_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9_-]*$/
+
+/** Maximum allowed length for tenant IDs (128 characters). */
+export const TENANT_ID_MAX_LENGTH = 128
+
+/**
+ * Validation pattern for tenant IDs.
+ *
+ * Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen.
+ *
+ * @see {@link ALPHANUMERIC_ID_PATTERN} - This is an alias for the common alphanumeric pattern
+ */
+export const TENANT_ID_PATTERN = ALPHANUMERIC_ID_PATTERN
+
+/** Maximum allowed page number (99,999,999). */
+export const MAX_PAGE_NUMBER = 99999999
+
+/**
+ * Validation pattern for query IDs.
+ *
+ * @see {@link ALPHANUMERIC_ID_PATTERN} - This is an alias for the common alphanumeric pattern
+ */
+export const QUERY_ID_PATTERN = ALPHANUMERIC_ID_PATTERN
+
+/**
+ * Validation pattern for snapshot IDs (numeric strings).
+ *
+ * Matches optional negative sign followed by one or more digits.
+ * Used for PostgreSQL 64-bit transaction/snapshot identifiers.
+ */
+export const SNAPSHOT_ID_PATTERN = /^-?[0-9]+$/
+
+/**
+ * Maximum snapshot ID value (2^63 - 1 as string).
+ *
+ * Represents the maximum value for a signed 64-bit integer.
+ * Stored as string to avoid JavaScript number precision issues.
+ */
+export const MAX_SNAPSHOT_ID = '9223372036854775807'
+
+/**
+ * Validation pattern for block IDs.
+ *
+ * Format: `{HOT|WARM|COLD}:{key}`
+ * - Tier must be uppercase: HOT, WARM, or COLD
+ * - Key can contain alphanumeric, underscore, hyphen, dot, or slash
+ *
+ * @example Valid block IDs
+ * - `'HOT:cache/session-123'`
+ * - `'WARM:data/recent.db'`
+ * - `'COLD:archive/2024/backup.tar'`
+ */
+export const BLOCK_ID_PATTERN = /^(HOT|WARM|COLD):[a-zA-Z0-9_\-/.]+$/
+
+/**
+ * Validation pattern for shard IDs.
+ *
+ * @see {@link ALPHANUMERIC_ID_PATTERN} - This is an alias for the common alphanumeric pattern
+ */
+export const SHARD_ID_PATTERN = ALPHANUMERIC_ID_PATTERN
+
+/** Maximum allowed length for shard IDs (64 characters). */
+export const SHARD_ID_MAX_LENGTH = 64
+
+/**
+ * Validation pattern for ingest IDs.
+ *
+ * @see {@link ALPHANUMERIC_ID_PATTERN} - This is an alias for the common alphanumeric pattern
+ */
+export const INGEST_ID_PATTERN = ALPHANUMERIC_ID_PATTERN
+
+/** Maximum allowed length for ingest IDs (64 characters). */
+export const INGEST_ID_MAX_LENGTH = 64
+
+/**
+ * Validation pattern for replica IDs.
+ *
+ * @see {@link ALPHANUMERIC_ID_PATTERN} - This is an alias for the common alphanumeric pattern
+ */
+export const REPLICA_ID_PATTERN = ALPHANUMERIC_ID_PATTERN
+
+/** Maximum allowed length for replica IDs (64 characters). */
+export const REPLICA_ID_MAX_LENGTH = 64
+
+/**
+ * Validation pattern for batch IDs.
+ *
+ * @see {@link ALPHANUMERIC_ID_PATTERN} - This is an alias for the common alphanumeric pattern
+ */
+export const BATCH_ID_PATTERN = ALPHANUMERIC_ID_PATTERN
+
+/** Maximum allowed length for batch IDs (128 characters). */
+export const BATCH_ID_MAX_LENGTH = 128
+
+// =============================================================================
+// Factory Functions
+// =============================================================================
+
+/**
+ * Creates a validated tenant ID from a string.
+ *
+ * Tenant IDs are used to uniquely identify tenants in multi-tenant deployments.
+ * They must start with an alphanumeric character and can only contain
+ * alphanumeric characters, underscores, or hyphens.
+ *
+ * @param value - The raw string to validate and brand
+ * @returns A branded TenantId
+ * @throws Error if the value is empty, exceeds max length, or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const tenantId = createTenantId('acme-corp')
+ * console.log(unwrap(tenantId)) // 'acme-corp'
+ * ```
+ *
+ * @example Error handling
+ * ```typescript
+ * try {
+ *   createTenantId('-invalid') // Throws: starts with hyphen
+ * } catch (error) {
+ *   console.error('Invalid tenant:', error.message)
+ * }
+ * ```
+ *
+ * @example Type-safe function parameter
+ * ```typescript
+ * function loadTenantData(id: TenantId): Promise<Data> {
+ *   // id is guaranteed to be valid
+ *   return fetch(`/api/tenants/${unwrap(id)}`)
+ * }
+ *
+ * const tenantId = createTenantId('acme-corp')
+ * await loadTenantData(tenantId) // OK
+ * await loadTenantData('plain-string') // Compile error!
+ * ```
+ *
+ * @see {@link isTenantId} - Type guard for checking without throwing
+ * @see {@link unsafeTenantId} - Skip validation (use with caution)
+ */
+export function createTenantId(value: string): TenantId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid tenant ID: cannot be empty')
+  }
+  if (value.length > TENANT_ID_MAX_LENGTH) {
+    throw new Error(`Invalid tenant ID: exceeds maximum length of ${TENANT_ID_MAX_LENGTH}`)
+  }
+  if (!TENANT_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid tenant ID: "${value}". Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen`)
+  }
+  return value as TenantId
+}
+
+/**
+ * Creates a validated page number.
+ *
+ * Page numbers represent storage pages in the tiered storage system.
+ * They must be non-negative integers within the allowed range (0 to 99,999,999).
+ *
+ * @param value - The raw number to validate and brand
+ * @returns A branded PageNumber
+ * @throws Error if value is negative, non-integer, or exceeds maximum
+ *
+ * @example Basic usage
+ * ```typescript
+ * const page = createPageNumber(42)
+ * console.log(unwrap(page)) // 42
+ * ```
+ *
+ * @example Boundary values
+ * ```typescript
+ * createPageNumber(0)           // Valid: minimum page
+ * createPageNumber(99999999)    // Valid: maximum page (MAX_PAGE_NUMBER)
+ * createPageNumber(-1)          // Throws: negative not allowed
+ * createPageNumber(100000000)   // Throws: exceeds maximum
+ * createPageNumber(1.5)         // Throws: must be integer
+ * ```
+ *
+ * @see {@link isPageNumber} - Type guard for checking without throwing
+ * @see {@link MAX_PAGE_NUMBER} - Maximum allowed value (99,999,999)
+ */
+export function createPageNumber(value: number): PageNumber {
+  if (!Number.isInteger(value) || value < 0 || value > MAX_PAGE_NUMBER) {
+    throw new Error(`Invalid page number: ${value}. Must be integer 0-${MAX_PAGE_NUMBER}`)
+  }
+  return value as PageNumber
+}
+
+/**
+ * Creates a validated migration version number.
+ *
+ * Migration versions represent sequential database schema versions.
+ * They must be positive integers (>= 1) since version 0 represents no migrations.
+ *
+ * @param value - The raw number to validate and brand
+ * @returns A branded MigrationVersion
+ * @throws Error if value is zero, negative, or non-integer
+ *
+ * @example Basic usage
+ * ```typescript
+ * const version = createMigrationVersion(3)
+ * console.log(unwrap(version)) // 3
+ * ```
+ *
+ * @example Migration tracking
+ * ```typescript
+ * async function runMigrations(currentVersion: MigrationVersion) {
+ *   const migrations = [
+ *     { version: createMigrationVersion(1), sql: 'CREATE TABLE users...' },
+ *     { version: createMigrationVersion(2), sql: 'ALTER TABLE users...' },
+ *     { version: createMigrationVersion(3), sql: 'CREATE INDEX...' },
+ *   ]
+ *   for (const m of migrations) {
+ *     if (unwrap(m.version) > unwrap(currentVersion)) {
+ *       await db.exec(m.sql)
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link isMigrationVersion} - Type guard for checking without throwing
+ */
+export function createMigrationVersion(value: number): MigrationVersion {
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`Invalid migration version: ${value}. Must be positive integer`)
+  }
+  return value as MigrationVersion
+}
+
+/**
+ * Creates a validated query ID from a string.
+ *
+ * Query IDs are used to uniquely identify and track queries for observability,
+ * logging, tracing, and cancellation purposes.
+ *
+ * @param value - The raw string to validate and brand
+ * @returns A branded QueryId
+ * @throws Error if the value is empty or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const queryId = createQueryId('query-abc123')
+ * console.log(unwrap(queryId)) // 'query-abc123'
+ * ```
+ *
+ * @example With tracing/observability
+ * ```typescript
+ * const queryId = createQueryId(`q-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+ * logger.info('Executing query', { queryId: unwrap(queryId), sql })
+ * const result = await db.query(sql)
+ * logger.info('Query completed', { queryId: unwrap(queryId), rows: result.length })
+ * ```
+ *
+ * @see {@link isQueryId} - Type guard for checking without throwing
+ */
+export function createQueryId(value: string): QueryId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid query ID: cannot be empty')
+  }
+  if (!QUERY_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid query ID: "${value}". Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen`)
+  }
+  return value as QueryId
+}
+
+/**
+ * Creates a validated snapshot ID from a numeric string.
+ *
+ * Snapshot IDs represent PostgreSQL transaction snapshots as 64-bit signed integers.
+ * They are stored as strings to avoid JavaScript's number precision limitations
+ * for values larger than Number.MAX_SAFE_INTEGER.
+ *
+ * @param value - The raw string to validate and brand (must be numeric)
+ * @returns A branded SnapshotId
+ * @throws Error if empty, non-numeric, or exceeds 64-bit signed integer range
+ *
+ * @example Basic usage
+ * ```typescript
+ * const snapshotId = createSnapshotId('1234567890')
+ * console.log(unwrap(snapshotId)) // '1234567890'
+ * ```
+ *
+ * @example Large values (beyond JS number precision)
+ * ```typescript
+ * // Safe: stored as string, no precision loss
+ * const largeId = createSnapshotId('9223372036854775807') // Max 64-bit signed int
+ * ```
+ *
+ * @example Negative values
+ * ```typescript
+ * const negativeId = createSnapshotId('-123') // Valid
+ * ```
+ *
+ * @see {@link isSnapshotId} - Type guard for checking without throwing
+ * @see {@link MAX_SNAPSHOT_ID} - Maximum allowed value (2^63 - 1)
+ */
+export function createSnapshotId(value: string): SnapshotId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid snapshot ID: cannot be empty')
+  }
+  if (!SNAPSHOT_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid snapshot ID: "${value}". Must be a numeric string (64-bit integer)`)
+  }
+  const absValue = value.startsWith('-') ? value.slice(1) : value
+  if (absValue.length > MAX_SNAPSHOT_ID.length || (absValue.length === MAX_SNAPSHOT_ID.length && absValue > MAX_SNAPSHOT_ID)) {
+    throw new Error(`Invalid snapshot ID: "${value}". Exceeds maximum 64-bit integer value`)
+  }
+  return value as SnapshotId
+}
+
+/**
+ * Creates a validated block ID from a string.
+ *
+ * Block IDs identify storage blocks in the tiered storage system. The format
+ * is `{TIER}:{key}` where TIER indicates the storage tier (HOT, WARM, or COLD).
+ *
+ * Storage tiers:
+ * - **HOT**: Cloudflare Cache API - fastest access, frequently used data
+ * - **WARM**: Durable Object SQLite - medium access, recent data
+ * - **COLD**: R2 object storage - archival, rarely accessed data
+ *
+ * @param value - The raw string to validate (format: `{HOT|WARM|COLD}:{key}`)
+ * @returns A branded BlockId
+ * @throws Error if the value is empty or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const blockId = createBlockId('HOT:users/page-42')
+ * console.log(unwrap(blockId)) // 'HOT:users/page-42'
+ * ```
+ *
+ * @example Different storage tiers
+ * ```typescript
+ * const hot = createBlockId('HOT:cache/session-123')    // Frequently accessed
+ * const warm = createBlockId('WARM:data/users.db')      // Medium access
+ * const cold = createBlockId('COLD:archive/2024.tar')   // Rarely accessed
+ * ```
+ *
+ * @example Path-like keys
+ * ```typescript
+ * const block = createBlockId('COLD:archive/2024/01/backup.bin')
+ * ```
+ *
+ * @see {@link isBlockId} - Type guard for checking without throwing
+ */
+export function createBlockId(value: string): BlockId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid block ID: cannot be empty')
+  }
+  if (!BLOCK_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid block ID: "${value}". Must be in format "{HOT|WARM|COLD}:{key}" with alphanumeric key`)
+  }
+  return value as BlockId
+}
+
+/**
+ * Creates a validated shard ID from a string.
+ *
+ * Shard IDs identify data partitions in horizontally sharded deployments.
+ * Commonly used for geographic or logical data partitioning strategies.
+ *
+ * @param value - The raw string to validate and brand
+ * @returns A branded ShardId
+ * @throws Error if empty, exceeds max length (64), or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const shardId = createShardId('shard-us-west-1')
+ * console.log(unwrap(shardId)) // 'shard-us-west-1'
+ * ```
+ *
+ * @example Geographic sharding
+ * ```typescript
+ * const shards = [
+ *   createShardId('shard-us-west'),
+ *   createShardId('shard-us-east'),
+ *   createShardId('shard-eu-central'),
+ *   createShardId('shard-ap-south'),
+ * ]
+ * ```
+ *
+ * @example Hash-based sharding
+ * ```typescript
+ * function getShardForUser(userId: string): ShardId {
+ *   const hash = hashCode(userId) % 4
+ *   return createShardId(`shard-${hash}`)
+ * }
+ * ```
+ *
+ * @see {@link isShardId} - Type guard for checking without throwing
+ * @see {@link SHARD_ID_MAX_LENGTH} - Maximum allowed length (64)
+ */
+export function createShardId(value: string): ShardId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid shard ID: cannot be empty')
+  }
+  if (value.length > SHARD_ID_MAX_LENGTH) {
+    throw new Error(`Invalid shard ID: exceeds maximum length of ${SHARD_ID_MAX_LENGTH}`)
+  }
+  if (!SHARD_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid shard ID: "${value}". Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen`)
+  }
+  return value as ShardId
+}
+
+/**
+ * Creates a validated ingest ID from a string.
+ *
+ * Ingest IDs identify data loading operations such as bulk imports, streaming
+ * data pipelines, or ETL jobs. Useful for tracking and resuming long-running operations.
+ *
+ * @param value - The raw string to validate and brand
+ * @returns A branded IngestId
+ * @throws Error if empty, exceeds max length (64), or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const ingestId = createIngestId('bulk-import-2024-01')
+ * console.log(unwrap(ingestId)) // 'bulk-import-2024-01'
+ * ```
+ *
+ * @example Timestamped ingest job
+ * ```typescript
+ * const ingestId = createIngestId(`csv-import-${Date.now()}`)
+ * await startIngestJob(ingestId, 'data.csv')
+ * // Later: check status or resume
+ * const status = await getIngestStatus(ingestId)
+ * ```
+ *
+ * @see {@link isIngestId} - Type guard for checking without throwing
+ * @see {@link INGEST_ID_MAX_LENGTH} - Maximum allowed length (64)
+ */
+export function createIngestId(value: string): IngestId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid ingest ID: cannot be empty')
+  }
+  if (value.length > INGEST_ID_MAX_LENGTH) {
+    throw new Error(`Invalid ingest ID: exceeds maximum length of ${INGEST_ID_MAX_LENGTH}`)
+  }
+  if (!INGEST_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid ingest ID: "${value}". Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen`)
+  }
+  return value as IngestId
+}
+
+/**
+ * Creates a validated replica ID from a string.
+ *
+ * Replica IDs identify database read replicas in replicated deployments.
+ * Used for routing read queries and tracking replication lag.
+ *
+ * @param value - The raw string to validate and brand
+ * @returns A branded ReplicaId
+ * @throws Error if empty, exceeds max length (64), or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const replicaId = createReplicaId('replica-eu-1')
+ * console.log(unwrap(replicaId)) // 'replica-eu-1'
+ * ```
+ *
+ * @example Regional replicas
+ * ```typescript
+ * const primary = createReplicaId('primary')
+ * const replicas = [
+ *   createReplicaId('replica-us-east'),
+ *   createReplicaId('replica-eu-west'),
+ *   createReplicaId('replica-ap-south'),
+ * ]
+ * ```
+ *
+ * @example Read routing
+ * ```typescript
+ * function selectReplica(region: string): ReplicaId {
+ *   const mapping: Record<string, ReplicaId> = {
+ *     'us': createReplicaId('replica-us-east'),
+ *     'eu': createReplicaId('replica-eu-west'),
+ *   }
+ *   return mapping[region] ?? createReplicaId('primary')
+ * }
+ * ```
+ *
+ * @see {@link isReplicaId} - Type guard for checking without throwing
+ * @see {@link REPLICA_ID_MAX_LENGTH} - Maximum allowed length (64)
+ */
+export function createReplicaId(value: string): ReplicaId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid replica ID: cannot be empty')
+  }
+  if (value.length > REPLICA_ID_MAX_LENGTH) {
+    throw new Error(`Invalid replica ID: exceeds maximum length of ${REPLICA_ID_MAX_LENGTH}`)
+  }
+  if (!REPLICA_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid replica ID: "${value}". Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen`)
+  }
+  return value as ReplicaId
+}
+
+/**
+ * Creates a validated batch ID from a string.
+ *
+ * Batch IDs identify groups of operations processed together. Useful for
+ * transactional batches, bulk operations, and audit trails.
+ *
+ * @param value - The raw string to validate and brand
+ * @returns A branded BatchId
+ * @throws Error if empty, exceeds max length (128), or has invalid format
+ *
+ * @example Basic usage
+ * ```typescript
+ * const batchId = createBatchId('batch-2024-01-21-abc123')
+ * console.log(unwrap(batchId)) // 'batch-2024-01-21-abc123'
+ * ```
+ *
+ * @example Daily batch jobs
+ * ```typescript
+ * const date = new Date().toISOString().slice(0, 10) // '2024-01-21'
+ * const batchId = createBatchId(`nightly-sync-${date}`)
+ * await runBatchJob(batchId)
+ * ```
+ *
+ * @example Transactional batch
+ * ```typescript
+ * async function processBatch(operations: Operation[]) {
+ *   const batchId = createBatchId(`tx-${Date.now()}`)
+ *   try {
+ *     for (const op of operations) {
+ *       await execute(op, batchId)
+ *     }
+ *     await commit(batchId)
+ *   } catch (error) {
+ *     await rollback(batchId)
+ *     throw error
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link isBatchId} - Type guard for checking without throwing
+ * @see {@link BATCH_ID_MAX_LENGTH} - Maximum allowed length (128)
+ */
+export function createBatchId(value: string): BatchId {
+  if (!value || value.length === 0) {
+    throw new Error('Invalid batch ID: cannot be empty')
+  }
+  if (value.length > BATCH_ID_MAX_LENGTH) {
+    throw new Error(`Invalid batch ID: exceeds maximum length of ${BATCH_ID_MAX_LENGTH}`)
+  }
+  if (!BATCH_ID_PATTERN.test(value)) {
+    throw new Error(`Invalid batch ID: "${value}". Must start with alphanumeric and contain only alphanumeric, underscore, or hyphen`)
+  }
+  return value as BatchId
+}
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+/**
+ * Type guard that checks if a value is a valid TenantId.
+ *
+ * Use this function to safely narrow an unknown value to TenantId without
+ * throwing an exception. Returns false for invalid values instead of throwing.
+ *
+ * @param value - The value to check (any type)
+ * @returns true if value is a valid TenantId, false otherwise
+ *
+ * @example Basic validation
+ * ```typescript
+ * if (isTenantId(input)) {
+ *   // TypeScript knows input is TenantId here
+ *   await loadTenant(input)
+ * }
+ * ```
+ *
+ * @example Filtering array of unknown values
+ * ```typescript
+ * const inputs: unknown[] = ['valid-tenant', '', 123, '-invalid']
+ * const validTenants = inputs.filter(isTenantId)
+ * // validTenants: TenantId[] = ['valid-tenant' as TenantId]
+ * ```
+ *
+ * @example Optional value handling
+ * ```typescript
+ * function getTenant(id: string | undefined): TenantId | undefined {
+ *   return id && isTenantId(id) ? id : undefined
+ * }
+ * ```
+ *
+ * @see {@link createTenantId} - Factory that throws on invalid input
+ */
+export function isTenantId(value: unknown): value is TenantId {
+  return typeof value === 'string' && value.length > 0 && value.length <= TENANT_ID_MAX_LENGTH && TENANT_ID_PATTERN.test(value)
+}
+
+/**
+ * Type guard that checks if a value is a valid PageNumber.
+ *
+ * Validates that the value is a non-negative integer within the allowed range.
+ *
+ * @param value - The value to check (any type)
+ * @returns true if value is a valid PageNumber, false otherwise
+ *
+ * @example Basic validation
+ * ```typescript
+ * if (isPageNumber(pageIndex)) {
+ *   await loadPage(pageIndex)
+ * }
+ * ```
+ *
+ * @see {@link createPageNumber} - Factory that throws on invalid input
+ * @see {@link MAX_PAGE_NUMBER} - Maximum allowed value
+ */
+export function isPageNumber(value: unknown): value is PageNumber {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0 && value <= MAX_PAGE_NUMBER
+}
+
+/**
+ * Type guard that checks if a value is a valid MigrationVersion.
+ *
+ * Validates that the value is a positive integer (>= 1).
+ *
+ * @param value - The value to check (any type)
+ * @returns true if value is a valid MigrationVersion, false otherwise
+ *
+ * @example Schema version check
+ * ```typescript
+ * if (isMigrationVersion(schemaVersion)) {
+ *   await runMigration(schemaVersion)
+ * }
+ * ```
+ *
+ * @see {@link createMigrationVersion} - Factory that throws on invalid input
+ */
+export function isMigrationVersion(value: unknown): value is MigrationVersion {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1
+}
+
+/**
+ * Type guard that checks if a value is a valid QueryId.
+ *
+ * @param value - The value to check (any type)
+ * @returns true if value is a valid QueryId, false otherwise
+ *
+ * @see {@link createQueryId} - Factory that throws on invalid input
+ */
+export function isQueryId(value: unknown): value is QueryId {
+  return typeof value === 'string' && value.length > 0 && QUERY_ID_PATTERN.test(value)
+}
+
+/**
+ * Type guard that checks if a value is a valid SnapshotId.
+ *
+ * @param value - The value to check
+ * @returns true if value is a valid SnapshotId
+ */
+export function isSnapshotId(value: unknown): value is SnapshotId {
+  if (typeof value !== 'string' || value.length === 0 || !SNAPSHOT_ID_PATTERN.test(value)) return false
+  const absValue = value.startsWith('-') ? value.slice(1) : value
+  return absValue.length < MAX_SNAPSHOT_ID.length || (absValue.length === MAX_SNAPSHOT_ID.length && absValue <= MAX_SNAPSHOT_ID)
+}
+
+/**
+ * Type guard that checks if a value is a valid BlockId.
+ *
+ * @param value - The value to check
+ * @returns true if value is a valid BlockId
+ */
+export function isBlockId(value: unknown): value is BlockId {
+  return typeof value === 'string' && value.length > 0 && BLOCK_ID_PATTERN.test(value)
+}
+
+/**
+ * Type guard that checks if a value is a valid ShardId.
+ *
+ * @param value - The value to check
+ * @returns true if value is a valid ShardId
+ */
+export function isShardId(value: unknown): value is ShardId {
+  return typeof value === 'string' && value.length > 0 && value.length <= SHARD_ID_MAX_LENGTH && SHARD_ID_PATTERN.test(value)
+}
+
+/**
+ * Type guard that checks if a value is a valid IngestId.
+ *
+ * @param value - The value to check
+ * @returns true if value is a valid IngestId
+ */
+export function isIngestId(value: unknown): value is IngestId {
+  return typeof value === 'string' && value.length > 0 && value.length <= INGEST_ID_MAX_LENGTH && INGEST_ID_PATTERN.test(value)
+}
+
+/**
+ * Type guard that checks if a value is a valid ReplicaId.
+ *
+ * @param value - The value to check
+ * @returns true if value is a valid ReplicaId
+ */
+export function isReplicaId(value: unknown): value is ReplicaId {
+  return typeof value === 'string' && value.length > 0 && value.length <= REPLICA_ID_MAX_LENGTH && REPLICA_ID_PATTERN.test(value)
+}
+
+/**
+ * Type guard that checks if a value is a valid BatchId.
+ *
+ * @param value - The value to check
+ * @returns true if value is a valid BatchId
+ */
+export function isBatchId(value: unknown): value is BatchId {
+  return typeof value === 'string' && value.length > 0 && value.length <= BATCH_ID_MAX_LENGTH && BATCH_ID_PATTERN.test(value)
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Extracts the underlying primitive value from a branded type.
+ *
+ * Use this when you need to pass a branded value to an API that expects
+ * the raw primitive type (e.g., JSON serialization, external APIs).
+ *
+ * @typeParam T - The underlying primitive type
+ * @typeParam Brand - The brand string
+ * @param value - The branded value to unwrap
+ * @returns The underlying primitive value
+ *
+ * @example
+ * ```typescript
+ * const tenantId = createTenantId('acme-corp')
+ * const raw: string = unwrap(tenantId)  // 'acme-corp'
+ * ```
+ */
+export function unwrap<T, Brand extends string>(value: Branded<T, Brand>): T {
+  return value as T
+}
+
+// =============================================================================
+// Unsafe Factory Functions
+// =============================================================================
+
+/**
+ * Creates a TenantId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated tenant ID string
+ * @returns A branded TenantId
+ *
+ * @see {@link createTenantId} - Safe factory with validation
+ */
+export function unsafeTenantId(value: string): TenantId {
+  return value as TenantId
+}
+
+/**
+ * Creates a PageNumber without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated page number
+ * @returns A branded PageNumber
+ */
+export function unsafePageNumber(value: number): PageNumber {
+  return value as PageNumber
+}
+
+/**
+ * Creates a MigrationVersion without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated migration version
+ * @returns A branded MigrationVersion
+ */
+export function unsafeMigrationVersion(value: number): MigrationVersion {
+  return value as MigrationVersion
+}
+
+/**
+ * Creates a QueryId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated query ID string
+ * @returns A branded QueryId
+ */
+export function unsafeQueryId(value: string): QueryId {
+  return value as QueryId
+}
+
+/**
+ * Creates a SnapshotId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated snapshot ID string
+ * @returns A branded SnapshotId
+ */
+export function unsafeSnapshotId(value: string): SnapshotId {
+  return value as SnapshotId
+}
+
+/**
+ * Creates a BlockId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated block ID string
+ * @returns A branded BlockId
+ */
+export function unsafeBlockId(value: string): BlockId {
+  return value as BlockId
+}
+
+/**
+ * Creates a ShardId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated shard ID string
+ * @returns A branded ShardId
+ */
+export function unsafeShardId(value: string): ShardId {
+  return value as ShardId
+}
+
+/**
+ * Creates an IngestId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated ingest ID string
+ * @returns A branded IngestId
+ */
+export function unsafeIngestId(value: string): IngestId {
+  return value as IngestId
+}
+
+/**
+ * Creates a ReplicaId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated replica ID string
+ * @returns A branded ReplicaId
+ */
+export function unsafeReplicaId(value: string): ReplicaId {
+  return value as ReplicaId
+}
+
+/**
+ * Creates a BatchId without validation.
+ *
+ * **WARNING**: Only use this when you are certain the value is valid.
+ *
+ * @param value - Pre-validated batch ID string
+ * @returns A branded BatchId
+ */
+export function unsafeBatchId(value: string): BatchId {
+  return value as BatchId
+}