feat: add support for URL and recursive option in write methods (#284)

Author: targos

src/save/__tests__/write.test.ts

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 
 import { write, writeSync } from '..';
-import { read } from '../..';
+import { read, readSync } from '../..';
 
 let tmpDir: string;
 beforeEach(() => {
@@ -40,36 +41,37 @@ test('async write image to disk (jpeg)', async () => {
   expect(imgRead.colorModel).toBe('RGBA');
 });
 
-test('write image to disk', async () => {
+test('sync write image to disk', () => {
   const img = testUtils.load('opencv/test.png');
   const destination = path.join(tmpDir, 'image.png');
   writeSync(destination, img);
   expect(existsSync(destination)).toBe(true);
-  const imgRead = await read(destination);
+  const imgRead = readSync(destination);
   expect(imgRead).toMatchImage(img);
 });
 
-test('write image to disk (jpeg)', async () => {
+test('sync write image to disk (jpeg)', () => {
   const img = testUtils.load('opencv/test.png');
   const destination = path.join(tmpDir, 'image.jpeg');
   writeSync(destination, img);
   expect(existsSync(destination)).toBe(true);
-  const imgRead = await read(destination);
+  const imgRead = readSync(destination);
   expect(imgRead.width).toBe(img.width);
   expect(imgRead.colorModel).toBe('RGBA');
 });
 
-test('write mask image to disk', async () => {
+test('sync write mask image to disk', () => {
   let img = testUtils.load('opencv/test.png');
   img = img.convertColor('GREY');
   let mask = img.threshold();
   let maskImage = mask.convertColor('GREY');
   const destination = path.join(tmpDir, 'image.png');
   writeSync(destination, mask);
   expect(existsSync(destination)).toBe(true);
-  const imgRead = await read(destination);
+  const imgRead = readSync(destination);
   expect(imgRead).toMatchImage(maskImage);
 });
+
 test('async write mask image to disk', async () => {
   let img = testUtils.load('opencv/test.png');
   img = img.convertColor('GREY');
@@ -82,6 +84,51 @@ test('async write mask image to disk', async () => {
   expect(imgRead).toMatchImage(maskImage);
 });
 
+test('async write with URL', async () => {
+  const img = testUtils.load('opencv/test.png');
+  const destination = pathToFileURL(path.join(tmpDir, 'image.png'));
+  await write(destination, img);
+  expect(existsSync(destination)).toBe(true);
+  const imgRead = await read(destination);
+  expect(imgRead).toMatchImage(img);
+});
+
+test('sync write with URL', () => {
+  const img = testUtils.load('opencv/test.png');
+  const destination = pathToFileURL(path.join(tmpDir, 'image.png'));
+  writeSync(destination, img);
+  expect(existsSync(destination)).toBe(true);
+  const imgRead = readSync(destination);
+  expect(imgRead).toMatchImage(img);
+});
+
+test('async write with recursive option', async () => {
+  const img = testUtils.load('opencv/test.png');
+  const destination = path.join(tmpDir, 'subdir/123', 'image.png');
+  await write(destination, img, { recursive: true });
+  expect(existsSync(destination)).toBe(true);
+  const imgRead = await read(destination);
+  expect(imgRead).toMatchImage(img);
+});
+
+test('sync write with recursive option', () => {
+  const img = testUtils.load('opencv/test.png');
+  const destination = path.join(tmpDir, 'subdir/123', 'image.png');
+  writeSync(destination, img, { recursive: true });
+  expect(existsSync(destination)).toBe(true);
+  const imgRead = readSync(destination);
+  expect(imgRead).toMatchImage(img);
+});
+
+test('unknown format error', () => {
+  const img = testUtils.load('opencv/test.png');
+  const destination = path.join(tmpDir, 'image.png');
+  // @ts-expect-error test invalid format
+  expect(() => writeSync(destination, img, { format: 'foo' })).toThrow(
+    /unknown format: foo/,
+  );
+});
+
 test('image extension error', async () => {
   const img = testUtils.load('opencv/test.png');
   const destination = path.join(tmpDir, 'image.tiff');

src/save/write.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
-import path from 'node:path';
+import { dirname, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 import { Mask, Image } from '..';
 
@@ -10,40 +11,55 @@ import {
   EncodeOptionsJpeg,
 } from './encode';
 
+export interface WriteOptions {
+  /**
+   * If true, attempts to create all the missing directories recursively.
+   */
+  recursive?: boolean;
+}
+
+export type WriteOptionsPng = WriteOptions & EncodeOptionsPng;
+export type WriteOptionsJpeg = WriteOptions & EncodeOptionsJpeg;
+
 /**
  * Write an image to the disk.
  * The file format is determined automatically from the file's extension.
  * If the extension is not supported, an error will be thrown.
  *
- * @param path - Path where the image should be written.
+ * @param path - Path or file URL where the image should be written.
  * @param image - Image to save.
+ * @param options - Write options.
  */
-export async function write(path: string, image: Image | Mask): Promise<void>;
+export async function write(
+  path: string | URL,
+  image: Image | Mask,
+  options?: WriteOptions,
+): Promise<void>;
 /**
  * Write an image to the disk as PNG.
  * When the `png` format is specified, the file's extension doesn't matter.
  *
- * @param path - Path where the image should be written.
+ * @param path - Path or file URL where the image should be written.
  * @param image - Image to save.
  * @param options - Encode options for png images.
  */
 export async function write(
-  path: string,
+  path: string | URL,
   image: Image | Mask,
-  options: EncodeOptionsPng,
+  options: WriteOptionsPng,
 ): Promise<void>;
 /**
  * Write an image to the disk as JPEG.
  * When the `jpeg` format is specified, the file's extension doesn't matter.
  *
- * @param path - Path where the image should be written.
+ * @param path - Path or file URL where the image should be written.
  * @param image - Image to save.
  * @param options - Encode options for jpeg images.
  */
 export async function write(
-  path: string,
+  path: string | URL,
   image: Image | Mask,
-  options: EncodeOptionsJpeg,
+  options: WriteOptionsJpeg,
 ): Promise<void>;
 /**
  * Asynchronously write an image to the disk.
@@ -53,14 +69,21 @@ export async function write(
  * @param options - Encode options.
  */
 export async function write(
-  path: string,
+  path: string | URL,
   image: Image | Mask,
-  options?: EncodeOptionsPng | EncodeOptionsJpeg,
+  options?: WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): Promise<void> {
+  if (typeof path !== 'string') {
+    path = fileURLToPath(path);
+  }
   if (image instanceof Mask) {
     image = image.convertColor('GREY');
   }
   const toWrite = getDataToWrite(path, image, options);
+  if (options?.recursive) {
+    const dir = dirname(path);
+    await fs.promises.mkdir(dir, { recursive: true });
+  }
   await fs.promises.writeFile(path, toWrite);
 }
 
@@ -72,14 +95,21 @@ export async function write(
  * @param options - Encode options.
  */
 export function writeSync(
-  path: string,
+  path: string | URL,
   image: Image | Mask,
-  options?: EncodeOptionsPng | EncodeOptionsJpeg,
+  options?: WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): void {
+  if (typeof path !== 'string') {
+    path = fileURLToPath(path);
+  }
   if (image instanceof Mask) {
     image = image.convertColor('GREY');
   }
   const toWrite = getDataToWrite(path, image, options);
+  if (options?.recursive) {
+    const dir = dirname(path);
+    fs.mkdirSync(dir, { recursive: true });
+  }
   fs.writeFileSync(path, toWrite);
 }
 
@@ -94,11 +124,11 @@ export function writeSync(
 function getDataToWrite(
   destinationPath: string,
   image: Image,
-  options?: EncodeOptionsPng | EncodeOptionsJpeg,
+  options?: WriteOptionsPng | WriteOptionsJpeg | WriteOptions,
 ): Uint8Array {
   let format: ImageFormat;
-  if (options === undefined) {
-    const extension = path.extname(destinationPath).slice(1).toLowerCase();
+  if (!options || !('format' in options)) {
+    const extension = extname(destinationPath).slice(1).toLowerCase();
     if (extension === 'png') {
       format = 'png';
       return encode(image, { format });