sequel-notion 0.2.0

data/lib/sequel/notion/sort_compiler.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "sequel/notion/filter_compiler"
+require "sequel/notion/type_map"
+
+module Sequel
+    module Notion
+        module SortCompiler
+            module_function
+
+            def compile(order_clauses)
+                Array(order_clauses).map { |clause| compile_one(clause) }
+            end
+
+            def compile_one(clause)
+                case clause
+                when Sequel::LiteralString then raise literal_error(clause)
+                when Sequel::SQL::OrderedExpression then compile_ordered(clause)
+                when Symbol, String, Sequel::SQL::Identifier,
+                     Sequel::SQL::QualifiedIdentifier
+                    compile_ascending(clause)
+                else
+                    raise Sequel::Error,
+                          "Unsupported order expression: #{clause.class}"
+                end
+            end
+
+            # Sequel.lit is a String, but SQL, not a property name
+            def literal_error(clause)
+                Sequel::Error.new("Notion takes no SQL in an order: #{clause}")
+            end
+
+            # Notion sorts empty values last in either direction, so only
+            # NULLS LAST (or no NULLS clause) can be honoured
+            def compile_ordered(clause)
+                if clause.nulls == :first
+                    raise Sequel::Error,
+                          "Notion sorts empty values last: #{clause.inspect}"
+                end
+
+                direction = clause.descending ? "descending" : "ascending"
+                { "property" => sort_property(clause.expression),
+                  "direction" => direction }
+            end
+
+            def compile_ascending(clause)
+                { "property" => sort_property(clause),
+                  "direction" => "ascending" }
+            end
+
+            # Notion sorts by a property or a timestamp, never by the
+            # page's own id or in_trash, and rejects them with a 400
+            def sort_property(expr)
+                raise literal_error(expr) if expr.is_a?(Sequel::LiteralString)
+
+                name = FilterCompiler.property_name(expr)
+                return name unless TypeMap::PAGE_KEYS.include?(name)
+
+                raise Sequel::Error, "Notion cannot sort by #{name}"
+            end
+        end
+    end
+end

data/lib/sequel/notion/type_map.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "notion_file"
+require_relative "type_map_builders"
+require_relative "type_map_dates"
+require_relative "type_map_extractors"
+
+module Sequel
+    module Notion
+        module TypeMap
+            module_function
+
+            # Notion property types that the Notion API never accepts on write.
+            READ_ONLY_TYPES = %w[
+                formula rollup created_time last_edited_time
+                created_by last_edited_by unique_id button verification
+            ].freeze
+
+            # Keys every row carries for the page itself; a property of
+            # the same name would overwrite them
+            PAGE_KEYS = %w[id in_trash].freeze
+
+            # Writable Notion type => the builder for its value
+            BUILDERS = {
+                "title" => :build_rich_text,
+                "rich_text" => :build_rich_text,
+                "number" => :build_number,
+                "select" => :build_select,
+                "status" => :build_select,
+                "multi_select" => :build_multi_select,
+                "date" => :build_date,
+                "checkbox" => :build_checkbox,
+                "url" => :build_string,
+                "email" => :build_string,
+                "phone_number" => :build_string,
+                "relation" => :build_relation,
+                "people" => :build_people,
+                "files" => :build_files
+            }.freeze
+
+            # Notion page → flat Ruby hash
+            def page_to_row(page)
+                row   = { id: page["id"], in_trash: page["in_trash"] }
+                props = page["properties"] || {}
+                check_property_names!(props.keys)
+
+                props.each do |name, prop|
+                    row[name.to_sym] = extract_value(prop)
+                end
+
+                row
+            end
+
+            # Flat Ruby hash → Notion properties payload
+            #
+            # +prop_types+ maps property NAME (String) to Notion TYPE
+            # (String), e.g. {"Name" => "title", "Status" => "status"}.
+            # +hash+ keys may be Symbols or Strings.
+            def row_to_properties(hash, prop_types)
+                hash.each_with_object({}) do |(key, value), props|
+                    name = key.to_s
+                    type = prop_types[name]
+                    ensure_known_property(name, type, prop_types)
+                    props[name] = build_named_property(name, value, type)
+                end
+            end
+
+            def check_property_names!(names)
+                clash = names & PAGE_KEYS
+                return if clash.empty?
+
+                raise Sequel::Error,
+                      "property #{clash.first.inspect} clashes with the " \
+                      "page's own column; rename it in Notion"
+            end
+
+            def ensure_known_property(name, type, prop_types)
+                return if type
+
+                raise Sequel::Error,
+                      "unknown property #{name.inspect}; " \
+                      "available: #{prop_types.keys.sort.inspect}"
+            end
+
+            # build_property, wrapped so a failure names the property.
+            def build_named_property(name, value, type)
+                build_property(value, type)
+            rescue Sequel::Error => e
+                raise Sequel::Error,
+                      "property #{name.inspect} (#{type.inspect}): " \
+                      "#{e.message}"
+            end
+
+            # ----------------------------------------------------------
+            # Notion → Ruby
+            # ----------------------------------------------------------
+
+            def extract_value(prop)
+                type = prop["type"]
+                extractor = EXTRACTORS[type]
+                return send(extractor, prop) if extractor
+
+                prop[type]
+            end
+
+            # ----------------------------------------------------------
+            # Ruby → Notion
+            # ----------------------------------------------------------
+
+            # Build a single Notion property payload for +value+ given its
+            # Notion +type+. Returns {TYPE => value}.
+            def build_property(value, type)
+                builder = BUILDERS[type]
+                return { type => send(builder, value) } if builder
+
+                if READ_ONLY_TYPES.include?(type)
+                    raise Sequel::Error,
+                          "property type #{type.inspect} is read-only"
+                end
+
+                raise Sequel::Error, "unsupported property type #{type.inspect}"
+            end
+        end
+    end
+end

data/lib/sequel/notion/type_map_builders.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require_relative "notion_file"
+
+# Ruby → Notion builders for Sequel::Notion::TypeMap, split out here to
+# keep type_map.rb's module short. See BUILDERS in type_map.rb for the
+# Notion type => builder mapping that dispatches to these.
+
+module Sequel
+    module Notion
+        module TypeMap
+            # Float() also accepts hex ("0x1A"), binary ("0b11") and
+            # underscore-grouped ("1_000") strings; a Notion number
+            # property is plain decimal text only.
+            DECIMAL = /\A\s*[+-]?(\d+(\.\d*)?|\.\d+)([eE][+-]?\d+)?\s*\z/
+
+            module_function
+
+            def build_string(value) = value&.to_s
+
+            # title / rich_text: to_s, split into text objects of at most
+            # 2000 characters each, as Notion counts them (UTF-16 units)
+            def build_rich_text(value)
+                text_runs(value.to_s).map do |run|
+                    { "type" => "text", "text" => { "content" => run } }
+                end
+            end
+
+            # A character outside the BMP counts two and is never split
+            def text_runs(str)
+                units = 0
+                str.each_char.slice_before do |c|
+                    n = c.ord > 0xFFFF ? 2 : 1
+                    (units += n) > 2000 && (units = n)
+                end.map(&:join)
+            end
+
+            def build_number(value)
+                case value
+                when nil then nil
+                when Integer then value
+                when Float then finite_number(value)
+                when Numeric then finite_number(value.to_f)
+                when String then parse_number(value)
+                else raise Sequel::Error, "invalid number: #{value.inspect}"
+                end
+            rescue RangeError # a Complex has no Float
+                raise Sequel::Error, "invalid number: #{value.inspect}"
+            end
+
+            # JSON has no NaN or Infinity
+            def finite_number(value)
+                return value if value.finite?
+
+                raise Sequel::Error, "invalid number: #{value.inspect}"
+            end
+
+            # Float overflows "1e400" to Infinity instead of raising; it
+            # also accepts hex/binary/underscored strings DECIMAL refuses
+            def parse_number(value)
+                raise Sequel::Error, "invalid number: #{value.inspect}" unless
+                    value.match?(DECIMAL)
+
+                finite_number(Float(value))
+            rescue ArgumentError
+                raise Sequel::Error, "invalid number: #{value.inspect}"
+            end
+
+            def build_select(value)
+                return nil if value.nil?
+
+                { "name" => value.to_s }
+            end
+
+            def build_multi_select(value)
+                list(value).map { { "name" => it.to_s } }
+            end
+
+            def build_checkbox(value)
+                case value
+                when true, false
+                    value
+                when nil
+                    false
+                else
+                    raise Sequel::Error,
+                          "invalid checkbox value: #{value.inspect}"
+                end
+            end
+
+            # One id or an Array of them; nil is none
+            def build_relation(value) = list(value).map { { "id" => it } }
+
+            def build_people(value)
+                list(value).map { { "object" => "user", "id" => it } }
+            end
+
+            # One item or an Array of them; nil is none. Array() would
+            # turn a Hash into its pairs.
+            def list(value)
+                if value.is_a?(Hash)
+                    raise Sequel::Error, "a list of names or ids takes no " \
+                                         "Hash: #{value.inspect}"
+                end
+
+                Array(value)
+            end
+
+            def build_files(value)
+                return [] if value.nil?
+
+                items = value.is_a?(Array) ? value : [value]
+                items.map { |item| build_file(item) }
+            end
+
+            def build_file(item)
+                case item
+                when File then item.to_notion
+                when String then File.external(item).to_notion
+                else raise Sequel::Error, "invalid file value: #{item.inspect}"
+                end
+            end
+        end
+    end
+end

data/lib/sequel/notion/type_map_dates.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "date"
+
+# Ruby → Notion date builders for Sequel::Notion::TypeMap, split out of
+# type_map_builders.rb to keep that module short.
+
+module Sequel
+    module Notion
+        module TypeMap
+            module_function
+
+            def build_date(value)
+                case value
+                when nil then nil
+                when String then { "start" => value }
+                when Range then build_date_range(value)
+                when Date, Time, DateTime then { "start" => value.iso8601 }
+                when Hash then build_date_hash(value)
+                else raise Sequel::Error, "invalid date value: #{value.inspect}"
+                end
+            end
+
+            # Notion's date needs a start; an endless range leaves the end open
+            def build_date_range(value)
+                if value.begin.nil?
+                    raise Sequel::Error,
+                          "a date range needs a start: #{value.inspect}"
+                end
+
+                { "start" => date_component(value.begin),
+                  "end" => date_component(inclusive_end(value)) }
+            end
+
+            # Notion's end is inclusive: an exclusive range ends the day
+            # before, which only a Date end can say
+            def inclusive_end(range)
+                last = range.end
+                return last if last.nil? || !range.exclude_end?
+                return last.prev_day if last.instance_of?(Date)
+
+                raise Sequel::Error,
+                      "an exclusive date range must end on a Date: " \
+                      "#{range.inspect}"
+            end
+
+            # Like a Range, a Hash needs a start; nil is how a date is cleared
+            def build_date_hash(value)
+                start_v = value.key?(:start) ? value[:start] : value["start"]
+                end_v = value.key?(:end) ? value[:end] : value["end"]
+
+                if start_v.nil?
+                    raise Sequel::Error,
+                          "a date needs a start: #{value.inspect}"
+                end
+
+                result = { "start" => date_component(start_v) }
+                result["end"] = date_component(end_v) unless end_v.nil?
+                result
+            end
+
+            def date_component(value)
+                value.respond_to?(:iso8601) ? value.iso8601 : value
+            end
+        end
+    end
+end

data/lib/sequel/notion/type_map_extractors.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "notion_file"
+
+# Notion → Ruby extractors for Sequel::Notion::TypeMap, split out here to
+# keep type_map.rb's module short. Types not listed in EXTRACTORS fall
+# back to extract_value's default: prop[prop["type"]].
+
+module Sequel
+    module Notion
+        module TypeMap
+            module_function
+
+            # Notion type => the extractor for its property hash. Only
+            # types whose value needs more than a plain prop[type] lookup
+            # are listed; see extract_value in type_map.rb for the rest.
+            EXTRACTORS = {
+                "title" => :extract_rich_text,
+                "rich_text" => :extract_rich_text,
+                "select" => :extract_select,
+                "status" => :extract_select,
+                "multi_select" => :extract_multi_select,
+                "date" => :extract_date,
+                "people" => :extract_people,
+                "relation" => :extract_relation,
+                "formula" => :extract_formula,
+                "files" => :extract_files,
+                "unique_id" => :extract_unique_id,
+                "rollup" => :extract_rollup
+            }.freeze
+
+            def extract_rich_text(prop)
+                prop[prop["type"]]&.map { it["plain_text"] }&.join
+            end
+
+            def extract_select(prop)
+                prop.dig(prop["type"], "name")
+            end
+
+            def extract_multi_select(prop)
+                prop["multi_select"]&.map { it["name"] }
+            end
+
+            # The start, or a Range of Strings when there is an end: the
+            # Range a write takes
+            def extract_date(prop)
+                date = prop["date"] || {}
+                return date["start"] unless date["end"]
+
+                date["start"]..date["end"]
+            end
+
+            # Its value: a number or date, or an Array of the rolled-up
+            # values, each read as its own type
+            def extract_rollup(prop)
+                inner = prop["rollup"]
+                return if inner.nil?
+                return inner["array"].map { extract_value(it) } if
+                    inner["type"] == "array"
+
+                extract_value(inner)
+            end
+
+            # As Notion displays it: "TK-62", or "62" with no prefix
+            def extract_unique_id(prop)
+                id = prop["unique_id"] || {}
+                return if id["number"].nil?
+
+                [id["prefix"], id["number"]].compact.join("-")
+            end
+
+            def extract_people(prop)
+                prop["people"]&.map { it["id"] }
+            end
+
+            def extract_relation(prop)
+                prop["relation"]&.map { it["id"] }
+            end
+
+            def extract_formula(prop)
+                extract_value(prop["formula"])
+            end
+
+            def extract_files(prop)
+                File.from_notion_property(prop)
+            end
+        end
+    end
+end

data/lib/sequel/notion/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Sequel
+    module Notion
+        VERSION = "0.2.0"
+    end
+end

data/lib/sequel/notion.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point for `require "sequel/notion"` and Bundler's auto-require;
+# Sequel itself loads the adapter on `Sequel.connect(adapter: :notion)`.
+require "sequel/adapters/notion"

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: sequel-notion
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Stéphane D'Alu
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sequel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: A Sequel database adapter that maps Notion databases and data sources
+  to Sequel's Dataset interface. Supports multi-source databases, filtering, sorting,
+  pagination, and CRUD operations via the Notion API (2026-03-11).
+email:
+- sdalu@sdalu.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/sequel/adapters/notion.rb
+- lib/sequel/notion.rb
+- lib/sequel/notion/dataset.rb
+- lib/sequel/notion/dataset_aggregates.rb
+- lib/sequel/notion/dataset_compounds.rb
+- lib/sequel/notion/dataset_computed.rb
+- lib/sequel/notion/dataset_grouping.rb
+- lib/sequel/notion/dataset_having.rb
+- lib/sequel/notion/dataset_joins.rb
+- lib/sequel/notion/dataset_pages.rb
+- lib/sequel/notion/dataset_selection.rb
+- lib/sequel/notion/dataset_truncation.rb
+- lib/sequel/notion/discovery.rb
+- lib/sequel/notion/errors.rb
+- lib/sequel/notion/filter_comparison.rb
+- lib/sequel/notion/filter_compiler.rb
+- lib/sequel/notion/filter_constants.rb
+- lib/sequel/notion/filter_helpers.rb
+- lib/sequel/notion/filter_like.rb
+- lib/sequel/notion/filter_like_tokenizer.rb
+- lib/sequel/notion/filter_negation.rb
+- lib/sequel/notion/filter_nested.rb
+- lib/sequel/notion/filter_nulls.rb
+- lib/sequel/notion/filter_predicates.rb
+- lib/sequel/notion/filter_shape.rb
+- lib/sequel/notion/filter_tables.rb
+- lib/sequel/notion/group_accumulator.rb
+- lib/sequel/notion/join_output.rb
+- lib/sequel/notion/join_where.rb
+- lib/sequel/notion/model_support.rb
+- lib/sequel/notion/notion_file.rb
+- lib/sequel/notion/page_api.rb
+- lib/sequel/notion/registry.rb
+- lib/sequel/notion/request_budget.rb
+- lib/sequel/notion/schema.rb
+- lib/sequel/notion/schema_lookup.rb
+- lib/sequel/notion/sort_compiler.rb
+- lib/sequel/notion/type_map.rb
+- lib/sequel/notion/type_map_builders.rb
+- lib/sequel/notion/type_map_dates.rb
+- lib/sequel/notion/type_map_extractors.rb
+- lib/sequel/notion/version.rb
+homepage: https://github.com/sdalu/sequel-notion
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sdalu/sequel-notion
+  changelog_uri: https://github.com/sdalu/sequel-notion/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Sequel adapter for Notion data sources
+test_files: []