[Feature] Add compress lz4-napi (#1284)

* [Feature] Add compress lz4-napi

* update

* change name

Author: 0xslipk

README.md

@@ -81,6 +81,7 @@ If there is already an adapter that you would like to add, please post an issue
 
 * [brotli](https://github.com/jaredwray/keyv/tree/main/packages/compress-brotli): Brotli compression adapter
 * [Gzip](https://github.com/jaredwray/keyv/tree/main/packages/compress-gzip): Gzip compression adapter
+* [lz4](https://github.com/jaredwray/keyv/tree/main/packages/compress-lz4): lz4-napi compression adapter
 
 ### Third-party Storage Adapters
 

packages/compress-lz4/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2017-2021 Luke Childs
+Copyright (c) 2021-2022 Jared Wray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/compress-lz4/README.md

@@ -0,0 +1,40 @@
+# @keyv/compress-lz4 [<img width="100" align="right" src="https://jaredwray.com/images/keyv-symbol.svg" alt="keyv">](https://github.com/jaredwra/keyv)
+
+> lz4-napi compression for Keyv
+
+[![build](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml)
+[![codecov](https://codecov.io/gh/jaredwray/keyv/branch/main/graph/badge.svg?token=bRzR3RyOXZ)](https://codecov.io/gh/jaredwray/keyv)
+[![npm](https://img.shields.io/npm/v/@keyv/compress-lz4.svg)](https://www.npmjs.com/package/@keyv/compress-lz4)
+[![npm](https://img.shields.io/npm/dm/@keyv/compress-lz4)](https://npmjs.com/package/@keyv/compress-lz4)
+
+lz4-napi compression for [Keyv](https://github.com/jaredwray/keyv).
+
+lz4-napi is a data compression algorithm that is designed to be fast and efficient.
+
+## Install
+
+```shell
+npm install --save keyv @keyv/compress-lz4
+```
+
+## Usage
+
+```javascript
+import Keyv from 'keyv';
+import KeyvLz4 from '@keyv/compress-lz4';
+
+const keyv = new Keyv({store: new Map(), compression: new KeyvLz4()});
+
+```
+
+## API
+
+### @keyv/compress-lz4(\[options])
+
+#### options
+
+All options for `@keyv/compress-lz4` are based on the package [lz4-napi](https://github.com/antoniomuso/lz4-napi)
+
+## License
+
+[MIT © Jared Wray](LICENSE)

packages/compress-lz4/package.json

@@ -0,0 +1,69 @@
+{
+	"name": "@keyv/compress-lz4",
+	"version": "0.1.0",
+	"description": "lz4-napi compression for keyv",
+	"type": "module",
+	"main": "dist/index.cjs",
+	"module": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"require": "./dist/index.cjs",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
+		"prepublishOnly": "pnpm build",
+		"test": "xo --fix && vitest run --coverage",
+		"test:ci": "xo && vitest --run --sequence.setupFiles=list",
+		"clean": "rimraf ./node_modules ./coverage ./test/testdb.sqlite ./dist"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/jaredwray/keyv.git"
+	},
+	"keywords": [
+		"compress",
+		"lz4-napi",
+		"lz4",
+		"snappy",
+		"keyv",
+		"storage",
+		"adapter",
+		"key",
+		"value",
+		"store",
+		"cache",
+		"ttl"
+	],
+	"author": "Blockcoders Engineering <[email protected]>",
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/jaredwray/keyv/issues"
+	},
+	"homepage": "https://github.com/jaredwray/keyv",
+	"dependencies": {
+		"@keyv/serialize": "workspace:^",
+		"lz4-napi": "^2.8.0",
+		"keyv": "workspace:^"
+	},
+	"devDependencies": {
+		"@keyv/test-suite": "workspace:^",
+		"@vitest/coverage-v8": "^2.1.8",
+		"c8": "^10.1.3",
+		"rimraf": "^6.0.1",
+		"vitest": "^2.1.8",
+		"xo": "^0.60.0"
+	},
+	"tsd": {
+		"directory": "test"
+	},
+	"engines": {
+		"node": ">= 18"
+	},
+	"files": [
+		"dist",
+		"LICENSE"
+	]
+}

packages/compress-lz4/src/index.ts

@@ -0,0 +1,40 @@
+import {compress, uncompress} from 'lz4-napi';
+import {defaultDeserialize, defaultSerialize} from '@keyv/serialize';
+import {type Deserialize, type Serialize} from 'types';
+
+export class KeyvLz4 {
+	constructor(private readonly dictionary?: string) {}
+
+	async compress(data: string): Promise<Uint8Array> {
+		return compress(Buffer.from(data), this.getDictionary());
+	}
+
+	async decompress(data: Uint8Array): Promise<string> {
+		const value = await uncompress(Buffer.from(data), this.getDictionary());
+
+		return value.toString('utf8');
+	}
+
+	async serialize({value, expires}: Serialize): Promise<string> {
+		const compressedUint8Array = await this.compress(value);
+
+		return defaultSerialize({value: compressedUint8Array, expires});
+	}
+
+	async deserialize(data: string): Promise<Serialize> {
+		const {value, expires}: Deserialize = defaultDeserialize(data);
+		const uncompressedUint8Array = await this.decompress(value);
+
+		return {value: uncompressedUint8Array, expires};
+	}
+
+	private getDictionary() {
+		if (this.dictionary) {
+			return Buffer.from(this.dictionary);
+		}
+
+		return undefined;
+	}
+}
+
+export default KeyvLz4;

packages/compress-lz4/src/types.ts

@@ -0,0 +1,9 @@
+export type Serialize = {
+	value: string;
+	expires?: number;
+};
+
+export type Deserialize = {
+	value: Uint8Array;
+	expires?: number;
+};

packages/compress-lz4/test/test.ts

@@ -0,0 +1,37 @@
+import {keyvCompresstionTests} from '@keyv/test-suite';
+import {Keyv} from 'keyv';
+import * as test from 'vitest';
+import KeyvLz4 from '../src/index.js';
+
+// @ts-expect-error - KeyvLz4 type
+keyvCompresstionTests(test, new KeyvLz4());
+
+test.it('object type compression/decompression', async t => {
+	const keyv = new KeyvLz4();
+	const value = JSON.stringify({
+		a: 1,
+		b: 'test',
+		c: true,
+	});
+	const compressed = await keyv.compress(value);
+	const decompressed = await keyv.decompress(compressed);
+	t.expect(decompressed).toEqual(value);
+});
+
+test.it('compression with options', async t => {
+	const keyv = new KeyvLz4('test');
+	const keyvWithoutOptions = new KeyvLz4();
+	const compressed = await keyv.compress('whatever');
+	const compressedWithoutOptions = await keyvWithoutOptions.compress('whatever');
+	t.expect(compressed).not.toBe(compressedWithoutOptions);
+});
+
+test.it('decompress should not throw error when empty with gzip', async t => {
+	const keyv = new Keyv({store: new Map(), compression: new KeyvLz4()});
+	await t.expect(keyv.get('foo')).resolves.not.toThrowError();
+});
+
+test.it('should not throw error when empty', async t => {
+	const keyv = new Keyv({store: new Map()});
+	await t.expect(keyv.get('foo')).resolves.not.toThrowError();
+});

packages/compress-lz4/tsconfig.json

@@ -0,0 +1,25 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
+        "baseUrl": "./src",                                  /* Specify the base directory to resolve non-relative module names. */
+
+        /* Emit */
+        "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+        "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+        "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
+
+        /* Interop Constraints */
+        "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+        "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+
+        /* Type Checking */
+        "strict": true,                                      /* Enable all strict type-checking options. */
+
+        /* Completeness */
+        "skipLibCheck": true,                     /* Skip type checking all .d.ts files. */
+        "lib": [
+            "ESNext", "DOM"
+        ]
+    }
+}

packages/compress-lz4/vitest.config.ts

@@ -0,0 +1,4 @@
+import {defineConfig, mergeConfig} from 'vitest/config';
+import vitestConfig from '../../vitest.general.config.js';
+
+export default mergeConfig(vitestConfig, defineConfig({}));

packages/keyv/README.md

@@ -289,14 +289,30 @@ The following are third-party storage adapters compatible with Keyv:
 
 # Compression
 
-Keyv supports `gzip` and `brotli` compression. To enable compression, pass the `compress` option to the constructor.
+Keyv supports `gzip`, `brotli` and lz4-napi compression. To enable compression, pass the `compress` option to the constructor.
 
 ```js
 import Keyv from 'keyv';
 import KeyvGzip from '@keyv/compress-gzip';
 
 const keyvGzip = new KeyvGzip();
-const keyv = new Keyv({ compression: KeyvGzip });
+const keyv = new Keyv({ compression: keyvGzip });
+```
+
+```js
+import Keyv from 'keyv';
+import KeyvBrotli from '@keyv/compress-brotli';
+
+const keyvBrotli = new KeyvBrotli();
+const keyv = new Keyv({ compression: keyvBrotli });
+```
+
+```js
+import Keyv from 'keyv';
+import KeyvLz4 from '@keyv/compress-lz4';
+
+const keyvLz4 = new KeyvLz4();
+const keyv = new Keyv({ compression: keyvLz4 });
 ```
 
 You can also pass a custom compression function to the `compression` option. Following the pattern of the official compression adapters.

packages/keyv/package.json

@@ -65,6 +65,7 @@
 	},
 	"devDependencies": {
 		"@keyv/compress-brotli": "workspace:^",
+		"@keyv/compress-lz4": "workspace:^",
 		"@keyv/compress-gzip": "workspace:^",
 		"@keyv/memcache": "workspace:^",
 		"@keyv/mongo": "workspace:^",

packages/keyv/test/test.ts

@@ -5,6 +5,7 @@ import {KeyvSqlite} from '@keyv/sqlite';
 import {KeyvMongo} from '@keyv/mongo';
 import {KeyvBrotli} from '@keyv/compress-brotli';
 import {KeyvGzip} from '@keyv/compress-gzip';
+import {KeyvLz4} from '@keyv/compress-lz4';
 import {KeyvMemcache} from '@keyv/memcache';
 import Keyv, {type KeyvStoreAdapter, type StoredDataNoRaw, type CompressionAdapter} from '../src/index.js';
 
@@ -397,6 +398,12 @@ test.it('compress/decompress with gzip', async t => {
 	t.expect(await keyv.get('foo')).toBe('bar');
 });
 
+test.it('compress/decompress with lz4-napi', async t => {
+	const keyv = new Keyv({store: new Map(), compression: new KeyvLz4()});
+	await keyv.set('foo', 'bar');
+	t.expect(await keyv.get('foo')).toBe('bar');
+});
+
 test.it('iterator should exists with url', t => {
 	const store = new Keyv({store: new KeyvMongo({url: 'mongodb://127.0.0.1:27017'})});
 	t.expect(typeof store.iterator).toBe('function');

packages/website/site/docs/index.md

@@ -165,7 +165,7 @@ await users.clear();
 
 ## 6. Advanced - Enable Compression
 
-Keyv supports both `gzip` and `brotli` methods of compression. Before you can enable compression, you will need to install the compression package:
+Keyv supports both `gzip`, `brotli` and lz4-napi methods of compression. Before you can enable compression, you will need to install the compression package:
 
 ```sh
 npm install --save keyv @keyv/compress-gzip
@@ -182,6 +182,26 @@ const keyvGzip = new KeyvGzip();
 const keyv = new Keyv({ compression: KeyvGzip });
 ```
 
+### Example - Enable Brotli compression
+
+```js
+import Keyv from 'keyv';
+import KeyvBrotli from '@keyv/compress-brotli';
+
+const keyvBrotli = new KeyvBrotli();
+const keyv = new Keyv({ compression: keyvBrotli });
+```
+
+### Example - Enable lz4-napi compression
+
+```js
+import Keyv from 'keyv';
+import KeyvLz4 from '@keyv/compress-lz4';
+
+const keyvLz4 = new KeyvLz4();
+const keyv = new Keyv({ compression: keyvLz4 });
+```
+
 You can also pass a custom compression function to the compression option. Custom compression functions must follow the pattern of the official compression adapter (see below for further information).
 
 ### Want to build your own?

packages/website/src/docs.ts

@@ -14,7 +14,7 @@ async function main() {
 async function copyStorageAdapters() {
     const packagesPath = await getRelativePackagePath();
     const storageAdapters = await fs.promises.readdir(`${packagesPath}`);
-    const filterList = ["keyv", "website", "compress-brotli", "compress-gzip", "test-suite", ".DS_Store", "serialize", "third-party"];
+    const filterList = ["keyv", "website", "compress-brotli", "compress-gzip", "compress-lz4", "test-suite", ".DS_Store", "serialize", "third-party"];
 
     for (const storageAdapter of storageAdapters) {
         if((filterList.indexOf(storageAdapter) > -1) !== true ) {