@ultimat3/storage 7.0.0 → 9.0.0

package/CLAUDE.md

@@ -32,6 +32,7 @@ Tier 1. Object storage: named disks, safe keys, signed URLs, sniffed uploads.
 | `signed-url.ts` | HMAC over the constraint tuple, constant-time verify |
 | `upload.ts` | magic-byte sniff + size/allowlist/checksum policy |
 | `image.ts` | deterministic variant keys; byte path over core's pipeline (png/jpeg encode only) |
+| | `VARIANT_FORMATS` — what a variant KEY can carry — and NOT `IMAGE_FORMATS`, which is core's and means what core can PROBE. See below |
 | | `variantKey` is the cache identity `@ultimat3/cli`'s `/media/*` route looks a variant up by — derived, never stored, so a request that misses transforms once and every later one is a disk read |
 | `storage.ts` | `defineStorage` + module-level `storage()` / `disk()` |
 | `grant.ts` | `grantUpload` — the ONE way a presigned PUT is minted; the client never names a key |
@@ -169,7 +170,21 @@ Gotchas:
   in `beforeEach`.
 - `image.ts` owns no pixels: core's `transformImageBytes`/`blurDataUrl` are the only scaler.
   Its image failures (`X_IMAGE_UNSUPPORTED`, `X_IMAGE_DECODE_FAILED`) surface unwrapped —
-  wrapping them in a `StorageError` would give one failure two codes.
+  wrapping them in a `StorageError` would give one failure two codes. `variantKey` now RAISES
+  core's `imageUnsupported()` as well as passing them through, for that same reason.
+- **`VARIANT_FORMATS` is this package's format vocabulary, and `IMAGE_FORMATS` is core's.** Until
+  9.0.0 both packages exported `IMAGE_FORMATS` **and** `ImageFormat` from their own barrels over
+  different sets (core: `png|jpeg|webp|avif|gif|svg`, what it can PROBE; storage: `avif|webp|jpeg|png`),
+  so a caller narrowing on storage's held a type saying `gif` and `svg` could not occur and a
+  `probeImage()` value that was one — and `variantKey('photos/hero.gif', { format })` minted
+  `photos/hero@full.undefined`, a well-formed writable key naming a file nothing can serve. The set
+  is now a strict subset **by the compiler**: `as const satisfies readonly ImageFormat[]`, so a
+  member core cannot name is a build error here. `isVariantFormat` takes `string` on purpose, so
+  `probeImage(bytes).format` narrows through it with no cast. `avif` is in the set and `gif`/`svg`
+  are not because the question is what a variant KEY can carry, never what core can transform —
+  core decodes `gif` perfectly well, and naming this set `TRANSFORMABLE_FORMATS` would have been
+  the same lie one rename later. `scripts/render-modes.ts` holds the `IMAGE_FORMATS` row (`by:
+  'name'`) and `image.test.ts` fails the day either core name reappears in `src/index.ts`.
 - `transformImage()` must encode at exactly `fitDimensions()`'s size, and passes `format`
   explicitly (`?? 'webp'`, which then rejects): bytes that disagree with the `variantKey`
   extension, or with the `width`/`height` `@ultimat3/seo` inlined, are the layout shift the

package/README.md

@@ -235,7 +235,7 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 | `X_STORAGE_QUARANTINED` | `promoteAttachment` on a key nothing has released from `pending/quarantine/` |
 | `X_NOT_IMPLEMENTED` | S3 user metadata / cache-control; `serverSideEncryption` on either driver |
 | `X_ENV_MISSING` | core's: S3 credential env vars, or a `localDriver` built outside development where neither `signingSecret` nor `STORAGE_SIGNING_SECRET` holds a secret other than the published `DEV_SIGNING_SECRET` |
-| `X_IMAGE_UNSUPPORTED` | core's: an `avif` encode, or a source no built-in decoder reads |
+| `X_IMAGE_UNSUPPORTED` | core's: an `avif` encode, a source no built-in decoder reads, or a `variantKey` format no variant can carry |
 | `X_IMAGE_DECODE_FAILED` | core's: truncated or corrupt image bytes |
 
 ## Images
@@ -243,6 +243,15 @@ Inside `pending/` deliberately: an upload nobody ever scanned is still an orphan
 `variantKey()`, `srcsetDescriptors()`, `fitDimensions()` are pure — `@ultimat3/seo` builds
 `srcset` from them without decoding a byte.
 
+**`VARIANT_FORMATS` / `VariantFormat` are what a variant KEY can carry, `As of 2026-08`** —
+`avif`, `webp`, `jpeg`, `png` — and this package exports no `IMAGE_FORMATS` and no `ImageFormat`. Those two names are
+`@ultimat3/core`'s, over the six formats it can PROBE (`png`, `jpeg`, `webp`, `avif`, `gif`,
+`svg`). Until 9.0.0 both packages exported both names over different sets, so a caller narrowing on
+storage's held a type saying `gif` and `svg` could not occur and a `probeImage()` value that was
+one. `isVariantFormat(format)` takes a `string`, so a probed format narrows through it with no
+cast, and `variantKey()` refuses anything else with core's `X_IMAGE_UNSUPPORTED` instead of minting
+`photos/hero@full.undefined`.
+
 `transformImage()` and `blurPlaceholder()` are real, over `@ultimat3/core`'s pipeline, which is
 `Bun.Image` — no `sharp`, no dependency. **It encodes `png`, `jpeg` and `webp`** — so the default
 format and the default `.webp` key extension finally agree, and a `srcset` entry can be served

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/storage",
-  "version": "7.0.0",
+  "version": "9.0.0",
   "description": "Named disks over Bun.file and Bun.s3: safe keys, signed URLs, sniffed uploads",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "7.0.0"
+    "@ultimat3/core": "9.0.0"
   }
 }

package/src/image.ts

@@ -3,11 +3,41 @@
 // `<img srcset>` from `srcsetDescriptors()` without decoding a byte, and when it does need the
 // bytes, `transformImage()` returns exactly the size `fitDimensions()` already promised.
 
-import { blurDataUrl, probeImage, transformImageBytes } from '@ultimat3/core';
+import {
+  blurDataUrl,
+  type ImageFormat,
+  imageUnsupported,
+  probeImage,
+  transformImageBytes,
+} from '@ultimat3/core';
 import { assertSafeKey, keyExtname } from './path';
 
-export const IMAGE_FORMATS = ['avif', 'webp', 'jpeg', 'png'] as const;
-export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+/**
+ * The formats a stored VARIANT can be minted in — a strict subset of the ones `@ultimat3/core`
+ * can PROBE, and a different question from them. `satisfies readonly ImageFormat[]` is the whole
+ * derivation: a member core cannot name is a compile error here, so this can never become a
+ * second vocabulary the way it was one until 9.0.0 (both packages exported `IMAGE_FORMATS` and
+ * `ImageFormat`, over different sets, from their own barrels — so a caller narrowing on storage's
+ * held a type saying `gif` and `svg` could not occur and a `probeImage()` value that was one).
+ *
+ * NOT "the formats storage can transform": core decodes `gif` perfectly well. This set is what a
+ * variant KEY can carry, which is why `avif` is in it (key and `srcset` math only — asking for
+ * its bytes rejects with core's `X_IMAGE_UNSUPPORTED`) and `gif` and `svg` are not.
+ */
+export const VARIANT_FORMATS = [
+  'avif',
+  'webp',
+  'jpeg',
+  'png',
+] as const satisfies readonly ImageFormat[];
+export type VariantFormat = (typeof VARIANT_FORMATS)[number];
+
+/**
+ * Takes `string`, so `probeImage(bytes).format` narrows through it without a cast. That is the
+ * whole point: the answer for `gif` is `false`, and it used to be unaskable.
+ */
+export const isVariantFormat = (format: string): format is VariantFormat =>
+  (VARIANT_FORMATS as readonly string[]).includes(format);
 
 /** `cover` fills the box and crops the overflow; `contain` fits inside it, no crop. */
 export type ImageFit = 'cover' | 'contain';
@@ -15,7 +45,7 @@ export type ImageFit = 'cover' | 'contain';
 export interface ImageTransform {
   readonly width?: number | undefined;
   readonly height?: number | undefined;
-  readonly format?: ImageFormat | undefined;
+  readonly format?: VariantFormat | undefined;
   /** 1-100. Omitted means the format default (`DEFAULT_QUALITY`). */
   readonly quality?: number | undefined;
   readonly fit?: ImageFit | undefined;
@@ -29,7 +59,7 @@ export interface ImageSize {
 export const DEFAULT_QUALITY = 80;
 export const DEFAULT_SRCSET_WIDTHS = [320, 640, 960, 1280, 1920] as const;
 
-const FORMAT_EXTENSIONS: Readonly<Record<ImageFormat, string>> = {
+const FORMAT_EXTENSIONS: Readonly<Record<VariantFormat, string>> = {
   avif: 'avif',
   webp: 'webp',
   jpeg: 'jpg',
@@ -43,7 +73,19 @@ const FORMAT_EXTENSIONS: Readonly<Record<ImageFormat, string>> = {
 export function variantKey(sourceKey: string, transform: ImageTransform): string {
   const safe = assertSafeKey(sourceKey);
   const stem = safe.slice(0, safe.length - keyExtname(safe).length);
-  const format = transform.format ?? 'webp';
+  // `string`, not `VariantFormat`: a format off a query string or through an `as` reaches here as
+  // any string core can probe, and indexing FORMAT_EXTENSIONS with `gif` minted
+  // `photos/hero@full.undefined` — a well-formed, writable key naming a file nothing can serve.
+  // Core's code, not a storage one: one bad format is one failure, and seo and the dev asset
+  // route already report it as X_IMAGE_UNSUPPORTED.
+  const format: string = transform.format ?? 'webp';
+  if (!isVariantFormat(format)) {
+    throw imageUnsupported(
+      `"${format}" is not a format a stored variant can be minted in`,
+      `variantKey('${safe}', { format: 'webp' }) — one of ${VARIANT_FORMATS.join(', ')}; a ${format} source is served as-is, it has no variant`,
+      { format, key: safe },
+    );
+  }
   const parts: string[] = [];
   if (transform.width !== undefined) parts.push(`w${transform.width}`);
   if (transform.height !== undefined) parts.push(`h${transform.height}`);
@@ -63,7 +105,7 @@ export interface SrcsetDescriptor {
 
 export interface SrcsetOptions {
   readonly widths?: readonly number[] | undefined;
-  readonly format?: ImageFormat | undefined;
+  readonly format?: VariantFormat | undefined;
   readonly quality?: number | undefined;
   /** Intrinsic size of the source. Widths above it are dropped — upscaling is never useful. */
   readonly intrinsic?: ImageSize | undefined;

package/src/index.ts

@@ -97,20 +97,24 @@ export type { GrantUploadInput, UploadGrant, UploadRequest } from './grant';
 export { grantUpload } from './grant';
 export type {
   ImageFit,
-  ImageFormat,
   ImageSize,
   ImageTransform,
   SrcsetDescriptor,
   SrcsetOptions,
+  VariantFormat,
 } from './image';
+// No `ImageFormat` and no `IMAGE_FORMATS` here, deliberately: `@ultimat3/core` owns that name and
+// that set (what it can PROBE), this package owns `VARIANT_FORMATS` (what a variant can be minted
+// in), and `image.test.ts` fails the day either core name reappears in this file.
 export {
   blurPlaceholder,
   DEFAULT_QUALITY,
   DEFAULT_SRCSET_WIDTHS,
   fitDimensions,
-  IMAGE_FORMATS,
+  isVariantFormat,
   srcsetDescriptors,
   transformImage,
+  VARIANT_FORMATS,
   variantKey,
 } from './image';