lowdata 0.1.0 → 0.3.0

data/lib/table_reference.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
 
 class LowData
-  # A table named by a constant, such as `Users`, waiting for its columns: `Users[:username]`.
+  # A table named by a constant, such as `Users`. Square brackets choose its columns, `Users[:username]`, and on its own
+  # it's every column. See ADR 0006.
   # An inverted reference is `Table`, standing in for the repository's table and any table related to it.
   # A reference can carry filters from round brackets, `Posts(published: true)`, and be negated with `~Posts`.
   class TableReference
     FILTER_KEYWORD_MESSAGE = 'Filters go in round brackets, e.g. Posts(published: true)[:title], not %<keywords>s'
+    BARE_TABLE_MESSAGE = 'Table joins the tables that own the columns it selects, so name them, e.g. Table[:title, :username]. ' \
+                         "For every column of the repository's table, name the table, e.g. Posts"
+    OPERATORS = %i[+ & < > <=> ^ * /].freeze
+
+    # A bare table on its own is every column, as a data expression: `Users[:username] + Posts`.
+    def self.expression(value) = value.is_a?(TableReference) ? value.to_expression : value
 
     attr_reader :table, :filter, :negated
 
@@ -17,18 +24,22 @@ class LowData
     end
 
     # Each argument's type decides its meaning:
-    #   Posts[:title]                              # A symbol is a column. No columns selects every column.
-    #   Users[:username, Posts[:title]]            # A data expression is a nested table.
+    #   Posts[:title]                              # A symbol is a column. Empty brackets select no columns.
+    #   Users[:username, Posts[:title]]            # A data expression is a nested table, and a bare table nests
+    #   Users[:username, Posts]                    # every column.
     #   Reviews[:rating, author: Users[:username]] # A keyword with a data expression names a nested table.
+    #   Posts[:id, headline: :title]               # A keyword with a symbol renames a column.
     def [](*arguments, **keywords)
-      raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't select columns" if negated
+      check_negated!
       return inverted(arguments:, keywords:) if @inverted
 
+      arguments = arguments.map { |argument| TableReference.expression(argument) }
       expressions, columns = arguments.partition { |argument| argument.is_a?(DataExpression) }
       check_columns!(columns:)
-      nested = nested(pairs: expressions.map { |expression| [nil, expression] } + named(keywords:))
+      named, renames = named(keywords:, columns:)
+      nested = nested(pairs: expressions.map { |expression| [nil, expression] } + named)
 
-      DataExpression.new(node: DataExpression::Source.new(table:, columns:, nested:, filter:))
+      DataExpression.new(node: DataExpression::Source.new(table:, columns:, renames:, nested:, filter:))
     end
 
     # Each argument's type decides its meaning:
@@ -37,8 +48,9 @@ class LowData
     #   Users(Posts), Users(~Posts)                # A table keeps rows with, or without, related rows.
     #   Users(Posts => 3..)                        # A table as a key keeps rows with that many related rows.
     #   Reviews(author: Users(username: 'alice'))  # A keyword with a table names the foreign key to follow.
+    #   Posts(:user_id)                            # A symbol names the foreign key a nested join links by.
     def where(*arguments, **keywords, &block)
-      related = arguments.map { |argument| related(key: nil, reference: argument) }
+      related = arguments.grep_v(Symbol).map { |argument| related(key: nil, reference: argument) }
       values = {}
 
       keywords.each do |key, value|
@@ -49,7 +61,7 @@ class LowData
       end
 
       conditions = block ? [Sequel.virtual_row(&block)] : []
-      with(filter: filter.merge(DataExpression::Filter.new(values:, conditions:, related:)))
+      with(filter: filter.merge(DataExpression::Filter.new(values:, conditions:, related:, foreign_keys: arguments.grep(Symbol))))
     end
 
     # `~Posts` keeps rows without related posts.
@@ -57,12 +69,35 @@ class LowData
       with(negated: !negated)
     end
 
+    # A bare table reads and joins as every column of the table:
+    #   Posts                          # SELECT posts.* FROM posts
+    #   Users[:username] + Posts       # Each user with every column of their posts.
+    #   Posts ^ -Col[:views] * 10      # The 10 most viewed posts.
+    def to_expression
+      raise ArgumentError, BARE_TABLE_MESSAGE if @inverted
+
+      check_negated!
+      DataExpression.new(node: source)
+    end
+
+    OPERATORS.each do |operator|
+      define_method(operator) { |other| to_expression.public_send(operator, other) }
+    end
+
+    %i[to_a sql dataset].each do |name|
+      define_method(name) { |**options| to_expression.public_send(name, **options) }
+    end
+
     def source
-      DataExpression::Source.new(table:, columns: [], filter:)
+      DataExpression::Source.new(table:, columns: [], filter:, bare: true)
     end
 
     private
 
+    def check_negated!
+      raise ArgumentError, "~#{LowData.constant_name(table)} filters by related rows, so it can't select columns" if negated
+    end
+
     def with(filter: @filter, negated: @negated)
       self.class.new(table:, inverted: @inverted, filter:, negated:)
     end
@@ -76,11 +111,20 @@ class LowData
       DataExpression::Related.new(key:, source: reference.source, count: count || (reference.negated ? 0 : 1..))
     end
 
-    def named(keywords:)
-      named, filters = keywords.partition { |_key, value| value.is_a?(DataExpression) }
+    # Returns the named nested tables and the renamed columns.
+    def named(keywords:, columns:)
+      keywords = keywords.transform_values { |value| TableReference.expression(value) }
+      named, others = keywords.partition { |_key, value| value.is_a?(DataExpression) }
+      renames, filters = others.partition { |_key, value| value.is_a?(Symbol) }
       raise ArgumentError, format(FILTER_KEYWORD_MESSAGE, keywords: filters.to_h) if filters.any?
 
-      named
+      check_renames!(names: columns + named.map(&:first), renames: renames.to_h)
+      [named, renames.to_h]
+    end
+
+    def check_renames!(names:, renames:)
+      duplicate = (renames.keys & names).first
+      raise ArgumentError, "#{LowData.constant_name(table)}[] returns #{duplicate} twice. Name each value once" if duplicate
     end
 
     def nested(pairs:)
@@ -88,10 +132,13 @@ class LowData
     end
 
     def inverted(arguments:, keywords:)
+      raise ArgumentError, BARE_TABLE_MESSAGE if arguments.empty? && keywords.empty?
+
       check_columns!(columns: arguments)
-      raise ArgumentError, 'Table[] takes column names only' if keywords.any?
+      raise ArgumentError, 'Table[] takes column names only, and renames such as headline: :title' unless keywords.values.all?(Symbol)
 
-      DataExpression.new(node: DataExpression::Inversion.new(table:, columns: arguments, filter:))
+      check_renames!(names: arguments, renames: keywords)
+      DataExpression.new(node: DataExpression::Inversion.new(table:, columns: arguments, renames: keywords, filter:))
     end
 
     def check_columns!(columns:)

data/lib/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class LowData
-  VERSION = '0.1.0'
+  VERSION = '0.3.0'
 end

data/lib/write_checks.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+class LowData
+  # Checks a write before it runs, so a mistake raises rather than writing the wrong rows. See Writer.
+  module WriteChecks
+    ROWS_MESSAGE = '%<operator>s takes a hash or an array of hashes, e.g. Posts %<operator>s { title: \'Hello\' }, not %<rows>s'
+    INSERT_FILTER_MESSAGE = 'An insert adds new rows, so it takes no round brackets. To insert a row or update the one ' \
+                            'matching the round brackets, upsert with <=, e.g. Posts(slug: \'hello\') <= { title: \'Hello\' }'
+    UPSERT_FILTER_MESSAGE = 'An upsert matches one row by plain values, e.g. Posts(slug: \'hello\') <= row, so it takes no ' \
+                            'ranges, lists, blocks or tables in round brackets'
+    FOREIGN_KEY_MESSAGE = "A symbol in round brackets names a foreign key for a nested join, so it can't choose rows to %<action>s"
+    # `Posts[:id] <= Users[:id]` reads like a comparison or a join, so it says what `<=` does instead.
+    EXPRESSION_MESSAGES = {
+      '<<' => "<< inserts rows, e.g. Posts << { title: 'Hello' }, not a data expression",
+      '<=' => "<= upserts rows, e.g. Posts(slug: 'hello') <= { title: 'Hello' }, so it can't compare or join data expressions. " \
+              'Join them with &, <, > or <=>'
+    }.freeze
+
+    private
+
+    def check_rows!(rows:, operator:)
+      return if rows.is_a?(Hash) || (rows.is_a?(Array) && rows.all?(Hash))
+      raise ArgumentError, EXPRESSION_MESSAGES.fetch(operator) if rows.is_a?(DataExpression)
+
+      raise ArgumentError, format(ROWS_MESSAGE, operator:, rows: rows.inspect)
+    end
+
+    def check_insert_filter!(filter:)
+      raise ArgumentError, INSERT_FILTER_MESSAGE if chooses_rows?(filter:)
+    end
+
+    # Whether the round brackets choose rows. Foreign keys only name how a nested join links.
+    def chooses_rows?(filter:)
+      filter.values.any? || filter.conditions.any? || filter.related.any?
+    end
+
+    def check_upsert_filter!(filter:)
+      plain = filter.values.values.none? { |value| value.is_a?(Range) || value.is_a?(Enumerable) || value.is_a?(Sequel::SQL::Expression) }
+      return if plain && filter.conditions.empty? && filter.related.empty? && filter.foreign_keys.empty?
+
+      raise ArgumentError, UPSERT_FILTER_MESSAGE
+    end
+
+    # An update or delete without round brackets would change every row, so it raises. `dataset` can still do that.
+    def check_chosen!(source:, action:, example:)
+      filter = source.filter
+      raise ArgumentError, format(FOREIGN_KEY_MESSAGE, action:) if filter.foreign_keys.any?
+      return if chooses_rows?(filter:)
+
+      raise ArgumentError, "Choose the #{source.table} to #{action} with round brackets, e.g. #{example}"
+    end
+
+    # MySQL's ON DUPLICATE KEY UPDATE matches any unique key, so the upsert must match on one, and the row mustn't set
+    # every column of another, which could match a different row. An auto-increment id left out of the row can't match.
+    def check_mysql_keys!(table:, keys:, row:, target:)
+      matched, others = keys.partition { |key| key.sort == target.sort }
+      raise Error, "MySQL upserts match on a unique key, and #{target.join(', ')} isn't one of #{table}'s" if matched.empty?
+
+      clashing = others.find { |key| key.none? { |column| row[column].nil? } }
+      return unless clashing
+
+      raise Error, "MySQL matches an upsert on any unique key, and the row also sets #{clashing.join(', ')}, which could match " \
+                   "another #{table} row. Leave #{clashing.join(', ')} out of the row, or match on it"
+    end
+
+    # Checked before the write, so a typo doesn't write a row and then fail to return it.
+    def check_returned!(source:, columns:)
+      missing = (source.columns + source.renames.values) - columns
+      raise ArgumentError, "#{source.table} has no #{missing.join(', ')} column to return" if missing.any?
+    end
+
+    def assignment(values:)
+      return "[:#{values.keys.first}] = #{values.values.first.inspect}" if values.one?
+
+      "[] = #{values.inspect}"
+    end
+  end
+end

data/lib/writer.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require_relative 'write_checks'
+
+class LowData
+  # Runs writes as soon as they're written, and returns what they wrote. See ADR 0007:
+  #   Posts << { title: 'Hello' }                 # INSERT, returning the primary key
+  #   Posts[:id, :title] << { title: 'Hello' }    # INSERT, returning the columns in square brackets
+  #   Posts(slug: 'hello') <= { title: 'Hello' }  # INSERT ... ON CONFLICT (slug) DO UPDATE, returning the primary key
+  #   Posts(id: 1)[:title] = 'New'                # UPDATE ... WHERE (posts.id = 1)
+  #   Posts(id: 1).delete                         # DELETE ... WHERE (posts.id = 1), returning the number of rows deleted
+  class Writer
+    include WriteChecks
+
+    def initialize(database:)
+      raise ConfigError, ConfigError::MISSING_DATABASE if database.nil?
+
+      @database = database
+      @schema = Schema.new(database:)
+      @filters = FilterCompiler.new(database:, schema: @schema)
+    end
+
+    def insert(source:, rows:)
+      check_rows!(rows:, operator: '<<')
+      check_insert_filter!(filter: source.filter)
+      check_returned!(source:, columns: @schema.columns(table: source.table))
+      return insert_all(source:, rows:) if source.no_columns? && rows.is_a?(Array) && rows.map(&:keys).uniq.one?
+
+      each_row(rows:) { |row| insert_row(source:, row:) }
+    end
+
+    # The round brackets name the columns to match on, and their values are written too.
+    def upsert(source:, rows:)
+      check_rows!(rows:, operator: '<=')
+      check_upsert_filter!(filter: source.filter)
+      check_returned!(source:, columns: @schema.columns(table: source.table))
+
+      each_row(rows:) { |row| upsert_row(source:, row: source.filter.values.merge(row)) }
+    end
+
+    def update(source:, values:)
+      check_chosen!(source:, action: 'update', example: "#{constant(source:)}(id: 1)#{assignment(values:)}")
+
+      chosen(source:).update(values)
+    end
+
+    def delete(source:)
+      check_chosen!(source:, action: 'delete', example: "#{constant(source:)}(id: 1).delete")
+
+      chosen(source:).delete
+    end
+
+    private
+
+    # A hash writes one row and returns a hash, and an array writes each row in a transaction and returns an array.
+    def each_row(rows:, &)
+      return yield(rows) if rows.is_a?(Hash)
+
+      @database.transaction { rows.map(&) }
+    end
+
+    # Empty brackets return nothing, so rows with the same columns go in one INSERT, as nothing needs matching back to
+    # them. Otherwise rows insert one by one, because RETURNING doesn't promise the inserted order, and a multi-row
+    # INSERT takes its columns from the first row, so a column missing from it would be dropped.
+    def insert_all(source:, rows:)
+      @database[source.table].multi_insert(rows)
+      rows.map { {} }
+    end
+
+    def insert_row(source:, row:)
+      dataset = @database[source.table]
+      return dataset.returning(*returned(source:)).insert(row).first if returning?(dataset:, source:)
+
+      id = dataset.insert(row)
+      read_back(source:, keys: inserted_keys(table: source.table, row:, id:))
+    end
+
+    def upsert_row(source:, row:)
+      target = conflict_target(source:, row:)
+      return mysql_upsert(source:, row:, target:) if @database.database_type == :mysql
+
+      dataset = @database[source.table]
+      raise Error, "LowData can't upsert on #{@database.database_type}" unless dataset.respond_to?(:insert_conflict)
+
+      dataset = dataset.insert_conflict(target:, update: updates(row:, target:))
+      return dataset.returning(*returned(source:)).insert(row).first if returning?(dataset:, source:)
+
+      dataset.insert(row)
+      read_back(source:, keys: row.slice(*target))
+    end
+
+    def mysql_upsert(source:, row:, target:)
+      check_mysql_keys!(table: source.table, keys: unique_keys(table: source.table), row:, target:)
+      @database[source.table].on_duplicate_key_update(*updates(row:, target:).keys).insert(row)
+      read_back(source:, keys: row.slice(*target))
+    end
+
+    def unique_keys(table:)
+      indexes = @database.indexes(table).values.select { |index| index[:unique] }.map { |index| index[:columns] }
+      ([@schema.primary_key(table:)] + indexes).reject(&:empty?)
+    end
+
+    # Without round brackets, an upsert matches on the primary key.
+    def conflict_target(source:, row:)
+      return source.filter.values.keys if source.filter.values.any?
+
+      primary_key = @schema.primary_key(table: source.table)
+      missing = primary_key - row.keys
+      return primary_key if primary_key.any? && missing.empty?
+
+      raise ArgumentError, "#{constant(source:)} <= row matches on the primary key, so the row needs #{missing.join(', ')}. " \
+                           "Or name the columns to match in round brackets, e.g. #{constant(source:)}(slug: 'hello') <= row"
+    end
+
+    # A row of only the matched columns still updates one of them, so the database returns the row rather than nothing.
+    def updates(row:, target:)
+      columns = row.keys - target
+      (columns.empty? ? [target.first] : columns).to_h { |column| [column, Sequel[:excluded][column]] }
+    end
+
+    # Square brackets choose the columns returned, and a bare table returns its primary key, or every column without one.
+    def returned(source:)
+      return @schema.primary_key(table: source.table) if source.every_column?
+
+      source.columns + source.renames.map { |name, column| Sequel.as(column, name) }
+    end
+
+    # Empty brackets return no columns, and databases without RETURNING read the row back by its keys.
+    def read_back(source:, keys:)
+      return {} if source.no_columns?
+
+      @database[source.table].where(keys).select(*returned(source:)).first
+    end
+
+    def returning?(dataset:, source:)
+      dataset.supports_returning?(:insert) && !source.no_columns?
+    end
+
+    def inserted_keys(table:, row:, id:)
+      primary_key = @schema.primary_key(table:)
+      return row if primary_key.empty?
+      return { primary_key.first => id } if primary_key.one? && !row.key?(primary_key.first)
+
+      row.slice(*primary_key)
+    end
+
+    def chosen(source:)
+      @filters.apply(dataset: @database[source.table], source:)
+    end
+
+    def constant(source:)
+      LowData.constant_name(source.table)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lowdata
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - maedi
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: lowtype
   requirement: !ruby/object:Gem::Requirement
@@ -58,20 +58,28 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- config/rubocop.yml
 - lib/col.rb
 - lib/data_expression.rb
+- lib/data_expression/source.rb
+- lib/data_expression/writes.rb
 - lib/errors.rb
 - lib/filter_compiler.rb
 - lib/inversion.rb
 - lib/lowdata.rb
+- lib/nested_join.rb
 - lib/nesting.rb
+- lib/nesting_path.rb
 - lib/nesting_tree.rb
 - lib/order_compiler.rb
 - lib/query_compiler.rb
 - lib/rows.rb
 - lib/schema.rb
 - lib/table_reference.rb
+- lib/table_reference/writes.rb
 - lib/version.rb
+- lib/write_checks.rb
+- lib/writer.rb
 homepage: https://github.com/low-rb/lowdata
 licenses: []
 metadata: