#RabitLogic/snowflake

#ID Structure

 0 | 41 bits timestamp | 10 bits node | 12 bits sequence

Customise bit allocation via Node::new(node, epoch, nb=?, sb=?) as long as nb + sb ≤ 22.

#Quick Start

///|
let node = Node::new_default(1L).unwrap()

///|
let id : Snowflake = node.generate()

///|
println(id)                  // 67817059108864
println(id.to_base36())      // 1w7p0bgwwb28

#API Reference

#Types

#Generator — Node

Thread safety: Node is not Send/Sync. Wrap in Mutex(Node) for shared access.

#ID value — Snowflake

///|
let id = Snowflake::new(67817059108864L) // from raw Int64

///|
let raw : Int64 = id.to_int64()

///|
let id2 = Snowflake::new(raw)

#Constants

///|
default_epoch  // 1767225600000L  (2026-01-01 00:00:00 UTC)

///|
node_bits      // 10

///|
step_bits      // 12

#Complete Example

///|
fn run {
  let node = Node::new_default(1L).unwrap()
  let id = node.generate()
  let id2 = node.generate()

  // Field extraction (default layout)
  println("\{id.time()} \{id.node_id()} \{id.step()}")

  // Field extraction (custom layout)
  println(
    "\{node.extract_time(id)} \{node.extract_node_id(id)} \{node.extract_step(id)}",
  )

  // Encoding
  println(id.to_base36())
  println(id.to_base58())

  // Parsing
  let parsed = Snowflake::from_base36(id.to_base36())
  println(parsed == Some(id)) // true

  // JSON serialisation
  let json_str = id.to_json().stringify()
  println(json_str) // "67817059108864"
}

#Production Guide

#Node ID management

• Static config: assign a unique ID per process at deployment time.
• Database sequence: use an AUTO_INCREMENT column or Redis INCR.
• Consensus: use etcd or ZooKeeper for automatic allocation.

#Clock accuracy

• Use ntpd or chronyd with minpoll no smaller than 6 (64 s).
• Avoid manual date commands or large step adjustments.
• Monitor system clock synchronisation in your observability pipeline.

Note: Unlike libraries that use an OS monotonic clock, this library will pause briefly if the clock jumps backwards. This is a deliberate trade‑off for portability across all MoonBit targets (Wasm, JS, native).

#Thread safety

///|
let node = Mutex(Node::new_default(1L).unwrap())

///|
let id = node.lock().generate()

#Bit width planning

#Epoch planning

///|
let node = Node::new(1L, 1893456000000L).unwrap() // 2030-01-01

#Limitations

• Clock monotonicity: see Clock accuracy above.
• Max timestamp: 41‑bit field + epoch (2026-01-01) → space lasts until ≈ 2095 (~69 years). Adjust the epoch to shift the window.

#Development

# Run all tests (40 tests)
moon test

# Update snapshots (if any)
moon test --update

# Run the demo
moon run cmd/main

# Check coverage
moon coverage analyze > uncovered.log

#Test Coverage

#License