alepha 0.10.4 → 0.10.5

package/bucket.d.ts

@@ -561,11 +561,88 @@ declare class FileNotFoundError extends AlephaError {
   readonly status = 404;
 }
 //#endregion
+//#region src/services/FileMetadataService.d.ts
+interface FileMetadata {
+  name: string;
+  type: string;
+}
+/**
+ * Service for encoding/decoding file metadata in storage streams.
+ *
+ * The metadata is stored at the beginning of the file with the following structure:
+ * - 4-byte header: UInt32BE containing the metadata length
+ * - N-byte metadata: JSON object containing file metadata (name, type)
+ * - Remaining bytes: Actual file content
+ *
+ * @example
+ * ```typescript
+ * const service = new FileMetadataService();
+ *
+ * // Encode metadata and content for storage
+ * const { header, metadata } = service.encodeMetadata({
+ *   name: "document.pdf",
+ *   type: "application/pdf"
+ * });
+ *
+ * // Decode metadata from stored file
+ * const fileHandle = await open(filePath, 'r');
+ * const { metadata, contentStart } = await service.decodeMetadata(fileHandle);
+ * ```
+ */
+declare class FileMetadataService {
+  /**
+   * Length of the header containing metadata size (4 bytes for UInt32BE)
+   */
+  static readonly METADATA_HEADER_LENGTH = 4;
+  /**
+   * Encodes file metadata into header and metadata buffers.
+   *
+   * @param file - The file or metadata to encode
+   * @returns Object containing the header buffer and metadata buffer
+   */
+  encodeMetadata(file: FileLike | FileMetadata): {
+    header: Buffer;
+    metadata: Buffer;
+  };
+  /**
+   * Decodes file metadata from a file handle.
+   *
+   * @param fileHandle - File handle opened for reading
+   * @returns Object containing the decoded metadata and content start position
+   */
+  decodeMetadata(fileHandle: {
+    read: (buffer: Buffer, offset: number, length: number, position: number) => Promise<{
+      bytesRead: number;
+    }>;
+  }): Promise<{
+    metadata: FileMetadata;
+    contentStart: number;
+  }>;
+  /**
+   * Decodes file metadata from a buffer.
+   *
+   * @param buffer - Buffer containing the file with metadata
+   * @returns Object containing the decoded metadata and content start position
+   */
+  decodeMetadataFromBuffer(buffer: Buffer): {
+    metadata: FileMetadata;
+    contentStart: number;
+  };
+  /**
+   * Creates a complete buffer with metadata header, metadata, and content.
+   *
+   * @param file - The file to encode
+   * @param content - The file content as a buffer
+   * @returns Complete buffer ready for storage
+   */
+  createFileBuffer(file: FileLike | FileMetadata, content: Buffer): Buffer;
+}
+//#endregion
 //#region src/providers/LocalFileStorageProvider.d.ts
 declare class LocalFileStorageProvider implements FileStorageProvider {
-  static METADATA_HEADER_LENGTH: number;
   protected readonly alepha: Alepha;
   protected readonly log: _alepha_logger0.Logger;
+  protected readonly metadataService: FileMetadataService;
   options: {
     storagePath: string;
   };
@@ -574,9 +651,9 @@ declare class LocalFileStorageProvider implements FileStorageProvider {
   download(bucketName: string, fileId: string): Promise<FileLike>;
   exists(bucketName: string, fileId: string): Promise<boolean>;
   delete(bucketName: string, fileId: string): Promise<void>;
-  protected stat(container: string, fileId: string): Promise<fs.Stats>;
+  protected stat(bucket: string, fileId: string): Promise<fs.Stats>;
   protected createId(): string;
-  protected path(container: string, fileId?: string): string;
+  protected path(bucket: string, fileId?: string): string;
   protected isErrorNoEntry(error: unknown): boolean;
 }
 declare const fileMetadataSchema: typebox0.TObject<{
@@ -620,5 +697,5 @@ declare module "alepha" {
  */
 declare const AlephaBucket: _alepha_core1.Service<_alepha_core1.Module<{}>>;
 //#endregion
-export { $bucket, AlephaBucket, BucketDescriptor, BucketDescriptorOptions, BucketFileOptions, FileNotFoundError, FileStorageProvider, LocalFileStorageProvider, MemoryFileStorageProvider, fileMetadataSchema };
+export { $bucket, AlephaBucket, BucketDescriptor, BucketDescriptorOptions, BucketFileOptions, FileMetadata, FileMetadataService, FileNotFoundError, FileStorageProvider, LocalFileStorageProvider, MemoryFileStorageProvider, fileMetadataSchema };
 //# sourceMappingURL=index.d.ts.map