open-index/open-npm huggingface dataset:
npm package: @nartallax/clamsensor
Description: A little testing framework
Author: Nartallax
Latest version: 2.1.3

# Clam Sensor

A builder-agnostic tool to test Typescript projects.  
For those of us who deem Jest needlessly complicated and demanding.  

## How it works

First, you define tests. Tests are defined in files that ends in `.test.ts`, as per custom.  
Second, you generate test code. Test code contains imports from all `.test.ts` files to avoid tree-shaking, and code that runs all (or some of) the defined tests.  
Third, you build and launch test build. It runs tests you select and gives progress and results in stderr. It also exits with nonzero exit code if testing was not successful.  

## Usage

### Install  

    npm install --save-dev @nartallax/clamsensor

### Define the tests

First step is to define the test cases.

    import {describe, test} from "@nartallax/clamsensor";
    import {MyCalc} from "appcode/my_calc";

    describe("MyCalc", () => {
        test("calculator should sum numbers correctly", () => {
            if(MyCalc.sum(1,2,3) !== 6){
                throw new Error("Something is wrong")
            }
        })
    })

It's up to you what assertion library to use. Clamsensor don't have anything built-in for that; the only expectation is that test will throw if something is not right.  
Asyncronous tests should return promise.  

### Generating the code

To generate the code, you should run `./node_modules/.bin/clamsensor_generator.js ./src/test ./generated/test_entrypoint.ts`.  
If you want to just have a module that imports from all the test modules without running them, you can add `--no-run` as generator option.  

### Running the code

Next step is to build your test build using file generated at the previous step as entrypoint. It's up to you how to do that.  
Then you can run your build like `node ./dist/test_build.js`.  
If you chose to add code that runs test in generated code (default behaviour), you should also be able to pass an argument (first one in CLI) to filter by test name.  
You can also pass `--no-stack-trace` if you want to only see messages of the errors instead of full stacks.  

## Naming

Clams are sometimes used as a sensors to control quality of outputted water in some water treatment plants.
npm package: @nartallax/cli
Description: A library for creating command-line interface for NodeJS applications
Author: Nartallax
Latest version: 1.0.13

# @nartallax/cli

A library for creating command-line interface for NodeJS applications  

## Install

```bash
npm install @nartallax/cli
```

## Use

```ts
import {CLI} from "@nartallax/cli"

// let's start with defining our options
const definition = CLI.define({
  // this is header that will be displayed in `--help`
  // as you can see, for this example we will define options for web application
  helpHeader: "Multiplication web application",
  options: {
    // simple number option.
    // note that this option will accept fractions; there is `CLI.int()` that won't.
    multiplier: CLI.number({
      keys: ["-m", "--multiplier"],
      description: "Factor by which input value will be multiplied",
      default: 2
    }),
    // enum option - only allows to pass a value from a predefined set of strings
    // parsed value will be typed as union of constants, not just `string`
    mode: CLI.str<"as-usual" | "negate">({
      keys: "--mode",
      description: "Mode in which application will work.",
      allowedValues: ["as-usual", "negate"],
      default: "as-usual"
    }),
    // port option - same as `CLI.int()` but with pre-defined boundaries
    port: CLI.port({
      keys: ["-p", "--port"],
      description: "Port on which web application will expose its UI",
      default: 46725
    }),
    // path option - same as `CLI.str()` but with built-in resolving to absolute path
    configPath: CLI.path({
      keys: ["-c", "--config-path"],
      description: "Path to config file"
      // no default here! it means this option is mandatory and can only be skipped if help is passed.
    }),
    // path array option
    // most options can be arrays, not only paths
    // user could pass multiple values like this: `--preset a.json --preset b.json`
    presets: CLI.pathArr({
      keys: "--preset",
      description: "Operation preset files.",
      default: []
    })
    // other types of options and constraints are available, make sure to check type definitions
  }
  // other parameters are possible to pass here, but I leave them for you to discover
})

// we may want to get the type we just defined
// after parsing arguments will be organised as object
export type CLIArgs = CLI.ArgsByDefinition<typeof definition>

// and, at last, let's parse arguments that were passed to our program
// default source or arguments is `process.argv`, but you may pass something custom here
export const parseCliArgs = (): CLIArgs => definition.parse()


// alternatively, if you want to also provide JS API, not only CLI, you could use defineMain.
// defineMain will run provided callback if import.meta.url points to currently executed file
// and will also create a wrapper for the callback for case when it is imported and used as a package
export const doMainThing = CLI.defineMain(definition, import.meta.url, async args => {
  await doTheThing(args)
})
```
npm package: @nartallax/fontello-wrapper
Description: A set of scripts to do with Fontello exactly what I want
Author: Nartallax
Latest version: 1.0.5

# Fontello Wrapper

A fine-tuning of [Fontello](https://github.com/fontello/fontello) to match my needs.  
Main purpose of this all is to have one-click button to render everything exactly like you want it.  

Disclaimer: I do not develop Fontello, and have no connections to the developers of Fontello.  

## Install

1. Make sure your NodeJS is version 14 or higher  
Fontello implicitly requires this version of Node by using some relatively new JS syntax.  
2. `npm install -g ttfautohint`  
Fontello implies that there will be executable `ttfautohint` available to shell. Easiest way to achieve this is by installing this package globally.  
3. `git clone https://github.com/fontello/fontello` somewhere  
Location does not matter much, as we will configure it later.  
4. `npm install` inside Fontello directory  
Because those packages won't install themselves.  
5. `npm install -g @nartallax/fontello-wrapper`  
It is implied that the wrapper will be installed globally. It's not really required to do so; it's just does not makes sense to me to install this as dependency for any particular project.  
6. Put a path to `server.js` of Fontello in file `FONTELLO_PATH.TXT` near `fontello-wrapper.js`  
If you isn't sure where exactly you should put it, just launch the `fontello-wrapper` and the wrapper will tell you.  

Note: most (all) of globally installed things here (like specific version of NodeJS, or ttfautohint) can be installed locally and mimic global behavior through manipulation of PATH environment variable, but this approach makes install and launch process even more complicated, so let's go without it.  

## Configure

Next step is to tell wrapper what to do on save.  
This settings are related to the project you build your font for, and stored in JSON file.  
I won't repeat myself here about exact syntax of the file; go look on it [in type definitions](ts/config.ts).  

## Launch

If you installed the wrapper globally, as I suggested earlier, you now should be able to just launch `fontello-wrapper ./my_project/my_config.json` in command line.  
After launch wrapper will open Fontello web interface in your default browser after the Fontello is launched. Don't use default web interface address, as this won't work as expected. "Export font" button will save the font as you configured.
npm package: @nartallax/forest
Description: Library about trees, groups of trees and various operations over them.
Author: Nartallax
Latest version: 1.5.0

# @nartallax/forest

TypeScript library about trees, groups of trees and various operations over them.

## Install

```bash
npm install @nartallax/forest
```

## Use

Main functionality of this library is contained within `Forest` class:

```typescript
import {Forest} from "@nartallax/forest"


let forest = new Forest({value: "branch", children: [{value: "leaf"}]})
console.log(forest + "")

forest = forest.insertLeafAt([0, 1], "new leaf"))
console.log(forest + "")

// etc, much more methods there, check'em out in typings
```
npm package: @nartallax/icon-font-tool
Description: A tool to work with icon fonts
Author: Nartallax
Latest version: 1.0.9

# Icon font tool

A tool to work with icon fonts.  
Very far from "swiss army knife of icon tools"; more like "a tool that fits just my exact needs".

## Install

```bash
npm install --save-dev @nartallax/icon-font-tool
```

## Use

Full list of options is available at

```bash
./node_modules/.bin/icon-font-tool --help
```

...but here's an example:

```bash
./node_modules/.bin/icon-font-tool \
	--svg-dir ./icons \
	--font-path target/my_icon_font \
	--ts-path target/icon_font.ts \
	--css-path target/icon_font_style.css
```

Command above will:

1. take all SVGs in `./icons` directory;
2. Make a `woff2` font out of it (there's option to control formats) and put it in `./target/my_icon_font.woff2`;
3. Generate CSS file with classes related to icons and put that CSS file at `./target/icon_font_style.css`;
4. Generate TS file that will import CSS file and export const enum with all the icons.

As you can see, this tool expects that your build process supports CSS importing. The idea behind all of those steps is that you can just import icons from TS file and let builder do all the work regarding delivery of the fonts/styles.  

If your CSS file ends with `.module.css`, then TS file will look a bit different - instead of const enum, it will export an object under the same name. That's not as optimal as const enum, but will work the same way, and if you want names of the icons to be mangled - you can go that route.  

# Development

```bash
# clone the repo
git clone ssh://git@nartallax.net:nartallax/icon-font-tool

# get into repo's dir
cd icon-font-tool

# set up signing
# also, make sure that `git config --get user.email` is equal to your email in forgejo
git config gpg.format ssh
git config user.signingKey "~/.ssh/id_rsa"

# this one is optional. forgejo will show commits as signed without this step
# but git can panic about missing keys sometimes
echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/id_rsa.pub)" >> allowed_signers
git add . && git commit -m "Add new key to allowed_signers" && git push

# enable signing by default
git config commit.gpgsign true
```
npm package: @nartallax/npm-run
Description: A small command-line tool to substitute `npm run` with.
Author: Nartallax
Latest version: 1.0.3

# @nartallax/npm-run

A small command-line tool to substitute `npm run` with.

## Install

```bash
npm install -g @nartallax/npm-run
```

## Use

```bash
nr my-command-from-packagejson
```

## Optimization(s)

If command starts with `node something.mjs`, or just `./something.mjs` - the mjs file will be imported within process of npm-run (with argv and cwd updated to match what file would expect). This avoids to spin up new NodeJS instance.  
This optimization is applied on very specific conditions - all arguments must be alphanumeric (otherwise we are at risk of misinterpreting some smart-er shell syntax as arguments, which will lead to unexpected results).  
Also there must be exactly one space between `node` and path start (or no spaces in the case of shebanged script call). This allows to override this optimization by adding more spaces, which should not affect logic of the script.

Every command not matching above conditions will just be run in system's default shell.

## Why?

I like to keep every single action I may want to run about my project in `package.json` scripts. Literally everything - build actions, diagnostics, systemd management...  
This requires me to run `npm run commandname` every time I want to run a command. It's convenient to have everything in one place, but comes with some problems:  

 - `npm run` sometimes takes noticeably more time than just running the command in the shell (sometimes up to 400ms more time). It's not much, but in case of short-lived commands like "show me systemd status of my service" it is very noticeable. (and yes, `yarn` also has this problem, sometimes even worse).  
 - `npm run` is a bit too much characters to type for my taste.  

So here comes this package, adding `nr` command, that does exactly the same as `npm run`, just slightly better.
npm package: @nartallax/package-cutter
Description: Small tool for preparing package.json for NPM packaging
Author: Nartallax
Latest version: 1.0.7

# Package Cutter

This tool can remove some properties from `package.json`.  
Some of the properties you have in `package.json` are only required for development (like `scripts`, `devDependencies`, `targets` if you use [Parcel](https://parceljs.org/)), can grow pretty large and shouldn't actually be present in published package.  
So, if your build process is advanced enough, you probably should throw them away when preparing your release.  

## Install

```bash
npm install @nartallax/package-cutter
```

## Use

Intended to be invoked from command line:
```bash
# this will take ./package.json
# then remove default set of keys from it
# then put result in ./build_result/package.json
./node_modules/.bin/package-cutter --output ./build_result/package.json

# There are other CLI parameters like `--pretty` or `--keys`
# find out more by running
./node_modules/.bin/package-cutter --help
```

Alternatively, JS API exists:
```js
import {cutPackageJson} from "@nartallax/package-cutter"

await cutPackageJson({
	output: "./target/package.json",
	pretty: true
})
```
npm package: @nartallax/package_syncer
Description: A tool to keep contents of your node_modules in sync with package.json
Author: Nartallax
Latest version: 1.0.4

# Package Syncer

Tool that helps you to keep contents of `package.json` and `node_modules` in sync.  

It's easy to keep them in sync if you're working on a project alone on your only workstation, but if you have multiple of them, or you have colleagues? Then all of those need some way to tell each other that they need to `npm install` packages every time someone installs/updates a package, and that's tedious.  

This tool allows to automate this process. It can run an update command (`npm ci` by default) every time it detects a change in `package.json` or `package-lock.json` (list of files is also configurable). Old versions of those files are stored inside `node_modules`, just to have something to compare current versions against.  

It also has watch mode, for those of us who love continuously-running development scripts that can keep running when you do `git pull`.  

## Install and run

	npm install --save-dev @nartallax/package_syncer
	./node_modules/.bin/package_syncer --help

## Options

All of thos options are, well, optional. That is, tool will work just fine without any of those; by default it syncs once and exits.  
(most of stuff below is repeated in `--help`, but anyway, here goes)

### --source-file

Allows to specify a list of files. If any changes are detected between current version of file and backupped version, sync command is issued.  
For multiple files pass this option more than once.  
By default it's just `package.json` and `package-lock.json`.  

### --sync-command

Command that will be used to update packages inside `node_modules`.  
By default it's `npm ci`, but you may use `yarn` or whatever else, in which case you will need to pass something meaningful in this option.  

### --watch

Enables watch mode.  
After initial check the tool won't exit; instead, it will watch for changes in source files, and every time there are any changes - it will issue sync command.  
Intended use-case is to be included as part of scripts that start your compiler, dev webserver and whatever else you need in development. It feels good to just keep them running in background when you do stuff, like `git pull` or whatever else.  

### --node-modules

Path to `node_modules` directory.  
Right now it's not used for anything beside backup files storage, but who knowns.  

### --remember

Copy source files into backup locations before start.  
That way, you're saying "this node_modules are currently in sync with package.json, no need to re-sync". So, this option should be supplied only after `npm install` or something like that.  

### --skip-initial-check

Don't check files initially. Tool will still check files in watch mode if --watch is passed. Initial check is always skipped if --remember passed.
npm package: @nartallax/parcel-transformer-bin-as-uint8-array
Description: Plugin for Parcel that embeds binary files as Uint8Array
Author: Nartallax
Latest version: 1.0.2

# Binary file transformer

This plugin will embed binary files as base64 into your bundle. In runtime that base64 will be parsed to `Uint8Array`.  

## Install

Install the package:

```bash
npm install --save-dev @nartallax/parcel-transformer-bin-as-uint8-array
```

Then update `.parcelrc`:

```json
"transformers": {
    "*.bin": ["...", "@nartallax/parcel-transformer-bin-as-uint8-array"]
}
```
npm package: @nartallax/ribcage-validation
Description: Validation library based on Ribcage
Author: Nartallax
Latest version: 2.0.1

# Ribcage-Validation

Validation library based on [Ribcage](https://github.com/nartallax/ribcage)

## Install

```bash
npm install @nartallax/ribcage
npm install @nartallax/ribcage-validation
```

Note that `@nartallax/ribcage` is a peer depencency.

## Use

### Validated functions

The most obvious example will be the validated functions:

```typescript
import {RC} from "@nartallax/ribcage"
import {RCV} from "@nartallax/ribcage-validation"

// define some data structure
let point = RC.struct({x: RC.number(), y: RC.number()})

// create a function that uses this data structure
let distanceBetweenPoints = RCV.validatedFunction([point, point], (a, b) => {
	return Math.sqrt((a.x - b.x) ** 2 + (a.y - b.y) ** 2)
})

// use this function
distanceBetweenPoints({x: 1, y: 1}, {x: 2, y: 1}) // 1
distanceBetweenPoints({x: 1, y: 1}, "this is not the point" as any) // throws
```

### Manual validator creation

You can also explicitly create validators, if this case doesn't fit your needs:

```typescript
import {RC} from "@nartallax/ribcage"
import {RCV} from "@nartallax/ribcage-validation"

let point = RC.struct({x: RC.number(), y: RC.number()})
let builder = RCV.getValidatorBuilder()
let validator = builder.build(point)

validator({x: 5, y: 10}) // nothing
validator({x: 5, y: "uwu"}) // throws
```

### Custom validators

You can attach custom validators to most types provided by Ribcage:

```typescript
import {RC} from "@nartallax/ribcage"

let positivePoint = RC.struct(
	{x: RC.number(), y: RC.number()},
	{
		validators: [point => point.x >= 0 && point.y >= 0]
	}
)

let builder = RCV.getValidatorBuilder()
let validator = builder.build(point)
validator({x: 5, y: 5}) // no error
validator({x: -1, y: 5}) // error
```
npm package: @nartallax/ts-build-utils
Description: A collection of utility scripts for automating build process of TypeScript projects.
Author: Nartallax
Latest version: 1.2.7

# @nartallax/ts-build-utils
A collection of utility scripts that help with build process of TypeScript projects.  
Powered by [ESBuild](https://www.npmjs.com/package/esbuild), [@chialab/esbuild-html-plugin](https://www.npmjs.com/package/@chialab/esbuild-plugin-html), [dts-bundle-generator](https://www.npmjs.com/package/dts-bundle-generator) and more.  

## Install 

```bash
npm install --save-dev @nartallax/ts-build-utils
```

## Use

```js
// Main entrypoint of this package is buildUtils function:
import {buildUtils} from "@nartallax/ts-build-utils"

// This function accepts parameters describing your project
// and creates a bunch of other functions
// (not everything listed here, be sure to check typedefs):
const {
  clear, 
  build, 
  runTests, 
  copyToTarget, 
  npm,
  serve
} = buildUtils({
  buildOptions: {
    entryPoints: ["./src/index.html"]
  }
})

// buildUtils() assumes a lot of stuff,
// like that project has tsconfig.json, 
// and that tsconfig.json has rootDir set;
// this may not always be true, but that's checked, 
// so if something is not there - the script will tell you.
// also override options are there for almost everything;
// you can pass various options to most util functions.

// after acquiring the utils, you may use them to describe your build process:
await clear()
switch(process.argv[2]){
  case "dev": {
    await serve()
  } break

  case "test": {
    await runTests({nameFilter: process.argv[3]})
  } break

  case "publish": {
    await build()
    await copyToTarget("README.md", "LICENSE", "package.json")
    await npm.publish({dryRun: true})
  }
}
```

# Development

```bash
# clone the repo
git clone ssh://git@nartallax.net:nartallax/ts-build-utils

# get into repo's dir
cd ts-build-utils

# set up signing
# also, make sure that `git config --get user.email` is equal to your email in forgejo
git config gpg.format ssh
git config user.signingKey "~/.ssh/id_rsa"

# this one is optional. forgejo will show commits as signed without this step
# but git can panic about missing keys sometimes
echo "$(git config --get user.email) namespaces=\"git\" $(cat ~/.ssh/id_rsa.pub)" >> allowed_signers
git add . && git commit -m "Add new key to allowed_signers" && git push

# enable signing by default
git config commit.gpgsign true
```
npm package: @nartallax/wait-file-change
Description: A command-line utility that waits for some file to change and then exits
Author: Nartallax
Latest version: 1.0.0

# wait-file-change

A command-line utility that waits for some file to change and then exits

## Install

```bash
npm install --save-dev @nartallax/wait-file-change
```

## Use

```bash
./node_modules/.bin/wait-file-change my_file.txt --timeout 3 --delay 0.5 --count 1 --verbose
```

Full list of parameters with their descriptions is available at `--help`:

```bash
./node_modules/.bin/wait-file-change --help
```