Forem: Jolene Langlinais

Vibe Coding Best Practices

Jolene Langlinais — Wed, 10 Sep 2025 03:02:38 +0000

AI coding tools are powerful accelerators, but only if used with intention. Seeing real gains requires structured workflows and making AI part of your discipline, not a shortcut.

Here’s how to get the most out of tools like Cursor and Claude on a serious engineering team:

Plan

Draft plans and iterate with AI to improve it

Ask clarifying questions about edge cases
Have it critique its own plan for gaps
Regenerate an improved version

Save the final plan in a temporary file and reference it in every prompt

✅ Prompting with a well defined plan eliminates the vast majority of "AI got confused halfway through" cases

TDD

Implement code in TDD with AI

Prompt AI to write a failing test that captures the desired goal
Review the test and ensure it captures the correct behavior
Prompt AI to write code to make the test pass
Iterate through running the test and fixing failures

✅ Prompting with human-reviewed tests results in implemented code passing the correct requirements

Reasoning

Keep this in prompts: Explain your approach step-by-step before writing any code

You need to walk before you can run, and putting adequate time into planning will make the implementation smoother

✅ Prompting for reasoning results in fewer mistakes and the model revealing assumptions

Context Curation

Large projects and dumping context break AI attention. Be intentional on what you include to the context.

Look into these solutions for context curation

Context7 keeps your docs up to date without needing to re-paste snippets
GitIngest curates codebases into summaries digestible for models

Git Safety

Rely on the fundamentals of git to have a fallback point prior to implementing something with AI. Commit granularly and prevent uncommitted changes piling up.

✅ Prompting with a clean git state results in an easier isolation and rollback of AI-introduced bugs

Prompt Focusing

❌ A poorly formed prompt:

"Here's my entire codebase. Why doesn't authentication work?"

Inputting specific problems generate specific solutions.

Inputting vague problems generate hallucinations.

Use specific code terminology in prompts:

Reference the exact identifiers from codebase, not generic business terms
i.e., call createOrder() and processRefund() instead of 'place order' or 'issue refund'

This precision helps the AI apply the correct abstractions and avoids mismatches between your domain language and code.

✅ A well formed prompt:

*@src/auth.ts:85-90 panics on None when JWT is malformed*
Fix this and add proper error handling

File References

References files with @src/database.ts instead of pasting code blocks

✅ Prompting direct file references results in an up-to-date context, fewer used tokens, and a more readable prompt history

Specifications

Prompt exactly what to test:

For the new `validate_email` function, write tests for:
- Valid email formats (basic cases)
- Invalid formats (no @, multiple @, empty string)
- Edge cases (very long domains, unicode characters)
- Return value format (should be `Result<(), ValidationError>`)

✅ Prompting specific test cases results in good test boilerplate generation

Debugging

When stuck, prompt for a systematic breakdown:

Generate a diagnostic report:
1. List all files modified in our last session
2. Explain the role of each file in the current feature
3. Identify why the current error is occurring
4. Propose 3 different debugging approaches

✅ Prompting specific instructions results in systemic thinking, instead of guess-and-check

Style Guidelines

Prompt a styling system in order to receive a consistent code quality:

Code style rules:
- Use explicit error handling, no unwraps in production code
- Include docstrings for public functions
- Prefer composition over inheritance
- Keep functions under 50 lines
- Use `pretty_assertions` in test
- Be explicit about lifetimes in Rust
- Use `anyhow::Result` for error handling in services and repositories.
- Create domain errors using `thiserror`.
- Never implement `From` for converting domain errors, manually convert them

✅ Prompting consistent rules results in consistent code quality

Code Review

Treat every AI change like a junior developer's PR/MR, and thus check for risks such as:

Security Review:

Vulnerabilities (XSS, SQL injection, insecure direct object references, etc.)
Input validation robustness
Information leakage, such as error messages or logging

Performance Review:

N+1 query patterns and expensive loops
Algorithm complexity and efficiency
Unnecessary allocations and other performance bottlenecks

Correctness Review:

Does it handle edge cases correctly?
Verify error handling and null-handling
Are there off-by-one errors or logical flaws?

Maintainability, Scalability, and Readability Review:

Does the code adhere to team standards and established design patterns?
Is the code overly complex? Are names clear?
Should this code even be added?

✅ Prompting with an expectation of AI being smart but not wise results in considering if the feature or change is truly necessary and well-designed

Antipatterns

The "Magic Prompt" Fallacy

❌ Prompting will not be perfect and AI will make mistakes

✅ Prompting with good workflows result in good implementations

Expecting Mind-Reading

❌ Prompting without state requirements do not result in correct inferences

✅ Prompting with specifics results in good implementation

Trusting AI with Architecture Decisions

❌ Prompting a high-level system design results in poor implementation

✅ Prompting with architecture already designed results in good implementation

Ignoring Domain-Specific Context

❌ Prompting without context results in hallucinations

✅ Prompting with direct reference to business logic, deployment constraints, and/or team conventions results in good implementation

Pair Programming

For most implementation tasks, treat AI as a pair programming driver

✅ AI has no ego or judgement, rather it has infinite patience and good memory

❌ AI doesn’t always catch logic errors and rarely pushes back on bad ideas

TL;DR

AI coding tools can significantly boost productivity, but only if you use them systematically. The engineers seeing massive gains aren't using magic prompts, they're using disciplined workflows.

Plan first, test everything, review like your production system depends on it (because it does), and remember two things:

AI is your intern, not your architect
AI is a tool that is only as good as they way in which you use it

ℹ️ The material here is from both my own experience and referencing a blog I found on the subject:

https://forgecode.dev/blog/ai-agent-best-practices/

ChatGPT Prompt Framework

Jolene Langlinais — Tue, 09 Jan 2024 15:09:39 +0000

This prompt engineering framework for ChatGPT acts as a guide for providing a structured set of instructions to the AI model in order to receive fuller, more accurate, and more desirable results.

I call this SPICIER because it is the best anagram I could think of, but it doesn't perfectly match the order of categories.

S.P.I.C.I.E.R.

ℹ️ This, especially Input, can and should be written for a computer, not a human.

Role: Give ChatGPT a persona to give a response through the lens of
Instruction: What you want to get out of ChatGPT
Context: Help ChatGPT understand the context
Input: The input data you want ChatGPT to respond to
Source: Reference websites to help shape the input to results
Exclusions: Further define parameters by omitting undesired results
Parameters: Specify specific options or constraints, i.e. the tone of voice, formatting, length

Example

ROLE:

Act as a software engineer expert in the following:

TypeScript

Node.js

Koa

Prisma

Zod

INSTRUCTIONS:

I will give you my code for a specific Koa middleware and the related Prisma schema

You will change the code to do the following:

Check if something123 exists.

If it does, send a patch to X API and ignore both Prisma and the Airtable response

If it does not, send a post to Y API and create the record in Prisma

CONTEXT:

The submit Koa middleware to handles form submissions

The following are arbitrary unique identifier variables:

something123

something456

CODE:
INSERT CODE
EXCLUSIONS:

Assume my web application code is working and is setup correctly

Node Service Template

Jolene Langlinais — Fri, 28 Jul 2023 15:29:22 +0000

PNK Stack Service

PostgreSQL, Node, and Koa

This acts as a guide for creating a relatively production ready backend micro-service, which can be customized to your needs.

The reference template repository can be found at irmerk/pnk-stack

Stack

Node.js with TypeScript
- Koa
PostgreSQL
- Prisma.io

Setup

All of this page assumes that you are using a Mac and that your software is up to date. If not up to date you may run into install issues when you install the packages below.

Shell

macOS now ships with Zsh as the default shell. If you want more customization and handy shortcuts, you can install oh my zsh.

Terminal Emulator

You can use the Terminal app that ships with macOS, but iTerm2 is a popular and recommended alternative with more features and following. For information regarding prompt customization, see Zsh Prompt.

A helpful setting can also allow you to use Alt/Cmd + Right/Left Arrow in iTerm.

Text Editor / IDE

Use whatever text editor / integrated development environment (IDE) you prefer. At the time of this writing, Visual Studio Code is an extremely popular one with a built-in plugin manager for easily extending and customizing functionality.

For helpful VSCode keyboard shortcuts to incorporate into your workflow, see their Tips and Tricks.

My suggestions for VSCode extensions and keyboard shortcuts.

Command Line Tools

Install the Homebrew package manager for easy and relatively safe installation and upgrades.

Recommended tools:

`nvm`

Manages installations of Node.js and npm:

brew install nvm \
&& mkdir ~/.nvm \
&& echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zprofile \
&& echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh" # This loads nvm' >> ~/.zprofile \
&& source ~/.zprofile

Node.js

Node.js and npm could be installed directly via Homebrew as well, but doing so makes it challenging to switch between versions. Some projects each require specific versions of Node.js and npm versions to work properly, so nvm installations are strongly preferred.

nvm install node

Git

brew install git

Set your name and email address explicitly:

git config --global user.name "<YOUR_NAME>"

git config --global user.email <YOUR_EMAIL>

Docker

Rationale

`Makefile`

Used for clarity and speed.

Koa
I chose Koa because it is newer, less opinionated, lighter weight, and easier to customize than the standard of Express. Koa is modular and customizable because it requires modules for routing, the templating engine, and JSONP. This way, I can create middleware ourselves or use the built-in middleware.
Koa focuses more on modern features of the JavaScript ES6 language, like generators, async functions, and the Node.js runtime. Moreover, it uses promise-based flows and async-await syntax to get rid of callbacks, making the code more manageable, cleaner, and more readable. Because it uses generator syntax instead of callbacks, I can use the yield keyword to exit and then reenter.
Koa uses a context object, which encapsulates req/res objects into one, helping us develop more efficiently by using several helpful methods. Finally, Koa uses cascading middleware. Thanks to asynchronous functions, middleware will run in a cascading fashion until the last middleware is reached.

Axios

HTTP Client Library for Node.js
Comparison to other libraries
I chose axios instead of got because “[the got] package is native ESM and no longer provides a CommonJS export. If your project uses CommonJS, you will have to convert to ESM or use the dynamic import() function. Please don't open issues for questions regarding CommonJS / ESM.”
GOT has issues with linting, TypeScript, ESM/CJS, and JSON.

Logging

The logging transport is configured for logging to the console. This happening in a service set up in a cloud service can be configured to be picked up from STDOUT

Linting

Why I add a new line to the end of a file.

GitHub Actions

npx: When I run a command with npx, it will check whether the command exists in the local node_modules/.bin directory or in the system-wide installed packages. If it doesn't find the command, it will attempt to temporary install the package and execute it. This makes npx an ideal tool to run the locally installed service being called.

Dockerfile & Docker Compose

Dockerfile
- Dockerizing a service allows for it to behave the same regardless of the platform on which it is run. A Dockerfile is a blueprint on which the Docker image is built. When the built image is running, it is called a container. Essentially, the container starts as a Dockerfile that has the instructions on how to build the Docker image. The same image can be used to spin up one or even hundreds of containers, which is why Docker is so useful for software scalability.
- I am using a slim production stage and a more feature-rich, development-focused dev stage.
- Setting NODE_ENV to production can increase performance by 3x.
- Notice some of our commands are put together with an &&, creating fewer Docker layers, which is good for build caching.
- Debian-based images because it may be better in some cases than the more standard alpine linux image.
docker-compose.yml
- Docker Compose is a way to more easily setup multiple services running with Docker in an ecosystem. The big advantage of using Compose is you can define your application stack in a file, keep it at the root of your project repo (it’s now version controlled).
.dockerignore
- Just like I wouldn’t use Git without .gitignore, I use a .dockerignore file to ignore files that I don’t want to land in our Docker image. It helps to keep the Docker image small and keep the build cache more efficient by ignoring irrelevant file changes.
dumb-init
- I use dumb-init because it will be the first process (PID 1) and will handle the signal forwarding and the reaping of the zombie processes. It is a simple process supervisor and init system that helps to handle these situations.
- Docker containers usually run a single application, and for that application, it is normal to expect it to receive signals from the Linux environment. However, when running in the background (as a daemon), the application may not correctly handle the Linux signals, which can lead to zombie processes and not graceful termination.
Multiple Stages
- Optimizing layers with multiple stages (build and production) in the Dockerfile results in a drastically smaller image size:

REPOSITORY      TAG     IMAGE ID        CREATED             SIZE
single-stage    latest  8ceb85286547    4 seconds ago       402MB
multi-stage     <none>  ec0680eefe42    About a minute ago  300MB

Reference

emmanuelnk/RESTful-Typescript-Koa
posquit0/koa-rest-api-boilerplate
inadarei/maikai
banzaicloud/service-tools
[transitive-bullshit/koa-micro][transitive]
Koa Js : Part 1 - How to make a Koa server in 10 minutes!
Sentry's Koa Guide
Health check
- dyhpoon/koa-simple-healthcheck
- rictorres/koa-ping-healthcheck
Docker

Agile Improv

Jolene Langlinais — Tue, 12 Jan 2021 13:05:08 +0000

The Principles of Improv

One of the things I miss most in quarantine is going to see live improv comedy. As often as I could, I used to go see shows at New York City’s Upright Citizen’s Brigade theater and lose my mind laughing at the incredibly talented improvisers there. I even took a few improv classes to try it out myself. On top of being painfully funny, improv has taught me lessons about communication, teamwork, and creativity that I’ve found extremely helpful to apply to my work in software engineering.

Improv isn’t easy, but its principles are simple. The only rules are:

Listen
Say yes
Advance the scene

1. Listen

Active listening is an underrated and undervalued skill. We all know we should do it, but oftentimes we’re merely waiting for our turn to speak or rushing to assert our own ideas. Improvisation emphasizes paying attention, staying present, and interpreting intent.

Listening to your teammates is perhaps the most important part of improv. Stephen Colbert, who got his start in improv, said:

“There are very few rules to improvisation, but one of the things I was taught early on is that you are not the most important person in the scene. Everybody else is. And if they are the most important people in the scene, you will naturally pay attention to them and serve them.”

Serving your fellow improvisers—or, in this case, your colleagues—requires setting aside ego, embracing humility, and placing trust in others.

In improv, neglecting to listen to a fellow performer means the scene won’t make sense. In programming, neglecting to listen to a coworker leads to missing valuable context or information, which often leads to making incorrect assumptions and even taking unnecessary risks.

2. Say yes

Improvisers avoid choices that hinder progress such as discouraging their teammates, shooting down ideas, or being contrarian. Instead, they make a habit of accepting the reality with which they are presented.

The Agile method of software engineering is a world-building exercise that is, in some ways, uncannily similar to improv. It advocates for responding to change rather than following a plan and it values individuals and interactions over processes and tools. Its reaction-and-response approach generates solutions that likely could not have been predicted at the beginning of the process.

Many of the skills valued by both improv and Agile come into play during the brainstorming process. A brainstorming session among colleagues requires a back-and-forth exchange of ideas and feedback. Programming is only possible when engineers are open to hearing new ideas—coding cannot progress if proposals are always struck down.

Saying yes to an idea does not necessarily mean endorsing it as a great idea; it only means accepting the idea as valid and following it to see where it may lead. No idea is great in and of itself—rather, a collection or evolution of ideas and the changes that result from them can lead to something great. Great results can emerge even from poor suggestions. Even if suggestions don’t end up working out, making a habit of exploring them encourages collaborative sharing of ideas.

3. Advance the scene

At its core, improv is not actually about making jokes or being funny—it’s about cooperative creation. When people step outside their comfort zones and let go of their limiting assumptions, rather than being critical or analytical, it enables a connection between them that leads to building, development, and invention.

There is a concept in improv called finding the game, which means finding the crux, the pattern, the thing that is interesting or funny about a scene. The UCB Theatre’s motto is Si haec insolita res vera est, quid exinde verum est?: “If this unusual thing is true, what else is true?” An improviser finds the game of the scene by identifying what is weird/remarkable/funny, then taking action to follow the implications to their natural, and often comical, results.

In software engineering, finding the game is analogous to problem-solving. When solving a technical issue, you have to identify a bug or roadblock before you can resolve it. This requires tackling challenges with creativity, flexibility, and open-mindedness.

Mistakes As Opportunities

Veteran improviser Colin Mochrie said:

“Embracing failure is one of the beautiful things about improv. If the scene is going well, great. But if something goes wrong, sometimes it can be even better. So, it’s just basically relaxing and dealing with whatever is going wrong at that point.”

In coding, like in improv (and everything else in life), mistakes are inevitable. Judging those who fail, including (and especially) yourself, is neither kind nor productive. Pushing past the discomfort of failure is essential for growth, and mistakes can often lead to revelatory discoveries.

A supportive, encouraging workplace environment is one in which the whole team is thought to have collective ownership over the project—that means the successes as well as the failures. This is why a blameless culture is ideal, especially in postmortems. Blame is a variation of saying, "no": we cannot say what someone did was not supposed to happen because there is no such thing in reality as 'supposed to happen'. Blame is a wasted effort, like regret. In a culture where mistakes are forgiven, these experiences become lessons learned. Embracing a challenge turns an obstacle into an opportunity.

Improv host Aisha Tyler also attested to the valuable lessons taught by failure:

“Killing doesn’t make you funny. It’s only bombing that makes you funny. […] When you bomb, you really have to reexamine every creative choice you’ve made and think about if it was the right one.”

Play

A tendency to overthink or overanalyze can cause work to feel chronically stressful. While there is a time and place for intense critical thought, improv provides a framework for avoiding analysis paralysis.

Experience allows for handling the unexpected with grace and competency. Just as improv scenes need to build gradually with solid development of characters and relationships, coding solutions should not be rushed in sacrifice of a good foundation. They both require patience and frustration tolerance.

Remaining playful and loose allows for quick reactions and prevents you from being left behind the action. If an improviser is in their head, they aren’t paying attention to what is happening. If an engineer is too busy planning, they aren’t responding appropriately to changes in real time.

While thoughtful, deliberate action is ideal, environments and situations are always changing in the chaotic real world. Improv thrives on making sense of what is happening at the speed of thought. Likewise, there is no perfect or static software; it changes incessantly in response to continuously changing circumstances. An engineer in Agile is quickly iterating on making sense of a changing landscape.

An improviser steps out on stage with only a few seconds’ worth of an idea in mind, never a whole scene. Similarly, no engineer begins with a flawless start-to-finish plan fully mapped out in their head. It takes the whole team to make a show.

This is the human element shared by improv, programming, and any other collaborative team endeavor. Humans are not machines: we thrive on connection, interaction, and relationships. We work best when we embrace playfulness and fun.

Fun is fun because it is in-the-moment, free from domination of the over-analytical brain. Being in the moment feels liberating. It can be freeing to accept that you do not know what will happen next, to let go of expectations for how things are “supposed to” go.

JavaScript Utility Libraries

Jolene Langlinais — Tue, 29 Dec 2020 18:26:20 +0000

Comparison of JS, Ramda, and Lodash

With ECMAScript 2020 available, external libraries are not necessary for functional programming (FP) - specifically currying and composition. The two main libraries for this kind of work have been Ramda and Lodash FP. UnderscoreJS is another, but Lodash is generally thought of as an improvement on this library. Lodash is a fork of Underscore, and the history of why it forked is rather interesting.

However, it can still be a good idea to use one of these tried-and-tested libraries for more complex situations with FP. If these complex scenarios are not being taken advantage of, vanilla JavaScript can keep up with utility libraries for the most part. Some notable exceptions would be debounce from Lodash and merge from Ramda.

To reiterate, a lot of the benefits that lead to the use of Ramda and Lodash have been baked into vanilla JavaScript. Arrow functions allow for a version of currying, and along with chaining functions, can adequately compose functions. Similarly, prototypal methods are being added every version which makes Lodash less and less useful.

Note: Arrow functions don't allow for actual currying ((a, b) => {} is the same as a => b => {}, i.e. the function itself tracks how many of its arguments have been defined), just quite close.

This article will:

Give a brief overview of Ramda and Lodash (FP)
Note the cases in which it makes sense to invest in the library or not
Give context to a few methods which stand out
Provide a table summary for which library is better in which regard
Provide a REPL and repository for generating benchmarks

All this being public means you are free to contribute to the list and make adjustments

JavaScript

As previously stated, native JavaScript has become quite a bit more powerful over the past few years. While helper and utility libraries are still helpful, most everything in them can be reduced down to some combination of filter(), map(), and reduce().

I write more at length in my Modern Javascript Techniques article.

Use Cases:

Functionality needed is straightforward, with few steps or transformations needed
Complex functionality needing a few extra steps is not a deterrent
Bundle size being important
Learning the process that goes into these simplified helper functions from other libraries

Ramda

Ramda emphasizes a purer functional style, with immutability and side-effect free functions being at the heart of the design philosophy. Ramda is about transforming data and composing functions. This is why things like throttle and debounce are not supported because they involve side-effects. To achieve this in a pure way, functional reactive programming would be required to abstract over this with event streams.

Ramda functions are automatically curried. This allows for easily building up new functions from old ones by not supplying the final parameters. The parameters to Ramda functions are arranged to make it convenient for currying. The data to be operated on is generally supplied last. These last two points together make it very easy to build functions as sequences of simpler functions, each of which transforms the data and passes it along to the next. Ramda is designed to support this style of coding.

Ramda provides several functions that return problematic values such as undefined, Infinity, or NaN when applied to unsuitable inputs. These are known as partial functions. Partial functions necessitate the use of guards or null checks.

A remedy for this could be Sanctuary, a JavaScript functional programming library inspired by Haskell and PureScript. It's stricter than Ramda, and provides a similar suite of functions.

Use Cases:

Composition, taking data last and always currying
Specific methods, typically involving complex operations, e.g. merge, assoc, pluck...
Similar common methods used in multiple places
Complex, non-linear composition by using R.converge()

Lodash

There's little to go into here. Lodash is an extremely performant utility library. While bundle size has been an issue in the past, Lodash has become much more modularized in format. This enables build tools like webpack and parcel to do tree-shaking and removing any unused functions, which reduces bundle size.

Keep in mind that there are many functions which can be done natively.

Note: While Lodash appears faster in the benchmarks below with the _.toString() method, the results were actually not identical to the same functions in JS and Ramda.

Use Cases:

debounce
Similar common methods used in multiple places

Lodash FP

Lodash provides lodash/fp, a module to promote a more functional programming style. This module allows for curried versions of the Lodash functions. This makes Lodash a good alternative to Ramda.

Use Cases:

Composition, taking data last and always currying

Benchmark Results

Note that I have begun this list with common methods I and my team use, and it is in no means exhaustive. Please feel free to look into the repository and open a pull request to add further methods or tests.

	Speed	Readability	Does Have	Does Not Have
Symbols	🔵	🔶	✅	❌

	Javascript	Lodash	Ramda
Downloads (week)	N/A ✅	41,323,748	7,952,372
Size (unpacked)	N/A ✅	1.41 MB	1.07 MB
Size (minified)	N/A ✅	69.9 kB	53.4 kB
Size (mini+gzip)	N/A ✅	24.4 kB	12.4 kB
Download Time	N/A ✅	488 ms	247 ms
Issues	N/A ✅	107	211
Last Publish	N/A ✅	4 month	5 month
FEATURES
Curry	Yes	Yes	Yes
Immutable	No	No	Yes ✅
Chainable	Yes ✅	Yes	Yes
Functional	No	Yes	Yes ✅
SECURITY
Known Issues	No	Yes	No
Dependencies	No	No	No
COMMON METHODS
Arrays
`all`	❌	❌
`concat`			🔵
`each`			🔵
`filter`
`find`
`findIndex`			🔵
`flatten`		🔵
`fromPairs`
`head`
`map`		🔵	🔵
`pluck`	❌	❌
`range`		🔵🔶	🔶
`reduce`		🔵	🔵
`reject`		🔵	🔵
`tail`	🔵	🔵
`uniq`	🔵	🔵🔶	🔶
`zip`	❌		🔵
Objects
`assoc`	❌	❌
`keys`	🔵		🔵
`merge`	❌		🔵
`omit`		🔶	🔵🔶
`path`
`pick`	🔵	🔶	🔵🔶
`toPairs`	🔵		🔵
`values`	🔵
`zipObj`	❌	🔶	🔵🔶
Strings
`toString` array	🔵
`toString` object		🔵
`toString` date
`split`
`toLower`
`toUpper`
Utility
`clone`	🔵	🔵🔶	🔶
`debounce`	❌		❌
`isEmpty`
`isEqual`	❌	🔵
`isFunction`
`isNil`
`type`
Composition
Numbers		🔵
Objects	🔵		🔵
Functional		🔵
Overall	🔵	🔵
Totals	10	16	21

Test: Arrays and Collections

Name	JS Time (ms)	_ Time [ms]	R Time [ms]	Diff to JS
concat	17	19	7	+83%
each	11	15	4	+93%
filter	17	22	14	+19%
find	10	10	7	+35%
findIndex	11	15	6	+58%
flatten (deep)	1438	174	1937	+156%
fromPairs	531	512	513	+3%
fromPairs (reduce)	542	509	510	+6%
head	0	1	3	N/A
map	15	9	11	+50%
range	533	34	62	+176%
reduce	64	14	14	+128%
reject	1263	35	31	+190%
tail	1	3	6	-100%
uniq	5	4	43	+22%
zip	N/A	19	7	N/A

Test: Objects

Name	JS Time (ms)	_ Time [ms]	R Time [ms]	Diff to JS
keys	145	800	109	+28%
merge (triple)	N/A	100	7	N/A
omit	16	35	7	+78%
path (short)	1	3	3	-100%
path (long)	1	2	3	-66%
pick	2	12	2	-0%
toPairs	71	107	52	+30%
values	5	94	28	-139%
zipObj	N/A	121	48	N/A

Test: Strings

Name	JS Time (ms)	_ Time [ms]	R Time [ms]	Diff to JS
toString (array) NOTE _	46	151	2391	-106%
toString (object) NOTE _	163	4	693	+190%
toString (date) NOTE _	10	19	16	-46%
split	592	633	601	-1%
toLower	29	29	32	-0%
toUpper	25	27	30	-7%

Test: Utility

Name	JS Time (ms)	_ Time [ms]	R Time [ms]	Diff to JS
clone	0	0	15	N/A
debounce	N/A	0	N/A	N/A
isEmpty	1	0	0	N/A
isEqual	N/A	25	106	N/A
isFunction	0	0	N/A	N/A
isNil	0	0	0	N/A
type	0	N/A	0	N/A

Test: Totals

Name	JS Time (ms)	_ Time [ms]	R Time [ms]	Diff to JS
Curried / Piping Numbers	1452	3	2941	+199%
Curried / Piping Objects	825	1167	748	+9%
Curried / Piping FP	N/A	25	1094	N/A
Common Methods	528	554	1155	-4%

Conclusions

Both Ramda and Lodash overlap, and should likely not be used in the same project. Depending on what data you're working on and which method you're using, these libraries can be very beneficial or unnecessary.

An approach of Vanilla-JavaScript-First should be taken, and these libraries shouldn't be used as a blanket approach to methods on data. Once you come across something that it is especially difficult to do in vanilla JavaScript, switch to one of these libraries. Which one? Comes down to taste. Both have a quite similar semantic style.

Ramda is generally a better approach for functional programming as it was designed for this and has a community established in this sense.

Lodash is generally better otherwise when needing specific functions (esp. debounce).

Either way, ensure you invest in tree shaking to minimize the bundle sizes of these libraries, because odds are you will only be using a few methods and do not need the entire library.

GitHub Clones Replenish

Jolene Langlinais — Sun, 06 Dec 2020 21:37:12 +0000

This configuration helps make my consistent pulling of repositories from GitHub a bit easier. Especially so if repositories can frequently change names, or the list of all current repositories can change.

I wrote a script to clone all (specific) repositories in an organization.

Context

My setup is currently running macOS Catalina, using iTerm2 with Bash.

You will need homebrew, jq, and gh:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install jq

brew install gh

Operation

For this configuration, ensure you're in the desired directory and this script exists in the directory. This will create a new directory (named the date, i.e. 2020-12-06T21:16:47Z) where you are, and then dump all the clones within that directory:

bash ./<SCRIPT_NAME>.sh INSERT_GITHUB_ORGANIZATION
# bash ./replenishRepos.sh accordproject

Configuration

All

My configuration within this scriptName.sh file in order to clone all repositories within an organization:

#!/bin/bash
CURRENTDATE=$(date -u +"%Y-%m-%dT%H%M%SZ")
repositories=(`gh api /orgs/$1/repos --paginate | jq -r '.[]' |  tr '\n' '  '`)

mkdir "${CURRENTDATE}"
cd "${CURRENTDATE}"

echo "####"
echo "## Cloning repositories"
echo "####"
for repo in "${repositories[@]}"
do
  echo "####"
  echo "# Cloning repo https://github.com/clauseHQ/${repo}.git"
  echo "####"
  git clone "https://github.com/clauseHQ/${repo}.git"
done

Specific

My configuration within this scriptName.sh file in order to clone only repositories within an organization that have specific prefixes, are archived, and are private:

#!/bin/bash
CURRENTDATE=$(date -u +"%Y-%m-%dT%H%M%SZ")
repositories=(`gh api /orgs/$1/repos --paginate | jq -r '.[] | select(.private == <BOOLEAN> and .archived == <BOOLEAN>) | .name | select(test("<PREFIX_1>") or test("<PREFIX_2>"))' |  tr '\n' '  '`)

mkdir "${CURRENTDATE}"
cd "${CURRENTDATE}"

echo "####"
echo "## Cloning repositories into ${CURRENTDATE}"
echo "####"
for repo in "${repositories[@]}"
do
  echo "####"
  echo "# Cloning repo https://github.com/clauseHQ/${repo}.git"
  echo "####"
  git clone "https://github.com/clauseHQ/${repo}.git"
done

In this configuration, I can select archived or private repositories, and/or repositories with a specific prefix in the name.

Shell CLI Readability

Jolene Langlinais — Sun, 06 Dec 2020 20:08:37 +0000

This configuration helps make my command line interface a bit more readable and increases the ease of use. It prevents from needing some consistent chores:

Running pwd to see where you are
Running git status to see which branch you are in
Investigating when you ran that one command a while ago

Zsh

Context

My setup is currently running macOS Ventura, using iTerm2 with Zsh.

My command line appears as:

This is showing the current date and which directory I am in, as well as the git branch (if this is a git repository):

<DATE>@<TIME>[<WORKING_DIRECTORY>][<GIT_BRANCH>]:

Configuration

This customization can be done by editing an existing ~/.zshrc file or creating one. My current ~/.zshrc:

autoload -Uz vcs_info
precmd_vcs_info() { vcs_info }
precmd_functions+=( precmd_vcs_info )
setopt prompt_subst
zstyle ':vcs_info:git:*' formats '%b'

PROMPT='%F{#FE9A0A}%D%f%F{#09CAFF}@%f%T[%F{#0165F5}%~%f[%F{#78D236}${vcs_info_msg_0_}%f]: '

First section is for loading the version control system (git in this case) and displaying the branch.

Prompt Options

Within the prompt:

%F{}...%f
- This formatting indicates the text in the ... area will be of the color within the {}
%F{#FE9A0A}%D%f
- %D indicates a date format of YY-MM-DD
%F{#09CAFF}@%f
- This is only the character @
%T
- Indicates the 24 hour time in format HH:MM
[
- This is only the character [
%F{#0165F5}%~%f
][
- This is only the characters ][
%F{#78D236}${vcs_info_msg_0_}%f
- ${vcs_info_msg_0_} will display the current git branch
]:
- This is only the characters ]:

Bash

Context

My setup is currently running macOS Catalina, using iTerm2 with Bash.

My command line appears as:

This is showing the current date and which directory I am in, as well as the git branch (if this is a git repository):

06.12.2020@13:50[current-directory][git-branch-name]:

Configuration

This customization can be done by editing an existing ~/.bashrc or ~/.bash_profile file, or creating one. This file needs to export PS1, which is the primary prompt. My current ~/.bash_profile:

# get current branch in git repo
function parse_git_branch() {
    BRANCH=`git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/\1/'`
    if [ ! "${BRANCH}" == "" ]
    then
        STAT=`parse_git_dirty`
        echo "[${BRANCH}${STAT}]"
    else
        echo ""
    fi
}

# get current status of git repo
function parse_git_dirty {
    status=`git status 2>&1 | tee`
    dirty=`echo -n "${status}" 2> /dev/null | grep "modified:" &> /dev/null; echo "$?"`
    untracked=`echo -n "${status}" 2> /dev/null | grep "Untracked files" &> /dev/null; echo "$?"`
    ahead=`echo -n "${status}" 2> /dev/null | grep "Your branch is ahead of" &> /dev/null; echo "$?"`
    newfile=`echo -n "${status}" 2> /dev/null | grep "new file:" &> /dev/null; echo "$?"`
    renamed=`echo -n "${status}" 2> /dev/null | grep "renamed:" &> /dev/null; echo "$?"`
    deleted=`echo -n "${status}" 2> /dev/null | grep "deleted:" &> /dev/null; echo "$?"`
    bits=''
    if [ "${renamed}" == "0" ]; then
        bits=">${bits}"
    fi
    if [ "${ahead}" == "0" ]; then
        bits="*${bits}"
    fi
    if [ "${newfile}" == "0" ]; then
        bits="+${bits}"
    fi
    if [ "${untracked}" == "0" ]; then
        bits="?${bits}"
    fi
    if [ "${deleted}" == "0" ]; then
        bits="x${bits}"
    fi
    if [ "${dirty}" == "0" ]; then
        bits="!${bits}"
    fi
    if [ ! "${bits}" == "" ]; then
        echo " ${bits}"
    else
        echo ""
    fi
}

export PS1="\[\e[38;5;214m\]\D{%d.%m.%Y}\[\e[36m\]@\[\e[m\]\A\[\e[m\][\[\e[38;5;63m\]\W\[\e[m\]]\[\e[38;5;82m\]\`parse_git_branch\`\[\e[m\]: "

This parse_git_dirty function will cause the ...[git-branch-name] section of my prompt to include the following optional characters:

*: This branch is ahead of main
+: A new file exists in this branch
?: Untracked files exist in this branch
x: Files have been deleted from this branch
!: Files have been modified in this branch

Prompt Options

\d: Date in “Weekday Month Date” format (e.g., Tue May 26)
\D{format}: Date in format passed in
\j: Number of jobs currently managed by the shell
\l: Basename of the shells terminal device
\n: Newline
\s: Name of the shell
\t: Current time in 24-hour HH:MM:SS format
\T: Current time in 12-hour HH:MM:SS format
\@: Current time in 12-hour am/pm format
\A: Current time in 24-hour HH:MM format
\u: Username of the current user
\w: Current working directory ($HOME is represented by ~)
\W: Basename of the working directory ($HOME is represented by ~)
\!: History number of this command
\#: Command number of this command
\$: Specifies whether the user is root (#) or otherwise ($)
\\: Backslash
\[: Start a sequence of non-displayed characters (useful if you want to add a command or instruction set to the prompt)
\]: Close or end a sequence of non-displayed characters

Note that my PS1 includes the following sections:

# Orange
\[\e[38;5;214m\]
# Date, in format
\D{%d.%m.%Y}
# Teal
\[\e[36m\]
# @ symbol
@
# Plain color
\[\e[m\]
# Time, 24hr format
\A
# Plain color
\[\e[m\]
# Open bracket symbol
[
# Blue
\[\e[38;5;63m\]
# Current directory, not path
\W
# Plain color
\[\e[m\]
# Close bracket symbol
]
# Green
\[\e[38;5;82m\]
# Function to generate git branch
\`parse_git_branch\`
# Plain color
\[\e[m\]
# Colon symbol
:

Year One: Lessons Learned

Jolene Langlinais — Tue, 18 Feb 2020 23:56:01 +0000

Setting

Halfway through university, I was forced to drop out due to lack of funds. I then spent ten years cycling through different careers (or, perhaps more accurately, attempts at careers). Throughout that time, I worked multiple jobs that did not truly interest me, none of which were in tech. Moreover, I also came out as transgender and transitioned during that time. When I finally decided to try to enter the tech industry, it felt like there were countless barriers against me. However, I was able to complete a coding bootcamp program and get hired as a software engineer. This article is my attempt to catalog some of the most important lessons I learned over the last year: my first year in tech.

Work

Accept the Chaos: It’s a Feature, Not a Bug

When I was first hired at my software engineering job, it was quite an adjustment. The pace, the process, and the style of workflow were all brand new to me. Initially, my approach was to create a comprehensive layout for every aspect of a project: I hoped that this would allow me to conquer all possible uncertainties. Soon enough, I learned there’s a reason the “waterfall method” doesn’t work in software. I struggled with feeling that I wasn’t making progress and did not have a grip on what was going on in a project. However, I came to understand that learning and identifying obstacles is progress. In fact, it’s the entire point. This is part of the reason Agile is such a widely used methodology: it enables me to adapt to changes on the go rather than attempt to stick to a rigid, linear plan.

Struggling in this process is the point—and I sure got the point. At some point during my many career attempts, I got it into my head that struggle equals failure, but in reality, that couldn’t be further from the truth. This may be some remnants of working in physical labor for a large part of my life, but my new career involves thinking and strategy and, as such, it has required me to reframe my perception of progress and success. Working in physical labor jobs for a large part of my life, my managers instilled mantras into me like, “If you have time to lean, you have time to clean.” In those types of jobs, it was understood that no physical labor being done means no work being done. In the last year, I had to become a lot more comfortable with taking time to research, talking to myself, asking others questions, going on a walk to think something over, or visually mapping something out to get a better grasp of it.

Teamwork

For the first time in my life, I’m in a career where I feel that my input is actually valued. Now, I feel empowered to express myself. I consistently speak up in discussions and meetings. I often bounce ideas off coworkers. It’s easy to forget to give other people feedback (especially praise) out loud in public, but I have learned how important it is to make a concerted effort to do so whenever possible.

Software development is a team sport. Relying on and supporting each other is paramount. It is the same with code: it is only useful when others can understand it. After much frustration, I have grown to appreciate that code quality is a constant pursuit, but understandable code is the ultimate goal. Code that is “inefficient” but easily comprehensible is infinitely better than super slick code that no one else can figure out.

Curing My Paranoia

I’m incompetent. I’m a fraud. I try to blend in, but soon enough, I’ll be exposed and exiled. Everyone in the office can smell my fear. They won’t fall for my act much longer. My manager and my coworkers frequently check in with me and assure me that they want to help, but I know better—they’re hoping I’ll fail. I must instantly know everything. Making a single mistake is unacceptable. I shouldn’t need to learn as I go. Without a doubt, my days at this job are numbered.

…Unless I’m wrong. Imposter syndrome is a hell of a drug.

For my own sanity, I try to remind myself that no one really knows what they are doing. It’s easy for me to assume everyone else knows exactly what is going on with everything, but the reality is that most people only understand a small section of the technology we work with. Admitting ignorance can actually empower others: I know it makes me feel better.

Learning from Others

As a junior developer, I often face difficulty when trying to keep up with more senior coworkers. When I am pair programming with a more experienced developer, I tend to insist on “driving.” This helps me control the pace and forces my partner to explain what they’re doing as we write our code together. I sometimes feel bad asking a ton of questions to gather more knowledge and context, but that is exactly what a junior should be doing. And patiently explaining is exactly what a senior should be doing. Remembering that helps relieve some of the imposter syndrome symptoms.

Being close to an answer is not failure, but success. This was a hard lesson to learn. I ask to ensure I am on the right path quite regularly. All software is built by direct or indirect teams. Anyone who thinks otherwise is a 10x’r and should be backed away from slowly.

One thing I love about the company I joined is that we emphasize teamwork and unity. Geographically, team members are spread out across two continents, but we invest in hosting several week-long in-person meetups each year. These have been instrumental in building team cohesion and chemistry, as well as giving me opportunities to develop interactive teaching sessions to knowledge share.

Self

Humility

I have always tried to set aside my ego and admit when I don’t know something. In fact, after I was chosen for my job, I learned that my refreshing humility was one of the main reasons I was picked. In the last year, I have found that acknowledging my ignorance makes me feel more comfortable and reduces my imposter syndrome. I think my willingness to be honest about what I do and do not know, combined with my eagerness to learn, is one of the things that makes me a valuable employee. I try to stay humble by keeping in mind that there is always more to learn.

A habit I have developed is to write down mistakes and wins in my notes a few times a week. This helps me to learn from my mistakes and combats imposter syndrome. Having a record of my accomplishments also helps me prepare for my bi-annual reviews.

Focus

While I adapt to let go of my organizational approach to work, I strive to maintain my organization. It’s as confusing as it sounds. I am finding a balance of organizing logistics and tasks in a way which fits with an agile and ever-changing workflow.

I aim to keep up to date on best practices to continually stay abreast with the industry standards. The job is to learn...which in itself is difficult to learn. I sometimes feel guilty about learning on the job, but I just have to remember, that is the job.

I aspire to be well-rounded. Rather than become a specialist in one narrow field, or a generalist with no area of expertise, I aim to develop what can be called a T-shaped skillset. I am not yet sure what the depth of that “T” will be for me, but I am enjoying the journey toward discovering that.

A thing that keeps me on track is focusing on the value I bring to the company. In the last year I have learned new ways to gauge my own worth. The company that I work for happens to be a lovely place that is staffed entirely of friendly and helpful people, but at the end of the day, a company is a company. The value I bring to that company constitutes my worth. This has served as a guiding principle for me when deciding where to focus my time and effort. For example, if I would like to make a feature that I think is interesting, but no one asked for it and no one wants it, then I am not adding value to the company. I would rather spend my energy contributing to a larger purpose.

Balance

It has been hard for me to get in the habit of taking breaks, but nevertheless, I have found it to be immensely helpful. Overworking myself does no one any favors. It is better for both myself and my team to have a short day and then recuperate, rather than to power through the work day while feeling scatterbrained. Knowing this doesn’t always stop me from doing it, but I still try my best to work smarter, not harder.

Burnout is real! Although I strive to maintain a workout routine and schedule plenty of physical activity outside of work, I frequently fail to stick to my goals. Attempting to balance my leisure activities with work has been an ongoing struggle. It is a work in progress that I hope to improve in my second year.

Taking Initiative

At Work

Many of my learning opportunities over the last year came from extra duties that I took on at work. In my company, I became the unofficial advocate for git etiquette in our development workflow. I also became the main driver to consider implementing accessibility features into our products. I never specifically intended for this to become “my thing” and I do worry about being pigeonholed into one particular role rather than growing in different directions. However, it is nice to have my own niche and to develop areas of expertise.

One of the coolest opportunities has been to work on an open source project as a maintainer. Even if it weren’t part of my official job duties, I would still want to be involved in open source projects. I am passionate about making open source projects accessible to newcomers and have put a lot of work into making our project’s structure and documentation more approachable. This interest of mine culminated in our participation in Hacktoberfest, which was quite a huge undertaking. Just now I am applying to Google Summer of Code, and I have high hopes for that process turning out well.

Outside of Work

I have made a specific effort to learn in public through blogging and public speaking. I try to write down what I learn and share it with others to spread the knowledge. It may feel obvious, but because it helped me, surely it can help others. I spent a large chunk of my first year’s free time writing articles and developing talks to present at meetups and conferences.

I have also benefited from getting more personally involved in the tech community. Networking with others in the tech industry has exposed me to a huge range of learning opportunities. I have been a mentor as well as a mentee; both experiences have been invaluable in my education.

Making It My Own

The great thing about this career compared to others in my past is that it is no longer about clocking in/tolerating the work/clocking out. In this job, I am actually engaged and invested in the work. I now have the freedom to go above and beyond the bare minimum expectations set for me by others. I work on projects that actually make sense to me. My company has a mission that actually speaks to me—I could even go so far as to say it inspires me. Coding and software engineering are brand new to me, yet somehow the work itself seems to fit me better than anything else I’ve tried. I feel that I have been given the chance to independently craft my own career, rather than simply just doing whatever work my boss orders me to do. In the old days, work was a chore that made me feel exploited; over the last year, I’ve learned what it feels like to have a job that gives me a sense of success and personal achievement.

Modern Javascript Techniques

Jolene Langlinais — Wed, 28 Aug 2019 16:39:48 +0000

Clean and Scalable Syntax in Pursuit of Purity

As a beautifully complex and adaptive language, JavaScript has many advantages which grow every year. It is no wonder that the language and community is so extremely popular given that it had a large hand in bringing user interface interactivity and responsive web design to the internet. While sometimes complicated, the language proves to be easy to pick up and start, and allows for faster user experiences by being executed client-side.

A large period of time saw JavaScript as problematic and flawed. This was never an issue with the language, but rather the platform it ran on: the browser. This ecosystem was flawed, as there were so many branching factions — most notably Microsoft coming in and mucking everything up. Mozilla was a voice of reason throughout this period, but it was not until Chrome gained enough market share to give incentive to realign people around a standard of how the engine should look and be built. Setting the standard with V8 is how Node.js was subsequently built. As a full programming language with server side execution support, JavaScript now powers modern web applications and scales across the tech stack.

Approach

My experience both as a maintainer of the Accord Project , an open source project for smart legal contracts, and as a Full Stack Engineer has shown me the powerful applications in which JavaScript can be implemented. Moreover, I have become quite keen to learn and adopt better and more efficient practices within the language. I will be sharing this as both a useful reference for others, as well as a historical reference for myself in the future. I am hoping to branch off this to expand on topics covered in here in subsequent, deeper dive articles.

The majority of our work at the Accord Project is in JavaScript , with some domain specific language mixed in. To architect a reliable tech stack which allows stability and efficiency for smart contracts, the Accord Project relies on JavaScript, as well as OCaml and Ergo. JavaScript provides the best set of tools to handle this in a wide array of use cases and environments. We chose JavaScript because of its applicability, diversity of libraries, and ease of use. Syntax within this language is expressive yet simple.

The Accord Project core codebase contains more than 250k lines of code. Along with our template library and UI components, there is near a million.

Outline:

→ Approach
→ Fundamentals
→ Workflow
→ Operations
→ Functions
→ Asynchronous
→ Functional Programming
→ Conclusion
→ Resources

Fundamentals

Comprehensible

Document code. Readability is paramount for programming, as it is humans who will need to interpret the code in order to collaborate. Being verbose enough to be legible at a later date or for another person is better practice than saving a few extra characters by naming variables with a single letter. Moreover, commenting and documentation - such as the JSDocs format - are extremely useful for building accessible code which can be shared with a team or others.

It may seem redundant at first, but commenting code as best as possible will allow for easy refreshing through this built-in documentation months later when you circle back to a project or when pairing with a colleague.

Globals

Avoid variables in the global scope. Multiple reasons exist for avoiding variables in the global scope. Performance is reduced due to function execution causing JavaScript to search through the scope change from in to out until it hits the global object. Furthermore, security flaws exist from this because functions can be invoked through the browser when they’re defined in the global space. This point will come up again in the functional programming section.

Variables

Stop using var. The scoping behavior is inconsistent and confusing, which can result in bugs. ES6 brought in const and let. Aim for using strictly const, and only let if that is not possible. There is more restriction and const is un-reassignable, but not quite immutable. The variable will have an unchanging reference to the same object or primitive value, but the value held by the variable is not immutable. Still, this will be best practice moving forward.

Naming

A bit of digression, but programmers can expend 10x amounts of energy on naming conventions, yet struggle to be inclusive with their language.

Taking the time to be descriptive and appropriate for legibility and comprehensive readability will do wonders in the future of the code.

This is especially important for those looking to educate others; variable names should help explain and give context to what is happening in the code. Someone new to this code should be able to have a loose understanding of what is happening. Use verbs! An example for a Boolean variable could start with is... and examples of functions could be action verbs.

Good reference material can be found here: A Grammar-Based Naming Convention

Workflow

A major key to maintainability is keeping logic in the right place and not cluttered or disorganized. The way a project or codebase is structured can make a large impact on how easy it is to understand and follow.

Importing Order

Starting at a granular level, the order in which different modules are imported can reduce confusion by having a predictable pattern. The specific structure you use is less important than there being some sort of structure:

/* Packages */
import React, { useState } from 'react';
import PropTypes from 'prop-types';
import * as R from 'ramda';

/* Styled Components */
import * as SC from './styles';

/* Components */
import Navigation from './Navigation';

/* Actions */
import * as ACT from './actions';

/* Utilities */
import { navigateToClause } from '../utilities';

Modularization

A goal to keep in mind is to keep packages, modules, functions, and scopes small. Reusability becomes much easier, as well as chaining, when this is in practice. Similar functions or those with many steps could be grouped into one module or class. Try to keep functions as simple as possible, and perform complex processes in steps.

Once a file has grown above 300-400 lines of code, there is a strong case for being too cluttered and unmaintainable. At this point, a lot of benefit can be gained from creating new modules and folders to break up processes. Think of a project as a tree with many branches, rather than a mountain of heaped-up code.

ESLint is a great tool to help here. Aim for keeping files less than four or five indentations deep. This keeps code specialized and encourages cleanup of dead code. Several functions that do one small process will be more useful than one function which does several things. The large function can only be used in that one way, whereas smaller functions may be able to be used in multiple processes around a project. Exposing these smaller, helper functions creates a robust API base in a project.

Great code can be improved upon without rewriting everything.

Isolate code

A function should have one purpose and not do multiple actions. That purpose should be something other than a side effect, but we will circle back to this in functional programming section

A contrived example of this is encapsulating conditionals:

// NO:
if (props.contract.errors === [] && isEmpty(parseErrors)) {
  // ... code
}

// YES:
const errorsExist = (props, parseErrors) => props.contract.errors === [] && isEmpty(parseErrors);

if (errorsExist(contractProps, parseErrors)) {
  // ... code
}

Guard Clauses

A great way to construct functions which have edge cases which result in an error or empty result is to have checks for these invalid results early. If this condition is not met or there is an invalid use case, then the bulk of the computation is prevented because we already know the result. This is referred to as the Bouncer Pattern or Guard Clauses:

const parseContract = (contract) => {
  // Does a contract exist
  if (!contract) return "Error, no contract!";

  // Are there already parsed errors
  if (contract.currentErrors.length > 0) return contract.currentErrors;

  // Parse the contract
  return contract.clauses.map((clause) => doSomething(clause));
}

Not only will this optimize code, but will encourage thinking of functions and processes in a way which takes handling edge cases into consideration.

Prettier + Linting

A theme to my article here is that code should be easy to read and understand. With that comes consistent styling and structuring. A linter - any linter - will be greatly useful. ESLint is a linter, and will identify issues with code correctness such as warning from using var. Prettier is a formatter, which will identify issues with uniformity and consistency and automatically align brackets, for example. Using both in conjunction is encouraged.

StandardJS and ESLint’s predefined config are good sources for linting rules if you need a good starting point.

Operations

Destructuring

Destructuring can help save a lot of typing and lines of code by keeping variables short and pulled from an object early on. Introduced with ECMAScript 6, this allows access to specific fields from any object or module and immediately assign it to a variable.

Objects:

// NO
const generateText = contract => {
 const clauses = contract.body.clauses;
 const text = contract.body.text;
 const errors = contract.errors;

 Cicero.parseContract( clauses, text )
};

// YES
const generateText = contract => {
 const { body: { clauses, text }, errors }, = contract;

 Cicero.parseContract( clauses, text )
};

Arrays (skipping elements consist of , ,):

// NO
const lettersArray = [ "A", "B", "C", "D", "E", "F" ];
const firstLetter = lettersArray[0]; // "A"
const thirdLetter = lettersArray[2]; // "C"

// YES
const [ firstLetter, , thirdLetter, ...remaining ] = lettersArray; // remaining = [ "D", "E", "F" ]

Functions (similar to objects):

// NO
const generateText = (contract) => {
  if(contract.errors) return "Errors exist!"
  if(!contract.clauses) return "No clauses exist!"
}

// YES
const generateText = ({ errors = null, clauses = null }) => {
  if(errors) return "Errors exist!"
  if(!clauses) return "No clauses exist!"
}

Default Values

When destructuring, there is an ability to assign default values to parameters. This can also indicate to the user what values can be passed in or are required.

const generateText = ({
    name = "Stock Contract",
    language = "English",
    text = "No text exists yet!",
    errors = [],
    clauses = [],
}) => { Cicero.parseContract( clauses, text ) }

If no error should be thrown when a value is not passed, a default value could be useful.

Ternary

This operator works similar to logical operators and if...else statements, and has three sections:

Boolean conditional
Return value in case of truthy
Return value in case of falsy

// condition ? truthyResult : falsyResult
const errorArrayLength = errors => ( errorsExist(errors) ? errors.length : 'No' );

Try to steer clear of negative conditionals - check if something does exist, rather than if it does not exist.

Spread

Another form of object destructuring, the spread operator allows for value extraction from data without having to iterate over the data explicitly. This is common in Redux and functional programming, as it is a short way to add to an object without mutating it - copy an old object by spreading it and adding a new value to it.

const firstHalf = [ "A", "B", "C" ];
const secondHalf = [ "D", "E", "F" ]; 

const lettersArray = [ ...firstHalf, ...secondHalf ];
// lettersArray = [ "A", "B", "C", "D", "E", "F" ];

const contract = {
    text = "No text exists yet!",
    errors = []
};

const contractWithClauses = {
    ...contract,
    clauses = []
};

Template Literals

This feature allows for embedding dynamic content into strings and writing strings which bridge multiple lines. These are designated with backquotes and template literal snippets (${}).

// NO
var contractTitle = ("Contract Name: " + contract.name + ", Errors: " + contract.errors.length + ".")

// YES
const contractTitle = `Contract Name: ${contract.name}, Errors: ${contract.errors.length}.`

// OTHER USES
const conditionalTitle = `${contractExist() ? ('Contract Name: ' + contract.name) : 'No contract exists.'}`
const multipleLines = `Hello,

Good to meet you`

Functions

Limit Scope

Functions should do one thing. They become difficult to test and reason through once they begin performing multiple actions. Aim to have no more than one level of abstraction in functions - split functions up if necessary.

// NO
const parseContract = contract => {
    contract.forEach(contract => {
        const contractText = generateText(contract);
        if (contractText.noErrors()) {
            execute(contract);
        };
    });
};

// YES
const isContractValid = contract => {
    const contractText = generateText(contract);
    return contractText.noErrors();
};

const parseContract = contracts => contracts.filter(isContractValid).forEach(execute);

Arrow

This newer syntax for functions provides a concise and clear flow to the notation. These also have more practical scoping behavior by inheriting this from the scope in which the function was defined in.

Previously, a function would be written as:

function someFunction(input) {
 // ... code
}

Now we define the same thing as:

const someFunction = input => {
 // ... code
}

If the function is only returning something simple, we can write this in one line with an implicit return statement:

const add = (a, b) => a + b;
const createObject = (a, b) => ({ a, b });

Parameters

Aim for limiting the amount of parameters passed into a function to improve testability. Ideally, this would be below three. Usually, if there are three or more arguments, the function may be trying to do many things itself and should be split up and consolidated.

Chaining

A source of current frustration comes from the inability to easily access a nested value within an object. Something like this may be used currently:

if(contract && contract.firstProp && contract.firstProp.secondProp && contract.firstProp.secondProp.thirdProp && contract.firstProp.secondProp.thirdProp.fourthProp.data) execute(contract.firstProp.secondProp.thirdProp.fourthProp.data)

Hideous.

The reason for doing this is if you go straight for the last line, you could run into this kind of error:

TypeError: Cannot read property ‘fourthProp’ of undefined

TC39 (the technical committee that determines what features become a part of the JavaScript standard) has moved the Optional Chaining proposal the later stages of acceptance.

I am really looking forward to this, because it would make the above code appear as such:

const data = contract?.firstProp?.secondProp?.thirdProp?.fourthProp?.data
if(data) execute(data)

If any property does not exist, the digging exits and returns undefined.

Another current solution to this is Ramda, which uses a function called path to safely execute code at run-time and not run into undefined errors in the console.

Asynchronous

I have previously written about Asynchronous with Redux Sagas, but will be focusing more on async/await and promises for this.

Asynchronous simply means things happen independently of the main program flow; computers are designed this way. A processor will not pause to wait for a side effect to happen to resume operations. JavaScript is synchronous by default and single threaded; code cannot run in parallel. However, JavaScript was designed to respond to user actions, which are asynchronous in nature. The browser, in which JavaScript lives, provides a set of APIs which handle this functionality. Moreover, Node.js introduces a non-blocking I/O environment to extend this concept to files, network calls, etc.

When this side function is handed over to a separate thread, such as an API call., it returns as a callback, which is a function passed into another function as an argument. This is then invoked inside the outer function to complete an action.

Async + Await

Previously, JavaScript relied on promises and callbacks for asynchronous code. This could easily result in Callback Hell. This syntactic sugar built on top of promises provides a much smoother way of handling asynchronous code, but cannot be used with plain callbacks or node callbacks. Now asynchronous code can be written more like synchronous code. Similar to promises, these are non-blocking.

Functions which use this require the async keyword before it, and await can only be used in functions which have this keyword. This async function implicitly returns a promise which will resolve to the value returned inside the function.

// Promises
const outsideRequest = () =>
  retrieveData()
    .then(data => {
      execute(data)
      return “Executed”
    })

// Async/Await
const outsideRequest = async () => {
  execute(await retrieveData())
  return “Executed”
}

Benefits:
+ Clarity - Less code and more readable.
+ Error handling - try/catch can handle both synchronous and asynchronous code
+ Conditionals - More straight forward handling of dynamic results
+ Debugging - Error stack traces are much easier to track
+ Await anything

Functional Programming

There are two major paradigms when it comes to programming, imperative and declarative. An imperative way to approach writing a function would be to explain each minute step of the process, whereas declarative takes the approach of expressing computational logic without describing specific flow.

Imperative: How to do something
Example: Instruct someone to bake a cake, step-by-step
Declarative: What to do
Example: Telling someone to bake a cake by describing a cake

Functional programming is declarative. An intimidating and powerful programming paradigm, this treats computation as the evaluation of mathematical functions and avoids changing state and mutable data. Functions are first class entities in JavaScript, which means they are treated as values and can be used as data. Functions can be referred to from constants and variables, be passed as a parameter to other functions, and be returned as a result of a function.

In functional code, output values are contingent upon only the arguments passed in, and will always result in the same value for the same input. Object-Oriented Programs, in contrast, can often depend on state and can produce different results at different times with the same arguments.

Pure Functions

A pure function is one which follows some guidelines of functional programming, namely it returns the same result given the same arguments (idempotent) and does not cause observable side effects. This makes it referentially transparent, and a benefit of this is that this code is much easier to test. With this concept, we are able to memoize these functions.

Side Effects

Mutability is avoided in functional programming, and an example of this would be modifying the global object or a value in the global scope. Instead of mutating, functional programming aims to create new copies of data with additions or subtractions rather than mutating the original data.

The main point is to avoid pitfalls like sharing state between objects or using mutable data that can be written to by anything. An action which is not pure, such as writing to a file, should be limited to one service which does it - minimize impure functionality.

In JavaScript, primitive data types are passed by value, whereas objects are passed by reference. So if a function makes a change to an array, any other function which references that array will be affected. This is a huge danger that functional programming seeks to avoid; if two separate and unrelated functions take the same input, but one of the functions mutates that input, the other function is now flawed. It can become taxing to performance to be cloning large objects all the time, but there are great libraries which are quite performant, such as Ramda.

Ramda

An excellent library which provides extra utility to functional programming in JavaScript, making it easier to create code pipelines. All functions are automatically curried, which makes this library extremely useful. Their wiki has a helpful section to help you find "What Function Should I Use"

Currying gives us the ability to use higher order functions (ones which take functions as input and return functions) and closures to great effect. Instead of a function with multiple arguments, a curried function would be one which takes a single argument and returns a function that takes a single argument. These are strung together to create a pipeline.

Piping

While Ramda is great for composing functions together in a pipe, JavaScript is a constantly evolving language and will soon have this natively. TC39 currently has a proposal for a Pipeline Operator Pipeline Operator. In the meantime, check out Ramda and find some really powerful tools!

Conclusion

The trope is old, criticism of JavaScript from many circles has lost merit. I suppose it is taking some 10x longer to get over their misgivings. This language has a high level of efficacy and is suitable for many environments and applications. There are a lot of exciting use cases all across technology, with the ability to touch the full stack.

Gatekeeping and toxicity in this field aside, the ability to access so many different sectors provides for a more collaborative and better experienced population in the community. This language has so much power. Cross platform desktop apps can be built with JavaScript in Electron, mobile apps with React Native, and server-side solutions with Node.js.

While there is constant evolution to this language, there is not quite a new framework every week. Progression is good, and the community behind this language is quite progressive and innovative.

Feel free to contact me with any questions or feedback.

Resources

Community

Education

Books

Blogs

Eric Elliott

Podcasts

Misc

JavaScript: Understanding the Weird Parts
30 days of JavaScript challenges with corresponding videos by Wes Bos: JS 30
Fun Fun Function
Switch Case vs Object Literal:
- Switch case, if else or a loopup map by May Shavin
- Rewriting Javascript: Replacing the Switch Statement by Chris Burgin
Static Typing
Functional Frontend
- Elm
- Elm Tutorial

Asynchronous with Redux Sagas

Jolene Langlinais — Fri, 16 Aug 2019 17:31:07 +0000

Sophisticated Side Effect Flow Management and Testing

Building an app with React can get a bit confusing when data is being shared among components and different states lead to too much complexity and difficulty. Redux is a lightweight state management tool which can be used with any JavaScript framework or library to maintain a consistent and predictable state container. By keeping the state of an application in a single global store rather than at the component level, each individual component can access any state it needs at any time regardless of the shape of the component tree, as long as it is connected to the store via Redux.

The predictable nature of Redux comes from the immutable state which never changes, as well as pure function reducers. Because reducers are functional, a commonly used middleware to handle side effect logic and asynchronous calls is redux-thunk. A Thunk allows action creators to return a function instead of an action.

While I will be assuming you have a basic understanding of React and Redux, this will be a guide into a different kind of Redux middleware for handling side effects: Redux Sagas

→ Skip to the walkthrough with sample code here

Why Redux Saga?

So long as the same action is passed to the reducer, we can be sure the store will be updated in the same way every time. Sagas, similar to normal reducers, are functions which listen for dispatched actions, perform side effects, and return their own actions back to the normal reducer. Because Sagas intercept actions with side effects and handle them, Redux reducers remain pure.

Redux Saga utilizes ES6 generator functions for this. Generators allow for synchronously written asynchronous code. A generator will automatically pause — or yield — at each asynchronous call until it completes before continuing. This paradigm allows for much simpler and more readable code by centralizing asynchronous logic for more manageable and sophisticated async flows.

Saga generator functions remind me a bit of async/await, with some minor changes such as yield and put(). Some of the differences provide powerful benefits, such as takeLatest() ensuring that only the latest fetch call runs to completion despite having dispatched multiple simultaneous fetch actions. However, asynchronous calls which would normally be directly inside an action creator in a thunk will have a clear separation in Redux Sagas.

Beyond code organization and attributes, testing becomes much easier. A Saga merely yields a description of what to call, thus saving the need for mocking data for every test.

Redux Saga becomes most useful when API or other asynchronous calls are being made with complex flows in which calls depend on the next.

Pros:

+ More readable code
+ Good for handling complex scenarios
+ Test cases become simple without necessity to mock the async behavior

Cons:

- Brings in more complexity to the code
- Additional dependency
- A lot of concepts to learn

Conclusion:

→ Suited for complex async parts of the application that requires complex unit test cases

A quick note on Thunks:

Given that Redux Saga seeks to orchestrate complex asynchronous operations with Redux, it is an alternative to Thunks. However, Sagas provide more functionality. Thunks work well for simple use cases, but may not be the best choice for more complicated scenarios.

Thunks add a layer of indirection for more flexibility, and pass dispatch functions to the function the action creator returns. This allows the component to be agnostic towards asking for a synchronous or asynchronous action.

Pros:

+ Simple code to maintain

Cons:

- Struggles at handling complex scenarios
- Async behavior needs mocking for test cases

Conclusion:

→ Suited for small, straight forward async parts of the application

Generators

Denoted with an *, generators make use of the yield keyword to pause the function. While async/await can be transpiled into generators, the reverse cannot be done. Moreover, Sagas’ takeLatest() behavior and generator function cancellation are more attributes provided by Redux Saga.

When a generator function is invoked, it returns an iterator object. Each subsequent next() method call will execute the generator until the next yield statement and pause.

function* testGenerator() {
  const first = yield 'first yield value';
  const second = yield 'second yield value';
  return 'third returned value';
}

const test = testGenerator();

console.log(test.next()); // { value: 'first yield value', done: false }
console.log(test.next()); // { value: 'second yield value', done: false }
console.log(test.next()); // { value: 'third returned value', done: true }
console.log(test.next()); // { value: undefined, done: true }

Walkthrough:

To guide through this concept, I will be referencing a codebase for the web app used by an open source software project I contribute to here:

Accord Project (AP)
AP Github
Template Studio repository

The project currently being built is a redesign of the Template Studio. Details are mostly unimportant, suffice it to say that the part I will be going through makes an API call to gather an array of templates, and displays them in a component. This redesign will consist of many interlocking React components, all housed in one app and controlled by the Redux store. Because this began complex and will only continue to be more-so, we chose to pursue Redux Saga to handle the complexity.

Unfortunately, as you may have experienced as well, there seems to be little out there as reference material. This is especially so when it comes to anything complicated.

This will be a guide to following the logic behind Redux Saga in Template Studio for Accord Project. Hopefully this will prove to be a useful resource for you.

Setup
Common Redux Saga methods (called Effects):

fork → Performs a non-blocking operation on the function passed.

take → Pauses until action received.

race → Runs effects simultaneously, then cancels them all once one finishes.

call → Runs function. If it returns a promise, pauses the Saga until resolved.

put → Dispatches an action.

select → Runs a selector function to get data from the state.

takeLatest → Executes the operation, returns only the results of the last call.

takeEvery → Will return results for all the calls triggered.

The overall structure of the application’s flow of data will look akin to this:

To begin, we set up the main render of the app, and applying a store to the Provider given by react-redux :

import React from 'react';
import { render } from 'react-dom';
import { Provider } from 'react-redux';

import MainApp from './containers/App';
import store from './store';

render(
  <Provider store={store}>
    <MainApp />
  </Provider>,
  document.querySelector('#root')
);

Store

Pulling in the createSagaMiddleware method from Redux Saga, we create sagaMiddleware and run it on our rootSaga, which we will see below. Moreover, we combine all of our reducers and include this in the store upon creation.

Similar to the reducers, Sagas will be registered with a rootSaga. Having the middleware use the rootSaga allows actions being dispatched to be successful.

import { combineReducers, createStore, applyMiddleware } from 'redux';
import createSagaMiddleware from 'redux-saga';
import logger from 'redux-logger';

import templatesReducer from './reducers/templatesReducer';
...
import contractReducer from './reducers/contractReducer';
import rootSaga from './sagas/rootSaga';

const sagaMiddleware = createSagaMiddleware();
const middlewares = [sagaMiddleware];

if (process.env.NODE_ENV === 'development') {
  middlewares.push(logger);
}

const rootReducer = combineReducers({
  templatesState: templatesReducer,
  ...
  contractState: contractReducer,
});

const store = createStore(
  rootReducer,
  applyMiddleware(...middlewares),
);
sagaMiddleware.run(rootSaga);

export default store;

Sagas

Sagas work in the background and sagaMiddleware controls them. Being generator functions, Sagas have control over every single step of the function. We yield objects to sagaMiddleware which tell it what to do with given arguments, which it will execute and resume upon completion, thus appearing to operate synchronously.

Sagas are broken down to the root, watchers, and workers. All other Sagas you write are consolidated into root.

→ Root

All Sagas will be registered with a root Saga. Combined in an all() function, they are allowed to all start at the same time each time.

import { all } from 'redux-saga/effects';
import { templatesSaga } from './templatesSaga';
import { modelSaga } from './modelSaga';
import { logicSaga } from './logicSaga';
import { sampleSaga } from './sampleSaga';

/**
 * saga to yield all others
 */
export default function* rootSaga() {
  yield all([...templatesSaga, ...modelSaga, ...logicSaga, ...sampleSaga]);
}

→ Watcher

Allowing the Saga to know when to start, this generator function watches for actions (similar to reducers) and calls worker Sagas to do an API call. This function is on Line 62 below:

import { TemplateLibrary, Template } from '@accordproject/cicero-core';
import { version as ciceroVersion } from '@accordproject/cicero-core/package.json';
import { takeLatest, put, select, takeEvery } from 'redux-saga/effects';

import * as actions from '../actions/templatesActions';
import * as selectors from '../selectors/templatesSelectors';

/**
 * worker saga
 * saga to populate store with templates
 */
export function* pushTemplatesToStore() {
  try {
    const templateLibrary = new TemplateLibrary();
    const templateIndex = yield templateLibrary.getTemplateIndex({
      latestVersion: false,
      ciceroVersion,
    });
    const templateIndexArray = Object.values(templateIndex);
    yield put(actions.getTemplatesSuccess(templateIndexArray));
  } catch (err) {
    yield put(actions.getTemplatesError(err));
  }
}

/**
 * worker saga
 * saga which puts a mock template onto the array
 * of templates in the store
 */
export function* addNewTemplateToStore() {
  const newTemplate = {
    uri: `${Date.now()}`,
    name: 'Temporary New Template',
    version: '1.0.0',
    description:
      'This is mock data to showcase an action to add a new template.',
  };
  yield put(actions.addNewTemplateSuccess(newTemplate));
}

/**
 * worker saga
 * saga which checks if template is in the store
 * and loads the template if it is not
 */
export function* addTemplateObjectToStore(action) {
  const templateObjects = yield select(selectors.templateObjects);

  if (!templateObjects || !templateObjects[action.uri]) {
    try {
      const templateObj = yield Template.fromUrl(action.uri);
      yield put(actions.loadTemplateObjectSuccess(action.uri, templateObj));
    } catch (err) {
      yield put(actions.loadTemplateObjectError(err));
    }
  }
}

/**
 * watcher saga
 */
export const templatesSaga = [
  takeLatest('GET_AP_TEMPLATES', pushTemplatesToStore),
  takeLatest('ADD_NEW_TEMPLATE', addNewTemplateToStore),
  takeEvery('LOAD_TEMPLATE_OBJECT', addTemplateObjectToStore),
];

Similar to takeLatest(), takeEvery() allows multiple instances of Sagas to run simultaneously. These are both built on take(), which is synchronous.

→ Worker

This Saga (Lines 14, 31, and 46 above) will perform a side effect. Once data loads, the put() method is used to dispatch another action. This does not directly dispatch, but rather creates an effect description that tells Redux Saga to dispatch it. Because put() expects an action for an argument, it serves as an action creator. We modularized these actions out, though, as you will see below.

Reducer

Similar to actions, reducers are the same for Redux Saga. This is simply a function that takes state and action as arguments, and returns the next state of the app. While an action only describes what happened, a reducer describes how the application’s state changes.

const initialState = {
  templatesAP: [],
  templateObjs: {},
  error: null,
};

const GET_AP_TEMPLATES_SUCEEDED = 'GET_AP_TEMPLATES_SUCEEDED';
const AP_TEMPLATES_ERROR = 'AP_TEMPLATES_ERROR';
const ADD_NEW_TEMPLATE_SUCCEEDED = 'ADD_NEW_TEMPLATE_SUCCEEDED';
const LOAD_TEMPLATE_OBJECT_SUCCEEDED = 'LOAD_TEMPLATE_OBJECT_SUCCEEDED';
const LOAD_TEMPLATE_OBJECT_ERROR = 'LOAD_TEMPLATE_OBJECT_ERROR';

const reducer = (state = initialState, action) => {
  switch (action.type) {
    case GET_AP_TEMPLATES_SUCEEDED:
      return { ...state, templatesAP: action.templates };
    case ADD_NEW_TEMPLATE_SUCCEEDED:
      return { ...state, templatesAP: [...state.templatesAP, action.template] };
    case AP_TEMPLATES_ERROR:
      return { ...state, error: action.error };
    case LOAD_TEMPLATE_OBJECT_SUCCEEDED:
      return {
        ...state,
        templateObjs: {
          ...state.templateObjs,
          [action.uri]: action.templateObj,
        },
      };
    case LOAD_TEMPLATE_OBJECT_ERROR:
      return { ...state, error: action.error };
    default:
      return state;
  }
};

export default reducer;

Component

Moving into the component, we have a straightforward approach to setting up state and dispatching to result in cleaner code.

import React from 'react';
import PropTypes from 'prop-types';
import styled from 'styled-components';
import { connect } from 'react-redux';
import { TemplateLibrary } from '@accordproject/cicero-ui';

import {
  getTemplatesAction,
  addNewTemplateAction,
} from '../../actions/templatesActions';

const TLWrapper = styled.div`
  ...;
`;
const mockAddToCont = input => {
  console.log('addToCont: ', input);
};
const mockImport = () => {
  console.log('import');
};
const mockUpload = () => {
  console.log('upload');
};

export class LibraryComponent extends React.PureComponent {
  componentDidMount() {
    this.props.fetchAPTemplates();
  }

  render() {
    return (
      <TLWrapper>
        <TemplateLibrary
          templates={this.props.templates}
          upload={mockUpload}
          import={mockImport}
          addTemp={this.props.addNewTemplate}
          addToCont={mockAddToCont}
        />
      </TLWrapper>
    );
  }
}

LibraryComponent.propTypes = {
  templates: PropTypes.array.isRequired,
  addNewTemplate: PropTypes.func.isRequired,
  fetchAPTemplates: PropTypes.func.isRequired,
};

const mapStateToProps = state => ({
  templates: state.templatesState.templatesAP,
});

const mapDispatchToProps = dispatch => ({
  fetchAPTemplates: () => dispatch(getTemplatesAction()),
  addNewTemplate: () => dispatch(addNewTemplateAction()),
});

export default connect(
  mapStateToProps,
  mapDispatchToProps
)(LibraryComponent);

Action Creator

Dispatched to the store for handling, actions are objects containing a description of an event. Because actions are made by action creator functions, the one dispatching the action does not need to know the exact structure.

With Sagas, actions are slightly different. Three actions happen for each API call. Beginning the action, successful response, and error response. While this pattern does not change, the location of each call may.

Beginning an action starts within the component, which may add necessary info for making the call. Worker Sagas will be dispatching success and error actions.

export const getTemplatesAction = () => ({
  type: 'GET_AP_TEMPLATES',
});

export const getTemplatesSuccess = templateIndexArray => ({
  type: 'GET_AP_TEMPLATES_SUCEEDED',
  templates: templateIndexArray,
});

export const getTemplatesError = error => ({
  type: 'AP_TEMPLATES_ERROR',
  error,
});

export const addNewTemplateAction = () => ({
  type: 'ADD_NEW_TEMPLATE',
});

export const addNewTemplateSuccess = template => ({
  type: 'ADD_NEW_TEMPLATE_SUCCEEDED',
  template,
});

export const loadTemplateObjectAction = uri => ({
  type: 'LOAD_TEMPLATE_OBJECT',
  uri,
});

export const loadTemplateObjectSuccess = (uri, templateObj) => ({
  type: 'LOAD_TEMPLATE_OBJECT_SUCCEEDED',
  uri,
  templateObj,
});

export const loadTemplateObjectError = error => ({
  type: 'LOAD_TEMPLATE_OBJECT_ERROR',
  error,
});

Recap

(TemplateLibrary.js) When the LibraryComponent mounts, an action (getTemplatesAction) is dispatched
(templatesActions.js) As we can see, getTemplatesAction dispatches an object with a type: ‘GET_AP_TEMPLATES’.
(templatesSaga.js) The watcher will pick up on the action of type ‘GET_AP_TEMPLATES’ and call pushTemplatesToStore.
(templatesSaga.js) When pushTemplatesToStore is called, a few things happen. We yield an API call made by the TemplateLibrary imported from @accordproject/cicero-core and put it in an array. From there, getTemplatesSuccess is called with the array of templates as an argument.
(templatesReducer.js) This action (GET_AP_TEMPLATES_SUCEEDED) ends up in the reducer, updating the state with the templates array which was attached to the action.
(TemplateLibrary.js) Because this component is subscribed to the store and has props *prop*agated to it, the templates array is now applied to this component through props.

Tests

Approaching testing for Redux Saga may be intimidating. A general rule for efficiency in Redux Sagas is to ensure Sagas are doing as little as possible and to move any complex logic out into a separate regular function. A couple approaches I would recommend pursuing:

Unit Tests

This approach steps through yield effects individually with the next() method. A test may inspect the yielded effect and compare it to an expected effect with next().value. While this is straightforward, it leads to brittle tests. This is due to the tests being coupled so tightly with the implementation and order of effects. Refactoring code will likely break tests.

A helper function called recordSaga is used to start a given saga outside the middleware with an action. The options object (dispatch and getState)is used to define behavior of side effects. dispatch fulfills put effects, and dispatched accumulates all the actions in a list and returns it after the Saga finishes.

import { runSaga } from 'redux-saga';

/**
 * saga to test independently
 */
export async function recordSaga(saga, initialAction, state) {
  const dispatched = [];
  await runSaga(
    {
      dispatch: action => dispatched.push(action),
      getState: () => state,
    },
    saga,
    initialAction
  ).toPromise();

  return dispatched;
}

Utilizing recordSaga allows us to view the type of the dispatched action in a given test case.

import { TemplateLibrary } from '@accordproject/cicero-core';
import { addNewTemplateToStore, pushTemplatesToStore } from '../templatesSaga';
import { recordSaga } from '../../utilities/test/sagaTest';

const mockedTemplateIndex = [
  {
    ciceroVersion: '^0.12.0',
    description:
      'This clause allows the receiver of goods to inspect them for a given time period after delivery.',
    name: 'acceptance-of-delivery',
    type: 1,
    uri:
      'ap://acceptance-of-delivery@0.11.0#311de48109cce10e6b2e33ef183ccce121886d0b76754d649d5054d1084f93cd',
    url:
      'https://templates.accordproject.org/archives/acceptance-of-delivery@0.11.0.cta',
    version: '0.11.0',
  },
];

jest.mock('@accordproject/cicero-core', () => ({
  TemplateLibrary: jest.fn(),
}));

beforeEach(() => {
  jest.resetModules();
});

describe('pushTemplatesToStore', () => {
  it('should dispatch the action getTemplatesSuccess', async () => {
    TemplateLibrary.mockImplementation(() => ({
      getTemplateIndex: () => Promise.resolve(mockedTemplateIndex),
    }));
    const dispatched = await recordSaga(pushTemplatesToStore);
    expect(dispatched[0].type).toEqual('GET_AP_TEMPLATES_SUCEEDED');
  });

  it('should dispatch an error if templates fetch fails', async () => {
    TemplateLibrary.mockImplementation(() => ({
      getTemplateIndex: () =>
        Promise.reject(new Error('Unable to recieve templates')),
    }));
    const dispatched = await recordSaga(pushTemplatesToStore);
    expect(dispatched[0].type).toContain('AP_TEMPLATES_ERROR');
  });
});

describe('addNewTemplateToStore', () => {
  it('should dispatch the action addNewTemplateSuccess', async () => {
    const dispatched = await recordSaga(addNewTemplateToStore);
    expect(dispatched[0].type).toEqual('ADD_NEW_TEMPLATE_SUCCEEDED');
  });
});

Integration Tests

This approach tests the effects you’re interested in. In this, you will execute the Saga until the end, mocking effects along the way. Because this is not run in isolation, results are more secure. Now refactoring should not break the tests nearly as easily. To make this process easier, we utilize the module by Jeremy Fairbank - redux-saga-test-plan , which helps to make assertions in the effects generated by Sagas.

This module contains expectSaga which returns an API for asserting that a Saga yields certain effects. It takes the generator function as an argument, along with additional arguments to pass to the generator. While expectSaga runs on runSaga, which we used in sagaTest, it provides a bit easier usage. This also means that expectSaga is asynchronous.

After calling expectSaga with assertions, start the Saga with run(). This returns a Promise which can then be used with a testing framework. We use Jest. If all assertions pass, the Promise will resolve.

import { select } from 'redux-saga/effects';
import { expectSaga } from 'redux-saga-test-plan';
import { ModelManager } from 'composer-concerto';
import { updateModelManagerSuccess } from '../../actions/modelActions';
import { updateModelFileOnStore, validateModelFiles } from '../modelSaga';

describe('validateModelFiles', () => {
  it('should complete successful update to model manager', async () => {
    const modelFiles = {
      'test.cto': `
                /**
                 * This is a comment
                 */

                namespace test

                asset Vehicle identified by vin {
                  o String vin default="unknown"
                }

                // this is another comment
                participant Person identified by ssn {
                  o String name
                  o String ssn
                  o DateTime dob
                  --> Vehicle vehicle
                }`,
    };
    const state = {
      modelState: {
        modelFiles,
      },
    };
    const modelManager = new ModelManager();
    Object.keys(modelFiles).forEach(fileName => {
      modelManager.addModelFile(modelFiles[fileName], fileName, true);
    });
    modelManager.updateExternalModels();
    modelManager.validateModelFiles();

    return expectSaga(validateModelFiles)
      .withState(state)
      .put(updateModelManagerSuccess(modelManager))
      .run();
  });
});

Conclusion

Redux Saga is amazing. They provide a very clean way of performing asynchronous calls in Redux, and encourages clear, modularized code. While it is possible to accomplish the same feat without it, this will prove quite difficult and I feel it is worth the time to learn.

Feel free to contact me with any questions or feedback.

Git Workflow Etiquette

Jolene Langlinais — Thu, 08 Aug 2019 22:26:05 +0000

Repository Organization for Clean Codebases

Version control with git provides for powerful collaboration, whether it be a tight-knit tech team or a distributed network in an open source format. Still, proper care must be taken. Git is used widely within the software development field and can manage a constantly evolving codebase. Most of its usefulness comes from the ability to branch off new work from an existing project in order to work on it in isolation until ready to integrate back into the project.

Good quality software consists of, among other things, code which is robust, resilient, secure, and performant. These attributes are achievable by maintaining a foundation of good quality code and a solid history of documentation. Anyone should be able to join the process and easily figure out and track the status of the project. This is where git and GitHub come in.

Skip to the following:

→ Branch vs. Fork
→ Rebase vs. Merge
→ CLI
→ Commit (Messages)
→ Pull Requests (and Reviews)
→ GitHub Issues
→ Open Source

Approach

My experience as a contributor to the Accord Project, an open source project for smart legal contracts, has led me to adopt and implement a standard of git workflow and etiquette which I find thorough and effective.

I will be sharing this as both a useful reference for others, as well as a historical reference for myself in the future. As is readily apparent by now, I am utilizing both git and GitHub. For perspective, you can reference GitHub’s official workflow proposal (GitHub flow).

The majority of my work at the Accord Project is in JavaScript, with some domain specific language mixed in, but the principles displayed here should apply to any language.

Branch + Fork:

Branching

Pros

+ All project work is centralized
+ Ease of collaboration
+ Single remote to handle

Cons

— Deprecated branches may clutter easily

Forking

Pros

+ Increased separation between user branches
+ Primary repository cleanliness

Cons

— Difficulty to track branches
— Collaboration requires extra steps
— Accessibility is lower for less experienced git users

While there are benefits to both of these approaches, my general rule consists of forking in an open source project and branching in a smaller or insular team. There is more incentive for keeping the main repository clean and tidy in open source, and less chance of quick-and-dirty collaboration on a branch. Conversely, a tech team would benefit from a centralized repository with trackable branches. Either way will necessitate strict organization.

As an open source project, the Accord Project follows the fork workflow model. Still, the main branches should be kept in sync (guide for syncing), and every feature, bug fix, release, or code change should occur in a different branch. This will be discussed more in the next section.

Naming a new branch will be one of the first steps in keeping a consistent tracking system of Issues, pull requests, and git history. The important factor here is consistency.

name/issue-tracker/short-description

name: Anything from initials to full name to GitHub username

issue-tracker: Reference the issue from GitHub or some other agile user stories source

short-description: One to three words describing the main goal of this branch, separated by hyphens

Example:

irmerk/i7/new-feature

In the case of collaborating on a single feature, maintain a single, main branch for the feature and individual branches from it. This can follow the previous naming convention:

main/i14/routing-service // team branch

irmerk/i14/routing-service // my branch

someone/i14/routing-service // someone else's branch

Personal branches can be merged into the main team branch, which will then be merged with the overall main through a pull request. Delete branches after they are merged.

Rebase + Squash

Common practice for teams is to squash or condense long commit message chains into one or a few commits before merging into main. This is useful when, like me, someone commits frequently and thus would clutter a git log. Squashing serves to maintain a readable git log.

Prior to merging a feature branch into the main (main) branch, it should be rebased from the up-to-date main. A pull request, discussed later, will be where all the commits of this branch are squashed down to a single buildable commit and merged into main. Rebasing essentially ports a branch (main) into your current branch by applying all of your commits on top of that branch (main), then replacing your branch with the revised version. This catches you up to a branch (main) by rewriting git history in your local git.

Think of it as moving your branch to the tip of main instead of having branched off from an earlier version of main.

Instead of needing to heavily investigate individual commits from a branch, each merge commit to main should contain all the code for a feature or bug fix. This allows for a much easier investigation process.

While squashing prior to rebasing reduces conflicts due to fewer steps of conflict resolution, it literally changes the history of the repository as documented on GitHub for everyone, and thus is not the most accurate representation. Rebasing before squashing retains the git log tidiness and you don’t change history prior to documenting it on GitHub.

Interactive Rebase

git rebase -i is super useful in several circumstances, such as needing to quickly remove a commit. If your team has a policy in which any feature commit must also contain tests for that feature, squashing several commits into one can be helpful. This would involve git rebase -i HEAD~n and replace n with the number of commits — replace pick on those commits’ lines to squash.

If your project, like the Accord Project, requires a Developer Certificate of Origin sign-off, you may find yourself needing to rapidly change the messages on a series of commits. Similarly to before, change pick to edit on the commits needing to change and simply git commit --amend -s and git rebase --continue for each commit. git push -f into the branch for the pull request. Caution: Force pushing can have dire consequences if not used properly, consult others if unsure how to use this.

Generally, if you do not have large, confusing conflicts, -i (interactive rebase) will be overkill.

Rewriting History

While rewriting history with git rebase is extremely useful in some cases, caution should still be taken. Make sure to not interrupt other people’s history and commits on accident. Caution: Avoid force pushing to a remote branch other people are working on.

Fear

I still fear rebase and squash. Merge conflicts can be more frequent and seem more difficult. I’ve had experiences of losing work due to incorrectly rebasing.

However, if you frequently commit ongoing work, rebasing complications should be infrequent. Fixing conflicts and git rebase --continue can feel intimidating at first, but continue working with it. A merge commit will be made with these conflicts, but that is important history on how a conflict was resolved. You can always try again if you feel it is going poorly with git rebase --abort and try again — this reverts too before the rebase attempt.

Flow

My recommendation for a general workflow:

Ensure you are currently in main → If working in a fork, fetch:

git checkout main
git fetch --all --prune
git merge --ff-only upstream/main
git push origin main

→ If working in a branch, pull:

git checkout main
git pull origin main

Create a new branch for your feature or bug fix

git checkout -b branchName

Make changes with as many commits as necessary. The final commit should build and pass tests.
Make sure your branch sits on top of main (as opposed to branch off a branch). This ensures the reviewer will need only minimal effort to integrate your work by fast-fowarding main

git rebase upstream/main

If you have previously pushed your code to a remote branch, you will need to force push. If not, omit the -f tag.

git push origin branchName -f

Open a pull request in GitHub from this forked branch. Once this has been merged to main, remember to clear out your branch locally

git branch -D branchName

Merge

As a non-destructive operation, merging can be nice. However, if the main you are working on is quite active, the git log can be polluted quickly by the extra commit created by a merge operation.

While many developers are uncomfortable with rebasing and resort to merge main on top of their changes, merging is not always the best option. If merging locally instead of rebasing, at the very least squash a pull request to merge into main on GitHub. This allows for greater control of the commit messages in main for the git log.

CLI

The Command Line Interface (CLI) is a place you can run all git commands. Git graphical user interfaces (GUI) such as GitKraken and Tower are great. I opt to not use them due to them being priced as well as the vast majority of solutions found online involving git are for CLI.

Moreover, knowing the CLI method of git allows you to easily navigate a GUI, but the reverse is not necessarily the case. Learning to interact with git and GitHub via the CLI will be a great use of your time, especially if you work with open source projects.

Diff

A good habit to adopt is utilizing git diff prior to committing anything. This allows you to ensure the code being committed is what you expect, all debugging statements are removed, and no junk is included.

Log

Logs reveal a history of everything that happens in a repository. This tool has many options for displaying commit history in specific ways. A full log contains a commit hash, author, date, and message. My preferred way of logging builds an ASCII graph representing the branch structure

git log --graph --decorate --pretty=oneline --abbrev-commit

Blame

A method for inspecting who changed what and when in files is git blame. If you code in VSCode, I strongly recommend looking into GitLens, which makes this inspection inline and extremely efficient.

Commits

A single logical change should be captured in a commit. More than one logical changes in a commit — an instance in which you may find yourself writing “and” in a commit message — is a good indicator of needing to split into two separate commits.

Commit often — do not let yourself get too far without committing. Small, incremental and self contained commits are easier to follow or revert in the future.

While ordering commits logically would be ideal, I recommend committing in the order in which you are working — this is a chronological history of what you did.

Messages

Take a moment for this process — a commit message should not be rushed. The description of a commit should be well documented, and thus will prove invaluable to whoever reads this in the future in attempt to understand why a change was made — even if they have little to no context. This accessibility is a vital goal for a thorough git history and workflow.

Include external information references such as Issues or pull requests. Anything that will be helpful to others or your future self should be reasoned out now. The long term success of a project relies on the maintainability of the code and log. A hassle at first pays off as a healthy habit.

Use the terminal, not the editor, when writing a commit message. Committing from the terminal encourages a mindset of describing a change in an incremental way, as well as keeping commits atomic — commits should not need a paragraph of explanation. This will assist you in creating a pull request message, where an overall change should be captured. More on this later.

Concise and consistent commit messages should be captured by always including the -m <msg> flag to a git commit.

Formatting

A properly formed git commit subject line should always be able to complete the following sentence:

If applied, this commit will your subject line here

type(scope): subject — footer

Types:

feat— A new feature
fix— A bug fix
docs— Changes to only documentation
style— Changes to formatting (missing semi colons, etc.)
refactor— A code change that neither fixes a bug nor adds a feature
test— Adding missing or correcting existing tests
chore— Change to build process or auxiliary tools, or maintenance

Scope:

Focal point of new code or best description for where changes can be found.

Subject:

Imperative description of changes, kept under 50 characters (not capitalized and no period)

Footer:

GitHub Issue reference ID

Examples

feat(utilities): include optional state for test utility - I22
    // implement a feature in src/utilities/test/sagaTest.js
test(sagas): initiate test for failed templates fetch - I22
    // tests run in and of src/sagas/*
chore(package): install saga testing library - I22
    // edits to dependencies in package.json
docs(README): add netlify badge and update - I27
    // alter documentation in the readme file

Pull Requests

A pull request (PR) is one of the best ways to share information. While an Issue describes what may be wrong or a feature, a PR provides a medium for what changes are actually occurring to the codebase. Moreover, it is excellent for peer reviews and accountability, as it encourages quality commits. When done well, the commits that construct a PR tell the whole story to those who review the code or examine it in the future.

PRs should consist of a complete addition to the code which contains value. Because the commits inside follow a pattern, the title should be an extension or summary of all the commits inside. Thus, earlier when I spoke of squashing, a git log will retain the pattern of each commit even after it is tidied up. To emphasize, a PR title should follow commit message formatting described above.

As a GitHub workflow tool, the innards of a PR are less important than the title maintaining the consistency and efficiency of formatting. This allows git logs to remain efficient with or without GitHub.

Similar to commits, PRs should be small. A PR which attempts to do multiple things (find yourself writing “and” in the title?) should be split up.

Cleanup

As discussed previously, rebasing prior to creating a PR is a good tidying habit. Take a moment to merge any extra commits created along the way, or reword commits for clarity. Every commit in a PR should be directly working towards the goal of the title of the PR, or even the related GitHub Issue.

Formatting

<!--- Provide a formatted commit message describing this PR in the Title above -->
# Closes #<CORRESPONDING ISSUE NUMBER>
<!--- Provide an overall summary of the pull request -->

### Changes
<!--- More detailed and granular description of changes -->
<!--- These should likely be gathered from commit message summaries -->
- <ONE>
- <TWO>

### Flags
<!--- Provide context or concerns a reviewer should be aware of -->
- <ONE>
- <TWO>

### Screenshots or Video
<!--- Provide an easily accessible demonstration of the changes, if applicable -->

### Related Issues
- Issue #<NUMBER>
- Pull Request #<NUMBER>

### Author Checklist
- [ ] Ensure you provide a [DCO sign-off](https://github.com/probot/dco#how-it-works) for your commits using the `--signoff` option of git commit.
- [ ] Vital features and changes captured in unit and/or integration tests
- [ ] Extend the documentation, if necessary
- [ ] Merging to `main` from `fork:branchname`
- [ ] Manual accessibility test performed
    - [ ] Keyboard-only access, including forms
    - [ ] Contrast at least WCAG Level A
    - [ ] Appropriate labels, alt text, and instructions

GitHub PRs are in Markdown
Keep in mind: What does this change do to address the issue and what side effects may it have? Why was it necessary? Try to preempt a reviewer needing to ask questions, be thorough in your information.

Drafts

GitHub offers a useful option for a PR which is not ready to be reviewed quite yet. If you want to have a source of truth in a PR for others to interact with prior to actual review, or even just to ensure the code is saved on GitHub and not only on your local machine, open a draft pull request.

Reviews

Setting a standard for PR reviews is important, and being thorough equally so. A reviewer is a guardian of the git history and code quality. This cannot be stressed enough. What seems obvious now will surely not be so in months’ or years’ time. Do not feel bad for requesting changes or having changes requested of you. It is better to have pristine code merged into main than to rush through out of desire to be done with a feature.

Strike a balance between the flow of getting PRs through and not holding up further edits or production, and maintaining quality. Every reviewer should make a judgment on whether an issue is sufficient enough to block a PR. However, anyone who contributes to the PR should not be reviewing what is merged into main. Keep a healthy separation between these roles. Generally, it is faster for the PR author to fix the code than for a reviewer to be involved.

GitHub

Issues

Very easy to maintain, Issues should be used liberally. Any question, idea, or bug — duplicate or not — should be reason enough to open an Issue. These are the foundation of conversations in projects, so insert points of view and establish a concrete record of discussions which can be searched and linked.

Speaking of which, search through a project before opening an Issue. While duplicates can be easily closed, this is a courtesy to other contributors. Also, be thorough and provide as much context as possible. Maybe even take a moment to read the project’s documentation on contributing, they may have guidelines on formatting an Issue.

Example feature request formatting of an Issue:

<!--- Provide a general summary of the feature in the Title above -->
# Feature Request 🛍️
<!--- Provide an expanded summary of the feature -->

## Use Case
<!--- Tell us what feature we should support and what should happen -->

## Possible Solution
<!--- Not obligatory, but suggest an implementation -->

## Context
<!--- How has this issue affected you? What are you trying to accomplish? -->
<!--- Providing context helps us come up with a solution that is most useful in the real world -->

## Detailed Description
<!--- Provide a detailed description of the change or addition you are proposing -->

Noise

Stay mindful of what you are presenting for others to read. Is it worth their time? Avoid posting short, rushed answers or responses. Take the time to be worthwhile to yourself and others in your contributions. Provide as much context as possible while still being helpful. Too little and too much context are both quite awful.

If a significant amount of time has passed, send a gentle bump to reviewers. It can be easy to forget about an active PR.

Open Source

I recommend this guide for contributing to open source. GitHub provides great functionalities which should be utilized for the best possible experience of contributing developers. Issues can be tagged for ease of navigation, protections can be enforced to prevent direct commits to main, and multiple reviewers can be required.

This guide is aimed at providing a framework which fosters a healthy, collaborative atmosphere. All of this can be applied and tweaked for any open source or proprietary tech team environment.

Conclusion

Contribute the work you would like to see. Politeness, respect, thoroughness, and efficiency are all things we appreciate, so develop and maintain good habits with git and collaborations will be the best they can be.

Perception is important in open source, and how others view the git log can make a big difference. Take time to care for the log with efficient commits and git etiquette. This is also true for a company and a new hire.

Feel free to contact me with any questions or feedback.