lacus-utils 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 55e2230dbc3093059a4cde7f74cac60ef27e2183bfc033b6f6d90bde601c81ec
+  data.tar.gz: d9f57500daeee5558f97b260f4fdc6338c854e76bd745f4b00b75ba0c2c81a2a
+SHA512:
+  metadata.gz: 8b5a1b1ce6f2317fe66916fdc8aae1534f94185b3b01c5491df497fc71ca3b997a9146e6e72437d702a62039df51dcc589d749ced638534a9cd46f19130b603a
+  data.tar.gz: f11bf35f4ee395cd388942a62e15d2e0cc57a36a2106faab112e54abb3faf40e897f1ced6bc82764fbc830c4cdb3657f4173e140a82e57a0535d64a9c5922e0a

data/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Julio L. Muller
+
+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,144 @@
+# Lacus Solutions' Utils
+
+[![Gem Version](https://img.shields.io/gem/v/lacus-utils)](https://rubygems.org/gems/lacus-utils)
+[![Downloads Count](https://img.shields.io/gem/dt/lacus-utils)](https://rubygems.org/gems/lacus-utils)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D?logo=ruby&logoColor=white)](https://www.ruby-lang.org/)
+[![Test Status](https://img.shields.io/github/actions/workflow/status/LacusSolutions/br-utils-ruby/ci.yml?label=ci/cd)](https://github.com/LacusSolutions/br-utils-ruby/actions)
+[![Last Update Date](https://img.shields.io/github/last-commit/LacusSolutions/br-utils-ruby)](https://github.com/LacusSolutions/br-utils-ruby)
+[![Project License](https://img.shields.io/github/license/LacusSolutions/br-utils-ruby)](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE)
+
+A Ruby reusable utilities library for Lacus Solutions' packages.
+
+## Ruby Support
+
+| ![Ruby 3.2](https://img.shields.io/badge/Ruby-3.2-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.3](https://img.shields.io/badge/Ruby-3.3-CC342D?logo=ruby&logoColor=white) | ![Ruby 3.4](https://img.shields.io/badge/Ruby-3.4-CC342D?logo=ruby&logoColor=white) |
+|--- | --- | --- |
+| Passing ✔ | Passing ✔ | Passing ✔ |
+
+## Features
+
+- **Type description**: Ruby-native type labels for error messages (`nil`, `hash`, `symbol`, built-ins, arrays, `NaN`, `Infinity`)
+- **Random sequences**: Generate numeric, alphabetic, or alphanumeric sequences of any length using a cryptographically secure RNG
+- **Zero dependencies**: No external runtime dependencies
+
+## Installation
+
+Install the gem directly:
+
+```bash
+gem install lacus-utils
+```
+
+Or add it to your `Gemfile` and run `bundle install`:
+
+```ruby
+gem 'lacus-utils'
+```
+
+## Require
+
+```ruby
+require 'lacus-utils'
+```
+
+## Quick Start
+
+```ruby
+require 'lacus-utils'
+
+LacusUtils.describe_type(nil)              # => 'nil'
+LacusUtils.describe_type('hello')          # => 'string'
+LacusUtils.describe_type(42)               # => 'integer number'
+LacusUtils.describe_type(3.14)             # => 'float number'
+LacusUtils.describe_type([1, 2, 3])        # => 'number[]'
+LacusUtils.describe_type([1, 'a', 2])      # => '(number | string)[]'
+LacusUtils.describe_type({})               # => 'hash'
+
+LacusUtils.generate_random_sequence(10, :numeric)      # => e.g. '9956000611'
+LacusUtils.generate_random_sequence(6, :alphabetic)    # => e.g. 'AXQMZB'
+LacusUtils.generate_random_sequence(8, :alphanumeric)  # => e.g. '8ZFB2K09'
+LacusUtils.generate_random_sequence(8)                 # => e.g. '8ZFB2K09' (alphanumeric)
+```
+
+## API
+
+All entry points are module functions on `LacusUtils`, implemented in [`src/`](src/) and covered by tests in [`tests/`](tests/).
+
+### `LacusUtils.describe_type(value) -> String`
+
+Describes the type of a value for error messages. Pure, deterministic, and never raises.
+
+| Input | Result |
+|--------|--------|
+| `nil` | `'nil'` |
+| `String` | `'string'` |
+| `true` / `false` | `'boolean'` |
+| `Integer` | `'integer number'` |
+| `Float` (finite) | `'float number'` |
+| `Float::NAN` | `'NaN'` |
+| `Float::INFINITY` / `-Float::INFINITY` | `'Infinity'` |
+| `Complex` | `'complex number'` |
+| `Rational` | `'rational number'` |
+| `Symbol` | `'symbol'` |
+| `Hash` | `'hash'` |
+| `Set` | `'set'` |
+| `Proc` / `Method` | `'function'` |
+| `Class` / `Module` | `'class'` |
+| custom object | `'object'` |
+| `[]` | `'Array (empty)'` |
+| `[1, 2, 3]` | `'number[]'` |
+| `[1, 'a', 2]` | `'(number \| string)[]'` |
+
+Inside an array, numeric values collapse to `'number'`, and the union of element types preserves first-seen order (it is **not** sorted).
+
+### `LacusUtils.generate_random_sequence(size, type = :alphanumeric) -> String`
+
+Generates a random character sequence of the given length and type, drawn using a cryptographically secure RNG (`SecureRandom`).
+
+- **`size`**: `Integer` — length of the sequence (e.g. `10`). `0` returns `''`.
+- **`type`**: `Symbol` — character set to draw from (defaults to `:alphanumeric`). One of:
+  - **`:numeric`**: digits `0-9`
+  - **`:alphabetic`**: uppercase letters `A-Z`
+  - **`:alphanumeric`**: digits and uppercase letters `0-9A-Z`
+
+```ruby
+LacusUtils.generate_random_sequence(10, :numeric)      # => e.g. '9956000611'
+LacusUtils.generate_random_sequence(6, :alphabetic)    # => e.g. 'AXQMZB'
+LacusUtils.generate_random_sequence(8)                 # => e.g. '8ZFB2K09' (alphanumeric)
+LacusUtils.generate_random_sequence(0)                 # => ''
+```
+
+Raises `ArgumentError` when `size` is negative, and `ArgumentError` when `type` is not one of the three known kinds:
+
+```ruby
+LacusUtils.generate_random_sequence(-1)       # => ArgumentError: size must be non-negative, got -1
+LacusUtils.generate_random_sequence(4, :foo)  # => ArgumentError: unknown sequence type: :foo
+```
+
+### Exports summary
+
+| Method | Description |
+|--------|-------------|
+| `describe_type(value)` | Type description for error messages |
+| `generate_random_sequence(size, type = :alphanumeric)` | Random sequence generation |
+
+## Contribution & Support
+
+We welcome contributions! Please see our [Contributing Guidelines](https://github.com/LacusSolutions/br-utils-ruby/blob/main/CONTRIBUTING.md) for details. If you find this project helpful, please consider:
+
+- ⭐ Starring the repository
+- 🤝 Contributing to the codebase
+- 💡 [Suggesting new features](https://github.com/LacusSolutions/br-utils-ruby/issues)
+- 🐛 [Reporting bugs](https://github.com/LacusSolutions/br-utils-ruby/issues)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/LacusSolutions/br-utils-ruby/blob/main/LICENSE) file for details.
+
+## Changelog
+
+See [CHANGELOG](./CHANGELOG.md) for a list of changes and version history.
+
+---
+
+Made with ❤️ by [Lacus Solutions](https://github.com/LacusSolutions)

data/src/lacus-utils/describe_type.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module LacusUtils
+  # Describes the type of a value for error messages. Returns a short
+  # human-readable string describing the runtime type of the value. Pure,
+  # deterministic, and never raises.
+  #
+  # @param value [Object] any value to describe
+  # @return [String] a human-readable type label
+  #
+  # @example
+  #   LacusUtils.describe_type(nil)              # => 'nil'
+  #   LacusUtils.describe_type('hello')          # => 'string'
+  #   LacusUtils.describe_type(true)             # => 'boolean'
+  #   LacusUtils.describe_type(42)               # => 'integer number'
+  #   LacusUtils.describe_type(3.14)             # => 'float number'
+  #   LacusUtils.describe_type(Float::NAN)       # => 'NaN'
+  #   LacusUtils.describe_type(Float::INFINITY)  # => 'Infinity'
+  #   LacusUtils.describe_type([])               # => 'Array (empty)'
+  #   LacusUtils.describe_type([1, 2, 3])        # => 'number[]'
+  #   LacusUtils.describe_type([1, 'a', 2])      # => '(number | string)[]'
+  #   LacusUtils.describe_type({})               # => 'hash'
+  def self.describe_type(value)
+    return describe_type_array(value) if value.is_a?(Array)
+
+    describe_type_scalar(value)
+  end
+
+  def self.describe_type_scalar(value)
+    return 'nil' if value.nil?
+    return 'boolean' if [true, false].include?(value)
+
+    describe_type_numeric(value) || describe_type_named(value)
+  end
+  private_class_method :describe_type_scalar
+
+  def self.describe_type_numeric(value)
+    case value
+    when Integer then 'integer number'
+    when Float then describe_type_float(value, 'float number')
+    when Complex then 'complex number'
+    when Rational then 'rational number'
+    end
+  end
+  private_class_method :describe_type_numeric
+
+  def self.describe_type_named(value)
+    case value
+    when String then 'string'
+    when Symbol then 'symbol'
+    when Hash then 'hash'
+    when Set then 'set'
+    else describe_type_callable(value)
+    end
+  end
+  private_class_method :describe_type_named
+
+  def self.describe_type_callable(value)
+    case value
+    when Proc, Method then 'function'
+    when Module then 'class'
+    else 'object'
+    end
+  end
+  private_class_method :describe_type_callable
+
+  def self.describe_type_float(value, finite_label)
+    return 'NaN' if value.nan?
+    return 'Infinity' if value.infinite?
+
+    finite_label
+  end
+  private_class_method :describe_type_float
+
+  def self.describe_type_array(array)
+    return 'Array (empty)' if array.empty?
+
+    types = array.map { |item| describe_type_item(item) }.uniq
+
+    return "#{types.first}[]" if types.length == 1
+
+    "(#{types.join(' | ')})[]"
+  end
+  private_class_method :describe_type_array
+
+  def self.describe_type_item(item)
+    case item
+    when nil then 'nil'
+    when true, false then 'boolean'
+    when Integer then 'number'
+    when Float then describe_type_float(item, 'number')
+    when String then 'string'
+    else describe_type(item)
+    end
+  end
+  private_class_method :describe_type_item
+end

data/src/lacus-utils/generate_random_sequence.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module LacusUtils
+  NUMERIC_CHARACTERS = '0123456789'
+  ALPHABETIC_CHARACTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+  ALPHANUMERIC_CHARACTERS = (NUMERIC_CHARACTERS + ALPHABETIC_CHARACTERS).freeze
+
+  SEQUENCE_CHARACTER_SETS = {
+    numeric: NUMERIC_CHARACTERS,
+    alphabetic: ALPHABETIC_CHARACTERS,
+    alphanumeric: ALPHANUMERIC_CHARACTERS
+  }.freeze
+
+  # Generates a random character sequence of the given length and type (numeric,
+  # alphabetic, or alphanumeric), drawn using a cryptographically secure RNG.
+  #
+  # @param size [Integer] length of the sequence
+  # @param type [Symbol] character set to draw from; one of +:numeric+ (+0-9+),
+  #   +:alphabetic+ (+A-Z+), or +:alphanumeric+ (+0-9A-Z+). Defaults to
+  #   +:alphanumeric+.
+  # @return [String] a random string of the requested length using uppercase
+  #   letters and/or digits, depending on +type+
+  # @raise [ArgumentError] if +size+ is negative
+  # @raise [ArgumentError] if +type+ is not one of the known kinds
+  #
+  # @example
+  #   LacusUtils.generate_random_sequence(10, :numeric)      # => e.g. '9956000611'
+  #   LacusUtils.generate_random_sequence(6, :alphabetic)    # => e.g. 'AXQMZB'
+  #   LacusUtils.generate_random_sequence(8, :alphanumeric)  # => e.g. '8ZFB2K09'
+  #   LacusUtils.generate_random_sequence(8)                 # => e.g. '8ZFB2K09' (alphanumeric)
+  def self.generate_random_sequence(size, type = :alphanumeric)
+    raise ArgumentError, "size must be non-negative, got #{size}" if size.negative?
+
+    characters = SEQUENCE_CHARACTER_SETS[type.to_sym]
+
+    raise ArgumentError, "unknown sequence type: #{type.inspect}" if characters.nil?
+
+    length = characters.length
+
+    Array.new(size) { characters[SecureRandom.random_number(length)] }.join
+  end
+end

data/src/lacus-utils/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LacusUtils
+  VERSION = '1.0.0'
+end

data/src/lacus-utils.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'lacus-utils/version'
+require_relative 'lacus-utils/describe_type'
+require_relative 'lacus-utils/generate_random_sequence'
+
+# General-purpose utility library: type description and random sequence
+# generation. All entry points are module functions on +LacusUtils+.
+module LacusUtils
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: lacus-utils
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Julio L. Muller
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-08 00:00:00.000000000 Z
+dependencies: []
+description: Reusable utilities library for Lacus Solutions Ruby gems (type description,
+  random sequences).
+email:
+- juliolmuller@outlook.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- src/lacus-utils.rb
+- src/lacus-utils/describe_type.rb
+- src/lacus-utils/generate_random_sequence.rb
+- src/lacus-utils/version.rb
+homepage: https://github.com/LacusSolutions/br-utils-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/LacusSolutions/br-utils-ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- src
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Reusable utilities for Lacus Solutions Ruby packages
+test_files: []