tafic/README.md

To ASCII First Impression Converter - normalizes text to closest first impression of reader based on ASCII set.

# TAFIC

**To ASCII First Impression Converter**

TAFIC is a TypeScript library that normalizes any string to its closest ASCII "first impression" to produce a clean ASCII-only string.

---


## Installation

```bash
npm install tafic
```

---


## Quick Start

```javascript
// ESM
import TAFIC from "tafic";

// CommonJS
const TAFIC = require("tafic");

// Normalize text
const dirty = "Héllø, wørld! 👋";
const clean = TAFIC.Normalize(dirty);

console.log(clean); // "Hello, world!"
```

---


## API

### `TAFIC.Normalize(str: string, options?: Options): string`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `skipHardcodedMapping` | `boolean` | `false` | Skip the built-in homoglyph map |
| `removeLeftovers` | `boolean` | `true` | Remove any remaining non-ASCII characters |
| `onLeftovers` | `function` | `null` | Callback with non-ASCII leftovers |

Returns the normalized ASCII-only string.

### Examples

```javascript
import TAFIC from "tafic";

// Basic usage
TAFIC.Normalize("Ηеllο Wοrld!"); // "Hello World!" (Greek → Latin)

// Keep non-ASCII leftovers
TAFIC.Normalize("Café ☕", { removeLeftovers: false }); // "Cafe ☕"

// Detect unconvertible characters
TAFIC.Normalize("Hello 世界", {
    onLeftovers: (chars) => console.log("Could not convert:", chars)
});
```

---


## Examples

See the [`examples/`](./examples) directory for complete usage examples:
- ESM (ECMAScript Modules)
- CommonJS
- TypeScript

---


## Building & Testing

```bash
# Build for production
npm run build

# Run benchmark
npm run testing:benchmark

# Run maintenance scripts
npm run maintaining:hcmap
npm run maintaining:culprits
```

---


## License

This project is licensed under the [ISC License](./LICENSE).