@mostajs/image 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog — @mostajs/image
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+
+## 0.0.1 — 2026-06-14
+- Scaffold initial (cas C). Registre de drivers façon dialectes.
+- Processeur raster **sharp** : `info`, `resize`, `convert` (png/jpeg/webp/avif), `cropCenter`, `stripExif`.
+- Extracteur d'images PDF **pdfjs** : `renderPages` (pdfjs-dist + @napi-rs/canvas) → PNG par page.
+- Façade : `registerBuiltins`, `capabilities`, helpers raster + `resizeDataUrl`/`dataUrlSizeKB`, `pdfPagesToImages`.
+- Drivers optionnels (lazy + sonde `available()`), dégradation gracieuse sans dépendance native.
+- Tests `test-scripts/` (node:test) : **5/5**.

package/README.md

@@ -0,0 +1,32 @@
+# @mostajs/image
+
+**Auteur** : Dr Hamid MADANI <drmdh@msn.com>
+**Licence** : AGPL-3.0-or-later
+
+Traitement d'image générique, **façon dialectes** (`@mostajs/orm`) : un registre de **processeurs raster** (resize / convert / crop / strip-EXIF — driver **Sharp**) et d'**extracteurs d'images de PDF** (rendu des pages — **pdfjs-dist** + **@napi-rs/canvas**). Tous les drivers sont **optionnels** (lazy + sonde `available()`) et **fs-free** (octets in → octets out).
+
+> La **lecture de texte** dans une image (OCR) est le module séparé **`@mostajs/ocr`**. Un dialecte de lecture compose les deux : `pdfPagesToImages` (ici) → `ocrImages` (là-bas).
+
+## API
+
+```ts
+import { registerBuiltins, capabilities, imageInfo, resizeImage, convertImage,
+         cropCenter, stripExif, resizeDataUrl, dataUrlSizeKB, pdfPagesToImages } from "@mostajs/image";
+
+registerBuiltins();                                  // enregistre sharp + pdfjs (idempotent)
+const caps = await capabilities();                   // { process, pdfImages }
+
+const small = await resizeImage(bytes, { width: 800, format: "webp", quality: 80 });
+const jpeg  = await convertImage(bytes, "jpeg", 85);
+const clean = await stripExif(bytes);                // vie privée
+const pages = await pdfPagesToImages(pdfBytes, { scale: 2, maxPages: 5 }); // PDF scanné → PNG[]
+```
+
+Drivers : `registerProcessor` / `registerPdfExtractor` pour brancher les vôtres (même contrat).
+
+## Dépendances (optionnelles)
+
+| Capacité | Paquet | Sans lui |
+|---|---|---|
+| resize/convert/crop/EXIF | `sharp` | `capabilities().process = false`, helpers lèvent une erreur claire |
+| rendu de pages PDF | `pdfjs-dist` + `@napi-rs/canvas` | `capabilities().pdfImages = false` |

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import type { ImageBytes, ImageCapabilities, ImageInfo, PdfRenderOpts, RasterFormat, ResizeOpts } from "./types.js";
+export * from "./types.js";
+export { registerProcessor, getProcessor, listProcessors, activeProcessor, registerPdfExtractor, getPdfExtractor, listPdfExtractors, activePdfExtractor, _resetRegistries, } from "./registry.js";
+export { makeSharpProcessor } from "./sharp-processor.js";
+export { makePdfjsExtractor } from "./pdf-images.js";
+/** Enregistre les drivers built-in (idempotent). À appeler une fois au démarrage. */
+export declare function registerBuiltins(): void;
+/** Capacités réellement disponibles (dépendances natives présentes ?). */
+export declare function capabilities(): Promise<ImageCapabilities>;
+export declare function imageInfo(bytes: ImageBytes): Promise<ImageInfo>;
+export declare function resizeImage(bytes: ImageBytes, opts: ResizeOpts): Promise<ImageBytes>;
+export declare function convertImage(bytes: ImageBytes, format: RasterFormat, quality?: number): Promise<ImageBytes>;
+export declare function cropCenter(bytes: ImageBytes, w: number, h: number): Promise<ImageBytes>;
+export declare function stripExif(bytes: ImageBytes): Promise<ImageBytes>;
+/** Redimensionne une image data-URL/base64 et renvoie une data-URL (format de sortie au choix). */
+export declare function resizeDataUrl(dataUrl: string, opts: ResizeOpts): Promise<string>;
+/** Taille en Ko d'une image base64/data-URL (estimation décodée). */
+export declare function dataUrlSizeKB(dataUrl: string): number;
+export declare function pdfPagesToImages(pdfBytes: Uint8Array, opts?: PdfRenderOpts): Promise<ImageBytes[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,73 @@
+/**
+ * @mostajs/image — façade publique. Enregistre les drivers built-in (sharp + pdfjs), expose le
+ * registre, des helpers de haut niveau (resize/convert/info, rendu de pages PDF) et la sonde de
+ * capacités. Tout est lazy : le module se charge sans aucune dépendance native installée.
+ *
+ * Composition typique (dialecte de lecture) :
+ *   const pages = await pdfPagesToImages(pdfBytes);   // @mostajs/image  (rendu)
+ *   const text  = await ocrImages(pages);             // @mostajs/ocr    (reconnaissance)
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import { registerProcessor, registerPdfExtractor, activeProcessor, activePdfExtractor, } from "./registry.js";
+import { makeSharpProcessor } from "./sharp-processor.js";
+import { makePdfjsExtractor } from "./pdf-images.js";
+export * from "./types.js";
+export { registerProcessor, getProcessor, listProcessors, activeProcessor, registerPdfExtractor, getPdfExtractor, listPdfExtractors, activePdfExtractor, _resetRegistries, } from "./registry.js";
+export { makeSharpProcessor } from "./sharp-processor.js";
+export { makePdfjsExtractor } from "./pdf-images.js";
+let _registered = false;
+/** Enregistre les drivers built-in (idempotent). À appeler une fois au démarrage. */
+export function registerBuiltins() {
+    if (_registered)
+        return;
+    registerProcessor(makeSharpProcessor());
+    registerPdfExtractor(makePdfjsExtractor());
+    _registered = true;
+}
+/** Capacités réellement disponibles (dépendances natives présentes ?). */
+export async function capabilities() {
+    return { process: !!(await activeProcessor()), pdfImages: !!(await activePdfExtractor()) };
+}
+function needProcessor() {
+    return activeProcessor().then((p) => {
+        if (!p)
+            throw new Error("aucun processeur d'image disponible (npm install sharp)");
+        return p;
+    });
+}
+// — Helpers raster (octets) —
+export async function imageInfo(bytes) { return (await needProcessor()).info(bytes); }
+export async function resizeImage(bytes, opts) { return (await needProcessor()).resize(bytes, opts); }
+export async function convertImage(bytes, format, quality) { return (await needProcessor()).convert(bytes, format, quality); }
+export async function cropCenter(bytes, w, h) { return (await needProcessor()).cropCenter(bytes, w, h); }
+export async function stripExif(bytes) { return (await needProcessor()).stripExif(bytes); }
+// — Helpers base64 / data-URL (reprend l'util historique parkmanager, désormais server-safe) —
+const B64 = (b) => Buffer.from(b).toString("base64");
+const fromDataUrl = (s) => {
+    const m = /^data:([^;]+);base64,(.*)$/s.exec(s.trim());
+    if (!m)
+        return { mime: "application/octet-stream", bytes: new Uint8Array(Buffer.from(s, "base64")) };
+    return { mime: m[1], bytes: new Uint8Array(Buffer.from(m[2], "base64")) };
+};
+/** Redimensionne une image data-URL/base64 et renvoie une data-URL (format de sortie au choix). */
+export async function resizeDataUrl(dataUrl, opts) {
+    const { bytes } = fromDataUrl(dataUrl);
+    const out = await resizeImage(bytes, opts);
+    const fmt = opts.format ?? "png";
+    return `data:image/${fmt};base64,${B64(out)}`;
+}
+/** Taille en Ko d'une image base64/data-URL (estimation décodée). */
+export function dataUrlSizeKB(dataUrl) {
+    const { bytes } = fromDataUrl(dataUrl);
+    return Math.round((bytes.length / 1024) * 10) / 10;
+}
+// — Helper PDF → images —
+export async function pdfPagesToImages(pdfBytes, opts) {
+    const x = await activePdfExtractor();
+    if (!x)
+        throw new Error("rendu PDF indisponible (npm install pdfjs-dist @napi-rs/canvas)");
+    return x.renderPages(pdfBytes, opts);
+}
+//# sourceMappingURL=index.js.map

package/dist/pdf-images.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @mostajs/image — extracteur d'images PDF « pdfjs » : rend chaque page en PNG via
+ * pdfjs-dist (legacy ESM) + @napi-rs/canvas. Driver OPTIONNEL, lazy. fs-free.
+ *
+ * Sert notamment à transformer un PDF SCANNÉ (sans couche texte) en images, qu'un moteur
+ * OCR (@mostajs/ocr) peut ensuite lire.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import type { PdfImageExtractor } from "./types.js";
+export declare function makePdfjsExtractor(): PdfImageExtractor;
+//# sourceMappingURL=pdf-images.d.ts.map

package/dist/pdf-images.js

@@ -0,0 +1,58 @@
+let _pdfjs;
+let _canvas;
+async function loadPdfjs() {
+    if (_pdfjs !== undefined)
+        return _pdfjs;
+    try {
+        _pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+    }
+    catch {
+        _pdfjs = null;
+    }
+    return _pdfjs;
+}
+async function loadCanvas() {
+    if (_canvas !== undefined)
+        return _canvas;
+    try {
+        _canvas = await import("@napi-rs/canvas");
+    }
+    catch {
+        _canvas = null;
+    }
+    return _canvas;
+}
+export function makePdfjsExtractor() {
+    return {
+        name: "pdfjs",
+        async available() { return (await loadPdfjs()) !== null && (await loadCanvas()) !== null; },
+        async renderPages(pdfBytes, opts) {
+            const pdfjs = await loadPdfjs();
+            const canvasMod = await loadCanvas();
+            if (!pdfjs || !canvasMod)
+                throw new Error("rendu PDF indisponible (npm install pdfjs-dist @napi-rs/canvas)");
+            const scale = opts?.scale ?? 2;
+            // copie défensive : pdfjs peut transférer/détacher le buffer d'entrée.
+            const data = new Uint8Array(pdfBytes);
+            const doc = await pdfjs.getDocument({ data, isEvalSupported: false, useSystemFonts: true }).promise;
+            const total = opts?.maxPages ? Math.min(opts.maxPages, doc.numPages) : doc.numPages;
+            const out = [];
+            try {
+                for (let i = 1; i <= total; i++) {
+                    const page = await doc.getPage(i);
+                    const viewport = page.getViewport({ scale });
+                    const canvas = canvasMod.createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+                    const ctx = canvas.getContext("2d");
+                    await page.render({ canvasContext: ctx, viewport }).promise;
+                    out.push(new Uint8Array(canvas.toBuffer("image/png")));
+                    page.cleanup();
+                }
+            }
+            finally {
+                await doc.destroy?.();
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=pdf-images.js.map

package/dist/registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @mostajs/image — registres de drivers (façon dialects @mostajs/orm) : processeurs raster,
+ * moteurs OCR, extracteurs d'images PDF. Enregistrement idempotent par `name` ; sélection du
+ * premier driver DISPONIBLE (sonde `available()`).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import type { ImageProcessor, PdfImageExtractor } from "./types.js";
+export declare function registerProcessor(p: ImageProcessor): void;
+export declare function getProcessor(name: string): ImageProcessor | undefined;
+export declare function listProcessors(): ImageProcessor[];
+export declare function registerPdfExtractor(x: PdfImageExtractor): void;
+export declare function getPdfExtractor(name: string): PdfImageExtractor | undefined;
+export declare function listPdfExtractors(): PdfImageExtractor[];
+export declare function activeProcessor(): Promise<ImageProcessor | undefined>;
+export declare function activePdfExtractor(): Promise<PdfImageExtractor | undefined>;
+/** Vide tous les registres (tests). */
+export declare function _resetRegistries(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,22 @@
+const processors = new Map();
+const pdfExtractors = new Map();
+// — Processeurs raster —
+export function registerProcessor(p) { processors.set(p.name, p); }
+export function getProcessor(name) { return processors.get(name); }
+export function listProcessors() { return [...processors.values()]; }
+// — Extracteurs d'images PDF —
+export function registerPdfExtractor(x) { pdfExtractors.set(x.name, x); }
+export function getPdfExtractor(name) { return pdfExtractors.get(name); }
+export function listPdfExtractors() { return [...pdfExtractors.values()]; }
+/** Premier driver effectivement disponible (ou `undefined`). */
+async function firstAvailable(list) {
+    for (const d of list)
+        if (await d.available())
+            return d;
+    return undefined;
+}
+export function activeProcessor() { return firstAvailable(listProcessors()); }
+export function activePdfExtractor() { return firstAvailable(listPdfExtractors()); }
+/** Vide tous les registres (tests). */
+export function _resetRegistries() { processors.clear(); pdfExtractors.clear(); }
+//# sourceMappingURL=registry.js.map

package/dist/sharp-processor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @mostajs/image — processeur raster « sharp » (libvips). Driver OPTIONNEL, chargé en lazy :
+ * si `sharp` n'est pas installé, `available()` renvoie false et les autres registres prennent
+ * le relais. fs-free : Uint8Array in → Uint8Array out.
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+import type { ImageProcessor } from "./types.js";
+export declare function makeSharpProcessor(): ImageProcessor;
+//# sourceMappingURL=sharp-processor.d.ts.map

package/dist/sharp-processor.js

@@ -0,0 +1,66 @@
+let _sharp;
+async function loadSharp() {
+    if (_sharp !== undefined)
+        return _sharp;
+    try {
+        _sharp = (await import("sharp")).default;
+    }
+    catch {
+        _sharp = null;
+    }
+    return _sharp;
+}
+function applyFormat(pipe, format, quality) {
+    if (!format)
+        return pipe;
+    if (format === "jpeg")
+        return pipe.jpeg({ quality: quality ?? 80 });
+    if (format === "webp")
+        return pipe.webp({ quality: quality ?? 80 });
+    if (format === "avif")
+        return pipe.avif({ quality: quality ?? 50 });
+    return pipe.png();
+}
+export function makeSharpProcessor() {
+    return {
+        name: "sharp",
+        async available() { return (await loadSharp()) !== null; },
+        async info(bytes) {
+            const sharp = await loadSharp();
+            if (!sharp)
+                throw new Error("driver « sharp » indisponible (npm install sharp)");
+            const m = await sharp(bytes).metadata();
+            return { width: m.width ?? 0, height: m.height ?? 0, format: m.format ?? "", hasAlpha: !!m.hasAlpha };
+        },
+        async resize(bytes, opts) {
+            const sharp = await loadSharp();
+            if (!sharp)
+                throw new Error("driver « sharp » indisponible (npm install sharp)");
+            let pipe = sharp(bytes).rotate(); // respecte l'orientation EXIF avant strip
+            if (opts.width || opts.height)
+                pipe = pipe.resize({ width: opts.width, height: opts.height, fit: opts.fit ?? "inside", withoutEnlargement: true });
+            pipe = applyFormat(pipe, opts.format, opts.quality);
+            return new Uint8Array(await pipe.toBuffer());
+        },
+        async convert(bytes, format, quality) {
+            const sharp = await loadSharp();
+            if (!sharp)
+                throw new Error("driver « sharp » indisponible (npm install sharp)");
+            return new Uint8Array(await applyFormat(sharp(bytes), format, quality).toBuffer());
+        },
+        async cropCenter(bytes, width, height) {
+            const sharp = await loadSharp();
+            if (!sharp)
+                throw new Error("driver « sharp » indisponible (npm install sharp)");
+            return new Uint8Array(await sharp(bytes).resize({ width, height, fit: "cover", position: "centre" }).toBuffer());
+        },
+        async stripExif(bytes) {
+            const sharp = await loadSharp();
+            if (!sharp)
+                throw new Error("driver « sharp » indisponible (npm install sharp)");
+            // sharp ne propage PAS les métadonnées par défaut → re-encoder = EXIF supprimé.
+            return new Uint8Array(await sharp(bytes).rotate().toBuffer());
+        },
+    };
+}
+//# sourceMappingURL=sharp-processor.js.map

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @mostajs/image — types du registre de traitement d'image (façon dialectes @mostajs/orm).
+ *
+ * Deux familles de drivers, toutes OPTIONNELLES (lazy + sonde `available()`), toutes fs-free
+ * (octets in → octets out, aucune écriture disque) :
+ *   • ImageProcessor    — manipulation raster (resize/convert/crop/strip-EXIF) — driver « sharp ».
+ *   • PdfImageExtractor — rendu des pages d'un PDF en images — driver « pdfjs ».
+ *
+ * La LECTURE de texte dans une image (OCR) est un module séparé : `@mostajs/ocr` (qu'un
+ * dialecte compose avec ce module : rendu des pages PDF ici → reconnaissance là-bas).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+/** Données binaires d'une image (PNG/JPEG/WebP… selon `format`). */
+export type ImageBytes = Uint8Array;
+/** Formats raster pris en charge en sortie. */
+export type RasterFormat = "png" | "jpeg" | "webp" | "avif";
+/** Métadonnées d'une image. */
+export interface ImageInfo {
+    width: number;
+    height: number;
+    format: string;
+    hasAlpha: boolean;
+}
+/** Options de redimensionnement (toutes optionnelles). */
+export interface ResizeOpts {
+    width?: number;
+    height?: number;
+    /** « contain » garde le ratio (défaut), « cover » remplit + recadre, « fill » déforme. */
+    fit?: "contain" | "cover" | "fill" | "inside" | "outside";
+    /** Qualité 1..100 pour les formats avec perte (jpeg/webp/avif). */
+    quality?: number;
+    /** Convertir en ce format de sortie (sinon conserve l'entrée). */
+    format?: RasterFormat;
+}
+/** Driver de manipulation raster. */
+export interface ImageProcessor {
+    readonly name: string;
+    /** Le driver sous-jacent est-il chargeable (dépendance présente) ? */
+    available(): Promise<boolean>;
+    info(bytes: ImageBytes): Promise<ImageInfo>;
+    resize(bytes: ImageBytes, opts: ResizeOpts): Promise<ImageBytes>;
+    convert(bytes: ImageBytes, format: RasterFormat, quality?: number): Promise<ImageBytes>;
+    /** Recadrage centré aux dimensions données. */
+    cropCenter(bytes: ImageBytes, width: number, height: number): Promise<ImageBytes>;
+    /** Supprime les métadonnées EXIF (vie privée). */
+    stripExif(bytes: ImageBytes): Promise<ImageBytes>;
+}
+/** Options de rendu de pages PDF. */
+export interface PdfRenderOpts {
+    /** Échelle de rendu (défaut 2 = ~144 dpi, bon compromis OCR). */
+    scale?: number;
+    /** Limiter au nombre de pages (défaut : toutes). */
+    maxPages?: number;
+}
+/** Extracteur d'images d'un PDF (rendu des pages + images embarquées). */
+export interface PdfImageExtractor {
+    readonly name: string;
+    available(): Promise<boolean>;
+    /** Rend chaque page en PNG (pour OCR de PDF scanné, aperçu…). */
+    renderPages(pdfBytes: Uint8Array, opts?: PdfRenderOpts): Promise<ImageBytes[]>;
+}
+/** Synthèse des capacités effectivement disponibles sur l'environnement courant. */
+export interface ImageCapabilities {
+    process: boolean;
+    pdfImages: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,16 @@
+/**
+ * @mostajs/image — types du registre de traitement d'image (façon dialectes @mostajs/orm).
+ *
+ * Deux familles de drivers, toutes OPTIONNELLES (lazy + sonde `available()`), toutes fs-free
+ * (octets in → octets out, aucune écriture disque) :
+ *   • ImageProcessor    — manipulation raster (resize/convert/crop/strip-EXIF) — driver « sharp ».
+ *   • PdfImageExtractor — rendu des pages d'un PDF en images — driver « pdfjs ».
+ *
+ * La LECTURE de texte dans une image (OCR) est un module séparé : `@mostajs/ocr` (qu'un
+ * dialecte compose avec ce module : rendu des pages PDF ici → reconnaissance là-bas).
+ *
+ * @author Dr Hamid MADANI <drmdh@msn.com>
+ * @license AGPL-3.0-or-later
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mostajs/image",
+  "version": "0.0.1",
+  "description": "Traitement d'image générique façon DIALECTES (@mostajs/orm) : un registre de PROCESSEURS (resize/convert/crop/strip-EXIF — driver Sharp) et d'extracteurs d'images de PDF (rendu des pages — pdfjs-dist + @napi-rs/canvas). Drivers optionnels, lazy + installHint. fs-free (octets in / octets out). L'OCR est le module séparé @mostajs/ocr. Réutilisable.",
+  "author": "Dr Hamid MADANI <drmdh@msn.com>",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "sharp": ">=0.33.0",
+    "pdfjs-dist": ">=4.0.0",
+    "@napi-rs/canvas": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    },
+    "pdfjs-dist": {
+      "optional": true
+    },
+    "@napi-rs/canvas": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  },
+  "keywords": [
+    "image",
+    "sharp",
+    "pdf",
+    "resize",
+    "convert",
+    "webp",
+    "exif",
+    "dialect",
+    "mostajs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test-scripts/"
+  }
+}