@ccci/micro-server 1.1.3 → 1.1.5

package/dist/test/Uploader.integration.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Uploader.integration.test.d.ts.map

package/dist/types/ApplicationOptionType.d.ts

@@ -32,5 +32,6 @@ export type ApplicationOptionType = {
     s3region?: string;
     s3AccessKeyId?: string;
     s3SecretAccessKey?: string;
+    appVersion?: string;
 };
 //# sourceMappingURL=ApplicationOptionType.d.ts.map

package/dist/types/UploadedFileType.d.ts

@@ -8,4 +8,61 @@ export type UploadedFileType = {
     location?: string;
     filesize?: number;
 };
+export type InitUpload = {
+    uploadId: string;
+    minioUploadId: string;
+    pathName: string;
+    message: string;
+};
+export type UploadPartConfig = {
+    bucketName: string;
+    objectName: string;
+    uploadID: string;
+    partNumber: number;
+    headers: unknown;
+};
+export type UploadSession = {
+    bucket: string;
+    uploadId: string;
+    fileName: string;
+    objectName: string;
+    minioUploadId: string;
+    parts: Array<{
+        part: number;
+        etag: string;
+    }>;
+    metadata?: Record<string, string>;
+    createdAt: Date;
+};
+export type UploadChunk = {
+    uploadId: string;
+    chunkNumber: number;
+    etag: string;
+    key: string;
+    part: number;
+    uploadedPart: number;
+    message: string;
+};
+export type CompleteUploadResult = {
+    etag: {
+        versionId: string;
+        etag: string;
+    };
+    path: string;
+    bucket: string;
+    location: string;
+    fileSize: number;
+    mimeType: string;
+    objectName: string;
+};
+export type UploadTypes = {
+    bucket: string;
+    objectKey: string;
+    objectName: string;
+};
+export type UploadPart = {
+    etag: string;
+    key: string;
+    part: number;
+};
 //# sourceMappingURL=UploadedFileType.d.ts.map

package/dist/utils/BaseRedis.d.ts

@@ -0,0 +1,36 @@
+import type { RedisClientType } from "redis";
+import { BaseRedisConnector } from "./BaseRedisConnector";
+import { type PaginatedResult, type QueryOptions } from "./RedisQueryHelper";
+export declare class BaseRedis extends BaseRedisConnector {
+    private clientReady?;
+    protected constructor();
+    protected ready: () => Promise<RedisClientType>;
+    private chunk;
+    /**
+     * Bounded, index-driven collection sync:
+     * - Stores IDs in a sorted set (score from scoreSelector)
+     * - Stores each item in a per-item hash
+     * - Trims oldest items beyond maxItems and unlinks their hashes
+     */
+    protected syncIndexedCollection: <T>(params: {
+        items: T[];
+        idSelector: (item: T) => string | number;
+        scoreSelector: (item: T) => number | Date;
+        indexKey: string;
+        itemPrefix: string;
+        maxItems: number;
+        ttlSeconds?: number;
+        batchSize?: number;
+    }) => Promise<void>;
+    /**
+     * Read indexed collection into memory (bounded by maxItems).
+     * Applies QueryHelper for search/sort/paginate.
+     */
+    protected getIndexedItems: <T>(params: {
+        indexKey: string;
+        itemPrefix: string;
+        options?: QueryOptions;
+        defaultSearchFields?: string[];
+    }) => Promise<T[] | PaginatedResult<T>>;
+}
+//# sourceMappingURL=BaseRedis.d.ts.map

package/dist/utils/BaseRedisConnector.d.ts

@@ -0,0 +1,10 @@
+import { type RedisClientType } from "redis";
+export declare class BaseRedisConnector {
+    private static client;
+    private static connectPromise;
+    protected client: RedisClientType;
+    protected constructor();
+    ensureConnected(): Promise<void>;
+    disconnect(): Promise<void>;
+}
+//# sourceMappingURL=BaseRedisConnector.d.ts.map

package/dist/utils/Mixins.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 /**
  * Retrieves the MIME type for a given file name based on its extension.
  * @param fileName - The name of the file to extract the MIME type for.
@@ -36,4 +37,36 @@ export declare const getCurrentWeek: () => {
     startOfWeek: Date;
     endOfWeek: Date;
 };
+/**
+ * Consumes a readable stream and aggregates all data chunks into a single Buffer.
+ * * @param {stream.Readable} res - The incoming data stream.
+ * @returns {Promise<Buffer>} A promise that resolves to the complete binary data.
+ */
+export declare function readAsBuffer(res: any): Promise<Buffer>;
+/**
+ * Reads an HTTP response body in its entirety and converts it to a string.
+ * Useful for parsing XML error messages or small metadata responses.
+ * * @param {http.IncomingMessage} res - The HTTP response object.
+ * @returns {Promise<string>} The body content decoded as a string.
+ */
+export declare function readAsString(res: any): Promise<string>;
+/**
+ * Parses an XML string into a JavaScript object using fast-xml-parser.
+ * * @throws {S3XmlError} If the XML contains an <Error> tag, it throws the error body.
+ */
+export declare const parseXml: (xml: string) => any;
+/**
+ * Specifically extracts the CopyPartResult from an S3 XML response.
+ * Used during multipart copy operations or part uploads that return XML.
+ */
+export declare const uploadPartParser: (xml: string) => any;
+/**
+ * Removes various encodings of double quotes from the start and end of an ETag.
+ * * @description
+ *  S3-compatible storage often returns ETags wrapped in literal quotes or
+ *  HTML entities. This regex-based sanitizer ensures only the raw hash remains.
+ * @param {string} [etag=''] - The raw ETag string from headers or XML.
+ * @returns {string} The cleaned ETag.
+ */
+export declare const sanitizeETag: (etag: string) => string;
 //# sourceMappingURL=Mixins.d.ts.map

package/dist/utils/RedisQueryHelper.d.ts

@@ -0,0 +1,38 @@
+export type QueryOptions = {
+    forceRefresh?: boolean;
+    paginate?: boolean;
+    limit?: number;
+    page?: number;
+    sort?: string;
+    search?: string;
+    fulltext?: boolean;
+    defaultSearchFields?: string[];
+};
+export type PaginatedResult<T> = {
+    rows: T[];
+    count: number;
+    meta: {
+        total: number;
+        limit: number;
+        page: number;
+        totalPages: number;
+        hasNextPage: boolean;
+        hasPrevPage: boolean;
+        sort: string;
+    };
+};
+type SearchOptions = {
+    fulltext?: boolean;
+    defaultFields?: string[];
+};
+export declare class QueryHelper {
+    private static getFieldValue;
+    private static buildHaystack;
+    private static matchesSearch;
+    static filterBySearch<T>(items: T[], search: string, options?: SearchOptions): T[];
+    static sort<T>(items: T[], sort: string): T[];
+    static paginate<T>(items: T[], limit: number, page: number, sort: string): PaginatedResult<T>;
+    static applyQuery<T>(items: T[], options?: QueryOptions): T[] | PaginatedResult<T>;
+}
+export {};
+//# sourceMappingURL=RedisQueryHelper.d.ts.map

package/dist/utils/Uploader.d.ts

@@ -1,10 +1,12 @@
+/// <reference types="node" />
 import { UploadedFile } from 'express-fileupload';
 import * as minio from 'minio';
 import { ApplicationOptionType } from '..';
-import { UploadedFileType } from '@/types/UploadedFileType';
+import { UploadedFileType, InitUpload, UploadChunk, CompleteUploadResult, UploadTypes, UploadPart } from '@/types/UploadedFileType';
 import { RemoveOptions } from 'minio';
 export default class Uploader {
     static client: minio.Client;
+    static clientEndpoint: string;
     constructor();
     /**
      * Initializes the minIO client instance
@@ -29,5 +31,97 @@ export default class Uploader {
      */
     preview(bucket: string, file: string): Promise<void>;
     static delete(bucketName: string, objectName: string, removeOpts?: RemoveOptions): Promise<void>;
+    /**
+     * Permanently cancels all pending multipart uploads within a specified S3/MinIO bucket.
+     * @description
+     *  This is a cleanup utility. Incomplete multipart uploads occupy storage space but are not visible as objects. This method iterates through the bucket's "incomplete" stream and issues an abort command for each. Use this to recover storage or clear stuck uploads after a service interruption.
+     * @param {string} bucketName - The unique identifier of the target MinIO bucket.
+     * @returns {Promise<void>} Resolves when the stream has finished processing all abort requests.
+     * @throws {Error} If the bucket is inaccessible or the list operation fails.
+     * @example
+     *  await Uploader.clearAllMultipartUploads('temp-uploads');
+     */
+    static clearAllMultipartUploads(bucketName: string): Promise<void>;
+    /**
+     * Starts a new multipart upload session and registers it in the local session cache.
+     * @description
+     * This method performs two actions:
+     *  1. Requests a new Multipart Upload ID from the MinIO/S3 server.
+     *  2. Initializes an internal tracking session in `uploadSessions` for part management.
+     * @param {string} bucket - Target bucket name.
+     * @param {string} fileName - The final destination filename/path.
+     * @param {Record<string, string>} [metadata={}] - Key-value pairs for S3 metadata.
+     * - Standard headers: `Content-Type`, `Cache-Control`, etc.
+     * - Custom tags: Use `X-Amz-meta-` prefix for custom attributes.
+     * @returns {Promise<InitUpload>}
+     *  Returns the internal session ID and the provider's upload ID.
+     * @throws {Error} If the connection to MinIO fails or the bucket does not exist.
+     */
+    static initiateUpload(bucket: string, fileName: string, metadata?: Record<string, string>): Promise<InitUpload>;
+    /**
+     * Processes and uploads a single data part to an active multipart session.
+     * @description
+     * This method normalizes various input formats (Buffer, string, or Uint8Array) into a binary Buffer, dispatches the upload to MinIO via `uploadPart`, and updates the  internal session state with the returned ETag.
+     * @param {string} uploadSessionId - The internal UUID generated during `initiateUpload`.
+     * @param {number} chunkNumber - The 1-based index of the part.
+     * @param {Buffer | string | Uint8Array} chunkData - The raw binary data or encoded string.
+     * @returns {Promise<UploadChunk>} Returns metadata about the uploaded part, including:
+     * - `etag`: The S3 identifier for this specific part (required for completion).
+     * - `uploadedPart`: The total count of parts successfully tracked in this session so far.
+     */
+    static uploadChunk(uploadSessionId: string, chunkNumber: number, chunkData: Buffer | string | Uint8Array): Promise<UploadChunk>;
+    /**
+     * Finalizes the multipart upload by assembling all uploaded parts into a single object.
+     * @description
+     * This method performs the final handshake with MinIO/S3. It:
+     * 1. Retrieves and sorts the accumulated ETags by part number (mandatory for S3 compliance).
+     * 2. Signals the storage server to merge the data parts.
+     * 3. Extracts file metadata (size, mime-type) from the session.
+     * 4. Purges the internal `uploadSessions` cache to prevent memory leaks.
+     * @param {string} uploadSessionId - The internal tracking ID of the session to be closed.
+     * @returns {Promise<Object>} A curated result object containing:
+     * - `etag`: The final entity tag for the completed object.
+     * - `location`: The public/internal URL of the uploaded file.
+     * - `fileSize`: Parsed size from the 'X-Amz-meta-filesize' metadata.
+     * @throws {Error} If parts are missing, the session is not found, or S3 assembly fails.
+     */
+    static completeUpload(uploadSessionId: string): Promise<CompleteUploadResult>;
+    /**
+     * Streams an object from storage directly to an HTTP response.
+     * @description
+     * Fetches object metadata (stat) to populate necessary download headers before
+     * piping the data stream to the client. This avoids loading the entire file
+     * into memory, making it efficient for large file transfers.
+     * * @param {Response} res - The Express/Node.js response object.
+     * @param {UploadTypes} options - Configuration object containing:
+     * - `bucket`: Target bucket name.
+     * - `objectKey`: The internal storage path (e.g., 'stream/123').
+     * - `objectName`: The "friendly" filename for the user's browser.
+     * @returns {Promise<void>} Resolves once the stream has been successfully piped.
+     * @throws {Error} If the object does not exist or metadata cannot be retrieved.
+     */
+    static streamDownload(res: any, { bucket, objectKey, objectName }: UploadTypes): Promise<void>;
+    /**
+     * Executes a low-level Multipart Upload Part request.
+     * * @description
+     *  This is a custom wrapper around the S3/MinIO PUT Object Part API. It manually constructs the query parameters and headers required for a part upload. Crucially, it handles inconsistent server responses by attempting to extract the ETag from both the response XML body and the HTTP headers.
+     * @param {Object} partConfig - Configuration for the specific part.
+     * @param {string} partConfig.bucketName - Target bucket.
+     * @param {string} partConfig.objectName - The internal path/key of the object.
+     * @param {string} partConfig.uploadID - The ID generated by `initiateNewMultipartUpload`.
+     * @param {number} partConfig.partNumber - 1-based index of the part.
+     * @param {unknown} partConfig.headers - HTTP headers (e.g., Content-Length, Content-MD5).
+     * @param {any} [payload] - The binary data buffer for this part.
+     * @returns {Promise<UploadPart>}
+     *  Returns a sanitized ETag required for the final `completeUpload` call.
+     * @throws {Error} If no ETag is found in the response or the network request fails.
+     */
+    static uploadPart: (partConfig: {
+        bucketName: string;
+        objectName: string;
+        uploadID: string;
+        partNumber: number;
+        headers: unknown;
+    }, payload?: any) => Promise<UploadPart>;
 }
 //# sourceMappingURL=Uploader.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccci/micro-server",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "module": "index.ts",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,10 @@
     "@types/nodemailer": "^6.4.15",
     "prettier": "^3.0.3",
     "rimraf": "^5.0.5",
-    "typescript": "^5.2.2"
+    "typescript": "^5.2.2",
+    "vite": "^5.0.10",
+    "vite-tsconfig-paths": "^6.1.0",
+    "vitest": "^1.1.0"
   },
   "peerDependencies": {
     "typescript": "^5.0.0"
@@ -45,6 +48,7 @@
     "express": "^4.19.2",
     "express-fileupload": "^1.5.0",
     "express-list-endpoints": "^7.1.1",
+    "fast-xml-parser": "^5.3.4",
     "firebase": "^10.13.1",
     "firebase-admin": "^12.4.0",
     "handlebars": "^4.7.8",
@@ -55,6 +59,7 @@
     "nodemailer": "^6.9.13",
     "pg": "^8.11.5",
     "pg-hstore": "^2.3.4",
+    "redis": "^5.11.0",
     "sequelize": "^6.37.3",
     "socket.io": "^4.7.5",
     "winston": "^3.13.0"