@effected/images 0.0.0-stage → 0.1.1

package/ImageBackend.js

@@ -0,0 +1,117 @@
+import { EXTENSIONS, MIME_TYPES } from "./ImageFormat.js";
+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
+/** `[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. */
+const EXTENSION_BY_TYPE = Object.fromEntries(FILES.map(([ext, type]) => [type, ext]));
+const assertDigest = (key) => DIGEST_PATTERN.test(key) ? Effect.void : Effect.die(/* @__PURE__ */ new TypeError(`image backend key ${JSON.stringify(key)} is not a 64-char hex digest`));
+/**
+* The storage port behind `ImageCache`.
+*
+* @public
+*/
+var ImageBackend = class ImageBackend extends Context.Service()("@effected/images/ImageBackend") {
+	/**
+	* The backend that stores nothing: `get` always misses and `set` discards the bytes.
+	*
+	* @remarks
+	* "The cache is off" as a layer, so a program keeps one `ImageCache.getOrGenerate` code path whether caching is
+	* enabled or not: provide this when it is off and `layerDirectory` (or `layerFrom`) when it is on. Every call runs
+	* the generator and returns `hit: false`; the generated bytes are still read and checked against `accept`. It needs
+	* nothing in `R`, never fails, and is a plain value, so it builds once however often it is provided.
+	*/
+	static layerNone = Layer.succeed(this)({
+		get: () => Effect.succeedNone,
+		set: () => Effect.void
+	});
+	/**
+	* A backend over one directory: `<directory>/<key>.<ext>`.
+	*
+	* @remarks
+	* Writes go to a temp file in the same directory and are renamed into place, so a failed or interrupted write
+	* never leaves a file that reads as a hit. Tags are accepted and ignored — a directory has no tag index. Keys must
+	* be 64-char lowercase hex digests (as `ImageCacheKey` produces); anything else is a defect, so a key can never
+	* name a path outside the directory. No expiry or eviction.
+	*
+	* Each call mints a fresh layer; bind the result to a `const` or the backend builds twice.
+	*/
+	static layerDirectory(options) {
+		return Layer.effect(ImageBackend, Effect.gen(function* () {
+			const fs = yield* FileSystem.FileSystem;
+			const path = yield* Path.Path;
+			const fileFor = (key, ext) => path.join(options.directory, `${key}.${ext}`);
+			return {
+				get: Effect.fn("ImageBackend.get")(function* (key) {
+					yield* assertDigest(key);
+					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",
+							key,
+							cause
+						})));
+						if (Option.isSome(bytes)) return Option.some({
+							value: bytes.value,
+							contentType
+						});
+					}
+					return Option.none();
+				}),
+				set: Effect.fn("ImageBackend.set")(function* (params) {
+					yield* assertDigest(params.key);
+					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",
+						key: params.key,
+						cause: /* @__PURE__ */ new Error(`unsupported content type ${JSON.stringify(params.contentType ?? null)}`)
+					});
+					const target = fileFor(params.key, ext);
+					const suffix = yield* Random.nextIntBetween(0, 2147483647);
+					const temp = path.join(options.directory, `.${params.key}.${suffix.toString(36)}.tmp`);
+					yield* Effect.gen(function* () {
+						yield* fs.makeDirectory(options.directory, { recursive: true });
+						yield* fs.writeFile(temp, params.value);
+						for (const [other] of FILES) if (other !== ext) yield* fs.remove(fileFor(params.key, other), { force: true });
+						yield* fs.rename(temp, target);
+					}).pipe(Effect.onError(() => fs.remove(temp, { force: true }).pipe(Effect.ignore)), Effect.mapError((cause) => new ImageBackendError({
+						operation: "set",
+						key: params.key,
+						cause
+					})));
+				})
+			};
+		}));
+	}
+	/**
+	* Adapt any structurally matching service, `@effected/store`'s `Cache` being the intended one, as the backend.
+	*
+	* @remarks
+	* `ImageBackend.layerFrom(Cache)` gives the image cache store's TTL, eviction and tag invalidation. Every source
+	* failure is wrapped as {@link ImageBackendError} with the original as `cause`.
+	*
+	* Each call mints a fresh layer; bind the result to a `const` or the backend builds twice.
+	*/
+	static layerFrom(key) {
+		return Layer.effect(ImageBackend, Effect.map(key, (source) => ({
+			get: (k) => source.get(k).pipe(Effect.map(Option.map((entry) => ({
+				value: entry.value,
+				contentType: entry.contentType
+			}))), Effect.mapError((cause) => new ImageBackendError({
+				operation: "get",
+				key: k,
+				cause
+			})), Effect.withSpan("ImageBackend.get")),
+			set: (params) => source.set(params).pipe(Effect.mapError((cause) => new ImageBackendError({
+				operation: "set",
+				key: params.key,
+				cause
+			})), Effect.withSpan("ImageBackend.set"))
+		})));
+	}
+};
+
+//#endregion
+export { ImageBackend };

package/ImageBackendError.js

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+
+//#region 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.
+*
+* @public
+*/
+var ImageBackendError = class extends Schema.TaggedError()("ImageBackendError", {
+	/** The backend operation that failed. */
+	operation: Schema.Literals(["get", "set"]),
+	/** 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)}`;
+	}
+};
+
+//#endregion
+export { ImageBackendError };

package/ImageCache.js

@@ -0,0 +1,70 @@
+import { ImageFacts } from "./ImageFacts.js";
+import { ImageBackend } from "./ImageBackend.js";
+import { ImageGenerateError } from "./ImageGenerateError.js";
+import { Context, Effect, Layer, Option, Result } from "effect";
+
+//#region 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.
+*/
+const accepted = (facts, accept) => accept === void 0 || accept.includes(facts.format);
+/**
+* A cache for generated images, keyed by `ImageCacheKey`, stored through {@link ImageBackend}.
+*
+* @public
+*/
+var ImageCache = class ImageCache extends Context.Service()("@effected/images/ImageCache") {
+	/** The cache over whichever {@link ImageBackend} the app provides. */
+	static layer = Layer.effect(ImageCache, Effect.gen(function* () {
+		const backend = yield* ImageBackend;
+		const getOrGenerate = (key, generate, options) => Effect.gen(function* () {
+			const accept = options?.accept;
+			const stored = yield* backend.get(key.digest);
+			if (Option.isSome(stored)) {
+				const facts = ImageFacts.fromBytesResult(stored.value.value);
+				if (Result.isSuccess(facts) && accepted(facts.success, accept)) {
+					yield* Effect.annotateCurrentSpan({
+						hit: true,
+						format: facts.success.format
+					});
+					return {
+						bytes: stored.value.value,
+						facts: facts.success,
+						hit: true
+					};
+				}
+			}
+			yield* Effect.annotateCurrentSpan("hit", false);
+			const bytes = yield* generate();
+			if (bytes.byteLength === 0) return yield* new ImageGenerateError({ reason: "empty" });
+			const parsed = ImageFacts.fromBytesResult(bytes);
+			if (Result.isFailure(parsed)) return yield* new ImageGenerateError({
+				reason: "unparseable",
+				cause: parsed.failure
+			});
+			const facts = parsed.success;
+			yield* Effect.annotateCurrentSpan("format", facts.format);
+			if (!accepted(facts, accept)) return yield* new ImageGenerateError({
+				reason: "rejected-format",
+				format: facts.format,
+				accept: [...accept ?? []]
+			});
+			yield* backend.set({
+				key: key.digest,
+				value: bytes,
+				contentType: facts.mimeType,
+				tags: [key.namespace]
+			});
+			return {
+				bytes,
+				facts,
+				hit: false
+			};
+		}).pipe(Effect.withSpan("ImageCache.getOrGenerate", { attributes: { namespace: key.namespace } }));
+		return { getOrGenerate };
+	}));
+};
+
+//#endregion
+export { ImageCache };

package/ImageCacheKey.js

@@ -0,0 +1,56 @@
+import { DIGEST_PATTERN } from "./internal/digest.js";
+import { ImageCacheKeyError } from "./ImageCacheKeyError.js";
+import { canonicalJson } from "./internal/canonical.js";
+import { Crypto, Effect, Result, Schema } from "effect";
+import * as Hex from "effect/encoding/Hex";
+
+//#region src/ImageCacheKey.ts
+/**
+* The identity of one generated image: a SHA-256 digest of the salt and the schema-encoded parameters.
+*
+* @public
+*/
+var ImageCacheKey = class ImageCacheKey extends Schema.Class("ImageCacheKey")({
+	/** Lowercase hex SHA-256 of `salt`, a NUL, and the canonical JSON of the encoded params. */
+	digest: Schema.String.check(Schema.isPattern(DIGEST_PATTERN)),
+	/** The salt the digest was derived with. */
+	salt: Schema.String,
+	/** The grouping tag. */
+	namespace: Schema.String
+}) {
+	/**
+	* Derive a key.
+	*
+	* @remarks
+	* `params` are encoded through `schema`, so a transformation participates and the key reflects the wire form. The
+	* digest is core `Crypto`'s SHA-256, so `Crypto` is required — Node apps get it from `NodeServices.layer` or
+	* `NodeCrypto.layer`.
+	*/
+	static fromParams(schema, params, options) {
+		return Effect.gen(function* () {
+			const encoded = yield* Schema.encodeEffect(schema)(params).pipe(Effect.mapError((cause) => new ImageCacheKeyError({
+				reason: "encode",
+				detail: cause.message,
+				cause
+			})));
+			const canonical = canonicalJson(encoded);
+			if (Result.isFailure(canonical)) return yield* new ImageCacheKeyError({
+				reason: "non-json",
+				detail: canonical.failure
+			});
+			const bytes = yield* (yield* Crypto.Crypto).digest("SHA-256", new TextEncoder().encode(`${options.salt}\u0000${canonical.success}`)).pipe(Effect.mapError((cause) => new ImageCacheKeyError({
+				reason: "digest",
+				detail: cause.message,
+				cause
+			})));
+			return ImageCacheKey.make({
+				digest: Hex.encode(bytes),
+				salt: options.salt,
+				namespace: options.namespace
+			});
+		}).pipe(Effect.withSpan("ImageCacheKey.fromParams", { attributes: { namespace: options.namespace } }));
+	}
+};
+
+//#endregion
+export { ImageCacheKey };

package/ImageCacheKeyError.js

@@ -0,0 +1,31 @@
+import { Schema } from "effect";
+
+//#region src/ImageCacheKeyError.ts
+/**
+* Cache-key parameters that could not be turned into a key.
+*
+* @remarks
+* `encode`: the parameter schema rejected the params. `non-json`: the encoded form holds a value canonical JSON
+* cannot carry (a `Date`, a `bigint`, a non-finite number, a class instance). `digest`: the `Crypto` service failed.
+*
+* @public
+*/
+var ImageCacheKeyError = class extends Schema.TaggedError()("ImageCacheKeyError", {
+	/** Which step failed. */
+	reason: Schema.Literals([
+		"encode",
+		"non-json",
+		"digest"
+	]),
+	/** What exactly was wrong. */
+	detail: Schema.String,
+	/** The schema error (`encode`) or platform error (`digest`). */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return `Cannot derive an image cache key (${this.reason}): ${this.detail}`;
+	}
+};
+
+//#endregion
+export { ImageCacheKeyError };

package/ImageFacts.js

@@ -0,0 +1,78 @@
+import { EXTENSIONS, ImageFormat, ImageMimeTypeSchema, MIME_TYPES } from "./ImageFormat.js";
+import { ImageParseError } from "./ImageParseError.js";
+import { readAvif } from "./internal/avif.js";
+import { detectFormat } from "./internal/detect.js";
+import { readGif } from "./internal/gif.js";
+import { readJpeg } from "./internal/jpeg.js";
+import { readPng } from "./internal/png.js";
+import { readWebp } from "./internal/webp.js";
+import { Effect, Result, Schema } from "effect";
+
+//#region src/ImageFacts.ts
+const READERS = {
+	png: readPng,
+	jpeg: readJpeg,
+	gif: readGif,
+	webp: readWebp,
+	avif: readAvif
+};
+const Dimension = Schema.Int.check(Schema.isGreaterThan(0));
+/**
+* What an image's header says about it: format, MIME type and stored pixel dimensions.
+*
+* @remarks
+* Dimensions are as stored in the file; EXIF orientation is not applied.
+*
+* @public
+*/
+var ImageFacts = class ImageFacts extends Schema.Class("ImageFacts")({
+	/** The detected format. */
+	format: ImageFormat,
+	/** The IANA media type for `format`: one of `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`. */
+	mimeType: ImageMimeTypeSchema,
+	/** Stored pixel width. */
+	width: Dimension,
+	/** Stored pixel height. */
+	height: Dimension
+}) {
+	/**
+	* The conventional file extension for `format`, without the dot: `jpg` for `jpeg`, the format name otherwise.
+	*
+	* @remarks
+	* A getter, not a field: it is derived from `format` on read, so it is absent from the encoded form and a decoded
+	* value has it again. Name a written file with it instead of keeping a private format-to-extension table.
+	*/
+	get extension() {
+		return EXTENSIONS[this.format];
+	}
+	/**
+	* Read facts from an image's bytes — the synchronous primitive.
+	*
+	* @remarks
+	* Reads only the header. Never throws: unknown bytes are `unrecognized`, a
+	* header that ends early is `truncated`, an impossible header is `malformed`.
+	*/
+	static fromBytesResult(bytes) {
+		const format = detectFormat(bytes);
+		if (format === void 0) return Result.fail(new ImageParseError({ reason: "unrecognized" }));
+		const read = READERS[format](bytes);
+		if (Result.isFailure(read)) return Result.fail(new ImageParseError({
+			reason: read.failure.reason,
+			format,
+			detail: read.failure.detail
+		}));
+		return Result.succeed(ImageFacts.make({
+			format,
+			mimeType: MIME_TYPES[format],
+			width: read.success.width,
+			height: read.success.height
+		}));
+	}
+	/**
+	* Read facts from an image's bytes — {@link ImageFacts.fromBytesResult} with a span.
+	*/
+	static fromBytes = Effect.fn("ImageFacts.fromBytes")((bytes) => Effect.fromResult(ImageFacts.fromBytesResult(bytes)));
+};
+
+//#endregion
+export { ImageFacts };

package/ImageFormat.js

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+
+//#region src/ImageFormat.ts
+/**
+* The image formats `@effected/images` reads.
+*
+* @public
+*/
+const ImageFormat = Schema.Literals([
+	"png",
+	"jpeg",
+	"gif",
+	"webp",
+	"avif"
+]);
+/**
+* The conventional file extension for each format — the one table every extension in the package is read from.
+* `ImageFacts#extension` declares the union these values must fall in.
+*
+* @internal
+*/
+const EXTENSIONS = {
+	png: "png",
+	jpeg: "jpg",
+	gif: "gif",
+	webp: "webp",
+	avif: "avif"
+};
+/**
+* The IANA media type for each format. `ImageFacts.mimeType`'s schema is built from these values.
+*
+* @internal
+*/
+const MIME_TYPES = {
+	png: "image/png",
+	jpeg: "image/jpeg",
+	gif: "image/gif",
+	webp: "image/webp",
+	avif: "image/avif"
+};
+/**
+* The schema of `ImageFacts.mimeType`: the literals of {@link MIME_TYPES}, so the two cannot drift.
+*
+* @internal
+*/
+const ImageMimeTypeSchema = Schema.Literals([
+	MIME_TYPES.png,
+	MIME_TYPES.jpeg,
+	MIME_TYPES.gif,
+	MIME_TYPES.webp,
+	MIME_TYPES.avif
+]);
+
+//#endregion
+export { EXTENSIONS, ImageFormat, ImageMimeTypeSchema, MIME_TYPES };

package/ImageGenerateError.js

@@ -0,0 +1,34 @@
+import { ImageFormat } from "./ImageFormat.js";
+import { Schema } from "effect";
+
+//#region src/ImageGenerateError.ts
+/**
+* A generator produced bytes the cache will not store.
+*
+* @remarks
+* `empty`: zero bytes. `unparseable`: not a readable image (`cause` is the `ImageParseError`).
+* `rejected-format`: a readable image whose format is outside the caller's `accept` list.
+*
+* @public
+*/
+var ImageGenerateError = class extends Schema.TaggedError()("ImageGenerateError", {
+	/** Why the output was refused. */
+	reason: Schema.Literals([
+		"empty",
+		"unparseable",
+		"rejected-format"
+	]),
+	/** The output's format, when it was readable. */
+	format: Schema.optionalKey(ImageFormat),
+	/** The formats the caller accepts, for `rejected-format`. */
+	accept: Schema.optionalKey(Schema.Array(ImageFormat)),
+	/** The parse failure, for `unparseable`. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return this.reason === "empty" ? "Image generator returned no bytes" : this.reason === "unparseable" ? "Image generator returned bytes that are not a readable image" : `Image generator returned a ${this.format ?? "?"} image; accepted: ${(this.accept ?? []).join(", ")}`;
+	}
+};
+
+//#endregion
+export { ImageGenerateError };

package/ImageParseError.js

@@ -0,0 +1,35 @@
+import { ImageFormat } from "./ImageFormat.js";
+import { Schema } from "effect";
+
+//#region src/ImageParseError.ts
+/**
+* Bytes that could not be read as an image header.
+*
+* @remarks
+* `unrecognized`: no known signature. `truncated`: a signature matched but the
+* bytes end before the dimension fields. `malformed`: a header field is
+* impossible (a zero or out-of-range dimension, an inconsistent length, or a
+* walk that exhausted its step budget).
+*
+* @public
+*/
+var ImageParseError = class extends Schema.TaggedError()("ImageParseError", {
+	/** Why the header could not be read. */
+	reason: Schema.Literals([
+		"unrecognized",
+		"truncated",
+		"malformed"
+	]),
+	/** The format whose signature matched, when one did. */
+	format: Schema.optionalKey(ImageFormat),
+	/** What exactly was wrong. */
+	detail: Schema.optionalKey(Schema.String)
+}) {
+	get message() {
+		const lead = this.reason === "unrecognized" ? "Unrecognized image signature" : `${this.reason === "truncated" ? "Truncated" : "Malformed"} ${this.format ?? "image"} header`;
+		return this.detail === void 0 ? lead : `${lead}: ${this.detail}`;
+	}
+};
+
+//#endregion
+export { ImageParseError };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.