wowsql-sdk 3.0.2 → 3.1.0

data/lib/wowsql/table.rb

@@ -1,169 +1,182 @@
 require_relative 'query_builder'
 
 module WOWSQL
-  # Table interface for database operations.
+  # Table interface for direct PostgREST operations.
+  #
+  # All mutations use PostgREST native query parameters (?id=eq.val) and
+  # Prefer headers (return=representation, resolution=merge-duplicates).
+  #
+  # @example
+  #   user = client.table("users").get_by_id("uuid-here")
+  #   result = client.table("users").create({ email: "a@b.com", name: "Alice" })
   class Table
     def initialize(client, table_name)
-      @client = client
+      @client     = client
       @table_name = table_name
     end
 
-    # Start a query with column selection.
-    #
-    # @param columns [Array<String>] Column(s) to select
-    # @return [QueryBuilder] QueryBuilder for chaining
+    # ── Query builder shortcuts ───────────────────────────────────
+
     def select(*columns)
       QueryBuilder.new(@client, @table_name).select(*columns)
     end
 
-    # Start a query with a filter.
-    #
-    # @param column [String, Hash] Column name or filter hash
-    # @param operator [String, nil] Operator
-    # @param value [Object] Filter value
-    # @param logical_op [String] "AND" or "OR"
-    # @return [QueryBuilder] QueryBuilder for chaining
     def filter(column, operator = nil, value = nil, logical_op: 'AND')
       QueryBuilder.new(@client, @table_name).filter(column, operator, value, logical_op: logical_op)
     end
 
-    # Get all records with optional filters.
+    def eq(column, value)
+      QueryBuilder.new(@client, @table_name).eq(column, value)
+    end
+
+    def neq(column, value)
+      QueryBuilder.new(@client, @table_name).neq(column, value)
+    end
+
+    def gt(column, value)
+      QueryBuilder.new(@client, @table_name).gt(column, value)
+    end
+
+    def gte(column, value)
+      QueryBuilder.new(@client, @table_name).gte(column, value)
+    end
+
+    def lt(column, value)
+      QueryBuilder.new(@client, @table_name).lt(column, value)
+    end
+
+    def lte(column, value)
+      QueryBuilder.new(@client, @table_name).lte(column, value)
+    end
+
+    def order_by(column, direction = 'asc')
+      QueryBuilder.new(@client, @table_name).order_by(column, direction)
+    end
+
+    def limit(n)
+      QueryBuilder.new(@client, @table_name).limit(n)
+    end
+
+    def offset(n)
+      QueryBuilder.new(@client, @table_name).offset(n)
+    end
+
+    # ── Read ─────────────────────────────────────────────────────
+
+    # Retrieve all rows (with optional filter options forwarded to QueryBuilder#get).
     #
-    # @param options [Hash, nil] Query options
-    # @return [Hash] Query response
+    # @param options [Hash, nil] Reserved for compatibility; use chained methods instead
+    # @return [Hash] { data: Array, count: Integer, total: Integer, limit: Integer, offset: Integer }
     def get(options = nil)
       QueryBuilder.new(@client, @table_name).get(options)
     end
 
-    # Get a single record by ID.
+    # Retrieve a single row by primary key.
     #
-    # @param record_id [Object] Record ID
-    # @return [Hash] Record data
+    # @param record_id [String] Row UUID
+    # @return [Hash] Row data
     def get_by_id(record_id)
-      @client.request('GET', "/#{@table_name}/#{record_id}", nil, nil)
+      result = @client.request(
+        'GET', "/#{@table_name}",
+        { 'id' => "eq.#{record_id}" },
+        nil,
+        'Prefer' => 'return=representation'
+      )
+      data = normalise_data(result)
+      data.first
     end
 
-    # Create a new record.
+    # ── Write ────────────────────────────────────────────────────
+
+    # Insert a single row and return the created record.
     #
-    # @param data [Hash] Record data
-    # @return [Hash] Create response with new record ID
+    # @param data [Hash] Column→value map
+    # @return [Hash] Created row
     def create(data)
-      @client.request('POST', "/#{@table_name}", nil, data)
+      result = @client.request(
+        'POST', "/#{@table_name}", nil, data,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result).first || {}
     end
 
-    # Insert a new record (alias for create).
-    #
-    # @param data [Hash] Record data
-    # @return [Hash] Create response with new record ID
-    def insert(data)
-      create(data)
-    end
+    alias insert create
 
-    # Insert multiple records.
+    # Insert multiple rows.
     #
-    # Attempts a single batch POST first. Falls back to individual
-    # inserts if the server does not support batch creation.
-    #
-    # @param records [Array<Hash>] List of record hashes
-    # @return [Array<Hash>] List of create responses
+    # @param records [Array<Hash>] List of row hashes
+    # @return [Array<Hash>] Created rows
     def bulk_insert(records)
       return [] if records.nil? || records.empty?
 
-      begin
-        result = @client.request('POST', "/#{@table_name}", nil, records)
-        result.is_a?(Array) ? result : [result]
-      rescue StandardError
-        records.map { |record| create(record) }
-      end
+      result = @client.request(
+        'POST', "/#{@table_name}", nil, records,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result)
     end
 
     # Insert or update based on conflict column.
     #
-    # Uses PostgreSQL ON CONFLICT (upsert). Falls back to
-    # get-then-insert/update when the backend doesn't expose
-    # a native upsert endpoint.
-    #
-    # @param data [Hash] Record data (must include the conflict column)
-    # @param on_conflict [String] Column to check for conflicts (default: "id")
-    # @return [Hash] Create or update response
+    # @param data [Hash] Row data (must include the conflict column value)
+    # @param on_conflict [String] Column to detect conflicts on (default: "id")
+    # @return [Hash] Upserted row
     def upsert(data, on_conflict: 'id')
-      conflict_value = data[on_conflict] || data[on_conflict.to_sym]
-      return create(data) if conflict_value.nil?
-
-      existing = QueryBuilder.new(@client, @table_name).eq(on_conflict, conflict_value).first
-      if existing
-        update_data = data.reject { |k, _| k.to_s == on_conflict }
-        if update_data.empty?
-          { 'message' => 'No changes', 'affected_rows' => 0 }
-        else
-          update(conflict_value, update_data)
-        end
-      else
-        create(data)
-      end
+      result = @client.request(
+        'POST', "/#{@table_name}", nil, data,
+        'Prefer'             => 'return=representation,resolution=merge-duplicates',
+        'on-conflict-column' => on_conflict
+      )
+      normalise_data(result).first || {}
     end
 
-    # Update a record by ID.
+    # Update a row by ID.
     #
-    # @param record_id [Object] Record ID
-    # @param data [Hash] Data to update
-    # @return [Hash] Update response
+    # @param record_id [String] Row UUID
+    # @param data [Hash] Columns to update
+    # @return [Hash] Updated row
     def update(record_id, data)
-      @client.request('PATCH', "/#{@table_name}/#{record_id}", nil, data)
+      result = @client.request(
+        'PATCH', "/#{@table_name}",
+        { 'id' => "eq.#{record_id}" },
+        data,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result).first || {}
     end
 
-    # Delete a record by ID.
+    # Delete a row by ID.
     #
-    # @param record_id [Object] Record ID
-    # @return [Hash] Delete response
+    # @param record_id [String] Row UUID
+    # @return [Hash] Deleted row
     def delete(record_id)
-      @client.request('DELETE', "/#{@table_name}/#{record_id}", nil, nil)
-    end
-
-    # ── Convenience shortcuts ──────────────────────────────────
-
-    def eq(column, value)
-      QueryBuilder.new(@client, @table_name).eq(column, value)
-    end
-
-    def neq(column, value)
-      QueryBuilder.new(@client, @table_name).neq(column, value)
-    end
-
-    def gt(column, value)
-      QueryBuilder.new(@client, @table_name).gt(column, value)
-    end
-
-    def gte(column, value)
-      QueryBuilder.new(@client, @table_name).gte(column, value)
-    end
-
-    def lt(column, value)
-      QueryBuilder.new(@client, @table_name).lt(column, value)
+      result = @client.request(
+        'DELETE', "/#{@table_name}",
+        { 'id' => "eq.#{record_id}" },
+        nil,
+        'Prefer' => 'return=representation'
+      )
+      normalise_data(result).first || {}
     end
 
-    def lte(column, value)
-      QueryBuilder.new(@client, @table_name).lte(column, value)
-    end
+    # ── Aggregates / pagination ───────────────────────────────────
 
-    def order_by(column, direction = 'asc')
-      QueryBuilder.new(@client, @table_name).order_by(column, direction)
-    end
-
-    # Get total record count for this table.
-    #
-    # @return [Integer]
     def count
       QueryBuilder.new(@client, @table_name).count
     end
 
-    # Paginate all records in this table.
-    #
-    # @param page [Integer] Page number (1-indexed)
-    # @param per_page [Integer] Records per page
-    # @return [Hash]
     def paginate(page: 1, per_page: 20)
       QueryBuilder.new(@client, @table_name).paginate(page: page, per_page: per_page)
     end
+
+    private
+
+    def normalise_data(result)
+      case result
+      when Array then result
+      when Hash  then result['data'] || result['rows'] || (result.key?('id') ? [result] : [])
+      else            []
+      end
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wowsql-sdk
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.1.0
 platform: ruby
 authors:
 - WOWSQL Team