Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/charted-dev/snowflake

Kotlin library to help generate Twitter snowflakes
https://github.com/charted-dev/snowflake

kotlin snowflake twitter-snowflake

Last synced: about 1 month ago
JSON representation

Kotlin library to help generate Twitter snowflakes

Host: GitHub
URL: https://github.com/charted-dev/snowflake
Owner: charted-dev
License: mit
Created: 2022-12-06T17:21:13.000Z (about 2 years ago)
Default Branch: main
Last Pushed: 2023-10-06T05:34:19.000Z (about 1 year ago)
Last Synced: 2023-10-06T12:43:16.163Z (about 1 year ago)
Topics: kotlin, snowflake, twitter-snowflake
Language: Kotlin
Homepage: https://charted-dev.github.io/snowflake
Size: 435 KB
Stars: 4
Watchers: 0
Forks: 0
Open Issues: 11
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

# 🐻‍❄️❄️ Snowflake
> *Easy to use Kotlin library to help you generate Twitter snowflakes asynchronously*
>
> [v0.1-beta](https://github.com/charted-dev/snowflake/releases/v0.1-beta) | [:scroll: **Documentation**](https://charted-dev.github.io/snowflake)

**Snowflake** is a Kotlin multiplatform library to help you generate Twitter snowflakes in a single node environment or in a clustered environment.
This library was majorly inspired by [@bwmarrin](https://github.com/bwmarrin)'s [Go Snowflake](https://github.com/bwmarrin/snowflake) library.

## Features
- Distributed snowflake to help you generate snowflakes on each node with the `SnowflakeNodes` API.
- **kotlinx.serialization** support to easily (de)serialize snowflakes.
- Simple and usable way to generate Twitter snowflakes
- **Asynchronous** support via Kotlin's coroutines

## Usage
View the [installation guide](#installation) on how to install the library in your Kotlin project.

The formatting of the snowflake is relatively the same as the [ID Format](https://github.com/bwmarrin/snowflake#id-format) that
Twitter uses.

```kotlin
// Defaults with node 0 and epoch of Twitter's snowflake
val snowflake = Snowflake()

val id = snowflake.generate()
// => returns [org.noelware.charted.snowflake.ID]
```

## Benchmaking
Since generating snowflakes should be fast as possible, we provide a benchmark suite in the [benchmarks](./benchmarks) folder with [kotlinx.benchmark](https://github.com/Kotlin/kotlinx-benchmark)

### Native
```
> Task :benchmarks:nativeBenchmark
Running 'main' benchmarks for 'native'
native: org.noelware.charted.snowflake.benchmarks.native.SnowflakeNativeBenchmarks.generateIds
Warm-up #0: 0.00240547 ms/op
Warm-up #1: 0.00380899 ms/op
Warm-up #2: 0.00514744 ms/op
Iteration #0: 0.00553965 ms/op
Iteration #1: 0.00633540 ms/op
Iteration #2: 0.00641139 ms/op
Iteration #3: 0.00698136 ms/op
Iteration #4: 0.00878726 ms/op
~ 0.00681101 ms/op ±15%

native summary:
Benchmark Mode Cnt Score Error Units
SnowflakeNativeBenchmarks.generateIds avgt 5 0.007 ± 0.001 ms/op
```

### JVM
```
> Task :benchmarks:jvmBenchmark
Running 'main' benchmarks for 'jvm'
jvm: org.noelware.charted.snowflake.benchmarks.jvm.SnowflakeJvmBenchmarks.generateIds

Warm-up 1: 0.001 ms/op
Warm-up 2: ≈ 10⁻⁴ ms/op
Warm-up 3: ≈ 10⁻⁴ ms/op
Warm-up 4: ≈ 10⁻⁴ ms/op
Warm-up 5: ≈ 10⁻⁴ ms/op
Iteration 1: ≈ 10⁻⁴ ms/op
Iteration 2: ≈ 10⁻⁴ ms/op
Iteration 3: ≈ 10⁻⁴ ms/op
Iteration 4: ≈ 10⁻⁴ ms/op
Iteration 5: ≈ 10⁻⁴ ms/op

≈ 10⁻⁴ ms/op

jvm summary:
Benchmark Mode Cnt Score Error Units
SnowflakeJvmBenchmarks.generateIds avgt 15 ≈ 10⁻⁴ ms/op
```

## Installation
To install the **Snowflake** library, you will need to enable Noelware's [Maven repository](https://maven.noelware.org).

### Gradle (Kotlin DSL)
```kotlin
repositories {
maven("https://maven.noelware.org")
mavenCentral()
}

dependencies {
implementation("org.noelware.charted.snowflake:snowflake:0.1-beta")
}
```

### Gradle (Groovy DSL)
```groovy
repositories {
maven "https://maven.noelware.org"
mavenCentral()
}

dependencies {
implementation "org.noelware.charted.snowflake:snowflake:0.1-beta"
}
```

### Maven
```xml

https://maven.noelware.org

org.noelware.charted.snowflake
snowflake-jvm
0.1-beta
pom

```

## License
**snowflake** is released under the **MIT License** with love by Noelware. <3