npm package: @opigence.com/utils
Description: Common Utilities targeting ESM / Typescript environments
Author: Wesley M. Conner
Latest version: 1.12.9

= Utils

This module includes general-purpose Typescript/NodeJS utilities.

WARNING: Circa 2023-01(Jan), npx np has faced issues. +
Manually update version, then: +
`npm publish --access public`

== Module Publication

[%autowidth, frame="none", grid="none", cols=">h,<"]
|===

|npm run installLatest
|Updates library dependencies.

|npm run doAll
|Build typescript and run available jests.

|git commit
|Commit all local changes and push them to origin/main.

|npm login
|Use the provided link to open a browser and authenticate with npm.

|npx np
|Trigger the `np` publisher. +
Review the list of files (if any) that are being published for the first time.

|select semver |`np` clarifies whether the update is a `patch`,
`minor`, `major`, ... +
`np` will insist you stash any local, uncommitted changes!

|Provide one-time password
|After running tests, `np` will seek a fresh one-time password when 'publishing'. +
  ✔ Prerequisite check +
  ✔ Git +
  ✔ Installing dependencies using npm +
  ✔ Running tests using npm +
  ✔ Bumping version using npm <- _one-time password required here_ +
  ✔ Publishing package using npm <- _`np` may hang and still be successful!_ +
  ✔ Pushing tags +

|Review Versions
|https://www.npmjs.com/search?q=%40opigence%2Futils

|Remove a Version
|`npm unpublish @opigence.com/utils@1.0.0 --force`

|Deprecate a Version
|`npm deprecate -f @opigence.com/utils@1.2.0 "this package has been deprecated"`

|===

WARNING: The documentation below (and other project adocs) needs to be reviewed/updated!

== Antora Support
The primary focus is to facilitate automatically generating an `_antora/` directory that complies with Antora's standard directory requirements.

=== Included AsciiDoc Files
One symbolic link is created for each discovered AsciiDoc file.

=== Included "Snippet" Files
One AsciiDoc file is created per Snippet source file.

Snippet source files are non-AsciiDoc files (i.e., no `.adoc` suffix) that embed _snippets_. Snippets are lines with one of the following snippet-prefixes.

[horizontal]
 //adoc|:: Snippet prefix for files using //-delimited comments
 #adoc|:: Snippet prefix for files using #-delimited comments

=== Optional TsDoc Inclusion
The `typedoc` npm module generates HTML from embedded TsDoc notation. Support exists for generating thus HTML into `_antora/` and referencing it in the generated Antora navigation file.

=== Optional Code Coverage Inclusion
Support exists for copying Code Coverage HTML into `_antora/` and referencing it in the generated Antora navigation file.

== KNOWN ISSUES
There's no clean way of adding `npm run antora` to `.git/hooks/pre-commit` without creating
some issues. For example: Tools like VsCode do not show any messages written to the console.
Rebuilding Antora (a) takes time and (b) it takes VsCode a little time to detect any file
changes and reconcile "Changes" to "Staged Changes".

Tactically, an Antora rebuild is being added as a pre-commit on a trial basis.

== Trigger on Git Pre-Commit
In order to ensure that `antora/` is up-to-date, a Git pre-commit hook is defined.

..git/hooks/pre-commit
----
#!/bin/sh
npm run antora
----

NOTE: Watch for the case where `.git/hooks/pre-commit` reverts to non-executable.

== LICENSE

Copyright (C) 2023-Present Wesley M. Conner DBA Opigence Tech
License: Apache-2.0
See LICENSE.txt