@deenruv/asset-server-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+# License 1
+
+The MIT License
+
+Copyright (c) 2025-present Aexol
+
+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.
+
+# License 2
+
+The MIT License
+
+Copyright (c) 2018-2025 Michael Bromley
+
+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,103 @@
+# @deenruv/asset-server-plugin
+
+Serves assets (images and other files) from the local file system or cloud storage (e.g. S3), with on-the-fly image transformation (resize, crop, format conversion) and result caching.
+
+## Installation
+
+```bash
+pnpm add @deenruv/asset-server-plugin
+```
+
+## Configuration
+
+```typescript
+import { AssetServerPlugin } from '@deenruv/asset-server-plugin';
+import path from 'path';
+
+const config = {
+  plugins: [
+    AssetServerPlugin.init({
+      route: 'assets',
+      assetUploadDir: path.join(__dirname, 'assets'),
+    }),
+  ],
+};
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `route` | `string` | *required* | URL route for serving assets (e.g. `'assets'`) |
+| `assetUploadDir` | `string` | *required* | Local directory for asset storage |
+| `assetUrlPrefix` | `string \| fn` | auto-detected | Complete URL prefix for asset files |
+| `presets` | `ImageTransformPreset[]` | See below | Named image transform presets |
+| `namingStrategy` | `AssetNamingStrategy` | `HashedAssetNamingStrategy` | Strategy for naming uploaded assets |
+| `previewStrategy` | `AssetPreviewStrategy` | `SharpAssetPreviewStrategy` | Strategy for generating preview images |
+| `storageStrategyFactory` | `fn` | `LocalAssetStorageStrategy` | Factory for custom storage backends (e.g. S3) |
+| `cacheHeader` | `string \| CacheConfig` | `'public, max-age=15552000'` | Cache-Control header (default: 6 months) |
+
+## Image Transformation
+
+Assets can be transformed on-the-fly via URL query parameters:
+
+```
+http://localhost:3000/assets/photo.jpg?w=500&h=300&mode=resize
+```
+
+**Query Parameters:**
+
+| Param | Description |
+|-------|-------------|
+| `w` | Target width in pixels |
+| `h` | Target height in pixels |
+| `mode` | `crop` (cover) or `resize` (contain) |
+| `preset` | Named preset (e.g. `?preset=thumb`) |
+| `fpx`, `fpy` | Focal point (0-1 normalized coordinates) for crop mode |
+| `format` | Output format: `jpg`, `png`, `webp`, `avif` |
+| `q` | Quality (1-100, default: 80 for jpg/webp, 50 for avif) |
+| `cache` | Set to `false` to skip caching |
+
+### Default Presets
+
+| Name | Width | Height | Mode |
+|------|-------|--------|------|
+| `tiny` | 50px | 50px | crop |
+| `thumb` | 150px | 150px | crop |
+| `small` | 300px | 300px | resize |
+| `medium` | 500px | 500px | resize |
+| `large` | 800px | 800px | resize |
+
+Custom presets can be added via the `presets` option:
+
+```typescript
+AssetServerPlugin.init({
+  route: 'assets',
+  assetUploadDir: path.join(__dirname, 'assets'),
+  presets: [
+    { name: 'hero', width: 1200, height: 600, mode: 'crop' },
+  ],
+});
+```
+
+## Features
+
+- On-the-fly image resize and crop via URL query parameters
+- Format conversion (JPEG, PNG, WebP, AVIF)
+- Quality control for lossy formats
+- Focal point-aware cropping
+- Named transform presets
+- Transformed image caching for subsequent requests
+- Configurable Cache-Control headers
+- S3-compatible cloud storage via `S3AssetStorageStrategy`
+- Hashed asset naming for cache busting
+- Sharp-based image processing
+- Content-type detection with fallback
+
+## Admin UI
+
+Server-only plugin. No Admin UI extensions.
+
+## API Extensions
+
+No GraphQL API extensions. Assets are served via Express middleware at the configured route.

package/lib/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./src/plugin";
+export * from "./src/s3-asset-storage-strategy";
+export * from "./src/sharp-asset-preview-strategy";
+export * from "./src/types";

package/lib/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./src/plugin"), exports);
+__exportStar(require("./src/s3-asset-storage-strategy"), exports);
+__exportStar(require("./src/sharp-asset-preview-strategy"), exports);
+__exportStar(require("./src/types"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAC7B,kEAAgD;AAChD,qEAAmD;AACnD,8CAA4B"}

package/lib/src/common.d.ts

@@ -0,0 +1,4 @@
+import { Request } from "express";
+import { AssetServerOptions, ImageTransformFormat } from "./types";
+export declare function getAssetUrlPrefixFn(options: AssetServerOptions): ((request: Request, identifier: string) => string) | ((...args: any[]) => string);
+export declare function getValidFormat(format?: unknown): ImageTransformFormat | undefined;

package/lib/src/common.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getValidFormat = exports.getAssetUrlPrefixFn = void 0;
+const constants_1 = require("@deenruv/core/dist/common/constants");
+function getAssetUrlPrefixFn(options) {
+    const { assetUrlPrefix, route } = options;
+    if (assetUrlPrefix == null) {
+        return (request, identifier) => {
+            var _a, _b;
+            const protocol = (_a = request.headers["x-forwarded-proto"]) !== null && _a !== void 0 ? _a : request.protocol;
+            return `${Array.isArray(protocol) ? protocol[0] : protocol}://${(_b = request.get("host")) !== null && _b !== void 0 ? _b : "could-not-determine-host"}/${route}/`;
+        };
+    }
+    if (typeof assetUrlPrefix === "string") {
+        return (...args) => assetUrlPrefix;
+    }
+    if (typeof assetUrlPrefix === "function") {
+        return (request, identifier) => {
+            const ctx = request[constants_1.REQUEST_CONTEXT_KEY];
+            return assetUrlPrefix(ctx, identifier);
+        };
+    }
+    throw new Error(`The assetUrlPrefix option was of an unexpected type: ${JSON.stringify(assetUrlPrefix)}`);
+}
+exports.getAssetUrlPrefixFn = getAssetUrlPrefixFn;
+function getValidFormat(format) {
+    if (typeof format !== "string") {
+        return undefined;
+    }
+    switch (format) {
+        case "jpg":
+        case "jpeg":
+        case "png":
+        case "webp":
+        case "avif":
+            return format;
+        default:
+            return undefined;
+    }
+}
+exports.getValidFormat = getValidFormat;
+//# sourceMappingURL=common.js.map

package/lib/src/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/common.ts"],"names":[],"mappings":";;;AAAA,mEAA0E;AAK1E,SAAgB,mBAAmB,CAAC,OAA2B;IAC7D,MAAM,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1C,IAAI,cAAc,IAAI,IAAI,EAAE,CAAC;QAC3B,OAAO,CAAC,OAAgB,EAAE,UAAkB,EAAE,EAAE;;YAC9C,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,mCAAI,OAAO,CAAC,QAAQ,CAAC;YAC1E,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,MACxD,MAAA,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,mCAAI,0BACzB,IAAI,KAAK,GAAG,CAAC;QACf,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,cAAc,KAAK,QAAQ,EAAE,CAAC;QACvC,OAAO,CAAC,GAAG,IAAW,EAAE,EAAE,CAAC,cAAc,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,cAAc,KAAK,UAAU,EAAE,CAAC;QACzC,OAAO,CAAC,OAAgB,EAAE,UAAkB,EAAE,EAAE;YAC9C,MAAM,GAAG,GAAI,OAAe,CAAC,+BAAmB,CAAC,CAAC;YAClD,OAAO,cAAc,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACzC,CAAC,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,KAAK,CACb,wDAAwD,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,EAAE,CACzF,CAAC;AACJ,CAAC;AAtBD,kDAsBC;AAED,SAAgB,cAAc,CAC5B,MAAgB;IAEhB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,QAAQ,MAAM,EAAE,CAAC;QACf,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAhBD,wCAgBC"}

package/lib/src/constants.d.ts

@@ -0,0 +1,2 @@
+export declare const loggerCtx = "AssetServerPlugin";
+export declare const DEFAULT_CACHE_HEADER = "public, max-age=15552000";

package/lib/src/constants.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CACHE_HEADER = exports.loggerCtx = void 0;
+exports.loggerCtx = "AssetServerPlugin";
+exports.DEFAULT_CACHE_HEADER = "public, max-age=15552000";
+//# sourceMappingURL=constants.js.map

package/lib/src/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,SAAS,GAAG,mBAAmB,CAAC;AAChC,QAAA,oBAAoB,GAAG,0BAA0B,CAAC"}

package/lib/src/default-asset-storage-strategy-factory.d.ts

@@ -0,0 +1,6 @@
+import { LocalAssetStorageStrategy } from "./local-asset-storage-strategy";
+import { AssetServerOptions } from "./types";
+/**
+ * By default the AssetServerPlugin will configure and use the LocalStorageStrategy to persist Assets.
+ */
+export declare function defaultAssetStorageStrategyFactory(options: AssetServerOptions): LocalAssetStorageStrategy;

package/lib/src/default-asset-storage-strategy-factory.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultAssetStorageStrategyFactory = void 0;
+const common_1 = require("./common");
+const local_asset_storage_strategy_1 = require("./local-asset-storage-strategy");
+/**
+ * By default the AssetServerPlugin will configure and use the LocalStorageStrategy to persist Assets.
+ */
+function defaultAssetStorageStrategyFactory(options) {
+    const { assetUrlPrefix, assetUploadDir, route } = options;
+    const prefixFn = (0, common_1.getAssetUrlPrefixFn)(options);
+    const toAbsoluteUrlFn = (request, identifier) => {
+        if (!identifier) {
+            return "";
+        }
+        const prefix = prefixFn(request, identifier);
+        return identifier.startsWith(prefix)
+            ? identifier
+            : `${prefix}${identifier}`;
+    };
+    return new local_asset_storage_strategy_1.LocalAssetStorageStrategy(assetUploadDir, toAbsoluteUrlFn);
+}
+exports.defaultAssetStorageStrategyFactory = defaultAssetStorageStrategyFactory;
+//# sourceMappingURL=default-asset-storage-strategy-factory.js.map

package/lib/src/default-asset-storage-strategy-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-asset-storage-strategy-factory.js","sourceRoot":"","sources":["../../src/default-asset-storage-strategy-factory.ts"],"names":[],"mappings":";;;AAEA,qCAA+C;AAC/C,iFAA2E;AAG3E;;GAEG;AACH,SAAgB,kCAAkC,CAChD,OAA2B;IAE3B,MAAM,EAAE,cAAc,EAAE,cAAc,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IAC1D,MAAM,QAAQ,GAAG,IAAA,4BAAmB,EAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,eAAe,GAAG,CAAC,OAAgB,EAAE,UAAkB,EAAU,EAAE;QACvE,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC7C,OAAO,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC;YAClC,CAAC,CAAC,UAAU;YACZ,CAAC,CAAC,GAAG,MAAM,GAAG,UAAU,EAAE,CAAC;IAC/B,CAAC,CAAC;IACF,OAAO,IAAI,wDAAyB,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AACxE,CAAC;AAfD,gFAeC"}

package/lib/src/hashed-asset-naming-strategy.d.ts

@@ -0,0 +1,21 @@
+import { DefaultAssetNamingStrategy, RequestContext } from "@deenruv/core";
+/**
+ * @description
+ * An extension of the {@link DefaultAssetNamingStrategy} which prefixes file names with
+ * the type (`'source'` or `'preview'`) as well as a 2-character sub-directory based on
+ * the md5 hash of the original file name.
+ *
+ * This is an implementation of the technique knows as "hashed directory" file storage,
+ * and the purpose is to reduce the number of files in a single directory, since a very large
+ * number of files can lead to performance issues when reading and writing to that directory.
+ *
+ * With this strategy, even with 200,000 total assets stored, each directory would
+ * only contain less than 800 files.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ */
+export declare class HashedAssetNamingStrategy extends DefaultAssetNamingStrategy {
+    generateSourceFileName(ctx: RequestContext, originalFileName: string, conflictFileName?: string): string;
+    generatePreviewFileName(ctx: RequestContext, originalFileName: string, conflictFileName?: string): string;
+    private getHashedDir;
+}

package/lib/src/hashed-asset-naming-strategy.js

@@ -0,0 +1,39 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HashedAssetNamingStrategy = void 0;
+const core_1 = require("@deenruv/core");
+const crypto_1 = require("crypto");
+const path_1 = __importDefault(require("path"));
+/**
+ * @description
+ * An extension of the {@link DefaultAssetNamingStrategy} which prefixes file names with
+ * the type (`'source'` or `'preview'`) as well as a 2-character sub-directory based on
+ * the md5 hash of the original file name.
+ *
+ * This is an implementation of the technique knows as "hashed directory" file storage,
+ * and the purpose is to reduce the number of files in a single directory, since a very large
+ * number of files can lead to performance issues when reading and writing to that directory.
+ *
+ * With this strategy, even with 200,000 total assets stored, each directory would
+ * only contain less than 800 files.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ */
+class HashedAssetNamingStrategy extends core_1.DefaultAssetNamingStrategy {
+    generateSourceFileName(ctx, originalFileName, conflictFileName) {
+        const filename = super.generateSourceFileName(ctx, originalFileName, conflictFileName);
+        return path_1.default.join("source", this.getHashedDir(filename), filename);
+    }
+    generatePreviewFileName(ctx, originalFileName, conflictFileName) {
+        const filename = super.generatePreviewFileName(ctx, originalFileName, conflictFileName);
+        return path_1.default.join("preview", this.getHashedDir(filename), filename);
+    }
+    getHashedDir(filename) {
+        return (0, crypto_1.createHash)("md5").update(filename).digest("hex").slice(0, 2);
+    }
+}
+exports.HashedAssetNamingStrategy = HashedAssetNamingStrategy;
+//# sourceMappingURL=hashed-asset-naming-strategy.js.map

package/lib/src/hashed-asset-naming-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hashed-asset-naming-strategy.js","sourceRoot":"","sources":["../../src/hashed-asset-naming-strategy.ts"],"names":[],"mappings":";;;;;;AAAA,wCAA2E;AAC3E,mCAAoC;AACpC,gDAAwB;AAExB;;;;;;;;;;;;;;GAcG;AACH,MAAa,yBAA0B,SAAQ,iCAA0B;IACvE,sBAAsB,CACpB,GAAmB,EACnB,gBAAwB,EACxB,gBAAyB;QAEzB,MAAM,QAAQ,GAAG,KAAK,CAAC,sBAAsB,CAC3C,GAAG,EACH,gBAAgB,EAChB,gBAAgB,CACjB,CAAC;QACF,OAAO,cAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;IACpE,CAAC;IACD,uBAAuB,CACrB,GAAmB,EACnB,gBAAwB,EACxB,gBAAyB;QAEzB,MAAM,QAAQ,GAAG,KAAK,CAAC,uBAAuB,CAC5C,GAAG,EACH,gBAAgB,EAChB,gBAAgB,CACjB,CAAC;QACF,OAAO,cAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,CAAC;IACrE,CAAC;IAEO,YAAY,CAAC,QAAgB;QACnC,OAAO,IAAA,mBAAU,EAAC,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC;CACF;AA7BD,8DA6BC"}

package/lib/src/local-asset-storage-strategy.d.ts

@@ -0,0 +1,28 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { AssetStorageStrategy } from "@deenruv/core";
+import { Request } from "express";
+import { ReadStream } from "fs";
+import { Stream } from "stream";
+/**
+ * @description
+ * A persistence strategy which saves files to the local file system.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ */
+export declare class LocalAssetStorageStrategy implements AssetStorageStrategy {
+    private readonly uploadPath;
+    private readonly toAbsoluteUrlFn?;
+    toAbsoluteUrl: ((reqest: Request, identifier: string) => string) | undefined;
+    constructor(uploadPath: string, toAbsoluteUrlFn?: ((reqest: Request, identifier: string) => string) | undefined);
+    writeFileFromStream(fileName: string, data: ReadStream): Promise<string>;
+    writeFileFromBuffer(fileName: string, data: Buffer): Promise<string>;
+    fileExists(fileName: string): Promise<boolean>;
+    readFileToBuffer(identifier: string): Promise<Buffer>;
+    readFileToStream(identifier: string): Promise<Stream>;
+    deleteFile(identifier: string): Promise<void>;
+    private filePathToIdentifier;
+    private identifierToFilePath;
+}

package/lib/src/local-asset-storage-strategy.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalAssetStorageStrategy = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+/**
+ * @description
+ * A persistence strategy which saves files to the local file system.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ */
+class LocalAssetStorageStrategy {
+    constructor(uploadPath, toAbsoluteUrlFn) {
+        this.uploadPath = uploadPath;
+        this.toAbsoluteUrlFn = toAbsoluteUrlFn;
+        fs_extra_1.default.ensureDirSync(this.uploadPath);
+        if (toAbsoluteUrlFn) {
+            this.toAbsoluteUrl = toAbsoluteUrlFn;
+        }
+    }
+    async writeFileFromStream(fileName, data) {
+        const filePath = path_1.default.join(this.uploadPath, fileName);
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(filePath));
+        const writeStream = fs_extra_1.default.createWriteStream(filePath, "binary");
+        return new Promise((resolve, reject) => {
+            data.pipe(writeStream);
+            writeStream.on("close", () => resolve(this.filePathToIdentifier(filePath)));
+            writeStream.on("error", reject);
+        });
+    }
+    async writeFileFromBuffer(fileName, data) {
+        const filePath = path_1.default.join(this.uploadPath, fileName);
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(filePath));
+        await fs_extra_1.default.writeFile(filePath, data, "binary");
+        return this.filePathToIdentifier(filePath);
+    }
+    fileExists(fileName) {
+        return new Promise((resolve) => {
+            fs_extra_1.default.access(this.identifierToFilePath(fileName), fs_extra_1.default.constants.F_OK, (err) => {
+                resolve(!err);
+            });
+        });
+    }
+    readFileToBuffer(identifier) {
+        return fs_extra_1.default.readFile(this.identifierToFilePath(identifier));
+    }
+    readFileToStream(identifier) {
+        const readStream = fs_extra_1.default.createReadStream(this.identifierToFilePath(identifier), "binary");
+        return Promise.resolve(readStream);
+    }
+    deleteFile(identifier) {
+        return fs_extra_1.default.unlink(this.identifierToFilePath(identifier));
+    }
+    filePathToIdentifier(filePath) {
+        const filePathDirname = path_1.default.dirname(filePath);
+        const deltaDirname = filePathDirname.replace(this.uploadPath, "");
+        const identifier = path_1.default.join(deltaDirname, path_1.default.basename(filePath));
+        return identifier.replace(/^[\\/]+/, "");
+    }
+    identifierToFilePath(identifier) {
+        return path_1.default.join(this.uploadPath, identifier);
+    }
+}
+exports.LocalAssetStorageStrategy = LocalAssetStorageStrategy;
+//# sourceMappingURL=local-asset-storage-strategy.js.map

package/lib/src/local-asset-storage-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-asset-storage-strategy.js","sourceRoot":"","sources":["../../src/local-asset-storage-strategy.ts"],"names":[],"mappings":"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"}

package/lib/src/plugin.d.ts

@@ -0,0 +1,167 @@
+import { MiddlewareConsumer, NestModule, OnApplicationBootstrap } from "@nestjs/common";
+import { Type } from "@deenruv/common/lib/shared-types";
+import { ProcessContext, RuntimeDeenruvConfig } from "@deenruv/core";
+import { AssetServerOptions } from "./types";
+/**
+ * @description
+ * The `AssetServerPlugin` serves assets (images and other files) from the local file system, and can also be configured to use
+ * other storage strategies (e.g. {@link S3AssetStorageStrategy}. It can also perform on-the-fly image transformations
+ * and caches the results for subsequent calls.
+ *
+ * ## Installation
+ *
+ * `yarn add \@deenruv/asset-server-plugin`
+ *
+ * or
+ *
+ * `npm install \@deenruv/asset-server-plugin`
+ *
+ * @example
+ * ```ts
+ * import { AssetServerPlugin } from '\@deenruv/asset-server-plugin';
+ *
+ * const config: DeenruvConfig = {
+ *   // Add an instance of the plugin to the plugins array
+ *   plugins: [
+ *     AssetServerPlugin.init({
+ *       route: 'assets',
+ *       assetUploadDir: path.join(__dirname, 'assets'),
+ *     }),
+ *   ],
+ * };
+ * ```
+ *
+ * The full configuration is documented at [AssetServerOptions](/reference/core-plugins/asset-server-plugin/asset-server-options)
+ *
+ * ## Image transformation
+ *
+ * Asset preview images can be transformed (resized & cropped) on the fly by appending query parameters to the url:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?w=500&h=300&mode=resize`
+ *
+ * The above URL will return `some-asset.jpg`, resized to fit in the bounds of a 500px x 300px rectangle.
+ *
+ * ### Preview mode
+ *
+ * The `mode` parameter can be either `crop` or `resize`. See the [ImageTransformMode](/reference/core-plugins/asset-server-plugin/image-transform-mode) docs for details.
+ *
+ * ### Focal point
+ *
+ * When cropping an image (`mode=crop`), Deenruv will attempt to keep the most "interesting" area of the image in the cropped frame. It does this
+ * by finding the area of the image with highest entropy (the busiest area of the image). However, sometimes this does not yield a satisfactory
+ * result - part or all of the main subject may still be cropped out.
+ *
+ * This is where specifying the focal point can help. The focal point of the image may be specified by passing the `fpx` and `fpy` query parameters.
+ * These are normalized coordinates (i.e. a number between 0 and 1), so the `fpx=0&fpy=0` corresponds to the top left of the image.
+ *
+ * For example, let's say there is a very wide landscape image which we want to crop to be square. The main subject is a house to the far left of the
+ * image. The following query would crop it to a square with the house centered:
+ *
+ * `http://localhost:3000/assets/landscape.jpg?w=150&h=150&mode=crop&fpx=0.2&fpy=0.7`
+ *
+ * ### Format
+ *
+ * Since v1.7.0, the image format can be specified by adding the `format` query parameter:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?format=webp`
+ *
+ * This means that, no matter the format of your original asset files, you can use more modern formats in your storefront if the browser
+ * supports them. Supported values for `format` are:
+ *
+ * * `jpeg` or `jpg`
+ * * `png`
+ * * `webp`
+ * * `avif`
+ *
+ * The `format` parameter can also be combined with presets (see below).
+ *
+ * ### Quality
+ *
+ * Since v2.2.0, the image quality can be specified by adding the `q` query parameter:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?q=75`
+ *
+ * This applies to the `jpg`, `webp` and `avif` formats. The default quality value for `jpg` and `webp` is 80, and for `avif` is 50.
+ *
+ * The `q` parameter can also be combined with presets (see below).
+ *
+ * ### Transform presets
+ *
+ * Presets can be defined which allow a single preset name to be used instead of specifying the width, height and mode. Presets are
+ * configured via the AssetServerOptions [presets property](/reference/core-plugins/asset-server-plugin/asset-server-options/#presets).
+ *
+ * For example, defining the following preset:
+ *
+ * ```ts
+ * AssetServerPlugin.init({
+ *   // ...
+ *   presets: [
+ *     { name: 'my-preset', width: 85, height: 85, mode: 'crop' },
+ *   ],
+ * }),
+ * ```
+ *
+ * means that a request to:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?preset=my-preset`
+ *
+ * is equivalent to:
+ *
+ * `http://localhost:3000/assets/some-asset.jpg?w=85&h=85&mode=crop`
+ *
+ * The AssetServerPlugin comes pre-configured with the following presets:
+ *
+ * name | width | height | mode
+ * -----|-------|--------|-----
+ * tiny | 50px | 50px | crop
+ * thumb | 150px | 150px | crop
+ * small | 300px | 300px | resize
+ * medium | 500px | 500px | resize
+ * large | 800px | 800px | resize
+ *
+ * ### Caching
+ * By default, the AssetServerPlugin will cache every transformed image, so that the transformation only needs to be performed a single time for
+ * a given configuration. Caching can be disabled per-request by setting the `?cache=false` query parameter.
+ *
+ * @docsCategory core plugins/AssetServerPlugin
+ */
+export declare class AssetServerPlugin implements NestModule, OnApplicationBootstrap {
+    private processContext;
+    private static assetStorage;
+    private readonly cacheDir;
+    private presets;
+    private static options;
+    private cacheHeader;
+    /**
+     * @description
+     * Set the plugin options.
+     */
+    static init(options: AssetServerOptions): Type<AssetServerPlugin>;
+    /** @internal */
+    static configure(config: RuntimeDeenruvConfig): Promise<RuntimeDeenruvConfig>;
+    constructor(processContext: ProcessContext);
+    /** @internal */
+    onApplicationBootstrap(): void;
+    configure(consumer: MiddlewareConsumer): void;
+    /**
+     * Creates the image server instance
+     */
+    private createAssetServer;
+    /**
+     * Reads the file requested and send the response to the browser.
+     */
+    private sendAsset;
+    /**
+     * If an exception was thrown by the first handler, then it may be because a transformed image
+     * is being requested which does not yet exist. In this case, this handler will generate the
+     * transformed image, save it to cache, and serve the result as a response.
+     */
+    private generateTransformedImage;
+    private getFileNameFromRequest;
+    private md5;
+    private addSuffix;
+    /**
+     * Attempt to get the mime type from the file name.
+     */
+    private getMimeType;
+}