@thi.ng/imago 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-01T15:22:50Z
+- **Last updated**: 2024-03-06T08:50:42Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,13 @@ 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.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.6.0) (2024-03-06)
+
+#### 🚀 Features
+
+- update ImgProcOpts/Ctx, add custom env object ([2b160e0](https://github.com/thi-ng/umbrella/commit/2b160e0))
+  - update processImage() & result
+
 ## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/imago@0.5.0) (2024-03-01)
 
 #### 🚀 Features

package/README.md

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

package/api.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" />
-import type { Fn, Fn3, Keys, Range1_4, TypedArray } from "@thi.ng/api";
+import type { Fn, Fn3, IObjectOf, Keys, Range1_4, 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, OverlayOptions, PngOptions, Sharp, TiffOptions, TileOptions, WebpOptions } from "sharp";
 /**
@@ -407,6 +407,17 @@ export interface ImgProcOpts {
      * replacement IDs, e.g. allowing to override `name`, `date` etc.
      */
     pathParts: Record<string, Fn3<ImgProcCtx, OutputSpec, BufferLike, string> | string>;
+    /**
+     * User provided environment, i.e. an object to provide arbitrary values to
+     * {@link Processor}s and for them to store results in.
+     *
+     * @remarks
+     * Note: This option is optional. Processors should only access the
+     * environment via {@link ImgProcCtx.env} which ensures the object is
+     * defined and it is only that version which will also be returned as part
+     * of the results from {@link processImage}...
+     */
+    env?: IObjectOf<any>;
 }
 export interface ImgProcCtx {
     path?: string;
@@ -421,6 +432,10 @@ export interface ImgProcCtx {
      * {@link output}.
      */
     outputs: Record<string, string>;
+    /**
+     * See {@link ImgProcOpts.env} for details/comments.
+     */
+    env: IObjectOf<any>;
 }
 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.5.2",
+  "version": "0.6.0",
   "description": "JSON & API-based declarative and extensible image processing trees/pipelines",
   "type": "module",
   "module": "./index.js",
@@ -180,5 +180,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "df9e312af741d87e6b450afcfea6a6e381662b1e\n"
+  "gitHead": "f6bb0e172c5dcb574b961f5155a50040d5569685\n"
 }

package/proc.d.ts

@@ -4,12 +4,14 @@ export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
 /**
  * Main API function. Takes an image input (file path, buffer or existing Sharp
  * instance) and applies given processing pipeline specs in sequence. Returns a
- * promise of final processed image, input metadata (if any) and an object of
- * all written output paths (keyed by each output's {@link OutputSpec.id}). The
- * process can be configured via provided options.
+ * promise of final processed image, input metadata (if any), an environment
+ * object of arbitrary data (likely produced by custom ops/processors) and an
+ * object of all written output paths (keyed by each output's
+ * {@link OutputSpec.id}). The process pipeline can be additionally configured
+ * via provided options.
  *
  * @remarks
- * The `parentCtx` arg is internal use only!
+ * The `parentCtx` arg is internal use only (nested processors)!
  *
  * @param src
  * @param specs
@@ -19,6 +21,7 @@ export declare const LOGGER: import("@thi.ng/logger").ProxyLogger;
 export declare const processImage: (src: string | BufferLike | ArrayBuffer | Sharp, specs: ProcSpec[], opts?: Partial<ImgProcOpts>, parentCtx?: ImgProcCtx) => Promise<{
     img: sharp.Sharp;
     meta: sharp.Metadata;
+    env: import("@thi.ng/api").IObjectOf<any>;
     outputs: Record<string, string>;
 }>;
 /**

package/proc.js

@@ -25,6 +25,7 @@ const processImage = async (src, specs, opts = {}, parentCtx) => {
   const ctx = {
     path: isString(src) ? src : parentCtx?.path,
     outputs: parentCtx ? parentCtx.outputs : {},
+    env: parentCtx ? parentCtx.env : opts.env || {},
     logger: opts.logger || LOGGER,
     size: [meta.width, meta.height],
     exif: parentCtx ? structuredClone(parentCtx.exif) : {},
@@ -59,7 +60,7 @@ const processImage = async (src, specs, opts = {}, parentCtx) => {
         }
       });
     }
-    return { img, meta, outputs: ctx.outputs };
+    return { img, meta, env: ctx.env, outputs: ctx.outputs };
   } finally {
     if (ctx.iccFile)
       deleteFile(ctx.iccFile, ctx.logger);