@nitida/asset-client 0.18.1 → 0.19.1

package/src/index.ts

@@ -80,6 +80,67 @@ export type RequestablePreset =
   // compact `presets` wire string — so it is here and not on VariantPreset.
   | "probe";
 
+/**
+ * The same set as {@link RequestablePreset}, at RUNTIME.
+ *
+ * The type stops the mistake in TypeScript. It cannot stop it anywhere else,
+ * and "anywhere else" is where it keeps happening: a preset list assembled
+ * from config, from a route body, from JSON, or from a script's argv arrives
+ * as `string[]`, and the only way past the type was a cast.
+ *
+ * Measured in neo-real-estate on 2026-08-23, in THREE independent files:
+ *
+ *     presets: [...opts.presets] as VariantPreset[]
+ *
+ * — a blind cast, and to the wrong type at that: `VariantPreset` includes
+ * `hls` and `mp3`, which are precisely the two you may not ask for. Every one
+ * of those casts would have compiled a request the server answers 400.
+ *
+ * So the narrowing lives here, once, instead of being re-invented per repo.
+ */
+export const REQUESTABLE_PRESETS: readonly RequestablePreset[] = [
+  "thumb",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "original",
+  "poster",
+  "video",
+  "aiproxy",
+  "probe",
+] as const;
+
+/** Type guard for a single value. */
+export const isRequestablePreset = (v: string): v is RequestablePreset =>
+  (REQUESTABLE_PRESETS as readonly string[]).includes(v);
+
+/**
+ * Narrow a `string[]` to the presets the server can actually produce, or throw
+ * naming the offender.
+ *
+ * Throws rather than filtering silently, for the same reason the seven URL
+ * builders throw on a private asset: **a silence reads as "you can't"**. A
+ * caller that asked for `hls` wants an HLS ladder; dropping it quietly returns
+ * a 200 and no ladder, and the 404 lands later and somewhere else. The error
+ * names the value, says why the server cannot make it, and lists what it can.
+ */
+export const toRequestablePresets = (
+  input: readonly string[],
+): RequestablePreset[] => {
+  const bad = input.filter((p) => !isRequestablePreset(p));
+  if (bad.length > 0) {
+    throw new Error(
+      `Cannot request ${bad.map((b) => `"${b}"`).join(", ")}. ` +
+        "`hls` and `mp3` are things a variant can BE, not things you may ask " +
+        "for — the server derives them itself (hls when a video is " +
+        "transcoded, mp3 alongside any audio original). " +
+        `Requestable: ${REQUESTABLE_PRESETS.join(", ")}.`,
+    );
+  }
+  return input as RequestablePreset[];
+};
+
 /** 1-char alias used in storage keys / wire `presets` string. */
 export const PRESET_SHORT: Record<VariantPreset, string> = {
   thumb: "q",