@bb-labs/deep-sort 0.0.1

package/README.md

@@ -0,0 +1,67 @@
+## Introduction
+
+A tiny utility that **deeply normalizes** JavaScript values by:
+
+- ✅ Recursively sorting **object keys**
+- ✅ Recursively sorting **arrays** using **SuperJSON** for deterministic comparison
+- ✅ Preserving non-plain objects (`Date`, `Map`, `Set`, `BigInt`, class instances, etc.)
+- ⚡ Perfect for generating cache keys, hashing structured data, or stabilizing query arguments
+
+The goal:
+**Identical structures always produce identical normalized output — even when key order or array order differs.**
+
+---
+
+## Installation
+
+```bash
+npm install @bigbang-sdk/deep-sort
+# or
+yarn add @bigbang-sdk/deep-sort
+# or
+bun add @bigbang-sdk/deep-sort
+```
+
+---
+
+## API
+
+### `deepSort(value: unknown): unknown`
+
+Returns a **fully normalized, deeply sorted copy** of any JSON-compatible data structure.
+
+Behavior:
+
+- **Object keys** are sorted at every level
+- **Arrays** are deeply normalized, then **sorted** using SuperJSON’s structural encoding
+- Non-plain objects (Dates, Maps, Sets, etc.) are **preserved**, and naturally handled by SuperJSON
+
+```ts
+import { deepSort } from "@bigbang-sdk/deep-sort";
+
+deepSort([3, 1, 2]);
+// → [1, 2, 3]
+
+deepSort([{ b: 2, a: 1 }, { a: 3 }]);
+// → [ { a: 1, b: 2 }, { a: 3 } ]
+
+deepSort([
+  { id: 2, tags: ["b", "a"] },
+  { id: 1, tags: ["c", "a"] },
+]);
+// → normalized deeply, sorted deterministically
+```
+
+---
+
+## Caveats
+
+- Sorting arrays by SuperJSON string is deterministic but may be expensive for very large/nested data.
+- Circular references are **not supported** (SuperJSON cannot serialize them).
+- This is intended for **cache key normalization**, **equality pre-normalization**, and **stable hashing** — not for mutating live data structuress.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export declare const deepSort: (value: unknown) => unknown;

package/dist/index.js

@@ -0,0 +1,19 @@
+import { sort as sortObjectKeys } from "@tamtamchik/json-deep-sort";
+import superjson from "superjson";
+export const deepSort = (value) => {
+    if (Array.isArray(value)) {
+        // Normalize each item deeply
+        const normalizedItems = value.map(deepSort);
+        // Deterministic array sorting using SuperJSON
+        return normalizedItems.sort((a, b) => {
+            const sa = superjson.stringify(a);
+            const sb = superjson.stringify(b);
+            return sa < sb ? -1 : sa > sb ? 1 : 0;
+        });
+    }
+    if (value !== null && typeof value === "object") {
+        // Sort object keys recursively
+        return sortObjectKeys(value);
+    }
+    return value; // primitives unchanged
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@bb-labs/deep-sort",
+  "description": "A library for deep sorting using",
+  "homepage": "https://github.com/beepbop-labs/deep-sort",
+  "keywords": [
+    "deep-sort",
+    "json-deep-sort"
+  ],
+  "author": "Beepbop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beepbop-labs/deep-sort.git"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "pack": "npm run build && npm pack --pack-destination ./archive/"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@tamtamchik/json-deep-sort": "^1.4.1",
+    "superjson": "^2.2.6"
+  },
+  "version": "0.0.1"
+}