ase-parser

library0.0.18jsnpmunverified

The `ase-parser` library provides a pure JavaScript solution for parsing Aseprite `.aseprite` files into a structured object, enabling programmatic access to sprite data like frames, layers, cels, slices, tilesets, and palettes. Currently at version `0.0.18`, it's actively maintained with a focus on adding support for newer Aseprite features like Aseprite 1.3 fields, tilesets, tilemap layers, and linked cels. It ships with TypeScript types, facilitating its use in modern TypeScript projects. A key differentiator is its minimal footprint, having no runtime dependencies for the core parsing functionality. While examples might utilize libraries like `sharp` for image manipulation, `ase-parser` itself focuses solely on data extraction. The `0.0.x` versioning suggests ongoing development, with feature additions and bug fixes released as needed, and implies that breaking changes could occur in minor versions.

serialization

npm install ase-parser

github ↗package ↗

INSTALL

IMPORT

SIG · ASE-PARSER

ase-parser

serializationjavascriptv0.0.18

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Aseprite

✓ import Aseprite from 'ase-parser';

✗ import { Aseprite } from 'ase-parser';

The main Aseprite class is a default export in ESM environments.

Aseprite

✓ const Aseprite = require('ase-parser');

CommonJS import for the Aseprite class. This is equivalent to the default ESM import.

AsepriteFrame

✓ import type { AsepriteFrame } from 'ase-parser';

✗ import { AsepriteFrame } from 'ase-parser';

Imports specific types (like AsepriteFrame) are named exports, typically used with `import type`.

This quickstart demonstrates how to instantiate and parse an Aseprite file using `ase-parser`, logging basic sprite information. It includes a placeholder for reading a file and basic error handling for file not found.

import Aseprite from 'ase-parser'; import * as fs from 'fs'; // Create a dummy Aseprite file buffer for demonstration // In a real scenario, replace this with fs.readFileSync('./path/to/your.aseprite') const createDummyAsepriteBuffer = (): Buffer => { // This is a minimal, non-functional placeholder buffer. // A real Aseprite file is a complex binary structure. // For actual testing, you would need a valid .aseprite file. const dummyHeader = Buffer.from([ 0x00, 0x00, 0x00, 0x00, // file size 0x01, 0x00, // magic number 0x01, 0x00, // frames 0x10, 0x00, // width 0x10, 0x00, // height // ... many more bytes for a valid Aseprite file ... ]); return dummyHeader; }; const filePath = './my_chocobo.aseprite'; try { const buff = fs.readFileSync(filePath); const aseFile = new Aseprite(buff, filePath); aseFile.parse(); console.log(`Successfully parsed Aseprite file: ${aseFile.name}`); console.log(`Number of frames: ${aseFile.numFrames}`); console.log(`Sprite dimensions: ${aseFile.width}x${aseFile.height}`); if (aseFile.frames.length > 0) { console.log(`First frame cels: ${aseFile.frames[0].cels.length}`); } } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') { console.error(`Error: Aseprite file not found at ${filePath}. Please create one or update the path.`); } else { console.error(`Failed to parse Aseprite file: ${error instanceof Error ? error.message : String(error)}`); } }

Debug

Known issues

gotchaThe package is in `0.0.x` versioning, which means breaking changes may occur in minor or patch releases without strictly adhering to SemVer principles. Always review changelogs when updating.

fix

Pin exact versions (e.g., `"ase-parser": "0.0.18"`) or thoroughly test updates before deploying to production.

affects: >=0.0.1

gotchaThe `sharp` library is frequently used in README examples for image processing after parsing. It is NOT a direct dependency of `ase-parser` itself. Installing `sharp` is optional and only required if you intend to perform image manipulation (e.g., generating PNGs from raw pixel data).

fix

Only install `sharp` (`npm install sharp`) if your application explicitly needs image processing capabilities. If not, omit it from your `package.json`.

affects: >=0.0.1

gotchaEarlier versions (`<0.0.16`) had a bug that could lead to an 'out of range read' error when processing Aseprite files containing specific ICC color profiles, potentially causing crashes during parsing.

fix

Update to `ase-parser@0.0.16` or newer to resolve issues with ICC color profile data processing. This fix improved parsing robustness for certain file types.

affects: <0.0.16

gotchaThe `parse()` method must be explicitly called on the `Aseprite` instance before attempting to access any properties (like `numFrames`, `width`, `height`, `frames`). Forgetting to call `parse()` will result in `undefined` values or errors.

fix

Ensure `aseFile.parse();` is called immediately after instantiating `new Aseprite(buffer, name);` and before accessing any parsed data.

affects: >=0.0.1

Errors

Common errors & fixes

TypeError: aseFile.parse is not a function

The Aseprite class was not correctly imported as a default export in an ESM context, leading to the `Aseprite` variable not being the class constructor itself, or `parse` was accessed before instantiation.

fix

For ESM, use `import Aseprite from 'ase-parser';`. For CommonJS, use `const Aseprite = require('ase-parser');`. Ensure you are calling `new Aseprite(...)` to create an instance.

Error: Cannot read properties of undefined (reading 'width')

The `parse()` method was not called on the Aseprite instance before attempting to access parsed properties like `width`, `height`, or `numFrames`.

fix

After creating `const aseFile = new Aseprite(buff, name);`, you must call `aseFile.parse();` to populate its properties from the Aseprite file data.

Error: Cannot find module 'ase-parser'

The `ase-parser` package is not installed, or the import/require path is incorrect, or your module resolver cannot find it.

fix

Run `npm install ase-parser` or `yarn add ase-parser` to install the package. Verify your `import` or `require` statement matches the package name.

Error: ENOENT: no such file or directory, open './somefile.aseprite'

The file path provided to `fs.readFileSync()` does not point to an existing Aseprite file.

fix

Verify that the file path in `fs.readFileSync('./your_file.aseprite')` is correct and the file exists at that location relative to where your script is run.

Upgrade

Version history

0.0.18latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/TheCyberRonin/ase-parser ↗

packagehttps://www.npmjs.com/package/ase-parser ↗