@venizia/ignis-helpers 0.2.0-9 → 0.2.0

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

@@ -1,3 +1,4 @@
+import { IDuration } from '../../../common/index.js';
 import { Readable } from 'node:stream';
 export interface IUploadFile {
     originalName: string;
@@ -8,16 +9,28 @@ export interface IUploadFile {
     folderPath?: string;
     [key: string | symbol]: any;
 }
+/** `metaLink` is a union: the old pair allowed both present, or neither. */
 export interface IUploadResult {
-    bucketName: string;
-    objectName: string;
+    bucket: IBucketRef;
+    object: IObjectRef & {
+        size: number;
+        contentType: string;
+    };
     link: string;
-    metaLink?: any;
-    metaLinkError?: any;
+    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: Record<string, any>;
+    metadata: IObjectMetadata;
     lastModified?: Date;
     etag?: string;
     versionId?: string;
@@ -33,68 +46,135 @@ export interface IObjectInfo {
     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: string;
+    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 {
-    isValidName(name: string): boolean;
-    isValidPath(pathStr: string, opts?: {
+    isValidSegment(opts: {
+        segment: string;
+    }): boolean;
+    isValidBucketName(opts: {
+        bucket: IBucketRef;
+    }): boolean;
+    isValidObjectKey(opts: {
+        object: IObjectRef;
         maxDepth?: number;
     }): boolean;
-    isBucketExists(opts: {
-        name: string;
+    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>;
+    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: string;
+        bucket: IBucketRef;
         files: IUploadFile[];
+        maxFolderDepth?: number;
         normalizeNameFn?: (opts: {
-            originalName: string;
-            folderPath?: string;
-        }) => string;
-        normalizeLinkFn?: (opts: {
-            bucketName: string;
-            normalizeName: string;
+            file: TUploadNaming;
         }) => string;
-        /** Folder nesting the caller allows. Omitted -> `BaseStorageHelper.DEFAULT_MAX_FOLDER_DEPTH`. */
-        maxFolderDepth?: number;
+        normalizeLinkFn?: (opts: IObjectLocation) => string;
     }): Promise<IUploadResult[]>;
-    getFile(opts: {
-        bucket: string;
-        name: string;
-        options?: any;
-    }): Promise<Readable>;
-    getStat(opts: {
-        bucket: string;
-        name: string;
-    }): Promise<IFileStat>;
-    removeObject(opts: {
-        bucket: string;
-        name: string;
+    /**
+     * 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: string;
-        names: string[];
+        bucket: IBucketRef;
+        objects: IObjectRef[];
     }): Promise<void>;
-    listObjects(opts: IListObjectsOptions): Promise<IObjectInfo[]>;
-    getFileType(opts: {
+    /** 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/esm/modules/storage/common/types.d.ts.map

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

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

@@ -0,0 +1,7 @@
+import { IDuration } from '../../../common/index.js';
+/** 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/esm/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/esm/modules/storage/common/utility.js

@@ -0,0 +1,23 @@
+import { DurationMultipliers } from '../../../common/index.js';
+import { getError } from '../../error/index.js';
+import { StoragePresignLimits } from './constants.js';
+/** S3 presigns in whole seconds. An unknown unit is refused; `null` would read as "no expiry". */
+export const toExpirySeconds = (opts) => {
+    const { expiresIn, operation } = opts;
+    const milliseconds = DurationMultipliers.toMilliseconds(expiresIn);
+    if (milliseconds === null || milliseconds <= 0) {
+        throw getError({
+            message: `[${operation}] Invalid expiry | unit: ${expiresIn?.unit} | value: ${expiresIn?.value}`,
+        });
+    }
+    const seconds = Math.ceil(milliseconds / 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 > StoragePresignLimits.MAX_EXPIRES_IN_SECONDS) {
+        throw getError({
+            message: `[${operation}] Expiry exceeds the SigV4 maximum of 7 days | unit: ${expiresIn.unit} | value: ${expiresIn.value}`,
+        });
+    }
+    return seconds;
+};
+//# sourceMappingURL=utility.js.map

package/dist/esm/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,OAAO,EAAE,mBAAmB,EAAa,MAAM,UAAU,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAEnD,kGAAkG;AAClG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,IAAiD,EAAU,EAAE;IAC3F,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IACtC,MAAM,YAAY,GAAG,mBAAmB,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAEnE,IAAI,YAAY,KAAK,IAAI,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,QAAQ,CAAC;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,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAErE,iGAAiG;IACjG,gGAAgG;IAChG,IAAI,OAAO,GAAG,oBAAoB,CAAC,sBAAsB,EAAE,CAAC;QAC1D,MAAM,QAAQ,CAAC;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"}

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

@@ -1,7 +1,8 @@
 import { Readable } from 'node:stream';
 import { BaseStorageHelper } from '../base.js';
-import { IBucketInfo, IFileStat, IObjectInfo, IStorageHelperOptions, IUploadFile } from '../common/index.js';
+import { IBucketInfo, IBucketRef, IFileStat, IListObjectsOptions, IObjectInfo, IObjectLocation, IObjectRef, IStorageHelperOptions, IUploadFile } from '../common/index.js';
 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/esm/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,WAAW,CAAC;AAEpG,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"}