@nomideusz/svelte-media 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # 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
+- **Breaking: the package is split into two entry points.** Storage adapters,
+  `processAndStore`, `deleteMedia` and `getMediaUrl` move to
+  `@nomideusz/svelte-media/server`; components, `validateImageFile`, the key
+  helpers, `IMAGE_SIZES` and the types stay on the root import.
+
+  Everything was previously behind one entry, and `core/process.ts` imported
+  `sharp` while `core/local-adapter.ts` imported `node:fs` and `node:path` at
+  module level. Any browser bundle that touched the package pulled those in and
+  failed to build — which means `ImageUpload` and `ImageGallery`, the two
+  exports that exist to be used from a component, could not be. The bug went
+  unnoticed because both apps in the source monorepo import only from server
+  files.
+
+  Migration: append `/server` to imports of the adapters or the pipeline. Key
+  helpers are re-exported from `/server` too, so a server file still needs one
+  import.
+
+### Added
+- A real demo at https://svelte-media-gamma.vercel.app/ — the components running
+  live, `validateImageFile` against files you choose, and the storage-key layout
+  for a prefix and entity you type. The server pipeline is shown as code, since
+  it cannot run in a browser.
+
+
 Backfilled 2026-08-02 from git history. Entries before that date are
 reconstructed from commits, so they record what changed rather than a release
 that was tagged at the time. 0.1.0 was published manually — trusted publishing

package/README.md

@@ -10,9 +10,18 @@ pluggable storage adapter — S3-compatible or local disk.
 pnpm add @nomideusz/svelte-media
 ```
 
-> Requires Svelte 5 (`^5.0.0`). The processing path is server-only: it uses
-> `sharp` and Node `Buffer`. Import `processAndStore` from server code
-> (`+page.server.ts`, a route handler, a script) — never from a component.
+> Requires Svelte 5 (`^5.0.0`).
+
+The package has two entry points, because half of it cannot run in a browser:
+
+| Import | Contains | Where |
+|---|---|---|
+| `@nomideusz/svelte-media` | components, `validateImageFile`, key helpers, `IMAGE_SIZES`, types | anywhere |
+| `@nomideusz/svelte-media/server` | storage adapters, `processAndStore`, `deleteMedia`, `getMediaUrl` | server only |
+
+The pipeline needs `sharp`, `node:fs` and `Buffer`. Keeping it behind `/server`
+is what lets a component import `ImageUpload` without a bundler dragging those
+into the browser build.
 
 ## Why
 
@@ -24,7 +33,7 @@ the seam.
 ## Quick Start
 
 ```ts
-import { createS3Adapter, processAndStore, getMediaUrl } from '@nomideusz/svelte-media';
+import { createS3Adapter, processAndStore, getMediaUrl } from '@nomideusz/svelte-media/server';
 
 const storage = createS3Adapter({
   endpoint:        process.env.S3_ENDPOINT!,     // https://xxx.r2.cloudflarestorage.com
@@ -49,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:
@@ -79,7 +114,7 @@ interface StorageAdapter {
 Two ship with the package:
 
 ```ts
-import { createS3Adapter, createLocalAdapter } from '@nomideusz/svelte-media';
+import { createS3Adapter, createLocalAdapter } from '@nomideusz/svelte-media/server';
 
 createS3Adapter({ /* S3Config, above */ });   // R2, MinIO, Tigris, AWS
 createLocalAdapter({ root: '/data/images' }); // writes under root, mkdir -p
@@ -109,7 +144,7 @@ is only needed to reject early and report a friendlier message.
 ## Deleting
 
 ```ts
-import { deleteMedia } from '@nomideusz/svelte-media';
+import { deleteMedia } from '@nomideusz/svelte-media/server';
 
 // Removes all four sizes; individual failures are swallowed
 await deleteMedia(storage, stored.prefix, stored.entityId, stored.filename);
@@ -152,23 +187,23 @@ the same reason: it renders on the client, where the adapter cannot go.
 ## API
 
 ```ts
-// Adapters
+// ── @nomideusz/svelte-media/server ──
 createS3Adapter(config: S3Config): StorageAdapter
 createLocalAdapter(config: LocalConfig): StorageAdapter
-
-// Pipeline
 processAndStore(adapter, file, prefix, entityId, config?): Promise<StoredMedia>
 deleteMedia(adapter, prefix, entityId, filename): Promise<void>
 getMediaUrl(adapter, prefix, entityId, filename, size = 'medium'): string
-getStorageKey(prefix, entityId, filename, size): string   // `${prefix}/${entityId}/${sizePrefix}${filename}`
+
+// ── @nomideusz/svelte-media (client-safe) ──
 validateImageFile(file, config?): ValidationResult
 generateMediaKey(): string                                 // `<cuid2>.webp`
+getStorageKey(prefix, entityId, filename, size): string   // `${prefix}/${entityId}/${sizePrefix}${filename}`
 IMAGE_SIZES
-
-// Components
 ImageUpload, ImageGallery
 ```
 
+Key helpers are exported from both entries, so server code needs only one import.
+
 Types: `StorageAdapter`, `S3Config`, `LocalConfig`, `StoredMedia`, `ImageSize`,
 `MediaConfig`, `ValidationResult`.
 

package/dist/core/media.d.ts

@@ -0,0 +1,25 @@
+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: {
+    thumbnail: {
+        width: number;
+        height: number;
+        fit: "cover";
+    };
+    medium: {
+        width: number;
+        height: number;
+        fit: "inside";
+    };
+    large: {
+        width: number;
+        height: number;
+        fit: "inside";
+    };
+};
+export declare const SIZE_PREFIXES: Record<ImageSize, string>;
+export declare const SIZE_QUALITY: Record<ImageSize, number>;
+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/media.js

@@ -0,0 +1,43 @@
+// Client-safe half of the package: validation, naming and key layout.
+// Deliberately free of sharp, node:fs and Buffer so components and browser code
+// can import it — see core/process.ts for the server pipeline.
+import { createId } from '@paralleldrive/cuid2';
+export const DEFAULT_MAX_SIZE = 5 * 1024 * 1024;
+export const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
+export const IMAGE_SIZES = {
+    thumbnail: { width: 300, height: 300, fit: 'cover' },
+    medium: { width: 800, height: 600, fit: 'inside' },
+    large: { width: 1200, height: 900, fit: 'inside' },
+};
+export const SIZE_PREFIXES = {
+    original: '',
+    thumbnail: 'thumb_',
+    medium: 'med_',
+    large: 'large_',
+};
+export const SIZE_QUALITY = {
+    original: 95,
+    thumbnail: 80,
+    medium: 85,
+    large: 90,
+};
+export function validateImageFile(file, config) {
+    const maxSize = config?.maxFileSize ?? DEFAULT_MAX_SIZE;
+    const allowed = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
+    if (file.size > maxSize) {
+        const mb = Math.round(maxSize / 1024 / 1024);
+        return { valid: false, error: `File too large (max ${mb}MB)` };
+    }
+    if (!allowed.includes(file.type)) {
+        return { valid: false, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
+    }
+    return { valid: true };
+}
+export function generateMediaKey(_originalName) {
+    // All processed output is WebP regardless of the uploaded format.
+    return `${createId()}.webp`;
+}
+export function getStorageKey(prefix, entityId, filename, size) {
+    const sizePrefix = SIZE_PREFIXES[size];
+    return `${prefix}/${entityId}/${sizePrefix}${filename}`;
+}

package/dist/core/process.d.ts

@@ -1,24 +1,4 @@
-import type { StorageAdapter, StoredMedia, ImageSize, MediaConfig, ValidationResult } from './types.js';
-export declare const IMAGE_SIZES: {
-    thumbnail: {
-        width: number;
-        height: number;
-        fit: "cover";
-    };
-    medium: {
-        width: number;
-        height: number;
-        fit: "inside";
-    };
-    large: {
-        width: number;
-        height: number;
-        fit: "inside";
-    };
-};
-export declare function validateImageFile(file: File, config?: MediaConfig): ValidationResult;
-export declare function generateMediaKey(_originalName?: string): string;
-export declare function getStorageKey(prefix: string, entityId: string, filename: string, size: ImageSize): string;
-export declare function processAndStore(adapter: StorageAdapter, file: File, prefix: string, entityId: string, config?: MediaConfig): Promise<StoredMedia>;
+import type { StorageAdapter, StoredMedia, ImageSize, MediaConfig } from './types.js';
+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

@@ -1,44 +1,8 @@
+// Server-only pipeline: needs sharp and Node's Buffer. Importing this from a
+// browser bundle will fail — the client-safe helpers live in core/media.ts and
+// are re-exported from the package root.
 import sharp from 'sharp';
-import { createId } from '@paralleldrive/cuid2';
-const DEFAULT_MAX_SIZE = 5 * 1024 * 1024;
-const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
-export const IMAGE_SIZES = {
-    thumbnail: { width: 300, height: 300, fit: 'cover' },
-    medium: { width: 800, height: 600, fit: 'inside' },
-    large: { width: 1200, height: 900, fit: 'inside' },
-};
-const SIZE_PREFIXES = {
-    original: '',
-    thumbnail: 'thumb_',
-    medium: 'med_',
-    large: 'large_',
-};
-const SIZE_QUALITY = {
-    original: 95,
-    thumbnail: 80,
-    medium: 85,
-    large: 90,
-};
-export function validateImageFile(file, config) {
-    const maxSize = config?.maxFileSize ?? DEFAULT_MAX_SIZE;
-    const allowed = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
-    if (file.size > maxSize) {
-        const mb = Math.round(maxSize / 1024 / 1024);
-        return { valid: false, error: `File too large (max ${mb}MB)` };
-    }
-    if (!allowed.includes(file.type)) {
-        return { valid: false, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
-    }
-    return { valid: true };
-}
-export function generateMediaKey(_originalName) {
-    // All processed output is WebP regardless of the uploaded format.
-    return `${createId()}.webp`;
-}
-export function getStorageKey(prefix, entityId, filename, size) {
-    const sizePrefix = SIZE_PREFIXES[size];
-    return `${prefix}/${entityId}/${sizePrefix}${filename}`;
-}
+import { IMAGE_SIZES, SIZE_QUALITY, generateMediaKey, getStorageKey, validateImageFile, } from './media.js';
 export async function processAndStore(adapter, file, prefix, entityId, config) {
     const validation = validateImageFile(file, config);
     if (!validation.valid)
@@ -65,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,7 +1,4 @@
-export type { StorageAdapter, S3Config, StoredMedia, ImageSize, MediaConfig, ValidationResult, } from './core/types.js';
-export type { LocalConfig } from './core/local-adapter.js';
-export { createS3Adapter } from './core/adapter.js';
-export { createLocalAdapter } from './core/local-adapter.js';
-export { validateImageFile, generateMediaKey, getStorageKey, processAndStore, deleteMedia, getMediaUrl, IMAGE_SIZES, } from './core/process.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/dist/index.js

@@ -1,5 +1,6 @@
-export { createS3Adapter } from './core/adapter.js';
-export { createLocalAdapter } from './core/local-adapter.js';
-export { validateImageFile, generateMediaKey, getStorageKey, processAndStore, deleteMedia, getMediaUrl, IMAGE_SIZES, } from './core/process.js';
+// Client-safe entry. The image pipeline and storage adapters need sharp,
+// node:fs and Buffer, so they live behind '@nomideusz/svelte-media/server' —
+// importing them here would break any browser bundle that touches a component.
+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/dist/server/index.d.ts

@@ -0,0 +1,6 @@
+export type { LocalConfig } from '../core/local-adapter.js';
+export { createS3Adapter } from '../core/adapter.js';
+export { createLocalAdapter } from '../core/local-adapter.js';
+export { processAndStore, deleteMedia, getMediaUrl } from '../core/process.js';
+export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';
+export type * from '../core/types.js';

package/dist/server/index.js

@@ -0,0 +1,6 @@
+// Server-only entry: sharp, node:fs and Buffer live behind here.
+export { createS3Adapter } from '../core/adapter.js';
+export { createLocalAdapter } from '../core/local-adapter.js';
+export { processAndStore, deleteMedia, getMediaUrl } from '../core/process.js';
+// Re-exported so server code needs only one import.
+export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nomideusz/svelte-media",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Image upload, processing, and S3-compatible storage for Svelte 5 apps.",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,10 @@
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
     }
   },
   "files": [