Metadata-Version: 2.3
Name: fourword
Version: 1.2.0
Requires-Python: >=3.9
Project-URL: GitHub, https://github.com/nercone-labs/fourword/
Description-Content-Type: text/markdown

# FourWord

## Overview
A new generation method for random identifiers.

It includes a timestamp at the beginning and uses Base32 Hex as the character set for text representation, allowing for sorting in chronological order.
Since 'Z' is used instead of '=' for padding, it should be usable in any environment that supports alphanumeric characters.

To minimize the possibility of collisions while preventing overflow, the timestamp is not fixed; instead, it occupies 1/4 of the total bits generated.
This allows for longer continuous use simply by increasing the total number of bits.
However, as a trade-off, unnecessary leading zeros will appear at the beginning of the timestamp portion.

It is intended for use in databases and similar applications.

## Etymology
The "Four" part comes from the fact that the timestamp occupies 1/4 of the total bits.
It is also a play on the word "Forward."

## Python Library
```
# Install using pip
pip3 install fourword

# Install using uv
uv pip install fourword

# Add to Project using uv
uv add fourword
```

```
from fourword.lib import FourWord

fourword = FourWord(bits=256)
print(fourword.text)
```

In Python, you can generate FourWord using the fourword library.
The fourword library works without any external dependencies.

The default bit size is 256.

The total number of bits must be divisible by 32.

## Specifications
A FourWord is represented as a byte sequence (big endian) as follows:

```
[ (Total bits/4) bit UNIX timestamp (UTC, ns) ] + [ (Total bits/4*3) bit CSPRNG ]
```

For example, when the total bit size is 256 bits, the timestamp is 64 bits and the random part is 192 bits.

The ratio is fixed so that when retrieving the timestamp from an ID, the exact length can be easily determined without needing a separator.

Unlike other methods like UUID, FourWord does not require text representation. It supports both byte sequence and text formats.

### Text Representation
Text representation uses something similar to Base32 Hex.

As mentioned above, it uses 'Z' instead of '=' as a padding character, but otherwise, it is identical to Base32 Hex.

### Collision Probability
IDs with different timestamps will not collide. The values below are for the worst-case scenario (all IDs generated within the same nanosecond).

| Bits | Random Bit Width | IDs for 10⁻¹⁸ Collision Probability | IDs for 10⁻⁹ Collision Probability | IDs for 50% Collision Probability |
|---:|---:|:---|:---|:---|
| 256 | 192 bit | Approx. 1.12 × 10²⁰ | Approx. 3.54 × 10²⁴ | Approx. 9.33 × 10²⁸ |
| 512 | 384 bit | Approx. 8.88 × 10⁴⁸ | Approx. 2.81 × 10⁵³ | Approx. 7.39 × 10⁵⁷ |
| 768 | 576 bit | Approx. 7.03 × 10⁷⁷ | Approx. 2.22 × 10⁸² | Approx. 5.85 × 10⁸⁶ |
| 1024 | 768 bit | Approx. 5.57 × 10¹⁰⁶ | Approx. 1.76 × 10¹¹¹ | Approx. 4.64 × 10¹¹⁵ |
| 1280 | 960 bit | Approx. 4.41 × 10¹³⁵ | Approx. 1.40 × 10¹⁴⁰ | Approx. 3.67 × 10¹⁴⁴ |
| 1536 | 1152 bit | Approx. 3.50 × 10¹⁶⁴ | Approx. 1.11 × 10¹⁶⁹ | Approx. 2.91 × 10¹⁷³ |
| 1792 | 1344 bit | Approx. 2.77 × 10¹⁹³ | Approx. 8.76 × 10¹⁹⁷ | Approx. 2.31 × 10²⁰² |
| 2048 | 1536 bit | Approx. 2.20 × 10²²² | Approx. 6.94 × 10²²⁶ | Approx. 1.83 × 10²³¹ |

### Overflow Timeline
Overflow will occur at the following times for each bit size:

| Bits | Timestamp Bit Width | Max Seconds | Overflow Date (Approx.) |
|---:|---:|:---|:---|
| 256 | 64 bit | Approx. 1.84 × 10¹⁹ seconds | Approx. 584.4 billion years AD (5.845 × 10¹¹ years) |
| 512 | 128 bit | Approx. 3.40 × 10³⁸ seconds | Approx. 1.07 × 10³¹ years later |
| 768 | 192 bit | Approx. 6.28 × 10⁵⁷ seconds | Approx. 1.99 × 10⁵⁰ years later |
| 1024 | 256 bit | Approx. 1.16 × 10⁷⁷ seconds | Approx. 3.67 × 10⁶⁹ years later |
| 1280 | 320 bit | Approx. 2.14 × 10⁹⁶ seconds | Approx. 6.77 × 10⁸⁸ years later |
| 1536 | 384 bit | Approx. 3.94 × 10¹¹⁵ seconds | Approx. 1.25 × 10¹⁰⁸ years later |
| 1792 | 448 bit | Approx. 7.26 × 10¹³⁴ seconds | Approx. 2.30 × 10¹²⁷ years later |
| 2048 | 512 bit | Approx. 1.34 × 10¹⁵⁴ seconds | Approx. 4.24 × 10¹⁴⁶ years later |

## License
The source code and libraries in this repository are free to use under the MIT License.

Credit is not required for software that utilizes the FourWord specification itself or for data generated using FourWord.
