datomic-flare 1.0.0

data/docs/templates/dsl.md

@@ -0,0 +1,206 @@
+## Flare DSL
+
+It provides a Ruby-familiar approach to working with Datomic. It brings Ruby’s conventions and idioms while preserving Datomic’s data-first principles and terminology.
+
+This approach should be cozy to those who are familiar with Ruby.
+
+Learn more about Ruby and The Rails Doctrine:
+
+- [About Ruby](https://www.ruby-lang.org/en/about/)
+- [The Rails Doctrine](https://rubyonrails.org/doctrine)
+
+### Creating a Database
+
+```ruby:runnable
+client.dsl.create_database!('radioactive')
+```
+
+```ruby:placeholder
+```
+
+### Deleting a Database
+
+```ruby:runnable
+client.dsl.destroy_database!('radioactive')
+```
+
+```ruby:placeholder
+```
+
+### Listing Databases
+
+```ruby
+client.dsl.databases
+```
+
+```ruby
+['my-datomic-database']
+```
+
+### Transacting Schema
+
+Like `CREATE TABLE` in SQL databases or defining document or record structures in other databases.
+
+```ruby:runnable
+client.dsl.transact_schema!(
+{
+  book: {
+    title: { type: :string, doc: 'The title of the book.' },
+    genre: { type: :string, doc: 'The genre of the book.' },
+    published_at_year: { type: :long, doc: 'The year the book was first published.' }
+  }
+})
+```
+
+```ruby:placeholder
+```
+
+### Checking Schema
+
+Like `SHOW COLUMNS FROM` in SQL databases or checking document or record structures in other databases.
+
+```ruby:runnable
+client.dsl.schema
+```
+
+```ruby:placeholder
+
+```
+
+### Asserting Facts
+
+Like `INSERT INTO` in SQL databases or creating a new document or record in other databases.
+
+```ruby:runnable
+client.dsl.assert_into!(
+  :book,
+  { title: 'Pride and Prejudice',
+    genre: 'Romance',
+    published_at_year: 1813 }
+)
+```
+
+```ruby:placeholder
+```
+
+```ruby:runnable
+client.dsl.assert_into!(
+  :book,
+  [{ title: 'Near to the Wild Heart',
+     genre: 'Novel',
+     published_at_year: 1943 },
+   { title: 'A Study in Scarlet',
+     genre: 'Detective',
+     published_at_year: 1887 },
+   { title: 'The Tell-Tale Heart',
+     genre: 'Horror',
+     published_at_year: 1843 }]
+)
+```
+
+```ruby:state
+state[:wild_heart_entity_id] = result[0]
+state[:scarlet_entity_id] = result[1]
+```
+
+```ruby:placeholder
+```
+
+### Reading Data by Entity
+
+Like `SELECT` in SQL databases or querying documents or records in other databases.
+
+```ruby:runnable/render
+client.dsl.find_by_entity_id({{ state.wild_heart_entity_id }})
+```
+
+```ruby:placeholder
+```
+
+### Reading Data by Querying
+
+Like `SELECT` in SQL databases or querying documents or records in other databases.
+
+```ruby:runnable
+client.dsl.query(
+  datalog: <<~EDN
+    [:find ?e ?title ?genre ?year
+     :where [?e :book/title ?title]
+            [?e :book/genre ?genre]
+            [?e :book/published_at_year ?year]]
+  EDN
+)
+```
+
+```ruby:placeholder
+```
+
+```ruby:runnable
+client.dsl.query(
+  params: ['The Tell-Tale Heart'],
+  datalog: <<~EDN
+    [:find ?e ?title ?genre ?year
+     :in $ ?title
+     :where [?e :book/title ?title]
+            [?e :book/genre ?genre]
+            [?e :book/published_at_year ?year]]
+  EDN
+)
+```
+
+```ruby:state
+state[:tale_heart_entity_id] = result[0][0]
+```
+
+```ruby:placeholder
+```
+
+### Accumulating Facts
+
+Like `UPDATE` in SQL databases or updating documents or records in other databases. However, Datomic never updates data. It is an immutable database that only accumulates new facts or retracts past facts.
+
+```ruby:runnable/render
+client.dsl.assert_into!(
+  :book, { _id: {{ state.tale_heart_entity_id }}, genre: 'Gothic' }
+)
+```
+
+```ruby:placeholder
+```
+
+### Retracting Facts
+
+Like `DELETE` in SQL databases or deleting documents or records in other databases. However, Datomic never deletes data. It is an immutable database that only accumulates new facts or retracts past facts.
+
+Retract the value of an attribute:
+
+```ruby:runnable/render
+client.dsl.retract_from!(
+  :book, { _id: {{ state.tale_heart_entity_id }}, genre: 'Gothic' }
+)
+```
+
+```ruby:placeholder
+```
+
+Retract an attribute:
+
+```ruby:runnable/render
+client.dsl.retract_from!(
+  :book, { _id: {{ state.wild_heart_entity_id }}, genre: nil }
+)
+```
+
+```ruby:placeholder
+```
+
+Retract an entity:
+
+```ruby:runnable/render
+client.dsl.retract_from!(
+  :book, { _id: {{ state.scarlet_entity_id }} }
+)
+```
+
+```ruby:placeholder
+```

data/helpers/h.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Flare
+  module H
+    def self.symbolize_keys(structure)
+      result = {}
+
+      structure.each do |key, value|
+        string_key = key.to_sym
+
+        result[string_key] = value.is_a?(Hash) ? symbolize_keys(value) : value
+      end
+
+      result
+    end
+  end
+end

data/logic/dangerous_override.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Flare
+  module DangerousOverrideLogic
+    CONNECTION_DATABASE_KEYS = [:name].freeze
+
+    DATABASE_KEYS = %i[name latest as_of].freeze
+
+    def self.apply_dangerous_overrides_to_payload(path, overrides, payload)
+      case path
+      when 'datomic/create-database', 'datomic/delete-database',
+           'datomic/get-database-names', 'datomic/list-databases',
+           'meta',
+           'datomic/_debug/as-peer/create-database',
+           'datomic/_debug/as-peer/delete-database'
+        payload
+      when 'datomic/transact'
+        inject_connection_overrides(overrides, payload)
+      when 'datomic/entity', 'datomic/datoms'
+        inject_database_overrides(overrides, payload)
+      when 'datomic/q'
+        inject_database_overrides_into_inputs(overrides, payload)
+      else
+        raise "Unexpected path: '#{path}'"
+      end
+    end
+
+    def self.inject_connection_overrides(overrides, payload)
+      if !overrides.key?(:database) || overrides[:database].slice(
+        *CONNECTION_DATABASE_KEYS
+      ).empty?
+        return payload
+      end
+
+      payload[:connection] = {} unless payload.key?(:connection)
+
+      payload[:connection][:database] = {} unless payload[:connection].key?(:database)
+
+      payload[:connection][:database] = payload[:connection][:database].merge(
+        overrides[:database].slice(*CONNECTION_DATABASE_KEYS)
+      )
+
+      payload
+    end
+
+    def self.inject_overrides_into_input(overrides, input)
+      input_has_latest = input[:database].key?(:latest)
+
+      input_has_as_of = input[:database].key?(:as_of)
+
+      overrides_has_as_of = overrides[:database].key?(:as_of)
+      overrides_has_latest = overrides[:database].key?(:latest)
+
+      input[:database] = input[:database].except(:latest) if input_has_latest && overrides_has_as_of
+
+      input[:database] = input[:database].except(:as_of) if input_has_as_of && overrides_has_latest
+
+      input[:database] = input[:database].merge(
+        overrides[:database].slice(*DATABASE_KEYS)
+      )
+
+      input
+    end
+
+    def self.inject_database_overrides_into_inputs(overrides, payload)
+      if !overrides.key?(:database) || overrides[:database].slice(
+        *DATABASE_KEYS
+      ).empty?
+        return payload
+      end
+
+      payload[:inputs] = {} unless payload.key?(:inputs)
+
+      index_for_database = payload[:inputs].index do |input|
+        input.key?(:database)
+      end
+
+      if index_for_database.nil?
+        require 'pry'
+        binding.pry
+      end
+
+      payload[:inputs][index_for_database] = inject_overrides_into_input(
+        overrides,
+        payload[:inputs][index_for_database]
+      )
+
+      payload
+    end
+
+    def self.inject_database_overrides(overrides, payload)
+      if !overrides.key?(:database) || overrides[:database].slice(
+        *DATABASE_KEYS
+      ).empty?
+        return payload
+      end
+
+      payload[:database] = {} unless payload.key?(:database)
+
+      payload[:database] = inject_overrides_into_input(
+        overrides,
+        { database: payload[:database] }
+      )[:database]
+
+      payload
+    end
+  end
+end

data/logic/querying.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Flare
+  module QueryingLogic
+    def self.entity_to_dsl(entity)
+      namespace = entity.keys.find { |key| key != ':db/id' }
+
+      return nil if namespace.nil?
+
+      namespace = namespace.split('/').first.sub(/^:/, '').to_sym
+
+      {
+        namespace => keys_to_dsl(entity)
+      }
+    end
+
+    def self.keys_to_dsl(entity)
+      result = {}
+
+      entity.each do |key, value|
+        # TODO: Is this correct? Should the 'id' exist?
+        dsl_key = if [':db/id', 'id'].include?(key)
+                    :_id
+                  else
+                    key.split('/').last.to_sym
+                  end
+
+        result[dsl_key] = value.is_a?(Hash) ? keys_to_dsl(value) : value
+      end
+
+      result
+    end
+  end
+end

data/logic/schema.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../helpers/h'
+
+require_relative 'types'
+
+module Flare
+  module SchemaLogic
+    QUERY = <<~EDN
+      [:find
+          ?e ?ident ?value_type ?cardinality ?doc
+          ?unique ?index ?no_history
+       :in $
+       :where
+         [?e :db/ident ?ident]
+
+         [?e :db/valueType ?value_type_id]
+         [?value_type_id :db/ident ?value_type]
+
+         [?e :db/cardinality ?cardinality_id]
+         [?cardinality_id :db/ident ?cardinality]
+
+         [(get-else $ ?e :db/doc "") ?doc]
+
+         [(get-else $ ?e :db/unique -1) ?unique_id]
+         [(get-else $ ?unique_id :db/ident false) ?unique]
+
+         [(get-else $ ?e :db/index false) ?index]
+         [(get-else $ ?e :db/noHistory false) ?no_history]]
+    EDN
+
+    NON_SCHEMA_NAMESPACES = %w[
+      db
+      db.alter db.attr db.bootstrap db.cardinality db.entity db.excise
+      db.fn db.install db.lang db.part db.sys db.type db.unique
+      fressian
+    ].freeze
+
+    def self.specification_to_edn(specification)
+      edn_schema = specification.flat_map do |namespace, attributes|
+        attributes.map.with_index do |(attribute, options), i|
+          fields = [
+            "#{i.zero? ? '' : ' '}{:db/ident       :#{namespace}/#{attribute}",
+            "  :db/valueType   #{TypesLogic.ruby_to_datomic_type(options[:type])}",
+            "  :db/cardinality #{TypesLogic.ruby_to_datomic_cardinality(options[:cardinality] || :one)}"
+          ]
+
+          fields << "  :db/doc         \"#{options[:doc]}\"" if options[:doc]
+          fields << "  :db/unique      #{TypesLogic.ruby_to_datomic_unique(options[:unique])}" if options[:unique]
+          fields << '  :db/index       true' if options[:index]
+          fields << '  :db/noHistory   true' if options[:history] == false
+
+          fields[fields.size - 1] = "#{fields.last}}"
+
+          fields.join("\n")
+        end
+      end.join("\n\n")
+
+      "[#{edn_schema}]"
+    end
+
+    def self.datoms_to_specification(datoms)
+      specification = {}
+
+      datoms.filter do |datom|
+        !NON_SCHEMA_NAMESPACES.include?(datom[1].split('/').first)
+      end.each do |entry|
+        namespace, attribute = entry[1].split('/')
+        type = TypesLogic.datomic_to_ruby_type(entry[2])
+        cardinality = TypesLogic.datomic_to_ruby_cardinality(entry[3])
+        doc = entry[4].empty? ? nil : entry[4]
+
+        unique = entry[5] ? TypesLogic.datomic_to_ruby_unique(entry[5]) : false
+        indexed = entry[6]
+        no_history = entry[7]
+
+        specification[namespace] ||= {}
+        specification[namespace][attribute] = {
+          type:,
+          cardinality:,
+          doc:,
+          unique:,
+          index: indexed,
+          history: !no_history
+        }
+      end
+
+      H.symbolize_keys(specification)
+    end
+  end
+end

data/logic/transacting.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'types'
+
+module Flare
+  module TransactingLogic
+    def self.retractions_to_edn(namespace, retractions)
+      edn = retractions.map do |retraction|
+        retraction_to_edn(namespace, retraction)
+      end
+
+      "[#{edn.join("\n ")}]"
+    end
+
+    def self.retraction_to_edn(namespace, retraction)
+      id = retraction[:_id]
+
+      attributes = retraction.except(:_id)
+
+      if attributes.empty?
+        # Built-In Transaction Functions
+        # https://docs.datomic.com/transactions/transaction-functions.html#built-in
+        "[:db/retractEntity #{id}]"
+      else
+        attributes.map do |attribute, value|
+          if value.nil?
+            "[:db/retract #{id} :#{namespace}/#{attribute}]"
+          else
+            "[:db/retract #{id} :#{namespace}/#{attribute} #{TypesLogic.to_datomic_value(value)}]"
+          end
+        end
+      end
+    end
+
+    def self.transactions_to_edn(namespace, transactions)
+      edn = transactions.map do |transaction|
+        attributes = transaction.map.with_index do |(attribute, value), i|
+          ident = if %i[_id _temporary_id].include?(attribute)
+                    ':db/id'
+                  else
+                    ":#{namespace}/#{attribute}"
+                  end
+
+          "#{i.zero? ? '' : '  '}#{ident} #{TypesLogic.to_datomic_value(value)}"
+        end.join("\n")
+
+        "{#{attributes}}"
+      end.join("\n ")
+
+      "[#{edn}]"
+    end
+  end
+end

data/logic/types.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'bigdecimal'
+
+module Flare
+  module TypesLogic
+    def self.to_datomic_value(value)
+      case value
+      when String
+        to_datomic_string(value)
+      when Integer
+        value.to_s
+      when Float
+        value.to_s
+      when BigDecimal
+        # https://github.com/relevance/edn-ruby/blob/master/lib/edn/core_ext.rb#L25
+        "#{value.to_s('F')}M"
+      when Integer, Float, TrueClass, FalseClass
+        value.to_s
+      when Time, DateTime, Date
+        to_datomic_instant(value)
+      when Symbol
+        ":#{value}"
+      when Array
+        '[' + value.map { |v| to_datomic_value(v) }.join(' ') + ']'
+      when NilClass
+        'nil'
+      when Hash
+        raise ArgumentError, "Missing :_id for reference: #{value.class}" unless value.key?(:_id)
+
+        "{:db/id #{value[:_id]}}"
+      else
+        raise ArgumentError, "Unsupported value type: #{value.class}"
+      end
+    end
+
+    def self.to_datomic_string(value)
+      # https://github.com/relevance/edn-ruby/blob/master/lib/edn/core_ext.rb#L36
+      array = value.chars.map do |ch|
+        if %w[" \\].include?(ch)
+          "\\#{ch}"
+        else
+          ch
+        end
+      end
+      "\"#{array.join}\""
+    end
+
+    def self.to_datomic_instant(value)
+      time = case value
+             when Time
+               value
+             when Date
+               value.to_time
+             end
+
+      "#inst \"#{time.utc.strftime('%Y-%m-%dT%H:%M:%S.%L%:z')}\""
+    end
+
+    def self.ruby_to_datomic_type(ruby_type)
+      case ruby_type
+      when :string    then ':db.type/string'
+      when :long      then ':db.type/long'
+      when :boolean   then ':db.type/boolean'
+      when :double    then ':db.type/double'
+      when :instant   then ':db.type/instant'
+      when :keyword   then ':db.type/keyword'
+      when :uuid      then ':db.type/uuid'
+      when :ref       then ':db.type/ref'
+      when :bigdec    then ':db.type/bigdec'
+      when :bigint    then ':db.type/bigint'
+      when :uri       then ':db.type/uri'
+      else
+        raise ArgumentError, "Unknown type: #{ruby_type}"
+      end
+    end
+
+    def self.ruby_to_datomic_cardinality(cardinality)
+      case cardinality
+      when :one  then ':db.cardinality/one'
+      when :many then ':db.cardinality/many'
+      else
+        raise ArgumentError, "Unknown cardinality: #{cardinality}"
+      end
+    end
+
+    def self.ruby_to_datomic_unique(unique_type)
+      case unique_type
+      when :identity then ':db.unique/identity'
+      when :value    then ':db.unique/value'
+      when nil       then nil
+      else
+        raise ArgumentError, "Unknown uniqueness constraint: #{unique_type}"
+      end
+    end
+
+    def self.datomic_to_ruby_type(datomic_type)
+      datomic_type = ":#{datomic_type}" unless datomic_type.start_with?(':')
+      case datomic_type
+      when ':db.type/bigdec'  then :bigdec
+      when ':db.type/bigint'  then :bigint
+      when ':db.type/boolean' then :boolean
+      when ':db.type/bytes'   then :bytes
+      when ':db.type/double'  then :double
+      when ':db.type/float'   then :float
+      when ':db.type/instant' then :instant
+      when ':db.type/keyword' then :keyword
+      when ':db.type/long'    then :long
+      when ':db.type/ref'     then :ref
+      when ':db.type/string'  then :string
+      when ':db.type/symbol'  then :symbol
+      when ':db.type/tuple'   then :tuple
+      when ':db.type/uuid'    then :uuid
+      when ':db.type/uri'     then :uri
+      else
+        raise ArgumentError, "Unknown Datomic type: #{datomic_type}"
+      end
+    end
+
+    def self.datomic_to_ruby_unique(datomic_unique)
+      datomic_unique = ":#{datomic_unique}" unless datomic_unique.start_with?(':')
+      case datomic_unique
+      when ':db.unique/value' then :value
+      when ':db.unique/identity' then :identity
+      else
+        raise ArgumentError, "Unknown Datomic uniqueness: #{datomic_unique}"
+      end
+    end
+
+    def self.datomic_to_ruby_cardinality(datomic_cardinality)
+      datomic_cardinality = ":#{datomic_cardinality}" unless datomic_cardinality.start_with?(':')
+      case datomic_cardinality
+      when ':db.cardinality/one' then :one
+      when ':db.cardinality/many' then :many
+      else
+        raise ArgumentError, "Unknown Datomic cardinality: #{datomic_cardinality}"
+      end
+    end
+  end
+end

data/ports/cli.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'dotenv/load'
+
+require_relative '../controllers/documentation/generator'
+
+module Flare
+  module CLI
+    def self.handle(command)
+      case command
+      when 'docs:generate'
+        Flare::Controllers::Documentation::Generator.handler
+      else
+        puts 'Invalid command.'
+      end
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.empty?
+    puts 'No command provided.'
+  else
+    Flare::CLI.handle(ARGV[0])
+  end
+end

data/ports/dsl/datomic-flare/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative '../../../components/errors'
+
+include Flare::Errors

data/ports/dsl/datomic-flare.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'uuidx'
+
+require_relative '../../static/gem'
+require_relative '../../controllers/client'
+
+module Flare
+  def self.new(...)
+    Controllers::Client.new(...)
+  end
+
+  def self.uuid
+    Uuidx
+  end
+
+  def self.version
+    Flare::GEM[:version]
+  end
+end