sidekiq-sorbet 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf07ecd6229ca17be91443492b29af00f719d9fa26f6f6f13c8f5ef3750cd43a
+  data.tar.gz: f821632d9af46561d5dabd1529ee0daeefd915f6ed1182a02035dc0084bb77ec
+SHA512:
+  metadata.gz: 95792b5c0cf3a4c603098a61342d4788a8f8da9bea4269e4fcdc411b9bc631bfa94b63a9c2f15b394eef4d1251236c74310f997bf3b29e58e42139899fea5d59
+  data.tar.gz: ebcedc188a5a2f7a7da792c8014daaaafdb18dc0cd944497abd4ef79692c0c0abf0e616cde526bc126dec6c18f1b0d879aeebb8443c0e9e8f222e02885890861

data/.vscode/cspell.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://raw.githubusercontent.com/streetsidesoftware/cspell/main/cspell.schema.json",
+  "version": "0.2",
+  "dictionaryDefinitions": [
+    {
+      "name": "project-words",
+      "path": "./project-words.txt",
+      "addWords": true
+    }
+  ],
+  "dictionaries": [
+    "project-words"
+  ],
+  "ignorePaths": [
+    ".idea",
+    ".vscode"
+  ]
+}

data/.vscode/project-words.txt

@@ -0,0 +1,8 @@
+bindir
+Kodkod
+kwargs
+nilable
+popen
+readlines
+rubocop
+sidekiq

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-12-16
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"sidekiq-sorbet" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["678665+akodkod@users.noreply.github.com"](mailto:"678665+akodkod@users.noreply.github.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Andrew Kodkod
+
+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,266 @@
+# Sidekiq::Sorbet
+
+Add typed arguments to your Sidekiq Workers with automatic argument access.
+
+## Quick Example
+
+```ruby
+# Worker Class
+class AnalyzeAttachmentWorker
+  include Sidekiq::Sorbet
+
+  class Args < T::Struct
+    const :attachment_id, Integer
+    const :regenerate, T::Boolean, default: false
+  end
+
+  def run
+    # Direct access to typed arguments
+    attachment = Attachment.find(attachment_id)
+    return if attachment.analyzed? && !regenerate
+
+    attachment.analyze!
+  end
+end
+
+# Call Worker
+AnalyzeAttachmentWorker.run_async(attachment_id: 1)                     # arguments are typed and validated
+AnalyzeAttachmentWorker.run_sync(attachment_id: 1, regenerate: true)    # execute synchronously
+```
+
+## Features
+
+- ✅ **Direct argument access** - Access arguments directly as `attachment_id` instead of `args.attachment_id`
+- ✅ **Type safety** - Arguments are validated at enqueue time using Sorbet's T::Struct
+- ✅ **Optional Args** - Workers can omit the Args class if they don't need arguments
+- ✅ **Backward compatible** - The `args` accessor still works: `args.attachment_id`
+- ✅ **Clean API** - Use `run_async`/`run_sync` instead of `perform_async`/`perform`
+- ✅ **Fail-fast validation** - Errors caught before jobs are enqueued
+- ✅ **Comprehensive errors** - Clear error messages for debugging
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add sidekiq-sorbet
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install sidekiq-sorbet
+```
+
+## Usage
+
+### Basic Worker with Arguments
+
+```ruby
+class ProcessUserWorker
+  include Sidekiq::Sorbet
+
+  class Args < T::Struct
+    const :user_id, Integer
+    const :send_email, T::Boolean, default: true
+  end
+
+  def run
+    user = User.find(user_id)
+    user.process!
+    UserMailer.processed(user).deliver_later if send_email
+  end
+end
+
+# Enqueue the job
+ProcessUserWorker.run_async(user_id: 123)
+ProcessUserWorker.run_async(user_id: 456, send_email: false)
+```
+
+### Worker Without Arguments
+
+Args class is optional! Workers without arguments work perfectly:
+
+```ruby
+class CleanupWorker
+  include Sidekiq::Sorbet
+
+  def run
+    # Perform cleanup tasks
+    clean_temp_files
+    vacuum_database
+  end
+end
+
+# No arguments needed
+CleanupWorker.run_async
+```
+
+### Complex Types
+
+```ruby
+class ReportWorker
+  include Sidekiq::Sorbet
+
+  class Args < T::Struct
+    const :user_ids, T::Array[Integer]
+    const :filters, T::Hash[String, T.untyped], default: {}
+    const :format, String
+  end
+
+  def run
+    users = User.where(id: user_ids)
+    report = ReportGenerator.new(users, filters)
+    report.export(format)
+  end
+end
+
+ReportWorker.run_async(
+  user_ids: [1, 2, 3],
+  filters: { "active" => true },
+  format: "pdf",
+)
+```
+
+### Nested T::Structs
+
+```ruby
+class NotificationWorker
+  include Sidekiq::Sorbet
+
+  class Recipient < T::Struct
+    const :name, String
+    const :email, String
+  end
+
+  class Args < T::Struct
+    const :recipient, Recipient
+    const :message, String
+  end
+
+  def run
+    # Access nested struct fields
+    email = NotificationMailer.compose(
+      to: recipient.email,
+      name: recipient.name,
+      body: message,
+    )
+    email.deliver
+  end
+end
+
+NotificationWorker.run_async(
+  recipient: NotificationWorker::Recipient.new(
+    name: "John Doe",
+    email: "john@example.com",
+  ),
+  message: "Hello!",
+)
+```
+
+### Backward Compatibility
+
+The `args` accessor still works if you prefer the old style:
+
+```ruby
+class LegacyWorker
+  include Sidekiq::Sorbet
+
+  class Args < T::Struct
+    const :value, Integer
+  end
+
+  def run
+    # Both styles work
+    direct = value           # Direct access (recommended)
+    via_args = args.value    # Via args accessor (still works)
+  end
+end
+```
+
+### Synchronous Execution
+
+Use `run_sync` for testing or immediate execution:
+
+```ruby
+# In tests
+result = ProcessUserWorker.run_sync(user_id: 123)
+
+# In console for debugging
+AnalyzeAttachmentWorker.run_sync(attachment_id: 456)
+```
+
+## Tapioca DSL Compiler
+
+This gem includes a Tapioca DSL compiler that generates proper type signatures for your workers. This enables Sorbet to understand the dynamically generated methods like `run_async`, `run_sync`, and argument accessors.
+
+### Generating RBI Files
+
+Run the Tapioca DSL compiler to generate type definitions:
+
+```bash
+bundle exec tapioca dsl SidekiqSorbet
+```
+
+Or generate RBI files for all DSL compilers:
+
+```bash
+bundle exec tapioca dsl
+```
+
+### Generated Signatures
+
+For a worker like this:
+
+```ruby
+class MyWorker
+  include Sidekiq::Sorbet
+
+  class Args < T::Struct
+    const :user_id, Integer
+    const :notify, T::Boolean, default: false
+  end
+
+  def run
+    # ...
+  end
+end
+```
+
+The compiler generates:
+
+```rbi
+class MyWorker
+  sig { returns(Integer) }
+  def user_id; end
+
+  sig { returns(T::Boolean) }
+  def notify; end
+
+  sig { params(user_id: Integer, notify: T::Boolean).returns(String) }
+  def self.run_async(user_id:, notify: T.unsafe(nil)); end
+
+  sig { params(user_id: Integer, notify: T::Boolean).returns(T.untyped) }
+  def self.run_sync(user_id:, notify: T.unsafe(nil)); end
+end
+```
+
+Workers without an `Args` class will still have `run_async` and `run_sync` generated with no parameters.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/sidekiq-sorbet. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/sidekiq-sorbet/blob/main/CODE_OF_CONDUCT.md).
+
+## 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 Sidekiq::Sorbet project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/sidekiq-sorbet/blob/main/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: [:spec, :rubocop]

data/lib/sidekiq/sorbet/class_methods.rb

@@ -0,0 +1,114 @@
+# typed: false
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Sidekiq
+  module Sorbet
+    # Class methods added to workers that include Sidekiq::Sorbet
+    module ClassMethods
+      extend T::Sig
+
+      # Enqueues a job asynchronously with validated arguments
+      #
+      # @param kwargs [Hash] Arguments matching the Args T::Struct (or empty if no Args)
+      # @return [String] Sidekiq job ID
+      # @raise [InvalidArgsError] if arguments fail validation
+      # @raise [SerializationError] if serialization fails
+      sig { params(kwargs: T.untyped).returns(String) }
+      def run_async(**kwargs)
+        args_instance = build_args(**kwargs)
+        serialized = serialize_args(args_instance)
+        perform_async(serialized)
+      end
+
+      # Executes a job synchronously with validated arguments
+      #
+      # @param kwargs [Hash] Arguments matching the Args T::Struct (or empty if no Args)
+      # @return [Object] Result of the run method
+      # @raise [InvalidArgsError] if arguments fail validation
+      sig { params(kwargs: T.untyped).returns(T.untyped) }
+      def run_sync(**kwargs)
+        args_instance = build_args(**kwargs)
+        worker = new
+        worker.instance_variable_set(:@args, args_instance)
+        worker.define_arg_accessors if args_instance
+        worker.run
+      rescue InvalidArgsError, ArgsNotDefinedError, SerializationError
+        raise
+      rescue StandardError => e
+        raise Error,
+              "Error in #{name}#run: #{e.message}\n#{e.backtrace&.join("\n")}"
+      end
+
+      # Returns the Args class for this worker, or nil if not defined
+      #
+      # @return [Class, nil] The Args T::Struct class or nil
+      sig { returns(T.nilable(T.class_of(T::Struct))) }
+      def args_class
+        return @args_class if defined?(@args_class)
+
+        @args_class = T.let(
+          begin
+            klass = const_defined?(:Args, false) ? const_get(:Args) : nil
+            validate_args_class!(klass) if klass
+            klass
+          end,
+          T.nilable(T.class_of(T::Struct)),
+        )
+      end
+
+      private
+
+      # Validates that the Args class is a T::Struct
+      #
+      # @param klass [Class] The class to validate
+      # @return [Class] The validated class
+      # @raise [ArgsNotDefinedError] if invalid
+      sig { params(klass: T.untyped).returns(T.class_of(T::Struct)) }
+      def validate_args_class!(klass)
+        unless klass < T::Struct
+          raise ArgsNotDefinedError,
+                "#{name}::Args must inherit from T::Struct, got #{klass.class}"
+        end
+
+        klass
+      end
+
+      # Builds and validates Args instance (or returns nil if no Args class)
+      #
+      # @param kwargs [Hash] Arguments to pass to Args.new
+      # @return [T::Struct, nil] Validated Args instance or nil
+      # @raise [InvalidArgsError] if validation fails
+      sig { params(kwargs: T.untyped).returns(T.nilable(T::Struct)) }
+      def build_args(**kwargs)
+        return nil unless args_class
+
+        if kwargs.empty?
+          # No args provided - create empty Args if possible
+          args_class.new
+        else
+          args_class.new(**kwargs)
+        end
+      rescue ArgumentError, TypeError => e
+        raise InvalidArgsError,
+              "Invalid arguments for #{name}: #{e.message}"
+      end
+
+      # Serializes Args instance to JSON-compatible hash
+      #
+      # @param args_instance [T::Struct, nil] The Args instance or nil
+      # @return [Hash] Serialized hash with string keys (empty if nil)
+      # @raise [SerializationError] if serialization fails
+      sig { params(args_instance: T.nilable(T::Struct)).returns(T::Hash[String, T.untyped]) }
+      def serialize_args(args_instance)
+        return {} unless args_instance
+
+        args_instance.serialize
+      rescue StandardError => e
+        raise SerializationError,
+              "Failed to serialize args for #{name}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/sidekiq/sorbet/errors.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+module Sidekiq
+  module Sorbet
+    # Base error class for all Sidekiq::Sorbet errors
+    class Error < StandardError; end
+
+    # Raised when a worker doesn't define an Args class or it's not a T::Struct
+    class ArgsNotDefinedError < Error; end
+
+    # Raised when argument validation fails at enqueue time
+    class InvalidArgsError < Error; end
+
+    # Raised when serialization or deserialization fails
+    class SerializationError < Error; end
+  end
+end

data/lib/sidekiq/sorbet/instance_methods.rb

@@ -0,0 +1,89 @@
+# typed: false
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+module Sidekiq
+  module Sorbet
+    # Instance methods added to workers that include Sidekiq::Sorbet
+    module InstanceMethods
+      extend T::Sig
+
+      # Sidekiq calls this method when executing the job
+      # We deserialize the args and delegate to the user's run method
+      #
+      # @param serialized_hash [Hash] Serialized arguments from Sidekiq
+      # @return [Object] Result of the run method
+      # @raise [SerializationError] if deserialization fails
+      sig { params(serialized_hash: T::Hash[String, T.untyped]).returns(T.untyped) }
+      def perform(serialized_hash)
+        @args = T.let(
+          deserialize_args(serialized_hash),
+          T.nilable(T::Struct),
+        )
+        define_arg_accessors if @args
+        run
+      rescue SerializationError
+        raise
+      rescue StandardError => e
+        raise Error,
+              "Error in #{self.class.name}#run: #{e.message}\n#{e.backtrace&.join("\n")}"
+      end
+
+      # Accessor for typed arguments (optional, for backward compatibility)
+      #
+      # @return [T::Struct, nil] The Args instance or nil
+      sig { returns(T.nilable(T::Struct)) }
+      def args
+        @args
+      end
+
+      # Define getter methods for each field in the Args struct
+      # This allows direct access like `attachment_id` instead of `args.attachment_id`
+      #
+      # @return [void]
+      sig { void }
+      def define_arg_accessors
+        return unless @args
+
+        @args.class.props.each_key do |field_name|
+          # Skip if method already defined (avoid overriding user methods)
+          next if respond_to?(field_name, true) && !@args.respond_to?(field_name)
+
+          # Define a method to access the field
+          define_singleton_method(field_name) do
+            @args.public_send(field_name)
+          end
+        end
+      end
+
+      # Users implement this method in their worker
+      #
+      # @return [Object] Whatever the worker returns
+      # @raise [NotImplementedError] if not overridden
+      sig { returns(T.untyped) }
+      def run
+        raise NotImplementedError,
+              "#{self.class.name} must implement #run method"
+      end
+
+      private
+
+      # Deserializes hash back into Args T::Struct
+      #
+      # @param serialized_hash [Hash] Hash with string keys from Sidekiq
+      # @return [T::Struct, nil] Deserialized Args instance or nil
+      # @raise [SerializationError] if deserialization fails
+      sig { params(serialized_hash: T::Hash[String, T.untyped]).returns(T.nilable(T::Struct)) }
+      def deserialize_args(serialized_hash)
+        args_klass = self.class.args_class
+        return nil unless args_klass
+
+        args_klass.from_hash(serialized_hash)
+      rescue StandardError => e
+        raise SerializationError,
+              "Failed to deserialize args for #{self.class.name}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/sidekiq/sorbet/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sidekiq
+  module Sorbet
+    VERSION = "0.1.0"
+  end
+end

data/lib/sidekiq/sorbet.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+require_relative "sorbet/version"
+require_relative "sorbet/errors"
+require_relative "sorbet/class_methods"
+require_relative "sorbet/instance_methods"
+
+# Load Tapioca DSL compiler if Tapioca is available
+begin
+  require "tapioca/dsl"
+  require_relative "../tapioca/dsl/compilers/sidekiq_sorbet"
+rescue LoadError
+  # Tapioca not available, skip compiler
+end
+
+module Sidekiq
+  module Sorbet
+    extend T::Sig
+
+    # Hook called when Sidekiq::Sorbet is included in a worker
+    # Automatically includes Sidekiq::Job if needed and wires up our modules
+    #
+    # @param base [Class] The worker class including this module
+    sig { params(base: T.untyped).void }
+    def self.included(base)
+      base.include(Sidekiq::Job) unless base.ancestors.include?(Sidekiq::Job)
+      base.extend(ClassMethods)
+      base.include(InstanceMethods)
+    end
+  end
+end