@byline/core 1.2.0 → 1.3.0

package/dist/@types/storage-types.d.ts

@@ -38,6 +38,21 @@ export interface UploadFileOptions {
      * Providers may use this to namespace storage paths.
      */
     collection?: string;
+    /**
+     * Explicit, fully-qualified storage path / object key the provider must
+     * write to verbatim. When set, providers MUST place the file at exactly
+     * this path — no UUID prefix, year/month rewrite, or `pathPrefix` injection.
+     *
+     * Used by the image-variant pipeline (`generateImageVariants`) to write
+     * sibling files alongside an already-stored original (e.g. so the
+     * `thumbnail` variant of `media/2026/05/abc-photo.jpg` lands at
+     * `media/2026/05/abc-photo-thumbnail.webp`).
+     *
+     * Always POSIX-style (forward slashes), no leading slash. Callers are
+     * responsible for sanitisation and collision-avoidance — providers do
+     * not second-guess the path when this is set.
+     */
+    targetStoragePath?: string;
 }
 /**
  * The pluggable file-storage interface.

package/dist/image/image-processor.d.ts

@@ -0,0 +1,51 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { ImageSize } from '../@types/collection-types.js';
+import type { IStorageProvider, StoredFileLocation } from '../@types/storage-types.js';
+import type { BylineLogger } from '../logger/index.js';
+export interface ImageMeta {
+    width: number | null;
+    height: number | null;
+    format: string | null;
+}
+export interface ImageVariantResult {
+    name: string;
+    storagePath: string;
+    width: number | undefined;
+    height: number | undefined;
+    format: string;
+}
+export interface ProcessImageResult {
+    meta: ImageMeta;
+    variants: ImageVariantResult[];
+}
+/**
+ * Returns true for MIME types that should skip Sharp processing.
+ * SVGs are vector files — Sharp cannot meaningfully resize or convert them,
+ * and they do not benefit from the responsive-image pipeline.
+ */
+export declare function isBypassMimeType(mimeType: string): boolean;
+/**
+ * Extract basic image metadata (dimensions + format) from a buffer using Sharp.
+ * Returns nulls for non-image or unrecognised formats.
+ */
+export declare function extractImageMeta(buffer: Buffer, mimeType: string): Promise<ImageMeta>;
+/**
+ * Generate the named image variants (sizes) defined in `UploadConfig.sizes`
+ * and persist them through the configured `IStorageProvider`.
+ *
+ * - SVG and GIF files are skipped entirely (bypass types).
+ * - Each variant is uploaded as a sibling object to `storedFile.storagePath`,
+ *   using the naming convention: `<dir>/<basename>-<variantName>.<ext>`
+ *   (POSIX paths — both local filesystem keys and S3 object keys).
+ * - Variant bytes are produced in-memory by Sharp and written via
+ *   `storage.upload(buffer, { targetStoragePath })` — no direct filesystem
+ *   access, so the function is provider-agnostic.
+ * - Returns an array of `ImageVariantResult` describing what was created.
+ */
+export declare function generateImageVariants(sourceBuffer: Buffer, mimeType: string, storedFile: StoredFileLocation, storage: IStorageProvider, sizes: ImageSize[], logger?: BylineLogger): Promise<ImageVariantResult[]>;

package/dist/image/image-processor.js

@@ -0,0 +1,163 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import path from 'node:path';
+// Sharp ships its own types; no @types/sharp needed.
+import sharp from 'sharp';
+// ---------------------------------------------------------------------------
+// SVG detection
+// ---------------------------------------------------------------------------
+/**
+ * Returns true for MIME types that should skip Sharp processing.
+ * SVGs are vector files — Sharp cannot meaningfully resize or convert them,
+ * and they do not benefit from the responsive-image pipeline.
+ */
+export function isBypassMimeType(mimeType) {
+    return mimeType === 'image/svg+xml' || mimeType === 'image/gif';
+}
+// ---------------------------------------------------------------------------
+// Metadata extraction
+// ---------------------------------------------------------------------------
+/**
+ * Extract basic image metadata (dimensions + format) from a buffer using Sharp.
+ * Returns nulls for non-image or unrecognised formats.
+ */
+export async function extractImageMeta(buffer, mimeType) {
+    if (isBypassMimeType(mimeType)) {
+        // For SVGs, attempt a lightweight XML parse for width/height attributes.
+        const svgMeta = tryParseSvgDimensions(buffer);
+        return { width: svgMeta.width, height: svgMeta.height, format: 'svg' };
+    }
+    try {
+        const metadata = await sharp(buffer).metadata();
+        return {
+            width: metadata.width ?? null,
+            height: metadata.height ?? null,
+            format: metadata.format ?? null,
+        };
+    }
+    catch {
+        return { width: null, height: null, format: null };
+    }
+}
+/**
+ * A lightweight SVG width/height parser — avoids pulling in a full XML library.
+ * Only reads the root `<svg>` element's `width` and `height` attributes.
+ */
+function tryParseSvgDimensions(buffer) {
+    try {
+        const text = buffer.toString('utf8', 0, Math.min(buffer.length, 2048));
+        const widthMatch = text.match(/<svg[^>]*\swidth=["']([0-9.]+)(?:px)?["']/);
+        const heightMatch = text.match(/<svg[^>]*\sheight=["']([0-9.]+)(?:px)?["']/);
+        return {
+            width: widthMatch ? Math.round(Number.parseFloat(widthMatch[1])) : null,
+            height: heightMatch ? Math.round(Number.parseFloat(heightMatch[1])) : null,
+        };
+    }
+    catch {
+        return { width: null, height: null };
+    }
+}
+// ---------------------------------------------------------------------------
+// Variant generation
+// ---------------------------------------------------------------------------
+/**
+ * Map a Sharp output format keyword to the corresponding image MIME type.
+ * Unknown formats fall back to `application/octet-stream` — the storage
+ * provider will accept it; only the served `Content-Type` is affected.
+ */
+function mimeTypeForFormat(format) {
+    switch (format) {
+        case 'jpeg':
+            return 'image/jpeg';
+        case 'png':
+            return 'image/png';
+        case 'webp':
+            return 'image/webp';
+        case 'avif':
+            return 'image/avif';
+        default:
+            return 'application/octet-stream';
+    }
+}
+/**
+ * Generate the named image variants (sizes) defined in `UploadConfig.sizes`
+ * and persist them through the configured `IStorageProvider`.
+ *
+ * - SVG and GIF files are skipped entirely (bypass types).
+ * - Each variant is uploaded as a sibling object to `storedFile.storagePath`,
+ *   using the naming convention: `<dir>/<basename>-<variantName>.<ext>`
+ *   (POSIX paths — both local filesystem keys and S3 object keys).
+ * - Variant bytes are produced in-memory by Sharp and written via
+ *   `storage.upload(buffer, { targetStoragePath })` — no direct filesystem
+ *   access, so the function is provider-agnostic.
+ * - Returns an array of `ImageVariantResult` describing what was created.
+ */
+export async function generateImageVariants(sourceBuffer, mimeType, storedFile, storage, sizes, logger) {
+    if (isBypassMimeType(mimeType) || sizes.length === 0) {
+        return [];
+    }
+    // Storage paths are POSIX-style across providers; use `path.posix` so
+    // Windows local-fs hosts don't introduce backslashes into S3 object keys.
+    const sourcePath = storedFile.storagePath;
+    const originalExt = path.posix.extname(sourcePath);
+    const originalBase = path.posix.basename(sourcePath, originalExt);
+    const variantDir = path.posix.dirname(sourcePath);
+    const variants = [];
+    for (const size of sizes) {
+        const outputFormat = size.format ?? 'webp';
+        const variantFilename = `${originalBase}-${size.name}.${outputFormat}`;
+        const variantStoragePath = variantDir === '.' ? variantFilename : `${variantDir}/${variantFilename}`;
+        try {
+            let pipeline = sharp(sourceBuffer);
+            const resizeOptions = {
+                width: size.width,
+                height: size.height,
+                fit: size.fit ?? 'cover',
+                withoutEnlargement: true,
+            };
+            pipeline = pipeline.resize(resizeOptions);
+            // Apply format + quality.
+            switch (outputFormat) {
+                case 'jpeg':
+                    pipeline = pipeline.jpeg({ quality: size.quality ?? 85 });
+                    break;
+                case 'png':
+                    pipeline = pipeline.png({ quality: size.quality ?? 85 });
+                    break;
+                case 'webp':
+                    pipeline = pipeline.webp({ quality: size.quality ?? 85 });
+                    break;
+                case 'avif':
+                    pipeline = pipeline.avif({ quality: size.quality ?? 55 });
+                    break;
+                default:
+                    pipeline = pipeline.webp({ quality: size.quality ?? 85 });
+            }
+            const variantBuffer = await pipeline.toBuffer();
+            const sharpMeta = await sharp(variantBuffer).metadata();
+            await storage.upload(variantBuffer, {
+                filename: variantFilename,
+                mimeType: mimeTypeForFormat(outputFormat),
+                size: variantBuffer.byteLength,
+                targetStoragePath: variantStoragePath,
+            });
+            variants.push({
+                name: size.name,
+                storagePath: variantStoragePath,
+                width: sharpMeta.width,
+                height: sharpMeta.height,
+                format: outputFormat,
+            });
+        }
+        catch (err) {
+            logger?.error({ err, variant: size.name }, 'failed to generate image variant');
+            // Non-fatal: skip this variant but continue with others.
+        }
+    }
+    return variants;
+}

package/dist/image/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Storage-agnostic image-processing helpers (sharp-backed). Lives in the
+ * neutral `@byline/core/image` subpath so any storage provider —
+ * `@byline/storage-local`, `@byline/storage-s3`, future providers — can
+ * consume the same metadata extraction and variant generation utilities
+ * without taking a dependency on a sibling provider package.
+ */
+export { extractImageMeta, generateImageVariants, isBypassMimeType, } from './image-processor.js';
+export type { ImageMeta, ImageVariantResult, ProcessImageResult, } from './image-processor.js';

package/dist/image/index.js

@@ -0,0 +1,15 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Storage-agnostic image-processing helpers (sharp-backed). Lives in the
+ * neutral `@byline/core/image` subpath so any storage provider —
+ * `@byline/storage-local`, `@byline/storage-s3`, future providers — can
+ * consume the same metadata extraction and variant generation utilities
+ * without taking a dependency on a sibling provider package.
+ */
+export { extractImageMeta, generateImageVariants, isBypassMimeType, } from './image-processor.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -61,6 +61,11 @@
       "import": "./dist/validation/index.js",
       "require": "./dist/validation/index.js"
     },
+    "./image": {
+      "types": "./dist/image/index.d.ts",
+      "import": "./dist/image/index.js",
+      "require": "./dist/image/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -71,9 +76,10 @@
     "jose": "^6.2.3",
     "npm-run-all": "^4.1.5",
     "pino": "^10.3.1",
+    "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.2.0"
+    "@byline/auth": "1.3.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",