Add a programmatic library API (buffer cores + decodeFile)

Exposes the decode/encode functionality as an importable API alongside
the CLIs, with ESM + CJS builds and TypeScript declarations.

API (src/index.ts):
- decodeBuffer(bytes) -> { format, xml } and encodeBuffer(xml, format,
  { blockSize? }) -> Buffer: pure buffer-in/buffer-out cores for the
  compressed-xml containers, factored out of the file/CLI wrappers.
- decodeMdbBuffer(bytes) -> MdbJson: Jet database -> plain JS object.
- decodeFile(path) -> DecodeResult: reads a file and returns decoded
  values in memory, discriminated by kind (compressed-xml -> xml bytes,
  mdb -> data object). This is the "filename -> decoded JS objects" path.
- the format registry (FORMATS, formatByKey, detectFormatByHeader, …)
  and all supporting types.

Build / packaging:
- build.ts now also emits dist/index.mjs + dist/index.cjs (deps inlined);
  tsconfig.build.json emits self-contained dist/*.d.ts via tsc.
- package.json gains main/module/types/exports; bin unchanged.
- Decode/encode functions now take a minimal local `Logger` interface
  (src/util/logger.ts) instead of winston's type, so winston stays out
  of the published type declarations (consumers don't install it — it's
  bundled). winston loggers remain structurally compatible.

Verified: installed the packed tarball into a clean project and
round-tripped through both `require` (CJS) and `import` (ESM). 81 tests
pass (+9 API tests); types are self-contained (no external imports).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: cinderblock

README.md

@@ -209,6 +209,43 @@ bloat) thanks to fixes in the `v5-fix` branch of the
 context and the fork's `v5-fix` branch for the specific bugs that
 were patched.
 
+## Programmatic API
+
+The package also ships a library API (ESM + CJS, with TypeScript types) — the
+same functions the CLIs are built on.
+
+```ts
+import {
+  decodeFile,
+  decodeBuffer,
+  encodeBuffer,
+  decodeMdbBuffer,
+  formatByKey,
+} from 'electronics-workbench-decoder';
+
+// Filename → decoded JS values (format detected from the file's magic bytes)
+const result = await decodeFile('Design1.ms14');
+if (result.kind === 'compressed-xml') {
+  console.log(result.xml.toString()); // the decoded XML
+} else {
+  console.log(result.data.tables.SYS_COMPONENT.rows); // Jet DB as a JS object
+}
+
+// Buffer in, buffer out — no file I/O
+const { xml } = decodeBuffer(ewprjBytes);
+const ewprj = encodeBuffer(xml, formatByKey('ewprj')!);
+const db = decodeMdbBuffer(prjBytes); // → { format, source, tables: {...} }
+```
+
+Exposed: `decodeFile`, `decodeBuffer`, `encodeBuffer`, `decodeMdbBuffer`, the
+format registry (`FORMATS`, `formatByKey`, `formatForExtension`,
+`detectFormatByHeader`, `detectFileFormat`), and the supporting types
+(`EwbFormat`, `MdbJson`, `DecodeResult`, `DecodedXml`, …).
+
+Decoding covers every supported format. Encoding via the API covers the
+compressed-xml containers (`encodeBuffer`); `.prj` in-place editing remains
+CLI-only (`ewe`).
+
 ## Tests
 
 ```bash
@@ -218,9 +255,10 @@ bun test
 Covers the format registry (extension matching, header detection
 including the Jet magic prefix with leading NUL bytes, on-disk
 detection), encoder filename helpers, `mdb` value normalization
-(`Date` → ISO, OLE blobs → base64), and compressed-xml round-trip
-integration (tiny `.ewprj`, tiny `.ms14`, multi-block payload that
-spans more than one PKWare section, and an empty payload).
+(`Date` → ISO, OLE blobs → base64), the public library API (buffer
+round-trips, `decodeFile` against a temp file), and compressed-xml
+round-trip integration (tiny `.ewprj`, tiny `.ms14`, multi-block
+payload that spans more than one PKWare section, and an empty payload).
 
 ## Development
 

build.ts

@@ -1,26 +1,48 @@
 /**
- * Bundles the two CLIs into self-contained, node-runnable scripts under
- * `dist/`. All dependencies (winston, command-line-args, mdb-reader, the
- * node-pkware fork) are inlined, so the published package declares no
- * runtime dependencies. A `#!/usr/bin/env node` banner makes the output
- * directly executable as the `ewd` / `ewe` bin commands.
+ * Builds everything that ships in the npm package:
+ *
+ * - `dist/ewd.js`, `dist/ewe.js` — the CLIs, CJS bundles with a node shebang.
+ * - `dist/index.mjs`, `dist/index.cjs` — the library API (ESM + CJS).
+ *
+ * All dependencies are inlined, so the published package declares no runtime
+ * dependencies. Type declarations (`dist/index.d.ts` + friends) are emitted
+ * separately by `tsc -p tsconfig.build.json` in the `build` npm script.
  */
 
-import { build } from 'bun';
+import { build, type BuildConfig } from 'bun';
 
-const result = await build({
+async function run(label: string, config: BuildConfig) {
+  const result = await build(config);
+  if (!result.success) {
+    console.error(`build failed: ${label}`);
+    for (const log of result.logs) console.error(log);
+    process.exit(1);
+  }
+  for (const out of result.outputs) console.log(`built ${out.path}`);
+}
+
+// CLIs — CJS bundles, executable.
+await run('clis', {
   entrypoints: ['src/ewd.ts', 'src/ewe.ts'],
   outdir: 'dist',
   target: 'node',
   format: 'cjs',
   banner: '#!/usr/bin/env node',
 });
 
-if (!result.success) {
-  for (const log of result.logs) console.error(log);
-  process.exit(1);
-}
+// Library — ESM and CJS.
+await run('lib-esm', {
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  target: 'node',
+  format: 'esm',
+  naming: '[name].mjs',
+});
 
-for (const out of result.outputs) {
-  console.log(`built ${out.path}`);
-}
+await run('lib-cjs', {
+  entrypoints: ['src/index.ts'],
+  outdir: 'dist',
+  target: 'node',
+  format: 'cjs',
+  naming: '[name].cjs',
+});

package.json

@@ -28,6 +28,17 @@
     "ewd": "dist/ewd.js",
     "ewe": "dist/ewe.js"
   },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist",
     "THIRD-PARTY-LICENSES.md"
@@ -44,7 +55,7 @@
     "check": "biome check",
     "check:fix": "biome check --write",
     "format": "biome format --write",
-    "build": "bun run build.ts",
+    "build": "bun run build.ts && tsc -p tsconfig.build.json",
     "licenses": "bun run scripts/collect-licenses.ts",
     "prepublishOnly": "bun run check && bun run typecheck && bun test && bun run licenses && bun run build"
   },

src/decode.ts

@@ -1,8 +1,8 @@
 import { promises as fs } from 'node:fs';
 import { explode } from 'node-pkware/simple';
-import type winston from 'winston';
-import { detectFormatByHeader, knownFormatsList, MAX_HEADER_LENGTH } from './formats';
-import { bufferToArrayBuffer } from './util/buffer';
+import { detectFormatByHeader, type EwbFormat, knownFormatsList, MAX_HEADER_LENGTH } from './formats';
+import { asBuffer, bufferToArrayBuffer } from './util/buffer';
+import type { Logger } from './util/logger';
 import { UnexpectedValue } from './util/UnexpectedValue';
 
 function decodeBlock(block: Buffer, expectedLength: number): Buffer {
@@ -13,107 +13,82 @@ function decodeBlock(block: Buffer, expectedLength: number): Buffer {
   return result;
 }
 
-export async function decode(filename: string, logger: winston.Logger, outFile = `${filename}.xml`): Promise<void> {
-  if (!filename) throw new Error('No filename provided');
+export interface DecodedXml {
+  /** The detected container format. */
+  format: EwbFormat;
+  /** The decompressed XML bytes. */
+  xml: Buffer;
+}
 
-  const file = await fs.open(filename, 'r');
+/**
+ * Decode a compressed-XML EW container (`.ewprj`, `.ms1x`) held entirely in
+ * memory. Detects the format from the magic header, decompresses every PKWare
+ * section, and returns the concatenated XML. Pure: no file or console I/O.
+ */
+export function decodeBuffer(input: Uint8Array): DecodedXml {
+  const buf = asBuffer(input);
   let pos = 0;
 
-  async function read(length: number) {
-    const { bytesRead, buffer } = await file.read(Buffer.allocUnsafe(length), 0, length, pos);
-
-    pos += bytesRead;
-
-    if (bytesRead !== length) {
-      throw new UnexpectedValue('Failed to read as many bytes as we expect', length, bytesRead);
+  const readBytes = (length: number): Buffer => {
+    if (pos + length > buf.length) {
+      throw new UnexpectedValue('Unexpected end of input', length, buf.length - pos);
     }
-
-    return buffer;
-  }
-
-  async function readNumber(size: 1): Promise<number>;
-  async function readNumber(size: 2): Promise<number>;
-  async function readNumber(size: 3): Promise<number>;
-  async function readNumber(size: 4): Promise<number>;
-  async function readNumber(size: 5): Promise<number>;
-  async function readNumber(size: 6): Promise<number>;
-  async function readNumber(size: 7): Promise<number | bigint>;
-  async function readNumber(size: 8): Promise<number | bigint>;
-  async function readNumber(size: number) {
-    const buffer = await read(size);
-    if ((size === 8 && buffer[6] && buffer[7]) || (size === 7 && buffer[6])) {
-      return buffer.readBigUInt64LE();
+    const slice = buf.subarray(pos, pos + length);
+    pos += length;
+    return slice;
+  };
+
+  // Reads a little-endian unsigned integer of `size` bytes (1-8). Values that
+  // wouldn't fit in a JS safe integer (bytes 6/7 set in a 7/8-byte field)
+  // are rejected rather than silently truncated.
+  const readUInt = (size: number): number => {
+    const slice = readBytes(size);
+    if ((size === 8 && (slice[6] || slice[7])) || (size === 7 && slice[6])) {
+      throw new Error('Cannot handle files this large');
     }
-
-    if (size > 8) throw new RangeError('Cannot handle size > 8');
-
-    // Buffer.readUIntLE() can only handle number up to 6 bytes
-    if (size >= 6) size = 6;
-
-    return buffer.readUIntLE(0, size);
+    // Buffer.readUIntLE handles at most 6 bytes; higher bytes are zero here.
+    return slice.readUIntLE(0, Math.min(size, 6));
+  };
+
+  const header = buf.subarray(0, Math.min(MAX_HEADER_LENGTH, buf.length));
+  const format = detectFormatByHeader(header);
+  if (!format) {
+    throw new UnexpectedValue(
+      `Input doesn't match any known EW format. Supported: ${knownFormatsList()}`,
+      `one of ${knownFormatsList()}`,
+      header.toString('ascii'),
+    );
+  }
+  if (format.kind !== 'compressed-xml') {
+    throw new Error(
+      `Input is "${format.label}" (kind=${format.kind}); decodeBuffer only handles compressed-xml. ` +
+        `Use decodeMdbBuffer for ${format.kind} containers.`,
+    );
   }
 
-  let written = 0;
-
-  try {
-    logger.silly(`Opening ${outFile} for output`);
-    const outputFile = await fs.open(outFile, 'w');
-
-    try {
-      const headerBuffer = await read(MAX_HEADER_LENGTH);
-      const format = detectFormatByHeader(headerBuffer);
-
-      if (!format) {
-        throw new UnexpectedValue(
-          `File header doesn't match any known EW format. Supported: ${knownFormatsList()}`,
-          `one of ${knownFormatsList()}`,
-          headerBuffer.toString('ascii'),
-        );
-      }
-
-      if (format.kind !== 'compressed-xml') {
-        throw new Error(
-          `This file is "${format.label}" (kind=${format.kind}); decode() only handles compressed-xml. ` +
-            `Dispatch through ewd.ts which routes to the correct decoder for each kind.`,
-        );
-      }
-
-      // Rewind past any bytes we read beyond the actual header length.
-      pos -= MAX_HEADER_LENGTH - format.header.length;
-      logger.silly(`Detected format: ${format.label}`);
-
-      const finalLength = await readNumber(8);
-
-      if (typeof finalLength === 'bigint') throw new Error('Cannot handle files this large');
-
-      logger.silly(`Full size: ${finalLength}`);
-
-      let section = -1;
-
-      let decompressedBytesRead = 0;
-
-      while (decompressedBytesRead < finalLength) {
-        section++;
-        const length = await readNumber(4);
-        const blockSize = await readNumber(4);
-
-        logger.silly(`Section #${section} read ${blockSize} bytes, decompresses to ${length}`);
-
-        const compressedData = await read(blockSize);
+  pos = format.header.length;
+  const finalLength = readUInt(8);
+
+  const blocks: Buffer[] = [];
+  let decompressed = 0;
+  while (decompressed < finalLength) {
+    const length = readUInt(4);
+    const blockSize = readUInt(4);
+    const compressed = readBytes(blockSize);
+    blocks.push(decodeBlock(compressed, length));
+    decompressed += length;
+  }
 
-        decompressedBytesRead += length;
+  return { format, xml: Buffer.concat(blocks) };
+}
 
-        const decodedBlock = decodeBlock(compressedData, length);
+export async function decode(filename: string, logger: Logger, outFile = `${filename}.xml`): Promise<void> {
+  if (!filename) throw new Error('No filename provided');
 
-        written += (await outputFile.write(decodedBlock)).bytesWritten;
-      }
+  logger.silly(`Reading ${filename}`);
+  const { format, xml } = decodeBuffer(await fs.readFile(filename));
+  logger.silly(`Detected format: ${format.label}`);
 
-      logger.verbose(`Wrote ${written} bytes to ${outFile}`);
-      logger.silly(`Finished reading file: ${filename}`);
-    } finally {
-      await outputFile.close();
-    }
-  } finally {
-    await file.close();
-  }
+  await fs.writeFile(outFile, xml);
+  logger.verbose(`Wrote ${xml.length} bytes to ${outFile}`);
 }

src/decodeFile.ts

@@ -0,0 +1,43 @@
+import { promises as fs } from 'node:fs';
+import { decodeBuffer } from './decode';
+import { decodeMdbBuffer, type MdbJson } from './decodeMdb';
+import { detectFormatByHeader, type EwbFormat, knownFormatsList, MAX_HEADER_LENGTH } from './formats';
+import { UnexpectedValue } from './util/UnexpectedValue';
+
+/**
+ * The in-memory decoded representation of an EW file, discriminated by the
+ * container kind:
+ *
+ * - `compressed-xml` (`.ewprj`, `.ms1x`): `xml` holds the decompressed XML
+ *   bytes (call `.toString()` for text).
+ * - `mdb` (`.prj`, `.usr`): `data` holds the database as a plain JS object
+ *   (tables → `{ columns, rows }`).
+ */
+export type DecodeResult =
+  | { kind: 'compressed-xml'; format: EwbFormat; xml: Buffer }
+  | { kind: 'mdb'; format: EwbFormat; data: MdbJson };
+
+/**
+ * Read an EW file from disk and decode it into in-memory JS values. The
+ * container format is detected from the file's magic bytes, so the extension
+ * doesn't matter.
+ */
+export async function decodeFile(filename: string): Promise<DecodeResult> {
+  const buf = await fs.readFile(filename);
+  const format = detectFormatByHeader(buf.subarray(0, MAX_HEADER_LENGTH));
+
+  if (!format) {
+    throw new UnexpectedValue(
+      `"${filename}" doesn't match any known EW format. Supported: ${knownFormatsList()}`,
+      `one of ${knownFormatsList()}`,
+      buf.subarray(0, MAX_HEADER_LENGTH).toString('ascii'),
+    );
+  }
+
+  switch (format.kind) {
+    case 'compressed-xml':
+      return { kind: 'compressed-xml', format, xml: decodeBuffer(buf).xml };
+    case 'mdb':
+      return { kind: 'mdb', format, data: decodeMdbBuffer(buf, filename) };
+  }
+}