# maskr

> A tiny (156B) utility to compare a string against a template mask.

Latest version **0.1.1** (published 2017-06-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install maskr
pnpm add maskr
yarn add maskr
bun add maskr
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2017-06-01 |
| First published | 2017-05-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=4 |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Luke Edwards |
| Maintainers | lukeed |

## Links

- npm: https://www.npmjs.com/package/maskr
- Repository: https://github.com/lukeed/maskr
- Homepage: https://github.com/lukeed/maskr#readme
- Issues: https://github.com/lukeed/maskr/issues
- npm.io page: https://npm.io/package/maskr

## Recent versions

- 0.1.1 (latest) — 2017-06-01
- 0.1.0 — 2017-06-01
- 0.0.0 — 2017-05-30

## README

# maskr [![Build Status](https://travis-ci.org/lukeed/maskr.svg?branch=master)](https://travis-ci.org/lukeed/maskr)

> A tiny (156B) utility to compare a string against a template mask.

[Demo][demo]

Technically, this is still a WIP! See the [Roadmap](#roadmap).

Use this module to compare a value against a desired template. Put differently, you can format a string however you'd like.

This is probably most useful for "masking" `<input />` values. There are no `EventListener`s included in this module

## Install

```
$ npm install --save maskr
```


## Usage

```js
const maskr = require('maskr');
const demo = '(___) ___-____';

maskr(demo, '');
//=> { value:'(___) ___-____', cursor:1 }

maskr(demo, '12345678');
//=> { value:'(123) 456-78__', cursor:12 }

maskr(demo, '1234567890');
//=> { value:'(123) 456-7890', cursor:14 }
```

_**Example `<form />` Usage:** ([demo][demo])_

```js
const maskr = require('maskr');
const form = document.getElementById('form');
const inputs = form.querySelectorAll('input');

function setValue(ev) {
  if (ev !== void 0 && ev.type === 'keydown') {
    ev.preventDefault();
    this._value += ev.key;
  }
  const mask = this.getAttribute('data-mask');
  const { value, cursor } = maskr(mask, this._value);
  // set visible value & cursor position
  this.value = value;
  this.setSelectionRange(cursor, cursor);
}

[].forEach.call(inputs, el => {
  if (!el.hasAttribute('data-mask')) return;
  // init internal tracking
  el._value = el.value || '';
  // first-run if has value
  (el.value.length > 0) && setValue.call(el);
  // attach listeners
  el.onfocus = el.onkeydown = setValue.bind(el);
});
```


## API

### maskr(mask, input)

#### mask

Type: `string`

The template/mask to be used.

#### input

Type: `string`

The value string to match against the `mask`.


## Roadmap

* **1.0**
  - Recognize `_` character only (signifes "any")
  - Find fastest + lightest implementation
* **2.0**
  - Recognize `_` (any), `a` (alpha), and `9` (numeric) characters
  - Likely change API/Type definition
  - Add options: `showEmpty`, custom definitions, ...
* **3.0**
  - Use `?` for optional masked input
  - TBD


## Benchmarks

```
maskr
  --> 6,415,566 ops/sec ±0.31% (94 runs sampled)
```

## License

MIT © [Luke Edwards](https://lukeed.com)

[demo]: https://jsfiddle.net/lukeed/fxcs6ret/

---
_Source: https://npm.io/package/maskr · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._