📦 Codsen 📦

A lerna monorepo for our 82 npm libraries

💡 Table of Contents

#%EF%B8%8F-17-miscellaneous-libraries

• Flagship Libraries
• Range Libraries
• String Processing Libraries
• Object Processing Libraries
• CLI Apps
• Miscellaneous Libraries
• Contributing
• Licence

🚢 Flagship Libraries

Library's name	Purpose	Web app	npm_link	Source code in monorepo
email-comb	Remove unused CSS from email templates	emailcomb.com		packages/email-comb
html-crush	Minifies HTML/CSS: valid or broken, pure or mixed with other languages	htmlcrush.com		packages/html-crush

There are quite a few small libraries, so let's group them by a common purpose.

🎯 11 Range Libraries

Range means an array of two text character index numbers, "from" and "to" (plus optional third element, string, which marks "what to add").

For example, "from the third character to the fourth character" could be marked with array [3, 4].

There can be a third element in a range array, what to add instead of the range. For example, [10, 12, "add this"]. When there is no third element in the range array, like [10, 12], that would mean "delete from index 10 to index 12". Empty third element is the same as if it was missing.

For example, a range [1, 3] in a string "abcdef" would mean bc because "b" is at index number 1 (counting starts at zero) and 3rd is "d". The beginning of the range is inclusive, and the ending is not. Hence, the result "bc".

Another example, if you want to replace "{placeholder}" with "John" in a string "Hi {placeholder}!"^, the range would be [3, 16, "John"].

Now, if you have many ranges, you put them into an array. You get an array of ranges. Majority of range- libraries process such arrays of ranges: sort bunch of ranges, fix overlapping ranges and so on.

Practically, we need ranges when we process strings and want to "keep a note" of what needs to be deleted or replaced later. The idea is, instead of processing the string many times:

"find out what needs to be done with a string" ->
"mutate the string" ->
"find out what more needs to be done with a string" ->
"mutate the mutated string" ->
... and so on,

We only "compile a to-do list" — push the ranges into an array. When we finish gathering them, we do all the actions in one go.

Performing string processing only once is better for both performance reasons (fewer actions = faster) and for consistency (in-between taking the notes, we operate on the original string instead of its previously mutated version).

If you think, strings are immutable in JavaScript — each change of a string means rewriting it in a computer memory. Let's say you want to add a letter and delete the same letter in a string which consists of a thousand characters. Both actions cancel each other out. However, if you do the string edits sequentially, you write a thousand characters to memory two times, after every amend. On the other hand, if you use ranges approach, you'd only create a new record in the computer memory, housing a couple of arrays, each consisting of couple index numbers. When you process the ranges, they would cancel each other out, and we would not write anything to the memory at all. Now, if you scale this — longer strings, more amends, and done many times — you'll soon feel the difference in performance.

Library's name	Purpose	npm_link	Source code in monorepo
ranges-push	Manage the array of slices referencing the index ranges within the string		packages/ranges-push
ranges-apply	Take an array of string slice ranges, delete/replace the string according to them		packages/ranges-apply
ranges-merge	Merge and sort arrays which mean string slice ranges		packages/ranges-merge
ranges-sort	Sort natural number index ranges [ [5, 6], [1, 3] ] => [ [1, 3], [5, 6] ]		packages/ranges-sort
string-range-expander	Expands string index ranges within whitespace boundaries until letters are met		packages/string-range-expander
ranges-crop	Crop array of ranges when they go beyond the reference string's length		packages/ranges-crop
ranges-ent-decode	Decode HTML entities recursively, get string index ranges of what needs to be replaced where		packages/ranges-ent-decode
ranges-invert	Invert string index ranges [ [1, 3] ] => [ [0, 1], [3, ...] ]		packages/ranges-invert
ranges-is-index-within	Efficiently checks if index is within any of the given ranges		packages/ranges-is-index-within
ranges-process-outside	Iterate through string and optionally a given ranges as if they were one		packages/ranges-process-outside
ranges-regex	Perform a regex search on string and get a ranges array of findings (or null)		packages/ranges-regex

🎻 25 String Processing Libraries

They process string inputs, which might be text, code or something else as long as it is of a string type.

Library's name	Purpose	npm_link	Source code in monorepo
string-strip-html	Strips HTML tags from strings. Detects legit unencoded brackets.		packages/string-strip-html
easy-replace	Replace strings with optional lookarounds, but without regexes		packages/easy-replace
str-indexes-of-plus	Search for a string in another string. Get array of indexes. Full Unicode support.		packages/str-indexes-of-plus
bitbucket-slug	Generate BitBucket readme header anchor slug URLs. Unofficial, covers whole ASCII and a bit beyond.		packages/bitbucket-slug
detect-is-it-html-or-xhtml	Answers, is the string input string more an HTML or XHTML (or neither)		packages/detect-is-it-html-or-xhtml
email-all-chars-within-ascii	Scans all characters within a string and checks are they within ASCII range		packages/email-all-chars-within-ascii
html-table-patcher	Wraps any content between TR/TD tags in additional rows/columns to appear in browser correctly		packages/html-table-patcher
js-row-num	Update all row numbers in all console.logs in JS code		packages/js-row-num
csv-sort	Sorts double-entry bookkeeping CSV coming from internet banking		packages/csv-sort
csv-sort-cli	Command line app to sort double-entry CSVs coming from internet banking statements		packages/csv-sort-cli
csv-split-easy	Splits the CSV string into array of arrays, each representing a row of columns		packages/csv-split-easy
string-character-is-astral-surrogate	Tells, is given character a part of astral character, specifically, a high and low surrogate		packages/string-character-is-astral-surrogate
string-collapse-leading-whitespace	Collapse the leading and trailing whitespace of a string		packages/string-collapse-leading-whitespace
string-collapse-white-space	Efficient collapsing of white space with optional outer- and/or line-trimming and HTML tag recognition		packages/string-collapse-white-space
string-convert-indexes	Convert string character indexes from JS native index-based to Unicode character-count-based and backwards.		packages/string-convert-indexes
string-extract-class-names	Extract class (or id) name from a string		packages/string-extract-class-names
string-find-heads-tails	Search for string pairs. A special case of string search algorithm.		packages/string-find-heads-tails
string-fix-broken-named-entities	Finds and fixes common and not so common broken named HTML entities, returns ranges array of fixes		packages/string-fix-broken-named-entities
string-match-left-right	Do substrings match what's on the left or right of a given index?		packages/string-match-left-right
string-overlap-one-on-another	Lay one string on top of another, with an optional offset		packages/string-overlap-one-on-another
string-remove-duplicate-heads-tails	Detect and (recursively) remove head and tail wrappings around the input string		packages/string-remove-duplicate-heads-tails
string-remove-thousand-separators	Detects and removes thousand separators (dot/comma/quote/space) from string-type digits		packages/string-remove-thousand-separators
string-split-by-whitespace	Split string into array by chunks of whitespace		packages/string-split-by-whitespace
string-trim-spaces-only	Like String.trim() but trims only spaces		packages/string-trim-spaces-only
string-unfancy	Replace all fancy dashes, quotes etc with their simpler equivalents		packages/string-unfancy

🔮 20 Object Processing Libraries

When we say "object" we mean a plain object in JavaScript, for example, { name: "Bob" }. Usually, plain objects come from JSON files, and often they are deeply nested. The following libraries help us to traverse them, set and delete keys and compare objects.

"ast-" in the library's name below just emphasises that it really works on nested objects (so-called Abstract Syntax Trees that come from parsed things).

Library's name	Purpose	npm_link	Source code in monorepo
ast-monkey	Utility library for ops on parsed HTML (AST's) or anything nested (plain objects within arrays within plain objects)		packages/ast-monkey
ast-monkey-traverse	Utility library to traverse parsed HTML (AST's) or anything nested (plain objects within arrays within plain objects)		packages/ast-monkey-traverse
json-comb-core	The inner core of json-comb		packages/json-comb-core
json-variables	Preprocessor for JSON to allow keys referencing keys		packages/json-variables
object-merge-advanced	Recursive, deep merge of anything (objects, arrays, strings or nested thereof), which weighs contents by type hierarchy to ensure the maximum content is retained		packages/object-merge-advanced
ast-compare	Compare anything: AST, objects, arrays, strings and nested thereof		packages/ast-compare
ast-contains-only-empty-space	Returns Boolean depending if passed AST contain only empty space		packages/ast-contains-only-empty-space
ast-delete-object	Delete all plain objects that contain a certain key/value pair		packages/ast-delete-object
ast-get-object	Getter/setter for nested parsed HTML AST's, querying objects by key/value pairs		packages/ast-get-object
ast-get-values-by-key	Read or edit parsed HTML (or AST in general)		packages/ast-get-values-by-key
ast-is-empty	Find out, is nested array/object/string/AST tree is empty		packages/ast-is-empty
ast-loose-compare	Compare anything: AST, objects, arrays and strings		packages/ast-loose-compare
object-all-values-equal-to	Does the AST/nested-plain-object/array/whatever contain only one kind of value?		packages/object-all-values-equal-to
object-boolean-combinations	Generate an array full of object copies, each containing a unique Boolean value combination. Includes overrides.		packages/object-boolean-combinations
object-delete-key	Delete keys from all arrays or plain objects, nested within anything, by key or by value or by both, and clean up afterwards. Accepts wildcards.		packages/object-delete-key
object-fill-missing-keys	Add missing keys into plain objects, according to a reference object		packages/object-fill-missing-keys
object-flatten-all-arrays	Merge and flatten any arrays found in all values within plain objects		packages/object-flatten-all-arrays
object-flatten-referencing	Flatten complex nested objects according to a reference objects		packages/object-flatten-referencing
object-no-new-keys	Check, does a plain object (AST/JSON) has any unique keys, not present in a reference object (another AST/JSON)		packages/object-no-new-keys
object-set-all-values-to	Recursively walk the input and set all found values in plain objects to something		packages/object-set-all-values-to

✂️ 8 CLI Apps

All the following libraries are command line applications. You install them using -g flag, for example, npm i -g json-sort-cli.

You use them in the Terminal (command line), for example:

Library's name	Purpose	npm_link	Source code in monorepo
lect	Maintenance automation for Readme's and, optionally, other project files		packages/lect
update-versions	Like npm-check-updates but supports Lerna monorepos and enforces strict semver values		packages/update-versions
chlu-cli	CH-ange-L-og U-pdate — Automatically fix errors in your changelog file		packages/chlu-cli
csv-sort-cli	Command line app to sort double-entry CSVs coming from internet banking statements		packages/csv-sort-cli
email-all-chars-within-ascii-cli	Command line app to scan email templates, are all their characters within ASCII range		packages/email-all-chars-within-ascii-cli
js-row-num-cli	Update all row numbers in all console.logs in JS code		packages/js-row-num-cli
json-sort-cli	Command line app to deep sort JSON files, also dot-files as long as they are valid JSON		packages/json-sort-cli
lerna-clean-changelogs-cli	CLI application to cleanse the lerna-generated changelogs		packages/lerna-clean-changelogs-cli

🛠️ 17 Miscellaneous Libraries

Library's name	Purpose	npm_link	Source code in monorepo
array-group-str-omit-num-char	Groups array of strings by omitting number characters		packages/array-group-str-omit-num-char
array-includes-with-glob	like _.includes but with wildcards		packages/array-includes-with-glob
array-of-arrays-into-ast	turns an array of arrays of data into a nested tree of plain objects		packages/array-of-arrays-into-ast
array-of-arrays-sort-by-col	sort array of arrays by column, rippling the sorting outwards from that column		packages/array-of-arrays-sort-by-col
array-pull-all-with-glob	pullAllWithGlob — like _.pullAll but pulling stronger, with globs		packages/array-pull-all-with-glob
arrayiffy-if-string	Put non-empty strings into arrays, turn empty-ones into empty arrays. Bypass everything else.		packages/arrayiffy-if-string
charcode-is-valid-xml-name-character	Does a given character belong to XML spec's "Production 4 OR 4a" type (is acceptable for XML element's name)		packages/charcode-is-valid-xml-name-character
check-types-mini	Check the types of your options object's values after user has customised them		packages/check-types-mini
chlu	CH-ange-L-og U-pdate — Automatically fix errors in your changelog file		packages/chlu
color-shorthand-hex-to-six-digit	Convert shorthand hex color codes into full		packages/color-shorthand-hex-to-six-digit
email-homey	Generate homepage in the Browsersync root with links/screenshots to all your email templates		packages/email-homey
emlint	Detects errors in HTML/CSS, proposes fixes, email-template friendly		packages/emlint
gulp-email-remove-unused-css	Gulp plugin to remove unused CSS classes/id's from styles in HTML HEAD and inline within BODY		packages/gulp-email-remove-unused-css
lerna-clean-changelogs	Cleans all the crap from Lerna and Conventional Commits-generated changelogs		packages/lerna-clean-changelogs
regex-empty-conditional-comments	Regular expression for matching HTML empty conditional comments		packages/regex-empty-conditional-comments
util-array-object-or-both	Validate and normalise user choice: array, object or both?		packages/util-array-object-or-both
util-nonempty	Is the input (plain object, array, string or whatever) not empty?		packages/util-nonempty

🤝 Contributing

• If you see an error, raise an issue.
• If you want a new feature but can't code it up yourself, also raise an issue. Let's discuss it.
• If you tried to use a package, but something didn't work out, also raise an issue. We'll try to help.
• If you want to contribute some code, fork the monorepo via GitLab, then write code, then file a pull request on GitLab. We'll merge it in and release.

In monorepo, npm libraries are located in packages/ folder. Inside, the source code is located either in src/ folder (normal npm library) or in the root, cli.js (if it's a command line application).

The npm script within each package's package.json "dev", the "dev": "rollup -c --dev --silent" builds the development version retaining all console.logs with row numbers. It's handy to have js-row-num-cli installed globally so you can automatically update the row numbers on all console.logs.

💼 Licence

MIT License

Copyright (c) 2015-2019 Roy Revelt and other contributors