@effected/images 0.5.0 → 0.6.1

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

@@ -1,26 +1,37 @@
+import { causeMessage } from "./internal/causeMessage.js";
 import { Schema } from "effect";
 
 // src/ImageBackendError.ts
-const causeMessage = (cause) => {
-	let current = cause;
-	for (let depth = 0; depth < 8 && current instanceof Error && current.cause instanceof Error; depth++) current = current.cause;
-	return current instanceof Error ? current.message : String(current);
-};
 /**
 * 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)}`;
+		const summary = `Image backend ${this.operation} failed for key "${this.key}" (${this.reason})`;
+		const detail = causeMessage(this.cause);
+		return detail === void 0 ? summary : `${summary}: ${detail}`;
 	}
 };
 

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/internal/causeMessage.js

@@ -0,0 +1,39 @@
+import { Predicate } from "effect";
+
+// src/internal/causeMessage.ts
+/** How many nodes of a cause chain the walk reads before stopping, so a cyclic chain cannot spin. */
+const CAUSE_DEPTH = 8;
+/** The message a single node carries: a thrown string, or a non-empty string `message` property. */
+const messageAt = (node) => {
+	const text = Predicate.isString(node) ? node : Predicate.hasProperty(node, "message") && Predicate.isString(node.message) ? node.message : void 0;
+	return text === void 0 || text.trim() === "" ? void 0 : text;
+};
+/**
+* Every distinct non-empty message a preserved cause chain carries, nearest
+* first and joined with `: `, or `undefined` when nothing along it has one.
+*
+* A `Schema.Defect()` field holds whatever was thrown, so the read is guarded
+* rather than assumed: `Predicate.hasProperty` + `Predicate.isString` accepts
+* an `Error`, a cross-realm `Error` that fails `instanceof`, a plain
+* `{ message }` object and a thrown string alike. An empty or whitespace-only
+* message counts as none. The walk follows `cause` links because a wrapper's
+* text is often the generic summary and the driver's text underneath is the
+* actionable detail, yet a wrapper that composes its own context must not
+* lose it either; so nothing is dropped, and a deeper text the nearer one
+* already contains is not repeated. The walk is bounded, so a cycle terminates.
+*/
+const causeMessage = (cause) => {
+	let message;
+	let node = cause;
+	for (let depth = 0; depth < CAUSE_DEPTH && node !== void 0 && node !== null; depth++) {
+		const text = messageAt(node);
+		if (text !== void 0) {
+			if (message === void 0 || text.includes(message)) message = text;
+			else if (!message.includes(text)) message = `${message}: ${text}`;
+		}
+		node = Predicate.hasProperty(node, "cause") ? node.cause : void 0;
+	}
+	return message;
+};
+
+export { causeMessage };

package/package.json

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