pixeli 0.1.9 → 1.0.4

package/dist/core/merges/shared-steps/exportCanvas.js

@@ -0,0 +1,25 @@
+import { MESSAGES } from '../../modules/messages.js';
+import { MergeError } from '../../mergeError.js';
+import { requireContextProp } from '../../pipeline/guards.js';
+export const exportCanvas = async (context, options, _onProgress) => {
+    // Ensure canvas exists
+    requireContextProp(context, 'canvas');
+    try {
+        return await context.canvas.toFormat(options.format).toBuffer();
+    }
+    catch (err) {
+        // Assuming ALL sharp errors are instances of the Error object
+        const sharpError = err;
+        // SPECIFIC SHARP ERROR
+        // occurs when trying to create a buffer that exceeds the limits of the current image format
+        if (sharpError.message.includes('pixel limit') || sharpError.message.includes('Processed image is too large')) {
+            const errText = `Error: image to large for "${options.format}" format, try a format that allows larger images`;
+            throw new MergeError(errText, { type: 'image' });
+        }
+        // Other sharp errors
+        throw new MergeError(MESSAGES.ERROR.INTERNAL.message, {
+            type: 'internal',
+            cause: err,
+        });
+    }
+};

package/dist/core/merges/shared-steps/finalizeImagePipelines.d.ts

@@ -0,0 +1,2 @@
+import type { MergeStep } from '../../pipeline/mergePipeline.js';
+export declare const finalizeImagePipelines: MergeStep<any, any>;

package/dist/core/merges/shared-steps/finalizeImagePipelines.js

@@ -0,0 +1,9 @@
+import { requireNonEmptyArray } from '../../pipeline/guards.js';
+import sharp from 'sharp';
+export const finalizeImagePipelines = async (context, _options, _onProgress) => {
+    requireNonEmptyArray(context.images);
+    for (let i = 0; i < context.images.length; i++) {
+        const buffer = await context.images[i].toBuffer();
+        context.images[i] = sharp(buffer);
+    }
+};

package/dist/core/merges/shared-steps/loadImages.d.ts

@@ -0,0 +1,2 @@
+import type { MergeStep } from '../../pipeline/mergePipeline.js';
+export declare const loadImages: MergeStep<any, any>;

package/dist/core/merges/shared-steps/loadImages.js

@@ -0,0 +1,26 @@
+import sharp from 'sharp';
+import { isActualImage } from '../../utils/images/isActualImage.js';
+import { MergeError } from '../../mergeError.js';
+import { requireNonEmptyArray } from '../../pipeline/guards.js';
+export const loadImages = async (context, _options, _onProgress) => {
+    // Ensure inputs are provided
+    requireNonEmptyArray(context.inputs, 'inputs');
+    const images = [];
+    for (let i = 0; i < context.inputs.length; i++) {
+        // Ensure image is valid
+        const input = context.inputs[i];
+        const { isImage, reason } = await isActualImage(input);
+        if (!isImage) {
+            throw new MergeError(`Invalid image input at index ${i}`, {
+                type: 'validation',
+                cause: reason,
+            });
+        }
+        images.push(sharp(input));
+    }
+    // Ensure there's at least one image
+    if (images.length <= 0) {
+        throw new MergeError('No images provided to merge', { type: 'validation' });
+    }
+    context.images = images;
+};

package/dist/core/merges/shared-steps/validateCaptions.d.ts

@@ -0,0 +1,10 @@
+import type { MergeStep } from '../../pipeline/mergePipeline.js';
+interface Options {
+    caption: boolean;
+    captions?: string[] | undefined;
+}
+interface State {
+    areCaptionsProvided: boolean;
+}
+export declare const validateCaptions: MergeStep<Options, State>;
+export {};

package/dist/core/merges/shared-steps/validateCaptions.js

@@ -0,0 +1,17 @@
+import { MergeError } from '../../mergeError.js';
+export const validateCaptions = async (context, options, _onProgress) => {
+    // Initially set to false
+    context.state.areCaptionsProvided = false;
+    // Update context
+    if (areCaptionsProvided(options.caption, options.captions)) {
+        context.state.areCaptionsProvided = true;
+        context.captions = options.captions;
+    }
+    // Ensure caption length is not less than image length
+    if (areCaptionsProvided(options.caption, options.captions) && options.captions.length !== context.images.length) {
+        throw new MergeError('The same number of captions and images must be provided', { type: 'validation' });
+    }
+};
+const areCaptionsProvided = (caption, captions) => {
+    return caption;
+};

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

@@ -0,0 +1,10 @@
+import type { TemplateMerge } from '../types.js';
+import type { Block } from './types.js';
+export interface TemplateState {
+    slotWidth: number;
+    slotHeight: number;
+    canvasWidth: number;
+    canvasHeight: number;
+    blocks: Block[];
+}
+export declare const templateMerge: TemplateMerge;

package/dist/core/merges/template/index.js

@@ -0,0 +1,28 @@
+import { MergePipeline } from '../../pipeline/mergePipeline.js';
+import { templateSchema } from '../../schemas/template.js';
+import { loadImages } from '../shared-steps/loadImages.js';
+import { applyComposites } from '../shared-steps/applyComposites.js';
+import { createCanvas } from '../shared-steps/createCanvas.js';
+import { exportCanvas } from '../shared-steps/exportCanvas.js';
+import { calculateCanvasDimensions } from './steps/calculateSlotDimensions.js';
+import { getBlocks } from './steps/getBlocks.js';
+import { createComposites } from './steps/createComposites.js';
+export const templateMerge = async (imageInputs, options, onProgress) => {
+    const context = {
+        inputs: imageInputs,
+        captions: [],
+        composites: [],
+        images: [],
+        state: {},
+    };
+    const templateMergePipeline = await MergePipeline.createPipeline(templateSchema, options, context, onProgress);
+    templateMergePipeline
+        .use(loadImages)
+        .use(calculateCanvasDimensions)
+        .use(getBlocks)
+        .use(createCanvas)
+        .use(createComposites)
+        .use(applyComposites)
+        .use(exportCanvas);
+    return await templateMergePipeline.run();
+};

package/dist/core/merges/template/steps/calculateSlotDimensions.d.ts

@@ -0,0 +1,9 @@
+import type { MergeStep } from '../../../pipeline/mergePipeline.js';
+import type { Template } from '../types.js';
+import type { TemplateState } from '../index.js';
+interface Options {
+    gap: number;
+    template: Template;
+}
+export declare const calculateCanvasDimensions: MergeStep<Options, TemplateState>;
+export {};

package/dist/core/merges/template/steps/calculateSlotDimensions.js

@@ -0,0 +1,12 @@
+export const calculateCanvasDimensions = async (context, options, _onProgress) => {
+    // Calculate each column's width and height
+    const workableCanvasWidth = options.template.canvas.width - options.gap * (options.template.canvas.columns + 1);
+    const workableCanvasHeight = options.template.canvas.height - options.gap * (options.template.canvas.rows + 1);
+    const slotWidth = workableCanvasWidth / options.template.canvas.columns;
+    const slotHeight = workableCanvasHeight / options.template.canvas.rows;
+    // Assign to state
+    context.state.canvasWidth = options.template.canvas.width;
+    context.state.canvasHeight = options.template.canvas.height;
+    context.state.slotWidth = slotWidth;
+    context.state.slotHeight = slotHeight;
+};

package/dist/core/merges/template/steps/createComposites.d.ts

@@ -0,0 +1,10 @@
+import type { MergeStep } from '../../../pipeline/mergePipeline.js';
+import type { Template } from '../types.js';
+import type { TemplateState } from '../index.js';
+interface Options {
+    template: Template;
+    gap: number;
+    cornerRadius: number;
+}
+export declare const createComposites: MergeStep<Options, TemplateState>;
+export {};

package/dist/core/merges/template/steps/createComposites.js

@@ -0,0 +1,25 @@
+import { requireState } from '../../../pipeline/guards.js';
+export const createComposites = async (context, options, onProgress) => {
+    // Require needed states
+    requireState(context, 'blocks');
+    requireState(context, 'slotWidth');
+    requireState(context, 'slotHeight');
+    // Collect composites
+    const composites = [];
+    for (const block of context.state.blocks) {
+        const x = (block.col - 1) * context.state.slotWidth + block.col * options.gap;
+        const y = (block.row - 1) * context.state.slotHeight + block.row * options.gap;
+        composites.push({
+            input: block.imageBuffer,
+            left: Math.floor(x),
+            top: Math.floor(y),
+        });
+        // Update progress
+        if (onProgress) {
+            context.progressInfo.phase = 'Merging images';
+            context.progressInfo.completed += 1;
+            onProgress({ ...context.progressInfo });
+        }
+    }
+    context.composites = composites;
+};

package/dist/core/merges/template/steps/getBlocks.d.ts

@@ -0,0 +1,13 @@
+import type { MergeStep } from '../../../pipeline/mergePipeline.js';
+import type { Template } from '../types.js';
+import type { TemplateState } from '../index.js';
+import type { RGBA } from '../../../utils/colors/types.js';
+interface Options {
+    template: Template;
+    gap: number;
+    borderWidth: number;
+    borderColor: RGBA;
+    cornerRadius: number;
+}
+export declare const getBlocks: MergeStep<Options, TemplateState>;
+export {};

package/dist/core/merges/template/steps/getBlocks.js

@@ -0,0 +1,28 @@
+import { requireNonEmptyArray, requireState } from '../../../pipeline/guards.js';
+import { handleImageEdges } from '../../../utils/images/handleImageEdges.js';
+export const getBlocks = async (context, options, _onProgress) => {
+    // Require needed states
+    requireState(context, 'slotWidth');
+    requireState(context, 'slotHeight');
+    requireNonEmptyArray(context.images, 'images');
+    const blocks = [];
+    for (let i = 0; i < options.template.slots.length && i < context.images.length; i++) {
+        const slot = options.template.slots[i];
+        const image = context.images[i];
+        // Calculate image width and height
+        const width = Math.floor(slot.colSpan * context.state.slotWidth + (slot.colSpan - 1) * options.gap);
+        const height = Math.floor(slot.rowSpan * context.state.slotHeight + (slot.rowSpan - 1) * options.gap);
+        // Resize image
+        const resizedImage = image.resize({ width, height });
+        const borderedImage = await handleImageEdges(resizedImage, {
+            borderWidth: options.borderWidth,
+            borderHeight: options.borderWidth,
+            borderColor: options.borderColor,
+            cornerRadius: options.cornerRadius,
+            imageWidth: width,
+            imageHeight: height,
+        });
+        blocks.push({ imageBuffer: await borderedImage.toBuffer(), col: slot.col, row: slot.row });
+    }
+    context.state.blocks = blocks;
+};

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

@@ -0,0 +1,21 @@
+export interface Canvas {
+    width: number;
+    height: number;
+    columns: number;
+    rows: number;
+}
+export interface Slot {
+    col: number;
+    row: number;
+    colSpan: number;
+    rowSpan: number;
+}
+export interface Template {
+    canvas: Canvas;
+    slots: Slot[];
+}
+export interface Block {
+    imageBuffer: Buffer;
+    col: number;
+    row: number;
+}

package/dist/core/merges/template/types.js

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

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

@@ -0,0 +1,123 @@
+import sharp from 'sharp';
+import type { Color } from '../utils/colors/types.js';
+import type { Template } from './template/types.js';
+export interface ProgressInfo {
+    /** How many images have been processed so far */
+    completed: number;
+    /** The total number of images to be processed */
+    total: number;
+    /** The current phase of the merge */
+    phase: string;
+}
+export type OnProgress = (info: ProgressInfo) => void;
+/**
+ * Generic image merge command.
+ *
+ * @template T - Merge-specific configuration options
+ * @param imageInputs - Input images to merge
+ * @param options - Merge options
+ * @param onProgress - Optional progress callback
+ * @returns A Promise resolving to the merged image buffer
+ */
+interface MergeCommand<T> {
+    (imageInputs: sharp.SharpInput[], options: T, onProgress?: OnProgress): Promise<Buffer>;
+}
+interface BaseMergeOptions {
+    /** Whether to randomize image order before merging. */
+    shuffle?: boolean;
+    /** Rounded corner radius in pixels. */
+    cornerRadius?: number;
+    /** Gap between images in pixels. */
+    gap?: number;
+    /** Background canvas color. */
+    canvasColor?: Color;
+    /** Width of the border around each image. Borders are placed internally in each image. */
+    borderWidth?: number;
+    /** Color of the border around each image. */
+    borderColor?: Color;
+    /** Output image format (png, jpeg, webp). */
+    format?: string;
+}
+export interface GridMergeOptions extends BaseMergeOptions {
+    /** The aspect ratio of each image. Used to calculate image height based on given width.
+     *
+     * Examples include `16:9`, `3x2` or `1.777`. */
+    aspectRatio?: string | number;
+    /** Width of each image cell in pixels, uses the median image width if undefined. */
+    imageWidth?: number | undefined;
+    /** Number of columns in the grid. */
+    columns?: number;
+    /** Enable captions under images. */
+    caption?: boolean;
+    /** Captions text (one per image, in order). */
+    captions?: string[];
+    /** Caption text color. */
+    captionColor?: Color;
+    /** Maximum caption font size in pixels. */
+    maxCaptionSize?: number;
+}
+export interface MasonryMergeOptions extends BaseMergeOptions {
+    /** The height of each row, defaults to the trimmed median image height if undefined. Only applied in horizontal flows. */
+    rowHeight?: number | undefined;
+    /** The width of each column, defaults to the trimmed median image width if undefined. Only applied in vertical flows. */
+    columnWidth?: number | undefined;
+    /** The width of the entire canvas. Only required in horizontal flows. */
+    canvasWidth?: number | undefined;
+    /** The width of the entire canvas. Only required in vertical flows. */
+    canvasHeight?: number | undefined;
+    /** The orientation of the masonry layout. */
+    flow: 'horizontal' | 'vertical';
+    /** The horizontal alignment of each row. Only applied in horizontal layouts. */
+    hAlign?: 'left' | 'center' | 'right' | 'justified';
+    /** The vertical alignment of each column. Only applied in vertical layouts. */
+    vAlign?: 'top' | 'middle' | 'bottom' | 'justified';
+}
+export interface TemplateMergeOptions extends BaseMergeOptions {
+    template: Template;
+}
+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.
+     *
+     * Examples include `16:9`, `3x2` or `1.777`. */
+    aspectRatio?: string | number;
+    /** Number of columns in the collage grid. */
+    columns?: number;
+    /** The number of pixels to potentially variate `imageWidth` by. Used to create random-sized images in the collage.
+     *
+     *  For example, a value of `50` results in images being up to `50` pixels wider or narrower than the given `imageWidth`. */
+    imageWidthVariance?: number;
+    /** The estimated percentage of overlap for every image pair. A higher percentage creates a tighter collage. */
+    overlapPercentage?: number;
+    /** The maximum and minimum degree to rotate each image.
+     *
+     * 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>;
+export type CollageMerge = MergeCommand<CollageMergeOptions>;
+export {};

package/dist/core/merges/types.js

@@ -0,0 +1 @@
+import sharp from 'sharp';

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

@@ -0,0 +1,32 @@
+interface Message {
+    message: string;
+    chalk?: (text: string) => string;
+}
+export declare const MESSAGES: {
+    WARNINGS: {
+        IGNORED_FILES: {
+            message: string;
+            chalk: import("chalk").ChalkInstance;
+        };
+    };
+    SUCCESS: {
+        OUTPUT: {
+            message: string;
+            chalk: import("chalk").ChalkInstance;
+        };
+    };
+    ERROR: {
+        INTERNAL: {
+            message: string;
+            chalk: import("chalk").ChalkInstance;
+        };
+    };
+};
+export declare class MessageRenderer {
+    #private;
+    message: Message;
+    constructor(message: Message, ...inputs: (string | number)[]);
+    render(): void;
+    confirm(defaultAnswer?: boolean): Promise<boolean>;
+}
+export {};

package/dist/core/modules/messages.js

@@ -0,0 +1,54 @@
+import readline from 'node:readline';
+import chalk from 'chalk';
+import { formatString } from '../../cli/utils/stringFormatter.js';
+export const MESSAGES = {
+    WARNINGS: {
+        IGNORED_FILES: {
+            message: '{0}\nThe following files will be ignored. Proceed?',
+            chalk: chalk.yellow,
+        },
+    },
+    SUCCESS: {
+        OUTPUT: {
+            message: 'Image created at {0}.',
+            chalk: chalk.blue,
+        },
+    },
+    ERROR: {
+        INTERNAL: {
+            message: 'An internal error has occurred.',
+            chalk: chalk.red,
+        },
+    },
+};
+export class MessageRenderer {
+    message;
+    #formattedMessage;
+    #message;
+    constructor(message, ...inputs) {
+        this.message = message;
+        this.#message = message;
+        const base = formatString(message.message, ...inputs);
+        this.#formattedMessage = message.chalk ? message.chalk(base) : base;
+    }
+    render() {
+        console.log(this.#formattedMessage);
+    }
+    confirm(defaultAnswer = true) {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const options = defaultAnswer ? '(Y/n)' : '(y/N)';
+        const question = this.#message.chalk
+            ? `${this.#formattedMessage} ${this.#message.chalk(options)} `
+            : `${this.#formattedMessage} ${options} `;
+        return new Promise((resolve) => {
+            rl.question(question, (value) => {
+                const cleanedValue = value.toLowerCase().trim();
+                resolve((!cleanedValue.length && !!defaultAnswer) || cleanedValue === 'y');
+                rl.close();
+            });
+        });
+    }
+}

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/pipeline/guards.d.ts

@@ -0,0 +1,4 @@
+import type { MergeContext } from './mergePipeline.js';
+export declare function requireState<TState, K extends keyof TState>(context: MergeContext<TState>, key: K): asserts context is MergeContext<TState & Required<Pick<TState, K>>>;
+export declare function requireContextProp<TState, K extends keyof MergeContext<TState>>(context: MergeContext<TState>, key: K): asserts context is MergeContext<TState> & Required<Pick<MergeContext<TState>, K>>;
+export declare function requireNonEmptyArray<T>(arr: readonly T[], name?: string): asserts arr is readonly [T, ...T[]];

package/dist/core/pipeline/guards.js

@@ -0,0 +1,23 @@
+import { MergeError } from '../mergeError.js';
+// |-------------------|
+// | Structural Guards |
+// |-------------------|
+export function requireState(context, key) {
+    if (context.state[key] === undefined) {
+        throw new MergeError(`State "${String(key)}" was not initialized`, { type: 'internal' });
+    }
+}
+export function requireContextProp(context, key) {
+    const value = context[key];
+    if (value === undefined) {
+        throw new MergeError(`Context "${String(key)}" was not initialized`, { type: 'internal' });
+    }
+}
+// |------------------|
+// | Invariant Guards |
+// |------------------|
+export function requireNonEmptyArray(arr, name = 'Array') {
+    if (arr.length === 0) {
+        throw new MergeError(`"${name}" must not be empty`, { type: 'internal' });
+    }
+}

package/dist/core/pipeline/mergePipeline.d.ts

@@ -0,0 +1,60 @@
+import sharp from 'sharp';
+import type z from 'zod';
+import type { OnProgress, ProgressInfo } from '../merges/types.js';
+export interface MergeContext<TState> {
+    inputs: sharp.SharpInput[];
+    progressInfo: ProgressInfo;
+    images: sharp.Sharp[];
+    canvas?: sharp.Sharp;
+    composites: sharp.OverlayOptions[];
+    captions: string[];
+    state: TState;
+}
+export type MergeStep<TOptions, TState> = (context: MergeContext<TState>, options: TOptions, onProgress?: OnProgress) => Promise<Buffer | void>;
+/**
+ * Pipeline orchestrator for running a sequence of merge steps that
+ * progressively build or modify a final merged image.
+ *
+ * Generic type parameters:
+ * - TOptions: the shape of the validated options object passed to each step.
+ * - TState: the shape of the pipeline's runtime state held in MergeContext.
+ *
+ * The pipeline:
+ * - Validates incoming options via a Zod schema (see createPipeline).
+ * - Maintains an ordered list of MergeStep functions to execute.
+ * - Provides optional progress reporting via an OnProgress callback.
+ *
+ * Usage:
+ * - Create an instance via createPipeline to ensure options are validated and
+ *   progressInfo is initialized on the supplied MergeContext.
+ * - Register steps with use(...).
+ * - Execute with run() — in normal usage this returns a Buffer containing the
+ *   final image. When run in "test" mode (testOptions supplied) the pipeline
+ *   may perform a dry-run and return void.
+ *
+ * Errors:
+ * - Validation-related errors thrown from createPipeline are surfaced as
+ *   MergeError instances with type 'validation' or 'internal'.
+ * - During execution, any thrown non-MergeError is converted into a runtime
+ *   Error indicating the offending step name.
+ *
+ * @template TOptions - Validated options shape used by registered steps.
+ * @template TState - Context/state shape managed by the pipeline.
+ */
+export declare class MergePipeline<TOptions, TState> {
+    private options;
+    private context;
+    private onProgress?;
+    private steps;
+    private optionsCounter;
+    private stateCounter;
+    constructor(options: TOptions, context: MergeContext<TState>, onProgress?: OnProgress | undefined);
+    static createPipeline<TZodSchema extends z.ZodType, TOptions, TState>(schema: TZodSchema, options: TOptions, context: Omit<MergeContext<TState>, 'progressInfo'>, onProgress?: OnProgress): Promise<MergePipeline<z.z.core.output<TZodSchema>, TState>>;
+    use(step: MergeStep<TOptions, TState>): this;
+    run(): Promise<Buffer>;
+    run(testOptions: {
+        logOptions?: boolean;
+        logContext?: boolean;
+    }): Promise<Buffer | void>;
+    private logForDebugging;
+}