smriti 0.5.0

data/app/jobs/smriti/refresh_view_job.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+##
+# Top-level namespace for the smriti engine.
+module Smriti
+  ##
+  # ActiveJob that handles `REFRESH MATERIALIZED VIEW` for a given
+  # {Smriti::MatViewDefinition}.
+  #
+  # The job mirrors {Smriti::CreateViewJob}'s lifecycle:
+  # it measures duration and persists state in {Smriti::MatViewRun}.
+  #
+  # The actual refresh implementation is delegated based on
+  # `definition.refresh_strategy`:
+  #
+  # - `"concurrent"` → {Smriti::Services::ConcurrentRefresh}
+  # - `"swap"`       → {Smriti::Services::SwapRefresh}
+  # - otherwise      → {Smriti::Services::RegularRefresh}
+  #
+  # Row count reporting can be controlled via `row_count_strategy`:
+  # - `:estimated` (default) - fast, approximate via reltuples
+  # - `:exact` - accurate `COUNT(*)`
+  # - `nil` - skip counting
+  #
+  # @see Smriti::MatViewDefinition
+  # @see Smriti::MatViewRun
+  # @see Smriti::Services::RegularRefresh
+  # @see Smriti::Services::ConcurrentRefresh
+  # @see Smriti::Services::SwapRefresh
+  #
+  # @example Enqueue a refresh with exact row count
+  #   Smriti::RefreshViewJob.perform_later(definition.id, :exact)
+  #
+  # @example Enqueue using keyword-hash form
+  #   Smriti::RefreshViewJob.perform_later(definition.id, row_count_strategy: :estimated)
+  #
+  class RefreshViewJob < ApplicationJob
+    ##
+    # Queue name for the job.
+    #
+    # Uses `Smriti.configuration.job_queue` when configured, otherwise `:default`.
+    #
+    queue_as { Smriti.configuration.job_queue || :default }
+
+    ##
+    # Perform the refresh job for the given materialised view definition.
+    #
+    # @api public
+    #
+    # @param mat_view_definition_id [Integer, String] ID of {Smriti::MatViewDefinition}.
+    # @param row_count_strategy_arg [:Symbol, String] One of: `:estimated`, `:exact`, `:none` or `nil`.
+    #
+    # @return [Hash] Serialized {Smriti::ServiceResponse#to_h}:
+    #   - `:status` [Symbol]
+    #   - `:error` [String, nil]
+    #   - `:duration_ms` [Integer]
+    #   - `:meta` [Hash]
+    #
+    # @raise [StandardError] Re-raised on unexpected failure after marking the run failed.
+    #
+    def perform(mat_view_definition_id, row_count_strategy_arg = nil)
+      definition = Smriti::MatViewDefinition.find(mat_view_definition_id)
+      record_run(definition, :refresh) do
+        service(definition).new(definition, row_count_strategy: normalize_strategy(row_count_strategy_arg)).call
+      end
+    end
+
+    private
+
+    ##
+    # Select the refresh service class based on the definition's strategy.
+    #
+    # @api private
+    #
+    # @param definition [Smriti::MatViewDefinition]
+    # @return [Class] One of the refresh service classes.
+    #
+    def service(definition)
+      case definition.refresh_strategy
+      when 'concurrent'
+        Smriti::Services::ConcurrentRefresh
+      when 'swap'
+        Smriti::Services::SwapRefresh
+      else
+        Smriti::Services::RegularRefresh
+      end
+    end
+  end
+end

data/app/models/concerns/smriti_i18n.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+#
+# SmritiI18n
+# ------------
+# Concern that adds convenient **class-level** helpers for model I18n:
+# - Humanized attribute names
+# - Humanized enum values
+# - Select-friendly enum option arrays
+# - Placeholders and hints for forms
+#
+# These helpers rely on Rails’ standard i18n model keys using the model’s
+# `model_name.i18n_key` (e.g. `Smriti::MatViewDefinition` → `smriti/mat_view_definition`).
+#
+# ## Expected i18n structure (examples)
+#
+# ```yml
+# en-US:
+#   activerecord:
+#     attributes:
+#       smriti/mat_view_definition:
+#         name: "View name"
+#         sql: "SQL"
+#     enums:
+#       smriti/mat_view_definition:
+#         refresh_strategy:
+#           regular: "Regular"
+#           concurrent: "Concurrent"
+#           swap: "Swap"
+#     placeholders:
+#       smriti/mat_view_definition:
+#         name: "e.g. monthly_sales_mv"
+#     hints:
+#       smriti/mat_view_definition:
+#         sql: "Use a SELECT statement; no trailing semicolon."
+# ```
+#
+# ## Usage
+# ```ruby
+# Smriti::MatViewDefinition.human_name(:name)                # => "View name"
+# Smriti::MatViewDefinition.human_enum_name(:refresh_strategy, :regular)  # => "Regular"
+# Smriti::MatViewDefinition.human_enum_options(:refresh_strategy)
+# # => [["Regular","regular"], ["Concurrent","concurrent"], ["Swap","swap"]]
+# Smriti::MatViewDefinition.placeholder_for(:name)           # => "e.g. monthly_sales_mv"
+# Smriti::MatViewDefinition.hint_for(:sql)                   # => "Use a SELECT statement..."
+# ```
+#
+# @note Methods are added as **class methods** to the including model.
+#
+# @!method self.human_name(attribute)
+#   Humanized (translated) attribute label for this model.
+#   Falls back to `attribute.to_s.humanize` when missing.
+#   @param attribute [Symbol, String]
+#   @return [String]
+#
+# @!method self.human_enum_name(enum_name, enum_value)
+#   Humanized (translated) enum value label.
+#   Falls back to `enum_value.to_s.humanize` when missing.
+#   @param enum_name [Symbol, String] the enum definition name
+#   @param enum_value [Symbol, String, Integer] the value/key of the enum
+#   @return [String]
+#
+# @!method self.human_enum_options(enum_name)
+#   Options array suitable for Rails `options_for_select`.
+#   @param enum_name [Symbol, String]
+#   @return [Array<Array(String, String)>] each item is `[label, value]`
+#
+# @!method self.placeholder_for(attribute)
+#   Form placeholder for the given attribute.
+#   Returns empty string if not defined.
+#   @param attribute [Symbol, String]
+#   @return [String]
+#
+# @!method self.hint_for(attribute)
+#   Form hint/help text for the given attribute.
+#   Returns empty string if not defined.
+#   @param attribute [Symbol, String]
+#   @return [String]
+#
+module SmritiI18n
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # @return [String]
+    def human_name(attribute)
+      I18n.t(
+        "activerecord.attributes.#{model_name.i18n_key}.#{attribute}",
+        default: attribute.to_s.humanize
+      )
+    end
+
+    # human_enum_name(:refresh_strategy, :regular) → "Regular"
+    #
+    # @param enum_name [Symbol, String]
+    # @param enum_value [Symbol, String, Integer]
+    # @return [String]
+    def human_enum_name(enum_name, enum_value)
+      key = enum_value.to_s
+      I18n.t(
+        "activerecord.enums.#{model_name.i18n_key}.#{enum_name}.#{key}",
+        default: key.humanize
+      )
+    end
+
+    # human_enum_options(:refresh_strategy)
+    # → [["Regular","regular"], ["Concurrent","concurrent"], ["Swap","swap"]]
+    #
+    # @param enum_name [Symbol, String]
+    # @return [Array<Array(String, String)>]
+    def human_enum_options(enum_name)
+      public_send(enum_name.to_s.pluralize).keys.map do |val|
+        [human_enum_name(enum_name, val), val]
+      end
+    end
+
+    # @param attribute [Symbol, String]
+    # @return [String]
+    def placeholder_for(attribute)
+      I18n.t(
+        "activerecord.placeholders.#{model_name.i18n_key}.#{attribute}",
+        default: ''
+      )
+    end
+
+    # @param attribute [Symbol, String]
+    # @return [String]
+    def hint_for(attribute)
+      I18n.t(
+        "activerecord.hints.#{model_name.i18n_key}.#{attribute}",
+        default: ''
+      )
+    end
+  end
+end

data/app/models/concerns/smriti_paginate.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# SmritiPaginate
+# ----------------
+# Concern that adds a class-level `paginate` scope to models, enabling
+# simple pagination based on `page` and `per_page` parameters.
+#
+# ## Usage
+# ```ruby
+# Smriti::MatViewDefinition.paginate(total: 100, page: 2, per_page: 20)
+# # => Returns records 21-40 of the total 100
+# ```
+#
+# @note Methods are added as **class methods** to the including model.
+#
+# @!method self.paginate(total:, page:, per_page:)
+#   Paginates the relation based on total records, current page, and per-page count.
+#   @param total [Integer] Total number of records in the full result set.
+#   @param page [Integer] Current page number (1-based).
+#   @param per_page [Integer] Number of records per page.
+#   @return [ActiveRecord::Relation] Paginated relation.
+#
+module SmritiPaginate
+  extend ActiveSupport::Concern
+
+  included do
+    # Adds a scope for paginating records.
+    # Usage: Model.paginate(total: total_count, page: current_page, per_page: per_page_count)
+    #
+    # Calculates the correct offset and limit based on the provided parameters.
+    # Ensures page and per_page are within valid ranges.
+    # Defaults per_page to 20 if an invalid value is provided.
+    # Returns an ActiveRecord::Relation with the appropriate records.
+    #
+    # @param total [Integer] Total number of records in the full result set.
+    # @param page [Integer] Current page number (1-based).
+    # @param per_page [Integer] Number of records per page.
+    #
+    # @return [ActiveRecord::Relation] Paginated relation.
+    scope :paginate, lambda { |total:, page:, per_page:|
+      page = page.to_i
+      per_page  = per_page.to_i
+      per_page  = 20 if per_page <= 0
+
+      total_pages = (total.to_f / per_page).ceil
+      page = 1 if page < 1 || (page > total_pages && total_pages.positive?)
+
+      offset((page - 1) * per_page).limit(per_page)
+    }
+  end
+  class_methods do
+    # Calculates the total number of pages based on total records and per-page count.
+    #
+    # @param total [Integer] Total number of records.
+    # @param per_page [Integer] Number of records per page.
+    # @return [Integer] Total number of pages.
+    #
+    # @example
+    #   total_pages(total: 100, per_page: 20) #=> 5
+    def total_pages(total:, per_page:)
+      per_page = per_page.to_i
+      (total.to_f / per_page).ceil
+    end
+  end
+end

data/app/models/concerns/smriti_query_helper.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+# SmritiQueryHelper
+# ----------------
+#
+module SmritiQueryHelper
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def ordered_by_enum(enum_values:, enum_name:, direction:)
+      enum_pairs = enum_values.map do |name, int|
+        [int, human_enum_name(enum_name, name)]
+      end
+      enum_pairs.sort_by! { |(_int, label)| label.to_s.downcase }
+
+      when_sql = enum_pairs.each_with_index
+                           .map { |(enum_int, _label), search_enum_int| "WHEN #{enum_int} THEN #{search_enum_int}" }
+                           .join(' ')
+
+      order(Arel.sql("CASE #{table_name}.#{enum_name} #{when_sql} ELSE #{enum_pairs.size} END #{direction.to_s.downcase}"))
+    end
+
+    def search_by_enum(enum_values:, enum_name:, term:)
+      enum_pairs = enum_values.map do |name, int|
+        [int, human_enum_name(enum_name, name)]
+      end
+      selected = enum_pairs.select { |(_int, label)| label.to_s.downcase.include?(term.downcase) }.map { |(int, _label)| int }
+      where(enum_name => selected)
+    end
+  end
+end

data/app/models/smriti/application_record.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+##
+# Top-level namespace for the smriti engine.
+module Smriti
+  ##
+  # Base model class for all ActiveRecord models in the smriti engine.
+  #
+  # Inherits from {ActiveRecord::Base} and marks itself as an abstract class.
+  # Other engine models should subclass this rather than inheriting directly
+  # from {ActiveRecord::Base}, so that shared behavior or configuration can be
+  # applied in one place.
+  #
+  # @abstract
+  #
+  # @example Define a new model under smriti
+  #   class Smriti::MatViewDefinition < Smriti::ApplicationRecord
+  #     self.table_name = "mat_view_definitions"
+  #   end
+  #
+  class ApplicationRecord < ActiveRecord::Base
+    ##
+    # Marks this record class as abstract, so it won’t be persisted to a table.
+    #
+    # @return [void]
+    #
+    self.abstract_class = true
+
+    # Include shared concerns for i18n, queries, and pagination.
+    include SmritiI18n
+    include SmritiPaginate
+    include SmritiQueryHelper
+  end
+end

data/app/models/smriti/mat_view_definition.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+##
+# Top-level namespace for the smriti engine.
+module Smriti
+  ##
+  # Represents a **materialised view definition** managed by the engine.
+  #
+  # A definition stores the canonical name and SQL for a materialised view and
+  # drives lifecycle operations (create, refresh, delete) via background jobs
+  # and services. It also tracks operational history through associated
+  # run models.
+  #
+  # Validations ensure a sane PostgreSQL identifier for `name` and that `sql`
+  # begins with `SELECT` (case-insensitive).
+  #
+  # @see Smriti::CreateViewJob
+  # @see Smriti::RefreshViewJob
+  # @see Smriti::DeleteViewJob
+  # @see Smriti::Services::CreateView
+  # @see Smriti::Services::RegularRefresh
+  # @see Smriti::Services::ConcurrentRefresh
+  # @see Smriti::Services::SwapRefresh
+  #
+  # @example Creating a definition
+  #   defn = Smriti::MatViewDefinition.create!(
+  #     name: "mv_user_accounts",
+  #     sql:  "SELECT users.id, accounts.id AS account_id FROM users JOIN accounts ON ..."
+  #   )
+  #
+  # @example Enqueue a refresh
+  #   Smriti::RefreshViewJob.perform_later(defn.id, :estimated)
+  #
+  class MatViewDefinition < ApplicationRecord
+    ##
+    # Underlying database table name.
+    self.table_name = 'mat_view_definitions'
+
+    # ────────────────────────────────────────────────────────────────
+    # Associations
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # Historical create runs linked to this definition.
+    #
+    # @return [ActiveRecord::Relation<Smriti::MatViewRun>]
+    #
+    has_many :mat_view_runs,
+             dependent: :destroy,
+             class_name: 'Smriti::MatViewRun'
+
+    # ────────────────────────────────────────────────────────────────
+    # Validations
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # @!attribute name
+    # validates :name that must be present, unique, and a valid identifier.
+    validates :name,
+              presence: true,
+              uniqueness: true,
+              format: { with: /\A[a-zA-Z_][a-zA-Z0-9_]*\z/ }
+
+    ##
+    # @!attribute sql
+    # validates :sql that must be present and begin with SELECT.
+    validates :sql,
+              presence: true,
+              format: { with: /\A\s*SELECT/i, message: :invalid }
+
+    ##
+    # @!attribute unique_index_columns
+    # validates :unique_index_columns to be non-empty when using `refresh_strategy=concurrent`.
+    validates :unique_index_columns,
+              length: { minimum: 1, message: :at_least_one },
+              if: -> { refresh_strategy == 'concurrent' }
+
+    # ────────────────────────────────────────────────────────────────
+    # Enums / configuration
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # Refresh strategy that governs which service is used by {RefreshViewJob}.
+    #
+    # - `:regular`    → {Smriti::Services::RegularRefresh}
+    # - `:concurrent` → {Smriti::Services::ConcurrentRefresh}
+    # - `:swap`       → {Smriti::Services::SwapRefresh}
+    #
+    # @!attribute [rw] refresh_strategy
+    #   @return [String] one of `"regular"`, `"concurrent"`, `"swap"`
+    #
+    enum :refresh_strategy, { regular: 0, concurrent: 1, swap: 2 }
+
+    # ────────────────────────────────────────────────────────────────
+    # Scopes for ordering, searching, filtering
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # Scope ordered by name
+    # Orders by the `name` attribute.
+    #
+    # @param dir [Symbol, String] `:asc` or `:desc`
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :ordered_by_name, ->(dir) { order("name #{dir.to_s.upcase}") }
+
+    ##
+    # Scope ordered by refresh_strategy
+    # Orders by the `refresh_strategy` attribute, using humanized enum labels.
+    #
+    # @param dir [Symbol, String] `:asc` or `:desc`
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :ordered_by_refresh_strategy, ->(dir) { ordered_by_enum(enum_values: refresh_strategies, enum_name: :refresh_strategy, direction: dir) }
+
+    ## Scope ordered by schedule_cron
+    # Orders by the `schedule_cron` attribute, NULLs last.
+    #
+    # @param dir [Symbol, String] `:asc` or `:desc`
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :ordered_by_schedule_cron, ->(dir) { order("schedule_cron #{dir.to_s.upcase} NULLS LAST") }
+
+    ## Scope ordered by last_run_at
+    # Orders by the timestamp of the most recent associated run's `started_at`, NULLs last.
+    #
+    # @param dir [Symbol, String] `:asc` or `:desc`
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :ordered_by_last_run_at, lambda { |dir|
+      dir = dir.to_s.casecmp('asc').zero? ? 'ASC' : 'DESC'
+
+      order(Arel.sql(<<~SQL.squish))
+        (
+          SELECT MAX(r.created_at)
+          FROM mat_view_runs r
+          WHERE r.mat_view_definition_id = mat_view_definitions.id
+        ) #{dir} NULLS LAST
+      SQL
+    }
+
+    ## Scope search by name
+    # Searches the `name` attribute using ILIKE.
+    #
+    # @param term [String] search term
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :search_by_name, ->(term) { where('name ILIKE ?', "%#{term}%") }
+
+    ## Scope search by refresh_strategy
+    # Searches the `refresh_strategy` attribute using humanized enum labels.
+    #
+    # @param term [String] search term
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :search_by_refresh_strategy, ->(term) { search_by_enum(enum_values: refresh_strategies, enum_name: :refresh_strategy, term: term) }
+
+    ## Scope search by schedule_cron
+    # Searches the `schedule_cron` attribute using ILIKE.
+    #
+    # @param term [String] search term
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :search_by_schedule_cron, ->(term) { where('schedule_cron ILIKE ?', "%#{term}%") }
+
+    ## Scope search by last_run_at
+    # Searches the timestamp of the most recent associated run's `started_at` using ILIKE
+    #
+    # @param term [String] search term
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :search_by_last_run_at, lambda { |term|
+      where(<<~SQL, like: "%#{term}%")
+        EXISTS (
+          SELECT 1
+          FROM (
+            SELECT MAX(r.started_at) AS last_run_at
+            FROM mat_view_runs r
+            WHERE r.mat_view_definition_id = mat_view_definitions.id
+          ) m
+          WHERE CAST(m.last_run_at AS TEXT) ILIKE :like
+        )
+      SQL
+    }
+
+    ## Scope filtered by name
+    # Filters by exact match on the `name` attribute.
+    #
+    # @param name [String] filter value
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :filtered_by_name, ->(name) { where(name:) }
+
+    ## Scope filtered by refresh_strategy
+    # Filters by exact match on the `refresh_strategy` attribute.
+    #
+    # @param refresh_strategy [String] filter value, one of `"regular"`, `"concurrent"`, `"swap"`
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :filtered_by_refresh_strategy, ->(refresh_strategy) { where(refresh_strategy:) }
+
+    ## Scope filtered by schedule_cron
+    # Filters by exact match on the `schedule_cron` attribute, or NULL/empty.
+    #
+    # @param schedule_cron [String] filter value, or `"no_value"` to match NULL/empty
+    # @return [ActiveRecord::Relation<Smriti::MatViewDefinition>]
+    scope :filtered_by_schedule_cron, lambda { |schedule_cron|
+      if schedule_cron == 'no_value'
+        where(schedule_cron: nil).or(where(schedule_cron: ''))
+      else
+        where('schedule_cron ILIKE ?', "%#{schedule_cron.tr('_', ' ')}%")
+      end
+    }
+
+    # ────────────────────────────────────────────────────────────────
+    # Class methods
+    # ────────────────────────────────────────────────────────────────
+
+    class << self
+      ##
+      # Returns options for filters in admin UI datatable.
+      #
+      # @return [Array<Array(String, String)>] array of `[label, value]` pairs
+      def filter_options_for_name
+        order(:name).distinct.pluck(:name).map { |name| [name, name] }
+      end
+
+      ##
+      # Returns options for filters in admin UI datatable.
+      #
+      # @return [Array<Array(String, String)>] array of `[label, value]` pairs
+      def filter_options_for_refresh_strategy
+        order(:refresh_strategy).distinct.pluck(:refresh_strategy).compact.map { |rs| [human_enum_name(:refresh_strategy, rs), rs] }
+      end
+
+      ##
+      # Returns options for filters in admin UI datatable.
+      #
+      # @return [Array<Array(String, String)>] array of `[label, value]` pairs
+      def filter_options_for_schedule_cron
+        order(:schedule_cron).distinct.pluck(:schedule_cron).compact.map { |sc| [sc, sc.tr(' ', '_')] }
+      end
+    end
+
+    # ────────────────────────────────────────────────────────────────
+    # Instance methods
+    # ────────────────────────────────────────────────────────────────
+
+    ##
+    # Returns the most recent run associated with this definition.
+    #
+    # @return [Smriti::MatViewRun, nil] the latest run or `nil` if none exist
+    #
+
+    def last_run
+      mat_view_runs.order(created_at: :desc).first
+    end
+  end
+end