@nomideusz/svelte-media 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0 — 2026-08-03
+
+### Added
+- **`derive` / `onDeriveError` on `MediaConfig`, and `derived` on `StoredMedia`.**
+  A hook over the decoded bytes during processing, so anything computed from the
+  image — placeholder, blurhash, dominant colour, EXIF — happens while the bytes
+  are in memory rather than fetching them back later. `TDerived` is inferred from
+  the callback, so the package takes no dependency on what you derive.
+
+  The hook runs after every size is stored, and failures deliberately do not
+  propagate: by then the upload has succeeded, and rejecting would make the
+  caller retry a completed upload and orphan the objects already written.
+  `derived` is left undefined and `onDeriveError` is called.
+
+
 ## 0.2.0 — 2026-08-03
 
 ### Changed

package/README.md

@@ -58,6 +58,32 @@ touches a database.
 **Output is always WebP**, whatever was uploaded; `generateMediaKey` names every
 file `<cuid2>.webp` and ignores the original extension.
 
+## Deriving extras at upload time
+
+`processAndStore` already has the decoded bytes in memory. A `derive` hook lets
+you compute something from them in the same pass — a placeholder, a blurhash, a
+dominant colour, EXIF — instead of fetching the image back later:
+
+```ts
+import { generatePlaceholder } from '@nomideusz/svelte-geometrize/node';
+
+const stored = await processAndStore(storage, file, 'tours', tourId, {
+  derive: ({ buffer }) => generatePlaceholder(buffer),
+  onDeriveError: (err) => log.warn('placeholder failed', err),
+});
+
+stored.derived;   // GeometrizePlaceholder | undefined — inferred from the hook
+```
+
+The hook runs **after** every size is stored, and **failures do not propagate**:
+by that point the upload has succeeded, and rejecting would make the caller
+retry a completed upload — orphaning the objects already written. A failing
+hook leaves `derived` undefined and calls `onDeriveError`. Wire that to your
+logger, or the failure is silent.
+
+The package takes no dependency on whatever you derive; `TDerived` is inferred
+from the callback's return type.
+
 ## Sizes
 
 `processAndStore` always writes four variants:

package/dist/core/media.d.ts

@@ -1,4 +1,4 @@
-import type { ImageSize, MediaConfig, ValidationResult } from './types.js';
+import type { ImageSize, ValidationConfig, ValidationResult } from './types.js';
 export declare const DEFAULT_MAX_SIZE: number;
 export declare const DEFAULT_ALLOWED_TYPES: string[];
 export declare const IMAGE_SIZES: {
@@ -20,6 +20,6 @@ export declare const IMAGE_SIZES: {
 };
 export declare const SIZE_PREFIXES: Record<ImageSize, string>;
 export declare const SIZE_QUALITY: Record<ImageSize, number>;
-export declare function validateImageFile(file: File, config?: MediaConfig): ValidationResult;
+export declare function validateImageFile(file: File, config?: ValidationConfig): ValidationResult;
 export declare function generateMediaKey(_originalName?: string): string;
 export declare function getStorageKey(prefix: string, entityId: string, filename: string, size: ImageSize): string;

package/dist/core/process.d.ts

@@ -1,4 +1,4 @@
 import type { StorageAdapter, StoredMedia, ImageSize, MediaConfig } from './types.js';
-export declare function processAndStore(adapter: StorageAdapter, file: File, prefix: string, entityId: string, config?: MediaConfig): Promise<StoredMedia>;
+export declare function processAndStore<TDerived = never>(adapter: StorageAdapter, file: File, prefix: string, entityId: string, config?: MediaConfig<TDerived>): Promise<StoredMedia<TDerived>>;
 export declare function deleteMedia(adapter: StorageAdapter, prefix: string, entityId: string, filename: string): Promise<void>;
 export declare function getMediaUrl(adapter: StorageAdapter, prefix: string, entityId: string, filename: string, size?: ImageSize): string;

package/dist/core/process.js

@@ -29,7 +29,20 @@ export async function processAndStore(adapter, file, prefix, entityId, config) {
     }
     // ponytail: existing objects stay JPEG under their old keys — URLs derive
     // from the stored filename, so old rows keep working without migration.
-    return { filename, originalName: file.name, prefix, entityId, sizes };
+    // Runs last, so a throwing hook cannot orphan a half-written upload — and it
+    // is caught, because by this point the image is stored and rejecting would
+    // make the caller retry a completed upload.
+    let derived;
+    if (config?.derive) {
+        const source = { buffer, filename, mimeType: file.type };
+        try {
+            derived = await config.derive(source);
+        }
+        catch (error) {
+            config.onDeriveError?.(error, source);
+        }
+    }
+    return { filename, originalName: file.name, prefix, entityId, sizes, derived };
 }
 export async function deleteMedia(adapter, prefix, entityId, filename) {
     const keys = ['original', 'thumbnail', 'medium', 'large'].map((size) => getStorageKey(prefix, entityId, filename, size));

package/dist/core/types.d.ts

@@ -17,7 +17,7 @@ export interface S3Config {
     /** Use path-style access (default: true for MinIO/R2, set false for Railway/AWS) */
     forcePathStyle?: boolean;
 }
-export interface StoredMedia {
+export interface StoredMedia<TDerived = never> {
     filename: string;
     originalName: string;
     /** Storage prefix, e.g. 'tours' or 'avatars' */
@@ -26,6 +26,11 @@ export interface StoredMedia {
     entityId: string;
     /** Storage keys for each size */
     sizes: Record<ImageSize, string>;
+    /**
+     * Result of `config.derive`, when supplied. Undefined if no hook was given,
+     * or if it threw — see `MediaConfig.onDeriveError`.
+     */
+    derived?: TDerived;
 }
 export interface MediaValidationError {
     isValid: false;
@@ -41,7 +46,35 @@ export interface ValidationResult {
     valid: boolean;
     error?: string;
 }
-export interface MediaConfig {
+/** What a `derive` hook receives — the image as uploaded, before any resizing. */
+export interface DeriveSource {
+    /** Original bytes, pre-resize, EXIF intact. */
+    buffer: Buffer;
+    /** The generated storage filename, e.g. `k7x2m9.webp`. */
+    filename: string;
+    /** The uploaded file's MIME type. */
+    mimeType: string;
+}
+/** The validation half of MediaConfig — all `validateImageFile` needs. */
+export interface ValidationConfig {
     maxFileSize?: number;
     allowedTypes?: string[];
 }
+export interface MediaConfig<TDerived = never> extends ValidationConfig {
+    /**
+     * Optional side-computation over the image, run once during processing while
+     * the bytes are already in hand — a placeholder, a blurhash, a dominant
+     * colour, EXIF. Whatever it returns is attached to the result as `derived`.
+     *
+     * Runs after every size has been stored, so a failure cannot orphan a
+     * half-written upload. Failures do not propagate: the upload has already
+     * succeeded and a derived extra must never invalidate it. `derived` is left
+     * undefined and `onDeriveError` is called.
+     */
+    derive?(source: DeriveSource): Promise<TDerived>;
+    /**
+     * Called when `derive` throws. The upload still succeeds. Without this the
+     * failure is silent, so wire it to your logger.
+     */
+    onDeriveError?(error: unknown, source: DeriveSource): void;
+}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { StorageAdapter, S3Config, StoredMedia, ImageSize, MediaConfig, ValidationResult, } from './core/types.js';
+export type { StorageAdapter, S3Config, StoredMedia, ImageSize, MediaConfig, ValidationResult, ValidationConfig, DeriveSource, } from './core/types.js';
 export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
 export { default as ImageUpload } from './components/ImageUpload.svelte';
 export { default as ImageGallery } from './components/ImageGallery.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomideusz/svelte-media",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Image upload, processing, and S3-compatible storage for Svelte 5 apps.",
   "type": "module",
   "sideEffects": false,