# API reference

Conversion methods, generated capabilities, directional formats, typed options, lifecycle, and failures.

Canonical page: https://libassimp.xyz/docs/api

Every public symbol is available from the single `libassimp` entry.

## `convert` [#convert]

```typescript
import type { AssimpFile, ConvertOptions, ConvertResult } from 'libassimp';

export declare const convert: <Format extends import('libassimp').ExportFormat>(
  files: AssimpFile | readonly AssimpFile[],
  options: ConvertOptions<Format>,
) => Promise<ConvertResult>;
```

Converts one entry file to one canonical target. The first array element is always the entry file. `ConvertOptions` contains `to`, `resolve`, `importOptions`, `postProcess`, and target-specific `exportOptions`.

## `convertFormats` [#convertformats]

```typescript
import type { AssimpFile, ConvertFormatsOptions, ConvertFormatsResult, ConvertTarget } from 'libassimp';

export declare const convertFormats: <const Targets extends readonly [ConvertTarget, ...ConvertTarget[]]>(
  files: AssimpFile | readonly AssimpFile[],
  options: ConvertFormatsOptions<Targets>,
) => Promise<ConvertFormatsResult<Targets>>;
```

Imports once and exports a non-empty target tuple sequentially. Each `ConvertedFormat` contains its literal `format` and ordered files; target order, repeats, and result positions are preserved. There is no caller ID field.

```typescript
import { convertFormats } from 'libassimp';

const bytes = new Uint8Array();
const [ascii, binary] = await convertFormats(
  { name: 'part.glb', bytes },
  {
    targets: [
      { to: 'stl', exportOptions: { binary: false } },
      { to: 'stl', exportOptions: { binary: true } },
    ],
  },
);

console.log(ascii.format, binary.format);
```

## `createAssimp` [#createassimp]

```typescript
import type { Assimp, CreateAssimpOptions } from 'libassimp';

export declare const createAssimp: (options?: CreateAssimpOptions) => Promise<Assimp>;
```

An instance exposes `convert`, `convertFormats`, directional `formats`, `dispose()`, and `Symbol.dispose`. Work is FIFO-serialized per instance; create separate instances for parallel conversions.

`CreateAssimpOptions` has only:

* `wasmUrl`: override the entry's single Wasm URL.
* `wasmBinary`: compile supplied bytes instead of fetching that URL.
* `onLog`: receive runtime diagnostics.

## Static generated data [#static-generated-data]

```typescript
import { assimpCapabilities, conversionEdges, defaultPostProcess } from 'libassimp';

const stl = assimpCapabilities.export.stl.exportOptions;
const glbToStl = conversionEdges.find(({ from, to }) => from === 'glb' && to === 'stl');

console.log(stl.binary.default, glbToStl, defaultPostProcess);
```

* `assimpCapabilities` is the keyed serializable registry: directional import/export metadata, exact export-option descriptors, `ImportOptions`, and `PostProcessDescriptor` data.
* `conversionEdges` is the exact import/export cross-product minus identity pairs. `ConversionEdge` remains a discriminated union of valid pairs.
* `defaultPostProcess` is the default readonly `PostProcessStep` tuple.

Importing these values does not load Wasm.

## Core types [#core-types]

### `AssimpFile` [#assimpfile]

**`AssimpFile`** — One named input or output payload.

- **`name`** (`string`, required)
- **`bytes`** (`Uint8Array<ArrayBufferLike>`, required)

### `ResolveFile` [#resolvefile]

`ResolveFile` returns `Uint8Array | undefined | Promise<Uint8Array | undefined>` for an exact requested sidecar name.

### Options [#options]

`ImportOptions` is the generated exact import configuration. `ExportOptionsByFormat` maps every canonical target to its exact options; `ExportOptionsFor<Format>` indexes that map. `ExportOptionDescriptorsFor<Format>` exposes its runtime descriptors. `OptionDescriptor` describes kind, default, bounds, enum values, applicability, and documentation. No public index signature or raw native property bag exists.

### Formats [#formats]

`ImportFormat` and `ExportFormat` are directional unions. `ImportFormatInfo` describes readable extensions; `ExportFormatInfo` adds target-specific option descriptors. `FormatInfo` is the shared base. Native exporter IDs are private.

### Requests and results [#requests-and-results]

`ConvertTarget`, `ConvertOptions`, `ConvertFormatsOptions`, `ConvertResult`, `ConvertedFormat`, and `ConvertFormatsResult` preserve exact target types. Empty plural target arrays are rejected by both TypeScript and runtime validation.

## Failures [#failures]

`AssimpError` is a normal `Error` with an `AssimpFailureCode`. `AssimpErrorContext` may add `formatIndex`, canonical `format`, exact resolver `fileName`, and `cause`.

**`AssimpFailureCode`** — Stable failure classification carried by {@link AssimpError}. - `NO_FILES` — `convert` was handed an empty array. - `UNSUPPORTED_FORMAT` — the `to` id is not compiled into this entry; the message lists the ids this entry does export. - `INVALID_OPTIONS` — a public option is unknown, has the wrong value, is not applicable to the target, or conflicts with another option. - `RESOLVE_FAILED` — a sidecar resolver threw or rejected. - `IMPORT_FAILED` — assimp could not read the entry file, or a referenced sidecar was missing. Pass the missing bytes through `files` or `resolve`. - `EXPORT_FAILED` — the scene imported but the exporter refused it, for example an export property outside the range the exporter accepts.

- **`toString`** (`() => string`, required)
- **`charAt`** (`(pos: number) => string`, required)
- **`charCodeAt`** (`(index: number) => number`, required)
- **`concat`** (`(...strings: string[]) => string`, required)
- **`indexOf`** (`(searchString: string, position?: number) => number`, required)
- **`lastIndexOf`** (`(searchString: string, position?: number) => number`, required)
- **`localeCompare`** (`{ (that: string): number; (that: string, locales?: string | string[], options?: Intl.CollatorOptions): number; (that: string, locales?: Intl.LocalesArgument, options?: Intl.CollatorOptions): number; }`, required)
- **`match`** (`{ (regexp: string | RegExp): RegExpMatchArray | null; (matcher: { [Symbol.match](string: string): RegExpMatchArray | null; }): RegExpMatchArray | null; }`, required)
- **`replace`** (`{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; (searchValue: { [Symbol.replace](string: string, replaceValue: string): string; }, replaceValue: string): string; (searchValue: { [Symbol.replace](string: string, replacer: (substring: string, ...args: any[]) => string): string; }, replacer: (substring: string, ...args: any[]) => string): string; }`, required)
- **`search`** (`{ (regexp: string | RegExp): number; (searcher: { [Symbol.search](string: string): number; }): number; }`, required)
- **`slice`** (`(start?: number, end?: number) => string`, required)
- **`split`** (`{ (separator: string | RegExp, limit?: number): string[]; (splitter: { [Symbol.split](string: string, limit?: number): string[]; }, limit?: number): string[]; }`, required)
- **`substring`** (`(start: number, end?: number) => string`, required)
- **`toLowerCase`** (`() => string`, required)
- **`toLocaleLowerCase`** (`{ (locales?: string | string[]): string; (locales?: Intl.LocalesArgument): string; }`, required)
- **`toUpperCase`** (`() => string`, required)
- **`toLocaleUpperCase`** (`{ (locales?: string | string[]): string; (locales?: Intl.LocalesArgument): string; }`, required)
- **`trim`** (`() => string`, required)
- **`length`** (`number`, required)
- **`substr`** (`(from: number, length?: number) => string`, required)
- **`valueOf`** (`() => string`, required)
- **`codePointAt`** (`(pos: number) => number | undefined`, required)
- **`includes`** (`(searchString: string, position?: number) => boolean`, required)
- **`endsWith`** (`(searchString: string, endPosition?: number) => boolean`, required)
- **`normalize`** (`{ (form: "NFC" | "NFD" | "NFKC" | "NFKD"): string; (form?: string): string; }`, required)
- **`repeat`** (`(count: number) => string`, required)
- **`startsWith`** (`(searchString: string, position?: number) => boolean`, required)
- **`anchor`** (`(name: string) => string`, required)
- **`big`** (`() => string`, required)
- **`blink`** (`() => string`, required)
- **`bold`** (`() => string`, required)
- **`fixed`** (`() => string`, required)
- **`fontcolor`** (`(color: string) => string`, required)
- **`fontsize`** (`{ (size: number): string; (size: string): string; }`, required)
- **`italics`** (`() => string`, required)
- **`link`** (`(url: string) => string`, required)
- **`small`** (`() => string`, required)
- **`strike`** (`() => string`, required)
- **`sub`** (`() => string`, required)
- **`sup`** (`() => string`, required)
- **`padStart`** (`(maxLength: number, fillString?: string) => string`, required)
- **`padEnd`** (`(maxLength: number, fillString?: string) => string`, required)
- **`trimEnd`** (`() => string`, required)
- **`trimStart`** (`() => string`, required)
- **`trimLeft`** (`() => string`, required)
- **`trimRight`** (`() => string`, required)
- **`matchAll`** (`(regexp: RegExp) => RegExpStringIterator<RegExpExecArray>`, required)
- **`replaceAll`** (`{ (searchValue: string | RegExp, replaceValue: string): string; (searchValue: string | RegExp, replacer: (substring: string, ...args: any[]) => string): string; }`, required)
- **`at`** (`(index: number) => string | undefined`, required)
- **`isWellFormed`** (`() => boolean`, required)
- **`toWellFormed`** (`() => string`, required)
- **`__@iterator@118`** (`() => StringIterator<string>`, required)

```typescript
import { AssimpError, convert } from 'libassimp';

try {
  await convert(
    { name: 'model.glb', bytes: new Uint8Array() },
    { to: 'stl', exportOptions: { binary: true } },
  );
} catch (error) {
  if (error instanceof AssimpError) {
    console.error(error.code, error.formatIndex, error.format, error.fileName, error.cause);
  }
}
```

Codes are `NO_FILES`, `UNSUPPORTED_FORMAT`, `INVALID_OPTIONS`, `RESOLVE_FAILED`, `IMPORT_FAILED`, and `EXPORT_FAILED`. Plural output is atomic: a failed target exposes no partial result.

## Versioning [#versioning]

Before 1.0, minor versions may break the prerelease API. Each removal is recorded in [BREAKING\_CHANGES.md](https://github.com/taucad/libassimp/blob/main/BREAKING_CHANGES.md).