pglpg 0.2.0 → 0.4.0

data/lib/pglpg/schema/element_type.rb

@@ -10,16 +10,21 @@ module Pglpg
       name.to_sym
     end
 
-    # Shared by node and edge types: declared properties. Types are closed:
-    # a property that is not declared is rejected.
+    # Declared properties stay typed. Explicit open types also accept a
+    # restricted JSON-native value set without guessing a schema for extras.
     class ElementType
       attr_reader :name
 
-      def initialize(name)
+      def initialize(name, open: false)
+        raise SchemaError, "open: must be true or false" unless open.equal?(true) || open.equal?(false)
+
         @name = Schema.check_name!(name, "type")
         @own_properties = {}
+        @open = open
       end
 
+      def open? = @open
+
       def property(name, type, required: false, values: nil, of: nil)
         name = Schema.check_name!(name, "property")
         raise SchemaError, "#{self.name}.#{name} is declared twice" if @own_properties.key?(name)
@@ -36,20 +41,50 @@ module Pglpg
 
       def required_properties = properties.values.select(&:required?)
 
+      # @api private
+      # Construction-only resolution; the descriptor is frozen afterwards.
+      def resolve_open!(columns, parents: [])
+        @open ||= parents.any?(&:open?)
+        @extra_reserved_names = (Column::RESERVED + Temporal::NAMES + columns.keys).uniq.freeze
+      end
+
+      # Normalize before the writer generates/merges keys, so ambiguous
+      # String/Symbol aliases cannot disappear before validation.
+      # @api private
+      def normalize_properties(props)
+        return (props || {}).transform_keys(&:to_sym) unless open?
+
+        (props || {}).each_with_object({}) do |(name, value), out|
+          unless (name.is_a?(String) || name.is_a?(Symbol)) && name.to_s.match?(NAME_FORMAT)
+            raise ValidationError, "invalid open property name"
+          end
+          name = name.to_sym
+          raise ValidationError, "duplicate property #{name}" if out.key?(name)
+          if !properties.key?(name) && @extra_reserved_names.include?(name)
+            raise ValidationError, "#{name} is reserved and cannot be an extra property"
+          end
+
+          out[name] = value
+        end
+      end
+
       # Validates +props+ and returns the JSON hash to store. nil values are
       # dropped (null means absent). With +partial+, required properties may be
       # missing but may not be set to nil.
       def encode_properties(props, partial: false)
-        props = (props || {}).transform_keys(&:to_sym)
+        props = normalize_properties(props)
         unknown = props.keys - properties.keys
-        raise ValidationError, "#{name} has no propert#{unknown.size == 1 ? "y" : "ies"} #{unknown.join(", ")}" if unknown.any?
+        if !open? && unknown.any?
+          raise ValidationError, "#{name} has no propert#{unknown.size == 1 ? "y" : "ies"} #{unknown.join(", ")}"
+        end
 
         required_properties.each do |p|
           next if partial && !props.key?(p.name)
           raise ValidationError, "#{name}.#{p.name} is required" if props[p.name].nil?
         end
         props.each_with_object({}) do |(k, v), out|
-          encoded = properties.fetch(k).encode(v)
+          prop = properties[k]
+          encoded = prop ? prop.encode(v) : encode_extra(v)
           out[k.to_s] = encoded unless encoded.nil?
         end
       end
@@ -57,9 +92,47 @@ module Pglpg
       def decode_properties(json)
         (json || {}).each_with_object({}) do |(k, v), out|
           prop = properties[k.to_sym]
-          out[k.to_sym] = prop ? prop.decode(v) : v
+          out[k.to_sym] = prop ? prop.decode(v) : freeze_extra(v)
         end.freeze
       end
+
+      private
+
+      def encode_extra(value)
+        return nil if value.nil?
+        return encode_extra_scalar(value) unless value.instance_of?(Array)
+
+        kinds = value.map { (_1.equal?(true) || _1.equal?(false)) ? :boolean : _1.class }.uniq
+        raise ValidationError, "extra property lists must be homogeneous scalar arrays" if kinds.size > 1
+
+        value.map { encode_extra_scalar(_1) }
+      end
+
+      def encode_extra_scalar(value)
+        if value.instance_of?(String)
+          begin
+            text = value.encode(Encoding::UTF_8)
+          rescue EncodingError
+            raise ValidationError, "extra property strings must be valid UTF-8"
+          end
+          raise ValidationError, "extra property strings must be valid UTF-8" unless text.valid_encoding?
+          raise ValidationError, "extra property strings cannot contain NUL" if text.include?("\0")
+
+          return text
+        end
+        return value if value.instance_of?(Integer) || value.equal?(true) || value.equal?(false)
+        return value if value.instance_of?(Float) && value.finite?
+
+        raise ValidationError, "extra property values must be JSON-native scalars or homogeneous scalar arrays"
+      end
+
+      def freeze_extra(value)
+        case value
+        when Array then value.each { freeze_extra(_1) }
+        when Hash then value.each { |key, child| freeze_extra(key); freeze_extra(child) }
+        end
+        value.freeze
+      end
     end
   end
 end

data/lib/pglpg/schema/graph_type.rb

@@ -27,9 +27,15 @@ module Pglpg
         node_types.values.select { _1.label?(label) }
       end
 
+      def temporal? = edge_types.values.any?(&:temporal?)
+
       def resolve!
         node_types.each_value { _1.resolve!(self) }
         edge_types.each_value { _1.resolve!(self) }
+        if temporal?
+          collisions = (node_columns.keys + edge_columns.keys + node_types.values.flat_map { _1.properties.keys } + edge_types.values.flat_map { _1.properties.keys }) & Temporal::NAMES
+          raise SchemaError, "reserved temporal names: #{collisions.join(", ")}" unless collisions.empty?
+        end
         [node_types, edge_types, node_columns, edge_columns].each(&:freeze)
         freeze
       end
@@ -41,19 +47,19 @@ module Pglpg
         @graph_type = graph_type
       end
 
-      def node(name, extends: [], abstract: false, &block)
-        type = NodeType.new(name, extends:, abstract:)
+      def node(name, extends: [], abstract: false, open: false, &block)
+        type = NodeType.new(name, extends:, abstract:, open:)
         raise SchemaError, "type #{type.name} is declared twice" if declared?(type.name)
 
         NodeBuilder.new(type).instance_eval(&block) if block
         @graph_type.node_types[type.name] = type
       end
 
-      def edge(name, from:, to:, unique: nil, symmetric: false, allow_self_loops: false, temporal: false, &block)
-        type = EdgeType.new(name, from:, to:, unique:, symmetric:, allow_self_loops:, temporal:)
+      def edge(name, from:, to:, unique: nil, symmetric: false, allow_self_loops: false, temporal: false, open: false, &block)
+        type = EdgeType.new(name, from:, to:, unique:, symmetric:, allow_self_loops:, temporal:, open:)
         raise SchemaError, "type #{type.name} is declared twice" if declared?(type.name)
 
-        ElementBuilder.new(type).instance_eval(&block) if block
+        EdgeBuilder.new(type).instance_eval(&block) if block
         @graph_type.edge_types[type.name] = type
       end
 
@@ -89,12 +95,20 @@ module Pglpg
       end
     end
 
+    class EdgeBuilder < ElementBuilder
+      def key(*names, generate: nil, scope: nil)
+        raise SchemaError, "Edge scope: is not supported" unless scope.nil?
+
+        @type.key_property(*names, generate:)
+      end
+    end
+
     class NodeBuilder < ElementBuilder
       # Declares an exclusive key. Interactive inserts get a value from
       # +generate+ (default: a random UUID). Scoped keys may be caller-chosen
       # with an explicit key_scope_allowed grant.
-      def key(name, generate: nil, scope: nil)
-        @type.key_property(name, generate:, scope:)
+      def key(*names, generate: nil, scope: nil)
+        @type.key_property(*names, generate:, scope:)
       end
     end
   end

data/lib/pglpg/schema/key.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Pglpg
+  module Schema
+    # One required, immutable property tuple. Shared by schema validation,
+    # index generation and ON CONFLICT so their equality cannot diverge.
+    class Key
+      TYPES = %i[string integer boolean enum].freeze
+      DEFAULT_GENERATOR = ->(_type) { SecureRandom.uuid }
+
+      attr_reader :properties, :declared_on, :scope, :generator
+
+      def initialize(names, declared_on:, generate: nil, scope: nil, generation: true)
+        @names = names.map { Schema.check_name!(_1, "key property") }.freeze
+        raise SchemaError, "a key needs distinct properties" if @names.empty? || @names.uniq != @names
+        raise SchemaError, "scope needs a single key property" if scope && @names.size != 1
+        raise SchemaError, "key generator must respond to call" if generate && !generate.respond_to?(:call)
+        raise SchemaError, "composite keys cannot have a generator" if generate && @names.size != 1
+
+        @scope = scope && Schema.check_name!(scope, "key scope")
+        @properties = [@scope, *@names].compact.freeze
+        raise SchemaError, "scope must differ from key property" if @properties.uniq != @properties
+        raise SchemaError, "key has too many components" if @properties.size > 32
+
+        @declared_on = declared_on
+        @generator = generate
+        @generation = generation
+      end
+
+      # Legacy single/scoped keys expose their generated property.
+      def property = @names.size == 1 ? @names.first : nil
+
+      def generated? = !generator.nil?
+
+      def generate(type) = generator.call(type)
+
+      def resolve!(type)
+        properties.each do |name|
+          prop = type.properties[name]
+          raise SchemaError, "key #{declared_on}.#{name} is not a declared property" unless prop
+          unless prop.required? && TYPES.include?(prop.type)
+            raise SchemaError, "key #{declared_on}.#{name} must be a required #{TYPES.join('/')} property"
+          end
+        end
+        if scope && properties.any? { type.properties.fetch(_1).type != :string }
+          raise SchemaError, "scoped keys require string properties"
+        end
+        if @generator && type.properties.fetch(property).type != :string
+          raise SchemaError, "only single string keys can have generators"
+        end
+        if @generation && property && type.properties.fetch(property).type == :string
+          @generator ||= DEFAULT_GENERATOR
+        end
+        @types = properties.to_h { [_1, type.properties.fetch(_1).type] }.freeze
+        freeze
+      end
+
+      def json_component?(name) = %i[integer boolean].include?(@types.fetch(name))
+
+      def expressions(connection)
+        properties.map do |name|
+          operator = json_component?(name) ? "->" : "->>"
+          "(properties#{operator}#{connection.quote(name.to_s)})"
+        end
+      end
+
+      # Lookups accept literal complete keys, never query operators/arrays/nil.
+      def validate_values!(type, values)
+        unless values.keys.sort == properties.sort
+          raise ArgumentError, "#{declared_on} requires the complete key #{properties.inspect}"
+        end
+        properties.each do |name|
+          raise ValidationError, "#{declared_on}.#{name} is required" if values[name].nil?
+
+          type.properties.fetch(name).encode(values[name])
+        end
+      end
+    end
+  end
+end

data/lib/pglpg/schema/node_type.rb

@@ -1,27 +1,14 @@
 # frozen_string_literal: true
 
-require "securerandom"
-
 module Pglpg
   module Schema
     # A node type: a key label, inherited labels and property types
     # (GQL node types, PG-Schema inheritance).
     class NodeType < ElementType
-      # An exclusive, mandatory string key, optionally scoped by another
-      # required string property. Caller-chosen scoped keys need an explicit
-      # occupancy grant; omitted keys use +generator+.
-      Key = Struct.new(:property, :declared_on, :generator, :scope, keyword_init: true) do
-        def properties = [scope, property].compact.freeze
-
-        def generate(type) = generator.call(type)
-      end
-
-      DEFAULT_KEY_GENERATOR = ->(_type) { SecureRandom.uuid }
-
       attr_reader :parents, :labels, :key, :ancestors
 
-      def initialize(name, extends: [], abstract: false)
-        super(name)
+      def initialize(name, extends: [], abstract: false, open: false)
+        super(name, open:)
         @parents = Array(extends).map { Schema.check_name!(_1, "type") }.freeze
         @abstract = abstract ? true : false
         @own_key = nil
@@ -29,11 +16,10 @@ module Pglpg
 
       def abstract? = @abstract
 
-      def key_property(name, generate: nil, scope: nil)
+      def key_property(*names, generate: nil, scope: nil)
         raise SchemaError, "#{self.name} declares more than one key" if @own_key
-        raise SchemaError, "key generator for #{self.name} must respond to call" if generate && !generate.respond_to?(:call)
 
-        @own_key = Key.new(property: name.to_sym, declared_on: self.name, generator: generate || DEFAULT_KEY_GENERATOR, scope: scope && Schema.check_name!(scope, "key scope"))
+        @own_key = Key.new(names, declared_on: self.name, generate:, scope:)
       end
 
       def own_key = @own_key
@@ -51,6 +37,7 @@ module Pglpg
         @ancestors = parent_types.flat_map { [_1.name, *_1.ancestors] }.uniq.freeze
         @labels = ([name] + @ancestors).map(&:to_s).sort.freeze
         @properties = merge_properties(parent_types)
+        resolve_open!(graph_type.node_columns, parents: parent_types)
         @key = resolve_key(parent_types)
         @resolved = true
         freeze
@@ -82,19 +69,8 @@ module Pglpg
         key = keys.first
         return nil unless key
 
-        prop = @properties[key.property]
-        raise SchemaError, "key #{key.declared_on}.#{key.property} is not a declared property" unless prop
-        raise SchemaError, "key #{key.declared_on}.#{key.property} must be required" unless prop.required?
-        raise SchemaError, "key #{key.declared_on}.#{key.property} must be a string" unless prop.type == :string
-
-        if key.scope
-          raise SchemaError, "scope must differ from key property" if key.scope == key.property
-          scope = @properties[key.scope]
-          unless scope && scope.required? && scope.type == :string
-            raise SchemaError, "key scope #{key.scope} must be a declared required string property"
-          end
-        end
-        key.freeze
+        # Inherited descriptors are already resolved and immutable.
+        key.frozen? ? key : key.resolve!(self)
       end
     end
   end

data/lib/pglpg/storage.rb

@@ -60,7 +60,7 @@ module Pglpg
             source_id bigint NOT NULL REFERENCES #{n} (id) ON DELETE RESTRICT,
             target_id bigint NOT NULL REFERENCES #{n} (id) ON DELETE RESTRICT,
             properties jsonb NOT NULL DEFAULT '{}',
-            #{columns_sql(connection, type.edge_columns)}created_at timestamptz NOT NULL DEFAULT now(),
+            #{type.temporal? ? "valid_from date, valid_to date, " : ""}#{columns_sql(connection, type.edge_columns)}created_at timestamptz NOT NULL DEFAULT now(),
             updated_at timestamptz NOT NULL DEFAULT now(),
             CHECK (jsonb_typeof(properties) = 'object')
           )
@@ -83,18 +83,29 @@ module Pglpg
       type.node_types.each_value do |t|
         has_label = "labels @> ARRAY[#{connection.quote(t.name.to_s)}]::text[]"
         if (key = t.own_key)
-          expressions = key.properties.map { "(properties->>#{connection.quote(_1.to_s)})" }.join(", ")
-          list << [:index, nodes_table, "key_#{t.name}_#{key.property}",
+          expressions = key.expressions(connection).join(", ")
+          list << [:index, nodes_table, "key_#{t.name}_#{key.property || key.properties.join("_")}",
                    "ON #{n} (#{expressions}) WHERE #{has_label}"]
         end
+        key_component_checks(list, connection, nodes_table, t, t.own_key, has_label) if t.own_key
         t.own_properties.each_value.select(&:required?).each do |p|
           list << [:check, nodes_table, "req_#{t.name}_#{p.name}", "NOT (#{has_label}) OR #{typed_check(connection, p)}"]
         end
       end
 
+      temporal_storage = type.temporal? || temporal_columns?(connection)
       type.edge_types.each_value do |t|
         is_type = "type = #{connection.quote(t.name.to_s)}"
-        list << [:index, edges_table, "pair_#{t.name}", "ON #{e} (source_id, target_id) WHERE #{is_type}"] if t.unique_pair?
+        list << [:check, edges_table, "validity_#{t.name}", temporal_check(connection, t)] if temporal_storage
+        if t.unique_tuple?
+          expressions = ["source_id", "target_id", *(t.pair_key&.expressions(connection) || [])].join(", ")
+          list << [:index, edges_table, "pair_#{t.name}", "ON #{e} (#{expressions}) WHERE #{is_type}"]
+        end
+        if t.key
+          list << [:index, edges_table, "key_#{t.name}_#{t.key.properties.join("_")}",
+                   "ON #{e} (#{t.key.expressions(connection).join(", ")}) WHERE #{is_type}"]
+        end
+        [t.key, t.pair_key].compact.each { key_component_checks(list, connection, edges_table, t, _1, is_type) }
         if t.symmetric?
           # Canonical orientation, so a pair is stored one way only (ADR-0008).
           list << [:check, edges_table, "sym_#{t.name}",
@@ -123,6 +134,28 @@ module Pglpg
       connection.transaction(requires_new: true) { synchronize_constraints(connection) }
     end
 
+    # Acknowledges only the named temporal types. The caller supplies any
+    # backfill, on the same locked connection, after checks are installed.
+    def enable_temporal!(types:, backfill: nil, connection: graph.connection)
+      names = Array(types).map { type.edge_type!(_1) }.uniq
+      raise ArgumentError, "types: needs temporal edge types" if names.empty? || names.any? { !_1.temporal? }
+      raise ArgumentError, "backfill must be callable" if backfill && !backfill.respond_to?(:call)
+
+      connection.transaction(requires_new: true) do
+        lock_temporal_table(connection)
+        check_temporal_columns!(connection, allow_missing: true)
+        acknowledge_temporal!(connection, names.map(&:name))
+        existing = connection.columns(edges_table).map(&:name)
+        Temporal::NAMES.each do |name|
+          next if existing.include?(name.to_s)
+          connection.execute("ALTER TABLE #{q(connection, edges_table)} ADD COLUMN #{q(connection, name)} date")
+        end
+        synchronize_constraints(connection, acknowledged: names.map(&:name))
+        backfill.call(connection) if backfill
+        nil
+      end
+    end
+
     # Rewrites stored label sets to match the graph type.
     def relabel!(connection = graph.connection)
       return 0 if concrete_types.empty?
@@ -148,7 +181,12 @@ module Pglpg
 
     private
 
-    def synchronize_constraints(connection)
+    def synchronize_constraints(connection, acknowledged: [])
+      if type.temporal? || temporal_columns?(connection)
+        lock_temporal_table(connection)
+        check_temporal_columns!(connection)
+        acknowledge_temporal!(connection, acknowledged)
+      end
       wanted = constraints(connection)
       existing = existing_constraints(connection)
       (existing.keys - wanted.keys).each do |name|
@@ -160,9 +198,70 @@ module Pglpg
         end
       end
       (wanted.keys - existing.keys).each { connection.execute(wanted[_1][:sql]) }
+      wanted.each_key do |name|
+        next unless existing[name] && existing[name][:validated] == false
+        connection.execute("ALTER TABLE #{q(connection, existing[name][:table])} VALIDATE CONSTRAINT #{q(connection, name)}")
+      end
       nil
     end
 
+    def lock_temporal_table(connection)
+      connection.execute("LOCK TABLE #{q(connection, edges_table)} IN ACCESS EXCLUSIVE MODE")
+    end
+
+    def temporal_columns?(connection)
+      return false unless connection.data_source_exists?(edges_table)
+      return false unless (connection.columns(edges_table).map(&:name) & Temporal::NAMES.map(&:to_s)).any?
+      return true if (type.edge_columns.keys & Temporal::NAMES).empty?
+
+      # Legacy application columns are allowed until explicitly migrated.
+      # Once metadata checks exist, redeclaring them as application columns
+      # must not silently bypass the temporal-disable transition.
+      existing_constraints(connection).values.any? do |info|
+        info[:table] == edges_table && Temporal::NAMES.all? { info[:definition]&.include?(_1.to_s) }
+      end
+    end
+
+    def check_temporal_columns!(connection, allow_missing: false)
+      if (type.edge_columns.keys & Temporal::NAMES).any?
+        raise TemporalMigrationRequired, "remove reserved validity metadata from application column declarations"
+      end
+      columns = connection.columns(edges_table).to_h { [_1.name, _1] }
+      Temporal::NAMES.each do |name|
+        column = columns[name.to_s]
+        if column.nil?
+          raise TemporalMigrationRequired, "run enable_temporal! to add #{name}" unless allow_missing
+        elsif column.type != :date || !column.null || column.default || column.default_function
+          raise TemporalMigrationRequired, "#{name} must be a nullable date column without a default; migrate incompatible columns explicitly"
+        end
+      end
+    end
+
+    def acknowledge_temporal!(connection, acknowledged)
+      existing = existing_constraints(connection)
+      type.edge_types.each_value do |t|
+        next unless t.temporal?
+        name = constraint_name(edges_table, "validity_#{t.name}", temporal_check(connection, t))
+        next if existing[name] && existing[name][:validated] != false
+        next if acknowledged.include?(t.name)
+        populated = connection.select_value("SELECT EXISTS (SELECT 1 FROM #{q(connection, edges_table)} WHERE type = #{connection.quote(t.name.to_s)})")
+        raise TemporalMigrationRequired, "acknowledge #{t.name} with enable_temporal!(types: [#{t.name.inspect}])" if populated
+      end
+    end
+
+    def temporal_check(connection, edge_type)
+      body = if edge_type.temporal?
+        checks = Temporal::NAMES.map do |name|
+          "(#{name} IS NULL OR #{name} BETWEEN DATE '0001-01-01' AND DATE '9999-12-31')"
+        end
+        checks << "(valid_from IS NULL OR valid_to IS NULL OR valid_from < valid_to)"
+        checks.join(" AND ")
+      else
+        "valid_from IS NULL AND valid_to IS NULL"
+      end
+      "NOT (type = #{connection.quote(edge_type.name.to_s)}) OR (#{body})"
+    end
+
     def type = graph.type
 
     def q(connection, name) = connection.quote_table_name(name)
@@ -192,6 +291,20 @@ module Pglpg
 
     # Rejects a missing key, JSON null and the wrong JSON type: a CHECK passes
     # on NULL, so the comparison is wrapped in IS TRUE.
+    def key_component_checks(list, connection, table, type, key, predicate)
+      key.properties.each do |name|
+        prop = type.properties.fetch(name)
+        value = "properties->#{connection.quote(name.to_s)}"
+        detail = case prop.type
+                 when :integer then "CASE WHEN jsonb_typeof(#{value}) = 'number' THEN (#{value})::numeric = trunc((#{value})::numeric) ELSE false END"
+                 when :enum then "properties->>#{connection.quote(name.to_s)} IN (#{prop.values.map { connection.quote(_1) }.join(", ")})"
+                 end
+        next unless detail
+
+        list << [:check, table, "keyval_#{type.name}_#{name}", "NOT (#{predicate}) OR (#{detail}) IS TRUE"]
+      end
+    end
+
     def typed_check(connection, prop)
       "(jsonb_typeof(properties->#{connection.quote(prop.name.to_s)}) = #{connection.quote(prop.json_type)}) IS TRUE"
     end
@@ -206,17 +319,17 @@ module Pglpg
     def existing_constraints(connection)
       prefixes = [nodes_table, edges_table].map { "pglpg\\_#{_1.gsub("_", "\\_")}\\_%" }
       rows = connection.select_rows(<<~SQL, "Pglpg constraints")
-        SELECT c.conname, 'check', t.relname FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid
+        SELECT c.conname, 'check', t.relname, c.convalidated, pg_get_constraintdef(c.oid) FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid
         WHERE t.relname IN (#{connection.quote(nodes_table)}, #{connection.quote(edges_table)})
           AND t.relnamespace = to_regnamespace(current_schema())
           AND (c.conname LIKE #{connection.quote(prefixes[0])} OR c.conname LIKE #{connection.quote(prefixes[1])})
         UNION ALL
-        SELECT i.indexname, 'index', i.tablename FROM pg_indexes i
+        SELECT i.indexname, 'index', i.tablename, true, NULL FROM pg_indexes i
         WHERE i.tablename IN (#{connection.quote(nodes_table)}, #{connection.quote(edges_table)})
           AND i.schemaname = current_schema()
           AND (i.indexname LIKE #{connection.quote(prefixes[0])} OR i.indexname LIKE #{connection.quote(prefixes[1])})
       SQL
-      rows.to_h { |name, kind, table| [name, { kind: kind.to_sym, table: }] }
+      rows.to_h { |name, kind, table, validated, definition| [name, { kind: kind.to_sym, table:, validated:, definition: }] }
     end
   end
 end

data/lib/pglpg/temporal.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Pglpg
+  # Internal validity metadata, deliberately separate from application columns.
+  module Temporal
+    NAMES = %i[valid_from valid_to].freeze
+    OMITTED = Object.new.freeze
+    MIN = Date.new(1, 1, 1, Date::GREGORIAN).freeze
+    MAX = Date.new(9999, 12, 31, Date::GREGORIAN).freeze
+
+    module_function
+
+    # PostgreSQL dates are proleptic Gregorian calendar dates. Interpret Ruby
+    # Dates by their civil fields, never by timezone or an implicit Time cast.
+    def date(value, error: ValidationError)
+      return nil if value.nil?
+      raise error, "expected an exact Date in 0001-01-01..9999-12-31" unless value.instance_of?(Date)
+
+      begin
+        result = Date.new(value.year, value.month, value.day, Date::GREGORIAN)
+      rescue Date::Error
+        raise error, "invalid Gregorian date"
+      end
+      raise error, "date outside 0001-01-01..9999-12-31" unless (MIN..MAX).cover?(result)
+
+      result.freeze
+    end
+
+    def bounds(type, lower, upper, required: false)
+      supplied = { valid_from: lower, valid_to: upper }.reject { |_, v| v.equal?(OMITTED) }
+      unless type.temporal?
+        raise ArgumentError, "#{type.name} is not temporal" unless supplied.empty?
+        return {}.freeze
+      end
+      raise ArgumentError, "temporal insert/upsert requires valid_from:" if required && lower.equal?(OMITTED)
+
+      result = supplied.transform_values { date(_1) }
+      validate_interval!(result[:valid_from], result[:valid_to])
+      result.freeze
+    end
+
+    def validate_interval!(lower, upper)
+      raise ValidationError, "valid_from must precede valid_to" if lower && upper && lower >= upper
+    end
+  end
+end