Merge pull request #1 from macmoonshine/main

Initial version

.gitignore

@@ -0,0 +1 @@
+.build

CHANGELOG.md

@@ -1,3 +1,4 @@
 # CHANGELOG
 
-@todo
+**v0.9.0:**
+- Initial implementation of [the spec](https://github.com/sqids/sqids-spec)

Package.swift

@@ -0,0 +1,46 @@
+// swift-tools-version: 5.9
+/*
+ MIT License
+
+ Copyright (c) 2023-present Sqids maintainers.
+
+ Permission is hereby granted, free of charge, to any person obtaining a copy
+ of this software and associated documentation files (the "Software"), to deal
+ in the Software without restriction, including without limitation the rights
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ copies of the Software, and to permit persons to whom the Software is
+ furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ SOFTWARE.
+ */
+
+import PackageDescription
+
+let package = Package(
+    name: "sqids",
+    products: [
+        // Products define the executables and libraries a package produces, making them visible to other packages.
+        .library(
+            name: "sqids",
+            targets: ["sqids"]
+        ),
+    ],
+    targets: [
+        // Targets are the basic building blocks of a package, defining a module or a test suite.
+        // Targets can depend on other targets in this package and products from dependencies.
+        .target(
+            name: "sqids"),
+        .testTarget(
+            name: "sqidsTests",
+            dependencies: ["sqids"]),
+    ]
+)

README.md

@@ -1,15 +1,87 @@
 # [Sqids Swift](https://sqids.org/swift)
 
-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.
+[![Github Actions](https://img.shields.io/github/actions/workflow/status/sqids/sqids-swift/tests.yml)](https://github.com/sqids/sqids-swift/actions)
 
-## Getting started
+[Sqids](https://sqids.org/swift) (*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.
 
-@todo
+Features:
 
-## Examples
+- **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/)
 
-@todo
+## 🧰 Use-cases
 
-## License
+Good for:
+
+- 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)
+
+Not good for:
+
+- Sensitive data (this is not an encryption library)
+- User IDs (can be decoded revealing user count)
+
+## 🚀 Getting started
+
+Add the following dependency to your Swift `Package.swift`:
+
+```swift
+dependencies.append(
+    .package(url: "https://github.com/squids/squitss-swift.git", from: "1.0.0")
+)
+```
+
+Import the `Sqids` struct from the `sqids` framework:
+
+```swift
+import sqids
+
+let sqids = Sqids()
+```
+
+## 👩‍💻 Examples
+
+Simple encode & decode:
+
+```swift
+let sqids = Sqids()
+let id = try sqids.encode([1, 2, 3]) // "86Rf07"
+let numbers = try 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:
+
+```swift
+let sqids = Sqids(minLength: 10)
+let id = try sqids.encode([1, 2, 3]) // "86Rf07xd4z"
+let numbers = try sqids.decode(id) // [1, 2, 3]
+```
+
+Randomize IDs by providing a custom alphabet:
+
+```swift
+let sqids = Sqids(alphabet: "FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE")
+let id = try sqids.encode([1, 2, 3]) // "B4aajs"
+let numbers = try sqids.decode(id) // [1, 2, 3]
+```
+
+Prevent specific words from appearing anywhere in the auto-generated IDs:
+
+```swift
+let sqids = Sqids(blocklist: ["86Rf07"])
+let id = try sqids.encode([1, 2, 3]) // "se8ojk"
+let numbers = try sqids.decode(id) # [1, 2, 3]
+```
+
+## 📝 License
 
 [MIT](LICENSE)