Building jargons.dev [#7]: The Word Editor Script

#javascript #opensource #productivity #buildinpublic

Remember the "The Word Editor"!? Here's the script responsible that implements it's end-to-end functionalities that allows for writing changes via the user interface to a user's forked repository.

The Functional Breakdown

The Word Editor empowered by the script should perform two (2) functions, taking some certain steps

Write New Word - basically to add new word to the dictionary; does this in the following steps...
- Get an already established word template (.md) file
- Fill template placeholder with collected word title and content to create a word.mdx file in the appropriate words directory src/pages/browse
- and commit the change to an established change branch/ref on the user's forked repository
Edit/Update Existing Words - modify existing word in the dictionary, it does this in the following steps...
- Get an existing word from the user's fork of jargons.dev (looking in the words directory src/pages/browse)
- Parse its content and make necessary edits
- and and commit the change to an established change branch/ref on the user's forked repository

The breakdown inspired creation of the following helper and utility functions.

writeNewWord - a function that accepts the word title and content amongst others, leveraging the user's GitHub authenticated instance, it perform a write operation i.e. writing a new file (word.mdx) to a fork of jargons.dev on the user's account on their behalf through the "PUT /repos/{owner}/{repo}/contents/{path}" endpoint.
getExistingWord - a function that simply retrieves the content of an existing word file on the user's forked repository, with the aim of availing it for edit. It does this by taking the word as argument and concatenates it in the path param (example src/pages/browse/${normalizeAsUrl(word)}.mdx) of the request it makes to the endpoint "GET /repos/{owner}/{repo}/contents/{path}"; It is important to state that I had to make a few adjustments to the returned data from this helper for consumption reason, the adjustments are as followed
- Added title property: the response.data object which comes from the query to the endpoint "GET /repos/{owner}/{repo}/contents/{path}" doesn't have a title property (this is the word itself);
- Added content_decoded property: the response.data.content property holds the main content of the retrieved word, BUT it comes in a "base64" format; so I thought it'd be nice if the functional avails it in the consumption-ready format which can be use immediately without the need to convert at consumption. These I did with code below...
```
const { content, ...responseData } = response.data;

return {
  title: word,
  content,
  content_decoded: Buffer.from(content, "base64").toString("utf-8"),
  ...responseData
};
```
updateExistingWord - with an initial name of editExistingWord and changed to current name in jargonsdev/jargons.dev#34, this function performs similar operation with the writeNewWord but it over-writes existing word content in a specific file by replacing the file with another file with updated content. This is also done via user's account on their behalf through the "PUT /repos/{owner}/{repo}/contents/{path}" endpoint.
writeFileContent - this helper as implied in its name does one thing — it writes file content for words which is submitted in requests made by both writeNewWord and updateExistingWord to the GitHub API, it does this by taking a word title and content (i.e. word definition) as variable and generates a content from a template avail to it replacing placeholder contents in it.

The PR

feat: implement `word-editor` script #18

babblebey posted on Apr 02, 2024

This Pull request implement the word-editor script; the primary functionality of this script is to allowing adding new word, retrieve and update existing word which are individual .mdx files residing in the src/pages/browse directory of the project. This script avails us of all the helper functions required to perform this operations.

Changes Made

Implemented the writeNewWord function - this function takes 3 params namely the userOctokit, forkedRepoDetails, and the word; it leverages the userOctokit instance to perform a write operation i.e. writing a new file (newWord.mdx) to a fork of our project on the user's account on behalf of the user through the "PUT /repos/{owner}/{repo}/contents/{path}" endpoint
Impelemented the getExistingWord function - this function helps retrieve data of existing words in the fork of our project on the user's account by calling the "GET /repos/{owner}/{repo}/contents/{path}" endpoint; it returns an object which carries the following properties that we are mostly interested in...
- title - title of the the existing word - this infact is a custom appended data to the response.data from the call made to the endpoint
- path - path to the existing word file
- sha - unique SHA of the existing word
Implemented the editExistingWord function - this function takes 3 params namely the userOctokit, forkedRepoDetails, and the word (holds the properties: path, sha, title and content); it leverages the userOctokit instance to perform a edit operation i.e. updating the existing file on a fork of our project on the user's account on behalf of the user through thesame "PUT /repos/{owner}/{repo}/contents/{path}" endpoint
Implemented writeFileContent helper function - this function help write a content for our dictionary word file generating them from another added constant in the src/lib/template/word.md.js