enriquekesslerm.com

Publish your cargo docs

2023-12-16T00:00:00+00:00

As discussed on https://github.com/CeleritasCelery/rune/issues/48</a>, we see valuable to publish the documentation to somewhere consumable, for future contributors to see the documentation without actually having the barrier of running cargo doc --workspace</code> on their machines.

Was testing the way to publish the cargo doc output, and saw that the tracing crate is doing something very similar with netlify. Since I like netlify (have this web on there) thought that we can do an MVP with something similar to tracing</code>: https://tracing-rs.netlify.app/tracing/

First, we move the core changes I have on master</code> to core</code> again. We want to be clean for the docs publishing</code> PR. We need dependencies included as part of the builds on netlify, because we seem to need gdk and pango, as with the CI. Talking about CI, we need to only publish these changes upon push to mainline, which is kinda what netlify does by default, so we should be good there, no need to update the CI.

There are some issues with the dependencies, so I'm really interested in knowing why we have them on the rune repo either way. Do we require specific dependencies for anything? Can we gate those dependencies with features (cfg or something) to avoid this?

Since we have that limitation, it sounds like we could build a CI step to happen on push to master where we would install rustup with the dependencies, run the command ourselves and deploy the target/doc, similar to what netlify is doing. I wonder whether netlify can just deploy a directory. Let's see with the netlify github action.

# .github/workflows/netlify.yml
</span>name</span>: </span>Build and Deploy to Netlify
</span>on</span>:
</span>push</span>:
</span>pull_request</span>:
</span>jobs</span>:
</span>build</span>:
</span>runs-on</span>: </span>ubuntu-22.04
</span>steps</span>:
</span>- </span>uses</span>: </span>actions/checkout@v3
</span>
</span>      </span># ( Build to ./dist or other directory... )
</span>
</span>      - </span>name</span>: </span>Deploy to Netlify
</span>        </span>uses</span>: </span>nwtgck/actions-netlify@v2.0
</span>        </span>with</span>:
</span>          </span>publish-dir</span>: </span>'./dist'
</span>          </span>production-branch</span>: </span>master
</span>          </span>github-token</span>: </span>${{ secrets.GITHUB_TOKEN }}
</span>          </span>deploy-message</span>: </span>"Deploy from GitHub Actions"
</span>          </span>enable-pull-request-comment</span>: </span>false
</span>          </span>enable-commit-comment</span>: </span>true
</span>          </span>overwrites-pull-request-comment</span>: </span>true
</span>        </span>env</span>:
</span>          </span>NETLIFY_AUTH_TOKEN</span>: </span>${{ secrets.NETLIFY_AUTH_TOKEN }}
</span>          </span>NETLIFY_SITE_ID</span>: </span>${{ secrets.NETLIFY_SITE_ID }}
</span>        </span>timeout-minutes</span>: </span>1
</span></code></pre>
Added both the NETLIFY_AUTH_TOKEN and the NETLIFY_SITE_ID to the secrets of my fork of rune. Let's test the github action by pushing to docs.</p>
It did publish, but since the target/doc directory has all the crates, including the `rune` one, we should set up a redirect from /</code> to /rune</code>. All the internal links should work.</p>
As part of the same PR, I fixed all the warnings on cargo doc, making sure that the documentation is correctly published. The trick to deploy cargo doc is to deploy target/doc</code> and then pair that with a redirect of the main page (configured rune-rs.netlify.app on my own account) to /rune</code> which (as the main crate) has the info about the subcrates as well.</p>
IMPORTANT</strong></strong>: For this to work, you need to do the following steps. I would do the steps myself, but I imagined you would like to have control of the app itself, as the author of the project:</p>

Create a Netlify account if you don't have any.</li>
Create a new site with the Rune project on Github.</li>
Note down</strong></strong> the site id.</li>
Change the site name to something like rune-rs, for https://rune-rs.netlify.app</a> to work. I'll remove my site with the same name to avoid conflicts.</li>
Go to your profile, User Settings, Applications and Generate a No Expiry (or to be expired, although that will need changing the secrets whenever it expires again) Personal Access Token and note it down</strong></strong>.</li>
Go to the SECRETS configuration of this repo.</li>
With the site id you noted down, add the NETLIFY_SITE_ID secret.</li>
With the personal access token you noted down, add the NETLIFY_AUTH_TOKEN secret.</li>
</ol>
The site will be published on any push to master</code>, no need to publish on PRs!</p>
With that, we have a successfully published cargo docs on https://rune-rs.netlify.app</a> so that other contributors can see the documentation without the barrier of running cargo doc --workspace</code> manually. Here's the PR</a>.</p>



Setting up the Rune project for success
2023-12-02T00:00:00+00:00
Introduction</h2>
After very recently syncing with Troy, the owner of the Rune project (you can check my first contribution blog post here</a>), we were discussing about the next (immediate) steps for the project, and overall my next contribution. Here's my proposal:</p>

Step by step, we need CI for pull requests and then we can potentially work on simplifying and completing the backlog of issues we have. With a prioritized backlog, we can call for contributions on both Emacs and Rust’s subreddits. What do you think?</p>
After the CI, I can build something with async rust (probably file io can benefit from it), and make sure to measure it with benchmarks (criterion or cargo benchmark). Those benchmarks could potentially be added to CI once we are happy with them, and make sure we don’t regress performance with pull requests or commits.</p>
Looking forward to next steps,
Best,
Quique.</p>
</blockquote>
With that, here's the first step: CI for the Rune project, buckle up!</p>
Stepping stones</h2>
I was aware that Jon Gjenset (@jonhoo) did a super nice video explaining his recommendation for CI that should run on lib/bin crates (ref</a>). That video goes through an overview of some files of the project rust-ci-conf</a>, which is a set of Github Actions workflows to cover the bare minimum for crates: stepping stones to a great CI pipeline for our Rune project.</p>
With that, I used the project as a blueprint of what CI could look like and started modifying the workflows with the specific requirements of the rune</code> crate. From the top of my head:</p>

Rune is a binary, not a library, so we can't run doctests on it.</li>
Rune has the rust-toolchain set to beta</code> and that broke CI and is not common in other popular crates.</li>
Rune does not have any feature gates so cargo-hack</code> wouldn't do us any good.</li>
Rune does not run correctly on Windows (yet), so it wouldn't make sense to run CI on something we don't support yet.</li>
Rune uses unsafe</code> code, which means we need to care about safety and ensure any change is sanitized and avoids any Undefined Behaviour.</li>
</ul>
Staring from those requirements, I modified the DOCS.md file of the .github folder</a> with the intention of documenting possible improvement points I see on CI, with the intention of future contributors iterating on the current CI pipeline.</p>
Potential improvements</h2>
cargo-hack</h3>

cargo-hack</code> checks combinations of feature flags to ensure that features are all additive which is required for feature unification.</p>
</blockquote>
source</a></p>
As we don't currently have any meaningful feature gates.</p>
scheduled</h3>

Run scheduled (rolling) jobs on a nightly basis, as your crate may break independently of any given PR. E.g., updates to rust nightly and updates to this crates dependencies. See check.yml for information about how the concurrency cancelation and workflow triggering works</p>
</blockquote>
source</a></p>
As we don't run on nightly, we don't really need to check whether nightly breaks our builds. A potential argument for adding this could be that we are running nightly for the CI, and we could break the CI from nightly builds. I propose revisiting adding the scheduled.yml</code> linked above if that's the case.</p>
loom</h3>

Loom is a testing tool for concurrent Rust code. It runs a test many times, permuting the possible concurrent executions of that test under the C11 memory model. It uses state reduction techniques to avoid combinatorial explosion.</p>
</blockquote>
source</a></p>
Loom is great and it's backed by Tokio, but it would mean a bigger investment in making the threads we use be loom specific. Definitely something to iterate on, as we get onto Async Emacs.</p>
codecov.io</h3>

Enhance Your Testing the Codecov Way: Codecov is the all-in-one code coverage reporting solution for any test suite — giving developers actionable insights to deploy reliable code with confidence.</p>
</blockquote>
source</a>, repo of Github Action</a></p>
If we want to add a badge or have nice reports on coverage, we could investigate CodeCov. It requires a token that should be added to the secrets of the repository: CODECOV_TOKEN</code>.</p>
Windows tests</h3>
matrix</span>:
</span>    </span>os</span>: [</span>macos-latest</span>] </span># REVIEW: We could add windows-latest here.
</span></code></pre>
As of today, we don't support Windows, or at least the tests are failing. We can iterate on this and if we feel Windows should be supported in the near feature, we can add windows-latest</code> to run CI on it.</p>
Doctests on binary crates</h3>
As suggested by issue</a>, doctests won't currently run on Binary creates. I don't see anything particularly wrong with running doctests on binary crates. Some of the argumenst include that "Why would a binary be documented?". Documentation is not only useful for consumers of the library, but rather also internal developers that are maintaining it, looking for better understanding of the binary crate. It's key that developers onboarding into the project have the material to have a swift ramp-up process, to move the project forward. </p>
Once the issue above is stabilized, we can add the following to the test.yml fire:</p>
-   </span>name</span>: </span>cargo test --doc
</span>    </span>run</span>: </span>cargo test --locked --all-features --doc
</span></code></pre>
Iterative process</h2>
The overarching theme with this contribution is: I see CI as an iterative process, and I'm sure we'll be changing it in the future</strong>. This acts as a good start, and opens the project to possible issues it may have, that CI now catches (say, dependency issue, as we see running cargo test</code> with -Zminimal-versions</code>).</p>
I see this first PR as not fixing all the issues with the repository, but rather creating the stepping stones to fix them in the next commits. Every commit that includes this PR has been tested with the CI changes, iterating on the process. I'm open to rebasing the commits if needed, but it's useful to see the iteration process to arrive to a CI that fits the project's needs.</p>
Conclusion</h2>
I was able to get a successfully configured CI pipeline for the Rune project, and propose additional improvements that we can discuss on the PR for it. I see CI as an iterative process, and I bet it's something we modify sooner than we think. As suggested by the step by step game plan above, next steps include:</p>

Run the runtime directly on Emacs, and add it to the CI.</li>
Create a benchmark suite to avoid any regressions on performance, and add it to the CI.</li>
Start playing with async code, where loom</code> could potentially fit (and add it to the CI).</li>
</ul>
Lots of work left, really excited about the future!</p>
P.S: Here's the PR link: #35</a></p>


Bye lazy_static, Welcome once_cell!
2023-11-26T00:00:00+00:00
Introduction</h2>
Very recently I have become really interested in a project called rune</a> (R</strong>ust Un</strong>der E</strong>macs, love the name), which in nature creates a Rust Virtual Machine to run Emacs on. The author of the project has written in detail about pros and cons of using Rust here</a>, for avid readers!</p>
In this post, I plan to contribute to the project by migrating all the usages of the late lazy_static</code> to the newer alternative once_cell</code>. once_cell</code> has the benefit of being macro-less and being included in the standard library, as of 1.70 (there's nice documentation in the module</a>).</p>
Since it's included in the standard library, I thought we could just use that, but then I thought back to the project initiative: do we need to support a minimal Rust version, say running on old devices? Quite possible not</strong>, as the project is not yet in production (0.1.0 version, though I don't think we are following semver</a>) and it won't be for a while. I don't find locking ourselves into a once_cell</code> dependency is the right play, but rather, use the std version.</p>
Minimal Stable Rust Version</h2>
Nevertheless, for the sake of completion, I wanted to verify the minimal Rust version we support in the rune repo. For that, we can use the command provided by the cargo-msrv crate</a>: </p>
></span>  cargo </span>msrv
</span>│     Checking fluent-syntax v0.11.0                                                     │
</span>│     Checking fluent-bundle v0.15.2                                                     │
</span>│    Compiling quote-use-macros v0.7.2                                                   │
</span>│     Checking tracing v0.1.40                                                           │
</span>│     Checking druid v0.8.3                                                              │
</span>│    Compiling quote-use v0.7.2                                                          │
</span>│    Compiling attribute-derive-macro v0.6.1                                             │
</span>│    Compiling attribute-derive v0.6.1                                                   │
</span>│ Compiling get-size-derive v0.1.3                                                       │
</span>│ (https://github.com/CeleritasCelery/get-size.git</span>?</span>branch=boxed_slice_fix#e0e9377d</span>)      </span>│
</span>│ Checking get-size v0.1.4                                                               │
</span>│ (https://github.com/CeleritasCelery/get-size.git</span>?</span>branch=boxed_slice_fix#e0e9377d</span>)      </span>│
</span>│     Checking text-buffer v0.1.0 (/Users/enrikes/Documents/rune/crates/text-buffer</span>)     </span>│
</span>│ error</span>[</span>E0658</span>]</span>: use of unstable library feature </span>'is_some_and'</span>                            │
</span>│    --</span>></span> src/buffer.rs:130:29                                                            │
</span>│     </span>|                                                                                  </span>│
</span>│ 130 </span>|         |</span>name: </span>&</span>str</span>| </span>ignore.is_some_and(</span>|</span>x</span>| </span>x == name</span>) </span>||                        </span>│
</span>│ !buffer_list.contains_key(name</span>)</span>;                                                       </span>│
</span>│     </span>|                             </span>^^^^^^^^^^^                                          │ │     </span>|                                                                                  </span>│
</span>│ = note: see issue </span>#93050 <https://github.com/rust-lang/rust/issues/93050> for more     │
</span>│ information                                                                            │
</span>│                                                                                        │
</span>│ For more information about this error, try `rustc --explain E0658`.                    │
</span>│ error: could not compile `rune` due to previous error                                  │
</span>└────────────────────────────────────────────────────────────────────────────────────────┘
</span>Finished The MSRV is: 1.70.0   ███████████████████████████████████████████████ 00:15:22
</span></code></pre>
Good to see, the Minimum Stable Rust Version is the 1.70.0, which includes std::sync::OnceLock</strong> (If you are curious about the error above, the API is_some_and</code> has been stabilized in 1.70.0</a> as well).</p>
Investigation</h1>
With that, we'll move forward with OnceLock (Sync version of OnceCell), but pretty much the same properties apply:</p>

OnceCell is somewhat of a hybrid of Cell and RefCell that works for values that typically only need to be set once. This means that a reference &T can be obtained without moving or copying the inner value (unlike Cell) but also without runtime checks (unlike RefCell). However, its value can also not be updated once set unless you have a mutable reference to the OnceCell.</p>
OnceCell provides the following methods:</p>

get: obtain a reference to the inner value</li>
set: set the inner value if it is unset (returns a Result)</li>
get_or_init: return the inner value, initializing it if needed</li>
get_mut: provide a mutable reference to the inner value, only available if you have a mutable reference to the cell itself.</li>
</ul>
The corresponding Sync version of OnceCell is OnceLock</p>
</blockquote>
source</a></p>
The first change I plan to make to the code base is the buffer.rs</a>, not part of core. REVIEW</strong>: I wonder whether as a follow-up we can consider moving the code around to avoid having similar files without their own modules.</p>
lazy_static! </span>{
</span>    </span>static ref </span>BUFFERS</span>: Mutex<HashMap<</span>String</span>, </span>&</span>'static</span> LispBuffer>> </span>=
</span>        Mutex::new(HashMap::default());
</span>}
</span>
</span>// versus the OnceLock version.
</span>
</span>static </span>BUFFERS</span>: OnceLock<Mutex<HashMap<</span>String</span>, </span>&</span>'static</span> LispBuffer>>> </span>= </span>OnceLock::new();
</span></code></pre>
As you'll see, we are not initializing the value here, and there isn't really an API to do so in the std, while there was on once_cell. If we wanted to hold the value across the different modules, we could potentially initialize it on main.rs and then access its value across the different functions. Don't know whether context here is that, or rather the context of the function, say all the variables at the time of execution (global set with setq</code>, and locals created with let*</code> for example).</p>
Interesting, checking the Context struct</a>, we are using std::cell to hold the vector of OwnedObject</code>, which makes me think whether the lazy_static!</code> usage is just due to old code that wasn't ported to the new APIs. Right, that's not the case, the git blame</code> command shows that the lazy_static!</code> macro was used in 2023. Since we don't have the LazyLock API stabilized yet (issue tracker</a>), we'll have to think of an ergonomic way to initialize the BUFFERS static:</p>

We could initialize it in main.rs and then consume it, although we would kinda using the BUFFERS static as a global variable, and that means that all the modules would be aware of it, which is probably not the right solution.</li>
We could initialize it on each of the lock()</code> usages, which is kinda repeating the initialization part.</li>
We could have a helper function on buffer.rs that gets or inits the BUFFERS static.</li>
</ol>
Opting for three, created this helper function:</p>
/// Helper function to avoid calling `get_or_init` on each of the calls to `lock()` on the Mutex.
</span>///
</span>/// TODO: Once [`LazyLock`] is stabilized, this can be changed to initializing on the LazyLock::new() method.
</span>/// Stabilization tracker: https://github.com/rust-lang/rust/issues/109736
</span>fn </span>buffers</span>() -> </span>&</span>'static </span>Mutex<HashMap<</span>String</span>, </span>&</span>'static</span> LispBuffer>> {
</span>    </span>BUFFERS</span>.</span>get_or_init</span>(|| Mutex::new(HashMap::default()))
</span>}
</span></code></pre>
Did something very similar for data.rs</a>. With that, we are only missing the complex changes for the INTERNED_SYMBOLS</code> (ref</a>). This is great, because it's making me dive deeper into why we are using x or y in different files. In this case, let's dive deep into the build.rs file</a>. We seem to be working with nightly a lot. Let's message the owner and see what he thinks. If he's good with it, we could just use LazyLock</code> instead of helper methods on buffer.rs and data.rs.</p>
build.rs</h1>
I was trying to understand why we include everything we generate with the build.rs file using the include!</code> macro, and I was pointed to https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script</a>.</p>
I don't see that we are actually running the println!</code> macros that I'm adding inside the build.rs file when running cargo run -- --load --repl</code>. I wonder when is that build.rs file running. Searching around, I see that because of this issue</a>, println!</code> won't run anything as it's used to communicate with cargo to run specific cargo commands on it (ref</a>). A workaround of this is to use println!("cargo:warning={}", ...)</code> we'll see the output. From that debugging output, I understand that:</p>

The build.rs script is used on rune to pull all the functions created for FFI using the #[defun] macro. From that macro, we take the lisp name and the contents and define the outputs for emacs to consume.</p>
</blockquote>
Here's the output of my prints:</p>
warning: rune@0.1.0: Reading </span>"src/emacs.rs"
</span>warning: rune@0.1.0: name between predicates </span>"kill_emacs"
</span>warning: rune@0.1.0: lisp_name: kill-emacs
</span>warning: rune@0.1.0: Reading </span>"src/reader.rs"
</span>warning: rune@0.1.0: Reading </span>"src/interpreter.rs"
</span>warning: rune@0.1.0: name between predicates </span>"eval"
</span>warning: rune@0.1.0: lisp_name: eval
</span>warning: rune@0.1.0: Reading </span>"src/threads.rs"
</span>warning: rune@0.1.0: name between predicates </span>"go"
</span>warning: rune@0.1.0: lisp_name: go
</span></code></pre>
Basically, we read through the files and build all the defuns, but also the defsym</code> and the defvar</code> (ref: https://github.com/CeleritasCelery/rune/blob/master/build.rs#L103-L110</a>). For the defsym, wanted to understand what they are a bit further. Added the print for all_defsym</a>:</p>
warning: rune@0.1.0: </span>[</span>(</span>"KW_TEST"</span>, None), (</span>"KW_DOCUMENTATION"</span>, None), (</span>"MD5"</span>, None), (</span>"SHA1"</span>, None), (</span>"SHA224"</span>, None), (</span>"SHA256"</span>, None), (</span>"SHA384"</span>, None), (</span>"SHA512"</span>, None), (</span>"MANY"</span>, None), (</span>"INTEGER"</span>, None), (</span>"SYMBOL"</span>, None), (</span>"COMPILED_FUNCTION"</span>, None), (</span>"HASH_TABLE"</span>, None), (</span>"BUFFER"</span>, None), (</span>"SUBR"</span>, None), (</span>"FUNCTION"</span>, None), (</span>"QUOTE"</span>, None), (</span>"MACRO"</span>, None), (</span>"UNQUOTE"</span>, Some(</span>"\",\""</span>)), (</span>"SPLICE"</span>, Some(</span>"\",@\""</span>)), (</span>"BACKQUOTE"</span>, Some(</span>"\"`\"")), ("</span>AND_OPTIONAL</span>", Some("\"</span>&</span>optional</span>\"")), ("</span>AND_REST</span>", Some("\"</span>&</span>rest</span>\"")), ("</span>LAMBDA</span>", None), ("</span>CLOSURE</span>", None), ("</span>CONDITION_CASE</span>", None), ("</span>UNWIND_PROTECT</span>", None), ("</span>SAVE_EXCURSION</span>", None), ("</span>SAVE_CURRENT_BUFFER</span>", None), ("</span>WHILE</span>", None), ("</span>INLINE</span>", None), ("</span>PROGN</span>", None), ("</span>PROG1</span>", None), ("</span>PROG2</span>", None), ("</span>SETQ</span>", None), ("</span>DEFCONST</span>", None), ("</span>COND</span>", None), ("</span>LET</span>", None), ("</span>LET_STAR</span>", Some("\"</span>let*</span>\"")), ("</span>IF</span>", None), ("</span>AND</span>", None), ("</span>OR</span>", None), ("</span>INTERACTIVE</span>", None), ("</span>CATCH</span>", None), ("</span>THROW</span>", None), ("</span>ERROR</span>", None), ("</span>DEBUG</span>", None), ("</span>VOID_VARIABLE</span>", None)]
</span></code></pre>
We seem to be defining them on different files, here's eval.rs:</p>
defsym!</span>(</span>FUNCTION</span>);
</span>defsym!</span>(</span>QUOTE</span>);
</span>defsym!</span>(</span>MACRO</span>);
</span>defsym!</span>(</span>UNQUOTE</span>, </span>","</span>);
</span>defsym!</span>(</span>SPLICE</span>, </span>",@"</span>);
</span></code></pre>
They seem to be symbols, probably for use on the different functions that we create. Don't think I should dive deeper there, won't work on it for now.</p>
Let's start with the build.rs changes for once_cell, now that we know how that file will be created on the OUT_DIR</code>, after reading its code and the rust documentation. I'm kinda split between using the unstable features or not. I would love the confirmation from the core maintainer.</p>
If we were to use the unstable lazy_cell</code>, we can just use the initialization, which is more ergonomic, removing helper methods, which could prove tricky for the statics on the build.rs file: INTERNED_SYMBOLS</a></p>
writeln!</span>(
</span>    f,
</span>    </span>"
</span>use std::sync::LazyLock;
</span>pub(crate) static INTERNED_SYMBOLS: LazyLock<Mutex<ObjectMap>> = LazyLock::new(|| Mutex::new({{
</span>    let size: usize = </span>{symbol_len}</span>;
</span>    let mut map = SymbolMap::with_capacity(size);
</span>    sym::init_symbols(&mut map);
</span>    ObjectMap {{
</span>        map,
</span>        block: Block::new_global(),
</span>    }}
</span>}}));
</span>"
</span></code></pre>
With LazyLock</code>, the callers wouldn't have to call get</code> on the OnceLock, and instead use the methods of the content directly, since by nature, they can assume it has been initialized</strong>. </p>
I was pretty happy with the simplification, since it removes the forced initialization + comment on the main.rs file</a> and removes the lazy_static dependency from the code base</strong>:</p>
 float-cmp = "0.9.0"
</span> fn_macros = { version = "0.1.0", path = "fn_macros" }
</span> hostname = "0.3.1"
</span>-lazy_static = "1.4.0"
</span> memoffset = "0.8.0"
</span> num_enum = "0.5.11"
</span> paste = "1.0.12"
</span></code></pre>


Open or Raise Emacs
2022-04-17T00:00:00+00:00
I use Keyboard maestro</a> to Activate the applications I use the most, with the intention of reducing hand movement I endure every day. In my normal developing workflow, I would start working with Emacs to do my first Inbox Review, I would then open up the browser to search for anything while developing and I would then want to go back to Emacs to keep developing. Everything works with a keypress and following mnemonics</a> to make the keys easier to remember.</p>
The latter is the part that I have been interested in improving. I use the Emacs client-server approach to have a fast running Emacs instance at all times. If I would want to close Emacs, I would be back to an open instance instantly.</p>
The problem with Emacs is that having the server running, we can't use the application condition with Keyboard maestro, since we already have an open application, even if it's running in the background.</p>
The idea is then run an Apple script as the condition to check whether the Emacs process is running (and not the Emacs window) to launch the Emacs client, or only activate the window that is already there. To do so, I would want to use an Apple Script to grep for the background process.</p>
Here is the script that I use as condition:</p>
tell </span>application </span>"System Events"
</span>    </span>set </span>emacsWindowsCount </span>to </span>count </span>of</span> window </span>1 </span>of </span>(processes </span>whose </span>name </span>is </span>"Emacs"</span>)
</span>    </span>if</span> emacsWindowsCount </span>is </span>0 </span>then
</span>        </span>error number </span>-1
</span>    </span>end if
</span>end tell
</span></code></pre>
And here is the Keyboard maestro macro I ended up with. The LauchEmacsClient is an application that I created with Automator to just call the emacsclient</code> binary with the buffer I want to start with.</p>
</p>
If anyone is interested in the .kmmacros</code> file, ping me on email</a>.</p>


Diving deep into Sequelize
2021-05-25T00:00:00+00:00
Introduction</h2>
In this post we will go deep into the SQL ORM world, highlighting some of the strong points for Sequelize. I find that everyone could find this post interesting, specially if you have heard of the "new" ES6 features. Sequelize is a great option for SQL database management. Let's get started!</p>
What is Sequelize?</h2>
Per the Sequelize website</a>:</p>

Sequelize is a promise-based Node.js ORM for Postgres, MySQL, MariaDB, SQLite and Microsoft SQL Server. It features solid transaction support, relations, eager and lazy loading, read replication and more.</p>
</blockquote>
But what does it really mean? What does the average Joe (The software engineer Joe, nevertheless) has to know about Sequelize?</p>
In my book, Sequelize is one of the most popular Node.js</a> ORMs (Object Relational Mapper)</a>, which provides extensive functionality to connect and work with relational databases, namely PostgreSQL, MySQL, MariaDB and more. One of the strong points of Sequelize is that the whole implementation hovers around Promises</a> which —as you know, we're all ES6 developers, aren't we?— provide asynchronous support. In this case, to database transitions, which is really interesting.</p>
Even though I will be talking about Promises more in depth in the following paragraphs, let's see a practical example: Image you are working on a web for your company, and you are tasked to connect to a database and perform some long and heavy transactions, all when the user presses a button. One option would be to keep the user waiting for the database to finish its transactions (this is not the way I would go about it) and the better option is to do all the database work asynchronously, using Promises!</p>
You can find about setting up Sequelize with your database —the right way— in the Set up Sequelize in a Node.js project section.</p>
Promises</h2>
Most of the methods provided by Sequelize are asynchronous and therefore return Promises. But what are Promises anyway?</p>
According to the JavaScript documentation</a>:</p>

A Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future.</p>
</blockquote>
The practical definition is that we are able to control when and in what situation wait for the result of asynchronous operations, and act accordingly to them. As I mentioned in the example before</a>, our developer friend would most likely want to wait for the database to finish if the next redirect is to the page where the information is updated. But let's imagine the case that the user is redirected to another page that doesn't really need to have the information updated. In that case we would benefit from doing work asynchronously, avoiding the wait; Pretty cool, huh?</p>
There are several operations that we can apply to Promises, in order to control the state</a> of the information they are processing. A Promise will initially be pending</code>, but then it can either go to fulfilled</code> —if the operation hasn't ended in error— or to rejected</code>, meaning the operation has failed.</p>
Let's assume we define the following Promise from the getAllProducts</code> operation, which applies a series of filters to the list of products of the user:</p>
// We can also create Promises with the constructor: new Promise(function)
</span>let </span>productList </span>= </span>getAllProducts</span>(</span>idUser</span>, </span>filters</span>)
</span></code></pre>
If we were to print the productList</code> variable out (via console.log</code>), we would likely get "Promise{  }", representing that the Promise is in the pending</code> state —it hasn't finished the operation.</p>
The three common Promise operations —which we will use more extensively in Sequelize— are:</p>
then()</code></h2>
The then()</code> function is used when we want to run some function when the Promise has resolved. In this case, if we wanted to print the list of products, we would write:</p>
// We could also omit the function body, as it's only one line.
</span>productList.</span>then</span>(</span>promiseResult </span>=> </span>{
</span>  </span>console</span>.</span>log</span>(</span>promiseResult</span>)
</span>})
</span></code></pre>
As we see in the snippet, we get the result of the operation as a parameter to the inside function, which we can then use in the body of the function.</p>
catch()</code></h2>
The catch()</code> function is used to literally "Catch" a possible error in the operation. Let's assume we are throwing an error in the getAllProducts</code> function if the user (symbolized with idUser</code>) doesn't exist. We can then catch the error in the result of the Promise:</p>
productList.</span>catch</span>(</span>error </span>=> </span>console</span>.</span>log</span>(</span>error</span>))
</span>
</span>// This could be: ERROR> The user doesn't exist! 
</span></code></pre>
finally()</code></h2>
The finally()</code> function is used to run a certain code whether the Promise resulted in a success or an error. It might remind you of the try-catch-finally structure, and it has been inspired in that. Let's redirect the user —with a populated or empty list— to the search page.</p>
// Let's assume we have the response variable ('res') declared before.
</span>productList.</span>then</span>(
</span>  </span>promiseResult </span>=> </span>{
</span>    </span>console</span>.</span>log</span>(</span>promiseResult</span>)
</span>    </span>return </span>promiseResult
</span>  })</span>.</span>catch</span>(
</span>    </span>err </span>=> </span>console</span>.</span>log</span>(</span>err</span>))</span>.</span>finally</span>(
</span>      </span>productList </span>=> </span>res.</span>redirect</span>(</span>'search'</span>, { productList: </span>productList</span>}))
</span></code></pre>
This has also been an excellent example of Promise chaining, which is the passing of the callback outputs from one function to the next. The catch</code> function catches all errors until that point, so it's common to use several then</code> functions that then a catch</code> one.</p>
⚠️ NOTE: We are returning the promiseResult</code> in the then</code> function to get the argument for the finally</code> call. If we didn't do that, JavaScript wouldn't complain, but the productList</code> variable would be 'undefined'.</p>
Instances vs Models</h2>
When you are starting to get in the Sequelize mood, it is crucial to differentiate Instances</a> and Models</a>.</p>
Model</h3>
For cohesion, let's start with Models. Models</code> are exactly what you would expect in relational databases. They represent an abstraction of an entity in your application's domain</code>, from which you need to store information. It is also commonly known as Table</code> —Sequelize handles all the Table creation for you when the model is defined</code>.</p>
Models can be defined in two equivalent ways</a> in Sequelize, from which I will only discuss the one that I find more convenient, no need to get into Sintax Hell when we have ready-to-go shortcut functions. I find that the easier is to use the define</code> function, which is defined as:</p>
sequelize.</span>define</span>(</span>modelName</span>, </span>attributes</span>, </span>options</span>) </span>// This sequelize object is an instance of the Sequelize class.
</span></code></pre>
Going back to the product example, let's define the Product Model.</p>
const </span>Product </span>= </span>sequelize.</span>define</span>(</span>'Product'</span>, {
</span>  idProduct: {
</span>    type: </span>DataTypes</span>.</span>INTEGER</span>,
</span>    allowNull: </span>false</span>,
</span>    primaryKey: </span>true</span>,
</span>    autoIncrement: </span>true</span>,
</span>  },
</span>  name: {
</span>    type: </span>DataTypes</span>.</span>STRING</span>,
</span>    allowNull: </span>false</span>,
</span>  },
</span>  price: {
</span>    type: </span>DataTypes</span>.</span>DOUBLE</span>,
</span>    allowNull: </span>false</span>,
</span>  },
</span>  idUser: {
</span>    type: </span>DataTypes</span>.</span>INTEGER</span>,
</span>    references: {
</span>      model: </span>User</span>,
</span>      key: </span>'idUser'</span>,
</span>    }
</span>  }
</span>})
</span></code></pre>
It could be more complex than the previous snippet, but I find that the Product model we defined has all the information I need for the explanation. As we know, every Table should have its primaryKey</code>, which then will be used to identify a particular row in the Table.</p>
⚠️ We set the autoIncrement</code> property to true</code>, in order to have ids automatically created for us.</p>
The other Product property that I wanted to mention is the idUser. You might be thinking, why are Users mixed up in all of this. Let me introduce you to the Foreign Key</a>, my friend. The idUser property has the references property, creating a "link" to the idUser</code> key —represented with the key</code> property— of the User</code> model.</p>
If you want to dig more into the possible attributes for Model definition Sequelize offers, see:</p>

https://sequelize.org/master/class/lib/model.js~Model.html#static-method-init</a></li>
https://sequelize.org/master/class/lib/model.js~Model.html</a></li>
https://sequelize.org/master/class/lib/sequelize.js~Sequelize.html#instance-method-define</a></li>
</ul>
Instance</h2>
Citing the Sequelize documentation:</p>

As you already know, a model is an ES6 class. An instance of the class represents one object from that model (which maps to one row of the table in the database). This way, model instances are DAOs.</p>
</blockquote>
Although a Model is a class, you cannot create instances using the default constructor —via new</code> — but using special creation and building functions. In this case, even though we have a shortcut to the creation of Instances, I find interesting showing the "long" way of creating them.</p>
const </span>createProduct </span>= </span>async </span>() </span>=> </span>{
</span>  </span>const </span>product </span>= </span>Product.</span>build</span>({ name: </span>"Headphones" </span>})
</span>  </span>console</span>.</span>log</span>(</span>product</span>.</span>name</span>) </span>// "Headphones"
</span>  </span>await </span>product.</span>save</span>()
</span>}
</span></code></pre>
From the snippet we can get gold information out of the build method. You might be thinking to yourself: we are assigning a Promise</code> to a constant, and then accessing its attribute. Enrique, your code is wrong.</p>
Mysteriously, the build function is one of the few methods in Sequelize that are not asynchronous, hence we are not assigning a Promise, but a Product</code> Instance. Note the save function on the instance —asynchronous. The build function does not insert the new "row" into the Product(s) Table. We need to explicitly save the instance using the save</code> function.</p>
Pretty cool, huh? Sequelize provides a shortcut for the combined operations: create</code>. The create</code> is an asynchronous function, which uses the same parameters as the build</code> method, but saving the instance in the database in the process. See:</p>
const </span>product </span>= </span>await </span>Product.</span>create</span>(
</span>  {
</span>    name: </span>"Headphones"</span>,
</span>    price: </span>120</span>,
</span>  }
</span>)</span>.</span>catch</span>(</span>err </span>=> </span>console</span>.</span>log</span>(</span>err</span>))
</span>console</span>.</span>log</span>(</span>product</span>.</span>name</span>) </span>// "Headphones"
</span></code></pre>
Note the catch function applied to the Promise to output any possible creation or insertion errors, as discussed in the Promises</a> section. After the create operation, the product</code> instance is inserted in the database.</p>
⚠️ If you want to log the product instance, use the toJSON()</code> function, as the default toString</code> is pretty terrifying, printing all the internals.</p>
Query the database</h2>
Why would we want to store information in a database if not to use it later on? Querying in sequelize couldn't be easier, both through raw queries —not here to judge— or Finder methods.</p>
Raw queries</h3>
Just for you hermits out there, let's start with Raw queries. We are working
with SQL databases anyway, right?  You can raw query the database through the
sequelize.query method. From the Sequelize documentation</a>:</p>

By default the function will return two arguments - a results array, and an object containing metadata (such as amount of affected rows, etc). Note that since this is a raw query, the metadata are dialect specific. Some dialects return the metadata "within" the results object (as properties on an array). </p>
</blockquote>
⚠️ If you are using MSSQL or MySQL, the two return variables will be the same object.</p>
Here is an update for our Product example.</p>
const </span>[</span>results</span>, </span>metadata</span>] </span>= </span>await </span>sequelize.</span>query</span>(</span>"UPDATE Product SET price = 42 WHERE idProduct = 1"</span>);
</span>// Results will be an empty array and metadata will contain the number of affected rows.
</span></code></pre>
Note that the even if we inserted the Product —singular— Model in the database, Sequelize creates both tables: Product and Products. Query away with your preference.</p>
There are special cases where you don't need change access to the database, just the data, i.e. through a SELECT query. You can then import the QueryType metadata.</p>
const </span>{ </span>QueryTypes </span>} </span>= </span>require</span>(</span>'sequelize'</span>);
</span>const </span>products </span>= </span>await </span>sequelize.</span>query</span>(</span>"SELECT * FROM `Products`"</span>, { type: </span>QueryTypes</span>.</span>SELECT </span>});
</span></code></pre>
Passing the QueryType Metadata, the function no longer needs to return two return variables, but the SELECT query's affected rows. If you wouldn't mind, let's go back to abstraction, where I fill a bit more comfortable. Sequelize defines shortcut functions to query the database(s).</p>
Finder methods</h2>
By default, the finder methods return Instances. We can then use those instances to get information, as if we were accessing an ES6 class. Here are the finder functions:</p>

findAll()</code>: returns an array of Instances for the Model that has been queried:</li>
</ul>
const </span>productList </span>= </span>await </span>Product.</span>findAll</span>();
</span></code></pre>

findByPk()</code>: returns an instance by passing the Primary Key as argument. In our case, the idProduct</code>.</li>
</ul>
const </span>idProduct </span>= </span>1
</span>const </span>product </span>= </span>await </span>Product.</span>findByPk</span>(</span>idProduct</span>);
</span>console</span>.</span>log</span>(</span>product</span>.</span>price</span>) </span>// 42, after the UPDATE.
</span></code></pre>

findOne()</code>: the method returns the first instance matching the options passed. As with all Sequelize methods —I really value the consistency— the format of the options is through objects.</li>
</ul>
const </span>product </span>= </span>await </span>Product.</span>findOne</span>({ where: { price: </span>42 </span>} });
</span>// This product constant is the same for the findByPk method.
</span></code></pre>
Although there are others, I find that the ones mentioned are the most important. If you still have the curiosity, see:</p>

https://sequelize.org/master/manual/model-querying-finders.html</a></li>
https://sequelize.org/master/manual/model-querying-basics.html</a></li>
https://sequelize.org/master/manual/getters-setters-virtuals.html</a></li>
</ul>
⚠️ For querying Operators are specially interesting, you can access all the operators you expect: and</code>, or</code>, eq</code>, between</code>, like</code> and more. Check: Operators</a>.</p>
Minimize transactions</h2>
When working with databases and specially with a ton of requests to it, it is key to have the mindset of reducing as much database transactions as possible. What do I mean by that?</p>
Instead of having multiple database requests to get and update some information, try to think of an SQL query</a> (remember that you can use both raw and Sequelize methods) to do the job in a single transaction if possible. A nice example of this is the Update functionality by Sequelize.</p>
Sequelize provides several ways of updating instances. The first one —bear with me here— is getting a certain instance, modify the properties you want to update and then save the instance back to the database. For our Product example, let's make it cheaper. With the sequelize methods discussed before, we would achieve that using:</p>
const </span>idProduct </span>= </span>1
</span>const </span>productInstance </span>= </span>Product.</span>getByPk</span>(</span>idProduct</span>)
</span>productInstance</span>.</span>price </span>= </span>12 </span>// It was 42 before.
</span>await </span>product.</span>save</span>()
</span></code></pre>
The previous sequence of operations creates two SQL requests, the first SELECT to get the product by id, and then a second one to update the value —when the instance is saved through the save()</code> method). That is the essence of what I mean, instead of being happy with the previous snippet, let's think further.</p>
We know that Sequelize provides an Update method</a> to update multiple instances that match the were</code> options. Here would be the snippet for the second option.</p>
const </span>idProduct </span>= </span>1
</span>const </span>[</span>numAffectedRows</span>, </span>product</span>] </span>= </span>Product.</span>update</span>({
</span>  where: {
</span>    idProduct: </span>1
</span> }})
</span></code></pre>
That snippet only produces an UPDATE query, using the WHERE clause to limit the target rows. As you see, you get the number of affected rows as the first deconstructing argument, and the actual affected rows in the second. No need to save the database afterwards, pretty cool, huh?</p>
Set up Sequelize in a Node.js project</h2>
On this section I intend to give you a working Sequelize configuration, done the efficient way. There are multiple ways to use Sequelize in your Node.js project, but I'm sure you will agree with me that there is no need to redefine the Sequelize connection every time you want to access the database.</p>
Instead, we should strive towards having a reusable and maintainable configuration, benefiting from having code that would work well with several DBs —let's image you intend to change from MySQL to PostgreSQL.</p>
I need to give credit where credit is due: I got this information for one of my projects from bezkoder's</a> blog post, which I highly recommend for a more profound dive on the setup part of Sequelize. Let's get started.</p>
First, Sequelize requires a series of arguments to set up the connection to the database. I recommend defining a db.config.js</code> file, where you will insert the constants required for the connection.</p>
module</span>.</span>exports </span>= </span>{
</span>  HOST: </span>'localhost'</span>,
</span>  DB: </span>'bualatok'</span>,
</span>  USER: </span>'root'</span>,
</span>  PASSWORD: </span>process</span>.</span>env</span>.</span>DB_PASSWORD</span>,
</span>  dialect: </span>'mysql'</span>,
</span>  pool: {
</span>    max: </span>5</span>,
</span>    min: </span>0</span>,
</span>    acquire: </span>30000</span>,
</span>    idle: </span>10000
</span>  },
</span>}
</span></code></pre>
As you can see in the snippet below, you need to setup the IP of the server
you are connecting to —through the HOST</code> property. The interesting part is
that you could either have your own server (i.e MySQL server) or connect to
one elsewhere. The DB</code> property is the name of the database you will be
connecting to. The USER</code> and PASSWORD</code> are pretty self-explanatory, but note
the use of the dotenv package</a>, which provides easy to use environment variables, that you will then .gitignore. The dialect</code> property is picked from a set list, you can find it here</a>.</p>
The pool</code> property is interesting enough to comment on it alone: Sequelize —and databases in general— uses the word "pool"</a>, as a "set" of connections to the database, which can then be used in parallel. We set up a pool of connections to limit the access to the db but still consider the possibility of having multiple "users" creating transactions at the same time.</p>
After having the db.config setup, we need to create the file which will be then imported throughout the application to access the database efficiently. We can even reduce the exports to our liking, or need. Here is the index.js</code> file in the /models</code> directory:</p>
const </span>dbConfig </span>= </span>require</span>(</span>"../config/db.config.js"</span>)
</span>
</span>const </span>{ </span>Sequelize</span>, </span>Op</span>, </span>DataTypes </span>} </span>= </span>require</span>(</span>"sequelize"</span>)
</span>const </span>sequelize </span>= </span>new </span>Sequelize</span>(</span>dbConfig</span>.</span>DB</span>, </span>dbConfig</span>.</span>USER</span>, </span>dbConfig</span>.</span>PASSWORD</span>, {
</span>  host: </span>dbConfig</span>.</span>HOST</span>,
</span>  dialect: </span>dbConfig</span>.</span>dialect</span>,
</span>  operatorsAliases: </span>false</span>,
</span>
</span>  pool: {
</span>    max: </span>dbConfig</span>.</span>pool</span>.</span>max</span>,
</span>    min: </span>dbConfig</span>.</span>pool</span>.</span>min</span>,
</span>    acquire: </span>dbConfig</span>.</span>pool</span>.</span>acquire</span>,
</span>    idle: </span>dbConfig</span>.</span>pool</span>.</span>idle
</span>  }
</span>})
</span>
</span>const </span>db </span>= </span>{}
</span>
</span>db</span>.</span>DataTypes </span>= </span>DataTypes
</span>db</span>.</span>Sequelize </span>= </span>Sequelize
</span>db</span>.</span>sequelize </span>= </span>sequelize
</span>db</span>.</span>Op </span>= </span>Op
</span>
</span>db</span>.</span>User </span>= </span>require</span>(</span>"./user.model.js"</span>)(</span>sequelize</span>, </span>DataTypes</span>)
</span>db</span>.</span>Product </span>= </span>require</span>(</span>"./product.model.js"</span>)(</span>sequelize</span>, </span>DataTypes</span>, </span>db</span>.</span>User</span>)
</span>
</span>module</span>.</span>exports </span>= </span>db
</span></code></pre>
Using the previous file, we are able to only require the needed aspects from "sequelize" and configure the database connection pool using the new Sequelize(...)</code> constructor —note that it uses the dbConfig object defined in the previous snippet. We are able to concentrate everything related to the database, even the User</code> and Product</code> models and import from that single file.</p>
I find this process the more efficient way to set up Sequelize in a Node.js project, and I would recommend starting with those configuration files.</p>
Should you use Sequelize?</h2>
After all the Sequelize talk, I figure you are thinking whether Sequelize is for you, your project, your team or your own use. This section tries to answer the previous question using pros and cons, and leaves you to the final answer.</p>
PROS:</p>

Sequelize provides a layer of abstraction, reducing the possible errors that developers can include in Raw SQL queries.</li>
Sequelize is multi-dialect, providing support for the use-case of having multiple databases with different providers at the same time —weird but OK.</li>
Using an ORM —Sequelize in this case— speeds up the development process for simple, repetitive queries.</li>
If you are concerned about security, ORMs will shield your application from injection attacks, since the framework will filter the requests for you.</li>
Sequelize "forces" you to create a maintainable database, that is independent of the database provider you use in that moment, making the switching process seemless.</li>
</ul>
CONS:</p>

If you are trying to pick an ORM to avoid learning SQL, you will be rendered out alone when the ORM goes out of the window. Understand the SQL sintax underneath the ORM's calls.</li>
Complex calls in ORMs are usually inefficient. If your queries are not simple or repetitive, you are better off using Raw Queries.</li>
Sequelize doens't have a perfect documentation, finding the information you need might be trivial or not.</li>
Learning a new ORM might tie you to a different and new sintax.</li>
</ul>
The Pros and Cons list that everyone was waiting for. If after the list you find that you are getting more and more curious about using Sequelize, go on! As you might know:</p>

By experimenting with voluntary discomfort, we  learn to appreciate far more of our life, and can be content with a much simpler and more wholesome one.</p>
</blockquote>
I intend to keep myself learning every day, and learning additional technologies is always exciting!</p>
Final conclusions</h2>
And there you have it folks, this brief Sequelize introduction is over. I really hope this post has inspired you in some way, to either try Sequelize or keep in mind it exists. I find Sequelize —and ORMs in general— to be the next generation of database transaction processing. If you have any questions or wanna chat with me, hit me up by email</a> or on twitter</a>.</p>
Advanced topics</h2>
Now that you have been given the seed of curiosity with Sequelize, I find that learning more is just about finding the right information. Below I provide a list of advanced topics that you might enjoy reading about if you are really taking serious using Sequelize for your project.</p>

Dialect specific configuration</a></li>
Hooks</a></li>
Constraints</a></li>
Using legacy tables</a></li>
Migrate your current project</a></li>
Using Typescript with Sequelize</a></li>
Caching information with Sequelize</a></li>
Sequelize temporal records</a></li>
Role, Permission based Auth with Sequelize</a></li>
Visual definition of Sequelize models</a></li>
</ul>

enriquekesslerm.com

Publish your cargo docs

Setting up the Rune project for success

Potential improvements</h2> cargo-hack</h3> cargo-hack</code> checks combinations of feature flags to ensure that features are all additive which is required for feature unification.</p> </blockquote>

cargo-hack</h3> cargo-hack</code> checks combinations of feature flags to ensure that features are all additive which is required for feature unification.</p> </blockquote>

loom</h3> Loom is a testing tool for concurrent Rust code. It runs a test many times, permuting the possible concurrent executions of that test under the C11 memory model. It uses state reduction techniques to avoid combinatorial explosion.</p> </blockquote>

codecov.io</h3> Enhance Your Testing the Codecov Way: Codecov is the all-in-one code coverage reporting solution for any test suite — giving developers actionable insights to deploy reliable code with confidence.</p> </blockquote>

Bye lazy_static, Welcome once_cell!

Open or Raise Emacs

Diving deep into Sequelize