feat(generateId): encode a UUID as base58 for the generateId method

.github/workflows/tests-and-checks.yml

@@ -3,7 +3,8 @@ name: Tests and Checks
 on: [push]
 
 jobs:
-  typecheck:
+  build-test-check:
+    name: Install deps, build required package, typecheck, lint and test
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -12,29 +13,13 @@ jobs:
           version: 9
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
+      - name: Build
+        run: pnpm build
       - name: Generate Prisma Types
         run: cd apps/server && pnpm prisma generate
       - name: Typecheck
         run: pnpm ts:check
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: pnpm/action-setup@v3
-        with:
-          version: 9
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
       - name: Linting
         run: pnpm lint
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: pnpm/action-setup@v3
-        with:
-          version: 9
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
       - name: Test
         run: pnpm test

apps/events/package.json

@@ -32,7 +32,7 @@
     "react-dom": "^18.3.1",
     "tailwind-merge": "^2.5.3",
     "tailwindcss-animate": "^1.0.7",
-    "uuid": "^10.0.0",
+    "uuid": "^11.0.2",
     "vite-plugin-node-polyfills": "^0.22.0"
   },
   "devDependencies": {
@@ -53,9 +53,7 @@
     "tailwindcss": "^3.4.13",
     "typescript": "^5.5.3",
     "typescript-eslint": "^8.8.0",
-    "vite": "^5.4.8",
     "vite-plugin-top-level-await": "^1.4.4",
-    "vite-plugin-wasm": "^3.3.0",
-    "vitest": "^2.1.2"
+    "vite-plugin-wasm": "^3.3.0"
   }
 }

package.json

@@ -1,14 +1,19 @@
 {
   "name": "graph-framework-monorepo",
   "private": true,
+  "type": "module",
   "workspaces": [
     "apps/*",
     "packages/*"
   ],
   "devDependencies": {
-    "typescript": "^5.6.2"
+    "escape-string-regexp": "^5.0.0",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.10",
+    "vitest": "^2.1.4"
   },
   "scripts": {
+    "build": "pnpm --filter graph-framework-utils build",
     "ts:check": "pnpm -r ts:check",
     "test": "pnpm -r test",
     "lint": "pnpm -r lint"

packages/graph-framework-identity/package.json

@@ -17,12 +17,10 @@
     "effect": "^3.10.12"
   },
   "devDependencies": {
-    "effect": "^3.10.12",
-    "vite": "^5.4.8",
-    "vitest": "^2.1.1"
+    "effect": "^3.10.12"
   },
   "dependencies": {
-    "uuid": "^10.0.0",
+    "uuid": "^11.0.2",
     "graph-framework-utils": "workspace:*"
   }
 }

packages/graph-framework-schema/package.json

@@ -30,9 +30,7 @@
     "@types/react": "^18.3.7",
     "@types/uuid": "^10.0.0",
     "@vitejs/plugin-react": "^4.3.2",
-    "jsdom": "^25.0.1",
-    "vite": "^5.4.8",
-    "vitest": "^2.1.1"
+    "jsdom": "^25.0.1"
   },
   "dependencies": {
     "fast-deep-equal": "^3.1.3",

packages/graph-framework-space-events/package.json

@@ -17,12 +17,10 @@
     "effect": "^3.10.12"
   },
   "devDependencies": {
-    "effect": "^3.10.12",
-    "vite": "^5.4.8",
-    "vitest": "^2.1.1"
+    "effect": "^3.10.12"
   },
   "dependencies": {
-    "uuid": "^10.0.0",
+    "uuid": "^11.0.2",
     "graph-framework-utils": "workspace:*"
   }
 }

packages/graph-framework-space-events/src/create-space.ts

@@ -1,5 +1,5 @@
 import { generateId } from "graph-framework-utils";
-import { Author, SpaceEvent } from "./types.js";
+import type { Author, SpaceEvent } from "./types.js";
 
 type Params = {
   author: Author;

packages/graph-framework-utils/README.md

@@ -0,0 +1,45 @@
+# Graph Framework Utils
+
+Provides common utilities for the Graph Framework.
+
+_All utilities must be runnable on: Browser, NodeJS server, ReactNative._
+
+## API
+
+- `generateId()` - generates a base58 encoded ID from a generated v4 UUID.
+
+```ts
+import { generateId } from "graph-framework-utils";
+
+const id = generateId();
+console.log(id); // Gw9uTVTnJdhtczyuzBkL3X
+```
+
+### Base58 utils
+
+- `encodeBase58` - encodes a given string (like the hyphen-stripped UUID) to base 58
+
+```ts
+import { v4 } from "uuid";
+import { encodeBase58 } from "graph-framework-utils/base58";
+
+const uuid = v4(); // 92539817-7989-4083-ab80-e9c2b2b66669
+const stripped = uuid.replaceAll(/-/g, ""); // 9253981779894083ab80e9c2b2b66669
+const encoded = encodeBase58(dashesRemoved);
+console.log(encoded); // K51CbDqxW35osbjPo5ZF77
+```
+
+- `decodeBase58ToUUID` - decodes the given base58 encoded UUID back to its original UUID value
+
+```ts
+import { v4 } from "uuid";
+import { decodeBase58ToUUID, encodeBase58 } from "graph-framework-utils/base58";
+
+const uuid = v4(); // 92539817-7989-4083-ab80-e9c2b2b66669
+const stripped = uuid.replaceAll(/-/g, ""); // 9253981779894083ab80e9c2b2b66669
+const encoded = encodeBase58(dashesRemoved); // K51CbDqxW35osbjPo5ZF77
+const decoded = decodeBase58ToUUID(encoded);
+
+expect(encoded).toHaveLength(22);
+expect(decoded).toEqual(uuid);
+```

packages/graph-framework-utils/package.json

@@ -1,25 +1,42 @@
 {
   "name": "graph-framework-utils",
   "version": "0.0.1",
-  "description": "",
+  "description": "Provides common utilities for the Graph Framework",
   "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./base58": {
+      "types": "./dist/base58.d.ts",
+      "require": "./dist/base58.cjs",
+      "import": "./dist/base58.mjs",
+      "default": "./dist/base58.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "sideEffects": false,
   "scripts": {
+    "build": "vite build",
     "test": "vitest run --typecheck",
     "ts:check": "tsc --noEmit",
     "lint": "echo 'No linting configured'"
   },
-  "exports": {
-    ".": {
-      "default": "./src/index.js"
-    }
-  },
   "devDependencies": {
-    "@types/react": "^18.3.7",
     "@types/uuid": "^10.0.0",
-    "vite": "^5.4.8",
-    "vitest": "^2.1.1"
+    "uuid": "^11.0.2",
+    "vite-plugin-dts": "^4.3.0"
   },
-  "dependencies": {
-    "uuid": "^10.0.0"
+  "peerDependencies": {
+    "uuid": "^11"
   }
 }

packages/graph-framework-utils/src/base58.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { v4 } from "uuid";
+
+import { decodeBase58ToUUID, encodeBase58 } from "./base58.js";
+
+describe("base58", () => {
+  it("should be able to encoded a UUID to base58 and then decode it back to its original UUID", () => {
+    const expected = v4();
+    const given = expected.replaceAll(/-/g, "");
+
+    const encoded = encodeBase58(given);
+    expect(encoded).toHaveLength(22);
+
+    const decoded = decodeBase58ToUUID(encoded);
+    expect(decoded).toHaveLength(expected.length);
+    expect(decoded).toEqual(expected);
+  });
+});

packages/graph-framework-utils/src/base58.ts

@@ -0,0 +1,76 @@
+const BASE58_ALLOWED_CHARS =
+  "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+
+export type Base58 = string;
+
+/**
+ * Base58 encodes the given string value.
+ *
+ * @example
+ * ```ts
+ * import { v4 as uuidv4 } from "uuid";
+ *
+ * const uuid = uuidv4(); // 92539817-7989-4083-ab80-e9c2b2b66669
+ * const dashesRemoved = uuid.replaceAll(/-/g, ""); // 9253981779894083ab80e9c2b2b66669
+ * const encoded = encodeBase58(dashesRemoved)
+ * console.log(encoded) // K51CbDqxW35osbjPo5ZF77
+ * ```
+ *
+ * @param val string to encode as base58
+ * @returns the base58 encoded string
+ */
+export function encodeBase58(val: string): Base58 {
+  const hex = BigInt(`0x${val}`);
+  let remainder = hex;
+  const result: string[] = []; // Use an array to store encoded characters
+
+  while (remainder > 0n) {
+    const mod = remainder % 58n;
+    result.push(BASE58_ALLOWED_CHARS[Number(mod)]!);
+    remainder = remainder / 58n;
+  }
+
+  // Reverse and join the array to get the final Base58 encoded string
+  return result.reverse().join("");
+}
+
+export type UUID = string;
+
+/**
+ * Expand the base58 encoded UUID back to its original UUID format
+ *
+ * @example
+ * ```ts
+ * const uuid = 92539817-7989-4083-ab80-e9c2b2b66669;
+ * const encoded = encodeBase58(dashesRemoved); // K51CbDqxW35osbjPo5ZF77
+ * const decoded = decodeBase58ToUUID(encoded); // 92539817-7989-4083-ab80-e9c2b2b66669
+ *
+ * expect(decoded).toEqual(uuid);
+ * ```
+ *
+ * @param encoded base58 encoded UUID
+ * @returns the expanded UUID from the base58 encoded value
+ */
+export function decodeBase58ToUUID(encoded: string): UUID {
+  let decoded = 0n;
+
+  for (let char of encoded) {
+    const index = BASE58_ALLOWED_CHARS.indexOf(char);
+    if (index === -1) {
+      throw new Error("Invalid Base58 character");
+    }
+    decoded = decoded * 58n + BigInt(index);
+  }
+
+  // Convert the bigint to a hex string, padded to 32 characters
+  let hexStr = decoded.toString(16);
+  hexStr = hexStr.padStart(32, "0"); // Ensure it is 32 characters
+
+  return [
+    hexStr.slice(0, 8),
+    hexStr.slice(8, 12),
+    hexStr.slice(12, 16),
+    hexStr.slice(16, 20),
+    hexStr.slice(20),
+  ].join("-");
+}

packages/graph-framework-utils/src/generateId.test.ts

@@ -1,10 +1,9 @@
 import { expect, it } from "vitest";
-import { generateId } from "./generateId.js";
 
-it("should generate an id", () => {
-  expect(generateId()).toBeTypeOf("string");
-});
+import { generateId } from "./generateId.js";
 
-it.skip("should have a length of 22 characters", () => {
-  expect(generateId()).toHaveLength(22);
+it("should generate a base58 encoded uuid of 22 char length", () => {
+  const id = generateId();
+  expect(id).toBeTypeOf("string");
+  expect(id).toHaveLength(22);
 });

packages/graph-framework-utils/src/generateId.ts

@@ -1,5 +1,24 @@
 import { v4 as uuidv4 } from "uuid";
 
-export const generateId = () => {
-  return uuidv4();
-};
+import { encodeBase58 } from "./base58.js";
+
+/**
+ * Generate a v4 UUID.
+ * Remove the dashes to make it a 32bit value.
+ * Base58 encode it and return.
+ *
+ * @example
+ * ```
+ * import { generateId } from 'graph-framework-utils'
+ *
+ * const id = generateId()
+ * console.log(id) // Gw9uTVTnJdhtczyuzBkL3X
+ * ```
+ *
+ * @returns base58 encoded v4 UUID
+ */
+export function generateId() {
+  const uuid = uuidv4();
+  const stripped = uuid.replaceAll(/-/g, "");
+  return encodeBase58(stripped);
+}

packages/graph-framework-utils/src/index.ts

@@ -1 +1,2 @@
+export * from "./base58.js";
 export * from "./generateId.js";