@hellkite/pipkin 0.5.0 → 0.5.2

package/src/lib/template.ts

@@ -2,18 +2,38 @@ import * as fs from 'fs';
 import { parse as parseCsv } from 'papaparse';
 import { Jimp, rgbaToInt } from 'jimp';
 import camelCase from 'lodash.camelcase';
-import { placeImage } from './utils/placeImage';
-import { drawBoundingBox } from './utils/drawBoundingBox';
-import { ImageType, ImageLayerOptions, ImageLayerProps } from './types/image';
-import { TextLayerProps } from './types/text';
-import { RenderOptions } from './types/render';
 import concat from 'lodash.concat';
 import { registerFont } from 'canvas';
 import path from 'path';
-import { hboxPackingFn, vboxPackingFn } from './utils/container';
-import { DirectionContainerOptions, PackingFn } from './types/containers';
-import { BoundingBox } from './types/2d';
-import { renderText } from './utils';
+import {
+    drawBoundingBox,
+    gridPackingFn,
+    hboxPackingFn,
+    placeImage,
+    renderText,
+    vboxPackingFn,
+} from './utils';
+import {
+    DirectionContainerOptions,
+    ImageLayerOptions,
+    ImageRef,
+    ImageType,
+    PackingFn,
+    BoundingBox,
+    RenderOptions,
+    Size,
+    TextLayerOptions,
+    TextRef,
+    GridContainerOptions,
+    DEFAULT_TEXT_LAYER_OPTIONS,
+    FontOptions,
+    DEFAULT_IMAGE_LAYER_OPTIONS,
+    LayerOptions,
+    ContainerOptions,
+    DEFAULT_CONTAINER_OPTIONS,
+} from './types';
+import merge from 'lodash.merge';
+import { RequiredDeep } from 'type-fest';
 
 type RequiredTemplateOptions = {
     height: number;
@@ -35,15 +55,13 @@ const DEFAULT_TEMPLATE_OPTIONS: RequiredTemplateOptions = {
 };
 
 export type LayerFnContext = {
-    width: number;
-    height: number;
     debugMode: boolean;
 };
 
 export type LayerFn<EntryType> = (
     entry: EntryType,
     context: LayerFnContext,
-) => Promise<ImageType>;
+) => Promise<ImageType | undefined>;
 
 export type TemplateLayerFn<EntryType extends Record<string, string>> = (
     template: Template<EntryType>,
@@ -90,6 +108,13 @@ export class Template<EntryType extends Record<string, string>> {
         });
     }
 
+    private get backgroundSize(): Size {
+        return {
+            width: this.background.width,
+            height: this.background.height,
+        };
+    }
+
     layer(fn: LayerFn<EntryType>): this {
         this.layers.push(fn);
         return this;
@@ -101,86 +126,137 @@ export class Template<EntryType extends Record<string, string>> {
             return template.render(entry);
         });
 
-    // TODO: logic for rendering debug helpers
     container = (
         imagesFn: (entry: EntryType) => Promise<Array<ImageType>>,
+        box: BoundingBox,
         packingFn: PackingFn,
+        options?: ContainerOptions<EntryType>,
     ): this =>
-        this.layer(async (entry: EntryType) => {
+        this.layer(async (entry: EntryType, { debugMode }) => {
+            const mergedOptions: RequiredDeep<ContainerOptions<EntryType>>= merge(
+                {},
+                DEFAULT_CONTAINER_OPTIONS,
+                options,
+            );
+            if (this.shouldSkipLayerForEntry(entry, mergedOptions)) {
+                return undefined;
+            }
+
             const images = await imagesFn(entry);
-            return packingFn(this.shadowBackground(), images);
+            const result = await packingFn(
+                box,
+                this.shadowBackground(),
+                images,
+            );
+
+            // debug mode
+            if (debugMode) {
+                const debugImage = await drawBoundingBox(
+                    box,
+                    this.backgroundSize,
+                );
+                return debugImage.composite(result);
+            }
+
+            return result;
         });
 
     hbox = (
         imagesFn: (entry: EntryType) => Promise<Array<ImageType>>,
-        position: BoundingBox,
-        options?: DirectionContainerOptions,
-    ): this => this.container(imagesFn, hboxPackingFn(position, options));
+        box: BoundingBox,
+        options?: DirectionContainerOptions<EntryType>,
+    ): this => this.container(imagesFn, box, hboxPackingFn(options), options);
 
     vbox = (
         imagesFn: (entry: EntryType) => Promise<Array<ImageType>>,
-        position: BoundingBox,
-        options?: DirectionContainerOptions,
-    ): this => this.container(imagesFn, vboxPackingFn(position, options));
-
-    image = ({
-        key,
-        path,
-        position,
-        options,
-    }: ImageLayerProps<EntryType>): this =>
-        this.layer(async (entry, { debugMode, width, height }) => {
-            const imagePath =
-                path ??
-                (options?.pathFn ? options.pathFn(entry[key]) : entry[key]);
-            const image = await this.loadImage(imagePath, options);
+        box: BoundingBox,
+        options?: DirectionContainerOptions<EntryType>,
+    ): this => this.container(imagesFn, box, vboxPackingFn(options), options);
+
+    grid = (
+        imagesFn: (entry: EntryType) => Promise<Array<ImageType>>,
+        box: BoundingBox,
+        options?: GridContainerOptions<EntryType>,
+    ): this => this.container(imagesFn, box, gridPackingFn(options), options);
+
+    image = (
+        ref: ImageRef<EntryType>,
+        box: BoundingBox,
+        options: ImageLayerOptions<EntryType>,
+    ): this =>
+        this.layer(async (entry, { debugMode }) => {
+            const mergedOptions: RequiredDeep<ImageLayerOptions<EntryType>>= merge(
+                {},
+                DEFAULT_IMAGE_LAYER_OPTIONS,
+                { assetsPath: this.defaultAssetsPath },
+                options,
+            );
+            if (this.shouldSkipLayerForEntry(entry, mergedOptions)) {
+                return undefined;
+            }
 
+            const image = await this.pathFromImageRef(entry, ref, mergedOptions);
             const result = await placeImage({
-                background: this.shadowBackground(),
                 image,
-                position,
+                box,
+                backgroundSize: this.backgroundSize,
+                options: mergedOptions,
             });
 
             // debug mode
             if (debugMode) {
-                const debugImage = await drawBoundingBox(position, {
-                    width,
-                    height,
-                });
+                const debugImage = await drawBoundingBox(
+                    box,
+                    this.backgroundSize,
+                );
                 return debugImage.composite(result);
             }
 
             return result;
         });
-
-    loadImage = async (
-        imagePath: string,
-        options?: ImageLayerOptions,
-    ): Promise<ImageType> => {
-        const assetsPath = options?.assetsPath ?? this.defaultAssetsPath;
-        const imageCompletePath = assetsPath
-            ? path.join(assetsPath, imagePath)
-            : imagePath;
-        const image = (await Jimp.read(
-            imageCompletePath,
-        )) as unknown as ImageType;
+    loadImage = async (imagePath: string | Buffer): Promise<ImageType> => {
+        const image = (await Jimp.read(imagePath)) as unknown as ImageType;
         return image;
     };
 
-    text = ({ key, position, options }: TextLayerProps<EntryType>): this =>
-        this.layer(async (entry, { debugMode, width, height }) => {
-            const text = entry[key] as string;
-            const fontFamily =
-                options?.font?.family ?? this.defaultFontFamily ?? 'Arial';
-            return renderText(
-                text,
-                position,
+    text = (
+        ref: TextRef<EntryType>,
+        box: BoundingBox,
+        options?: TextLayerOptions<EntryType>,
+    ): this =>
+        this.layer(async (entry, { debugMode }) => {
+            const mergedOptions = merge(
+                {},
+                DEFAULT_TEXT_LAYER_OPTIONS,
                 {
-                    width,
-                    height, 
-                },
-                { ...options, font: { ...options?.font, family: fontFamily } },
+                    font: {
+                        family: this.defaultFontFamily,
+                    },
+                } as FontOptions,
+                options,
+            );
+            if (this.shouldSkipLayerForEntry(entry, mergedOptions)) {
+                return undefined;
+            }
+
+            const text = this.textFromTextRef(entry, ref);
+            const result = await renderText(
+                text,
+                box,
+                this.backgroundSize,
+                mergedOptions,
             );
+
+            // debug mode
+            if (debugMode) {
+                const debugImage = await drawBoundingBox(
+                    box,
+                    this.backgroundSize,
+                );
+                return debugImage.composite(result);
+            }
+
+            return result;
         });
 
     font(path: fs.PathLike, name: string): this {
@@ -196,15 +272,14 @@ export class Template<EntryType extends Record<string, string>> {
     }
 
     private async renderLayers(entry: EntryType): Promise<Array<ImageType>> {
-        return Promise.all(
+        const results = await Promise.all(
             this.layers.map(layerFn =>
                 layerFn(entry, {
                     debugMode: this.debugMode,
-                    width: this.background.width,
-                    height: this.background.height,
                 }),
             ),
         );
+        return results.filter(result => !!result);
     }
 
     async render(
@@ -273,6 +348,53 @@ export class Template<EntryType extends Record<string, string>> {
             }
         });
     }
-}
 
-// TODO: Ledger of actions applied to the image like a logging feed
+    private pathFromImageRef = async (
+        entry: EntryType,
+        ref: ImageRef<EntryType>,
+        options: RequiredDeep<ImageLayerOptions<EntryType>>,
+    ): Promise<ImageType> => {
+        const pathSegments = [];
+        if (options.assetsPath) {
+            pathSegments.push(options.assetsPath);
+        }
+
+        if ('buffer' in ref) {
+            return this.loadImage(ref.buffer);
+        } else if ('path' in ref) {
+            return this.loadImage(path.join(...pathSegments, ref.path));
+        } else if ('absolutePath' in ref) {
+            return this.loadImage(ref.absolutePath);
+        } else if ('key' in ref) {
+            const fileName = entry[ref.key];
+            return this.loadImage(path.join(...pathSegments, fileName));
+        } else if ('pathFn' in ref) {
+            const fileName = ref.pathFn(entry);
+            return this.loadImage(path.join(...pathSegments, fileName));
+        } else {
+            throw new Error('Unknown ImageRef variant');
+        }
+    };
+
+    private textFromTextRef = (
+        entry: EntryType,
+        ref: TextRef<EntryType>,
+    ): string => {
+        if ('key' in ref) {
+            return entry[ref.key];
+        } else if ('text' in ref) {
+            return ref.text;
+        } else if ('textFn' in ref) {
+            return ref.textFn(entry);
+        } else {
+            throw new Error('Unknown TextRef variant');
+        }
+    };
+
+    private shouldSkipLayerForEntry = (entry: EntryType, options: LayerOptions<EntryType>): boolean => {
+        if (typeof options.skip === 'function') {
+            return options.skip(entry);
+        }
+        return options.skip ?? false;
+    }
+}

package/src/lib/types/boundingBox.ts

@@ -0,0 +1,28 @@
+export type BoundingBox = (
+    | {
+          top: number;
+          height: number;
+      }
+    | {
+          bottom: number;
+          height: number;
+      }
+    | {
+          top: number;
+          bottom: number;
+      }
+) &
+    (
+        | {
+              left: number;
+              width: number;
+          }
+        | {
+              right: number;
+              width: number;
+          }
+        | {
+              left: number;
+              right: number;
+          }
+    );

package/src/lib/types/containers.ts

@@ -1,77 +1,72 @@
-import { Alignment, ImageType, ScaleMode } from './image';
+import { RequiredDeep } from 'type-fest';
+import { BoundingBox } from './boundingBox';
+import { ImageType } from './image';
+import { ScaleMode } from './scale';
+import { LayerOptions } from './layer';
 
-export const DEFAULT_CONTAINER_OPTIONS: Required<ContainerOptions> = {
+export type ContainerOptions<EntryType extends Record<string, string>> =
+    LayerOptions<EntryType> & {
+        /**
+         * This is treated as a minimum length of an unit of space
+         * between two items, but it can grow larger than it
+         *
+         * Defaults to 0
+         */
+        gap?: number;
+
+        /**
+         * Defaults to `none`
+         */
+        scale?: ScaleMode;
+    };
+
+export const DEFAULT_CONTAINER_OPTIONS: RequiredDeep<
+    ContainerOptions<Record<string, string>>
+> = {
     gap: 0,
     justifyContent: 'normal',
     alignItems: 'center',
     scale: 'none',
+    skip: false,
 };
 
-export type ContainerOptions = {
-    /**
-     * Setting a non-default value for justify will cause the alignment to be ignored.
-     * 
-     * Defaults to `normal`
-     */
-    justifyContent?: ContainerJustifyContent;
-
-    /**
-     * This is treated as a minimum length of an unit of space
-     * between two items, but it can grow larger than it
-     * 
-     * Defaults to 0
-     */
-    gap?: number;
-
-    /**
-     * Defines how the items should be placed
-     * across the secondary direction of the container
-     *
-     * Defaults to `center`
-     */
-    alignItems?: Alignment;
-
-    /**
-     * Defaults to `none`
-     */
-    scale?: ScaleMode;
-};
-
-export type DirectionContainerOptions = ContainerOptions & {
+export type DirectionContainerOptions<
+    EntryType extends Record<string, string>,
+> = ContainerOptions<EntryType> & {
     reversed?: boolean;
 };
 
-// TODO: all required
-export const DEFAULT_DIRECTION_CONTAINER_OPTIONS: DirectionContainerOptions = {
+export const DEFAULT_DIRECTION_CONTAINER_OPTIONS: RequiredDeep<
+    DirectionContainerOptions<Record<string, string>>
+> = {
     ...DEFAULT_CONTAINER_OPTIONS,
     reversed: false,
-}
+};
 
-/**
- * Same as CSS justify-content property
- */
-type ContainerJustifyContent =
-    | 'flex-start'
-    | 'flex-end'
-    | 'center'
-    | 'space-evenly'
-    | 'space-between'
-    | 'space-around'
-    | 'normal';
+export type GridContainerOptions<EntryType extends Record<string, string>> =
+    ContainerOptions<EntryType> & {
+        size?: number;
 
-export type GridContainerOptions = ContainerOptions & {
-    rows?: number;
-    cols?: number;
+        /**
+         * Defines what is considered the main direction of the container.
+         * -> `rows` - the items would be placed to fill each row before starting the next
+         * -> `cols` - the items would be placed to fill each col before starting the next
+         *
+         * Defaults to `rows`
+         */
+        direction?: 'rows' | 'cols';
+    };
 
-    /**
-     * Defines what is considered the main direction of the container.
-     * -> `rows` - the items would be placed to fill each row before starting the next
-     * -> `cols` - the items would be placed to fill each col before starting the next
-     *
-     * Defaults to `rows`
-     */
-    direction?: 'rows' | 'cols';
+export const DEFAULT_GRID_CONTAINER_OPTIONS: RequiredDeep<
+    GridContainerOptions<Record<string, string>>
+> = {
+    ...DEFAULT_CONTAINER_OPTIONS,
+    size: 3,
+    direction: 'rows',
 };
 
-
-export type PackingFn = (background: ImageType, images: Array<ImageType>) => Promise<ImageType>;
+export type PackingFn = (
+    box: BoundingBox,
+    background: ImageType,
+    images: Array<ImageType>,
+) => Promise<ImageType>;

package/src/lib/types/css.ts

@@ -1 +1,32 @@
-export const toPx = (value: number): string => `${value}px`;
+import { ScaleMode } from './scale';
+
+export type JustifyContent =
+    | 'flex-start'
+    | 'flex-end'
+    | 'center'
+    | 'space-evenly'
+    | 'space-between'
+    | 'space-around'
+    | 'normal';
+
+export type AlignItems =
+    | 'normal'
+    | 'stretch'
+    | 'center'
+    | 'start'
+    | 'end'
+    | 'flex-start'
+    | 'flex-end'
+    | 'self-start'
+    | 'self-end'
+    | 'baseline'
+    | 'first baseline'
+    | 'last baseline'
+    | 'safe center'
+    | 'unsafe center';
+
+export const SCALE_MODE_TO_OBJECT_FIT: Record<ScaleMode, string> = {
+    'keep-ratio': 'contain',
+    stretch: 'fill',
+    none: 'none',
+};

package/src/lib/types/image.ts

@@ -1,66 +1,41 @@
 import { JimpInstance } from 'jimp';
-import { BoundingBox, Point, Size } from './2d';
+import { ScaleMode } from './scale';
+import { LayerOptions } from './layer';
+import { RequiredDeep } from 'type-fest';
 
 export type ImageType = JimpInstance;
 
-export type ImageLayerProps<EntryType> = (
-    | {
-          key: keyof EntryType;
-          path?: undefined;
-      }
-    | {
-          key?: undefined;
-          path: string;
-      }
-) & {
-    position: ImagePosition;
-    options?: ImageLayerOptions;
-};
-
-export type ImageLayerOptions = {
-    assetsPath?: string;
-    pathFn?: (path: string) => string;
-    // TODO:
-    // processorFn?: (entry: EntryType, image: ImageType) => Promise<ImageType>;
-};
-
-export type ImagePosition = ImageAlignmentProps & ScaleProps & BoundingBox;
-
-export type ImageAlignmentProps = {
-    /**
-     * Overridden by xAlignment and/or yAlignment if provided.
-     * default `center`
-     */
-    alignment?: Alignment;
-    /**
-     * default `center`
-     */
-    xAlignment?: Alignment;
-    /**
-     * default `center`
-     */
-    yAlignment?: Alignment;
+export type ImageRef<EntryType extends Record<string, string>> =
+    | { buffer: Buffer }
+    | { path: string }
+    | { absolutePath: string }
+    | { key: keyof EntryType }
+    | { pathFn: (entry: EntryType) => string };
+
+export type ImageLayerOptions<EntryType extends Record<string, string>> =
+    LayerOptions<EntryType> & {
+        /**
+         * Base path for the assets. Overrides the more global property of the template `defaultAssetsPath`.
+         */
+        assetsPath?: string;
+
+        /**
+         * Defaults to `none`
+         */
+        scale?: ScaleMode;
+
+        // TODO:
+        // processorFn?: (entry: EntryType, image: ImageType) => Promise<ImageType>;
+    };
+
+export const DEFAULT_IMAGE_LAYER_OPTIONS: RequiredDeep<ImageLayerOptions<Record<string, string>>> = {
+    justifyContent: 'center',
+    alignItems: 'center',
+    scale: 'none',
+    skip: false,
+    assetsPath: ''
 };
 
 export type Alignment = 'start' | 'center' | 'end';
 
 export const DEFAULT_IMAGE_ALIGNMENT: Alignment = 'center';
-
-/**
- * Behavior of the content around a space
- * that is bigger or smaller than necessary
- * -> `none`: no scaling
- * -> `keep-ration`: scale while preserving aspect ration
- * -> `stretch`: scale without preserving aspect ration
- */
-// TODO: Could be extended with 'x-stretch' and 'y-stretch'
-export type ScaleMode = 'none' | 'keep-ratio' | 'stretch';
-
-export const DEFAULT_SCALE_MODE: ScaleMode = 'none';
-
-export type ScaleProps = {
-    /**
-     * Defaults to `none`
-     */
-    scale?: ScaleMode;
-};

package/src/lib/types/index.ts

@@ -1,9 +1,10 @@
-export * from './2d';
+export * from './size';
 export * from './containers';
 export * from './image';
-export * from './omitArgument';
 export * from './render';
 export * from './replacement';
 export * from './scale';
 export * from './text';
+export * from './boundingBox';
 export * from './css';
+export * from './layer';

package/src/lib/types/layer.ts

@@ -0,0 +1,18 @@
+import { JustifyContent, AlignItems } from "./css";
+
+export type LayerOptions<EntryType extends Record<string, string>> = {
+    /**
+     * default `center`
+     */
+    justifyContent?: JustifyContent;
+
+    /**
+     * default `center`
+     */
+    alignItems?: AlignItems;
+
+    /**
+     * Decides if a layer should be rendered or not for a certain entry
+     */
+    skip?: boolean | ((entry: EntryType) => boolean);
+};

package/src/lib/types/scale.ts

@@ -0,0 +1,11 @@
+/**
+ * Behavior of the content around a space
+ * that is bigger or smaller than necessary
+ * -> `none`: no scaling
+ * -> `keep-ration`: scale while preserving aspect ration
+ * -> `stretch`: scale without preserving aspect ration
+ */
+// TODO: Could be extended with 'x-stretch' and 'y-stretch'
+export type ScaleMode = 'none' | 'keep-ratio' | 'stretch';
+
+export const DEFAULT_SCALE_MODE: ScaleMode = 'none';

package/src/lib/types/size.ts

@@ -0,0 +1,4 @@
+export type Size = {
+    width: number;
+    height: number;
+};