@maiyunnet/kebab 9.20.0 → 9.20.1

package/doc/kebab-rag.md

@@ -1589,7 +1589,7 @@ index/variables/VER.md
 
 # Variable: VER
 
-> `const` **VER**: `"9.20.0"` = `'9.20.0'`
+> `const` **VER**: `"9.20.1"` = `'9.20.1'`
 
 Defined in: [index.ts:10](https://github.com/maiyunnet/kebab/blob/master/index.ts#L10)
 
@@ -122018,7 +122018,7 @@ Defined in: [lib/s3.ts:88](https://github.com/maiyunnet/kebab/blob/master/lib/s3
 
 > **deleteObject**(`key`, `bucket?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/s3.ts:279](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L279)
+Defined in: [lib/s3.ts:367](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L367)
 
 删除对象
 
@@ -122046,7 +122046,7 @@ bucket 名
 
 > **deleteObjects**(`keys`, `bucket?`): `Promise`\<`boolean`\>
 
-Defined in: [lib/s3.ts:299](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L299)
+Defined in: [lib/s3.ts:387](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L387)
 
 批量删除对象
 
@@ -122074,7 +122074,7 @@ bucket 名
 
 > **destroy**(): `void`
 
-Defined in: [lib/s3.ts:341](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L341)
+Defined in: [lib/s3.ts:429](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L429)
 
 销毁连接，释放资源
 一般会自动垃圾回收，但高频接口也可主动调用
@@ -122089,7 +122089,7 @@ Defined in: [lib/s3.ts:341](https://github.com/maiyunnet/kebab/blob/master/lib/s
 
 > **getObject**(`key`, `bucket?`): `Promise`\<`false` \| `Readable` & `SdkStreamMixin` \| `Blob` & `SdkStreamMixin` \| `ReadableStream`\<`any`\> & `SdkStreamMixin` \| `undefined`\>
 
-Defined in: [lib/s3.ts:235](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L235)
+Defined in: [lib/s3.ts:323](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L323)
 
 获取对象流，可通过流获取 buffer 或 text
 
@@ -122117,7 +122117,7 @@ bucket 名
 
 > **getObjectBuffer**(`key`, `bucket?`): `Promise`\<`false` \| `Buffer`\<`ArrayBufferLike`\>\>
 
-Defined in: [lib/s3.ts:256](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L256)
+Defined in: [lib/s3.ts:344](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L344)
 
 获取对象 Buffer
 
@@ -122147,7 +122147,7 @@ bucket 名
 
 > **headObject**(`key`, `bucket?`): `Promise`\<`false` \| `HeadObjectCommandOutput`\>
 
-Defined in: [lib/s3.ts:321](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L321)
+Defined in: [lib/s3.ts:409](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L409)
 
 检测对象是否存在
 
@@ -122175,9 +122175,9 @@ bucket 名
 
 > **putObject**(`key`, `content`, `length?`, `bucket?`): `Promise`\<`false` \| `CompleteMultipartUploadCommandOutput`\>
 
-Defined in: [lib/s3.ts:139](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L139)
+Defined in: [lib/s3.ts:140](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L140)
 
-上传对象（可传流且也可无需设置 length） --
+上传对象，流内容可省略 length
 
 #### Parameters
 
@@ -122195,9 +122195,9 @@ Defined in: [lib/s3.ts:139](https://github.com/maiyunnet/kebab/blob/master/lib/s
 
 ##### length?
 
-`number` \| \{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `type?`: `string`; \}
+`number` \| \{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `signal?`: `AbortSignal`; `type?`: `string`; \}
 
-设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+contentLength 或上传选项
 
 `number`
 
@@ -122205,22 +122205,36 @@ Defined in: [lib/s3.ts:139](https://github.com/maiyunnet/kebab/blob/master/lib/s
 
 ###### Type Literal
 
-\{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `type?`: `string`; \}
+\{ `bucket?`: `string`; `disposition?`: `string`; `length?`: `number`; `signal?`: `AbortSignal`; `type?`: `string`; \}
 
-设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+contentLength 或上传选项
 
 ###### bucket?
 
 `string`
 
+bucket 名，省略时使用预定义 bucket
+
 ###### disposition?
 
 `string`
 
+content-disposition，如 attachment
+
 ###### length?
 
 `number`
 
+contentLength，流内容可省略
+
+###### signal?
+
+`AbortSignal`
+
+取消上传请求并销毁输入流，等待已知的未完成分片清理后返回 false
+清理使用独立的 30 秒超时信号，失败时记录错误；不传则沿用原上传流程
+不删除同名对象，上传完成与取消同时发生时，由调用方清理独立任务文件
+
 ###### type?
 
 `string`
@@ -122237,13 +122251,15 @@ bucket 名
 
 `Promise`\<`false` \| `CompleteMultipartUploadCommandOutput`\>
 
+上传结果，失败或取消返回 false；传入 signal 时，返回前会尝试清理已知的未完成分片
+
 ***
 
 ### putObjects()
 
 > **putObjects**(`items`, `options?`): `Promise`\<[`IPutObjectsItemResult`](../interfaces/IPutObjectsItemResult.md)[]\>
 
-Defined in: [lib/s3.ts:184](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L184)
+Defined in: [lib/s3.ts:272](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L272)
 
 批量上传对象，并发控制，单次失败不影响其他项
 
@@ -122347,7 +122363,7 @@ lib/s3/functions/get.md
 
 > **get**(`ctr`, `opt`): [`S3`](../classes/S3.md)
 
-Defined in: [lib/s3.ts:351](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L351)
+Defined in: [lib/s3.ts:439](https://github.com/maiyunnet/kebab/blob/master/lib/s3.ts#L439)
 
 创建一个对象存储对象
 

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.20.0";
+export declare const VER = "9.20.1";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.20.0';
+export const VER = '9.20.1';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/s3.d.ts

@@ -3,8 +3,8 @@
  * Date: 2024-2-18 18:32:45
  * Last: 2024-2-18 18:32:47, 2024-3-16 16:42:27, 2024-5-31 21:36:26, 2024-7-8 00:28:42, 2024-7-19 11:32:43, 2025-6-10 21:45:34, 2025-12-5 23:42:59
  */
-import * as s3 from '@aws-sdk/client-s3';
 import * as stream from 'stream';
+import * as s3 from '@aws-sdk/client-s3';
 import * as sCtr from '#kebab/sys/ctr.js';
 /**
  * --- s3 文档：https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/ ---
@@ -76,18 +76,28 @@ export declare class S3 {
      */
     setBucket(bucket: string): void;
     /**
-     * --- 上传对象（可传流且也可无需设置 length） --
+     * --- 上传对象，流内容可省略 length ---
      * @param key 对象路径
      * @param content 内容
-     * @param length 设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+     * @param length contentLength 或上传选项
      * @param bucket bucket 名
+     * @returns 上传结果，失败或取消返回 false；传入 signal 时，返回前会尝试清理已知的未完成分片
      */
     putObject(key: string, content: string | Buffer | stream.Readable, length?: number | {
+        /** --- contentLength，流内容可省略 --- */
         'length'?: number;
         /** --- content-type，如 application/javascript --- */
         'type'?: string;
+        /** --- content-disposition，如 attachment --- */
         'disposition'?: string;
+        /** --- bucket 名，省略时使用预定义 bucket --- */
         'bucket'?: string;
+        /**
+         * --- 取消上传请求并销毁输入流，等待已知的未完成分片清理后返回 false ---
+         * --- 清理使用独立的 30 秒超时信号，失败时记录错误；不传则沿用原上传流程 ---
+         * --- 不删除同名对象，上传完成与取消同时发生时，由调用方清理独立任务文件 ---
+         */
+        'signal'?: AbortSignal;
     }, bucket?: string): Promise<s3.CompleteMultipartUploadCommandOutput | false>;
     /**
      * --- 批量上传对象，并发控制，单次失败不影响其他项 ---

package/lib/s3.js

@@ -4,6 +4,7 @@
  * Last: 2024-2-18 18:32:47, 2024-3-16 16:42:27, 2024-5-31 21:36:26, 2024-7-8 00:28:42, 2024-7-19 11:32:43, 2025-6-10 21:45:34, 2025-12-5 23:42:59
  */
 // --- 库和定义 ---
+import * as stream from 'stream';
 import * as s3 from '@aws-sdk/client-s3';
 import * as ls from '@aws-sdk/lib-storage';
 import * as lCore from '#kebab/lib/core.js';
@@ -67,28 +68,79 @@ export class S3 {
         this._bucket = bucket;
     }
     /**
-     * --- 上传对象（可传流且也可无需设置 length） --
+     * --- 上传对象，流内容可省略 length ---
      * @param key 对象路径
      * @param content 内容
-     * @param length 设置 contentLength，如果是流模式则需要设置此项，也可以设置为对象参数
+     * @param length contentLength 或上传选项
      * @param bucket bucket 名
+     * @returns 上传结果，失败或取消返回 false；传入 signal 时，返回前会尝试清理已知的未完成分片
      */
     async putObject(key, content, length, bucket) {
+        /** --- 对象内容类型 --- */
+        let type;
+        /** --- 对象下载方式 --- */
+        let disposition;
+        /** --- 调用方传入的取消信号，仅作用于本次上传 --- */
+        let signal;
+        if (typeof length !== 'number') {
+            type = length?.type;
+            disposition = length?.disposition;
+            bucket = length?.bucket;
+            signal = length?.signal;
+            length = length?.length;
+        }
+        bucket ??= this._bucket;
+        /** --- 输入流，传入 signal 时在取消或失败后停止读取；字符串与 Buffer 无需释放 --- */
+        const source = content instanceof stream.Readable ? content : undefined;
+        /**
+         * --- 停止流读取，避免取消时仍阻塞在等待下一块数据的阶段 ---
+         * @returns 无返回值
+         */
+        const onAbort = () => {
+            source?.destroy();
+        };
+        /** --- 尚未确认合并或清理完成的分片上传 ID，用于失败后的兜底清理 --- */
+        let uploadId;
+        /** --- 是否取得有效上传结果，失败时需要释放输入流 --- */
+        let success = false;
+        /** --- 分片清理请求的超时毫秒数，避免清理阶段无限等待 --- */
+        const cleanupTimeout = 30000;
         try {
-            /** --- content type --- */
-            let type = undefined;
-            /** --- content disposition --- */
-            let disposition = undefined;
-            if (typeof length !== 'number') {
-                type = length?.type;
-                disposition = length?.disposition;
-                bucket = length?.bucket;
-                length = length?.length;
+            if (signal?.aborted) {
+                return false;
             }
+            signal?.addEventListener('abort', onAbort, { 'once': true });
+            /** --- 本次上传的客户端入口，共享连接配置但不修改共享客户端的 send --- */
+            const client = signal ? Object.create(this._link) : this._link;
+            if (signal) {
+                /**
+                 * --- 为上传命令传递取消信号，并跟踪未完成的分片上传 ---
+                 * --- Upload.abort() 会提前结束 done()，且不会取消正在发送的请求 ---
+                 * --- 逐条命令传入信号，让 done() 等待分片任务和清理结束 ---
+                 * @param command SDK 上传或分片清理命令；Upload 仅使用 send 的 Promise 调用形式
+                 * @returns SDK 命令结果
+                 */
+                client.send = (async (command) => {
+                    /** --- 清理请求必须使用独立信号，避免随上传请求一起取消 --- */
+                    const isCleanup = command instanceof s3.AbortMultipartUploadCommand;
+                    /** --- 命令成功后再更新分片 ID，失败时保留 ID 供 finally 重试清理 --- */
+                    const res = await this._link.send(command, {
+                        'abortSignal': isCleanup ? AbortSignal.timeout(cleanupTimeout) : signal,
+                    });
+                    if (command instanceof s3.CreateMultipartUploadCommand) {
+                        uploadId = res.UploadId;
+                    }
+                    else if (isCleanup || (command instanceof s3.CompleteMultipartUploadCommand)) {
+                        uploadId = undefined;
+                    }
+                    return res;
+                });
+            }
+            /** --- SDK 上传任务，继续由 SDK 管理分片和并发 --- */
             const upload = new ls.Upload({
-                'client': this._link,
+                'client': client,
                 'params': {
-                    'Bucket': bucket ?? this._bucket,
+                    'Bucket': bucket,
                     'Key': key,
                     'Body': content,
                     'ContentLength': length,
@@ -96,13 +148,40 @@ export class S3 {
                     'ContentDisposition': disposition,
                 }
             });
+            /** --- 上传结果；取消与上传完成同时发生时仍向调用方返回 false --- */
             const res = await upload.done();
-            return (res.Location && res.Bucket && res.Key) ? res : false;
+            if (signal?.aborted || !res.Location || !res.Bucket || !res.Key) {
+                return false;
+            }
+            success = true;
+            return res;
         }
         catch (e) {
-            lCore.log(this._ctr, '[LIB][S3][putObject] ' + lText.stringifyJson(e.message ?? '').slice(1, -1).replace(/"/g, '""'), '-error');
+            if (!signal?.aborted) {
+                lCore.log(this._ctr, `[LIB][S3][putObject] ${lText.stringifyError(e)}`, '-error');
+            }
             return false;
         }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+            if (signal && !success) {
+                source?.destroy();
+            }
+            // --- SDK 的合并失败分支不会清理分片；SDK 清理失败时也保留 ID，在这里兜底 ---
+            // --- 只清理本次未完成的分片，不删除可能已存在的同名对象 ---
+            if (uploadId) {
+                try {
+                    await this._link.send(new s3.AbortMultipartUploadCommand({
+                        'Bucket': bucket,
+                        'Key': key,
+                        'UploadId': uploadId,
+                    }), { 'abortSignal': AbortSignal.timeout(cleanupTimeout) });
+                }
+                catch (e) {
+                    lCore.log(this._ctr, `[LIB][S3][putObject][cleanup] ${lText.stringifyError(e)}`, '-error');
+                }
+            }
+        }
     }
     /**
      * --- 批量上传对象，并发控制，单次失败不影响其他项 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.20.0",
+  "version": "9.20.1",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [