@miaixz/sdk 0.5.0

package/dist/files/files.d.ts

@@ -0,0 +1,138 @@
+import type { MiaixzApiClient } from "../api/index.js";
+import { type MiaixzTranslator } from "../i18n/index.js";
+import type { MiaixzFileDescriptor, MiaixzUploadResult } from "../types/index.js";
+/**
+ * Configures a multipart file upload.
+ *
+ * @public
+ */
+export interface MiaixzUploadOptions {
+    /**
+     * Optional multipart field name used for uploaded files.
+     */
+    fieldName?: string;
+    /**
+     * Optional scalar metadata appended to the multipart body.
+     */
+    metadata?: Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Optional signal used to cancel the upload.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional request-specific HTTP headers.
+     */
+    headers?: HeadersInit;
+}
+/**
+ * Configures a file download.
+ *
+ * @public
+ */
+export interface MiaixzDownloadOptions {
+    /**
+     * Optional signal used to cancel the download.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional request-specific HTTP headers.
+     */
+    headers?: HeadersInit;
+    /**
+     * Optional filename that overrides response metadata.
+     */
+    filename?: string;
+}
+/**
+ * Describes a file downloaded into memory.
+ *
+ * @public
+ */
+export interface MiaixzDownloadedFile {
+    /**
+     * Downloaded binary content.
+     */
+    blob: Blob;
+    /**
+     * Optional decoded or caller-provided filename.
+     */
+    filename?: string;
+    /**
+     * Optional media type returned by the server.
+     */
+    contentType?: string;
+}
+/**
+ * Configures a high-level Miaixz file client.
+ *
+ * @public
+ */
+export interface MiaixzFileClientOptions {
+    /**
+     * Optional translator used for file-operation errors.
+     */
+    translate?: MiaixzTranslator;
+}
+/**
+ * Extracts and decodes a filename from an HTTP Content-Disposition header.
+ *
+ * @param headers - Response headers to inspect.
+ * @returns Decoded filename when one is present.
+ * @public
+ */
+export declare function getMiaixzDownloadFilename(headers: Headers): string | undefined;
+/**
+ * High-level file upload and download operations built on a Miaixz API client.
+ *
+ * @public
+ */
+export declare class MiaixzFileClient {
+    #private;
+    /**
+     * Configured API client used for file requests.
+     */
+    readonly api: MiaixzApiClient;
+    /**
+     * Creates a high-level file client.
+     *
+     * @param api - Configured API client.
+     * @param options - File-specific adapters.
+     */
+    constructor(api: MiaixzApiClient, options?: MiaixzFileClientOptions);
+    /**
+     * Uploads one or more files as multipart form data.
+     *
+     * @param path - API path that accepts the upload.
+     * @param files - Single blob or immutable blob collection to upload.
+     * @param options - Optional multipart metadata and request controls.
+     * @returns The backend's unwrapped upload result.
+     */
+    upload<TFile extends MiaixzFileDescriptor = MiaixzFileDescriptor>(path: string, files: Blob | readonly Blob[], options?: MiaixzUploadOptions): Promise<MiaixzUploadResult<TFile>>;
+    /**
+     * Downloads a binary response and derives its filename and content type.
+     *
+     * @param path - API path of the file to download.
+     * @param options - Optional filename and request controls.
+     * @returns Downloaded binary content and response metadata.
+     */
+    download(path: string, options?: MiaixzDownloadOptions): Promise<MiaixzDownloadedFile>;
+}
+/**
+ * Creates a high-level file client around an existing API client.
+ *
+ * @param api - Configured API client used for file requests.
+ * @param options - Optional file-client adapters.
+ * @returns Configured high-level file client.
+ * @public
+ */
+export declare function createMiaixzFileClient(api: MiaixzApiClient, options?: MiaixzFileClientOptions): MiaixzFileClient;
+/**
+ * Triggers a browser download for an in-memory blob; no-ops during SSR.
+ *
+ * @param blob - Binary content to download.
+ * @param filename - Filename presented to the browser.
+ * @param targetDocument - Optional document used to create the download link.
+ * @public
+ */
+export declare function saveMiaixzBlob(blob: Blob, filename: string, targetDocument?: Document | undefined): void;
+//# sourceMappingURL=files.d.ts.map

package/dist/files/files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/files/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC5E,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAE/D;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,IAAI,EAAE,IAAI,CAAC;IAEX;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAYD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAY9E;AAED;;;;GAIG;AACH,qBAAa,gBAAgB;;IAG3B;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAE9B;;;;;OAKG;IACH,YAAY,GAAG,EAAE,eAAe,EAAE,OAAO,GAAE,uBAA4B,EAGtE;IAED;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,SAAS,oBAAoB,GAAG,oBAAoB,EACpE,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,IAAI,GAAG,SAAS,IAAI,EAAE,EAC7B,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAgBpC;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAqB/F;CACF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,eAAe,EACpB,OAAO,CAAC,EAAE,uBAAuB,GAChC,gBAAgB,CAElB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,MAAM,EAChB,cAAc,GAAE,QAAQ,GAAG,SAAkE,GAC5F,IAAI,CAWN"}

package/dist/files/files.js

@@ -0,0 +1,144 @@
+import { MiaixzSdkError, isMiaixzSdkError } from "../api/errors.js";
+import { miaixzDefaultI18n } from "../i18n/index.js";
+/**
+ * Normalizes a single upload blob to the multi-file representation.
+ *
+ * @param files - Single blob or immutable blob collection.
+ * @returns Immutable blob collection.
+ */
+function normalizeFiles(files) {
+    return files instanceof Blob ? [files] : files;
+}
+/**
+ * Extracts and decodes a filename from an HTTP Content-Disposition header.
+ *
+ * @param headers - Response headers to inspect.
+ * @returns Decoded filename when one is present.
+ * @public
+ */
+export function getMiaixzDownloadFilename(headers) {
+    const disposition = headers.get("content-disposition");
+    if (!disposition)
+        return undefined;
+    const encoded = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
+    if (encoded) {
+        try {
+            return decodeURIComponent(encoded.replace(/^"|"$/g, ""));
+        }
+        catch {
+            return encoded;
+        }
+    }
+    return disposition.match(/filename="?([^";]+)"?/i)?.[1]?.trim();
+}
+/**
+ * High-level file upload and download operations built on a Miaixz API client.
+ *
+ * @public
+ */
+export class MiaixzFileClient {
+    #translate;
+    /**
+     * Configured API client used for file requests.
+     */
+    api;
+    /**
+     * Creates a high-level file client.
+     *
+     * @param api - Configured API client.
+     * @param options - File-specific adapters.
+     */
+    constructor(api, options = {}) {
+        this.api = api;
+        this.#translate = options.translate ?? miaixzDefaultI18n.t;
+    }
+    /**
+     * Uploads one or more files as multipart form data.
+     *
+     * @param path - API path that accepts the upload.
+     * @param files - Single blob or immutable blob collection to upload.
+     * @param options - Optional multipart metadata and request controls.
+     * @returns The backend's unwrapped upload result.
+     */
+    async upload(path, files, options = {}) {
+        const formData = new FormData();
+        const fieldName = options.fieldName ?? "files";
+        for (const file of normalizeFiles(files)) {
+            const filename = typeof File !== "undefined" && file instanceof File ? file.name : "file";
+            formData.append(fieldName, file, filename);
+        }
+        for (const [key, value] of Object.entries(options.metadata ?? {})) {
+            formData.append(key, String(value));
+        }
+        const response = await this.api.post(path, formData, {
+            responseType: "json",
+            ...(options.signal === undefined ? {} : { signal: options.signal }),
+            ...(options.headers === undefined ? {} : { headers: options.headers }),
+        });
+        return response.data;
+    }
+    /**
+     * Downloads a binary response and derives its filename and content type.
+     *
+     * @param path - API path of the file to download.
+     * @param options - Optional filename and request controls.
+     * @returns Downloaded binary content and response metadata.
+     */
+    async download(path, options = {}) {
+        try {
+            const response = await this.api.get(path, {
+                responseType: "blob",
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+                ...(options.headers === undefined ? {} : { headers: options.headers }),
+            });
+            const filename = options.filename ?? getMiaixzDownloadFilename(response.headers);
+            const contentType = response.headers.get("content-type") ?? undefined;
+            return {
+                blob: response.data,
+                ...(filename === undefined ? {} : { filename }),
+                ...(contentType === undefined ? {} : { contentType }),
+            };
+        }
+        catch (cause) {
+            if (isMiaixzSdkError(cause))
+                throw cause;
+            throw new MiaixzSdkError(this.#translate("sdk.error.file.download"), {
+                code: "FILE_DOWNLOAD_FAILED",
+                cause,
+            });
+        }
+    }
+}
+/**
+ * Creates a high-level file client around an existing API client.
+ *
+ * @param api - Configured API client used for file requests.
+ * @param options - Optional file-client adapters.
+ * @returns Configured high-level file client.
+ * @public
+ */
+export function createMiaixzFileClient(api, options) {
+    return new MiaixzFileClient(api, options);
+}
+/**
+ * Triggers a browser download for an in-memory blob; no-ops during SSR.
+ *
+ * @param blob - Binary content to download.
+ * @param filename - Filename presented to the browser.
+ * @param targetDocument - Optional document used to create the download link.
+ * @public
+ */
+export function saveMiaixzBlob(blob, filename, targetDocument = typeof document === "undefined" ? undefined : document) {
+    if (!targetDocument || typeof URL === "undefined")
+        return;
+    const url = URL.createObjectURL(blob);
+    const anchor = targetDocument.createElement("a");
+    anchor.href = url;
+    anchor.download = filename;
+    anchor.hidden = true;
+    targetDocument.body.append(anchor);
+    anchor.click();
+    anchor.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+//# sourceMappingURL=files.js.map

package/dist/files/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/files/files.ts"],"names":[],"mappings":"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","sourcesContent":["import type { MiaixzApiClient } from \"../api/index.js\";\nimport { MiaixzSdkError, isMiaixzSdkError } from \"../api/errors.js\";\nimport { miaixzDefaultI18n, type MiaixzTranslator } from \"../i18n/index.js\";\nimport type { MiaixzFileDescriptor, MiaixzUploadResult } from \"../types/index.js\";\n\n/**\n * Configures a multipart file upload.\n *\n * @public\n */\nexport interface MiaixzUploadOptions {\n  /**\n   * Optional multipart field name used for uploaded files.\n   */\n  fieldName?: string;\n\n  /**\n   * Optional scalar metadata appended to the multipart body.\n   */\n  metadata?: Readonly<Record<string, string | number | boolean>>;\n\n  /**\n   * Optional signal used to cancel the upload.\n   */\n  signal?: AbortSignal;\n\n  /**\n   * Optional request-specific HTTP headers.\n   */\n  headers?: HeadersInit;\n}\n\n/**\n * Configures a file download.\n *\n * @public\n */\nexport interface MiaixzDownloadOptions {\n  /**\n   * Optional signal used to cancel the download.\n   */\n  signal?: AbortSignal;\n\n  /**\n   * Optional request-specific HTTP headers.\n   */\n  headers?: HeadersInit;\n\n  /**\n   * Optional filename that overrides response metadata.\n   */\n  filename?: string;\n}\n\n/**\n * Describes a file downloaded into memory.\n *\n * @public\n */\nexport interface MiaixzDownloadedFile {\n  /**\n   * Downloaded binary content.\n   */\n  blob: Blob;\n\n  /**\n   * Optional decoded or caller-provided filename.\n   */\n  filename?: string;\n\n  /**\n   * Optional media type returned by the server.\n   */\n  contentType?: string;\n}\n\n/**\n * Configures a high-level Miaixz file client.\n *\n * @public\n */\nexport interface MiaixzFileClientOptions {\n  /**\n   * Optional translator used for file-operation errors.\n   */\n  translate?: MiaixzTranslator;\n}\n\n/**\n * Normalizes a single upload blob to the multi-file representation.\n *\n * @param files - Single blob or immutable blob collection.\n * @returns Immutable blob collection.\n */\nfunction normalizeFiles(files: Blob | readonly Blob[]): readonly Blob[] {\n  return files instanceof Blob ? [files] : files;\n}\n\n/**\n * Extracts and decodes a filename from an HTTP Content-Disposition header.\n *\n * @param headers - Response headers to inspect.\n * @returns Decoded filename when one is present.\n * @public\n */\nexport function getMiaixzDownloadFilename(headers: Headers): string | undefined {\n  const disposition = headers.get(\"content-disposition\");\n  if (!disposition) return undefined;\n  const encoded = disposition.match(/filename\\*=UTF-8''([^;]+)/i)?.[1];\n  if (encoded) {\n    try {\n      return decodeURIComponent(encoded.replace(/^\"|\"$/g, \"\"));\n    } catch {\n      return encoded;\n    }\n  }\n  return disposition.match(/filename=\"?([^\";]+)\"?/i)?.[1]?.trim();\n}\n\n/**\n * High-level file upload and download operations built on a Miaixz API client.\n *\n * @public\n */\nexport class MiaixzFileClient {\n  readonly #translate: MiaixzTranslator;\n\n  /**\n   * Configured API client used for file requests.\n   */\n  readonly api: MiaixzApiClient;\n\n  /**\n   * Creates a high-level file client.\n   *\n   * @param api - Configured API client.\n   * @param options - File-specific adapters.\n   */\n  constructor(api: MiaixzApiClient, options: MiaixzFileClientOptions = {}) {\n    this.api = api;\n    this.#translate = options.translate ?? miaixzDefaultI18n.t;\n  }\n\n  /**\n   * Uploads one or more files as multipart form data.\n   *\n   * @param path - API path that accepts the upload.\n   * @param files - Single blob or immutable blob collection to upload.\n   * @param options - Optional multipart metadata and request controls.\n   * @returns The backend's unwrapped upload result.\n   */\n  async upload<TFile extends MiaixzFileDescriptor = MiaixzFileDescriptor>(\n    path: string,\n    files: Blob | readonly Blob[],\n    options: MiaixzUploadOptions = {},\n  ): Promise<MiaixzUploadResult<TFile>> {\n    const formData = new FormData();\n    const fieldName = options.fieldName ?? \"files\";\n    for (const file of normalizeFiles(files)) {\n      const filename = typeof File !== \"undefined\" && file instanceof File ? file.name : \"file\";\n      formData.append(fieldName, file, filename);\n    }\n    for (const [key, value] of Object.entries(options.metadata ?? {})) {\n      formData.append(key, String(value));\n    }\n    const response = await this.api.post<MiaixzUploadResult<TFile>, FormData>(path, formData, {\n      responseType: \"json\",\n      ...(options.signal === undefined ? {} : { signal: options.signal }),\n      ...(options.headers === undefined ? {} : { headers: options.headers }),\n    });\n    return response.data;\n  }\n\n  /**\n   * Downloads a binary response and derives its filename and content type.\n   *\n   * @param path - API path of the file to download.\n   * @param options - Optional filename and request controls.\n   * @returns Downloaded binary content and response metadata.\n   */\n  async download(path: string, options: MiaixzDownloadOptions = {}): Promise<MiaixzDownloadedFile> {\n    try {\n      const response = await this.api.get<Blob>(path, {\n        responseType: \"blob\",\n        ...(options.signal === undefined ? {} : { signal: options.signal }),\n        ...(options.headers === undefined ? {} : { headers: options.headers }),\n      });\n      const filename = options.filename ?? getMiaixzDownloadFilename(response.headers);\n      const contentType = response.headers.get(\"content-type\") ?? undefined;\n      return {\n        blob: response.data,\n        ...(filename === undefined ? {} : { filename }),\n        ...(contentType === undefined ? {} : { contentType }),\n      };\n    } catch (cause) {\n      if (isMiaixzSdkError(cause)) throw cause;\n      throw new MiaixzSdkError(this.#translate(\"sdk.error.file.download\"), {\n        code: \"FILE_DOWNLOAD_FAILED\",\n        cause,\n      });\n    }\n  }\n}\n\n/**\n * Creates a high-level file client around an existing API client.\n *\n * @param api - Configured API client used for file requests.\n * @param options - Optional file-client adapters.\n * @returns Configured high-level file client.\n * @public\n */\nexport function createMiaixzFileClient(\n  api: MiaixzApiClient,\n  options?: MiaixzFileClientOptions,\n): MiaixzFileClient {\n  return new MiaixzFileClient(api, options);\n}\n\n/**\n * Triggers a browser download for an in-memory blob; no-ops during SSR.\n *\n * @param blob - Binary content to download.\n * @param filename - Filename presented to the browser.\n * @param targetDocument - Optional document used to create the download link.\n * @public\n */\nexport function saveMiaixzBlob(\n  blob: Blob,\n  filename: string,\n  targetDocument: Document | undefined = typeof document === \"undefined\" ? undefined : document,\n): void {\n  if (!targetDocument || typeof URL === \"undefined\") return;\n  const url = URL.createObjectURL(blob);\n  const anchor = targetDocument.createElement(\"a\");\n  anchor.href = url;\n  anchor.download = filename;\n  anchor.hidden = true;\n  targetDocument.body.append(anchor);\n  anchor.click();\n  anchor.remove();\n  setTimeout(() => URL.revokeObjectURL(url), 0);\n}\n"]}

package/dist/files/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./files.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/files/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC"}

package/dist/files/index.js

@@ -0,0 +1,2 @@
+export * from "./files.js";
+//# sourceMappingURL=index.js.map

package/dist/files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC","sourcesContent":["export * from \"./files.js\";\n"]}

package/dist/formatters/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Configures locale-aware Miaixz formatters.
+ *
+ * @public
+ */
+export interface MiaixzFormatOptions {
+    /**
+     * Optional BCP 47 locale used by the platform formatter.
+     */
+    locale?: string;
+}
+/**
+ * Formats a date with the platform Intl implementation.
+ *
+ * @param value - Date-compatible value to format.
+ * @param options - Locale and date-time formatting options.
+ * @returns An empty string for invalid dates.
+ * @public
+ */
+export declare function formatMiaixzDate(value: Date | string | number, options?: MiaixzFormatOptions & Intl.DateTimeFormatOptions): string;
+/**
+ * Formats a numeric value using locale-aware Intl options.
+ *
+ * @param value - Numeric value to format.
+ * @param options - Locale and number formatting options.
+ * @returns Locale-aware numeric text.
+ * @public
+ */
+export declare function formatMiaixzNumber(value: number, options?: MiaixzFormatOptions & Intl.NumberFormatOptions): string;
+/**
+ * Formats a byte count with a compact binary unit and localized number.
+ *
+ * @param bytes - Byte count to format.
+ * @param options - Locale and fraction-digit options.
+ * @returns Localized byte count or an empty string for non-finite input.
+ * @public
+ */
+export declare function formatMiaixzBytes(bytes: number, options?: MiaixzFormatOptions & {
+    /**
+     * Optional maximum number of fractional digits to display.
+     */
+    maximumFractionDigits?: number;
+}): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/formatters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatters/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAC7B,OAAO,GAAE,mBAAmB,GAAG,IAAI,CAAC,qBAA0B,GAC7D,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAmB,GAAG,IAAI,CAAC,mBAAwB,GAC3D,MAAM,CAGR;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,mBAAmB,GAAG;IAC7B;;OAEG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAC3B,GACL,MAAM,CAaR"}

package/dist/formatters/index.js

@@ -0,0 +1,50 @@
+/**
+ * Formats a date with the platform Intl implementation.
+ *
+ * @param value - Date-compatible value to format.
+ * @param options - Locale and date-time formatting options.
+ * @returns An empty string for invalid dates.
+ * @public
+ */
+export function formatMiaixzDate(value, options = {}) {
+    const { locale, ...formatOptions } = options;
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime()))
+        return "";
+    return new Intl.DateTimeFormat(locale, formatOptions).format(date);
+}
+/**
+ * Formats a numeric value using locale-aware Intl options.
+ *
+ * @param value - Numeric value to format.
+ * @param options - Locale and number formatting options.
+ * @returns Locale-aware numeric text.
+ * @public
+ */
+export function formatMiaixzNumber(value, options = {}) {
+    const { locale, ...formatOptions } = options;
+    return new Intl.NumberFormat(locale, formatOptions).format(value);
+}
+/**
+ * Formats a byte count with a compact binary unit and localized number.
+ *
+ * @param bytes - Byte count to format.
+ * @param options - Locale and fraction-digit options.
+ * @returns Localized byte count or an empty string for non-finite input.
+ * @public
+ */
+export function formatMiaixzBytes(bytes, options = {}) {
+    if (!Number.isFinite(bytes))
+        return "";
+    const units = ["B", "KB", "MB", "GB", "TB", "PB"];
+    const absolute = Math.abs(bytes);
+    const index = absolute === 0
+        ? 0
+        : Math.min(Math.floor(Math.log(absolute) / Math.log(1024)), units.length - 1);
+    const value = bytes / 1024 ** index;
+    return `${formatMiaixzNumber(value, {
+        ...(options.locale === undefined ? {} : { locale: options.locale }),
+        maximumFractionDigits: options.maximumFractionDigits ?? 1,
+    })} ${units[index]}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/formatters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/formatters/index.ts"],"names":[],"mappings":"AAYA;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAA6B,EAC7B,OAAO,GAAqD,EAAE;IAE9D,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAC7C,MAAM,IAAI,GAAG,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7D,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5C,OAAO,IAAI,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAa,EACb,OAAO,GAAmD,EAAE;IAE5D,MAAM,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,CAAC;IAC7C,OAAO,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAa,EACb,OAAO,GAKH,EAAE;IAEN,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC;IAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjC,MAAM,KAAK,GACT,QAAQ,KAAK,CAAC;QACZ,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClF,MAAM,KAAK,GAAG,KAAK,GAAG,IAAI,IAAI,KAAK,CAAC;IACpC,OAAO,GAAG,kBAAkB,CAAC,KAAK,EAAE;QAClC,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;QACnE,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,IAAI,CAAC;KAC1D,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;AACvB,CAAC","sourcesContent":["/**\n * Configures locale-aware Miaixz formatters.\n *\n * @public\n */\nexport interface MiaixzFormatOptions {\n  /**\n   * Optional BCP 47 locale used by the platform formatter.\n   */\n  locale?: string;\n}\n\n/**\n * Formats a date with the platform Intl implementation.\n *\n * @param value - Date-compatible value to format.\n * @param options - Locale and date-time formatting options.\n * @returns An empty string for invalid dates.\n * @public\n */\nexport function formatMiaixzDate(\n  value: Date | string | number,\n  options: MiaixzFormatOptions & Intl.DateTimeFormatOptions = {},\n): string {\n  const { locale, ...formatOptions } = options;\n  const date = value instanceof Date ? value : new Date(value);\n  if (Number.isNaN(date.getTime())) return \"\";\n  return new Intl.DateTimeFormat(locale, formatOptions).format(date);\n}\n\n/**\n * Formats a numeric value using locale-aware Intl options.\n *\n * @param value - Numeric value to format.\n * @param options - Locale and number formatting options.\n * @returns Locale-aware numeric text.\n * @public\n */\nexport function formatMiaixzNumber(\n  value: number,\n  options: MiaixzFormatOptions & Intl.NumberFormatOptions = {},\n): string {\n  const { locale, ...formatOptions } = options;\n  return new Intl.NumberFormat(locale, formatOptions).format(value);\n}\n\n/**\n * Formats a byte count with a compact binary unit and localized number.\n *\n * @param bytes - Byte count to format.\n * @param options - Locale and fraction-digit options.\n * @returns Localized byte count or an empty string for non-finite input.\n * @public\n */\nexport function formatMiaixzBytes(\n  bytes: number,\n  options: MiaixzFormatOptions & {\n    /**\n     * Optional maximum number of fractional digits to display.\n     */\n    maximumFractionDigits?: number;\n  } = {},\n): string {\n  if (!Number.isFinite(bytes)) return \"\";\n  const units = [\"B\", \"KB\", \"MB\", \"GB\", \"TB\", \"PB\"] as const;\n  const absolute = Math.abs(bytes);\n  const index =\n    absolute === 0\n      ? 0\n      : Math.min(Math.floor(Math.log(absolute) / Math.log(1024)), units.length - 1);\n  const value = bytes / 1024 ** index;\n  return `${formatMiaixzNumber(value, {\n    ...(options.locale === undefined ? {} : { locale: options.locale }),\n    maximumFractionDigits: options.maximumFractionDigits ?? 1,\n  })} ${units[index]}`;\n}\n"]}

package/dist/i18n/default-translator.d.ts

@@ -0,0 +1,17 @@
+import type { MiaixzTranslator } from "./i18n.js";
+/**
+ * Resolves a default SDK message without creating a runtime import cycle.
+ *
+ * @param key - Translation key to resolve.
+ * @param params - Optional interpolation values.
+ * @param fallback - Optional explicit fallback text.
+ * @returns Message resolved by the currently registered default runtime.
+ */
+export declare const translateMiaixzDefaultMessage: MiaixzTranslator;
+/**
+ * Registers the translator owned by the fully initialized default runtime.
+ *
+ * @param translator - Default SDK runtime translator.
+ */
+export declare function setMiaixzDefaultTranslator(translator: MiaixzTranslator): void;
+//# sourceMappingURL=default-translator.d.ts.map

package/dist/i18n/default-translator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-translator.d.ts","sourceRoot":"","sources":["../../src/i18n/default-translator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAIlD;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,gBACH,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,gBAAgB,GAAG,IAAI,CAE7E"}

package/dist/i18n/default-translator.js

@@ -0,0 +1,19 @@
+let activeTranslator = (key, _params, fallback) => fallback ?? key;
+/**
+ * Resolves a default SDK message without creating a runtime import cycle.
+ *
+ * @param key - Translation key to resolve.
+ * @param params - Optional interpolation values.
+ * @param fallback - Optional explicit fallback text.
+ * @returns Message resolved by the currently registered default runtime.
+ */
+export const translateMiaixzDefaultMessage = (key, params, fallback) => activeTranslator(key, params, fallback);
+/**
+ * Registers the translator owned by the fully initialized default runtime.
+ *
+ * @param translator - Default SDK runtime translator.
+ */
+export function setMiaixzDefaultTranslator(translator) {
+    activeTranslator = translator;
+}
+//# sourceMappingURL=default-translator.js.map

package/dist/i18n/default-translator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-translator.js","sourceRoot":"","sources":["../../src/i18n/default-translator.ts"],"names":[],"mappings":"AAEA,IAAI,gBAAgB,GAAqB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,QAAQ,IAAI,GAAG,CAAC;AAErF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CACvF,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;AAE1C;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CAAC,UAA4B;IACrE,gBAAgB,GAAG,UAAU,CAAC;AAChC,CAAC","sourcesContent":["import type { MiaixzTranslator } from \"./i18n.js\";\n\nlet activeTranslator: MiaixzTranslator = (key, _params, fallback) => fallback ?? key;\n\n/**\n * Resolves a default SDK message without creating a runtime import cycle.\n *\n * @param key - Translation key to resolve.\n * @param params - Optional interpolation values.\n * @param fallback - Optional explicit fallback text.\n * @returns Message resolved by the currently registered default runtime.\n */\nexport const translateMiaixzDefaultMessage: MiaixzTranslator = (key, params, fallback) =>\n  activeTranslator(key, params, fallback);\n\n/**\n * Registers the translator owned by the fully initialized default runtime.\n *\n * @param translator - Default SDK runtime translator.\n */\nexport function setMiaixzDefaultTranslator(translator: MiaixzTranslator): void {\n  activeTranslator = translator;\n}\n"]}