sequel-notion 0.2.0

data/lib/sequel/notion/filter_compiler.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "sequel/notion/filter_constants"
+require "sequel/notion/filter_tables"
+require "sequel/notion/filter_helpers"
+require "sequel/notion/filter_predicates"
+require "sequel/notion/filter_like_tokenizer"
+require "sequel/notion/filter_like"
+require "sequel/notion/filter_comparison"
+require "sequel/notion/filter_nested"
+require "sequel/notion/filter_negation"
+require "sequel/notion/filter_nulls"
+require "sequel/notion/filter_shape"
+
+module Sequel
+    module Notion
+        class FilterCompiler
+            include FilterConstants
+            include FilterHelpers
+            include FilterPredicates
+            include FilterLikeTokenizer
+            include FilterLike
+            include FilterComparison
+            include FilterNested
+            include FilterNegation
+            include FilterNulls
+            include FilterShape
+
+            # ----------------------------------------------------------
+            # Property name resolution (rule N)
+            # ----------------------------------------------------------
+            #
+            # Turns whatever Sequel hands us for a property reference into
+            # the plain String name Notion expects.
+            def self.property_name(expr)
+                case expr
+                when Symbol, String then return expr.to_s
+                when Sequel::SQL::Identifier then return expr.value.to_s
+                when Sequel::SQL::QualifiedIdentifier
+                    return property_name(expr.column)
+                end
+
+                raise Sequel::Error,
+                      "Unsupported property name expression: " \
+                      "#{expr.inspect}"
+            end
+
+            # The compiler for one data source of a Database
+            def self.for(db, ds_id)
+                new(db.property_type_map(ds_id), db.rollup_kinds(ds_id))
+            end
+
+            # schema: { "Status" => "status", "Name" => "title", ... };
+            # rollups: rollup name => the kind of value its function gives
+            # ("number", "date", or "array" for every value)
+            def initialize(schema, rollups = {})
+                @prop_types = schema
+                @rollups    = rollups
+            end
+
+            # The Notion filter for a WHERE: nil when every page meets it
+            # (send none), NOTHING when no page does (send no request)
+            def compile(expr)
+                filter = compile_node(expr)
+                return (filter.equal?(NOTHING) ? NOTHING : nil) if
+                    constant?(filter)
+
+                notion_shape(sql_nulls(filter))
+            end
+
+            private
+
+            def compile_node(expr) = compile_expr(unwrap_noop(expr))
+
+            def compile_expr(expr)
+                case expr
+                when Sequel::SQL::BooleanExpression then compile_boolean(expr)
+                when Sequel::SQL::ComplexExpression
+                    compile_comparison(expr)
+                when Symbol, Sequel::SQL::Identifier,
+                     Sequel::SQL::QualifiedIdentifier
+                    compile_bare_column(expr)
+                else
+                    raise Sequel::Error, "Unsupported filter: #{expr.class}"
+                end
+            end
+
+            # Sequel wraps some conditions in a one-argument NOOP
+            def unwrap_noop(expr)
+                while expr.is_a?(Sequel::SQL::BooleanExpression) &&
+                      expr.op == :NOOP && expr.args.size == 1
+                    expr = expr.args.first
+                end
+                expr
+            end
+
+            # AND/OR/NOT are rule N's boolean connectives; IS/IS NOT is
+            # Sequel's `Sequel.expr(col => nil/true/false)` form (rule I).
+            def compile_boolean(expr)
+                case expr.op
+                when :AND then all_of(expr.args.map { compile_node(it) })
+                when :OR then any_of(expr.args.map { compile_node(it) })
+                when :NOT then compile_not(expr.args.first)
+                when :IS, :"IS NOT" then compile_is(expr)
+                else
+                    compile_comparison(expr)
+                end
+            end
+
+            # Rule N's bare-column reading of NOT: `NOT checkbox_col` means
+            # the checkbox is false, not "negate whatever this compiles to".
+            def compile_not(inner)
+                if bare_column_expr?(inner)
+                    compile_bare_column(inner, value: false)
+                else
+                    negate(compile_node(inner))
+                end
+            end
+        end
+    end
+end

data/lib/sequel/notion/filter_constants.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Sequel
+    module Notion
+        # Conditions every page meets, or none does, mixed into
+        # FilterCompiler. An empty list compiles to one, as Sequel's SQL
+        # adapters read it (IN () is false, NOT IN () true); Notion has no
+        # such filter, so and/or fold them away, NOT swaps them, and only
+        # a whole filter can be one: no filter sent, or no request.
+        module FilterConstants
+            EVERYTHING = { "everything" => true }.freeze
+            NOTHING    = { "nothing" => true }.freeze
+
+            private
+
+            def constant?(filter)
+                filter.equal?(EVERYTHING) || filter.equal?(NOTHING)
+            end
+
+            def opposite(filter) = filter.equal?(NOTHING) ? EVERYTHING : NOTHING
+
+            # An and of compiled parts: NOTHING if one is, the EVERYTHING
+            # ones dropped; an or the other way round
+            def all_of(parts) = folded("and", parts, NOTHING, EVERYTHING)
+            def any_of(parts) = folded("or", parts, EVERYTHING, NOTHING)
+
+            def folded(op, parts, absorbing, neutral)
+                return absorbing if parts.any? { it.equal?(absorbing) }
+
+                rest = parts.reject { it.equal?(neutral) }
+                return neutral if rest.empty?
+
+                rest.one? ? rest.first : { op => rest }
+            end
+        end
+    end
+end

data/lib/sequel/notion/filter_helpers.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "date"
+
+require "sequel/notion/filter_tables"
+require "sequel/notion/type_map"
+
+module Sequel
+    module Notion
+        # Small shared helpers mixed into FilterCompiler: property/type
+        # lookups (rule N), column/literal recognition (rule S), and value
+        # coercion. All private; they rely on the host's @prop_types.
+        module FilterHelpers
+            private
+
+            # ----------------------------------------------------------
+            # Shared lookups
+            # ----------------------------------------------------------
+
+            def lookup_type!(name)
+                raise page_column_error(name) if
+                    TypeMap::PAGE_KEYS.include?(name)
+
+                @prop_types[name] or
+                    raise Sequel::Error,
+                          "Unknown property '#{name}'. " \
+                          "Available: #{@prop_types.keys.join(", ")}"
+            end
+
+            # id and in_trash are the page's own, no property to filter on
+            def page_column_error(name)
+                hint = ": look pages up by id alone, where(id: ...)" if
+                    name == "id"
+                Sequel::Error.new("'#{name}' is the page's own column, " \
+                                  "which Notion cannot filter on#{hint}")
+            end
+
+            def filter_key_for!(name, type)
+                FilterTables::FILTER_TYPE_KEY[type] or
+                    raise Sequel::Error,
+                          "Property '#{name}' (type: #{type}) is not " \
+                          "filterable"
+            end
+
+            def ensure_supported!(name, key, op)
+                ops = FilterTables::SUPPORTED_OPS.fetch(key, [])
+                return if ops.include?(op)
+
+                why = " (never empty)" if key == "unique_id" && op =~ /empty/
+                raise Sequel::Error, "Operator '#{op}' not supported for " \
+                                     "#{key} property '#{name}'#{why}"
+            end
+
+            def equal_to_contains(op)
+                case op
+                when "equals" then "contains"
+                when "does_not_equal" then "does_not_contain"
+                else op
+                end
+            end
+
+            # ----------------------------------------------------------
+            # Column / literal helpers (rule S)
+            # ----------------------------------------------------------
+
+            def column_expr?(x)
+                case x
+                when Symbol, String, Sequel::SQL::Identifier,
+                     Sequel::SQL::QualifiedIdentifier
+                    true
+                else
+                    false
+                end
+            end
+
+            def bare_column_expr?(x)
+                x.is_a?(Symbol) ||
+                    x.is_a?(Sequel::SQL::Identifier) ||
+                    x.is_a?(Sequel::SQL::QualifiedIdentifier)
+            end
+
+            # Sequel wraps a bare literal in a NOOP NumericExpression when it
+            # ends up as the receiver of a comparison operator inside a
+            # virtual row block (e.g. `5 < n`). Unwrap it back to the plain
+            # value.
+            def unwrap_literal(value)
+                if value.is_a?(Sequel::SQL::ComplexExpression) &&
+                   value.op == :NOOP && value.args.length == 1
+                    value.args.first
+                else
+                    value
+                end
+            end
+
+            # ----------------------------------------------------------
+            # Value coercion
+            # ----------------------------------------------------------
+
+            def boolean_value!(value)
+                return value if [true, false].include?(value)
+
+                raise Sequel::Error, "not a boolean: #{value.inspect}"
+            end
+
+            # Integer and Float as is; any other number as a Float, which
+            # JSON writes as a number (BigDecimal and Rational would not).
+            # JSON has no NaN or Infinity.
+            def number_value!(value)
+                number = case value
+                         when Integer, Float then value
+                         when Numeric then value.to_f
+                         when String then decimal_number!(value)
+                         else Float(value)
+                         end
+                return number if number.is_a?(Integer) || number.finite?
+
+                raise Sequel::Error, "not a number: #{value.inspect}"
+            rescue ArgumentError, TypeError, RangeError
+                raise Sequel::Error, "not a number: #{value.inspect}"
+            end
+
+            # Float() also accepts hex/binary/underscored strings; a
+            # number filter value is plain decimal text only
+            def decimal_number!(value)
+                raise Sequel::Error, "not a number: #{value.inspect}" unless
+                    value.match?(TypeMap::DECIMAL)
+
+                Float(value)
+            end
+
+            # A unique id's number, given bare or as displayed ("TK-62")
+            def unique_id_value!(value)
+                return value if value.is_a?(Integer) && !value.negative?
+
+                number = value.to_s[/\A(?:[A-Za-z][\w-]*-)?(\d+)\z/, 1]
+                return number.to_i if value.is_a?(String) && number
+
+                raise Sequel::Error, "not a unique id: #{value.inspect}"
+            end
+
+            # A Date, Time or DateTime, or an ISO 8601 string
+            def date_value!(value)
+                return value.iso8601 if value.respond_to?(:iso8601)
+                return value if value.is_a?(String) &&
+                                !Date._iso8601(value).empty?
+
+                raise Sequel::Error, "not a date: #{value.inspect}"
+            end
+
+            def coerce_value(value, key)
+                case key
+                when "date" then date_value!(value)
+                when "checkbox" then boolean_value!(value)
+                when "number" then number_value!(value)
+                when "unique_id" then unique_id_value!(value)
+                else
+                    value.to_s
+                end
+            end
+        end
+    end
+end

data/lib/sequel/notion/filter_like.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "sequel/notion/filter_tables"
+
+module Sequel
+    module Notion
+        # LIKE / ILIKE / NOT LIKE / NOT ILIKE compilation (rule L), mixed
+        # into FilterCompiler. All private.
+        #
+        # Notion does not distinguish case-sensitive from case-insensitive
+        # text matching, so LIKE and ILIKE (and their NOT variants) are
+        # treated identically here.
+        module FilterLike
+            # Carries the bits a LIKE-pattern error message needs, so the
+            # tokenizing/classifying helpers below stay under the parameter
+            # count limit.
+            LikeContext = Struct.new(:name, :sequel_op, :pattern)
+
+            private
+
+            def compile_like(expr)
+                left, pattern = expr.args
+                name = FilterCompiler.property_name(left)
+                validate_like_pattern!(pattern, name, expr.op)
+
+                type = lookup_type!(name)
+                key  = filter_key_for!(name, type)
+
+                op, value = translate_like_pattern(pattern, name, expr.op)
+                op = like_operator(op, key, name, expr)
+                ensure_supported!(name, key, op)
+
+                { "property" => name, key => { op => value } }
+            end
+
+            # The pattern's operator, negated for NOT LIKE and turned into
+            # contains for the types that compare through it
+            def like_operator(op, key, name, expr)
+                op = whole_value_like!(op, expr) if contains_type?(key)
+                op = negate_like_operator(op, name) if negated_like?(expr.op)
+                contains_type?(key) ? equal_to_contains(op) : op
+            end
+
+            # Notion's contains on a multi_select, people or relation
+            # matches a whole option or id, never a substring: only a
+            # pattern without wildcard means the same thing
+            def whole_value_like!(op, expr)
+                return op if op == "equals"
+
+                left, pattern = expr.args
+                raise Sequel::Error,
+                      "Unsupported #{expr.op} pattern for property " \
+                      "'#{FilterCompiler.property_name(left)}' (matches " \
+                      "whole values only, no wildcard): #{pattern.inspect}"
+            end
+
+            def validate_like_pattern!(pattern, name, sequel_op)
+                return if pattern.is_a?(String)
+
+                raise Sequel::Error,
+                      "Unsupported #{sequel_op} pattern for property " \
+                      "'#{name}': #{pattern.inspect}"
+            end
+
+            def negated_like?(sequel_op)
+                [:"NOT LIKE", :"NOT ILIKE"].include?(sequel_op)
+            end
+
+            def negate_like_operator(op, name)
+                case op
+                when "equals" then "does_not_equal"
+                when "contains" then "does_not_contain"
+                when "is_not_empty" then "is_empty"
+                when "starts_with", "ends_with"
+                    raise Sequel::Error,
+                          "Notion has no negated #{op} operator " \
+                          "(property '#{name}')"
+                else op
+                end
+            end
+
+            # Unescapes \% \_ \\ as literals, then classifies the remaining
+            # (unescaped) wildcards into a Notion text operator.
+            def translate_like_pattern(pattern, name, sequel_op)
+                ctx = LikeContext.new(name, sequel_op, pattern)
+                tokens = tokenize_like_pattern(pattern)
+                reject_underscore_wildcard!(tokens, ctx)
+
+                literal = like_literal(tokens)
+                wild_idxs = like_wildcard_indexes(tokens)
+
+                classify_like_wildcards(wild_idxs, tokens.length - 1,
+                                        literal, ctx)
+            end
+
+            def reject_underscore_wildcard!(tokens, ctx)
+                return unless tokens.any? { |t| t[0] == :underscore }
+
+                raise Sequel::Error,
+                      "Unsupported #{ctx.sequel_op} pattern for property " \
+                      "'#{ctx.name}' (unescaped '_' is not supported): " \
+                      "#{ctx.pattern.inspect}"
+            end
+
+            def like_literal(tokens)
+                tokens.select { it[0] == :lit }.map { it[1] }.join
+            end
+
+            def like_wildcard_indexes(tokens)
+                tokens.each_index.select { |idx| tokens[idx][0] == :wild }
+            end
+
+            def classify_like_wildcards(wild_idxs, last_idx, literal, ctx)
+                return ["is_not_empty", true] if
+                    literal.empty? && !wild_idxs.empty?
+
+                case wild_idxs
+                when [] then ["equals", literal]
+                when [0] then classify_leading_wildcard(last_idx, literal, ctx)
+                when [last_idx] then ["starts_with", literal]
+                when [0, last_idx] then ["contains", literal]
+                else
+                    raise unsupported_wildcard_error(ctx)
+                end
+            end
+
+            def classify_leading_wildcard(last_idx, literal, ctx)
+                # pattern was just "%"
+                raise unsupported_wildcard_error(ctx) if last_idx.zero?
+
+                ["ends_with", literal]
+            end
+
+            def unsupported_wildcard_error(ctx)
+                Sequel::Error.new(
+                    "Unsupported #{ctx.sequel_op} pattern for property " \
+                    "'#{ctx.name}' (unsupported wildcard placement): " \
+                    "#{ctx.pattern.inspect}"
+                )
+            end
+        end
+    end
+end

data/lib/sequel/notion/filter_like_tokenizer.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Sequel
+    module Notion
+        # Tokenizes a SQL LIKE pattern into literal/wildcard pieces, mixed
+        # into FilterCompiler. All private. Unescapes \% \_ \\ as literal
+        # characters; unescaped % and _ become :wild / :underscore markers.
+        module FilterLikeTokenizer
+            ESCAPABLE_LIKE_CHARS = %w[% _ \\].freeze
+
+            private
+
+            def tokenize_like_pattern(pattern)
+                tokens = []
+                chars = pattern.chars
+                i = 0
+                while i < chars.length
+                    token, consumed = next_like_token(chars, i)
+                    tokens << token
+                    i += consumed
+                end
+                tokens
+            end
+
+            def next_like_token(chars, i)
+                c = chars[i]
+                return [[:lit, chars[i + 1]], 2] if escaped_like_char?(chars, i)
+
+                case c
+                when "%" then [[:wild], 1]
+                when "_" then [[:underscore], 1]
+                else [[:lit, c], 1]
+                end
+            end
+
+            def escaped_like_char?(chars, i)
+                chars[i] == "\\" && i + 1 < chars.length &&
+                    ESCAPABLE_LIKE_CHARS.include?(chars[i + 1])
+            end
+        end
+    end
+end

data/lib/sequel/notion/filter_negation.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "sequel/notion/filter_tables"
+
+module Sequel
+    module Notion
+        # Filter negation (rule G), mixed into FilterCompiler. All private.
+        # Negates a compiled Notion filter hash by swapping and/or and
+        # inverting the leaf operator via the explicit NEGATE_MAP table.
+        module FilterNegation
+            private
+
+            def negate(filter)
+                return opposite(filter) if constant?(filter)
+                if filter.key?("and")
+                    return { "or" => negate_each(filter["and"]) }
+                end
+                if filter.key?("or")
+                    return { "and" => negate_each(filter["or"]) }
+                end
+
+                negate_leaf(filter)
+            end
+
+            def negate_each(filters)
+                filters.map { negate(it) }
+            end
+
+            def negate_leaf(filter)
+                type_key = (filter.keys - ["property"]).first
+                inner = filter[type_key]
+
+                if %w[formula rollup].include?(type_key)
+                    negate_nested_leaf(filter, type_key, inner)
+                else
+                    negate_simple_leaf(filter, type_key, inner)
+                end
+            end
+
+            def negate_nested_leaf(filter, key, inner)
+                inner_key = inner.keys.first
+                cond = inner[inner_key]
+                op = cond.keys.first
+                if inner_key == "date" && op == "equals"
+                    return nested_date_not_equal(filter["property"], key,
+                                                 cond[op])
+                end
+
+                new_op = negated_operator!(op, filter["property"])
+                { "property" => filter["property"],
+                  key => { inner_key => { new_op => cond[op] } } }
+            end
+
+            def negate_simple_leaf(filter, type_key, inner)
+                op = inner.keys.first
+                # Notion's date has no does_not_equal (rule D)
+                if type_key == "date" && op == "equals"
+                    return date_not_equal_filter(filter["property"], inner[op])
+                end
+
+                new_op = negated_operator!(op, filter["property"])
+
+                { "property" => filter["property"],
+                  type_key => { new_op => inner[op] } }
+            end
+
+            def negated_operator!(op, property)
+                FilterTables::NEGATE_MAP.fetch(op) do
+                    raise Sequel::Error,
+                          "Operator '#{op}' has no inverse " \
+                          "(property '#{property}')"
+                end
+            end
+        end
+    end
+end

data/lib/sequel/notion/filter_nested.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Sequel
+    module Notion
+        # Formula (rule F) and rollup (rule R) comparisons, mixed into
+        # FilterCompiler: the condition nested under the kind of value
+        # the property gives. All private.
+        module FilterNested
+            NESTED_KEYS = %w[formula rollup].freeze
+
+            private
+
+            def compile_nested_key(name, op, value, key)
+                inner_key = if key == "formula"
+                                formula_inner_key(value, name)
+                            else
+                                rollup_kind!(name)
+                            end
+                compile_nested_comparison(name, op, value, key, inner_key)
+            end
+
+            # IN on a formula, a rollup or a date: an or of equalities, or
+            # an and of inequalities, each compiled as a comparison (nested,
+            # or a date's before-or-after)
+            def in_by_value(sequel_op, name, values, key)
+                op = sequel_op == :IN ? :"=" : :"!="
+                leaves = values.map do |v|
+                    next null_check_filter(name, empty: op == :"=") if v.nil?
+
+                    compile_typed_comparison(name, op, v, key)
+                end
+                { (sequel_op == :IN ? "or" : "and") => leaves }
+            end
+
+            # Notion checks a formula's emptiness under any value key,
+            # whatever its result type (checked live); a rollup's under
+            # the kind it gives
+            def nested_null_filter(name, key, op)
+                inner = key == "formula" ? "string" : rollup_kind!(name)
+                { "property" => name, key => { inner => { op => true } } }
+            end
+
+            # A formula's kind follows the value's class
+            def formula_inner_key(value, name)
+                case value
+                when String then "string"
+                when Numeric then "number"
+                when true, false then "checkbox"
+                when Date, Time, DateTime then "date"
+                else
+                    raise Sequel::Error,
+                          "Unsupported formula value type for property " \
+                          "'#{name}': #{value.class}"
+                end
+            end
+
+            def compile_formula_comparison(name, op, value)
+                compile_nested_comparison(name, op, value, "formula",
+                                          formula_inner_key(value, name))
+            end
+
+            def compile_nested_comparison(name, op, value, key, inner_key)
+                coerced = coerce_value(value, inner_key)
+                if inner_key == "date" && op == :"!="
+                    return nested_date_not_equal(name, key, coerced)
+                end
+
+                notion_op = translated_operator(op, inner_key)
+                ensure_supported!(name, inner_key, notion_op)
+                { "property" => name,
+                  key => { inner_key => { notion_op => coerced } } }
+            end
+
+            # A rollup whose function gives one value; one that keeps
+            # every value is filtered by any/every/none in Notion, which a
+            # SQL comparison does not say
+            def rollup_kind!(name)
+                kind = @rollups[name]
+                return kind if %w[number date].include?(kind)
+
+                raise Sequel::Error,
+                      "Rollup '#{name}' gives #{kind || "an unknown"} " \
+                      "values; only number and date rollups filter"
+            end
+
+            # Notion's date has no does_not_equal (rule D)
+            def nested_date_not_equal(name, key, value)
+                { "or" => %w[before after].map do |op|
+                    { "property" => name, key => { "date" => { op => value } } }
+                end }
+            end
+        end
+    end
+end