@bb-labs/convex-helpers 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/fns/create-table.d.ts

@@ -0,0 +1,25 @@
+import { type TableDefinition, type GenericTableIndexes } from "convex/server";
+import type { GenericValidator, ObjectType, VObject } from "convex/values";
+type SchemaDefinition = Record<string, GenericValidator>;
+type IndexDefinition<T extends SchemaDefinition> = {
+    name: string;
+    fields: [keyof T & string, ...(keyof T & string)[]];
+};
+type CreateTableOptions<T extends SchemaDefinition> = {
+    schema: T;
+    indexes?: IndexDefinition<T>[];
+};
+/**
+ * Helper to define a Convex table with a declarative syntax.
+ *
+ * @example
+ * export const otpsTable = createTable({
+ *   schema: OtpSchema,
+ *   indexes: [
+ *     { name: "by_email_otp", fields: ["email", "otp"] },
+ *     { name: "by_email", fields: ["email", "expiresAt"] },
+ *   ],
+ * });
+ */
+export declare function createTable<T extends SchemaDefinition>({ schema, indexes, }: CreateTableOptions<T>): TableDefinition<VObject<ObjectType<T>, T>, GenericTableIndexes>;
+export {};

package/dist/fns/create-table.js

@@ -0,0 +1,20 @@
+import { defineTable } from "convex/server";
+/**
+ * Helper to define a Convex table with a declarative syntax.
+ *
+ * @example
+ * export const otpsTable = createTable({
+ *   schema: OtpSchema,
+ *   indexes: [
+ *     { name: "by_email_otp", fields: ["email", "otp"] },
+ *     { name: "by_email", fields: ["email", "expiresAt"] },
+ *   ],
+ * });
+ */
+export function createTable({ schema, indexes = [], }) {
+    let table = defineTable(schema);
+    for (const index of indexes) {
+        table = table.index(index.name, index.fields);
+    }
+    return table;
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from "./fns/create-table";

package/dist/index.js

@@ -0,0 +1 @@
+export * from "./fns/create-table";

package/package.json

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