@openinary/core 1.1.0

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

@@ -0,0 +1,188 @@
+import { StorageConfig, StorageClientOptions } from "./types";
+import { type FolderSummary, type LevelFile } from "../storage-level";
+import { type AggregateStats, type BucketStats, type StatsBackend } from "./stats-tracker";
+export declare class CloudStorage implements StatsBackend {
+    private s3Client;
+    private cache;
+    constructor(config: StorageConfig, clientOptions?: StorageClientOptions);
+    /**
+     * Lists objects in storage (cloud only)
+     */
+    list(prefix?: string): Promise<{
+        key: string;
+        size?: number;
+        lastModified?: Date;
+    }[]>;
+    /**
+     * Lists one directory level (direct child prefixes + objects) using Delimiter: "/"
+     */
+    listDelimited(prefix: string): Promise<{
+        prefixes: string[];
+        objects: {
+            key: string;
+            size?: number;
+            lastModified?: Date;
+        }[];
+    }>;
+    /**
+     * Lists a single page of one directory level (bounded by maxKeys)
+     */
+    listDelimitedPage(prefix: string, maxKeys?: number): Promise<{
+        prefixes: string[];
+        objects: {
+            key: string;
+            size?: number;
+            lastModified?: Date;
+        }[];
+        isTruncated: boolean;
+    }>;
+    /**
+     * Lists all objects under a prefix by fanning out one recursive listing per
+     * top-level folder in parallel, instead of a single sequential pagination
+     */
+    listAllParallel(prefix: string): Promise<{
+        key: string;
+        size?: number;
+        lastModified?: Date;
+    }[]>;
+    /**
+     * Lists one directory level of original files (under public/)
+     */
+    listLevel(folderPath: string): Promise<{
+        folderNames: string[];
+        files: LevelFile[];
+    }>;
+    /**
+     * Gets a bounded summary of a folder (direct child count, truncation flag,
+     * media preview items) from a single delimiter-listed page
+     */
+    getFolderSummary(folderPath: string, maxKeys?: number): Promise<FolderSummary>;
+    /**
+     * Creates a folder marker object so empty folders are visible in S3-compatible storage
+     */
+    createFolder(folderPath: string): Promise<void>;
+    /**
+     * Checks whether a folder exists (marker or any object with the folder prefix)
+     */
+    folderExists(folderPath: string): Promise<boolean>;
+    /**
+     * Renames/moves all objects under a folder prefix to a new prefix (copy + delete each)
+     */
+    renameFolder(oldFolderPath: string, newFolderPath: string): Promise<void>;
+    /**
+     * Deletes all objects under a folder prefix (marker + contents)
+     */
+    deleteFolder(folderPath: string): Promise<number>;
+    /**
+     * Checks file existence with intelligent caching for transformed files
+     */
+    exists(originalPath: string, params: any): Promise<boolean>;
+    /**
+     * Checks the existence of an original file with cache (by original path)
+     */
+    existsOriginal(originalPath: string): Promise<boolean>;
+    /**
+     * Checks the existence of an original file WITHOUT using cache
+     * Used after deletion to ensure we don't serve stale cache data
+     */
+    existsOriginalNoCache(originalPath: string): Promise<boolean>;
+    /**
+     * Checks existence of an arbitrary original-path key (without params),
+     * using the same semantics as uploadOriginal/downloadOriginal.
+     * This is useful for detecting duplicate uploads by full path.
+     */
+    existsOriginalPath(filePath: string): Promise<boolean>;
+    /**
+     * Retrieves an original (unprocessed) file from the bucket
+     */
+    downloadOriginal(originalPath: string): Promise<Buffer>;
+    /**
+     * Retrieves an original (unprocessed) file as a stream, without buffering
+     * it in memory. Used to serve large originals (e.g. videos still being
+     * optimized) directly to clients.
+     */
+    downloadOriginalStream(originalPath: string): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentLength?: number;
+        contentType?: string;
+    }>;
+    /**
+     * Uploads an original (unprocessed) file to the bucket
+     */
+    uploadOriginal(filePath: string, buffer: Buffer, contentType: string): Promise<string>;
+    /**
+     * Upload with cache invalidation
+     */
+    upload(originalPath: string, params: any, buffer: Buffer, contentType: string): Promise<string>;
+    /**
+     * Retrieves a file from the bucket
+     */
+    download(originalPath: string, params: any): Promise<Buffer>;
+    /**
+     * Generates a signed URL for temporary access (optional)
+     */
+    getSignedUrl(originalPath: string, params: any, expiresIn?: number): Promise<string>;
+    /**
+     * Deletes an original file from storage
+     */
+    deleteOriginal(originalPath: string): Promise<void>;
+    /**
+     * Copies an original file to a new path within storage
+     */
+    copyOriginal(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * Renames/moves an original file to a new path (copy + delete)
+     */
+    renameOriginal(sourcePath: string, destPath: string): Promise<void>;
+    /**
+     * Gets metadata for an original file (size, dates)
+     */
+    getOriginalMetadata(originalPath: string): Promise<{
+        size: number;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
+    /**
+     * Gets metadata for an optimized/transformed file (size only)
+     */
+    getOptimizedMetadata(originalPath: string, params: any): Promise<{
+        size: number;
+    } | null>;
+    /**
+     * Invalidates the cache for a specific file
+     */
+    invalidateCache(originalPath: string, params?: any): void;
+    /**
+     * Deletes all cached transformations for an original file from cloud storage
+     * Uses metadata to identify files belonging to the original path
+     */
+    deleteAllCachedTransformations(originalPath: string): Promise<number>;
+    /**
+     * Loads the persisted aggregate stats object, or null when it doesn't
+     * exist yet or is unreadable (triggering a recomputation)
+     */
+    loadPersistedStats(): Promise<BucketStats | null>;
+    /**
+     * Persists the aggregate stats object to the bucket
+     */
+    persistStats(stats: BucketStats): Promise<void>;
+    /**
+     * Recomputes aggregate stats from full bucket listings. O(n) in object
+     * count - only used to seed the tracker and for explicit reconciliation,
+     * never on the /storage/stats read path.
+     */
+    computeBucketStats(): Promise<{
+        storage: AggregateStats;
+        cache: AggregateStats;
+    }>;
+    /**
+     * Deletes all cached transformations from cloud storage and clears the in-memory cache
+     */
+    clearAllCache(): Promise<number>;
+    /**
+     * Invalidates all cache entries for a given original path
+     * This clears the in-memory cache for both the original file and all its transformations
+     */
+    invalidateAllCacheEntries(originalPath: string): void;
+}
+//# sourceMappingURL=cloud-storage.d.ts.map

package/dist/utils/storage/cloud-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-storage.d.ts","sourceRoot":"","sources":["../../../src/utils/storage/cloud-storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAezB,qBAAa,YAAa,YAAW,YAAY;IAC/C,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,KAAK,CAAe;gBAEhB,MAAM,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,oBAAoB;IAKvE;;OAEG;IACG,IAAI,CACR,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;IAIjE;;OAEG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAC3C,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,IAAI,CAAA;SAAE,EAAE,CAAC;KAChE,CAAC;IAIF;;OAEG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;QACT,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,YAAY,CAAC,EAAE,IAAI,CAAA;SAAE,EAAE,CAAC;QAC/D,WAAW,EAAE,OAAO,CAAC;KACtB,CAAC;IAIF;;;OAGG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;IAkBjE;;OAEG;IACG,SAAS,CACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,SAAS,EAAE,CAAA;KAAE,CAAC;IAMzD;;;OAGG;IACG,gBAAgB,CACpB,UAAU,EAAE,MAAM,EAClB,OAAO,SAA0B,GAChC,OAAO,CAAC,aAAa,CAAC;IAMzB;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrD;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYxD;;OAEG;IACG,YAAY,CAAC,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB/E;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAiCvD;;OAEG;IACG,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;IAqBjE;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI5D;;;OAGG;IACG,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyBnE;;;;OAIG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoC5D;;OAEG;IACG,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM7D;;;;OAIG;IACG,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC;QAC1D,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;QACnC,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IAKF;;OAEG;IACG,cAAc,CAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAiBlB;;OAEG;IACG,MAAM,CACV,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,GAAG,EACX,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC;IAuBlB;;OAEG;IACG,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC;IAKlE;;OAEG;IACG,YAAY,CAChB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,GAAG,EACX,SAAS,GAAE,MAAa,GACvB,OAAO,CAAC,MAAM,CAAC;IAKlB;;OAEG;IACG,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBzD;;OAEG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBvE;;OAEG;IACG,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKzE;;OAEG;IACG,mBAAmB,CACvB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,IAAI,CAAC;QAAC,SAAS,EAAE,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IAgBrE;;OAEG;IACG,oBAAoB,CACxB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,GAAG,GACV,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAanC;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI;IAQzD;;;OAGG;IACG,8BAA8B,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA2D3E;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IA0BvD;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrD;;;;OAIG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAClC,OAAO,EAAE,cAAc,CAAC;QACxB,KAAK,EAAE,cAAc,CAAC;KACvB,CAAC;IAsBF;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAmBtC;;;OAGG;IACH,yBAAyB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;CA0BtD"}