@kevisual/oss 0.0.12 → 0.0.14

package/src/s3/core.ts

@@ -0,0 +1,425 @@
+import {
+  S3Client,
+  GetObjectCommand,
+  PutObjectCommand,
+  DeleteObjectCommand,
+  ListObjectsV2Command,
+  HeadObjectCommand,
+  CopyObjectCommand,
+  type GetObjectCommandOutput,
+} from '@aws-sdk/client-s3';
+import type { Readable } from 'node:stream';
+import fs from 'node:fs';
+import { omit } from 'es-toolkit';
+import {
+  OssBaseOperation,
+  ItemBucketMetadata,
+  UploadedObjectInfo,
+  StatObjectResult,
+  ListObjectResult,
+  ListFileObject,
+} from './type.ts';
+import { hash } from '../util/hash.ts';
+import { getContentType } from '../util/get-content-type.ts';
+import { extractStandardHeaders } from '../util/extract-standard-headers.ts';
+
+export type OssBaseOptions<T = { [key: string]: any }> = {
+  /**
+   * 已经初始化好的 S3Client
+   */
+  client: S3Client;
+  /**
+   * 桶名
+   */
+  bucketName: string;
+  /**
+   * 前缀
+   */
+  prefix?: string;
+} & T;
+
+export class OssBase implements OssBaseOperation {
+  client: S3Client;
+  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;
+  }
+
+  /**
+   * 获取对象
+   * @param objectName 对象名
+   */
+  async getObject(objectName: string): Promise<GetObjectCommandOutput> {
+    const command = new GetObjectCommand({
+      Bucket: this.bucketName,
+      Key: `${this.prefix}${objectName}`,
+    });
+    const response = await this.client.send(command);
+    return response;
+  }
+
+  /**
+   * 获取对象内容为字符串
+   * @param objectName 对象名
+   */
+  async getObjectAsString(objectName: string): Promise<string> {
+    const response = await this.getObject(objectName);
+    if (response.Body) {
+      return await response.Body.transformToString();
+    }
+    throw new Error('Object body is empty');
+  }
+
+  /**
+   * 获取对象内容为 JSON
+   * @param objectName 对象名
+   */
+  async getJson(objectName: string): Promise<Record<string, any>> {
+    const str = await this.getObjectAsString(objectName);
+    try {
+      return JSON.parse(str);
+    } catch (error) {
+      throw new Error('Failed to parse JSON');
+    }
+  }
+
+  /**
+   * 上传对象
+   * @param objectName 对象名
+   * @param data 数据
+   * @param metaData 元数据
+   * @param opts 选项
+   */
+  async putObject(
+    objectName: string,
+    data: Buffer | string | Object | Readable,
+    metaData: ItemBucketMetadata = {},
+    opts?: { check?: boolean; isStream?: boolean; size?: number; contentType?: string },
+  ): Promise<UploadedObjectInfo> {
+    let putData: Buffer | string | Readable;
+    let contentLength: number | undefined = opts?.size;
+    const isStream = opts?.isStream;
+
+    if (!isStream) {
+      if (typeof data === 'string') {
+        putData = data;
+        contentLength = Buffer.byteLength(data);
+      } else if (Buffer.isBuffer(data)) {
+        putData = data;
+        contentLength = data.length;
+      } else {
+        putData = JSON.stringify(data);
+        contentLength = Buffer.byteLength(putData);
+      }
+    } else {
+      putData = data as Readable;
+      if (!contentLength) {
+        throw new Error('Stream upload requires size parameter');
+      }
+    }
+
+    // 检查现有对象并合并元数据
+    if (opts?.check) {
+      const obj = await this.statObject(objectName, true);
+      if (obj) {
+        const omitMeta = ['size', 'content-type', 'cache-control', 'app-source'];
+        const objMeta = JSON.parse(JSON.stringify(omit(obj.metaData, omitMeta)));
+        metaData = {
+          ...objMeta,
+          ...metaData,
+        };
+      }
+    }
+
+    const { standardHeaders, customMetadata } = extractStandardHeaders(metaData);
+
+    const command = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: `${this.prefix}${objectName}`,
+      Body: putData,
+      ContentLength: contentLength,
+      ContentType: opts?.contentType || standardHeaders.ContentType || getContentType(objectName),
+      CacheControl: standardHeaders.CacheControl,
+      ContentDisposition: standardHeaders.ContentDisposition,
+      ContentEncoding: standardHeaders.ContentEncoding,
+      ContentLanguage: standardHeaders.ContentLanguage,
+      Expires: standardHeaders.Expires,
+      Metadata: customMetadata,
+    });
+
+    const response = await this.client.send(command);
+    return {
+      etag: response.ETag?.replace(/"/g, '') || '',
+      versionId: response.VersionId || '',
+    };
+  }
+
+  /**
+   * 上传文件
+   * @param objectName 对象名
+   * @param filePath 文件路径
+   * @param metaData 元数据
+   */
+  async fPutObject(
+    objectName: string,
+    filePath: string,
+    metaData?: ItemBucketMetadata,
+  ): Promise<UploadedObjectInfo> {
+    const fileStream = fs.createReadStream(filePath);
+    const stat = fs.statSync(filePath);
+
+    const { standardHeaders, customMetadata } = extractStandardHeaders(metaData || {});
+
+    const command = new PutObjectCommand({
+      Bucket: this.bucketName,
+      Key: `${this.prefix}${objectName}`,
+      Body: fileStream,
+      ContentLength: stat.size,
+      ContentType: standardHeaders.ContentType || getContentType(filePath),
+      CacheControl: standardHeaders.CacheControl,
+      ContentDisposition: standardHeaders.ContentDisposition,
+      ContentEncoding: standardHeaders.ContentEncoding,
+      ContentLanguage: standardHeaders.ContentLanguage,
+      Expires: standardHeaders.Expires,
+      Metadata: customMetadata,
+    });
+
+    const response = await this.client.send(command);
+    return {
+      etag: response.ETag?.replace(/"/g, '') || '',
+      versionId: response.VersionId || '',
+    };
+  }
+
+  /**
+   * 删除对象
+   * @param objectName 对象名
+   */
+  async deleteObject(objectName: string): Promise<void> {
+    const command = new DeleteObjectCommand({
+      Bucket: this.bucketName,
+      Key: `${this.prefix}${objectName}`,
+    });
+    await this.client.send(command);
+  }
+
+  /**
+   * 列出对象
+   * @param objectName 前缀
+   * @param opts 选项
+   */
+  async listObjects<IS_FILE = false>(
+    objectName: string,
+    opts?: { recursive?: boolean; startAfter?: string; maxKeys?: number },
+  ): Promise<IS_FILE extends true ? ListFileObject[] : ListObjectResult[]> {
+    const prefix = `${this.prefix}${objectName}`;
+    const results: ListObjectResult[] = [];
+    let continuationToken: string | undefined;
+
+    do {
+      const command = new ListObjectsV2Command({
+        Bucket: this.bucketName,
+        Prefix: prefix,
+        Delimiter: opts?.recursive ? undefined : '/',
+        StartAfter: opts?.startAfter,
+        MaxKeys: opts?.maxKeys || 1000,
+        ContinuationToken: continuationToken,
+      });
+
+      const response = await this.client.send(command);
+
+      // 处理文件对象
+      if (response.Contents) {
+        for (const item of response.Contents) {
+          results.push({
+            name: item.Key || '',
+            size: item.Size || 0,
+            lastModified: item.LastModified || new Date(),
+            etag: item.ETag?.replace(/"/g, '') || '',
+          });
+        }
+      }
+
+      // 处理目录（CommonPrefixes）
+      if (response.CommonPrefixes && !opts?.recursive) {
+        for (const prefix of response.CommonPrefixes) {
+          results.push({
+            prefix: prefix.Prefix || '',
+            size: 0,
+          });
+        }
+      }
+
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+
+    return results as IS_FILE extends true ? ListFileObject[] : ListObjectResult[];
+  }
+
+  /**
+   * 获取对象信息
+   * @param objectName 对象名
+   * @param checkFile 是否检查文件存在（不存在返回null而非抛错）
+   */
+  async statObject(objectName: string, checkFile = true): Promise<StatObjectResult | null> {
+    try {
+      const command = new HeadObjectCommand({
+        Bucket: this.bucketName,
+        Key: `${this.prefix}${objectName}`,
+      });
+      const response = await this.client.send(command);
+
+      return {
+        size: response.ContentLength || 0,
+        etag: response.ETag?.replace(/"/g, '') || '',
+        lastModified: response.LastModified || new Date(),
+        metaData: (response.Metadata as ItemBucketMetadata) || {},
+        versionId: response.VersionId || null,
+      };
+    } catch (e: any) {
+      if (checkFile && (e.name === 'NotFound' || e.$metadata?.httpStatusCode === 404)) {
+        return null;
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * 获取完整的对象名称
+   * @param objectName 对象名
+   */
+  getObjectName(objectName: string): string {
+    return `${this.prefix}${objectName}`;
+  }
+
+  /**
+   * 检查文件hash是否一致
+   * @param objectName 对象名
+   * @param hash hash值
+   * @param meta 元数据
+   */
+  async checkObjectHash(
+    objectName: string,
+    hash: string,
+    meta?: ItemBucketMetadata,
+  ): Promise<{ success: boolean; metaData: ItemBucketMetadata | null; obj: StatObjectResult | null; equalMeta?: boolean }> {
+    const obj = await this.statObject(objectName, true);
+    if (!obj) {
+      return { success: false, metaData: null, obj: null, equalMeta: false };
+    }
+    const omitMeta = ['content-type', 'cache-control', 'app-source'];
+    const metaData = omit(obj.metaData, omitMeta);
+    let equalMeta = false;
+    if (meta) {
+      equalMeta = JSON.stringify(metaData) === JSON.stringify(meta);
+    }
+    return { success: obj.etag === hash, metaData, obj, equalMeta };
+  }
+
+  /**
+   * 获取元数据
+   * @param pathname 路径名
+   * @param meta 元数据
+   */
+  getMetadata(pathname: string, meta: ItemBucketMetadata = { 'app-source': 'user-app' }): ItemBucketMetadata {
+    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;
+  }
+
+  /**
+   * 复制对象
+   * @param sourceObject 源对象
+   * @param targetObject 目标对象
+   */
+  async copyObject(sourceObject: string, targetObject: string): Promise<any> {
+    const command = new CopyObjectCommand({
+      Bucket: this.bucketName,
+      CopySource: `${this.bucketName}/${this.prefix}${sourceObject}`,
+      Key: `${this.prefix}${targetObject}`,
+    });
+    const response = await this.client.send(command);
+    return response;
+  }
+
+  /**
+   * 替换对象元数据
+   * @param objectName 对象名
+   * @param meta 新元数据
+   */
+  async replaceObject(objectName: string, meta: ItemBucketMetadata): Promise<any> {
+    const key = `${this.prefix}${objectName}`;
+    // 获取当前对象的元数据
+    const stat = await this.statObject(objectName, false);
+    const sourceMetadata = stat?.metaData || {};
+
+    const mergedMeta = { ...sourceMetadata, ...meta };
+    const { standardHeaders, customMetadata } = extractStandardHeaders(mergedMeta);
+
+    const command = new CopyObjectCommand({
+      Bucket: this.bucketName,
+      CopySource: `${this.bucketName}/${key}`,
+      Key: key,
+      ContentType: standardHeaders.ContentType,
+      CacheControl: standardHeaders.CacheControl,
+      ContentDisposition: standardHeaders.ContentDisposition,
+      ContentEncoding: standardHeaders.ContentEncoding,
+      ContentLanguage: standardHeaders.ContentLanguage,
+      Expires: standardHeaders.Expires,
+      Metadata: customMetadata,
+      MetadataDirective: 'REPLACE',
+    });
+    const response = await this.client.send(command);
+    return response;
+  }
+
+  /**
+   * 创建实例
+   */
+  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/type.ts

@@ -0,0 +1,157 @@
+import { CopyObjectCommandOutput } from '@aws-sdk/client-s3';
+import { Readable } from 'node:stream';
+
+export type ItemBucketMetadata = Record<string, string>;
+
+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;
+
+  /**
+   * 设置前缀
+   * @param prefix 前缀
+   */
+  setPrefix(prefix: string): void;
+
+  /**
+   * 获取对象
+   * @param objectName 对象名
+   */
+  getObject(objectName: string): Promise<any>;
+
+  /**
+   * 获取对象内容为字符串
+   * @param objectName 对象名
+   */
+  getObjectAsString?(objectName: string): Promise<string>;
+
+  /**
+   * 获取对象内容为 JSON
+   * @param objectName 对象名
+   */
+  getJson?(objectName: string): Promise<Record<string, any>>;
+
+  /**
+   * 上传对象
+   * @param objectName 对象名
+   * @param data 数据
+   * @param metaData 元数据
+   * @param opts 选项
+   */
+  putObject(
+    objectName: string,
+    data: Buffer | string | Object | Readable,
+    metaData?: ItemBucketMetadata,
+    opts?: { check?: boolean; isStream?: boolean; size?: number; contentType?: string },
+  ): Promise<UploadedObjectInfo>;
+
+  /**
+   * 上传文件
+   * @param objectName 对象名
+   * @param filePath 文件路径
+   * @param metaData 元数据
+   */
+  fPutObject(objectName: string, filePath: string, metaData?: ItemBucketMetadata): Promise<UploadedObjectInfo>;
+
+  /**
+   * 获取对象信息
+   * @param objectName 对象名
+   * @param checkFile 是否检查文件存在（不存在返回null而非抛错）
+   */
+  statObject(objectName: string, checkFile?: boolean): Promise<StatObjectResult | null>;
+
+  /**
+   * 删除对象
+   * @param objectName 对象名
+   */
+  deleteObject(objectName: string): Promise<any>;
+
+  /**
+   * 列出对象
+   * @param objectName 前缀
+   * @param opts 选项
+   */
+  listObjects(
+    objectName: string,
+    opts?: {
+      /** 是否递归 */
+      recursive?: boolean;
+      /** 开始位置 */
+      startAfter?: string;
+      /** 最大返回数量 */
+      maxKeys?: number;
+    },
+  ): Promise<ListObjectResult[]>;
+
+  /**
+   * 获取完整的对象名称
+   * @param objectName 对象名
+   */
+  getObjectName?(objectName: string): string;
+
+  /**
+   * 检查文件hash是否一致
+   * @param objectName 对象名
+   * @param hash hash值
+   * @param meta 元数据
+   */
+  checkObjectHash?(
+    objectName: string,
+    hash: string,
+    meta?: ItemBucketMetadata,
+  ): Promise<{ success: boolean; metaData: ItemBucketMetadata | null; obj: StatObjectResult | null; equalMeta?: boolean }>;
+
+  /**
+   * 获取元数据
+   * @param pathname 路径名
+   * @param meta 元数据
+   */
+  getMetadata?(pathname: string, meta?: ItemBucketMetadata): ItemBucketMetadata;
+
+  /**
+   * 复制对象
+   * @param sourceObject 源对象
+   * @param targetObject 目标对象
+   */
+  copyObject(sourceObject: string, targetObject: string): Promise<CopyObjectCommandOutput>;
+
+  /**
+   * 替换对象元数据
+   * @param objectName 对象名
+   * @param meta 新元数据
+   */
+  replaceObject?(objectName: string, meta: ItemBucketMetadata): Promise<any>;
+}
+
+export interface OssService extends OssBaseOperation {
+  owner: string;
+}

package/src/services/config.ts

@@ -0,0 +1,67 @@
+import { OssBase, OssBaseOptions } from '../index.ts';
+import { OssService } from '../core/type.ts';
+import * as util from '../util/index.ts';
+
+export class ConfigOssService extends OssBase implements OssService {
+  owner: string;
+  constructor(opts: OssBaseOptions<{ owner: string }>) {
+    super(opts);
+    this.owner = opts.owner;
+    this.setPrefix(`${this.owner}/config/1.0.0/`);
+  }
+  async listAllFile() {
+    const list = await this.listObjects<true>('');
+    return list.filter((item) => item.size > 0 && this.isEndWithJson(item.name));
+  }
+  async listAll() {
+    return await this.listObjects<false>('');
+  }
+  configMap = new Map<string, any>();
+  keys: string[] = [];
+  async getAllConfigJson() {
+    const list = await this.listAllFile();
+    return list;
+  }
+  isEndWithJson(string: string) {
+    return string?.endsWith?.(`.json`);
+  }
+  putJsonObject(key: string, data: any) {
+    const json = util.hashSringify(data);
+    return this.putObject(key, json, {
+      'Content-Type': 'application/json',
+      'app-source': 'user-config-app',
+      'Cache-Control': 'max-age=31536000, immutable',
+    });
+  }
+  async getObjectList(objectNameList: string[]) {
+    const jsonMap = new Map<string, Record<string, any>>();
+    for (const objectName of objectNameList) {
+      try {
+        const json = await this.getJson(objectName);
+        jsonMap.set(objectName, json);
+      } catch (error) {
+        console.error(error);
+        continue;
+      }
+    }
+    return jsonMap;
+  }
+  async getList() {
+    const list = await this.listAllFile();
+    /**
+     * key -> etag
+     */
+    const keyEtagMap = new Map<string, Etag>();
+    const listKeys = list.map((item) => {
+      const key = item.name.replace(this.prefix, '');
+      keyEtagMap.set(key, item.etag);
+      return {
+        ...item,
+        key,
+      };
+    });
+    type Etag = string;
+    const keys = Array.from(keyEtagMap.keys());
+    return { list: listKeys, keys, keyEtagMap };
+  }
+}

package/src/services/index.ts

@@ -0,0 +1,9 @@
+export { OssBase } from '../index.ts';
+export type { OssBaseOptions } from '../index.ts';
+export { ConfigOssService } from './config.ts';
+
+export * from '../util/download.ts';
+
+export * from '../util/index.ts';
+
+export * from '../core/type.ts';