react-native-libyuv-resizer 0.2.0

package/src/NativeLibyuvResizer.ts

@@ -0,0 +1,81 @@
+import {
+  NativeModules,
+  TurboModuleRegistry,
+  type TurboModule,
+} from 'react-native';
+
+/**
+ * Metadata returned by the native `resize()` bridge call.
+ *
+ * All numeric fields reflect the **output** file / bitmap — not the source.
+ */
+export type ResizeResult = {
+  /** Absolute path of the resized image file. */
+  path: string;
+  /** `file://` URI of the resized image file. */
+  uri: string;
+  /** File size in bytes. */
+  size: number;
+  /** File name (e.g. `"a3f2…1c.jpg"`). */
+  name: string;
+  /** Output bitmap width in pixels. */
+  width: number;
+  /** Output bitmap height in pixels. */
+  height: number;
+};
+
+/**
+ * Turbo Module contract for the native `LibyuvResizer` implementation.
+ *
+ * **Do not call this interface directly.** Use the public {@link resize}
+ * function from `./resizer` (or the package root) instead — it validates
+ * arguments and applies sensible defaults before forwarding to this bridge.
+ *
+ * This interface is consumed by React Native codegen to auto-generate the
+ * JSI glue code (`LibyuvResizerSpec`).
+ */
+export interface Spec extends TurboModule {
+  /**
+   * Low-level bridge method. Parameter order mirrors the public `resize()`
+   * signature with defaults already resolved.
+   *
+   * @param filePath    - Absolute path to the source image.
+   * @param targetWidth - Output width in pixels.
+   * @param targetHeight - Output height in pixels.
+   * @param quality     - JPEG/WebP quality `0–100`.
+   * @param rotation    - Canonical rotation in degrees (`0 | 90 | 180 | 270`).
+   * @param mode        - Resize mode string (`'contain' | 'cover' | 'stretch'`).
+   * @param outputPath  - Absolute output path, or empty string for auto.
+   * @param filterMode  - Scaling filter (`'none' | 'linear' | 'bilinear' | 'box'`).
+   * @param keepMeta    - Copy EXIF tags from source to output (JPEG only, Android only).
+   * @param format      - Output format (`'jpeg' | 'png' | 'webp'`).
+   * @returns Metadata about the resized image.
+   */
+  resize(
+    filePath: string,
+    targetWidth: number,
+    targetHeight: number,
+    quality: number,
+    rotation: number,
+    mode: string,
+    outputPath: string,
+    filterMode: string,
+    keepMeta: boolean,
+    format: string
+  ): Promise<ResizeResult>;
+}
+
+const isTurboModuleEnabled =
+  (globalThis as Record<string, unknown>).__turboModuleProxy != null;
+
+const LibyuvResizerModule: Spec = isTurboModuleEnabled
+  ? TurboModuleRegistry.getEnforcing<Spec>('LibyuvResizer')
+  : (NativeModules.LibyuvResizer as Spec);
+
+if (!LibyuvResizerModule) {
+  throw new Error(
+    'react-native-libyuv-resizer: native module not found. Did you forget to link the library?'
+  );
+}
+
+export default LibyuvResizerModule;

package/src/index.tsx

@@ -0,0 +1,23 @@
+/**
+ * `react-native-libyuv-resizer` — high-performance image resizer for React
+ * Native backed by libyuv on Android.
+ *
+ * **Entry point.** Import {@link resize} and the supporting types from here.
+ *
+ * @example
+ * ```ts
+ * import { resize } from 'react-native-libyuv-resizer';
+ *
+ * const result = await resize('/path/to/photo.jpg', 1280, 720, 85);
+ * console.log(result.path, result.width, result.height);
+ * ```
+ *
+ * @packageDocumentation
+ */
+export { resize } from './resizer';
+export type {
+  RotationAngle,
+  ResizeMode,
+  ResizeOptions,
+  ResizeResult,
+} from './resizer';

package/src/resizer.native.tsx

@@ -0,0 +1,175 @@
+import LibyuvResizer, { type ResizeResult } from './NativeLibyuvResizer';
+
+export type { ResizeResult };
+
+/**
+ * Valid rotation values in degrees.
+ * Negative angles are normalised to their positive equivalents before being
+ * sent to the native layer (`-90` → `270`, etc.).
+ */
+export type RotationAngle = 0 | 90 | 180 | 270 | -90 | -180 | -270;
+
+/**
+ * Controls how the source image is fitted into the target bounding box.
+ *
+ * - `'contain'` — scales uniformly so the entire image fits within the box,
+ *   preserving aspect ratio. Empty space is left uncropped.
+ * - `'cover'` — scales uniformly so the image fills the box, preserving
+ *   aspect ratio. Excess pixels are cropped.
+ * - `'stretch'` — scales to exactly `targetWidth × targetHeight`, ignoring
+ *   aspect ratio.
+ */
+export type ResizeMode = 'contain' | 'cover' | 'stretch';
+
+/**
+ * Scaling filter applied during the resize operation.
+ *
+ * Higher quality filters are slower. Choose based on your latency vs quality
+ * requirements.
+ *
+ * - `'none'` — nearest-neighbour; fastest, lowest quality.
+ * - `'linear'` — linear interpolation.
+ * - `'bilinear'` — bilinear interpolation.
+ * - `'box'` — box filter; best quality for downscaling *(default)*.
+ */
+export type FilterMode = 'none' | 'linear' | 'bilinear' | 'box';
+
+/**
+ * Output image format.
+ *
+ * When omitted, format is derived from `quality`: `quality === 100` → `'png'`, else `'jpeg'`.
+ * When specified, this value takes precedence over the quality-based heuristic.
+ *
+ * - `'jpeg'` — lossy JPEG.
+ * - `'png'`  — lossless PNG. `quality` is ignored.
+ * - `'webp'` — lossy WebP. `quality` controls compression level *(Android only; iOS produces JPEG)*.
+ */
+export type OutputFormat = 'jpeg' | 'png' | 'webp';
+
+/** Options accepted by {@link resize}. */
+export interface ResizeOptions {
+  /**
+   * Clockwise rotation applied to the image **before** resizing.
+   * @default 0
+   */
+  rotation?: RotationAngle;
+
+  /**
+   * How the image is fitted into the target bounding box.
+   * @default 'contain'
+   */
+  mode?: ResizeMode;
+
+  /**
+   * Scaling filter used during the resize operation.
+   * @default 'box'
+   */
+  filterMode?: FilterMode;
+
+  /**
+   * Absolute path for the output file.
+   * When omitted the native layer generates a path in the app's cache
+   * directory automatically.
+   */
+  outputPath?: string;
+
+  /**
+   * When `true`, copies all EXIF tags from the source image to the output
+   * JPEG. Has no effect on PNG or WebP output, or on iOS (no-op).
+   * @default false
+   * @platform android
+   */
+  keepMeta?: boolean;
+
+  /**
+   * Output image format. When omitted, `quality === 100` produces PNG; otherwise JPEG.
+   * Specifying `format` takes precedence over the quality-based heuristic.
+   * @default derived from quality
+   */
+  format?: OutputFormat;
+}
+
+const VALID_MODES: ResizeMode[] = ['contain', 'cover', 'stretch'];
+const VALID_FILTER_MODES: FilterMode[] = ['none', 'linear', 'bilinear', 'box'];
+const VALID_FORMATS: OutputFormat[] = ['jpeg', 'png', 'webp'];
+
+/** Normalises negative or out-of-range angles to 0 | 90 | 180 | 270. */
+function toCanonicalAngle(angle: RotationAngle): 0 | 90 | 180 | 270 {
+  return (((angle % 360) + 360) % 360) as 0 | 90 | 180 | 270;
+}
+
+/**
+ * Resizes an image using the libyuv native backend (Android).
+ *
+ * The source image is read from `filePath`, resized to the requested
+ * dimensions, and saved as a JPEG. The absolute path of the output file is
+ * returned on success.
+ *
+ * @param filePath - Absolute path to the source image.
+ * @param targetWidth - Output width in pixels (must be > 0).
+ * @param targetHeight - Output height in pixels (must be > 0).
+ * @param quality - JPEG encoding quality from `1` (lowest) to `100` (highest).
+ *   Use `100` to produce PNG output instead of JPEG.
+ * @param options - Optional resize behaviour overrides.
+ * @returns A `Promise` that resolves to a {@link ResizeResult} with the output
+ *   file path, URI, size, name, and dimensions.
+ * @throws {TypeError} When `options.mode` or `options.filterMode` is not one
+ *   of the accepted string literals.
+ *
+ * @example
+ * ```ts
+ * // Basic resize
+ * const result = await resize('/path/to/photo.jpg', 1280, 720, 85);
+ * console.log(result.path, result.width, result.height);
+ *
+ * // With options
+ * const result = await resize('/path/to/photo.jpg', 800, 600, 80, {
+ *   rotation: 90,
+ *   mode: 'cover',
+ *   filterMode: 'bilinear',
+ *   outputPath: '/path/to/output-dir',
+ * });
+ *
+ * // Preserve EXIF (GPS, camera, date) — Android only
+ * const result = await resize('/path/to/photo.jpg', 800, 600, 80, {
+ *   keepMeta: true,
+ * });
+ * ```
+ */
+export function resize(
+  filePath: string,
+  targetWidth: number,
+  targetHeight: number,
+  quality: number,
+  options?: ResizeOptions
+): Promise<ResizeResult> {
+  const rotation =
+    options?.rotation != null ? toCanonicalAngle(options.rotation) : 0;
+  const mode: ResizeMode = options?.mode ?? 'contain';
+  if (!VALID_MODES.includes(mode)) {
+    return Promise.reject(new TypeError(`Invalid resize mode: '${mode}'`));
+  }
+  const filterMode: FilterMode = options?.filterMode ?? 'box';
+  if (!VALID_FILTER_MODES.includes(filterMode)) {
+    return Promise.reject(
+      new TypeError(`Invalid filter mode: '${filterMode}'`)
+    );
+  }
+  const format: OutputFormat =
+    options?.format ?? (quality === 100 ? 'png' : 'jpeg');
+  if (!VALID_FORMATS.includes(format)) {
+    return Promise.reject(new TypeError(`Invalid format: '${format}'`));
+  }
+  return LibyuvResizer.resize(
+    filePath,
+    targetWidth,
+    targetHeight,
+    quality,
+    rotation,
+    mode,
+    options?.outputPath ?? '',
+    filterMode,
+    options?.keepMeta ?? false,
+    format
+  );
+}

package/src/resizer.tsx

@@ -0,0 +1,31 @@
+import type { ResizeOptions, ResizeResult } from './resizer.native';
+
+export type {
+  RotationAngle,
+  ResizeMode,
+  ResizeOptions,
+  ResizeResult,
+} from './resizer.native';
+
+/**
+ * Web / non-native fallback for {@link resize}.
+ *
+ * This module is selected by Metro on platforms other than Android/iOS.
+ * It always rejects because `react-native-libyuv-resizer` requires a native
+ * runtime. Import the real implementation via the `.native` platform extension.
+ *
+ * @throws {Error} Always — native platform required.
+ */
+export function resize(
+  _filePath: string,
+  _targetWidth: number,
+  _targetHeight: number,
+  _quality: number,
+  _options?: ResizeOptions
+): Promise<ResizeResult> {
+  return Promise.reject(
+    new Error(
+      "'react-native-libyuv-resizer' is only supported on native platforms."
+    )
+  );
+}