@acmekit/utils 2.13.1

package/dist/feature-flags/discover-feature-flags.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverFeatureFlagsFromDir = discoverFeatureFlagsFromDir;
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const common_1 = require("../common");
+const excludedFiles = ["index.js", "index.ts"];
+const excludedExtensions = [".d.ts", ".d.ts.map", ".js.map"];
+function isFeatureFlag(flag) {
+    const f = flag;
+    return !!f && (0, common_1.isString)(f.key) && (0, common_1.isString)(f.env_key);
+}
+/**
+ * Discover feature flag definitions from a directory and subdirectories
+ */
+async function discoverFeatureFlagsFromDir(sourcePath, maxDepth = 2) {
+    if (!sourcePath) {
+        return [];
+    }
+    const root = (0, path_1.normalize)(sourcePath);
+    const discovered = [];
+    const allEntries = await (0, common_1.readDirRecursive)(root, {
+        ignoreMissing: true,
+        maxDepth,
+    });
+    const featureFlagDirs = allEntries
+        .filter((e) => e.isDirectory() && e.name === "feature-flags")
+        .map((e) => (0, path_1.join)(e.path, e.name));
+    if (!featureFlagDirs.length) {
+        return discovered;
+    }
+    await Promise.all(featureFlagDirs.map(async (scanDir) => {
+        const entries = await (0, promises_1.readdir)(scanDir, { withFileTypes: true });
+        await Promise.all(entries.map(async (entry) => {
+            if (entry.isDirectory()) {
+                return;
+            }
+            if (excludedExtensions.some((ext) => entry.name.endsWith(ext)) ||
+                excludedFiles.includes(entry.name)) {
+                return;
+            }
+            const fileExports = await (0, common_1.dynamicImport)((0, path_1.join)(scanDir, entry.name));
+            const values = Object.values(fileExports);
+            for (const value of values) {
+                if (isFeatureFlag(value)) {
+                    discovered.push(value);
+                }
+            }
+        }));
+    }));
+    return discovered;
+}
+//# sourceMappingURL=discover-feature-flags.js.map

package/dist/feature-flags/discover-feature-flags.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover-feature-flags.js","sourceRoot":"","sources":["../../src/feature-flags/discover-feature-flags.ts"],"names":[],"mappings":";;AAgBA,kEAqDC;AApED,0CAAqC;AACrC,+BAAsC;AACtC,sCAAqE;AAErE,MAAM,aAAa,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,CAAA;AAC9C,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,CAAC,CAAA;AAE5D,SAAS,aAAa,CAAC,IAAa;IAClC,MAAM,CAAC,GAAG,IAAW,CAAA;IACrB,OAAO,CAAC,CAAC,CAAC,IAAI,IAAA,iBAAQ,EAAC,CAAC,CAAC,GAAG,CAAC,IAAI,IAAA,iBAAQ,EAAC,CAAC,CAAC,OAAO,CAAC,CAAA;AACtD,CAAC;AAED;;GAEG;AACI,KAAK,UAAU,2BAA2B,CAC/C,UAAmB,EACnB,WAAmB,CAAC;IAEpB,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,EAAE,CAAA;IACX,CAAC;IAED,MAAM,IAAI,GAAG,IAAA,gBAAS,EAAC,UAAU,CAAC,CAAA;IAClC,MAAM,UAAU,GAAmB,EAAE,CAAA;IAErC,MAAM,UAAU,GAAG,MAAM,IAAA,yBAAgB,EAAC,IAAI,EAAE;QAC9C,aAAa,EAAE,IAAI;QACnB,QAAQ;KACT,CAAC,CAAA;IAEF,MAAM,eAAe,GAAG,UAAU;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC;SAC5D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,WAAI,EAAE,CAAS,CAAC,IAAc,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IAEtD,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,CAAC;QAC5B,OAAO,UAAU,CAAA;IACnB,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CACf,eAAe,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACpC,MAAM,OAAO,GAAG,MAAM,IAAA,kBAAO,EAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QAC/D,MAAM,OAAO,CAAC,GAAG,CACf,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YAC1B,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,OAAM;YACR,CAAC;YAED,IACE,kBAAkB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;gBAC1D,aAAa,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAClC,CAAC;gBACD,OAAM;YACR,CAAC;YAED,MAAM,WAAW,GAAG,MAAM,IAAA,sBAAa,EAAC,IAAA,WAAI,EAAC,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;YAClE,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;YACzC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,IAAI,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;oBACzB,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;gBACxB,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CACH,CAAA;IACH,CAAC,CAAC,CACH,CAAA;IAED,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/feature-flags/flag-router.d.ts

@@ -0,0 +1,33 @@
+import { FeatureFlagTypes } from "@acmekit/types";
+export declare class FlagRouter implements FeatureFlagTypes.IFlagRouter {
+    private readonly flags;
+    constructor(flags: Record<string, boolean | Record<string, boolean>>);
+    /**
+     * Check if a feature flag is enabled.
+     * There are two ways of using this method:
+     * 1. `isFeatureEnabled("myFeatureFlag")`
+     * 2. `isFeatureEnabled({ myNestedFeatureFlag: "someNestedFlag" })`
+     * We use 1. for top-level feature flags and 2. for nested feature flags. Almost all flags are top-level.
+     * An example of a nested flag is workflows. To use it, you would do:
+     * `isFeatureEnabled({ workflows: Workflows.CreateCart })`
+     * @param flag - The flag to check
+     * @return {boolean} - Whether the flag is enabled or not
+     */
+    isFeatureEnabled(flag: string | string[] | Record<string, string>): boolean;
+    /**
+     * Sets a feature flag.
+     * Flags take two shapes:
+     * `setFlag("myFeatureFlag", true)`
+     * `setFlag("myFeatureFlag", { nestedFlag: true })`
+     * These shapes are used for top-level and nested flags respectively, as explained in isFeatureEnabled.
+     * @param key - The key of the flag to set.
+     * @param value - The value of the flag to set.
+     * @return {void} - void
+     */
+    setFlag(key: string, value: boolean | {
+        [key: string]: boolean;
+    }): void;
+    listFlags(): FeatureFlagTypes.FeatureFlagsResponse;
+}
+export declare const FeatureFlag: FlagRouter;
+//# sourceMappingURL=flag-router.d.ts.map

package/dist/feature-flags/flag-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-router.d.ts","sourceRoot":"","sources":["../../src/feature-flags/flag-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGjD,qBAAa,UAAW,YAAW,gBAAgB,CAAC,WAAW;IAC7D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwD;gBAElE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIpE;;;;;;;;;;OAUG;IACI,gBAAgB,CACrB,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC/C,OAAO;IAkBV;;;;;;;;;OASG;IACI,OAAO,CACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,GAAG;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,GAC1C,IAAI;IAgBA,SAAS,IAAI,gBAAgB,CAAC,oBAAoB;CAM1D;AAED,eAAO,MAAM,WAAW,YAAqB,CAAA"}

package/dist/feature-flags/flag-router.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlag = exports.FlagRouter = void 0;
+const common_1 = require("../common");
+class FlagRouter {
+    constructor(flags) {
+        this.flags = {};
+        this.flags = flags;
+    }
+    /**
+     * Check if a feature flag is enabled.
+     * There are two ways of using this method:
+     * 1. `isFeatureEnabled("myFeatureFlag")`
+     * 2. `isFeatureEnabled({ myNestedFeatureFlag: "someNestedFlag" })`
+     * We use 1. for top-level feature flags and 2. for nested feature flags. Almost all flags are top-level.
+     * An example of a nested flag is workflows. To use it, you would do:
+     * `isFeatureEnabled({ workflows: Workflows.CreateCart })`
+     * @param flag - The flag to check
+     * @return {boolean} - Whether the flag is enabled or not
+     */
+    isFeatureEnabled(flag) {
+        if ((0, common_1.isObject)(flag)) {
+            const [nestedFlag, value] = Object.entries(flag)[0];
+            if (typeof this.flags[nestedFlag] === "boolean") {
+                return this.flags[nestedFlag];
+            }
+            return !!this.flags[nestedFlag]?.[value];
+        }
+        const flags = (Array.isArray(flag) ? flag : [flag]);
+        return flags.every((flag_) => {
+            if (!(0, common_1.isString)(flag_)) {
+                throw Error("Flag must be a string an array of string or an object");
+            }
+            return !!this.flags[flag_];
+        });
+    }
+    /**
+     * Sets a feature flag.
+     * Flags take two shapes:
+     * `setFlag("myFeatureFlag", true)`
+     * `setFlag("myFeatureFlag", { nestedFlag: true })`
+     * These shapes are used for top-level and nested flags respectively, as explained in isFeatureEnabled.
+     * @param key - The key of the flag to set.
+     * @param value - The value of the flag to set.
+     * @return {void} - void
+     */
+    setFlag(key, value) {
+        if ((0, common_1.isObject)(value)) {
+            const existing = this.flags[key];
+            if (!existing) {
+                this.flags[key] = value;
+                return;
+            }
+            this.flags[key] = { ...this.flags[key], ...value };
+            return;
+        }
+        this.flags[key] = value;
+    }
+    listFlags() {
+        return Object.entries(this.flags || {}).map(([key, value]) => ({
+            key,
+            value,
+        }));
+    }
+}
+exports.FlagRouter = FlagRouter;
+exports.FeatureFlag = new FlagRouter({});
+//# sourceMappingURL=flag-router.js.map

package/dist/feature-flags/flag-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-router.js","sourceRoot":"","sources":["../../src/feature-flags/flag-router.ts"],"names":[],"mappings":";;;AACA,sCAA8C;AAE9C,MAAa,UAAU;IAGrB,YAAY,KAAwD;QAFnD,UAAK,GAAsD,EAAE,CAAA;QAG5E,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAED;;;;;;;;;;OAUG;IACI,gBAAgB,CACrB,IAAgD;QAEhD,IAAI,IAAA,iBAAQ,EAAC,IAAI,CAAC,EAAE,CAAC;YACnB,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YACnD,IAAI,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,SAAS,EAAE,CAAC;gBAChD,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAY,CAAA;YAC1C,CAAC;YACD,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC,KAAK,CAAC,CAAA;QAC1C,CAAC;QAED,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAa,CAAA;QAC/D,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YAC3B,IAAI,CAAC,IAAA,iBAAQ,EAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,MAAM,KAAK,CAAC,uDAAuD,CAAC,CAAA;YACtE,CAAC;YACD,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;QAC5B,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;;;;;;;;OASG;IACI,OAAO,CACZ,GAAW,EACX,KAA2C;QAE3C,IAAI,IAAA,iBAAQ,EAAC,KAAK,CAAC,EAAE,CAAC;YACpB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YAEhC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;gBACvB,OAAM;YACR,CAAC;YAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,GAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,EAAE,GAAG,KAAK,EAAE,CAAA;YAC9D,OAAM;QACR,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IACzB,CAAC;IAEM,SAAS;QACd,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7D,GAAG;YACH,KAAK;SACN,CAAC,CAAC,CAAA;IACL,CAAC;CACF;AAzED,gCAyEC;AAEY,QAAA,WAAW,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAA"}

package/dist/feature-flags/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./discover-feature-flags";
+export * from "./discover-and-register-feature-flags";
+export * from "./flag-router";
+export * from "./register-flag";
+//# sourceMappingURL=index.d.ts.map

package/dist/feature-flags/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/feature-flags/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAA;AACxC,cAAc,uCAAuC,CAAA;AACrD,cAAc,eAAe,CAAA;AAC7B,cAAc,iBAAiB,CAAA"}

package/dist/feature-flags/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("./discover-feature-flags"), exports);
+__exportStar(require("./discover-and-register-feature-flags"), exports);
+__exportStar(require("./flag-router"), exports);
+__exportStar(require("./register-flag"), exports);
+//# sourceMappingURL=index.js.map

package/dist/feature-flags/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/feature-flags/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,2DAAwC;AACxC,wEAAqD;AACrD,gDAA6B;AAC7B,kDAA+B"}

package/dist/feature-flags/register-flag.d.ts

@@ -0,0 +1,18 @@
+import { FlagSettings, Logger } from "@acmekit/types";
+import { FlagRouter } from "./flag-router";
+export type RegisterFeatureFlagOptions = {
+    flag: FlagSettings;
+    projectConfigFlags: Record<string, string | boolean | Record<string, boolean>>;
+    router: FlagRouter;
+    logger?: Logger;
+    track?: (key: string) => void;
+};
+/**
+ * Registers a feature flag on the provided router.
+ * Resolving precedence:
+ * - env overrides
+ * - project config overrides
+ * - default value
+ */
+export declare function registerFeatureFlag(options: RegisterFeatureFlagOptions): void;
+//# sourceMappingURL=register-flag.d.ts.map

package/dist/feature-flags/register-flag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-flag.d.ts","sourceRoot":"","sources":["../../src/feature-flags/register-flag.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAQrD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAE1C,MAAM,MAAM,0BAA0B,GAAG;IACvC,IAAI,EAAE,YAAY,CAAA;IAClB,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAC9E,MAAM,EAAE,UAAU,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAC9B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,QAwCtE"}

package/dist/feature-flags/register-flag.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerFeatureFlag = registerFeatureFlag;
+const common_1 = require("../common");
+/**
+ * Registers a feature flag on the provided router.
+ * Resolving precedence:
+ * - env overrides
+ * - project config overrides
+ * - default value
+ */
+function registerFeatureFlag(options) {
+    const { flag, projectConfigFlags, router, logger, track } = options;
+    let value = (0, common_1.isTruthy)(flag.default_val);
+    let from;
+    if ((0, common_1.isDefined)(process.env[flag.env_key])) {
+        from = "environment";
+        const envVal = process.env[flag.env_key];
+        value = (0, common_1.isTruthy)(envVal);
+        const parsedFromEnv = (0, common_1.isString)(envVal) ? envVal.split(",") : [];
+        if (parsedFromEnv.length > 1) {
+            value = (0, common_1.objectFromStringPath)(parsedFromEnv);
+        }
+    }
+    else if ((0, common_1.isDefined)(projectConfigFlags[flag.key])) {
+        from = "project config";
+        const pc = projectConfigFlags[flag.key];
+        value = (0, common_1.isTruthy)(pc);
+        if ((0, common_1.isObject)(projectConfigFlags[flag.key])) {
+            value = projectConfigFlags[flag.key];
+        }
+    }
+    if (logger && from) {
+        logger.info(`Using flag ${flag.env_key} from ${from} with value ${JSON.stringify(value)}`);
+    }
+    if (track && value === true) {
+        track(flag.key);
+    }
+    router.setFlag(flag.key, value);
+}
+//# sourceMappingURL=register-flag.js.map

package/dist/feature-flags/register-flag.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-flag.js","sourceRoot":"","sources":["../../src/feature-flags/register-flag.ts"],"names":[],"mappings":";;AAyBA,kDAwCC;AAhED,sCAMkB;AAWlB;;;;;;GAMG;AACH,SAAgB,mBAAmB,CAAC,OAAmC;IACrE,MAAM,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,OAAO,CAAA;IAEnE,IAAI,KAAK,GAAsC,IAAA,iBAAQ,EAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IACzE,IAAI,IAAwB,CAAA;IAE5B,IAAI,IAAA,kBAAS,EAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACzC,IAAI,GAAG,aAAa,CAAA;QACpB,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAExC,KAAK,GAAG,IAAA,iBAAQ,EAAC,MAAM,CAAC,CAAA;QAExB,MAAM,aAAa,GAAG,IAAA,iBAAQ,EAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;QAC/D,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,KAAK,GAAG,IAAA,6BAAoB,EAAC,aAAa,CAAC,CAAA;QAC7C,CAAC;IACH,CAAC;SAAM,IAAI,IAAA,kBAAS,EAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;QACnD,IAAI,GAAG,gBAAgB,CAAA;QAEvB,MAAM,EAAE,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAqB,CAAA;QAC3D,KAAK,GAAG,IAAA,iBAAQ,EAAC,EAAE,CAAC,CAAA;QAEpB,IAAI,IAAA,iBAAQ,EAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YAC3C,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAA4B,CAAA;QACjE,CAAC;IACH,CAAC;IAED,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;QACnB,MAAM,CAAC,IAAI,CACT,cAAc,IAAI,CAAC,OAAO,SAAS,IAAI,eAAe,IAAI,CAAC,SAAS,CAClE,KAAK,CACN,EAAE,CACJ,CAAA;IACH,CAAC;IAED,IAAI,KAAK,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;AACjC,CAAC"}

package/dist/file/abstract-file-provider.d.ts

@@ -0,0 +1,239 @@
+import { FileTypes, IFileProvider } from "@acmekit/types";
+import type { Readable, Writable } from "stream";
+/**
+ * ### constructor
+ *
+ * The constructor allows you to access resources from the module's container using the first parameter,
+ * and the module's options using the second parameter.
+ *
+ * If you're creating a client or establishing a connection with a third-party service, do it in the constructor.
+ *
+ * #### Example
+ *
+ * ```ts
+ * import { Logger } from "@acmekit/framework/types"
+ * import { AbstractFileProviderService } from "@acmekit/framework/utils"
+ *
+ * type InjectedDependencies = {
+ *   logger: Logger
+ * }
+ *
+ * type Options = {
+ *   apiKey: string
+ * }
+ *
+ * class MyFileProviderService extends AbstractFileProviderService {
+ *   protected logger_: Logger
+ *   protected options_: Options
+ *   static identifier = "my-file"
+ *   // assuming you're initializing a client
+ *   protected client
+ *
+ *   constructor (
+ *     { logger }: InjectedDependencies,
+ *     options: Options
+ *   ) {
+ *     super()
+ *
+ *     this.logger_ = logger
+ *     this.options_ = options
+ *
+ *     // assuming you're initializing a client
+ *     this.client = new Client(options)
+ *   }
+ * }
+ *
+ * export default MyFileProviderService
+ * ```
+ */
+export declare class AbstractFileProviderService implements IFileProvider {
+    /**
+     * Each file provider has a unique ID used to identify it. The provider's ID
+     * will be stored as `fs_{identifier}_{id}`, where `{id}` is the provider's `id`
+     * property in the `acmekit-config.ts`.
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   static identifier = "my-file"
+     *   // ...
+     * }
+     */
+    static identifier: string;
+    /**
+     * This method validates the options of the provider set in `acmekit-config.ts`.
+     * Implementing this method is optional. It's useful if your provider requires custom validation.
+     *
+     * If the options aren't valid, throw an error.
+     *
+     * @param options - The provider's options.
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   static validateOptions(options: Record<any, any>) {
+     *     if (!options.apiKey) {
+     *       throw new AcmeKitError(
+     *         AcmeKitError.Types.INVALID_DATA,
+     *         "API key is required in the provider's options."
+     *       )
+     *     }
+     *   }
+     * }
+     */
+    static validateOptions(options: Record<any, any>): void | never;
+    /**
+     * @ignore
+     */
+    getIdentifier(): any;
+    /**
+     * This method uploads a file using your provider's custom logic. In this method, you can upload the file
+     * into your provider's storage, and return the uploaded file's details.
+     *
+     * This method will be used when uploading product images, CSV files for imports, or other
+     * custom file uploads.
+     *
+     * @param {FileTypes.ProviderUploadFileDTO} file - The file to upload.
+     * @returns {Promise<FileTypes.ProviderFileResultDTO>} The uploaded file's details.
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   // ...
+     *   async upload(
+     *     file: ProviderUploadFileDTO
+     *   ): Promise<ProviderFileResultDTO> {
+     *     // TODO upload file to third-party provider
+     *     // or using custom logic
+     *     // for example:
+     *     this.client.upload(file)
+     *
+     *     return {
+     *       url: "some-url.com",
+     *       key: "file-name-or-id"
+     *     }
+     *   }
+     * }
+     */
+    upload(file: FileTypes.ProviderUploadFileDTO): Promise<FileTypes.ProviderFileResultDTO>;
+    /**
+     * This method deletes one or more files from the storage. It's used when an admin user
+     * deletes a product image, or other custom file deletions.
+     *
+     * @param {FileTypes.ProviderDeleteFileDTO | FileTypes.ProviderDeleteFileDTO[]} files - The details of the files to delete.
+     * @returns {Promise<void>} Resolves when the files are deleted.
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   // ...
+     *   async delete(
+     *     files: FileTypes.ProviderDeleteFileDTO | FileTypes.ProviderDeleteFileDTO[]
+     *   ): Promise<void> {
+     *     // TODO logic to remove the file from storage
+     *     // Use the `file.fileKey` to delete the file, which is the identifier of the file
+     *    // in the provider's storage.
+     *     // for example:
+     *     const fileArray = Array.isArray(files) ? files : [files]
+     *     for (const file of fileArray) {
+     *       this.client.delete(file.fileKey)
+     *     }
+     *   }
+     * }
+     */
+    delete(files: FileTypes.ProviderDeleteFileDTO | FileTypes.ProviderDeleteFileDTO[]): Promise<void>;
+    /**
+     * This method is used to retrieve a download URL of the file. For some providers,
+     * such as S3, a presigned URL indicates a temporary URL to get access to a file.
+     *
+     * If your provider doesn’t perform or offer a similar functionality, you can
+     * return the URL to download the file.
+     *
+     * @param {FileTypes.ProviderGetFileDTO} fileData - The details of the file to get its
+     * presigned URL.
+     * @returns {Promise<string>} The file's presigned URL.
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   // ...
+     *   async getPresignedDownloadUrl(
+     *     fileData: ProviderGetFileDTO
+     *   ): Promise<string> {
+     *     // TODO logic to get the presigned URL
+     *     // Use the `file.fileKey` to delete the file, which is the identifier of the file
+     *    // in the provider's storage.
+     *     // for example:
+     *     return this.client.getPresignedUrl(fileData.fileKey)
+     *   }
+     * }
+     */
+    getPresignedDownloadUrl(fileData: FileTypes.ProviderGetFileDTO): Promise<string>;
+    /**
+     * This method retrieves an uploaded file as a stream. This is useful when streaming
+     * a file to clients or you want to process the file in chunks.
+     *
+     * @param {FileTypes.ProviderGetFileDTO} fileData - The details of the file to get its stream.
+     * @returns {Promise<Readable>} The file's stream.
+     *
+     * @since 2.8.0
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   // ...
+     *   async getAsStream(file: ProviderDeleteFileDTO): Promise<Readable> {
+     *    // TODO logic to get the file as a stream
+     *    // Use the `file.fileKey` to get the file, which is the identifier of the file
+     *    // in the provider's storage.
+     *    // for example:
+     *     this.client.getAsStream(file.fileKey)
+     *   }
+     * }
+     */
+    getDownloadStream(fileData: FileTypes.ProviderGetFileDTO): Promise<Readable>;
+    /**
+     * This method retrieves an uploaded file as a buffer. This is useful when you want to
+     * process the entire file in memory or send it as a response.
+     *
+     * @param {FileTypes.ProviderGetFileDTO} fileData - The details of the file to get its buffer.
+     * @returns {Promise<Buffer>} The file's buffer.
+     *
+     * @since 2.8.0
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   // ...
+     *   async getAsBuffer(file: ProviderDeleteFileDTO): Promise<Buffer> {
+     *     // TODO logic to get the file as a buffer
+     *     // Use the `file.fileKey` to get the file, which is the identifier of the file
+     *     // in the provider's storage.
+     *     // for example:
+     *     this.client.getAsBuffer(file.fileKey)
+     *   }
+     * }
+     */
+    getAsBuffer(fileData: FileTypes.ProviderGetFileDTO): Promise<Buffer>;
+    /**
+     * This method returns a writeable stream to upload a file.
+     *
+     * @param {FileTypes.ProviderUploadStreamDTO} fileData - The details of the file to upload.
+     * @returns {Promise<{ writeStream: Writable, promise: Promise<FileTypes.ProviderFileResultDTO>, url: string, fileKey: string }>} The writeable stream and upload promise.
+     *
+     * @since 2.8.0
+     *
+     * @example
+     * class MyFileProviderService extends AbstractFileProviderService {
+     *   // ...
+     *   async getUploadStream(fileData: FileTypes.ProviderUploadStreamDTO): Promise<{
+     *     writeStream: Writable
+     *     promise: Promise<FileTypes.ProviderFileResultDTO>
+     *     url: string
+     *     fileKey: string
+     *   }> {
+     *     // TODO logic to get the writeable stream
+     *   }
+     * }
+     */
+    getUploadStream(fileData: FileTypes.ProviderUploadStreamDTO): Promise<{
+        writeStream: Writable;
+        promise: Promise<FileTypes.ProviderFileResultDTO>;
+        url: string;
+        fileKey: string;
+    }>;
+}
+//# sourceMappingURL=abstract-file-provider.d.ts.map

package/dist/file/abstract-file-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract-file-provider.d.ts","sourceRoot":"","sources":["../../src/file/abstract-file-provider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,2BAA4B,YAAW,aAAa;IAC/D;;;;;;;;;;OAUG;IACH,MAAM,CAAC,UAAU,EAAE,MAAM,CAAA;IAEzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,KAAK;IAE/D;;OAEG;IACH,aAAa;IAIb;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,MAAM,CACV,IAAI,EAAE,SAAS,CAAC,qBAAqB,GACpC,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC;IAI3C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,MAAM,CACV,KAAK,EAAE,SAAS,CAAC,qBAAqB,GAAG,SAAS,CAAC,qBAAqB,EAAE,GACzE,OAAO,CAAC,IAAI,CAAC;IAIhB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,uBAAuB,CAC3B,QAAQ,EAAE,SAAS,CAAC,kBAAkB,GACrC,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CAAC,QAAQ,EAAE,SAAS,CAAC,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,eAAe,CAAC,QAAQ,EAAE,SAAS,CAAC,uBAAuB,GAAG,OAAO,CAAC;QACpE,WAAW,EAAE,QAAQ,CAAA;QACrB,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,qBAAqB,CAAC,CAAA;QACjD,GAAG,EAAE,MAAM,CAAA;QACX,OAAO,EAAE,MAAM,CAAA;KAChB,CAAC;CAGH"}