tina4ruby 3.10.90 → 3.10.91

data/lib/tina4/graphql.rb

@@ -68,23 +68,36 @@ module Tina4
       register_scalars
     end
 
-    def add_type(type)
-      @types[type.name] = type
+    # add_type(name, fields) — parity with PHP/Python/Node
+    # add_type(type_object)  — legacy Ruby form (type_object responds to .name)
+    def add_type(name_or_type, fields = nil)
+      if fields
+        # New form: add_type("User", { "id" => "ID", "name" => "String" })
+        @types[name_or_type] = fields
+      else
+        # Legacy form: add_type(GraphQLType.new(...))
+        @types[name_or_type.name] = name_or_type
+      end
     end
 
     def get_type(name)
       @types[name]
     end
 
-    # Register a query field
-    #   schema.add_query("user", type: "User", args: { id: { type: "ID!" } }) { |root, args, ctx| ... }
-    def add_query(name, type:, args: {}, description: nil, &resolve)
-      @queries[name] = { type: type, args: args, resolve: resolve, description: description }
+    # Register a query field.
+    # Cross-framework form: add_query(name, args, return_type, resolver)
+    # Block form also accepted: add_query(name, args, return_type) { |root, args, ctx| ... }
+    def add_query(name, args = {}, return_type = nil, resolver = nil, &block)
+      resolve = resolver || block
+      @queries[name] = { type: return_type, args: args, resolve: resolve }
     end
 
-    # Register a mutation field
-    def add_mutation(name, type:, args: {}, description: nil, &resolve)
-      @mutations[name] = { type: type, args: args, resolve: resolve, description: description }
+    # Register a mutation field.
+    # Cross-framework form: add_mutation(name, args, return_type, resolver)
+    # Block form also accepted: add_mutation(name, args, return_type) { |root, args, ctx| ... }
+    def add_mutation(name, args = {}, return_type = nil, resolver = nil, &block)
+      resolve = resolver || block
+      @mutations[name] = { type: return_type, args: args, resolve: resolve }
     end
 
     # ── ORM Auto-Schema ──────────────────────────────────────────────────
@@ -127,17 +140,13 @@ module Tina4
       # ── Queries ──
 
       # Single record: user(id: ID!): User
-      add_query(table_lower, type: type_name,
-                args: { pk_field => { type: "ID!" } },
-                description: "Fetch a single #{model_name} by #{pk_field}") do |_root, args, _ctx|
+      add_query(table_lower, { pk_field => { type: "ID!" } }, type_name) do |_root, args, _ctx|
         record = klass.find_by_id(args[pk_field])
         record&.to_hash
       end
 
       # List: users(limit: Int, offset: Int): [User]
-      add_query(plural, type: "[#{type_name}]",
-                args: { "limit" => { type: "Int" }, "offset" => { type: "Int" } },
-                description: "Fetch a list of #{model_name} records") do |_root, args, _ctx|
+      add_query(plural, { "limit" => { type: "Int" }, "offset" => { type: "Int" } }, "[#{type_name}]") do |_root, args, _ctx|
         limit  = args["limit"] || 100
         offset = args["offset"] || 0
         result = klass.all(limit: limit, offset: offset)
@@ -147,17 +156,13 @@ module Tina4
       # ── Mutations ──
 
       # Create
-      add_mutation("create#{model_name}", type: type_name,
-                   args: { "input" => { type: "#{type_name}Input!" } },
-                   description: "Create a new #{model_name}") do |_root, args, _ctx|
+      add_mutation("create#{model_name}", { "input" => { type: "#{type_name}Input!" } }, type_name) do |_root, args, _ctx|
         record = klass.create(args["input"] || {})
         record.respond_to?(:to_hash) ? record.to_hash : record
       end
 
       # Update
-      add_mutation("update#{model_name}", type: type_name,
-                   args: { pk_field => { type: "ID!" }, "input" => { type: "#{type_name}Input!" } },
-                   description: "Update an existing #{model_name}") do |_root, args, _ctx|
+      add_mutation("update#{model_name}", { pk_field => { type: "ID!" }, "input" => { type: "#{type_name}Input!" } }, type_name) do |_root, args, _ctx|
         record = klass.find_by_id(args[pk_field])
         return nil unless record
         (args["input"] || {}).each { |k, v| record.send(:"#{k}=", v) if record.respond_to?(:"#{k}=") }
@@ -166,9 +171,7 @@ module Tina4
       end
 
       # Delete
-      add_mutation("delete#{model_name}", type: "Boolean",
-                   args: { pk_field => { type: "ID!" } },
-                   description: "Delete a #{model_name} by #{pk_field}") do |_root, args, _ctx|
+      add_mutation("delete#{model_name}", { pk_field => { type: "ID!" } }, "Boolean") do |_root, args, _ctx|
         record = klass.find_by_id(args[pk_field])
         return false unless record
         record.delete

data/lib/tina4/health.rb

@@ -8,7 +8,7 @@ module Tina4
 
     class << self
       def register!
-        Tina4::Router.add_route("GET", "/health", method(:handle))
+        Tina4::Router.add("GET", "/health", method(:handle))
       end
 
       def handle(_request, response)

data/lib/tina4/job.rb

@@ -7,7 +7,7 @@ module Tina4
     attr_reader :id, :topic, :payload, :created_at, :attempts, :priority, :available_at
     attr_accessor :status
 
-    def initialize(topic:, payload:, id: nil, priority: 0, available_at: nil, attempts: 0)
+    def initialize(topic:, payload:, id: nil, priority: 0, available_at: nil, attempts: 0, queue: nil)
       @id = id || SecureRandom.uuid
       @topic = topic
       @payload = payload
@@ -16,15 +16,19 @@ module Tina4
       @priority = priority
       @available_at = available_at
       @status = :pending
+      @queue = queue
     end
 
     # Re-queue this message with incremented attempts.
-    # Delegates to the queue's backend via the queue reference.
-    def retry(queue:, delay_seconds: 0)
+    # Uses the stored queue reference (set at construction time).
+    def retry(delay_seconds: 0)
+      q = @queue
+      raise ArgumentError, "No queue reference — set at construction" unless q
+
       @attempts += 1
       @status = :pending
       @available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
-      queue.backend.enqueue(self)
+      q.backend.enqueue(self)
       self
     end
 

data/lib/tina4/localization.rb

@@ -64,6 +64,27 @@ module Tina4
         value
       end
 
+      def set_locale(locale)
+        self.current_locale = locale.to_s
+      end
+
+      def get_locale
+        current_locale
+      end
+
+      def translate(key, params: nil, locale: nil)
+        t(key, locale: locale, **(params || {}))
+      end
+
+      def load_translations(locale)
+        load(Dir.pwd) if translations.empty?
+        translations[locale.to_s] || {}
+      end
+
+      def add_translation(locale, key, value)
+        add(locale, key, value)
+      end
+
       def add(locale, key, value)
         translations[locale.to_s] ||= {}
         keys = key.to_s.split(".")

data/lib/tina4/middleware.rb

@@ -16,6 +16,11 @@ module Tina4
         @global_middleware ||= []
       end
 
+      # Parity alias matching Python/PHP/Node orchestrators.
+      def get_global
+        global_middleware.dup
+      end
+
       def before(pattern = nil, &block)
         before_handlers << { pattern: pattern, handler: block }
       end
@@ -37,9 +42,13 @@ module Tina4
       end
 
       # Run all "before" hooks: block-based handlers, then class-based before_* methods.
+      #
+      # Signature matches Python/PHP/Node orchestrators: pass the list of
+      # middleware classes explicitly.
+      #
       # Returns [request, response] on success, or false to halt the request.
-      def run_before(request, response)
-        # 1. Block-based before handlers (backward compat)
+      def run_before(middleware_classes, request, response)
+        # 1. Block-based before handlers (pattern-matched)
         before_handlers.each do |entry|
           next unless matches_pattern?(request.path, entry[:pattern])
           result = entry[:handler].call(request, response)
@@ -47,7 +56,7 @@ module Tina4
         end
 
         # 2. Class-based middleware: call every before_* method
-        global_middleware.each do |klass|
+        middleware_classes.each do |klass|
           before_methods_for(klass).each do |method_name|
             result = klass.send(method_name, request, response)
             # Support returning [request, response] (Python convention) or false to halt
@@ -65,15 +74,18 @@ module Tina4
       end
 
       # Run all "after" hooks: block-based handlers, then class-based after_* methods.
-      def run_after(request, response)
-        # 1. Block-based after handlers (backward compat)
+      #
+      # Signature matches Python/PHP/Node orchestrators: pass the list of
+      # middleware classes explicitly.
+      def run_after(middleware_classes, request, response)
+        # 1. Block-based after handlers (pattern-matched)
         after_handlers.each do |entry|
           next unless matches_pattern?(request.path, entry[:pattern])
           entry[:handler].call(request, response)
         end
 
         # 2. Class-based middleware: call every after_* method
-        global_middleware.each do |klass|
+        middleware_classes.each do |klass|
           after_methods_for(klass).each do |method_name|
             result = klass.send(method_name, request, response)
             if result.is_a?(Array) && result.length == 2

data/lib/tina4/migration.rb

@@ -61,30 +61,75 @@ module Tina4
     end
 
     # Create a new migration file
-    def create(name)
+    #
+    # kind="ruby"   — creates {timestamp}_{description}.rb with MigrationBase subclass (default)
+    # kind="sql"    — creates {timestamp}_{description}.sql + .down.sql
+    # kind="python" — alias for "ruby" (class-based scaffold for cross-framework parity)
+    def create(description, kind = "sql")
       FileUtils.mkdir_p(@migrations_dir)
       timestamp = Time.now.strftime("%Y%m%d%H%M%S")
-      filename = "#{timestamp}_#{name.gsub(/\s+/, '_')}.rb"
-      filepath = File.join(@migrations_dir, filename)
+      created_at = Time.now.utc.strftime("%Y-%m-%d %H:%M:%S UTC")
+      safe_name = description.gsub(/[^a-z0-9]+/i, "_").downcase.gsub(/^_|_$/, "")
+
+      if kind == "ruby" || kind == "python"
+        filename = "#{timestamp}_#{safe_name}.rb"
+        filepath = File.join(@migrations_dir, filename)
+
+        File.write(filepath, <<~RUBY)
+          # frozen_string_literal: true
+          # Migration: #{description}
+          # Created: #{created_at}
+
+          class #{classify(description)} < Tina4::MigrationBase
+            def up(db = nil)
+              # db.execute("CREATE TABLE ...")
+            end
+
+            def down(db = nil)
+              # db.execute("DROP TABLE IF EXISTS ...")
+            end
+          end
+        RUBY
 
-      File.write(filepath, <<~RUBY)
-        # frozen_string_literal: true
-        # Migration: #{name}
-        # Created: #{Time.now}
+        Tina4::Log.info("Created migration: #{filename}")
+        return filepath
+      end
 
-        class #{classify(name)} < Tina4::MigrationBase
-          def up(db)
-            # db.exec("CREATE TABLE ...")
-          end
+      # Default: SQL
+      up_filename = "#{timestamp}_#{safe_name}.sql"
+      down_filename = "#{timestamp}_#{safe_name}.down.sql"
+      up_path = File.join(@migrations_dir, up_filename)
+      down_path = File.join(@migrations_dir, down_filename)
 
-          def down(db)
-            # db.exec("DROP TABLE IF EXISTS ...")
-          end
-        end
-      RUBY
+      File.write(up_path, "-- Migration: #{description}\n-- Created: #{created_at}\n\n")
+      File.write(down_path, "-- Rollback: #{description}\n-- Created: #{created_at}\n\n")
 
-      Tina4::Log.info("Created migration: #{filename}")
-      filepath
+      Tina4::Log.info("Created migration: #{up_filename}")
+      up_path
+    end
+
+    # Insert a record into the migration tracking table.
+    #
+    # @param name  [String]  Migration filename (e.g. "20240101000000_create_users.sql")
+    # @param batch [Integer] Batch number this migration belongs to
+    # @param passed [Integer] 1 if successful (default), 0 if failed
+    def record_migration(name, batch, passed: 1)
+      _record_migration(name, batch, passed: passed)
+    end
+
+    # Delete a migration record from the tracking table by filename.
+    #
+    # @param name [String] Migration filename to remove
+    def remove_migration_record(name)
+      _remove_migration_record(name)
+    end
+
+    # Create a migration file — static helper for parity with Python/Node.
+    # @param description [String] Human-readable migration name
+    # @param migrations_dir [String] Directory for migration files (default: 'migrations')
+    # @param kind [String] File kind: 'sql' or 'ruby' (default: 'sql')
+    def self.create_migration(description, migrations_dir: "migrations", kind: "sql")
+      new(nil, migrations_dir: migrations_dir).create(description, kind)
     end
 
     # Get list of applied migration records (public alias for completed_migrations)
@@ -92,6 +137,11 @@ module Tina4
       completed_migrations
     end
 
+    # Alias for get_applied — parity with PHP/Node
+    def get_applied_migrations
+      get_applied
+    end
+
     # Get list of pending migration filenames (public alias for pending_migrations)
     def get_pending
       pending_migrations.map { |f| File.basename(f) }
@@ -119,6 +169,7 @@ module Tina4
     end
 
     def ensure_tracking_table
+      return unless @db
       unless @db.table_exists?(TRACKING_TABLE)
         if firebird?
           # Firebird: no AUTOINCREMENT, no TEXT type, use generator for IDs
@@ -201,11 +252,11 @@ module Tina4
         else
           execute_sql_file(file)
         end
-        record_migration(name, batch, passed: 1)
+        _record_migration(name, batch, passed: 1)
         { name: name, status: "success" }
       rescue => e
         Tina4::Log.error("Migration failed: #{name} - #{e.message}")
-        record_migration(name, batch, passed: 0)
+        _record_migration(name, batch, passed: 0)
         { name: name, status: "failed", error: e.message }
       end
     end
@@ -224,7 +275,7 @@ module Tina4
             Tina4::Log.warning("No rollback file for: #{name}")
           end
         end
-        remove_migration_record(name)
+        _remove_migration_record(name)
         { name: name, status: "rolled_back" }
       rescue => e
         Tina4::Log.error("Rollback failed: #{name} - #{e.message}")
@@ -345,7 +396,7 @@ module Tina4
       end
     end
 
-    def record_migration(name, batch, passed: 1)
+    def _record_migration(name, batch, passed: 1)
       # Extract description from filename (strip numeric prefix and extension)
       stem = File.basename(name, File.extname(name))
       desc = stem.sub(/\A\d+_/, "").tr("_", " ")
@@ -367,7 +418,7 @@ module Tina4
       end
     end
 
-    def remove_migration_record(name)
+    def _remove_migration_record(name)
       @db.delete(TRACKING_TABLE, { migration_name: name })
     end
 
@@ -389,11 +440,11 @@ module Tina4
 
   # Base class for Ruby migrations
   class MigrationBase
-    def up(db)
+    def up(db = nil)
       raise NotImplementedError, "Implement #up in your migration"
     end
 
-    def down(db)
+    def down(db = nil)
       raise NotImplementedError, "Implement #down in your migration"
     end
   end

data/lib/tina4/orm.rb

@@ -243,14 +243,14 @@ module Tina4
         end
       end
 
-      def where(conditions, params = [], include: nil) # -> list[Self]
+      def where(conditions, params = [], limit: 20, offset: 0, include: nil) # -> list[Self]
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
           sql += " WHERE (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0) AND (#{conditions})"
         else
           sql += " WHERE #{conditions}"
         end
-        results = db.fetch(sql, params)
+        results = db.fetch(sql, params, limit: limit, offset: offset)
         instances = results.map { |row| from_hash(row) }
         eager_load(instances, include) if include
         instances
@@ -394,13 +394,32 @@ module Tina4
       end
 
       # Find a single record by primary key. Returns instance or nil.
-      def find_by_id(id) # -> Self | nil
+      def find_by_id(id, include: nil) # -> Self | nil
         pk = primary_key_field || :id
         sql = "SELECT * FROM #{table_name} WHERE #{pk} = ?"
         if soft_delete
           sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
         end
-        select_one(sql, [id])
+        select_one(sql, [id], include: include)
+      end
+
+      # Clear the relationship cache on all loaded instances (class-level helper).
+      # Useful after bulk operations when you want to force relationship re-loads.
+      def clear_rel_cache # -> nil
+        @_rel_cache = {}
+        nil
+      end
+
+      # Return the database connection used by this model.
+      def get_db # -> Database
+        db
+      end
+
+      # Map a Ruby property name to its database column name using field_mapping.
+      # Returns the column name as a symbol.
+      def get_db_column(property) # -> Symbol
+        col = field_mapping[property.to_s] || property
+        col.to_sym
       end
 
       private

data/lib/tina4/queue.rb

@@ -30,7 +30,7 @@ module Tina4
     # delay_seconds: delay before the message becomes available (default 0).
     def push(payload, priority: 0, delay_seconds: 0)
       available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
-      message = Job.new(topic: @topic, payload: payload, priority: priority, available_at: available_at)
+      message = Job.new(topic: @topic, payload: payload, priority: priority, available_at: available_at, queue: self)
       @backend.enqueue(message)
       message
     end
@@ -40,6 +40,21 @@ module Tina4
       @backend.dequeue(@topic)
     end
 
+    # Pop up to count jobs at once. Returns a partial batch if fewer available.
+    def pop_batch(count)
+      if @backend.respond_to?(:dequeue_batch)
+        @backend.dequeue_batch(@topic, count)
+      else
+        jobs = []
+        count.times do
+          job = @backend.dequeue(@topic)
+          break if job.nil?
+          jobs << job
+        end
+        jobs
+      end
+    end
+
     # Clear all pending jobs from this queue's topic. Returns count removed.
     def clear # -> int
       return 0 unless @backend.respond_to?(:clear)
@@ -52,34 +67,37 @@ module Tina4
       @backend.failed(@topic, max_retries: @max_retries)
     end
 
-    # Retry failed jobs on this queue's topic. Returns true if re-queued.
-    def retry(delay_seconds = 0) # -> bool
+    # Retry a specific failed job by ID, or all dead-letter jobs if no id given.
+    # Returns true if re-queued.
+    def retry(job_id = nil, delay_seconds: 0) # -> bool
       return false unless @backend.respond_to?(:retry_job)
-      @backend.retry_job(@topic, delay_seconds: delay_seconds)
+      @backend.retry_job(@topic, job_id: job_id, delay_seconds: delay_seconds)
     end
 
     # Get dead letter jobs — messages that exceeded max retries.
-    def dead_letters # -> list[dict]
+    # Pass max_retries to override the queue's default.
+    def dead_letters(max_retries: nil) # -> list[dict]
       return [] unless @backend.respond_to?(:dead_letters)
-      @backend.dead_letters(@topic, max_retries: @max_retries)
+      @backend.dead_letters(@topic, max_retries: max_retries || @max_retries)
     end
 
     # Delete messages by status (completed, failed, dead).
-    def purge(status) # -> int
+    def purge(status, max_retries: nil) # -> int
       return 0 unless @backend.respond_to?(:purge)
       @backend.purge(@topic, status)
     end
 
     # Re-queue failed messages (under max_retries) back to pending.
     # Returns the number of jobs re-queued.
-    def retry_failed # -> int
+    def retry_failed(max_retries: nil) # -> int
       return 0 unless @backend.respond_to?(:retry_failed)
-      @backend.retry_failed(@topic, max_retries: @max_retries)
+      @backend.retry_failed(@topic, max_retries: max_retries || @max_retries)
     end
 
     # Produce a message onto a topic. Convenience wrapper around push().
-    def produce(topic, payload, priority = 0)
-      message = Job.new(topic: topic, payload: payload, priority: priority)
+    def produce(topic, payload, priority: 0, delay_seconds: 0)
+      available_at = delay_seconds > 0 ? Time.now + delay_seconds : nil
+      message = Job.new(topic: topic, payload: payload, priority: priority, available_at: available_at, queue: self)
       @backend.enqueue(message)
       message
     end
@@ -108,7 +126,7 @@ module Tina4
     #   queue.consume("emails", poll_interval: 5) { |job| process(job) }
     #   queue.consume("emails", id: "abc-123") { |job| process(job) }
     #
-    def consume(topic = nil, id: nil, poll_interval: 1.0, iterations: 0, &block)
+    def consume(topic = nil, id: nil, poll_interval: 1.0, iterations: 0, batch_size: 1, &block)
       topic ||= @topic
 
       if id
@@ -125,16 +143,30 @@ module Tina4
       # iterations>0    → stop after consuming N jobs
       if block_given?
         consumed = 0
-        loop do
-          job = @backend.dequeue(topic)
-          if job.nil?
-            break if poll_interval <= 0
-            sleep(poll_interval)
-            next
+        if batch_size > 1
+          loop do
+            jobs = pop_batch(batch_size)
+            if jobs.empty?
+              break if poll_interval <= 0
+              sleep(poll_interval)
+              next
+            end
+            yield jobs
+            consumed += jobs.length
+            break if iterations > 0 && consumed >= iterations
+          end
+        else
+          loop do
+            job = @backend.dequeue(topic)
+            if job.nil?
+              break if poll_interval <= 0
+              sleep(poll_interval)
+              next
+            end
+            yield job
+            consumed += 1
+            break if iterations > 0 && consumed >= iterations
           end
-          yield job
-          consumed += 1
-          break if iterations > 0 && consumed >= iterations
         end
       else
         Enumerator.new do |yielder|
@@ -178,6 +210,49 @@ module Tina4
       end
     end
 
+    # Get the topic name this queue was constructed with.
+    def get_topic
+      @topic
+    end
+
+    # Consume all available jobs and pass each to handler, then stop.
+    #
+    # Simpler alternative to consume() for drain-and-exit use cases.
+    #
+    #   queue.process { |job| handle(job); job.complete }
+    #   queue.process(topic: "emails", max_jobs: 10) { |job| ... }
+    #
+    def process(topic: nil, max_jobs: nil, batch_size: 1, &handler)
+      raise ArgumentError, "block required" unless block_given?
+      drain_topic = topic || @topic
+      processed = 0
+      loop do
+        break if max_jobs && processed >= max_jobs
+        if batch_size > 1
+          remaining = max_jobs ? [batch_size, max_jobs - processed].min : batch_size
+          jobs = @backend.respond_to?(:dequeue_batch) ?
+                   @backend.dequeue_batch(drain_topic, remaining) :
+                   (1..remaining).map { @backend.dequeue(drain_topic) }.compact
+          break if jobs.empty?
+          begin
+            handler.call(jobs)
+          rescue => e
+            jobs.each { |job| job.fail(e.message) }
+          end
+          processed += jobs.length
+        else
+          job = @backend.dequeue(drain_topic)
+          break if job.nil?
+          begin
+            handler.call(job)
+          rescue => e
+            job.fail(e.message)
+          end
+          processed += 1
+        end
+      end
+    end
+
     # Get the underlying backend instance.
     def backend
       @backend