@effected/images 0.5.0 → 0.6.0

package/ImageBackend.js

@@ -50,6 +50,7 @@ var ImageBackend = class ImageBackend extends Context.Service()("@effected/image
 					for (const [ext, contentType] of FILES) {
 						const bytes = yield* fs.readFile(fileFor(key, ext)).pipe(Effect.map(Option.some), Effect.catchReason("PlatformError", "NotFound", () => Effect.succeedNone), Effect.mapError((cause) => new ImageBackendError({
 							operation: "get",
+							reason: "backend",
 							key,
 							cause
 						})));
@@ -65,6 +66,7 @@ var ImageBackend = class ImageBackend extends Context.Service()("@effected/image
 					const ext = params.contentType !== void 0 && Object.hasOwn(EXTENSION_BY_TYPE, params.contentType) ? EXTENSION_BY_TYPE[params.contentType] : void 0;
 					if (ext === void 0) return yield* new ImageBackendError({
 						operation: "set",
+						reason: "unsupported-content-type",
 						key: params.key,
 						cause: /* @__PURE__ */ new Error(`unsupported content type ${JSON.stringify(params.contentType ?? null)}`)
 					});
@@ -78,6 +80,7 @@ var ImageBackend = class ImageBackend extends Context.Service()("@effected/image
 						yield* fs.rename(temp, target);
 					}).pipe(Effect.onError(() => fs.remove(temp, { force: true }).pipe(Effect.ignore)), Effect.mapError((cause) => new ImageBackendError({
 						operation: "set",
+						reason: "backend",
 						key: params.key,
 						cause
 					})));
@@ -101,11 +104,13 @@ var ImageBackend = class ImageBackend extends Context.Service()("@effected/image
 				contentType: entry.contentType
 			}))), Effect.mapError((cause) => new ImageBackendError({
 				operation: "get",
+				reason: "backend",
 				key: k,
 				cause
 			})), Effect.withSpan("ImageBackend.get")),
 			set: (params) => source.set(params).pipe(Effect.mapError((cause) => new ImageBackendError({
 				operation: "set",
+				reason: "backend",
 				key: params.key,
 				cause
 			})), Effect.withSpan("ImageBackend.set"))

package/ImageBackendError.js

@@ -9,18 +9,31 @@ const causeMessage = (cause) => {
 /**
 * An image backend read or write failed.
 *
+* @remarks
+* `reason` says why, so a caller branches on a literal rather than reading
+* the message: `backend` is a failure of the store underneath (the file
+* system for `layerDirectory`, the adapted service for `layerFrom`), and
+* `unsupported-content-type` is a `set` whose content type the directory
+* backend has no file extension for. `backend` names the source rather than
+* claiming file IO, because `layerFrom` wraps any source failure — a store
+* `Cache` error included — under it.
+*
+* `reason` is required: a hand-written backend states which case it hit.
+*
 * @public
 */
 var ImageBackendError = class extends Schema.TaggedError()("ImageBackendError", {
 	/** The backend operation that failed. */
 	operation: Schema.Literals(["get", "set"]),
+	/** Why it failed: the store underneath, or a content type the backend cannot store. */
+	reason: Schema.Literals(["backend", "unsupported-content-type"]),
 	/** The key involved. */
 	key: Schema.String,
 	/** The underlying failure, preserved structurally. */
 	cause: Schema.Defect()
 }) {
 	get message() {
-		return `Image backend ${this.operation} failed for key "${this.key}": ${causeMessage(this.cause)}`;
+		return `Image backend ${this.operation} failed for key "${this.key}" (${this.reason}): ${causeMessage(this.cause)}`;
 	}
 };
 

package/README.md

@@ -142,7 +142,7 @@ The directory backend stores `<directory>/<key>.<ext>` through a temp file and a
 - `ImageFormat` — the literal union `png | jpeg | gif | webp | avif`.
 - `ImageParseError` — the one parse failure, with a `reason` and, once a signature matched, the `format`.
 - `ImageCacheKey` / `ImageCacheKeyError` — content-addressed keys from schema-encoded parameters; failure reasons `encode`, `non-json` and `digest`.
-- `ImageBackend` / `ImageBackendError` — the storage port, a directory backend, a no-store backend and a structural adapter.
+- `ImageBackend` / `ImageBackendError` — the storage port, a directory backend, a no-store backend and a structural adapter; failure reasons `backend` and `unsupported-content-type`.
 - `ImageCache` / `ImageGenerateError` — `getOrGenerate` with an optional `accept` format list that narrows the result's format.
 
 SVG, BMP, ICO, TIFF, HEIC, JPEG XL, EXIF orientation, image transformation and cache eviction are out of scope.

package/cache.d.ts

@@ -3,6 +3,8 @@ import * as Images from "@effected/images";
 declare const ImageBackendError_base: Schema.Class<ImageBackendError, Schema.TaggedStruct<"ImageBackendError", {
   /** The backend operation that failed. */
   readonly operation: Schema.Literals<readonly ["get", "set"]>;
+  /** Why it failed: the store underneath, or a content type the backend cannot store. */
+  readonly reason: Schema.Literals<readonly ["backend", "unsupported-content-type"]>;
   /** The key involved. */
   readonly key: Schema.String;
   /** The underlying failure, preserved structurally. */
@@ -11,6 +13,17 @@ declare const ImageBackendError_base: Schema.Class<ImageBackendError, Schema.Tag
 /**
  * An image backend read or write failed.
  *
+ * @remarks
+ * `reason` says why, so a caller branches on a literal rather than reading
+ * the message: `backend` is a failure of the store underneath (the file
+ * system for `layerDirectory`, the adapted service for `layerFrom`), and
+ * `unsupported-content-type` is a `set` whose content type the directory
+ * backend has no file extension for. `backend` names the source rather than
+ * claiming file IO, because `layerFrom` wraps any source failure — a store
+ * `Cache` error included — under it.
+ *
+ * `reason` is required: a hand-written backend states which case it hit.
+ *
  * @public
  */
 export declare class ImageBackendError extends ImageBackendError_base {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/images",
-	"version": "0.5.0",
+	"version": "0.6.0",
 	"private": false,
 	"description": "Image facts (format, MIME type, dimensions) from bytes, and a generated-image cache, for Effect.",
 	"keywords": [