@lark-apaas/dataloom 0.1.1-alpha.0

package/lib/storage/packages/StorageFileApi.d.ts

@@ -0,0 +1,190 @@
+import { StorageError } from '../libs/errors';
+import { type Fetch } from '../libs/fetch';
+import type { FetchParameters, FileBody, FileObject, FileOptions, FileOptionsV2, OnRequestErrorType, SearchOptions, TransformOptions, UploadFileData } from '../libs/types';
+export default class StorageFileApi {
+    protected url: string;
+    protected headers: {
+        [key: string]: string;
+    };
+    protected bucketId?: string;
+    protected appId?: string;
+    protected fetch: Fetch;
+    protected loggerEnabled?: boolean;
+    protected onRequestError?: (error: OnRequestErrorType) => void;
+    constructor(url: string, headers?: {
+        [key: string]: string;
+    }, bucketId?: string, appId?: string, fetch?: Fetch, loggerEnabled?: boolean, onRequestError?: (error: OnRequestErrorType) => void);
+    /**
+     * Uploads a file to an existing bucket or replaces an existing file at the specified path with a new one.
+     *
+     * @param method HTTP method.
+     * @param path The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
+     * @param fileBody The body of the file to be stored in the bucket.
+     */
+    private uploadOrUpdate;
+    /**
+     * Uploads a file to an existing bucket.
+     *
+     * @param path The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
+     * @param fileBody The body of the file to be stored in the bucket.
+     * @param fileOptions Upload options.
+     */
+    upload(path: string, fileBody: FileBody, fileOptions?: FileOptions): Promise<{
+        data: UploadFileData;
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Uploads a file to an existing bucket.
+     *
+     * @param fileBody The body of the file to be stored in the bucket.
+     * @param fileOptions Upload options including filePath.
+     */
+    upload(fileBody: FileBody, fileOptions?: FileOptionsV2): Promise<{
+        data: UploadFileData;
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Uploads a file to an existing bucket.
+     *
+     * @param path The file path, including the file name. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to upload.
+     * @param fileBody The body of the file to be stored in the bucket.
+     */
+    uploadFile(fileBody: FileBody, fileOptions?: FileOptionsV2): Promise<{
+        data: UploadFileData;
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Replaces an existing file at the specified path with a new one.
+     *
+     * @param path The relative file path. Should be of the format `folder/subfolder/filename.png`. The bucket must already exist before attempting to update.
+     * @param fileBody The body of the file to be stored in the bucket.
+     */
+    update(path: string, fileBody: ArrayBuffer | ArrayBufferView | Blob | File | FormData | ReadableStream<Uint8Array> | URLSearchParams | string, fileOptions?: FileOptions): Promise<{
+        data: UploadFileData;
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Creates a signed URL. Use a signed URL to share a file for a fixed amount of time.
+     *
+     * @param path The file path, including the current file name. For example `folder/image.png`.
+     * @param expiresIn The number of seconds until the signed URL expires. For example, `60` for a URL which is valid for one minute.
+     * @param options.download triggers the file as a download if set to true. Set this parameter as the name of the file if you want to trigger the download with a different filename.
+     * @param options.transform Transform the asset before serving it to the client.
+     */
+    createSignedUrl(path: string, expiresIn: number, _options?: {
+        download?: string | boolean;
+        transform?: TransformOptions;
+    }): Promise<{
+        data: {
+            signedUrl: string;
+        };
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Creates multiple signed URLs. Use a signed URL to share a file for a fixed amount of time.
+     *
+     * @param paths The file paths to be downloaded, including the current file names. For example `['folder/image.png', 'folder2/image2.png']`.
+     * @param expiresIn The number of seconds until the signed URLs expire. For example, `60` for URLs which are valid for one minute.
+     * @param options.download triggers the file as a download if set to true. Set this parameter as the name of the file if you want to trigger the download with a different filename.
+     *
+     *
+     * success: { error: "", path: "xxxx/xxxx.xx", signedURL: "https://xxxx"}
+     * failed: { error: "xxxx", path: "xxxx/xxxx.xx", signedURL: "" }
+     */
+    createSignedUrls(paths: string[], expiresIn: number, _options?: {
+        download: string | boolean;
+    }): Promise<{
+        data: {
+            error: string | null;
+            path: string | null;
+            signedUrl: string;
+        }[];
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Downloads a file from a private bucket. For public buckets, make a request to the URL returned from `getPublicUrl` instead.
+     *
+     * @param path The full path and file name of the file to be downloaded. For example `folder/image.png`.
+     * @param options.transform Transform the asset before serving it to the client.
+     */
+    download(path: string, _options?: {
+        transform?: TransformOptions;
+    }): Promise<{
+        data: Blob;
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Deletes files within the same bucket
+     *
+     * @param paths An array of files to delete, including the path and file name. For example [`'folder/image.png'`].
+     */
+    remove(paths: string[]): Promise<{
+        data: FileObject[];
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Upload a file from a public URL to the bucket.
+     *
+     * @param url The public URL of the file to download (e.g., CDN link).
+     */
+    uploadFromUrl(url: string): Promise<{
+        data: UploadFileData;
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    /**
+     * Lists all the files within a bucket.
+     * @param path The folder path.
+     * @param options Search options including limit (defaults to 100), offset, sortBy, and search
+     */
+    list(path?: string, options?: SearchOptions, parameters?: FetchParameters): Promise<{
+        data: FileObject[];
+        error: null;
+    } | {
+        data: null;
+        error: StorageError;
+    }>;
+    generateDownloadUrlFromFilePath(filePath: string): string;
+    protected encodeMetadata(metadata: Record<string, any>): string;
+    toBase64(data: string): string;
+    private _getFinalPath;
+    private _removeEmptyFolders;
+    private _isValidDownloadUrl;
+    /**
+     * Get the filePath from download url with format like
+     * /spark/app/app_xxxx/runtime/api/v1/storage/object/bucket_xxx/123%2Fimage.png
+     * or /app/app_xxxx/runtime/api/v1/storage/object/bucket_xxx/123%2Fimage.png
+     */
+    private _retrieveFilePathFromDownloadUrl;
+    /**
+     * Directly copy files using VolcEngine API if url is from VolcEngine Beijing Region.
+     */
+    private _copyWithinVolcEngine;
+}
+//# sourceMappingURL=StorageFileApi.d.ts.map

package/lib/storage/packages/StorageFileApi.d.ts.map

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

package/lib/storage/packages/StorageFileApi.js

@@ -0,0 +1,378 @@
+import { StorageError, StorageUnknownError, isCustomError, isStorageError } from "../libs/errors.js";
+import { get, post, put, remove } from "../libs/fetch.js";
+import { checkIsVolcEngineUrl, getUpdateFileSize, resolveFetch, sanitizeFileName, toValidExpiresIn, transformFilePayload } from "../libs/helpers.js";
+const DEFAULT_SEARCH_OPTIONS = {
+    limit: 100,
+    offset: 0,
+    sortBy: {
+        column: 'name',
+        order: 'asc'
+    }
+};
+const DEFAULT_FILE_OPTIONS = {
+    upsert: false
+};
+class StorageFileApi {
+    constructor(url, headers = {}, bucketId, appId, fetch, loggerEnabled, onRequestError){
+        this.url = url;
+        this.headers = headers;
+        this.bucketId = bucketId;
+        this.appId = appId;
+        this.fetch = resolveFetch(fetch);
+        this.loggerEnabled = loggerEnabled;
+        this.onRequestError = onRequestError;
+    }
+    async uploadOrUpdate(path, fileBody, fileOptions) {
+        try {
+            const options = {
+                ...DEFAULT_FILE_OPTIONS,
+                ...fileOptions
+            };
+            const cleanPath = this._removeEmptyFolders(path);
+            let contentDisposition = null;
+            if (options?.contentDisposition) contentDisposition = options?.contentDisposition;
+            else if (fileBody instanceof File) contentDisposition = fileBody?.name;
+            const preUploadBody = {
+                bucket_id: this.bucketId ?? '',
+                file_size: getUpdateFileSize(fileBody),
+                upsert: options.upsert ?? false,
+                file_path: cleanPath,
+                file_name: fileBody instanceof File ? fileBody?.name : ''
+            };
+            const res = await post(this.fetch, `${this.url}/object/${this.bucketId}/pre_upload`, preUploadBody, {
+                headers: this.headers,
+                logFetch: this.loggerEnabled,
+                onRequestError: this.onRequestError
+            }, void 0, {
+                psmName: 'Storage.Upload.PreUpload'
+            });
+            const { upload_id, upload_url } = res?.data ?? {};
+            if (!upload_url || !upload_id) return {
+                data: null,
+                error: new StorageError('upload_url or upload_id is empty')
+            };
+            {
+                const tosHeaders = {};
+                if (contentDisposition) tosHeaders['content-disposition'] = `attachment; filename="${sanitizeFileName(contentDisposition)}"`;
+                if (options.cacheControl || 0 === options.cacheControl) tosHeaders['cache-control'] = `max-age=${options.cacheControl}`;
+                if (options.contentType) tosHeaders['content-type'] = options.contentType;
+                const tosRes = await put(this.fetch, upload_url, fileBody, {
+                    noResolveJson: true,
+                    headers: tosHeaders,
+                    logFetch: this.loggerEnabled,
+                    onRequestError: this.onRequestError
+                }, void 0, {
+                    psmName: 'Storage.Upload.TosUpload'
+                });
+                const etag = tosRes?.headers?.get('Etag') ?? '';
+                const callbackRes = await post(this.fetch, `${this.url}/object/callback`, {
+                    upload_id,
+                    etag,
+                    app_id: this.appId
+                }, {
+                    headers: this.headers,
+                    logFetch: this.loggerEnabled,
+                    onRequestError: this.onRequestError
+                }, void 0, {
+                    psmName: 'Storage.Upload.Callback'
+                });
+                return {
+                    data: callbackRes?.data ?? {},
+                    error: null
+                };
+            }
+        } catch (error) {
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('upload file error', error)
+            };
+        }
+    }
+    async upload(pathOrFileBody, fileBodyOrOptions, fileOptions) {
+        const isSecondArgFileBody = fileBodyOrOptions instanceof Blob || fileBodyOrOptions instanceof ArrayBuffer || 'undefined' != typeof File && fileBodyOrOptions instanceof File || fileBodyOrOptions instanceof FormData || fileBodyOrOptions instanceof URLSearchParams || 'undefined' != typeof ReadableStream && fileBodyOrOptions instanceof ReadableStream || ArrayBuffer.isView(fileBodyOrOptions) || 'string' == typeof fileBodyOrOptions;
+        if ('string' == typeof pathOrFileBody && isSecondArgFileBody) return this.uploadOrUpdate(pathOrFileBody, fileBodyOrOptions, fileOptions);
+        const options = fileBodyOrOptions;
+        return this.uploadOrUpdate(options?.filePath ?? '', pathOrFileBody, options);
+    }
+    async uploadFile(fileBody, fileOptions) {
+        return this.uploadOrUpdate(fileOptions?.filePath ?? '', fileBody, fileOptions);
+    }
+    async update(path, fileBody, fileOptions) {
+        return this.uploadOrUpdate(path, fileBody, fileOptions);
+    }
+    async createSignedUrl(path, expiresIn, _options) {
+        try {
+            const _path = this._getFinalPath(path);
+            const res = await post(this.fetch, `${this.url}/object/sign/${_path}`, {
+                expires_in: toValidExpiresIn(expiresIn)
+            }, {
+                headers: this.headers,
+                logFetch: this.loggerEnabled,
+                onRequestError: this.onRequestError
+            }, void 0, {
+                psmName: 'Storage.CreateSignedUrl'
+            });
+            return {
+                data: res.data,
+                error: null
+            };
+        } catch (error) {
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('create signed url error', error)
+            };
+        }
+    }
+    async createSignedUrls(paths, expiresIn, _options) {
+        try {
+            const _paths = paths.map((path)=>this._retrieveFilePathFromDownloadUrl(path));
+            const res = await post(this.fetch, `${this.url}/object/sign/${this.bucketId}`, {
+                expires_in: toValidExpiresIn(expiresIn),
+                paths: _paths
+            }, {
+                headers: this.headers,
+                logFetch: this.loggerEnabled,
+                onRequestError: this.onRequestError
+            }, void 0, {
+                psmName: 'Storage.CreateSignedUrls'
+            });
+            return {
+                data: res.data,
+                error: null
+            };
+        } catch (error) {
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('create signed urls error', error)
+            };
+        }
+    }
+    async download(path, _options) {
+        try {
+            const _path = this._retrieveFilePathFromDownloadUrl(path);
+            const res = await get(this.fetch, `${this.url}/object/${this.bucketId}/${_path}`, {
+                headers: this.headers,
+                noResolveJson: true,
+                logFetch: this.loggerEnabled,
+                onRequestError: this.onRequestError
+            }, void 0, {
+                psmName: 'Storage.Download'
+            });
+            if (res.redirected) {
+                const resBody = await res.blob();
+                return {
+                    data: resBody,
+                    error: null
+                };
+            }
+            const resBody = await res.json();
+            return {
+                data: null,
+                error: resBody
+            };
+        } catch (error) {
+            if (error && 'object' == typeof error && 'originalError' in error) {
+                const originalError = error.originalError;
+                if (originalError instanceof Response && originalError.redirected) try {
+                    return {
+                        data: null,
+                        error: new StorageError(await originalError.text())
+                    };
+                } catch (_e) {
+                    return {
+                        data: null,
+                        error: new StorageUnknownError('download file error', error)
+                    };
+                }
+            }
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('download file error', error)
+            };
+        }
+    }
+    async remove(paths) {
+        try {
+            const _paths = paths.map((path)=>this._retrieveFilePathFromDownloadUrl(path));
+            const res = await remove(this.fetch, `${this.url}/object/${this.bucketId}`, {
+                prefixes: _paths
+            }, {
+                headers: this.headers,
+                logFetch: this.loggerEnabled,
+                onRequestError: this.onRequestError
+            }, void 0, {
+                psmName: 'Storage.Remove'
+            });
+            return {
+                data: res.data.map((file)=>transformFilePayload(file)),
+                error: null
+            };
+        } catch (error) {
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('remove file error', error)
+            };
+        }
+    }
+    async uploadFromUrl(url) {
+        try {
+            let parsedUrl;
+            try {
+                parsedUrl = new URL(url);
+            } catch  {
+                return {
+                    data: null,
+                    error: new StorageError('Invalid URL provided')
+                };
+            }
+            if ('http:' !== parsedUrl.protocol && 'https:' !== parsedUrl.protocol) return {
+                data: null,
+                error: new StorageError('Only http and https protocols are supported')
+            };
+            if (checkIsVolcEngineUrl(url)) {
+                const res = await this._copyWithinVolcEngine(url);
+                return {
+                    data: res,
+                    error: null
+                };
+            }
+            const response = await this.fetch(url);
+            if (!response.ok) return {
+                data: null,
+                error: new StorageError(`Failed to download file from URL: ${response.status} ${response.statusText}`)
+            };
+            const responseContentType = response.headers.get('content-type') || '';
+            const mimeType = responseContentType.split(';')[0].trim().toLowerCase();
+            const contentDisposition = response.headers.get('content-disposition');
+            const cacheControl = response.headers.get('cache-control');
+            const blob = await response.blob();
+            if (0 === blob.size) return {
+                data: null,
+                error: new StorageError('Downloaded file is empty')
+            };
+            const options = {};
+            if (mimeType) options.contentType = mimeType;
+            if (contentDisposition) options.contentDisposition = contentDisposition;
+            if (cacheControl) {
+                const maxAgeMatch = cacheControl.match(/max-age=(\d+)/i);
+                if (maxAgeMatch) options.cacheControl = Number.parseInt(maxAgeMatch[1], 10);
+            }
+            return this.uploadOrUpdate('', blob, options);
+        } catch (error) {
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('copy from url error', error)
+            };
+        }
+    }
+    async list(path, options, parameters) {
+        try {
+            const body = {
+                ...DEFAULT_SEARCH_OPTIONS,
+                ...options,
+                prefix: path || ''
+            };
+            const res = await post(this.fetch, `${this.url}/object/list/${this.bucketId}`, body, {
+                headers: this.headers,
+                logFetch: this.loggerEnabled,
+                onRequestError: this.onRequestError
+            }, parameters, {
+                psmName: 'Storage.List'
+            });
+            const transformedData = res.data.map((file)=>transformFilePayload(file));
+            return {
+                data: transformedData,
+                error: null
+            };
+        } catch (error) {
+            if (isCustomError(error) || isStorageError(error)) return {
+                data: null,
+                error: error
+            };
+            return {
+                data: null,
+                error: new StorageUnknownError('list file error', error)
+            };
+        }
+    }
+    generateDownloadUrlFromFilePath(filePath) {
+        return `/app/${this.appId}/runtime/api/v1/storage/object/${this.bucketId}/${encodeURIComponent(this._removeEmptyFolders(filePath))}`;
+    }
+    encodeMetadata(metadata) {
+        return JSON.stringify(metadata);
+    }
+    toBase64(data) {
+        if ('undefined' != typeof Buffer) return Buffer.from(data).toString('base64');
+        return btoa(data);
+    }
+    _getFinalPath(path) {
+        const _path = this._retrieveFilePathFromDownloadUrl(path);
+        return `${this.bucketId}/${_path.replace(/^\/+/, '')}`;
+    }
+    _removeEmptyFolders(path) {
+        if (!path) return path;
+        return path.replace(/^\/|\/$/g, '').replace(/\/+/g, '/');
+    }
+    _isValidDownloadUrl(url) {
+        return /^(\/spark)?\/app\/app_[\w]+\/runtime\/api\/v1\/storage\/object\//.test(url);
+    }
+    _retrieveFilePathFromDownloadUrl(url) {
+        if (!this._isValidDownloadUrl(url)) return url;
+        const objectPath = '/object/';
+        const objectIndex = url.indexOf(objectPath);
+        if (-1 === objectIndex) return '';
+        const afterObject = url.slice(objectIndex + objectPath.length);
+        const bucketEndIndex = afterObject.indexOf('/');
+        if (-1 !== bucketEndIndex) {
+            const result = afterObject.slice(bucketEndIndex + 1);
+            return decodeURIComponent(result);
+        }
+        return '';
+    }
+    async _copyWithinVolcEngine(url) {
+        const res = await post(this.fetch, `${this.url}/runtime/app/${this.appId}/object/${this.bucketId}/copy`, {
+            source: {
+                type: 'externalTOS',
+                externalURL: url
+            }
+        }, {
+            headers: this.headers,
+            logFetch: this.loggerEnabled,
+            onRequestError: this.onRequestError
+        }, void 0, {
+            psmName: 'Storage.Copy'
+        });
+        const { metadata } = res?.data ?? {};
+        return {
+            id: metadata?.id ?? '',
+            file_path: metadata?.filePath ?? '',
+            bucket_id: metadata?.bucketID ?? '',
+            download_url: metadata?.downloadURL ?? ''
+        };
+    }
+}
+export { StorageFileApi as default };

package/lib/storage/utils/logger.d.ts

@@ -0,0 +1,15 @@
+type FetchMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD';
+type LogParams = {
+    traceId: number;
+    url: string;
+    method: FetchMethod;
+    body?: unknown;
+};
+export declare const logRequest: (params: LogParams, psmName?: string) => void;
+export declare const logResponse: (traceId: number, response: {
+    data: any;
+    error: any;
+    status: number;
+}, psmName?: string) => void;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/lib/storage/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../src/storage/utils/logger.ts"],"names":[],"mappings":"AAAA,KAAK,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE9D,KAAK,SAAS,GAAG;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,SAAS,EAAE,gBAAmB,SAoBhE,CAAC;AAEF,eAAO,MAAM,WAAW,GACtB,SAAS,MAAM,EACf,UAAU;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,GAAG,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EACnD,gBAAmB,SA0BpB,CAAC"}

package/lib/storage/utils/logger.js

@@ -0,0 +1,18 @@
+const logRequest = (params, psmName = 'Storage')=>{
+    const { traceId, url, method, body } = params;
+    const decodedParams = Array.from(new URL(url).searchParams.entries()).filter(([key])=>![
+            'count',
+            'tx',
+            'missing',
+            'resolution',
+            'column'
+        ].includes(key)).map(([key, value])=>`${key}=${value}`);
+    console.log(`[Dataloom][${psmName}][Request]`, 'trace id:', traceId, 'method:', method, 'params:', decodedParams.join(','), 'body:', body);
+};
+const logResponse = (traceId, response, psmName = 'Storage')=>{
+    const { data, error, status } = response;
+    const hasError = !!error;
+    if (hasError) console.error(`[Dataloom][${psmName}][Response Failed]`, 'trace id:', traceId, 'statusCode:', status, 'error:', error);
+    else console.log(`[Dataloom][${psmName}][Response Success]`, 'trace id:', traceId, 'statusCode:', status, 'data:', data);
+};
+export { logRequest, logResponse };

package/lib/storage/utils/trace-id.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TraceIdGenerator
+ *
+ * A singleton class for generating auto-incrementing trace IDs within a process.
+ * Each call to next() returns a unique, incremented number.
+ *
+ * @example
+ *   const traceId = traceIdGenerator.next();
+ */
+declare class TraceIdGenerator {
+    /**
+     * The singleton instance of TraceIdGenerator.
+     */
+    private static instance;
+    /**
+     * The current trace id value.
+     */
+    private counter;
+    private constructor();
+    /**
+     * Get the singleton instance of TraceIdGenerator.
+     * @returns {TraceIdGenerator}
+     */
+    static getInstance(): TraceIdGenerator;
+    /**
+     * Get the next trace id (auto-increment).
+     * @returns {number} The next trace id.
+     */
+    next(): number;
+    /**
+     * Get the current trace id (without increment).
+     * @returns {number} The current trace id.
+     */
+    getCurrent(): number;
+    /**
+     * Reset the trace id counter to 1. (For testing or special use only)
+     */
+    reset(): void;
+}
+/**
+ * The singleton instance for trace id generation.
+ */
+declare const traceIdGenerator: TraceIdGenerator;
+export { TraceIdGenerator, traceIdGenerator };
+//# sourceMappingURL=trace-id.d.ts.map

package/lib/storage/utils/trace-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-id.d.ts","sourceRoot":"","sources":["../../../src/storage/utils/trace-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,cAAM,gBAAgB;IACpB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAmB;IAE1C;;OAEG;IACH,OAAO,CAAC,OAAO,CAAa;IAE5B,OAAO;IAEP;;;OAGG;WACW,WAAW,IAAI,gBAAgB;IAO7C;;;OAGG;IACI,IAAI,IAAI,MAAM;IAIrB;;;OAGG;IACI,UAAU,IAAI,MAAM;IAI3B;;OAEG;IACI,KAAK,IAAI,IAAI;CAGrB;AAED;;GAEG;AACH,QAAA,MAAM,gBAAgB,kBAAiC,CAAC;AAExD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC"}

package/lib/storage/utils/trace-id.js

@@ -0,0 +1,20 @@
+class TraceIdGenerator {
+    constructor(){
+        this.counter = 1;
+    }
+    static getInstance() {
+        if (!TraceIdGenerator.instance) TraceIdGenerator.instance = new TraceIdGenerator();
+        return TraceIdGenerator.instance;
+    }
+    next() {
+        return this.counter++;
+    }
+    getCurrent() {
+        return this.counter;
+    }
+    reset() {
+        this.counter = 1;
+    }
+}
+const traceIdGenerator = TraceIdGenerator.getInstance();
+export { TraceIdGenerator, traceIdGenerator };