MonoLexID

MonoLexID is a time-ordered and sortable Universally Unique Identifier (UUID) generator for Object Pascal (Lazarus/Free Pascal), producing identifiers structurally compatible with the RFC 9562 UUIDv7 layout while privileging intra-millisecond monotonicity.

Generation Policy

• Lexicographic Monotonicity: Identifiers are time-ordered at millisecond precision, ensuring natural sequential sorting, preventing index fragmentation and optimising database insertion performance.

• Time Integrity: The generator privileges chronological truth (clock-dependent). Should the system exhaust the sequence counter (4,096 allocations per millisecond) or detect a retrograde clock shift, generation is suspended via a CPU spin-wait loop. It yields (pauses) until physical time advances, so that identifiers are not generated with a fictitious-future time.

• Cryptographic Uniqueness: To preclude collisions in distributed environments, the remainder of the string payload is populated using OS-native, cryptographically secure pseudorandom number generators to minimise collision risk.

Structure

MonoLexID generates a 36-character string (xxxxxxxx-xxxx-7xxx-xxxx-xxxxxxxxxxxx), which breaks down as follows:

• Chars 1-8: UNIX Timestamp in Milliseconds (Part 1)
• Char 9: Hyphen -
• Chars 10-13: UNIX Timestamp in Milliseconds (Part 2)
• Char 14: Hyphen -
• Chars 15-18: Version Identifier (7) + 12-bit Sequence Counter
• Char 19: Hyphen -
• Chars 20-23: Variant Identifier (8, 9, a, or b) + Random Data
• Char 24: Hyphen -
• Chars 25-36: Secure Random Data

Usage

MonoLexID is contained entirely within a single unit with no external dependencies. To integrate it, download the latest version from the Releases page, include MonoLexID.pas in the project directory, and add it to the uses clause.

To generate a standard 36-character string format:

uses
  MonoLexID;

var
  NewID: String;
begin
  NewID := NewMonoLexID; 
end;

Alternatively, to retrieve the raw 16-byte array:

uses
  MonoLexID;

var
  RawBytes: TMonoLexIDBytes;
begin
  RawBytes := NewMonoLexIDBytes;
end;

Thread Safety Configuration

• MonoLexID uses threadvar by default for state management, providing efficient thread-local monotonic generation.

• If the application requires a globally monotonic sequence across multiple threads, it can be enabled by adding a -dMONOLEXID_GLOBAL_MONOTONIC flag in the project/compiler options or a {$DEFINE MONOLEXID_GLOBAL_MONOTONIC} directive at the very top of MonoLexID.pas.

Error Handling

• Due to reliance on physical time and secure OS-level randomisation, generation may fail if system-level anomalies occur (such as a CSPRNG failure or severe clock instability that causes the generation loop to time out).

• MonoLexID provides safe ‘Try’ functions that will return False rather than raising an exception. When using these functions, callers must handle the False result, as an empty string will be passed downstream. Recommended use for critical applications:

var
  NewID: String;
begin
  if TryNewMonoLexID(NewID) then
    WriteLn('Generated ID: ', NewID)
  else
    WriteLn('Critical Error: Could not generate a unique ID.');
end;

Compatibility

MonoLexID compiles and functions under:

• Windows
• Linux/macOS (Requires BaseUnix and /dev/urandom)
• Free Pascal 3.2.2/Lazarus

Acknowledgements

The project has benefited significantly from Google Gemini 3.1 Pro’s assistance for ideation, code generation, and refactoring.

License

The project is under the BSD 3-Clause License and is provided “as-is”, without any warranties. Please see the LICENSE file for details.