@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 png-chunks-extract@1.0.0.
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/png-chunks-extract@1.0.5 |
| 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
Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.