image-utils: replace toBase64/toBuffer with base64 option on each function

Remove standalone toBase64/toBuffer operations. All image functions
(resize, compress, strip) now accept a base64: true option — when set
the output buffer key is replaced with a base64 string. Uses
buffer.toString('base64') directly since util.encode is text/JSON-
oriented and not suitable for binary image data.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mtuchi

packages/image-utils/src/Adaptor.js

@@ -12,6 +12,14 @@ function resolveInput(raw) {
   return Buffer.isBuffer(raw) ? raw : decodeBase64Image(raw);
 }
 
+// util.encode from language-common is text/JSON-oriented (utf-8 encoding).
+// For binary image buffers we encode directly with buffer.toString('base64').
+function applyBase64Option(result, encode) {
+  if (!encode) return result;
+  const { buffer, ...rest } = result;
+  return { ...rest, base64: buffer.toString('base64') };
+}
+
 /**
  * State object
  * @typedef {Object} ImageState
@@ -30,14 +38,15 @@ function resolveInput(raw) {
  * @param {object} [options={}]
  * @param {number} [options.width=1200] - Output width in pixels
  * @param {number} [options.height=1600] - Output height in pixels
+ * @param {boolean} [options.base64=false] - When true, returns `{ base64, width, height }` instead of `{ buffer, width, height }`
  * @state {ImageState}
  * @returns {Operation}
  */
 export function resize(base64ImgOrBuffer, options = {}) {
   return async state => {
     const [resolvedImg, resolvedOptions] = expandReferences(state, base64ImgOrBuffer, options);
     const result = await resizeImage(resolveInput(resolvedImg), resolvedOptions);
-    return composeNextState(state, result);
+    return composeNextState(state, applyBase64Option(result, resolvedOptions.base64));
   };
 }
 
@@ -53,14 +62,15 @@ export function resize(base64ImgOrBuffer, options = {}) {
  * @param {number} [options.maxBytes=716800] - Maximum output file size in bytes
  * @param {number} [options.minQuality=20] - JPEG quality floor (1–100); compression stops here even if maxBytes is not met
  * @param {string} [options.comment] - String to embed in the EXIF UserComment field
+ * @param {boolean} [options.base64=false] - When true, returns `{ base64, size, quality }` instead of `{ buffer, size, quality }`
  * @state {ImageState}
  * @returns {Operation}
  */
 export function compress(base64ImgOrBuffer, options = {}) {
   return async state => {
     const [resolvedImg, resolvedOptions] = expandReferences(state, base64ImgOrBuffer, options);
     const result = await compressImage(resolveInput(resolvedImg), resolvedOptions);
-    return composeNextState(state, result);
+    return composeNextState(state, applyBase64Option(result, resolvedOptions.base64));
   };
 }
 
@@ -71,14 +81,16 @@ export function compress(base64ImgOrBuffer, options = {}) {
  * strip(state.data.photoBase64)
  * @function
  * @param {string|Buffer|Function} base64ImgOrBuffer - Base64 string, data URL, Buffer, or resolver fn
+ * @param {object} [options={}]
+ * @param {boolean} [options.base64=false] - When true, returns `{ base64 }` instead of `{ buffer }`
  * @state {ImageState}
  * @returns {Operation}
  */
-export function strip(base64ImgOrBuffer) {
+export function strip(base64ImgOrBuffer, options = {}) {
   return async state => {
-    const [resolvedImg] = expandReferences(state, base64ImgOrBuffer);
+    const [resolvedImg, resolvedOptions] = expandReferences(state, base64ImgOrBuffer, options);
     const result = await stripImage(resolveInput(resolvedImg));
-    return composeNextState(state, result);
+    return composeNextState(state, applyBase64Option(result, resolvedOptions.base64));
   };
 }
 
@@ -105,42 +117,6 @@ export function metadata(base64ImgOrBuffer) {
   };
 }
 
-/**
- * Convert a Buffer to a base64 string.
- * Writes the base64 string to `state.data`.
- * @example
- * toBase64(state.data.buffer)
- * @function
- * @param {Buffer|Function} bufferOrRef - Buffer or resolver fn
- * @state {ImageState}
- * @returns {Operation}
- */
-export function toBase64(bufferOrRef) {
-  return async state => {
-    const [resolved] = expandReferences(state, bufferOrRef);
-    const base64 = Buffer.isBuffer(resolved) ? resolved.toString('base64') : resolved;
-    return composeNextState(state, base64);
-  };
-}
-
-/**
- * Convert a base64 string or data URL to a Buffer.
- * Writes the Buffer to `state.data`.
- * @example
- * toBuffer(state.data.photoBase64)
- * @function
- * @param {string|Function} base64OrRef - Base64 string, data URL, or resolver fn
- * @state {ImageState}
- * @returns {Operation}
- */
-export function toBuffer(base64OrRef) {
-  return async state => {
-    const [resolved] = expandReferences(state, base64OrRef);
-    const buffer = Buffer.isBuffer(resolved) ? resolved : decodeBase64Image(resolved);
-    return composeNextState(state, buffer);
-  };
-}
-
 export {
   as,
   combine,

packages/image-utils/test/Adaptor.test.js

@@ -5,7 +5,7 @@ import { expect } from 'chai';
 import { Jimp } from 'jimp';
 import piexif from 'piexifjs';
 
-import { resize, compress, strip, metadata, toBase64, toBuffer } from '../src/Adaptor.js';
+import { resize, compress, strip, metadata } from '../src/Adaptor.js';
 import { resizeImage } from '../src/Utils.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -148,6 +148,19 @@ describe('resize', () => {
       expect(finalState.references[0]).to.deep.equal(seed.data);
     });
   });
+
+  describe('base64 option', () => {
+    it('returns { base64, width, height } when base64: true', async () => {
+      const finalState = await resize(
+        toBase64Str('portrait-small.jpg'),
+        { ...DEFAULT_RESIZE_OPTS, base64: true },
+      )(state);
+
+      expect(finalState.data).to.have.keys(['base64', 'width', 'height']);
+      expect(finalState.data.base64).to.be.a('string');
+      expect(finalState.data.base64.length).to.be.greaterThan(0);
+    });
+  });
 });
 
 // ─── compress ────────────────────────────────────────────────────────────────
@@ -272,6 +285,19 @@ describe('compress', () => {
       expect(finalState.references[0]).to.deep.equal(seed.data);
     });
   });
+
+  describe('base64 option', () => {
+    it('returns { base64, size, quality } when base64: true', async () => {
+      const inputBuffer = await getResizedBuffer('portrait-small.jpg');
+      const finalState = await compress(
+        inputBuffer,
+        { ...DEFAULT_COMPRESS_OPTS, base64: true },
+      )(state);
+
+      expect(finalState.data).to.have.keys(['base64', 'size', 'quality']);
+      expect(finalState.data.base64).to.be.a('string');
+    });
+  });
 });
 
 // ─── strip ───────────────────────────────────────────────────────────────────
@@ -329,6 +355,13 @@ describe('strip', () => {
     expect(finalState.data).to.have.keys(['buffer']);
     expect(finalState.data.buffer).to.be.instanceOf(Buffer);
   });
+
+  it('returns { base64 } when base64: true', async () => {
+    const finalState = await strip(toBase64Str('portrait-small.jpg'), { base64: true })(state);
+
+    expect(finalState.data).to.have.keys(['base64']);
+    expect(finalState.data.base64).to.be.a('string');
+  });
 });
 
 // ─── metadata ────────────────────────────────────────────────────────────────
@@ -384,73 +417,34 @@ describe('metadata', () => {
   });
 });
 
-// ─── toBase64 / toBuffer ─────────────────────────────────────────────────────
+// ─── buffer passing between steps ────────────────────────────────────────────
 
-describe('toBase64', () => {
-  it('converts a Buffer to a base64 string', async () => {
-    const buf = toBuf('portrait-small.jpg');
-    const finalState = await toBase64(buf)(state);
-
-    expect(finalState.data).to.be.a('string');
-    expect(finalState.data).to.equal(buf.toString('base64'));
-  });
-
-  it('writes the base64 string to state.data', async () => {
-    const buf = toBuf('portrait-small.jpg');
-    const finalState = await toBase64(buf)(state);
-
-    expect(finalState.data).to.be.a('string');
-    expect(finalState.data.length).to.be.greaterThan(0);
-  });
-
-  it('is a no-op when given a string (already base64)', async () => {
-    const b64 = toBase64Str('portrait-small.jpg');
-    const finalState = await toBase64(b64)(state);
-
-    expect(finalState.data).to.equal(b64);
-  });
-});
-
-describe('toBuffer', () => {
-  it('converts a base64 string to a Buffer', async () => {
-    const b64 = toBase64Str('portrait-small.jpg');
-    const finalState = await toBuffer(b64)(state);
-
-    expect(finalState.data).to.be.instanceOf(Buffer);
-    expect(finalState.data).to.deep.equal(toBuf('portrait-small.jpg'));
-  });
-
-  it('converts a data URL to a Buffer', async () => {
-    const dataUrl = `data:image/jpeg;base64,${toBase64Str('portrait-small.jpg')}`;
-    const finalState = await toBuffer(dataUrl)(state);
-
-    expect(finalState.data).to.be.instanceOf(Buffer);
-    expect(finalState.data).to.deep.equal(toBuf('portrait-small.jpg'));
-  });
-
-  it('is a no-op when given a Buffer', async () => {
-    const buf = toBuf('portrait-small.jpg');
-    const finalState = await toBuffer(buf)(state);
+describe('buffer passing between steps', () => {
+  it('passes buffer from resize() to compress() explicitly', async () => {
+    const resizeState = await resize(toBase64Str('portrait-large.jpg'), DEFAULT_RESIZE_OPTS)(state);
+    const compressState = await compress(resizeState.data.buffer, DEFAULT_COMPRESS_OPTS)(resizeState);
 
-    expect(finalState.data).to.deep.equal(buf);
+    expect(compressState.data.size).to.be.at.most(DEFAULT_COMPRESS_OPTS.maxBytes);
+    expect(compressState.data.buffer).to.be.instanceOf(Buffer);
   });
 
-  it('round-trips a buffer through base64 without data loss', async () => {
-    const resizeState = await resize(toBase64Str('portrait-small.jpg'), DEFAULT_RESIZE_OPTS)(state);
-    const originalBuffer = resizeState.data.buffer;
+  it('passes buffer from resize() to strip() explicitly', async () => {
+    const resizeState = await resize(toBase64Str('with-gps.JPG'), DEFAULT_RESIZE_OPTS)(state);
+    const stripState = await strip(resizeState.data.buffer)(resizeState);
 
-    const b64State = await toBase64(originalBuffer)(resizeState);
-    expect(b64State.data).to.be.a('string');
-
-    const bufState = await toBuffer(b64State.data)(b64State);
-    expect(bufState.data).to.deep.equal(originalBuffer);
+    expect(stripState.data.buffer).to.be.instanceOf(Buffer);
+    expect(stripState.data.buffer[0]).to.equal(0xff);
+    expect(stripState.data.buffer[1]).to.equal(0xd8);
   });
 
-  it('passes a buffer from resize() to compress() as an explicit argument', async () => {
-    const resizeState = await resize(toBase64Str('portrait-large.jpg'), DEFAULT_RESIZE_OPTS)(state);
-    const compressState = await compress(resizeState.data.buffer, DEFAULT_COMPRESS_OPTS)(resizeState);
+  it('base64 output from resize() can be fed directly into compress()', async () => {
+    const resizeState = await resize(
+      toBase64Str('portrait-large.jpg'),
+      { ...DEFAULT_RESIZE_OPTS, base64: true },
+    )(state);
+    expect(resizeState.data.base64).to.be.a('string');
 
+    const compressState = await compress(resizeState.data.base64, DEFAULT_COMPRESS_OPTS)(resizeState);
     expect(compressState.data.size).to.be.at.most(DEFAULT_COMPRESS_OPTS.maxBytes);
-    expect(compressState.data.buffer).to.be.instanceOf(Buffer);
   });
 });