byte-codec 1.0.0 → 1.0.1

package/.husky/pre-commit

@@ -1,2 +0,0 @@
-# Lint and auto-fix staged TypeScript files.
-pnpm exec lint-staged

package/.husky/pre-push

@@ -1,2 +0,0 @@
-# Run the full test suite before push to catch breakage early.
-pnpm test

package/CHANGELOG.md

@@ -1,12 +0,0 @@
-# 1.0.0 (2026-08-05)
-
-
-### Bug Fixes
-
-* ci test and smoke steps for byte-codec's script set ([a64531d](https://github.com/ExaDev/byte-codec/commit/a64531df7cec8969ffe2f99cb4b100020b549ad4))
-* ci yaml — remove stray key, fix job name, correct alias ([c1c6291](https://github.com/ExaDev/byte-codec/commit/c1c629166831899be2b07f761fafdd130babbe78))
-
-
-### Features
-
-* initial byte-codec package — generic byte/image utilities ([698c6ab](https://github.com/ExaDev/byte-codec/commit/698c6abd755e72e40759569a3ffa6b0f2f5d9f21))

package/commitlint.config.ts

@@ -1,8 +0,0 @@
-import { commitTypes } from './release.config';
-
-export default {
-  extends: ['@commitlint/config-conventional'],
-  rules: {
-    'type-enum': [2, 'always', commitTypes.map((t) => t.type)],
-  },
-};

package/eslint.config.ts

@@ -1,19 +0,0 @@
-import js from '@eslint/js';
-import tseslint from 'typescript-eslint';
-import globals from 'globals';
-
-export default tseslint.config(
-  js.configs.recommended,
-  ...tseslint.configs.recommended,
-  {
-    languageOptions: {
-      globals: { ...globals.node },
-    },
-    rules: {
-      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
-    },
-  },
-  {
-    ignores: ['dist/**', 'node_modules/**'],
-  },
-);

package/release.config.ts

@@ -1,65 +0,0 @@
-import type { Options } from 'semantic-release';
-
-type ReleaseLevel = 'major' | 'minor' | 'patch' | false;
-
-interface CommitType {
-  readonly type: string;
-  readonly release: ReleaseLevel;
-}
-
-/**
- * Single source of truth for the conventional-commit types this project uses. commitlint's allowed type-enum (commitlint.config.ts imports this) and commit-analyzer's releaseRules below both derive from it, so a type can't trigger a release without also being accepted by commit-msg validation, or the reverse.
- *
- * Defined here rather than in a shared commit-types.ts: semantic-release loads this file via cosmiconfig, which transpiles only this one file to ESM, so a sibling .ts module would not resolve. commitlint's jiti loader has no such limit, so it imports commitTypes from here.
- */
-export const commitTypes: readonly CommitType[] = [
-  { type: 'feat', release: 'minor' },
-  { type: 'fix', release: 'patch' },
-  { type: 'perf', release: 'patch' },
-  { type: 'revert', release: 'patch' },
-  { type: 'refactor', release: 'patch' },
-  { type: 'docs', release: 'patch' },
-  { type: 'style', release: 'patch' },
-  { type: 'test', release: 'patch' },
-  { type: 'build', release: 'patch' },
-  { type: 'ci', release: 'patch' },
-  { type: 'chore', release: 'patch' },
-];
-
-/**
- * Runs on `main`. Analyses commits since the last tag, bumps the version, publishes to npmjs.org (trusted OIDC publishing, no stored token -- see .github/workflows/ci.yml), creates a versioned tag and GitHub Release with generated notes, and commits CHANGELOG.md + package.json back to main. The release commit's [skip ci] message avoids a redundant CI run.
- */
-const config: Options = {
-  branches: ['main'],
-  plugins: [
-    [
-      '@semantic-release/commit-analyzer',
-      {
-        preset: 'conventionalcommits',
-        releaseRules: [
-          { breaking: true, release: 'major' },
-          ...commitTypes.map((t) => ({ type: t.type, release: t.release })),
-        ],
-      },
-    ],
-    [
-      '@semantic-release/release-notes-generator',
-      {
-        // Deliberately angular, not conventionalcommits, despite commit-analyzer above using conventionalcommits without issue. conventional-changelog-conventionalcommits@10.2.1 exports its changelog body under the key `template`, but the conventional-changelog-writer version release-notes-generator@14.1.1 bundles only reads `options.mainTemplate` -- so the body silently falls back to the writer's own generic default, whose commit partial doesn't match conventionalcommits' function-based partial signature either. The result is a changelog with a version header and nothing under it, for every commit, with zero custom configuration: confirmed with `preset: 'conventionalcommits'` and no presetConfig at all. angular is release-notes-generator's own tested default and renders correctly. commitTypes above still drives commit-analyzer's releaseRules and commitlint's type-enum; it just can't also drive per-type changelog sections until this is fixed upstream, so there is no per-type `section` field here to go unused.
-        preset: 'angular',
-      },
-    ],
-    '@semantic-release/changelog',
-    ['@semantic-release/npm', { npmPublish: true }],
-    '@semantic-release/github',
-    [
-      '@semantic-release/git',
-      {
-        assets: ['CHANGELOG.md', 'package.json'],
-        message: 'chore(release): ${nextRelease.version} [skip ci]',
-      },
-    ],
-  ],
-};
-
-export default config;

package/src/bytes/crc32.ts

@@ -1,24 +0,0 @@
-// Table-driven CRC32 (polynomial 0xEDB88320, the standard IEEE 802.3 / ZIP / PNG polynomial). fflate exports no CRC32 of its own (only an internal one used by its ZIP writer), and PNG's chunk format requires one per chunk, so this is genuinely new code, not a duplicate of anything already in the tree.
-const CRC32_POLYNOMIAL = 0xedb88320;
-const BYTE_VALUES = 256;
-const BITS_PER_BYTE = 8;
-
-const CRC32_TABLE: Uint32Array = (() => {
-  const table = new Uint32Array(BYTE_VALUES);
-  for (let n = 0; n < BYTE_VALUES; n++) {
-    let c = n;
-    for (let k = 0; k < BITS_PER_BYTE; k++) {
-      c = (c & 1) === 1 ? CRC32_POLYNOMIAL ^ (c >>> 1) : c >>> 1;
-    }
-    table[n] = c >>> 0;
-  }
-  return table;
-})();
-
-export function crc32(bytes: Uint8Array<ArrayBuffer>): number {
-  let crc = 0xffffffff;
-  for (const byte of bytes) {
-    crc = CRC32_TABLE[(crc ^ byte) & 0xff]! ^ (crc >>> 8);
-  }
-  return (crc ^ 0xffffffff) >>> 0;
-}

package/src/bytes/flate.ts

@@ -1,69 +0,0 @@
-import { Unzlib, inflateSync, unzlibSync, zlibSync } from 'fflate';
-import { isAsciiWhitespace } from './reader';
-import { concatBytes } from './writer';
-
-// The only file in the package that imports fflate -- the direct analogue of ooxml.js's own src/zip.ts ("a thin wrapper over fflate's zipSync/unzipSync, isomorphic and dependency-free"). PDF's FlateDecode filter and PNG's IDAT payload both use zlib-framed DEFLATE (RFC 1950 -- a 2-byte header plus a trailing Adler-32 checksum) -- that is zlibSync/unzlibSync, NOT fflate's deflateSync/inflateSync, which are raw DEFLATE (RFC 1951) with no wrapper. Emitting or expecting the wrong framing produces a stream every conformant PDF/PNG reader rejects.
-
-// Guards every call in this module against a maliciously or accidentally huge decompressed output -- both PDF and PNG streams here come from arbitrary, potentially adversarial input.
-export const MAX_INFLATE_OUTPUT_BYTES = 512 * 1024 * 1024;
-
-export type DeflateLevel = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-
-export function deflate(data: Uint8Array<ArrayBuffer>, level?: DeflateLevel): Uint8Array<ArrayBuffer> {
-  return zlibSync(data, level === undefined ? undefined : { level });
-}
-
-export function inflate(data: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer> {
-  const out = unzlibSync(data);
-  if (out.length > MAX_INFLATE_OUTPUT_BYTES) {
-    throw new Error(`inflated output exceeds the ${MAX_INFLATE_OUTPUT_BYTES}-byte limit`);
-  }
-  return out;
-}
-
-export interface InflateResult {
-  readonly bytes: Uint8Array<ArrayBuffer>;
-  readonly recovered: boolean;
-}
-
-// A tolerant inflate for the read path: real-world PDF/PNG streams occasionally carry a leading whitespace byte, are mistakenly raw-DEFLATE under a zlib-labelled filter, or are truncated. Tries, in order: a plain inflate(); skipping leading whitespace and retrying; raw inflateSync (some producers mislabel raw DEFLATE as FlateDecode); and finally the streaming Unzlib class, which emits chunks as they're produced, so a mid-stream truncation still yields whatever decoded successfully before the failure (`recovered: true`) rather than nothing at all.
-export function inflateTolerant(data: Uint8Array<ArrayBuffer>): InflateResult {
-  try {
-    return { bytes: inflate(data), recovered: false };
-  } catch {
-    // fall through to the recovery ladder below
-  }
-
-  let offset = 0;
-  while (offset < data.length && isAsciiWhitespace(data[offset])) {
-    offset++;
-  }
-  if (offset > 0) {
-    try {
-      return { bytes: inflate(data.subarray(offset)), recovered: true };
-    } catch {
-      // fall through
-    }
-  }
-
-  try {
-    return { bytes: inflateSync(data), recovered: true };
-  } catch {
-    // fall through
-  }
-
-  const chunks: Uint8Array<ArrayBuffer>[] = [];
-  const unzlib = new Unzlib((chunk) => {
-    chunks.push(chunk);
-  });
-  try {
-    // Pushed as NOT final: fflate only flushes decoded output incrementally as it's produced when a push is not marked as the stream's end -- marking truncated data `final: true` instead makes it run the end-of-stream/checksum finalisation path, which throws atomically before emitting anything at all (verified empirically against fflate 0.8.3). Since this is already the last-resort recovery tier, skipping checksum verification here is an acceptable trade.
-    unzlib.push(data, false);
-  } catch {
-    // whatever chunks were emitted before the throw are still valid partial output
-  }
-  if (chunks.length === 0) {
-    throw new Error('unable to inflate stream: no data could be recovered');
-  }
-  return { bytes: concatBytes(chunks), recovered: true };
-}

package/src/bytes/reader.ts

@@ -1,73 +0,0 @@
-const ASCII_WHITESPACE_BYTES = new Set([0x00, 0x09, 0x0a, 0x0c, 0x0d, 0x20]);
-
-export function isAsciiWhitespace(byte: number | undefined): boolean {
-  return byte !== undefined && ASCII_WHITESPACE_BYTES.has(byte);
-}
-
-// A forward-only cursor over a byte buffer, with explicit mark()/reset() for the backtracking a tokenizer needs -- e.g. the PDF lexer's `N G R` (a reference) vs `N G obj` (an indirect object header) ambiguity, resolved only by trying to read two integers and a keyword, then rewinding if it doesn't match.
-export class ByteReader {
-  private readonly bytes: Uint8Array<ArrayBuffer>;
-  private position = 0;
-
-  constructor(bytes: Uint8Array<ArrayBuffer>) {
-    this.bytes = bytes;
-  }
-
-  get offset(): number {
-    return this.position;
-  }
-
-  get length(): number {
-    return this.bytes.length;
-  }
-
-  atEnd(): boolean {
-    return this.position >= this.bytes.length;
-  }
-
-  peek(aheadBy = 0): number | undefined {
-    return this.bytes[this.position + aheadBy];
-  }
-
-  next(): number | undefined {
-    const byte = this.bytes[this.position];
-    if (byte !== undefined) {
-      this.position++;
-    }
-    return byte;
-  }
-
-  // Returns a resumption point for reset(); does not itself change position.
-  mark(): number {
-    return this.position;
-  }
-
-  reset(mark: number): void {
-    this.position = mark;
-  }
-
-  seek(offset: number): void {
-    this.position = offset;
-  }
-
-  slice(start: number, end: number): Uint8Array<ArrayBuffer> {
-    return this.bytes.subarray(start, end);
-  }
-
-  skipWhitespace(): void {
-    while (isAsciiWhitespace(this.peek())) {
-      this.position++;
-    }
-  }
-
-  // Consumes `keyword` as a literal ASCII sequence at the current position, advancing past it, and returns true; otherwise leaves the position unchanged and returns false.
-  matchKeyword(keyword: string): boolean {
-    for (let i = 0; i < keyword.length; i++) {
-      if (this.peek(i) !== keyword.charCodeAt(i)) {
-        return false;
-      }
-    }
-    this.position += keyword.length;
-    return true;
-  }
-}

package/src/bytes/writer.ts

@@ -1,45 +0,0 @@
-// A chunked, growable byte-output builder: writes accumulate into a list of chunks rather than repeatedly reallocating and copying one growing buffer, which is O(n^2) for many small writes -- exactly the access pattern the PDF writer (one write per operator) and the PNG encoder (one write per scanline) both have.
-export class ByteWriter {
-  private readonly chunks: Uint8Array<ArrayBuffer>[] = [];
-  private byteLength = 0;
-
-  get length(): number {
-    return this.byteLength;
-  }
-
-  writeBytes(bytes: Uint8Array<ArrayBuffer>): void {
-    if (bytes.length === 0) {
-      return;
-    }
-    this.chunks.push(bytes);
-    this.byteLength += bytes.length;
-  }
-
-  writeByte(byte: number): void {
-    this.writeBytes(new Uint8Array([byte]));
-  }
-
-  // Encodes `text` as UTF-8 (ASCII in practice, for the PDF/PNG syntax this writer produces) and appends it.
-  writeAscii(text: string): void {
-    this.writeBytes(new TextEncoder().encode(text));
-  }
-
-  toBytes(): Uint8Array<ArrayBuffer> {
-    const out = new Uint8Array(this.byteLength);
-    let offset = 0;
-    for (const chunk of this.chunks) {
-      out.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return out;
-  }
-}
-
-// Concatenates a list of byte chunks into one contiguous array without the O(n^2) cost of repeated single-chunk concatenation.
-export function concatBytes(chunks: readonly Uint8Array<ArrayBuffer>[]): Uint8Array<ArrayBuffer> {
-  const writer = new ByteWriter();
-  for (const chunk of chunks) {
-    writer.writeBytes(chunk);
-  }
-  return writer.toBytes();
-}

package/src/image/jpeg-info.ts

@@ -1,90 +0,0 @@
-// A JPEG's compressed byte stream passes through this whole package unchanged in both directions (embedded via a PDF Image XObject's /DCTDecode filter on write; extracted as-is on read) -- the single biggest scope reduction in the hand-written PDF codec, since no JPEG decoder or encoder is needed at all. The one piece of information still needed from a JPEG that isn't available without looking inside it is its pixel dimensions and component count, which the PDF Image XObject dictionary requires (/Width, /Height, /ColorSpace) -- this module recovers exactly that, by scanning marker segments, without decoding a single sample.
-export interface JpegInfo {
-  readonly width: number;
-  readonly height: number;
-  readonly components: number;
-  readonly precision: number;
-  readonly progressive: boolean;
-  // The Adobe APP14 marker's transform byte, if present: 0 = unknown/CMYK-as-is, 1 = YCbCr, 2 = YCCK. A 4-component (CMYK) JPEG with transform 2, or an untagged 4-component JPEG, almost always needs colour inversion (/Decode [1 0 1 0 1 0 1 0]) to render correctly -- a well-known, near-universal convention rather than something this scanner can verify from the bytes alone.
-  readonly adobeTransform: number | undefined;
-}
-
-const SOI = 0xd8;
-const EOI = 0xd9;
-const APP14 = 0xee;
-// SOF0 (baseline), SOF1 (extended sequential Huffman), SOF2 (progressive Huffman), SOF9 (extended sequential arithmetic), SOF10 (progressive arithmetic) -- the marker codes actually used to carry frame dimensions. SOF3/SOF5-7/SOF11/SOF13-15 (lossless / differential / hierarchical variants) are not handled, since they are not produced by mainstream PDF-embedding producers.
-const SOF_MARKERS = new Set([0xc0, 0xc1, 0xc2, 0xc9, 0xca]);
-const PROGRESSIVE_SOF_MARKERS = new Set([0xc2, 0xca]);
-// Markers with no following length/payload: TEM, SOI, EOI, and the eight restart markers.
-const NO_PAYLOAD_MARKERS = new Set([0x01, 0xd8, 0xd9, 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7]);
-
-function requireByte(bytes: Uint8Array<ArrayBuffer>, index: number): number {
-  const value = bytes[index];
-  if (value === undefined) {
-    throw new Error('unexpected end of JPEG data');
-  }
-  return value;
-}
-
-function readUint16BE(bytes: Uint8Array<ArrayBuffer>, offset: number): number {
-  return (requireByte(bytes, offset) << 8) | requireByte(bytes, offset + 1);
-}
-
-// Scans a JPEG file's marker segments for its SOF (start-of-frame) segment, recovering dimensions, component count and progressive-ness without decoding any entropy-coded scan data. Throws if the bytes don't start with SOI or no SOF marker is found before EOI/truncation.
-export function readJpegInfo(bytes: Uint8Array<ArrayBuffer>): JpegInfo {
-  if (requireByte(bytes, 0) !== 0xff || requireByte(bytes, 1) !== SOI) {
-    throw new Error('not a valid JPEG file: missing SOI marker');
-  }
-
-  let offset = 2;
-  let adobeTransform: number | undefined;
-
-  while (offset < bytes.length) {
-    if (bytes[offset] !== 0xff) {
-      offset++;
-      continue;
-    }
-    let markerOffset = offset + 1;
-    while (bytes[markerOffset] === 0xff) {
-      markerOffset++;
-    }
-    const marker = bytes[markerOffset];
-    if (marker === undefined) {
-      break;
-    }
-    offset = markerOffset + 1;
-
-    if (marker === EOI) {
-      break;
-    }
-    if (NO_PAYLOAD_MARKERS.has(marker)) {
-      continue;
-    }
-
-    const segmentLength = readUint16BE(bytes, offset); // includes the 2 length bytes themselves
-
-    if (marker === APP14 && segmentLength >= 14) {
-      adobeTransform = requireByte(bytes, offset + 2 + 11);
-    }
-
-    if (SOF_MARKERS.has(marker)) {
-      const p = offset + 2;
-      const precision = requireByte(bytes, p);
-      const height = readUint16BE(bytes, p + 1);
-      const width = readUint16BE(bytes, p + 3);
-      const components = requireByte(bytes, p + 5);
-      return {
-        width,
-        height,
-        components,
-        precision,
-        progressive: PROGRESSIVE_SOF_MARKERS.has(marker),
-        adobeTransform,
-      };
-    }
-
-    offset += segmentLength;
-  }
-
-  throw new Error('no SOF marker found in JPEG file');
-}