@nomideusz/svelte-media 0.2.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,86 @@
 # Changelog
 
+## 0.5.0 — 2026-08-09
+
+### Added
+- **The read half of the pipeline.** `StorageAdapter` gains
+  `get(key): Promise<StorageObject | null>` (null = not found; real failures
+  reject), implemented by both adapters. Every deployment of this package was
+  serving from a private bucket, and both source apps had built parallel raw
+  S3 clients — three across the two apps — to work around the adapter being
+  write-only.
+- **`getSignedUrl(key, expiresIn?)` on the S3 adapter** (the `S3Adapter`
+  type), with expiry-buffered caching and in-flight dedupe — absorbed from
+  thebest's hand-rolled presign layer. This is what the previously-dead
+  `@aws-sdk/s3-request-presigner` dependency is now for.
+- **`serveMedia(adapter, key): Promise<Response>`** — the whole body of a
+  same-origin `/photos/[...key]`-style route: key validation (incl. `..`
+  traversal — one app's hand-written copy lacked the check), 404 on missing,
+  immutable cache headers.
+- **`createMediaStore({ adapter, ...limits, derive? })`** — the per-app
+  binding factory both apps had hand-built (`photo-storage.ts`, `media.ts`),
+  returning bound `store/remove/get/serve/url/signedUrl/validate`. Env reading
+  stays in the app; the adapter is the seam.
+
+### Changed
+- **Breaking for external adapter implementations:** `get` is now a required
+  `StorageAdapter` method. (Both in-repo apps consume the built-in adapters.)
+- `S3Config.publicUrl` is now optional — both real deployments serve private
+  buckets and were passing dummy values to satisfy the field. `getUrl()`
+  throws without it.
+
+## 0.4.0 — 2026-08-09
+
+### Added
+- **`SIZE_PREFIXES` and `SIZE_QUALITY` are now exported** (root and `/server`).
+  Both source apps had re-copied the prefix table by hand (one script copied the
+  quality values too) because the package kept them private — and the README had
+  already drifted from the code once (`lg_` vs `large_`). The variant naming is a
+  cross-app contract; now it has one home.
+- **Joined-key helpers** for apps that persist the single original key rather
+  than the (prefix, entityId, filename) triple: `variantKey(key, size)`,
+  `parseStorageKey(key)` (null for keys that don't fit the layout, e.g. legacy
+  ids), and `deleteMediaByKey(adapter, key)` on `/server`. Also
+  `sizeForWidth(width?)` — the smallest pre-generated variant that still fills a
+  display width (moved in from yoga's hand-rolled copy).
+- **Machine-readable validation.** `ValidationResult` gains
+  `code: 'empty' | 'file-too-large' | 'invalid-type'` plus `maxBytes` /
+  `allowedTypes`, and `processAndStore` now throws a typed
+  `MediaValidationError` carrying them — so a PL/EN/UK app maps `code` to its
+  own copy instead of surfacing the English `message`. Both apps had
+  re-implemented validation in 4 places purely to localize the strings.
+  The `empty` code also covers the zero-byte file every form action was
+  checking by hand.
+
+### Fixed
+- `ImageUpload`'s declared `config` prop was never read, so the client-side
+  pre-validation it implied never ran. It now validates each file before
+  `onUpload` and routes failures to `onError`.
+- README documented the large-variant prefix as `lg_`; the code writes
+  `large_`.
+
+### Changed
+- `generateMediaKey()` no longer takes the ignored `originalName` parameter.
+- The dead duplicate `DEFAULT_MAX_SIZE`/`DEFAULT_ALLOWED_TYPES` constants and
+  the unused `MediaValidation`/`MediaValidationOk` types in `core/types.ts` are
+  gone. (`MediaValidationError` is now the thrown error class instead of an
+  unused interface — technically a change to `/server`'s type surface.)
+
+## 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

@@ -1,5 +1,7 @@
 # @nomideusz/svelte-media
 
+[![npm](https://badgen.net/npm/v/@nomideusz/svelte-media)](https://www.npmjs.com/package/@nomideusz/svelte-media) [![license](https://badgen.net/badge/license/MIT/blue)](https://github.com/nomideusz/svelte-media/blob/main/LICENSE)
+
 Image upload, resizing and multi-size storage for Svelte 5 apps. One call takes
 a `File`, validates it, renders four sizes with sharp, and writes them through a
 pluggable storage adapter — S3-compatible or local disk.
@@ -58,6 +60,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:
@@ -67,7 +95,7 @@ file `<cuid2>.webp` and ignores the original extension.
 | `original` | unchanged | — | *(none)* |
 | `thumbnail` | 300×300 | `cover` | `thumb_` |
 | `medium` | 800×600 | `inside` | `med_` |
-| `large` | 1200×900 | `inside` | `lg_` |
+| `large` | 1200×900 | `inside` | `large_` |
 
 `cover` crops to fill; `inside` fits within the box and preserves aspect ratio,
 so `medium` and `large` are upper bounds rather than exact dimensions. The table
@@ -126,6 +154,11 @@ await deleteMedia(storage, stored.prefix, stored.entityId, stored.filename);
 
 ## Components
 
+> **Demo-grade.** Both production apps built on this package hand-roll their
+> upload UI (multi-file queues, form-action submission, brand styling, i18n)
+> and import only the server half. Treat these as starters to copy from, not
+> primitives to build on.
+
 ```svelte
 <script lang="ts">
   import { ImageUpload, ImageGallery } from '@nomideusz/svelte-media';

package/dist/components/ImageUpload.svelte

@@ -1,8 +1,10 @@
-<script lang="ts">let {
+<script lang="ts">import { validateImageFile } from "../core/media.js";
+let {
   onUpload,
   onError,
   maxFiles = 1,
-  accept = "image/jpeg,image/png,image/webp"
+  accept = "image/jpeg,image/png,image/webp",
+  config
 } = $props();
 let dragging = $state(false);
 let uploading = $state(false);
@@ -12,6 +14,11 @@ async function handleFiles(files) {
   uploading = true;
   try {
     for (const file of Array.from(files).slice(0, maxFiles)) {
+      const validation = validateImageFile(file, config);
+      if (!validation.valid) {
+        onError?.(validation.error ?? "Invalid file");
+        continue;
+      }
       await onUpload(file);
     }
   } catch (e) {

package/dist/components/ImageUpload.svelte.d.ts

@@ -4,6 +4,7 @@ interface Props {
     onError?: (message: string) => void;
     maxFiles?: number;
     accept?: string;
+    /** Pre-validates each file before onUpload; failures go to onError. */
     config?: MediaConfig;
 }
 declare const ImageUpload: import("svelte").Component<Props, {}, "">;

package/dist/core/adapter.d.ts

@@ -1,2 +1,2 @@
-import type { S3Config, StorageAdapter } from './types.js';
-export declare function createS3Adapter(config: S3Config): StorageAdapter;
+import type { S3Adapter, S3Config } from './types.js';
+export declare function createS3Adapter(config: S3Config): S3Adapter;

package/dist/core/adapter.js

@@ -1,4 +1,8 @@
-import { S3Client, PutObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { getSignedUrl as presignGetObject } from '@aws-sdk/s3-request-presigner';
+// Refresh signed URLs a minute before they actually expire, so a URL handed to
+// a browser never dies mid-request.
+const SIGNED_TTL_BUFFER_MS = 60_000;
 export function createS3Adapter(config) {
     const client = new S3Client({
         endpoint: config.endpoint,
@@ -9,6 +13,9 @@ export function createS3Adapter(config) {
         },
         forcePathStyle: config.forcePathStyle ?? true,
     });
+    // ponytail: unbounded caches — media keys are a finite catalog; add LRU if that changes.
+    const signedCache = new Map();
+    const signedInflight = new Map();
     return {
         async put(key, buffer, contentType) {
             await client.send(new PutObjectCommand({
@@ -20,6 +27,27 @@ export function createS3Adapter(config) {
                 CacheControl: 'public, max-age=31536000, immutable',
             }));
         },
+        async get(key) {
+            let res;
+            try {
+                res = await client.send(new GetObjectCommand({ Bucket: config.bucket, Key: key }));
+            }
+            catch (e) {
+                const err = e;
+                if (err.name === 'NoSuchKey' || err.name === 'NotFound' || err.$metadata?.httpStatusCode === 404) {
+                    return null;
+                }
+                throw e;
+            }
+            const body = res.Body?.transformToWebStream();
+            if (!body)
+                return null;
+            return {
+                body,
+                contentType: res.ContentType ?? 'application/octet-stream',
+                contentLength: res.ContentLength ?? null,
+            };
+        },
         async delete(key) {
             await client.send(new DeleteObjectCommand({
                 Bucket: config.bucket,
@@ -27,7 +55,34 @@ export function createS3Adapter(config) {
             }));
         },
         getUrl(key) {
+            if (!config.publicUrl) {
+                throw new Error('publicUrl not configured — serve private buckets via get() or getSignedUrl()');
+            }
             return `${config.publicUrl.replace(/\/$/, '')}/${key}`;
         },
+        async getSignedUrl(key, expiresIn = 3600) {
+            const cacheKey = `${expiresIn}:${key}`;
+            const cached = signedCache.get(cacheKey);
+            if (cached && cached.expiresAt > Date.now())
+                return cached.url;
+            if (cached)
+                signedCache.delete(cacheKey);
+            const inflight = signedInflight.get(cacheKey);
+            if (inflight)
+                return inflight;
+            const signing = presignGetObject(client, new GetObjectCommand({ Bucket: config.bucket, Key: key }), { expiresIn })
+                .then((url) => {
+                signedCache.set(cacheKey, {
+                    url,
+                    expiresAt: Date.now() + Math.max(expiresIn * 1000 - SIGNED_TTL_BUFFER_MS, 1_000),
+                });
+                return url;
+            })
+                .finally(() => {
+                signedInflight.delete(cacheKey);
+            });
+            signedInflight.set(cacheKey, signing);
+            return signing;
+        },
     };
 }

package/dist/core/local-adapter.js

@@ -1,5 +1,11 @@
-import { writeFile, unlink, mkdir } from 'node:fs/promises';
-import { join, dirname } from 'node:path';
+import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
+import { join, dirname, extname } from 'node:path';
+const MIME_BY_EXT = {
+    '.webp': 'image/webp',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+};
 export function createLocalAdapter(config) {
     return {
         async put(key, buffer, contentType) {
@@ -7,6 +13,22 @@ export function createLocalAdapter(config) {
             await mkdir(dirname(filePath), { recursive: true });
             await writeFile(filePath, buffer);
         },
+        async get(key) {
+            let buffer;
+            try {
+                buffer = await readFile(join(config.root, key));
+            }
+            catch (e) {
+                if (e.code === 'ENOENT')
+                    return null;
+                throw e;
+            }
+            return {
+                body: new Blob([new Uint8Array(buffer)]).stream(),
+                contentType: MIME_BY_EXT[extname(key).toLowerCase()] ?? 'application/octet-stream',
+                contentLength: buffer.length,
+            };
+        },
         async delete(key) {
             await unlink(join(config.root, key)).catch(() => { });
         },

package/dist/core/media.d.ts

@@ -1,4 +1,4 @@
-import type { ImageSize, MediaConfig, ValidationResult } from './types.js';
+import type { ImageSize, ValidationConfig, ValidationErrorCode, 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,35 @@ 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 generateMediaKey(_originalName?: string): string;
+export declare function validateImageFile(file: File, config?: ValidationConfig): ValidationResult;
+/**
+ * What `processAndStore` throws on a failed validation. Carries the
+ * machine-readable `code` (+ limits) so form actions can map it to their own
+ * copy instead of surfacing the English `message`.
+ */
+export declare class MediaValidationError extends Error {
+    readonly code: ValidationErrorCode;
+    readonly maxBytes?: number;
+    readonly allowedTypes?: string[];
+    constructor(result: ValidationResult);
+}
+export declare function generateMediaKey(): string;
 export declare function getStorageKey(prefix: string, entityId: string, filename: string, size: ImageSize): string;
+/**
+ * The variant key for a stored ORIGINAL key (`prefix/entityId/filename`) —
+ * for apps that persist the single joined key rather than the
+ * (prefix, entityId, filename) triple.
+ */
+export declare function variantKey(key: string, size: ImageSize): string;
+/** The smallest pre-generated variant that still fills `width` display pixels. */
+export declare function sizeForWidth(width?: number): ImageSize;
+/**
+ * Inverse of `getStorageKey` for an original key. Returns null for keys that
+ * don't fit the `prefix/entityId/filename` layout (e.g. legacy ids), so
+ * callers can treat those as "nothing to do".
+ */
+export declare function parseStorageKey(key: string): {
+    prefix: string;
+    entityId: string;
+    filename: string;
+} | null;

package/dist/core/media.js

@@ -24,16 +24,36 @@ export const SIZE_QUALITY = {
 export function validateImageFile(file, config) {
     const maxSize = config?.maxFileSize ?? DEFAULT_MAX_SIZE;
     const allowed = config?.allowedTypes ?? DEFAULT_ALLOWED_TYPES;
+    if (file.size === 0) {
+        return { valid: false, code: 'empty', error: 'No file provided' };
+    }
     if (file.size > maxSize) {
         const mb = Math.round(maxSize / 1024 / 1024);
-        return { valid: false, error: `File too large (max ${mb}MB)` };
+        return { valid: false, code: 'file-too-large', maxBytes: maxSize, 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: false, code: 'invalid-type', allowedTypes: allowed, error: `Invalid file type. Allowed: JPEG, PNG, WebP` };
     }
     return { valid: true };
 }
-export function generateMediaKey(_originalName) {
+/**
+ * What `processAndStore` throws on a failed validation. Carries the
+ * machine-readable `code` (+ limits) so form actions can map it to their own
+ * copy instead of surfacing the English `message`.
+ */
+export class MediaValidationError extends Error {
+    code;
+    maxBytes;
+    allowedTypes;
+    constructor(result) {
+        super(result.error ?? 'Invalid file');
+        this.name = 'MediaValidationError';
+        this.code = result.code ?? 'invalid-type';
+        this.maxBytes = result.maxBytes;
+        this.allowedTypes = result.allowedTypes;
+    }
+}
+export function generateMediaKey() {
     // All processed output is WebP regardless of the uploaded format.
     return `${createId()}.webp`;
 }
@@ -41,3 +61,35 @@ export function getStorageKey(prefix, entityId, filename, size) {
     const sizePrefix = SIZE_PREFIXES[size];
     return `${prefix}/${entityId}/${sizePrefix}${filename}`;
 }
+/**
+ * The variant key for a stored ORIGINAL key (`prefix/entityId/filename`) —
+ * for apps that persist the single joined key rather than the
+ * (prefix, entityId, filename) triple.
+ */
+export function variantKey(key, size) {
+    const idx = key.lastIndexOf('/');
+    return `${key.slice(0, idx + 1)}${SIZE_PREFIXES[size]}${key.slice(idx + 1)}`;
+}
+/** The smallest pre-generated variant that still fills `width` display pixels. */
+export function sizeForWidth(width) {
+    if (!width)
+        return 'medium';
+    if (width <= IMAGE_SIZES.thumbnail.width)
+        return 'thumbnail';
+    if (width <= IMAGE_SIZES.medium.width)
+        return 'medium';
+    return 'large';
+}
+/**
+ * Inverse of `getStorageKey` for an original key. Returns null for keys that
+ * don't fit the `prefix/entityId/filename` layout (e.g. legacy ids), so
+ * callers can treat those as "nothing to do".
+ */
+export function parseStorageKey(key) {
+    const parts = key.split('/');
+    if (parts.length < 3)
+        return null;
+    const filename = parts.pop();
+    const entityId = parts.pop();
+    return { prefix: parts.join('/'), entityId, filename };
+}

package/dist/core/process.d.ts

@@ -1,4 +1,10 @@
 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>;
+/**
+ * `deleteMedia` for apps that persist the single joined original key.
+ * Keys that don't parse (legacy ids from a previous storage system) are a
+ * silent no-op — there is nothing in object storage to delete.
+ */
+export declare function deleteMediaByKey(adapter: StorageAdapter, key: string): Promise<void>;
 export declare function getMediaUrl(adapter: StorageAdapter, prefix: string, entityId: string, filename: string, size?: ImageSize): string;

package/dist/core/process.js

@@ -2,12 +2,12 @@
 // 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 { IMAGE_SIZES, SIZE_QUALITY, generateMediaKey, getStorageKey, validateImageFile, } from './media.js';
+import { IMAGE_SIZES, SIZE_QUALITY, MediaValidationError, generateMediaKey, getStorageKey, parseStorageKey, validateImageFile, } from './media.js';
 export async function processAndStore(adapter, file, prefix, entityId, config) {
     const validation = validateImageFile(file, config);
     if (!validation.valid)
-        throw new Error(validation.error);
-    const filename = generateMediaKey(file.name);
+        throw new MediaValidationError(validation);
+    const filename = generateMediaKey();
     const arrayBuffer = await file.arrayBuffer();
     const buffer = Buffer.from(arrayBuffer);
     const sizes = {
@@ -29,12 +29,36 @@ 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));
     await Promise.all(keys.map((key) => adapter.delete(key).catch(() => { })));
 }
+/**
+ * `deleteMedia` for apps that persist the single joined original key.
+ * Keys that don't parse (legacy ids from a previous storage system) are a
+ * silent no-op — there is nothing in object storage to delete.
+ */
+export async function deleteMediaByKey(adapter, key) {
+    const parsed = parseStorageKey(key);
+    if (!parsed)
+        return;
+    await deleteMedia(adapter, parsed.prefix, parsed.entityId, parsed.filename);
+}
 export function getMediaUrl(adapter, prefix, entityId, filename, size = 'medium') {
     return adapter.getUrl(getStorageKey(prefix, entityId, filename, size));
 }

package/dist/core/serve.d.ts

@@ -0,0 +1,8 @@
+import type { StorageAdapter } from './types.js';
+/**
+ * Same-origin media serving: the whole body of a
+ * `/photos/[...key]`-style route. Key validation, 404 on missing, immutable
+ * cache headers (keys are content-addressed and never change in place).
+ * Returns a standard `Response` — return it directly from a SvelteKit handler.
+ */
+export declare function serveMedia(adapter: StorageAdapter, key: string): Promise<Response>;

package/dist/core/serve.js

@@ -0,0 +1,26 @@
+// Media keys are `prefix/entityId/(sizePrefix)filename.ext` — reject anything
+// else (especially `..` traversal) before it reaches the adapter. Both source
+// apps had written this route by hand; the copy without the guard had a path
+// traversal, which is why the validation lives here now.
+const MEDIA_KEY = /^[a-zA-Z0-9_/.-]+\.(webp|jpe?g|png)$/;
+/**
+ * Same-origin media serving: the whole body of a
+ * `/photos/[...key]`-style route. Key validation, 404 on missing, immutable
+ * cache headers (keys are content-addressed and never change in place).
+ * Returns a standard `Response` — return it directly from a SvelteKit handler.
+ */
+export async function serveMedia(adapter, key) {
+    if (!MEDIA_KEY.test(key) || key.includes('..')) {
+        return new Response('Not found', { status: 404 });
+    }
+    const obj = await adapter.get(key);
+    if (!obj)
+        return new Response('Not found', { status: 404 });
+    return new Response(obj.body, {
+        headers: {
+            'Content-Type': obj.contentType,
+            ...(obj.contentLength != null ? { 'Content-Length': String(obj.contentLength) } : {}),
+            'Cache-Control': 'public, max-age=31536000, immutable',
+        },
+    });
+}

package/dist/core/store.d.ts

@@ -0,0 +1,30 @@
+import type { ImageSize, MediaConfig, StorageAdapter, StorageObject, StoredMedia, ValidationResult } from './types.js';
+export interface MediaStoreConfig<TDerived = never> extends MediaConfig<TDerived> {
+    adapter: StorageAdapter;
+}
+/**
+ * The per-app binding — adapter, limits and derive hook bound once, so call
+ * sites pass only what varies per upload. Both source apps had hand-built this
+ * module (and one ended up configuring the same bucket two different ways);
+ * app #3 starts here instead.
+ *
+ * Env reading stays in the app: build the adapter from your own env names and
+ * hand it in.
+ */
+export interface MediaStore<TDerived = never> {
+    adapter: StorageAdapter;
+    /** `processAndStore` with the bound adapter + config. */
+    store(file: File, prefix: string, entityId: string): Promise<StoredMedia<TDerived>>;
+    /** Deletes all variants by the joined original key; unparseable keys are a no-op. */
+    remove(key: string): Promise<void>;
+    get(key: string): Promise<StorageObject | null>;
+    /** `serveMedia` with the bound adapter — a complete same-origin route body. */
+    serve(key: string): Promise<Response>;
+    /** Public URL for a size variant (adapters with a publicUrl only). */
+    url(key: string, size?: ImageSize): string;
+    /** Presigned URL for a size variant — rejects unless the adapter is S3. */
+    signedUrl(key: string, size?: ImageSize, expiresIn?: number): Promise<string>;
+    /** `validateImageFile` with the bound limits. */
+    validate(file: File): ValidationResult;
+}
+export declare function createMediaStore<TDerived = never>(config: MediaStoreConfig<TDerived>): MediaStore<TDerived>;

package/dist/core/store.js

@@ -0,0 +1,22 @@
+import { validateImageFile, variantKey } from './media.js';
+import { processAndStore, deleteMediaByKey } from './process.js';
+import { serveMedia } from './serve.js';
+export function createMediaStore(config) {
+    const { adapter, ...media } = config;
+    return {
+        adapter,
+        store: (file, prefix, entityId) => processAndStore(adapter, file, prefix, entityId, media),
+        remove: (key) => deleteMediaByKey(adapter, key),
+        get: (key) => adapter.get(key),
+        serve: (key) => serveMedia(adapter, key),
+        url: (key, size = 'original') => adapter.getUrl(variantKey(key, size)),
+        signedUrl: (key, size = 'original', expiresIn) => {
+            const s3 = adapter;
+            if (!s3.getSignedUrl) {
+                return Promise.reject(new Error('signedUrl needs an S3 adapter (getSignedUrl)'));
+            }
+            return s3.getSignedUrl(variantKey(key, size), expiresIn);
+        },
+        validate: (file) => validateImageFile(file, media),
+    };
+}

package/dist/core/types.d.ts

@@ -1,9 +1,27 @@
 export type ImageSize = 'original' | 'thumbnail' | 'medium' | 'large';
+/** What `StorageAdapter.get` resolves for an existing object. */
+export interface StorageObject {
+    body: ReadableStream<Uint8Array>;
+    contentType: string;
+    contentLength: number | null;
+}
 export interface StorageAdapter {
     put(key: string, buffer: Buffer, contentType: string): Promise<void>;
+    /** null when the object doesn't exist; rejects on real failures (network, auth). */
+    get(key: string): Promise<StorageObject | null>;
     delete(key: string): Promise<void>;
+    /** Public-URL serving only — throws when the adapter has no public base URL. */
     getUrl(key: string): string;
 }
+/** What `createS3Adapter` actually returns — a StorageAdapter that can presign. */
+export interface S3Adapter extends StorageAdapter {
+    /**
+     * Presigned GET URL for a private bucket. Cached until shortly before
+     * expiry and deduped in flight, so page loads with many images cost one
+     * signing pass per key.
+     */
+    getSignedUrl(key: string, expiresIn?: number): Promise<string>;
+}
 export interface S3Config {
     /** Full endpoint URL, e.g. https://xxx.r2.cloudflarestorage.com */
     endpoint: string;
@@ -12,12 +30,16 @@ export interface S3Config {
     bucket: string;
     accessKeyId: string;
     secretAccessKey: string;
-    /** Base public URL for getUrl(), e.g. https://pub-xxx.r2.dev */
-    publicUrl: string;
+    /**
+     * Base public URL for getUrl(), e.g. https://pub-xxx.r2.dev. Optional —
+     * private buckets serve via `get()` (same-origin proxy) or `getSignedUrl()`
+     * instead, and `getUrl()` throws without it.
+     */
+    publicUrl?: string;
     /** 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,22 +48,54 @@ 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;
-    error: string;
-}
-export interface MediaValidationOk {
-    isValid: true;
-}
-export type MediaValidation = MediaValidationOk | MediaValidationError;
-export declare const DEFAULT_MAX_SIZE: number;
-export declare const DEFAULT_ALLOWED_TYPES: string[];
+/** Machine-readable validation failure — map it to your own copy/i18n. */
+export type ValidationErrorCode = 'empty' | 'file-too-large' | 'invalid-type';
 export interface ValidationResult {
     valid: boolean;
+    /** Set when `valid` is false. */
+    code?: ValidationErrorCode;
+    /** The limit that produced a 'file-too-large', for message interpolation. */
+    maxBytes?: number;
+    /** The allow-list that produced an 'invalid-type'. */
+    allowedTypes?: string[];
+    /** Human-readable English fallback; apps with i18n should map `code` instead. */
     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/core/types.js

@@ -1,3 +1,2 @@
 // packages/svelte-media/src/lib/core/types.ts
-export const DEFAULT_MAX_SIZE = 5 * 1024 * 1024; // 5 MB
-export const DEFAULT_ALLOWED_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/webp'];
+export {};

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { StorageAdapter, S3Config, StoredMedia, ImageSize, MediaConfig, ValidationResult, } from './core/types.js';
-export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, DEFAULT_MAX_SIZE, DEFAULT_ALLOWED_TYPES, } from './core/media.js';
+export type { StorageAdapter, S3Adapter, S3Config, StorageObject, StoredMedia, ImageSize, MediaConfig, ValidationResult, ValidationConfig, ValidationErrorCode, DeriveSource, } from './core/types.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, 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,6 +1,6 @@
 // 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 { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, 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

@@ -1,6 +1,9 @@
 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 { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
+export { serveMedia } from '../core/serve.js';
+export { createMediaStore } from '../core/store.js';
+export type { MediaStore, MediaStoreConfig } from '../core/store.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, } from '../core/media.js';
 export type * from '../core/types.js';

package/dist/server/index.js

@@ -1,6 +1,8 @@
 // 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';
+export { processAndStore, deleteMedia, deleteMediaByKey, getMediaUrl } from '../core/process.js';
+export { serveMedia } from '../core/serve.js';
+export { createMediaStore } from '../core/store.js';
 // Re-exported so server code needs only one import.
-export { validateImageFile, generateMediaKey, getStorageKey, IMAGE_SIZES, } from '../core/media.js';
+export { validateImageFile, MediaValidationError, generateMediaKey, getStorageKey, variantKey, sizeForWidth, parseStorageKey, IMAGE_SIZES, SIZE_PREFIXES, SIZE_QUALITY, } from '../core/media.js';

package/package.json

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