knowledge base: libraries

[hex13]

internal (own solutions)

vifi - virtual filesystem, core library which provides useful abstraction and allows for using object based approach for manipulating files.

external (third party)

CodeMirror - used as editor widget and for syntax highlighting search results

Git-utils - npmjs.com/package/git-utils "A package for using Git repositories." May throw error "Module version mismatch.". It's something related to native modules in NodeJS. Look into https://github.com/electron/electron/issues/7557 ( ./node_modules/.bin/electron-rebuild --version=HERE_WRITE_ELECTRON_VERSION )

React - library that was used previously for making GUI. I dropped it because of debugging/optimization problems.

Vue - library used currently for making GUI (but I'm rewriting GUI to Snabbdom right now). It seems to have more flexible component system than react.

Snabbdom - virtual DOM library, can be used instead of React, Vue etc. but you operate on lower level of abstraction (which can be good, it allows for more control and seems more predictable - less magic - better debugging. At least I hope. I've just started playing with Snabbdom so I don't really know its cons, yet.

virtual-dom - library similar to snabbdom, has similar API but a little bit different (in snabbdom patch does 3 things: initialize element, makes diffs and patches. In virtual-dom these three things are divided: createElement for initializing, diff for diff and patch for patch. So it seems more SRP.

ESLint - not only linter, but it's possible to get parsed AST from it, and even scope information (because ESLint uses EScope).

EScope - analyzes JS files and return hierarchical scopes and information about all references of given variable etc. This information can be used for simple autocompletion, basic go to definition, renaming etc.

I wrote "simple" and "basic" because there are situations where EScope is not providing sufficient info. This is why I've already started writing my own library for this kind of things (I also tried once using Tern, but without greater success).

I also consider using Babel (instead of using Tern, EScope or homegrown solution) because Babel also does some static analysis.

glob "Match files using the patterns the shell uses, like stars and stuff." unfortunately can be very slow

Others (not used): Ace browserify compatible version of the ace editor. https://www.npmjs.com/package/brace

[hex13]

Estraverse - library for traversing AST (alternatives: recast, babel-traverse).

when you use it with some other AST (for example from Babylon) you have to add something like this:

 fallback: 'iteration',

to the visitor (e.g. https://github.com/hex13/enter-ghost/blob/0baef1022cbf5d569a73cdd78b04395f12c87d93/packages/power-scope/old/traverse.js#L102 )

Read more on : https://github.com/estools/estraverse/issues/32 https://github.com/estools/estraverse/issues/67

[hex13]

markdown libraries:

markdown-it: https://www.npmjs.com/package/markdown-it

• renders markdown to HTML
• it allows for customize code snippets ```my-language bla bla ``` - you can transform what will display inside (unfortunately it doesn't allow for complete replacement of such block).
• parses markdown to token list (unfortunately tokens describes HTML elements, not Markdown)

[hex13]

Winston - logging library for NodeJS, unfortunately it does not support browser environment.

[hex13]

rich editors:

ProseMirror: couldn't make it work properly, look: https://github.com/ProseMirror/prosemirror/issues/664

Quill

• [x] I've embedded this in Electron
• [x] I've created custom widget (they are called blots in Quill
• [x] I've embedded CodeMirror in this custom widget
• [ ] I wanted to bind Ctrl+Enter for action "insert my custom widget", but I had problem with event handling for enter key. It wasn't triggered,
• [x] so I've bound this to Ctrl+J
• [x] workaround for images on local file system was needed. I've created custom blot, but there is also other solution: https://github.com/quilljs/quill/issues/895
• [x] it allows for easy serialization and deserialization. For custom widgets you just write code in create and value methods, which serialize/deserialize.
• [x] I've managed to write it to JSON, close program, and load contents this from *.json file on start.
• [ ] implementing finding on Electron

[hex13]

Why not assert?

assert (from NodeJS standard library). It' simple you don't have to install anything else, it's always there (if you're using Node). I made transition once from chai despite the warnings on NodeJS docs:

The module is intended for internal use by Node.js, but can be used in application code via require('assert'). However, assert is not a testing framework, and is not intended to be used as a general purpose assertion library.

https://nodejs.org/dist/v5.10.0/docs/api/assert.html (it's from old version of Node because now they took off these warnings)

So why not assert?

it's easy to create passing assertion even if it should not pass. by default equal is loose (==)

assert.equal(2, ['2']) // it doesn't throw!

you can avoid this using strictEqual

assert.strictEqual(2, ['2']) // error, like it should be

But this is too verbose so most of people (from what I've seen) uses equal anyway and risk bugs. Readability counts.

If you're comparing in deep equal mode you're also risk bugs:

assert.deepEqual({}, []) // it doesn't throw

so in most cases you would probably want to use deepStrictEqual

assert.deepStrictEqual({}, []) // error, like it should be

but it looks ridiculous and most of people uses loose version anyway (assert.deepEqual: 609,183 results when searching JS code on Github, assert.deepStrictEqual 34,266). And this means that if people on your team use assert, they probably make this in a loose way. So it's safer to just not to use assert whatsoever and use something which is more stricter by default.

And assert was not really meant for general purpose use. https://github.com/nodejs/node/issues/5312

So now what? I will return to chai.expect. It has strict equality by default and has some other features missing in assert (like keys). Besides it allows for more readable error messages

assert

> assert({} instanceof Date)
> AssertionError: false == true

false == true? WTF?

chai

> expect({}).instanceOf(Date)
> AssertionError: expected {} to be an instance of Date

Besides mocha has nice diffs for Chai

EDIT: actually I used old version of mocha (installed globally), when I started to use local version of mocha (newer) even assert has nice diffs.

expect({
     animal: 'cat', color: 'black'
}).deep.equal({
    animal: 'dog', color: 'black'
})

AssertionError: expected { animal: 'cat', color: 'black' } to deeply equal { animal: 'dog', color: 'black' }
    + expected - actual

     {
    +  "animal": "dog"
    -  "animal": "cat"
       "color": "black"
     }

inb4: I know, I'm not cool, I still use old solutions (Mocha + Chai) instead of Ava, Jest, Tape, Enzyme or whatever is now in fashion.

and despite the things I wrote I would probably use assert for once in a while because I don't like adding dependencies to projects. But assert feels a little bit inferior as a solution.

[hex13]

link to discussion on Reddit: https://www.reddit.com/r/javascript/comments/6l09qz/why_not_assert/ (don't comment here)

[hex13]

Google Maps API

• [x] it works on localhost
• [x] it works offline (plain *.html file open from disk, without server)
• [x] it allows easily for creating markers
• [x] markers has mouse events
• [x] markers can have custom images as icons (instead of default one)

[hex13]

CodeMirror tip: to fix issues with trimming letters:

call cm.refresh() (with some delay, e.g. after timeout):

[hex13]

CodeMirror: I had issues with vertical scrolling (it jumped back after scrolling). First I thought this was a bug in CM, but then I saw that I introduced these problems myself. I had such declaration in my styles:

* {
    transition: 0.2s all;
}

it was for enabling CSS transitions by default in the rest of my app (I wanted to have cool transitions). It was problematic, because unfortunate * selector caught also CodeMirror and caused it to behave weirdly. So: I removed this CSS declaration and scrolling problems were solved.

[hex13]

CodeMirror performance problems with using large marks (created by markText), when CSS animation and gradient background is used (in Chrome - it seems to be CSS/browser related thing, browser just renders it too slowly. I don't blame CodeMirror for that, CSS animations can slow down Chrome overally).

.scope {
    animation: 0.5s ease-in-out infinite  scope;
}

@keyframes scope {
    0% {
        background: repeating-linear-gradient(to bottom, rgba(0,0,0,0.4) 1px, rgba(0,0,200,0.4) 3px) 0 10px;
    }
    100% {
        background: repeating-linear-gradient(to bottom,rgba(0,0,0,0.4) 1px, rgba(0,0,200,0.4) 3px) 0 3px;
    }
}

I've removed this animation from marks that are supposed to be large (in small marks this is not such a pain).