pixeli 0.1.9 → 1.0.4

package/dist/validators/outputFile.d.ts

@@ -0,0 +1,2 @@
+import z from 'zod';
+export declare const outputFileValidator: z.ZodString;

package/dist/validators/outputFile.js

@@ -0,0 +1,7 @@
+import path from 'node:path';
+import z from 'zod';
+import { SUPPORTED_OUTPUT_FORMATS } from '../core/helpers.js';
+export const outputFileValidator = z.string().refine((outputPath) => {
+    const extension = path.extname(outputPath).replace('.', '');
+    return SUPPORTED_OUTPUT_FORMATS.includes(extension);
+}, 'output image format is invalid');

package/dist/validators/path.d.ts

@@ -0,0 +1,3 @@
+import z from 'zod';
+export declare const filePathValidator: z.ZodString;
+export declare const dirPathValidator: z.ZodString;

package/dist/validators/path.js

@@ -0,0 +1,18 @@
+import { stat } from 'node:fs/promises';
+import z from 'zod';
+export const filePathValidator = z.string().refine(async (path) => {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}, { error: 'File path does not exist or is invalid.' });
+export const dirPathValidator = z.string().refine(async (path) => {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}, { error: 'Directory path does not exist or is invalid.', abort: true });

package/dist/validators/sharpImageInput.d.ts

@@ -0,0 +1,3 @@
+import z from 'zod';
+export declare const sharpImageValidation: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Buffer<ArrayBufferLike>, Buffer<ArrayBufferLike>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>]>;
+export type SharpImageInput = z.infer<typeof sharpImageValidation>;

package/dist/validators/sharpImageInput.js

@@ -0,0 +1,6 @@
+import z from 'zod';
+export const sharpImageValidation = z.union([
+    z.string(),
+    z.instanceof(Buffer), // technically redundant, but verbose
+    z.instanceof(Uint8Array),
+]);

package/dist/validators/template.d.ts

@@ -0,0 +1,15 @@
+import z from 'zod';
+export declare const templateValidator: z.ZodObject<{
+    canvas: z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        columns: z.ZodNumber;
+        rows: z.ZodNumber;
+    }, z.z.core.$strip>;
+    slots: z.ZodArray<z.ZodObject<{
+        col: z.ZodNumber;
+        row: z.ZodNumber;
+        colSpan: z.ZodNumber;
+        rowSpan: z.ZodNumber;
+    }, z.z.core.$strip>>;
+}, z.z.core.$strip>;

package/dist/validators/template.js

@@ -0,0 +1,41 @@
+import z from 'zod';
+export const templateValidator = z
+    .object({
+    canvas: z.object({
+        width: z.number().int().positive(),
+        height: z.number().int().positive(),
+        columns: z.number().int().positive(),
+        rows: z.number().int().positive(),
+    }),
+    slots: z.array(z.object({
+        col: z.number().int().positive(),
+        row: z.number().int().positive(),
+        colSpan: z.number().int().positive(),
+        rowSpan: z.number().int().positive(),
+    })),
+})
+    .superRefine((opts, ctx) => {
+    // Ensure slots do not overlap
+    const result = validateSlotOverlaps(opts.slots);
+    if (!result.success) {
+        const [i, j] = result.overlaps;
+        ctx.addIssue({ code: 'custom', message: `slot ${i} overlaps with slot ${j}` });
+    }
+});
+const validateSlotOverlaps = (slots) => {
+    for (let i = 0; i < slots.length; i++) {
+        const A = slots[i];
+        const A_right = A.col + A.colSpan - 1;
+        const A_bottom = A.row + A.rowSpan - 1;
+        for (let j = i + 1; j < slots.length; j++) {
+            const B = slots[j];
+            const B_right = B.col + B.colSpan - 1;
+            const B_bottom = B.row + B.rowSpan - 1;
+            const overlap = A.col <= B_right && A_right >= B.col && A.row <= B_bottom && A_bottom >= B.row;
+            if (overlap) {
+                return { success: false, overlaps: [i, j] };
+            }
+        }
+    }
+    return { success: true };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixeli",
-  "version": "0.1.9",
+  "version": "1.0.4",
   "description": "A lightweight command-line tool for merging multiple images into customizable grid layouts.",
   "homepage": "https://github.com/pakdad-mousavi/pixeli#readme",
   "bugs": {
@@ -11,16 +11,21 @@
     "url": "git+https://github.com/pakdad-mousavi/pixeli.git"
   },
   "bin": {
-    "pixeli": "bin/pixeli.js"
+    "pixeli": "./dist/cli/index.js"
   },
   "license": "MIT",
   "author": "Pakdad Mousavi",
   "type": "module",
-  "main": "index.js",
+  "main": "./dist/core/index.js",
+  "types": "./dist/core/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    }
+  },
   "files": [
-    "/lib",
-    "/bin",
-    "/commands"
+    "dist"
   ],
   "keywords": [
     "cli",
@@ -30,14 +35,26 @@
     "image-merge"
   ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "tsc --watch",
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "ajv": "^8.17.1",
     "chalk": "^5.6.2",
     "cli-progress": "^3.12.0",
     "commander": "^14.0.2",
     "sharp": "^0.34.5",
-    "table": "^6.9.0"
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/cli-progress": "^3.11.6",
+    "@types/node": "^25.0.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "prettier": "^3.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
   }
 }

package/bin/pixeli.js

@@ -1,26 +0,0 @@
-#!/usr/bin/env node
-
-import { Command } from 'commander';
-import mergeCommand from '../commands/merge/index.js';
-import { configureCommandErrors, handleError } from '../lib/helpers/utils.js';
-
-const program = new Command();
-
-// Define program
-program
-  .name('pixeli')
-  .description('A lightweight command-line tool for merging multiple images into customizable grid layouts.')
-  .version('1.0.0');
-
-// Add subcommands
-program.addCommand(mergeCommand);
-
-// Configure errors for all subcommands
-configureCommandErrors(program);
-
-// Parse arguments
-try {
-  program.parse();
-} catch (e) {
-  handleError(e);
-}

package/commands/merge/collage.js

@@ -1,83 +0,0 @@
-import { Command } from 'commander';
-import chalk from 'chalk';
-import {
-  cliConfirm,
-  displayInfoMessage,
-  displaySuccessMessage,
-  displayWarningMessage,
-  handleError,
-  writeImage,
-} from '../../lib/helpers/utils.js';
-import { validateCollageOptions, validateSharedOptions } from './helpers/validations.js';
-import { loadImages } from '../../lib/helpers/loadImages.js';
-import { addSharedOptions } from './helpers/utils.js';
-import { validateTemplate } from '../../lib/helpers/templateValidator.js';
-import { collageMerge } from '../../lib/merges/collage-merge/index.js';
-
-const collageCommand = new Command('collage');
-
-collageCommand
-  .description('Use JSON layouts to build custom collages.')
-  .option('-t, --template <path>', 'The path to the JSON file describing the collage template', null)
-  .option('-m, --mapping <json>', 'Inline JSON template override straight from the command line', null)
-  .option('-p, --preset <preset-id>', 'Collage preset ID to use. Available collage IDs: ', null)
-  .action(async (files, opts) => {
-    await main(files, opts);
-  });
-
-const main = async (files, opts) => {
-  // Collect and validate parameters
-  try {
-    const params = { files, ...opts };
-    const sharedOptions = await validateSharedOptions(params);
-    const collageOptions = await validateCollageOptions(opts);
-    const validatedParams = { ...sharedOptions, ...collageOptions };
-
-    // Load images, create collage, and write on disk
-    await generateAndSaveCollage(validatedParams);
-
-    // Output success message
-  } catch (e) {
-    handleError(e);
-  }
-};
-
-const generateAndSaveCollage = async (validatedParams) => {
-  // Replace gap and background if not provided with command line values
-  if (validatedParams.template?.canvas?.gap === undefined) {
-    validatedParams.template.canvas.gap = validatedParams.gap;
-  }
-  if (validatedParams.template?.canvas?.background === undefined) {
-    validatedParams.template.canvas.background = validatedParams.canvasColor;
-  }
-
-  // Validate the template and update it
-  const validatedTemplate = validateTemplate(validatedParams.template);
-  validatedParams.template = validatedTemplate;
-
-  // Load images from file
-  const { images, ignoredFiles } = await loadImages({ ...validatedParams, count: validatedParams.template.slots.length });
-
-  // Display warnings if needed
-  if (ignoredFiles.length) {
-    displayWarningMessage('\nThese files will be ignored due to unsupported formats:');
-    for (const file of ignoredFiles) {
-      displayInfoMessage(file);
-    }
-
-    const confirmation = await cliConfirm('\nAre you sure you want to continue?');
-    if (!confirmation) return;
-  }
-
-  const collage = await collageMerge(images, validatedParams);
-
-  const success = await writeImage(collage, validatedParams.output);
-
-  // Display success message
-  if (success) {
-    displaySuccessMessage(`\nImage has been created successfully: ${chalk.bold(validatedParams.output)}\n`);
-  }
-};
-
-addSharedOptions(collageCommand);
-export default collageCommand;

package/commands/merge/grid.js

@@ -1,71 +0,0 @@
-import { Command } from 'commander';
-import chalk from 'chalk';
-import {
-  cliConfirm,
-  displayInfoMessage,
-  displaySuccessMessage,
-  displayWarningMessage,
-  handleError,
-  writeImage,
-} from '../../lib/helpers/utils.js';
-import { addSharedOptions } from './helpers/utils.js';
-import { validateGridOptions, validateSharedOptions } from './helpers/validations.js';
-import { loadImages } from '../../lib/helpers/loadImages.js';
-import { gridMerge } from '../../lib/merges/grid-merge/index.js';
-
-const gridCommand = new Command('grid');
-
-gridCommand
-  .description('Arranges images in an organized grid.')
-  .option('--ar, --aspect-ratio <width/height|number>', 'The aspect ratio of all the images (examples: 16/9, 4:3, 1.777)', '1:1')
-  .option('-w, --image-width <px>', 'The width of each image, defaults to the smallest image', null)
-  .option('-c, --columns <n>', 'The number of columns', 4)
-  .option('--ca, --caption', 'Whether to caption each image', false)
-  .option('--cc, --caption-color <hex>', 'Image Caption color', '#000000')
-  .option('--mcs, --max-caption-size <pt>', 'The maximum allowed caption size', 100)
-  .action(async (files, opts) => {
-    await main(files, opts);
-  });
-
-const main = async (files, opts) => {
-  // Collect and validate parameters
-  try {
-    const params = { files, ...opts };
-    const sharedOptions = await validateSharedOptions(params);
-    const gridOptions = validateGridOptions(sharedOptions, params);
-    const validatedParams = { ...sharedOptions, ...gridOptions };
-
-    // Load images, create grid, and write grid on disk
-    await generateAndSaveGrid(validatedParams);
-
-    // Output success message
-  } catch (e) {
-    handleError(e);
-  }
-};
-
-const generateAndSaveGrid = async (validatedParams) => {
-  const { files, images, ignoredFiles } = await loadImages(validatedParams);
-
-  // Display warnings if needed
-  if (ignoredFiles.length) {
-    displayWarningMessage('\nThese files will be ignored due to unsupported formats:');
-    for (const file of ignoredFiles) {
-      displayInfoMessage(file);
-    }
-
-    const confirmation = await cliConfirm('\nAre you sure you want to continue?');
-    if (!confirmation) return;
-  }
-
-  const grid = await gridMerge(files, images, validatedParams);
-  const success = await writeImage(grid, validatedParams.output);
-
-  // Display success message
-  if (success) {
-    displaySuccessMessage(`\nImage has been created successfully: ${chalk.bold(validatedParams.output)}\n`);
-  }
-};
-
-addSharedOptions(gridCommand);
-export default gridCommand;

package/commands/merge/helpers/utils.js

@@ -1,11 +0,0 @@
-export const addSharedOptions = (cmd) => {
-  return cmd
-    .argument('[files...]', 'Image filepaths to merge (use --dir for directories)')
-    .option('-d, --dir <path>', 'Directory of images to merge')
-    .option('-r, --recursive', 'Recursively include subdirectories', false)
-    .option('--sh, --shuffle', 'Shuffle up images to randomize order in the grid', false)
-    .option('--cr, --corner-radius <px>', 'How much to round the corners of each image', 0)
-    .option('-g, --gap <px>', 'Gap between images', 50)
-    .option('--bg, --canvas-color <hex|transparent>', 'Background color for canvas', '#ffffff')
-    .option('-o, --output <file>', 'Output file path', './pixeli.png');
-};

package/commands/merge/helpers/validations.js

@@ -1,269 +0,0 @@
-import fs from 'node:fs/promises';
-
-import {
-  displayWarningMessage,
-  handleError,
-  isSupportedOutputImage,
-  isValidHexadecimal,
-  parseAspectRatio,
-  SUPPORTED_OUTPUT_FORMATS,
-} from '../../../lib/helpers/utils.js';
-import { isValidPreset, PRESETS } from '../../../lib/merges/collage-merge/presets.js';
-
-export const validateSharedOptions = async (sharedOptions) => {
-  // Extract params
-  const { files, dir, recursive, shuffle, cornerRadius, gap, canvasColor, output } = sharedOptions;
-
-  // Conduct validations
-  if ((!files || !files.length) && !dir) {
-    throw new Error('You must specify either [files...] or --dir.');
-  }
-
-  // Ensure dir is a valid dir path
-  if (dir.length) {
-    let stats;
-
-    try {
-      stats = await fs.stat(dir);
-    } catch (e) {
-      throw new Error('Path does not exist.');
-    }
-
-    if (!stats.isDirectory()) {
-      throw new Error('Path is not a directory.');
-    }
-  }
-
-  if (isNaN(gap) || !Number.isInteger(Number(gap)) || gap < 0) {
-    throw new Error('--gap must be a positive integer.');
-  }
-
-  if (isNaN(cornerRadius) || !Number.isInteger(Number(cornerRadius)) || cornerRadius < 0) {
-    throw new Error('--corner-radius must be a positive integer.');
-  }
-
-  if (canvasColor !== 'transparent' && !isValidHexadecimal(canvasColor)) {
-    throw new Error('--canvas-color must be a valid hexadecimal value.');
-  }
-
-  if (!isSupportedOutputImage(output)) {
-    throw new Error('Invalid output format. Choose one of the following: ' + SUPPORTED_OUTPUT_FORMATS.join(', '));
-  }
-
-  const formattedParams = {
-    files: files || [],
-    dir,
-    recursive,
-    shuffle,
-    cornerRadius: Number(cornerRadius),
-    gap: Number(gap),
-    canvasColor: canvasColor === 'transparent' ? { r: 0, g: 0, b: 0, alpha: 0 } : canvasColor,
-    output,
-  };
-
-  return formattedParams;
-};
-
-export const validateMasonryOptions = (sharedOptions, masonryOptions) => {
-  // Extract params
-  const { gap } = sharedOptions;
-  const { rowHeight, columnWidth, canvasWidth, canvasHeight, flow, hAlign, vAlign } = masonryOptions;
-
-  // Define orientations and alignments for validation
-  const FLOWS = ['horizontal', 'vertical'];
-  const HORIZONTAL_ALIGNMENTS = ['left', 'center', 'right', 'justified'];
-  const VERTICAL_ALIGNMENTS = ['top', 'middle', 'bottom', 'justified'];
-
-  // Define orientation dependent options which are ignored if defined for the wrong orientation
-  const IGNORED_FLOW_DEPENDENT_OPTIONS = {
-    horizontal: [
-      {
-        option: '--v-align',
-        value: vAlign,
-      },
-      {
-        option: '--canvas-height',
-        value: canvasHeight,
-      },
-      {
-        option: '--column-width',
-        value: columnWidth,
-      },
-    ],
-    vertical: [
-      {
-        option: '--h-align',
-        value: hAlign,
-      },
-      {
-        option: '--canvas-width',
-        value: canvasWidth,
-      },
-      {
-        option: '--row-height',
-        value: rowHeight,
-      },
-    ],
-  };
-
-  // Validate orientations and alignments
-  if (!FLOWS.includes(flow)) {
-    throw new Error('Invalid orientation. Choose one of the following: ' + FLOWS.join(', '));
-  }
-
-  if (hAlign && !HORIZONTAL_ALIGNMENTS.includes(hAlign)) {
-    throw new Error('Invalid horizontal alignment. Choose one of the following: ' + HORIZONTAL_ALIGNMENTS.join(', '));
-  }
-
-  if (vAlign && !VERTICAL_ALIGNMENTS.includes(vAlign)) {
-    throw new Error('Invalid vertical orientation. Choose one of the following: ' + VERTICAL_ALIGNMENTS.join(', '));
-  }
-
-  // Ensure numeric values are positive integers
-  if (rowHeight && (isNaN(rowHeight) || !Number.isInteger(Number(rowHeight)) || Number(rowHeight) < 1)) {
-    throw new Error('--row-height must be a positive integer.');
-  }
-
-  if (columnWidth && (isNaN(columnWidth) || !Number.isInteger(Number(columnWidth)) || Number(columnWidth) < 1)) {
-    throw new Error('--column-width must be a positive integer.');
-  }
-
-  // Ensure canvas width is given
-  if (flow === 'horizontal' && !canvasWidth) {
-    throw new Error('--canvas-width must be given.');
-  }
-  // and is a positive integer
-  else if (flow === 'horizontal' && (isNaN(canvasWidth) || !Number.isInteger(Number(canvasWidth)) || Number(canvasWidth) < 1)) {
-    throw new Error('--canvas-width must be a positive integer.');
-  }
-  // and it accomodates for the minimum width needed
-  else if (flow === 'horizontal' && canvasWidth <= gap * 2) {
-    throw new Error(`--canvas-width must be greater than 2 gaps or ${gap * 2}px.`);
-  }
-
-  // Ensure canvas height is given
-  if (flow === 'vertical' && !canvasHeight) {
-    throw new Error('--canvas-height must be given.');
-  }
-  // and is a positive integer
-  else if (flow === 'vertical' && (isNaN(canvasHeight) || !Number.isInteger(Number(canvasHeight)) || Number(canvasHeight) < 1)) {
-    throw new Error('--canvas-height must be a positive integer.');
-  }
-  // and it accomodates for the minimum height needed
-  else if (flow === 'vertical' && canvasHeight <= gap * 2) {
-    throw new Error(`--canvas-height must be greater than 2 gaps or ${gap * 2}px.`);
-  }
-
-  // Validate dependent options by showing warnings when incorrect parameters
-  // are used with incorrect orientation
-  const ignoredFlowOptions = IGNORED_FLOW_DEPENDENT_OPTIONS[flow];
-  for (const { option, value } of ignoredFlowOptions) {
-    if (value) {
-      displayWarningMessage(`"${option}" option is ignored due to ${flow} flow.`);
-    }
-  }
-
-  const params = {
-    rowHeight: Number(rowHeight) || null,
-    columnWidth: Number(columnWidth) || null,
-    canvasHeight: Number(canvasHeight) || null,
-    canvasWidth: Number(canvasWidth) || null,
-    flow,
-    hAlign,
-    vAlign,
-  };
-
-  return params;
-};
-
-export const validateGridOptions = (sharedOptions, gridOptions) => {
-  // Extract params
-  const { aspectRatio, imageWidth, columns, caption, captionColor, maxCaptionSize } = gridOptions;
-
-  // Ensure aspect ratio is valid
-  const parsedAspectRatio = parseAspectRatio(aspectRatio);
-  if (!parsedAspectRatio) {
-    throw new Error('--aspect-ratio must be a valid ratio. Examples: 16/9, 2:3, 1x2, 1.77');
-  }
-
-  if (imageWidth && (isNaN(imageWidth) || !Number.isInteger(Number(imageWidth)) || Number(imageWidth) < 1)) {
-    throw new Error('--image-width must be a positive integer.');
-  }
-
-  if (isNaN(columns) || !Number.isInteger(Number(columns)) || Number(columns) < 1) {
-    throw new Error('--columns must be a positive integer.');
-  }
-
-  if (isNaN(maxCaptionSize) || !Number.isInteger(Number(maxCaptionSize)) || Number(maxCaptionSize) < 2) {
-    throw new Error('--max-caption-size must be a positive integer >= 2 (minimum caption size).');
-  }
-
-  if (!isValidHexadecimal(captionColor)) {
-    throw new Error('--caption-color must be a valid hexadecimal value.');
-  }
-
-  const formattedParams = {
-    aspectRatio: parsedAspectRatio,
-    imageWidth: Number(imageWidth) || null,
-    columns: Number(columns),
-    caption,
-    captionColor,
-    maxCaptionSize,
-  };
-
-  return formattedParams;
-};
-
-export const validateCollageOptions = async (collageOptions) => {
-  const { template, mapping, preset } = collageOptions;
-
-  // If a valid preset is given, use it
-  if (preset && isValidPreset(preset)) {
-    return { template: PRESETS[preset] };
-  }
-  // If preset is invalid, throw error
-  else if (preset && !isValidPreset(preset)) {
-    const validPresets = Object.keys(PRESETS).join(', ');
-    throw new Error(`"${preset}" is not a valid preset ID. Choose one of the following: \n${validPresets}`);
-  }
-
-  // Ensure only one of the two are given
-  if (!template && !mapping) {
-    throw new Error('Either --template, --mapping, or --preset need to be provided.');
-  } else if (template && mapping) {
-    throw new Error('Either use --template or --mapping, not both.');
-  }
-
-  // Ensure mapping is actually a json string
-  if (!template && mapping) {
-    try {
-      JSON.parse(mapping);
-    } catch {
-      throw new Error('--mapping should be a valid JSON string.');
-    }
-  }
-
-  // Ensure template is a valid dir path
-  if (template && !mapping) {
-    let stats;
-
-    try {
-      stats = await fs.stat(template);
-    } catch (e) {
-      throw new Error('Template path does not exist.');
-    }
-  }
-
-  // Parse and return respective JSON data
-  try {
-    if (template) {
-      const jsonStr = await fs.readFile(template, 'utf8');
-      return { template: JSON.parse(jsonStr) };
-    }
-
-    // mapping is already a JSON string
-    return { template: JSON.parse(mapping) };
-  } catch (err) {
-    throw new Error('Could not read or parse the provided template or mapping JSON.');
-  }
-};

package/commands/merge/index.js

@@ -1,12 +0,0 @@
-import { Command } from 'commander';
-import masonryCommand from './masonry.js';
-import gridCommand from './grid.js';
-import collageCommand from './collage.js';
-
-const mergeCommand = new Command('merge').description('Merge images into a grid layout.');
-
-mergeCommand.addCommand(masonryCommand);
-mergeCommand.addCommand(gridCommand);
-mergeCommand.addCommand(collageCommand);
-
-export default mergeCommand;