Merge pull request #1 from kevinxmorales/main

Kotlin implementation

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v3
+        with:
+          distribution: 'corretto'
+          java-version: '17'
+      - uses: gradle/gradle-build-action@v2
+      - run: gradle wrapper
+      - run: ./gradlew test

.gitignore

@@ -0,0 +1,43 @@
+.gradle
+build/
+!gradle/wrapper/gradle-wrapper.jar
+!**/src/main/**/build/
+!**/src/test/**/build/
+
+### IntelliJ IDEA ###
+.idea/
+.idea/modules.xml
+.idea/jarRepositories.xml
+.idea/compiler.xml
+.idea/libraries/
+*.iws
+*.iml
+*.ipr
+out/
+!**/src/main/**/out/
+!**/src/test/**/out/
+
+### Eclipse ###
+.apt_generated
+.classpath
+.factorypath
+.project
+.settings
+.springBeans
+.sts4-cache
+bin/
+!**/src/main/**/bin/
+!**/src/test/**/bin/
+
+### NetBeans ###
+/nbproject/private/
+/nbbuild/
+/dist/
+/nbdist/
+/.nb-gradle/
+
+### VS Code ###
+.vscode/
+
+### Mac OS ###
+.DS_Store

README.md

@@ -1,15 +1,75 @@
 # [Sqids Kotlin](https://sqids.org/kotlin)
 
-Sqids (pronounced "squids") is a small library that lets you generate YouTube-looking IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.
+[Sqids](https://sqids.org/kotlin) (*pronounced "squids"*) is a small library that lets you **generate unique IDs from numbers**. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.
 
-## Getting started
+Features:
 
-@todo
+- **Encode multiple numbers** - generate short IDs from one or several non-negative numbers
+- **Quick decoding** - easily decode IDs back into numbers
+- **Unique IDs** - generate unique IDs by shuffling the alphabet once
+- **ID padding** - provide minimum length to make IDs more uniform
+- **URL safe** - auto-generated IDs do not contain common profanity
+- **Randomized output** - Sequential input provides nonconsecutive IDs
+- **Many implementations** - Support for [40+ programming languages](https://sqids.org/)
 
-## Examples
+## 🧰 Use-cases
 
-@todo
+Good for:
 
-## License
+- Generating IDs for public URLs (eg: link shortening)
+- Generating IDs for internal systems (eg: event tracking)
+- Decoding for quicker database lookups (eg: by primary keys)
 
-[MIT](LICENSE)
+Not good for:
+
+- Sensitive data (this is not an encryption library)
+- User IDs (can be decoded revealing user count)
+
+## 🚀 Getting started
+
+Install Sqids via:
+
+```kotlin
+import org.sqidskotlin.sqids
+```
+
+## 👩‍💻 Examples
+
+Simple encode & decode:
+
+```kotlin
+val sqids = Sqids()
+val id = sqids.encode(listOf<Long>(1, 2, 3)) // "86Rf07"
+val numbers = sqids.decode(id) // [1, 2, 3]
+```
+
+> **Note**
+> 🚧 Because of the algorithm's design, **multiple IDs can decode back into the same sequence of numbers**. If it's important to your design that IDs are canonical, you have to manually re-encode decoded numbers and check that the generated ID matches.
+
+Enforce a *minimum* length for IDs:
+
+```kotlin
+val sqids = Sqids(minLength = 10)
+val id = sqids.encode(listOf<Long>(1, 2, 3)) // "86Rf07xd4z"
+val numbers = sqids.decode(id) // [1, 2, 3]
+```
+
+Randomize IDs by providing a custom alphabet:
+
+```kotlin
+val sqids = Sqids(alphabet = "FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE")
+val id = sqids.encode(listOf<Long>(1, 2, 3)) // "B4aajs"
+val numbers = sqids.decode(id) // [1, 2, 3]
+```
+
+Prevent specific words from appearing anywhere in the auto-generated IDs:
+
+```kotlin
+val sqids = Sqids(blockList = setOf("86Rf07"))
+val id = sqids.encode(listOf<Long>(1, 2, 3)) // "se8ojk"
+val numbers = sqids.decode(id) // [1, 2, 3]
+```
+
+## 📝 License
+
+[MIT](LICENSE)

build.gradle.kts

@@ -0,0 +1,24 @@
+import org.jetbrains.kotlin.gradle.tasks.KotlinCompile
+
+plugins {
+    kotlin("jvm") version "1.6.0"
+}
+
+group = "org.sqidskotlin.sqids"
+version = "1.0-SNAPSHOT"
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testImplementation(kotlin("test"))
+}
+
+tasks.test {
+    useJUnitPlatform()
+}
+
+tasks.withType<KotlinCompile> {
+    kotlinOptions.jvmTarget = "1.8"
+}

gradle.properties

@@ -0,0 +1 @@
+kotlin.code.style=official

gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists