@tmlmobilidade/go-providers-storage 20260723.1350.16

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './provider.js';
+export * from './types/hooks.js';
+export * from './types/operation-context.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from './provider.js';
+export * from './types/hooks.js';
+export * from './types/operation-context.js';

package/dist/operations/batch-delete.d.ts

@@ -0,0 +1,14 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type StorageDeps } from '../types/deps.js';
+import { type BatchResult } from './batch-upload.js';
+export interface BatchDeleteInput {
+    concurrency?: number;
+    fileIds: string[];
+    hooks?: OperationHooks<OperationContext, BatchResult<{
+        fileId: string;
+    }>>;
+}
+export declare function batchDelete(deps: StorageDeps, input: BatchDeleteInput): Promise<BatchResult<{
+    fileId: string;
+}>>;

package/dist/operations/batch-delete.js

@@ -0,0 +1,45 @@
+/* * */
+import { toStorageError } from '@tmlmobilidade/go-clients-oci-storage';
+import { runWithConcurrency } from '@tmlmobilidade/utils';
+import { deleteAttachment } from './delete.js';
+/* * */
+export async function batchDelete(deps, input) {
+    //
+    const { concurrency = 5, fileIds, hooks } = input;
+    const context = { itemCount: fileIds.length, operation: 'batchDelete' };
+    await hooks?.onStart?.(context);
+    try {
+        const settlements = await runWithConcurrency(fileIds, concurrency, async (fileId) => {
+            return deleteAttachment(deps, {
+                fileId,
+                hooks: {
+                    onError: async () => undefined,
+                    onSuccess: async () => undefined,
+                },
+            });
+        });
+        const fulfilled = [];
+        const rejected = [];
+        settlements.forEach((settlement, index) => {
+            if (settlement.status === 'fulfilled') {
+                fulfilled.push({ index, value: settlement.value });
+            }
+            else {
+                rejected.push({ error: settlement.reason, index });
+            }
+        });
+        const result = { fulfilled, rejected };
+        await hooks?.onSuccess?.(context, result);
+        return result;
+    }
+    catch (error) {
+        //
+        const storageError = toStorageError(error, { operation: context.operation });
+        await hooks?.onError?.(context, storageError);
+        throw storageError;
+    }
+    finally {
+        //
+        await hooks?.onFinally?.(context);
+    }
+}

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

@@ -0,0 +1,28 @@
+import { BlobBody } from '../types/blob-body.js';
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type StorageError } from '@tmlmobilidade/go-clients-oci-storage';
+import { type Attachment, type CreateAttachmentDto } from '@tmlmobilidade/types';
+import { type StorageDeps } from '../types/deps.js';
+export interface BatchUploadItem {
+    createAttachmentDto: CreateAttachmentDto & {
+        _id?: string;
+    };
+    file: BlobBody;
+}
+export interface BatchResult<T> {
+    fulfilled: {
+        index: number;
+        value: T;
+    }[];
+    rejected: {
+        error: StorageError;
+        index: number;
+    }[];
+}
+export interface BatchUploadInput {
+    concurrency?: number;
+    hooks?: OperationHooks<OperationContext, BatchResult<Attachment>>;
+    items: BatchUploadItem[];
+}
+export declare function batchUpload(deps: StorageDeps, input: BatchUploadInput): Promise<BatchResult<Attachment>>;

package/dist/operations/batch-upload.js

@@ -0,0 +1,45 @@
+/* * */
+import { toStorageError } from '@tmlmobilidade/go-clients-oci-storage';
+import { runWithConcurrency } from '@tmlmobilidade/utils';
+import { upload } from './upload.js';
+export async function batchUpload(deps, input) {
+    //
+    const { concurrency = 5, hooks, items } = input;
+    const context = { itemCount: items.length, operation: 'batchUpload' };
+    await hooks?.onStart?.(context);
+    try {
+        const settlements = await runWithConcurrency(items, concurrency, async (item) => {
+            return upload(deps, {
+                createAttachmentDto: item.createAttachmentDto,
+                file: item.file,
+                hooks: {
+                    onError: async () => undefined,
+                    onSuccess: async () => undefined,
+                },
+            });
+        });
+        const fulfilled = [];
+        const rejected = [];
+        settlements.forEach((settlement, index) => {
+            if (settlement.status === 'fulfilled') {
+                fulfilled.push({ index, value: settlement.value });
+            }
+            else {
+                rejected.push({ error: settlement.reason, index });
+            }
+        });
+        const result = { fulfilled, rejected };
+        await hooks?.onSuccess?.(context, result);
+        return result;
+    }
+    catch (error) {
+        //
+        const storageError = toStorageError(error, { operation: context.operation });
+        await hooks?.onError?.(context, storageError);
+        throw storageError;
+    }
+    finally {
+        //
+        await hooks?.onFinally?.(context);
+    }
+}

package/dist/operations/copy.d.ts

@@ -0,0 +1,11 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type Attachment } from '@tmlmobilidade/types';
+import { type StorageDeps } from '../types/deps.js';
+export interface CopyInput {
+    fileId: string;
+    hooks?: OperationHooks<OperationContext, Attachment>;
+    resourceId: string;
+    scope: string;
+}
+export declare function copy(deps: StorageDeps, input: CopyInput): Promise<Attachment>;

package/dist/operations/copy.js

@@ -0,0 +1,71 @@
+/* * */
+import { getFileExtension } from '../utils/mime.js';
+import { runSaga } from '../utils/operation-runner.js';
+import { storageKey } from '../utils/storage-key.js';
+import { MetadataError, NotFoundError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+import { generateRandomString } from '@tmlmobilidade/strings';
+import { CreateAttachmentSchema } from '@tmlmobilidade/types';
+import { convertObject } from '@tmlmobilidade/utils';
+/* * */
+export async function copy(deps, input) {
+    //
+    const { fileId, hooks, resourceId, scope } = input;
+    const _id = generateRandomString({ length: 5 });
+    const context = { attachmentId: _id, operation: 'copy', resourceId, scope, sourceAttachmentId: fileId };
+    let source;
+    let originalFilePath = '';
+    let newFilePath = '';
+    let inserted;
+    return runSaga({
+        context,
+        hooks,
+        observability: deps.observability,
+        result: () => {
+            if (!inserted)
+                throw new MetadataError('Copy 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 } });
+                    source = found;
+                    originalFilePath = storageKey(found);
+                    newFilePath = `${scope}/${resourceId}/${_id}.${getFileExtension(found.name)}`;
+                    context.key = newFilePath;
+                },
+                name: 'loadSource',
+            },
+            {
+                compensate: async () => {
+                    await deps.blobs.deleteFile(newFilePath);
+                },
+                execute: async () => {
+                    await deps.blobs.copyFile(originalFilePath, newFilePath);
+                },
+                name: 'copyBlob',
+            },
+            {
+                compensate: async () => {
+                    if (inserted)
+                        await goDb.core.attachments.deleteById(inserted._id, { forceIfLocked: true });
+                },
+                execute: async () => {
+                    if (!source)
+                        throw new MetadataError('Copy source missing during insert');
+                    const newFile = convertObject(source, CreateAttachmentSchema);
+                    inserted = await goDb.core.attachments.insertOne({
+                        ...newFile,
+                        _id,
+                        resource_id: resourceId,
+                        scope,
+                    });
+                },
+                name: 'insertMetadata',
+            },
+        ],
+    });
+}

package/dist/operations/delete.d.ts

@@ -0,0 +1,17 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type StorageDeps } from '../types/deps.js';
+/**
+ * Deletes blob then metadata.
+ * Invariant: prefer an orphan blob over dangling metadata pointing at a missing blob.
+ * If metadata delete fails after blob delete, there is no blob restore compensation.
+ */
+export interface DeleteInput {
+    fileId: string;
+    hooks?: OperationHooks<OperationContext, {
+        fileId: string;
+    }>;
+}
+export declare function deleteAttachment(deps: StorageDeps, input: DeleteInput): Promise<{
+    fileId: string;
+}>;

package/dist/operations/delete.js

@@ -0,0 +1,43 @@
+/* * */
+import { runSaga } from '../utils/operation-runner.js';
+import { storageKey } from '../utils/storage-key.js';
+import { NotFoundError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+export async function deleteAttachment(deps, input) {
+    //
+    const { fileId, hooks } = input;
+    const context = { attachmentId: fileId, operation: 'delete' };
+    let key = '';
+    return runSaga({
+        context,
+        hooks,
+        observability: deps.observability,
+        result: () => ({ fileId }),
+        steps: [
+            {
+                execute: async () => {
+                    const attachment = await goDb.core.attachments.findById(fileId);
+                    if (!attachment)
+                        throw new NotFoundError('File not found', { context: { fileId } });
+                    key = storageKey(attachment);
+                    context.key = key;
+                    context.resourceId = attachment.resource_id;
+                    context.scope = attachment.scope;
+                },
+                name: 'loadSource',
+            },
+            {
+                execute: async () => {
+                    await deps.blobs.deleteFile(key);
+                },
+                name: 'deleteBlob',
+            },
+            {
+                execute: async () => {
+                    await goDb.core.attachments.deleteById(fileId, { forceIfLocked: true });
+                },
+                name: 'deleteMetadata',
+            },
+        ],
+    });
+}

package/dist/operations/exists.d.ts

@@ -0,0 +1,13 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type StorageDeps } from '../types/deps.js';
+export interface ExistsResult {
+    blob: boolean;
+    metadata: boolean;
+}
+export interface ExistsInput {
+    fileId?: string;
+    hooks?: OperationHooks<OperationContext, ExistsResult>;
+    key?: string;
+}
+export declare function exists(deps: StorageDeps, input: ExistsInput): Promise<ExistsResult>;

package/dist/operations/exists.js

@@ -0,0 +1,30 @@
+/* * */
+import { runOperation } from '../utils/operation-runner.js';
+import { storageKey } from '../utils/storage-key.js';
+import { ValidationError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+/* * */
+export async function exists(deps, input) {
+    //
+    const { fileId, hooks, key: keyInput } = input;
+    const context = { attachmentId: fileId, key: keyInput, operation: 'exists' };
+    return runOperation({
+        context,
+        execute: async () => {
+            if (!fileId && !keyInput) {
+                throw new ValidationError('Either "fileId" or "key" must be provided');
+            }
+            if (fileId) {
+                const file = await goDb.core.attachments.findById(fileId);
+                if (!file)
+                    return { blob: false, metadata: false };
+                const blob = await deps.blobs.fileExists(storageKey(file));
+                return { blob, metadata: true };
+            }
+            const blob = await deps.blobs.fileExists(keyInput);
+            return { blob, metadata: false };
+        },
+        hooks,
+        observability: deps.observability,
+    });
+}

package/dist/operations/find-by-id.d.ts

@@ -0,0 +1,9 @@
+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 } from '@tmlmobilidade/types';
+export interface FindByIdInput {
+    hooks?: OperationHooks<OperationContext, Attachment | null>;
+    id: string;
+}
+export declare function findById(deps: StorageDeps, input: FindByIdInput): Promise<Attachment | null>;

package/dist/operations/find-by-id.js

@@ -0,0 +1,22 @@
+/* * */
+import { runOperation } from '../utils/operation-runner.js';
+import { storageKey } from '../utils/storage-key.js';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+/* * */
+export async function findById(deps, input) {
+    //
+    const { hooks, id } = input;
+    const context = { attachmentId: id, operation: 'findById' };
+    return runOperation({
+        context,
+        execute: async () => {
+            const file = await goDb.core.attachments.findById(id);
+            if (!file)
+                return null;
+            file.url = await deps.blobs.getFileUrl(storageKey(file));
+            return file;
+        },
+        hooks,
+        observability: deps.observability,
+    });
+}

package/dist/operations/find-many.d.ts

@@ -0,0 +1,13 @@
+import type { StorageDeps } from '../types/deps.js';
+import type { OperationHooks } from '../types/hooks.js';
+import type { OperationContext } from '../types/operation-context.js';
+import type { Filter, FindOptions } from '@tmlmobilidade/go-clients-mongo';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+import { Attachment } from '@tmlmobilidade/types';
+interface FindManyInput {
+    filter?: Filter<Attachment>;
+    hooks?: OperationHooks<OperationContext, Attachment[]>;
+    options?: FindOptions;
+}
+export declare function findMany(deps: StorageDeps, input: FindManyInput): ReturnType<typeof goDb.core.attachments.findMany>;
+export {};

package/dist/operations/find-many.js

@@ -0,0 +1,16 @@
+/* * */
+import { runOperation } from '../utils/operation-runner.js';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+export async function findMany(deps, input) {
+    //
+    const { filter, hooks, options } = input;
+    const context = { operation: 'findMany' };
+    return runOperation({
+        context,
+        execute: async () => {
+            return await goDb.core.attachments.findMany(filter, options);
+        },
+        hooks,
+        observability: deps.observability,
+    });
+}

package/dist/operations/get-signed-url.d.ts

@@ -0,0 +1,9 @@
+import { type StorageDeps } from '../types/deps.js';
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+export interface GetSignedUrlInput {
+    fileId?: string;
+    hooks?: OperationHooks<OperationContext, string>;
+    key?: string;
+}
+export declare function getSignedUrl(deps: StorageDeps, input: GetSignedUrlInput): Promise<string>;

package/dist/operations/get-signed-url.js

@@ -0,0 +1,29 @@
+/* * */
+import { runOperation } from '../utils/operation-runner.js';
+import { storageKey } from '../utils/storage-key.js';
+import { NotFoundError, ValidationError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+/* * */
+export async function getSignedUrl(deps, input) {
+    //
+    const { fileId, hooks, key: keyInput } = input;
+    const context = { attachmentId: fileId, key: keyInput, operation: 'getSignedUrl' };
+    return runOperation({
+        context,
+        execute: async () => {
+            if (!fileId && !keyInput) {
+                throw new ValidationError('Either "fileId" or "key" must be provided');
+            }
+            let key = keyInput;
+            if (fileId) {
+                const file = await goDb.core.attachments.findOne({ _id: { $eq: fileId } });
+                if (!file)
+                    throw new NotFoundError('File not found', { context: { fileId } });
+                key = storageKey(file);
+            }
+            return deps.blobs.getFileUrl(key);
+        },
+        hooks,
+        observability: deps.observability,
+    });
+}

package/dist/operations/index.d.ts

@@ -0,0 +1,12 @@
+export * from './batch-delete.js';
+export * from './batch-upload.js';
+export * from './copy.js';
+export * from './delete.js';
+export * from './exists.js';
+export * from './find-by-id.js';
+export * from './find-many.js';
+export * from './get-signed-url.js';
+export * from './move.js';
+export * from './replace.js';
+export * from './upload.js';
+export * from './validate-upload.js';

package/dist/operations/index.js

@@ -0,0 +1,12 @@
+export * from './batch-delete.js';
+export * from './batch-upload.js';
+export * from './copy.js';
+export * from './delete.js';
+export * from './exists.js';
+export * from './find-by-id.js';
+export * from './find-many.js';
+export * from './get-signed-url.js';
+export * from './move.js';
+export * from './replace.js';
+export * from './upload.js';
+export * from './validate-upload.js';

package/dist/operations/move.d.ts

@@ -0,0 +1,11 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type Attachment } from '@tmlmobilidade/types';
+import { type StorageDeps } from '../types/deps.js';
+export interface MoveInput {
+    fileId: string;
+    hooks?: OperationHooks<OperationContext, Attachment>;
+    resourceId: string;
+    scope: string;
+}
+export declare function move(deps: StorageDeps, input: MoveInput): Promise<Attachment>;

package/dist/operations/move.js

@@ -0,0 +1,98 @@
+/* * */
+import { getFileExtension } from '../utils/mime.js';
+import { runSaga } from '../utils/operation-runner.js';
+import { storageKey } from '../utils/storage-key.js';
+import { MetadataError, NotFoundError } from '@tmlmobilidade/go-clients-oci-storage';
+import { goDb } from '@tmlmobilidade/go-interfaces-godb';
+import { generateRandomString } from '@tmlmobilidade/strings';
+import { CreateAttachmentSchema } from '@tmlmobilidade/types';
+import { convertObject } from '@tmlmobilidade/utils';
+/* * */
+export async function move(deps, input) {
+    //
+    const { fileId, hooks, resourceId, scope } = input;
+    const _id = generateRandomString({ length: 5 });
+    const context = { attachmentId: _id, operation: 'move', resourceId, scope, sourceAttachmentId: fileId };
+    let source;
+    let originalFilePath = '';
+    let newFilePath = '';
+    let inserted;
+    let sourceBlobDeleted = false;
+    let sourceMetaDeleted = false;
+    return runSaga({
+        context,
+        hooks,
+        observability: deps.observability,
+        result: () => {
+            if (!inserted)
+                throw new MetadataError('Move 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 } });
+                    source = found;
+                    originalFilePath = storageKey(found);
+                    newFilePath = `${scope}/${resourceId}/${_id}.${getFileExtension(found.name)}`;
+                    context.key = newFilePath;
+                },
+                name: 'loadSource',
+            },
+            {
+                compensate: async () => {
+                    await deps.blobs.deleteFile(newFilePath);
+                },
+                execute: async () => {
+                    await deps.blobs.copyFile(originalFilePath, newFilePath);
+                },
+                name: 'copyBlob',
+            },
+            {
+                compensate: async () => {
+                    if (inserted)
+                        await goDb.core.attachments.deleteById(inserted._id, { forceIfLocked: true });
+                },
+                execute: async () => {
+                    if (!source)
+                        throw new MetadataError('Move source missing during insert');
+                    const newFile = convertObject(source, CreateAttachmentSchema);
+                    inserted = await goDb.core.attachments.insertOne({
+                        ...newFile,
+                        _id,
+                        resource_id: resourceId,
+                        scope,
+                    });
+                },
+                name: 'insertMetadata',
+            },
+            {
+                compensate: async () => {
+                    if (sourceBlobDeleted) {
+                        await deps.blobs.copyFile(newFilePath, originalFilePath);
+                    }
+                },
+                execute: async () => {
+                    await deps.blobs.deleteFile(originalFilePath);
+                    sourceBlobDeleted = true;
+                },
+                name: 'deleteSourceBlob',
+            },
+            {
+                compensate: async () => {
+                    if (sourceMetaDeleted && source) {
+                        const restored = convertObject(source, CreateAttachmentSchema);
+                        await goDb.core.attachments.insertOne({ ...restored, _id: fileId });
+                    }
+                },
+                execute: async () => {
+                    await goDb.core.attachments.deleteById(fileId, { forceIfLocked: true });
+                    sourceMetaDeleted = true;
+                },
+                name: 'deleteSourceMetadata',
+            },
+        ],
+    });
+}

package/dist/operations/replace.d.ts

@@ -0,0 +1,17 @@
+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';
+/**
+ * Replace an existing attachment in place (same id / path).
+ * Uses copy-aside of the old blob so a failed put can restore the previous object.
+ */
+export interface ReplaceInput {
+    createAttachmentDto: CreateAttachmentDto & {
+        _id: string;
+    };
+    file: BlobBody;
+    hooks?: OperationHooks<OperationContext, Attachment>;
+}
+export declare function replace(deps: StorageDeps, input: ReplaceInput): Promise<Attachment>;