@basaltkit/image-sharp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Basalt Contributors
+
+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,75 @@
+# @basaltkit/image-sharp
+
+**Image processing engine** for [`@basaltkit/storage`](https://www.npmjs.com/package/@basaltkit/storage), backed by [sharp](https://sharp.pixelplumbing.com). It implements the storage `ImageProcessor` contract so `disk.image(...)` can resize, rotate, and re-encode to WebP/AVIF/JPEG/PNG.
+
+You need this module only when you actually process images. The core `@basaltkit/storage` ships the fluent pipeline and the contract, but **no native dependency** — the heavy `sharp`/`libvips` binary lives here, as an opt-in satellite (see the framework's ARCHITECTURE §9.1).
+
+## Installation
+
+```bash
+pnpm add @basaltkit/image-sharp sharp
+```
+
+`sharp` is a **peer dependency** (it carries the native `libvips` binary). It's loaded lazily on first use, so a missing install fails fast with a clear message instead of at import time.
+
+## Usage
+
+Wire the engine once, then use `disk.image(...)` anywhere:
+
+```ts
+import { storagePlugin } from '@basaltkit/storage'
+import { SharpImageProcessor } from '@basaltkit/image-sharp'
+
+storagePlugin({
+  imageProcessor: new SharpImageProcessor(),
+  disks: { uploads: { driver: 'local', root: './storage' } },
+})
+```
+
+```ts
+// resize + re-encode + write back to the disk (tenant scope + key guard apply)
+await storage.disk('uploads')
+  .image('avatars/1.png')
+  .resize(256, 256, { fit: 'cover' })
+  .webp(80)
+  .save('avatars/1.webp')
+
+// or just get the bytes
+const thumb = await storage.disk('uploads').image('hero.jpg').resize(320).jpeg().toBuffer()
+
+// read dimensions without re-encoding
+const { width, height, format } = await storage.disk('uploads').image('hero.jpg').metadata()
+```
+
+Do heavy work inside a `@basaltkit/queue` job so it never blocks the request.
+
+## Pipeline operations
+
+| Method | sharp call | Notes |
+|---|---|---|
+| `.resize(width?, height?, { fit?, position? })` | `resize()` | Omit a dimension to scale by aspect ratio |
+| `.rotate(degrees?)` | `rotate()` | No argument → auto-orient from EXIF |
+| `.blur(sigma?)` | `blur()` | |
+| `.grayscale()` / `.flip()` / `.flop()` | same | |
+| `.webp(q?)` `.jpeg(q?)` `.png(q?)` `.avif(q?)` | encoder | Sets the output format (+ quality) |
+| `.format(fmt, q?)` | encoder | Dynamic form of the above |
+
+Terminals: `.toBuffer()`, `.save(path, options?)`, `.metadata()`.
+
+## API
+
+### `class SharpImageProcessor`
+
+`new SharpImageProcessor({ sharp? })` — implements `ImageProcessor` from `@basaltkit/storage`. Pass a `sharp` factory to inject a fake in tests; by default the real `sharp` is lazy-loaded.
+
+### `applyOps(image, ops)`
+
+The pure op-list → sharp-call translator, exported for testing and advanced embedding.
+
+## How it connects
+
+`@basaltkit/storage` owns `disk.image(...)`, the fluent `ImagePipeline`, and the `ImageProcessor` interface. This package is one implementation of that interface — swap it for another engine without touching app code.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { ImageProcessor, ImageOp, ImageMetadata } from '@basaltkit/storage';
+
+/**
+ * The slice of sharp's fluent API this driver uses. Declared structurally so the
+ * op translator is testable with a fake and the core never imports sharp's types.
+ */
+interface SharpLike {
+    resize(options: {
+        width?: number;
+        height?: number;
+        fit?: string;
+        position?: string;
+    }): SharpLike;
+    rotate(degrees?: number): SharpLike;
+    blur(sigma?: number): SharpLike;
+    grayscale(): SharpLike;
+    flip(): SharpLike;
+    flop(): SharpLike;
+    jpeg(options?: {
+        quality?: number;
+    }): SharpLike;
+    png(options?: {
+        quality?: number;
+    }): SharpLike;
+    webp(options?: {
+        quality?: number;
+    }): SharpLike;
+    avif(options?: {
+        quality?: number;
+    }): SharpLike;
+    toBuffer(): Promise<Buffer>;
+    metadata(): Promise<{
+        format?: string;
+        width?: number;
+        height?: number;
+        size?: number;
+    }>;
+}
+/** `sharp(input)` — the module's callable default export. */
+type SharpFactory = (input: Buffer) => SharpLike;
+/**
+ * Applies the engine-neutral op list to a sharp instance, in order. Pure and
+ * synchronous over the chainable — unit-tested without the native binary.
+ */
+declare function applyOps(image: SharpLike, ops: readonly ImageOp[]): SharpLike;
+interface SharpImageProcessorOptions {
+    /**
+     * Injectable sharp factory — the real `sharp` by default (lazy-loaded). Tests
+     * pass a fake so no native binary is required.
+     */
+    sharp?: SharpFactory;
+}
+/**
+ * A {@link ImageProcessor} backed by [sharp](https://sharp.pixelplumbing.com).
+ * Wire it into storage: `storagePlugin({ imageProcessor: new SharpImageProcessor(), ... })`.
+ * `sharp` is a **peer dependency** (native `libvips`), loaded on first use so the
+ * app fails fast with a clear message if it isn't installed.
+ */
+declare class SharpImageProcessor implements ImageProcessor {
+    readonly name = "sharp";
+    private factory;
+    constructor(options?: SharpImageProcessorOptions);
+    run(input: Buffer, ops: ImageOp[]): Promise<Buffer>;
+    metadata(input: Buffer): Promise<ImageMetadata>;
+    private load;
+}
+
+export { type SharpFactory, SharpImageProcessor, type SharpImageProcessorOptions, type SharpLike, applyOps };

package/dist/index.js

@@ -0,0 +1,74 @@
+// src/index.ts
+function applyOps(image, ops) {
+  let out = image;
+  for (const op of ops) {
+    switch (op.op) {
+      case "resize":
+        out = out.resize({
+          ...op.width !== void 0 ? { width: op.width } : {},
+          ...op.height !== void 0 ? { height: op.height } : {},
+          ...op.fit ? { fit: op.fit } : {},
+          ...op.position ? { position: op.position } : {}
+        });
+        break;
+      case "rotate":
+        out = op.degrees === void 0 ? out.rotate() : out.rotate(op.degrees);
+        break;
+      case "blur":
+        out = op.sigma === void 0 ? out.blur() : out.blur(op.sigma);
+        break;
+      case "grayscale":
+        out = out.grayscale();
+        break;
+      case "flip":
+        out = out.flip();
+        break;
+      case "flop":
+        out = out.flop();
+        break;
+      case "format":
+        out = out[op.format](op.quality === void 0 ? {} : { quality: op.quality });
+        break;
+    }
+  }
+  return out;
+}
+var SharpImageProcessor = class {
+  name = "sharp";
+  factory;
+  constructor(options = {}) {
+    this.factory = options.sharp;
+  }
+  async run(input, ops) {
+    const sharp = await this.load();
+    return applyOps(sharp(input), ops).toBuffer();
+  }
+  async metadata(input) {
+    const sharp = await this.load();
+    const m = await sharp(input).metadata();
+    return {
+      ...m.format ? { format: m.format } : {},
+      ...m.width !== void 0 ? { width: m.width } : {},
+      ...m.height !== void 0 ? { height: m.height } : {},
+      ...m.size !== void 0 ? { size: m.size } : {}
+    };
+  }
+  async load() {
+    if (this.factory) return this.factory;
+    try {
+      const specifier = "sharp";
+      const mod = await import(specifier);
+      const factory = typeof mod === "function" ? mod : mod.default ?? mod;
+      this.factory = factory;
+      return factory;
+    } catch {
+      throw new Error(
+        "@basaltkit/image-sharp requires the 'sharp' peer dependency. Install it with `pnpm add sharp`."
+      );
+    }
+  }
+};
+export {
+  SharpImageProcessor,
+  applyOps
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@basaltkit/image-sharp",
+  "version": "1.0.0",
+  "description": "sharp-backed image processor for @basaltkit/storage — resize/rotate/blur and JPEG/PNG/WebP/AVIF encoding behind the engine-neutral ImageProcessor contract.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/storage": "^1.2.0"
+  },
+  "peerDependencies": {
+    "sharp": "^0.33.0 || ^0.34.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/image-sharp"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/image-sharp#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "image",
+    "sharp",
+    "resize",
+    "webp",
+    "avif"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}