@stackline/png-chunks-extract

Dependency-free PNG chunk extraction with bounded validation and CRC checks.

Documentation | npm | Issues | Repository

Current package version: 1.0.5

Why this package?

A dependency-free compatibility continuation of [email protected]. It keeps the small synchronous API and valid PNG chunk output while validating each complete chunk envelope and its IEEE CRC-32 before copying payload bytes.

Stackline maintains this package independently. It is not affiliated with or endorsed by Hugh Kennedy or the original project.

Compatibility

| Item | Value | | --- | --- | | Package | @stackline/[email protected] | | Node.js runtime | >=18.0.0 | | CommonJS / primary entry | ./index.js | | ES module entry | ./index.mjs | | Type declarations | ./index.d.ts |

Runtimes and types

• Node.js 18 or newer;
• modern browsers through standard CommonJS or ESM bundlers;
• callable CommonJS and native ESM default entries;
• TypeScript 3.9-compatible CommonJS declarations and modern conditional ESM/CJS declarations;
• zero runtime, optional, peer, and bundled dependencies.

Installation

Install

npm install @stackline/png-chunks-extract

An npm alias preserves an existing dependency key and every root import:

{
  "dependencies": {
    "png-chunks-extract": "npm:@stackline/png-chunks-extract@^1.0.1"
  }
}

Usage

CommonJS returns the callable function directly:

const extractChunks = require('@stackline/png-chunks-extract')
const chunks = extractChunks(pngBytes)

Native ESM has the same function as its default export:

import extractChunks from '@stackline/png-chunks-extract'

const chunks = extractChunks(pngBytes)

pngBytes may be a Uint8Array or Node.js Buffer. Each result has this shape:

[
  { name: 'IHDR', data: Uint8Array.from(/* ... */) },
  { name: 'IDAT', data: Uint8Array.from(/* ... */) },
  { name: 'IEND', data: new Uint8Array(0) }
]

Payloads are detached Uint8Array copies, including when the input is a Buffer. Modifying the input after extraction does not change a result.

Security

Review inputs and the package-specific compatibility limits before processing untrusted data. Report suspected vulnerabilities as described in the security policy.

API Surface

Validation contract

The parser validates the eight-byte PNG signature and requires IHDR to be the first chunk. Before allocating or copying a payload, it proves that the four-byte type, declared payload, and four-byte CRC are all present. Declared payload lengths above PNG's 2^31 - 1 limit fail immediately.

IEEE CRC-32 is checked for every chunk, including IEND. IEND must have a zero-length payload. A valid IEND terminates extraction; trailing bytes are ignored for compatibility with the historical parser. This is a chunk extractor, not a full image decoder: it does not validate the semantics of IHDR, IDAT, color profiles, text chunks, or ancillary chunk names.

Malformed inputs throw synchronous TypeError, RangeError, or Error instances with deterministic messages. See COMPATIBILITY_CONTRACT.md for the exact compatibility and intentional-hardening boundary.

Local Development

git clone https://github.com/alexandroit/stackline-png-chunks-extract.git
cd stackline-png-chunks-extract
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

MIT. Original attribution is preserved in LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.

Credits and original authors

• Stackline maintainers.
• Hugh Kennedy.
• Copyright (c) 2015 Hugh Kennedy.
• Copyright (c) 2026 Stackline maintainers.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.