diamond-orm 0.1.0

data/lib/diamond/domains/dql.rb

@@ -0,0 +1,395 @@
+module Diamond
+  module Domains
+    require_relative 'dml'
+    require_relative 'ddl'
+    require_relative 'cte'
+    require_relative 'dynamic_finders'
+
+    module DQL
+      # how each chainable node reconciles with the nodes already on the
+      # chain. builders validate args and construct nodes; _chain applies
+      # the strategy. new AST node types declare one line here (unknown
+      # classes accumulate).
+      RECONCILE = {
+        AST::Where      => :accumulate,
+        AST::Join       => :accumulate,
+        AST::With       => :accumulate,
+        AST::Order      => :merge,
+        AST::Limit      => :replace,
+        AST::Offset     => :replace,
+        AST::GroupBy    => :replace,
+        AST::Having     => :replace,
+        AST::Projection => :once,
+        AST::Distinct   => :replace
+      }.freeze
+
+      # the one operation every chain call funnels through. wraps a bare
+      # Table into a QueryObject, then reconciles the node into the ast.
+      # `.or` passes strategy: :fold_or explicitly — the single escape
+      # hatch, since folding rewrites history instead of appending.
+      def _chain(node, strategy: nil)
+        strategy ||= RECONCILE.fetch(node.class, :accumulate)
+        table = self.is_a?(Diamond::Table) ? self : @table
+        base  = self.is_a?(Diamond::Table) ? [] : @ast
+        q = Diamond::QueryObject.new(table, DQL.apply_strategy(strategy, base, node))
+        # Phase 7: carry the current mode across chain calls (so .first /
+        # .last / .limit / etc. don't reset .as_hash to .struct).
+        if self.is_a?(Diamond::QueryObject)
+          q.instance_variable_set(:@mode, @mode)
+        end
+        q
+      end
+
+      def self.apply_strategy(strategy, ast, node)
+        case strategy
+        when :accumulate
+          ast + [node]
+        when :replace
+          ast.reject { |n| n.instance_of?(node.class) } + [node]
+        when :merge # Order: concat specs into a single node
+          existing = ast.find { |n| n.is_a?(AST::Order) }
+          merged = AST::Order.new((existing ? existing.specs : []) + node.specs)
+          ast.reject { |n| n.is_a?(AST::Order) } + [merged]
+        when :once # Projection: second one is a usage error
+          raise "derive() called twice; use it once on each chain" if ast.any? { |n| n.is_a?(AST::Projection) }
+
+          ast + [node]
+        when :fold_or # .or: merge into the last Where, else append fresh
+          idx = ast.rindex { |n| n.is_a?(AST::Where) }
+          if idx
+            combined = AST::Or.new(ast[idx].condition, node.condition)
+            duped = ast.dup
+            duped[idx] = AST::Where.new(combined)
+            duped
+          else
+            ast + [node]
+          end
+        end
+      end
+
+      def _build_where(&block)
+        condition = Parser.parse_block(block, _schema_for_dsl, _scope_for_dsl)
+        raise "Where block must return an AST condition" unless condition.is_a?(AST::Node)
+        _chain(AST::Where.new(condition))
+      end
+
+      def _build_or_where(&block)
+        condition = Parser.parse_block(block, _schema_for_dsl, _scope_for_dsl)
+        raise "Or block must return an AST condition" unless condition.is_a?(AST::Node)
+        _chain(AST::Where.new(condition), strategy: :fold_or)
+      end
+
+      def _build_where_node(condition_node)
+        raise "Where node must be an AST::Node" unless condition_node.is_a?(AST::Node)
+        _chain(AST::Where.new(condition_node))
+      end
+
+      # Operators allowed as `{ op: value }` hashes inside where-hash
+      # values. Anything else raises with this list in the message.
+      HASH_OPERATORS = %i[not gt gte lt lte in nin like].freeze
+
+      def dispatch_where_arg(arg)
+        case arg
+        when Hash then _build_hash_where(arg)
+        when Array then _build_or_chain(arg)
+        else raise ArgumentError, "where expects a Hash, Array of Hashes, or a block, got #{arg.class}"
+        end
+      end
+
+      # Single hash: AND across columns.
+      def _build_hash_where(hash)
+        raise ArgumentError, "where hash must not be empty" if hash.empty?
+        _build_where_node(combine_and(hash.map { |col, val| hash_condition(col, val) }))
+      end
+
+      # Array of hashes: OR across hashes, AND within each hash.
+      def _build_or_chain(hashes)
+        raise ArgumentError, "where array must not be empty" if hashes.empty?
+        unless hashes.all? { |h| h.is_a?(Hash) }
+          raise ArgumentError, "where array must contain only Hashes"
+        end
+        node = combine_and(hashes.first.map { |col, val| hash_condition(col, val) })
+        hashes.drop(1).each do |h|
+          node = AST::Or.new(node, combine_and(h.map { |col, val| hash_condition(col, val) }))
+        end
+        _build_where_node(node)
+      end
+
+      def combine_and(conds)
+        raise ArgumentError, "where hash must not be empty" if conds.empty?
+        conds.reduce { |acc, c| AST::And.new(acc, c) }
+      end
+
+      # One column => one AST condition node. Values take runtime data
+      # directly (no parsing), so locals, method returns, and constants
+      # all work here — this is the value path blocks can't provide.
+      def hash_condition(col, val)
+        col = col.to_sym
+        Diamond::Parser.validate_column!(col, _schema_for_dsl)
+        column = AST::Column.new(col)
+        case val
+        when Hash
+          unknown = val.keys.map(&:to_sym) - HASH_OPERATORS
+          unless unknown.empty?
+            raise ArgumentError, "unknown where operator(s) #{unknown.inspect} on #{col}; allowed: #{HASH_OPERATORS.inspect}"
+          end
+          combine_and(val.map { |op, v| hash_operator(column, col, op.to_sym, v) })
+        when Range
+          if val.begin.nil? || val.end.nil?
+            raise ArgumentError, "where range on #{col} must have both bounds (no endless/beginless ranges)"
+          end
+          AST::Between.new(column, AST::Literal.new(val.begin), AST::Literal.new(val.end))
+        when Array
+          # Empty arrays compile to 1=0 natively (same as where_in) —
+          # no special case needed.
+          AST::In.new(column, val.map { |v| AST::Literal.new(v) })
+        when nil
+          AST::IsNull.new(column)
+        else
+          AST::Equality.new(column, AST::Literal.new(val))
+        end
+      end
+
+      def hash_operator(column, col, op, v)
+        case op
+        when :not
+          if v.nil?
+            AST::IsNotNull.new(column)
+          elsif v.is_a?(Array)
+            AST::NotIn.new(column, v.map { |e| AST::Literal.new(e) })
+          else
+            AST::NotEqual.new(column, AST::Literal.new(v))
+          end
+        when :gt then AST::GreaterThan.new(column, AST::Literal.new(v))
+        when :gte then AST::GreaterEqual.new(column, AST::Literal.new(v))
+        when :lt then AST::LessThan.new(column, AST::Literal.new(v))
+        when :lte then AST::LessEqual.new(column, AST::Literal.new(v))
+        when :in then AST::In.new(column, Array(v).map { |e| AST::Literal.new(e) })
+        when :nin then AST::NotIn.new(column, Array(v).map { |e| AST::Literal.new(e) })
+        when :like then AST::Like.new(column, AST::Literal.new(v))
+        end
+      end
+
+      def _build_projection(*args, &block)
+        nodes = if args.empty? && block_given?
+                  Parser.parse_derive(block, _schema_for_dsl)
+                else
+                  args.map do |a|
+                    if a.is_a?(Symbol)
+                      unless _schema_for_dsl[:columns].include?(a)
+                        raise Diamond::UnknownColumnError.build(_schema_for_dsl, a)
+                      end
+                      AST::Column.new(a)
+                    elsif a.is_a?(Array) && a.size == 2
+                      _qualified_pair_column(a[0].to_sym, a[1].to_sym)
+                    else
+                      a
+                    end
+                  end
+                end
+        _chain(AST::Projection.new(nodes))
+      end
+
+      def _build_join(table_name, type, on, eager: false, single: nil, as: nil)
+        if on.nil?
+          on = _resolve_join_keys(table_name)
+        end
+        single = _detect_single_join(table_name) if single.nil?
+        _chain(AST::Join.new(table_name, type, on, eager: eager, single: single, as: as))
+      end
+
+      # `.includes(:posts)` is sugar for `.join(:posts, eager: true)`.
+      # supports a single table or a list. each eagerly-loaded child becomes
+      # a nested struct array on the parent.
+      # Auto-detects cardinality from FKs: belongs_to -> single, has_many -> collection.
+      # `as:` renames the struct member (only meaningful for a single table).
+      def _build_includes(*tables, **opts)
+        single = opts.fetch(:single, nil)
+        as = opts.fetch(:as, nil)
+        if as && tables.size > 1
+          raise ArgumentError, "includes with `as:` only supports a single table, got #{tables.size}"
+        end
+        result = self
+        tables.each do |table_name|
+          result = result._build_join(table_name, :left, nil, eager: true, single: single, as: as)
+        end
+        result
+      end
+
+      def _build_order(*args, **kwargs)
+        _chain(AST::Order.new(_order_pairs(*args, **kwargs)))
+      end
+
+      # Replace any existing ordering (order merges). Bare call with
+      # no pairs clears ordering entirely.
+      def _build_reorder(*args, **kwargs)
+        pairs = args.empty? && kwargs.empty? ? [] : _order_pairs(*args, **kwargs)
+        _chain(AST::Order.new(pairs), strategy: :replace)
+      end
+
+      # Pure pair parsing shared by order (merge) and reorder
+      # (replace). Same validation, same errors.
+      def _order_pairs(*args, **kwargs)
+        pairs = []
+        args.each do |a|
+          qualified = _qualified_sort_pair(a)
+          if qualified
+            pairs << qualified
+            next
+          end
+          sym, dir =
+            if a.is_a?(Array) && a.size == 2 && a[1].is_a?(Symbol)
+              [a[0].to_sym, a[1]]
+            else
+              [a.to_sym, :asc]
+            end
+          raise Diamond::UnknownColumnError.build(_schema_for_dsl, sym) unless _schema_for_dsl[:columns].include?(sym)
+          unless %i[asc desc].include?(dir)
+            raise ArgumentError, "direction must be :asc or :desc, got #{dir.inspect}"
+          end
+          pairs << [sym, dir]
+        end
+        kwargs.each do |col, direction|
+          sym = col.to_sym
+          raise Diamond::UnknownColumnError.build(_schema_for_dsl, sym) unless _schema_for_dsl[:columns].include?(sym)
+          d = direction.to_s.downcase.to_sym
+          unless %i[asc desc].include?(d)
+            raise ArgumentError, "direction must be :asc or :desc, got #{direction.inspect}"
+          end
+          pairs << [sym, d]
+        end
+        raise ArgumentError, "order requires at least one column" if pairs.empty?
+
+        pairs
+      end
+
+      def _build_limit(n)
+        raise ArgumentError, "limit must be Integer >= 0, got #{n.inspect}" unless n.is_a?(Integer) && n >= 0
+        _chain(AST::Limit.new(n))
+      end
+
+      def _build_offset(n)
+        raise ArgumentError, "offset must be Integer >= 0, got #{n.inspect}" unless n.is_a?(Integer) && n >= 0
+        _chain(AST::Offset.new(n))
+      end
+
+      def _build_group(columns)
+        validated = columns.map do |c|
+          if c.is_a?(Array)
+            unless c.size == 2
+              raise ArgumentError, "group takes columns or [table, column] pairs, got #{c.inspect}"
+            end
+            _qualified_pair_column(c[0].to_sym, c[1].to_sym)
+          else
+            sym = c.to_sym
+            raise Diamond::UnknownColumnError.build(_schema_for_dsl, sym) unless _schema_for_dsl[:columns].include?(sym)
+            sym
+          end
+        end
+        _chain(AST::GroupBy.new(validated))
+      end
+
+      def _build_having(&block)
+        condition = Parser.parse_block(block, _schema_for_dsl, _scope_for_dsl)
+        raise "Having block must return an AST condition" unless condition.is_a?(AST::Node)
+        _chain(AST::Having.new(condition))
+      end
+
+      # --- Context Hooks (Used by the DSL modules) ---
+      def _schema_for_dsl
+        self.is_a?(Diamond::Table) ? @schema : @table.schema
+      end
+
+      # tables the current chain can filter on: the base table plus every
+      # joined table, each mapped to its schema. lets `tags.tag` in a
+      # block resolve to a qualified column. unknown join targets are
+      # skipped (their own errors surface at compile time).
+      def _scope_for_dsl
+        base = self.is_a?(Diamond::Table) ? @name : @table.name
+        scope = { base => _schema_for_dsl }
+        joins = self.is_a?(Diamond::Table) ? [] : @ast.select { |n| n.is_a?(AST::Join) }
+        joins.each do |j|
+          sch = Diamond.engine.schema_cache[j.table_name]
+          scope[j.table_name] = sch if sch
+        end
+        scope
+      end
+
+      private
+
+      # [table, col] or [table, col, dir] in order/group/derive args.
+      # returns [AST::Column(table:), dir] or nil when `a` isn't a
+      # qualified shape (caller falls back to the plain path). bare
+      # [col, :asc/:desc] pairs keep their old meaning.
+      def _qualified_sort_pair(a)
+        return nil unless a.is_a?(Array) && (a.size == 2 || a.size == 3)
+        return nil unless a[1].is_a?(Symbol) && !%i[asc desc].include?(a[1])
+
+        dir = a.size == 3 ? a[2] : :asc
+        unless %i[asc desc].include?(dir)
+          raise ArgumentError, "direction must be :asc or :desc, got #{dir.inspect}"
+        end
+        [_qualified_pair_column(a[0].to_sym, a[1].to_sym), dir]
+      end
+
+      # validate a [table, column] pair against the chain scope and build
+      # a qualified Column. join-first rule mirrors where-blocks.
+      def _qualified_pair_column(t, c)
+        scope = _scope_for_dsl
+        if scope.key?(t)
+          sch = scope[t]
+          raise Diamond::UnknownColumnError.build(sch, c) unless sch[:columns].include?(c)
+
+          AST::Column.new(c, table: t)
+        elsif Diamond.engine.schema_cache.key?(t)
+          raise ArgumentError,
+                "using '#{t}.#{c}' needs `.join(:#{t})` first " \
+                "(joins must come before the clause that uses them)"
+        else
+          raise ArgumentError, "unknown table '#{t}' in [table, column] pair"
+        end
+      end
+
+      # Convention for the returned `on` hash (consumed by
+      # Compiler::DQL.render_on_clauses): `{ <joined_local> => <current_ref> }`.
+      # Either side of the FK edge can hold the local column, so normalize.
+      def _resolve_join_keys(target_table)
+        current = _current_table_name
+        fks = Diamond.engine.foreign_keys
+
+        if fks[current]
+          fks[current].each do |fk|
+            return { fk[:ref_col] => fk[:local] } if fk[:ref_table] == target_table
+          end
+        end
+
+        if fks[target_table]
+          fks[target_table].each do |fk|
+            return { fk[:local] => fk[:ref_col] } if fk[:ref_table] == current
+          end
+        end
+
+        raise Diamond::TableNotFound,
+              "No foreign key connects '#{current}' and '#{target_table}'. " \
+              "Pass `on: { <local>: <ref> }` explicitly."
+      end
+
+      # Detect if join is to-one (belongs_to) vs to-many (has_many)
+      # Current table has FK to target -> belongs_to -> single (to-one)
+      # Target table has FK to current -> has_many -> collection (to-many)
+      # Default: collection (safer)
+      def _detect_single_join(target_table)
+        current = _current_table_name
+        fks = Diamond.engine.foreign_keys
+
+        return true  if fks[current]&.any? { |fk| fk[:ref_table] == target_table }
+        return false if fks[target_table]&.any? { |fk| fk[:ref_table] == current }
+        false
+      end
+
+      def _current_table_name
+        self.is_a?(Diamond::Table) ? @name : @table.name
+      end
+    end
+  end
+end

data/lib/diamond/domains/dynamic_finders.rb

@@ -0,0 +1,64 @@
+module Diamond
+  module Domains
+    module DynamicFinders
+      FINDER_PREFIX = 'by_'.freeze
+      AND_SEPARATOR = '_and_'.freeze
+      CACHES_KEY = Diamond::RACTOR_KEYS[:finder_cols]
+
+      # Per-Ractor cache for finder name -> column symbols. the parse is pure
+      # (name only), so a hot `by_id` loop doesn't re-split every call.
+      # validation still runs per call against the live schema.
+      def self.cache
+        Ractor.current[CACHES_KEY] ||= {}
+      end
+
+      def self.clear_caches!
+        Ractor.current[CACHES_KEY] = {}
+      end
+
+      def method_missing(name, *args, &block)
+        method_str = name.to_s
+        return super unless method_str.start_with?(FINDER_PREFIX)
+
+        cache = DynamicFinders.cache
+        columns = cache[method_str]
+        unless columns
+          column_strs = method_str.delete_prefix(FINDER_PREFIX).split(AND_SEPARATOR)
+          if column_strs.empty?
+            raise ArgumentError, "Invalid dynamic finder '#{name}': no columns after prefix"
+          end
+          columns = column_strs.map(&:to_sym)
+          cache[method_str] = columns
+        end
+        unless args.size == columns.size
+          raise ArgumentError,
+                "wrong number of arguments for #{name} (given #{args.size}, expected #{columns.size})"
+        end
+
+        columns.each do |col|
+          unless _schema_for_dsl[:columns].include?(col)
+            raise Diamond::UnknownColumnError.build(_schema_for_dsl, col)
+          end
+        end
+
+        pairs = columns.zip(args)
+        condition = pairs.drop(1).reduce(build_equality(pairs.first)) do |acc, pair|
+          AST::And.new(acc, build_equality(pair))
+        end
+
+        _chain(AST::Where.new(condition))
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        name.to_s.start_with?(FINDER_PREFIX) || super
+      end
+
+      private
+
+      def build_equality(pair)
+        col, val = pair
+        AST::Equality.new(AST::Column.new(col), AST::Literal.new(val))
+      end
+    end
+  end
+end