Skip to content

docs: enhance README with examples, comparison table, and migration guides #63

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
derodero24 merged 2 commits into from
Mar 20, 2026
Merged

docs: enhance README with examples, comparison table, and migration guides #63

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
da10fcc
docs: enhance README with examples, comparison table, and migration g…
derodero24 Mar 20, 2026
6d56cf0
docs: fix comparison table accuracy for pako and Deno/Bun support
derodero24 Mar 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 76 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# zflate

[![npm version](https://img.shields.io/npm/v/zflate)](https://www.npmjs.com/package/zflate)
[![npm downloads](https://img.shields.io/npm/dm/zflate)](https://www.npmjs.com/package/zflate)
[![CI](https://github.com/derodero24/zflate/actions/workflows/ci.yml/badge.svg)](https://github.com/derodero24/zflate/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/derodero24/zflate/graph/badge.svg)](https://codecov.io/gh/derodero24/zflate)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
Comment on lines 3 to 7

@coderabbitai coderabbitai Bot Mar 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

受け入れ基準の「bundle size バッジ」が未反映です。

バッジ追加は進んでいますが、issue #47 の目的にある bundle size バッジが見当たりません。README 冒頭に追加してください。

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 3 - 7, Add the missing "bundle size" badge to the
README.md top badges block: insert a Bundlephobia/packagephobia badge for the
zflate package (the same place as the existing npm/version/download/CI/license
badges) so it appears in the README header next to those existing shields;
ensure the badge links to the package's bundlephobia page and follows the same
markdown badge format as the other badges in README.md.


Rust-powered universal compression for JavaScript/TypeScript. **zstd**, **gzip**, and **brotli** in one package.
Expand Down Expand Up @@ -44,6 +46,22 @@ const compressed = zstdCompress(data);
const decompressed = zstdDecompress(compressed);
```

```typescript
// Gzip
import { gzipCompress, gzipDecompress } from 'zflate';

const compressed = gzipCompress(Buffer.from('Hello, gzip!'));
const decompressed = gzipDecompress(compressed);
```

```typescript
// Brotli
import { brotliCompress, brotliDecompress } from 'zflate';

const compressed = brotliCompress(Buffer.from('Hello, brotli!'));
const decompressed = brotliDecompress(compressed);
```
Comment on lines +49 to +63

@coderabbitai coderabbitai Bot Mar 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Quick Start が「4アルゴリズム掲載」の基準を満たしていません。

zstd/gzip/brotli はありますが、deflate の one-shot 例が未掲載です。受け入れ基準に合わせて deflate 例も追加した方がよいです。

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 49 - 63, Add a one-shot deflate example to the Quick
Start in README.md similar to the Gzip/Brotli snippets: import and call the
deflate functions (e.g., deflateCompress and deflateDecompress) on a Buffer and
show storing the compressed result and then decompressing it; place this new
snippet alongside the gzip and brotli examples so Quick Start includes
zstd/gzip/brotli/deflate and meets the 4-algorithm requirement.


### Streaming

```typescript
Expand Down Expand Up @@ -147,6 +165,64 @@ zstdCompress(data, -1);

`x86_64-apple-darwin`, `aarch64-apple-darwin`, `x86_64-unknown-linux-gnu`, `x86_64-unknown-linux-musl`, `aarch64-unknown-linux-gnu`, `aarch64-unknown-linux-musl`, `x86_64-pc-windows-msvc`, `aarch64-pc-windows-msvc`

## Browser Usage

zflate works in browsers via WASM. Use a bundler like Vite, webpack, or esbuild, or import directly from a CDN:

```typescript
import { gzipCompress, gzipDecompress } from 'zflate';

const encoder = new TextEncoder();
const data = encoder.encode('Hello from the browser!');

const compressed = gzipCompress(data);
const decompressed = gzipDecompress(compressed);
```

> Note: WASM initialization happens automatically on first use. For performance-critical applications, consider warming up the module by calling any function once during app startup.

Comment on lines +168 to +183

@coderabbitai coderabbitai Bot Mar 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Browser/WASM セクションに必須情報が不足しています。

目的にある「CDN import 例」と「WASM 最適化バンドルサイズの明記」が不足しています。現状は説明文のみなので、実コード例とサイズ情報（目安値）を追記してください。

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 168 - 183, Update the "Browser Usage" section to
include a concrete CDN import example and an estimated WASM bundle size note:
show how to import gzipCompress and gzipDecompress from a CDN (mention the
package name 'zflate' and a typical CDN pattern) and add a short sentence about
an approximate WASM payload size and how to reduce it (e.g., mention
tree-shaking or using a smaller WASM build), keeping the existing TextEncoder
example and the note about warming up the module; reference the functions
gzipCompress and gzipDecompress and the use of TextEncoder so readers can easily
locate where to insert the CDN line and the size/optimization note.

## Comparison with Alternatives

| Feature | zflate | pako | fflate | node:zlib |
|---------|--------|------|--------|-----------|
| zstd | ✅ | ❌ | ❌ | ✅* |
| gzip/deflate | ✅ | ✅ | ✅ | ✅ |
| brotli | ✅ | ❌ | ❌ | ✅ |
| Web Streams API | ✅ | ❌ | ❌ | ❌ |
| Streaming | ✅ | ✅† | ✅ | ✅ |
| Browser | ✅ | ✅ | ✅ | ❌ |
| Deno/Bun | ✅ | ✅ | ✅ | ❌ |
| Native performance | ✅ | ❌ | ❌ | ✅ |
| TypeScript | ✅ | ✅ | ✅ | ✅ |
| Zero JS deps | ✅ | ✅ | ✅ | ✅ |

\* Node.js ≥ 22.15 (experimental)
† Chunked mode via `Inflate`/`Deflate` classes, not Web Streams API
Comment on lines +188 to +200

@coderabbitai coderabbitai Bot Mar 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

Node.js 公式ドキュメントで、node:zlib の Zstandard（zstdCompress/zstdDecompress）対応バージョンと安定性（experimental/stable）を確認してください。該当する API リファレンス URL も提示してください。

💡 Result:

Node.jsの公式ドキュメントによると、node:zlibモジュールのZstandard（zstd）対応はzstdCompressおよびzstdDecompress（およびストリーム版のcreateZstdCompress/createZstdDecompress）が利用可能で、初回導入バージョンはv23.8.0およびv22.15.0です。安定性はexperimental（Stability: 1 - Experimental）です。 該当APIリファレンスURL: https://nodejs.org/api/zlib.html

Citations:

Node.js公式ドキュメントでzstd対応を確認し、リンク付きで明記してください。

Node.js ≥ 22.15 (experimental) はNode.js公式ドキュメント（https://nodejs.org/api/zlib.html）で確認された正確な情報です。ただし、今後のバージョンアップで変更される可能性があるため、注記に公式ドキュメントへの直接リンクを追加することで、ドキュメントの信頼性と保守性を向上させることをお勧めします。

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 188 - 200, Add a direct link to the Node.js zlib docs
next to the zstd footnote so readers can verify the "Node.js ≥ 22.15
(experimental)" claim; find the table row for zstd and the footnote text
"Node.js ≥ 22.15 (experimental)" and append or replace it with a parenthetical
or inline link to the official docs (https://nodejs.org/api/zlib.html) and a
short clarifying phrase like "(see Node.js zlib docs)" so the note is explicit
and verifiable.


## Migration

### From pako

```diff
- import pako from 'pako';
- const compressed = pako.gzip(data);
- const decompressed = pako.ungzip(compressed);
+ import { gzipCompress, gzipDecompress } from 'zflate';
+ const compressed = gzipCompress(data);
+ const decompressed = gzipDecompress(compressed);
```

### From node:zlib

```diff
- import { gzipSync, gunzipSync } from 'node:zlib';
- const compressed = gzipSync(data);
- const decompressed = gunzipSync(compressed);
+ import { gzipCompress, gzipDecompress } from 'zflate';
+ const compressed = gzipCompress(data);
+ const decompressed = gzipDecompress(compressed);
```

## Benchmarks

Measured on Apple M1, Node.js v22 (zstd level 3, gzip/brotli level 6):
Expand Down