react-native-image-compression-kit 0.1.0

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "react-native-image-compression-kit",
+  "version": "0.1.0",
+  "description": "Native-first image compression and transcoding pipeline for React Native.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GGULBAE/react-native-image-compression-kit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GGULBAE/react-native-image-compression-kit/issues"
+  },
+  "homepage": "https://github.com/GGULBAE/react-native-image-compression-kit#readme",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "files": [
+    "android/build.gradle",
+    "android/src/main",
+    "ios",
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE",
+    "react-native-image-compression-kit.podspec",
+    "react-native.config.js"
+  ],
+  "keywords": [
+    "react-native",
+    "image",
+    "image-processing",
+    "compression",
+    "resize",
+    "transcode",
+    "jpeg",
+    "png",
+    "webp",
+    "heic",
+    "heif",
+    "avif"
+  ],
+  "peerDependencies": {
+    "react-native": ">=0.73 <1.0"
+  },
+  "codegenConfig": {
+    "name": "RNImageCompressionKitSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "outputDir": {
+      "ios": "ios/generated",
+      "android": "android/generated"
+    },
+    "android": {
+      "javaPackageName": "com.imagecompressionkit"
+    },
+    "ios": {
+      "modulesProvider": {
+        "ImageCompressionKit": "RCTImageCompressionKit"
+      }
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "example:android": "pnpm --filter image-compression-kit-example android",
+    "example:build": "RNICK_ANDROID_APP_DIR=example/android pnpm android:build",
+    "example:codegen": "RNICK_ANDROID_APP_DIR=example/android pnpm android:codegen",
+    "example:android-instrumentation": "RNICK_ANDROID_APP_DIR=example/android RNICK_ANDROID_GRADLE_TASK=:react-native-image-compression-kit:connectedDebugAndroidTest pnpm android:build",
+    "example:android-unit-test": "RNICK_ANDROID_APP_DIR=example/android RNICK_ANDROID_GRADLE_TASK=:react-native-image-compression-kit:testDebugUnitTest pnpm android:build",
+    "example:start": "pnpm --filter image-compression-kit-example start",
+    "example:typecheck": "pnpm --filter image-compression-kit-example typecheck",
+    "fixtures:avif": "node scripts/generate-avif-fixtures.mjs",
+    "fixtures:avif:check": "node scripts/generate-avif-fixtures.mjs --check",
+    "fixtures:heic-heif": "node scripts/generate-heic-heif-fixtures.mjs",
+    "fixtures:heic-heif:check": "node scripts/generate-heic-heif-fixtures.mjs --check",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "release:dry-run": "node scripts/release-dry-run.mjs",
+    "smoke:consumer": "pnpm build && node scripts/consumer-smoke-test.mjs",
+    "verify": "pnpm typecheck && pnpm test && pnpm build && pnpm android:doctor",
+    "android:doctor": "node scripts/android-verification.mjs doctor",
+    "android:codegen": "node scripts/android-verification.mjs codegen",
+    "android:build": "node scripts/android-verification.mjs build",
+    "docker:android:build": "node scripts/docker-android.mjs build",
+    "docker:android:verify": "node scripts/docker-android.mjs verify",
+    "docker:android:example:typecheck": "node scripts/docker-android.mjs example:typecheck",
+    "docker:android:example:codegen": "node scripts/docker-android.mjs example:codegen",
+    "docker:android:example:android-unit-test": "node scripts/docker-android.mjs example:android-unit-test",
+    "docker:android:example:build": "node scripts/docker-android.mjs example:build",
+    "docker:android:ci": "node scripts/docker-android.mjs ci",
+    "docker:android:shell": "node scripts/docker-android.mjs shell",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/react-native-image-compression-kit.podspec

@@ -0,0 +1,21 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name = "react-native-image-compression-kit"
+  s.version = package["version"]
+  s.summary = package["description"]
+  s.license = package["license"]
+  s.homepage = "https://github.com/GGULBAE/react-native-image-compression-kit"
+  s.authors = "react-native-image-compression-kit contributors"
+  s.source = { :git => "https://github.com/GGULBAE/react-native-image-compression-kit.git", :tag => "#{s.version}" }
+  s.platforms = { :ios => "13.4" }
+  s.source_files = "ios/**/*.{h,m,mm}"
+
+  if respond_to?(:install_modules_dependencies, true)
+    install_modules_dependencies(s)
+  else
+    s.dependency "React-Core"
+  end
+end

package/react-native.config.js

@@ -0,0 +1,12 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath:
+          'import com.imagecompressionkit.ImageCompressionKitPackage;',
+        packageInstance: 'new ImageCompressionKitPackage()',
+      },
+    },
+  },
+};

package/src/NativeImageCompressionKit.ts

@@ -0,0 +1,81 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export type NativeImageFormat =
+  | 'jpeg'
+  | 'png'
+  | 'webp'
+  | 'heic'
+  | 'heif'
+  | 'avif'
+  | 'gif';
+
+export type NativeOutputFormat =
+  | 'jpeg'
+  | 'png'
+  | 'webp'
+  | 'heic'
+  | 'heif'
+  | 'avif';
+
+export type NativeMetadataPolicy = 'preserve' | 'safe' | 'strip';
+export type NativeResizeMode = 'contain' | 'cover' | 'stretch';
+
+export type NativeCompressionSource = {
+  uri: string;
+};
+
+export type NativeResizeOptions = {
+  maxWidth?: number;
+  maxHeight?: number;
+  mode: NativeResizeMode;
+};
+
+export type NativeOutputOptions = {
+  format: NativeOutputFormat;
+  quality?: number;
+  maxBytes?: number;
+};
+
+export type NativeCompressionOptions = {
+  source: NativeCompressionSource;
+  resize?: NativeResizeOptions;
+  output: NativeOutputOptions;
+  metadata: NativeMetadataPolicy;
+};
+
+export type NativeCompressionResult = {
+  uri: string;
+  format: NativeOutputFormat;
+  width: number;
+  height: number;
+  byteSize: number;
+  originalByteSize: number;
+  compressionRatio: number;
+};
+
+export type NativeFormatCapability = {
+  format: NativeImageFormat;
+  input: boolean;
+  output: boolean;
+  supportsAlpha: boolean;
+  supportsAnimation: boolean;
+  notes?: Array<string>;
+};
+
+export type NativeImageCompressionCapabilities = {
+  platform: 'android' | 'ios' | 'unknown';
+  formats: Array<NativeFormatCapability>;
+  metadataPolicies: Array<NativeMetadataPolicy>;
+  supportsTargetSizeCompression: boolean;
+  supportsCancellation: boolean;
+};
+
+export interface Spec extends TurboModule {
+  compressImage(
+    options: NativeCompressionOptions
+  ): Promise<NativeCompressionResult>;
+  getImageCompressionCapabilities(): Promise<NativeImageCompressionCapabilities>;
+}
+
+export default TurboModuleRegistry.get<Spec>('ImageCompressionKit');

package/src/api.ts

@@ -0,0 +1,28 @@
+import { normalizeNativeError } from './errors';
+import { getNativeModule } from './nativeModule';
+import type {
+  CompressionOptions,
+  CompressionResult,
+  ImageCompressionCapabilities,
+} from './types';
+import { normalizeCompressionOptions } from './validation';
+
+export async function compressImage(
+  options: CompressionOptions
+): Promise<CompressionResult> {
+  const normalizedOptions = normalizeCompressionOptions(options);
+
+  try {
+    return await getNativeModule().compressImage(normalizedOptions);
+  } catch (error) {
+    throw normalizeNativeError(error);
+  }
+}
+
+export async function getImageCompressionCapabilities(): Promise<ImageCompressionCapabilities> {
+  try {
+    return await getNativeModule().getImageCompressionCapabilities();
+  } catch (error) {
+    throw normalizeNativeError(error);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,91 @@
+export type ImageCompressionKitErrorCode =
+  | 'ERR_INVALID_OPTIONS'
+  | 'ERR_UNSUPPORTED_SOURCE'
+  | 'ERR_UNSUPPORTED_FORMAT'
+  | 'ERR_NATIVE_MODULE_UNAVAILABLE'
+  | 'ERR_NOT_IMPLEMENTED'
+  | 'ERR_FILE_ACCESS'
+  | 'ERR_DECODE_FAILED'
+  | 'ERR_ENCODE_FAILED'
+  | 'ERR_NATIVE_OPERATION_FAILED';
+
+export class ImageCompressionKitError extends Error {
+  readonly code: ImageCompressionKitErrorCode;
+
+  constructor(
+    code: ImageCompressionKitErrorCode,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message);
+    this.name = 'ImageCompressionKitError';
+    this.code = code;
+
+    if (options && 'cause' in options) {
+      (this as Error & { cause?: unknown }).cause = options.cause;
+    }
+  }
+}
+
+export function normalizeNativeError(error: unknown): Error {
+  if (error instanceof ImageCompressionKitError) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return new ImageCompressionKitError(
+      getNativeErrorCode(error),
+      error.message || 'Native image compression failed.',
+      { cause: error }
+    );
+  }
+
+  if (isRecord(error)) {
+    const message =
+      typeof error.message === 'string'
+        ? error.message
+        : 'Native image compression failed.';
+
+    return new ImageCompressionKitError(
+      getNativeErrorCode(error),
+      message,
+      { cause: error }
+    );
+  }
+
+  return new ImageCompressionKitError(
+    'ERR_NATIVE_OPERATION_FAILED',
+    'Native image compression failed.',
+    { cause: error }
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function getNativeErrorCode(value: unknown): ImageCompressionKitErrorCode {
+  if (!isRecord(value) || typeof value.code !== 'string') {
+    return 'ERR_NATIVE_OPERATION_FAILED';
+  }
+
+  return isImageCompressionKitErrorCode(value.code)
+    ? value.code
+    : 'ERR_NATIVE_OPERATION_FAILED';
+}
+
+function isImageCompressionKitErrorCode(
+  code: string
+): code is ImageCompressionKitErrorCode {
+  return (
+    code === 'ERR_INVALID_OPTIONS' ||
+    code === 'ERR_UNSUPPORTED_SOURCE' ||
+    code === 'ERR_UNSUPPORTED_FORMAT' ||
+    code === 'ERR_NATIVE_MODULE_UNAVAILABLE' ||
+    code === 'ERR_NOT_IMPLEMENTED' ||
+    code === 'ERR_FILE_ACCESS' ||
+    code === 'ERR_DECODE_FAILED' ||
+    code === 'ERR_ENCODE_FAILED' ||
+    code === 'ERR_NATIVE_OPERATION_FAILED'
+  );
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+export {
+  compressImage,
+  getImageCompressionCapabilities,
+} from './api';
+export { ImageCompressionKitError } from './errors';
+export {
+  IMAGE_FORMATS,
+  METADATA_POLICIES,
+  OUTPUT_FORMATS,
+  RESIZE_MODES,
+} from './types';
+export type {
+  CompressionOptions,
+  CompressionResult,
+  CompressionSource,
+  FormatCapability,
+  ImageCompressionCapabilities,
+  ImageFormat,
+  MetadataPolicy,
+  NormalizedCompressionOptions,
+  OutputFormat,
+  OutputOptions,
+  ResizeMode,
+  ResizeOptions,
+} from './types';

package/src/nativeModule.ts

@@ -0,0 +1,130 @@
+import { ImageCompressionKitError } from './errors';
+import type { Spec as NativeImageCompressionKitSpec } from './NativeImageCompressionKit';
+import type {
+  CompressionResult,
+  ImageCompressionCapabilities,
+  NormalizedCompressionOptions,
+} from './types';
+
+export const NATIVE_MODULE_NAME = 'ImageCompressionKit';
+
+export type NativeImageCompressionKitModule = NativeImageCompressionKitSpec;
+
+type NativeModuleContractCheck = {
+  compressImage(
+    options: NormalizedCompressionOptions
+  ): Promise<CompressionResult>;
+  getImageCompressionCapabilities(): Promise<ImageCompressionCapabilities>;
+};
+
+const _nativeModuleContractCheck: NativeImageCompressionKitModule extends NativeModuleContractCheck
+  ? true
+  : never = true;
+
+type ReactNativeRuntime = {
+  NativeModules?: Record<string, unknown>;
+  TurboModuleRegistry?: {
+    get?: <T>(name: string) => T | null;
+  };
+};
+
+declare const require: ((moduleName: string) => unknown) | undefined;
+
+let testNativeModule: NativeImageCompressionKitModule | null | undefined;
+
+export function getNativeModule(): NativeImageCompressionKitModule {
+  const nativeModule =
+    testNativeModule !== undefined
+      ? testNativeModule
+      : resolveNativeModuleFromReactNative();
+
+  if (nativeModule) {
+    return nativeModule;
+  }
+
+  throw new ImageCompressionKitError(
+    'ERR_NATIVE_MODULE_UNAVAILABLE',
+    `Native module ${NATIVE_MODULE_NAME} is unavailable. The TypeScript API is scaffolded, but Android and iOS implementations have not been added yet.`
+  );
+}
+
+export function setNativeModuleForTesting(
+  nativeModule: NativeImageCompressionKitModule | null
+): void {
+  testNativeModule = nativeModule;
+}
+
+export function resetNativeModuleForTesting(): void {
+  testNativeModule = undefined;
+}
+
+function resolveNativeModuleFromReactNative():
+  | NativeImageCompressionKitModule
+  | null {
+  const codegenModule = resolveNativeModuleFromCodegenSpec();
+
+  if (codegenModule) {
+    return codegenModule;
+  }
+
+  const reactNative = loadReactNativeRuntime();
+
+  const turboModule = reactNative?.TurboModuleRegistry?.get?.<
+    NativeImageCompressionKitModule
+  >(NATIVE_MODULE_NAME);
+
+  if (isNativeModule(turboModule)) {
+    return turboModule;
+  }
+
+  const legacyModule = reactNative?.NativeModules?.[NATIVE_MODULE_NAME];
+
+  if (isNativeModule(legacyModule)) {
+    return legacyModule;
+  }
+
+  return null;
+}
+
+function resolveNativeModuleFromCodegenSpec():
+  | NativeImageCompressionKitModule
+  | null {
+  if (typeof require !== 'function') {
+    return null;
+  }
+
+  try {
+    const codegenSpec = require('./NativeImageCompressionKit') as {
+      default?: unknown;
+    };
+
+    return isNativeModule(codegenSpec.default) ? codegenSpec.default : null;
+  } catch {
+    return null;
+  }
+}
+
+function loadReactNativeRuntime(): ReactNativeRuntime | null {
+  if (typeof require !== 'function') {
+    return null;
+  }
+
+  try {
+    return require('react-native') as ReactNativeRuntime;
+  } catch {
+    return null;
+  }
+}
+
+function isNativeModule(
+  value: unknown
+): value is NativeImageCompressionKitModule {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as NativeImageCompressionKitModule).compressImage ===
+      'function' &&
+    typeof (value as NativeImageCompressionKitModule)
+      .getImageCompressionCapabilities === 'function'
+  );
+}

package/src/types.ts

@@ -0,0 +1,88 @@
+export const IMAGE_FORMATS = [
+  'jpeg',
+  'png',
+  'webp',
+  'heic',
+  'heif',
+  'avif',
+  'gif',
+] as const;
+
+export const OUTPUT_FORMATS = [
+  'jpeg',
+  'png',
+  'webp',
+  'heic',
+  'heif',
+  'avif',
+] as const;
+
+export const METADATA_POLICIES = ['preserve', 'safe', 'strip'] as const;
+
+export const RESIZE_MODES = ['contain', 'cover', 'stretch'] as const;
+
+export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+export type OutputFormat = (typeof OUTPUT_FORMATS)[number];
+export type MetadataPolicy = (typeof METADATA_POLICIES)[number];
+export type ResizeMode = (typeof RESIZE_MODES)[number];
+
+export interface CompressionSource {
+  uri: string;
+}
+
+export interface ResizeOptions {
+  maxWidth?: number;
+  maxHeight?: number;
+  mode?: ResizeMode;
+}
+
+export interface OutputOptions {
+  format: OutputFormat;
+  quality?: number;
+  maxBytes?: number;
+}
+
+export interface CompressionOptions {
+  source: CompressionSource;
+  resize?: ResizeOptions;
+  output: OutputOptions;
+  metadata?: MetadataPolicy;
+}
+
+export interface NormalizedResizeOptions
+  extends Omit<ResizeOptions, 'mode'> {
+  mode: ResizeMode;
+}
+
+export interface NormalizedCompressionOptions
+  extends Omit<CompressionOptions, 'metadata' | 'resize'> {
+  metadata: MetadataPolicy;
+  resize?: NormalizedResizeOptions;
+}
+
+export interface CompressionResult {
+  uri: string;
+  format: OutputFormat;
+  width: number;
+  height: number;
+  byteSize: number;
+  originalByteSize: number;
+  compressionRatio: number;
+}
+
+export interface FormatCapability {
+  format: ImageFormat;
+  input: boolean;
+  output: boolean;
+  supportsAlpha: boolean;
+  supportsAnimation: boolean;
+  notes?: string[];
+}
+
+export interface ImageCompressionCapabilities {
+  platform: 'android' | 'ios' | 'unknown';
+  formats: FormatCapability[];
+  metadataPolicies: MetadataPolicy[];
+  supportsTargetSizeCompression: boolean;
+  supportsCancellation: boolean;
+}