@zenweb/cache 5.2.0 → 5.3.0

package/README.md

@@ -8,6 +8,8 @@
 - JSON 序列直接输出
 - 防止缓存击穿
 - 单例执行
+- 支持自定义序列化方式
+- 支持自定义压缩方式
 
 ## 安装
 
@@ -83,3 +85,44 @@ export class CacheController {
   }
 }
 ```
+
+## 进阶优化
+使用 msgpackr 序列化 + snappy 压缩
+
+```ts
+import { create } from 'zenweb';
+import modCache from '@zenweb/cache';
+import { Packr } from 'msgpackr';
+import * as snappy from 'snappy';
+
+const SNAPPY_MAGIC_HEADER = Buffer.from('SNAPPY');
+const packer = new Packr();
+
+const app = create();
+
+app.setup(cache({
+  serializer: {
+    deserialize(data) {
+      return packer.unpack(data)
+    },
+    serialize(data) {
+      return packer.pack(data)
+    },
+  },
+  compressor: {
+    isCompressed(data) {
+      return SNAPPY_MAGIC_HEADER.equals(data.subarray(0, SNAPPY_MAGIC_HEADER.length));
+    },
+    async compress(data) {
+      const compressed = await snappy.compress(data);
+      return Buffer.concat([SNAPPY_MAGIC_HEADER, compressed]);
+    },
+    async decompress(data) {
+      const result = await snappy.uncompress(data.subarray(SNAPPY_MAGIC_HEADER.length));
+      return typeof result === 'string' ? Buffer.from(result) : result;
+    },
+  },
+}));
+
+app.start();
+```

package/dist/cache.js

@@ -1,10 +1,5 @@
-import { gzip, unzip } from 'node:zlib';
-import { promisify } from 'node:util';
 import { Locker } from './locker.js';
 import { debug, sleep } from './utils.js';
-const compress = promisify(gzip);
-const decompress = promisify(unzip);
-const GZ_HEADER = Buffer.from([0x1F, 0x8B, 0x08]);
 const _getDebug = debug.extend('get');
 const _setDebug = debug.extend('set');
 const _lockDebug = debug.extend('lock');
@@ -65,14 +60,14 @@ export class Cache {
      */
     async set(key, value, ttlopt) {
         let compressed;
-        let data = Buffer.isBuffer(value) ? value : this.option.serializer.serialize(value);
+        let data = Buffer.isBuffer(value) ? value : await this.option.serializer.serialize(value);
         const opt = Object.assign({}, this.option.set, typeof ttlopt === 'object' ? ttlopt : undefined);
         if (typeof ttlopt === 'number') {
             opt.ttl = ttlopt;
         }
         _setDebug('[%s] data length:', key, data.length);
         if (opt.compressMinLength && data.length >= opt.compressMinLength) {
-            let _compressed = await compress(data, { level: opt.compressLevel });
+            let _compressed = await this.option.compressor.compress(data);
             _setDebug('[%s] compressed length: %d', key, _compressed.length);
             if (_compressed.length < (data.length * (opt.compressStoreRatio || 0.95))) {
                 compressed = _compressed;
@@ -95,19 +90,19 @@ export class Cache {
         let _opt = Object.assign({ parse: true, decompress: true }, opt);
         if (data) {
             // 解压处理
-            let compressed = GZ_HEADER.equals(data.subarray(0, GZ_HEADER.length));
+            let compressed = await this.option.compressor.isCompressed(data);
             if (compressed) {
                 _getDebug('[%s] is compressed', key);
                 if (_opt.parse || _opt.decompress) {
                     _getDebug('[%s] decompress', key);
-                    data = await decompress(data);
+                    data = await this.option.compressor.decompress(data);
                     compressed = false;
                 }
             }
             // 解析处理
             if (_opt.parse) {
                 _getDebug('[%s] parse', key);
-                return this.option.serializer.deserialize(data);
+                return await this.option.serializer.deserialize(data);
             }
             return new CacheResult(compressed, data);
         }

package/dist/compressor.d.ts

@@ -0,0 +1,9 @@
+import { ZlibOptions } from 'node:zlib';
+import { DataCompressor } from "./types.js";
+export declare class GzCompressor implements DataCompressor {
+    private opt?;
+    constructor(opt?: ZlibOptions | undefined);
+    isCompressed(data: Buffer): boolean;
+    compress(data: Buffer): Promise<Buffer<ArrayBufferLike>>;
+    decompress(data: Buffer): Promise<Buffer<ArrayBufferLike>>;
+}

package/dist/compressor.js

@@ -0,0 +1,20 @@
+import { gzip, unzip } from 'node:zlib';
+import { promisify } from 'node:util';
+const compress = promisify(gzip);
+const decompress = promisify(unzip);
+const GZ_HEADER = Buffer.from([0x1F, 0x8B, 0x08]);
+export class GzCompressor {
+    opt;
+    constructor(opt) {
+        this.opt = opt;
+    }
+    isCompressed(data) {
+        return GZ_HEADER.equals(data.subarray(0, GZ_HEADER.length));
+    }
+    compress(data) {
+        return compress(data, this.opt);
+    }
+    decompress(data) {
+        return decompress(data, this.opt);
+    }
+}

package/dist/index.d.ts

@@ -5,6 +5,8 @@ import { Redis } from 'ioredis';
 export * from './global.js';
 export * from './types.js';
 export * from './utils.js';
+export { GzCompressor } from './compressor.js';
+export { JSONSerializer } from './serializer.js';
 export { Locker } from './locker.js';
 export { cached } from './middleware.js';
 export { CacheHelper } from './helper.js';

package/dist/index.js

@@ -4,6 +4,8 @@ import { defaultSetupOption } from './options.js';
 export * from './global.js';
 export * from './types.js';
 export * from './utils.js';
+export { GzCompressor } from './compressor.js';
+export { JSONSerializer } from './serializer.js';
 export { Locker } from './locker.js';
 export { cached } from './middleware.js';
 export { CacheHelper } from './helper.js';

package/dist/options.d.ts

@@ -1,7 +1,10 @@
 import type { RedisOptions } from "ioredis";
-import type { LockGetOption, ObjectSerializer, SetOption, SetupOption } from "./types.js";
+import type { LockGetOption, SetOption, SetupOption } from "./types.js";
+import { JSONSerializer } from "./serializer.js";
+import { GzCompressor } from "./compressor.js";
 export declare const defaultRedisOption: RedisOptions;
 export declare const defaultSetOption: SetOption;
 export declare const defaultLockGetOption: LockGetOption;
-export declare const defaultSerializer: ObjectSerializer;
+export declare const jsonSerializer: JSONSerializer;
+export declare const gzCompressor: GzCompressor;
 export declare const defaultSetupOption: Required<SetupOption>;

package/dist/options.js

@@ -1,3 +1,5 @@
+import { JSONSerializer } from "./serializer.js";
+import { GzCompressor } from "./compressor.js";
 export const defaultRedisOption = {
     host: process.env.REDIS_HOST || '127.0.0.1',
     port: parseInt(process.env.REDIS_PORT || '') || 6379,
@@ -7,8 +9,7 @@ export const defaultRedisOption = {
 export const defaultSetOption = {
     ttl: 60,
     compressMinLength: 1024,
-    compressStoreRatio: 0.95,
-    compressLevel: 1,
+    compressStoreRatio: 0.8,
 };
 export const defaultLockGetOption = {
     retryTimeout: 5000,
@@ -17,17 +18,12 @@ export const defaultLockGetOption = {
     refresh: false,
     localStore: undefined,
 };
-export const defaultSerializer = {
-    serialize: (data) => {
-        return Buffer.from(JSON.stringify(data));
-    },
-    deserialize: (data) => {
-        return JSON.parse(data.toString());
-    },
-};
+export const jsonSerializer = new JSONSerializer();
+export const gzCompressor = new GzCompressor({ level: 1 });
 export const defaultSetupOption = {
     redis: defaultRedisOption,
     set: defaultSetOption,
     lockGet: defaultLockGetOption,
-    serializer: defaultSerializer,
+    serializer: jsonSerializer,
+    compressor: gzCompressor,
 };

package/dist/serializer.d.ts

@@ -0,0 +1,5 @@
+import { ObjectSerializer } from "./types.js";
+export declare class JSONSerializer implements ObjectSerializer {
+    serialize(data: object): Buffer<ArrayBuffer>;
+    deserialize(data: Buffer): any;
+}

package/dist/serializer.js

@@ -0,0 +1,8 @@
+export class JSONSerializer {
+    serialize(data) {
+        return Buffer.from(JSON.stringify(data));
+    }
+    deserialize(data) {
+        return JSON.parse(data.toString());
+    }
+}

package/dist/types.d.ts

@@ -23,22 +23,45 @@ export interface SetOption {
      * - 压缩完成后的长度对比压缩之前的长度所缩减的比率
      * - 压缩率不满足要求则不存储压缩数据
      * - 相对于低比率的压缩数据再解压节省的空间十分有限又浪费计算资源
-     * - 默认 0.95, 至少压缩率达到 95% 才有价值
-     * @default 0.95
+     * - 默认 0.8, 至少压缩率达到 95% 才有价值
+     * @default 0.8
      */
     compressStoreRatio?: number;
-    /**
-     * 压缩级别
-     * @default 1
-     */
-    compressLevel?: number;
 }
 /**
  * 对象序列化
  */
 export interface ObjectSerializer {
-    serialize(data: object): Buffer;
-    deserialize(data: Buffer): object;
+    /**
+     * 序列化
+     * @param data 需要被序列化的对象
+     */
+    serialize(data: object): Buffer | Promise<Buffer>;
+    /**
+     * 发序列化
+     * @param data 序列化数据
+     */
+    deserialize(data: Buffer): object | Promise<object>;
+}
+/**
+ * 数据压缩器
+ */
+export interface DataCompressor {
+    /**
+     * 是否为压缩数据
+     * @param data 压缩数据
+     */
+    isCompressed(data: Buffer): boolean | Promise<boolean>;
+    /**
+     * 压缩数据
+     * @param data 原始数据
+     */
+    compress(data: Buffer): Buffer | Promise<Buffer>;
+    /**
+     * 解压缩数据
+     * @param data 压缩数据
+     */
+    decompress(data: Buffer): Buffer | Promise<Buffer>;
 }
 export interface SetupOption {
     /**
@@ -58,6 +81,11 @@ export interface SetupOption {
      * - 默认为 JSON 序列化
      */
     serializer?: ObjectSerializer;
+    /**
+     * 数据压缩器
+     * - 默认为 Gz 压缩器
+     */
+    compressor?: DataCompressor;
 }
 /**
  * 取得缓存选项
@@ -145,6 +173,6 @@ export interface LockGetOption extends GetOption, SetOption, LockOption {
      */
     noWait?: boolean;
 }
-export type CacheKeyType = string | number | object;
+export type CacheKeyType = string | number | object | undefined | null | boolean;
 export type CacheHelperOption = Omit<LockGetOption, 'parse' | 'noWait'>;
 export type CacheHelperKey<P extends CacheKeyType[]> = string | ((...param: P) => string | Promise<string>);

package/dist/utils.js

@@ -72,12 +72,14 @@ function plainifyOrHash(obj) {
  */
 export function cacheKey(...key) {
     return key.map(i => {
-        if (typeof i === 'string')
-            return i;
-        if (typeof i === 'number')
-            return String(i);
-        if (typeof i === 'undefined')
-            return '';
+        if (i === null)
+            return 'N';
+        switch (typeof i) {
+            case 'string': return i;
+            case 'number': return String(i);
+            case 'boolean': return i ? 'T' : 'F';
+            case 'undefined': return '';
+        }
         if (i instanceof Date)
             return i.toJSON();
         return plainifyOrHash(i);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zenweb/cache",
   "type": "module",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Zenweb Cache module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -37,6 +37,7 @@
     "mocha": "^10.2.0",
     "msgpackr": "^1.11.0",
     "rimraf": "^4.3.1",
+    "snappy": "^7.3.3",
     "ts-node": "^10.9.1",
     "typescript": "^5.6.3",
     "zenweb": "^5.1.0"