# Utilities

List knowledge packages and the error classes.

https://texform.dev/api/js/utilities

The structured library errors derive from `TexformError` (which extends `Error`) and carry a `kind` discriminator, so one `instanceof TexformError` check catches all of them:

- `TexformError`
  - `TexformParseError` — an operation needed a complete tree but parsing produced none.
  - `TexformEditError` — an invalid `Document` edit.
  - `TexformConfigError` — invalid construction or per-call configuration input.
  - `TexformTransformError` — a transform-engine failure.

`Parser.parse` reports malformed LaTeX through its result object rather than throwing; invalid configuration still throws `TexformConfigError`. Passing `TransformEngine.transform` a document that `hasErrors()` throws `TexformTransformError` with `kind: "transform"`, not the base class.

There is no target-counting helper here. Python's `count_targets`, which tallies command, environment, and character occurrences in a formula, is Python-only. To approximate it, parse the source and walk the `Document` with `findCommands` / `findEnvironments` or the `Node` navigation methods.

## `listPackages`

Kind: function

```ts
listPackages(): PackageInfo[]
```

List all built-in knowledge packages with record counts.

The returned names are the identifiers accepted by the `packages` option of
[KnowledgeBase](/api/js/knowledge-base#KnowledgeBase): `ams`, `base`, `bboldx`,
`boldsymbol`, `braket`, `physics`, `textmacros`.

**Returns** `PackageInfo[]` One [PackageInfo](/api/js/utilities#PackageInfo) per built-in package.

```ts
import { listPackages } from 'texform';

listPackages(); // [ { name: 'ams', commands: 35, environments: 28 }, ... ]
```

- [KnowledgeBase](https://texform.dev/api/js/knowledge-base.md#KnowledgeBase)
- [PackageInfo](https://texform.dev/api/js/utilities.md#PackageInfo)

## `PackageInfo`

Kind: interface

Summary of one built-in knowledge package, returned by [listPackages](/api/js/utilities#listPackages).

| Name | Type | Description |
| --- | --- | --- |
| `name` | string | The package identifier, accepted by the `packages` option. |
| `commands` | number | Number of command records in the package. |
| `environments` | number | Number of environment records in the package. |

- [listPackages](https://texform.dev/api/js/utilities.md#listPackages)

## `TexformError`

Kind: exception

Extends: Error

Base class for every error the library throws.

`TexformError` extends the built-in `Error`, so a single `catch` with an
`instanceof TexformError` check catches all library errors. The
[TexformError.kind](/api/js/utilities#TexformError.kind) discriminator identifies which subsystem raised it.

- [TexformError.kind](https://texform.dev/api/js/utilities.md#TexformError.kind)
- [TexformParseError](https://texform.dev/api/js/utilities.md#TexformParseError)
- [TexformEditError](https://texform.dev/api/js/utilities.md#TexformEditError)
- [TexformConfigError](https://texform.dev/api/js/utilities.md#TexformConfigError)
- [TexformTransformError](https://texform.dev/api/js/utilities.md#TexformTransformError)

#### `kind`

Discriminator naming the subsystem that raised the error: `"parse"`,
`"edit"`, `"config"`, `"transform"`, or `"internal"`.

## `TexformParseError`

Kind: exception

Extends: TexformError

Thrown when source could not be parsed into a complete tree.

[TransformEngine.normalize](/api/js/transform-engine#TransformEngine.normalize) throws this on input that cannot produce a
complete tree, and `Document` construction and editing methods throw it for invalid source strings. Note that [Parser.parse](/api/js/parser#Parser.parse) itself never throws — it
returns a [ParseResult](/api/js/parser#ParseResult) instead.

- [TransformEngine.normalize](https://texform.dev/api/js/transform-engine.md#TransformEngine.normalize)
- [Parser.parse](https://texform.dev/api/js/parser.md#Parser.parse)
- [ParseResult](https://texform.dev/api/js/parser.md#ParseResult)

#### `diagnostics`

The diagnostics describing why parsing could not produce a complete tree.

#### `document`

The partial [Document](/api/js/document#Document) that was recovered, or `null` if none.

## `TexformEditError`

Kind: exception

Extends: TexformError

Thrown by [Document](/api/js/document#Document) editing methods on an invalid edit: editing a
read-only (error) tree, detaching or removing the root, an out-of-bounds
index, or mixing nodes across documents.

- [Document](https://texform.dev/api/js/document.md#Document)

## `TexformConfigError`

Kind: exception

Extends: TexformError

Thrown on invalid construction or per-call configuration: unknown package or
profile names, unknown or snake_case keys, arrays in object positions, and
wrong scalar types. Messages include a camelCase field path.

## `TexformTransformError`

Kind: exception

Extends: TexformError

Thrown on a transform-engine failure, such as an eliminated-form contract
violation, or passing [TransformEngine.transform](/api/js/transform-engine#TransformEngine.transform) a document that
[Document.hasErrors](/api/js/document#Document.hasErrors) or that is bound to a different
[KnowledgeBase](/api/js/knowledge-base#KnowledgeBase) instance.

- [TransformEngine.transform](https://texform.dev/api/js/transform-engine.md#TransformEngine.transform)
- [Document.hasErrors](https://texform.dev/api/js/document.md#Document.hasErrors)
- [KnowledgeBase](https://texform.dev/api/js/knowledge-base.md#KnowledgeBase)

## `TexformConformanceError`

Kind: exception

Extends: TexformEditError

Thrown when a construction, edit, or syntax import violates the knowledge base or the document's structure.

#### `path`

The tree path where the violation was found.

#### `rule`

A stable machine-readable rule code.

## `listRules`

Kind: function

```ts
listRules(): RuleInfo[]
```

List all built-in rewrite rules, sorted by key.

The keys are the identifiers accepted by the `disableRules` option of
[TransformEngine](/api/js/transform-engine#TransformEngine) and reported in [RewriteReport](/api/js/transform-engine#RewriteReport) `rules`. A rule
runs only when the engine's profile selects its level and the knowledge base
enables one of its packages.

**Returns** `RuleInfo[]` One [RuleInfo](/api/js/utilities#RuleInfo) per built-in rule.

```ts
import { listRules } from 'texform';

listRules().find((rule) => rule.key === 'base/over-to-frac');
// { key: 'base/over-to-frac', level: 'authoring', fidelity: 'render', summary: '...', enabledByPackages: ['base'] }
```

- [TransformEngine](https://texform.dev/api/js/transform-engine.md#TransformEngine)
- [RewriteReport](https://texform.dev/api/js/transform-engine.md#RewriteReport)
- [RuleInfo](https://texform.dev/api/js/utilities.md#RuleInfo)

## `RuleInfo`

Kind: interface

Summary of one built-in rewrite rule, returned by [listRules](/api/js/utilities#listRules).

| Name | Type | Description |
| --- | --- | --- |
| `key` | string | Stable rule key, such as `"base/over-to-frac"`, accepted by `disableRules`. |
| `level` | RuleLevel | The first profile that accepts the rule's output. |
| `fidelity` | RuleFidelity | Worst-case equivalence guarantee of the rule. |
| `summary` | string | One-line description of what the rule does. |
| `enabledByPackages` | string[] | Packages that make the rule loadable when any one of them is enabled. |

- [listRules](https://texform.dev/api/js/utilities.md#listRules)

## `RuleFidelity`

Kind: typeAlias

```ts
"math" | "reading" | "render"
```

A rewrite rule's worst-case equivalence guarantee over its declared input
domain, ordered least to most faithful: `math` (mathematical meaning is
preserved, rendering may change), `reading` (notation content, reading order,
and structural roles are preserved), `render` (rendering is equivalent under
the reference renderer).