@warlock.js/core 4.0.48 → 4.0.59

package/esm/image/image.d.ts

@@ -0,0 +1,388 @@
+/// <reference types="node" />
+import type sharp from "sharp";
+import type { FormatEnum } from "sharp";
+export type ImageFormat = keyof FormatEnum;
+export type ImageInput = string | Buffer | Uint8Array | ArrayBuffer;
+/**
+ * Watermark configuration for deferred execution
+ */
+export type WatermarkConfig = {
+    image: ImageInput | Image;
+    options: sharp.OverlayOptions;
+};
+/**
+ * Operation descriptor for deferred pipeline execution.
+ * All operations are stored and executed at save/toBuffer time.
+ */
+type ImageOperation = {
+    type: "resize";
+    options: sharp.ResizeOptions;
+} | {
+    type: "crop";
+    options: sharp.Region;
+} | {
+    type: "rotate";
+    angle: number;
+} | {
+    type: "flip";
+} | {
+    type: "flop";
+} | {
+    type: "blur";
+    sigma: number;
+} | {
+    type: "sharpen";
+    options?: sharp.SharpenOptions;
+} | {
+    type: "blackAndWhite";
+} | {
+    type: "opacity";
+    value: number;
+} | {
+    type: "negate";
+    options?: sharp.NegateOptions;
+} | {
+    type: "tint";
+    color: sharp.Color;
+} | {
+    type: "trim";
+    options?: sharp.TrimOptions;
+} | {
+    type: "watermark";
+    config: WatermarkConfig;
+} | {
+    type: "watermarks";
+    configs: WatermarkConfig[];
+};
+/**
+ * Transformation options that can be applied in batch via `apply()` method.
+ *
+ * **Execution Order (when using apply()):**
+ * 1. resize - Resize first to work with correct dimensions
+ * 2. crop - Crop after resize to extract the desired region
+ * 3. rotate - Rotation after sizing
+ * 4. flip/flop - Mirror operations
+ * 5. blackAndWhite/grayscale - Color space conversion
+ * 6. blur - Blur effect
+ * 7. sharpen - Sharpen effect
+ * 8. tint - Color overlay
+ * 9. negate - Invert colors
+ * 10. opacity - Transparency (applied via composite)
+ * 11. format/quality - Applied on save/export
+ */
+export type ImageTransformOptions = {
+    /**
+     * Output quality (1-100), applied based on final format
+     */
+    quality?: number;
+    /**
+     * Output format (jpeg, png, webp, avif, etc.)
+     */
+    format?: ImageFormat;
+    /**
+     * Resize options
+     */
+    resize?: sharp.ResizeOptions;
+    /**
+     * Crop/extract region
+     */
+    crop?: sharp.Region;
+    /**
+     * Rotation angle in degrees
+     */
+    rotate?: number;
+    /**
+     * Flip vertically (top to bottom)
+     */
+    flip?: boolean;
+    /**
+     * Flop horizontally (left to right)
+     */
+    flop?: boolean;
+    /**
+     * Convert to black and white
+     */
+    blackAndWhite?: boolean;
+    /**
+     * Alias for blackAndWhite
+     */
+    grayscale?: boolean;
+    /**
+     * Blur sigma (must be >= 0.3)
+     */
+    blur?: number;
+    /**
+     * Sharpen options
+     */
+    sharpen?: sharp.SharpenOptions | boolean;
+    /**
+     * Tint color
+     */
+    tint?: sharp.Color;
+    /**
+     * Negate/invert colors
+     */
+    negate?: sharp.NegateOptions | boolean;
+    /**
+     * Opacity (0-100)
+     */
+    opacity?: number;
+    /**
+     * Trim options
+     */
+    trim?: sharp.TrimOptions | boolean;
+    /**
+     * Single watermark
+     */
+    watermark?: WatermarkConfig;
+    /**
+     * Multiple watermarks
+     */
+    watermarks?: WatermarkConfig[];
+};
+/**
+ * Internal options stored for deferred application
+ */
+type InternalOptions = {
+    quality?: number;
+    format?: ImageFormat;
+};
+/**
+ * Image manipulation class with deferred pipeline execution.
+ *
+ * **Important:** This class requires the `sharp` package to be installed.
+ * Install it with: `warlock add image` or `npm install sharp`
+ *
+ * Sharp is lazy-loaded on the first async operation (save, toBuffer, etc.),
+ * so the constructor and all chainable methods remain synchronous.
+ *
+ * All operations are synchronous and stored as descriptors.
+ * The pipeline is executed only when calling output methods:
+ * - `save()` - Save to file
+ * - `toBuffer()` - Get as buffer
+ * - `toBase64()` - Get as base64 string
+ * - `toDataUrl()` - Get as data URL
+ *
+ * @example
+ * ```typescript
+ * // All chaining is synchronous - single await at the end
+ * await new Image("photo.jpg")
+ *   .resize({ width: 800 })
+ *   .watermark("logo.png", { gravity: "southeast" })
+ *   .quality(85)
+ *   .save("output.jpg");
+ * ```
+ */
+export declare class Image {
+    /**
+     * Image options that will be applied on save/export
+     */
+    protected options: InternalOptions;
+    /**
+     * Deferred operations pipeline
+     */
+    protected operations: ImageOperation[];
+    /**
+     * Cached metadata to avoid repeated async calls
+     */
+    protected cachedMetadata: sharp.Metadata | null;
+    /**
+     * Whether the pipeline has been executed
+     */
+    protected pipelineExecuted: boolean;
+    /**
+     * Sharp image object
+     */
+    readonly image: sharp.Sharp;
+    /**
+     * Formats that support quality option
+     */
+    protected static readonly QUALITY_FORMATS: string[];
+    /**
+     * Constructor
+     */
+    constructor(image: ImageInput | sharp.Sharp);
+    /**
+     * Create image instance from file path
+     */
+    static fromFile(path: string): Image;
+    /**
+     * Create image instance from buffer
+     */
+    static fromBuffer(buffer: Buffer): Image;
+    /**
+     * Create image instance from url
+     */
+    static fromUrl(url: string): Promise<Image>;
+    /**
+     * Add an operation to the deferred pipeline
+     */
+    protected addOperation(operation: ImageOperation): this;
+    /**
+     * Apply multiple transformations at once with a predefined execution order.
+     *
+     * This method ensures transformations are applied in a logical order:
+     * resize → crop → rotate → flip/flop → colorspace → effects → opacity → format
+     *
+     * For custom ordering, use individual chained methods instead.
+     */
+    apply(options: ImageTransformOptions): this;
+    /**
+     * Set image opacity (0-100)
+     */
+    opacity(value: number): this;
+    /**
+     * Convert image to black and white
+     */
+    blackAndWhite(): this;
+    /**
+     * Alias for blackAndWhite
+     */
+    grayscale(): this;
+    /**
+     * Get image dimensions (cached after first call)
+     */
+    dimensions(): Promise<{
+        width: number | undefined;
+        height: number | undefined;
+    }>;
+    /**
+     * Get image metadata (cached after first call)
+     *
+     * The metadata is cached to avoid repeated async operations.
+     * Use `refreshMetadata()` to force a fresh fetch.
+     */
+    metadata(): Promise<sharp.Metadata>;
+    /**
+     * Force refresh of cached metadata
+     *
+     * Call this after transformations if you need updated metadata.
+     */
+    refreshMetadata(): Promise<sharp.Metadata>;
+    /**
+     * Clear cached metadata
+     */
+    clearMetadataCache(): this;
+    /**
+     * Resize image
+     */
+    resize(options: sharp.ResizeOptions): this;
+    /**
+     * Crop/extract a region from the image
+     */
+    crop(options: sharp.Region): this;
+    /**
+     * Set image quality (1-100)
+     * Quality is stored and applied when saving/exporting
+     * based on the final format.
+     */
+    quality(quality: number): this;
+    /**
+     * Execute the deferred pipeline - apply all stored operations
+     */
+    protected executePipeline(): Promise<sharp.Sharp>;
+    /**
+     * Execute a single operation
+     */
+    protected executeOperation(image: sharp.Sharp, operation: ImageOperation): Promise<void>;
+    /**
+     * Resolve an image input to a buffer
+     */
+    protected resolveImageBuffer(input: ImageInput | Image): Promise<Buffer>;
+    /**
+     * Apply format and quality options.
+     * If no format is explicitly set, preserves the original format and applies
+     * quality appropriately based on the format type.
+     */
+    protected applyFormatAndQuality(image: sharp.Sharp): Promise<void>;
+    /**
+     * Save to file
+     */
+    save(path: string): Promise<sharp.OutputInfo>;
+    /**
+     * Convert to webp and save to file
+     */
+    saveAsWebp(path: string): Promise<sharp.OutputInfo>;
+    /**
+     * Change the file format
+     */
+    format(format: ImageFormat): this;
+    /**
+     * Add watermark (deferred - executed at save time)
+     */
+    watermark(image: ImageInput | Image, options?: sharp.OverlayOptions): this;
+    /**
+     * Add multiple watermarks (deferred - executed at save time)
+     */
+    watermarks(configs: WatermarkConfig[]): this;
+    /**
+     * Rotate image
+     */
+    rotate(angle: number): this;
+    /**
+     * Flip image vertically (top to bottom)
+     */
+    flip(): this;
+    /**
+     * Flop image horizontally (left to right)
+     */
+    flop(): this;
+    /**
+     * Blur image
+     */
+    blur(sigma: number): this;
+    /**
+     * Convert to base64
+     */
+    toBase64(): Promise<string>;
+    /**
+     * Convert to data URL (base64 with mime type prefix)
+     */
+    toDataUrl(): Promise<string>;
+    /**
+     * Sharpen image
+     */
+    sharpen(options?: sharp.SharpenOptions): this;
+    /**
+     * Negate/invert image colors
+     */
+    negate(options?: sharp.NegateOptions): this;
+    /**
+     * Tint image with a color
+     */
+    tint(color: sharp.Color): this;
+    /**
+     * Trim edges from the image
+     */
+    trim(options?: sharp.TrimOptions): this;
+    /**
+     * Convert to buffer
+     */
+    toBuffer(): Promise<Buffer>;
+    /**
+     * Clone the image for separate transformations
+     */
+    clone(): Image;
+    /**
+     * Get the current stored options
+     */
+    getOptions(): Readonly<InternalOptions>;
+    /**
+     * Get the pending operations count
+     */
+    getPendingOperationsCount(): number;
+    /**
+     * Reset all stored options
+     */
+    resetOptions(): this;
+    /**
+     * Clear all pending operations
+     */
+    clearOperations(): this;
+    /**
+     * Reset the image to its initial state (clear operations and options)
+     */
+    reset(): this;
+}
+export {};
+//# sourceMappingURL=image.d.ts.map

package/esm/image/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/image/image.ts"],"names":[],"mappings":"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"}