tina4ruby 3.13.131 → 3.13.133

data/lib/tina4/frond.rb

@@ -2489,6 +2489,40 @@ module Tina4
       }
     end
 
+    # Collect the body tokens of a {% <open_tag> %}...{% <close_tag> %} block,
+    # honoring nested same-tag pairs. `start` is the index of the opening tag;
+    # returns [body_tokens, index_just_past_the_matching_close]. Shared by
+    # handle_cache / handle_spaceless / handle_autoescape, whose collection
+    # loops were identical apart from the tag names.
+    def collect_block_body(tokens, start, open_tag, close_tag)
+      body_tokens = []
+      i = start + 1
+      depth = 0
+      while i < tokens.length
+        if tokens[i][0] == BLOCK
+          tc, _, _ = strip_tag(tokens[i][1])
+          tag = tc.split[0] || ""
+          if tag == open_tag
+            depth += 1
+            body_tokens << tokens[i]
+          elsif tag == close_tag
+            if depth == 0
+              i += 1
+              break
+            end
+            depth -= 1
+            body_tokens << tokens[i]
+          else
+            body_tokens << tokens[i]
+          end
+        else
+          body_tokens << tokens[i]
+        end
+        i += 1
+      end
+      [body_tokens, i]
+    end
+
     # {% cache "key" ttl %}...{% endcache %}
     def handle_cache(tokens, start, context)
       content, _, _ = strip_tag(tokens[start][1])
@@ -2523,31 +2557,7 @@ module Tina4
         end
       end
 
-      body_tokens = []
-      i = start + 1
-      depth = 0
-      while i < tokens.length
-        if tokens[i][0] == BLOCK
-          tc, _, _ = strip_tag(tokens[i][1])
-          tag = tc.split[0] || ""
-          if tag == "cache"
-            depth += 1
-            body_tokens << tokens[i]
-          elsif tag == "endcache"
-            if depth == 0
-              i += 1
-              break
-            end
-            depth -= 1
-            body_tokens << tokens[i]
-          else
-            body_tokens << tokens[i]
-          end
-        else
-          body_tokens << tokens[i]
-        end
-        i += 1
-      end
+      body_tokens, i = collect_block_body(tokens, start, "cache", "endcache")
 
       rendered = render_tokens(body_tokens.dup, context)
       cap_cache(@fragment_cache, TEMPLATE_CACHE_MAX)
@@ -2773,31 +2783,7 @@ module Tina4
     end
 
     def handle_spaceless(tokens, start, context)
-      body_tokens = []
-      i = start + 1
-      depth = 0
-      while i < tokens.length
-        if tokens[i][0] == BLOCK
-          tc, _, _ = strip_tag(tokens[i][1])
-          tag = tc.split[0] || ""
-          if tag == "spaceless"
-            depth += 1
-            body_tokens << tokens[i]
-          elsif tag == "endspaceless"
-            if depth == 0
-              i += 1
-              break
-            end
-            depth -= 1
-            body_tokens << tokens[i]
-          else
-            body_tokens << tokens[i]
-          end
-        else
-          body_tokens << tokens[i]
-        end
-        i += 1
-      end
+      body_tokens, i = collect_block_body(tokens, start, "spaceless", "endspaceless")
 
       rendered = render_tokens(body_tokens.dup, context)
       rendered = rendered.gsub(SPACELESS_RE, "><")
@@ -2809,31 +2795,7 @@ module Tina4
       mode_match = content.match(AUTOESCAPE_RE)
       auto_escape_on = !(mode_match && mode_match[1] == "false")
 
-      body_tokens = []
-      i = start + 1
-      depth = 0
-      while i < tokens.length
-        if tokens[i][0] == BLOCK
-          tc, _, _ = strip_tag(tokens[i][1])
-          tag = tc.split[0] || ""
-          if tag == "autoescape"
-            depth += 1
-            body_tokens << tokens[i]
-          elsif tag == "endautoescape"
-            if depth == 0
-              i += 1
-              break
-            end
-            depth -= 1
-            body_tokens << tokens[i]
-          else
-            body_tokens << tokens[i]
-          end
-        else
-          body_tokens << tokens[i]
-        end
-        i += 1
-      end
+      body_tokens, i = collect_block_body(tokens, start, "autoescape", "endautoescape")
 
       if !auto_escape_on
         old_auto_escape = @auto_escape

data/lib/tina4/model_collection.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Tina4
+  # A list of ORM models that ALSO carries the total rows matching the query.
+  #
+  # ModelCollection is what the ORM read queries (+where+ / +select+ / +find+
+  # (filter form) / +all+ / +with_trashed+) return. It IS an Array -- iterate it,
+  # index it, slice it, map it, count it, serialise it to JSON -- so every
+  # existing caller keeps working unchanged. It adds one thing: the TOTAL number
+  # of rows matching the query's filter, independent of +limit+ / +offset+.
+  #
+  # The total is free. Every one of those methods already runs +db.fetch+, which
+  # computes a +SELECT COUNT(*)+ probe and hands it back on +DatabaseResult#count+;
+  # the ORM used to hydrate the page of models and throw that count away. This
+  # class carries it instead, so a caller with 20 models on the page can still
+  # learn there are 250 rows in the set -- with ZERO extra queries.
+  #
+  # Uniform across all four Tina4 frameworks (ADR-0064). Same concept, language-
+  # idiomatic accessor name:
+  #
+  #     Python / Ruby : get_total_records   to_paginate
+  #     PHP / Node    : getTotalRecords     toPaginate
+  #
+  # The accessor is a METHOD, not a +.total+ property, on purpose: +Array#count+
+  # already exists, so a +.count+ would shadow a built-in. +DatabaseResult+ keeps
+  # its +.count+ (it is not an Array); both expose the identical seven-key
+  # +to_paginate+ envelope (ADR-0043).
+  class ModelCollection < Array
+    # The SQL limit / offset that produced this page -- carried for to_paginate.
+    # The total is exposed only through get_total_records (the documented
+    # accessor), never a bare reader, so it reads the same in every framework.
+    attr_reader :limit, :offset
+
+    # @param items  [Array] the page of hydrated model instances
+    # @param total  [Integer] total rows matching the query's filter (ignores limit/offset)
+    # @param limit  [Integer] the SQL limit that produced this page (0 = none applied)
+    # @param offset [Integer] the SQL offset that produced this page
+    def initialize(items = [], total: 0, limit: 0, offset: 0)
+      super()
+      concat(items || [])
+      @total = total.to_i
+      @limit = limit.to_i
+      @offset = offset.to_i
+    end
+
+    # Total rows matching the query's filter, ignoring limit / offset.
+    #
+    # This is the whole point of the collection: the page slice you are iterating
+    # is capped by +limit+, but this number is the full count of matching rows --
+    # what a pager needs to render "page 3 of 13". Sourced from the fetch COUNT
+    # probe (+DatabaseResult#count+); no second query is fired.
+    def get_total_records
+      @total
+    end
+
+    # The canonical pagination envelope -- seven snake_case keys, identical to
+    # +DatabaseResult#to_paginate+ (ADR-0043) and to the other three frameworks'
+    # +toPaginate+:
+    #
+    #   records     the page's rows as model hashes (never re-sliced)
+    #   total       get_total_records -- the true total for the filter
+    #   page        floor(offset / per_page) + 1
+    #   per_page    the query's limit
+    #   total_pages ceil(total / per_page)
+    #   limit       the SQL limit actually applied
+    #   offset      the SQL offset actually applied
+    #
+    # +records+ are model hashes (via +#to_h+) so the JSON a client sees matches
+    # +DatabaseResult+ exactly -- the result is uniform whether the route returned
+    # a raw +db.fetch+ or an ORM query.
+    def to_paginate
+      per_page    = @limit > 0 ? @limit : size
+      page        = per_page > 0 ? (@offset / per_page) + 1 : 1
+      total       = @total
+      total_pages = per_page > 0 ? [1, (total.to_f / per_page).ceil].max : 1
+      {
+        records: map { |model| model.respond_to?(:to_h) ? model.to_h : model },
+        total: total,
+        page: page,
+        per_page: per_page,
+        total_pages: total_pages,
+        limit: per_page,
+        offset: @offset
+      }
+    end
+  end
+end

data/lib/tina4/orm.rb

@@ -250,16 +250,25 @@ module Tina4
 
       def find(id_or_filter = nil, filter = nil, **kwargs)
         include_list = kwargs.delete(:include)
+        # find(filter, limit:, offset:, order_by:) honours pagination on the
+        # filter/all form, matching the Python master (find -> select with
+        # limit/offset/order_by). Ruby used to swallow these into **kwargs and
+        # drop them, so find({...}, limit: 10) returned the default 100-row cap
+        # instead of 10 -- a parity divergence fixed alongside the ADR-0064 port.
+        # The PK branch (find_by_id) stays single and ignores them.
+        limit = kwargs.delete(:limit) || 100
+        offset = kwargs.delete(:offset)
+        order_by = kwargs.delete(:order_by)
 
         # find(id) — find by primary key
         # find(filter_hash) — find by criteria
         # find(name: "Alice") — keyword args as filter hash
         result = if id_or_filter.is_a?(Hash)
-          find_by_filter(id_or_filter)
+          find_by_filter(id_or_filter, limit: limit, offset: offset, order_by: order_by)
         elsif filter.is_a?(Hash)
-          find_by_filter(filter)
+          find_by_filter(filter, limit: limit, offset: offset, order_by: order_by)
         elsif !kwargs.empty?
-          find_by_filter(kwargs)
+          find_by_filter(kwargs, limit: limit, offset: offset, order_by: order_by)
         else
           find_by_id(id_or_filter)
         end
@@ -369,6 +378,23 @@ module Tina4
         end
       end
 
+      # Hydrate a fetch result into a ModelCollection (ADR-0064).
+      #
+      # The page of models AND the total for the query in one return: every read
+      # path already runs db.fetch, which computes a SELECT COUNT(*) probe and
+      # hands the TRUE total back on DatabaseResult#count. We carry it on the
+      # collection instead of throwing it away -- so get_total_records() /
+      # to_paginate() cost ZERO extra queries. limit/offset are what the fetch
+      # actually applied, so ModelCollection#to_paginate matches the same-query
+      # db.fetch(...).to_paginate exactly. The soft-delete filter lives in the SQL
+      # this fetch ran, so the probe already respects it.
+      def hydrate_collection(results, include: nil)
+        instances = results.map { |row| from_hash(row) }
+        eager_load(instances, include) if include
+        ModelCollection.new(instances, total: results.count,
+                            limit: results.limit, offset: results.offset)
+      end
+
       def where(conditions, params = [], limit: 100, offset: nil, order_by: nil, include: nil)
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
@@ -377,10 +403,7 @@ module Tina4
           sql += " WHERE #{conditions}"
         end
         sql += " ORDER BY #{order_by}" if order_by
-        results = db.fetch(sql, params, limit: limit, offset: offset)
-        instances = results.map { |row| from_hash(row) }
-        eager_load(instances, include) if include
-        instances
+        hydrate_collection(db.fetch(sql, params, limit: limit, offset: offset), include: include)
       end
 
       def all(limit: 100, offset: nil, order_by: nil, include: nil)
@@ -389,17 +412,11 @@ module Tina4
           sql += " WHERE #{soft_delete_field} IS NULL OR #{soft_delete_field} = 0"
         end
         sql += " ORDER BY #{order_by}" if order_by
-        results = db.fetch(sql, [], limit: limit, offset: offset)
-        instances = results.map { |row| from_hash(row) }
-        eager_load(instances, include) if include
-        instances
+        hydrate_collection(db.fetch(sql, [], limit: limit, offset: offset), include: include)
       end
 
       def select(sql, params = [], limit: 100, offset: nil, include: nil)
-        results = db.fetch(sql, params, limit: limit, offset: offset)
-        instances = results.map { |row| from_hash(row) }
-        eager_load(instances, include) if include
-        instances
+        hydrate_collection(db.fetch(sql, params, limit: limit, offset: offset), include: include)
       end
 
       def select_one(sql, params = [], include: nil)
@@ -536,8 +553,7 @@ module Tina4
 
       def with_trashed(conditions = "1=1", params = [], limit: 100, offset: 0)
         sql = "SELECT * FROM #{table_name} WHERE #{conditions}"
-        results = db.fetch(sql, params, limit: limit, offset: offset)
-        results.map { |row| from_hash(row) }
+        hydrate_collection(db.fetch(sql, params, limit: limit, offset: offset))
       end
 
       def create_table
@@ -821,14 +837,17 @@ module Tina4
         Tina4.bind_database(Tina4::Database.new(url, username: ENV.fetch("TINA4_DATABASE_USERNAME", ""), password: ENV.fetch("TINA4_DATABASE_PASSWORD", "")))
       end
 
-      def find_by_filter(filter)
+      def find_by_filter(filter, limit: 100, offset: nil, order_by: nil)
         where_parts = filter.keys.map { |k| "#{k} = ?" }
         sql = "SELECT * FROM #{table_name} WHERE #{where_parts.join(' AND ')}"
         if soft_delete
           sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
         end
-        results = db.fetch(sql, filter.values)
-        results.map { |row| from_hash(row) }
+        sql += " ORDER BY #{order_by}" if order_by
+        # find(filter) returns a ModelCollection (ADR-0064); find(pk) stays single
+        # (find_by_id -> select_one -> .first). find() applies its own eager_load
+        # to the returned collection, which is an Array so nothing there changes.
+        hydrate_collection(db.fetch(sql, filter.values, limit: limit, offset: offset))
       end
 
       # Render a column DEFAULT literal for create_table.