@thi.ng/imago 1.2.4 → 1.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-07-21T08:21:58Z
+- **Last updated**: 2025-07-25T00:04:12Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,20 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [1.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@1.4.0) (2025-07-25)
+
+#### 🚀 Features
+
+- add support for absolute output paths ([c440e25](https://github.com/thi-ng/umbrella/commit/c440e25))
+  - update `formatPath()` to always return abs path
+  - simplify `outputProc()` path handling
+
+## [1.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@1.3.0) (2025-07-21)
+
+#### 🚀 Features
+
+- add `dataURL` output option ([eca0ee3](https://github.com/thi-ng/umbrella/commit/eca0ee3))
+
 ### [1.2.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@1.2.1) (2025-07-14)
 
 #### 🩹 Bug fixes

package/README.md

@@ -375,7 +375,7 @@ For Node.js REPL:
 const imago = await import("@thi.ng/imago");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.08 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.17 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -372,6 +372,19 @@ export interface OutputSpec extends ProcSpec {
      * WebP output options. See [Sharp docs](https://sharp.pixelplumbing.com/api-output#webp)
      */
     webp?: WebpOptions;
+    /**
+     * Only used if {@link OutputSpec.path} is NOT set. If true, output will be
+     * captured as data URL, otherwise as binary data/buffer.
+     *
+     * @remarks
+     * Other conditions:
+     *
+     * - Requires {@link OutputSpec.format} to be set to a data URL compatible
+     *   image format.
+     * - An error will be thrown during processing if the encoded image size
+     *   exceeds 32KB.
+     */
+    dataURL?: boolean;
 }
 export interface ResizeSpec extends ProcSpec {
     op: "resize";

package/ops/output.d.ts

@@ -1,3 +1,4 @@
 import type { Processor } from "../api.js";
 export declare const outputProc: Processor;
+export declare const asDataURL: (mime: string, data: Buffer) => string;
 //# sourceMappingURL=output.d.ts.map

package/ops/output.js

@@ -1,19 +1,18 @@
 import { encode } from "@thi.ng/blurhash";
 import { isNumber, isPlainObject } from "@thi.ng/checks";
+import { illegalArgs } from "@thi.ng/errors";
 import { writeFile, writeJSON } from "@thi.ng/file-io";
-import { firstNonNullKey } from "@thi.ng/object-utils/first-non-null";
-import { join, resolve } from "node:path";
+import { firstNonNullKey } from "@thi.ng/object-utils";
 import { formatPath } from "../path.js";
 const outputProc = async (spec, input, ctx) => {
   const opts = spec;
-  const outDir = resolve(ctx.opts.outDir || ".");
   let output = input.clone();
   if (opts.blurhash) {
     await __outputBlurHash(opts, output, ctx);
     return [input, false];
   }
   if (opts.raw) {
-    await __outputRaw(opts, output, ctx, outDir);
+    await __outputRaw(opts, output, ctx);
     return [input, false];
   }
   if (ctx.meta.exif && ctx.opts.keepEXIF) {
@@ -72,18 +71,15 @@ const outputProc = async (spec, input, ctx) => {
   if (format) output = output.toFormat(format);
   const result = await output.toBuffer();
   if (opts.path !== void 0) {
-    const path = join(
-      outDir,
-      formatPath(opts.path, ctx, spec, result)
-    );
+    const path = formatPath(opts.path, ctx, spec, result);
     writeFile(path, result, null, ctx.logger);
     ctx.outputs[opts.id] = path;
   } else {
-    ctx.outputs[opts.id] = result;
+    ctx.outputs[opts.id] = format && opts.dataURL ? asDataURL(`image/${format}`, result) : result;
   }
   return [input, false];
 };
-const __outputRaw = async (opts, output, ctx, outDir) => {
+const __outputRaw = async (opts, output, ctx) => {
   const { alpha = false, meta = false } = isPlainObject(opts.raw) ? opts.raw : {};
   if (alpha) output = output.ensureAlpha();
   else output = output.removeAlpha();
@@ -92,7 +88,7 @@ const __outputRaw = async (opts, output, ctx, outDir) => {
     ctx.outputMeta[opts.id] = { ...info, exif: ctx.exif };
   }
   if (opts.path !== void 0) {
-    const path = join(outDir, formatPath(opts.path, ctx, opts, data));
+    const path = formatPath(opts.path, ctx, opts, data);
     writeFile(path, data, null, ctx.logger);
     ctx.outputs[opts.id] = path;
     if (meta) {
@@ -122,6 +118,12 @@ const __outputBlurHash = async (opts, output, ctx) => {
   ctx.logger.debug("computed blurhash:", hash);
   ctx.outputs[opts.id] = hash;
 };
+const asDataURL = (mime, data) => {
+  if (data.length > 32768)
+    illegalArgs("encoded image too large for dataURL (max. 32KB allowed)");
+  return `data:${mime};base64,${data.toString("base64")}`;
+};
 export {
+  asDataURL,
   outputProc
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/imago",
-  "version": "1.2.4",
+  "version": "1.4.0",
   "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
   "type": "module",
   "module": "./index.js",
@@ -54,7 +54,7 @@
     "sharp": "^0.34.3"
   },
   "devDependencies": {
-    "@thi.ng/vectors": "^8.4.1",
+    "@thi.ng/vectors": "^8.5.0",
     "@types/node": "^24.0.15",
     "esbuild": "^0.25.8",
     "typedoc": "^0.28.7",
@@ -189,5 +189,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "11747c482773d3da03c8b7848b25a56251ccd759\n"
+  "gitHead": "b8784efbd8beaa2ff296bb8fb802cb73f6d881ac\n"
 }

package/path.d.ts

@@ -1,9 +1,13 @@
 import type { TypedArray } from "@thi.ng/api";
 import type { ImgProcCtx, OutputSpec } from "./api.js";
 /**
- * Expands/replaces all `{xyz}`-templated identifiers in given file path.
+ * Expands/replaces all `{xyz}`-templated identifiers in given file path and
+ * makes result an absolute path (if needed).
  *
  * @remarks
+ * If the input path is not yet absolute, it will be joined with the
+ * {@link ImgProcOpts.outDir}.
+ *
  * The following built-in IDs are supported and custom IDs will be looked up via
  * the {@link ImgProcOpts.pathParts} options provided to {@link processImage}.
  * Any others will remain as is. Custom IDs take precedence over built-in ones.

package/path.js

@@ -12,57 +12,60 @@ import {
 } from "@thi.ng/date";
 import { illegalArgs as unsupported } from "@thi.ng/errors";
 import { createHash } from "node:crypto";
-import { basename } from "node:path";
+import { basename, isAbsolute, join, resolve } from "node:path";
 const _ = void 0;
-const formatPath = (path, ctx, spec, buf) => path.replace(/\{(\w+)\}/g, (match, id) => {
-  const custom = ctx.opts.pathParts?.[id];
-  if (custom != null) {
-    return isFunction(custom) ? custom(ctx, spec, buf) : custom;
-  }
-  switch (id) {
-    case "name": {
-      !path && unsupported(
-        "cannot format `{name}`, image has no file source"
-      );
-      const name = basename(ctx.path);
-      const idx = name.lastIndexOf(".");
-      return idx > 0 ? name.substring(0, idx) : name;
+const formatPath = (path, ctx, spec, buf) => {
+  path = path.replace(/\{(\w+)\}/g, (match, id) => {
+    const custom = ctx.opts.pathParts?.[id];
+    if (custom != null) {
+      return isFunction(custom) ? custom(ctx, spec, buf) : custom;
     }
-    case "sha1":
-    case "sha224":
-    case "sha256":
-    case "sha384":
-    case "sha512":
-      return createHash(id).update(buf).digest("hex").substring(0, 8);
-    case "w":
-      return String(ctx.size[0]);
-    case "h":
-      return String(ctx.size[1]);
-    case "aspect": {
-      const [w, h] = ctx.size;
-      return w > h ? "l" : w < h ? "p" : "sq";
+    switch (id) {
+      case "name": {
+        !path && unsupported(
+          "cannot format `{name}`, image has no file source"
+        );
+        const name = basename(ctx.path);
+        const idx = name.lastIndexOf(".");
+        return idx > 0 ? name.substring(0, idx) : name;
+      }
+      case "sha1":
+      case "sha224":
+      case "sha256":
+      case "sha384":
+      case "sha512":
+        return createHash(id).update(buf).digest("hex").substring(0, 8);
+      case "w":
+        return String(ctx.size[0]);
+      case "h":
+        return String(ctx.size[1]);
+      case "aspect": {
+        const [w, h] = ctx.size;
+        return w > h ? "l" : w < h ? "p" : "sq";
+      }
+      case "date":
+        return FMT_yyyyMMdd_ALT(_, true);
+      case "time":
+        return FMT_HHmmss_ALT(_, true);
+      case "year":
+        return FMT_yyyy(_, true);
+      case "month":
+        return FMT_MM(_, true);
+      case "week":
+        return FMT_ww(_, true);
+      case "day":
+        return FMT_dd(_, true);
+      case "hour":
+        return FMT_HH(_, true);
+      case "minute":
+        return FMT_mm(_, true);
+      case "second":
+        return FMT_ss(_, true);
     }
-    case "date":
-      return FMT_yyyyMMdd_ALT(_, true);
-    case "time":
-      return FMT_HHmmss_ALT(_, true);
-    case "year":
-      return FMT_yyyy(_, true);
-    case "month":
-      return FMT_MM(_, true);
-    case "week":
-      return FMT_ww(_, true);
-    case "day":
-      return FMT_dd(_, true);
-    case "hour":
-      return FMT_HH(_, true);
-    case "minute":
-      return FMT_mm(_, true);
-    case "second":
-      return FMT_ss(_, true);
-  }
-  return match;
-});
+    return match;
+  });
+  return isAbsolute(path) ? path : join(resolve(ctx.opts.outDir || "."), path);
+};
 export {
   formatPath
 };