@venizia/ignis-helpers 0.2.0-8 → 0.2.0

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

@@ -0,0 +1,180 @@
+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;
+}
+/** What `presignPost` hands a browser: where to post, the fields to post with it, and when the grant dies. */
+export interface IPostPolicy {
+    postURL: string;
+    formData: Record<string, string>;
+    expiresAt: string;
+}
+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>;
+    /** Copies within one bucket, server side - the bytes never travel through this process. */
+    copyObject(opts: {
+        bucket: IBucketRef;
+        source: IObjectRef;
+        destination: IObjectRef;
+    }): Promise<void>;
+    removeObject(opts: IObjectLocation): Promise<void>;
+    removeObjects(opts: {
+        bucket: IBucketRef;
+        objects: IObjectRef[];
+    }): Promise<void>;
+    /** The form a browser posts straight to the storage. Unlike a presigned PUT, a policy carries `content-length-range`, so "at most N bytes" is expressible - a signed PUT binds the length to one exact value. */
+    presignPost(opts: {
+        bucket: IBucketRef;
+        keyPrefix: string;
+        maxBytes: number;
+        contentType?: string;
+        expiresIn?: IDuration;
+    }): Promise<IPostPolicy>;
+    /** A URL a browser may PUT one object to. Every extra option below is SIGNED - the client must send it back unchanged. A pinned size is exact, never a ceiling; for a ceiling use {@link IStorageHelper.presignPost}. */
+    presignPut(opts: IObjectLocation & {
+        expiresIn?: IDuration;
+        /** The object's tag set, written at the moment it is stored. */
+        tagging?: Record<string, string>;
+        /** Pins the body to EXACTLY this many bytes. A retry at a different size is refused. */
+        contentLength?: number;
+        /** Pins the stored content type. Unsigned, the uploader picks what is stored - and the stored type is what a browser later renders. */
+        contentType?: string;
+    }): 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"}

package/dist/cjs/modules/storage/disk/helper.js

@@ -4,12 +4,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DiskHelper = void 0;
-const error_1 = require("../../../modules/error");
-const logger_1 = require("../../../modules/logger");
+const error_1 = require("../../error");
+const logger_1 = require("../../logger");
 const node_fs_1 = __importDefault(require("node:fs"));
 const promises_1 = __importDefault(require("node:fs/promises"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_stream_1 = require("node:stream");
 const base_1 = require("../base");
+const common_1 = require("../common");
 class DiskHelper extends base_1.BaseStorageHelper {
     constructor(options) {
         super({
@@ -21,39 +23,54 @@ class DiskHelper extends base_1.BaseStorageHelper {
             node_fs_1.default.mkdirSync(this.basePath, { recursive: true });
         }
     }
-    getBucketPath(bucketName) {
-        return node_path_1.default.join(this.basePath, bucketName);
+    getBucketPath(opts) {
+        return node_path_1.default.join(this.basePath, opts.bucket.name);
     }
-    getObjectPath(bucketName, objectName) {
-        return node_path_1.default.join(this.getBucketPath(bucketName), objectName);
+    getObjectPath(opts) {
+        return node_path_1.default.join(this.getBucketPath({ bucket: opts.bucket }), opts.object.key);
     }
-    async exists(pathToCheck) {
+    /** Validates the name AND the resolved path: containment survives a naming rule we get wrong. */
+    resolveObjectPath(opts) {
+        const { bucket, object } = opts;
+        if (!this.isValidBucketName({ bucket })) {
+            throw (0, error_1.getError)({ message: `[storage] Invalid bucket name | bucket: ${bucket.name}` });
+        }
+        if (!this.isValidObjectKey({ object, maxDepth: Number.MAX_SAFE_INTEGER })) {
+            throw (0, error_1.getError)({ message: `[storage] Invalid object name | key: ${object.key}` });
+        }
+        const bucketPath = this.getBucketPath({ bucket });
+        const objectPath = node_path_1.default.resolve(bucketPath, object.key);
+        if (objectPath !== bucketPath && !objectPath.startsWith(`${bucketPath}${node_path_1.default.sep}`)) {
+            throw (0, error_1.getError)({ message: `[storage] Invalid object name | key: ${object.key}` });
+        }
+        return objectPath;
+    }
+    /** `null` means not there. Anything but ENOENT is logged: it may exist and be unreadable. */
+    async statOrNull(opts) {
+        const { target } = opts;
         try {
-            await promises_1.default.access(pathToCheck);
-            return true;
+            return await promises_1.default.stat(target);
         }
         catch (error) {
-            // ENOENT is the answer, not a failure; EACCES/EIO mean the path may well exist and is unreadable.
             if (error?.code !== 'ENOENT') {
-                this.logger.warn('[exists] Cannot determine existence, reporting false | path: %s | %s', pathToCheck, logger_1.ErrorPrettier.format({ error }));
+                this.logger.warn('[statOrNull] Cannot determine existence, reporting missing | path: %s | %s', target, logger_1.ErrorPrettier.format({ error }));
             }
-            return false;
+            return null;
         }
     }
-    async isBucketExists(opts) {
-        const { name } = opts;
-        if (!this.isValidName(name)) {
-            return false;
-        }
-        const bucketPath = this.getBucketPath(name);
-        if (!(await this.exists(bucketPath))) {
+    async exists(opts) {
+        return (await this.statOrNull(opts)) !== null;
+    }
+    /** One `stat` answers existence and type. */
+    async hasBucket(opts) {
+        if (!this.isValidBucketName(opts)) {
             return false;
         }
-        const stat = await promises_1.default.stat(bucketPath);
-        return stat.isDirectory();
+        const stat = await this.statOrNull({ target: this.getBucketPath(opts) });
+        return stat?.isDirectory() ?? false;
     }
     async getBuckets() {
-        if (!(await this.exists(this.basePath))) {
+        if (!(await this.exists({ target: this.basePath }))) {
             return [];
         }
         const entries = await promises_1.default.readdir(this.basePath, { withFileTypes: true });
@@ -71,43 +88,41 @@ class DiskHelper extends base_1.BaseStorageHelper {
         return buckets;
     }
     async getBucket(opts) {
-        const { name } = opts;
-        const isExists = await this.isBucketExists(opts);
-        if (!isExists) {
+        const { name } = opts.bucket;
+        if (!this.isValidBucketName(opts)) {
             return null;
         }
-        const bucketPath = this.getBucketPath(name);
-        const stat = await promises_1.default.stat(bucketPath);
-        return {
-            name,
-            creationDate: stat.birthtime,
-        };
+        const stat = await this.statOrNull({ target: this.getBucketPath(opts) });
+        if (!stat?.isDirectory()) {
+            return null;
+        }
+        return { name, creationDate: stat.birthtime };
     }
     async createBucket(opts) {
-        const { name } = opts;
-        if (!this.isValidName(name)) {
+        const { name } = opts.bucket;
+        if (!this.isValidBucketName(opts)) {
             throw (0, error_1.getError)({
                 message: '[createBucket] Invalid name to create bucket!',
             });
         }
-        const bucketPath = this.getBucketPath(name);
-        if (await this.exists(bucketPath)) {
+        const bucketPath = this.getBucketPath(opts);
+        if (await this.exists({ target: bucketPath })) {
             throw (0, error_1.getError)({
                 message: `[createBucket] Bucket already exists | name: ${name}`,
             });
         }
         await promises_1.default.mkdir(bucketPath, { recursive: true });
-        return this.getBucket({ name });
+        return this.getBucket(opts);
     }
     async removeBucket(opts) {
-        const { name } = opts;
-        if (!this.isValidName(name)) {
+        const { name } = opts.bucket;
+        if (!this.isValidBucketName(opts)) {
             throw (0, error_1.getError)({
                 message: '[removeBucket] Invalid name to remove bucket!',
             });
         }
-        const bucketPath = this.getBucketPath(name);
-        if (!(await this.exists(bucketPath))) {
+        const bucketPath = this.getBucketPath(opts);
+        if (!(await this.exists({ target: bucketPath }))) {
             throw (0, error_1.getError)({
                 message: `[removeBucket] Bucket does not exist | name: ${name}`,
             });
@@ -125,96 +140,120 @@ class DiskHelper extends base_1.BaseStorageHelper {
         return '/static-resources/';
     }
     async writeObject(opts) {
-        const { bucket, normalizeName, file } = opts;
-        const objectPath = this.getObjectPath(bucket, normalizeName);
-        const objectDir = node_path_1.default.dirname(objectPath);
-        if (!(await this.exists(objectDir))) {
-            await promises_1.default.mkdir(objectDir, { recursive: true });
-        }
+        const { bucket, object, file } = opts;
+        const objectPath = this.getObjectPath({ bucket, object });
+        // `recursive` succeeds on an existing directory; probing first wastes a syscall per file.
+        await promises_1.default.mkdir(node_path_1.default.dirname(objectPath), { recursive: true });
         await promises_1.default.writeFile(objectPath, file.buffer);
     }
-    async getFile(opts) {
-        const { bucket, name } = opts;
-        const objectPath = this.getObjectPath(bucket, name);
-        if (!(await this.exists(objectPath))) {
+    async getObject(opts) {
+        const { bucket, object } = opts;
+        const objectPath = this.resolveObjectPath({ bucket, object });
+        if (!(await this.exists({ target: objectPath }))) {
             throw (0, error_1.getError)({
-                message: `[getFile] File not found | bucket: ${bucket} | name: ${name}`,
+                error: common_1.StorageErrors.OBJECT_NOT_FOUND,
+                message: `[getObject] Object not found | bucket: ${bucket.name} | key: ${object.key}`,
             });
         }
         return node_fs_1.default.createReadStream(objectPath);
     }
+    /** `createReadStream` seeks natively, so a range never reads the bytes before it. */
+    async getObjectStream(opts) {
+        const { bucket, object, range } = opts;
+        const objectPath = this.resolveObjectPath({ bucket, object });
+        if (!(await this.exists({ target: objectPath }))) {
+            throw (0, error_1.getError)({
+                error: common_1.StorageErrors.OBJECT_NOT_FOUND,
+                message: `[getObjectStream] Object not found | bucket: ${bucket.name} | key: ${object.key}`,
+            });
+        }
+        const source = node_fs_1.default.createReadStream(objectPath, range ? { start: range.start, end: range.end } : {});
+        return node_stream_1.Readable.toWeb(source);
+    }
     async getStat(opts) {
-        const { bucket, name } = opts;
-        const objectPath = this.getObjectPath(bucket, name);
-        if (!(await this.exists(objectPath))) {
+        const { bucket, object } = opts;
+        const objectPath = this.resolveObjectPath({ bucket, object });
+        const stat = await this.statOrNull({ target: objectPath });
+        if (!stat) {
             throw (0, error_1.getError)({
-                message: `[getStat] File not found | bucket: ${bucket} | name: ${name}`,
+                error: common_1.StorageErrors.OBJECT_NOT_FOUND,
+                message: `[getStat] Object not found | bucket: ${bucket.name} | key: ${object.key}`,
             });
         }
-        const stat = await promises_1.default.stat(objectPath);
         return {
             size: stat.size,
             lastModified: stat.mtime,
             metadata: {
-                mimetype: this.getMimeType(name),
+                mimetype: this.getMimeType({ filename: object.key }),
             },
         };
     }
     async removeObject(opts) {
-        const { bucket, name } = opts;
-        const objectPath = this.getObjectPath(bucket, name);
-        if (!(await this.exists(objectPath))) {
+        const { bucket, object } = opts;
+        const objectPath = this.resolveObjectPath({ bucket, object });
+        if (!(await this.exists({ target: objectPath }))) {
             throw (0, error_1.getError)({
-                message: `[removeObject] File not found | bucket: ${bucket} | name: ${name}`,
+                error: common_1.StorageErrors.OBJECT_NOT_FOUND,
+                message: `[removeObject] Object not found | bucket: ${bucket.name} | key: ${object.key}`,
             });
         }
         await promises_1.default.unlink(objectPath);
     }
+    // Bounded concurrency; one failure stops the batch.
     async removeObjects(opts) {
-        const { bucket, names } = opts;
-        for (const name of names) {
-            await this.removeObject({ bucket, name });
-        }
+        const { bucket, objects } = opts;
+        await this.mapWithConcurrency({
+            items: objects,
+            task: ({ item: object }) => this.removeObject({ bucket, object }),
+        });
     }
     async listObjects(opts) {
         const { bucket, prefix = '', useRecursive = false, maxKeys } = opts;
-        const bucketPath = this.getBucketPath(bucket);
-        if (!(await this.exists(bucketPath))) {
+        if (!this.isValidBucketName({ bucket })) {
+            throw (0, error_1.getError)({ message: `[listObjects] Invalid bucket name | bucket: ${bucket.name}` });
+        }
+        // `maxKeys: 0` means zero, not unlimited.
+        const limit = maxKeys ?? Number.POSITIVE_INFINITY;
+        if (limit <= 0) {
+            return [];
+        }
+        const bucketPath = this.getBucketPath({ bucket });
+        if (!(await this.exists({ target: bucketPath }))) {
             return [];
         }
         const objects = [];
-        const scanDirectory = async (dirPath, currentPrefix = '') => {
-            if (maxKeys && objects.length >= maxKeys) {
+        const scanDirectory = async (scanOptions) => {
+            const { directory } = scanOptions;
+            if (objects.length >= limit) {
                 return;
             }
-            const entries = await promises_1.default.readdir(dirPath, { withFileTypes: true });
+            const entries = await promises_1.default.readdir(directory.path, { withFileTypes: true });
             for (const entry of entries) {
-                const fullName = currentPrefix ? `${currentPrefix}/${entry.name}` : entry.name;
-                const fullPath = node_path_1.default.join(dirPath, entry.name);
-                const isDirectory = entry.isDirectory();
-                if (isDirectory && useRecursive) {
-                    await scanDirectory(fullPath, fullName);
-                    continue;
+                if (objects.length >= limit) {
+                    return;
                 }
-                if (isDirectory || !entry.isFile()) {
+                // An object key always joins on '/'; `path.join` would emit '\' on Windows.
+                const entryKey = directory.prefix ? `${directory.prefix}/${entry.name}` : entry.name;
+                const entryPath = node_path_1.default.join(directory.path, entry.name);
+                if (entry.isDirectory()) {
+                    // A prefix that cannot match below here makes descending pointless.
+                    const canMatch = !prefix || prefix.startsWith(entryKey) || entryKey.startsWith(prefix);
+                    if (useRecursive && canMatch) {
+                        await scanDirectory({ directory: { path: entryPath, prefix: entryKey } });
+                    }
                     continue;
                 }
-                if (prefix && !fullName.startsWith(prefix)) {
+                if (!entry.isFile() || (prefix && !entryKey.startsWith(prefix))) {
                     continue;
                 }
-                const stat = await promises_1.default.stat(fullPath);
-                objects.push({
-                    name: fullName,
-                    size: stat.size,
-                    lastModified: stat.mtime,
-                    etag: undefined,
-                });
-                if (maxKeys && objects.length >= maxKeys) {
-                    break;
+                const stat = await this.statOrNull({ target: entryPath });
+                if (!stat) {
+                    continue;
                 }
+                objects.push({ name: entryKey, size: stat.size, lastModified: stat.mtime });
             }
         };
-        await scanDirectory(bucketPath);
+        await scanDirectory({ directory: { path: bucketPath } });
         return objects;
     }
 }