|
| 1 | +import process from 'node:process'; |
| 2 | +import { threadId } from 'node:worker_threads'; |
| 3 | + |
| 4 | +/** |
| 5 | + * Counter interface for generating sequential instance IDs. |
| 6 | + * Encapsulates increment logic within the counter implementation. |
| 7 | + */ |
| 8 | +export interface Counter { |
| 9 | + /** |
| 10 | + * Returns the next counter value and increments the internal state. |
| 11 | + * @returns The next counter value |
| 12 | + */ |
| 13 | + next(): number; |
| 14 | +} |
| 15 | + |
| 16 | +/** |
| 17 | + * Base regex pattern for time ID format: yyyymmdd-hhmmss-ms |
| 18 | + */ |
| 19 | +const TIME_ID_BASE = /\d{8}-\d{6}-\d{3}/; |
| 20 | + |
| 21 | +/** |
| 22 | + * Regex patterns for validating ID formats used in Write-Ahead Logging (WAL) system. |
| 23 | + * All patterns use strict anchors (^ and $) to ensure complete matches. |
| 24 | + */ |
| 25 | +export const WAL_ID_PATTERNS = Object.freeze({ |
| 26 | + /** |
| 27 | + * Time ID / Run ID format: yyyymmdd-hhmmss-ms |
| 28 | + * Example: "20240101-120000-000" |
| 29 | + * Used by: getUniqueTimeId() |
| 30 | + */ |
| 31 | + TIME_ID: new RegExp(`^${TIME_ID_BASE.source}$`), |
| 32 | + /** |
| 33 | + * Group ID format: alias by convention, semantically represents a group of shards |
| 34 | + * Example: "20240101-120000-000" |
| 35 | + * Used by: ShardedWal.groupId |
| 36 | + */ |
| 37 | + GROUP_ID: new RegExp(`^${TIME_ID_BASE.source}$`), |
| 38 | + /** |
| 39 | + * Process/Thread ID format: timeId-pid-threadId |
| 40 | + * Example: "20240101-120000-000-12345-1" |
| 41 | + * Used by: getUniqueProcessThreadId() |
| 42 | + */ |
| 43 | + PROCESS_THREAD_ID: new RegExp(`^${TIME_ID_BASE.source}-\\d+-\\d+$`), |
| 44 | + /** |
| 45 | + * Instance ID / Shard ID format: timeId.pid.threadId.counter |
| 46 | + * Example: "20240101-120000-000.12345.1.1" |
| 47 | + * Used by: getUniqueInstanceId(), getShardId() |
| 48 | + */ |
| 49 | + INSTANCE_ID: new RegExp(`^${TIME_ID_BASE.source}\\.\\d+\\.\\d+\\.\\d+$`), |
| 50 | + /** @deprecated Use INSTANCE_ID instead */ |
| 51 | + SHARD_ID: new RegExp(`^${TIME_ID_BASE.source}\\.\\d+\\.\\d+\\.\\d+$`), |
| 52 | + /** @deprecated Use TIME_ID instead */ |
| 53 | + READABLE_DATE: new RegExp(`^${TIME_ID_BASE.source}$`), |
| 54 | +} as const); |
| 55 | + |
| 56 | +/** |
| 57 | + * Generates a unique run ID. |
| 58 | + * This ID uniquely identifies a run/execution with a globally unique, sortable, human-readable date string. |
| 59 | + * Format: yyyymmdd-hhmmss-ms |
| 60 | + * Example: "20240101-120000-000" |
| 61 | + * |
| 62 | + * @returns A unique run ID string in readable date format |
| 63 | + */ |
| 64 | +export function getUniqueTimeId(): string { |
| 65 | + return sortableReadableDateString( |
| 66 | + Math.floor(performance.timeOrigin + performance.now()), |
| 67 | + ); |
| 68 | +} |
| 69 | + |
| 70 | +/** |
| 71 | + * Generates a unique process/thread ID. |
| 72 | + * This ID uniquely identifies a process/thread execution and prevents race conditions when running |
| 73 | + * the same plugin for multiple projects in parallel. |
| 74 | + * Format: timeId-pid-threadId |
| 75 | + * Example: "20240101-120000-000-12345-1" |
| 76 | + * |
| 77 | + * @returns A unique ID string combining timestamp, process ID, and thread ID |
| 78 | + */ |
| 79 | +export function getUniqueProcessThreadId(): string { |
| 80 | + return `${getUniqueTimeId()}-${process.pid}-${threadId}`; |
| 81 | +} |
| 82 | + |
| 83 | +/** |
| 84 | + * Generates a unique instance ID based on performance time origin, process ID, thread ID, and instance count. |
| 85 | + * This ID uniquely identifies a WAL instance across processes and threads. |
| 86 | + * Format: timestamp.pid.threadId.counter |
| 87 | + * Example: "20240101-120000-000.12345.1.1" |
| 88 | + * |
| 89 | + * @param counter - Counter that provides the next instance count value |
| 90 | + * @returns A unique ID string combining timestamp, process ID, thread ID, and counter |
| 91 | + */ |
| 92 | +export function getUniqueInstanceId(counter: Counter): string { |
| 93 | + return `${getUniqueTimeId()}.${process.pid}.${threadId}.${counter.next()}`; |
| 94 | +} |
| 95 | + |
| 96 | +/** |
| 97 | + * Generates a unique instance ID and updates a static class property. |
| 98 | + * Encapsulates the read → increment → write pattern safely within a single execution context. |
| 99 | + * |
| 100 | + * @param getCount - Function that returns the current instance count |
| 101 | + * @param setCount - Function that sets the new instance count |
| 102 | + * @returns A unique ID string combining timestamp, process ID, thread ID, and counter |
| 103 | + */ |
| 104 | +export function getUniqueInstanceIdAndUpdate( |
| 105 | + getCount: () => number, |
| 106 | + setCount: (value: number) => void, |
| 107 | +): string { |
| 108 | + let value = getCount(); |
| 109 | + const counter: Counter = { |
| 110 | + next() { |
| 111 | + return ++value; |
| 112 | + }, |
| 113 | + }; |
| 114 | + const id = getUniqueInstanceId(counter); |
| 115 | + setCount(value); |
| 116 | + return id; |
| 117 | +} |
| 118 | + |
| 119 | +/** |
| 120 | + * Converts a timestamp in milliseconds to a sortable, human-readable date string. |
| 121 | + * Format: yyyymmdd-hhmmss-ms |
| 122 | + * Example: "20240101-120000-000" |
| 123 | + * |
| 124 | + * @param timestampMs - Timestamp in milliseconds |
| 125 | + * @returns A sortable date string in yyyymmdd-hhmmss-ms format |
| 126 | + */ |
| 127 | +export function sortableReadableDateString(timestampMs: number): string { |
| 128 | + const date = new Date(timestampMs); |
| 129 | + const MILLISECONDS_PER_SECOND = 1000; |
| 130 | + const yyyy = date.getFullYear(); |
| 131 | + const mm = String(date.getMonth() + 1).padStart(2, '0'); |
| 132 | + const dd = String(date.getDate()).padStart(2, '0'); |
| 133 | + const hh = String(date.getHours()).padStart(2, '0'); |
| 134 | + const min = String(date.getMinutes()).padStart(2, '0'); |
| 135 | + const ss = String(date.getSeconds()).padStart(2, '0'); |
| 136 | + // eslint-disable-next-line @typescript-eslint/no-magic-numbers |
| 137 | + const ms = String(timestampMs % MILLISECONDS_PER_SECOND).padStart(3, '0'); |
| 138 | + |
| 139 | + return `${yyyy}${mm}${dd}-${hh}${min}${ss}-${ms}`; |
| 140 | +} |
0 commit comments