smolcanon 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ This change log follows the format documented in [Keep a CHANGELOG].
 [semantic versioning]: http://semver.org/
 [keep a changelog]: http://keepachangelog.com/
 
+## v0.2.0 - 2025-08-18
+
+### Changed
+
+- Significantly improved performance.
+
+### Fixed
+
+- Fixed README initially copied from [`smolxxh`](https://github.com/kossnocorp/smolxxh).
+
 ## v0.1.0 - 2025-08-17
 
 Initial version

package/README.md

@@ -1,32 +1,76 @@
-# Smol xxHash
+# Smol Canon
 
-Tiny [xxHash](https://xxhash.com/) JS implementation.
+Tiny JS values canonicalization for hashing.
 
-It is a modern, faster and smaller alternative to [xxhashjs](https://www.npmjs.com/package/xxhashjs) package. It is 3.8x faster and fits in just `381B`.
+It uses a simple serialization algorithm, generating a consistent string representation of JS values. It is built to use with [Smol xxHash](https://github.com/kossnocorp/smolxxh).
 
-It is just 1.8x slower than [xxhash-wasm](https://www.npmjs.com/package/xxhash-wasm) package.
+It is tiny and efficient. It is just `185B` and 30%+ faster than other stable serialization libraries.
 
-It features dual CJS/ESM support and built-in TypeScript definitions.
+Unlike alternatives, it is focused on hashing and doesn't produce valid JSON, making it more efficient, and also supports more value types, i.e., `undefined`.
 
-It is based on [a reference C implementation](https://github.com/easyaspi314/xxhash-clean/blob/86a04ab3f01277049a23f6c9e2c4a6c174ff50c4/xxhash32-ref.c)
+It features dual CJS/ESM support and built-in TypeScript definitions.
 
 ## Installation
 
 The package is available on npm:
 
 ```sh
-npm install smolxxh
+npm install smolcanon
 ```
 
 ## Usage
 
-Pass `Buffer` or `Uint8Array` to `xxh32` function to get the hash of the content:
+Pass any JS value to the `canonize` function to get its string representation:
+
+```ts
+import { canonize } from "smolcanon";
+
+const canon = canonize({ foo: "bar", baz: "qux" });
+// => '{foo:"bar";baz:"qux"}'
+```
+
+You can use it with [Smol xxHash](https://github.com/kossnocorp/smolxxh) to produce consistent hashes for your data:
 
 ```ts
+import { canonize } from "smolcanon";
 import { xxh32 } from "smolxxh";
 
-xxh32(Buffer.from("hello world", "utf8")).toString(16);
-// => 0x31b7405d
+const canon = canonize({ foo: "bar", baz: "qux" });
+const hash = xxh32(Buffer.from("hello world", "utf8")).toString(16);
+//=> "ed4e5029"
+```
+
+## Benchmark
+
+[The benchmark](./benchmark/benchmark.ts) shows that Smol Canon is significantly faster than other popular libraries for canonicalizing JavaScript values:
+
+```
+canonicalize:
+  4 197 ops/s, ±0.28%   | 43.59% slower
+
+json-canon:
+  5 171 ops/s, ±2.11%   | 30.5% slower
+
+fast-json-stable-stringify:
+  4 548 ops/s, ±2.32%   | 38.87% slower
+
+fast-safe-stringify:
+  5 310 ops/s, ±2.30%   | 28.63% slower
+
+fast-stable-stringify:
+  4 973 ops/s, ±1.56%   | 33.16% slower
+
+json-stable-stringify:
+  3 648 ops/s, ±1.93%   | 50.97% slower
+
+json-stringify-deterministic:
+  3 054 ops/s, ±1.80%   | slowest, 58.95% slower
+
+safe-stable-stringify:
+  5 345 ops/s, ±2.17%   | 28.16% slower
+
+smolcanon:
+  7 440 ops/s, ±1.68%   | fastest
 ```
 
 ## Changelog

package/index.cjs

@@ -13,13 +13,19 @@ exports.canonize = canonize;
  */
 function canonize(input) {
   if (typeof input !== "object" || !input) {
-    if (Object.is(input, -0)) return "-0";
-    if (typeof input === "string") return JSON.stringify(input);
+    // NOTE: Traditional approach is faster than `Object.is(input, -0)`
+    if (input === 0 && 1 / input === -Infinity) return "-0";
+    //  NOTE: Manual replacing is faster than `JSON.stringify`
+    if (typeof input === "string") return `"${input.replace(/"/g, '\\"')}"`;
     return String(input);
   }
   let canon = "";
-  for (const key of Object.keys(input).sort()) {
+  const isArray = Array.isArray(input);
+  // NOTE: Skipping sorting for arrays improves performance. We also tried
+  // using `for...in` loop for arrays but it didn't affect performance at all.
+  const keys = isArray ? Object.keys(input) : Object.keys(input).sort();
+  for (const key of keys) {
     canon += `${key}:${canonize(input[key])};`;
   }
-  return Array.isArray(input) ? `[${canon}]` : `{${canon}}`;
+  return isArray ? `[${canon}]` : `{${canon}}`;
 }

package/index.js

@@ -10,13 +10,19 @@
  */
 export function canonize(input) {
   if (typeof input !== "object" || !input) {
-    if (Object.is(input, -0)) return "-0";
-    if (typeof input === "string") return JSON.stringify(input);
+    // NOTE: Traditional approach is faster than `Object.is(input, -0)`
+    if (input === 0 && 1 / input === -Infinity) return "-0";
+    //  NOTE: Manual replacing is faster than `JSON.stringify`
+    if (typeof input === "string") return `"${input.replace(/"/g, '\\"')}"`;
     return String(input);
   }
   let canon = "";
-  for (const key of Object.keys(input).sort()) {
+  const isArray = Array.isArray(input);
+  // NOTE: Skipping sorting for arrays improves performance. We also tried
+  // using `for...in` loop for arrays but it didn't affect performance at all.
+  const keys = isArray ? Object.keys(input) : Object.keys(input).sort();
+  for (const key of keys) {
     canon += `${key}:${canonize(input[key])};`;
   }
-  return Array.isArray(input) ? `[${canon}]` : `{${canon}}`;
+  return isArray ? `[${canon}]` : `{${canon}}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smolcanon",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Tiny JS objects canonicalization for hashing",
   "type": "module",
   "main": "index.cjs",
@@ -45,10 +45,19 @@
     "@swc/core": "^1.13.3",
     "@types/xxhashjs": "^0.2.4",
     "babel-plugin-replace-import-extension": "^1.1.5",
+    "benny": "^3.7.1",
     "bytes-iec": "^3.1.1",
+    "canonicalize": "^2.1.0",
+    "fast-json-stable-stringify": "^2.1.0",
+    "fast-safe-stringify": "^2.1.1",
+    "fast-stable-stringify": "^1.0.0",
     "glob": "^10.4.5",
+    "json-canon": "^1.0.1",
+    "json-stable-stringify": "^1.3.0",
+    "json-stringify-deterministic": "^1.0.12",
     "minimatch": "^10.0.3",
     "picocolors": "^1.1.1",
+    "safe-stable-stringify": "^2.5.0",
     "tsx": "^4.20.4",
     "typescript": "^5.9.2",
     "vitest": "^1.6.1"