API reference

Every public symbol is available from the single libassimp entry.

convert

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

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.

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

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

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

AssimpFile

ResolveFile

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

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

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

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

Failures

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

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

Before 1.0, minor versions may break the prerelease API. Each removal is recorded in BREAKING_CHANGES.md.