rails_age 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d54712ca67a303ffa92d78165d30a500b1f695be6176b3198e7ff3f9f60ab4f9
-  data.tar.gz: 8f8f999c42777dc432bf543b6256852d10a0fbcbcd4fe33ad06817277a47bb5d
+  metadata.gz: 6777870b945c8684ea2ef5d10b8e7411259e002001b074754840a9422b594cee
+  data.tar.gz: '008ab62bbe28d408d390acd5e00cecc764507e21ae3d38ca94d219e9d299435f'
 SHA512:
-  metadata.gz: 75c804a5b29705a18344ea70d9a799ea3578d90055b056ba48b70984132f2fbd04bdd906ac744e2a587fe095e9a8e112d773ecc84cf6325be192c212d769090d
-  data.tar.gz: 932a6c5843243a23ef48b69e87f0fef940030c9e47ce652be141bc6efb45a8cbde04c191853b3d15e754e3ee71d7033b301ab6432982c1fc357250fceb892f02
+  metadata.gz: 8a9c122ce1a8b5b173fc9ffd6ba45a4bf97965eb0681ec0d44e9779dcc1ef647da8e7e5110a5564a9f28c329ebe9e83ba832d920f4504bb5026650f41cc102d2
+  data.tar.gz: f9217b16e0177746a438ab5fed8a4e5c7f4bb6ff02b3e31a2a4d1db7a8bd246550e33be6494e0533c70dcbcde3a54078ed041b2c3a08718cb9b020c73353eee5

data/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-## VERSION 0.6.2 - 2024-xx-xx
+## VERSION 0.6.4 - 2024-xx-xx
 
 - **cypher queries** (like active record queries)
   * schema override
@@ -8,11 +8,11 @@
   * paths support
   * select attributes support
 
-## VERSION 0.6.1 - 2024-xx-xx
+## VERSION 0.6.3 - 2024-xx-xx
 
 - **Age Path**
 
-## VERSION 0.6.0 - 2024-xx-xx
+## VERSION 0.6.2 - 2024-xx-xx
 
 breaking change?: namespaces (by default) will use their own schema? (add to database.yml & schema.rb ?)
 
@@ -20,24 +20,44 @@ breaking change?: namespaces (by default) will use their own schema? (add to dat
 
 - **multiple AGE Schema**
 
-## VERSION 0.5.3 - 2024-xx-xx
-
-- **Edge Scaffold** (generates edge, type, view and controller)
-  * add `rails generate apache_age:edge_scaffold HasJob employee_role start_node:person end_node:company`
+## VERSION 0.6.1 - 2024-xx-xx
 
-## VERSION 0.5.2 - 2024-xx-xx
+- **Fix**
+  * show validation errors in scaffold views
 
 - **Edge Generator**
   * add start-/end-nodes types to edge generator (would make scaffold easier), ie:
     `rails generate apache_age:edge HasPet owner_role start_node:person end_node:pet`
     with property and specified start-/end-nodes (person and pet nodes must have already been created)
 
+- **Edge Scaffold** (generates edge, type, view and controller)
+  * add `rails generate apache_age:edge_scaffold HasJob employee_role start_node:person end_node:company`
+
+## VERSION 0.6.0 - 2024-06-xx
+
+**breaking changes**: update naming
+  * renamed `Entities::Vertex` module to `Entities::Node`
+  * renamed `UniqueVertex` to `UniqueNode`
+  * rebamed `AgeTypeGenerator` to `Type::Factory`
+  * move `lib/generators/*` intp `lib/apache_age/generators`
+
+here is the [commit](https://github.com/marpori/rails_age_demo_app/commit/a6f0708f2bbc165eddbafe63896068a72d803b17) to see the changes te demo app to make it work for release 0.6.0
+
+## VERSION 0.5.3 - 2024-06-23
+
+- **Edge Scaffold** (generates edge, type, view and controller) - without start-/end-nodes types!?
+  * add `rails generate apache_age:edge_scaffold HasJob employee_role`
+  * add system test (to dummy app after scaffold_node is run)
+
+- **Node Scaffold** (generates node, type, view and controller)
+  * add system test (to dummy app after scaffold_node is run)
+
 ## VERSION 0.5.2 - 2024-06-16
 
 - **Node Scaffold** (generates node, type, view and controller)
   * add `rails generate apache_age:node_scaffold Person first_name last_name age:integer`
 
-## VERSION 0.5.1 - 2024-06-16
+## VERSION 0.5.1 - 2024-06-16 (yanked)
 
 **yanked** (2024-06-16) - had an issue with the generator
 
@@ -50,7 +70,7 @@ breaking change?: namespaces (by default) will use their own schema? (add to dat
 
 - **Edge Generator**
   * add `rails generate apache_age:edge HasPet owner_role`
-    caveate: start_node and end_node are of type `:vertex` in the generator but can be changed manually in the class file - having trouble with the generator loading the types (the generator rejects custom types - but rails still works with custom types)
+    caveate: start_node and end_node are of type `:node` in the generator but can be changed manually in the class file - having trouble with the generator loading the types (the generator rejects custom types - but rails still works with custom types)
 
 ## VERSION 0.4.1 - 2024-06-15
 

data/README.md

@@ -1,25 +1,76 @@
 # RailsAge
 
-Simplify Apache Age usage within a Rails application.
+Apache Age integration within a Rails application.
 
-## Installation
+## Quick Start - Essentials
 
 **NOTE:** you must be using Postgres as your database! Apache Age requires it.
 
-Add this line to your application's Gemfile:
+```bash
+bundle add rails_age
+bundle install
+bin/rails apache_age:install
+# optional: prevents `bin/rails db:migrate` from modifying the schema file,
+# bin/rails apache_age:override_db_migrate
+git add .
+git commit -m "Add & configure Apache Age within Rails"
+```
+
+## Generators
+
+**NODES**
+
+```bash
+rails generate apache_age:scaffold_node Company company_name
+
+rails generate apache_age:scaffold_node Person first_name last_name
+```
+
+**EDGES**
 
+```bash
+rails generate apache_age:scaffold_edge HasJob employee_role start_date:date
+```
+
+Ideally, edit the HasJob class so that `start_node` would use a type `:person` and the `end_node` uses at type `:company` - this is not yet supported by the generator, but easy to do manually as shown below.  (The problem is that I havent been able to figure out how load all the rails types in the testing environment).
+
+ie:
 ```ruby
-gem "rails_age"
+# app/edges/has_job.rb
+class HasJob
+  include ApacheAge::Entities::Edge
+
+  attribute :employee_role, :string
+  attribute :start_node, :person
+  attribute :end_node, :company
+
+  validates :employee_role, presence: true
+  validate :validate_unique_edge
+
+  private
+
+  def validate_unique_edge
+    ApacheAge::Validators::UniqueEdge
+      .new(attributes: %i[employee_role start_node end_node])
+      .validate(self)
+  end
+end
 ```
 
-## Quick Start
+## Installation in Detail
 
 using the installer, creates the migration to install age, runs the migration, and adjusts the schema file, and updates the `config/database.yml` file.
 
-setup (& Test) postgresql with AGE (using the docker version of AGE DB may be the easiest way to get started)
-using the docker version of AGE DB, you can confirm psql AGE with the following commands:
+### Install Apache Age
+
+see: [Apache AGE Installation](https://age.apache.org/age-manual/master/intro/setup.html#installation)
+(The docker install is probably the easiest way to get started with a new application - for existing applications you may need to compile the extension from source.)
+
+Verify your PostgreSQL AGE with the following commands:
+
 ```bash
-psql -h localhost -p 5455 -U docker_username
+$ psql -h localhost -p 5455 -U docker_username
+
 > CREATE EXTENSION IF NOT EXISTS age;
 > LOAD 'age';
 > SET search_path = ag_catalog, "$user", public;
@@ -27,7 +78,12 @@ psql -h localhost -p 5455 -U docker_username
 > \q
 ```
 
+### Install and Configure Rails (if not done already)
+
+AGE REQUIRES POSTGRESQL!
+
 create a new Rails app (WITH POSTGRESQL!)
+
 ```bash
 rails new age_demo -d postgresql
 cd age_demo
@@ -35,6 +91,7 @@ git add .
 git commit -m "Initial Rails App"
 ```
 configure `config/database.yml` when using the docker version of AGE DB my config looks like:
+
 ```yaml
 port: 5455
 host: localhost
@@ -42,15 +99,19 @@ username: docker_username
 password: dockerized_password
 ```
 
-now you should be able to create the rails database:
+If both the Rails DB config and AGE DB are correctly configured, you should be able to run the following command without error:
+
 ```bash
 rails db:create
 rails db:migrate
 git add .
-git commit -m "Add Apache Age Postgres DB configured with Rails App"
+git commit -m "Basic Rails Configuration"
 ```
 
-install Apache Age (you can ignore the `unknown OID` warnings)
+### install Apache Age Plugin
+
+NOTE: _ignore the `unknown OID` warnings_
+
 ```bash
 bundle add rails_age
 bundle install
@@ -62,62 +123,52 @@ git add .
 git commit -m "Add & configure Apache Age within Rails"
 ```
 
-make some nodes :string is the default type
+### Optional Migration override (OPTIONAL)
+
+run `bin/rails apache_age:override_db_migrate` to ensure that running `rails db:migrate` does not inappropriately modify the schema file.
+
+However, if you are familiar with the schema file and git then you can safely ignore this step and manage the changes after a migration manually - only submitting changes directly related to the newest migration and not those related AGE.
+
+**NOTE:**
+* **You can run `bin/rails apache_age:config_schema` at any time to repair the schema file as needed.**
+( **You can run `bin/rails apache_age:install` at any time to repair any AGE related config file**
+
+If you are using `db/structure.sql` you will need to manually configure Apache Age (RailsAge).
+
+### NODE Scaffold Generation
+
 ```bash
-rails generate apache_age:node Company company_name
-rails generate apache_age:node Person first_name last_name
-rails generate apache_age:node Pet pet_name:string age:integer
+rails generate apache_age:scaffold_node Company company_name:string
+
+# string is the default type (so it can be omitted)
+rails generate apache_age:scaffold_node Person first_name last_name
+
+# with a namespace
+rails generate apache_age:scaffold_node Animals/Pet pet_name birthdate:date
 ```
-make some edges (`:vertex` is the default type) for start_node and end_node
+
+### EDGE Scaffold Generation**
+
+NOTE: the generator will only allow `:node` (default type) for start_node and end_node, however, it is strongly recommended to specify the start_node and end_node types manually. _Hopefully, I can find a way to get the generators to recognize and allow the usage of custom node types. Thus eventually, I hope: `rails generate apache_age:node HasPet start_node:person end_node:pet caretaker_role` will work._
+
 ```bash
-# when start node and end node are not specified they are of type `:vertex`
-# this is generally not recommended - exept when very generic relationships are needed
 rails generate apache_age:edge HasJob employee_role begin_date:date
-
-# # this is recommended - (but not yet working) add explicit start_node and end_node types manually
-# rails generate apache_age:node HasPet start_node:person end_node:pet caretaker_role
 ```
 
-**NOTE:** the default `rails db:migrate` inappropriately modifies the schema file. This installer patches the migration to prevent this (however this might break on rails updates, etc). **You can run `bin/rails apache_age:install` at any time to repair the schema file as needed.**
-
-For now, if you are using `db/structure.sql` you will need to manually configure Apache Age (RailsAge) as described below.
+_edge scaffold is coming soon._
 
-### Rails Console Usage
+```bash
+# without a namespace
+rails generate apache_age:scaffold_edge HasPet caretaker_role
 
-```ruby
-bin/rails c
-
-fred = Person.new(first_name: 'Fredrick Jay', last_name: 'Flintstone')
-fred.valid?
-fred.save
-fred.to_h # should have an ID
-
-# fails because of a missing required field (Property)
-incomplete = Person.new(first_name: 'Fredrick Jay')
-incomplete.valid?
-incomplete.errors
-incomplete.to_h
-
-# fails because of uniqueness constraints
-jay = Person.create(first_name: 'Fredrick Jay', last_name: 'Flintstone')
-jay.to_h
-=> {:id=>nil, :first_name=>"Fredrick Jay", :last_name=>"Flintstone"}
-jay.valid?
-=> false
-jay.errors
-=> #<ActiveModel::Errors [#<ActiveModel::Error attribute=base, type=record not unique, options={}>, #<ActiveModel::Error attribute=first_name, type=property combination not unique, options={}>, #<ActiveModel::Error attribute=last_name, type=property combination not unique, options={}>]>
-irb(main):008> jav.to_h
-=> {:id=>nil, :first_name=>"Fredrick Jay", :last_name=>"Flintstone"}
-
-# .create is a shortcut for .new and .save
-quarry = Company.create(company_name: 'Bedrock Quarry')
-quarry.to_h # should have an ID
-
-# create an edge (no generator yet)
-job = HasJob.create(start_node: fred, end_node: quarry, employee_role: 'Crane Operator')
-job.to_h # should have an ID
+# with a namespace
+rails generate apache_age:scaffold_edge People/HasSpouse spousal_role
 ```
 
+### AGE Usage within Rails Console
+
+see [AGE Usage within Rails Console](AGE_CONSOLE_USAGE.md)
+
 ## Manual Install, Config and Usage
 
 see [Manuel Installation, Configuration and Usage](MANUAL_INSTALL.md)

data/config/initializers/types.rb

@@ -0,0 +1,20 @@
+# config/initializers/types.rb
+
+require 'apache_age/types/factory'
+# USAGE (with edges or nodes) - ie:
+# require_dependency 'company'
+# ActiveModel::Type.register(
+#   :company, ApacheAge::Types::Factory.type_for(Company)
+# )
+
+Rails.application.config.to_prepare do
+  # Register AGE types
+  require_dependency 'apache_age/node'
+  ActiveModel::Type.register(
+    :node, ApacheAge::Types::Factory.type_for(ApacheAge::Node)
+  )
+  require_dependency 'apache_age/edge'
+  ActiveModel::Type.register(
+    :edge, ApacheAge::Types::Factory.type_for(ApacheAge::Edge)
+  )
+end

data/lib/apache_age/edge.rb

@@ -0,0 +1,5 @@
+module ApacheAge
+  class Edge
+    include ApacheAge::Entities::Edge
+  end
+end

data/lib/apache_age/entities/common_methods.rb

@@ -7,6 +7,12 @@ module ApacheAge
       def persisted? = id.present?
       def to_s = ":#{age_label} #{properties_to_s}"
 
+      # default display value
+      def display
+        info = age_properties&.values&.first
+        info.blank? ? "#{age_label} (#{id})" : "#{info} (#{age_label})"
+      end
+
       def to_h
         base_h = attributes.to_hash
         if age_type == 'edge'

data/lib/apache_age/entities/edge.rb

@@ -9,11 +9,12 @@ module ApacheAge
         include ActiveModel::Attributes
 
         attribute :id, :integer
+        # attribute :label, :string
         attribute :end_id, :integer
         attribute :start_id, :integer
-        # type: `:vertex` can be overriden with a specific node type
-        attribute :end_node, :vertex
-        attribute :start_node, :vertex
+        # override with a specific node type in the defining class
+        attribute :end_node
+        attribute :start_node
 
         validates :end_node, :start_node, presence: true
         validate :validate_nodes

data/lib/apache_age/entities/node.rb

@@ -0,0 +1,53 @@
+module ApacheAge
+  module Entities
+    module Node
+      extend ActiveSupport::Concern
+
+      included do
+        include ActiveModel::Model
+        include ActiveModel::Dirty
+        include ActiveModel::Attributes
+
+        attribute :id, :integer
+
+        extend ApacheAge::Entities::ClassMethods
+        include ApacheAge::Entities::CommonMethods
+      end
+
+      def age_type = 'vertex'
+
+      # AgeSchema::Nodes::Company.create(company_name: 'Bedrock Quarry')
+      # SELECT *
+      # FROM cypher('age_schema', $$
+      #     CREATE (company:Company {company_name: 'Bedrock Quarry'})
+      # RETURN company
+      # $$) as (Company agtype);
+      def create_sql
+        alias_name = age_alias || age_label.downcase
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              CREATE (#{alias_name}#{self})
+          RETURN #{alias_name}
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+
+      # So far just properties of string type with '' around them
+      def update_sql
+        alias_name = age_alias || age_label.downcase
+        set_caluse =
+          age_properties.map { |k, v| v ? "#{alias_name}.#{k} = '#{v}'" : "#{alias_name}.#{k} = NULL" }.join(', ')
+        <<-SQL
+          SELECT *
+          FROM cypher('#{age_graph}', $$
+              MATCH (#{alias_name}:#{age_label})
+              WHERE id(#{alias_name}) = #{id}
+              SET #{set_caluse}
+              RETURN #{alias_name}
+          $$) as (#{age_label} agtype);
+        SQL
+      end
+    end
+  end
+end

data/lib/apache_age/entities/vertex.rb

@@ -1,53 +1,53 @@
-module ApacheAge
-  module Entities
-    module Vertex
-      extend ActiveSupport::Concern
+# module ApacheAge
+#   module Entities
+#     module Vertex
+#       extend ActiveSupport::Concern
 
-      included do
-        include ActiveModel::Model
-        include ActiveModel::Dirty
-        include ActiveModel::Attributes
+#       included do
+#         include ActiveModel::Model
+#         include ActiveModel::Dirty
+#         include ActiveModel::Attributes
 
-        attribute :id, :integer
+#         attribute :id, :integer
 
-        extend ApacheAge::Entities::ClassMethods
-        include ApacheAge::Entities::CommonMethods
-      end
+#         extend ApacheAge::Entities::ClassMethods
+#         include ApacheAge::Entities::CommonMethods
+#       end
 
-      def age_type = 'vertex'
+#       def age_type = 'vertex'
 
-      # AgeSchema::Nodes::Company.create(company_name: 'Bedrock Quarry')
-      # SELECT *
-      # FROM cypher('age_schema', $$
-      #     CREATE (company:Company {company_name: 'Bedrock Quarry'})
-      # RETURN company
-      # $$) as (Company agtype);
-      def create_sql
-        alias_name = age_alias || age_label.downcase
-        <<-SQL
-          SELECT *
-          FROM cypher('#{age_graph}', $$
-              CREATE (#{alias_name}#{self})
-          RETURN #{alias_name}
-          $$) as (#{age_label} agtype);
-        SQL
-      end
+#       # AgeSchema::Nodes::Company.create(company_name: 'Bedrock Quarry')
+#       # SELECT *
+#       # FROM cypher('age_schema', $$
+#       #     CREATE (company:Company {company_name: 'Bedrock Quarry'})
+#       # RETURN company
+#       # $$) as (Company agtype);
+#       def create_sql
+#         alias_name = age_alias || age_label.downcase
+#         <<-SQL
+#           SELECT *
+#           FROM cypher('#{age_graph}', $$
+#               CREATE (#{alias_name}#{self})
+#           RETURN #{alias_name}
+#           $$) as (#{age_label} agtype);
+#         SQL
+#       end
 
-      # So far just properties of string type with '' around them
-      def update_sql
-        alias_name = age_alias || age_label.downcase
-        set_caluse =
-          age_properties.map { |k, v| v ? "#{alias_name}.#{k} = '#{v}'" : "#{alias_name}.#{k} = NULL" }.join(', ')
-        <<-SQL
-          SELECT *
-          FROM cypher('#{age_graph}', $$
-              MATCH (#{alias_name}:#{age_label})
-              WHERE id(#{alias_name}) = #{id}
-              SET #{set_caluse}
-              RETURN #{alias_name}
-          $$) as (#{age_label} agtype);
-        SQL
-      end
-    end
-  end
-end
+#       # So far just properties of string type with '' around them
+#       def update_sql
+#         alias_name = age_alias || age_label.downcase
+#         set_caluse =
+#           age_properties.map { |k, v| v ? "#{alias_name}.#{k} = '#{v}'" : "#{alias_name}.#{k} = NULL" }.join(', ')
+#         <<-SQL
+#           SELECT *
+#           FROM cypher('#{age_graph}', $$
+#               MATCH (#{alias_name}:#{age_label})
+#               WHERE id(#{alias_name}) = #{id}
+#               SET #{set_caluse}
+#               RETURN #{alias_name}
+#           $$) as (#{age_label} agtype);
+#         SQL
+#       end
+#     end
+#   end
+# end

data/lib/apache_age/node.rb

@@ -0,0 +1,36 @@
+module ApacheAge
+  class Node
+    include ApacheAge::Entities::Node
+
+    attribute :label, :string
+    attribute :properties
+    # attribute :properties, :hash
+
+    # def display = [label, properties&.values&.first].compact.join(' - ')
+    def display
+      info = properties&.values&.first
+      info.blank? ? "#{label} (#{id})" : "#{info} (#{label})"
+    end
+
+    def self.all
+      all_nodes_sql = <<~SQL
+      SELECT *
+      FROM cypher('age_schema', $$
+          MATCH (node)
+          RETURN node
+      $$) as (node agtype);
+      SQL
+      age_results = ActiveRecord::Base.connection.execute(all_nodes_sql)
+      return [] if age_results.values.count.zero?
+
+      age_results.values.map do |result|
+        json_string = result.first.split('::').first
+        hash = JSON.parse(json_string)
+        attribs = hash.slice('id', 'label').symbolize_keys
+        attribs[:properties] = hash['properties'].symbolize_keys
+
+        new(**attribs)
+      end
+    end
+  end
+end

data/lib/apache_age/types/{age_type_generator.rb → factory.rb}

@@ -1,4 +1,4 @@
-# lib/apache_age/types/age_type_generator.rb
+# lib/apache_age/types/factory.rb
 # Automatically generates ActiveModel::Type classes
 # Dynamically builds this (as a concrete example):
 # module ApacheAge
@@ -22,8 +22,8 @@
 # end
 module ApacheAge
   module Types
-    class AgeTypeGenerator
-      def self.create_type_for(klass)
+    class Factory
+      def self.type_for(klass)
         Class.new(ActiveModel::Type::Value) do
           define_method(:cast) do |value|
             case value

data/lib/apache_age/validators/expected_node_type.rb

@@ -0,0 +1,17 @@
+module ApacheAge
+  module Validators
+    module ExpectedNodeType
+      def
+        # Register the AGE types vertex_attribute(attribute_name, type_symbol, klass)
+        attribute attribute_name, type_symbol
+
+        validate do
+          value = send(attribute_name)
+          unless value.is_a?(klass)
+            errors.add(attribute_name, "must be a #{klass.name}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/apache_age/validators/node_type_validator.rb

@@ -0,0 +1,15 @@
+module ApacheAge
+  module NodeTypeValidator
+    def
+      # Register the AGE typesvertex_attribute(attribute_name, type_symbol, klass)
+      attribute attribute_name, type_symbol
+
+      validate do
+        value = send(attribute_name)
+        unless value.is_a?(klass)
+          errors.add(attribute_name, "must be a #{klass.name}")
+        end
+      end
+    end
+  end
+end

data/lib/apache_age/validators/unique_node.rb

@@ -0,0 +1,32 @@
+# lib/apache_age/validators/unique_node.rb
+
+# Usage:
+# validates_with(
+#   ApacheAge::Validators::UniqueNode,
+#   attributes: [:first_name, :last_name, :gender]
+# )
+
+module ApacheAge
+  module Validators
+    class UniqueNode < ActiveModel::Validator
+      def validate(record)
+        allowed_keys = record.age_properties.keys
+        attributes = options[:attributes]
+        return if attributes.blank?
+
+        record_attribs =
+          attributes
+          .map { |attr| [attr, record.send(attr)] }
+          .to_h.symbolize_keys
+          .slice(*allowed_keys)
+        query = record.class.find_by(record_attribs)
+
+        # if no match is found or if it finds itself, it's valid
+        return if query.blank?  || (query.id == record.id)
+
+        record.errors.add(:base, 'record not unique')
+        attributes.each { record.errors.add(_1, 'property combination not unique') }
+      end
+    end
+  end
+end