@aquienpz/asset-compressor-web 0.4.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@aquienpz/asset-compressor-web",
+  "version": "0.4.0",
+  "description": "Browser-side image compression (compressorjs + heic2any) for the @aquienpz asset platform.",
+  "private": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/espaciofuturoio/aquienpz.git",
+    "directory": "packages/asset-compressor-web"
+  },
+  "homepage": "https://github.com/espaciofuturoio/aquienpz/tree/main/packages/asset-compressor-web",
+  "license": "UNLICENSED",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src/**"
+  ],
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "compressorjs": "^1.2.1",
+    "heic2any": "^0.0.4",
+    "p-limit": "^7.1.1"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/src/compression.ts

@@ -0,0 +1,133 @@
+/**
+ * Browser-side image compression. Wraps `compressorjs` (Canvas-based) +
+ * lazy HEIC fallback. Suitable for product photos, listing photos,
+ * receipts — anything you want to shrink BEFORE upload to save bandwidth
+ * and let the server-side variant generator focus on resizing, not on
+ * decoding 50MB iPhone JPEGs.
+ *
+ * Status callback is intentionally per-file (not per-batch) so a UI can
+ * show "converting HEIC…" / "compressing…" per row.
+ */
+
+import pLimit from "p-limit";
+import {
+  DEFAULT_COMPRESSION_OPTIONS,
+  DEFAULT_CPU_WORK_CONCURRENCY,
+  getOptimalCpuConcurrency,
+  isHeic,
+} from "./constants";
+import type {
+  CompressedResult,
+  CompressionError,
+  CompressionOptions,
+  CompressionStatusKey,
+} from "./types";
+
+export type CompressInput = {
+  blob: Blob;
+  filename: string;
+  /** Caller-supplied stable id; passed back unchanged in result/error */
+  id?: string;
+};
+
+/**
+ * Compress a single image. Designed to be called directly when you only
+ * have one file; otherwise use `compressImages` for batched concurrency.
+ */
+export async function compressImage(opts: {
+  blob: Blob;
+  filename: string;
+  options?: CompressionOptions;
+  originalArrayIndex?: number;
+  statusCallback?: (status: CompressionStatusKey) => void;
+}): Promise<CompressedResult> {
+  const opt = { ...DEFAULT_COMPRESSION_OPTIONS, ...opts.options };
+  if (opts.options?.keepOriginalDimensions) {
+    opt.maxWidth = Number.POSITIVE_INFINITY;
+    opt.maxHeight = Number.POSITIVE_INFINITY;
+  }
+
+  let processedBlob = opts.blob;
+  let processedFilename = opts.filename;
+
+  // HEIC → JPEG first, then compressor handles the rest.
+  if (opts.blob instanceof File && isHeic(opts.blob)) {
+    opts.statusCallback?.("convertingHeic");
+    const { convertHeicFile } = await import("./heic-converter");
+    const converted = await convertHeicFile(opts.blob, opt.quality);
+    processedBlob = converted;
+    processedFilename = converted.name;
+  }
+
+  opts.statusCallback?.(
+    opts.options?.keepOriginalDimensions ? "compressingKeepingDimensions" : "compressing",
+  );
+
+  const mod = await import("compressorjs");
+  const Compressor = (mod as { default: typeof import("compressorjs").default }).default;
+
+  return new Promise<CompressedResult>((resolve, reject) => {
+    new Compressor(processedBlob, {
+      ...opt,
+      success(out) {
+        const originalSize = opts.blob.size;
+        const compressedSize = out.size;
+        opts.statusCallback?.("done");
+        resolve({
+          blob: out,
+          filename: processedFilename,
+          originalSize,
+          compressedSize,
+          compressionRatio: originalSize > 0 ? compressedSize / originalSize : 1,
+          originalArrayIndex: opts.originalArrayIndex ?? 0,
+        });
+      },
+      error(err) {
+        reject(
+          new Error(`compress failed for ${processedFilename}: ${err.message}`),
+        );
+      },
+    });
+  });
+}
+
+/**
+ * Compress many images with concurrency control. Failures are returned
+ * — they don't reject the overall promise, so a single bad file can't
+ * sink a whole batch.
+ */
+export async function compressImages(
+  images: CompressInput[],
+  options: CompressionOptions = {},
+  statusCallback?: (id: string, status: CompressionStatusKey) => void,
+): Promise<{ successful: CompressedResult[]; failed: CompressionError[] }> {
+  const successful: CompressedResult[] = [];
+  const failed: CompressionError[] = [];
+  const limit = pLimit(getOptimalCpuConcurrency(DEFAULT_CPU_WORK_CONCURRENCY));
+
+  await Promise.all(
+    images.map((img, index) =>
+      limit(async () => {
+        try {
+          const r = await compressImage({
+            blob: img.blob,
+            filename: img.filename,
+            options,
+            originalArrayIndex: index,
+            statusCallback: img.id ? (s) => statusCallback?.(img.id!, s) : undefined,
+          });
+          successful.push(r);
+        } catch (err) {
+          failed.push({
+            filename: img.filename,
+            originalBlob: img.blob,
+            error: err instanceof Error ? err : new Error(String(err)),
+            originalArrayIndex: index,
+          });
+        }
+      }),
+    ),
+  );
+
+  return { successful, failed };
+}

package/src/constants.ts

@@ -0,0 +1,79 @@
+/**
+ * Defaults for the web compressor. Values copied from
+ * neo-real-estate-v2 production tuning (LISTING_STANDARD_*) so first-time
+ * adopters get the same field-tested behavior without reading source.
+ */
+
+import type { CompressionOptions } from "./types";
+
+/** Quality on a 0..1 scale. 0.85 ≈ visually lossless for product photos. */
+const STANDARD_QUALITY = 0.85;
+
+/** Maximum dimension (longest side) of the compressed output. */
+export const MAX_UPLOAD_DIMENSION = 2880;
+
+/**
+ * Defaults: compression ALWAYS runs and ALWAYS outputs WebP regardless of
+ * source format. Why:
+ *
+ *   - WebP beats JPEG (~30% smaller at same quality) and crushes PNG
+ *     (~70% smaller for photos), and is universally supported in browsers
+ *     since 2020.
+ *   - The asset-manager generates WebP variants server-side anyway, so
+ *     uploading WebP costs nothing in fidelity but saves real bandwidth.
+ *   - We DO NOT use compressorjs's `convertSize` gate (which would skip
+ *     re-encoding for files under 5MB) because users expect the upload
+ *     row to show a savings ratio for every image, not just the big ones.
+ *
+ * Override per call if a use case needs the original format preserved
+ * (e.g. uploading a PNG for icon-extraction where the alpha channel must
+ * be exact).
+ */
+export const DEFAULT_COMPRESSION_OPTIONS: Required<
+  Omit<CompressionOptions, "keepOriginalDimensions" | "skipCompression">
+> = {
+  quality: STANDARD_QUALITY,
+  maxWidth: MAX_UPLOAD_DIMENSION,
+  maxHeight: MAX_UPLOAD_DIMENSION,
+  // Force WebP output for every image — compressorjs recompresses through
+  // canvas regardless of source size when mimeType is set.
+  mimeType: "image/webp",
+  // Setting this very low ensures the convertSize gate never blocks our
+  // re-encode (it would otherwise pass through PNGs < this threshold).
+  convertSize: 0,
+};
+
+/** Process N images concurrently. Empirically a sweet-spot on 8-core MBA. */
+export const DEFAULT_CPU_WORK_CONCURRENCY = 2;
+
+/** Mobile defaults to sequential to avoid OOM on low-end Android. */
+export const BATCH_SIZE_MOBILE = 1;
+export const BATCH_SIZE_DESKTOP = 4;
+
+const DEFAULT_MAX_CPU_CORES = 8;
+
+/**
+ * Adaptive concurrency: respect navigator.hardwareConcurrency but cap so we
+ * don't fan out to 32+ workers on big iron.
+ */
+export function getOptimalCpuConcurrency(
+  defaultConcurrency = 1,
+  maxCores = DEFAULT_MAX_CPU_CORES,
+): number {
+  if (typeof navigator === "undefined") return defaultConcurrency;
+  const cores = navigator.hardwareConcurrency || defaultConcurrency;
+  if (defaultConcurrency === 1) return 1;
+  return Math.min(Math.max(cores, defaultConcurrency), maxCores);
+}
+
+export const HEIC_MIME_TYPES = ["image/heic", "image/heif"];
+export const HEIC_EXTENSIONS = [".heic", ".heif"];
+
+export function isHeic(file: Blob | File): boolean {
+  if (file.type && HEIC_MIME_TYPES.includes(file.type.toLowerCase())) return true;
+  if (file instanceof File) {
+    const lower = file.name.toLowerCase();
+    return HEIC_EXTENSIONS.some((ext) => lower.endsWith(ext));
+  }
+  return false;
+}

package/src/heic-converter.ts

@@ -0,0 +1,29 @@
+/**
+ * HEIC → JPEG conversion via lazy `heic2any`.
+ *
+ * Isolated in its own module so the heavy heic2any blob (~1MB) stays out
+ * of the initial bundle and only loads when a HEIC file actually appears.
+ */
+
+let heic2anyCache: unknown = null;
+
+export async function convertHeicFile(file: File, quality = 0.85): Promise<File> {
+  if (!heic2anyCache) {
+    const mod = await import("heic2any");
+    heic2anyCache = (mod as { default?: unknown }).default ?? mod;
+  }
+  const heic2any = heic2anyCache as (opts: {
+    blob: Blob;
+    toType: string;
+    quality: number;
+  }) => Promise<Blob | Blob[]>;
+
+  const result = await heic2any({ blob: file, toType: "image/jpeg", quality });
+  const converted = Array.isArray(result) ? result[0] : result;
+  if (!converted || converted.size === 0) {
+    throw new Error("HEIC conversion produced an empty file");
+  }
+
+  const baseName = file.name.replace(/\.[^/.]+$/, "");
+  return new File([converted], `${baseName}.jpg`, { type: "image/jpeg" });
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @aquienpz/asset-compressor-web — browser-side image compression for the
+ * upload pipeline. Pairs with @aquienpz/asset-uploader-web; designed to
+ * mirror the future @aquienpz/asset-compressor-expo native counterpart so
+ * call sites stay identical across web and mobile.
+ */
+
+export {
+  type CompressInput,
+  compressImage,
+  compressImages,
+} from "./compression";
+export {
+  DEFAULT_COMPRESSION_OPTIONS,
+  getOptimalCpuConcurrency,
+  HEIC_EXTENSIONS,
+  HEIC_MIME_TYPES,
+  isHeic,
+  MAX_UPLOAD_DIMENSION,
+} from "./constants";
+export { convertHeicFile } from "./heic-converter";
+export type {
+  CompressedResult,
+  CompressionError,
+  CompressionOptions,
+  CompressionStatusKey,
+} from "./types";

package/src/types.ts

@@ -0,0 +1,53 @@
+/**
+ * Public types for @aquienpz/asset-compressor-web.
+ *
+ * Mirrors the legacy neo-real-estate compressor types but trimmed to the
+ * surface actually consumed by the uploader. The mobile package (Expo
+ * native module) re-uses CompressionOptions/CompressionResult so the call
+ * site is identical regardless of platform.
+ */
+
+export type CompressionStatusKey =
+  | "convertingHeic"
+  | "compressing"
+  | "compressingKeepingDimensions"
+  | "skipped"
+  | "done";
+
+/**
+ * Subset of `compressorjs` options we expose. Renderers should only need
+ * these — convertSize / strict / mimeType etc. stay defaulted.
+ */
+export type CompressionOptions = {
+  /** 0..1, defaults to 0.85 */
+  quality?: number;
+  /** Pixels; defaults to 2880 */
+  maxWidth?: number;
+  /** Pixels; defaults to 2880 */
+  maxHeight?: number;
+  /** Force a specific output mime ("image/jpeg" or "image/webp"). Default: keep original mime, fall back to JPEG. */
+  mimeType?: string;
+  /** Source files smaller than this are passed through. Default 5 MB. */
+  convertSize?: number;
+  /** If true, ignore maxWidth/Height and keep the source dimensions exactly. */
+  keepOriginalDimensions?: boolean;
+  /** Caller-controlled escape hatch — when true, compression is bypassed entirely. */
+  skipCompression?: boolean;
+};
+
+export type CompressedResult = {
+  blob: Blob;
+  filename: string;
+  originalSize: number;
+  compressedSize: number;
+  /** compressedSize / originalSize. <1 = saved bytes. */
+  compressionRatio: number;
+  originalArrayIndex: number;
+};
+
+export type CompressionError = {
+  filename: string;
+  originalBlob: Blob;
+  error: Error;
+  originalArrayIndex: number;
+};