0.4.0

Continuous Integration

• preview release notes; closes #17 (5d0211e)

  See the example here from the very PR which implemented this feature.

Features

• (parser): init (056852f)

  Parser combinator libraries provide composable parsers used together to construct more complex parsers. This first draft is robust enough for simple DSLs. Notably it does not implement backtracking or a chain combinator, which would allow for more advanced branching. However the TS implementation is very powerful, capable of inferring the return types from complex parsers without explicit compiler hints in userland.

  show/hide

  The following is a brief overview of the features added. Additionally, the four existing parsers in the repository were re-written using the library - they can serve as examples and documentation, in addition to robust JSDoc comments and test suites.

  • The base Parser class implements core helper methods like .fallback(), into(), .not(), .and(), .or(), .optional, .ignore, and .zeroOrMore.

  • Shorthand factory string() makes it easy to construct a Parser from one or more strings.

  • ArrayParser with shorthand factory sequence() provides a specialized Parser with array-specific .flat, .item(), .items(), .join(), and .toObject(), and specialized handling for parser-like inputs and ignored parsers.

  • RegExpParser with shorthand factory regexp() provides a specialized Parser around one or more RegExp patterns, with RegExp-specific .match, .group(), and .groups() methods.

  • Common helpers like whitespace, blankLine, and end are provided. Some are re-exported under line (ex. line.blank) and whitespace (ex. whitespace.inline) for convenience.

• (string): add Text; replace location(); closes #89 (a759626)

  show/hide

  The Text class wraps a string value as a body of text such as a text file's contents, with special considerations for lines, line numbers, and column numbers.

  • The input Text value can be accessed via .value or .input getters. The internal value is immutable.

  • Text exposes .length and .valueOf() for convenience and parity with native String.

  • Text.lines correctly handles splitting on newline characters while retaining them, and caches its output.

  • Text.locationAt(index) converts a Position-like index to a TextLocation (line number, column number, and normalized offset value). This replaces the location() helper. The TextLocation type is moved into string/Text.ts and also re-exported as Text.Location.

• (string): add TextCursor (3830890)

  A TextCursor is Text tracking a Position within itself, alongside a suite of useful methods and getters. This provides a way to describe substrings without creating them, which can be memory-intensive for some tasks. Preliminary benchmarks also show that TextCursor is ~1.8x faster for standard parsing tasks than plain string and its methods, regardless of input length.

  TextCursor also has an attractive .inspect() method which depicts the cursor location within the text:

  …jumps over the lazy d…
               ^
  

• (array/types): init (e3b017f)

  show/hide

  • Fill replaces array values with a given value.

  • Flat is analogous to Array.prototype.flat()

  • Indices extracts the index values of an array.

  • Index extracts a union of indices from an array.

  • FromIndices describes a new array from a given array and a tuple of indices.

  • Reverse describes an array with the same elements in reverse order.

  • Zip combines two arrays into an array of tuples. Useful for creating object entries.

  • The Tuple namespace clusters all helper types which respect tuples, which currently includes all types. This was a preferable alternative to starting a new top-level tuple module just to house these typedefs.

• (object/types): init (5da75ff)

  show/hide

  • Key is a valid object key.

  • EmptyObject is an object for which all properties are invalid.

  • Entry is a key-value tuple.

  • Pair is a key-value pair in an object.

  • EntryToPair converts an Entry to a Pair

  • FromEntries converts Entrys to an object

  • ToEntries converts an object to an array of Entrys

  • The Obj namespace clusters these helper types.

• (array/types): add TypedArray (3574bb1)

• (array/types): add TupleOfLength (5edb2ca)

• (ts/types): add Satisfies (d32c3d6)

• (number): init; add types (54b6c7a)

  show/hide

  • NumberType yields a string literal that describes an input number:

    type T = NumberType<-1> // "-integer"

  • Wide filters for widened types number and the infinities.

  • Finite filters for non-Wide types

  • Integer filters integers including zero.

  • Float filters numbers with decimals.

  • The Num namespace clusters these types.

• (string/types): init (eae206d)

  show/hide

  • Char represents one of the characters within a string.

  • Index represents one of the indices of a string.

  • Indices represents a tuple containing each index of a string.

  • ToTuple represents a string as a tuple of individual characters.

  • Wide filters string from specific strings, returning string when the input was string and never otherwise.

  • The Str namespace clusters these types.

• (collection/types): init (2359f6f)

  show/hide

  • IndexedCollection is simply ArrayLike<unknown> for naming purposes.

  • Index represents one of the indices within an IndexedCollection collection.

  • Indices represents a tuple containing each index of an IndexedCollection. Uses Str.Indices and Tuple.Indices under the hood.

• (path): add dir() (881798b)

• (os): init; add newlines utilities (a57d4e7)

• (evalCodeBlocks): allow blocks to opt out with no-eval; closes #37 (9a0fea2)

• (evalCodeBlocks): condense output (c635b8a)

• (evalCodeBlocks): exit code 1 on failure; closes #59 (c67c2be)

• (json): init; move types/json -> json/types (d5b6167)

• (ts): add Intersect util type (71a657e)

• (DirectedGraph): .has() accepts edges, paths, and is variadic (6d3df59)

• (DirectedGraph): .add() accepts edges, paths, and is variadic (7d80ed1)

• (DirectedGraph): .remove() accepts edges, paths, and is variadic (b84c431)

• (DirectedGraph): namespace typedefs (22789a1)

• (cli): add console size helpers; closes #93 (18a8ee7)

  • consoleWidth() returns the actual console width in columns, else a fallback value when unable.

  • consoleHeight() does the same for height in rows.

  • consoleSize() does both at once.

• (string): add elide helpers; closes #94 (88636fe)

  • elideStart() replaces the start of a string with ellipses

  • elideEnd() replaces the end of a string with ellipses

  • elideMiddle() replaces the middle of a string with ellipses

  • elideAround() dynamically elides the start and/or end of a string with ellipses, centered around a chosen index

• (md/codeBlock): findAll functions return TextLocation (4e7f776)

• (evalCodeBlocks): log line and error on fail; closes #42 (f3c9bed)

• (collection): add position submodule (19fa4a6)

  A Position describes a location between items in an IndexedCollection such as an array or string. For example "a" has two Positions - 0 and 1, representing the locations before and after a. This has some unique properties: 0 is always a valid, and the collection's length is always valid. These semantics correspond to the behavior of the first argument of Array.splice.

  The function toPosition takes a positive or negative index and normalizes it into a positive Position value, where -1 refers to the position before the last item in the collection. The special value -0 refers to the Position at the end of the collection, identical to the collection's length.

• (mermaid): init; add flowchart() (bbb4fff)

• (string): add escape helpers (7f4b8ee)

  • escapeFull() replaces special characters like newline with two-character literals of their escape sequences like "\n"

  • escapeTerse() is converts special characters into single-character unicode symbols, to preserve string length. Importantly, newline becomes "¶" and tab becomes "⇥"

• (array/types): Flat respects non-tuple arrays (329912e)

• (string/TextCursor): visualize spaces as · (b57ac02)

• (git/commit): add sha() (641b43d)

• (md/codeBlock): findAll functions return details objects (1cc011f)

Fixes

• Breaking Change (DirectedGraph): constrain and document vertex types (28bd64e)

  Previously vertices were NonNullable but this still allowed problematic boolean, unknown, and Array types. This commit constrains vertices to string, number, symbol, and non-Array objects, preventing confusion and setting up for API improvements that rely on arrays to represent edges and paths.

• (makeReleaseNotes): wire inclusive CLI flag (1f91b7b)

• (path/globRoot): make path separator agnostic (9ebdce5)

• (md): parse Windows newlines (dc368ff)

• (path/utils): export dir(); closes #61 (72894d2)

• (array/types): handle readonly arrays (032d55b)

• (evalCodeBlocks): handle ✔️ (019f8a5)

• (evalCodeBlocks): avoid check em...

0.3.0

This release we focused on adding CI and getting it running on MacOS, Ubuntu, and Windows 🎉

Thanks to @AustinArey for his many contributions to this release!

Continuous Integration

• init PR checks (7ec03b1)

• (steps): continue-on-error-> success() || failure(); closes #29 (c4b37fc)

• (macos): enable unit tests; closes #13 (83b8ab7)

• Enable tests on Windows; Closes #14 (4d889d6)

• adding full tests on ubuntu (ade5e6a)

• enable readme tests; closes #16 (7291352)

Features

• (cli/cmd): don't throw with fullResult option; closes #27 (c179244)

• (ts): init; extract evaluate() from md/codeBlock/evaluate (6bf2e21)

• (makeReleaseNotes): add inclusive option; closes #24 (da4582c)

Fixes

• (cli/cmd): use Deno.Command API; closes #20 (85a4cd8)

• check if tty before using consoleSize (f56730c)

• (fs): handle Windows path separators (ea481c4)

• (fs): use FileUrl schemes (71f416c)

• (io): Clipboard works in Windows (dce8f1c)

• (makeReleaseNotes): include commit footers; closes #25 (f2c075f)

0.2.0

Chores

• add license file (7227b43)

  This was accidentally omitted before. In case it ever matters: All previous commits are available under the same (0BSD) license.

Features

• Breaking Change: scripts/evalCodeBlocks -> md/script/evalCodeBlocks (3c51daa)

• (md): init; add codeBlock module (8e4b1e8)

  • regex.ts contains regex patterns matching code blocks

  • framed.ts and indented.ts address both types of code block

  • infoString.ts addresses the info string of a fenced code block

  • create.ts, parse.ts, and findAll.ts dynamically handle both types of code block

  • scripts/evalCodeBlock.ts upgraded to use superior code block finding and parsing, and to be more aware of language codes

• (md): extract evaluate() & evaluateAll() (712b3ab)

  Previously scripts/evalCodeBlock held this logic for evaluating TS code blocks. Now that md/codeBlock module exists, it makes a perfect home for extracting this code. This also lays the groundwork for upcoming features.

• (cli): init; add cmd() (b0b821d)

• (io/clipboard): init; add copy() & paste() (e9d3276)

• (git): add script/makeReleaseNotes.ts (38a6fc8)

  This script will generate release notes from conventional commits since the last tag. Often the result is satisfactory as-is, and it's otherwise a great starting point.

  See the readme entry or run with --help option for full info. It's recommended to use the -g flag to group commits by type, the -c flag to copy the output to clipboard, and the --types flag to filter and order the types of commits to include.

  deno run -A https://deno.land/x/handy/git/script/makeReleaseNotes.ts \
    -gc --types=feat,fix

• (git): init; add tag.ts (d223236)

  • get() retrieves all tags

  • getLatest() retrieves the latest semver tag, or the alphabetically last tag if the tags are not semver-sortable

• (git): add commit module (32ec6c1)

  • commit.COMMIT_LOG_REGEX can parse a commit into named capture groups

  • commit.splitLog() splits a git log result into multiple commits

  • commit.describe() takes one git log commit and turns it into a CommitDescription

  • commit.get() retrieves a single commit as CommitDescription

  • commit.getSpan() retrieves an inclusive span of commits as CommitDescription[]

• (git): add commit/conventional module (3da1887)

  • commit.conventional.parse() turns a commit message into a ConventionalCommit

  • commit.conventional.stringify() turns a ConventionalCommit into a commit message

• (DirectedGraph): custom console log output (0b29d2a)

• (DirectedGraph): add Symbol.iterator (19fdcc0)

• (DirectedGraph): add .roots & .leaves (b54deb7)

• (DirectedGraph): add .isCyclic & .hasCycle() (b2a9703)

• (DirectedGraph): add .isTree (a66d63c)

• (DirectedGraph): add .isForest (2bbcdda)

• (DirectedGraph): add .has() (4a440e4)

• (DirectedGraph): add .subgraph() (fe8fe01)

• (string): init; add splitOn() & splitOnFirst() (bf4f771)

• (string): add sequences() & mostConsecutive() (f4ffe25)

• (string): add dedent() (d20afed)

• (string): add indent() (e7cb673)

Fixes

• (evalCodeBlocks): eval as TypeScript (80ee9fc)

• (graph): remove accidental import (a80bd56)

• (md): skip empty groups in release notes (a67cbaf)

0.1.0

• Ported from https://github.com/pskfyi/deno-utils and renamed to Handy
• Added Scripts section with first script
• Polished some existing functions
  • Fixed and simplified globImport
  • Renamed timing.oncePerInterval to array.mapOnInterval and adjusted API