@tmlmobilidade/go-providers-storage 20260723.1350.16

package/dist/utils/observability.js

@@ -0,0 +1,46 @@
+/* * */
+import { Logger } from '@tmlmobilidade/logger';
+/**
+ * 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 const noopObservability = {
+    onOperationEnd: () => undefined,
+    onOperationStart: () => undefined,
+    onStep: () => undefined,
+};
+/**
+ * Creates an Observability implementation that logs to the console using the Logger.
+ *
+ * @returns {Observability} The logger-based observability implementation.
+ */
+export function createLoggerObservability() {
+    //
+    return {
+        onOperationEnd: (ctx) => {
+            const { durationMs, outcome, ...rest } = ctx;
+            const message = outcome === 'success'
+                ? `[storage] ${rest.operation} succeeded (${durationMs}ms)`
+                : `[storage] ${rest.operation} failed (${durationMs}ms)`;
+            if (outcome === 'success') {
+                Logger.info({ contextOrSpacesAfter: rest, message });
+            }
+            else {
+                Logger.error({ contextOrErrorOrSpacesAfter: rest, message });
+            }
+        },
+        onOperationStart: (ctx) => {
+            Logger.info({ contextOrSpacesAfter: ctx, message: `[storage] ${ctx.operation} started` });
+        },
+        onStep: (ctx) => {
+            Logger.info({
+                contextOrSpacesAfter: ctx,
+                message: `[storage] ${ctx.operation} ${ctx.phase} ${ctx.step}`,
+            });
+        },
+    };
+}

package/dist/utils/operation-runner.d.ts

@@ -0,0 +1,51 @@
+import { type OperationHooks } from '../types/hooks.js';
+import { type OperationContext } from '../types/operation-context.js';
+import { type Observability } from './observability.js';
+export interface SagaStep {
+    compensate?: () => Promise<void>;
+    execute: () => Promise<void>;
+    name: string;
+}
+export interface RunSagaOptions<TContext extends OperationContext, TResult> {
+    context: TContext;
+    hooks?: OperationHooks<TContext, TResult>;
+    observability?: Observability;
+    result: () => Promise<TResult> | TResult;
+    steps: SagaStep[];
+}
+/**
+ * Runs a saga consisting of a sequence of steps, handling compensation in case of errors and
+ * invoking lifecycle hooks and observability callbacks.
+ *
+ * @template TContext - The type of the operation context.
+ * @template TResult - The type of the result returned by the saga.
+ * @param {RunSagaOptions<TContext, TResult>} options - Options for running the saga, including context, hooks, observability, result function, and saga steps.
+ * @returns {Promise<TResult>} The result of the saga execution.
+ *
+ * @throws {StorageError} If a storage step fails, or CompensationError if compensations fail.
+ * @throws {unknown} If `onSuccess` / a non-storage failure throws and compensations succeed, the original error is rethrown (so callers can keep HttpException status codes).
+ *
+ * @remarks
+ * - If a step or `onSuccess` fails, `onRollback` runs first (restore external state while storage resources still exist), then completed steps are compensated in reverse order.
+ * - Lifecycle hooks are invoked at the start, on success, on rollback, on error, and finally.
+ * - Observability callbacks are fired at various phases (operation start, step execution/compensation, operation end).
+ */
+export declare function runSaga<TContext extends OperationContext, TResult>(options: RunSagaOptions<TContext, TResult>): Promise<TResult>;
+/**
+ * Runs a single-step storage operation (such as read or validation) with standard lifecycle hooks and observability.
+ *
+ * @template TContext - The type of the operation context.
+ * @template TResult - The type of the result returned by the operation.
+ * @param options - Configuration for the operation.
+ * @param options.context - The context for the operation, passed to all lifecycle hooks and observability.
+ * @param options.execute - An async function that performs the main operation and returns the result.
+ * @param options.hooks - Lifecycle hooks for the operation (start, success, error, rollback, finally).
+ * @param [options.observability] - Optional observability integration for reporting operation/step lifecycle events.
+ * @returns A promise that resolves with the result of the operation, or rejects with a StorageError if it fails.
+ */
+export declare function runOperation<TContext extends OperationContext, TResult>(options: {
+    context: TContext;
+    execute: () => Promise<TResult>;
+    hooks?: OperationHooks<TContext, TResult>;
+    observability?: Observability;
+}): Promise<TResult>;

package/dist/utils/operation-runner.js

@@ -0,0 +1,124 @@
+import { CompensationError, StorageError, toStorageError } from '@tmlmobilidade/go-clients-oci-storage';
+import { noopObservability } from './observability.js';
+/**
+ * Runs a saga consisting of a sequence of steps, handling compensation in case of errors and
+ * invoking lifecycle hooks and observability callbacks.
+ *
+ * @template TContext - The type of the operation context.
+ * @template TResult - The type of the result returned by the saga.
+ * @param {RunSagaOptions<TContext, TResult>} options - Options for running the saga, including context, hooks, observability, result function, and saga steps.
+ * @returns {Promise<TResult>} The result of the saga execution.
+ *
+ * @throws {StorageError} If a storage step fails, or CompensationError if compensations fail.
+ * @throws {unknown} If `onSuccess` / a non-storage failure throws and compensations succeed, the original error is rethrown (so callers can keep HttpException status codes).
+ *
+ * @remarks
+ * - If a step or `onSuccess` fails, `onRollback` runs first (restore external state while storage resources still exist), then completed steps are compensated in reverse order.
+ * - Lifecycle hooks are invoked at the start, on success, on rollback, on error, and finally.
+ * - Observability callbacks are fired at various phases (operation start, step execution/compensation, operation end).
+ */
+export async function runSaga(options) {
+    //
+    const { context, result, steps } = options;
+    const hooks = options.hooks ?? {};
+    const observability = options.observability ?? noopObservability;
+    const startedAt = Date.now();
+    const completed = [];
+    observability.onOperationStart(context);
+    await hooks.onStart?.(context);
+    try {
+        //
+        /**
+         * Execute each saga step in sequence:
+         * - For every step, trigger an observability event before execution.
+         * - Await the step's execution logic.
+         * - Once successful, record the step as completed to enable compensation if needed.
+         */
+        for (const step of steps) {
+            observability.onStep({ ...context, phase: 'execute', step: step.name });
+            await step.execute();
+            completed.push(step);
+        }
+        const value = await result();
+        await hooks.onSuccess?.(context, value);
+        observability.onOperationEnd({ ...context, durationMs: Date.now() - startedAt, outcome: 'success' });
+        return value;
+    }
+    catch (error) {
+        //
+        const storageError = toStorageError(error, { operation: context.operation });
+        const suppressed = [];
+        /**
+         * Restore external state before compensating storage steps, so callers can point
+         * dependents back at the previous resource while it (and the new one) still exist.
+         */
+        try {
+            await hooks.onRollback?.(context, storageError);
+        }
+        catch (rollbackFailure) {
+            suppressed.push(rollbackFailure);
+        }
+        /**
+         * Compensate all completed steps in reverse order, if they have a compensate handler.
+         * For each step that defines a compensate function:
+         *   1. Fires an observability callback before compensation.
+         *   2. Awaits the compensation.
+         *   3. If compensation throws, collects the error for reporting as suppressed.
+         */
+        for (const step of completed.reverse()) {
+            if (!step.compensate)
+                continue;
+            try {
+                observability.onStep({ ...context, phase: 'compensate', step: step.name });
+                await step.compensate();
+            }
+            catch (compensationFailure) {
+                suppressed.push(compensationFailure);
+            }
+        }
+        /**
+         * If rollback/compensations failed, wrap as CompensationError.
+         * Otherwise prefer the original error when it was not already a StorageError
+         * (typical for HttpException thrown from onSuccess side effects).
+         */
+        const finalError = suppressed.length > 0
+            ? new CompensationError(storageError.message, { cause: storageError, context: { ...storageError.context, ...context }, suppressed })
+            : storageError;
+        await hooks.onError?.(context, finalError);
+        observability.onOperationEnd({ ...context, durationMs: Date.now() - startedAt, outcome: 'error' });
+        if (suppressed.length > 0)
+            throw finalError;
+        if (!(error instanceof StorageError))
+            throw error;
+        throw finalError;
+    }
+    finally {
+        //
+        await hooks.onFinally?.(context);
+    }
+}
+/**
+ * Runs a single-step storage operation (such as read or validation) with standard lifecycle hooks and observability.
+ *
+ * @template TContext - The type of the operation context.
+ * @template TResult - The type of the result returned by the operation.
+ * @param options - Configuration for the operation.
+ * @param options.context - The context for the operation, passed to all lifecycle hooks and observability.
+ * @param options.execute - An async function that performs the main operation and returns the result.
+ * @param options.hooks - Lifecycle hooks for the operation (start, success, error, rollback, finally).
+ * @param [options.observability] - Optional observability integration for reporting operation/step lifecycle events.
+ * @returns A promise that resolves with the result of the operation, or rejects with a StorageError if it fails.
+ */
+export async function runOperation(options) {
+    let value;
+    return runSaga({
+        context: options.context,
+        hooks: options.hooks,
+        observability: options.observability,
+        result: () => value,
+        steps: [{
+                execute: async () => { value = await options.execute(); },
+                name: 'execute',
+            }],
+    });
+}

package/dist/utils/storage-key.d.ts

@@ -0,0 +1,22 @@
+import { type Attachment } from '@tmlmobilidade/types';
+/**
+ * Generates a storage key for an attachment.
+ * @param {Pick<Attachment, '_id' | 'name' | 'resource_id' | 'scope'>} file - The attachment to generate a key for.
+ * @returns The generated storage key.
+ */
+export declare function storageKey(file: Pick<Attachment, '_id' | 'name' | 'resource_id' | 'scope'>): string;
+/**
+ * Builds a storage key for an attachment.
+ * @param scopeThe scope of the attachment.
+ * @param resourceIdThe resource ID of the attachment.
+ * @param idThe ID of the attachment.
+ * @param fileNameThe name of the attachment.
+ * @returns The generated storage key.
+ */
+export declare function buildStorageKey(scope: string, resourceId: string, id: string, fileName: string): string;
+/**
+ * Generates a temporary storage key for an attachment.
+ * @param key The key of the attachment.
+ * @returns The generated temporary storage key.
+ */
+export declare function tempStorageKey(key: string): string;

package/dist/utils/storage-key.js

@@ -0,0 +1,29 @@
+/* * */
+import { getFileExtension } from './mime.js';
+/**
+ * Generates a storage key for an attachment.
+ * @param {Pick<Attachment, '_id' | 'name' | 'resource_id' | 'scope'>} file - The attachment to generate a key for.
+ * @returns The generated storage key.
+ */
+export function storageKey(file) {
+    return `${file.scope}/${file.resource_id}/${file._id}.${getFileExtension(file.name)}`;
+}
+/**
+ * Builds a storage key for an attachment.
+ * @param scopeThe scope of the attachment.
+ * @param resourceIdThe resource ID of the attachment.
+ * @param idThe ID of the attachment.
+ * @param fileNameThe name of the attachment.
+ * @returns The generated storage key.
+ */
+export function buildStorageKey(scope, resourceId, id, fileName) {
+    return `${scope}/${resourceId}/${id}.${getFileExtension(fileName)}`;
+}
+/**
+ * Generates a temporary storage key for an attachment.
+ * @param key The key of the attachment.
+ * @returns The generated temporary storage key.
+ */
+export function tempStorageKey(key) {
+    return `.tmp/${key}.${Date.now()}`;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@tmlmobilidade/go-providers-storage",
+	"version": "20260723.1350.16",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"public transit",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"go"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/consts": "*",
+		"@tmlmobilidade/go-clients-mongo": "*",
+		"@tmlmobilidade/go-clients-oci-storage": "*",
+		"@tmlmobilidade/go-interfaces-godb": "*",
+		"@tmlmobilidade/logger": "*",
+		"@tmlmobilidade/strings": "*",
+		"@tmlmobilidade/types": "*",
+		"@tmlmobilidade/utils": "*"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/node": "26.1.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.1",
+		"tsx": "4.23.1",
+		"typescript": "6.0.3"
+	}
+}