pixeli 1.0.3 → 1.0.5

package/README.md

@@ -51,6 +51,7 @@ The tool currently supports four main layout modes: ***Grid***, ***Masonry*** (h
     * [All Supported Input Formats](#all-supported-input-formats)
     * [All Supported Output Formats](#all-supported-output-formats)
     * [Pixel Limits](#pixel-limits)
+    * [Error Handling](#error-handling)
     * [Colors and Transparency](#colors-and-transparency)
         * [CLI](#cli)
         * [Library](#library)
@@ -471,6 +472,26 @@ Generating extremely large images significantly reduces speed, and may also lead
 | **BMP**                      | `.bmp`               | **32,767×32,767 or ~2,147,483,647×2,147,483,647 px** | Depends on version/fields.                                                                         |
 | **TIFF**                     | `.tif`, `.tiff`      | **4,294,967,295 × 4,294,967,295 px** (theoretical)   | Very large; may be limited by software or memory.                                                  |
 
+### Error Handling
+All errors produced by this library are instances of the `MergeError` class, which extends the `Error` class.
+
+In addition to the inherited `message` property, the `MergeError` class also has a `context` object parameter attached to it, where there is a `type` and an optional `cause` property. Consider the following:
+
+```typescript
+throw new MergeError("Some error has occurred", {
+  type: 'internal',
+  cause: 'helper "trimmedMedian" failed'
+});
+```
+
+The `cause` property is only used when an internal error has occurred, meaning that there is something wrong with the API.
+
+The `type` property can be one of the following:
+- `validation`: One of the options provided to the merge function is incorrect or is required but not provided.
+- `image`: An invalid, corrupt, or empty image input list has been provided.
+- `internal`: An error with the interal library. Should not occur.
+
+
 ### Colors and Transparency
 
 #### CLI

package/dist/core/index.d.ts

@@ -1 +1,2 @@
 export * from './merges/index.js';
+export { BatchRunner } from './jobs/batchRunner.js';

package/dist/core/index.js

@@ -1 +1,2 @@
 export * from './merges/index.js';
+export { BatchRunner } from './jobs/batchRunner.js';

package/dist/core/jobs/batchRunner.d.ts

@@ -0,0 +1,44 @@
+import { MergeError } from '../mergeError.js';
+import { TypedEventEmitter } from '../modules/typedEventEmitter.js';
+import type { BatchOptions, MergeJob } from './types.js';
+type MergeResult = {
+    index: number;
+    success: true;
+    buffer: Buffer;
+} | {
+    index: number;
+    success: false;
+    error: MergeError;
+};
+export interface BatchEvents {
+    start: {
+        totalJobs: number;
+    };
+    'job:start': {
+        job: MergeJob;
+        index: number;
+    };
+    'job:complete': {
+        job: MergeJob;
+        index: number;
+        buffer: Buffer;
+    };
+    'job:error': {
+        job: MergeJob;
+        index: number;
+        error: MergeError;
+    };
+    complete: {
+        results: MergeResult[];
+    };
+}
+export declare class BatchRunner extends TypedEventEmitter<BatchEvents> {
+    private jobs;
+    private results;
+    private validatedJobs;
+    constructor(jobs: MergeJob[]);
+    run(options?: BatchOptions): Promise<MergeResult[]>;
+    private runJob;
+    private validateJob;
+}
+export {};

package/dist/core/jobs/batchRunner.js

@@ -0,0 +1,90 @@
+// Merges
+import * as mergeFunctions from '../merges/index.js';
+// Errors
+import { MergeError } from '../mergeError.js';
+import { MESSAGES } from '../modules/messages.js';
+// Other
+import { TypedEventEmitter } from '../modules/typedEventEmitter.js';
+import { mergeJobSchema } from '../schemas/mergeJob.js';
+export class BatchRunner extends TypedEventEmitter {
+    jobs;
+    results = [];
+    validatedJobs = [];
+    constructor(jobs) {
+        super();
+        this.jobs = jobs;
+        // Ensure all jobs are valid
+        for (const job of jobs) {
+            const validatedJob = this.validateJob(job);
+            this.validatedJobs.push(validatedJob);
+        }
+    }
+    async run(options = {}) {
+        const { stopOnError = false } = options;
+        // Run jobs
+        for (let i = 0; i < this.validatedJobs.length; i++) {
+            const job = this.validatedJobs[i];
+            try {
+                // Emit job start event
+                this.emit('job:start', {
+                    index: i,
+                    job: this.jobs[i],
+                });
+                // Run job
+                const buffer = await this.runJob(job);
+                // Emit job completion event
+                this.emit('job:complete', {
+                    index: i,
+                    job: this.jobs[i],
+                    buffer,
+                });
+                this.results.push({ index: i, success: true, buffer: buffer });
+            }
+            catch (error) {
+                // Emit job error event
+                this.emit('job:error', {
+                    index: i,
+                    job: this.jobs[i],
+                    error: error,
+                });
+                // Throw error if needed
+                if (stopOnError)
+                    throw error;
+                // Store error for later
+                this.results.push({ index: i, success: false, error: error });
+            }
+        }
+        // Emit batch job completion event
+        this.emit('complete', {
+            results: this.results,
+        });
+        return this.results;
+    }
+    async runJob(job) {
+        // Run job and return resulting buffer
+        switch (job.type) {
+            case 'grid':
+                return mergeFunctions.gridMerge(job.inputs, job.options);
+            case 'masonry':
+                return mergeFunctions.masonryMerge(job.inputs, job.options);
+            case 'collage':
+                return mergeFunctions.collageMerge(job.inputs, job.options);
+            case 'template':
+                return mergeFunctions.templateMerge(job.inputs, job.options);
+        }
+    }
+    validateJob(job) {
+        // Validate job format
+        const { success, data, error } = mergeJobSchema.safeParse(job);
+        if (!success) {
+            const path = error.issues[0]?.path;
+            const err = error.issues[0]?.message;
+            if (!path || !err) {
+                throw new MergeError(MESSAGES.ERROR.INTERNAL.message, { type: 'internal', cause: error });
+            }
+            const errorText = path.length > 0 ? `Invalid value at ${path.join('/')}: ${err}` : `Error: ${err}`;
+            throw new MergeError(errorText, { type: 'validation' });
+        }
+        return data;
+    }
+}

package/dist/core/jobs/types.d.ts

@@ -0,0 +1,10 @@
+import type sharp from 'sharp';
+import type { MergeTypeOptions } from '../merges/types.js';
+export type MergeJob = {
+    /** File paths to all of the images to load. */
+    inputs: sharp.SharpInput[];
+} & MergeTypeOptions;
+export interface BatchOptions {
+    /** Throws a `MergeError` instantly and stops the process if true. */
+    stopOnError?: boolean;
+}

package/dist/core/jobs/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/merges/index.d.ts

@@ -1,3 +1,5 @@
 export { gridMerge } from './grid/index.js';
 export { masonryMerge } from './masonry/index.js';
 export { templateMerge } from './template/index.js';
+export { collageMerge } from './collage/index.js';
+export type { GridMergeOptions, MasonryMergeOptions, TemplateMergeOptions, CollageMergeOptions } from './types.js';

package/dist/core/merges/index.js

@@ -1,3 +1,4 @@
 export { gridMerge } from './grid/index.js';
 export { masonryMerge } from './masonry/index.js';
 export { templateMerge } from './template/index.js';
+export { collageMerge } from './collage/index.js';

package/dist/core/merges/types.d.ts

@@ -72,10 +72,10 @@ export interface MasonryMergeOptions extends BaseMergeOptions {
     /** The vertical alignment of each column. Only applied in vertical layouts. */
     vAlign?: 'top' | 'middle' | 'bottom' | 'justified';
 }
-interface TemplateMergeOptions extends BaseMergeOptions {
+export interface TemplateMergeOptions extends BaseMergeOptions {
     template: Template;
 }
-interface CollageMergeOptions extends Omit<BaseMergeOptions, 'gap'> {
+export interface CollageMergeOptions extends Omit<BaseMergeOptions, 'gap'> {
     /** Width of each image cell in pixels, uses the median image width if undefined. */
     imageWidth?: number | undefined;
     /** The aspect ratio of each image. Used to calculate image height based on given width.
@@ -95,6 +95,27 @@ interface CollageMergeOptions extends Omit<BaseMergeOptions, 'gap'> {
      * For example, a value of `10` will result in a random degree being picked from `-10` to `+10` degrees. */
     rotationRange?: number;
 }
+export type MergeTypeOptions = {
+    /** Use the grid layout engine. */
+    type: 'grid';
+    /** Options specific to grid merges. */
+    options: GridMergeOptions;
+} | {
+    /** Use the masonry layout engine. */
+    type: 'masonry';
+    /** Options specific to masonry merges. */
+    options: MasonryMergeOptions;
+} | {
+    /** Use the template-based merge engine. */
+    type: 'template';
+    /** Options specific to template merges. */
+    options: TemplateMergeOptions;
+} | {
+    /** Use the free-form collage merge engine. */
+    type: 'collage';
+    /** Options specific to collage merges. */
+    options: CollageMergeOptions;
+};
 export type GridMerge = MergeCommand<GridMergeOptions>;
 export type MasonryMerge = MergeCommand<MasonryMergeOptions>;
 export type TemplateMerge = MergeCommand<TemplateMergeOptions>;

package/dist/core/modules/typedEventEmitter.d.ts

@@ -0,0 +1,7 @@
+import EventEmitter from 'node:events';
+type EventKey<T> = keyof T & string;
+export declare class TypedEventEmitter<TEvents> extends EventEmitter {
+    on<K extends EventKey<TEvents>>(event: K, listener: (payload: TEvents[K]) => void): this;
+    emit<K extends EventKey<TEvents>>(event: K, payload: TEvents[K]): boolean;
+}
+export {};

package/dist/core/modules/typedEventEmitter.js

@@ -0,0 +1,9 @@
+import EventEmitter from 'node:events';
+export class TypedEventEmitter extends EventEmitter {
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    emit(event, payload) {
+        return super.emit(event, payload);
+    }
+}

package/dist/core/schemas/mergeJob.d.ts

@@ -0,0 +1,11 @@
+import z from 'zod';
+export declare const mergeJobSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        template: "template";
+        grid: "grid";
+        masonry: "masonry";
+        collage: "collage";
+    }>;
+    inputs: z.ZodArray<z.ZodString>;
+    options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.z.core.$strict>;

package/dist/core/schemas/mergeJob.js

@@ -0,0 +1,6 @@
+import z from 'zod';
+export const mergeJobSchema = z.strictObject({
+    type: z.enum(['grid', 'masonry', 'collage', 'template']),
+    inputs: z.array(z.string()).min(1),
+    options: z.record(z.string(), z.any()).optional(),
+});

package/dist/validators/outputFile.js

@@ -4,4 +4,4 @@ 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');
+}, 'output image format is invalid');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixeli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "A lightweight command-line tool for merging multiple images into customizable grid layouts.",
   "homepage": "https://github.com/pakdad-mousavi/pixeli#readme",
   "bugs": {
@@ -56,5 +56,10 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
+  },
+  "allowScripts": {
+    "esbuild@0.27.2": true,
+    "fsevents@2.3.3": true,
+    "sharp@0.34.5": true
   }
 }