yuuki 0.1.12 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7409615113f6585101139dd2df95c8f737d0f291016351b152bc3e01390ab8d0
-  data.tar.gz: 3941d1d916033d8cbf5944f55cad051f74213d8d0d809476d155800b60204b5f
+  metadata.gz: 73ee236ec079617db802006ec29558cb42cbeb17143487fb5d03f9b0781e2211
+  data.tar.gz: 507eaffb469b260061af77703546bfb20bb4c9e5c8d62c26b946a861a2c69f36
 SHA512:
-  metadata.gz: 2a7dc76ec6ac0d04fbc8a734a5e79994a3f58fbb1f8d8c888c586e66442ce1eb5398ce9e1a413c9edb0145a3bfeb479843bbc2c721dd317305fdeb242bac8e3c
-  data.tar.gz: b22db32336dcceced700ffb15b65221c8020db7243df8b9cf79adc7a9d6a51426cfade7826a38045e74eb5da4d2ce5b2df0d76c2a90a5924591fe65c76fe9373
+  metadata.gz: 70b198d6f2b79d3df1a27bd750d5ded8d7a1a827b6078f90f34b03ff701716d60a69dd0baa5e2774c4da0b2af7ccbc4b46fb9139056d301a6cfa59b5adcbe714
+  data.tar.gz: 7a8cdefa1d6aa71c65f45b6dda02e6b6987435d82efc821a31a3d40d2921443ad69088bd7e83a339aed22462894ac33afa84416f20af93ecb1468c9895a497d2

data/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  rspec:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['3.0', 'ruby']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec
+
+  rubocop:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby
+          bundler-cache: true
+      - uses: reviewdog/action-rubocop@v2
+        with:
+          github_token: ${{ secrets.github_token }}
+          reporter: ${{ github.event_name == 'pull_request' && 'github-pr-review' || 'github-check' }}
+          skip_install: true
+          use_bundler: true
+          fail_level: any
+          rubocop_flags: lib
+
+  rbs:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['3.0', 'ruby']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rbs -I sig validate

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+---
+AllCops:
+  TargetRubyVersion: 3.0
+Metrics/AbcSize:
+  Enabled: false
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/NumericPredicate:
+  EnforcedStyle: comparison
+Style/SpecialGlobalVars:
+  EnforcedStyle: use_perl_names

data/README.md

@@ -2,6 +2,8 @@
 
 A caller / runner framework for Ruby.
 
+Yuuki lets you tag methods of a class and invoke them by tag. Arguments are delivered to each method by parameter name, and methods can be run in threads, ordered by priority, or executed periodically.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,33 +22,132 @@ Or install it yourself as:
 
 ## Usage
 
+### Basics
+
+Define a runner class that inherits `Yuuki::Runner`. A method named `on_<tag>` is automatically registered with the tag `<tag>`. Any other method can be registered with the `on` decorator, which applies to the next method definition.
+
 ```ruby
 require 'yuuki'
 
-class HogeClass
-  extend Yuuki::Runner
+class Greeter < Yuuki::Runner
+  # registered with the tag :greet (taken from the method name)
+  def on_greet
+    puts 'hello!'
+  end
+
+  # registered with the tags :greet and :farewell
+  on :greet
+  on :farewell
+  def say_goodbye
+    puts 'goodbye!'
+  end
+end
+
+yuuki = Yuuki::Caller.new(Greeter)
+yuuki.run(:greet)
+# hello!
+# goodbye!
+
+yuuki.run(:farewell)
+# goodbye!
+```
+
+`Yuuki::Caller.new` (and `#add`) accepts runner classes and runner instances. A class is instantiated automatically. Inside a runner method, `yuuki` returns the caller the instance belongs to.
+
+### Passing arguments
+
+Keyword arguments given to `run` are delivered to each method by parameter name — no matter whether the parameter is positional or keyword. Extra arguments are simply ignored, and a missing required parameter raises `Yuuki::Error`. A block given to `run` is forwarded as the block of each method.
+
+```ruby
+class Worker < Yuuki::Runner
+  def on_process(name, size: 1)
+    puts "processing #{name} (size: #{size})"
+  end
+end
+
+yuuki = Yuuki::Caller.new(Worker)
+yuuki.run(:process, name: 'job', size: 3, unused: 42)
+# processing job (size: 3)
+```
+
+### Decorators
+
+Decorators are class methods that annotate the **next** method definition.
+
+| Decorator | Effect |
+| --- | --- |
+| `on :tag` | Adds a tag. Can be specified multiple times. |
+| `priority n` | Runs methods with higher priority first (default 0). Also used as `Thread#priority` for threaded methods. |
+| `thread` | Runs the method in a new thread. |
+| `periodic interval` | Runs the method every `interval` seconds (`Yuuki::PeriodicCaller` only). |
+| `first_run` | Runs the method once on startup (`Yuuki::PeriodicCaller` only). |
 
-  add :a
-  def a
-    puts 'a'
+### Threading
+
+Methods marked with `thread` run in their own thread; `run` returns without waiting for them.
+
+```ruby
+class Background < Yuuki::Runner
+  on :heavy
+  thread
+  def heavy_task
+    sleep 1
+    puts 'done'
+  end
+end
+
+yuuki = Yuuki::Caller.new(Background)
+yuuki.run(:heavy) # returns immediately
+yuuki.running?    # => true
+yuuki.join        # waits for all running threads
+```
+
+### Periodic execution
+
+`Yuuki::PeriodicCaller` runs `periodic` methods repeatedly and `first_run` methods once on startup. It is not required by default:
+
+```ruby
+require 'yuuki/periodic_caller'
+
+class Watcher < Yuuki::Runner
+  first_run
+  def setup
+    puts 'starting'
+  end
+
+  periodic 60
+  def check
+    puts 'checking...'
   end
 
-  add :b
-  tag :b, :tag_b
-  def b
-    puts 'b'
+  periodic 86_400
+  def daily
+    puts 'a new day has come'
   end
 end
 
-yuuki = Yuuki::Caller.new(HogeClass)
-yuuki.run
-# a
-# b
+yuuki = Yuuki::PeriodicCaller.new(Watcher)
+yuuki.on_error { |error| warn error.message }
+yuuki.run # blocks forever
+```
+
+Intervals are aligned to wall-clock boundaries in local time: `periodic 60` fires at the top of every minute, and `periodic 86_400` fires at local midnight (pass a GMT offset as the first argument of `run` to change the time zone). Intervals shorter than 1 second are not supported.
+
+An exception raised by a (non-threaded) runner method is passed to the `on_error` callback and the loop keeps running. Without `on_error`, the exception stops `run`.
 
-yuuki.run_tag(:tag_b)
-# b
+### Loading runner files
+
+`Yuuki::Caller.require_dir` requires all `*.rb` files in a directory:
+
+```ruby
+Yuuki::Caller.require_dir('runners')
+Yuuki::Caller.require_dir('runners', recursive: true)
 ```
 
+### Graceful shutdown with Yoshinon
+
+By default, each method invocation is wrapped in a [Yoshinon](https://github.com/Ishotihadus/yoshinon) lock so that a trapped signal waits for running methods to finish. Pass `use_yoshinon: false` to `Yuuki::Caller.new` to disable this.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/ishotihadus/yuuki](https://github.com/ishotihadus/yuuki).

data/lib/yuuki/caller.rb

@@ -1,18 +1,15 @@
 # frozen_string_literal: true
 
-require 'yuuki/runner'
+require 'set'
 require 'yoshinon'
+require 'yuuki/runner'
 
 module Yuuki
   class Caller
-    # requires all the rb files in the given directory
-    # @param [String] require_dir directory
-    # @param [Boolean] recursive
     def self.require_dir(require_dir, recursive: false)
       Dir.glob(recursive ? "#{require_dir}/**/*.rb" : "#{require_dir}/*.rb").each { |file| require file }
     end
 
-    # @param [Object] instances
     def initialize(*instances, use_yoshinon: true)
       @instances = Set.new
       @threads = []
@@ -20,110 +17,53 @@ module Yuuki
       @use_yoshinon = use_yoshinon
     end
 
-    # adds instances to yuuki
-    # @param [Object] instances
     def add(*instances)
       instances.each do |instance|
-        # create instance if class is given
         if instance.is_a?(Class)
           klass = instance
-          # check the klass is extended
-          unless klass.singleton_class.include?(Yuuki::Runner)
-            raise Yuuki::Error, 'Runner instance must be extend Yuuki::Runner'
-          end
+          raise Yuuki::Error, 'Runner instance must be inherit Yuuki::Runner' unless klass < Yuuki::Runner
 
+          # allocate + explicit initialize so that @yuuki is already set when
+          # the runner's #initialize runs
           instance = instance.allocate
           instance.instance_variable_set(:@yuuki, self)
           instance.send(:initialize)
         else
-          # check the klass is extended
-          unless instance.class.singleton_class.include?(Yuuki::Runner)
-            raise Yuuki::Error, 'Runner instance must be extend Yuuki::Runner'
-          end
+          raise Yuuki::Error, 'Runner instance must be inherit Yuuki::Runner' unless instance.is_a?(Yuuki::Runner)
 
-          # add @yuuki to the instance
           instance.instance_variable_set(:@yuuki, self)
         end
-
-        # regist
         @instances << instance
       end
     end
 
-    # returns runners
-    # @return [Array<[Method, Hash<Symbol, Object>]>]
-    def runners
+    # NOTE: intentionally shadows Object#methods; returns [Method, meta] pairs
+    # sorted by priority (highest first)
+    def methods
       list = @instances.flat_map do |instance|
-        methods = instance.class.instance_variable_get(:@yuuki_methods)
-        methods.select { |_sig, meta| meta[:enabled] }.map { |sig, meta| [instance.method(sig), meta] }
+        methods = instance.class.yuuki_methods
+        methods.map { |sig, meta| [instance.method(sig), meta] }
       end
-      list.sort_by { |_method, meta| -(meta[:priority] || 0) }
+      list.sort_by! { |_method, meta| -(meta[:priority] || 0) }
+      list
     end
 
-    # returns all tags defined as Set
-    def tags
-      tags = @instances.flat_map do |instance|
-        methods = instance.class.instance_variable_get(:@yuuki_methods)
-        methods.select { |_sig, meta| meta[:enabled] }.flat_map { |_sig, meta| meta[:tags] }
+    def run(*tags, **args, &block)
+      selector = proc do |_method, meta|
+        meta[:tags] && !(meta[:tags] & tags).empty?
       end
-      ret = Set.new
-      tags.each { |e| ret += e if e }
-      ret
-    end
-
-    # runs all methods
-    # @param [Object] args arguments
-    def run(**args, &)
-      run_internal(runners, args, &)
-    end
-
-    # runs all selected methods
-    # @param [Proc] proc_select
-    # @param [Object] args arguments
-    def run_select(proc_select, **args, &)
-      run_internal(runners.select(&proc_select), args, &)
+      run_select(selector, **args, &block)
     end
 
-    # set whether to ignore ``tag not associated'' error
-    def ignore_tag_error(enabled: true)
-      @ignore_tag_error = enabled
+    def run_select(selector, **args, &block)
+      run_internal(methods.select(&selector), args, &block)
     end
 
-    # runs all methods with the specified tags
-    # @param [Array<Symbol>] tags
-    # @param [Object] args arguments
-    def run_tag(*tags, **args, &)
-      t = self.tags
-      tags.each do |e|
-        next if t.include?(e)
-        raise Yuuki::Error, "tag `#{e}` is not associated" unless @ignore_tag_error
-
-        warn "Yuuki Warning: tag `#{e}` is not associated"
-      end
-      run_select(proc { |_method, meta| meta[:tags]&.intersect?(tags) }, **args, &)
-    end
-
-    # runs the specific method
-    # @param [Class, nil] klass
-    # @param [Symbol, nil] method_sig method name
-    # @param [Object] args arguments
-    def run_method(klass, method_sig, **args, &)
-      select_proc = proc do |method, _meta|
-        flag_klass = klass ? method.receiver.instance_of?(klass) : true
-        flag_method = method_sig ? method.name == method_sig : true
-        flag_klass && flag_method
-      end
-      run_select(select_proc, **args, &)
-    end
-
-    # joins all runnning threads
     def join
       @threads.each(&:join)
       @threads.select!(&:alive?)
     end
 
-    # returns whether any thread is alive
-    # @return [Boolean]
     def alive?
       @threads.select!(&:alive?)
       !@threads.empty?
@@ -147,10 +87,13 @@ module Yuuki
       end
     end
 
+    # Maps the args hash onto the method's parameters by name. Positional
+    # optionals can only be filled left-to-right: once one is unspecified,
+    # passing any later :opt/:rest argument is an error (nonspecified_last_opt).
     def run_method_internal(method, args, &block)
       yoshinon = Yoshinon.lock if @use_yoshinon
       params = method.parameters
-      return method[] if params.empty?
+      return method[&block] if params.empty?
 
       params_array = []
       params_hash = {}
@@ -160,7 +103,8 @@ module Yuuki
         case type
         when :req
           unless args.key?(name)
-            raise Yuuki::Error, "A required argument '#{name}' was not found on running #{method.owner}::#{method.name}"
+            raise Yuuki::Error,
+                  "A required argument '#{name}' was not found on running #{method.owner}::#{method.name}"
           end
 
           params_array << args[name]
@@ -205,10 +149,11 @@ module Yuuki
             params_hash[name] = args[name]
           end
         when :block
-          params_block = args[name]
+          params_block = args[name] if args.key?(name)
         end
       end
-      params_block = block unless params.any? { |type, _| type == :block }
+      # fall back to the block passed to run unless one was explicitly given via args
+      params_block = block unless params.any? { |type, name| type == :block && args.key?(name) }
       params_hash.empty? ? method[*params_array, &params_block] : method[*params_array, **params_hash, &params_block]
     ensure
       yoshinon&.unlock

data/lib/yuuki/periodic_caller.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'yoshinon'
+require 'yuuki/caller'
+require 'yuuki/runner'
+
+module Yuuki
+  class PeriodicCaller < Caller
+    attr_reader :first_run, :current_time
+
+    def initialize(*instances, use_yoshinon: true)
+      super
+      @first_run = true
+    end
+
+    def on_error(&block)
+      @on_error = block
+    end
+
+    def start(gmtoff = Time.now.gmtoff, **args, &block)
+      last_time = nil
+      loop do
+        @current_time = Time.now.to_f
+        begin
+          selector = proc do |_method, meta|
+            next true if @first_run && meta[:first_run]
+            next false unless meta[:periodic]
+            next false unless last_time
+
+            # gmtoff shifts epoch seconds into local time so that intervals
+            # align with local clock boundaries (e.g. 86400 fires at local midnight).
+            # Fires when a multiple of the interval lies in (last_time, current_time].
+            c = @current_time + gmtoff
+            l = last_time + gmtoff
+            (l.div(meta[:periodic]) + 1) * meta[:periodic] <= c
+          end
+          run_select(selector, **args, &block)
+        rescue StandardError
+          @on_error ? @on_error[$!] : raise
+        end
+        @first_run = false
+
+        last_time = @current_time
+        # wake at the next wall-clock second; the boundary check above makes
+        # ticks drift-free, but intervals below 1 second cannot be honored
+        sleep_duration = (@current_time + 1).floor - Time.now.to_f
+        sleep(sleep_duration) if sleep_duration > 0
+      end
+    end
+  end
+end

data/lib/yuuki/runner.rb

@@ -1,63 +1,77 @@
 # frozen_string_literal: true
 
 module Yuuki
-  module Runner
-    def self.extended(base)
-      base.define_method(:yuuki) do
-        @yuuki
-      end
+  class Runner
+    attr_reader :yuuki
+
+    # Decorator-style DSL (`on` / `priority` / `thread` / `periodic` / `first_run`)
+    # pushes entries here; the next instance-method definition consumes them
+    # (see method_added). Both this and yuuki_methods live in per-class ivars.
+    def self.accumulated_decorators
+      @accumulated_decorators ||= []
     end
 
-    # adds methods to yuuki
-    # @param [Array<Symbol>] methods method names
-    def add(*methods)
+    def self.yuuki_methods
       @yuuki_methods ||= {}
-      methods.each do |method|
-        @yuuki_methods[method] ||= {}
-        @yuuki_methods[method][:enabled] = true
-      end
     end
 
-    # deletes methods from yuuki
-    # @param [Array<Symbol>] methods method names
-    def delete(*methods)
-      @yuuki_methods ||= {}
-      methods.each do |method|
-        @yuuki_methods[method] ||= {}
-        @yuuki_methods[method][:enabled] = false
-      end
+    # yuuki_methods is a per-class ivar, so copy it on inheritance to make
+    # runner methods defined in a superclass visible from the subclass.
+    # NOTE: methods added to the superclass after the subclass is defined are
+    # not reflected.
+    def self.inherited(subclass)
+      subclass.instance_variable_set(:@yuuki_methods, yuuki_methods.dup)
+      super
     end
 
-    # adds tags to the method
-    # @param [Symbol] method method name
-    # @param [Array<Symbol>] tags tag names
-    def tag(method, *tags)
-      @yuuki_methods ||= {}
-      @yuuki_methods[method] ||= {}
-      @yuuki_methods[method][:tags] ||= Set.new
-      @yuuki_methods[method][:tags].merge(tags)
+    def self.on(tag)
+      accumulated_decorators << [:tag, tag]
     end
 
-    # enables threading for the methods
-    # @param [Array<Symbol>] methods method names
-    # @param [Boolean] enabled
-    def thread(*methods, enabled: true)
-      @yuuki_methods ||= {}
-      methods.each do |method|
-        @yuuki_methods[method] ||= {}
-        @yuuki_methods[method][:thread] = enabled
-      end
+    def self.priority(priority = 0)
+      accumulated_decorators << [:priority, priority]
     end
 
-    # sets priority to the method
-    # @param [Array<Symbol>] methods method names
-    # @param [Numeric] value
-    def priority(*methods, value)
-      @yuuki_methods ||= {}
-      methods.each do |method|
-        @yuuki_methods[method] ||= {}
-        @yuuki_methods[method][:priority] = value
+    def self.thread(enabled: true)
+      accumulated_decorators << [:thread, enabled]
+    end
+
+    def self.periodic(interval)
+      accumulated_decorators << [:periodic, interval]
+    end
+
+    def self.first_run(enabled: true)
+      accumulated_decorators << [:first_run, enabled]
+    end
+
+    # Registers the method as a runner method when decorators are pending or the
+    # name is `on_<tag>` (which implies the tag <tag>). Note this hook fires for
+    # ANY instance-method definition, including attr_* and private helpers, so
+    # pending decorators are consumed by whatever method comes next.
+    def self.method_added(method_name)
+      return if accumulated_decorators.empty? && !method_name.start_with?('on_')
+
+      options = {}
+      options[:tags] = [method_name[3..].to_sym] if method_name.start_with?('on_')
+
+      accumulated_decorators.each do |tag, elem|
+        if tag == :tag
+          options[:tags] ||= []
+          options[:tags] << elem
+        else
+          options[tag] = elem
+        end
       end
+      accumulated_decorators.clear
+
+      yuuki_methods[method_name] = options
+
+      super
+    end
+
+    def self.singleton_method_added(_method_name)
+      accumulated_decorators.clear
+      super
     end
   end
 end

data/lib/yuuki/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yuuki
-  VERSION = '0.1.12'
+  VERSION = '1.0.2'
 end

data/lib/yuuki.rb

@@ -2,5 +2,6 @@
 
 require 'yuuki/caller'
 require 'yuuki/error'
+require 'yuuki/periodic_caller'
 require 'yuuki/runner'
 require 'yuuki/version'

data/sig/yuuki/caller.rbs

@@ -1,25 +1,43 @@
-# TypeProf 0.21.2
-
-# Classes
 module Yuuki
   class Caller
-    @instances: Set[untyped]
+    # a runner method paired with its registered metadata
+    type runner_entry = [Method, meta]
+
+    type selector = ^(Method, meta) -> boolish
+
+    @instances: Set[Runner]
+
     @threads: Array[Thread]
 
+    @use_yoshinon: bool
+
     def self.require_dir: (String require_dir, ?recursive: bool) -> void
-    def initialize: (*untyped instances) -> void
-    def add: (*untyped instances) -> void
-    def runners: -> Array[untyped]
-    def run: (**untyped) -> void
-    def run_select: (^(Method, Hash[Symbol, untyped]) -> bool proc_select, **untyped) -> void
-    def run_tag: (*Symbol tags, **untyped) -> void
-    def run_method: (Class klass, Symbol method_sig, **untyped) -> void
-    def join: -> void
-    def alive?: -> bool
+
+    def initialize: (*(Runner | Class) instances, ?use_yoshinon: bool) -> void
+
+    def add: (*(Runner | Class) instances) -> void
+
+    # NOTE: intentionally shadows Object#methods; returns [Method, meta] pairs
+    # sorted by priority (highest first)
+    def methods: () -> Array[runner_entry]
+
+    def run: (*Symbol tags, **untyped args) ?{ (?) -> untyped } -> void
+
+    def run_select: (selector selector, **untyped args) ?{ (?) -> untyped } -> void
+
+    def join: () -> void
+
+    def alive?: () -> bool
+
     alias running? alive?
 
     private
-    def run_internal: (Array[untyped] runners, Hash[Symbol, untyped] args) -> void
-    def run_method_internal: (Method method, Hash[Symbol, untyped] args) -> void
+
+    def run_internal: (Array[runner_entry] runners, Hash[Symbol, untyped] args) ?{ (?) -> untyped } -> void
+
+    # Maps the args hash onto the method's parameters by name. Positional
+    # optionals can only be filled left-to-right: once one is unspecified,
+    # passing any later :opt/:rest argument is an error (nonspecified_last_opt).
+    def run_method_internal: (Method method, Hash[Symbol, untyped] args) ?{ (?) -> untyped } -> untyped
   end
 end

data/sig/yuuki/error.rbs

@@ -1,6 +1,3 @@
-# TypeProf 0.21.2
-
-# Classes
 module Yuuki
   class Error < StandardError
   end

data/sig/yuuki/periodic_caller.rbs

@@ -0,0 +1,18 @@
+module Yuuki
+  class PeriodicCaller < Caller
+    @on_error: (^(StandardError) -> untyped)?
+
+    # true until the first iteration of #run has finished
+    attr_reader first_run: bool
+
+    # epoch seconds of the current iteration; nil before #run is called
+    attr_reader current_time: Float?
+
+    def initialize: (*(Runner | Class) instances, ?use_yoshinon: bool) -> void
+
+    def on_error: () { (StandardError) -> untyped } -> void
+
+    # loops forever; only returns by raising (when no on_error callback is set)
+    def start: (?Integer gmtoff, **untyped args) ?{ (?) -> untyped } -> bot
+  end
+end

data/sig/yuuki/runner.rbs

@@ -1,14 +1,44 @@
-# TypeProf 0.21.2
-
-# Classes
 module Yuuki
-  module Runner
-    @yuuki_methods: Hash[Symbol, Hash[Symbol, untyped]]
-
-    def add: (*Symbol methods) -> void
-    def delete: (*Symbol methods) -> void
-    def tag: (Symbol method, *Symbol tags) -> void
-    def thread: (*Symbol methods, ?enabled: bool) -> void
-    def priority: (*Symbol methods, Numeric value) -> void
+  class Runner
+    # a decorator entry: [:tag, Symbol] | [:priority, Integer] | [:thread, bool]
+    #                  | [:periodic, Numeric] | [:first_run, bool]
+    type decorator = [Symbol, untyped]
+
+    self.@accumulated_decorators: Array[decorator]
+
+    self.@yuuki_methods: Hash[Symbol, meta]
+
+    attr_reader yuuki: Caller?
+
+    # Decorator-style DSL (`on` / `priority` / `thread` / `periodic` / `first_run`)
+    # pushes entries here; the next instance-method definition consumes them
+    # (see method_added). Both this and yuuki_methods live in per-class ivars.
+    def self.accumulated_decorators: () -> Array[decorator]
+
+    def self.yuuki_methods: () -> Hash[Symbol, meta]
+
+    # yuuki_methods is a per-class ivar, so copy it on inheritance to make
+    # runner methods defined in a superclass visible from the subclass.
+    # NOTE: methods added to the superclass after the subclass is defined are
+    # not reflected.
+    def self.inherited: (singleton(Runner) subclass) -> void
+
+    def self.on: (Symbol tag) -> void
+
+    def self.priority: (?Integer priority) -> void
+
+    def self.thread: (?enabled: bool) -> void
+
+    def self.periodic: (Numeric interval) -> void
+
+    def self.first_run: (?enabled: bool) -> void
+
+    # Registers the method as a runner method when decorators are pending or the
+    # name is `on_<tag>` (which implies the tag <tag>). Note this hook fires for
+    # ANY instance-method definition, including attr_* and private helpers, so
+    # pending decorators are consumed by whatever method comes next.
+    def self.method_added: (Symbol method_name) -> void
+
+    def self.singleton_method_added: (Symbol _method_name) -> void
   end
 end

data/sig/yuuki/version.rbs

@@ -1,6 +1,3 @@
-# TypeProf 0.21.2
-
-# Classes
 module Yuuki
   VERSION: String
 end

data/sig/yuuki.rbs

@@ -0,0 +1,10 @@
+module Yuuki
+  # metadata registered for a runner method (see Runner.method_added)
+  type meta = {
+    ?tags: Array[Symbol],
+    ?priority: Integer,
+    ?thread: bool,
+    ?periodic: Numeric,
+    ?first_run: bool
+  }
+end

data/yuuki.gemspec

@@ -18,15 +18,18 @@ Gem::Specification.new do |spec|
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files         = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject {|f| f.match(%r{^(test|spec|features)/})}
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
   spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) {|f| File.basename(f)}
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.0'
 
   spec.add_dependency 'yoshinon'
   spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'minitest'
-  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'irb'
   spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'rbs'
+  spec.add_development_dependency 'rspec'
+  spec.add_development_dependency 'rubocop'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: yuuki
 version: !ruby/object:Gem::Version
-  version: 0.1.12
+  version: 1.0.2
 platform: ruby
 authors:
 - Ishotihadus
 bindir: exe
 cert_chain: []
-date: 2025-08-03 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yoshinon
@@ -38,7 +38,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: irb
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -52,7 +52,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -66,7 +66,35 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rbs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -86,8 +114,10 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".DS_Store"
+- ".github/workflows/ci.yml"
 - ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -97,12 +127,13 @@ files:
 - lib/yuuki.rb
 - lib/yuuki/caller.rb
 - lib/yuuki/error.rb
-- lib/yuuki/periodic.rb
+- lib/yuuki/periodic_caller.rb
 - lib/yuuki/runner.rb
 - lib/yuuki/version.rb
+- sig/yuuki.rbs
 - sig/yuuki/caller.rbs
 - sig/yuuki/error.rbs
-- sig/yuuki/periodic.rbs
+- sig/yuuki/periodic_caller.rbs
 - sig/yuuki/runner.rbs
 - sig/yuuki/version.rbs
 - yuuki.gemspec
@@ -117,14 +148,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A caller / runner framework for Ruby
 test_files: []

data/lib/yuuki/periodic.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-require 'English'
-require 'yuuki/caller'
-require 'yuuki/runner'
-require 'yoshinon'
-
-module Yuuki
-  module Runner
-    # sets interval to the method
-    # @param [Array<Symbol>] methods method names
-    # @param [Integer] interval
-    def periodic(*methods, interval)
-      @yuuki_methods ||= {}
-      methods.each do |method|
-        @yuuki_methods[method] ||= {}
-        @yuuki_methods[method][:periodic] = interval
-      end
-    end
-
-    # sets whether the method run at the first time
-    # @param [Array<Symbol>] methods method names
-    # @param [Boolean] enabled
-    def first_run(*methods, enabled: true)
-      @yuuki_methods ||= {}
-      methods.each do |method|
-        @yuuki_methods[method] ||= {}
-        @yuuki_methods[method][:first_run] = enabled
-      end
-    end
-  end
-end
-
-module Yuuki
-  # @attr_reader [Boolean] first_run
-  # @attr_reader [Float] current_time
-  class PeriodicCaller < Caller
-    attr_reader :first_run, :current_time
-
-    def initialize(*instances, use_yoshinon: true)
-      super
-      @first_run = true
-    end
-
-    # sets error callback
-    # @yield [error]
-    # @yieldparam [Exception] error
-    def on_error(&block)
-      @on_error = block
-    end
-
-    # runs the periodic caller
-    # @param [Numeric] gmtoff GMT Offset
-    # @param [Object] args arguments
-    def run(gmtoff = Time.now.gmtoff, **args, &)
-      last_time = nil
-      loop do
-        @current_time = Time.now.to_f
-        begin
-          select_proc = proc do |_method, meta|
-            next true if @first_run && meta[:first_run]
-            next false unless meta[:periodic]
-            next false unless last_time
-
-            c = @current_time + gmtoff
-            l = last_time + gmtoff
-            (l.div(meta[:periodic]) + 1) * meta[:periodic] <= c
-          end
-          run_select(select_proc, **args, &)
-        rescue StandardError
-          @on_error ? @on_error[$ERROR_INFO] : raise
-        end
-        @first_run = false
-
-        last_time = @current_time
-        ((@current_time + 1).floor - Time.now.to_f).tap { |e| sleep e if e > 0 }
-      end
-    end
-  end
-end

data/sig/yuuki/periodic.rbs

@@ -1,19 +0,0 @@
-# TypeProf 0.21.2
-
-# Classes
-module Yuuki
-  module Runner
-    def periodic: (Symbol method, Integer interval) -> void
-    def first_run: (Symbol method, ?enabled: bool) -> void
-  end
-
-  class PeriodicCaller < Caller
-    @on_error: Proc
-
-    attr_reader first_run: bool
-    attr_reader current_time: Float
-    def initialize: (*untyped instances) -> void
-    def on_error: {(Exception) -> void} -> void
-    def run: (?Integer gmtoff, **untyped) -> void
-  end
-end