@effected/images 0.0.0-stage → 0.1.1

package/internal/canonical.js

@@ -0,0 +1,48 @@
+import { Result } from "effect";
+
+//#region src/internal/canonical.ts
+const MAX_DEPTH = 256;
+const isPlainObject = (value) => {
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+};
+const encode = (value, depth) => {
+	if (depth > MAX_DEPTH) return Result.fail(`nesting deeper than ${MAX_DEPTH}`);
+	if (value === null || typeof value === "boolean" || typeof value === "string") return Result.succeed(JSON.stringify(value));
+	if (typeof value === "number") return Number.isFinite(value) ? Result.succeed(JSON.stringify(value)) : Result.fail(`non-finite number ${value}`);
+	if (Array.isArray(value)) {
+		const parts = [];
+		for (const item of value) {
+			if (item === void 0) return Result.fail("undefined array element");
+			const part = encode(item, depth + 1);
+			if (Result.isFailure(part)) return part;
+			parts.push(part.success);
+		}
+		return Result.succeed(`[${parts.join(",")}]`);
+	}
+	if (typeof value === "object" && isPlainObject(value)) {
+		const parts = [];
+		for (const key of Object.keys(value).sort()) {
+			const member = value[key];
+			if (member === void 0) continue;
+			const part = encode(member, depth + 1);
+			if (Result.isFailure(part)) return part;
+			parts.push(`${JSON.stringify(key)}:${part.success}`);
+		}
+		return Result.succeed(`{${parts.join(",")}}`);
+	}
+	const kind = typeof value === "object" ? value.constructor?.name ?? "object" : typeof value;
+	return Result.fail(`value of type ${kind} is not JSON data`);
+};
+/**
+* Canonical JSON: recursively sorted keys, no whitespace, undefined members omitted; non-JSON values refused.
+*
+* Core has no canonical serializer, and `@effected/schemastore`'s `CanonicalJson` is a file formatter that keeps
+* insertion order, so this one is the package's own.
+*
+* @internal
+*/
+const canonicalJson = (value) => encode(value, 0);
+
+//#endregion
+export { canonicalJson };

package/internal/detect.js

@@ -0,0 +1,31 @@
+import { ascii, matches } from "./bytes.js";
+import { isAvifBrand } from "./avif.js";
+
+//#region src/internal/detect.ts
+const PNG = [
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+];
+const JPEG = [
+	255,
+	216,
+	255
+];
+/** The format whose signature `bytes` starts with, or undefined. A partial signature is no match. */
+const detectFormat = (b) => {
+	if (matches(b, 0, PNG)) return "png";
+	if (matches(b, 0, JPEG)) return "jpeg";
+	const gif = b.length >= 6 ? ascii(b, 0, 6) : "";
+	if (gif === "GIF87a" || gif === "GIF89a") return "gif";
+	if (b.length >= 12 && ascii(b, 0, 4) === "RIFF" && ascii(b, 8, 4) === "WEBP") return "webp";
+	if (isAvifBrand(b)) return "avif";
+};
+
+//#endregion
+export { detectFormat };

package/internal/digest.js

@@ -0,0 +1,6 @@
+//#region 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

@@ -0,0 +1,9 @@
+import { u16le } from "./bytes.js";
+import { dimensions, truncated } from "./result.js";
+
+//#region 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

@@ -0,0 +1,41 @@
+import { u16be } from "./bytes.js";
+import { dimensions, malformed, truncated } from "./result.js";
+
+//#region 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). */
+const isFrameHeader = (marker) => marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204;
+/** Markers that carry no length field. */
+const isStandalone = (marker) => marker === 1 || marker === 216 || marker >= 208 && marker <= 215;
+const readJpeg = (b) => {
+	let offset = 2;
+	let steps = 0;
+	for (;;) {
+		if (++steps > 4096) return malformed("segment walk exceeded its step budget");
+		if (offset >= b.length) return truncated("ended before a frame header");
+		if (b[offset] !== 255) return malformed(`expected a marker at offset ${offset}`);
+		let at = offset + 1;
+		while (at < b.length && b[at] === 255) {
+			at++;
+			if (++steps > 4096) return malformed("segment walk exceeded its step budget");
+		}
+		if (at >= b.length) return truncated("ended inside a marker");
+		const marker = b[at];
+		offset = at + 1;
+		if (isStandalone(marker)) continue;
+		if (marker === 217 || marker === 218) return malformed("reached end of image or a scan before any frame header");
+		if (offset + 2 > b.length) return truncated("ended inside a segment length");
+		const length = u16be(b, offset);
+		if (length < 2) return malformed(`segment length ${length} is below 2`);
+		if (isFrameHeader(marker)) {
+			if (length < 11) return malformed(`frame header length ${length} is below 11`);
+			if (offset + 7 > b.length) return truncated("ended inside the frame header");
+			return dimensions(u16be(b, offset + 5), u16be(b, offset + 3));
+		}
+		offset += length;
+	}
+};
+
+//#endregion
+export { JPEG_STEP_BUDGET, readJpeg };

package/internal/png.js

@@ -0,0 +1,15 @@
+import { ascii, u32be } from "./bytes.js";
+import { dimensions, malformed, truncated } from "./result.js";
+
+//#region 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}`);
+	if (ascii(b, 12, 4) !== "IHDR") return malformed("first chunk is not IHDR");
+	const length = u32be(b, 8);
+	if (length !== 13) return malformed(`IHDR length ${length} is not 13`);
+	return dimensions(u32be(b, 16), u32be(b, 20));
+};
+
+//#endregion
+export { readPng };

package/internal/result.js

@@ -0,0 +1,21 @@
+import { Result } from "effect";
+
+//#region src/internal/result.ts
+const MAX_DIMENSION = 2147483647;
+const truncated = (detail) => Result.fail({
+	reason: "truncated",
+	detail
+});
+const malformed = (detail) => Result.fail({
+	reason: "malformed",
+	detail
+});
+const legal = (n) => Number.isInteger(n) && n >= 1 && n <= 2147483647;
+/** Succeed with the pair, or fail `malformed` when either side is out of range. */
+const dimensions = (width, height) => legal(width) && legal(height) ? Result.succeed({
+	width,
+	height
+}) : malformed(`dimensions ${width}x${height} out of range 1..${MAX_DIMENSION}`);
+
+//#endregion
+export { MAX_DIMENSION, dimensions, malformed, truncated };

package/internal/webp.js

@@ -0,0 +1,33 @@
+import { ascii, u16le, u24le } from "./bytes.js";
+import { dimensions, malformed, truncated } from "./result.js";
+
+//#region src/internal/webp.ts
+const PAYLOAD = 20;
+const readWebp = (b) => {
+	if (b.length < 16) return truncated("need the first chunk's fourcc");
+	const fourcc = ascii(b, 12, 4);
+	switch (fourcc) {
+		case "VP8 ":
+			if (b.length < 30) return truncated("need the VP8 frame header");
+			if (b[23] !== 157 || b[24] !== 1 || b[25] !== 42) return malformed("VP8 start code is not 9D 01 2A");
+			return dimensions(u16le(b, 26) & 16383, u16le(b, 28) & 16383);
+		case "VP8L": {
+			if (b.length < 25) return truncated("need the VP8L header");
+			if (b[PAYLOAD] !== 47) return malformed("VP8L signature byte is not 0x2F");
+			const b1 = b[21];
+			const b2 = b[22];
+			const b3 = b[23];
+			const b4 = b[24];
+			const width = 1 + ((b2 & 63) << 8 | b1);
+			const height = 1 + ((b4 & 15) << 10 | b3 << 2 | (b2 & 192) >> 6);
+			return dimensions(width, height);
+		}
+		case "VP8X":
+			if (b.length < 30) return truncated("need the VP8X canvas size");
+			return dimensions(1 + u24le(b, 24), 1 + u24le(b, 27));
+		default: return malformed(`unknown first WebP chunk ${JSON.stringify(fourcc)}`);
+	}
+};
+
+//#endregion
+export { readWebp };

package/package.json

@@ -1,6 +1,53 @@
 {
-  "name": "@effected/images",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/images",
+	"version": "0.1.1",
+	"private": false,
+	"description": "Image facts (format, MIME type, dimensions) from bytes, and a generated-image cache, for Effect.",
+	"keywords": [
+		"image",
+		"dimensions",
+		"png",
+		"jpeg",
+		"webp",
+		"avif",
+		"cache",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/images#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/images"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./cache": {
+			"types": "./cache.d.ts",
+			"import": "./cache.js",
+			"default": "./cache.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"effect": "^4.0.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.1"
+    }
+  ]
+}