@stacksjs/image 0.70.163

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 Open Web Foundation
+
+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.

package/README.md

@@ -0,0 +1,74 @@
+# @stacksjs/image
+
+Native responsive image generation for Stacks, powered by `ts-images`.
+
+## Generate responsive images
+
+```ts
+import { image } from '@stacksjs/image'
+
+const manifest = await image('uploads/hero.jpg', {
+  root: process.cwd(),
+  outputDir: 'public/media/images',
+  publicPath: '/media/images',
+})
+  .preset('hero')
+  .formats(['avif', 'webp', 'jpeg'])
+  .quality(82)
+  .generate()
+```
+
+Presets cover `avatar`, `content`, `hero`, and `thumbnail`. Custom transforms can use `.widths()`, `.height()`, `.aspectRatio()`, `.fit()`, and `.position()`. Source-sized output is included where appropriate, and generation never upscales unless `upscale: true` is explicit.
+
+## S3-compatible storage and CloudFront
+
+Pass any structural storage adapter. The adapter can wrap Stacks storage, S3, R2, B2, or another S3-compatible provider.
+
+```ts
+const manifest = await image('uploads/avatar.png', {
+  authorize: (_path, request) => request.user.can('view-media'),
+  authorizationContext: request,
+})
+  .preset('avatar')
+  .storage({
+    fileExists: key => disk.exists(key),
+    write: async (key, contents) => {
+      await disk.put(key, contents)
+      return { size: contents.byteLength }
+    },
+    stat: async key => ({ size: (await disk.stat(key)).size }),
+    publicUrl: key => disk.url(key),
+  })
+  .generate()
+```
+
+The returned filenames are content-addressed and safe for an immutable CloudFront behavior. Use a short-lived signed transform for private originals:
+
+```ts
+import { signImageTransform, verifyImageTransform } from '@stacksjs/image'
+
+const expires = Math.floor(Date.now() / 1000) + 300
+const signature = signImageTransform('/private/hero.jpg?w=1280&format=avif', expires, secret)
+
+if (!verifyImageTransform(requestPath, expires, signature, secret))
+  throw new Response('Forbidden', { status: 403 })
+```
+
+## STX component and art direction
+
+```stx
+<Image
+  src="{{ fallback.url }}"
+  alt="A product on a workbench"
+  width="{{ fallback.width }}"
+  height="{{ fallback.height }}"
+  :sources="[
+    { media: '(min-width: 960px)', type: 'image/avif', srcset: desktopAvif },
+    { media: '(max-width: 959px)', type: 'image/webp', srcset: mobileWebp },
+  ]"
+  sizes="(max-width: 959px) 100vw, 50vw"
+  priority
+/>
+```
+
+Use `decorative` instead of empty alt text for decorative images. The component renders responsive, layout-stable HTML without requiring client JavaScript.

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+import { stat } from 'node:fs/promises';
+import type { ResizeFit } from 'ts-images';
+export declare function resolveImageSource(source: string, root?: string): string;
+export declare function image(source: string, options?: ImageOptions): ImageBuilder;
+export declare function negotiateImageVariant(variants: readonly ImageVariant[], accept?: string, width?: number): ImageVariant | undefined;
+export declare function imageResponseHeaders(variant: ImageVariant): Record<string, string>;
+export declare function signImageTransform(path: string, expires: number, secret: string): string;
+export declare function verifyImageTransform(path: string, expires: number, signature: string, secret: string, now?: number): boolean;
+export declare interface ImageVariant { width: number, height: number, bytes: number, format: ImageFormat, mimeType: string, path: string, url: string, cacheKey: string }
+export declare interface ImageManifest { source: { width: number, height: number, hash: string }, variants: ImageVariant[], placeholder: string }
+export declare interface ImageStorageAdapter { fileExists: (_path: string) => Promise<boolean>, write: (_path: string, _contents: Uint8Array) => Promise<{ size: number }>, stat: (_path: string) => Promise<{ size: number }>, publicUrl: (_path: string) => Promise<string> }
+export declare interface ImageOptions { root?: string, outputDir?: string, publicPath?: string, concurrency?: number, upscale?: boolean, authorize?: (_source: string, _context?: unknown) => boolean | Promise<boolean>, authorizationContext?: unknown }
+export type ImageFormat = 'avif' | 'webp' | 'jpeg' | 'png';
+export type ImagePreset = 'avatar' | 'content' | 'hero' | 'thumbnail';
+export declare class ImageBuilder {
+  constructor(source: string, options?: ImageOptions);
+  widths(widths: number[]): this;
+  formats(formats: ImageFormat[]): this;
+  fit(fit: ResizeFit): this;
+  height(value: number): this;
+  aspectRatio(value: number): this;
+  position(value: typeof this.targetPosition): this;
+  preset(value: ImagePreset): this;
+  quality(value: number): this;
+  output(dir: string, publicPath?: string): this;
+  storage(adapter: ImageStorageAdapter, prefix?: string): this;
+  generate(): Promise<ImageManifest>;
+}

package/dist/index.js

@@ -0,0 +1,165 @@
+import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import { mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { basename, extname, isAbsolute, relative, resolve } from "node:path";
+import { decode, encode, imageToSplatHash, resize } from "ts-images";
+const mime = { avif: "image/avif", webp: "image/webp", jpeg: "image/jpeg", png: "image/png" };
+function integer(name, value, min, max) {
+  if (!Number.isInteger(value) || value < min || value > max)
+    throw TypeError(`${name} must be between ${min} and ${max}`);
+}
+export function resolveImageSource(source, root = process.cwd()) {
+  const allowed = resolve(root), candidate = isAbsolute(source) ? resolve(source) : resolve(allowed, source), relation = relative(allowed, candidate);
+  if (source.includes("\x00") || relation === ".." || relation.startsWith("../") || isAbsolute(relation))
+    throw Error("Image source must stay inside the configured root");
+  return candidate;
+}
+
+export class ImageBuilder {
+  source;
+  targetWidths = [480, 768, 1280, 1920];
+  targetFormats = ["avif", "webp", "jpeg"];
+  targetFit = "inside";
+  targetHeight;
+  targetAspectRatio;
+  targetPosition = "center";
+  includeOriginal = !0;
+  targetStorage;
+  targetQuality = 82;
+  options;
+  constructor(source, options = {}) {
+    this.source = source;
+    this.options = { ...options, root: options.root ?? process.cwd(), outputDir: options.outputDir ?? resolve("public/media/images"), publicPath: options.publicPath ?? "/media/images", concurrency: options.concurrency ?? 4, upscale: options.upscale ?? !1 };
+  }
+  widths(widths) {
+    if (!widths.length)
+      throw TypeError("Image widths are required");
+    widths.forEach((value) => integer("Image width", value, 1, 16384));
+    this.targetWidths = [...new Set(widths)].sort((a, b) => a - b);
+    return this;
+  }
+  formats(formats) {
+    if (!formats.length)
+      throw TypeError("Image formats are required");
+    this.targetFormats = [...new Set(formats)];
+    return this;
+  }
+  fit(fit) {
+    this.targetFit = fit;
+    return this;
+  }
+  height(value) {
+    integer("Image height", value, 1, 16384);
+    this.targetHeight = value;
+    this.targetAspectRatio = void 0;
+    return this;
+  }
+  aspectRatio(value) {
+    if (!Number.isFinite(value) || value <= 0 || value > 100)
+      throw TypeError("Image aspect ratio must be between 0 and 100");
+    this.targetAspectRatio = value;
+    this.targetHeight = void 0;
+    return this;
+  }
+  position(value) {
+    this.targetPosition = value;
+    return this;
+  }
+  preset(value) {
+    const preset = { avatar: { widths: [64, 128, 256, 512], ratio: 1, fit: "cover", original: !1 }, content: { widths: [320, 640, 960, 1280, 1920], fit: "inside", original: !0 }, hero: { widths: [640, 1280, 1920, 2560], ratio: 1.7777777777777777, fit: "cover", original: !0 }, thumbnail: { widths: [160, 320, 640], ratio: 1.7777777777777777, fit: "cover", original: !1 } }[value];
+    this.targetWidths = [...preset.widths];
+    this.targetFit = preset.fit;
+    this.targetAspectRatio = "ratio" in preset ? preset.ratio : void 0;
+    this.targetHeight = void 0;
+    this.includeOriginal = preset.original;
+    return this;
+  }
+  quality(value) {
+    integer("Image quality", value, 1, 100);
+    this.targetQuality = value;
+    return this;
+  }
+  output(dir, publicPath = "/media/images") {
+    this.options.outputDir = resolve(dir);
+    this.options.publicPath = `/${publicPath.replace(/^\/+|\/+$/g, "")}`;
+    return this;
+  }
+  storage(adapter, prefix = "media/images") {
+    this.targetStorage = { adapter, prefix: prefix.replace(/^\/+|\/+$/g, "") };
+    return this;
+  }
+  async generate() {
+    integer("Image concurrency", this.options.concurrency, 1, 32);
+    const sourcePath = resolveImageSource(this.source, this.options.root);
+    if (this.options.authorize && !await this.options.authorize(sourcePath, this.options.authorizationContext))
+      throw Error("Image delivery is not authorized");
+    const bytes = new Uint8Array(await readFile(sourcePath)), hash = createHash("sha256").update(bytes).digest("hex"), decoded = await decode(bytes), widths = this.targetWidths.filter((width) => this.options.upscale || width <= decoded.width);
+    if (this.includeOriginal && !widths.includes(decoded.width))
+      widths.push(decoded.width);
+    const tasks = [...new Set(widths)].sort((a, b) => a - b).flatMap((width) => this.targetFormats.map((format) => ({ width, format }))), variants = [];
+    let cursor = 0;
+    await Promise.all(Array.from({ length: Math.min(tasks.length, this.options.concurrency) }, async () => {
+      while (cursor < tasks.length) {
+        const task = tasks[cursor++];
+        variants.push(await this.variant(decoded, hash, sourcePath, task.width, task.format));
+      }
+    }));
+    variants.sort((a, b) => a.width - b.width || this.targetFormats.indexOf(a.format) - this.targetFormats.indexOf(b.format));
+    return { source: { width: decoded.width, height: decoded.height, hash }, variants, placeholder: Buffer.from(imageToSplatHash(decoded)).toString("base64url") };
+  }
+  async variant(source, hash, sourcePath, width, format) {
+    const height = this.targetHeight ?? (this.targetAspectRatio ? Math.max(1, Math.round(width / this.targetAspectRatio)) : void 0), output = width === source.width && height === void 0 ? source : resize(source, { width, height, fit: this.targetFit, position: this.targetPosition });
+    if (!this.options.upscale && (output.width > source.width || output.height > source.height))
+      throw TypeError(`Image variant ${output.width}x${output.height} would upscale the source`);
+    const cacheKey = createHash("sha256").update(`${hash}:${width}:${height ?? "auto"}:${format}:${this.targetFit}:${this.targetPosition}:${this.targetQuality}`).digest("hex"), filename = `${basename(sourcePath, extname(sourcePath)).replace(/[^a-zA-Z0-9_-]/g, "-") || "image"}-${output.width}x${output.height}-${cacheKey.slice(0, 16)}.${format === "jpeg" ? "jpg" : format}`, path = resolve(this.options.outputDir, filename);
+    if (this.targetStorage) {
+      const key = this.targetStorage.prefix ? `${this.targetStorage.prefix}/${filename}` : filename;
+      if (await this.targetStorage.adapter.fileExists(key)) {
+        const existing = await this.targetStorage.adapter.stat(key);
+        return { width: output.width, height: output.height, bytes: existing.size, format, mimeType: mime[format], path: key, url: await this.targetStorage.adapter.publicUrl(key), cacheKey };
+      }
+      const encoded = await encode(output, format, { quality: this.targetQuality, progressive: !0 }), written = await this.targetStorage.adapter.write(key, encoded);
+      return { width: output.width, height: output.height, bytes: written.size, format, mimeType: mime[format], path: key, url: await this.targetStorage.adapter.publicUrl(key), cacheKey };
+    }
+    const existing = await stat(path).catch(() => null);
+    if (existing)
+      return { width: output.width, height: output.height, bytes: existing.size, format, mimeType: mime[format], path, url: `${this.options.publicPath}/${filename}`, cacheKey };
+    const encoded = await encode(output, format, { quality: this.targetQuality, progressive: !0 });
+    await mkdir(this.options.outputDir, { recursive: !0 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temporary, encoded);
+    await rename(temporary, path);
+    return { width: output.width, height: output.height, bytes: encoded.byteLength, format, mimeType: mime[format], path, url: `${this.options.publicPath}/${filename}`, cacheKey };
+  }
+}
+export function image(source, options = {}) {
+  return new ImageBuilder(source, options);
+}
+function accepted(accept, mimeType) {
+  const [type, subtype] = mimeType.split("/");
+  let best = 0;
+  for (const item of accept.split(",")) {
+    const [range = "*/*", ...params] = item.trim().toLowerCase().split(";").map((value) => value.trim()), [acceptedType, acceptedSubtype] = range.split("/");
+    if (acceptedType !== "*" && acceptedType !== type || acceptedSubtype !== "*" && acceptedSubtype !== subtype)
+      continue;
+    const raw = params.find((param) => param.startsWith("q="));
+    best = Math.max(best, raw ? Number.parseFloat(raw.slice(2)) || 0 : 1);
+  }
+  return best;
+}
+export function negotiateImageVariant(variants, accept = "*/*", width) {
+  const widths = [...new Set(variants.map((item) => item.width))].sort((a, b) => a - b), target = width === void 0 ? widths.at(-1) : widths.find((value) => value >= width) ?? widths.at(-1);
+  return variants.filter((item) => item.width === target).map((variant, index) => ({ variant, index, q: accepted(accept || "*/*", variant.mimeType) })).filter((item) => item.q > 0).sort((a, b) => b.q - a.q || a.index - b.index)[0]?.variant;
+}
+export function imageResponseHeaders(variant) {
+  return { "Content-Type": variant.mimeType, "Content-Length": String(variant.bytes), "Cache-Control": "public, max-age=31536000, immutable", ETag: `"${variant.cacheKey}"`, Vary: "Accept", "X-Image-Width": String(variant.width), "X-Image-Height": String(variant.height) };
+}
+export function signImageTransform(path, expires, secret) {
+  return createHmac("sha256", secret).update(`${path}
+${expires}`).digest("base64url");
+}
+export function verifyImageTransform(path, expires, signature, secret, now = Date.now()) {
+  if (!Number.isInteger(expires) || expires * 1000 <= now)
+    return !1;
+  const expected = Buffer.from(signImageTransform(path, expires, secret)), actual = Buffer.from(signature);
+  return expected.length === actual.length && timingSafeEqual(expected, actual);
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@stacksjs/image",
+  "type": "module",
+  "sideEffects": false,
+  "version": "0.70.163",
+  "description": "Native responsive image delivery for Stacks.",
+  "author": "Chris Breuer",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/chrisbbreuer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stacksjs/stacks.git",
+    "directory": "./storage/framework/core/image"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build.ts",
+    "typecheck": "bun tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "ts-images": "^0.2.1"
+  },
+  "devDependencies": {
+    "better-dx": "^0.2.17"
+  }
+}