pglpg 0.1.0 → 0.2.0

data/lib/pglpg/model/base.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+module Pglpg
+  module Model
+    # Shared by Model::Node and Model::Edge. A model class binds a graph and
+    # a schema type; its attributes are the type's properties and the
+    # graph's application columns. Models keep the Context they were read
+    # or built through, and write through its guarded write API (ADR-0010).
+    class Base
+      include ActiveModel::API
+      include ActiveModel::Attributes
+      include ActiveModel::Dirty
+
+      # Attributes are assigned as given: no form coercion ("42" stays a
+      # String). The schema checks values on validation.
+      #
+      # Every conversion copies Strings and Arrays, so the dirty baseline and
+      # the caller's object never share the record's value, and in-place
+      # edits (tags << "b", name << "e") count as changes.
+      class StrictType < ActiveModel::Type::Value
+        def cast(value) = copy(value)
+
+        def deserialize(value) = copy(value)
+
+        def serialize(value) = copy(value)
+
+        def changed_in_place?(raw_old_value, new_value) = raw_old_value != new_value
+
+        private
+
+        def copy(value)
+          case value
+          when Array then value.map { copy(_1) }
+          when String then value.dup
+          else value
+          end
+        end
+      end
+
+      STRICT = StrictType.new
+
+      CORE_OWNERS = [Kernel, Object, BasicObject].freeze
+      CORE_METHODS = %i[
+        class hash freeze frozen? send public_send object_id method methods respond_to? dup clone
+        equal? eql? is_a? kind_of? instance_of? nil? itself instance_variable_get instance_variable_set
+      ].freeze
+
+      validate :validate_schema
+
+      class << self
+        # Binds the model to a graph and a schema type:
+        #   graph Kg, type: :Person
+        # Without arguments, returns the bound graph.
+        def graph(graph = nil, type: nil)
+          return @graph if graph.nil? && type.nil?
+          raise ConfigurationError, "#{self} is already bound to graph #{@graph.name}" if @graph
+          raise ArgumentError, "graph must be a Pglpg::Graph" unless graph.is_a?(Pglpg::Graph)
+
+          schema_type = resolve_type(graph, type)
+          check_parent!(graph, schema_type)
+          property_names = schema_type.properties.keys
+          column_names = element_columns(graph).keys
+          check_attribute_names!(schema_type, property_names, column_names)
+
+          property_names.each { attribute(_1, STRICT) }
+          column_names.each { attribute(_1, STRICT) }
+          @graph = graph
+          @schema_type = schema_type
+          @property_names = property_names.freeze
+          @column_names = column_names.freeze
+          Model.register(graph, kind, schema_type.name, self)
+          graph
+        end
+
+        attr_reader :schema_type, :property_names, :column_names
+
+        # The model's elements as seen through +context+: a Relation.
+        def in(context)
+          raise ConfigurationError, "#{self} is not bound to a graph; declare graph Kg, type: ..." unless @graph
+          raise ArgumentError, "expected a Pglpg::Context" unless context.is_a?(Pglpg::Context)
+          raise ArgumentError, "the context belongs to graph #{context.graph.name}, not #{@graph.name}" unless context.graph.equal?(@graph)
+
+          Relation.new(self, context)
+        end
+
+        # Anonymous model classes are named after their schema type, so
+        # validation messages work for them too.
+        def model_name
+          return super if name
+
+          @model_name ||= ActiveModel::Name.new(self, nil, schema_type&.name&.to_s || base_class.name.split("::").last)
+        end
+
+        # -- internal ----------------------------------------------------------
+
+        # A model of +element+, read through +context+: the model registered
+        # for its concrete type, else this one.
+        def instantiate(context, element)
+          klass = Model.lookup(graph, kind, element_type_name(element)) || self
+          klass.allocate.tap { _1.send(:load_element, context, element) }
+        end
+
+        # A new record bound to +context+.
+        def build(context, attributes)
+          new(attributes).tap { _1.instance_variable_set(:@context, context) }
+        end
+
+        private
+
+        # A model may extend another model only along the schema's inheritance,
+        # checked against the nearest bound ancestor (unbound classes between
+        # them still inherit its attributes).
+        def check_parent!(graph, schema_type)
+          parent = superclass
+          parent = parent.superclass while parent < Base && parent.schema_type.nil?
+          return unless parent < Base
+          return if parent.graph.equal?(graph) && inherits_type?(schema_type, parent.schema_type)
+
+          raise SchemaError, "#{self} (#{schema_type.name}) cannot extend #{parent} (#{parent.schema_type.name})"
+        end
+
+        def check_attribute_names!(schema_type, property_names, column_names)
+          clashes = property_names & column_names
+          raise SchemaError, "#{schema_type.name} has properties named like columns: #{clashes.join(", ")}" if clashes.any?
+
+          (property_names + column_names).each do |name|
+            if inherited_member_names.include?(name)
+              raise SchemaError, "#{schema_type.name}.#{name} clashes with the inherited association #{name}"
+            end
+            next unless reserved_name?(name)
+
+            raise SchemaError, "#{schema_type.name}.#{name} clashes with a method of #{base_class}"
+          end
+        end
+
+        # Names a model inherits that attributes may not take (associations).
+        def inherited_member_names = []
+
+        # Methods of the model classes and ActiveModel, public or private, plus
+        # the core Object methods an attribute must never shadow. Other
+        # Kernel and Object methods (format, display, ...) may be shadowed.
+        def reserved_name?(name)
+          [name, :"#{name}="].any? do |m|
+            next true if CORE_METHODS.include?(m)
+            next false unless base_class.method_defined?(m) || base_class.private_method_defined?(m)
+
+            !CORE_OWNERS.include?(base_class.instance_method(m).owner)
+          end
+        end
+      end
+
+      attr_reader :context, :ref, :created_at, :updated_at
+
+      # Properties stored on the element that this model's type does not
+      # declare (a subtype read through a base-type model). Read-only.
+      def extra_properties = @extra_properties || {}.freeze
+
+      def id = ref&.id
+
+      def persisted? = !ref.nil? && !destroyed?
+
+      def new_record? = ref.nil?
+
+      def destroyed? = @destroyed == true
+
+      def to_key = persisted? ? [id] : nil
+
+      # The ref as a String; Relation#find accepts it back.
+      def to_param = ref&.to_s
+
+      # Validates, then writes through the context's guarded write API: an
+      # insert for a new record, else an update of the changed attributes
+      # only. Returns false when validation fails. Refusals (WriteRejected,
+      # NotTrusted), timeouts and database errors raise; changes are kept on
+      # any failure. +writer:+ hands over the context's trusted writer, for
+      # trusted-only operations; it never permits assigning a key.
+      #
+      # Success means the statement succeeded in the caller's transaction.
+      # Local state is what was assigned, not a stored snapshot (generated
+      # keys and timestamps are unknown until #reload), and a caller's
+      # rollback is not tracked: discard or reload the record after one.
+      def save(writer: nil)
+        target = write_target(writer)
+        return false unless valid?
+
+        persist(target)
+      end
+
+      # As #save, but raises RecordInvalid when validation fails.
+      def save!(writer: nil)
+        target = write_target(writer)
+        raise RecordInvalid, self unless valid?
+
+        persist(target)
+      end
+
+      # Deletes the element through the guarded write API (a node only
+      # through the trusted writer). Returns true.
+      def destroy(writer: nil)
+        raise ArgumentError, "only a persisted record can be destroyed" unless persisted?
+
+        delete_element(write_target(writer))
+        @association_cache = nil
+        @destroyed = true
+      end
+
+      # Replaces attributes, timestamps and the dirty baseline from the
+      # stored element. Raises RecordNotFound, leaving the record unchanged,
+      # when it is missing or no longer visible.
+      def reload
+        element = ref && context&.find(ref)
+        raise RecordNotFound unless element && self.class.matches?(element)
+
+        load_element(context, element)
+        self
+      end
+
+      def ==(other) = other.is_a?(self.class.base_class) && !ref.nil? && other.ref == ref
+
+      alias eql? ==
+
+      def hash = ref ? ref.hash : super
+
+      def inspect
+        attrs = attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+        "#<#{self.class.name || self.class.base_class.name} #{ref || "new"} #{attrs}>"
+      end
+
+      private
+
+      # ActiveModel casts lazily, on first read; copy on assignment so a
+      # caller who changes the object afterwards doesn't change the record.
+      def _write_attribute(name, value) = super(name, STRICT.cast(value))
+
+      def load_element(context, element)
+        @association_cache = nil
+        @attributes = self.class._default_attributes.deep_dup
+        @context = context
+        @ref = element.ref
+        @created_at = element.created_at
+        @updated_at = element.updated_at
+        properties = element.properties
+        self.class.property_names.each { @attributes.write_from_database(_1.to_s, properties[_1]) }
+        self.class.column_names.each { @attributes.write_from_database(_1.to_s, element.attrs[_1]) }
+        @extra_properties = properties.except(*self.class.property_names).freeze
+        load_identity(element)
+        clear_changes_information
+        self
+      end
+
+      # The context's interactive writes, or the given writer, which must
+      # belong to this record's own context (identity).
+      def write_target(writer)
+        raise ArgumentError, "#{self.class} has no context; build it with Model.in(ctx).new" unless context
+        raise ArgumentError, "#{self.class} was destroyed" if destroyed?
+        return context if writer.nil?
+        raise ArgumentError, "writer: expects a Pglpg::Writer" unless writer.is_a?(Pglpg::Writer)
+        raise ArgumentError, "the writer belongs to another context" unless writer.context.equal?(context)
+
+        writer
+      end
+
+      def persist(target)
+        if new_record?
+          create_element(target, assigned(self.class.property_names), assigned(self.class.column_names))
+        elsif changed?
+          update_element(target, changes_to(self.class.property_names), changes_to(self.class.column_names))
+        end
+        changes_applied
+        @association_cache = nil
+        true
+      end
+
+      # Non-nil values to insert (nil means absent).
+      def assigned(names)
+        names.each_with_object({}) do |name, out|
+          value = attribute(name.to_s)
+          out[name] = value unless value.nil?
+        end
+      end
+
+      # Changed values to update (nil removes a property).
+      def changes_to(names) = names.select { attribute_changed?(_1.to_s) }.to_h { [_1, attribute(_1.to_s)] }
+
+      def element_columns = self.class.send(:element_columns, self.class.graph)
+
+      # Schema checks: property values per the stored type, required
+      # properties and columns.
+      def validate_schema
+        type = schema_type
+        self.class.property_names.each do |name|
+          prop = type.property_named(name)
+          value = attribute(name.to_s)
+          if value.nil?
+            errors.add(name, :blank) if prop.required? && required_now?(name)
+          else
+            begin
+              prop.encode(value)
+            rescue ValidationError
+              errors.add(name, :invalid, message: "is not a valid #{prop.type == :list ? "list of #{prop.of}" : prop.type}")
+            end
+          end
+        end
+        element_columns.each_value do |column|
+          next unless attribute(column.name.to_s).nil?
+
+          blank = new_record? ? column.required? : attribute_changed?(column.name.to_s) && !column.null?
+          errors.add(column.name, :blank) if blank
+        end
+      end
+
+      # A missing required property is an error on insert, and when an
+      # update would remove it.
+      def required_now?(name) = new_record? || attribute_changed?(name.to_s)
+    end
+
+    # save! or create! found validation errors. #record has them.
+    class RecordInvalid < Error
+      attr_reader :record
+
+      def initialize(record)
+        @record = record
+        super("validation failed: #{record.errors.full_messages.join(", ")}")
+      end
+    end
+  end
+end

data/lib/pglpg/model/edge.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Pglpg
+  module Model
+    # A model of an edge type. For a symmetric type, source and target are
+    # the stored (canonical) endpoints and carry no direction.
+    #
+    #   class WorksOn < Pglpg::Model::Edge
+    #     graph Kg, type: :WORKS_ON
+    #   end
+    class Edge < Base
+      class << self
+        def base_class = Model::Edge
+
+        def kind = :edge
+
+        def query_var = :e
+
+        # Symmetric edges bind once per orientation, so the relation returns
+        # each edge once (distinct).
+        def pattern(context)
+          q = context.match.node(:s)
+          q = schema_type.symmetric? ? q.both(schema_type.name, :t, edge: :e) : q.out(schema_type.name, :t, edge: :e)
+          q.return(:e).distinct
+        end
+
+        def matches?(element) = element.type == schema_type.name
+
+        def element_type_name(element) = element.type
+
+        private
+
+        def resolve_type(graph, type) = graph.type.edge_type!(type)
+
+        def element_columns(graph) = graph.type.edge_columns
+
+        def inherits_type?(type, parent_type) = type == parent_type
+      end
+
+      attr_reader :source, :target
+
+      def schema_type = self.class.schema_type
+
+      def symmetric? = schema_type.symmetric?
+
+      # The endpoint opposite +ref+ (the same node for a self-loop).
+      def other(ref)
+        return target if ref == source
+        return source if ref == target
+
+        raise ArgumentError, "#{ref} is not an endpoint of #{self.ref}"
+      end
+
+      # Endpoints of a new record: a node Ref or a node model. They can't
+      # change once the edge is stored.
+      def source=(node)
+        @source = endpoint(node)
+      end
+
+      def target=(node)
+        @target = endpoint(node)
+      end
+
+      validate :validate_endpoints
+
+      private
+
+      def load_identity(element)
+        @source = element.source
+        @target = element.target
+        self
+      end
+
+      def endpoint(node)
+        raise ArgumentError, "the endpoints of a stored edge can't change" unless new_record?
+        return nil if node.nil?
+
+        ref = node.is_a?(Model::Node) ? node.ref : node
+        raise ArgumentError, "the endpoint is not stored yet" if ref.nil?
+
+        self.class.graph.check_ref!(ref, :node)
+      end
+
+      # A symmetric edge is stored in canonical order, so the record takes it.
+      def create_element(writer, properties, attrs)
+        @ref = writer.insert_edge(schema_type.name, from: source, to: target, properties:, attrs:)
+        @source, @target = @target, @source if symmetric? && @source.id > @target.id
+      end
+
+      def update_element(writer, properties, attrs)
+        writer.update_edge(ref, properties:, attrs:)
+      end
+
+      def delete_element(writer) = writer.delete_edge(ref)
+
+      def validate_endpoints
+        return unless new_record?
+
+        errors.add(:source, :blank) if source.nil?
+        errors.add(:target, :blank) if target.nil?
+      end
+    end
+  end
+end

data/lib/pglpg/model/node.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+module Pglpg
+  module Model
+    # A model of a node type. A query on it returns nodes of the type and its
+    # subtypes; each is built as the model registered for its concrete type,
+    # else as the queried model.
+    #
+    #   class Person < Pglpg::Model::Node
+    #     graph Kg, type: :Person
+    #     has_many :projects, :out, edge: :WORKS_ON
+    #   end
+    class Node < Base
+      # A declared association: follow +edge_type+ in +direction+ to nodes of
+      # +label+, loaded as +model+ (a class, a class name, or nil for the
+      # model registered for +label+).
+      Association = Data.define(:name, :direction, :edge_type, :label, :model)
+
+      class << self
+        def base_class = Model::Node
+
+        # Declares an association, read as a method returning an
+        # AssociationRelation:
+        #   has_many :projects, :out, edge: :WORKS_ON
+        #   has_many :friends, :both, edge: :FRIEND
+        #   has_many :team, :in, edge: :WORKS_ON, label: :Employee, model: "Employee"
+        # +direction+ is :out or :in for a directed edge type and :both for a
+        # symmetric one. The target label defaults to the edge type's other
+        # endpoint; +model+ defaults to the model registered for that label.
+        def has_many(name, direction, edge:, label: nil, model: nil)
+          raise ConfigurationError, "#{self}: declare graph before has_many" unless graph
+
+          name = Schema.check_name!(name, "association")
+          edge_type = graph.type.edge_type!(edge)
+          owner_labels, target_label = association_ends(edge_type, direction)
+          unless owner_labels.any? { |l| graph.type.node_types_with_label(l).any? { _1.label?(schema_type.name) } }
+            raise SchemaError, "#{schema_type.name} is not an endpoint of #{edge_type.name} (#{direction})"
+          end
+          target_label = graph.type.node_type!(label).name if label
+          if target_label.nil? && model.nil?
+            raise SchemaError, "#{name}: #{edge_type.name} joins two labels; give label: or model:"
+          end
+          if method_defined?(name) || reserved_name?(name)
+            raise SchemaError, "association #{name} clashes with a method of #{self}"
+          end
+
+          association = Association.new(name:, direction:, edge_type: edge_type.name, label: target_label, model:)
+          own_associations[name] = association
+          define_method(name) { association_relation(association) }
+          association
+        end
+
+        # Associations declared on this model and the models it extends.
+        def associations
+          inherited = superclass.respond_to?(:associations) ? superclass.associations : {}
+          inherited.merge(own_associations)
+        end
+
+        # The query variable a relation binds the node to.
+
+        def kind = :node
+
+        # The query variable a relation binds the node to.
+        def query_var = :n
+
+        # The pattern a relation starts from.
+        def pattern(context) = context.match.node(:n, schema_type.name)
+
+        def matches?(element) = element.label?(schema_type.name)
+
+        def element_type_name(element) = element.key_label
+
+        # Internal association target resolution, shared by lazy and eager reads.
+        def association_model(association)
+          model = case association.model
+                  when nil then Model.lookup(graph, :node, association.label)
+                  when String, Symbol then resolve_model_name(association.model.to_s)
+                  else association.model
+                  end
+          unless model.is_a?(Class) && model < Model::Node && model.graph.equal?(graph)
+            raise ConfigurationError, "#{self}##{association.name}: no node model of graph #{graph.name} " \
+                                      "for #{association.label}; give model:"
+          end
+          if association.label && !graph.type.node_type!(association.label).label?(model.schema_type.name)
+            raise ConfigurationError, "#{self}##{association.name}: #{association.label} nodes are not #{model}"
+          end
+
+          model
+        end
+
+        # nil for a name that doesn't resolve, so it reports as a missing model.
+        def resolve_model_name(name)
+          Object.const_get(name)
+        rescue NameError
+          nil
+        end
+
+        private
+
+        def own_associations = (@own_associations ||= {})
+
+        def inherited_member_names = associations.keys
+
+        # The owner's possible labels and the target label for +direction+,
+        # following the query DSL's rule for symmetric types (ADR-0008).
+        def association_ends(edge_type, direction)
+          case direction
+          when :out, :in
+            raise SchemaError, "#{edge_type.name} is symmetric; use :both" if edge_type.symmetric?
+
+            direction == :out ? [[edge_type.from], edge_type.to] : [[edge_type.to], edge_type.from]
+          when :both
+            raise SchemaError, "#{edge_type.name} is directed; use :out or :in" unless edge_type.symmetric?
+
+            [[edge_type.from, edge_type.to].uniq, (edge_type.from if edge_type.from == edge_type.to)]
+          else
+            raise ArgumentError, "direction must be :out, :in or :both"
+          end
+        end
+
+        def resolve_type(graph, type) = graph.type.node_type!(type)
+
+        def element_columns(graph) = graph.type.node_columns
+
+        def inherits_type?(type, parent_type) = type == parent_type || type.ancestors.include?(parent_type.name)
+      end
+
+      attr_reader :labels
+
+      # The concrete schema type of the stored node, which may be a subtype
+      # of the model's type.
+      def schema_type = @schema_type || self.class.schema_type
+
+      # The value of the type's key property, or nil.
+      def key
+        key = schema_type.key or return nil
+        self.class.property_names.include?(key.property) ? attribute(key.property.to_s) : extra_properties[key.property]
+      end
+
+      validate :validate_node
+
+      private
+
+      # The association's targets as seen through this record's context,
+      # starting from this record (visibility applies to it too).
+      def association_relation(association)
+        raise ArgumentError, "#{association.name}: save the record first" unless persisted?
+
+        target = association_model(association)
+        query = context.match.node(:owner, ref:)
+                       .public_send(association.direction, association.edge_type, :n,
+                                    association.label || target.schema_type.name, edge: :e)
+        edge_model = Model.lookup(self.class.graph, :edge, association.edge_type)
+        AssociationRelation.new(target, context, query, edge_model:, cached: (@association_cache || {})[association.name])
+      end
+
+      def association_model(association) = self.class.association_model(association)
+
+      def load_identity(element)
+        @schema_type = self.class.graph.type.node_type!(element.key_label)
+        @labels = element.labels
+        self
+      end
+
+      # Labels follow from the type, so they are known without a reload.
+      def create_element(target, properties, attrs)
+        @ref = target.insert_node(schema_type.name, properties:, attrs:)
+        @labels = schema_type.labels.map(&:to_sym).freeze
+      end
+
+      def update_element(target, properties, attrs)
+        target.update_node(ref, properties:, attrs:)
+      end
+
+      def delete_element(target)
+        raise NotTrusted, "destroying a node needs the trusted writer" unless target.is_a?(Pglpg::Writer)
+
+        target.delete_node(ref)
+      end
+
+      def key_property = schema_type.key&.property
+
+      # The generated key is not required on insert.
+      def required_now?(name) = new_record? ? name != key_property : super
+
+      # Keys are generated on insert and never change (ADR-0005, ADR-0010).
+      def validate_node
+        errors.add(:base, "#{schema_type.name} is abstract") if new_record? && schema_type.abstract?
+        key = key_property
+        return unless key && self.class.property_names.include?(key)
+
+        if new_record?
+          errors.add(key, "is generated and cannot be assigned") unless attribute(key.to_s).nil?
+        else
+          schema_type.key.properties.each do |property|
+            errors.add(property, "cannot be changed") if attribute_changed?(property.to_s)
+          end
+        end
+      end
+    end
+  end
+end