@zucker-framework/storage 1.0.2 → 1.0.5

package/README.md

@@ -0,0 +1,19 @@
+# Storage
+
+## WebDAV streaming and directory APIs (unreleased)
+
+`WebDavStorage.uploadStream(readable, key, { contentType?, signal? })` streams through a bounded Node Transform to the WebDAV SDK without collecting the file. It counts bytes, awaits both the source pipeline and remote response, and aborts/destroys the streams on source failure, remote failure, setup failure or cancellation. Failed remote writes may leave a partial remote object: the provider does not promise atomic overwrite or delete a previous object on failure. Consumers retain recovery/commit policy.
+
+`download(key, { signal? })` checks stat is a file and returns `{ stream: Readable, size }` using the SDK's real read stream (no buffer conversion). Abort destroys the stream. Callers must consume or destroy returned streams and handle stream errors; a resolved download call does not mean all bytes have arrived.
+
+**Type compatibility:** `FileManager.download().stream` is now honestly typed as Node `Readable`, not an `fs.ReadStream` (WebDAV/S3 streams have no file descriptor/path). `FileManager.uploadStream` accepts `Readable`. Consumers using filesystem-specific stream properties must migrate. This is a public type-contract breaking correction; release/version it accordingly. Local and S3 streaming implementations are not changed by this WebDAV work.
+
+`list(prefix, { deep: false, includeDirectories: true, missing: 'throw' })` requests shallow entries including directories and propagates missing-directory errors for host fallback. Defaults preserve recursive files-only enumeration and empty-on-404 behavior. `WebDavEntry` includes the original `filename`, `basename`, `lastmod`, `type`, as well as generic `key`, `size`, `lastModified`, `contentType`.
+
+`ensureDirectory(key)` is public, recursively creates missing parents and coalesces concurrent uncancelled creation. All public keys retain base-path traversal protection. Cancellation-owned upload directory operations use their own SDK signal rather than sharing another caller's cancellation.
+
+Credentials remain required by default. Explicit `allowAnonymous: true` permits missing credentials for hosts that deliberately allow unauthenticated WebDAV endpoints; URL remains mandatory. This opt-in does not read environment variables or change host authentication policy. Storage logs never include credentials or endpoint URLs.
+
+The host owns URL-to-key normalization, public URL settings, tenant ownership, disk fallback/recovery paths and error disclosure. No in-memory fallback or product environment configuration is introduced.
+
+Verification includes SDK mocks and the actual installed WebDAV SDK against a local synthetic HTTP server. Neither demonstrates real infrastructure permissions, durability or remote cancellation cleanup.

package/dist/index.d.mts

@@ -1,6 +1,6 @@
+import { Readable } from 'node:stream';
 import { ReadStream } from 'fs';
 import { OnModuleDestroy, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
-import { ReadStream as ReadStream$1 } from 'node:fs';
 
 interface UploadOptions {
     contentType?: string;
@@ -19,6 +19,10 @@ interface UploadResult {
 }
 interface FileInfo {
     key: string;
+    /** Available when the provider exposes filesystem entries (e.g. WebDAV). */
+    type?: 'file' | 'directory';
+    filename?: string;
+    basename?: string;
     size: number;
     lastModified: Date;
     contentType?: string;
@@ -127,9 +131,9 @@ interface FileManager {
     readonly providerType: StorageProviderType;
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions): Promise<UploadResult>;
     download(key: string): Promise<{
-        stream: ReadStream;
+        stream: Readable;
         size: number;
     }>;
     delete(key: string): Promise<void>;
@@ -150,7 +154,7 @@ interface FileManager {
      * @param position 起始偏移量（字节）
      */
     downloadRange?(key: string, position: number, length?: number): Promise<{
-        stream: ReadStream;
+        stream: Readable;
         size: number;
     }>;
     /**
@@ -229,7 +233,7 @@ declare class LocalFileStorage implements FileManager {
     });
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, _options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions): Promise<UploadResult>;
     download(key: string): Promise<{
         stream: ReadStream;
         size: number;
@@ -295,9 +299,9 @@ declare class S3Storage implements FileManager, OnModuleDestroy {
     onModuleDestroy(): void;
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions): Promise<UploadResult>;
     download(key: string): Promise<{
-        stream: ReadStream;
+        stream: Readable;
         size: number;
     }>;
     delete(key: string): Promise<void>;
@@ -310,11 +314,19 @@ declare class S3Storage implements FileManager, OnModuleDestroy {
     move(sourceKey: string, destKey: string): Promise<void>;
 }
 
+interface WebDavEntry extends FileInfo {
+    type: 'file' | 'directory';
+    filename: string;
+    basename: string;
+    lastmod: string;
+}
 interface WebDavStorageOptions {
     /** WebDAV 服务地址，如 https://nextcloud.example.com/remote.php/dav/files/user */
     url: string;
-    username: string;
-    password: string;
+    username?: string;
+    password?: string;
+    /** Explicit opt-in for endpoints/consumer policies allowing missing credentials. Default false. */
+    allowAnonymous?: boolean;
     /** 公开访问 URL 前缀（可选） */
     publicUrl?: string;
     /** 基础路径前缀（可选，默认 '/'） */
@@ -333,23 +345,33 @@ declare class WebDavStorage implements FileManager {
     private getClient;
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
-    download(key: string): Promise<{
-        stream: ReadStream;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions & {
+        signal?: AbortSignal;
+    }): Promise<UploadResult>;
+    download(key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        stream: Readable;
         size: number;
     }>;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
     getPublicUrl(key: string): Promise<string>;
     getDownloadUrl(key: string): Promise<string>;
-    list(prefix: string): Promise<FileInfo[]>;
+    list(prefix: string, options?: {
+        deep?: boolean;
+        includeDirectories?: boolean;
+        missing?: 'empty' | 'throw';
+    }): Promise<WebDavEntry[]>;
     getFileInfo(key: string): Promise<FileInfo | undefined>;
     copy(sourceKey: string, destKey: string): Promise<void>;
     move(sourceKey: string, destKey: string): Promise<void>;
     /**
      * 递归创建目录
      */
-    private ensureDirectory;
+    /** Accepts a storage key, with the same traversal protection as upload. */
+    ensureDirectory(key: string): Promise<void>;
+    private ensureRemoteDirectory;
     private createDirectoryIfMissing;
     private resolvePath;
     private stripBasePath;
@@ -448,9 +470,9 @@ declare class UnavailableFileManager implements FileManager {
     isConfigured(): boolean;
     private unavailable;
     upload(_buffer: Buffer, _key: string, _options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(_stream: ReadStream$1, _key: string, _options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(_stream: Readable, _key: string, _options?: UploadOptions): Promise<UploadResult>;
     download(_key: string): Promise<{
-        stream: ReadStream$1;
+        stream: Readable;
         size: number;
     }>;
     delete(_key: string): Promise<void>;
@@ -529,4 +551,4 @@ declare enum StorageProvider {
     WEBDAV = "WEBDAV"
 }
 
-export { BufferedFileManagerStore, type BufferedObjectStore, type ChunkUploadState, DANGEROUS_EXTENSIONS, type DownloadedStorageObject, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, StorageTransferError, type StorageTransferErrorCode, type StorageTransferErrorFactory, type StorageUrlHydrationOptions, UnavailableFileManager, type UploadOptions, type UploadResult, type VerifiedObjectTransferOptions, type VerifiedStorageMetadata, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, hydrateStorageUrls, isFileDenied, isSafeOriginalFileName, sanitizeFileName, transferVerifiedObject, verifyStoredObject };
+export { BufferedFileManagerStore, type BufferedObjectStore, type ChunkUploadState, DANGEROUS_EXTENSIONS, type DownloadedStorageObject, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, StorageTransferError, type StorageTransferErrorCode, type StorageTransferErrorFactory, type StorageUrlHydrationOptions, UnavailableFileManager, type UploadOptions, type UploadResult, type VerifiedObjectTransferOptions, type VerifiedStorageMetadata, type WebDavEntry, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, hydrateStorageUrls, isFileDenied, isSafeOriginalFileName, sanitizeFileName, transferVerifiedObject, verifyStoredObject };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
+import { Readable } from 'node:stream';
 import { ReadStream } from 'fs';
 import { OnModuleDestroy, Type, DynamicModule, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
-import { ReadStream as ReadStream$1 } from 'node:fs';
 
 interface UploadOptions {
     contentType?: string;
@@ -19,6 +19,10 @@ interface UploadResult {
 }
 interface FileInfo {
     key: string;
+    /** Available when the provider exposes filesystem entries (e.g. WebDAV). */
+    type?: 'file' | 'directory';
+    filename?: string;
+    basename?: string;
     size: number;
     lastModified: Date;
     contentType?: string;
@@ -127,9 +131,9 @@ interface FileManager {
     readonly providerType: StorageProviderType;
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions): Promise<UploadResult>;
     download(key: string): Promise<{
-        stream: ReadStream;
+        stream: Readable;
         size: number;
     }>;
     delete(key: string): Promise<void>;
@@ -150,7 +154,7 @@ interface FileManager {
      * @param position 起始偏移量（字节）
      */
     downloadRange?(key: string, position: number, length?: number): Promise<{
-        stream: ReadStream;
+        stream: Readable;
         size: number;
     }>;
     /**
@@ -229,7 +233,7 @@ declare class LocalFileStorage implements FileManager {
     });
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, _options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions): Promise<UploadResult>;
     download(key: string): Promise<{
         stream: ReadStream;
         size: number;
@@ -295,9 +299,9 @@ declare class S3Storage implements FileManager, OnModuleDestroy {
     onModuleDestroy(): void;
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions): Promise<UploadResult>;
     download(key: string): Promise<{
-        stream: ReadStream;
+        stream: Readable;
         size: number;
     }>;
     delete(key: string): Promise<void>;
@@ -310,11 +314,19 @@ declare class S3Storage implements FileManager, OnModuleDestroy {
     move(sourceKey: string, destKey: string): Promise<void>;
 }
 
+interface WebDavEntry extends FileInfo {
+    type: 'file' | 'directory';
+    filename: string;
+    basename: string;
+    lastmod: string;
+}
 interface WebDavStorageOptions {
     /** WebDAV 服务地址，如 https://nextcloud.example.com/remote.php/dav/files/user */
     url: string;
-    username: string;
-    password: string;
+    username?: string;
+    password?: string;
+    /** Explicit opt-in for endpoints/consumer policies allowing missing credentials. Default false. */
+    allowAnonymous?: boolean;
     /** 公开访问 URL 前缀（可选） */
     publicUrl?: string;
     /** 基础路径前缀（可选，默认 '/'） */
@@ -333,23 +345,33 @@ declare class WebDavStorage implements FileManager {
     private getClient;
     isConfigured(): boolean;
     upload(buffer: Buffer, key: string, options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(stream: ReadStream, key: string, options?: UploadOptions): Promise<UploadResult>;
-    download(key: string): Promise<{
-        stream: ReadStream;
+    uploadStream(stream: Readable, key: string, options?: UploadOptions & {
+        signal?: AbortSignal;
+    }): Promise<UploadResult>;
+    download(key: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        stream: Readable;
         size: number;
     }>;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
     getPublicUrl(key: string): Promise<string>;
     getDownloadUrl(key: string): Promise<string>;
-    list(prefix: string): Promise<FileInfo[]>;
+    list(prefix: string, options?: {
+        deep?: boolean;
+        includeDirectories?: boolean;
+        missing?: 'empty' | 'throw';
+    }): Promise<WebDavEntry[]>;
     getFileInfo(key: string): Promise<FileInfo | undefined>;
     copy(sourceKey: string, destKey: string): Promise<void>;
     move(sourceKey: string, destKey: string): Promise<void>;
     /**
      * 递归创建目录
      */
-    private ensureDirectory;
+    /** Accepts a storage key, with the same traversal protection as upload. */
+    ensureDirectory(key: string): Promise<void>;
+    private ensureRemoteDirectory;
     private createDirectoryIfMissing;
     private resolvePath;
     private stripBasePath;
@@ -448,9 +470,9 @@ declare class UnavailableFileManager implements FileManager {
     isConfigured(): boolean;
     private unavailable;
     upload(_buffer: Buffer, _key: string, _options?: UploadOptions): Promise<UploadResult>;
-    uploadStream(_stream: ReadStream$1, _key: string, _options?: UploadOptions): Promise<UploadResult>;
+    uploadStream(_stream: Readable, _key: string, _options?: UploadOptions): Promise<UploadResult>;
     download(_key: string): Promise<{
-        stream: ReadStream$1;
+        stream: Readable;
         size: number;
     }>;
     delete(_key: string): Promise<void>;
@@ -529,4 +551,4 @@ declare enum StorageProvider {
     WEBDAV = "WEBDAV"
 }
 
-export { BufferedFileManagerStore, type BufferedObjectStore, type ChunkUploadState, DANGEROUS_EXTENSIONS, type DownloadedStorageObject, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, StorageTransferError, type StorageTransferErrorCode, type StorageTransferErrorFactory, type StorageUrlHydrationOptions, UnavailableFileManager, type UploadOptions, type UploadResult, type VerifiedObjectTransferOptions, type VerifiedStorageMetadata, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, hydrateStorageUrls, isFileDenied, isSafeOriginalFileName, sanitizeFileName, transferVerifiedObject, verifyStoredObject };
+export { BufferedFileManagerStore, type BufferedObjectStore, type ChunkUploadState, DANGEROUS_EXTENSIONS, type DownloadedStorageObject, FILE_MANAGER, type FileInfo, FileLifecycleManager, type FileLifecyclePolicy, type FileManager, type FileMetadata, type FileUploadValidation, type LifecycleResult, LocalFileStorage, type PosixFilePermissions, type S3ObjectAclMode, S3Storage, type S3StorageOptions, type S3UploadUrlMode, type StorageModuleAsyncOptions, type StorageModuleOptions, type StorageModuleOptionsFactory, StorageProvider, type StorageProviderType, StorageTransferError, type StorageTransferErrorCode, type StorageTransferErrorFactory, type StorageUrlHydrationOptions, UnavailableFileManager, type UploadOptions, type UploadResult, type VerifiedObjectTransferOptions, type VerifiedStorageMetadata, type WebDavEntry, WebDavStorage, type WebDavStorageOptions, ZuckerStorageModule, generateDateBasedKey, hydrateStorageUrls, isFileDenied, isSafeOriginalFileName, sanitizeFileName, transferVerifiedObject, verifyStoredObject };

package/dist/index.js

@@ -437,6 +437,7 @@ LocalFileStorage = _ts_decorate([
 var import_common2 = require("@nestjs/common");
 var import_client_s3 = require("@aws-sdk/client-s3");
 var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
+var import_node_stream = require("stream");
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -529,6 +530,9 @@ var S3Storage = class _S3Storage {
     if (!response.Body) {
       throw new Error("Stored object response had no body");
     }
+    if (!(response.Body instanceof import_node_stream.Readable)) {
+      throw new Error("Stored object response must be a Node readable stream");
+    }
     return {
       stream: response.Body,
       size: response.ContentLength ?? 0
@@ -635,7 +639,8 @@ __name(encodeKeyPath, "encodeKeyPath");
 // src/webdav-storage.ts
 var import_common3 = require("@nestjs/common");
 var path2 = __toESM(require("path"));
-var import_stream = require("stream");
+var import_node_stream2 = require("stream");
+var import_promises = require("stream/promises");
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -668,7 +673,7 @@ var WebDavStorage = class _WebDavStorage {
   providerType = "webdav";
   options;
   constructor(options) {
-    if (!options.url || !options.username || !options.password) {
+    if (!options.url || !options.allowAnonymous && (!options.username || !options.password)) {
       throw new Error("WebDAV url, username and password are required");
     }
     this.options = options;
@@ -695,7 +700,7 @@ var WebDavStorage = class _WebDavStorage {
     const remotePath = this.resolvePath(key);
     const parentDir = remotePath.substring(0, remotePath.lastIndexOf("/"));
     if (parentDir && parentDir !== "/") {
-      await this.ensureDirectory(parentDir);
+      await this.ensureRemoteDirectory(parentDir);
     }
     await client.putFileContents(remotePath, buffer, {
       contentLength: buffer.length,
@@ -711,21 +716,87 @@ var WebDavStorage = class _WebDavStorage {
     };
   }
   async uploadStream(stream, key, options) {
-    const chunks = [];
-    for await (const chunk of stream) {
-      chunks.push(Buffer.from(chunk));
+    const controller = new AbortController();
+    const abort = /* @__PURE__ */ __name(() => controller.abort(options?.signal?.reason), "abort");
+    options?.signal?.addEventListener("abort", abort, {
+      once: true
+    });
+    if (options?.signal?.aborted) abort();
+    let size = 0;
+    const counter = new import_node_stream2.Transform({
+      transform(chunk, _encoding, callback) {
+        size += chunk.length;
+        callback(null, chunk);
+      }
+    });
+    let transfer;
+    let pumping;
+    const sourceError = /* @__PURE__ */ __name((error) => controller.abort(error), "sourceError");
+    stream.on("error", sourceError);
+    (0, import_node_stream2.addAbortSignal)(controller.signal, stream);
+    try {
+      controller.signal.throwIfAborted();
+      const client = await this.getClient();
+      const remotePath = this.resolvePath(key);
+      await this.ensureRemoteDirectory(path2.posix.dirname(remotePath), controller.signal);
+      controller.signal.throwIfAborted();
+      transfer = client.putFileContents(remotePath, counter, {
+        overwrite: true,
+        contentLength: false,
+        signal: controller.signal,
+        headers: options?.contentType ? {
+          "Content-Type": options.contentType
+        } : void 0
+      });
+      pumping = (0, import_promises.pipeline)(stream, counter, {
+        signal: controller.signal
+      });
+      await Promise.all([
+        transfer,
+        pumping
+      ]);
+      return {
+        key,
+        url: this.buildUrl(key),
+        size
+      };
+    } catch (error) {
+      controller.abort(error);
+      stream.destroy(error instanceof Error ? error : new Error("Storage upload failed"));
+      counter.destroy();
+      await Promise.allSettled([
+        transfer,
+        pumping,
+        (0, import_promises.finished)(stream, {
+          cleanup: true
+        })
+      ]);
+      throw error;
+    } finally {
+      options?.signal?.removeEventListener("abort", abort);
+      stream.off("error", sourceError);
     }
-    return this.upload(Buffer.concat(chunks), key, options);
   }
-  async download(key) {
+  async download(key, options) {
+    options?.signal?.throwIfAborted();
     const client = await this.getClient();
     const remotePath = this.resolvePath(key);
-    const stat = await client.stat(remotePath);
-    const buffer = await client.getFileContents(remotePath);
-    const readable = import_stream.Readable.from(buffer);
+    const stat = await client.stat(remotePath, ...options?.signal ? [
+      {
+        signal: options.signal
+      }
+    ] : []);
+    if (stat.type !== "file") throw new Error("Remote path is not a file");
+    options?.signal?.throwIfAborted();
+    const stream = client.createReadStream(remotePath, ...options?.signal ? [
+      {
+        signal: options.signal
+      }
+    ] : []);
+    if (options?.signal) (0, import_node_stream2.addAbortSignal)(options.signal, stream);
     return {
-      stream: readable,
-      size: stat.size ?? buffer.length
+      stream,
+      size: stat.size
     };
   }
   async delete(key) {
@@ -750,22 +821,26 @@ var WebDavStorage = class _WebDavStorage {
   async getDownloadUrl(key) {
     return this.getPublicUrl(key);
   }
-  async list(prefix) {
+  async list(prefix, options = {}) {
     const client = await this.getClient();
     const remotePath = this.resolvePath(prefix);
     try {
       const items = await client.getDirectoryContents(remotePath, {
-        deep: true
+        deep: options.deep ?? true
       });
-      return items.filter((item) => item.type === "file").map((item) => ({
+      return items.filter((item) => item.type === "file" || options.includeDirectories).map((item) => ({
         key: this.stripBasePath(item.filename),
+        type: item.type,
+        filename: item.filename,
+        basename: item.basename,
+        lastmod: item.lastmod,
         size: item.size ?? 0,
         lastModified: new Date(item.lastmod ?? Date.now()),
         contentType: item.mime
       }));
     } catch (error) {
       const err = error;
-      if (err.status === 404) return [];
+      if (err.status === 404 && options.missing !== "throw") return [];
       throw error;
     }
   }
@@ -810,7 +885,12 @@ var WebDavStorage = class _WebDavStorage {
   /**
   * 递归创建目录
   */
-  async ensureDirectory(dirPath) {
+  /** Accepts a storage key, with the same traversal protection as upload. */
+  async ensureDirectory(key) {
+    return this.ensureRemoteDirectory(this.resolvePath(key));
+  }
+  async ensureRemoteDirectory(dirPath, signal) {
+    if (signal) return this.createDirectoryIfMissing(dirPath, signal);
     const inflight = this.directoryPromises.get(dirPath);
     if (inflight) return inflight;
     const creation = this.createDirectoryIfMissing(dirPath);
@@ -823,21 +903,35 @@ var WebDavStorage = class _WebDavStorage {
       }
     }
   }
-  async createDirectoryIfMissing(dirPath) {
+  async createDirectoryIfMissing(dirPath, signal) {
+    signal?.throwIfAborted();
     const client = await this.getClient();
-    if (await client.exists(dirPath)) return;
+    if (await client.exists(dirPath, ...signal ? [
+      {
+        signal
+      }
+    ] : [])) return;
     const parent = dirPath.substring(0, dirPath.lastIndexOf("/"));
     if (parent && parent !== "/") {
-      await this.ensureDirectory(parent);
+      await this.ensureRemoteDirectory(parent, signal);
     }
     try {
-      await client.createDirectory(dirPath);
+      signal?.throwIfAborted();
+      await client.createDirectory(dirPath, ...signal ? [
+        {
+          signal
+        }
+      ] : []);
     } catch (error) {
       const status = error.status;
       if ([
         405,
         409
-      ].includes(status ?? 0) && await client.exists(dirPath)) return;
+      ].includes(status ?? 0) && await client.exists(dirPath, ...signal ? [
+        {
+          signal
+        }
+      ] : [])) return;
       throw error;
     }
   }

package/dist/index.mjs

@@ -386,6 +386,7 @@ LocalFileStorage = _ts_decorate([
 import { Injectable as Injectable2, Logger as Logger2 } from "@nestjs/common";
 import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, HeadObjectCommand, ListObjectsV2Command, CopyObjectCommand } from "@aws-sdk/client-s3";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { Readable } from "stream";
 function _ts_decorate2(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -478,6 +479,9 @@ var S3Storage = class _S3Storage {
     if (!response.Body) {
       throw new Error("Stored object response had no body");
     }
+    if (!(response.Body instanceof Readable)) {
+      throw new Error("Stored object response must be a Node readable stream");
+    }
     return {
       stream: response.Body,
       size: response.ContentLength ?? 0
@@ -584,7 +588,8 @@ __name(encodeKeyPath, "encodeKeyPath");
 // src/webdav-storage.ts
 import { Injectable as Injectable3, Logger as Logger3 } from "@nestjs/common";
 import * as path2 from "path";
-import { Readable } from "stream";
+import { Transform, addAbortSignal } from "stream";
+import { pipeline, finished } from "stream/promises";
 function _ts_decorate3(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -617,7 +622,7 @@ var WebDavStorage = class _WebDavStorage {
   providerType = "webdav";
   options;
   constructor(options) {
-    if (!options.url || !options.username || !options.password) {
+    if (!options.url || !options.allowAnonymous && (!options.username || !options.password)) {
       throw new Error("WebDAV url, username and password are required");
     }
     this.options = options;
@@ -644,7 +649,7 @@ var WebDavStorage = class _WebDavStorage {
     const remotePath = this.resolvePath(key);
     const parentDir = remotePath.substring(0, remotePath.lastIndexOf("/"));
     if (parentDir && parentDir !== "/") {
-      await this.ensureDirectory(parentDir);
+      await this.ensureRemoteDirectory(parentDir);
     }
     await client.putFileContents(remotePath, buffer, {
       contentLength: buffer.length,
@@ -660,21 +665,87 @@ var WebDavStorage = class _WebDavStorage {
     };
   }
   async uploadStream(stream, key, options) {
-    const chunks = [];
-    for await (const chunk of stream) {
-      chunks.push(Buffer.from(chunk));
+    const controller = new AbortController();
+    const abort = /* @__PURE__ */ __name(() => controller.abort(options?.signal?.reason), "abort");
+    options?.signal?.addEventListener("abort", abort, {
+      once: true
+    });
+    if (options?.signal?.aborted) abort();
+    let size = 0;
+    const counter = new Transform({
+      transform(chunk, _encoding, callback) {
+        size += chunk.length;
+        callback(null, chunk);
+      }
+    });
+    let transfer;
+    let pumping;
+    const sourceError = /* @__PURE__ */ __name((error) => controller.abort(error), "sourceError");
+    stream.on("error", sourceError);
+    addAbortSignal(controller.signal, stream);
+    try {
+      controller.signal.throwIfAborted();
+      const client = await this.getClient();
+      const remotePath = this.resolvePath(key);
+      await this.ensureRemoteDirectory(path2.posix.dirname(remotePath), controller.signal);
+      controller.signal.throwIfAborted();
+      transfer = client.putFileContents(remotePath, counter, {
+        overwrite: true,
+        contentLength: false,
+        signal: controller.signal,
+        headers: options?.contentType ? {
+          "Content-Type": options.contentType
+        } : void 0
+      });
+      pumping = pipeline(stream, counter, {
+        signal: controller.signal
+      });
+      await Promise.all([
+        transfer,
+        pumping
+      ]);
+      return {
+        key,
+        url: this.buildUrl(key),
+        size
+      };
+    } catch (error) {
+      controller.abort(error);
+      stream.destroy(error instanceof Error ? error : new Error("Storage upload failed"));
+      counter.destroy();
+      await Promise.allSettled([
+        transfer,
+        pumping,
+        finished(stream, {
+          cleanup: true
+        })
+      ]);
+      throw error;
+    } finally {
+      options?.signal?.removeEventListener("abort", abort);
+      stream.off("error", sourceError);
     }
-    return this.upload(Buffer.concat(chunks), key, options);
   }
-  async download(key) {
+  async download(key, options) {
+    options?.signal?.throwIfAborted();
     const client = await this.getClient();
     const remotePath = this.resolvePath(key);
-    const stat = await client.stat(remotePath);
-    const buffer = await client.getFileContents(remotePath);
-    const readable = Readable.from(buffer);
+    const stat = await client.stat(remotePath, ...options?.signal ? [
+      {
+        signal: options.signal
+      }
+    ] : []);
+    if (stat.type !== "file") throw new Error("Remote path is not a file");
+    options?.signal?.throwIfAborted();
+    const stream = client.createReadStream(remotePath, ...options?.signal ? [
+      {
+        signal: options.signal
+      }
+    ] : []);
+    if (options?.signal) addAbortSignal(options.signal, stream);
     return {
-      stream: readable,
-      size: stat.size ?? buffer.length
+      stream,
+      size: stat.size
     };
   }
   async delete(key) {
@@ -699,22 +770,26 @@ var WebDavStorage = class _WebDavStorage {
   async getDownloadUrl(key) {
     return this.getPublicUrl(key);
   }
-  async list(prefix) {
+  async list(prefix, options = {}) {
     const client = await this.getClient();
     const remotePath = this.resolvePath(prefix);
     try {
       const items = await client.getDirectoryContents(remotePath, {
-        deep: true
+        deep: options.deep ?? true
       });
-      return items.filter((item) => item.type === "file").map((item) => ({
+      return items.filter((item) => item.type === "file" || options.includeDirectories).map((item) => ({
         key: this.stripBasePath(item.filename),
+        type: item.type,
+        filename: item.filename,
+        basename: item.basename,
+        lastmod: item.lastmod,
         size: item.size ?? 0,
         lastModified: new Date(item.lastmod ?? Date.now()),
         contentType: item.mime
       }));
     } catch (error) {
       const err = error;
-      if (err.status === 404) return [];
+      if (err.status === 404 && options.missing !== "throw") return [];
       throw error;
     }
   }
@@ -759,7 +834,12 @@ var WebDavStorage = class _WebDavStorage {
   /**
   * 递归创建目录
   */
-  async ensureDirectory(dirPath) {
+  /** Accepts a storage key, with the same traversal protection as upload. */
+  async ensureDirectory(key) {
+    return this.ensureRemoteDirectory(this.resolvePath(key));
+  }
+  async ensureRemoteDirectory(dirPath, signal) {
+    if (signal) return this.createDirectoryIfMissing(dirPath, signal);
     const inflight = this.directoryPromises.get(dirPath);
     if (inflight) return inflight;
     const creation = this.createDirectoryIfMissing(dirPath);
@@ -772,21 +852,35 @@ var WebDavStorage = class _WebDavStorage {
       }
     }
   }
-  async createDirectoryIfMissing(dirPath) {
+  async createDirectoryIfMissing(dirPath, signal) {
+    signal?.throwIfAborted();
     const client = await this.getClient();
-    if (await client.exists(dirPath)) return;
+    if (await client.exists(dirPath, ...signal ? [
+      {
+        signal
+      }
+    ] : [])) return;
     const parent = dirPath.substring(0, dirPath.lastIndexOf("/"));
     if (parent && parent !== "/") {
-      await this.ensureDirectory(parent);
+      await this.ensureRemoteDirectory(parent, signal);
     }
     try {
-      await client.createDirectory(dirPath);
+      signal?.throwIfAborted();
+      await client.createDirectory(dirPath, ...signal ? [
+        {
+          signal
+        }
+      ] : []);
     } catch (error) {
       const status = error.status;
       if ([
         405,
         409
-      ].includes(status ?? 0) && await client.exists(dirPath)) return;
+      ].includes(status ?? 0) && await client.exists(dirPath, ...signal ? [
+        {
+          signal
+        }
+      ] : [])) return;
       throw error;
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zucker-framework/storage",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",