AAB Parser

1.0.1 verified Sun Apr 19 auth: no javascript

aab-parser is a lightweight, asynchronous Android App Bundle (AAB) parser written entirely in TypeScript. It provides functionality to extract key manifest attributes from an AAB file, either as a strongly typed `Manifest` object (a subset of common attributes) or a raw JSON object with more comprehensive data. A key differentiator is its pure Node.js implementation, which means it does not require a Java Development Kit (JDK) installation, unlike many other AAB inspection tools. The current stable version is 1.0.1, released recently after its initial 1.0.0 debut, suggesting an early but active development phase with releases focused on stability and minor enhancements rather than a fixed cadence. It is primarily used for programmatic inspection of AAB metadata in build pipelines or analysis tools.

Common errors

error SyntaxError: await is only valid in async functions and the top level bodies of modules ↓

cause Attempting to use `await` outside an `async` function or in a CommonJS module that doesn't support top-level await.

fix

Wrap your code calling parseAabManifest or parseAabManifestJSON in an async function, or ensure your project is configured as an ESM module with Node.js version supporting top-level await (Node.js 14.8+).

error Error: ENOENT: no such file or directory, open 'path/to/your/bundle.aab' ↓

cause The provided path to the AAB file is incorrect, or the file does not exist at that location.

fix

Verify the file path is correct and accessible. Use an absolute path or ensure the relative path is correct from where your script is executed.

error TypeError: Cannot read properties of undefined (reading 'packageName') ↓

cause Attempting to access properties on the result of `parseAabManifest` or `parseAabManifestJSON` when the parsing failed or returned an unexpected value (e.g., due to a corrupt AAB).

fix

Always include error handling (try...catch) around AAB parsing calls. Log the error to understand the underlying cause. Ensure the AAB file is valid and not corrupt.

Warnings

gotcha The `Manifest` type and the `parseAabManifest` function return a strict subset of AAB manifest attributes. If you require full, untyped manifest data, use `parseAabManifestJSON` instead. ↓

fix For comprehensive manifest data, invoke `parseAabManifestJSON` which returns a plain object containing all parsed fields from the manifest XML.

gotcha All parsing functions in `aab-parser` are asynchronous and return Promises. Synchronous usage will result in an unhandled promise rejection or a `TypeError` if `await` is not used correctly. ↓

fix Always use `await` with `parseAabManifest` and `parseAabManifestJSON` within an `async` function, or ensure your environment supports top-level `await`.

gotcha The README example uses CommonJS `require()`. While this might work, in modern TypeScript and Node.js projects, ESM `import` statements are preferred for better type inference, tree-shaking, and consistency. Mixing module systems can lead to build or runtime issues. ↓

fix Adopt ESM `import { parseAabManifest, Manifest } from 'aab-parser';` for clarity and compatibility in TypeScript projects. Ensure your `tsconfig.json` and `package.json` are configured for ESM (e.g., `"type": "module"`).

Install

npm install aab-parser

yarn add aab-parser

pnpm add aab-parser

Imports

parseAabManifest
wrong
```
const aabParser = require('aab-parser'); aabParser.parseAabManifest(...);
```
correct
```
import { parseAabManifest } from 'aab-parser';
```
Preferred ESM named import for functions. CommonJS `require` can lead to incorrect type inference or module resolution issues in modern TypeScript/Node.js environments.
parseAabManifestJSON
wrong
```
const { parseAabManifestJSON } = require('aab-parser');
```
correct
```
import { parseAabManifestJSON } from 'aab-parser';
```
ESM named import for accessing the function that returns the full manifest as a plain JSON object.
Manifest
wrong
```
import { Manifest } from 'aab-parser';
```
correct
```
import type { Manifest } from 'aab-parser';
```
Use `import type` for type declarations to ensure they are stripped during compilation, preventing potential runtime errors or bundle size increases.

Quickstart

Demonstrates how to asynchronously parse an Android App Bundle (AAB) file to extract its manifest information using `parseAabManifest`, showing the typed output and handling potential file errors.

import { parseAabManifest, Manifest } from 'aab-parser';
import * as path from 'path';
import { promises as fs } from 'fs';

// Ensure you have an 'example.aab' file in your project root or specify a path.
// For testing, you might use a dummy AAB or a real one from a build process.
const AAB_FILE_PATH = process.env.AAB_PATH ?? path.join(__dirname, 'example.aab');

async function main() {
  try {
    // Create a dummy AAB file for demonstration if it doesn't exist
    // In a real scenario, this file would be provided.
    try {
        await fs.access(AAB_FILE_PATH);
    } catch (error) {
        console.warn(`AAB file not found at ${AAB_FILE_PATH}. This example requires an AAB file to run fully.`);
        console.warn("Creating a placeholder. Please replace with a real AAB for actual parsing.");
        await fs.writeFile(AAB_FILE_PATH, Buffer.from('PK\x03\x04... (truncated for brevity, a real AAB is much larger)', 'binary'));
    }

    console.log(`Parsing AAB manifest from: ${AAB_FILE_PATH}`);
    const manifest: Manifest = await parseAabManifest(AAB_FILE_PATH);

    console.log('Parsed AAB Manifest:');
    console.log(manifest);

    // Example of accessing specific fields
    console.log(`Package Name: ${manifest.packageName}`);
    console.log(`Version Code: ${manifest.versionCode}`);
    console.log(`Version Name: ${manifest.versionName}`);

  } catch (error) {
    console.error('Error parsing AAB manifest:', error);
  }
}

main();