tessl/npm-qiniu-js

JavaScript SDK for Qiniu Cloud Storage that enables browser-based file uploads with resumable transfer, image processing, and comprehensive error handling.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Image Processing

Name: tessl/npm-qiniu-js
Author: tessl

Comprehensive image processing capabilities including thumbnails, advanced transformations, watermarks, and metadata extraction using Qiniu's cloud-based image processing services.

Capabilities

Advanced Image Processing (imageMogr2)

High-level image processing operations including resizing, cropping, rotation, and format conversion.

/**
 * Generate advanced image processing URL
 * @param op - Image processing operations
 * @param key - Image key in storage (optional)
 * @param domain - Domain for direct URL generation (optional)
 * @returns Processing URL or URL parameter string
 */
function imageMogr2(op: ImageMogr2, key?: string, domain?: string): string;

interface ImageMogr2 {
  /** Auto-orient based on EXIF */
  'auto-orient'?: boolean;
  /** Remove EXIF data */
  strip?: boolean;
  /** Thumbnail size specification */
  thumbnail?: number;
  /** Crop specification */
  crop?: number;
  /** Gravity for positioning */
  gravity?: number;
  /** Output format */
  format?: number;
  /** Blur radius */
  blur?: number;
  /** Quality (1-100) */
  quality?: number;
  /** Rotation angle */
  rotate?: number;
}

Usage Examples:

import { imageMogr2 } from "qiniu-js";

// Generate processing parameters only
const resizeParams = imageMogr2({
  thumbnail: 300,
  quality: 80,
  format: 1, // JPEG
  'auto-orient': true
});
// Returns: "imageMogr2/auto-orient/thumbnail/300/quality/80/format/1"

// Generate complete URL for immediate use
const processedImageUrl = imageMogr2({
  thumbnail: 200,
  crop: 200,
  gravity: 1, // Center
  strip: true
}, 'photos/original.jpg', 'https://cdn.example.com');
// Returns complete URL for processed image

// Complex processing pipeline
const advancedProcessing = imageMogr2({
  'auto-orient': true,
  thumbnail: 800,
  quality: 90,
  rotate: 90,
  blur: 3
});

Image Watermarking

Add text or image watermarks to images with positioning and style control.

/**
 * Generate watermark processing URL
 * @param op - Watermark configuration
 * @param key - Image key in storage (optional)
 * @param domain - Domain for direct URL generation (optional)
 * @returns Watermark URL or URL parameter string
 */
function watermark(op: ImageWatermark, key?: string, domain?: string): string;

interface ImageWatermark {
  /** Watermark mode: 1=image, 2=text */
  mode: number;
  /** Image URL for image watermarks (mode 1) */
  image?: string;
  /** Text content for text watermarks (mode 2) */
  text?: string;
  /** Font for text watermarks */
  font?: string;
  /** Font size for text watermarks */
  fontsize?: number;
  /** Text color for text watermarks */
  fill?: string;
  /** Transparency (0-100) */
  dissolve?: number;
  /** Horizontal offset */
  dx?: number;
  /** Vertical offset */
  dy?: number;
  /** Gravity for positioning */
  gravity?: string;
}

Usage Examples:

import { watermark } from "qiniu-js";

// Text watermark
const textWatermark = watermark({
  mode: 2,
  text: 'Copyright 2024',
  font: 'SimSun',
  fontsize: 24,
  fill: '#FFFFFF',
  dissolve: 80,
  gravity: 'SouthEast',
  dx: 10,
  dy: 10
}, 'photos/image.jpg', 'https://cdn.example.com');

// Image watermark
const logoWatermark = watermark({
  mode: 1,
  image: 'https://example.com/logo.png',
  dissolve: 70,
  gravity: 'NorthWest',
  dx: 20,
  dy: 20
});

// Multiple positioning example
const centeredWatermark = watermark({
  mode: 2,
  text: 'CONFIDENTIAL',
  fontsize: 48,
  fill: '#FF0000',
  dissolve: 50,
  gravity: 'Center'
});

Image Information Extraction

Retrieve basic image metadata and EXIF information.

/**
 * Get basic image information
 * @param key - Image key in storage
 * @param domain - Storage domain
 * @returns Promise with image metadata
 */
function imageInfo(key: string, domain: string): Promise<ResponseSuccess<ImageInfoData>>;

/**
 * Get EXIF data from image
 * @param key - Image key in storage  
 * @param domain - Storage domain
 * @returns Promise with EXIF data
 */
function exif(key: string, domain: string): Promise<ResponseSuccess<ExifData>>;

interface ResponseSuccess<T> {
  data: T;
  reqId: string;
}

Usage Examples:

import { imageInfo, exif } from "qiniu-js";

// Get basic image information
try {
  const info = await imageInfo('photos/image.jpg', 'https://cdn.example.com');
  console.log('Image info:', info.data);
  // Contains: width, height, format, size, colorModel, etc.
} catch (error) {
  console.error('Failed to get image info:', error);
}

// Get EXIF data
try {
  const exifData = await exif('photos/camera-shot.jpg', 'https://cdn.example.com');
  console.log('EXIF data:', exifData.data);
  // Contains: camera info, GPS data, shooting parameters, etc.
} catch (error) {
  console.error('Failed to get EXIF data:', error);
}

Processing Pipeline

Chain multiple image processing operations together for complex transformations.

/**
 * Chain multiple image processing operations
 * @param arr - Array of processing operations
 * @param key - Image key in storage (optional)
 * @param domain - Domain for direct URL generation (optional)
 * @returns Pipeline URL or URL parameter string
 */
function pipeline(arr: Pipeline[], key?: string, domain?: string): string;

type Pipeline = 
  | (ImageWatermark & { fop: 'watermark' })
  | (ImageViewOptions & { fop: 'imageView2' })
  | (ImageMogr2 & { fop: 'imageMogr2' });

interface ImageViewOptions {
  mode: number;
  format?: string;
  w?: number;
  h?: number;
  q?: number;
}

Usage Examples:

import { pipeline } from "qiniu-js";

// Complex processing pipeline
const complexProcessing = pipeline([
  {
    fop: 'imageMogr2',
    'auto-orient': true,
    thumbnail: 800,
    quality: 90
  },
  {
    fop: 'watermark',
    mode: 2,
    text: '© 2024',
    fontsize: 20,
    fill: '#FFFFFF',
    gravity: 'SouthEast',
    dx: 10,
    dy: 10
  },
  {
    fop: 'imageView2',
    mode: 1,
    w: 600,
    h: 400,
    q: 85
  }
], 'photos/original.jpg', 'https://cdn.example.com');

// Thumbnail with watermark pipeline
const thumbnailPipeline = pipeline([
  {
    fop: 'imageMogr2',
    thumbnail: 300,
    crop: 300,
    gravity: 1
  },
  {
    fop: 'watermark',
    mode: 1,
    image: 'https://example.com/small-logo.png',
    dissolve: 60,
    gravity: 'NorthEast'
  }
]);

Processing Specifications

Thumbnail Modes

For thumbnail parameter in imageMogr2:

Numbers represent pixel dimensions
Can specify width and height constraints
Maintains aspect ratio by default

Gravity Values

Positioning reference points:

1 or 'Center' - Center position
'NorthWest' - Top-left corner
'North' - Top-center
'NorthEast' - Top-right corner
'West' - Middle-left
'East' - Middle-right
'SouthWest' - Bottom-left corner
'South' - Bottom-center
'SouthEast' - Bottom-right corner

Format Values

For format parameter:

0 - Original format
1 - JPEG
2 - GIF
3 - PNG
4 - WebP

Quality Settings

For quality parameter:

Range: 1-100
Higher values = better quality, larger file size
Recommended: 75-90 for most use cases

Complete Example:

import { imageMogr2, watermark, pipeline, imageInfo } from "qiniu-js";

async function processUserAvatar(imageKey: string, domain: string) {
  try {
    // First get image info to check dimensions
    const info = await imageInfo(imageKey, domain);
    console.log(`Original image: ${info.data.width}x${info.data.height}`);
    
    // Create optimized avatar with watermark
    const avatarUrl = pipeline([
      {
        fop: 'imageMogr2',
        'auto-orient': true,
        thumbnail: 200,
        crop: 200,
        gravity: 1,
        quality: 90,
        format: 1
      },
      {
        fop: 'watermark',
        mode: 2,
        text: 'Profile',
        fontsize: 12,
        fill: '#FFFFFF',
        dissolve: 70,
        gravity: 'SouthEast',
        dx: 5,
        dy: 5
      }
    ], imageKey, domain);
    
    return avatarUrl;
  } catch (error) {
    console.error('Image processing failed:', error);
    throw error;
  }
}

Install with Tessl CLI