@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/helpers/uid/index.md

@@ -1,272 +1,103 @@
-# UID
-
-Snowflake ID generator with Base62 encoding for unique, time-sortable distributed identifiers.
+---
+title: UID
+description: Snowflake ID generator with Base62 encoding for unique, time-sortable distributed identifiers
+difficulty: beginner
+---
 
-## Quick Reference
+# UID
 
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis-helpers` |
-| **Class** | `SnowflakeUidHelper` |
-| **Extends** | `BaseHelper` |
-| **Runtimes** | Both |
+`SnowflakeUidHelper` generates 70-bit, time-sortable Snowflake IDs and encodes them as compact Base62 strings, suitable as database primary keys.
 
-#### Import Paths
+## In one example
 
 ```typescript
-import { SnowflakeUidHelper, SnowflakeConfig } from '@venizia/ignis-helpers';
+import { SnowflakeUidHelper } from '@venizia/ignis-helpers';
 
-// Types
-import type { IIdGeneratorOptions, ISnowflakeParsedId } from '@venizia/ignis-helpers';
+const generator = new SnowflakeUidHelper(); // workerId: 199, epoch: 2025-01-01 UTC
+const id = generator.nextId();
+// => e.g. "9du1sJXO88"
 ```
 
-#### Snowflake ID Structure (70 bits)
-
-| Component | Bits | Range | Purpose |
-|-----------|------|-------|---------|
-| Timestamp | 48 | ~8,919 years | Time since epoch |
-| Worker ID | 10 | 0--1023 | Unique worker identifier |
-| Sequence | 12 | 0--4095 | IDs per millisecond |
-
-#### Key Specifications
+Use one `SnowflakeUidHelper` instance per worker process - `nextId()` returns a URL-safe Base62 string that sorts the same order as the IDs were generated.
 
-| Spec | Value |
-|------|-------|
-| Base62 Output | 10--12 characters |
-| Throughput | 4,096,000 IDs/second/worker |
-| Max Workers | 1024 |
-| Lifespan | Until ~10,944 AD |
-| Default Epoch | 2025-01-01 00:00:00 UTC |
+## How it works
 
-## Creating an Instance
+- **The ID packs three fields into 70 bits.** A 48-bit timestamp (offset from a custom epoch), a 10-bit worker ID (0-1023), and a 12-bit sequence (0-4095) - shifted and OR'd together in `nextSnowflake()`. Sorting the raw bigints, or the Base62 strings, sorts by generation time.
+- **The sequence resets every millisecond, per worker.** Within the same millisecond it increments and wraps at 4096; a wrap forces the generator to busy-wait for the next millisecond, capping throughput at 4,096,000 IDs/second/worker.
+- **Backward clock drift is handled, up to a point.** A drift up to 100ms (`MAX_CLOCK_BACKWARD_MS`) busy-waits until the clock catches up, logging a warning. A larger drift throws instead of risking a duplicate ID.
+- **`encodeBase62` / `decodeBase62` are just a bigint <-> string codec.** They do not know about the Snowflake layout - `parseId()` is `decodeBase62()` followed by the three `extract*` calls, all built on the same instance's `epoch` and bit-shift constants.
+- **An expiry warning logs once the epoch nears its 48-bit limit.** ~8,919 years after the configured epoch the timestamp field overflows; a warning starts logging 10 years before that.
 
-`SnowflakeUidHelper` extends `BaseHelper`, providing scoped logging via `LoggerFactory`.
+**Snowflake layout (70 bits)**
 
-```typescript
-import { SnowflakeUidHelper } from '@venizia/ignis-helpers';
-
-// Use defaults (workerId: 199, epoch: 2025-01-01 00:00:00 UTC)
-const generator = new SnowflakeUidHelper();
-
-// Or with custom values
-const customGenerator = new SnowflakeUidHelper({
-  workerId: 123,
-  epoch: BigInt(1735689600000),
-});
-```
+| Component | Bits | Range | Purpose |
+|-----------|------|-------|---------|
+| Timestamp | 48 | ~8,919 years | Milliseconds since `epoch` |
+| Worker ID | 10 | 0-1023 | Set per instance, must be unique across a deployment |
+| Sequence | 12 | 0-4095 | IDs generated within the same millisecond |
 
-#### `IIdGeneratorOptions`
+**`IIdGeneratorOptions`**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `workerId` | `number` | `199` | Worker ID (0--1023). Must be unique per instance in distributed deployments |
-| `epoch` | `bigint` | `BigInt(1735689600000)` | Custom epoch timestamp in milliseconds since Unix epoch. Must be positive and in the past |
-
-> [!TIP]
-> Use unique worker IDs in distributed systems to prevent ID collisions, and keep the epoch consistent across all instances to ensure proper ID ordering.
-
-#### `SnowflakeConfig` Constants
+| `workerId` | `number` | `199` | Integer, `0`-`1023` |
+| `epoch` | `bigint` | `BigInt(1735689600000)` (2025-01-01 00:00:00 UTC) | Positive, must be in the past |
 
-```typescript
-import { SnowflakeConfig } from '@venizia/ignis-helpers';
-
-SnowflakeConfig.DEFAULT_EPOCH      // BigInt(1735689600000) - 2025-01-01 00:00:00 UTC
-SnowflakeConfig.MAX_WORKER_ID      // 1023n
-SnowflakeConfig.MAX_SEQUENCE       // 4095n
-SnowflakeConfig.TIMESTAMP_SHIFT    // 22n
-SnowflakeConfig.WORKER_ID_SHIFT    // 12n
-
-// Bit widths
-SnowflakeConfig.TIMESTAMP_BITS     // 48n
-SnowflakeConfig.WORKER_ID_BITS     // 10n
-SnowflakeConfig.SEQUENCE_BITS      // 12n
-
-// Safety thresholds
-SnowflakeConfig.MAX_CLOCK_BACKWARD_MS  // 100n (busy-wait tolerance)
-SnowflakeConfig.MAX_TIMESTAMP_MS       // (1n << 48n) - 1n (~8,919 years)
-SnowflakeConfig.WARNING_THRESHOLD_MS   // ~8,909 years (warns 10 years before expiry)
-```
+## Common tasks
 
-## Usage
+### Generate an ID
 
-### Generating IDs
-
-Generate unique Snowflake IDs as either compact Base62 strings or raw bigints.
+`nextId()` is the common case - a Base62 string, 10-12 characters. `nextSnowflake()` returns the raw `bigint` when you need arithmetic or bit-level access.
 
 ```typescript
-// Generate Base62 encoded ID (recommended for most use cases)
-const id = generator.nextId();
-// => e.g., "9du1sJXO88"
-
-// Generate raw Snowflake ID as bigint
-const snowflakeId = generator.nextSnowflake();
-// => e.g., 130546360012247045n
+const id = generator.nextId();               // "9du1sJXO88"
+const raw = generator.nextSnowflake();        // 130546360012247045n
 ```
 
-> [!TIP]
-> Use `nextId()` for most cases -- it returns a compact Base62 string (10--12 chars) that works well as database primary keys and URL-safe identifiers. Use `nextSnowflake()` only when you need the raw bigint for arithmetic or bit-level operations.
-
-#### Clock Drift Handling
-
-When `nextSnowflake()` detects the system clock has moved backward:
-- Drifts up to 100ms are handled automatically by busy-waiting until the clock catches up.
-- Drifts exceeding 100ms throw an error to protect ID uniqueness.
-- A warning is logged whenever any backward clock movement is detected.
-
-#### Sequence Exhaustion
-
-If more than 4096 IDs are requested in a single millisecond from the same worker, the generator busy-waits until the next millisecond before continuing. This is transparent to the caller.
-
-### Base62 Encoding and Decoding
-
-Encode any bigint to a compact, URL-safe Base62 string using the alphabet `0-9A-Za-z`, or decode back to the original bigint.
-
-```typescript
-// Encode
-const encoded = generator.encodeBase62(130546360012247045n);
-// => "9du1sJXO88"
-
-// Decode
-const decoded = generator.decodeBase62('9du1sJXO88');
-// => 130546360012247045n
-```
-
-> [!WARNING]
-> `decodeBase62()` throws if the input contains characters outside the Base62 alphabet (`0-9`, `A-Z`, `a-z`). Watch for URL-encoded strings or accidental whitespace.
-
-### Parsing IDs
-
-Extract the embedded timestamp, worker ID, and sequence from a generated ID.
-
-#### Parse a Base62 ID
+### Parse an ID back into its components
 
 ```typescript
 const parsed = generator.parseId('9du1sJXO88');
-// => {
-//   raw: 130546360012247045n,
-//   timestamp: Date,
-//   workerId: 199,
-//   sequence: 0
-// }
-```
-
-#### `ISnowflakeParsedId`
-
-```typescript
-interface ISnowflakeParsedId {
-  raw: bigint;
-  timestamp: Date;
-  workerId: number;
-  sequence: number;
-}
+// => { raw: 130546360012247045n, timestamp: Date, workerId: 199, sequence: 0 }
 ```
 
-#### Extract Individual Components
+### Extract a single component from a raw ID
 
 ```typescript
-const snowflakeId = generator.nextSnowflake();
-
-// Extract timestamp
-const timestamp = generator.extractTimestamp(snowflakeId);
-// => Date object
-
-// Extract worker ID
-const workerId = generator.extractWorkerId(snowflakeId);
-// => 199
-
-// Extract sequence
-const sequence = generator.extractSequence(snowflakeId);
-// => 0-4095
-
-// Get current instance's worker ID
-const currentWorkerId = generator.getWorkerId();
-// => 199
+const timestamp = generator.extractTimestamp(raw);
+const workerId = generator.extractWorkerId(raw);
+const sequence = generator.extractSequence(raw);
 ```
 
-## API Summary
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `nextId` | `nextId(): string` | Generate a Base62-encoded Snowflake ID (10--12 chars) |
-| `nextSnowflake` | `nextSnowflake(): bigint` | Generate a raw 70-bit Snowflake ID |
-| `encodeBase62` | `encodeBase62(num: bigint): string` | Encode a bigint to Base62 string |
-| `decodeBase62` | `decodeBase62(str: string): bigint` | Decode a Base62 string to bigint |
-| `parseId` | `parseId(base62Id: string): ISnowflakeParsedId` | Parse a Base62 ID into its components |
-| `extractTimestamp` | `extractTimestamp(id: bigint): Date` | Extract the timestamp from a raw Snowflake ID |
-| `extractWorkerId` | `extractWorkerId(id: bigint): number` | Extract the worker ID from a raw Snowflake ID |
-| `extractSequence` | `extractSequence(id: bigint): number` | Extract the sequence number from a raw Snowflake ID |
-| `getWorkerId` | `getWorkerId(): number` | Get the current instance's worker ID |
+### Run one generator per worker in a distributed deployment
 
-## Troubleshooting
-
-### "Worker ID must be between 0 and 1023"
-
-**Cause:** The `workerId` option passed to the constructor is negative or exceeds 1023 (10-bit maximum).
-
-**Fix:** Ensure the worker ID is within the valid range (0--1023):
+Give each process a unique `workerId`; keep `epoch` identical across all of them so ID ordering stays meaningful.
 
 ```typescript
-// Wrong
-new SnowflakeUidHelper({ workerId: 2000 });
-
-// Correct
-new SnowflakeUidHelper({ workerId: 1 });
+const generator = new SnowflakeUidHelper({ workerId: Number(process.env.WORKER_ID) });
 ```
 
-### "Epoch must be a positive number"
+### Decode Base62 defensively
 
-**Cause:** The `epoch` option is zero or negative.
-
-**Fix:** Provide a valid epoch as a positive bigint representing milliseconds since Unix epoch:
+`decodeBase62()` throws on any character outside `0-9A-Za-z` - including a leading space or a URL-decoded `+`.
 
 ```typescript
-// Wrong
-new SnowflakeUidHelper({ epoch: BigInt(0) });
-
-// Correct
-new SnowflakeUidHelper({ epoch: BigInt(1735689600000) });
-```
-
-### "Epoch cannot be in the future"
-
-**Cause:** The `epoch` option is set to a timestamp later than the current time. A future epoch would produce negative timestamp offsets in generated IDs.
-
-**Fix:** Use a past date as the epoch. The default (`2025-01-01 00:00:00 UTC`) is recommended unless you have a specific reason to change it.
-
-### "Clock moved backward by Xms. Refusing to generate ID."
-
-**Cause:** The system clock moved backward by more than 100ms, typically caused by NTP time synchronization. Small drifts (up to 100ms) are handled by busy-waiting, but larger jumps are rejected to protect ID uniqueness.
-
-**Fix:** Ensure your system clock is stable. If running in containers, verify the host clock is not being adjusted aggressively. There is no code-level workaround -- the error protects against duplicate IDs.
-
-### "Invalid Base62 character: X"
-
-**Cause:** `decodeBase62()` encountered a character outside the Base62 alphabet (`0-9`, `A-Z`, `a-z`).
-
-**Fix:** Ensure the input string only contains valid Base62 characters:
-
-```typescript
-// Wrong
-generator.decodeBase62('9du1sJ+O88');   // '+' is not Base62
-generator.decodeBase62(' 9du1sJXO88');  // leading space
-
-// Correct
-generator.decodeBase62('9du1sJXO88');
+try {
+  const raw = generator.decodeBase62(userSuppliedId);
+} catch (error) {
+  // not a valid Base62 ID
+}
 ```
 
-## See Also
-
-- **Related Concepts:**
-  - [Models](/guides/core-concepts/persistent/models) - Using UIDs as primary keys
-  - [Services](/guides/core-concepts/services) - Generating unique IDs in services
+## See also
 
-- **Other Helpers:**
-  - [Helpers Index](../index) - All available helpers
-  - [Crypto Helper](../crypto/) - For cryptographic random values
+- [Models](/guides/core-concepts/persistent/models) - using UIDs as primary keys
+- [Services](/guides/core-concepts/services) - generating unique IDs in services
+- [Helpers Overview](/extensions/helpers/) - all available helpers
+- [Crypto Helper](/extensions/helpers/crypto/) - cryptographic random values
+- [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) - the algorithm this helper implements
 
-- **External Resources:**
-  - [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) - Snowflake algorithm explained
-  - [Base62 Encoding](https://en.wikipedia.org/wiki/Base62) - Base62 encoding overview
+**Files:**
 
-- **Best Practices:**
-  - [Data Modeling](/best-practices/data-modeling) - ID generation strategies
+- [`packages/helpers/src/modules/uid/helper.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/uid/helper.ts) - `SnowflakeUidHelper`, `SnowflakeConfig`
+- [`packages/helpers/src/modules/uid/index.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/uid/index.ts) - module barrel