@effected/images 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# @effected/images
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@effected%2Fimages?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/images)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Image facts from bytes, and a cache for generated images. `ImageFacts` reads the format, MIME type and pixel dimensions of a PNG, JPEG, GIF, WebP or AVIF file straight from its header, with one typed failure for bytes that are not a readable image. `ImageCache` answers "have I already generated an image from these parameters?", so a build stops re-running an expensive renderer such as an Open Graph card generator on every run.
+
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
+> Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Install
+
+```bash
+npm install @effected/images effect
+```
+
+```bash
+pnpm add @effected/images effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is the only peer dependency, and the only dependency of any kind — the format readers are in-house.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED`. Import from an ES module.
+
+## Image facts
+
+The root entry is pure: no IO, no services. `ImageFacts.fromBytesResult` is the synchronous engine, usable from a script with no Effect runtime, and `ImageFacts.fromBytes` is the same read as an `Effect`.
+
+```ts
+import { ImageFacts } from "@effected/images";
+import { Effect, Result } from "effect";
+
+declare const bytes: Uint8Array;
+
+// Synchronous: a Result, never a throw.
+const result = ImageFacts.fromBytesResult(bytes);
+if (Result.isSuccess(result)) {
+  const { format, mimeType, width, height } = result.success; // "png", "image/png", 1200, 630
+  const file = `card.${result.success.extension}`; // "card.png"; a JPEG is written ".jpg"
+}
+
+// Effect: fails with ImageParseError.
+const facts = ImageFacts.fromBytes(bytes).pipe(
+  Effect.catchTag("ImageParseError", (e) => Effect.logWarning(`not an image: ${e.reason}`)),
+);
+```
+
+`mimeType` is one of the five media types (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`), and `extension` is the conventional file extension: `jpg` for `jpeg`, the format name otherwise. `extension` is a getter derived from `format`, so it is not part of the encoded form, and a spread such as `{ ...facts }` drops it.
+
+`ImageParseError.reason` is `unrecognized` (no known signature), `truncated` (a recognized file cut short) or `malformed` (a header that contradicts itself). Readers never throw on any input, bounds-check every length before reading it, and bound the JPEG and AVIF walks with a step budget.
+
+## The generated-image cache
+
+`@effected/images/cache` caches generated bytes under a key derived from the parameters that produced them. `ImageCacheKey.fromParams` encodes the parameters through your `Schema`, serializes them canonically and digests them with a `salt` — the identity of your generator, bumped when its template changes so every old entry misses.
+
+```ts
+import { ImageBackend, ImageCache, ImageCacheKey } from "@effected/images/cache";
+import { NodeServices } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+
+const CardParams = Schema.Struct({ title: Schema.String, theme: Schema.String });
+declare const renderCard: () => Effect.Effect<Uint8Array>; // your renderer
+
+const CacheLive = ImageCache.layer.pipe(
+  Layer.provide(ImageBackend.layerDirectory({ directory: ".cache/og" })),
+);
+
+const program = Effect.gen(function* () {
+  const cache = yield* ImageCache;
+  const key = yield* ImageCacheKey.fromParams(
+    CardParams,
+    { title: "Hello", theme: "dark" },
+    { salt: "og-card-v3", namespace: "og" },
+  );
+  const { bytes, facts, hit } = yield* cache.getOrGenerate(
+    key,
+    renderCard, // () => Effect<Uint8Array, E, R> - runs only on a miss
+    { accept: ["png"] },
+  );
+  return { bytes, width: facts.width, hit };
+}).pipe(Effect.provide(CacheLive), Effect.provide(NodeServices.layer));
+```
+
+`getOrGenerate` returns the bytes, their `ImageFacts` and whether it was a `hit`. With `accept`, the result's `facts.format` is typed as the accepted formats, so `["png", "jpeg", "webp"]` gives `"png" | "jpeg" | "webp"`; without it, every format. A stored entry that no longer parses, or whose format is outside `accept`, is treated as a miss and overwritten. A generator result that is empty, unparseable or outside `accept` fails with `ImageGenerateError` and is never stored. Backend failures surface as `ImageBackendError`; the generator's own error passes through untouched.
+
+### A Promise-returning renderer
+
+When the renderer returns a Promise, wrap it with both `try` and `catch` so its own error reaches the caller:
+
+```ts
+import { Effect } from "effect";
+
+declare const render: (info: { readonly title: string }) => Promise<Uint8Array>;
+declare const info: { readonly title: string };
+
+const generate = () => Effect.tryPromise({ try: () => render(info), catch: (cause) => cause });
+```
+
+The one-argument `Effect.tryPromise(() => render(info))` wraps a rejection in `UnknownError`, so the generator's own error is lost.
+
+### Switching the cache off
+
+`ImageBackend.layerNone` stores nothing: `get` always misses and `set` discards. Provide it when caching is disabled and keep the same `getOrGenerate` call; every call runs the generator and returns `hit: false`.
+
+```ts
+import { ImageBackend } from "@effected/images/cache";
+
+declare const cachingEnabled: boolean;
+const backend = cachingEnabled ? ImageBackend.layerDirectory({ directory: ".cache/og" }) : ImageBackend.layerNone;
+```
+
+The key digest uses core `Crypto`, and the directory backend uses `FileSystem` and `Path`. On Node, `NodeServices.layer` from `@effect/platform-node` provides all three.
+
+### Bring your own store
+
+`ImageBackend` is a port, not a dependency. `ImageBackend.layerFrom(key)` adapts any service whose `get` and `set` match structurally — for example the `Cache` from `@effected/store`, with no edge between the two packages:
+
+```ts
+import { Cache } from "@effected/store";
+import { ImageBackend } from "@effected/images/cache";
+
+const StoreBacked = ImageBackend.layerFrom(Cache); // provide Cache underneath
+```
+
+The directory backend stores `<directory>/<key>.<ext>` through a temp file and an atomic rename. It accepts and ignores `tags`.
+
+## Features
+
+- `ImageFacts` — format, MIME type, file extension and pixel dimensions as stored in the file; sync `fromBytesResult` and Effect `fromBytes`.
+- `ImageExtension` / `ImageMimeType` — the extension and media-type unions.
+- `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.
+- `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.
+
+## License
+
+[MIT](LICENSE)

package/cache.d.ts

@@ -0,0 +1,257 @@
+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"]>;
+  /** The key involved. */
+  readonly key: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * An image backend read or write failed.
+ *
+ * @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.
+ *
+ * @public
+ */
+interface StoredImage {
+  readonly value: Uint8Array;
+  readonly contentType: string;
+}
+/**
+ * What {@link ImageBackendShape.set} writes.
+ *
+ * @public
+ */
+interface ImageBackendSetParams {
+  readonly key: string;
+  readonly value: Uint8Array;
+  readonly contentType?: string;
+  readonly tags?: ReadonlyArray<string>;
+}
+/**
+ * The port an image cache stores through.
+ *
+ * @remarks
+ * Failures are {@link ImageBackendError}. `@effected/store`'s `Cache` is adapted through
+ * `ImageBackend.layerFrom`, which {@link ImageBackendSource} describes structurally.
+ *
+ * @public
+ */
+interface ImageBackendShape {
+  readonly get: (key: string) => Effect.Effect<Option.Option<StoredImage>, ImageBackendError>;
+  readonly set: (params: ImageBackendSetParams) => Effect.Effect<void, ImageBackendError>;
+}
+/**
+ * Any service whose shape can stand behind the image cache.
+ *
+ * @remarks
+ * `@effected/store`'s `CacheShape` satisfies it: its `get` yields a wider `CacheEntry`, and its `set` accepts these
+ * params plus a `ttl`. Failures may be of any type; `ImageBackend.layerFrom` wraps them.
+ *
+ * @public
+ */
+interface ImageBackendSource {
+  readonly get: (key: string) => Effect.Effect<Option.Option<StoredImage>, unknown>;
+  readonly set: (params: ImageBackendSetParams) => Effect.Effect<void, unknown>;
+}
+declare const ImageBackend_base: Context.ServiceClass<ImageBackend, "@effected/images/ImageBackend", ImageBackendShape>;
+/**
+ * The storage port behind `ImageCache`.
+ *
+ * @public
+ */
+export declare class ImageBackend extends ImageBackend_base {
+  /**
+   * 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 readonly layerNone: Layer.Layer<ImageBackend>;
+  /**
+   * 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: {
+    readonly directory: string;
+  }): Layer.Layer<ImageBackend, never, FileSystem.FileSystem | Path.Path>;
+  /**
+   * 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<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"]>;
+  /** What exactly was wrong. */
+  readonly detail: Schema.String;
+  /** The schema error (`encode`) or platform error (`digest`). */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class ImageCacheKeyError extends ImageCacheKeyError_base {
+  get message(): string;
+}
+//#endregion
+//#region src/ImageCacheKey.d.ts
+/**
+ * Options for {@link ImageCacheKey.fromParams}.
+ *
+ * @public
+ */
+interface ImageCacheKeyOptions {
+  /** The generator's identity: change it when the template changes, and every old key misses. */
+  readonly salt: string;
+  /** A grouping tag the backend records (store can invalidate by it); not part of the digest. */
+  readonly namespace: string;
+}
+declare const ImageCacheKey_base: Schema.Class<ImageCacheKey, Schema.Struct<{
+  /** Lowercase hex SHA-256 of `salt`, a NUL, and the canonical JSON of the encoded params. */
+  readonly digest: Schema.String;
+  /** The salt the digest was derived with. */
+  readonly salt: Schema.String;
+  /** The grouping tag. */
+  readonly namespace: Schema.String;
+}>, {}>;
+/**
+ * The identity of one generated image: a SHA-256 digest of the salt and the schema-encoded parameters.
+ *
+ * @public
+ */
+export declare class ImageCacheKey extends ImageCacheKey_base {
+  /**
+   * 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<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"]>;
+  /** The output's format, when it was readable. */
+  readonly format: Schema.optionalKey<Schema.Literals<readonly ["png", "jpeg", "gif", "webp", "avif"]>>;
+  /** The formats the caller accepts, for `rejected-format`. */
+  readonly accept: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["png", "jpeg", "gif", "webp", "avif"]>>>;
+  /** The parse failure, for `unparseable`. */
+  readonly cause: Schema.optionalKey<Schema.Defect>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+export declare class ImageGenerateError extends ImageGenerateError_base {
+  get message(): string;
+}
+//#endregion
+//#region src/ImageCache.d.ts
+/**
+ * Options for {@link ImageCacheShape.getOrGenerate}.
+ *
+ * @public
+ */
+interface GetOrGenerateOptions<F extends Images.ImageFormat = Images.ImageFormat> {
+  /**
+   * Formats the caller will use. A stored image outside it is a miss; a generated one outside it fails. The result's
+   * `facts.format` is narrowed to these formats.
+   */
+  readonly accept?: ReadonlyArray<F>;
+}
+/**
+ * What {@link ImageCacheShape.getOrGenerate} returns.
+ *
+ * @public
+ */
+interface ImageCacheResult<F extends Images.ImageFormat = Images.ImageFormat> {
+  /** The image bytes. */
+  readonly bytes: Uint8Array;
+  /** The facts read from those bytes, with `format` narrowed to the formats the call accepted. */
+  readonly facts: Images.ImageFacts & {
+    readonly format: F;
+  };
+  /** True when the bytes came from the backend rather than the generator. */
+  readonly hit: boolean;
+}
+/**
+ * The image cache service.
+ *
+ * @public
+ */
+interface ImageCacheShape {
+  /**
+   * Return the image stored under `key`, or run `generate`, check its output, store it and return it.
+   *
+   * @remarks
+   * Stored bytes are re-read with `ImageFacts`: unreadable bytes, or a format outside `accept`, are a miss and are
+   * overwritten. Generated bytes that are empty, unreadable or outside `accept` fail with `ImageGenerateError` and are
+   * never stored. Backend failures are surfaced, never swallowed. With `accept`, the result's `facts.format` is typed
+   * as the accepted formats; without it, every `ImageFormat`. The two cases are separate overloads so a format type
+   * argument can only be given alongside the `accept` list that enforces it at run time.
+   */
+  readonly getOrGenerate: {
+    <E, R, const F extends Images.ImageFormat>(key: ImageCacheKey, generate: () => Effect.Effect<Uint8Array, E, R>, options: GetOrGenerateOptions<F> & {
+      readonly accept: ReadonlyArray<F>;
+    }): Effect.Effect<ImageCacheResult<F>, ImageGenerateError | ImageBackendError | E, R>;
+    <E, R>(key: ImageCacheKey, generate: () => Effect.Effect<Uint8Array, E, R>, options?: GetOrGenerateOptions): Effect.Effect<ImageCacheResult, ImageGenerateError | ImageBackendError | E, R>;
+  };
+}
+declare const ImageCache_base: Context.ServiceClass<ImageCache, "@effected/images/ImageCache", ImageCacheShape>;
+/**
+ * A cache for generated images, keyed by `ImageCacheKey`, stored through {@link ImageBackend}.
+ *
+ * @public
+ */
+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/cache.js

@@ -0,0 +1,8 @@
+import { ImageBackendError } from "./ImageBackendError.js";
+import { ImageBackend } from "./ImageBackend.js";
+import { ImageGenerateError } from "./ImageGenerateError.js";
+import { ImageCache } from "./ImageCache.js";
+import { ImageCacheKeyError } from "./ImageCacheKeyError.js";
+import { ImageCacheKey } from "./ImageCacheKey.js";
+
+export { ImageBackend, ImageBackendError, ImageCache, ImageCacheKey, ImageCacheKeyError, ImageGenerateError };

package/index.d.ts

@@ -0,0 +1,96 @@
+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"]>;
+  /** The format whose signature matched, when one did. */
+  readonly format: Schema.optionalKey<Schema.Literals<readonly ["png", "jpeg", "gif", "webp", "avif"]>>;
+  /** What exactly was wrong. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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
+ */
+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`.
+ *
+ * @public
+ */
+type ImageMimeType = ImageFacts["mimeType"];
+/**
+ * The conventional file extension for an image format, without the dot: `jpeg` is written `jpg`, the others keep
+ * their format name. The type of `ImageFacts#extension`.
+ *
+ * @public
+ */
+type ImageExtension = ImageFacts["extension"];
+declare const ImageFacts_base: Schema.Class<ImageFacts, Schema.Struct<{
+  /** The detected format. */
+  readonly format: Schema.Literals<readonly ["png", "jpeg", "gif", "webp", "avif"]>;
+  /** The IANA media type for `format`: one of `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`. */
+  readonly mimeType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp", "image/avif"]>;
+  /** Stored pixel width. */
+  readonly width: Schema.Int;
+  /** Stored pixel height. */
+  readonly height: Schema.Int;
+}>, {}>;
+/**
+ * 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
+ */
+export declare class ImageFacts extends ImageFacts_base {
+  /**
+   * 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(): "png" | "jpg" | "gif" | "webp" | "avif";
+  /**
+   * 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: Uint8Array): Result.Result<ImageFacts, ImageParseError>;
+  /**
+   * Read facts from an image's bytes — {@link ImageFacts.fromBytesResult} with a span.
+   */
+  static readonly fromBytes: (bytes: Uint8Array) => Effect.Effect<ImageFacts, ImageParseError>;
+}
+//#endregion
+//#region src/ImageFormat.d.ts
+/**
+ * The image formats `@effected/images` reads.
+ *
+ * @public
+ */
+export declare const ImageFormat: Schema.Literals<readonly ["png", "jpeg", "gif", "webp", "avif"]>;
+/**
+ * One of the image formats `@effected/images` reads.
+ *
+ * @public
+ */
+export type ImageFormat = typeof ImageFormat.Type;
+//#endregion
+export type { ImageExtension, ImageMimeType };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,5 @@
+import { ImageFormat } from "./ImageFormat.js";
+import { ImageParseError } from "./ImageParseError.js";
+import { ImageFacts } from "./ImageFacts.js";
+
+export { ImageFacts, ImageFormat, ImageParseError };

package/internal/avif.js

@@ -0,0 +1,95 @@
+import { ascii, u32be } from "./bytes.js";
+import { dimensions, malformed, truncated } from "./result.js";
+import { Result } from "effect";
+
+//#region 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. */
+const MAX_BRANDS = 64;
+/** True when an ftyp box at offset 0 names `avif` or `avis` as its major or a compatible brand. */
+const isAvifBrand = (b) => {
+	if (b.length < 12 || ascii(b, 4, 4) !== "ftyp") return false;
+	const brand = (o) => ascii(b, o, 4);
+	if (brand(8) === "avif" || brand(8) === "avis") return true;
+	const end = Math.min(u32be(b, 0), b.length);
+	for (let o = 16, n = 0; o + 4 <= end && n < MAX_BRANDS; o += 4, n++) if (brand(o) === "avif" || brand(o) === "avis") return true;
+	return false;
+};
+/**
+* Only a top-level box can be cut short by the end of the bytes: below it the parent has already been
+* verified to end inside the buffer, so more bytes could never complete a child that overruns it.
+*/
+const readBox = (b, offset, parentEnd, topLevel) => {
+	const short = topLevel ? truncated : malformed;
+	if (offset + 8 > b.length) return short("ended inside a box header");
+	let size = u32be(b, offset);
+	const type = ascii(b, offset + 4, 4);
+	let header = 8;
+	if (size === 1) {
+		if (offset + 16 > b.length) return short("ended inside a largesize header");
+		if (u32be(b, offset + 8) !== 0) return malformed(`box ${JSON.stringify(type)} largesize exceeds 32 bits`);
+		size = u32be(b, offset + 12);
+		header = 16;
+	} else if (size === 0) size = parentEnd - offset;
+	if (size < header) return malformed(`box ${JSON.stringify(type)} size ${size} is below its header`);
+	const end = offset + size;
+	if (topLevel && end > b.length) return truncated(`box ${JSON.stringify(type)} runs past the end of the bytes`);
+	if (end > parentEnd) return malformed(`box ${JSON.stringify(type)} overruns its parent`);
+	return Result.succeed({
+		type,
+		start: offset + header,
+		end
+	});
+};
+/** Every child box of [start, end), stopping early on failure. */
+const children = (b, start, end, budget) => {
+	const out = [];
+	for (let offset = start; offset < end;) {
+		if (--budget.remaining < 0) return malformed("box walk exceeded its budget");
+		const box = readBox(b, offset, end, false);
+		if (Result.isFailure(box)) return Result.fail(box.failure);
+		out.push(box.success);
+		offset = box.success.end;
+	}
+	return Result.succeed(out);
+};
+/** Find the first child of type `type`; at top level its absence means the bytes ended early. */
+const child = (b, start, end, type, budget, topLevel) => {
+	for (let offset = start; offset < end;) {
+		if (--budget.remaining < 0) return malformed("box walk exceeded its budget");
+		const box = readBox(b, offset, end, topLevel);
+		if (Result.isFailure(box)) return Result.fail(box.failure);
+		if (box.success.type === type) return box;
+		offset = box.success.end;
+	}
+	return topLevel ? truncated(`ended before the ${type} box`) : malformed(`no ${type} box`);
+};
+const readAvif = (b) => {
+	const budget = { remaining: AVIF_BOX_BUDGET };
+	const meta = child(b, 0, b.length, "meta", budget, true);
+	if (Result.isFailure(meta)) return Result.fail(meta.failure);
+	const metaChildren = meta.success.start + 4;
+	if (metaChildren > meta.success.end) return malformed("meta box is too short for its version and flags");
+	const iprp = child(b, metaChildren, meta.success.end, "iprp", budget, false);
+	if (Result.isFailure(iprp)) return Result.fail(iprp.failure);
+	const ipco = child(b, iprp.success.start, iprp.success.end, "ipco", budget, false);
+	if (Result.isFailure(ipco)) return Result.fail(ipco.failure);
+	const properties = children(b, ipco.success.start, ipco.success.end, budget);
+	if (Result.isFailure(properties)) return Result.fail(properties.failure);
+	let best;
+	for (const property of properties.success) {
+		if (property.type !== "ispe") continue;
+		if (property.end - property.start < 12) return malformed("ispe box is too short");
+		const width = u32be(b, property.start + 4);
+		const height = u32be(b, property.start + 8);
+		if (best === void 0 || width * height > best.width * best.height) best = {
+			width,
+			height
+		};
+	}
+	return best === void 0 ? malformed("no ispe property") : dimensions(best.width, best.height);
+};
+
+//#endregion
+export { AVIF_BOX_BUDGET, isAvifBrand, readAvif };

package/internal/bytes.js

@@ -0,0 +1,14 @@
+//#region 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;
+const u32be = (b, o) => b[o] * 16777216 + (b[o + 1] << 16 | b[o + 2] << 8 | b[o + 3]);
+const ascii = (b, o, length) => {
+	let out = "";
+	for (let i = 0; i < length; i++) out += String.fromCharCode(b[o + i]);
+	return out;
+};
+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 };