diamond-orm 0.1.0

data/lib/diamond/ast.rb

@@ -0,0 +1,397 @@
+module Diamond
+  module AST
+    class Node
+      # so you can `&` / `|` any two conditions together.
+      def &(other)
+        AST::And.new(self, other)
+      end
+
+      def |(other)
+        AST::Or.new(self, other)
+      end
+    end
+
+    # `table` is nil for plain `age`, or a table name for qualified
+    # `tags.tag` refs in blocks over joins. qualified columns render with
+    # their own table and ignore the eager parent-prefix.
+    class Column < Node
+      attr_reader :name, :table
+      def initialize(name, table: nil); @name = name; @table = table; end
+
+      def ==(other)
+        AST::Equality.new(self, AST::Literal.new(other))
+      end
+
+      def !=(other)
+        AST::NotEqual.new(self, AST::Literal.new(other))
+      end
+
+      def >(other)
+        AST::GreaterThan.new(self, AST::Literal.new(other))
+      end
+
+      def <(other)
+        AST::LessThan.new(self, AST::Literal.new(other))
+      end
+    end
+
+    class Literal < Node
+      attr_reader :value
+      def initialize(value); @value = value; end
+    end
+
+    class BinaryOp < Node
+      attr_reader :left, :right, :operator
+      def initialize(left, right, operator)
+        @left = left; @right = right; @operator = operator
+      end
+    end
+
+    class Equality < BinaryOp
+      def initialize(left, right); super(left, right, :'='); end
+    end
+
+    class NotEqual < BinaryOp
+      def initialize(left, right); super(left, right, :'<>'); end
+    end
+
+    # `right` may hold expressions, not just literals.
+    class In < Node
+      attr_reader :left, :right
+      def initialize(left, right)
+        @left = left
+        @right = right
+      end
+    end
+
+    class NotIn < Node
+      attr_reader :left, :right
+      def initialize(left, right)
+        @left = left
+        @right = right
+      end
+    end
+
+    # Wraps a QueryObject as a SQL subquery: `(SELECT ...)`.
+    class Subquery < Node
+      attr_reader :query
+      def initialize(query); @query = query; end
+    end
+
+    class GreaterThan < BinaryOp
+      def initialize(left, right); super(left, right, :'>'); end
+    end
+
+    class LessThan < BinaryOp
+      def initialize(left, right); super(left, right, :'<'); end
+    end
+
+    class GreaterEqual < BinaryOp
+      def initialize(left, right); super(left, right, :'>='); end
+    end
+
+    class LessEqual < BinaryOp
+      def initialize(left, right); super(left, right, :<=); end
+    end
+
+    # `!(cond)` and `not cond` are the same Prism shape. wraps anything;
+    # sqlite truthiness applies to non-boolean operands.
+    class Not < Node
+      attr_reader :condition
+      def initialize(condition); @condition = condition; end
+    end
+
+    class Like < BinaryOp
+      def initialize(left, right); super(left, right, :LIKE); end
+    end
+
+    class IsNull < Node
+      attr_reader :column
+      def initialize(column); @column = column; end
+    end
+
+    class IsNotNull < Node
+      attr_reader :column
+      def initialize(column); @column = column; end
+    end
+
+    class Between < Node
+      attr_reader :column, :low, :high
+      def initialize(column, low, high)
+        @column = column
+        @low = low
+        @high = high
+      end
+    end
+
+    class And < BinaryOp
+      def initialize(left, right); super(left, right, :AND); end
+    end
+
+    class Or < BinaryOp
+      def initialize(left, right); super(left, right, :OR); end
+    end
+
+    class Where < Node
+      attr_reader :condition
+      def initialize(condition); @condition = condition; end
+    end
+
+    class Projection < Node
+      attr_reader :columns
+      def initialize(columns); @columns = columns; end
+    end
+
+    # marker: SELECT DISTINCT. carries nothing; presence is the flag.
+    class Distinct < Node
+    end
+
+    # `on` maps LOCAL col to FOREIGN col, e.g. { user_id: :id }.
+    # `eager: true` marks the join for object-graph transform: the SQL gets
+    # column aliases (users.id AS users.id, posts.id AS posts.id, ...) and
+    # the compiler returns an Extralite::Transform spec that deduplicates
+    # and nests the rows.
+    class Join < Node
+      attr_reader :table_name, :type, :on, :eager, :single, :as
+      def initialize(table_name, type, on, eager: false, single: false, as: nil)
+        @table_name = table_name
+        @type = type
+        @on = on
+        @eager = eager
+        @single = single
+        @as = as
+      end
+    end
+
+    class With < Node
+      attr_reader :name, :query, :recursive
+      def initialize(name, query, recursive: false)
+        @name = name
+        @query = query
+        @recursive = recursive
+      end
+    end
+
+    # `specs` is [[col, :asc|:desc], ...]. lands after WHERE in the sql.
+    class Order < Node
+      attr_reader :specs
+      def initialize(specs)
+        @specs = specs
+      end
+    end
+
+    class Limit < Node
+      attr_reader :value
+      def initialize(value)
+        @value = value
+      end
+    end
+
+    class Offset < Node
+      attr_reader :value
+      def initialize(value)
+        @value = value
+      end
+    end
+
+    class GroupBy < Node
+      attr_reader :columns
+      def initialize(columns)
+        @columns = columns # Array of Symbol column names
+      end
+    end
+
+    class Having < Node
+      attr_reader :condition
+      def initialize(condition)
+        @condition = condition
+      end
+    end
+
+    # swap the FROM target (how you query a CTE).
+    class From < Node
+      attr_reader :name
+      def initialize(name); @name = name; end
+    end
+
+    class Function < Node
+      attr_reader :name, :args
+      def initialize(name, args)
+        @name = name.to_s.upcase
+        @args = args # Array of AST::Column or AST::Literal
+      end
+    end
+
+    class WindowFunction < Node
+      attr_reader :func_name, :args, :partition_by, :order_by
+
+      def initialize(func_name, args, partition_by: [], order_by: [])
+        @func_name = func_name.to_s.upcase
+        @args = args
+        @partition_by = partition_by
+        @order_by = order_by
+      end
+    end
+
+    class Union < Node
+      attr_reader :left, :right, :operator
+      def initialize(left, right, operator = "UNION ALL")
+        @left = left
+        @right = right
+        @operator = operator
+      end
+    end
+
+    # --- DDL Nodes ---
+
+    # column order is DDL order.
+    class DefineRelation < Node
+      attr_reader :name, :columns
+      def initialize(name, columns)
+        @name = name
+        @columns = columns
+      end
+    end
+
+    # `type` is a ruby class. `options` knows :primary_key, :nullable, :default.
+    class ColumnDefinition < Node
+      attr_reader :name, :type, :options
+      def initialize(name, type, options = {})
+        @name = name
+        @type = type
+        @options = options
+      end
+    end
+
+    # on_delete/on_update: :cascade, :set_null, :set_default, :restrict,
+    # :no_action. nil leaves the clause out.
+    class ForeignKey < Node
+      attr_reader :local_column, :ref_table, :ref_column, :on_delete, :on_update
+      def initialize(local_column, ref_table, ref_column = :id,
+                     on_delete: nil, on_update: nil)
+        @local_column = local_column
+        @ref_table = ref_table
+        @ref_column = ref_column
+        @on_delete = on_delete
+        @on_update = on_update
+      end
+    end
+
+    # lifted into the AST so define_relation does CREATE TABLE then
+    # CREATE INDEX in one go.
+    class IndexDefinition < Node
+      attr_reader :name, :columns, :unique
+      def initialize(name, columns, unique: false)
+        @name = name
+        @columns = columns
+        @unique = unique
+      end
+    end
+
+    # --- DML Nodes ---
+
+    # `data`: Hash mapping column name (Symbol) to value.
+    class Insert < Node
+      attr_reader :data
+      def initialize(data)
+        @data = data
+      end
+    end
+
+    # `data`: Hash mapping column name (Symbol) to value.
+    class Update < Node
+      attr_reader :data
+      def initialize(data)
+        @data = data
+      end
+    end
+
+    # rows come from the chain's WHERE nodes.
+    class Delete < Node
+    end
+
+    # indented tree dump for staring at what a block became. one line
+    # per node, children indented two spaces. QueryObject#ast_tree maps
+    # this over the chain.
+    def self.dump(node, indent = 0)
+      pad = '  ' * indent
+      label = case node
+              when Column
+                node.table ? "Column(#{node.table}.#{node.name})" : "Column(#{node.name})"
+              when Literal
+                "Literal(#{node.value.inspect})"
+              when BinaryOp
+                node.class.name.split('::').last
+              when In, NotIn
+                "#{node.class.name.split('::').last}(#{node.right.size} vals)"
+              when IsNull, IsNotNull
+                node.class.name.split('::').last
+              when Between
+                'Between'
+              when Not
+                'Not'
+              when Subquery
+                'Subquery'
+              when Function
+                "#{node.name}(#{node.args.size} args)"
+              when WindowFunction
+                "#{node.func_name} OVER"
+              when Where
+                'Where'
+              when Projection
+                "Projection(#{node.columns.size} cols)"
+              when Join
+                "Join(#{node.table_name}, #{node.type}#{node.eager ? ', eager' : ''})"
+              when Order
+                labels = node.specs.map do |c, d|
+                  name = c.is_a?(Column) && c.table ? "#{c.table}.#{c.name}" : c.to_s
+                  "#{name} #{d}"
+                end
+                "Order(#{labels.join(', ')})"
+              when Limit
+                "Limit(#{node.value})"
+              when Offset
+                "Offset(#{node.value})"
+              when GroupBy
+                "GroupBy(#{node.columns.join(', ')})"
+              when Having
+                'Having'
+              when From
+                "From(#{node.name})"
+              when With
+                "With(#{node.name}#{node.recursive ? ', recursive' : ''})"
+              when Union
+                "Union(#{node.operator})"
+              else
+                node.class.name.split('::').last
+              end
+      lines = ["#{pad}#{label}"]
+      kids = case node
+             when BinaryOp then [node.left, node.right]
+             when In, NotIn then [node.left] + (node.right.is_a?(Array) ? node.right : [node.right])
+             when IsNull, IsNotNull then [node.column]
+             when Between then [node.column, node.low, node.high]
+             when Not then [node.condition]
+             when Function then node.args
+             when Where, Having then [node.condition]
+             when Projection then node.columns
+             when Union then [node.left, node.right]
+             else []
+             end
+      kids.each do |k|
+        lines << (k.is_a?(Node) ? dump(k, indent + 1) : "#{pad}  #{k.inspect}")
+      end
+      # With/Subquery hold whole queries — a Union node or a QueryObject
+      # carrying a chain. dump whichever it is.
+      if node.is_a?(With) || node.is_a?(Subquery)
+        q = node.query
+        if q.is_a?(Node)
+          lines << dump(q, indent + 1)
+        else
+          q.ast.each { |n| lines << dump(n, indent + 1) }
+        end
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/diamond/changeset.rb

@@ -0,0 +1,36 @@
+module Diamond
+  # Thin wrapper around Extralite::Changeset. Provides .apply(target_db),
+  # .invert, .to_blob, .load(blob) under a Diamond-y namespace.
+  #
+  # Used by Diamond.track_changes to keep callers from having to
+  # know that the underlying type is Extralite-specific.
+  class Changeset
+    def initialize(raw_changeset)
+      @raw = raw_changeset
+    end
+
+    # Replay the changeset on a target database (another Extralite db,
+    # a Diamond Engine, or your own test DB).
+    def apply(target)
+      target_db = target.is_a?(Diamond::Engine) ? target.db : target
+      @raw.apply(target_db)
+    end
+
+    # Returns a new Changeset that, when applied, undoes this one.
+    def invert
+      Diamond::Changeset.new(@raw.invert)
+    end
+
+    # Serialize for network transfer.
+    def to_blob
+      @raw.to_blob
+    end
+
+    # Build a Changeset from a serialized blob.
+    def self.load(blob)
+      cs = Extralite::Changeset.new
+      cs.load(blob)
+      Diamond::Changeset.new(cs)
+    end
+  end
+end

data/lib/diamond/compiler/base.rb

@@ -0,0 +1,17 @@
+require_relative 'dql'
+require_relative 'dml'
+require_relative 'ddl'
+require_relative 'registry'
+
+module Diamond
+  module Compiler
+    module Base
+      # Returns [sql, params, transform_or_nil]. The transform is non-nil
+      # only for eager-loaded queries; non-eager callers can ignore it.
+      def self.compile(table, ast, params = nil)
+        params ||= []
+        DQL.compile(table, ast, params)
+      end
+    end
+  end
+end

data/lib/diamond/compiler/ddl.rb

@@ -0,0 +1,94 @@
+module Diamond
+  module Compiler
+    module DDL
+      TYPE_MAP = {
+        Integer    => 'INTEGER',
+        String     => 'TEXT',
+        Float      => 'REAL',
+        TrueClass  => 'INTEGER',
+        FalseClass => 'INTEGER'
+      }.freeze
+
+      def self.compile(node)
+        raise ArgumentError, "Expected AST::DefineRelation, got #{node.class}" unless node.is_a?(AST::DefineRelation)
+        Diamond.validate_ident!(node.name, "table name")
+
+        column_clauses = node.columns.select { |c| c.is_a?(AST::ColumnDefinition) }.map { |c| render_column(c) }
+        fk_clauses    = node.columns.select { |c| c.is_a?(AST::ForeignKey) }.map { |c| render_foreign_key(c) }
+
+        body = (column_clauses + fk_clauses).join(', ')
+        sql  = "CREATE TABLE IF NOT EXISTS #{node.name} (#{body})"
+        [sql, []]
+      end
+
+      def self.render_column(node)
+        Diamond.validate_ident!(node.name, "column name")
+        sql_type = TYPE_MAP[node.type] or raise ArgumentError, "Unsupported column type: #{node.type}"
+        parts    = [node.name.to_s, sql_type]
+
+        if node.options[:primary_key]
+          parts << 'PRIMARY KEY'
+        elsif node.options[:nullable] == false
+          parts << 'NOT NULL'
+        end
+
+        if node.options.key?(:default)
+          parts << "DEFAULT #{render_default!(node.options[:default])}"
+        end
+
+        parts.join(' ')
+      end
+
+      # DDL cannot bind parameters, so DEFAULT literals go through a
+      # strict allowlist — numerics, booleans (as 1/0), and strings
+      # with single-quote escaping. Anything else raises instead of
+      # interpolating raw input into SQL.
+      def self.render_default!(value)
+        case value
+        when Numeric then value.to_s
+        when true then '1'
+        when false then '0'
+        when String then "'#{value.gsub("'", "''")}'"
+        when nil then 'NULL'
+        else raise ArgumentError, "Unsupported DEFAULT value: #{value.inspect}"
+        end
+      end
+
+      # ALTER TABLE ... ADD COLUMN for safe migrations. Only plain
+      # column definitions allowed — no PK/FK/index nodes (SQLite
+      # rejects most of those via ADD COLUMN anyway).
+      def self.compile_add_column(table_name, coldef)
+        raise ArgumentError, "Expected AST::ColumnDefinition, got #{coldef.class}" unless coldef.is_a?(AST::ColumnDefinition)
+        Diamond.validate_ident!(table_name, "table name")
+        if coldef.options[:primary_key]
+          raise ArgumentError, "Cannot ADD COLUMN #{coldef.name} as PRIMARY KEY (SQLite restriction)"
+        end
+        sql = "ALTER TABLE #{table_name} ADD COLUMN #{render_column(coldef)}"
+        [sql, []]
+      end
+
+      def self.render_foreign_key(node)
+        Diamond.validate_ident!(node.local_column, "foreign key column")
+        Diamond.validate_ident!(node.ref_table, "referenced table")
+        Diamond.validate_ident!(node.ref_column, "referenced column")
+        sql = "FOREIGN KEY (#{node.local_column}) REFERENCES #{node.ref_table}(#{node.ref_column})"
+        sql += " ON DELETE #{format_action(node.on_delete)}" if node.on_delete
+        sql += " ON UPDATE #{format_action(node.on_update)}" if node.on_update
+        sql
+      end
+
+      def self.format_action(sym)
+        sym.to_s.upcase.tr('_', ' ')
+      end
+
+      def self.compile_index(index_node, table_name)
+        Diamond.validate_ident!(index_node.name, "index name")
+        Diamond.validate_ident!(table_name, "table name")
+        index_node.columns.each { |c| Diamond.validate_ident!(c, "indexed column") }
+        unique_kw = index_node.unique ? 'UNIQUE ' : ''
+        sql = "CREATE #{unique_kw}INDEX IF NOT EXISTS #{index_node.name} ON #{table_name}(#{index_node.columns.join(', ')})"
+        [sql, []]
+      end
+    end
+  end
+end

data/lib/diamond/compiler/dml.rb

@@ -0,0 +1,109 @@
+require_relative 'dql'
+
+module Diamond
+  module Compiler
+    module DML
+      def self.compile_insert(table, insert_node, returning: [])
+        cols = insert_node.data.keys
+        placeholders = (['?'] * cols.size).join(', ')
+        sql = +"INSERT INTO #{table.name} (#{cols.join(', ')}) VALUES (#{placeholders})"
+        params = insert_node.data.values
+
+        if returning && !returning.empty?
+          sql << " RETURNING " << returning.map { |c| c.to_s }.join(', ')
+        end
+
+        db = Diamond.engine.db
+        stmt = db.prepare(sql)
+        begin
+          stmt.bind(*params)
+          if returning && !returning.empty?
+            # collect rows from the RETURNING clause
+            rows = []
+            stmt.each { |row| rows << row }
+            rows
+          else
+            stmt.to_a   # forces execution
+            []
+          end
+        ensure
+          begin
+            stmt.close unless stmt.closed?
+          rescue StandardError
+            # ensure must not raise
+          end
+        end
+        returning && !returning.empty? ? rows : db.last_insert_rowid
+      end
+
+      def self.compile_update(table, hash, where_nodes, returning: [])
+        params = []
+        set_clause = hash.keys.map { |k| "#{k} = ?" }.join(', ')
+        params.concat(hash.values)
+
+        sql = +"UPDATE #{table.name} SET #{set_clause}"
+        unless where_nodes.empty?
+          conditions = where_nodes.map { |w| DQL.translate_node(w.condition, params) }
+          sql << " WHERE " << conditions.join(' AND ')
+        end
+        if returning && !returning.empty?
+          sql << " RETURNING " << returning.map { |c| c.to_s }.join(', ')
+        end
+
+        db = Diamond.engine.db
+        stmt = db.prepare(sql)
+        rows = nil
+        begin
+          stmt.bind(*params)
+          if returning && !returning.empty?
+            rows = []
+            stmt.each { |row| rows << row }
+          else
+            stmt.to_a
+          end
+        ensure
+          begin
+            stmt.close unless stmt.closed?
+          rescue StandardError
+            # ensure must not raise
+          end
+        end
+
+        returning && !returning.empty? ? rows : db.changes
+      end
+
+      def self.compile_delete(table, where_nodes, returning: [])
+        params = []
+        sql = +"DELETE FROM #{table.name}"
+        unless where_nodes.empty?
+          conditions = where_nodes.map { |w| DQL.translate_node(w.condition, params) }
+          sql << " WHERE " << conditions.join(' AND ')
+        end
+        if returning && !returning.empty?
+          sql << " RETURNING " << returning.map { |c| c.to_s }.join(', ')
+        end
+
+        db = Diamond.engine.db
+        stmt = db.prepare(sql)
+        rows = nil
+        begin
+          stmt.bind(*params)
+          if returning && !returning.empty?
+            rows = []
+            stmt.each { |row| rows << row }
+          else
+            stmt.to_a
+          end
+        ensure
+          begin
+            stmt.close unless stmt.closed?
+          rescue StandardError
+            # ensure must not raise
+          end
+        end
+
+        returning && !returning.empty? ? rows : db.changes
+      end
+    end
+  end
+end