@venizia/ignis-helpers 0.2.0-2 → 0.2.0-21

package/dist/cjs/modules/storage/common/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/common/constants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,SAAS,EAAE,MAAM,UAAU,CAAC;AAEpD,+FAA+F;AAC/F,qBAAa,sBAAsB;IACjC,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,SAAS,CAA6C;IACtF,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,SAAS,CAA4C;CACtF;AAED,kEAAkE;AAClE,qBAAa,oBAAoB;IAC/B,MAAM,CAAC,QAAQ,CAAC,sBAAsB,SAAoB;CAC3D;AAED,sFAAsF;AACtF,qBAAa,kBAAkB;IAC7B,MAAM,CAAC,QAAQ,CAAC,aAAa,MAAM;CACpC"}

package/dist/cjs/modules/storage/common/constants.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageConcurrency = exports.StoragePresignLimits = exports.StoragePresignDefaults = void 0;
+const common_1 = require("../../../common");
+/** Presign expiry defaults - a PUT carries a file and needs more time; a GET is a redirect. */
+class StoragePresignDefaults {
+    static { this.PUT_EXPIRES_IN = { unit: common_1.DurationUnits.MINUTE, value: 10 }; }
+    static { this.GET_EXPIRES_IN = { unit: common_1.DurationUnits.MINUTE, value: 1 }; }
+}
+exports.StoragePresignDefaults = StoragePresignDefaults;
+/** SigV4 refuses a presigned URL valid for longer than 7 days. */
+class StoragePresignLimits {
+    static { this.MAX_EXPIRES_IN_SECONDS = 7 * 24 * 60 * 60; }
+}
+exports.StoragePresignLimits = StoragePresignLimits;
+/** Concurrent object operations. Unbounded exhausts sockets and gets rate limited. */
+class StorageConcurrency {
+    static { this.DEFAULT_LIMIT = 16; }
+}
+exports.StorageConcurrency = StorageConcurrency;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/modules/storage/common/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../../../src/modules/storage/common/constants.ts"],"names":[],"mappings":";;;AAAA,qCAAoD;AAEpD,+FAA+F;AAC/F,MAAa,sBAAsB;aACjB,mBAAc,GAAc,EAAE,IAAI,EAAE,sBAAa,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;aACtE,mBAAc,GAAc,EAAE,IAAI,EAAE,sBAAa,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;;AAFvF,wDAGC;AAED,kEAAkE;AAClE,MAAa,oBAAoB;aACf,2BAAsB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;;AAD5D,oDAEC;AAED,sFAAsF;AACtF,MAAa,kBAAkB;aACb,kBAAa,GAAG,EAAE,CAAC;;AADrC,gDAEC"}

package/dist/cjs/modules/storage/common/errors.d.ts

@@ -0,0 +1,22 @@
+import type { TRegisterErrors } from '@venizia/ignis-inversion';
+/** Codes a caller branches on for a storage failure that is the request's fault, not the backend's. */
+export declare const StorageErrors: {
+    readonly OBJECT_NOT_FOUND: {
+        readonly message: {
+            readonly text: "Object not found";
+            readonly code: "core.storage.object_not_found";
+        };
+        readonly statusCode: 404;
+        readonly category: "business";
+    };
+};
+/** Augments inversion, not helpers: TS only treats this as an augmentation when the file imports that module. */
+declare module '@venizia/ignis-inversion' {
+    interface IErrorKeyRegistry extends TRegisterErrors<typeof StorageErrors> {
+    }
+}
+/** "Not there", across SDKs. Both minio and Bun report `S3Error` in `name`, so `code` and status decide. */
+export declare const isNotFoundError: (opts: {
+    error: unknown;
+}) => boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/cjs/modules/storage/common/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/common/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAoB,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAIlF,uGAAuG;AACvG,eAAO,MAAM,aAAa;;;;;;;;;CAM2B,CAAC;AAEtD,iHAAiH;AACjH,OAAO,QAAQ,0BAA0B,CAAC;IACxC,UAAU,iBAAkB,SAAQ,eAAe,CAAC,OAAO,aAAa,CAAC;KAAG;CAC7E;AAED,4GAA4G;AAC5G,eAAO,MAAM,eAAe,GAAI,MAAM;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,KAAG,OAW1D,CAAC"}

package/dist/cjs/modules/storage/common/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isNotFoundError = exports.StorageErrors = void 0;
+const ignis_inversion_1 = require("@venizia/ignis-inversion");
+const constants_1 = require("../../../common/constants");
+/** Codes a caller branches on for a storage failure that is the request's fault, not the backend's. */
+exports.StorageErrors = {
+    OBJECT_NOT_FOUND: {
+        message: { text: 'Object not found', code: 'core.storage.object_not_found' },
+        statusCode: constants_1.HTTP.ResultCodes.RS_4.NotFound,
+        category: ignis_inversion_1.ErrorScopes.BUSINESS,
+    },
+};
+/** "Not there", across SDKs. Both minio and Bun report `S3Error` in `name`, so `code` and status decide. */
+const isNotFoundError = (opts) => {
+    const { error } = opts;
+    const source = error;
+    if (source?.statusCode === constants_1.HTTP.ResultCodes.RS_4.NotFound || source?.status === 404) {
+        return true;
+    }
+    const marker = `${source?.code ?? ''} ${source?.name ?? ''}`.toLowerCase();
+    return ['nosuchkey', 'nosuchbucket', 'notfound'].some(needle => marker.includes(needle));
+};
+exports.isNotFoundError = isNotFoundError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/modules/storage/common/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../../../../src/modules/storage/common/errors.ts"],"names":[],"mappings":";;;AACA,8DAAuD;AACvD,kDAA0C;AAE1C,uGAAuG;AAC1F,QAAA,aAAa,GAAG;IAC3B,gBAAgB,EAAE;QAChB,OAAO,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,+BAA+B,EAAE;QAC5E,UAAU,EAAE,gBAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ;QAC1C,QAAQ,EAAE,6BAAW,CAAC,QAAQ;KAC/B;CACkD,CAAC;AAOtD,4GAA4G;AACrG,MAAM,eAAe,GAAG,CAAC,IAAwB,EAAW,EAAE;IACnE,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACvB,MAAM,MAAM,GAAG,KAA+E,CAAC;IAE/F,IAAI,MAAM,EAAE,UAAU,KAAK,gBAAI,CAAC,WAAW,CAAC,IAAI,CAAC,QAAQ,IAAI,MAAM,EAAE,MAAM,KAAK,GAAG,EAAE,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,MAAM,EAAE,IAAI,IAAI,EAAE,IAAI,MAAM,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,WAAW,EAAE,CAAC;IAE3E,OAAO,CAAC,WAAW,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;AAC3F,CAAC,CAAC;AAXW,QAAA,eAAe,mBAW1B"}

package/dist/cjs/modules/storage/common/index.d.ts

@@ -0,0 +1,5 @@
+export * from './constants';
+export * from './errors';
+export * from './types';
+export * from './utility';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/modules/storage/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/cjs/modules/storage/common/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("./constants"), exports);
+__exportStar(require("./errors"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utility"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/modules/storage/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/modules/storage/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,8CAA4B;AAC5B,2CAAyB;AACzB,0CAAwB;AACxB,4CAA0B"}

package/dist/cjs/modules/storage/common/types.d.ts

@@ -0,0 +1,153 @@
+import { IDuration } from '../../../common';
+import { Readable } from 'node:stream';
+export interface IUploadFile {
+    originalName: string;
+    mimetype: string;
+    buffer: Buffer;
+    size: number;
+    encoding?: string;
+    folderPath?: string;
+    [key: string | symbol]: any;
+}
+/** `metaLink` is a union: the old pair allowed both present, or neither. */
+export interface IUploadResult {
+    bucket: IBucketRef;
+    object: IObjectRef & {
+        size: number;
+        contentType: string;
+    };
+    link: string;
+    metaLink?: {
+        data: any;
+    } | {
+        error: string;
+    };
+}
+/** `mimetype` is named because consumers persist it; `any` let it be renamed silently. */
+export interface IObjectMetadata {
+    mimetype?: string;
+    [key: string]: any;
+}
+export interface IFileStat {
+    size: number;
+    metadata: IObjectMetadata;
+    lastModified?: Date;
+    etag?: string;
+    versionId?: string;
+}
+export interface IBucketInfo {
+    name: string;
+    creationDate: Date;
+}
+export interface IObjectInfo {
+    name?: string;
+    size?: number;
+    lastModified?: Date;
+    etag?: string;
+    prefix?: string;
+}
+/** One bucket. */
+export interface IBucketRef {
+    name: string;
+}
+/** The parts of an upload a naming hook needs; `IUploadFile` already declares both. */
+export type TUploadNaming = Pick<IUploadFile, 'originalName' | 'folderPath'>;
+/** One object. `key` is the S3 term. */
+export interface IObjectRef {
+    key: string;
+}
+/** Which bucket, which object. */
+export interface IObjectLocation {
+    bucket: IBucketRef;
+    object: IObjectRef;
+}
+export interface IListObjectsOptions {
+    bucket: IBucketRef;
+    prefix?: string;
+    useRecursive?: boolean;
+    maxKeys?: number;
+}
+export interface IStorageHelperOptions {
+    scope?: string;
+    identifier?: string;
+}
+export interface IStorageHelper {
+    isValidSegment(opts: {
+        segment: string;
+    }): boolean;
+    isValidBucketName(opts: {
+        bucket: IBucketRef;
+    }): boolean;
+    isValidObjectKey(opts: {
+        object: IObjectRef;
+        maxDepth?: number;
+    }): boolean;
+    hasBucket(opts: {
+        bucket: IBucketRef;
+    }): Promise<boolean>;
+    getBuckets(): Promise<IBucketInfo[]>;
+    getBucket(opts: {
+        bucket: IBucketRef;
+    }): Promise<IBucketInfo | null>;
+    createBucket(opts: {
+        bucket: IBucketRef;
+    }): Promise<IBucketInfo | null>;
+    removeBucket(opts: {
+        bucket: IBucketRef;
+    }): Promise<boolean>;
+    getObject(opts: IObjectLocation & {
+        options?: any;
+    }): Promise<Readable>;
+    /** A web stream, what a `Response` body wants. `range` includes `end`, like the HTTP header. */
+    getObjectStream(opts: IObjectLocation & {
+        range?: {
+            start: number;
+            end?: number;
+        };
+    }): Promise<ReadableStream<Uint8Array>>;
+    getStat(opts: IObjectLocation): Promise<IFileStat>;
+    listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;
+    upload(opts: {
+        bucket: IBucketRef;
+        files: IUploadFile[];
+        maxFolderDepth?: number;
+        normalizeNameFn?: (opts: {
+            file: TUploadNaming;
+        }) => string;
+        normalizeLinkFn?: (opts: IObjectLocation) => string;
+    }): Promise<IUploadResult[]>;
+    /**
+     * Writes an object from a stream, so a large body never lands in this process. A backend whose
+     * transport takes a stream overrides it; the default buffers, which is the thing to avoid.
+     */
+    writeStream(opts: IObjectLocation & {
+        source: ReadableStream<Uint8Array> | Blob | Response | Request;
+        contentType?: string;
+        /** Folder nesting the key may carry, as `upload` takes it. Omitted -> DEFAULT_MAX_FOLDER_DEPTH. */
+        maxFolderDepth?: number;
+    }): Promise<void>;
+    removeObject(opts: IObjectLocation): Promise<void>;
+    removeObjects(opts: {
+        bucket: IBucketRef;
+        objects: IObjectRef[];
+    }): Promise<void>;
+    presignPut(opts: IObjectLocation & {
+        expiresIn?: IDuration;
+    }): Promise<string>;
+    presignGet(opts: IObjectLocation & {
+        expiresIn?: IDuration;
+        responseContentType?: string;
+        responseContentDisposition?: string;
+    }): Promise<string>;
+    getObjectTags(opts: IObjectLocation): Promise<Record<string, string>>;
+    replaceObjectTags(opts: IObjectLocation & {
+        tags: Record<string, string>;
+    }): Promise<void>;
+    getMediaType(opts: {
+        mimeType: string;
+    }): string;
+    getMimeType(opts: {
+        filename: string;
+    }): string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/modules/storage/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/common/types.ts"],"names":[],"mappings":"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"}

package/dist/cjs/modules/storage/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/modules/storage/common/types.ts"],"names":[],"mappings":""}

package/dist/cjs/modules/storage/common/utility.d.ts

@@ -0,0 +1,7 @@
+import { IDuration } from '../../../common';
+/** S3 presigns in whole seconds. An unknown unit is refused; `null` would read as "no expiry". */
+export declare const toExpirySeconds: (opts: {
+    expiresIn: IDuration;
+    operation: string;
+}) => number;
+//# sourceMappingURL=utility.d.ts.map

package/dist/cjs/modules/storage/common/utility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/common/utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1D,kGAAkG;AAClG,eAAO,MAAM,eAAe,GAAI,MAAM;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,MAqBnF,CAAC"}

package/dist/cjs/modules/storage/common/utility.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toExpirySeconds = void 0;
+const common_1 = require("../../../common");
+const error_1 = require("../../error");
+const constants_1 = require("./constants");
+/** S3 presigns in whole seconds. An unknown unit is refused; `null` would read as "no expiry". */
+const toExpirySeconds = (opts) => {
+    const { expiresIn, operation } = opts;
+    const milliseconds = common_1.DurationMultipliers.toMilliseconds(expiresIn);
+    if (milliseconds === null || milliseconds <= 0) {
+        throw (0, error_1.getError)({
+            message: `[${operation}] Invalid expiry | unit: ${expiresIn?.unit} | value: ${expiresIn?.value}`,
+        });
+    }
+    const seconds = Math.ceil(milliseconds / common_1.DurationMultipliers.SECOND);
+    // SigV4 caps a presigned URL at 7 days. `IDuration` accepts `month` and `year`, which type-check
+    // and then produce a URL the provider rejects - refused here, where the unit is still readable.
+    if (seconds > constants_1.StoragePresignLimits.MAX_EXPIRES_IN_SECONDS) {
+        throw (0, error_1.getError)({
+            message: `[${operation}] Expiry exceeds the SigV4 maximum of 7 days | unit: ${expiresIn.unit} | value: ${expiresIn.value}`,
+        });
+    }
+    return seconds;
+};
+exports.toExpirySeconds = toExpirySeconds;
+//# sourceMappingURL=utility.js.map

package/dist/cjs/modules/storage/common/utility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility.js","sourceRoot":"","sources":["../../../../../src/modules/storage/common/utility.ts"],"names":[],"mappings":";;;AAAA,qCAA0D;AAC1D,2CAA2C;AAC3C,2CAAmD;AAEnD,kGAAkG;AAC3F,MAAM,eAAe,GAAG,CAAC,IAAiD,EAAU,EAAE;IAC3F,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IACtC,MAAM,YAAY,GAAG,4BAAmB,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAEnE,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAA,gBAAQ,EAAC;YACb,OAAO,EAAE,IAAI,SAAS,4BAA4B,SAAS,EAAE,IAAI,aAAa,SAAS,EAAE,KAAK,EAAE;SACjG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,4BAAmB,CAAC,MAAM,CAAC,CAAC;IAErE,iGAAiG;IACjG,gGAAgG;IAChG,IAAI,OAAO,GAAG,gCAAoB,CAAC,sBAAsB,EAAE,CAAC;QAC1D,MAAM,IAAA,gBAAQ,EAAC;YACb,OAAO,EAAE,IAAI,SAAS,wDAAwD,SAAS,CAAC,IAAI,aAAa,SAAS,CAAC,KAAK,EAAE;SAC3H,CAAC,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AArBW,QAAA,eAAe,mBAqB1B"}

package/dist/cjs/modules/storage/disk/helper.d.ts

@@ -1,7 +1,8 @@
 import { Readable } from 'node:stream';
 import { BaseStorageHelper } from '../base';
-import { IBucketInfo, IFileStat, IObjectInfo, IStorageHelperOptions, IUploadFile } from '../types';
+import { IBucketInfo, IBucketRef, IFileStat, IListObjectsOptions, IObjectInfo, IObjectLocation, IObjectRef, IStorageHelperOptions, IUploadFile } from '../common';
 export interface IDiskHelperOptions extends IStorageHelperOptions {
+    /** Base directory every bucket lives under. */
     basePath: string;
 }
 export declare class DiskHelper extends BaseStorageHelper {
@@ -9,48 +10,45 @@ export declare class DiskHelper extends BaseStorageHelper {
     constructor(options: IDiskHelperOptions);
     private getBucketPath;
     private getObjectPath;
+    /** Validates the name AND the resolved path: containment survives a naming rule we get wrong. */
+    private resolveObjectPath;
+    /** `null` means not there. Anything but ENOENT is logged: it may exist and be unreadable. */
+    private statOrNull;
     private exists;
-    isBucketExists(opts: {
-        name: string;
+    /** One `stat` answers existence and type. */
+    hasBucket(opts: {
+        bucket: IBucketRef;
     }): Promise<boolean>;
     getBuckets(): Promise<IBucketInfo[]>;
     getBucket(opts: {
-        name: string;
+        bucket: IBucketRef;
     }): Promise<IBucketInfo | null>;
     createBucket(opts: {
-        name: string;
+        bucket: IBucketRef;
     }): Promise<IBucketInfo | null>;
     removeBucket(opts: {
-        name: string;
+        bucket: IBucketRef;
     }): Promise<boolean>;
     protected get defaultLinkPrefix(): string;
-    protected writeObject(opts: {
-        bucket: string;
-        normalizeName: string;
+    protected writeObject(opts: IObjectLocation & {
         file: IUploadFile;
     }): Promise<void>;
-    getFile(opts: {
-        bucket: string;
-        name: string;
+    getObject(opts: IObjectLocation & {
         options?: any;
     }): Promise<Readable>;
-    getStat(opts: {
-        bucket: string;
-        name: string;
-    }): Promise<IFileStat>;
-    removeObject(opts: {
-        bucket: string;
-        name: string;
-    }): Promise<void>;
+    /** `createReadStream` seeks natively, so a range never reads the bytes before it. */
+    getObjectStream(opts: IObjectLocation & {
+        range?: {
+            start: number;
+            end?: number;
+        };
+    }): Promise<ReadableStream<Uint8Array>>;
+    getStat(opts: IObjectLocation): Promise<IFileStat>;
+    removeObject(opts: IObjectLocation): Promise<void>;
     removeObjects(opts: {
-        bucket: string;
-        names: string[];
+        bucket: IBucketRef;
+        objects: IObjectRef[];
     }): Promise<void>;
-    listObjects(opts: {
-        bucket: string;
-        prefix?: string;
-        useRecursive?: boolean;
-        maxKeys?: number;
-    }): Promise<IObjectInfo[]>;
+    listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;
 }
 //# sourceMappingURL=helper.d.ts.map

package/dist/cjs/modules/storage/disk/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/disk/helper.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAEnG,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAW,SAAQ,iBAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,kBAAkB;IAYvC,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;YAIP,MAAM;IAkBd,cAAc,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAexD,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAsBpC,SAAS,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAgB9D,YAAY,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAoBjE,YAAY,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B5D,SAAS,KAAK,iBAAiB,IAAI,MAAM,CAExC;cAEe,WAAW,CAAC,IAAI,EAAE;QAChC,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,WAAW,CAAC;KACnB,GAAG,OAAO,CAAC,IAAI,CAAC;IAaX,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAajF,OAAO,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAqBnE,YAAY,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAanE,aAAa,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvE,WAAW,CAAC,IAAI,EAAE;QACtB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,OAAO,CAAC;QACvB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAoD3B"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../../../src/modules/storage/disk/helper.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,WAAW,EACX,UAAU,EACV,SAAS,EACT,mBAAmB,EACnB,WAAW,EACX,eAAe,EACf,UAAU,EACV,qBAAqB,EACrB,WAAW,EAEZ,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,UAAW,SAAQ,iBAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,kBAAkB;IAYvC,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,aAAa;IAIrB,iGAAiG;IACjG,OAAO,CAAC,iBAAiB;IAqBzB,6FAA6F;YAC/E,UAAU;YAkBV,MAAM;IAIpB,6CAA6C;IACvC,SAAS,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IASzD,UAAU,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAsBpC,SAAS,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAgBpE,YAAY,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAqBvE,YAAY,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BlE,SAAS,KAAK,iBAAiB,IAAI,MAAM,CAExC;cAEe,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASnF,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG;QAAE,OAAO,CAAC,EAAE,GAAG,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAc7E,qFAAqF;IACtE,eAAe,CAC5B,IAAI,EAAE,eAAe,GAAG;QAAE,KAAK,CAAC,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,GAAG,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAClE,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAmBhC,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,CAAC;IAqBlD,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAelD,aAAa,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,UAAU,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASjF,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;CAiErE"}