toolx 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f027d545a91be1a02f8ef28f52ced20c6d6ffe3defc99be3f59dd783b78bed2f
+  data.tar.gz: 453e20a3f42da721d4acdb50fb62de95ad62b4801c6c652c3285c8a5de311a21
+SHA512:
+  metadata.gz: 9551fd33fe000bf1a10e5500a409f770ea64533b3db892825174f96659773fa93b872b78f21cb7dbdfc575045e54024bddb18e499b96417c36a1edf0a931a3b4
+  data.tar.gz: '018ed1cadf76d903502d6e1b5fdd1c3bc14d3891995d35d2566fb36c2c15ffbd59ea04c6af87d46f7c876cbf840a5f903b3b2eae8b6d43e3afafa3738ee74de1'

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,58 @@
+# Omakase Ruby styling for Rails
+inherit_gem: { rubocop-rails-omakase: rubocop.yml }
+
+# Overwrite or add rules to create your own house style
+#
+# # Use `[a, [b, c]]` not `[ a, [ b, c ] ]`
+# Layout/SpaceInsideArrayLiteralBrackets:
+#   Enabled: false
+
+AllCops:
+  TargetRubyVersion: 3.4.0
+  MaxFilesInCache: 30000
+  DefaultFormatter: progress
+  NewCops: enable
+  Exclude:
+    - 'spec/fixtures/**/*'
+    - 'tmp/**/*'
+    - 'bin/*'
+    - 'lib/tasks/**/*'
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 240
+  IgnoredPatterns:
+    - !ruby/regexp /\A +(it|describe|context|shared_examples|include_examples|it_behaves_like|def) ["']/
+  Severity: info
+
+Layout/EndOfLine:
+  EnforcedStyle: lf
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/AbcSize:
+  Max: 36
+
+Layout/HashAlignment:
+  Enabled: false
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+  EnforcedLastArgumentHashStyle: always_inspect
+
+Layout/MultilineMethodCallIndentation:
+  Enabled: true
+
+Layout/SpaceInsideArrayLiteralBrackets:
+  EnforcedStyle: no_space
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/Guardfile

@@ -0,0 +1,11 @@
+guard :rspec, cmd: 'rspec' do
+  watch(%r{^lib/(.+).rb$})      { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^spec/(.+).rb$})     { |m| "spec/#{m[1]}.rb" }
+  watch('spec/spec_helper.rb')  { 'spec' }
+  watch('Gemfile')
+end
+
+guard :rubocop, all_on_start: false, cli: ['--format', 'clang'] do
+  watch(%r{.+\.rb$})
+  watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Pawel Niemczyk
+
+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,452 @@
+# Toolx
+
+This gem adds a set of tools to enhance your Ruby on Rails application, providing utilities for envs, uniq ids, and more.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add toolx
+
+Use rake tasks if needed:
+
+```bash
+bin/rails toolx:aliases:generate                             # Generate toolx_aliases.rb
+bin/rails toolx:annotate:generate                            # Generate annotate rake tasks
+bin/rails toolx:stateman:generate[model]                     # Generate StateMachine, Transition class, and migration
+```
+
+Add your toolx mixins to the `ApplicationRecord` or any other model:
+
+```ruby
+class ApplicationRecord < ActiveRecord::Base
+  primary_abstract_class
+
+  include Toolx::Core::Concerns::Inquirer
+  include Toolx::Core::Concerns::Transformer
+  include Toolx::Core::Concerns::CustomIdentifier
+  include Toolx::Core::Concerns::DateTimeToBoolean
+  include Toolx::Core::Concerns::WithStateMachine
+end
+```
+
+
+## Features
+
+### Env
+
+Access environment variables in a clean, expressive way.
+
+```ruby
+ENV['ROLE'] = 'admin'
+
+Env = Toolx::Core::Env
+
+Env[:role]             # => "admin"
+Env.role               # => "admin"
+Env.role_.admin?       # => true
+Env.role_.user?        # => false
+Env.debug?             # => true/false (boolean cast)
+Env.timeout!(10)       # => 10 (integer cast)
+Env.role_(:none).none? # => true (inquiry cast)
+```
+
+### CustomIdentifier
+
+Generate a custom ID for the `id` column
+
+```ruby
+CustomIdentifier = Toolx::Core::Concerns::CustomIdentifier
+
+class User < ApplicationRecord
+  include CustomIdentifier
+  cid 'usr'
+end
+
+user.id # => "usr_Nc82xL0w92..."
+```
+
+```ruby
+CustomIdentifier = Toolx::Core::Concerns::CustomIdentifier
+
+class Document < ApplicationRecord
+  include CustomIdentifier
+  belongs_to :workspace
+  cid 'doc', related: { workspace: 4 }
+end
+
+# If workspace_id = "wsp_ABCXYZ...", then document id will be like:
+# "doc_ABCXabcd123..."
+```
+
+### Inquirer
+
+Adds ? predicate-style behavior for strings.
+
+```ruby
+
+class User < ApplicationRecord
+  include Toolx::Core::Concerns::Inquirer
+
+  inquirer :status, :kind
+end
+
+user = User.new(status: "active", kind: "admin")
+user.status.active? # => true
+user.status.inactive? # => false
+user.kind.admin? # => true
+user.kind.user?  # => false
+```
+
+### Transformer
+
+Transform input strings on assignment (e.g., strip, downcase, etc.)
+
+```ruby
+class User < ApplicationRecord
+  include Toolx::Core::Concerns::Transformer
+
+  transform :email, :strip, :downcase
+  transform :name, :strip, :presence
+end
+
+user = User.new
+user.email = " Foo@Example.COM  "
+user.name  = "   "
+
+user.email # => "foo@example.com"
+user.name  # => nil
+```
+
+### DateTimeToBoolean
+
+Use datetime fields as boolean-style flags:
+
+```ruby
+class User < ApplicationRecord
+  include Toolx::Core::Concerns::DateTimeToBoolean
+
+  date_time_to_boolean :deleted_at
+end
+
+user.deleted?  # => false
+user.deleted!  # sets deleted_at to current time
+user.deleted = true  # also sets current time
+user.deleted = false # sets deleted_at to nil
+```
+
+### Errors
+
+A structured, extensible error-handling framework:
+
+
+Wrap errors with nested backtrace info
+
+```ruby
+class MyError < StandardError
+  include Toolx::Core::Errors::NestedError
+end
+
+begin
+  raise "Something failed"
+rescue => e
+  raise MyError.new("Outer error", e)
+end
+```
+
+Base error classes
+
+```ruby 
+Toolx::Core::Errors::NestedStandardError
+Toolx::Core::Errors::AppError
+Toolx::Core::Errors::ApiError
+
+Toolx::Core::Errors::BadRequest
+Toolx::Core::Errors::Unauthorized
+Toolx::Core::Errors::NotFound
+Toolx::Core::Errors::Conflict
+Toolx::Core::Errors::UnprocessableEntity
+Toolx::Core::Errors::FailedDependency
+Toolx::Core::Errors::Forbidden
+Toolx::Core::Errors::InternalServerError
+Toolx::Core::Errors::BadGateway
+Toolx::Core::Errors::ServiceUnavailable
+Toolx::Core::Errors::GatewayTimeout
+```
+
+### Form
+
+A simple form builder for Rails applications:
+
+```ruby
+class Space::InfoForm < Toolx::Core::Form
+  attribute :name, :string
+  attribute :description, :string
+  attribute :kind, :string
+
+  validates :name, presence: true
+  validates :kind, inclusion: { in: Space::KINDS }, allow_blank: true
+end
+```
+
+### Presenter
+
+Elegant presenter base class wrapping any object, with I18n support and flexible invocation patterns.
+
+```ruby
+class UserPresenter < Toolx::Core::Presenter
+  def display_name
+    name.upcase
+  end
+end
+
+UserPresenter.present(user).display_name # => "ALICE"
+```
+
+to_proc usage
+
+```ruby
+users.map(&UserPresenter) # => wraps each user
+```
+
+as_proc(use: :method) usage
+
+```ruby
+users.map(&UserPresenter.as_proc(use: :display_name))
+```
+
+ auto_present detection
+
+```ruby
+class Article
+  class Presenter < ::Toolx::Core::Presenter
+    def short_title = title.truncate(10)
+  end
+end
+
+Presenter.auto_present(Article.new(title: "A very long title"))
+```
+
+
+### SimpleCrypt
+
+Simple AES encryption helper using ActiveSupport::MessageEncryptor.
+
+```ruby
+Toolx::Core::SimpleCrypt.encrypt('hello') # => encrypted string
+Toolx::Core::SimpleCrypt.decrypt(encrypted_string) # => "hello"
+```
+
+* Uses ENV['CRYPT_SECRET'] or Rails credentials by default.
+* You can pass a custom secret: if needed.
+
+```ruby
+encrypted = Toolx::Core::SimpleCrypt.encrypt('secret info', secret: 'a' * 32)
+Toolx::Core::SimpleCrypt.decrypt(encrypted, secret: 'a' * 32) # => 'secret info'
+```
+
+❗️ Errors
+* MissingSecretError – when no secret is configured
+* EncryptionError – on encryption failure
+* DecryptionError – on verification or decoding failure
+
+### Operation
+
+A base class for service operations, providing a structured way to define and execute business logic with typed parameters and responses.
+
+```ruby
+class Country::Code < Toolx::Core::Operation
+  self.transactional = false # When we do not need transaction support, by default it is true
+  simplified_result :value
+
+  params { attribute :source, Types.Instance(ISO3166::Country) | Types::Coercible::String }
+  response { attribute :value, Types::Symbol }
+
+  def perform = { value: Country::Object[source:].alpha2.to_sym }
+
+  private
+
+  delegate :source, to: :params
+end
+# when simplified_result is used it is possible to use it like this:
+source = 'Polska'
+Country::Code[source:] # => :PL
+Country::Code.call(source:) # => :PL
+Country::Code.(source:) # => :PL
+# And default one 
+Country::Code.new(source:).perform.value # => :PL
+```
+
+Operation provides accessories like `params`, `response` but it can be used as Param and Response classes as well.
+
+```ruby
+class Country::Code < Toolx::Core::Operation
+  self.transactional = false # When we do not need transaction support
+  # callback :before, :after, :around, etc. can be used to add hooks
+  after -> { 'send notification' }
+  before :validate!
+  
+  rescue_from ActiveRecord::RecordInvalid, with: :raise_something
+  
+  class Params 
+    attribute :source, Types.Instance(ISO3166::Country) | Types::Coercible::String }
+  end
+  
+  class Response
+    attribute :value, Types::Symbol
+  end
+
+  def perform = { value: Country::Object[source:].alpha2.to_sym }
+
+  private
+  
+  def validate! = true
+  
+  def raise_something(exception)
+    raise Toolx::Core::Errors::BadRequest, "Invalid source: #{exception.message}"
+  end
+
+  delegate :source, to: :params
+end
+```
+
+### Operation::Flow
+
+A streamlined interface for orchestrating and executing service operations with support for:
+
+* typed parameters (via Dry::Types)
+* typed responses (with translation helpers & inquiry methods)
+* flow control (.on_success, .on_fail, .bind_with, .perform, etc.)
+
+```ruby
+class SignupOperation < Toolx::Core::Operation
+  include Toolx::Core::Operation::Flow
+
+  params do
+    attribute :email, Types::String
+    attribute :age, Types::Integer
+  end
+
+  response do
+    include Toolx::Core::Concerns::Inquirer
+    attribute :status, Types::String
+    attribute :message, Types::String
+    inquirer :status
+  end
+
+  def perform
+    if age < 18
+      { status: 'error', message: 'You must be 18+' }
+    else
+      { status: 'success', message: "Welcome, #{email}" }
+    end
+  end
+end
+```
+
+🚀 Execution Flow
+
+Initialize, perform, and access result:
+
+```ruby
+flow = SignupOperation.flow
+executor = flow.perform(email: 'foo@bar.com', age: 20)
+
+executor.response.status.success? # => true
+executor.response.message         # => "Welcome, foo@bar.com"
+```
+
+Retry logic:
+
+```ruby
+executor.perform!                # Re-executes with same params
+executor.perform!(email: ..., age: ...) # Replaces and re-executes
+```
+
+🔁 Handler Bindings
+
+Symbolic method bindings:
+
+```ruby
+SignupOperation.flow
+  .bind_with(self)
+  .on(success: :redirect_to_dashboard, fail: :render_form)
+  .perform(email: 'foo@bar.com', age: 17)
+```
+
+Proc-style handler chaining:
+
+```ruby
+SignupOperation.flow
+  .on_success { |resp, exec| notify_user(resp.message) }
+  .on_fail { |resp, exec| logger.warn("Failed: #{resp.message}") }
+  .perform!(email: 'foo@bar.com', age: 20)
+```
+
+### Stateman via with_state_machine 
+
+It is working only with `Statesman::Adapters::ActiveRecord`
+
+You can generate state machine classes via rake task
+
+```bash
+bin/rails "toolx:stateman:generate[Project]"
+```
+command will generate models for existing `Project` model as
+`Project::StateMachine` and `Project::Transition`.
+
+also will add migraion file for those models.
+
+Example usage:
+
+```ruby
+class Project::StateMachine
+  include Statesman::Machine
+
+  state :active, initial: true
+  state :pending
+  state :skipped
+  state :cancelled
+  state :done
+
+  transition from: :active, to: [:pending, :pending, :skipped, :cancelled, :done]
+  transition from: :pending, to: [:skipped, :cancelled, :done]
+  transition from: :skipped, to: [:pending]
+
+  after_transition do |model, transition|
+    model.update!(status: transition.to_state)
+  end
+end
+
+class Project::Transition < ActiveRecord::Base
+  belongs_to :project
+
+  attribute :most_recent, :boolean, default: false
+  attribute :sort_key, :integer
+  attribute :to_state, :string
+  attribute :metadata, :json, default: {}
+
+  validates :to_state, inclusion: { in: Project::StateMachine.states }
+end
+
+class Project < ActiveRecord::Base
+  include Toolx::Core::Concerns::WithStateMachine
+  STATUSES = %w[active pending done skipped cancelled].freeze
+
+  with_state_machine
+
+  attribute :name, :string
+  attribute :status, :string, default: 'active'
+
+  validates :name, presence: true
+  validates :status, inclusion: { in: STATUSES }, allow_nil: true
+end
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Toolx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/toolx/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]