byte-codec 0.0.0 → 1.0.0

package/src/image/png-encode.ts

@@ -0,0 +1,74 @@
+import { crc32 } from '../bytes/crc32';
+import { deflate } from '../bytes/flate';
+import { ByteWriter, concatBytes } from '../bytes/writer';
+import type { RawImage } from './png-decode';
+import { filterScanlines } from './png-filter';
+
+const PNG_SIGNATURE = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+export interface PngEncodeOptions {
+  // 'adaptive' (the default) picks, per row, whichever of the five PNG filters minimises the sum of the filtered bytes' absolute values -- the PNG spec's own recommended heuristic. 'none' always emits filter type 0, useful for deterministic, human-auditable test output.
+  readonly filter?: 'none' | 'adaptive';
+}
+
+function u32be(value: number): Uint8Array<ArrayBuffer> {
+  const bytes = new Uint8Array(4);
+  new DataView(bytes.buffer).setUint32(0, value);
+  return bytes;
+}
+
+function writeChunk(writer: ByteWriter, type: string, data: Uint8Array<ArrayBuffer>): void {
+  const typeBytes = new TextEncoder().encode(type);
+  writer.writeBytes(u32be(data.length));
+  writer.writeBytes(typeBytes);
+  writer.writeBytes(data);
+  writer.writeBytes(u32be(crc32(concatBytes([typeBytes, data]))));
+}
+
+// IHDR colour type: 0 gray, 2 truecolor(RGB), 4 gray+alpha, 6 truecolor+alpha(RGBA). RawImage's channels/alpha combination maps onto these four (never 3, palette -- this encoder never emits an indexed-colour image, since RawImage carries no palette of its own).
+function colorTypeFor(image: RawImage): number {
+  if (image.channels === 1) {
+    return image.alpha === undefined ? 0 : 4;
+  }
+  return image.alpha === undefined ? 2 : 6;
+}
+
+// Encodes normalised raw pixel data (8 bits per channel, optionally with a separate alpha plane) into PNG file bytes -- the exact inverse of decodePng's RawImage shape.
+export function encodePng(image: RawImage, options: PngEncodeOptions = {}): Uint8Array<ArrayBuffer> {
+  const { width, height, channels, data, alpha } = image;
+  const outChannels = alpha === undefined ? channels : channels + 1;
+  const bytesPerRow = width * outChannels;
+  const pixelCount = width * height;
+
+  const interleaved = new Uint8Array(pixelCount * outChannels);
+  for (let i = 0; i < pixelCount; i++) {
+    const srcBase = i * channels;
+    const dstBase = i * outChannels;
+    for (let c = 0; c < channels; c++) {
+      interleaved[dstBase + c] = data[srcBase + c]!;
+    }
+    if (alpha !== undefined) {
+      interleaved[dstBase + channels] = alpha[i]!;
+    }
+  }
+
+  const filtered = filterScanlines(interleaved, height, bytesPerRow, outChannels, options.filter ?? 'adaptive');
+  const compressed = deflate(filtered);
+
+  const ihdr = new Uint8Array(13);
+  const ihdrView = new DataView(ihdr.buffer);
+  ihdrView.setUint32(0, width);
+  ihdrView.setUint32(4, height);
+  ihdr[8] = 8; // bit depth: always 8, since RawImage is always 8 bits per channel
+  ihdr[9] = colorTypeFor(image);
+  ihdr[10] = 0; // compression method: always 0 (deflate)
+  ihdr[11] = 0; // filter method: always 0 (the five-filter adaptive scheme)
+  ihdr[12] = 0; // interlace method: 0 (no interlacing)
+
+  const writer = new ByteWriter();
+  writer.writeBytes(PNG_SIGNATURE);
+  writeChunk(writer, 'IHDR', ihdr);
+  writeChunk(writer, 'IDAT', compressed);
+  writeChunk(writer, 'IEND', new Uint8Array(0));
+  return writer.toBytes();
+}

package/src/image/png-filter.ts

@@ -0,0 +1,142 @@
+// The five PNG scanline (un)filters (PNG spec section 9.2), shared by the PDF cross-reference stream predictor path (src/pdf/predictors.ts): xref streams are almost always /Predictor 12, which is exactly PNG's "Up" filter applied to fixed-width rows, so this module sits on the critical path for reading modern PDFs, not just for PNG images.
+export type PngFilterType = 0 | 1 | 2 | 3 | 4; // None, Sub, Up, Average, Paeth
+
+function paethPredictor(a: number, b: number, c: number): number {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  if (pa <= pb && pa <= pc) {
+    return a;
+  }
+  if (pb <= pc) {
+    return b;
+  }
+  return c;
+}
+
+// The value a filter type predicts from the left (a), above (b), and above-left (c) samples -- added back in during unfiltering, or subtracted out during filtering. Returning a value from a pure function (rather than assigning inside a switch) sidesteps having to prove a switch over a literal union is exhaustive to a variable declared without an initialiser.
+function isPngFilterType(value: number): value is PngFilterType {
+  return value === 0 || value === 1 || value === 2 || value === 3 || value === 4;
+}
+
+function predictorValue(filterType: PngFilterType, a: number, b: number, c: number): number {
+  if (filterType === 1) {
+    return a;
+  }
+  if (filterType === 2) {
+    return b;
+  }
+  if (filterType === 3) {
+    return Math.floor((a + b) / 2);
+  }
+  if (filterType === 4) {
+    return paethPredictor(a, b, c);
+  }
+  return 0; // None
+}
+
+// Reverses PNG's per-scanline filtering. `data` is the inflated IDAT payload: height rows, each prefixed by one filter-type byte followed by `bytesPerRow` filtered sample bytes. Returns the raw (unfiltered) pixel bytes, height * bytesPerRow long, with the filter-type bytes stripped.
+export function unfilterScanlines(
+  data: Uint8Array<ArrayBuffer>,
+  height: number,
+  bytesPerRow: number,
+  bpp: number,
+): Uint8Array<ArrayBuffer> {
+  const stride = bytesPerRow + 1;
+  if (data.length < height * stride) {
+    throw new Error(
+      `PNG scanline data too short: expected at least ${height * stride} bytes, got ${data.length}`,
+    );
+  }
+  const out = new Uint8Array(height * bytesPerRow);
+  for (let y = 0; y < height; y++) {
+    const filterByte = data[y * stride];
+    if (filterByte === undefined || !isPngFilterType(filterByte)) {
+      throw new Error(`unknown PNG filter type: ${String(filterByte)}`);
+    }
+    const rowStart = y * stride + 1;
+    const outRowStart = y * bytesPerRow;
+    const prevOutRowStart = y > 0 ? outRowStart - bytesPerRow : undefined;
+    for (let x = 0; x < bytesPerRow; x++) {
+      const raw = data[rowStart + x]!;
+      const a = x >= bpp ? out[outRowStart + x - bpp]! : 0;
+      const b = prevOutRowStart === undefined ? 0 : out[prevOutRowStart + x]!;
+      const c = x >= bpp && prevOutRowStart !== undefined ? out[prevOutRowStart + x - bpp]! : 0;
+      out[outRowStart + x] = (raw + predictorValue(filterByte, a, b, c)) & 0xff;
+    }
+  }
+  return out;
+}
+
+function sumOfAbsSigned(bytes: Uint8Array<ArrayBuffer>): number {
+  let sum = 0;
+  for (const byte of bytes) {
+    sum += byte < 128 ? byte : 256 - byte;
+  }
+  return sum;
+}
+
+function filterRowInto(
+  raw: Uint8Array<ArrayBuffer>,
+  rowStart: number,
+  prevRowStart: number | undefined,
+  bytesPerRow: number,
+  bpp: number,
+  filterType: PngFilterType,
+  out: Uint8Array<ArrayBuffer>,
+  outOffset: number,
+): void {
+  for (let x = 0; x < bytesPerRow; x++) {
+    const rawByte = raw[rowStart + x]!;
+    const a = x >= bpp ? raw[rowStart + x - bpp]! : 0;
+    const b = prevRowStart === undefined ? 0 : raw[prevRowStart + x]!;
+    const c = x >= bpp && prevRowStart !== undefined ? raw[prevRowStart + x - bpp]! : 0;
+    out[outOffset + x] = (rawByte - predictorValue(filterType, a, b, c)) & 0xff;
+  }
+}
+
+const ALL_FILTER_TYPES: readonly PngFilterType[] = [0, 1, 2, 3, 4];
+
+// Filters raw (unfiltered) pixel bytes into PNG's per-scanline IDAT payload shape. `strategy: 'none'` always emits filter type 0 (useful for deterministic, human-auditable test output); `'adaptive'` (the default) picks, per row, whichever of the five filters minimises the sum of the filtered bytes' absolute values interpreted as signed -- the heuristic the PNG spec itself recommends.
+export function filterScanlines(
+  raw: Uint8Array<ArrayBuffer>,
+  height: number,
+  bytesPerRow: number,
+  bpp: number,
+  strategy: 'none' | 'adaptive' = 'adaptive',
+): Uint8Array<ArrayBuffer> {
+  const stride = bytesPerRow + 1;
+  const out = new Uint8Array(height * stride);
+  const candidate = new Uint8Array(bytesPerRow);
+
+  for (let y = 0; y < height; y++) {
+    const rowStart = y * bytesPerRow;
+    const prevRowStart = y > 0 ? rowStart - bytesPerRow : undefined;
+    const outRowStart = y * stride;
+
+    if (strategy === 'none') {
+      out[outRowStart] = 0;
+      filterRowInto(raw, rowStart, prevRowStart, bytesPerRow, bpp, 0, out, outRowStart + 1);
+      continue;
+    }
+
+    let bestType: PngFilterType = 0;
+    let bestSum = Number.POSITIVE_INFINITY;
+    let best: Uint8Array<ArrayBuffer> | undefined;
+    for (const filterType of ALL_FILTER_TYPES) {
+      filterRowInto(raw, rowStart, prevRowStart, bytesPerRow, bpp, filterType, candidate, 0);
+      const sum = sumOfAbsSigned(candidate);
+      if (sum < bestSum) {
+        bestSum = sum;
+        bestType = filterType;
+        best = candidate.slice();
+      }
+    }
+    out[outRowStart] = bestType;
+    if (best !== undefined) {
+      out.set(best, outRowStart + 1);
+    }
+  }
+  return out;
+}

package/src/index.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { crc32, encodePng, decodePng, readJpegInfo, ByteWriter, concatBytes } from './index';
+
+describe('byte-codec smoke', () => {
+  it('crc32 produces a consistent hash for known input', () => {
+    expect(crc32(new Uint8Array([1, 2, 3, 4]))).toBe(crc32(new Uint8Array([1, 2, 3, 4])));
+  });
+
+  it('encodePng then decodePng round-trips a small image', () => {
+    const pixels = new Uint8Array([255, 0, 0, 0, 255, 0, 0, 0, 255, 255, 255, 0]);
+    const png = encodePng({ width: 2, height: 2, channels: 3, data: pixels });
+    const decoded = decodePng(png);
+    expect(decoded.width).toBe(2);
+    expect(decoded.height).toBe(2);
+  });
+
+  it('ByteWriter accumulates and produces concatenated output', () => {
+    const w = new ByteWriter();
+    w.writeByte(1);
+    w.writeByte(2);
+    w.writeByte(3);
+    expect(Array.from(w.toBytes())).toEqual([1, 2, 3]);
+  });
+
+  it('concatBytes joins arrays', () => {
+    const result = concatBytes([new Uint8Array([1, 2]), new Uint8Array([3, 4])]);
+    expect(Array.from(result)).toEqual([1, 2, 3, 4]);
+  });
+
+  it('readJpegInfo throws for non-JPEG input', () => {
+    expect(() => readJpegInfo(new Uint8Array([0, 0, 0]))).toThrow(/JPEG/);
+  });
+});

package/src/index.ts

@@ -0,0 +1,9 @@
+// The shared byte/image utility package for the documents.js family: generic byte-level primitives (ByteWriter, ByteReader, CRC-32, deflate/inflate) and PNG/JPEG image encoding/decoding with zero PDF knowledge. Extracted from pdf-codec (where they lived as a directory-isolated subgraph with no PDF imports) so both pdf-codec and documents.js consume them from a neutral home rather than one fetching byte utilities from a backend.
+export * from './bytes/writer';
+export * from './bytes/reader';
+export * from './bytes/crc32';
+export * from './bytes/flate';
+export * from './image/png-encode';
+export * from './image/png-decode';
+export * from './image/png-filter';
+export * from './image/jpeg-info';

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "target": "ES2024",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2024"],
+    "types": ["node"],
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['src/**/*.ts', '!src/**/*.test.ts'],
+  root: 'src',
+  format: ['esm', 'cjs'],
+  dts: true,
+  platform: 'neutral',
+  clean: true,
+});