rails_age 0.5.0 → 0.5.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ccc1964e751ea0670eeab5cc406f1d73d0ac4a188c3f0c97ff410cf0a12aa664
-  data.tar.gz: 9de0e59661db92464c6505c9dc3d6a2eb314f35333eeb4f97d92d2f4b628275b
+  metadata.gz: cd10883497fc245765a9e8313265e4d06c7a602a2f83cad592ecb5a951ab488d
+  data.tar.gz: ce03c6dc4535e2a54dddc9f2b9df8e4b413c6aeb690ee00138c4120fe1d72ce1
 SHA512:
-  metadata.gz: 15179f421eaa5fcf6180af0fd7865b1c69884064a2030b7f03300898eeda08d7bb2f871c43ec3b5ad1ae49db98b30cf274c582e3906fd66fe24b68812fb78b9a
-  data.tar.gz: 1a83d773effad75f2e90f89ee06f8585fa5a9fe40104df7913b0e0470d3026b7cc160ecb8e3ce3e2f2fcf7c1831a902fb61b1140974cc5f792d15e43ee3de4f1
+  metadata.gz: dcb00b35abd3a931c95ffce304c079eee2d1ba1b09ee3aa17f9c9150f4bc3b55276e7670cf3925e4ae484a117bef66bddc0242efc0cbc8295da03538ae628805
+  data.tar.gz: d6ac9aaa1ba0b04c9a48ed320e53a4de65a74e6cb6574f42c407b0c1124fafc650def68df4c41beaad27607b6f1fa22a7962518108c2fc39cd7c0e95f76d8c09

data/CHANGELOG.md

@@ -20,19 +20,36 @@ breaking change?: namespaces (by default) will use their own schema? (add to dat
 
 - **multiple AGE Schema**
 
-## VERSION 0.5.3 - 2024-xx-xx
+## VERSION 0.5.4 - 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.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)
 
-## VERSION 0.5.1 - 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.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 (yanked)
+
+**yanked** (2024-06-16) - had an issue with the generator
 
 - **Node Scaffold** (generates node, type, view and controller)
   * add `rails generate apache_age:node_scaffold Person first_name last_name age:integer`
@@ -43,7 +60,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`
+
+ie:
 ```ruby
-gem "rails_age"
+# app/edges/has_job.rb
+class HasJob
+  include ApacheAge::Entities::Edge
+
+  attribute :employee_role, :string
+  attribute :start_node, :person # instead of `:node`
+  attribute :end_node, :company # instead of `:node`
+
+  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/age_type_factory'
+# USAGE (with edges or nodes) - ie:
+# require_dependency 'nodes/company'
+# ActiveModel::Type.register(
+#   :company, ApacheAge::Types::AgeTypeFactory.create_type_for(Nodes::Company)
+# )
+
+Rails.application.config.to_prepare do
+  # Register AGE types
+  require_dependency 'apache_age/node'
+  ActiveModel::Type.register(
+    :node, ApacheAge::Types::AgeTypeFactory.create_type_for(ApacheAge::Node)
+  )
+  require_dependency 'apache_age/edge'
+  ActiveModel::Type.register(
+    :edge, ApacheAge::Types::AgeTypeFactory.create_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 Vertex
+      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,6 +1,6 @@
 module ApacheAge
   module Entities
-    module Vertex
+    module Node
       extend ActiveSupport::Concern
 
       included do

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_factory.rb

@@ -0,0 +1,46 @@
+# lib/apache_age/types/age_type_factory.rb
+# Automatically generates ActiveModel::Type classes
+# Dynamically builds this (as a concrete example):
+# module ApacheAge
+#   module Types
+#     class CompanyType < ActiveModel::Type::Value
+#       def cast(value)
+#         case value
+#         when Nodes::Company
+#           value
+#         when Hash
+#           Nodes::Company.new(value)
+#         else
+#           nil
+#         end
+#       end
+#       def serialize(value)
+#         value.is_a?(Nodes::Company) ? value.attributes : nil
+#       end
+#     end
+#   end
+# end
+module ApacheAge
+  module Types
+    class AgeTypeFactory
+      def self.create_type_for(klass)
+        Class.new(ActiveModel::Type::Value) do
+          define_method(:cast) do |value|
+            case value
+            when klass
+              value
+            when Hash
+              klass.new(value)
+            else
+              nil
+            end
+          end
+
+          define_method(:serialize) do |value|
+            value.is_a?(klass) ? value.attributes : nil
+          end
+        end
+      end
+    end
+  end
+end

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/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

data/lib/apache_age/validators/{vertex_type_validator.rb → vertex_type_validator copy.rb }

@@ -1,6 +1,7 @@
 module ApacheAge
   module VertexTypeValidator
-    def vertex_attribute(attribute_name, type_symbol, klass)
+    def
+      # Register the AGE typesvertex_attribute(attribute_name, type_symbol, klass)
       attribute attribute_name, type_symbol
 
       validate do

data/lib/generators/apache_age/edge/edge_generator.rb

@@ -2,13 +2,15 @@
 require 'rails/generators'
 require 'rails/generators/named_base'
 
-require_relative '../generate_entity_methods'
+require_relative '../generator_entity_helpers'
 # TODO: get generators to work with custom types!
 # require_relative "#{Rails.root}/config/initializers/types"
 
 module ApacheAge
   class EdgeGenerator < Rails::Generators::NamedBase
-    include ApacheAge::GenerateEntityMethods
+    include ApacheAge::GeneratorEntityHelpers
+
+    desc "Generates edge (model) with attributes."
 
     source_root File.expand_path('templates', __dir__)
     argument :attributes, type: :array, default: [], banner: "field:type field:type"

data/lib/generators/apache_age/edge/templates/edge.rb.tt

@@ -4,10 +4,10 @@ class <%= class_name %>
 <%- attributes_list.each do |attribute| -%>
   attribute :<%= attribute[:name] %>, :<%= attribute[:reference] || attribute[:type] %>
 <%- end -%>
-  # recommendation for (start_node and end_node): change `:vertex` with the 'node' type
+  # recommendation for (start_node and end_node): change `:node` with the actual 'node' type
   # see `config/initializers/apache_age.rb` for the list of available node types
-  attribute :start_node, :vertex
-  attribute :end_node, :vertex
+  attribute :start_node
+  attribute :end_node
 
 <%- attributes_list.each do |attribute| -%>
   validates :<%= attribute[:name] %>, presence: true

data/lib/generators/apache_age/{generate_entity_methods.rb → generator_entity_helpers.rb}

@@ -1,14 +1,17 @@
-# lib/generators/apache_age/generate_entity_methods.rb
+# lib/generators/apache_age/generator_entity_helpers.rb
 
 module ApacheAge
-  module GenerateEntityMethods
+  module GeneratorEntityHelpers
     def generate_age_entity(age_type)
-      template "#{age_type}.rb.tt", File.join(destination_root, "app/#{age_type}s", class_path, "#{file_name}.rb")
+      template(
+        "#{age_type}.rb.tt",
+        File.join(Rails.root, "app/#{age_type}s", class_path, "#{file_name}.rb")
+      )
       add_type_config
     end
 
     def destroy_age_entity(age_type)
-      file_path = File.join(destination_root, "app/#{age_type}s", class_path, "#{file_name}.rb")
+      file_path = File.join(Rails.root, "app/#{age_type}s", class_path, "#{file_name}.rb")
       File.delete(file_path) if File.exist?(file_path)
       remove_type_config
     end

data/lib/generators/apache_age/generator_resource_helpers.rb

@@ -0,0 +1,6 @@
+module ApacheAge
+  # Some helpers for generating scaffolding
+  module GeneratorResourceHelpers
+
+  end
+end

data/lib/generators/apache_age/node/node_generator.rb

@@ -2,11 +2,13 @@
 require 'rails/generators'
 require 'rails/generators/named_base'
 
-require_relative '../generate_entity_methods'
+require_relative '../generator_entity_helpers'
 
 module ApacheAge
   class NodeGenerator < Rails::Generators::NamedBase
-    include ApacheAge::GenerateEntityMethods
+    include ApacheAge::GeneratorEntityHelpers
+
+    desc "Generates node (model) with attributes."
 
     source_root File.expand_path('templates', __dir__)
     argument :attributes, type: :array, default: [], banner: "field:type field:type"

data/lib/generators/apache_age/scaffold_edge/USAGE

@@ -0,0 +1,16 @@
+Description:
+    Explain the generator
+
+Example:
+    bin/rails generate apache_age:scaffold_edge HasPet careciver_role
+
+    This will create:
+        create  app/edge/has_pet.rb
+        modified: config/initializers/types.rb
+        create  app/controllers/has_pets_controller.rb
+        route  resources :has_pets
+        create  app/views/pets/index.html.erb
+        create  app/views/pets/edit.html.erb
+        create  app/views/pets/show.html.erb
+        create  app/views/pets/new.html.erb
+        create  app/views/pets/partial.html.erb