@thi.ng/imago 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-02-22T11:59:16Z
+- **Last updated**: 2024-02-22T23:15:26Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,14 @@ 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.
 
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.2.0) (2024-02-22)
+
+#### 🚀 Features
+
+- add support for custom path part replacements ([b0419e1](https://github.com/thi-ng/umbrella/commit/b0419e1))
+- add more path part replacements ([9f84a8a](https://github.com/thi-ng/umbrella/commit/9f84a8a))
+- collect all output paths, update processImage() result ([a3ca52f](https://github.com/thi-ng/umbrella/commit/a3ca52f))
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.1.0) (2024-02-22)
 
 #### 🚀 Features

package/README.md

@@ -42,6 +42,7 @@
   - [hsbl](#hsbl)
   - [nest](#nest)
   - [output](#output)
+    - [Templated output paths](#templated-output-paths)
   - [resize](#resize)
   - [rotate](#rotate)
 - [Status](#status)
@@ -219,6 +220,36 @@ File output in any of these formats:
 - tiff
 - webp
 
+#### Templated output paths
+
+Output paths can contain `{id}`-templated parts which will be replaced/expanded.
+The following built-in IDs are supported and custom IDs will be looked up via
+the
+[pathParts](https://docs.thi.ng/umbrella/imago/interfaces/ImgProcOpts.html#pathParts)
+options provided to
+[processImage()](https://docs.thi.ng/umbrella/imago/functions/processImage.html).
+Any others will remain as is. Custom IDs take precedence over built-in ones.
+
+- `name`: original base filename (w/o ext)
+- `sha1`/`sha224`/`sha256`/`sha384`/`sha512`: truncated hash of output (8 chars)
+- `w`: current image width
+- `h`: current image height
+- `date`: yyyyMMdd date format, e.g. 20240223
+- `time`: HHmmss time format, e.g. 234459
+- `year`: 4-digit year
+- `month`: 2-digit month
+- `week`: 2-digit week
+- `day`: 2-digit day in month
+- `hour`: 2-digit hour (24h system)
+- `minute`: 2-digit minute
+- `second`: 2-digit second
+
+Output paths can contain sub-directories which will be automatically created
+(relative to the [configured output
+dir](https://docs.thi.ng/umbrella/imago/interfaces/ImgProcOpts.html#outDir)).
+For example, the path template `{year}/{month}/{day}/{name}-{sha1}.jpg` might
+get replaced to: `2024/02/22/test-123cafe4.jpg`...
+
 ### resize
 
 Resizing image
@@ -250,7 +281,7 @@ For Node.js REPL:
 const imago = await import("@thi.ng/imago");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.13 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.29 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -1,4 +1,5 @@
-import type { Keys } from "@thi.ng/api";
+/// <reference types="node" />
+import type { Fn3, Keys, TypedArray } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
 import type { AvifOptions, Blend, Exif, ExtendWith, FitEnum, GifOptions, Jp2Options, JpegOptions, JxlOptions, KernelEnum, Metadata, PngOptions, TiffOptions, TileOptions, WebpOptions } from "sharp";
 export type Gravity = "c" | "e" | "n" | "ne" | "nw" | "s" | "se" | "sw" | "w";
@@ -147,6 +148,17 @@ export interface ImgProcOpts {
      * Base directory for {@link output} steps
      */
     outDir: string;
+    /**
+     * An object with custom output path replacements for {@link formatPath}. If
+     * a given replacement value is a function, it will be called with the
+     * current {@link ImgProcCtx}, the current {@link OutputSpec} (e.g. to
+     * obtain configured options) and the already serialized image as buffer.
+     *
+     * @remarks
+     * Replacement IDs in this object will take precedence over built-in
+     * replacement IDs, e.g. allowing to override `name`, `date` etc.
+     */
+    pathParts: Record<string, Fn3<ImgProcCtx, OutputSpec, Buffer | TypedArray, string> | string>;
 }
 export interface ImgProcCtx {
     path?: string;
@@ -155,6 +167,10 @@ export interface ImgProcCtx {
     meta: Metadata;
     logger: ILogger;
     opts: Partial<ImgProcOpts>;
+    /**
+     * Paths of all exported images.
+     */
+    outputs: string[];
 }
 export declare const GRAVITY_POSITION: Record<Gravity, string>;
 export declare const GRAVITY_MAP: Record<Gravity, string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/imago",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
   "type": "module",
   "module": "./index.js",
@@ -37,18 +37,18 @@
   "dependencies": {
     "@thi.ng/api": "^8.9.25",
     "@thi.ng/checks": "^3.5.0",
-    "@thi.ng/date": "^2.6.0",
+    "@thi.ng/date": "^2.7.0",
     "@thi.ng/defmulti": "^3.0.25",
     "@thi.ng/errors": "^2.4.18",
-    "@thi.ng/file-io": "^1.3.2",
+    "@thi.ng/file-io": "^1.3.3",
     "@thi.ng/logger": "^3.0.2",
-    "@thi.ng/pixel": "^6.1.10",
-    "@thi.ng/pixel-dither": "^1.1.108",
+    "@thi.ng/pixel": "^6.1.11",
+    "@thi.ng/pixel-dither": "^1.1.109",
     "sharp": "^0.33.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.40.1",
-    "@thi.ng/vectors": "^7.10.10",
+    "@thi.ng/vectors": "^7.10.11",
     "esbuild": "^0.20.0",
     "rimraf": "^5.0.5",
     "typedoc": "^0.25.7",
@@ -121,5 +121,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "4513a1c703bdbf0f0867f03e547e47692e415fac\n"
+  "gitHead": "16f2b92b5410bd35dcde6c2971c8e62783ebc472\n"
 }

package/path.d.ts

@@ -1,22 +1,34 @@
 /// <reference types="node" />
 import type { TypedArray } from "@thi.ng/api";
-import type { ImgProcCtx } from "./api.js";
+import type { ImgProcCtx, OutputSpec } from "./api.js";
 /**
  * Expands/replaces all `{xyz}`-templated identifiers in given file path.
  *
  * @remarks
- * The following IDs are supported. Any others will remain as is.
+ * 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.
  *
- * - date: yyyyMMdd
- * - time: HHmmss
  * - name: original base filename (w/o ext)
  * - sha1/224/256/384/512: truncated hash of output
  * - w: current width
  * - h: current height
+ * - date: yyyyMMdd
+ * - time: HHmmss
+ * - year: 4-digit year
+ * - month: 2-digit month
+ * - week: 2-digit week
+ * - day: 2-digit day in month
+ * - hour: 2-digit hour (24h system)
+ * - minute: 2-digit minute
+ * - second: 2-digit second
+ *
+ * All date/time related values will be in UTC.
  *
  * @param path
- * @param buf
  * @param ctx
+ * @param spec
+ * @param buf
  */
-export declare const formatPath: (path: string, buf: Buffer | TypedArray, ctx: ImgProcCtx) => string;
+export declare const formatPath: (path: string, ctx: ImgProcCtx, spec: OutputSpec, buf: Buffer | TypedArray) => string;
 //# sourceMappingURL=path.d.ts.map

package/path.js

@@ -1,8 +1,24 @@
-import { FMT_HHmmss_ALT, FMT_yyyyMMdd_ALT } from "@thi.ng/date";
+import { isFunction } from "@thi.ng/checks";
+import {
+  FMT_HH,
+  FMT_HHmmss_ALT,
+  FMT_MM,
+  FMT_dd,
+  FMT_mm,
+  FMT_ss,
+  FMT_ww,
+  FMT_yyyy,
+  FMT_yyyyMMdd_ALT
+} from "@thi.ng/date";
 import { illegalArgs as unsupported } from "@thi.ng/errors";
 import { createHash } from "node:crypto";
 import { basename } from "node:path";
-const formatPath = (path, buf, ctx) => path.replace(/\{(\w+)\}/g, (match, id) => {
+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(
@@ -23,9 +39,23 @@ const formatPath = (path, buf, ctx) => path.replace(/\{(\w+)\}/g, (match, id) =>
     case "h":
       return String(ctx.size[1]);
     case "date":
-      return FMT_yyyyMMdd_ALT();
+      return FMT_yyyyMMdd_ALT(_, true);
     case "time":
-      return FMT_HHmmss_ALT();
+      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;
 });

package/proc.d.ts

@@ -2,7 +2,11 @@
 import sharp, { type Sharp } from "sharp";
 import { type CompLayer, type ImgProcCtx, type ImgProcOpts, type ProcSpec } from "./api.js";
 export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
-export declare const processImage: (src: string | Buffer | Sharp, procs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<sharp.Sharp>;
+export declare const processImage: (src: string | Buffer | Sharp, procs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
+    img: sharp.Sharp;
+    meta: sharp.Metadata;
+    outputs: string[];
+}>;
 /**
  * Extensible polymorphic function performing a single image processing step.
  *

package/proc.js

@@ -51,7 +51,8 @@ const processImage = async (src, procs, opts = {}, parentCtx) => {
   ensureSize(meta);
   const ctx = {
     path: isString(src) ? src : parentCtx?.path,
-    logger: opts?.logger || LOGGER,
+    outputs: parentCtx ? parentCtx.outputs : [],
+    logger: opts.logger || LOGGER,
     size: [meta.width, meta.height],
     channels: meta.channels,
     meta,
@@ -76,7 +77,7 @@ const processImage = async (src, procs, opts = {}, parentCtx) => {
       }
     });
   }
-  return img;
+  return { img, meta, outputs: ctx.outputs };
 };
 const process = defmulti(
   (spec) => spec.type,
@@ -227,11 +228,15 @@ const process = defmulti(
         if (alpha)
           output = output.ensureAlpha();
         const { data, info } = await output.raw().toBuffer({ resolveWithObject: true });
-        const path = join(outDir, formatPath(opts.path, data, ctx));
-        writeFile(path, data, null, ctx.logger);
+        const path2 = join(
+          outDir,
+          formatPath(opts.path, ctx, spec, data)
+        );
+        writeFile(path2, data, null, ctx.logger);
+        ctx.outputs.push(path2);
         if (meta) {
           writeJSON(
-            path + ".meta.json",
+            path2 + ".meta.json",
             info,
             void 0,
             void 0,
@@ -281,12 +286,12 @@ const process = defmulti(
       if (format)
         output = output.toFormat(format);
       const result = await output.toBuffer();
-      writeFile(
-        join(outDir, formatPath(opts.path, result, ctx)),
-        result,
-        null,
-        ctx.logger
+      const path = join(
+        outDir,
+        formatPath(opts.path, ctx, spec, result)
       );
+      writeFile(path, result, null, ctx.logger);
+      ctx.outputs.push(path);
       return [input, false];
     },
     resize: async (spec, input, ctx) => {