@tmlmobilidade/go-providers-storage 20260723.1350.16

package/dist/operations/replace.js

@@ -0,0 +1,99 @@
+/* * */
+import { getMimeTypeFromFileExtension } from '../utils/mime.js';
+import { runSaga } from '../utils/operation-runner.js';
+import { buildStorageKey, storageKey, tempStorageKey } from '../utils/storage-key.js';
+import { ConflictError, MetadataError, NotFoundError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+import { CreateAttachmentSchema } from '@tmlmobilidade/types';
+import { convertObject } from '@tmlmobilidade/utils';
+export async function replace(deps, input) {
+    //
+    const { createAttachmentDto, file, hooks } = input;
+    const fileId = createAttachmentDto._id;
+    const mimeType = getMimeTypeFromFileExtension(createAttachmentDto.name);
+    const filePath = buildStorageKey(createAttachmentDto.scope, createAttachmentDto.resource_id, fileId, createAttachmentDto.name);
+    const context = { attachmentId: fileId, key: filePath, operation: 'replace', resourceId: createAttachmentDto.resource_id, scope: createAttachmentDto.scope };
+    let existing;
+    let asideKey = '';
+    let inserted;
+    let asideCreated = false;
+    let newBlobWritten = false;
+    return runSaga({
+        context,
+        hooks,
+        observability: deps.observability,
+        result: () => {
+            if (!inserted)
+                throw new MetadataError('Replace completed without inserted attachment');
+            return inserted;
+        },
+        steps: [
+            {
+                execute: async () => {
+                    const found = await goDb.core.attachments.findOne({ _id: { $eq: fileId } });
+                    if (!found)
+                        throw new NotFoundError('File not found', { context: { fileId } });
+                    existing = found;
+                    const existingPath = storageKey(found);
+                    if (existingPath !== filePath) {
+                        throw new ConflictError('File ID is provided, but the file path is different from the existing file', {
+                            context: { existingPath, filePath },
+                        });
+                    }
+                    asideKey = tempStorageKey(existingPath);
+                },
+                name: 'loadAndValidate',
+            },
+            {
+                compensate: async () => {
+                    if (asideCreated)
+                        await deps.blobs.deleteFile(asideKey);
+                },
+                execute: async () => {
+                    await deps.blobs.copyFile(filePath, asideKey);
+                    asideCreated = true;
+                },
+                name: 'copyAside',
+            },
+            {
+                compensate: async () => {
+                    if (newBlobWritten) {
+                        await deps.blobs.copyFile(asideKey, filePath);
+                    }
+                },
+                execute: async () => {
+                    await deps.blobs.uploadFile(filePath, file, mimeType);
+                    newBlobWritten = true;
+                },
+                name: 'putBlob',
+            },
+            {
+                compensate: async () => {
+                    if (inserted && existing) {
+                        await goDb.core.attachments.deleteById(fileId, { forceIfLocked: true });
+                        const restored = convertObject(existing, CreateAttachmentSchema);
+                        await goDb.core.attachments.insertOne({ ...restored, _id: fileId });
+                    }
+                },
+                execute: async () => {
+                    await goDb.core.attachments.deleteById(fileId, { forceIfLocked: true });
+                    inserted = await goDb.core.attachments.insertOne({
+                        ...createAttachmentDto,
+                        _id: fileId,
+                        type: mimeType,
+                    });
+                },
+                name: 'replaceMetadata',
+            },
+            {
+                execute: async () => {
+                    if (asideCreated) {
+                        await deps.blobs.deleteFile(asideKey);
+                        asideCreated = false;
+                    }
+                },
+                name: 'cleanupAside',
+            },
+        ],
+    });
+}

package/dist/operations/upload.d.ts

@@ -0,0 +1,13 @@
+import { BlobBody } from '../types/blob-body.js';
+import { type StorageDeps } from '../types/deps.js';
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type Attachment, type CreateAttachmentDto } from '@tmlmobilidade/types';
+export interface UploadInput {
+    createAttachmentDto: CreateAttachmentDto & {
+        _id?: string;
+    };
+    file: BlobBody;
+    hooks?: OperationHooks<OperationContext, Attachment>;
+}
+export declare function upload(deps: StorageDeps, input: UploadInput): Promise<Attachment>;

package/dist/operations/upload.js

@@ -0,0 +1,52 @@
+/* * */
+import { getMimeTypeFromFileExtension } from '../utils/mime.js';
+import { runSaga } from '../utils/operation-runner.js';
+import { buildStorageKey } from '../utils/storage-key.js';
+import { MetadataError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+import { generateRandomString } from '@tmlmobilidade/strings';
+/* * */
+export async function upload(deps, input) {
+    //
+    const { createAttachmentDto, file, hooks } = input;
+    const fileId = createAttachmentDto._id || generateRandomString({ length: 5 });
+    const mimeType = getMimeTypeFromFileExtension(createAttachmentDto.name);
+    const filePath = buildStorageKey(createAttachmentDto.scope, createAttachmentDto.resource_id, fileId, createAttachmentDto.name);
+    const context = { attachmentId: fileId, key: filePath, operation: 'upload', resourceId: createAttachmentDto.resource_id, scope: createAttachmentDto.scope };
+    let inserted;
+    return runSaga({
+        context,
+        hooks,
+        observability: deps.observability,
+        result: () => {
+            if (!inserted)
+                throw new MetadataError('Upload completed without inserted attachment');
+            return inserted;
+        },
+        steps: [
+            {
+                compensate: async () => {
+                    await deps.blobs.deleteFile(filePath);
+                },
+                execute: async () => {
+                    await deps.blobs.uploadFile(filePath, file, mimeType);
+                },
+                name: 'putBlob',
+            },
+            {
+                compensate: async () => {
+                    if (inserted)
+                        await goDb.core.attachments.deleteById(inserted._id, { forceIfLocked: true });
+                },
+                execute: async () => {
+                    inserted = await goDb.core.attachments.insertOne({
+                        ...createAttachmentDto,
+                        _id: fileId,
+                        type: mimeType,
+                    });
+                },
+                name: 'insertMetadata',
+            },
+        ],
+    });
+}

package/dist/operations/validate-upload.d.ts

@@ -0,0 +1,15 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type Observability } from '../utils/observability.js';
+import { type CreateAttachmentDto } from '@tmlmobilidade/types';
+export interface ValidateUploadResult {
+    extension: string;
+    mimeType: string;
+}
+export interface ValidateUploadInput {
+    createAttachmentDto: Pick<CreateAttachmentDto, 'name' | 'size'>;
+    hooks?: OperationHooks<OperationContext, ValidateUploadResult>;
+    maxSizeBytes?: number;
+    observability?: Observability;
+}
+export declare function validateUpload(input: ValidateUploadInput): Promise<ValidateUploadResult>;

package/dist/operations/validate-upload.js

@@ -0,0 +1,28 @@
+/* * */
+import { getFileExtension, getMimeTypeFromFileExtension } from '../utils/mime.js';
+import { runOperation } from '../utils/operation-runner.js';
+import { ValidationError } from '@tmlmobilidade/go-clients-oci-storage';
+/* * */
+export async function validateUpload(input) {
+    //
+    const { createAttachmentDto, hooks, maxSizeBytes, observability } = input;
+    const context = { operation: 'validateUpload' };
+    return runOperation({
+        context,
+        execute: async () => {
+            const extension = getFileExtension(createAttachmentDto.name);
+            const mimeType = getMimeTypeFromFileExtension(createAttachmentDto.name);
+            if (typeof createAttachmentDto.size === 'number' && createAttachmentDto.size < 0) {
+                throw new ValidationError('File size cannot be negative', { context: { size: createAttachmentDto.size } });
+            }
+            if (maxSizeBytes !== undefined && createAttachmentDto.size > maxSizeBytes) {
+                throw new ValidationError(`File size exceeds maximum of ${maxSizeBytes} bytes`, {
+                    context: { maxSizeBytes, size: createAttachmentDto.size },
+                });
+            }
+            return { extension, mimeType };
+        },
+        hooks,
+        observability,
+    });
+}

package/dist/provider.d.ts

@@ -0,0 +1,130 @@
+import { BlobBody } from './types/blob-body.js';
+import { type OperationHooks } from './types/hooks.js';
+import { type OperationContext } from './types/operation-context.js';
+import { type Filter, type FindOptions } from '@tmlmobilidade/go-clients-mongo';
+import { type Attachment, type CreateAttachmentDto } from '@tmlmobilidade/types';
+import * as operations from './operations/index.js';
+declare class StorageProviderClass {
+    private readonly deps;
+    private static _instance;
+    private constructor();
+    static getInstance(): Promise<StorageProviderClass>;
+    /**
+     * Deletes multiple files by their IDs in a batch operation.
+     * @param fileIds - An array of file IDs to be deleted.
+     * @param hooks - Operation hooks for observability or side effects.
+     * @param options - Optional: Batch deletion settings such as concurrency.
+     * @returns A promise resolving to the batch result containing deleted fileIds.
+     */
+    batchDelete(fileIds: string[], hooks?: OperationHooks<OperationContext, operations.BatchResult<{
+        fileId: string;
+    }>>, options?: Pick<operations.BatchDeleteInput, 'concurrency'>): Promise<operations.BatchResult<{
+        fileId: string;
+    }>>;
+    /**
+     * Uploads multiple items in a batch operation.
+     * @param items - List of items to be uploaded.
+     * @param hooks - Operation hooks for the batch upload.
+     * @param options - Optional: Control concurrency for batch uploads.
+     * @returns A promise resolving to the batch upload result with attachments.
+     */
+    batchUpload(items: operations.BatchUploadItem[], hooks?: OperationHooks<OperationContext, operations.BatchResult<Attachment>>, options?: {
+        concurrency?: number;
+    }): Promise<operations.BatchResult<Attachment>>;
+    /**
+     * Copies a file to a new resource and scope.
+     * @param fileId - The ID of the file to copy.
+     * @param scope - The new scope for the copied file.
+     * @param resourceId - The ID of the new associated resource.
+     * @param hooks - Hooks for operation observability and behavior.
+     * @returns A promise resolving to the new copied Attachment.
+     */
+    copy(fileId: string, scope: string, resourceId: string, hooks?: OperationHooks<OperationContext, Attachment>): Promise<Attachment>;
+    /**
+     * Deletes a single file by its ID.
+     * @param fileId - The ID of the file to delete.
+     * @param hooks - Hooks for operation side effects and observability.
+     * @returns A promise resolving with the deleted fileId.
+     */
+    delete(fileId: string, hooks?: OperationHooks<OperationContext, {
+        fileId: string;
+    }>): Promise<{
+        fileId: string;
+    }>;
+    /**
+     * Checks for existence of a file by ID or key.
+     * @param params - An object containing fileId or key.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the existence result.
+     */
+    exists(params: {
+        fileId?: string;
+        key?: string;
+    }, hooks?: OperationHooks<OperationContext, operations.ExistsResult>): Promise<operations.ExistsResult>;
+    /**
+     * Finds a file attachment by its unique ID.
+     * @param id - The ID of the attachment.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the Attachment or null if not found.
+     */
+    findById(id: string, hooks?: OperationHooks<OperationContext, Attachment | null>): Promise<Attachment | null>;
+    /**
+     * Generates a signed URL for downloading or accessing a file.
+     * @param params - Parameters with fileId or key for which to generate the URL.
+     * @param hooks - Hooks for execution/observability.
+     * @returns A promise resolving to the signed URL as a string.
+     */
+    getSignedUrl(params: {
+        fileId?: string;
+        key?: string;
+    }, hooks?: OperationHooks<OperationContext, string>): Promise<string>;
+    /**
+     * Moves a file to a different resource and/or scope.
+     * @param fileId - ID of the file to move.
+     * @param scope - Target scope.
+     * @param resourceId - Target resource ID.
+     * @param hooks - Hooks for observability or side effects.
+     * @returns A promise resolving to the updated Attachment.
+     */
+    move(fileId: string, scope: string, resourceId: string, hooks?: OperationHooks<OperationContext, Attachment>): Promise<Attachment>;
+    /**
+     * Replaces an existing file's data while preserving its identifier.
+     * @param file - Blob body of the new file.
+     * @param createAttachmentDto - Data transfer object describing the attachment, must include _id.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the updated Attachment.
+     */
+    replace(file: BlobBody, createAttachmentDto: CreateAttachmentDto & {
+        _id: string;
+    }, hooks?: OperationHooks<OperationContext, Attachment>): Promise<Attachment>;
+    /**
+     * Uploads a new file and creates the corresponding attachment.
+     * @param file - Blob body of the file to upload.
+     * @param createAttachmentDto - Data transfer object for attachment creation. _id is optional.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the created Attachment.
+     */
+    upload(file: BlobBody, createAttachmentDto: CreateAttachmentDto & {
+        _id?: string;
+    }, hooks?: OperationHooks<OperationContext, Attachment>): Promise<Attachment>;
+    /**
+     * Validates whether a file upload can proceed, based on file size and name.
+     * @param createAttachmentDto - Contains file information to validate (name and size).
+     * @param hooks - Hooks for operation execution.
+     * @param options - Optional: Max allowed file size in bytes.
+     * @returns A promise resolving to the validation result.
+     */
+    validateUpload(createAttachmentDto: Pick<CreateAttachmentDto, 'name' | 'size'>, hooks?: OperationHooks<OperationContext, operations.ValidateUploadResult>, options?: {
+        maxSizeBytes?: number;
+    }): Promise<operations.ValidateUploadResult>;
+    /**
+     * Finds multiple attachments matching the filter criteria.
+     * @param filter - Filter criteria to match attachments.
+     * @param options - Find options.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to an array of matching attachments.
+     */
+    findMany(filter?: Filter<Attachment>, options?: FindOptions, hooks?: OperationHooks<OperationContext, Attachment[]>): Promise<Attachment[] | null>;
+}
+export declare const storageProvider: StorageProviderClass;
+export {};

package/dist/provider.js

@@ -0,0 +1,146 @@
+/* * */
+import { createLoggerObservability } from './utils/observability.js';
+import { OCIStorageClient } from '@tmlmobilidade/go-clients-oci-storage';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+import * as operations from './operations/index.js';
+/* * */
+class StorageProviderClass {
+    deps;
+    //
+    static _instance;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    static async getInstance() {
+        if (!StorageProviderClass._instance) {
+            const ociStorageClient = await OCIStorageClient.getClient({ prefix: 'OCI_STORAGE' });
+            StorageProviderClass._instance = new StorageProviderClass({ blobs: ociStorageClient, observability: createLoggerObservability() });
+        }
+        return StorageProviderClass._instance;
+    }
+    /**
+     * Deletes multiple files by their IDs in a batch operation.
+     * @param fileIds - An array of file IDs to be deleted.
+     * @param hooks - Operation hooks for observability or side effects.
+     * @param options - Optional: Batch deletion settings such as concurrency.
+     * @returns A promise resolving to the batch result containing deleted fileIds.
+     */
+    async batchDelete(fileIds, hooks, options) {
+        return operations.batchDelete(this.deps, { concurrency: options?.concurrency, fileIds, hooks });
+    }
+    /**
+     * Uploads multiple items in a batch operation.
+     * @param items - List of items to be uploaded.
+     * @param hooks - Operation hooks for the batch upload.
+     * @param options - Optional: Control concurrency for batch uploads.
+     * @returns A promise resolving to the batch upload result with attachments.
+     */
+    async batchUpload(items, hooks, options) {
+        return operations.batchUpload(this.deps, { concurrency: options?.concurrency, hooks, items });
+    }
+    /**
+     * Copies a file to a new resource and scope.
+     * @param fileId - The ID of the file to copy.
+     * @param scope - The new scope for the copied file.
+     * @param resourceId - The ID of the new associated resource.
+     * @param hooks - Hooks for operation observability and behavior.
+     * @returns A promise resolving to the new copied Attachment.
+     */
+    async copy(fileId, scope, resourceId, hooks) {
+        return operations.copy(this.deps, { fileId, hooks, resourceId, scope });
+    }
+    /**
+     * Deletes a single file by its ID.
+     * @param fileId - The ID of the file to delete.
+     * @param hooks - Hooks for operation side effects and observability.
+     * @returns A promise resolving with the deleted fileId.
+     */
+    async delete(fileId, hooks) {
+        return operations.deleteAttachment(this.deps, { fileId, hooks });
+    }
+    /**
+     * Checks for existence of a file by ID or key.
+     * @param params - An object containing fileId or key.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the existence result.
+     */
+    async exists(params, hooks) {
+        return operations.exists(this.deps, { ...params, hooks });
+    }
+    /**
+     * Finds a file attachment by its unique ID.
+     * @param id - The ID of the attachment.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the Attachment or null if not found.
+     */
+    async findById(id, hooks) {
+        return operations.findById(this.deps, { hooks, id });
+    }
+    /**
+     * Generates a signed URL for downloading or accessing a file.
+     * @param params - Parameters with fileId or key for which to generate the URL.
+     * @param hooks - Hooks for execution/observability.
+     * @returns A promise resolving to the signed URL as a string.
+     */
+    async getSignedUrl(params, hooks) {
+        return operations.getSignedUrl(this.deps, { ...params, hooks });
+    }
+    /**
+     * Moves a file to a different resource and/or scope.
+     * @param fileId - ID of the file to move.
+     * @param scope - Target scope.
+     * @param resourceId - Target resource ID.
+     * @param hooks - Hooks for observability or side effects.
+     * @returns A promise resolving to the updated Attachment.
+     */
+    async move(fileId, scope, resourceId, hooks) {
+        return operations.move(this.deps, { fileId, hooks, resourceId, scope });
+    }
+    /**
+     * Replaces an existing file's data while preserving its identifier.
+     * @param file - Blob body of the new file.
+     * @param createAttachmentDto - Data transfer object describing the attachment, must include _id.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the updated Attachment.
+     */
+    async replace(file, createAttachmentDto, hooks) {
+        return operations.replace(this.deps, { createAttachmentDto, file, hooks });
+    }
+    /**
+     * Uploads a new file and creates the corresponding attachment.
+     * @param file - Blob body of the file to upload.
+     * @param createAttachmentDto - Data transfer object for attachment creation. _id is optional.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to the created Attachment.
+     */
+    async upload(file, createAttachmentDto, hooks) {
+        return operations.upload(this.deps, { createAttachmentDto, file, hooks });
+    }
+    /**
+     * Validates whether a file upload can proceed, based on file size and name.
+     * @param createAttachmentDto - Contains file information to validate (name and size).
+     * @param hooks - Hooks for operation execution.
+     * @param options - Optional: Max allowed file size in bytes.
+     * @returns A promise resolving to the validation result.
+     */
+    async validateUpload(createAttachmentDto, hooks, options) {
+        return operations.validateUpload({
+            createAttachmentDto,
+            hooks,
+            maxSizeBytes: options?.maxSizeBytes,
+            observability: this.deps.observability,
+        });
+    }
+    /**
+     * Finds multiple attachments matching the filter criteria.
+     * @param filter - Filter criteria to match attachments.
+     * @param options - Find options.
+     * @param hooks - Hooks for operation execution.
+     * @returns A promise resolving to an array of matching attachments.
+     */
+    async findMany(filter, options, hooks) {
+        return operations.findMany(this.deps, { filter, hooks, options });
+    }
+}
+/* * */
+export const storageProvider = asyncSingletonProxy(StorageProviderClass);

package/dist/types/blob-body.d.ts

@@ -0,0 +1,2 @@
+import { Readable } from 'node:stream';
+export type BlobBody = Buffer | Readable | ReadableStream;

package/dist/types/blob-body.js

@@ -0,0 +1 @@
+export {};

package/dist/types/deps.d.ts

@@ -0,0 +1,6 @@
+import { type Observability } from '../utils/observability.js';
+import { type OCIStorageClientWrapper } from '@tmlmobilidade/go-clients-oci-storage';
+export interface StorageDeps {
+    blobs: OCIStorageClientWrapper;
+    observability: Observability;
+}

package/dist/types/deps.js

@@ -0,0 +1 @@
+export {};

package/dist/types/hooks.d.ts

@@ -0,0 +1,8 @@
+import { type StorageError } from '@tmlmobilidade/go-clients-oci-storage';
+export interface OperationHooks<TContext, TResult> {
+    onError?: (ctx: TContext, error: StorageError) => Promise<void> | void;
+    onFinally?: (ctx: TContext) => Promise<void> | void;
+    onRollback?: (ctx: TContext, error?: StorageError) => Promise<void> | void;
+    onStart?: (ctx: TContext) => Promise<void> | void;
+    onSuccess?: (ctx: TContext, result: TResult) => Promise<void> | void;
+}

package/dist/types/hooks.js

@@ -0,0 +1 @@
+export {};

package/dist/types/operation-context.d.ts

@@ -0,0 +1,8 @@
+export interface OperationContext {
+    [key: string]: unknown;
+    attachmentId?: string;
+    key?: string;
+    operation: string;
+    resourceId?: string;
+    scope?: string;
+}

package/dist/types/operation-context.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/mime.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Extracts the file extension from a file name and validates it against supported MIME types.
+ *
+ * @param {string} fileName - The name of the file.
+ * @returns {string} The lowercase file extension.
+ * @throws {ValidationError} If the file does not have an extension or the extension is unsupported.
+ */
+export declare function getFileExtension(fileName: string): string;
+/**
+ * Retrieves the MIME type associated with a file extension found in the file name.
+ *
+ * @param {string} fileName - The name of the file.
+ * @returns {string} The MIME type corresponding to the file extension.
+ * @throws {ValidationError} If the extension is missing or unsupported.
+ */
+export declare function getMimeTypeFromFileExtension(fileName: string): string;
+/**
+ * Finds the file extension corresponding to the provided MIME type.
+ *
+ * @param {string} mimeType - The MIME type to look up.
+ * @returns {string} The file extension matching the MIME type, or an empty string if not found.
+ */
+export declare function getFileExtensionFromMimeType(mimeType: string): string;

package/dist/utils/mime.js

@@ -0,0 +1,41 @@
+/* * */
+import { mimeTypes } from '@tmlmobilidade/consts';
+import { ValidationError } from '@tmlmobilidade/go-clients-oci-storage';
+/* * */
+/**
+ * Extracts the file extension from a file name and validates it against supported MIME types.
+ *
+ * @param {string} fileName - The name of the file.
+ * @returns {string} The lowercase file extension.
+ * @throws {ValidationError} If the file does not have an extension or the extension is unsupported.
+ */
+export function getFileExtension(fileName) {
+    const extension = fileName.split('.').pop()?.toLowerCase();
+    if (!extension)
+        throw new ValidationError('File has no extension', { context: { fileName } });
+    if (!(extension in mimeTypes)) {
+        throw new ValidationError(`Unsupported file extension: ${extension}`, { context: { extension, fileName } });
+    }
+    return extension;
+}
+/**
+ * Retrieves the MIME type associated with a file extension found in the file name.
+ *
+ * @param {string} fileName - The name of the file.
+ * @returns {string} The MIME type corresponding to the file extension.
+ * @throws {ValidationError} If the extension is missing or unsupported.
+ */
+export function getMimeTypeFromFileExtension(fileName) {
+    return mimeTypes[getFileExtension(fileName)];
+}
+/**
+ * Finds the file extension corresponding to the provided MIME type.
+ *
+ * @param {string} mimeType - The MIME type to look up.
+ * @returns {string} The file extension matching the MIME type, or an empty string if not found.
+ */
+export function getFileExtensionFromMimeType(mimeType) {
+    if (!mimeType)
+        return '';
+    return Object.keys(mimeTypes).find(key => mimeTypes[key] === mimeType) ?? '';
+}

package/dist/utils/observability.d.ts

@@ -0,0 +1,35 @@
+import { type OperationContext } from '../types/operation-context.js';
+/**
+ * Interface defining the contract for observability in storage operations.
+ *
+ * @interface Observability
+ * @property {function} onOperationEnd - Callback to be invoked when an operation ends.
+ * @property {function} onOperationStart - Callback to be invoked when an operation starts.
+ * @property {function} onStep - Callback to be invoked when a step in an operation is executed.
+ */
+export interface Observability {
+    onOperationEnd: (ctx: OperationContext & {
+        durationMs: number;
+        outcome: 'error' | 'success';
+    }) => void;
+    onOperationStart: (ctx: OperationContext) => void;
+    onStep: (ctx: OperationContext & {
+        phase: 'compensate' | 'execute';
+        step: string;
+    }) => void;
+}
+/**
+ * No-op implementation of the Observability interface.
+ *
+ * @type {Observability}
+ * @property {function} onOperationEnd - Does nothing.
+ * @property {function} onOperationStart - Does nothing.
+ * @property {function} onStep - Does nothing.
+ */
+export declare const noopObservability: Observability;
+/**
+ * Creates an Observability implementation that logs to the console using the Logger.
+ *
+ * @returns {Observability} The logger-based observability implementation.
+ */
+export declare function createLoggerObservability(): Observability;