@effected/images 0.4.0 → 0.6.0

package/ImageBackend.js

@@ -3,7 +3,7 @@ import { ImageBackendError } from "./ImageBackendError.js";
 import { DIGEST_PATTERN } from "./internal/digest.js";
 import { Context, Effect, FileSystem, Layer, Option, Path, Random } from "effect";
 
-//#region src/ImageBackend.ts
+// src/ImageBackend.ts
 /** `[extension, media type]` pairs, in the fixed order `get` probes them, from the package's one extension table. */
 const FILES = Object.entries(EXTENSIONS).map(([format, ext]) => [ext, MIME_TYPES[format]]);
 /** Media type to extension. Read only through `Object.hasOwn`: a content type is caller input. */
@@ -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"))
@@ -113,5 +118,4 @@ var ImageBackend = class ImageBackend extends Context.Service()("@effected/image
 	}
 };
 
-//#endregion
 export { ImageBackend };

package/ImageBackendError.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/ImageBackendError.ts
+// 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;
@@ -9,20 +9,32 @@ 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)}`;
 	}
 };
 
-//#endregion
 export { ImageBackendError };

package/ImageCache.js

@@ -3,7 +3,7 @@ import { ImageBackend } from "./ImageBackend.js";
 import { ImageGenerateError } from "./ImageGenerateError.js";
 import { Context, Effect, Layer, Option, Result } from "effect";
 
-//#region src/ImageCache.ts
+// src/ImageCache.ts
 /**
 * True when `accept` admits the facts' format. With `accept` omitted the call's `F` is every format, so admitting
 * everything is exactly the narrowing the guard claims.
@@ -66,5 +66,4 @@ var ImageCache = class ImageCache extends Context.Service()("@effected/images/Im
 	}));
 };
 
-//#endregion
 export { ImageCache };

package/ImageCacheKey.js

@@ -4,7 +4,7 @@ import { canonicalJson } from "./internal/canonical.js";
 import { Crypto, Effect, Result, Schema } from "effect";
 import * as Hex from "effect/encoding/Hex";
 
-//#region src/ImageCacheKey.ts
+// src/ImageCacheKey.ts
 /**
 * The identity of one generated image: a SHA-256 digest of the salt and the schema-encoded parameters.
 *
@@ -52,5 +52,4 @@ var ImageCacheKey = class ImageCacheKey extends Schema.Class("ImageCacheKey")({
 	}
 };
 
-//#endregion
 export { ImageCacheKey };

package/ImageCacheKeyError.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/ImageCacheKeyError.ts
+// src/ImageCacheKeyError.ts
 /**
 * Cache-key parameters that could not be turned into a key.
 *
@@ -27,5 +27,4 @@ var ImageCacheKeyError = class extends Schema.TaggedError()("ImageCacheKeyError"
 	}
 };
 
-//#endregion
 export { ImageCacheKeyError };

package/ImageFacts.js

@@ -8,7 +8,7 @@ import { readPng } from "./internal/png.js";
 import { readWebp } from "./internal/webp.js";
 import { Effect, Result, Schema } from "effect";
 
-//#region src/ImageFacts.ts
+// src/ImageFacts.ts
 const READERS = {
 	png: readPng,
 	jpeg: readJpeg,
@@ -74,5 +74,4 @@ var ImageFacts = class ImageFacts extends Schema.Class("ImageFacts")({
 	static fromBytes = Effect.fn("ImageFacts.fromBytes")((bytes) => Effect.fromResult(ImageFacts.fromBytesResult(bytes)));
 };
 
-//#endregion
 export { ImageFacts };

package/ImageFormat.js

@@ -1,6 +1,6 @@
 import { Schema } from "effect";
 
-//#region src/ImageFormat.ts
+// src/ImageFormat.ts
 /**
 * The image formats `@effected/images` reads.
 *
@@ -51,5 +51,4 @@ const ImageMimeTypeSchema = Schema.Literals([
 	MIME_TYPES.avif
 ]);
 
-//#endregion
 export { EXTENSIONS, ImageFormat, ImageMimeTypeSchema, MIME_TYPES };

package/ImageGenerateError.js

@@ -1,7 +1,7 @@
 import { ImageFormat } from "./ImageFormat.js";
 import { Schema } from "effect";
 
-//#region src/ImageGenerateError.ts
+// src/ImageGenerateError.ts
 /**
 * A generator produced bytes the cache will not store.
 *
@@ -30,5 +30,4 @@ var ImageGenerateError = class extends Schema.TaggedError()("ImageGenerateError"
 	}
 };
 
-//#endregion
 export { ImageGenerateError };

package/ImageParseError.js

@@ -1,7 +1,7 @@
 import { ImageFormat } from "./ImageFormat.js";
 import { Schema } from "effect";
 
-//#region src/ImageParseError.ts
+// src/ImageParseError.ts
 /**
 * Bytes that could not be read as an image header.
 *
@@ -31,5 +31,4 @@ var ImageParseError = class extends Schema.TaggedError()("ImageParseError", {
 	}
 };
 
-//#endregion
 export { ImageParseError };

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

@@ -1,9 +1,10 @@
 import { Context, Crypto, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
 import * as Images from "@effected/images";
-//#region src/ImageBackendError.d.ts
 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. */
@@ -12,13 +13,22 @@ 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 {
   get message(): string;
 }
-//#endregion
-//#region src/ImageBackend.d.ts
 /**
  * Bytes and media type a backend holds for one key.
  *
@@ -107,8 +117,6 @@ export declare class ImageBackend extends ImageBackend_base {
    */
   static layerFrom<I>(key: Context.Key<I, ImageBackendSource>): Layer.Layer<ImageBackend, never, I>;
 }
-//#endregion
-//#region src/ImageCacheKeyError.d.ts
 declare const ImageCacheKeyError_base: Schema.Class<ImageCacheKeyError, Schema.TaggedStruct<"ImageCacheKeyError", {
   /** Which step failed. */
   readonly reason: Schema.Literals<readonly ["encode", "non-json", "digest"]>;
@@ -129,8 +137,6 @@ declare const ImageCacheKeyError_base: Schema.Class<ImageCacheKeyError, Schema.T
 export declare class ImageCacheKeyError extends ImageCacheKeyError_base {
   get message(): string;
 }
-//#endregion
-//#region src/ImageCacheKey.d.ts
 /**
  * Options for {@link ImageCacheKey.fromParams}.
  *
@@ -166,8 +172,6 @@ export declare class ImageCacheKey extends ImageCacheKey_base {
    */
   static fromParams<S extends Schema.ConstraintEncoder<unknown>>(schema: S, params: S["Type"], options: ImageCacheKeyOptions): Effect.Effect<ImageCacheKey, ImageCacheKeyError, Crypto.Crypto>;
 }
-//#endregion
-//#region src/ImageGenerateError.d.ts
 declare const ImageGenerateError_base: Schema.Class<ImageGenerateError, Schema.TaggedStruct<"ImageGenerateError", {
   /** Why the output was refused. */
   readonly reason: Schema.Literals<readonly ["empty", "unparseable", "rejected-format"]>;
@@ -190,8 +194,6 @@ declare const ImageGenerateError_base: Schema.Class<ImageGenerateError, Schema.T
 export declare class ImageGenerateError extends ImageGenerateError_base {
   get message(): string;
 }
-//#endregion
-//#region src/ImageCache.d.ts
 /**
  * Options for {@link ImageCacheShape.getOrGenerate}.
  *
@@ -252,6 +254,5 @@ export declare class ImageCache extends ImageCache_base {
   /** The cache over whichever {@link ImageBackend} the app provides. */
   static readonly layer: Layer.Layer<ImageCache, never, ImageBackend>;
 }
-//#endregion
 export type { GetOrGenerateOptions, ImageBackendSetParams, ImageBackendShape, ImageBackendSource, ImageCacheKeyOptions, ImageCacheResult, ImageCacheShape, StoredImage };
 //# sourceMappingURL=cache.d.ts.map

package/index.d.ts

@@ -1,5 +1,4 @@
 import { Effect, Result, Schema } from "effect";
-//#region src/ImageParseError.d.ts
 declare const ImageParseError_base: Schema.Class<ImageParseError, Schema.TaggedStruct<"ImageParseError", {
   /** Why the header could not be read. */
   readonly reason: Schema.Literals<readonly ["unrecognized", "truncated", "malformed"]>;
@@ -22,8 +21,6 @@ declare const ImageParseError_base: Schema.Class<ImageParseError, Schema.TaggedS
 export declare class ImageParseError extends ImageParseError_base {
   get message(): string;
 }
-//#endregion
-//#region src/ImageFacts.d.ts
 /**
  * One of the five media types `ImageFacts.mimeType` holds, one per `ImageFormat`.
  *
@@ -77,8 +74,6 @@ export declare class ImageFacts extends ImageFacts_base {
    */
   static readonly fromBytes: (bytes: Uint8Array) => Effect.Effect<ImageFacts, ImageParseError>;
 }
-//#endregion
-//#region src/ImageFormat.d.ts
 /**
  * The image formats `@effected/images` reads.
  *
@@ -91,6 +86,5 @@ export declare const ImageFormat: Schema.Literals<readonly ["png", "jpeg", "gif"
  * @public
  */
 export type ImageFormat = typeof ImageFormat.Type;
-//#endregion
 export type { ImageExtension, ImageMimeType };
 //# sourceMappingURL=index.d.ts.map

package/internal/avif.js

@@ -2,7 +2,7 @@ import { ascii, u32be } from "./bytes.js";
 import { dimensions, malformed, truncated } from "./result.js";
 import { Result } from "effect";
 
-//#region src/internal/avif.ts
+// src/internal/avif.ts
 /** Boxes the walk may visit before it gives up. Hostile input cannot loop past it. */
 const AVIF_BOX_BUDGET = 1024;
 /** Brands scanned in the ftyp box, at most. */
@@ -91,5 +91,4 @@ const readAvif = (b) => {
 	return best === void 0 ? malformed("no ispe property") : dimensions(best.width, best.height);
 };
 
-//#endregion
 export { AVIF_BOX_BUDGET, isAvifBrand, readAvif };

package/internal/bytes.js

@@ -1,4 +1,4 @@
-//#region src/internal/bytes.ts
+// src/internal/bytes.ts
 const u16be = (b, o) => b[o] << 8 | b[o + 1];
 const u16le = (b, o) => b[o] | b[o + 1] << 8;
 const u24le = (b, o) => b[o] | b[o + 1] << 8 | b[o + 2] << 16;
@@ -10,5 +10,4 @@ const ascii = (b, o, length) => {
 };
 const matches = (b, o, signature) => b.length >= o + signature.length && signature.every((byte, i) => b[o + i] === byte);
 
-//#endregion
 export { ascii, matches, u16be, u16le, u24le, u32be };

package/internal/canonical.js

@@ -1,6 +1,6 @@
 import { Result } from "effect";
 
-//#region src/internal/canonical.ts
+// src/internal/canonical.ts
 const MAX_DEPTH = 256;
 const isPlainObject = (value) => {
 	const proto = Object.getPrototypeOf(value);
@@ -44,5 +44,4 @@ const encode = (value, depth) => {
 */
 const canonicalJson = (value) => encode(value, 0);
 
-//#endregion
 export { canonicalJson };

package/internal/detect.js

@@ -1,7 +1,7 @@
 import { ascii, matches } from "./bytes.js";
 import { isAvifBrand } from "./avif.js";
 
-//#region src/internal/detect.ts
+// src/internal/detect.ts
 const PNG = [
 	137,
 	80,
@@ -27,5 +27,4 @@ const detectFormat = (b) => {
 	if (isAvifBrand(b)) return "avif";
 };
 
-//#endregion
 export { detectFormat };

package/internal/digest.js

@@ -1,6 +1,5 @@
-//#region src/internal/digest.ts
+// src/internal/digest.ts
 /** A lowercase hex SHA-256 digest: the shape of every image cache key, and the only name a directory backend writes. */
 const DIGEST_PATTERN = /^[0-9a-f]{64}$/u;
 
-//#endregion
 export { DIGEST_PATTERN };

package/internal/gif.js

@@ -1,9 +1,8 @@
 import { u16le } from "./bytes.js";
 import { dimensions, truncated } from "./result.js";
 
-//#region src/internal/gif.ts
+// src/internal/gif.ts
 /** The logical screen descriptor follows the 6-byte signature: width(2 LE), height(2 LE). */
 const readGif = (b) => b.length < 10 ? truncated(`need 10 bytes for the screen descriptor, have ${b.length}`) : dimensions(u16le(b, 6), u16le(b, 8));
 
-//#endregion
 export { readGif };

package/internal/jpeg.js

@@ -1,7 +1,7 @@
 import { u16be } from "./bytes.js";
 import { dimensions, malformed, truncated } from "./result.js";
 
-//#region src/internal/jpeg.ts
+// src/internal/jpeg.ts
 /** Markers plus fill bytes the walk may consume before it gives up. Hostile input cannot loop past it. */
 const JPEG_STEP_BUDGET = 4096;
 /** SOFn frame headers: C0-CF except C4 (DHT), C8 (JPG) and CC (DAC). */
@@ -37,5 +37,4 @@ const readJpeg = (b) => {
 	}
 };
 
-//#endregion
 export { JPEG_STEP_BUDGET, readJpeg };

package/internal/png.js

@@ -1,7 +1,7 @@
 import { ascii, u32be } from "./bytes.js";
 import { dimensions, malformed, truncated } from "./result.js";
 
-//#region src/internal/png.ts
+// src/internal/png.ts
 /** IHDR is the first chunk: length(4)=13, type(4)="IHDR", width(4), height(4) after the 8-byte signature. */
 const readPng = (b) => {
 	if (b.length < 24) return truncated(`need 24 bytes for IHDR dimensions, have ${b.length}`);
@@ -11,5 +11,4 @@ const readPng = (b) => {
 	return dimensions(u32be(b, 16), u32be(b, 20));
 };
 
-//#endregion
 export { readPng };

package/internal/result.js

@@ -1,6 +1,6 @@
 import { Result } from "effect";
 
-//#region src/internal/result.ts
+// src/internal/result.ts
 const MAX_DIMENSION = 2147483647;
 const truncated = (detail) => Result.fail({
 	reason: "truncated",
@@ -17,5 +17,4 @@ const dimensions = (width, height) => legal(width) && legal(height) ? Result.suc
 	height
 }) : malformed(`dimensions ${width}x${height} out of range 1..${MAX_DIMENSION}`);
 
-//#endregion
 export { MAX_DIMENSION, dimensions, malformed, truncated };

package/internal/webp.js

@@ -1,7 +1,7 @@
 import { ascii, u16le, u24le } from "./bytes.js";
 import { dimensions, malformed, truncated } from "./result.js";
 
-//#region src/internal/webp.ts
+// src/internal/webp.ts
 const PAYLOAD = 20;
 const readWebp = (b) => {
 	if (b.length < 16) return truncated("need the first chunk's fourcc");
@@ -29,5 +29,4 @@ const readWebp = (b) => {
 	}
 };
 
-//#endregion
 export { readWebp };

package/package.json

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