@kevisual/oss 0.0.13 → 0.0.14

package/package.json

@@ -1,24 +1,27 @@
 {
   "name": "@kevisual/oss",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "main": "dist/index.js",
   "scripts": {
     "build": "bun run bun.config.ts"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "keywords": [],
   "author": "abearxiong <xiongxiao@xiongxiao.me>",
   "license": "MIT",
   "type": "module",
   "devDependencies": {
-    "@types/bun": "^1.3.3",
-    "@types/node": "^24.10.1",
+    "@types/bun": "^1.3.5",
+    "@types/node": "^25.0.3",
     "bun-plugin-dts": "^0.3.0",
-    "dotenv": "^16.5.0",
-    "minio": "^8.0.5",
-    "tsup": "^8.4.0"
+    "dotenv": "^17.2.3",
+    "minio": "^8.0.6",
+    "@aws-sdk/client-s3": "^3.0.0",
+    "es-toolkit": "^1.43.0",
+    "fast-glob": "^3.3.3"
   },
   "exports": {
     ".": {
@@ -37,9 +40,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@types/lodash": "^4.17.21",
-    "fast-glob": "^3.3.3",
-    "lodash": "^4.17.21"
-  }
+  "dependencies": {}
 }

package/src/core/copy-object.ts

@@ -0,0 +1,26 @@
+import { Client, CopyDestinationOptions, CopySourceOptions } from 'minio';
+
+type CopyObjectOpts = {
+  bucketName: string;
+  newMetadata: Record<string, string>;
+  objectName: string;
+  client: Client;
+};
+/**
+ * 复制对象 REPLACE 替换
+ * @param param0
+ * @returns
+ */
+export const copyObject = async ({ bucketName, newMetadata, objectName, client }: CopyObjectOpts) => {
+  const source = new CopySourceOptions({ Bucket: bucketName, Object: objectName });
+  const stat = await client.statObject(bucketName, objectName);
+  const sourceMetadata = stat.metaData;
+  const destination = new CopyDestinationOptions({
+    Bucket: bucketName,
+    Object: objectName,
+    UserMetadata: { ...sourceMetadata, ...newMetadata },
+    MetadataDirective: 'REPLACE',
+  });
+  const copyResult = await client.copyObject(source, destination);
+  return copyResult;
+};

package/src/core/type.ts

@@ -0,0 +1,87 @@
+import { ItemBucketMetadata, Client } from 'minio';
+export type UploadedObjectInfo = {
+  etag: string;
+  lastModified?: Date;
+  size?: number;
+  versionId: string;
+  metadata?: ItemBucketMetadata;
+};
+export type StatObjectResult = {
+  size: number;
+  etag: string;
+  lastModified: Date;
+  metaData: ItemBucketMetadata;
+  versionId?: string | null;
+};
+export type ListFileObject = {
+  name: string;
+  size: number;
+  lastModified: Date;
+  etag: string;
+};
+export type ListDirectoryObject = {
+  prefix: string;
+  size: number;
+};
+export type ListObjectResult = ListFileObject | ListDirectoryObject;
+export interface OssBaseOperation {
+  prefix: string;
+  setPrefix(prefix: string): void;
+  /**
+   * 获取对象
+   * @param objectName 对象名
+   */
+  getObject(objectName: string): Promise<any>;
+  /**
+   * 上传对象
+   * @param objectName 对象名
+   * @param data 数据
+   */
+  putObject(objectName: string, data: Buffer | string, metaData?: ItemBucketMetadata): Promise<UploadedObjectInfo>;
+  /**
+   * 上传文件
+   * @param objectName 对象名
+   * @param filePath 文件路径
+   */
+  fPutObject(objectName: string, filePath: string, metaData?: ItemBucketMetadata): Promise<UploadedObjectInfo>;
+  /**
+   * 获取对象信息
+   * @param objectName 对象名
+   */
+  statObject(objectName: string): Promise<StatObjectResult>;
+  /**
+   * 删除对象
+   * @param objectName 对象名
+   */
+  deleteObject(objectName: string): Promise<any>;
+  /**
+   * 列出对象
+   * @param objectName 对象名
+   * @param opts 选项
+   * @param opts.recursive 是否递归
+   * @param opts.startAfter 开始位置
+   */
+  listObjects(
+    objectName: string,
+    opts?: {
+      /**
+       * 是否递归
+       */
+      recursive?: boolean;
+      /**
+       * 开始位置
+       */
+      startAfter?: string;
+    },
+  ): Promise<ListObjectResult[]>;
+  /**
+   * 复制对象
+   * @param sourceObject 源对象
+   * @param targetObject 目标对象
+   */
+  copyObject: Client['copyObject'];
+}
+
+export interface OssService extends OssBaseOperation {
+  owner: string;
+}

package/src/index.ts

@@ -0,0 +1,244 @@
+import { Client, ItemBucketMetadata } from 'minio';
+import { ListFileObject, ListObjectResult, OssBaseOperation } from './core/type.ts';
+import { hash } from './util/hash.ts';
+import { copyObject } from './core/copy-object.ts';
+import { getContentType } from './util/get-content-type.ts';
+import { omit } from 'es-toolkit'
+export type OssBaseOptions<T = { [key: string]: any }> = {
+  /**
+   * 已经初始化好的minio client
+   */
+  client: Client;
+  /**
+   * 桶名
+   */
+  bucketName: string;
+  /**
+   * 前缀
+   */
+  prefix?: string;
+} & T;
+
+export class OssBase implements OssBaseOperation {
+  client?: Client;
+  bucketName: string;
+  prefix = '';
+  /**
+   * 计算字符串或者对象的的md5值
+   */
+  hash = hash;
+  constructor(opts: OssBaseOptions) {
+    if (!opts.client) {
+      throw new Error('client is required');
+    }
+    this.bucketName = opts.bucketName;
+    this.client = opts.client;
+    this.prefix = opts?.prefix ?? '';
+  }
+
+  setPrefix(prefix: string) {
+    this.prefix = prefix;
+  }
+
+  async getObject(objectName: string) {
+    const bucketName = this.bucketName;
+    const obj = await this.client.getObject(bucketName, `${this.prefix}${objectName}`);
+    return obj;
+  }
+
+  async getJson(objectName: string): Promise<Record<string, any>> {
+    const obj = await this.getObject(objectName);
+    return new Promise((resolve, reject) => {
+      let data = '';
+      obj.on('data', (chunk) => {
+        data += chunk;
+      });
+      obj.on('end', () => {
+        try {
+          const jsonData = JSON.parse(data);
+          resolve(jsonData);
+        } catch (error) {
+          reject(new Error('Failed to parse JSON'));
+        }
+      });
+      obj.on('error', (err) => {
+        reject(err);
+      });
+    });
+  }
+  /**
+   * 上传文件, 当是流的时候，中断之后的etag会变，所以传递的时候不要嵌套async await，例如 busboy 监听文件流内部的时候，不要用check
+   * @param objectName
+   * @param data
+   * @param metaData
+   * @param options 如果文件本身存在，则复制原有的meta的内容
+   * @returns
+   */
+  async putObject(
+    objectName: string,
+    data: Buffer | string | Object,
+    metaData: ItemBucketMetadata = {},
+    opts?: { check?: boolean; isStream?: boolean; size?: number },
+  ) {
+    let putData: Buffer | string;
+    let size: number = opts?.size;
+    const isStream = opts?.isStream;
+    if (!isStream) {
+      if (typeof data === 'string') {
+        putData = data;
+        size = putData.length;
+      } else {
+        putData = JSON.stringify(data);
+        size = putData.length;
+      }
+    } else {
+      putData = data as any;
+      // 对于流式上传，如果没有提供 size，会导致多部分上传，ETag 会是 ****-1 格式
+      // 必须提供准确的 size 才能得到标准的 MD5 格式 ETag
+      if (!size) {
+        throw new Error('Stream upload requires size parameter to avoid multipart upload and get standard MD5 ETag');
+      }
+    }
+    if (opts?.check) {
+      const obj = await this.statObject(objectName, true);
+      if (obj) {
+        const omitMeda = ['size', 'content-type', 'cache-control', 'app-source'];
+        const objMeta = JSON.parse(JSON.stringify(omit(obj.metaData, omitMeda)));
+        metaData = {
+          ...objMeta,
+          ...metaData,
+        };
+      }
+    }
+
+    const bucketName = this.bucketName;
+    const obj = await this.client.putObject(bucketName, `${this.prefix}${objectName}`, putData, size, metaData);
+    return obj;
+  }
+
+  async deleteObject(objectName: string) {
+    const bucketName = this.bucketName;
+    const obj = await this.client.removeObject(bucketName, `${this.prefix}${objectName}`);
+    return obj;
+  }
+
+  async listObjects<IS_FILE = false>(objectName: string, opts?: { recursive?: boolean; startAfter?: string }) {
+    const bucketName = this.bucketName;
+    const prefix = `${this.prefix}${objectName}`;
+    const res = await new Promise((resolve, reject) => {
+      let res: any[] = [];
+      let hasError = false;
+      this.client
+        .listObjectsV2(bucketName, prefix, opts?.recursive ?? false, opts?.startAfter)
+        .on('data', (data) => {
+          res.push(data);
+        })
+        .on('error', (err) => {
+          console.error('minio error', prefix, err);
+          hasError = true;
+        })
+        .on('end', () => {
+          if (hasError) {
+            reject();
+            return;
+          } else {
+            resolve(res);
+          }
+        });
+    });
+    return res as IS_FILE extends true ? ListFileObject[] : ListObjectResult[];
+  }
+
+  async fPutObject(objectName: string, filePath: string, metaData?: ItemBucketMetadata) {
+    const bucketName = this.bucketName;
+    const obj = await this.client.fPutObject(bucketName, `${this.prefix}${objectName}`, filePath, metaData);
+    return obj as any;
+  }
+  /**
+   * 获取完整的对象名称
+   * @param objectName
+   * @returns
+   */
+  async getObjectName(objectName: string) {
+    return `${this.prefix}${objectName}`;
+  }
+  async statObject(objectName: string, checkFile = true) {
+    const bucketName = this.bucketName;
+    try {
+      const obj = await this.client.statObject(bucketName, `${this.prefix}${objectName}`);
+      return obj;
+    } catch (e) {
+      if (e.code === 'NotFound') {
+        return null;
+      }
+      throw e;
+    }
+  }
+  /**
+   * 检查文件hash是否一致
+   * @param objectName
+   * @param hash
+   * @returns
+   */
+  async checkObjectHash(
+    objectName: string,
+    hash: string,
+    meta?: ItemBucketMetadata,
+  ): Promise<{ success: boolean; metaData: ItemBucketMetadata | null; obj: any; equalMeta?: boolean }> {
+    const obj = await this.statObject(`${this.prefix}${objectName}`, true);
+    if (!obj) {
+      return { success: false, metaData: null, obj: null, equalMeta: false };
+    }
+    let metaData: ItemBucketMetadata = {};
+    const omitMeda = ['content-type', 'cache-control', 'app-source'];
+    const objMeta = omit(obj.metaData, omitMeda);
+    metaData = {
+      ...objMeta,
+    };
+    let equalMeta = false;
+    if (meta) {
+      equalMeta = JSON.stringify(metaData) === JSON.stringify(meta);
+    }
+    return { success: obj.etag === hash, metaData, obj, equalMeta };
+  }
+  getMetadata(pathname: string, meta: ItemBucketMetadata = { 'app-source': 'user-app' }) {
+    const isHtml = pathname.endsWith('.html');
+    if (isHtml) {
+      meta = {
+        ...meta,
+        'content-type': 'text/html; charset=utf-8',
+        'cache-control': 'no-cache',
+      };
+    } else {
+      meta = {
+        ...meta,
+        'content-type': getContentType(pathname),
+        'cache-control': 'max-age=31536000, immutable',
+      };
+    }
+    return meta;
+  }
+
+  async copyObject(sourceObject: any, targetObject: any) {
+    const bucketName = this.bucketName;
+    const obj = await this.client.copyObject(bucketName, sourceObject, targetObject);
+    return obj;
+  }
+  async replaceObject(objectName: string, meta: { [key: string]: string }) {
+    const { bucketName, client } = this;
+    return copyObject({ bucketName, client, objectName: `${this.prefix}${objectName}`, newMetadata: meta });
+  }
+  static create<T extends OssBase, U>(this: new (opts: OssBaseOptions<U>) => T, opts: OssBaseOptions<U>): T {
+    return new this(opts);
+  }
+
+  static fromBase<T extends OssBase, U>(this: new (opts: OssBaseOptions<U>) => T, createOpts: { oss: OssBase; opts: Partial<OssBaseOptions<U>> }): T {
+    const base = createOpts.oss;
+    const opts = createOpts.opts as any;
+    return new this({
+      client: base.client,
+      bucketName: base.bucketName,
+      ...opts,
+    });
+  }
+}

package/src/s3/copy-object.ts

@@ -0,0 +1,46 @@
+import { S3Client, CopyObjectCommand, HeadObjectCommand } from '@aws-sdk/client-s3';
+import { extractStandardHeaders } from '../util/extract-standard-headers.ts';
+
+type CopyObjectOpts = {
+  bucketName: string;
+  newMetadata: Record<string, string>;
+  objectName: string;
+  client: S3Client;
+};
+
+/**
+ * 复制对象 REPLACE 替换（使用 AWS SDK 实现）
+ * @param opts 复制选项
+ * @returns 复制结果
+ */
+export const copyObject = async ({ bucketName, newMetadata, objectName, client }: CopyObjectOpts) => {
+  // 获取当前对象的元数据
+  const headCommand = new HeadObjectCommand({
+    Bucket: bucketName,
+    Key: objectName,
+  });
+  const headResponse = await client.send(headCommand);
+  const sourceMetadata = headResponse.Metadata || {};
+
+  // 合并元数据
+  const mergedMeta = { ...sourceMetadata, ...newMetadata };
+  const { standardHeaders, customMetadata } = extractStandardHeaders(mergedMeta);
+
+  // 执行复制操作（同一对象，用于更新元数据）
+  const copyCommand = new CopyObjectCommand({
+    Bucket: bucketName,
+    CopySource: `${bucketName}/${objectName}`,
+    Key: objectName,
+    ContentType: standardHeaders.ContentType,
+    CacheControl: standardHeaders.CacheControl,
+    ContentDisposition: standardHeaders.ContentDisposition,
+    ContentEncoding: standardHeaders.ContentEncoding,
+    ContentLanguage: standardHeaders.ContentLanguage,
+    Expires: standardHeaders.Expires,
+    Metadata: customMetadata,
+    MetadataDirective: 'REPLACE',
+  });
+
+  const copyResult = await client.send(copyCommand);
+  return copyResult;
+};