@hpcc-js/wasm-zstd 1.0.0

package/package.json

@@ -0,0 +1,57 @@
+{
+    "name": "@hpcc-js/wasm-zstd",
+    "version": "1.0.0",
+    "description": "hpcc-js - WASM zstd",
+    "type": "module",
+    "exports": {
+        ".": {
+            "types": "./types/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "types": "./types/index.d.ts",
+    "files": [
+        "dist/**/*",
+        "src/**/*",
+        "types/**/*"
+    ],
+    "scripts": {
+        "clean": "rimraf ./dist ./dist-test ./types",
+        "build-types": "tsc --project tsconfig.json --emitDeclarationOnly",
+        "build-types-watch": "npm run build-types -- --watch",
+        "build-ts": "node esbuild.mjs",
+        "build-ts-dev": "npm run build-ts -- --mode=development",
+        "build-ts-watch": "npm run compile-ts-dev -- --watch",
+        "build-dev": "run-p build-types build-ts-dev",
+        "build": "run-p build-types build-ts",
+        "lint-skypack": "npx -y @skypack/package-check",
+        "lint-eslint": "eslint src/**/*.ts",
+        "lint": "run-p lint-eslint lint-skypack",
+        "test-chrome": "karma start --single-run --browsers ChromiumHeadless karma.conf.cjs",
+        "test-firefox": "karma start --single-run --browsers Firefox karma.conf.cjs",
+        "test-node": "mocha ./dist-test/index.node.js --reporter spec",
+        "test": "run-s test-chrome test-node"
+    },
+    "dependencies": {
+        "yargs": "17.7.2"
+    },
+    "devDependencies": {
+        "@hpcc-js/esbuild-plugins": "1.0.0"
+    },
+    "keywords": [
+        "graphviz",
+        "typescript",
+        "webassembly",
+        "wasm",
+        "dot",
+        "neato",
+        "twopi"
+    ],
+    "author": "hpcc-systems",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/hpcc-systems/hpcc-js-wasm.git"
+    },
+    "homepage": "https://hpcc-systems.github.io/hpcc-js-wasm/",
+    "license": "Apache-2.0"
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./zstd.ts";

package/src/wasm-library.ts

@@ -0,0 +1,59 @@
+export type PTR = number;
+export interface HeapU8 {
+    ptr: PTR;
+    size: number;
+}
+
+/**
+ * Base class to simplify moving data into and out of Wasm memory.
+ */
+export class WasmLibrary {
+
+    protected _module: any;
+    protected _exports: any;
+
+    protected constructor(_module: any, _export: any) {
+        this._module = _module;
+        this._exports = _export;
+    }
+
+    protected malloc_heapu8(size: number): HeapU8 {
+        const ptr: PTR = this._exports.malloc(size);
+        return {
+            ptr,
+            size
+        };
+    }
+
+    protected free_heapu8(data: HeapU8) {
+        this._exports.free(data.ptr);
+    }
+
+    protected uint8_heapu8(data: Uint8Array): HeapU8 {
+        const retVal = this.malloc_heapu8(data.byteLength);
+        this._module.HEAPU8.set(data, retVal.ptr);
+        return retVal;
+    }
+
+    protected heapu8_view(data: HeapU8): Uint8Array {
+        return this._module.HEAPU8.subarray(data.ptr, data.ptr + data.size);
+    }
+
+    protected heapu8_uint8(data: HeapU8): Uint8Array {
+        return new Uint8Array([...this.heapu8_view(data)]);
+    }
+
+    protected string_heapu8(str: string): HeapU8 {
+        const data = Uint8Array.from(str, x => x.charCodeAt(0));
+        return this.uint8_heapu8(data);
+    }
+
+    protected heapu8_string(data: HeapU8): string {
+        const retVal = Array.from({ length: data.size });
+        const submodule = this._module.HEAPU8.subarray(data.ptr, data.ptr + data.size);
+        submodule.forEach((c: number, i: number) => {
+            retVal[i] = String.fromCharCode(c);
+        });
+        return retVal.join("");
+    }
+}

package/src/zstd.ts

@@ -0,0 +1,130 @@
+// @ts-ignore
+import load, { reset } from "../../../build/src-cpp/zstd/zstdlib.wasm";
+import { WasmLibrary } from "./wasm-library.ts";
+
+//  Ref:  http://facebook.github.io/zstd/zstd_manual.html
+//  Ref:  https://github.com/facebook/zstd
+
+let g_zstd: Promise<Zstd>;
+
+/**
+ * The Zstandard WASM library, provides a simplified wrapper around the Zstandard c++ library.
+ * 
+ * See [Zstandard](https://facebook.github.io/zstd/) for more details.
+ * 
+ * ```ts
+ * import { Zstd } from "@hpcc-js/wasm/zstd";
+ * 
+ * const zstd = await Zstd.load();
+ * 
+ * //  Generate some "data"
+ * const data = new Uint8Array(Array.from({ length: 100000 }, (_, i) => i % 256));
+ * 
+ * const compressed_data = zstd.compress(data);
+ * const decompressed_data = zstd.decompress(compressed_data);
+ * ```
+ */
+export class Zstd extends WasmLibrary {
+
+    private constructor(_module: any) {
+        super(_module, _module.zstd.prototype);
+    }
+
+    /**
+     * Compiles and instantiates the raw wasm.
+     * 
+     * ::: info
+     * In general WebAssembly compilation is disallowed on the main thread if the buffer size is larger than 4KB, hence forcing `load` to be asynchronous;
+     * :::
+     * 
+     * @returns A promise to an instance of the Zstd class.
+     */
+    static load(): Promise<Zstd> {
+        if (!g_zstd) {
+            g_zstd = load().then((module: any) => {
+                return new Zstd(module)
+            });
+        }
+        return g_zstd;
+    }
+
+    /**
+     * Unloades the compiled wasm instance.
+     */
+    static unload() {
+        reset();
+    }
+
+    /**
+     * @returns The Zstd c++ version
+     */
+    version(): string {
+        return this._exports.version();
+    }
+
+    /**
+     * @param data Data to be compressed
+     * @param compressionLevel Compression v Speed tradeoff, when omitted it will default to `zstd.defaultCLevel()` which is currently 3.
+     * @returns Compressed data.
+     * 
+     * :::tip
+     * A note on compressionLevel:  The library supports regular compression levels from 1 up o 22. Levels >= 20, should be used with caution, as they require more memory. The library also offers negative compression levels, which extend the range of speed vs. ratio preferences.  The lower the level, the faster the speed (at the cost of compression).
+     * :::
+     */
+    compress(data: Uint8Array, compressionLevel: number = this.defaultCLevel()): Uint8Array {
+        const uncompressed = this.uint8_heapu8(data);
+
+        const compressedSize = this._exports.compressBound(data.length);
+        const compressed = this.malloc_heapu8(compressedSize);
+        compressed.size = this._exports.compress(compressed.ptr, compressedSize, uncompressed.ptr, uncompressed.size, compressionLevel);
+        /* istanbul ignore if  */
+        if (this._exports.isError(compressed.size)) {
+            console.error(this._exports.getErrorName(compressed.size));
+        }
+        const retVal = this.heapu8_uint8(compressed);
+
+        this.free_heapu8(compressed);
+        this.free_heapu8(uncompressed);
+        return retVal;
+    }
+
+    /**
+     * @param compressedData Data to be compressed
+     * @returns Uncompressed data.
+     */
+    decompress(compressedData: Uint8Array): Uint8Array {
+        const compressed = this.uint8_heapu8(compressedData);
+        const uncompressedSize = this._exports.getFrameContentSize(compressed.ptr, compressed.size);
+        /* istanbul ignore if  */
+        if (this._exports.isError(uncompressedSize)) {
+            console.error(this._exports.getErrorName(uncompressedSize));
+        }
+        const uncompressed = this.malloc_heapu8(uncompressedSize);
+
+        uncompressed.size = this._exports.decompress(uncompressed.ptr, uncompressedSize, compressed.ptr, compressed.size);
+        /* istanbul ignore if  */
+        if (this._exports.isError(uncompressed.size)) {
+            console.error(this._exports.getErrorName(uncompressed.size));
+        }
+        const retVal = this.heapu8_uint8(uncompressed);
+
+        this.free_heapu8(uncompressed);
+        this.free_heapu8(compressed);
+        return retVal;
+    }
+
+    /**
+     * @returns Default compression level (see notes above above).
+     */
+    defaultCLevel(): number {
+        return this._exports.defaultCLevel();
+    }
+
+    minCLevel(): number {
+        return this._exports.minCLevel();
+    }
+
+    maxCLevel(): number {
+        return this._exports.maxCLevel();
+    }
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export * from "./zstd.ts";

package/types/wasm-library.d.ts

@@ -0,0 +1,20 @@
+export type PTR = number;
+export interface HeapU8 {
+    ptr: PTR;
+    size: number;
+}
+/**
+ * Base class to simplify moving data into and out of Wasm memory.
+ */
+export declare class WasmLibrary {
+    protected _module: any;
+    protected _exports: any;
+    protected constructor(_module: any, _export: any);
+    protected malloc_heapu8(size: number): HeapU8;
+    protected free_heapu8(data: HeapU8): void;
+    protected uint8_heapu8(data: Uint8Array): HeapU8;
+    protected heapu8_view(data: HeapU8): Uint8Array;
+    protected heapu8_uint8(data: HeapU8): Uint8Array;
+    protected string_heapu8(str: string): HeapU8;
+    protected heapu8_string(data: HeapU8): string;
+}

package/types/zstd.d.ts

@@ -0,0 +1,60 @@
+import { WasmLibrary } from "./wasm-library.ts";
+/**
+ * The Zstandard WASM library, provides a simplified wrapper around the Zstandard c++ library.
+ *
+ * See [Zstandard](https://facebook.github.io/zstd/) for more details.
+ *
+ * ```ts
+ * import { Zstd } from "@hpcc-js/wasm/zstd";
+ *
+ * const zstd = await Zstd.load();
+ *
+ * //  Generate some "data"
+ * const data = new Uint8Array(Array.from({ length: 100000 }, (_, i) => i % 256));
+ *
+ * const compressed_data = zstd.compress(data);
+ * const decompressed_data = zstd.decompress(compressed_data);
+ * ```
+ */
+export declare class Zstd extends WasmLibrary {
+    private constructor();
+    /**
+     * Compiles and instantiates the raw wasm.
+     *
+     * ::: info
+     * In general WebAssembly compilation is disallowed on the main thread if the buffer size is larger than 4KB, hence forcing `load` to be asynchronous;
+     * :::
+     *
+     * @returns A promise to an instance of the Zstd class.
+     */
+    static load(): Promise<Zstd>;
+    /**
+     * Unloades the compiled wasm instance.
+     */
+    static unload(): void;
+    /**
+     * @returns The Zstd c++ version
+     */
+    version(): string;
+    /**
+     * @param data Data to be compressed
+     * @param compressionLevel Compression v Speed tradeoff, when omitted it will default to `zstd.defaultCLevel()` which is currently 3.
+     * @returns Compressed data.
+     *
+     * :::tip
+     * A note on compressionLevel:  The library supports regular compression levels from 1 up o 22. Levels >= 20, should be used with caution, as they require more memory. The library also offers negative compression levels, which extend the range of speed vs. ratio preferences.  The lower the level, the faster the speed (at the cost of compression).
+     * :::
+     */
+    compress(data: Uint8Array, compressionLevel?: number): Uint8Array;
+    /**
+     * @param compressedData Data to be compressed
+     * @returns Uncompressed data.
+     */
+    decompress(compressedData: Uint8Array): Uint8Array;
+    /**
+     * @returns Default compression level (see notes above above).
+     */
+    defaultCLevel(): number;
+    minCLevel(): number;
+    maxCLevel(): number;
+}