ashid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4202347d4a935d5d28ecb9b77c9ea91e7ce374b66ec12e70ee24ee031d41f8e5
+  data.tar.gz: f5fc04121314a8fdbf012ad06a6a78ad6d103dffbdf12da716ca98e107b290f7
+SHA512:
+  metadata.gz: 98959c0286172b5705b5f27732267630097697bad82edc41a381f6b2a73ff6a35694596d8265c975b257d2d64fd3feebd92eefd54e325ece2d570aa8054f77c4
+  data.tar.gz: 8a1e40a69897006d9be2a1c14d39b452f38f02d7b70ace342c74d26ca39779ea38021f026815f3e0a6bbe2f0faf638efcee76e8435cc29a150f933da62f8cdd2

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-06
+
+### Added
+- Initial release of `ashid` Ruby port.
+- `Ashid.generate(prefix, time:, random:)` — time-sortable IDs with optional Stripe-style prefix.
+- `Ashid.generate4(prefix, random1:, random2:)` — UUIDv4-equivalent random-only IDs.
+- `Ashid.parse`, `.prefix`, `.timestamp`, `.time`, `.random`, `.random_bytes` — inspection helpers.
+- `Ashid.valid?` — non-raising predicate.
+- `Ashid.normalize` — canonicalize lookalikes and casing.
+- `Ashid::Encoder` — Crockford Base32 encoder/decoder + CSPRNG.
+- Cross-language parity test against the TypeScript reference implementation.
+- Custom error hierarchy: `Ashid::Error`, `Ashid::InvalidIdError`, `Ashid::InvalidEncodingError`.
+
+[Unreleased]: https://github.com/dankozlowski/ashid-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/dankozlowski/ashid-ruby/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Dan Kozlowski (Ruby port)
+Copyright (c) 2024 Dathan Guiley / Wilde Agency (original ashid library)
+
+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.

data/README.md

@@ -0,0 +1,186 @@
+# ashid
+
+[![Gem Version](https://badge.fury.io/rb/ashid.svg)](https://rubygems.org/gems/ashid)
+[![Test](https://github.com/dankozlowski/ashid-ruby/actions/workflows/test.yml/badge.svg)](https://github.com/dankozlowski/ashid-ruby/actions/workflows/test.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+
+**Time-sortable unique identifiers with type prefixes.** Ruby port of the [ashid library](https://github.com/wildeagency/ashid), wire-compatible with the TypeScript and Kotlin implementations.
+
+```ruby
+Ashid.generate("user")  # => "user_1je3kvrg000007fn17wx6b"
+Ashid.generate("tx")    # => "tx_1je3kvrg1000075n93qdpk"
+Ashid.generate          # => "1je3kvrg000007fn17wx6b"
+```
+
+## Why ashid?
+
+UUIDs are opaque. When you see `550e8400-e29b-41d4-a716-446655440000` in a log, you have no idea what it represents.
+
+ashid generates IDs that tell you what they are:
+
+```
+user_1je3kvrg000007fn17wx6b   ← Obviously a user
+tx_1je3kvrg1000075n93qdpk     ← Obviously a transaction
+asset_1je3kvrg200005j6x7eygm  ← Obviously an asset
+```
+
+### Features
+
+- **Type prefixes** — Self-documenting IDs, like Stripe (`sk_`, `pi_`, `cus_`).
+- **Time-sortable** — Lexicographic sort = chronological sort.
+- **Crockford Base32** — Case-insensitive, `I/L→1`, `O→0` (no more "is that a zero or an O?").
+- **Double-click selectable** — No hyphens or special characters.
+- **URL-safe** — No encoding required.
+- **Cross-language** — Round-trips with the TypeScript and Kotlin libraries.
+- **Zero runtime dependencies** — Just stdlib `SecureRandom`.
+
+## Installation
+
+```bash
+gem install ashid
+```
+
+Or in a Gemfile:
+
+```ruby
+gem "ashid"
+```
+
+## Quick Start
+
+```ruby
+require "ashid"
+
+Ashid.generate                    # => "1je3kvrg000007fn17wx6b"
+Ashid.generate("user")            # => "user_1je3kvrg000007fn17wx6b"
+Ashid.generate4("tok")            # => "tok_14d2pf2dbsqqg0zvebn63pags1" (random-only, like UUIDv4)
+
+id = Ashid.generate("user")
+Ashid.parse(id)                   # => {prefix: "user_", encoded_timestamp: "...", encoded_random: "..."}
+Ashid.timestamp(id)               # => 1733140800000
+Ashid.time(id)                    # => 2024-12-02 12:00:00 UTC
+Ashid.valid?(id)                  # => true
+```
+
+## API Reference
+
+### `Ashid.generate(prefix = nil, time:, random:)`
+
+Generate a time-sortable ID, optionally with a prefix.
+
+```ruby
+Ashid.generate                                  # => "1je3kvrg000007fn17wx6b"
+Ashid.generate("user")                          # => "user_1je3kvrg000007fn17wx6b"
+Ashid.generate("user", time: 1_733_140_800_000, random: 8_234_567_890_123)
+```
+
+- `prefix` (positional, optional): alphanumeric chars are kept and lowercased; everything else is stripped. The trailing `_` delimiter is added automatically — passing `"user"`, `"user_"`, or `"user-"` yields the same result.
+- `time:` (keyword, defaults to current ms): Integer milliseconds since Unix epoch. Range: `0` to `35_184_372_088_831` (Dec 12, 3084).
+- `random:` (keyword, defaults to a secure 64-bit random Integer): non-negative Integer.
+
+Raises `ArgumentError` for negative `time`, `time` exceeding the max, or negative `random`.
+
+### `Ashid.generate4(prefix = nil, random1:, random2:)`
+
+Generate a random-only ID (UUIDv4 equivalent), without time-sortability. 26-char base, ~106 bits of entropy. Useful for tokens, secrets, or any case where unpredictability matters more than ordering.
+
+```ruby
+Ashid.generate4         # => "14d2pf2dbsqqg0zvebn63pags1" (26 chars)
+Ashid.generate4("tok")  # => "tok_14d2pf2dbsqqg0zvebn63pags1"
+```
+
+### `Ashid.parse(id)`
+
+Parse an ID into its components.
+
+```ruby
+Ashid.parse("user_1je3kvrg000007fn17wx6b")
+# => {prefix: "user_", encoded_timestamp: "1je3kvrg0", encoded_random: "00007fn17wx6b"}
+```
+
+Raises `Ashid::InvalidIdError` for `nil`, empty, or malformed input.
+
+### `Ashid.prefix(id)`, `Ashid.timestamp(id)`, `Ashid.time(id)`, `Ashid.random(id)`, `Ashid.random_bytes(id)`
+
+Convenience accessors:
+
+```ruby
+id = Ashid.generate("user")
+
+Ashid.prefix(id)        # => "user_"
+Ashid.timestamp(id)     # => 1733140800000   (Integer ms)
+Ashid.time(id)          # => 2024-12-02 12:00:00 UTC  (Time object)
+Ashid.random(id)        # => 8234567890123   (Integer)
+Ashid.random_bytes(id)  # => "\x00\x00..."   (8-byte ASCII-8BIT String)
+```
+
+### `Ashid.valid?(id)`
+
+Returns `true`/`false`. Never raises, even on `nil` or non-String input.
+
+```ruby
+Ashid.valid?("user_1je3kvrg000007fn17wx6b")  # => true
+Ashid.valid?(nil)                            # => false
+Ashid.valid?("garbage")                      # => false
+```
+
+### `Ashid.normalize(id)`
+
+Canonicalize an ID: lowercase the prefix and resolve Crockford lookalikes (`I/L → 1`, `O → 0`, `U → V`).
+
+```ruby
+Ashid.normalize("USER_IJE3KVRGOOOOO7FNI7WX6B")
+# => "user_1je3kvrg000007fn17wx6b"
+```
+
+## Format
+
+```
+[prefix_]?[timestamp][random]
+   ↓         ↓          ↓
+ user_   1je3kvrg0  00007fn17wx6b
+```
+
+- **With prefix**: variable-length timestamp + 13-char padded random.
+- **Without prefix**: 9-char zero-padded timestamp + 13-char padded random = fixed 22 chars.
+- **`generate4` (random-only)**: 13 + 13 = 26-char base.
+
+**Crockford alphabet:** `0123456789abcdefghjkmnpqrstvwxyz`. Excludes `i`, `l`, `o`, `u`. On decode, lookalikes map: `I/L → 1`, `O → 0`, `U → V`.
+
+## Cross-language compatibility
+
+`ashid` IDs round-trip byte-for-byte across:
+
+- [ashid (TypeScript/JavaScript)](https://www.npmjs.com/package/ashid)
+- [ashid (Kotlin/Java)](https://central.sonatype.com/artifact/agency.wilde/ashid)
+- This Ruby gem
+
+A test fixture in `test/fixtures/parity.json` verifies parity against IDs generated by the TS reference implementation.
+
+## Comparison
+
+| Feature | ashid | UUID | nanoid | ULID | SecureRandom.uuid |
+|---|---|---|---|---|---|
+| Type prefixes | Built-in | No | No | No | No |
+| Time-sortable | Yes | No | No | Yes | No |
+| Human-readable encoding | Crockford Base32 | Hex | Base64 | Base32 | Hex |
+| Case-insensitive | Yes | Yes | No | No | Yes |
+| Lookalike correction | Yes (I→1, O→0) | No | No | No | No |
+| Double-click selectable | Yes | No (hyphens) | Yes | Yes | No |
+| URL-safe | Yes | Needs encoding | Yes | Yes | Needs encoding |
+| Stdlib only | Yes | (gem) | (gem) | (gem) | Yes |
+
+## Inspired by
+
+- [Stripe's ID format](https://stripe.com/docs/api) — the `sk_`, `pi_`, `cus_` prefix convention
+- [Crockford Base32](https://www.crockford.com/base32.html) — human-friendly encoding
+- [ULID](https://github.com/ulid/spec) — time-sortable IDs
+- [TypeID](https://github.com/jetpack-io/typeid) — type-safe, K-sortable IDs
+
+## Credits
+
+Original ashid library by **Dathan Guiley** at [Wilde Agency](https://wilde.agency). Ruby port by **Dan Kozlowski**.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/ashid/encoder.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "securerandom" # used by secure_random (added in Task 7)
+
+module Ashid
+  module Encoder
+    extend self
+
+    ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz".freeze
+
+    DECODE_MAP = begin
+      map = {}
+      ALPHABET.each_char.with_index do |c, i|
+        map[c] = i
+        map[c.upcase] = i
+      end
+      # Crockford lookalike corrections
+      map["O"] = map["o"] = 0
+      map["I"] = map["i"] = map["L"] = map["l"] = 1
+      map["U"] = map["u"] = 27 # maps to V's value
+      map.freeze
+    end
+    private_constant :DECODE_MAP
+
+    def encode(n, padded: false)
+      raise ArgumentError, "must be non-negative" if n < 0
+
+      str = encode_iterative(n)
+      padded ? str.rjust(13, "0") : str
+    end
+
+    def decode(str)
+      raise InvalidEncodingError, "empty string" if str.nil? || str.empty?
+
+      str.each_char.reduce(0) do |acc, ch|
+        v = DECODE_MAP[ch]
+        raise InvalidEncodingError, "invalid character: #{ch.inspect}" if v.nil?
+
+        acc * 32 + v
+      end
+    end
+
+    def secure_random(bits: 64)
+      raise ArgumentError, "bits must be a positive multiple of 8" unless bits.is_a?(Integer) && bits.positive? && (bits % 8).zero?
+
+      SecureRandom.bytes(bits / 8).bytes.reduce(0) { |acc, b| (acc << 8) | b }
+    end
+
+    def valid?(str)
+      return false unless str.is_a?(String)
+
+      decode(str)
+      true
+    rescue InvalidEncodingError
+      false
+    end
+
+    private
+
+    def encode_iterative(n)
+      return "0" if n.zero?
+
+      chars = []
+      while n > 0
+        chars.unshift(ALPHABET[n % 32])
+        n /= 32
+      end
+      chars.join
+    end
+  end
+end

data/lib/ashid/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Ashid
+  class Error < StandardError; end
+  class InvalidIdError < Error; end
+  class InvalidEncodingError < Error; end
+end

data/lib/ashid/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ashid
+  VERSION = "0.1.0"
+end

data/lib/ashid.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative "ashid/version"
+require_relative "ashid/error"
+require_relative "ashid/encoder"
+
+module Ashid
+  extend self
+
+  MAX_TIMESTAMP            = 35_184_372_088_831
+  TIMESTAMP_ENCODED_LENGTH = 9
+  RANDOM_ENCODED_LENGTH    = 13
+  STANDARD_BASE_LENGTH     = 22
+  ASHID4_BASE_LENGTH       = 26
+
+  def generate(prefix = nil, time: current_time_ms, random: Encoder.secure_random(bits: 64))
+    raise ArgumentError, "time must be non-negative"             if time < 0
+    raise ArgumentError, "time must not exceed #{MAX_TIMESTAMP}" if time > MAX_TIMESTAMP
+    raise ArgumentError, "random must be non-negative"           if random < 0
+
+    normalized = normalize_prefix(prefix)
+    base       = build_base_id(normalized, time, random)
+    "#{normalized}#{base}"
+  end
+
+  def generate4(prefix = nil, random1: Encoder.secure_random(bits: 64), random2: Encoder.secure_random(bits: 64))
+    raise ArgumentError, "random1 must be non-negative" if random1 < 0
+    raise ArgumentError, "random2 must be non-negative" if random2 < 0
+
+    normalized = normalize_prefix(prefix)
+    base       = "#{Encoder.encode(random1, padded: true)}#{Encoder.encode(random2, padded: true)}"
+    "#{normalized}#{base}"
+  end
+
+  def parse(id)
+    raise InvalidIdError, "id cannot be nil"    if id.nil?
+    raise InvalidIdError, "id must be a String" unless id.is_a?(String)
+    raise InvalidIdError, "id cannot be empty"  if id.empty?
+
+    prefix_length = 0
+    has_delimiter = false
+
+    id.each_char do |ch|
+      if ch.match?(/[a-zA-Z]/)
+        prefix_length += 1
+      elsif (ch == "_" || ch == "-") && prefix_length > 0
+        prefix_length += 1
+        has_delimiter = true
+        break
+      else
+        prefix_length = 0
+        break
+      end
+    end
+
+    prefix  = has_delimiter ? id[0, prefix_length].sub(/-\z/, "_") : ""
+    base_id = has_delimiter ? id[prefix_length..] : id
+
+    raise InvalidIdError, "id must have a base ID" if base_id.nil? || base_id.empty?
+
+    encoded_timestamp, encoded_random = split_base(base_id, has_delimiter)
+
+    { prefix: prefix, encoded_timestamp: encoded_timestamp, encoded_random: encoded_random }
+  end
+
+  def prefix(id)
+    parse(id)[:prefix]
+  end
+
+  def timestamp(id)
+    Encoder.decode(parse(id)[:encoded_timestamp])
+  end
+
+  # Returns a Time. Note: ms-precision via float division to seconds; sub-ms detail is lost
+  # but ms is our resolution anyway.
+  def time(id)
+    Time.at(timestamp(id) / 1000.0)
+  end
+
+  def random(id)
+    Encoder.decode(parse(id)[:encoded_random])
+  end
+
+  def random_bytes(id)
+    [random(id).to_s(16).rjust(16, "0")].pack("H*")
+  end
+
+  def valid?(id)
+    return false unless id.is_a?(String) && !id.empty?
+
+    parsed = parse(id)
+    if !parsed[:prefix].empty? && parsed[:prefix] !~ /\A[a-z0-9]+_\z/
+      return false
+    end
+
+    Encoder.decode(parsed[:encoded_timestamp])
+    Encoder.decode(parsed[:encoded_random])
+    true
+  rescue Error
+    false
+  end
+
+  def normalize(id)
+    parsed       = parse(id)
+    norm_prefix  = parsed[:prefix].empty? ? nil : parsed[:prefix].downcase.chomp("_")
+    time_value   = Encoder.decode(parsed[:encoded_timestamp])
+    random_value = Encoder.decode(parsed[:encoded_random])
+    generate(norm_prefix, time: time_value, random: random_value)
+  end
+
+  private
+
+  def normalize_prefix(prefix)
+    return nil if prefix.nil? || prefix.empty?
+
+    cleaned = prefix.gsub(/[^a-zA-Z0-9]/, "").downcase
+    cleaned.empty? ? nil : "#{cleaned}_"
+  end
+
+  def build_base_id(normalized_prefix, time, random)
+    if normalized_prefix.nil?
+      # No prefix: fixed 22-char (timestamp padded to 9, random padded to 13)
+      time_part   = Encoder.encode(time).rjust(TIMESTAMP_ENCODED_LENGTH, "0")
+      random_part = Encoder.encode(random, padded: true)
+      "#{time_part}#{random_part}"
+    elsif time > 0
+      # Variable length, padded random
+      "#{Encoder.encode(time)}#{Encoder.encode(random, padded: true)}"
+    else
+      # time == 0: omit timestamp, encode random unpadded
+      Encoder.encode(random)
+    end
+  end
+
+  def current_time_ms
+    (Process.clock_gettime(Process::CLOCK_REALTIME) * 1000).to_i
+  end
+
+  def split_base(base_id, has_delimiter)
+    if has_delimiter
+      if base_id.length <= RANDOM_ENCODED_LENGTH
+        ["0", base_id]
+      else
+        [base_id[0...-RANDOM_ENCODED_LENGTH], base_id[-RANDOM_ENCODED_LENGTH..]]
+      end
+    elsif base_id.length == ASHID4_BASE_LENGTH
+      [base_id[0, RANDOM_ENCODED_LENGTH], base_id[RANDOM_ENCODED_LENGTH..]]
+    elsif base_id.length == STANDARD_BASE_LENGTH
+      [base_id[0, TIMESTAMP_ENCODED_LENGTH], base_id[TIMESTAMP_ENCODED_LENGTH..]]
+    else
+      raise InvalidIdError,
+        "base ID must be #{STANDARD_BASE_LENGTH} or #{ASHID4_BASE_LENGTH} chars without delimiter (got #{base_id.length})"
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: ashid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dan Kozlowski
+bindir: bin
+cert_chain: []
+date: 2026-05-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.20'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: 'Ruby port of ashid: time-sortable unique IDs with optional type prefixes,
+  encoded in Crockford Base32. Wire-compatible with the TypeScript and Kotlin implementations.'
+email:
+- dakozlowski@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/ashid.rb
+- lib/ashid/encoder.rb
+- lib/ashid/error.rb
+- lib/ashid/version.rb
+homepage: https://github.com/dankozlowski/ashid-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/dankozlowski/ashid-ruby
+  source_code_uri: https://github.com/dankozlowski/ashid-ruby
+  changelog_uri: https://github.com/dankozlowski/ashid-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dankozlowski/ashid-ruby/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Time-sortable unique identifiers with type prefixes
+test_files: []