@kitschpatrol/aphex 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -4,8 +4,9 @@ import { OmitDeep, PartialDeep, Simplify } from "type-fest";
 
 //#region src/aphex-swift/cli-bridge.d.ts
 /**
- * Start an interactive session with aphex-swift.
- * Commands will be sent to this persistent process instead of spawning new ones.
+ * Start an interactive session with aphex-swift. Commands will be sent to this
+ * persistent process instead of spawning new ones.
+ *
  * @throws {Error} If the session is already active or fails to start
  */
 declare function interactiveSessionStart(): Promise<void>;
@@ -25,8 +26,8 @@ type ResourceInfo = {
   width: number;
 };
 /**
- * TypeScript type definition for the JSON representation of a PHAsset
- * from the iOS Photos framework (CodablePHAsset)
+ * TypeScript type definition for the JSON representation of a PHAsset from the
+ * iOS Photos framework (CodablePHAsset)
  */
 type PhotoInfo = {
   dateCreated: Date;
@@ -49,12 +50,15 @@ type AlbumInfo = {
   uuid: string;
 };
 /**
- * Get photo asset information for given identifiers (ID, filename, album name, or photo path)
+ * Get photo asset information for given identifiers (ID, filename, album name,
+ * or photo path)
+ *
  * @throws {Error} If the command fails
  */
 declare function aphexPhotoInfo(identifiers: string | string[], caseSensitive?: boolean): Promise<PhotoInfo[]>;
 /**
  * Get album info
+ *
  * @throws {Error} If the command fails
  */
 declare function aphexAlbumInfo(identifiers: string | string[], caseSensitive?: boolean): Promise<AlbumInfo[]>;
@@ -65,7 +69,8 @@ type ImageMimeType = (typeof IMAGE_MIME_TYPES)[number];
 //#endregion
 //#region src/pipeline/engines/applescript-gui.d.ts
 /**
- * Mirrors the export UI in Note that note that some options are contingent on others.
+ * Mirrors the export UI in Note that note that some options are contingent on
+ * others.
  *
  * The AppleScript implementation is smart about only "clicking" the necessary
  * options in the GUI.
@@ -120,8 +125,10 @@ type ExportApplePhotoOptions = {
   engineOriginal: ExportEngineOptions;
   engineOriginalAlpha: ExportEngineOptions;
   /**
-   * Append a few digits from the image's local identifier in Photos.app, useful to avoid name collisions if exporting multiple album-worth of photos.
-   * Only applies to `FileNameOptions` `title` or `uuid`. This is NOT the same as a content hash.
+   * Append a few digits from the image's local identifier in Photos.app, useful
+   * to avoid name collisions if exporting multiple album-worth of photos. Only
+   * applies to `FileNameOptions` `title` or `uuid`. This is NOT the same as a
+   * content hash.
    */
   fileNameAppendUuidFragment: boolean;
   fileNameNormalizeExtensions: boolean;
@@ -154,8 +161,8 @@ type ImageTags = {
   credit?: string | undefined; /** Description, used as alt text in HTML content */
   description?: string | undefined;
   /**
-  Image Type, e.g. 'animation', 'diagram', 'illustration', 'screenshot',
-  'image', 'photo', 'render', 'video'
+   * Image Type, e.g. 'animation', 'diagram', 'illustration', 'screenshot',
+   * 'image', 'photo', 'render', 'video'
    */
   label?: Label | undefined;
   preservedFileName?: string | undefined;
@@ -192,20 +199,24 @@ type LossyFormat = 'avif' | 'jpeg' | 'none' | 'webp';
  * Configuration options for image compression.
  *
  * The compression process follows a three-tier approach:
+ *
  * 1. First attempts lossless compression if enabled
  * 2. Falls back to near-lossless compression if lossless exceeds size limit
- * 3. Finally uses lossy compression if other methods fail to meet size requirements
+ * 3. Finally uses lossy compression if other methods fail to meet size
+ *    requirements
  *
  * Set format to 'none' to disable that compression tier.
  */
 type CompressImageOptions = {
   /**
-   * Force compression even if the original image is already within the size limit.
-   * When false, images smaller than maxFileSizeBytes are copied without modification.
+   * Force compression even if the original image is already within the size
+   * limit. When false, images smaller than maxFileSizeBytes are copied without
+   * modification.
    */
   forceCompression: boolean;
   /**
    * Format to use for lossless compression (first attempt).
+   *
    * - 'avif': Best compression but slower encoding
    * - 'png': Good compatibility, optimized with oxipng
    * - 'webp': Good balance of compression and speed
@@ -214,6 +225,7 @@ type CompressImageOptions = {
   losslessFormat: LosslessFormat;
   /**
    * Format to use for lossy compression (final fallback).
+   *
    * - 'avif': Best compression but very slow encoding
    * - 'jpeg': Good compatibility, uses mozjpeg encoder
    * - 'webp': Good balance of compression and speed
@@ -222,19 +234,21 @@ type CompressImageOptions = {
   lossyFormat: LossyFormat;
   /**
    * Quality level for lossy compression (0-1 scale).
+   *
    * - 0: Lowest quality, smallest file size
    * - 1: Highest quality, largest file size
    * - Recommended range: 0.85-0.96 for high-quality images
    */
   lossyQuality: number;
   /**
-   * Maximum allowed file size in bytes.
-   * Images exceeding this size will be compressed using the configured formats.
-   * The compression process stops when this target is met or all options are exhausted.
+   * Maximum allowed file size in bytes. Images exceeding this size will be
+   * compressed using the configured formats. The compression process stops when
+   * this target is met or all options are exhausted.
    */
   maxFileSizeBytes: number;
   /**
    * Format to use for near-lossless compression (second attempt).
+   *
    * - 'webp': Only format currently supporting near-lossless mode
    * - 'none': Skip near-lossless compression
    */
@@ -321,16 +335,18 @@ type SyncResult = {
 /**
  * End the exiftool process gracefully
  *
- * This should be called when you're done using exiftool to prevent
- * hanging processes. It's safe to call multiple times.
+ * This should be called when you're done using exiftool to prevent hanging
+ * processes. It's safe to call multiple times.
  */
 declare function endExiftool(): Promise<void>;
 //#endregion
 //#region src/utilities/log.d.ts
 /**
- * Set the logger instance for the module.
- * Export this for library consumers to inject their own logger.
- * @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+ * Set the logger instance for the module. Export this for library consumers to
+ * inject their own logger.
+ *
+ * @param logger - Accepts either a LogLayer instance or a Console- or
+ *   Stream-like log target
  */
 declare function setLogger(logger?: ILogBasic | ILogLayer<unknown>): void;
 //#endregion

package/dist/index.js

@@ -20,9 +20,11 @@ import { deepEqual } from "fast-equals";
 */
 let log = createLogger("@kitschpatrol/aphex");
 /**
-* Set the logger instance for the module.
-* Export this for library consumers to inject their own logger.
-* @param logger - Accepts either a LogLayer instance or a Console- or Stream-like log target
+* Set the logger instance for the module. Export this for library consumers to
+* inject their own logger.
+*
+* @param logger - Accepts either a LogLayer instance or a Console- or
+*   Stream-like log target
 */
 function setLogger(logger) {
 	log = injectionHelper(logger);
@@ -33,8 +35,8 @@ function setLogger(logger) {
 * Centralized exiftool instance management
 *
 * This module provides a managed exiftool instance with proper lifecycle
-* management to prevent hanging processes. The exiftool-vendored library
-* spawns persistent Perl processes that must be explicitly ended.
+* management to prevent hanging processes. The exiftool-vendored library spawns
+* persistent Perl processes that must be explicitly ended.
 */
 const exiftoolInstance = new ExifTool({
 	maxProcs: 4,
@@ -52,8 +54,8 @@ function getExiftool() {
 /**
 * End the exiftool process gracefully
 *
-* This should be called when you're done using exiftool to prevent
-* hanging processes. It's safe to call multiple times.
+* This should be called when you're done using exiftool to prevent hanging
+* processes. It's safe to call multiple times.
 */
 async function endExiftool() {
 	if (exiftoolInstance.pids.length > 0) {
@@ -65,8 +67,8 @@ async function endExiftool() {
 /**
 * Install process exit handlers for automatic cleanup
 *
-* This ensures exiftool processes are cleaned up even if the user
-* forgets to call endExiftool(). Only installs handlers once.
+* This ensures exiftool processes are cleaned up even if the user forgets to
+* call endExiftool(). Only installs handlers once.
 */
 function scheduleProcessCleanup() {
 	if (processExitHandlerInstalled) return;
@@ -107,9 +109,8 @@ async function getSizeBytes(filePath) {
 	return size;
 }
 /**
-* Normalizes file extensions, particularly for image files
-* Converts to lowercase.
-* Converts .jpg to .jpeg and .tif to .tiff
+* Normalizes file extensions, particularly for image files Converts to
+* lowercase. Converts .jpg to .jpeg and .tif to .tiff
 */
 function normalizeExtension(filePath) {
 	const directory = path.dirname(filePath);
@@ -123,7 +124,9 @@ function normalizeExtension(filePath) {
 }
 /**
 * Converts a filename to a GitHub-style slug format
+*
 * @param filePath - The path of the file
+*
 * @returns The slug version of the filename without extension
 */
 function getSlugFilename(filePath) {
@@ -132,7 +135,9 @@ function getSlugFilename(filePath) {
 /**
 * Ensures the directory for a given file path exists, creating it if necessary.
 * Expands '~' to the user's home directory.
+*
 * @param filePath - The full file path for which to ensure the directory exists
+*
 * @returns The fully expanded directory path which definitely exists
 */
 async function ensureDirectoryExists(filePath) {
@@ -141,7 +146,8 @@ async function ensureDirectoryExists(filePath) {
 	return expandedDirectory;
 }
 /**
-* Creates a temporary directory with an optional custom prefix based on provided labels
+* Creates a temporary directory with an optional custom prefix based on
+* provided labels
 */
 async function getTempDirectory(...labels) {
 	const prefix = labels.length > 0 ? `com.kitschpatrol.aphex.${labels.map((l) => l.toLowerCase()).join(".")}.` : "com.kitschpatrol.aphex.";
@@ -188,8 +194,10 @@ function assertSingleElement(array) {
 //#endregion
 //#region src/utilities/paths.ts
 /**
-* import.meta.dirname for Node >= 20.19.0
-* @example getDirname(import.meta)
+* Import.meta.dirname for Node >= 20.19.0
+*
+* @example
+* 	getDirname(import.meta)
 */
 function getDirname(meta) {
 	return dirname(fileURLToPath(process.env.PISCINA_WORKER_META_URL ?? meta.url));
@@ -209,7 +217,8 @@ function getPackageWorkersPath(meta) {
 	return path.basename(dirname) === "dist" ? path.join(dirname, "workers") : path.join(dirname, "..", "workers");
 }
 /**
-* Binary directory path of package or distribution folder (Copied by native build script)
+* Binary directory path of package or distribution folder (Copied by native
+* build script)
 */
 function getPackageBinPath(meta) {
 	const dirname = getDirname(meta);
@@ -221,8 +230,9 @@ const SHELL_SPECIAL_CHARS_REGEX = /[\s'"\\]/;
 let interactiveProcess;
 let currentRequest;
 /**
-* Start an interactive session with aphex-swift.
-* Commands will be sent to this persistent process instead of spawning new ones.
+* Start an interactive session with aphex-swift. Commands will be sent to this
+* persistent process instead of spawning new ones.
+*
 * @throws {Error} If the session is already active or fails to start
 */
 async function interactiveSessionStart() {
@@ -386,7 +396,9 @@ function assertAlbumInfoArray(value) {
 	if (!isAlbumInfoArray(value)) throw new Error("Invalid AlbumInfo array");
 }
 /**
-* Get photo asset information for given identifiers (ID, filename, album name, or photo path)
+* Get photo asset information for given identifiers (ID, filename, album name,
+* or photo path)
+*
 * @throws {Error} If the command fails
 */
 async function aphexPhotoInfo(identifiers, caseSensitive = false) {
@@ -410,6 +422,7 @@ async function aphexPhotoInfo(identifiers, caseSensitive = false) {
 }
 /**
 * Get album info
+*
 * @throws {Error} If the command fails
 */
 async function aphexAlbumInfo(identifiers, caseSensitive = false) {
@@ -433,6 +446,7 @@ async function aphexAlbumInfo(identifiers, caseSensitive = false) {
 }
 /**
 * Export photos for given identifiers to a destination directory
+*
 * @throws {Error} If the command fails
 */
 async function aphexExport(identifiers, destination, caseSensitive = false, originals = false) {
@@ -464,7 +478,8 @@ function dateReviver$1(key, value) {
 //#endregion
 //#region src/aphex-swift/identifiers.ts
 /**
-* Takes a mix of photos, albums, strings, all resolved to a single array of PhotoInfo objects
+* Takes a mix of photos, albums, strings, all resolved to a single array of
+* PhotoInfo objects
 */
 async function resolveIdentifiers(identifiers) {
 	const photoInfos = identifiers.filter((identifier) => isPhotoInfo(identifier));
@@ -892,8 +907,10 @@ function escapeForAppleScript(text) {
 }
 /**
 * Export a photo via AppleScript using the Photos app's scripting dictionary
+*
 * @param photoUuid - UUID of the photo to export
 * @param forceOriginal - Whether to force export of original version
+*
 * @returns Promise<string> - Path to the exported file
 */
 async function exportViaAppleScript(photoUuid, forceOriginal = false) {
@@ -941,8 +958,8 @@ const defaultExportViaAppleScriptGuiOptions = {
 	tiffBitDepth: 8
 };
 /**
-* Export a photo via the Photos.app GUI to a temporary directory
-* Clean up and move the file as needed afterwards
+* Export a photo via the Photos.app GUI to a temporary directory Clean up and
+* move the file as needed afterwards
 */
 async function exportViaAppleScriptGui(uuid, options) {
 	const tempDirectory = await getTempDirectory("engine", "applescript-gui");
@@ -973,8 +990,8 @@ async function exportViaAppleScriptGui(uuid, options) {
 //#endregion
 //#region src/pipeline/engines/file-system.ts
 /**
-* Export a photo via direct file system copy of the original or edited file to a temporary directory
-* Clean up and move the file as needed afterwards
+* Export a photo via direct file system copy of the original or edited file to
+* a temporary directory Clean up and move the file as needed afterwards
 */
 async function exportViaFileSystem(photoUuid, forceOriginal = false) {
 	const [{ edited, original }] = isPhotoInfo(photoUuid) ? [photoUuid] : await aphexPhotoInfo(photoUuid);
@@ -1136,10 +1153,9 @@ async function getEngineForPhoto(photoInfo, options) {
 	return engine;
 }
 /**
-* Export a single album to a folder
-* Optionally sync the output directory with the album, deleting any images that are no longer in the album
-* Optionally audit the album for duplicate titles
-* Does NOT further process the images
+* Export a single album to a folder Optionally sync the output directory with
+* the album, deleting any images that are no longer in the album Optionally
+* audit the album for duplicate titles Does NOT further process the images
 */
 //#endregion
 //#region src/pipeline/image-metadata.ts
@@ -1207,8 +1223,9 @@ async function optimizePng(imagePath, destinationDirectory) {
 	return destinationImagePath;
 }
 /**
-* Resize a PNG image to fit within a maximum width and height
-* Copies the image unchanged if it already fits within the target size
+* Resize a PNG image to fit within a maximum width and height Copies the image
+* unchanged if it already fits within the target size
+*
 * @returns The destination image path
 */
 async function resizePngToFit(imagePath, destinationDirectory, maxWidth, maxHeight) {
@@ -1314,8 +1331,8 @@ async function convertToWebp(sourceImagePath, destinationDirectory, quality, for
 	return destinationImagePath;
 }
 /**
-* Convert an image to a PNG
-* Supports width / height to help quality comparison tools match target sizes in one step
+* Convert an image to a PNG Supports width / height to help quality comparison
+* tools match target sizes in one step
 */
 async function convertToPng(sourceImagePath, destinationDirectory, force = false, width, height) {
 	const mime = lookupImageMimeType(sourceImagePath, true);
@@ -1347,9 +1364,9 @@ async function convertToPng(sourceImagePath, destinationDirectory, force = false
 	return destinationImagePath;
 }
 /**
-* Convert an image to a TGA
-* Only viable input to mozjpeg is TGA, BMP, and some other esoteric stuff...
-* BMP emitted by sips is too modern for cjpeg, so we need to convert to TGA instead
+* Convert an image to a TGA Only viable input to mozjpeg is TGA, BMP, and some
+* other esoteric stuff... BMP emitted by sips is too modern for cjpeg, so we
+* need to convert to TGA instead
 */
 async function convertToTga(sourceImagePath, destinationDirectory, force = false) {
 	const mime = lookupImageMimeType(sourceImagePath, [
@@ -1495,9 +1512,8 @@ async function compressImage(sourceImagePath, destinationDirectory, options) {
 const SSIM_REGEX = /All:\s*([\d.]+)/;
 const PSNR_REGEX = /average:\s*([\d.]+)/;
 /**
-* Get two identically sized PNGs from two images.
-* Uses the smaller image size as the target size.
-* Remember to clean up temp
+* Get two identically sized PNGs from two images. Uses the smaller image size
+* as the target size. Remember to clean up temp
 */
 async function getTwoIdenticallySizedPng(image1, image2) {
 	const tempDirectory1 = await fse.mkdtemp(path.join(os.tmpdir(), `com.kitschpatrol.aphex.get-two-identically-sized-png.${getSlugFilename(image1)}.`));
@@ -1816,6 +1832,7 @@ async function getSyncPlanForImages(identifiers, destinationDirectory, options,
 }
 /**
 * See if there's a difference between the source image and the target image
+*
 * @returns Undefined if the, or the reason for the difference if found
 */
 async function isDifferent(diffStrategies, sourcePhotoInfo, sourcePhotoFileBaseName, matchPhotoFilePath, matchPhotoTags, exportOptions, forceUpdate) {

package/dist/workers/process-image-worker.js

@@ -7,14 +7,22 @@
  * Worker function for processing images in a separate thread
  *
  * Note: Each worker spawns its own exiftool instance via the centralized
- * exiftool module. These are managed by Piscina's worker lifecycle - when
- * the worker terminates, the exiftool process exit handlers will clean up.
+ * exiftool module. These are managed by Piscina's worker lifecycle - when the
+ * worker terminates, the exiftool process exit handlers will clean up.
+ *
  * @param {object} params - Worker parameters
- * @param {string} params.destinationDirectory - Directory where processed image will be saved
- * @param {import('../pipeline/image-process.ts').ProcessImageOptions} params.options - Image processing options
+ * @param {string} params.destinationDirectory - Directory where processed image
+ *   will be saved
+ * @param {import('../pipeline/image-process.ts').ProcessImageOptions} params.options
+ *   - Image processing options
+ *
  * @param {string} params.sourceImagePath - Path to the source image file
  * @param {boolean} params.verbose - Whether to log verbose output
- * @returns {Promise<import('../pipeline/image-process.ts').ProcessImageResult>} Processing result with input/output info and report
+ *
+ * @returns {Promise<
+ * 	import('../pipeline/image-process.ts').ProcessImageResult
+ * >}
+ *   Processing result with input/output info and report
  */
 export default async function worker({ destinationDirectory, options, sourceImagePath, verbose }) {
 	// Weird workaround after issues with ESM imports in worker threads and more recent versions of Node / TSX / Piscina / etc?
@@ -26,11 +34,13 @@ export default async function worker({ destinationDirectory, options, sourceImag
 	if (verbose) {
 		console.log(`Processing image on worker thread:\n${sourceImagePath}`)
 	}
+
 	const result = await processImage(sourceImagePath, destinationDirectory, options)
 	if (verbose) {
 		console.log(
 			`Finished processing image on worker thread:\n${sourceImagePath}\nTime:\n${result.report.durationMs / 1000} seconds`,
 		)
 	}
+
 	return result
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitschpatrol/aphex",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Apple Photos Export. TypeScript library and CLI tool to export and process images and albums from your macOS Photos.app library.",
   "keywords": [
     "apple",
@@ -42,7 +42,7 @@
     "@sindresorhus/is": "^8.0.0",
     "defu": "^6.1.7",
     "execa": "^9.6.1",
-    "exiftool-vendored": "^35.18.0",
+    "exiftool-vendored": "^35.19.0",
     "fast-equals": "^6.0.0",
     "fs-extra": "^11.3.4",
     "github-slugger": "^2.0.0",
@@ -55,8 +55,8 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@clack/prompts": "^1.2.0",
-    "@kitschpatrol/shared-config": "^7.5.0",
+    "@clack/prompts": "^1.3.0",
+    "@kitschpatrol/shared-config": "^7.5.2",
     "@types/fs-extra": "^11.0.4",
     "@types/node": "~22.18.13",
     "@vitest/coverage-v8": "^4.1.5",

package/readme.md

@@ -9,7 +9,7 @@
 <!-- badges -->
 
 [![NPM Package @kitschpatrol/aphex](https://img.shields.io/npm/v/@kitschpatrol/aphex.svg)](https://npmjs.com/package/@kitschpatrol/aphex)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit/)
 
 <!-- /badges -->