@lhy-meta-server/meta-oss 0.0.0-stage → 0.0.1

package/dist/core/execution.d.ts

@@ -0,0 +1,130 @@
+import { StorageError } from './errors';
+/**
+ * 重试退避配置。
+ */
+export interface RetryOptions {
+    /**
+     * 首次失败后的最大重试次数，默认为 2。
+     */
+    retries?: number;
+    /**
+     * 第一次重试前的等待毫秒数，默认为 100。
+     */
+    baseDelay?: number;
+    /**
+     * 单次等待的上限毫秒数，默认为 2000。
+     */
+    maxDelay?: number;
+    /**
+     * 是否在指数退避上叠加随机抖动，默认为 `true`。
+     */
+    jitter?: boolean;
+    /**
+     * 自定义可重试判定；默认仅重试 `retryable` 为 `true` 的错误。
+     */
+    shouldRetry?(error: unknown, attempt: number): boolean;
+}
+/**
+ * 计算指数退避等待时间。
+ *
+ * @param attempt 已失败的尝试次数，从 1 开始。
+ * @param baseDelay 基础等待毫秒数。
+ * @param maxDelay 等待上限毫秒数。
+ * @param jitter 是否叠加 0 到 50% 的随机抖动。
+ * @param random 随机数来源，便于测试注入。
+ * @returns 等待毫秒数。
+ */
+export declare function backoff(attempt: number, baseDelay: number, maxDelay: number, jitter: boolean, random?: () => number): number;
+/**
+ * 默认可重试判定：只有被标记为 `retryable` 的存储错误才会重试。
+ *
+ * @param error 失败原因。
+ * @returns 是否允许重试。
+ */
+export declare function isRetryable(error: unknown): boolean;
+/**
+ * 单次尝试的受控执行范围，合并调用方取消与超时。
+ */
+export interface AttemptScope {
+    /**
+     * 传给适配器的合并信号。
+     */
+    readonly signal: AbortSignal;
+    /**
+     * 释放定时器与监听器。
+     */
+    dispose(): void;
+}
+/**
+ * 创建一次尝试的取消范围。
+ *
+ * @param timeout 超时毫秒数；`0` 表示不限制。
+ * @param parent 调用方取消信号。
+ * @returns 合并后的执行范围。
+ */
+export declare function createScope(timeout: number, parent?: AbortSignal): AttemptScope;
+/**
+ * 在信号中止时立即拒绝，即使底层操作未响应信号。
+ *
+ * @param task 实际执行的异步任务。
+ * @param signal 合并信号。
+ * @returns 任务结果。
+ */
+export declare function race<T>(task: Promise<T>, signal: AbortSignal): Promise<T>;
+/**
+ * 将信号的中止原因转换为存储错误；超时原因保持 `TIMEOUT`，其余视为 `ABORTED`。
+ *
+ * @param signal 已中止的信号。
+ * @returns 对应的存储错误。
+ */
+export declare function abortReason(signal: AbortSignal): StorageError;
+/**
+ * 可被取消的等待。
+ *
+ * @param milliseconds 等待毫秒数。
+ * @param signal 调用方取消信号。
+ * @throws {@link StorageError} 等待期间被取消时抛出 `ABORTED`。
+ */
+export declare function sleep(milliseconds: number, signal?: AbortSignal): Promise<void>;
+/**
+ * 公平的异步信号量，用于限制对后端的并发请求数。
+ */
+export declare class Semaphore {
+    private readonly limit;
+    private active;
+    private readonly queue;
+    /**
+     * 创建信号量。
+     *
+     * @param limit 最大并发数。
+     */
+    constructor(limit: number);
+    /**
+     * 在获得许可后执行任务，并确保任务结束后释放许可。
+     *
+     * @param task 要执行的任务。
+     * @returns 任务结果。
+     */
+    run<T>(task: () => Promise<T>): Promise<T>;
+}
+/**
+ * 以受控并发映射数组，结果顺序与输入一致；任一任务失败时整体拒绝。
+ *
+ * @param items 输入数组。
+ * @param concurrency 最大并发数。
+ * @param mapper 映射函数。
+ * @returns 与输入顺序一致的结果数组。
+ */
+export declare function mapLimit<T, R>(items: readonly T[], concurrency: number, mapper: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * 等待任务结束（成功或失败均可），最长等待 `grace` 毫秒；任务的结果与错误都会被吞掉。
+ *
+ * 用于在超时或取消后让底层操作有机会响应信号并释放资源，同时避免不响应取消的任务
+ * 无限期阻塞调用方。
+ *
+ * @param task 正在执行的任务。
+ * @param grace 最长等待毫秒数；`0` 表示不等待。
+ * @returns 任务是否在宽限期内结束。
+ */
+export declare function settle(task: Promise<unknown>, grace: number): Promise<boolean>;
+//# sourceMappingURL=execution.d.ts.map

package/dist/core/execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution.d.ts","sourceRoot":"","sources":["../../src/core/execution.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,YAAY,EAAE,MAAM,UAAU,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;OAEG;IACH,WAAW,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;CACvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACrB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,EACf,MAAM,GAAE,MAAM,MAAoB,GACjC,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B;;OAEG;IACH,OAAO,IAAI,IAAI,CAAA;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAsB/E;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAgBzE;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAI7D;AAED;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAa/E;AAED;;GAEG;AACH,qBAAa,SAAS;IASD,OAAO,CAAC,QAAQ,CAAC,KAAK;IARzC,OAAO,CAAC,MAAM,CAAI;IAClB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAE9C;;;;OAIG;IACH,YAAoC,KAAK,EAAE,MAAM,EAAI;IAErD;;;;;OAKG;IACU,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAUtD;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,EAAE,CAAC,CAYd;AAED;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAepF"}

package/dist/core/keys.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 根据原始文件名生成对象键的函数。
+ */
+export type KeyGenerator = (filename: string) => string;
+/**
+ * 默认对象键生成器的选项。
+ */
+export interface CreateObjectKeyOptions {
+    /**
+     * 生成键的目录前缀，例如 `avatars`。
+     */
+    directory?: string;
+    /**
+     * 用于日期目录的时间，默认为当前时间。
+     */
+    date?: Date;
+}
+/**
+ * 生成形如 `yyyy/mm/dd/<uuid>.<ext>` 的不可预测对象键。
+ *
+ * 原始文件名只用于提取扩展名，扩展名仅保留字母与数字，避免用户输入污染路径。
+ *
+ * @param filename 原始文件名，例如 `头像.PNG`。
+ * @param options 目录前缀与日期。
+ * @returns 新的对象键，例如 `avatars/2026/10/13/<uuid>.png`。
+ *
+ * @example
+ * ```ts
+ * createObjectKey('report.pdf', { directory: 'docs' })
+ * // docs/2026/10/13/3b1f...e2.pdf
+ * ```
+ */
+export declare function createObjectKey(filename: string, options?: CreateObjectKeyOptions): string;
+//# sourceMappingURL=keys.d.ts.map

package/dist/core/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/core/keys.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;AAEvD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,CAAA;CACZ;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B,GAAG,MAAM,CAW9F"}

package/dist/core/mime.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 未知扩展名时采用的默认 MIME 类型。
+ */
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+/**
+ * 读取对象键的小写扩展名，不含点号。
+ *
+ * @param key 对象键。
+ * @returns 扩展名；无扩展名时返回空字符串。
+ */
+export declare function extensionOf(key: string): string;
+/**
+ * 按对象键扩展名推断 MIME 类型。
+ *
+ * @param key 对象键。
+ * @param overrides 自定义扩展名映射，优先于内置映射，键为不含点号的小写扩展名。
+ * @returns 推断出的 MIME 类型；无法识别时返回 `application/octet-stream`。
+ */
+export declare function lookupContentType(key: string, overrides?: Readonly<Record<string, string>>): string;
+/**
+ * 去除 MIME 类型的参数部分并转换为小写，用于比较。
+ *
+ * @param contentType 完整 MIME 类型，例如 `text/plain; charset=utf-8`。
+ * @returns 基础 MIME 类型，例如 `text/plain`。
+ */
+export declare function essenceOf(contentType: string): string;
+/**
+ * 判断 MIME 类型是否命中允许列表，支持 `image/*` 形式的通配。
+ *
+ * @param contentType 待判断的 MIME 类型。
+ * @param patterns 允许列表。
+ * @returns 是否命中。
+ */
+export declare function matchContentType(contentType: string, patterns: readonly string[]): boolean;
+//# sourceMappingURL=mime.d.ts.map

package/dist/core/mime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mime.d.ts","sourceRoot":"","sources":["../../src/core/mime.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,oBAAoB,6BAA6B,CAAA;AA4C9D;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI/C;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,GAAG,MAAM,CAGvG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAM1F"}

package/dist/core/observability.d.ts

@@ -0,0 +1,224 @@
+import type { StorageError, StorageErrorCode } from './errors';
+/**
+ * 可观测的对象存储操作名称。
+ */
+export type StorageOperation = 'put' | 'get' | 'head' | 'exists' | 'delete' | 'deleteMany' | 'list' | 'copy' | 'move' | 'signUrl' | 'createMultipart' | 'uploadPart' | 'completeMultipart' | 'abortMultipart' | 'close';
+/**
+ * 操作结果分类。
+ */
+export type StorageOutcome = 'success' | 'error';
+/**
+ * 单次操作完成后产生的结构化事件。
+ *
+ * 事件不会包含凭据、签名或签名 URL；`key` 为业务可见键，不含服务级前缀。
+ */
+export interface StorageEvent {
+    /**
+     * 操作名称。
+     */
+    readonly operation: StorageOperation;
+    /**
+     * 操作结果。
+     */
+    readonly outcome: StorageOutcome;
+    /**
+     * 适配器名称。
+     */
+    readonly driver: string;
+    /**
+     * 关联的对象键；批量或列举操作时省略。
+     */
+    readonly key?: string;
+    /**
+     * 包含重试在内的总耗时毫秒数。
+     */
+    readonly duration: number;
+    /**
+     * 实际尝试次数，首次执行计为 1。
+     */
+    readonly attempts: number;
+    /**
+     * 写入或读取的已知字节数。
+     */
+    readonly bytes?: number;
+    /**
+     * 失败时的稳定错误码。
+     */
+    readonly errorCode?: StorageErrorCode;
+    /**
+     * 失败时的脱敏错误摘要，可直接写入日志。
+     */
+    readonly error?: StorageErrorSummary;
+    /**
+     * 事件产生时的 Unix 毫秒时间戳。
+     */
+    readonly timestamp: number;
+}
+/**
+ * 写入可观测事件的脱敏错误摘要。
+ *
+ * 只保留分类与排障所需的少量字段，不包含原始错误对象：SDK 错误通常携带请求参数、
+ * 请求头或签名信息，直接记录存在泄露凭据的风险。需要完整错误时请在业务调用处捕获。
+ */
+export interface StorageErrorSummary {
+    /**
+     * 稳定错误码。
+     */
+    readonly code: StorageErrorCode;
+    /**
+     * 存储错误消息；底层原始消息不会出现在此处。
+     */
+    readonly message: string;
+    /**
+     * 是否可重试。
+     */
+    readonly retryable: boolean;
+    /**
+     * 底层错误的 HTTP 状态码。
+     */
+    readonly status?: number;
+    /**
+     * 底层错误的字符串错误码，例如 `NoSuchKey`、`ECONNRESET`。
+     */
+    readonly causeCode?: string;
+    /**
+     * 底层错误携带的请求 ID，便于向云厂商排障。
+     */
+    readonly requestId?: string;
+}
+/**
+ * 每次重试前产生的事件。
+ */
+export interface StorageRetryEvent {
+    /**
+     * 操作名称。
+     */
+    readonly operation: StorageOperation;
+    /**
+     * 适配器名称。
+     */
+    readonly driver: string;
+    /**
+     * 关联的对象键。
+     */
+    readonly key?: string;
+    /**
+     * 即将开始的尝试序号。
+     */
+    readonly attempt: number;
+    /**
+     * 本次重试前的等待毫秒数。
+     */
+    readonly delay: number;
+    /**
+     * 触发重试的脱敏错误摘要。
+     */
+    readonly error: StorageErrorSummary;
+}
+/**
+ * 结构化事件观察器。
+ *
+ * 回调应快速返回并把耗时上报放入自身队列；回调抛出的异常会被服务隔离，
+ * 不会影响业务请求。
+ */
+export interface StorageObserver {
+    /**
+     * 每次操作完成（成功或失败）后调用。
+     */
+    onOperation?(event: StorageEvent): void;
+    /**
+     * 每次重试等待前调用。
+     */
+    onRetry?(event: StorageRetryEvent): void;
+}
+/**
+ * 进程内累计指标快照。
+ */
+export interface StorageMetricsSnapshot {
+    /**
+     * 已完成的操作数量。
+     */
+    readonly operations: number;
+    /**
+     * 失败的操作数量。
+     */
+    readonly errors: number;
+    /**
+     * 重试次数。
+     */
+    readonly retries: number;
+    /**
+     * 当前执行中的操作数量。
+     */
+    readonly inFlight: number;
+    /**
+     * 成功写入的已知字节数。
+     */
+    readonly bytesWritten: number;
+    /**
+     * 所有操作累计耗时毫秒数。
+     */
+    readonly totalDuration: number;
+    /**
+     * 按操作名称累计的调用数量。
+     */
+    readonly byOperation: Readonly<Partial<Record<StorageOperation, number>>>;
+    /**
+     * 按错误码累计的失败数量。
+     */
+    readonly byErrorCode: Readonly<Partial<Record<StorageErrorCode, number>>>;
+}
+/**
+ * 低开销的进程内对象存储指标收集器。
+ *
+ * 可在多个 `ObjectStorage` 实例间共享，用于汇总同一进程的指标。
+ */
+export declare class StorageMetrics {
+    private operations;
+    private errors;
+    private retries;
+    private inFlight;
+    private bytesWritten;
+    private totalDuration;
+    private byOperation;
+    private byErrorCode;
+    /**
+     * 创建空的指标收集器。
+     */
+    constructor();
+    /**
+     * 标记一个操作开始执行。
+     */
+    start(): void;
+    /**
+     * 记录一个已完成操作。
+     *
+     * @param event 操作完成事件。
+     */
+    record(event: StorageEvent): void;
+    /**
+     * 记录一次重试。
+     */
+    retry(): void;
+    /**
+     * 返回当前累计指标的冻结快照。
+     *
+     * @returns 与后续更新隔离的只读快照。
+     */
+    snapshot(): StorageMetricsSnapshot;
+    /**
+     * 将累计指标清零；执行中的操作数保持不变。
+     */
+    reset(): void;
+}
+/**
+ * 生成存储错误的脱敏摘要。
+ *
+ * 由服务层生成的错误消息只包含固定文本、操作名与配置值；`BACKEND` 错误的消息可能来自
+ * 底层 SDK，因此统一替换为固定文本。
+ *
+ * @param error 存储错误。
+ * @returns 可安全记录的错误摘要。
+ */
+export declare function summarizeError(error: StorageError): StorageErrorSummary;
+//# sourceMappingURL=observability.d.ts.map

package/dist/core/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/core/observability.ts"],"names":[],"mappings":"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"}

package/dist/core/payload.d.ts

@@ -0,0 +1,81 @@
+import { Readable } from 'node:stream';
+import type { ObjectBody } from './types';
+/**
+ * 统一后的上传内容，由服务层创建并交给适配器消费。
+ *
+ * 适配器无需关心原始输入是字符串、`Blob` 还是 Node.js 流，只需按需调用
+ * {@link StoragePayload.stream} 或 {@link StoragePayload.bytes}。
+ */
+export interface StoragePayload {
+    /**
+     * 已知的内容字节数；流式输入在读取前无法确定时为 `undefined`。
+     */
+    readonly size: number | undefined;
+    /**
+     * 内容能否被重复读取；不可重复读取的内容不会被自动重试。
+     */
+    readonly replayable: boolean;
+    /**
+     * 打开内容的 Web 标准可读流。
+     *
+     * 可重复读取的内容每次调用都返回新的流；不可重复读取的内容只能调用一次。
+     *
+     * @throws {@link StorageError} 不可重复读取的内容被二次打开时抛出 `INVALID_OPTION`。
+     */
+    stream(): ReadableStream<Uint8Array>;
+    /**
+     * 将全部内容读取为连续字节数组。
+     */
+    bytes(): Promise<Uint8Array>;
+}
+/**
+ * 将任意分块统一转换为字节数组。
+ *
+ * @param chunk 流或异步迭代器产生的分块。
+ * @returns 对应的字节视图，不复制底层内存。
+ * @throws {@link StorageError} 分块类型不受支持时抛出 `INVALID_OPTION`。
+ */
+export declare function toBytes(chunk: unknown): Uint8Array;
+/**
+ * 将可读流完整读取为连续字节数组。
+ *
+ * @param stream Web 标准可读流。
+ * @returns 合并后的字节数组。
+ */
+export declare function readAll(stream: ReadableStream<Uint8Array>): Promise<Uint8Array>;
+/**
+ * 以异步迭代方式逐块读取 Web 可读流，并在提前退出时释放读取锁。
+ *
+ * @param stream Web 标准可读流。
+ * @returns 逐块产生字节的异步迭代器。
+ */
+export declare function iterate(stream: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array>;
+/**
+ * 将业务输入统一为 {@link StoragePayload}。
+ *
+ * 字符串、二进制与 `Blob` 是可重复读取的；Web 流、Node.js 流与异步迭代器
+ * 只能被消费一次。Node.js 流按异步迭代器读取，因此对象模式下产生的字符串
+ * 或 Buffer 分块同样会被正确转换。
+ *
+ * @param body 业务提供的对象内容。
+ * @returns 统一后的上传内容。
+ * @throws {@link StorageError} 输入类型不受支持时抛出 `INVALID_OPTION`。
+ */
+export declare function createPayload(body: ObjectBody): StoragePayload;
+/**
+ * 为上传内容附加字节数上限，超限时以 `UPLOAD_REJECTED` 终止读取。
+ *
+ * @param payload 原始上传内容。
+ * @param maxSize 允许的最大字节数。
+ * @returns 带上限检查的上传内容。
+ * @throws {@link StorageError} 已知大小超过上限时立即抛出 `UPLOAD_REJECTED`。
+ */
+export declare function limitPayload(payload: StoragePayload, maxSize: number): StoragePayload;
+/**
+ * 将 Web 可读流转换为 Node.js 可读流，供只接受 Node.js 流的 SDK 使用。
+ *
+ * @param stream Web 标准可读流。
+ * @returns Node.js 可读流。
+ */
+export declare function toNodeReadable(stream: ReadableStream<Uint8Array>): Readable;
+//# sourceMappingURL=payload.d.ts.map

package/dist/core/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/core/payload.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAGtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAIzC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;IAC5B;;;;;;OAMG;IACH,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC,CAAA;IACpC;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC,CAAA;CAC7B;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAMlD;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAcrF;AAED;;;;;GAKG;AACH,wBAAuB,OAAO,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,cAAc,CAAC,UAAU,CAAC,CAW7F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,cAAc,CAmB9D;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAOrF;AA6DD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,QAAQ,CAE3E"}

package/dist/core/policy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 上传限制策略，同时作用于普通上传、分片上传与 `PUT` 签名 URL。
+ */
+export interface UploadPolicy {
+    /**
+     * 单个对象允许的最大字节数。`PUT` 签名 URL 无法在服务端强制该限制。
+     */
+    maxSize?: number;
+    /**
+     * 允许的 MIME 类型，支持 `image/*` 通配；省略时不限制。
+     */
+    allowedContentTypes?: readonly string[];
+    /**
+     * 允许的扩展名（不含点号，大小写不敏感）；省略时不限制。
+     */
+    allowedExtensions?: readonly string[];
+    /**
+     * 禁止的扩展名（不含点号，大小写不敏感），优先于允许列表。
+     */
+    deniedExtensions?: readonly string[];
+}
+/**
+ * 按策略校验对象键扩展名与 MIME 类型。
+ *
+ * @param policy 上传策略。
+ * @param key 业务对象键。
+ * @param contentType 最终采用的 MIME 类型。
+ * @throws {@link StorageError} 不满足策略时抛出 `UPLOAD_REJECTED`。
+ */
+export declare function checkUploadPolicy(policy: UploadPolicy, key: string, contentType: string): void;
+//# sourceMappingURL=policy.d.ts.map

package/dist/core/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/core/policy.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACvC;;OAEG;IACH,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC;;OAEG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAY9F"}