@h-ai/storage 0.1.0-alpha.67 → 0.1.0-alpha.68

package/dist/chunk-P65WYXJG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/storage-schemas.ts"],"names":[],"mappings":";;;AAgBO,IAAM,qBAAA,GAAwB;AAa9B,IAAM,uBAAA,GAA0B;AA6BhC,SAAS,kBAAA,CAAmB,GAAA,EAAa,UAAA,GAAa,KAAA,EAAoC;AAC/F,EAAA,IAAI,cAAc,GAAA,KAAQ,EAAA;AACxB,IAAA,OAAO,MAAA;AACT,EAAA,IAAI,GAAA,CAAI,MAAK,KAAM,EAAA;AACjB,IAAA,OAAO,OAAA;AACT,EAAA,IAAI,IAAI,WAAA,EAAY,CAAE,MAAA,CAAO,GAAG,EAAE,UAAA,GAAa,qBAAA;AAC7C,IAAA,OAAO,SAAA;AACT,EAAA,IAAI,GAAA,CAAI,WAAW,GAAG,CAAA,IAAK,IAAI,QAAA,CAAS,IAAI,CAAA,IAAK,CAAC,GAAG,GAAG,EAAE,IAAA,CAAK,CAAA,IAAA,KAAQ,IAAA,CAAK,UAAA,CAAW,CAAC,CAAA,GAAI,MAAM,IAAA,CAAK,UAAA,CAAW,CAAC,CAAA,KAAM,GAAG,CAAA;AAC1H,IAAA,OAAO,YAAA;AACT,EAAA,IAAI,GAAA,CAAI,MAAM,GAAG,CAAA,CAAE,KAAK,CAAA,OAAA,KAAW,OAAA,KAAY,GAAA,IAAO,OAAA,KAAY,IAAI,CAAA;AACpE,IAAA,OAAO,UAAA;AACT,EAAA,OAAO,MAAA;AACT;AAGA,SAAS,UAAU,UAAA,EAAqB;AACtC,EAAA,OAAO,EAAE,MAAA,EAAO,CAAE,WAAA,CAAY,CAAC,KAAK,OAAA,KAAY;AAC9C,IAAA,MAAM,KAAA,GAAQ,kBAAA,CAAmB,GAAA,EAAK,UAAU,CAAA;AAChD,IAAA,IAAI,KAAA;AACF,MAAA,OAAA,CAAQ,QAAA,CAAS,EAAE,IAAA,EAAM,QAAA,EAAU,QAAQ,EAAE,eAAA,EAAiB,KAAA,EAAM,EAAG,CAAA;AAAA,EAC3E,CAAC,CAAA;AACH;AAYO,IAAM,gBAAA,GAAmB,UAAU,KAAK;AAYxC,IAAM,mBAAA,GAAsB,UAAU,IAAI;AAY1C,IAAM,uBAAA,GAA0B,EAAE,KAAA,CAAM,gBAAgB,EAAE,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,uBAAuB;AAY5F,IAAM,6BAAA,GAAgC,CAAA,CAAE,MAAA,EAAO,CAAE,GAAA,GAAM,GAAA,CAAI,CAAC,CAAA,CAAE,GAAA,CAAI,MAAM","file":"chunk-P65WYXJG.js","sourcesContent":["/**\n * @h-ai/storage — 跨端输入约束；仅依赖 Zod，不加载 Provider、配置或 Node 模块。\n * @module storage-schemas\n */\nimport { z } from 'zod'\n\n/**\n * 对象键的 UTF-8 字节上限；不是 JavaScript 字符串长度。\n * @example\n * ```ts\n * import { STORAGE_KEY_MAX_BYTES } from '@h-ai/storage/schemas'\n *\n * const fits = new TextEncoder().encode('uploads/报告.pdf').length <= STORAGE_KEY_MAX_BYTES\n * void fits\n * ```\n */\nexport const STORAGE_KEY_MAX_BYTES = 1024\n\n/**\n * 单次公开 HTTP 删除请求的原始键数量上限；Node deleteMany 仍按 Provider 上限分批。\n * @example\n * ```ts\n * import { STORAGE_DELETE_MAX_KEYS } from '@h-ai/storage/schemas'\n *\n * const keys = ['a.txt', 'b.txt']\n * const page = keys.slice(0, STORAGE_DELETE_MAX_KEYS)\n * void page\n * ```\n */\nexport const STORAGE_DELETE_MAX_KEYS = 1000\n\n/**\n * 键校验失败类别；调用层据此生成本地化消息，不解析错误文本。\n * @example\n * ```ts\n * import type { StorageKeyIssue } from '@h-ai/storage'\n *\n * const value: StorageKeyIssue = 'tooLong'\n * void value\n * ```\n */\nexport type StorageKeyIssue = 'empty' | 'tooLong' | 'characters' | 'segments'\n\n/**\n * 检查跨端键边界，不归一化输入，不替代文件系统防逃逸或资源授权。\n *\n * @param key - 调用方视角的对象键，不含 Provider 配置前缀。\n * @param allowEmpty - 是否允许空字符串（用于列表前缀）；纯空白仍无效。\n * @returns 首个失败类别；合法时为 undefined。\n * @example\n * ```ts\n * import { getStorageKeyIssue } from '@h-ai/storage/schemas'\n *\n * const unsafe = getStorageKeyIssue('../private.txt') // segments\n * const emptyPrefix = getStorageKeyIssue('', true) // undefined\n * void [unsafe, emptyPrefix]\n * ```\n */\nexport function getStorageKeyIssue(key: string, allowEmpty = false): StorageKeyIssue | undefined {\n  if (allowEmpty && key === '')\n    return undefined\n  if (key.trim() === '')\n    return 'empty'\n  if (new TextEncoder().encode(key).byteLength > STORAGE_KEY_MAX_BYTES)\n    return 'tooLong'\n  if (key.startsWith('/') || key.includes('\\\\') || [...key].some(char => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127))\n    return 'characters'\n  if (key.split('/').some(segment => segment === '.' || segment === '..'))\n    return 'segments'\n  return undefined\n}\n\n/** 通过稳定 params 保留失败类别；默认 Zod 消息交由请求层按 locale 映射。 */\nfunction keySchema(allowEmpty: boolean) {\n  return z.string().superRefine((key, context) => {\n    const issue = getStorageKeyIssue(key, allowEmpty)\n    if (issue)\n      context.addIssue({ code: 'custom', params: { storageKeyIssue: issue } })\n  })\n}\n\n/**\n * 文件键 Schema：非空、UTF-8 最多 1024 字节，无绝对路径、反斜线、控制符或点路径段。\n * @example\n * ```ts\n * import { StorageKeySchema } from '@h-ai/storage'\n *\n * const value = StorageKeySchema.parse('users/u1/report.pdf')\n * void value\n * ```\n */\nexport const StorageKeySchema = keySchema(false)\n\n/**\n * 列表前缀 Schema；允许空字符串与部分文件名，不把前缀当物理目录。\n * @example\n * ```ts\n * import { StoragePrefixSchema } from '@h-ai/storage'\n *\n * const value = StoragePrefixSchema.parse('users/u1/rep')\n * void value\n * ```\n */\nexport const StoragePrefixSchema = keySchema(true)\n\n/**\n * HTTP 批量删除键 Schema；按输入数量计数，重复键不能绕过上限。\n * @example\n * ```ts\n * import { StorageDeleteKeysSchema } from '@h-ai/storage'\n *\n * const value = StorageDeleteKeysSchema.parse(['users/u1/a.txt', 'users/u1/b.txt'])\n * void value\n * ```\n */\nexport const StorageDeleteKeysSchema = z.array(StorageKeySchema).min(1).max(STORAGE_DELETE_MAX_KEYS)\n\n/**\n * 预签名有效期，单位秒；整数 1–604800，不在此处填充 Node/HTTP 各自默认值。\n * @example\n * ```ts\n * import { StoragePresignExpiresInSchema } from '@h-ai/storage'\n *\n * const value = StoragePresignExpiresInSchema.parse(900)\n * void value\n * ```\n */\nexport const StoragePresignExpiresInSchema = z.number().int().min(1).max(604800)\n"]}

package/dist/client/index.d.ts

@@ -8,6 +8,13 @@
  * 上传进度回调数据
  *
  * 由 `uploadWithPresignedUrl` 在上传过程中通过 `onProgress` 回调返回。
+ * @example
+ * ```ts
+ * import type { UploadProgress } from '@h-ai/storage'
+ *
+ * const value: UploadProgress = { loaded: 50, total: 100, percent: 50 }
+ * void value
+ * ```
  */
 interface UploadProgress {
     /** 已上传字节数 */
@@ -21,19 +28,33 @@ interface UploadProgress {
  * 前端上传选项
  *
  * 控制 `uploadWithPresignedUrl` 的行为，包括内容类型、进度监听和取消。
+ * @example
+ * ```ts
+ * import type { ClientUploadOptions } from '@h-ai/storage'
+ *
+ * const value: ClientUploadOptions = { contentType: 'text/plain', onProgress: progress => { document.title = `${progress.percent}%` } }
+ * void value
+ * ```
  */
 interface ClientUploadOptions {
     /** 内容类型（设置后会加到请求 Content-Type 头） */
     contentType?: string;
     /** 进度回调（设置后会使用 XMLHttpRequest；仅 lengthComputable=true 时回调） */
     onProgress?: (progress: UploadProgress) => void;
-    /** AbortController 用于取消上传（abort 后返回 {success: false}） */
+    /** 取消上传；预取消不发送请求，进行中取消返回失败，完成后移除本次监听。取消不能撤销远端已写入对象。 */
     abortController?: AbortController;
 }
 /**
  * 前端下载选项
  *
  * 控制 `downloadWithPresignedUrl` / `downloadAndSave` 的行为。
+ * @example
+ * ```ts
+ * import type { ClientDownloadOptions } from '@h-ai/storage'
+ *
+ * const value: ClientDownloadOptions = { filename: 'report.pdf', abortController: new AbortController() }
+ * void value
+ * ```
  */
 interface ClientDownloadOptions {
     /** 保存的文件名（仅 downloadAndSave 使用，默认为 'download'） */
@@ -44,31 +65,19 @@ interface ClientDownloadOptions {
 /**
  * 使用签名 URL 上传文件
  *
- * @param url - 后端生成的上传签名 URL
+ * @param url - 已成功获取的 S3 HTTP(S) 上传签名 URL；本地存储须使用应用的鉴权文件接口。
  * @param data - 要上传的数据（File、Blob、ArrayBuffer 或字符串）
  * @param options - 上传选项
- * @returns 上传结果
- *
+ * @returns 上传结果；预取消不发送，进行中取消/网络失败/初始化异常结算为失败，终态移除本次监听。
+ * 取消不代表远端对象已回滚；上传完成后的撤销由应用另行授权删除。
  * @example
  * ```ts
- * // 获取签名 URL（通常从后端 API 获取）
- * const response = await fetch('/api/storage/presign', {
- *     method: 'POST',
- *     body: JSON.stringify({ key: 'uploads/image.png', contentType: 'image/png' })
- * })
- * const { uploadUrl } = await response.json()
- *
- * // 使用签名 URL 上传
- * const file = document.getElementById('fileInput').files[0]
- * const result = await uploadWithPresignedUrl(uploadUrl, file, {
- *     contentType: 'image/png',
- *     onProgress: (p) => {
- *         // 在此更新进度条：p.percent
- *     }
- * })
- *
- * if (result.success) {
- *     // 上传成功
+ * import { uploadWithPresignedUrl } from '@h-ai/storage/client'
+ *
+ * // url 由应用鉴权接口返回，且 S3 签名包含相同 Content-Type。
+ * async function upload(url: string, file: File) {
+ *   const result = await uploadWithPresignedUrl(url, file, { contentType: file.type })
+ *   if (!result.success) throw new Error(result.error)
  * }
  * ```
  */
@@ -82,18 +91,15 @@ declare function uploadWithPresignedUrl(url: string, data: File | Blob | ArrayBu
  * @param url - 后端生成的下载签名 URL
  * @param options - 下载选项
  * @returns 下载结果（成功时 data 为 Blob）
- *
  * @example
  * ```ts
- * // 下载为 Blob
- * const result = await downloadWithPresignedUrl(downloadUrl)
- * if (result.success) {
- *     const blob = result.data
- *     // 处理 blob...
- * }
+ * import { downloadWithPresignedUrl } from '@h-ai/storage/client'
  *
- * // 下载并保存为文件（浏览器环境）
- * await downloadAndSave(downloadUrl, { filename: 'document.pdf' })
+ * async function download(url: string) {
+ *   const result = await downloadWithPresignedUrl(url)
+ *   if (!result.success || !result.data) throw new Error(result.error ?? 'Empty download')
+ *   return result.data
+ * }
  * ```
  */
 declare function downloadWithPresignedUrl(url: string, options?: ClientDownloadOptions): Promise<{
@@ -106,12 +112,15 @@ declare function downloadWithPresignedUrl(url: string, options?: ClientDownloadO
  *
  * @param url - 下载 URL
  * @param options - 下载选项
- *
+ * @returns 声明返回类型对应的操作结果。
  * @example
  * ```ts
- * await downloadAndSave(presignedUrl, {
- *     filename: 'report.pdf'
- * })
+ * import { downloadAndSave } from '@h-ai/storage/client'
+ *
+ * async function save(url: string) {
+ *   const result = await downloadAndSave(url, { filename: 'report.pdf' })
+ *   if (!result.success) throw new Error(result.error)
+ * }
  * ```
  */
 declare function downloadAndSave(url: string, options?: ClientDownloadOptions): Promise<{
@@ -122,16 +131,16 @@ declare function downloadAndSave(url: string, options?: ClientDownloadOptions):
  * 从 File 对象获取文件扩展名
  *
  * 取文件名中最后一个 '.' 之后的部分，转为小写。
- * 若文件名无点号或以点号开头且无其他点号，返回空字符串。
+ * 没有点号或以点号结尾时返回空字符串；仅前导点号的文件名按其后文本返回扩展名。
  *
  * @param file - 浏览器 File 对象
  * @returns 扩展名（不含点），如 'png'、'tar.gz' 返回 'gz'
- *
  * @example
  * ```ts
- * getFileExtension(new File([], 'photo.PNG'))  // 'png'
- * getFileExtension(new File([], '.gitignore')) // 'gitignore'
- * getFileExtension(new File([], 'noext'))      // ''
+ * import { getFileExtension } from '@h-ai/storage/client'
+ *
+ * const extension = getFileExtension(new File(['hello'], 'report.txt'))
+ * void extension
  * ```
  */
 declare function getFileExtension(file: File): string;
@@ -143,11 +152,12 @@ declare function getFileExtension(file: File): string;
  *
  * @param extension - 文件扩展名（不含点，大小写不敏感）
  * @returns MIME 类型字符串
- *
  * @example
  * ```ts
- * getMimeType('png')  // 'image/png'
- * getMimeType('xyz')  // 'application/octet-stream'
+ * import { getMimeType } from '@h-ai/storage/client'
+ *
+ * const mime = getMimeType('pdf')
+ * void mime
  * ```
  */
 declare function getMimeType(extension: string): string;
@@ -155,16 +165,15 @@ declare function getMimeType(extension: string): string;
  * 格式化文件大小为人类可读字符串
  *
  * 使用 1024 进制，输出单位为 B/KB/MB/GB/TB。
- * 大于 1 B 时保留 2 位小数。
+ * 非零值使用对应单位并保留 2 位小数。
  *
  * @param bytes - 字节数（非负整数）
  * @returns 格式化后的字符串，如 '0 B'、'1.50 KB'、'2.30 MB'
- *
  * @example
  * ```ts
- * formatFileSize(0)         // '0 B'
- * formatFileSize(1536)      // '1.50 KB'
- * formatFileSize(1048576)   // '1.00 MB'
+ * import { formatFileSize } from '@h-ai/storage/client'
+ *
+ * void formatFileSize(1536)
  * ```
  */
 declare function formatFileSize(bytes: number): string;

package/dist/client/index.js

@@ -1,3 +1,3 @@
-export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from '../chunk-25GYTRA7.js';
+export { downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from '../chunk-I4BSES63.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/node.d.ts

@@ -1,6 +1,7 @@
 export { ClientDownloadOptions, ClientUploadOptions, UploadProgress, downloadAndSave, downloadWithPresignedUrl, formatFileSize, getFileExtension, getMimeType, uploadWithPresignedUrl } from './client/index.js';
 import { StorageFunctions } from './browser.js';
-export { ChecksumAlgorithm, ChecksumOperations, ChecksumOptions, CopyOptions, DirOperations, DownloadOptions, FileMetadata, FileOperations, HaiStorageError, ListOptions, ListResult, LocalConfig, LocalConfigSchema, PresignOperations, PresignOptions, PresignOptionsSchema, PresignUploadOptions, PresignUploadOptionsSchema, S3Config, S3ConfigSchema, StorageConfig, StorageConfigInput, StorageConfigSchema, StorageData, StorageOperationLogConfig, StorageOperationLogConfigSchema, StorageProvider, StorageType, StorageTypeSchema, UploadOptions } from './browser.js';
+export { ChecksumAlgorithm, ChecksumOperations, ChecksumOptions, CopyOptions, DirOperations, DownloadOptions, FileMetadata, FileOperations, HaiStorageError, ListOptions, ListResult, LocalConfig, LocalConfigSchema, PresignOperations, PresignOptions, PresignOptionsSchema, PresignUploadOptions, PresignUploadOptionsSchema, S3Config, S3ConfigSchema, StorageConfig, StorageConfigInput, StorageConfigSchema, StorageData, StorageDeleteFailure, StorageDeleteResult, StorageDeleteSummary, StorageOperationLogConfig, StorageOperationLogConfigSchema, StorageType, StorageTypeSchema, UploadOptions } from './browser.js';
+export { STORAGE_DELETE_MAX_KEYS, STORAGE_KEY_MAX_BYTES, StorageDeleteKeysSchema, StorageKeyIssue, StorageKeySchema, StoragePrefixSchema, StoragePresignExpiresInSchema, getStorageKeyIssue } from './schemas.js';
 import 'zod';
 import '@h-ai/core';
 import 'node:buffer';
@@ -15,21 +16,24 @@ import 'node:buffer';
 /**
  * 存储服务单例
  *
- * 使用前必须先调用 `storage.init()` 初始化，传入 S3 或本地存储配置。
+ * 文件、目录及签名操作前须调用 `storage.init()`；checksum 为无状态工具，无需初始化。
  * 初始化后通过 `storage.file`、`storage.dir`、`storage.presign` 访问各操作接口。
- *
  * @example
  * ```ts
  * import { storage } from '@h-ai/storage'
  *
- * // 初始化
- * await storage.init({ type: 'local', root: '/data/uploads' })
- *
- * // 上传文件
- * await storage.file.put('hello.txt', 'Hello World')
- *
- * // 关闭连接
- * await storage.close()
+ * const initialized = await storage.init({ type: 'local', root: './data/uploads' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const uploaded = await storage.file.put('reports/a.txt', 'hello', { ifNoneMatch: '*' })
+ *   if (!uploaded.success) throw new Error(uploaded.error.message)
+ *   const downloaded = await storage.file.get('reports/a.txt')
+ *   if (!downloaded.success) throw new Error(downloaded.error.message)
+ *   void downloaded.data
+ * } finally {
+ *   const closed = await storage.close()
+ *   if (!closed.success) throw new Error(closed.error.message)
+ * }
  * ```
  */
 declare const storage: StorageFunctions;