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

package.json

@@ -9,6 +9,7 @@
     "typescript": "^5.6.2"
   },
   "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-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,22 +1,40 @@
 {
   "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",
+    "vite-plugin-dts": "^4.3.0",
     "vitest": "^2.1.1"
   },
   "dependencies": {

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,25 @@
 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, "");
+  const encoded = encodeBase58(stripped);
+  return encoded.padStart(22, "1");
+}

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

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

packages/graph-framework-utils/tsconfig.build.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "declaration": true,
+    "strictNullChecks": true,
+    "incremental": true,
+    "composite": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strictFunctionTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "noErrorTruncation": true,
+    "isolatedModules": true,
+    "target": "ESNext",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "jsx": "react-jsx"
+  },
+  "include": ["./src"],
+  "exclude": ["node_modules", "src/**/*.test.ts", "src/**/*.spec.ts", "dist"]
+}

packages/graph-framework-utils/tsconfig.json

@@ -1,27 +1,10 @@
 {
+  "extends": "./tsconfig.build.json",
   "compilerOptions": {
-    "strict": true,
-    "exactOptionalPropertyTypes": true,
-    "noUncheckedIndexedAccess": true,
-    "esModuleInterop": true,
-    "sourceMap": true,
-    "declarationMap": true,
-    "declaration": true,
-    "strictNullChecks": true,
-    "incremental": true,
-    "composite": true,
-    "allowJs": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "noFallthroughCasesInSwitch": true,
-    "noErrorTruncation": true,
-    "isolatedModules": true,
-    "target": "ESNext",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "jsx": "react-jsx"
+    "baseUrl": ".",
+    "rootDir": ".",
+    "noEmit": true
   },
-  "include": ["./src"]
+  "include": ["**/*"],
+  "exclude": ["**/node_modules", "**/dist"]
 }

packages/graph-framework-utils/vite.config.mts

@@ -0,0 +1,21 @@
+import { defineConfig } from "vite";
+import dts from "vite-plugin-dts";
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [
+    dts({ tsconfigPath: "./tsconfig.build.json", insertTypesEntry: true }),
+  ],
+  build: {
+    lib: {
+      entry: {
+        index: "./src/index.ts",
+        base58: "./src/base58.ts",
+      },
+      formats: ["es", "cjs"],
+      fileName(format, entryName) {
+        return `${entryName}${format === "es" ? ".mjs" : ".cjs"}`;
+      },
+    },
+  },
+});