# harfbuzz-modern-wrapper

> TypeScript wrapper for Harfbuzz font engine with bidirectional Unicode support

Latest version **0.0.1** (published 2023-02-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install harfbuzz-modern-wrapper
pnpm add harfbuzz-modern-wrapper
yarn add harfbuzz-modern-wrapper
bun add harfbuzz-modern-wrapper
```

## Health

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

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.1 |
| Published | 2023-02-11 |
| First published | 2023-02-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 13.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | beanandbean |
| Maintainers | beanandbean |

## Links

- npm: https://www.npmjs.com/package/harfbuzz-modern-wrapper
- Repository: https://github.com/beanandbean/font-mesh-pipeline
- Homepage: https://github.com/beanandbean/font-mesh-pipeline/tree/main/packages/harfbuzz-modern-wrapper
- npm.io page: https://npm.io/package/harfbuzz-modern-wrapper

## Dependencies (2)

- [bidi-js](https://npm.io/package/bidi-js.md) ^1.0.2
- [harfbuzzjs](https://npm.io/package/harfbuzzjs.md) ^0.3.1

## Recent versions

- 0.0.1 (latest) — 2023-02-11

## README

# harfbuzz-modern-wrapper

A TypeScript wrapper for the [HarfBuzz text shaping engine](https://harfbuzz.github.io/), via the official JavaScript binding [harfbuzz/harfbuzzjs](https://github.com/harfbuzz/harfbuzzjs). This implementation also integrates the [Unicode Bidirectional Algorithm](https://unicode.org/reports/tr9/) via [bidi-js](https://github.com/lojjic/bidi-js).

## The HarfBuzz singleton

The HarfBuzz singleton is accessed through
```typescript
import harfbuzz from "harfbuzz-modern-wrapper";
```

This object boots up the HarfBuzz web assembly instance and manages all raw pointers exposed by it.

### Initialisation

To check whether the web assembly instance has been initialized, either check the return value of the sync method `harfbuzz.ready()`, or wait until the async `harfbuzz.init()` method returns.

The web assembly instance is automatically fetched on module load and `harfbuzz.init()` does nothing more than simply waiting for the initialisation to complete. Thus it is safe to invoke this at multiple locations in client code.

### Manage fonts

The following method on the singleton exposes a font to the HarfBuzz instance:
```typescript
createFont(id: string, data: Uint8Array, index: number = 0): Font | undefined
```
Here, `id` is an arbitrary identifier (any previously registered font with the same identifier will automatically be freed), `data` is the content of any file type supported by the HarfBuzz engine and `index` locates a specific font face when the provided file is a TrueType/OpenType Collection.

A registered font instance can be requested through `harfbuzz.getFont(id)` and, when no longer in use, it can be freed by `harfbuzz.freeFont(id)`. Use `harfbuzz.fontIds` to access a list of all currently registered fonts.

### Text shaping

A font instance exposes the following signature for text shaping:
```typescript
type GlyphLayout = { id: number; base: { x: number; y: number } };
Font.shape(text: string): { glyphs: GlyphLayout[]; bounds: { width: number; height: number } };
```

This will convert a Unicode string to a sequence of glyphs in the font file. As per implementation of the HarfBuzz engine, the anchor points of the glyphs will be sorted in a left-to-right order, even if the input text is using a right-to-left script.

Use the methods `font.glyphName(id)` and `font.glyphGeometry(id)` to retrieve information about each specific glyph. The latter will return a sequence of [SVG path commands](https://svgwg.org/specs/paths/#PathData). It is guaranteed that only commands of types `M`, `L`, `Q`, `C` and `Z` will be generated.

All coordinates will be given using the internal metrics defined by the font file. To convert them for display, scale all numbers by a ratio of `fontSize / shapingResult.bounds.height`).

## Glyph Geometry Cache

The glyph geometry cache is a utility to cache the geometric data of each glyph, should you run any post-processing on the retrieved SVG commands — for example, to cache the results of triangulation. A typical invocation looks like the following:

```typescript
import { GlyphGeometryCache, GlyphGeometryFactory } from "harfbuzz-modern-wrapper";

const geometryFactory: GlyphGeometryFactory<T> = (paths, upem) => {
  // analyse `paths` and build a geometry object of type `T`
};
const geometryCache = new GlyphGeometryCache(font, geometryFactory);
```

Now, `geometryCache.glyphGeometry(id)` can be used in place of `font.glyphGeometry(id)` to retrieve the geometry after post-processing.

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