string-masking/README.md

Mask strings while optionally preserving formatting characters

# string-masking

This package masks strings in two ways:

1. Legacy `digit` mode for the original package behavior.
2. Options-based mode for cleaner masking with support for formatted strings.

## What This Repository Does

The repository exports a single function from `index.js`:

```js
const stringMask = require("string-masking");
```

It returns a model in this shape:

```js
{
  status: "success" | "failure",
  response: "masked output or error message"
}
```

Failures also include a `NOTE` field.

## Legacy API

### Keep the last N characters visible

```js
const stringMask = require("string-masking");

const output = stringMask("1234567890", 3);
console.log(output);

// { status: 'success', response: 'XXXXXXX890' }
```

### Keep the first N characters visible

```js
const stringMask = require("string-masking");

const output = stringMask("1234567890", -3);
console.log(output);

// { status: 'success', response: '123XXXXXXX' }
```

### Mask the middle portion

```js
const stringMask = require("string-masking");

const output = stringMask("1234567890", 0);
console.log(output);

// { status: 'success', response: '12XXXXXX90' }
```

## Improved API

Use an options object when you want more control.

### Keep a custom number of characters at the start and end

```js
const stringMask = require("string-masking");

const output = stringMask("ABCD1234EFGH", {
  visibleStart: 2,
  visibleEnd: 2
});

console.log(output);

// { status: 'success', response: 'ABXXXXXXXXGH' }
```

### Preserve separators such as spaces, dashes, and symbols

```js
const stringMask = require("string-masking");

const output = stringMask("4111-1111-1111-1111", {
  visibleEnd: 4,
  preserveFormat: true
});

console.log(output);

// { status: 'success', response: 'XXXX-XXXX-XXXX-1111' }
```

### Mask alternate characters

```js
const stringMask = require("string-masking");

const output = stringMask("ABCDEFGH", {
  alternateMask: true
});

console.log(output);

// { status: 'success', response: 'XBXDXFXH' }
```

### Use the legacy `digit` argument with formatting support

```js
const stringMask = require("string-masking");

const output = stringMask("ABHA-9988-XY12", 4, {
  preserveFormat: true,
  maskChar: "*"
});

console.log(output);

// { status: 'success', response: '****-****-XY12' }
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `visibleStart` | integer | `0` | Number of maskable characters to keep visible at the start |
| `visibleEnd` | integer | `0` | Number of maskable characters to keep visible at the end |
| `preserveFormat` | boolean | `false` | Preserves non-alphanumeric separators while masking |
| `maskChar` | string | `"X"` | Single character used for masking |
| `alternateMask` | boolean | `false` | Masks every other eligible character inside the maskable region |

When `preserveFormat` is `true`, letters and numbers are masked, while characters such as spaces, `-`, `.`, `@`, and `+` stay in place.

When `alternateMask` is `true`, alternating starts from the first character that would otherwise be masked after `visibleStart` and `visibleEnd` are applied.

## Suggestions For Further Improvement

1. Add TypeScript definitions so the options API is easier to consume in editors.
2. Publish a major version when you want to formalize the new options-based API.
3. Add a `maskPattern` option later if you want different masking rules for emails, phones, or IDs.
4. Add CI to run `npm test` automatically before publishing.

## Contribution

Rohan Solse  
Suggestions and recommendations are welcome.  
Contact: `rohansolse@gmail.com`