Forem: Grant Cloyd

The magic of metaprogramming : Examining the has_many association using Active Record's code base - Part 2

Grant Cloyd — Sun, 18 Jul 2021 20:35:58 +0000

This post picks up exactly where we left our intrepid has_many macro for our Teacher class and their books:

class Teacher < ApplicationRecord
has_many :books
end

class Book < ApplicationRecord
belongs_to :teacher
end

Please be sure to refer to part one of this post before diving in any further!

So, when last we left off, we had just gotten back our reflection, and now we are ready to move on to that next line and see our accessors and continue to see the code beneath the Rails magic. We'll take a look at what mixins are in Ruby over the course of this post and how they relate to the accessors in particular.

Line 2 - That's a #{reflection.name} of a different #{mixin.value}!

On to the next line to see what needs to happen.

      define_accessors model, reflection

Okay - I can read what will happen next - even though I don't necessarily know exactly how it will happen. Thanks Ruby and ActiveRecord team for making where we're going fairly clear! We're going to take that reflection we just got back, and we're going to pass it and our model (Teacher) to a #define_accessors method. It seems pretty likely we're going to get to see how our #books and our #books= are finally created here.

If we move further down the page we can find the #define_accessors class method and start to unravel it and the subsequent methods that will get us back what we need.

def self.define_accessors(model, reflection)
      mixin = model.generated_association_methods
      name = reflection.name
      define_readers(mixin, name)
      define_writers(mixin, name)
    end

Great! We're at the place where they're about to be defined. But before we get there - we've got a mixin variable. So, what's that about? For a quick answer, we can look to this short Geeks for Geeks post which explains:

"When a class can inherit features from more than one parent class, the class is supposed to have multiple inheritance. But Ruby does not support multiple inheritance directly and instead uses a facility called mixin. Mixins in Ruby allow modules to access instance methods of another one using the include method. Mixins provide a controlled way of adding functionality to classes."

This will hopefully make a little more sense as we move into the method itself. The file points to a more abstract method than most of what we've come across so far.

def generated_association_methods # :nodoc:
        @generated_association_methods ||= begin
          mod = const_set(:GeneratedAssociationMethods, Module.new)
          private_constant :GeneratedAssociationMethods
          include mod

          mod
        end
      end

We can see that there is an instance method that either already exists or which will point to a place in memory where a block is passed that will create the instance variable mod (the new Module class that is created). From the ruby docs, const_set, "Sets the named constant to the given object, returning that object," and then, "[c]reates a new constant if no constant with the given name previously existed." This seems in line with the usage of the ||= portion which points to either something that exists or something that needs to be set to point to the following line of code. I've spent sometime looking at this method and I still find it a little strange. My assumption with this overall method is that it is a method that is used in multiple places in the code base, and in order to make it more flexible and dynamic it can either create a new version of generated methods or leave it alone if it already exists. Ensuring that is the intended logic would likely take a much deeper dive into the code base. However, as we spent a little time broadly exploring the HasManyAssocation class when it would have been passed in earlier, it seems likely that our necessary methods are already set rather than needing to be created again and simply need to be attached to our class.

If we look back at the first line to what the generated_assocation_methods is being called on (our Teacher model), we can see that whether we needed to generate more methods or if our methods already existed, the new module is being added to the model class as an instance variable called @generated_assocation_methods. This seems to line up quite nicely with our definition of a mixin in which multiple class inheritances are able to be combined to create what will ultimately allow our Teacher class to make use of our specific instance of those private HasManyAssocation instance methods. It seems like this is starting to come together

Once the mod is done, it is returned and we can move on to the last few lines in our #define_accessors method.

    name = reflection.name
      define_readers(mixin, name)
      define_writers(mixin, name)

Our reflection name is accessed from the the reflection variable (our books) and then we have two more methods define_readers and define_writers that we will need to - once again - scroll down the file to locate.

    def self.define_readers(mixin, name)
      mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
        def #{name}
          association(:#{name}).reader
        end
      CODE
    end

    def self.define_writers(mixin, name)
      mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
        def #{name}=(value)
          association(:#{name}).writer(value)
        end
      CODE
    end

The class_eval method is part of the Ruby language itself, Ruby Docs, and is a method that, "Evaluates the string or block in the context of mod, except that when a block is given, constant/class variable lookup is not affected. This can be used to add methods to a class." Which is exactly what it is doing in our case, the heredoc will ultimately resolve as a string and opens with <<-CODE and closes with CODE. From googling, the __FILE__ portion seems to be a way in Ruby to reference the current file that the code is running in, and unsurprisingly, the __LINE__ refers similarly to the current line. My assumption here in terms of the problem it might be solving is that when the methods are generated, they are being created in a way that if the program does not move to the next available line before generating the code, each time a method is created (after the first method) it would cause the program to run into an error as an end would proceed a def on the same line. These two methods are where our getter and setter methods are actually defined. However, the way they're written is so dynamic that (assuming we've missed all those possible errors along the way) we can pass so many different names and associations in to Rails and always get our specific named variation back. The magic is advanced and clever usage of interpolation to create whatever is needed! These particular methods should help give us the #books and `#books=, but this style of generating method writers appears elsewhere in the ActiveRecord code base.

As an example - take a look at these methods from our CollectionAssocation class, the parent of our HasManyAssocation, which would have been generated previously during the creation of our reflection:

`
mixin.class_eval <<-CODE, FILE, LINE + 1
def #{name.to_s.singularize}_ids
association(:#{name}).ids_reader
end
CODE
end

def self.define_writers(mixin, name)
  super

  mixin.class_eval <<-CODE, __FILE__, __LINE__ + 1
    def #{name.to_s.singularize}_ids=(ids)
      association(:#{name}).ids_writer(ids)
    end
  CODE
end

Looks pretty similar right? Here - it's making sure though that instead of passing 'books' as the variable to a string it will pass the id of a 'book'. This follows a somewhat similar pattern that we saw before when we came across the #camelize method elsewhere. These are the kinds of methods and writing that generate the convention that makes using Rails relatively easy.

Ultimately, because we're making a has_many association, we'll get the following commands back from similar reader/writer pairs throughout the process of generating this specific macro:

Teacher#books.empty?, Teacher#books.size, Teacher#books, Project#books<<(book), Teacher#books.delete(book), Teacher#books.destroy(book), Teacher#books.find(book_id), Teacher#books.build, Teacher#books.create

So we can check to see if if this teacher has any books (which would be stored in an array and the method would return a boolean), how many books (if any) are stored in that array, return an array that contains all of the books objects, shovel in another book into our books array, delete a specific book by passing in the specific book instance we want to get rid of, run the same operation except destroy it (which would allow callbacks to run, if they have been set up, that could, for example, destroy other associations that might reference the deleted object). Nice so we must be done now right?

No! Not even close! There are still two more methods to go before our reflection is passed back to us which will further tether our reflection (our individualized BooksHasManyAssocation) to our model (Teacher).

define_callbacks model, reflection define_validations model, reflection reflection end

In our case though, we did not define any callbacks, such as this very readable method from the Active Record docs

`
before_validation :ensure_login_has_a_value

private
def ensure_login_has_a_value
if login.nil?
self.login = email unless email.blank?
end
end
`
This callback method will check if a login variable (essentially a username) which is possibly being passed through an HTTP request exists, and if that variable does not exist upon arrival, the object that has been passed will have the login set to the email argument that would have been passed - unless that too was passed as a nil using the #blank? method to check. That callback is then set-up using the before_validation macro to instruct the program exactly when during the creation process, or lifecycle, of this method to utilize the provided method.

We also did not define any validations on our class - such as:

validates :books, presence: true

Which ... in fairness would be a rather strange thing to define given our current example. But those methods will still need to be traversed before the Assocation can make it's way back to us. However, we've come to the end of our two lines and will leave those methods for another day and a part three if these posts receive enough attention.

On a personal note - it's humbling and wonderful to be able to learn from programmers who are far more experienced than I am just by just being able to look at their code in GitHub - especially if it is also well documented like Rails and the Active Record team have done in this case. The ability to move back and forth between those pieces of information are truly invaluable to increasing my understanding of both the language, the framework, and coding in general and I'd recommend others reading this post to not be afraid to do the same.

And again, as mentioned in my previous post, if there are more experienced programmers who can see errors in my explanation and who have somehow made it this far without clawing your eyes out and banging your head against a wall - please chime in and explain any and all mistakes!

While I can't pretend to have fully pulled back the curtain of ActiveRecord or even all of has_many with these posts - and assuredly some explanations are inadequate - I hope that the process of working with Rails continues to look less like magic and more like:

The magic of metaprogramming : Examining the has_many association using Active Record's code base - Part 1

Grant Cloyd — Sun, 18 Jul 2021 20:34:40 +0000

It's Magic

When working with Rails, its capacity for metaprogramming and adherence to convention over configuration can make programming basically feel like this:

This is okay! In fact, it's wonderful to see just how little boilerplate coding is necessary for each new model and its associations. For example, let's look at the following code:

class Teacher < ApplicationRecord
has_many :books
end

class Book < ApplicationRecord
belongs_to :teacher
end

These few lines of code allow you to do many things based on the methods that are extended to the Teacher and Book class by using ActiveRecord's Base module. Perhaps most powerfully though, is how it lets one take any instance of the Teacher class and access all instances of the Book class associated with that teacher instance by invoking the .books accessor method. But how?

No - it's Code

So - a lot is clearly being generated under the hood in the above example. To figure out how passing has_many :books could make the associations and build out the methods for our Teacher class, I started by looking at the documentation before diving into the GitHub repo for Active Record to look at the source code to see what I could uncover. This turned out to be a somewhat ambitious project so I ultimately decided to split this up into two separate blog posts. In order to understand this, we'll need to spend some time uncovering what reflections are in ActiveRecord in this blog post before moving on to what the define_accessors method is doing, and what mixins are in Ruby in the next. So let's get this duology off the ground!

While my initial forays have not enabled me to grasp every part of the code base - and there will be gaps in my explanation - I hope it will at least provide some understanding and provoke the desire for additional exploration for you!

The starting point was to look at the ActiveRecord docs for additional information on the has_many assocation.

The use of this macro, :has many, will call a method that takes the following parameters:

(name, scope = nil, **options, &extension)

So we'll get the name of association, the scope which will default to nil if nothing is passed, an options parameter, and the possibility for passing in a block as an extension. But how are these parameters passed in? It's not very clear from the above example how the method receives these options.

Fortunately Rails is well documented and the way to accomplish these tasks are just below the explanation of possible methods that can be utilized. For the scope: "You can pass a second argument scope as a callable (i.e. proc or lambda) to retrieve a specific set of records or customize the generated query when you access the associated collection." So an example for us might be to pass something like the following to restrict the books to only books published within the last ten years.

has_many :books, -> { where(book_age > 10) }

Options has a lot of possible ways that you can specify how you're getting your data or how your data is coming back to you. Perhaps the most common example would be the :through option, which allows you to use an intermediary class that operates as a join table between two other classes so that you can access pertinent information -through- a connected class. Other possible options include :source if you need to specify a different class name to prevent overlapping accessor methods and :dependent if you wanted to set a way to destroy multiple associations when a #destroy method is called. The syntax for creating an option mirrors how to pass in a scope parameter.

Lastly, there are extensions which are passed as blocks and define methods within body of the block. These custom methods allow you to create unique ways of interacting with your model that could enable you to generate additional accessor, creator, or associate the instances in other ways with one another.

While this is great information - and we could certainly stop here if we just want to know how to do something - it doesn't really answer the question of how these things are actually being created under the hood. So - off to the Rails Github repo!

We're Off

After stumbling around the labyrinth of ActiveRecord files, my searching lead me to this ruby file which handles all macro definitions that are created by our association method call. Every has_many, belongs_to, and belongs_to_one you have written have effectively been passed to this block of twelve lines of code twelve lines of code:

def self.build(model, name, scope, options, &block)
      if model.dangerous_attribute_method?(name)
        raise ArgumentError, "You tried to define an association named #{name} on the model #{model.name}, but " \
                             "this will conflict with a method #{name} already defined by Active Record. " \
                             "Please choose a different association name."
      end

      reflection = create_reflection(model, name, scope, options, &block)
      define_accessors model, reflection
      define_callbacks model, reflection
      define_validations model, reflection
      reflection
    end

While twelve lines may not seem like a lot, it will take a lot more time and code parsing to try to understand what is happening here.

The first half of the #build method is fairly intuitive - it is a class level method which is called and is passed five arguments - the model, the name, the scope, the options and an optional block statement. So while we haven't seen the fact that the model is called in the documentation - when we go under the hood - we can see how the particular model is brought into the method that will create the association. The model will refer to our class model - so in our example above - it would be the Teacher. The name parameter refers to the name of the association. In our case, the :books symbol is being passed in here. The scope and options will line up with our corresponding understanding from starting in the ruby docs and and would be defined as nil in our above Teacher class. As a side note, as we work through the code you'll see examples of the options so let's put a pin it that for a moment for when we come back it. Finally, there is an optional block that can be passed in via the &block parameter - which we know would refer to any custom extensions we might want to add.

Next, there is some error handling happening. This particular error seems to be handling for this exception listed in the Active Record Docs:

"Don’t create associations that have the same name as instance methods ... of ActiveRecord::Base. Since the association adds a method with that name to its model, using an association with the same name as one provided by ActiveRecord::Base will override the method inherited through ActiveRecord::Base and will break things. For instance, 'attributes' and 'connection' would be bad choices for association names, because those names already exist in the list of ActiveRecord::Base instance methods." In short, if there is a conflict with the association name that you passed in and it falls under a declared method name from within ActiveRecord, it will politely tell you, "Hey friend - that's already in use. Have you thought about trying something else?"

Our :books should have no trouble clearing this error handling so we can move forward!

These two lines hide multitudes

   reflection = create_reflection(model, name, scope, options, &block)
      define_accessors model, reflection

The following becomes a bit more dense so this post will focus on tracking down just these the first line to the best that our rookie Ruby skills can manage. Part two will focus on the second line.

Line One - Reflections and Options and Extensions, Oh My!

For the first line, we don't have to go travel far as the method create_reflection is defined further down the page.

    def self.create_reflection(model, name, scope, options, &block)
      raise ArgumentError, "association names must be a Symbol" unless name.kind_of?(Symbol)

      validate_options(options)

      extension = define_extensions(model, name, &block)
      options[:extend] = [*options[:extend], extension] if extension

      scope = build_scope(scope)

      ActiveRecord::Reflection.create(macro, name, scope, options, model)
    end

Here are passing in the same arguments from our build method, and having an additional step for error handling. The association cleared the fact that it wasn't dangerous - but was it written as a symbol? In our case - yes - :books is a symbol. Validate options is declared further down the file and it handles error handling for any passed in options. We haven't passed any that we need to concern ourselves with - so I'll step over that to focus on the extension creation. Even though we haven't passed any extensions, it's worth taking a look at this method to see a little bit behind the curtain.

The #define_extension method points to this location in collection_assocation.rb file


   def self.define_extensions(model, name, &block)
      if block_given?
        extension_module_name = "#{name.to_s.camelize}AssociationExtension"
        extension = Module.new(&block)
        model.const_set(extension_module_name, extension)
      end
    end

This checks to see if a block was given. If so, it's here that it generates an association extension that has a CamelCase name. We can note where some of Rail's convention logic comes into play. If there is not a class called Book that our Teacher class can associate to, this association will not connect to anything. This is why a class called book won't work because it doesn't adhere to the camel cased creation happening throughout the codebase. This helps create our extension which is generated with a new Module class using our passed in block. If we were adding anything, our model would receive the extension model via the #const_set. Instead, as we won't meet the conditional requirement, we will simply jump down to the bottom of the method and hit our end to move move back and look at the options.

  options[:extend] = [*options[:extend], extension] if extension

      scope = build_scope(scope)

Our options[:extend] key is updated to include all of the components previously inside of our :extend and our newly minted extension (if we had one) would be added and now made to be part of an array. This then moves us towards building our
scope variable which is created by passing our scope to the build_scope method.

   def self.build_scope(scope)
      if scope && scope.arity == 0
        proc { instance_exec(&scope) }
      else
        scope
      end
    end

Within this method, our scope is then checked as part of a conditional. If it exists AND when #arity method is invoked on the scope variable (#arity is part of Ruby and returns, per the docs, "an indication of the number of arguments accepted by a method") it return that we have 0 arguments being accepted, then it uses a proc method to create a new variable which which, in turn, creates a hash that stores what the scope will be and returns it. While I do not entirely understand this, I believe what it does is if our scope variable has no arguments when it is passed in (like ours would in this case), this line creates the properties necessary to prevent any errors as scope is passed around later during the creation process. My reasoning is because if the scope is passed in and it clears this hurdle - that is - it possesses more than 0 arguments, it will instead simply be returned fully intact. So if the scope exists - leave it be. If it doesn't - let's 'create' it here - hence the build_scope method name.

So now that scope has been passed back we're left with:

 ActiveRecord::Reflection.create(macro, name, scope, options, model)
    end

So now we're almost to the end of this method - but before we get there .. we have to make a little trip to find our Reflection module and see what is being created here. It looks like this little method is the culprit:

 def create(macro, name, scope, options, ar)
        reflection = reflection_class_for(macro).new(name, scope, options, ar)
        options[:through] ? ThroughReflection.new(reflection) : reflection
      end

So it creates a reflection, which, according to the docs is what "enables the ability to examine the associations and aggregations of Active Record classes and objects. This information, for example, can be used in a form builder that takes an Active Record object and creates input fields for all of the attributes depending on their type and displays the associations to other objects." It looks like we've stumbled right into what will help with the heavy lifting of setting associations.

Here we can also see another place where an option is possible. Since we did not pass in the option of :through and define a way that teachers might connect to another model through the :books accessor, when we finish with the reflection_class_for, we will simply return the reflection rather than creating a new ThroughReflection instance when we eventually hit the ternary statement. But - we're not there yet so let's not get too ahead of ourselves! Instead we now have a new definition to track down - the reflection_class_for method. Well let's scroll down through this file and see ..

        def reflection_class_for(macro)
          case macro
          when :composed_of
            AggregateReflection
          when :has_many
            HasManyReflection
          when :has_one
            HasOneReflection
          when :belongs_to
            BelongsToReflection
          else
            raise "Unsupported Macro: #{macro}"
          end
        end
    end

Well look at this - it's our good buddy switch case which is checking the symbol associated with our macro and passing a class back. Our little :has_many that started its journey oh so long ago is finally looking back at us! We won't hit that error at the end because we typed it correctly so let's scroll down the file to find the HasManyReflection below ...

  class HasManyReflection < AssociationReflection # :nodoc:
      def macro; :has_many; end

      def collection?; true; end

      def association_class
        if options[:through]
          Associations::HasManyThroughAssociation
        else
          Associations::HasManyAssociation
        end
      end
    end

Okay - seems fairly straight forward. The HasManyReflection inherits from a class called AssocationReflection, and has a few short definitions built in - including if you've set the option for there to be a has_many, through: relationship - it will return the HasManyThroughAssocations module as opposed to the HasManyAssocation module. Otherwise it will define the method of #macro as has_many and create a method #collection? which will be used later to let the builder know if this macro will require a collection (most likely a reference to an array, as we will see later) during creation. Neat.

Okay, so - we can jump back. We've got our macro back - which is a class instance of HasManyAssocations and .new is called on it and we pass in our arguments to get back our particular HasManyAssociation instance. To see more about the HasManyAssociation class itself, you can examine the class here. It will handle a great deal of the functionality that our custom class will ultimately need to make use of when we are working with it in a Rails app. Specifically there are methods that handle when #destroy is called on an object, how the teacher instance will be able access the array that contains its books, how to see the length of the specified association array, and how these pieces of information are updated 'behind the scenes' when books are added or removed from having an association with the teacher.

HasManyAssocations is also an extension of the of the CollectionAssocation class. This class will actually do the work of creating the array that will hold our associations mentioned above. Remember def collection?; true; end awhile ago? If this was false, there would be no need to create a collection. It also creates the setter and getter methods for collection IDs associated - in our case - to specific book foreign ID keys. We'll look at those methods in part two as they will more cleanly line up with the generation of our accessor methods.

After that, our :books macro has been created - but it isn't wired up to all of our specifications quite yet as most of the methods that handle the behavior mentioned above are private methods that, as a user, we're not able to directly access. So, the macro will be passed back as 'reflection' to our starting method and we can move on to the next line of code in the Association class. Do you remember that location?

We're now back in our original method call and we've actually come to the next line. Hoo - it's amazing what one method can do when you have a lot of pure functions, huh?

Take a moment and when you're ready, you can follow me as I endeavor to track down our next line and finish out the method in part two!

As an aside, if there are more experienced programmers who can see errors in my explanation and who have somehow made it this far without clawing your eyes out and banging your head against a wall - please chime in and explain any and all mistakes in the comments!

Examining React's Synthetic Event: the nativeEvent, the eventPhase, and Bubbling.

Grant Cloyd — Thu, 24 Jun 2021 13:13:14 +0000

Perhaps you've just started working with React, and you're working with event handlers and you've noticed that when you get the Event Object back, it doesn't look quite the same as it did in vanilla JS.

What you're getting back instead is the SyntheticEvent (SE) and it contains the original event object in what React has dubbed the nativeEvent (nE).

What is the SyntheticEvent?

Straight from the React Docs, it is "a cross-browser wrapper around the browser’s native event ... except the events work identically across all browsers."

To examine this, I've built a basic React component with an onClick button.

function ButtonDemo(){  

 function showEventDifferences(e) {
      console.log(e)
      console.log(e.nativeEvent)
   }

 return ( 
<div>   
  <button 
  onClick={showEventDifferences}
  className="lookingAtClick">
            Discover Events
    </button>
 </div> )  }

This logs the SE first, and the nE second when clicking the discover events button. If you were to click on button within the demo component, you'd get something like this back:

SyntheticBaseEvent 
{_reactName: "onClick", 
_targetInst: null, 
type: "click", 
nativeEvent: MouseEvent, 
target: button.lookingAtClick, …}
altKey: false 
bubbles: true 
button: 0 
buttons: 0 
cancelable: true 
clientX: 259 
clientY: 618 
ctrlKey: false 
currentTarget: null 
defaultPrevented: false
 detail: 1 
eventPhase: 3
 getModifierState: ƒ modifierStateGetter(keyArg) 
isDefaultPrevented: ƒ functionThatReturnsFalse() 
isPropagationStopped: ƒ functionThatReturnsFalse() 
isTrusted: true
 metaKey: false 
movementX: 0 
movementY: 0 
nativeEvent: MouseEvent {isTrusted: true, 
screenX: 1723, screenY: 752, 
clientX: 259, clientY: 618, …}
 pageX: 259
 pageY: 618 
relatedTarget: null
 screenX: 1723 
screenY: 752 
shiftKey: false
 target: button.lookingAtClick 
timeStamp: 734167.6999999881
 type: "click" view: Window {window: Window, self: Window, 
document: document, name: "", location: Location, …} 
_reactName: "onClick" 
_targetInst: null
 __proto__: Object 


MouseEvent {isTrusted: true, 
screenX: 1723, screenY: 752, 
clientX: 259, clientY: 618, …}
altKey: false
bubbles: true 
button: 0
 buttons: 0 
cancelBubble: false 
cancelable: true 
clientX: 259 
clientY: 618 
composed: true 
ctrlKey: false 
currentTarget: null 
defaultPrevented: false 
detail: 1
 eventPhase: 0 
fromElement: null 
isTrusted: true 
layerX: 259 
layerY: 618 
metaKey: false
 movementX: 0 
movementY: 0 
offsetX: 90 
offsetY: 13 
pageX: 259 
pageY: 618 path: (8) [button.lookingAtClick, div,
 div, div#root, body, html, document, Window]
relatedTarget: null 
returnValue: true 
screenX: 1723
 screenY: 752 
shiftKey: false sourceCapabilities: InputDeviceCapabilities 
{firesTouchEvents: false}
 srcElement: button.lookingAtClick target: button.lookingAtClick 
timeStamp: 734167.6999999881 
toElement: button.lookingAtClick
 type: "click" view: Window {window: Window, 
self: Window, document: document, 
name: "", location: Location, …}
 which: 1
 x: 259 
y: 618 
__proto__: MouseEvent

Let's filter that to make it a little more readable. What the SyntheticEvent provides that's different:

SyntheticBaseEvent:
{_reactName: "onClick", 
_targetInst: null, type: "click", 
nativeEvent: MouseEvent, target: button.lookingAtClick, …}
...
eventPhase: 3
 getModifierState: ƒ modifierStateGetter(keyArg) 
isDefaultPrevented: ƒ functionThatReturnsFalse() 
isPropagationStopped: ƒ functionThatReturnsFalse() 
nativeEvent: MouseEvent {isTrusted: 
true, screenX: 1723, screenY: 752, 
clientX: 259, clientY: 618, …}
 _reactName: "onClick" 
_targetInst: null
 __proto__: Object

The mouse event:

MouseEvent {isTrusted: true,
 screenX: 1723, screenY: 752, 
clientX: 259, clientY: 618, …}
cancelBubble: false 
composed: true 
eventPhase: 0
currentTarget: null 
layerX: 259 
layerY: 618 
offsetX: 90 
offsetY: 13 
returnValue: true 
sourceCapabilities: InputDeviceCapabilities 
{firesTouchEvents: false}
 srcElement: button.lookingAtClick 
which: 1
 x: 259 
y: 618 
__proto__: MouseEvent

And their overlap:

altKey: false 
bubbles: true 
button: 0 
buttons: 0 
cancelable: true 
clientX: 259 
clientY: 618 
ctrlKey: false 
defaultPrevented: false
isTrusted: true
metaKey: false
 movementX: 0 
movementY: 0 
pageX: 259
 pageY: 618 
relatedTarget: null
 screenX: 1723 
screenY: 752 
shiftKey: false 
target: button.lookingAtClick 
timeStamp: 734167.6999999881
 type: "click" 
view: Window {window: 
Window, self: Window, document: 
document, name: "", location: Location, …}

When looking at this, what's perhaps surprising is how much this wrapper SE and its nE child have in common. React's SE has bundled at the top level of the SE most of what a dev would need for the majority event handling. This should make the need to drill into the nE relatively uncommon. Except when you need to do something obvious, such as needing to access the MouseEvent 'which' key value. Enjoy trying to Google what that does.

Pulling Back the Curtain

However, some of the differences are also striking. A small one is that you can see a little bit of the abstraction that is taking place under the hood of React with its synthetic wrapper element around the MouseEvent. This was what React is talking about when it discusses how it works across all browsers. Note the __reactName: "onClick", which points to the fact that somewhere in the compilation process (as Javascript is passed through Babel to become JS code that can be read by the browser), there is code that, in rough pseudocode amounts to:

 React.createEvent("OnClick", () => {
 if (browser === Safari){
  {return new React.SyntheticObject(Safari)
}
  else if (browser === Chrome){ 
  {return new React.SyntheticObject(Chrome)}
}
  else if ...

This way of having React handle the heavy lifting is in stark contrast to, for example, working with vanilla CSS, in which one can spend a fair amount of time and additional space writing repetitive code that ensures that the various browsers will display similar looking experiences by adding -webkit-, -moz-, or various other prefixes to ensure compatibility.

Drilling Down to the Root

Beyond giving us a peek at the abstraction, there's something else interesting in this object. Take a look at the proto key. The SE comes with a different class constructor than does the nE! While it is called an Object, this is not the plain old JavaScript object (we'll see that soon enough). Instead, this is where you'll find the .preventDefault(), .stopPropogation() and the now defunct (as of React 17) .persist() method which helped with asynchronous JS due to React previously using a pooling process for its events. When you call any of these methods as part of an event handler function, the reason they work is because they are instanced as part of the SE object itself.

The relatively small SE prototype though is put to shame by the much more massive nE which has a laundry list of getter functions which allow it to create the various components such as the pagex/y locations of the click, if any buttons are being held at the time of the click, and at what time the event happened (among many others). It also shows that the MouseEvent object is not the end of the line as far as the nativeElement constructor. The MouseEvent object itself is an extension of the UIEvent class:

...
__proto__: MouseEvent
(...)
get x: ƒ x()
get y: ƒ y()
__proto__: UIEvent
  bubbles: (...)
  cancelBubble: (...)
  cancelable: (...)
  composed: (...)
  (...)

Which, in turn, is an extension of the Event class ...

...
__proto__: UIEvent
(...)
get which: ƒ which()
__proto__: Event
   AT_TARGET: 2
   BUBBLING_PHASE: 3
   CAPTURING_PHASE: 1
   (...)

And then finally finds its most basic root class which is a plain old JS object.

___proto__: Event
(...)
get timeStamp: ƒ timeStamp()
get type: ƒ type()
__proto__:
   constructor: ƒ Object()
   hasOwnProperty: ƒ hasOwnProperty()
   isPrototypeOf: ƒ isPrototypeOf()
   (...)

Told you we'd get here. So why did we trek down this particular rabbit hole? The point is that React's abstraction can be something of a double edged sword. By adding an additional layer of polish which helps us to write code more quickly and cleanly, it can sometimes make it harder to understand what is actually happening.

event.eventPhase and Bubbling

This brings me to the final example, the event.eventPhase attribute. For greater detail on the .eventPhase, feel free to parse its MDN page, but to keep it short - here it is as follows:

eventPhase = 0 : No event exists.
eventPhase = 1 : The event is being capture. To see this phase, instead of calling onClick in React, make use of the onClickCapture, or add 'Capture' to almost all of the 'onAction' events (ie OnChangeCapture).
eventPhase = 2 : The event has arrived in the code/function and is ready to be used. If there is no *bubbling the eventPhase should terminate here.
eventPhase = 3 : If there is bubbling, the event terminates after this point.

Bubbling refers to the fact that when an event is triggered at the local/initial level, it will then proceed to the parent level to look for additional events and if it finds any it will set those events in motion, and then it will continue through connected ancestor elements until all events have been triggered. This 'upward' movement through parent elements in the DOM structure can help you visualize the term as it 'bubbles up'.

So why does the React onClick element return an eventPhase of 3 when there is nothing else on the page that we have rendered? What is causing the bubbling? If we make a code snippet for vanilla JS that mimics our previous React element, like so:

in index.html:

<body>
      <button class="lookingAtClick">Discover Events</button>
   <script src="./index.js"></script>
 </body>

in index.js :

function testEventPhase(e) {
   console.log(e.eventPhase)
   console.log(e)
}

document.querySelector(".lookingAtClick").addEventListener("click", testEventPhase)

Why do we get back an eventPhase of 2 on our click? Why would a vanilla JS version eventPhase terminate earlier than the React eventPhase?

The answer, which we can probably guess from our eventPhase chart is because bubbling is happening. What might not be clear though is that's because React events always bubble. This isn't new for a click event, but it is different for some other common JavaScript events such as 'focus', 'blur', and 'change' which do not have this behavior in JS. This bubbling won't be an issue for our simple console logging button functional component, but not realizing that all events in React trigger other nested events can lead to rapid-onset baldness when trying to debug your code.

Just remember if this starts happening to you - there is a reason why the aforementioned .stopPropagation() is instanced on the SE class to begin with.

In short, frameworks and libraries can make our lives easier, but they can also make them more confusing if we don't realize that the glossy sheen also has an additional layer of rules, extensions, and interactions on top of our base language. Discovering these nuances and realizing how to troubleshoot the new problems are just part of the process of figuring it all out!

Working with Your First JSON based API

Grant Cloyd — Mon, 31 May 2021 21:24:21 +0000

So you want to work with an API?

Maybe you're just starting to experiment with asynchronous JavaScript and you're wondering now how you can start making use of what you're learning in conjunction with an API to build a small project or app. To start, an API, or Application and Programming Interface, is justing something which allows communication between two programs. Before booting up your text editor of choice and trying to plow through a ton of data the hard way - you can spend some time just working with your browser and your browser console to cement your understanding before writing a single line of code.

Browser Extensions

For people using Chrome or Chrome based web browsers, it can be helpful to get a couple of extensions added in to your browser before starting this process. I like JSON Formatter which will help make the JSON (or JavaScript Object Notation) string format that we'll be looking at easier to read. There are others extensions as well that will make your data easier to read. The second, and far more optional, is Moesif Origin & CORS Changer. This extension can prevent something called a CORS error from happening if you are querying from the browser console. This is far more likely to occur once you are actually coding your app so you you may never need it for what we'll focus on for now, but if you see a message like this:

Cross-Origin Request Blocked: The Same Origin Policy disallows
reading the remote resource at https://url-location. (Reason:
Error Message and additional Information).

the extension should help clear it up!

Acquaint Yourself with Something Called a Query String

A query string is part of the URL structure that assists with setting parameters for your request and can be seen whenever you are searching for something in your browser. For a quick example, open up a new page and go to a search engine of your choice. I would recommend DuckDuckGo over Google for this one, because DuckDuckGo will be easier to parse as it returns the same search for every user regardless of what they enter. Google's search adds ... well ... feel free to take a look after the DuckDuckGo example.

Type anything into your search bar, hit enter, and then look at your URL.

https://duckduckgo.com/?q=cool+APIs&atb=v274-5__&ia=web

For now, just focus on the "?q=cool+APIs" portion of your search. Look at least somewhat familiar? The '?q=' portion represents your query and the rest is going to be whatever you typed in! While not all query strings start with ?q=, it is a common variable naming convention, and it will be important to note if your API handles direct queries.

The next part of the query is '&atb=v274-5__&ia=web' . If it looks like hot nonsense, take a moment and just focus on the '&atb=v24-5' and '&ia=web' portion. It's following the same pattern as our initial search - just with a slightly different syntax. These are additional parameters that DuckDuckGo is passing at the same time it passes our initial query! When working with your API, you can often see similar paths or routes, which will frequently be marked as '&foo=' or possibly '\foo' if it is part of the URL path itself. The idea is similar either way. When you get to the next step, be thinking about what structure it wants you to follow when you request its data.

Now .. you can do the same with Google .. but I wouldn't recommend it.

1)Find an API

There are countless APIs that can provide all kinds of data, but don't start by jumping into the deep end if this is your first time. Start with something small and relatively simple like the Jokes API free version. If you're feeling ambitious, you can try the Pokemon API. Other similar options that will have a lot of data to work with include TV Maze's API or some of ProPublica's free options.
For the time being, you'll want to stay away from any APIs that require authentication for access. You can work on API-keys and OAuth at a later time.

2)Read your Documentation

If you're starting off with a lightweight API this might be very easy. Make sure you know what the primary URL address is, and then start seeing how their end-points have been set-up. These will be ultimately be where you send your fetch request.

If, on the other hand, you're working with something that has a lot of data, the ability to get the data back in multiple formats like XML, or has a lot of parameters or paths available for accessing the information (for example, ProPublica's non-profit API has search parameters for pages, by state, by category, by 501 designation, etc), make note of them, and start thinking about how much of the data you might want to work with for your first project (and making sure you're querying in a way that will return JSON!).

Know that while there are conventions when working with these APIs, every API will be set-up differently. Be sure to also take note of any rate limiting (how frequently you can make requests either per second, day, or other measurement) your API of choice might have in place. Also, when you do get to the actual coding part, be thoughtful while testing your get coding so that you don't - say - call the end-point in any kind of infinite loop.

Odds are high that they're not going to let you keep doing that. Just remember that these are free resources that are letting us experiment, explore, and work with their data.

If you don't understand everything or one part of it after your first pass - that's fine because the next step is:

3)Reread the Documentation

Seriously - this will save you time. It can be tempting to just start diving in and trying to brute force your way through it. The documentation may or may not be dense but the more time you spend with it, the easier it will become. And the more you work with and understand one API, chances are that much higher it will pay off for the next one you want to work with.

4)Now Start Playing Around

If you have the JSON formatter extension installed, the easiest thing to do is to take the endpoint and throw it straight into your browser's http/search bar. Though you may be new to JSON, if you've made it to asynchronous JavaScript, you will likely recognize the way the data is being stored. You will be looking at a combination of nested objects and arrays that use almost the same syntax as JavaScript. You may be looking at a large swatch of many sets of data, or you may be looking at other routes or paths that you can start digging in to.

Using the knowledge that you gleaned from your documentation, you can start trying out your query strings and path options in the browser. Start by figuring out how you can access either the first piece of the data available to you or any one small section of the data. On some, it might be as simple as adding an id number like one at the end of a path:

http://api-url/apipath/1

While '1' might seem rather simple, the idea holds up in . For example to view Propublica's tax records from within it's own API (meta - right?) you could throw this in your browser:

https://projects.propublica.org/nonprofits/api/v2/organizations/142007220.json

It's a longer string but one that follows the preceding format. Others will let you search by name which will often provide a ?q= or ?query= path to note.

By the way - if you look at that Propublica data set or any other and feel a panic at the amount of data that exists - do not be overwhelmed! When you're starting out, you do not need to use every piece of data that every point offers - you just want to familiarize yourself with the form and get accustomed to working with it!

If you start looking around and you start running into something like this:

{"status": 404,
 "error": "Not found"
}

That's okay! As Obi-Wan never said, "These aren't the end-points you're looking for." Go back to the documentation and make sure that you're understanding your pathing and checking your query strings where appropriate.

Once you have that first piece of data, you can open up your browser's devtools (function+F12 works for most browsers/operating systems). For the moment, make sure you're entering the following code in the console on the same page as the end-point you're going to use as fetch requests from an outside domain may be automatically blocked. Navigate to the console portion of devtools, edit the provided URL location below, and throw the following code in:

fetch("your-entire-url-here-passed-as-a-string").then(r=>r.json()).then(console.log)

You should see the same object - but now you can start working with it in your text editor! The fetch() command (which amusingly enough, is a web API itself), when using it for a 'GET' request, works in a similar fashion as when you're making a request from your browser. After that, the first .then() statement helps us parse the JSON structure into a JavaScript data structure, and then the second .then() logs that sweet sweet data to your console. Congrats! You now have your first line of code and can start focusing on the fun things you want to do with it.