prisma-prefixed-ids 1.0.0

package/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "env": {
+    "node": true,
+    "es2021": true,
+    "jest": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "error",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "^_" }
+    ]
+  },
+  "ignorePatterns": [
+    "**/*.test.ts",
+    "**/*.spec.ts",
+    "dist/**/*",
+    "node_modules/**/*"
+  ]
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Check formatting
+      run: npm run format:check
+
+    - name: Run linter
+      run: npm run lint
+
+    - name: Build
+      run: npm run build
+
+    - name: Run tests with coverage
+      run: npm run test:coverage 

package/.prettierrc

@@ -0,0 +1 @@
+ 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Prageeth Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,127 @@
+# Prisma Prefixed IDs
+
+[![npm version](https://img.shields.io/npm/v/prisma-prefixed-ids.svg)](https://www.npmjs.com/package/prisma-prefixed-ids)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/pureartisan/prisma-prefixed-ids/actions/workflows/ci.yml/badge.svg)](https://github.com/pureartisan/prisma-prefixed-ids/actions/workflows/ci.yml)
+
+A Prisma extension that automatically adds prefixed IDs to your models. This package allows you to configure custom prefixes for your models and even customize how the IDs are generated.
+
+## Why nanoid instead of UUID v4?
+
+This package uses [nanoid](https://github.com/ai/nanoid) for ID generation instead of UUID v4 for several reasons:
+
+1. **Better Collision Resistance**: While UUID v4 has a 122-bit random component, nanoid with 24 characters (using 36 possible characters) provides approximately 128 bits of entropy, making it even more collision-resistant than UUID v4.
+
+2. **Smaller Size**: A UUID v4 is 36 characters long (including hyphens), while a nanoid with 24 characters is more compact. When combined with a prefix (e.g., `usr_`), the total length is still shorter than a UUID v4.
+
+3. **URL-Safe**: nanoid uses URL-safe characters by default, making it suitable for use in URLs without encoding.
+
+4. **Customizable**: nanoid allows you to customize the alphabet and length, giving you more control over the ID format.
+
+5. **Better Performance**: nanoid is optimized for performance and generates IDs faster than UUID v4.
+
+For example, with a 24-character nanoid:
+- The chance of a collision is approximately 1 in 2^128 (same as UUID v4)
+- The ID length is 24 characters + prefix length (e.g., `usr_abc123...`)
+- The alphabet includes 36 characters (0-9, a-z), making it both readable and compact
+
+## Installation
+
+```bash
+npm install prisma-prefixed-ids
+```
+
+## Usage
+
+```typescript
+import { type Prisma, PrismaClient } from "@prisma/client";
+import { extendPrismaClient } from 'prisma-prefixed-ids';
+
+type ModelName = Prisma.ModelName;
+// NOTE: is your Prisma.ModelName is not available in your setup,
+// simply use the following instead:
+// type ModelName = string;
+
+// Create your Prisma client
+const prisma = new PrismaClient();
+
+// Define your model prefixes
+const prefixes: Partial<Record<ModelName, string>> = {
+	 Organization: 'org',
+  User: 'usr',
+  // Add more model prefixes as needed
+};
+
+// Extend the client with prefixed IDs
+const extendedPrisma = extendPrismaClient(prisma, {
+  prefixes,
+});
+
+// Use the extended client
+const organization = await extendedPrisma.organization.create({
+  data: {
+    name: 'My Organization',
+    // id will be automatically generated with prefix 'org_'
+  },
+});
+
+console.log(organization.id); // e.g., 'org_abc123...'
+```
+
+## Custom ID Generation
+
+You can customize how IDs are generated by providing your own ID generator function:
+
+```typescript
+import { extendPrismaClient } from 'prisma-prefixed-ids';
+import { customAlphabet } from 'nanoid';
+
+// Create a custom ID generator
+const customIdGenerator = (prefix: string) => {
+  const nanoid = customAlphabet('1234567890abcdef', 10);
+  return `${prefix}_${nanoid()}`;
+};
+
+const extendedPrisma = extendPrismaClient(prisma, {
+  prefixes: {
+    Organization: 'org',
+    User: 'usr',
+  },
+  idGenerator: customIdGenerator,
+});
+```
+
+## Configuration Options
+
+The extension accepts the following configuration:
+
+- `prefixes`: A record mapping model names to their prefixes (required)
+- `idGenerator`: A function that generates IDs (optional, defaults to using nanoid)
+
+### Prefixes Configuration
+
+The `prefixes` configuration is a simple object where:
+- Keys are your Prisma model names (case sensitive)
+- Values are the prefixes you want to use (without the underscore, which is added automatically)
+
+Example:
+```typescript
+const prefixes = {
+  Organization: 'org',
+  User: 'usr',
+  Post: 'post',
+  Comment: 'cmt',
+};
+```
+
+### ID Generator Function
+
+The `idGenerator` function should:
+- Accept a prefix as its only parameter
+- Return a string that will be used as the ID
+
+The default generator uses nanoid with a 24-character length and alphanumeric characters.
+
+## License
+
+MIT 

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { PrismaClient } from "@prisma/client";
+type ModelName = string;
+export type PrefixConfig<ModelName extends string> = {
+    prefixes: Record<ModelName, string>;
+    idGenerator?: (prefix: string) => string;
+};
+type QueryArgs = {
+    args: any;
+    query: (args: any) => Promise<any>;
+    model: ModelName;
+};
+export declare function createPrefixedIdsExtension<ModelName extends string>(config: PrefixConfig<ModelName>): {
+    name: string;
+    query: {
+        $allModels: {
+            create: (args: QueryArgs) => Promise<any>;
+            createMany: (args: QueryArgs) => Promise<any>;
+        };
+    };
+};
+export declare function extendPrismaClient<ModelName extends string = string>(prisma: PrismaClient, config: PrefixConfig<ModelName>): PrismaClient;
+export {};

package/dist/index.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPrefixedIdsExtension = createPrefixedIdsExtension;
+exports.extendPrismaClient = extendPrismaClient;
+const nanoid_1 = require("nanoid");
+const defaultIdGenerator = (prefix) => {
+    const nanoid = (0, nanoid_1.customAlphabet)("0123456789abcdefghijklmnopqrstuvwxyz", 24);
+    return `${prefix}_${nanoid()}`;
+};
+function createPrefixedIdsExtension(config) {
+    const { prefixes, idGenerator = defaultIdGenerator } = config;
+    const prefixedId = (modelName) => {
+        if (modelName in prefixes) {
+            return idGenerator(prefixes[modelName]);
+        }
+        return null;
+    };
+    return {
+        name: "prefixedIds",
+        query: {
+            $allModels: {
+                create: ({ args, query, model }) => {
+                    if (args.data && !args.data.id) {
+                        const id = prefixedId(model);
+                        if (id) {
+                            args.data.id = id;
+                        }
+                    }
+                    return query(args);
+                },
+                createMany: ({ args, query, model }) => {
+                    if (model in prefixes && args.data && Array.isArray(args.data)) {
+                        args.data = args.data.map((item) => {
+                            if (!item.id) {
+                                const id = prefixedId(model);
+                                if (id) {
+                                    return {
+                                        ...item,
+                                        id,
+                                    };
+                                }
+                            }
+                            return item;
+                        });
+                    }
+                    return query(args);
+                },
+            },
+        },
+    };
+}
+function extendPrismaClient(prisma, config) {
+    return prisma.$extends(createPrefixedIdsExtension(config));
+}

package/jest.config.cjs

@@ -0,0 +1,16 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
+  transform: {
+    "^.+\\.ts$": [
+      "ts-jest",
+      {
+        tsconfig: "tsconfig.test.json",
+      },
+    ],
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1",
+  },
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "prisma-prefixed-ids",
+  "version": "1.0.0",
+  "description": "A Prisma extension that adds prefixed IDs to your models",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pureartisan/prisma-prefixed-ids"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage --collectCoverageFrom='src/**/*.ts' --coveragePathIgnorePatterns='src/__tests__'",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "git:push": "git push && git push --tags"
+  },
+  "keywords": [
+    "prisma",
+    "extension",
+    "ids",
+    "prefixed",
+    "nanoid"
+  ],
+  "author": "Prageeth Silva <prageethsilva@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@prisma/client": "^5.0.0",
+    "nanoid": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "@types/nanoid": "^2.0.0",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.56.0",
+    "eslint-config-prettier": "^9.0.0",
+    "jest": "^29.0.0",
+    "prettier": "^3.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "peerDependencies": {
+    "@prisma/client": "^5.0.0"
+  }
+}

package/src/__tests__/index.test.ts

@@ -0,0 +1,137 @@
+import { jest } from "@jest/globals";
+
+import { PrismaClient } from "@prisma/client";
+import { createPrefixedIdsExtension, extendPrismaClient } from "../index";
+
+// Mock PrismaClient
+jest.mock("@prisma/client", () => {
+  return {
+    PrismaClient: jest.fn().mockImplementation(() => ({
+      $extends: jest.fn(),
+    })),
+  };
+});
+
+// Mock nanoid
+jest.mock("nanoid", () => ({
+  customAlphabet: jest.fn().mockImplementation(() => () => "mock_nanoid_value"),
+}));
+
+describe("PrefixedIdsExtension", () => {
+  let prisma: PrismaClient;
+  const mockQuery = jest.fn((args: any) => Promise.resolve(args));
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    prisma = new PrismaClient();
+  });
+
+  describe("createPrefixedIdsExtension", () => {
+    it("should create an extension with the correct name", () => {
+      const extension = createPrefixedIdsExtension({
+        prefixes: {
+          Test: "test",
+        },
+      });
+
+      expect(extension.name).toBe("prefixedIds");
+    });
+
+    it("should use default idGenerator if none provided", async () => {
+      const extension = createPrefixedIdsExtension({
+        prefixes: {
+          Test: "test",
+        },
+      });
+
+      const result = await extension.query.$allModels.create({
+        args: { data: {} },
+        query: mockQuery,
+        model: "Test",
+      });
+
+      expect(result).toBeDefined();
+      expect(mockQuery).toHaveBeenCalled();
+    });
+
+    it("should use custom idGenerator if provided", async () => {
+      const customIdGenerator = jest.fn(
+        (prefix: string) => `${prefix}_custom_id`,
+      );
+      const extension = createPrefixedIdsExtension({
+        prefixes: {
+          Test: "test",
+        },
+        idGenerator: customIdGenerator,
+      });
+
+      await extension.query.$allModels.create({
+        args: { data: {} },
+        query: mockQuery,
+        model: "Test",
+      });
+
+      expect(customIdGenerator).toHaveBeenCalledWith("test");
+      expect(mockQuery).toHaveBeenCalledWith({
+        data: { id: "test_custom_id" },
+      });
+    });
+
+    it("should not modify args if model has no prefix", async () => {
+      const extension = createPrefixedIdsExtension({
+        prefixes: {
+          Test: "test",
+        },
+      });
+
+      const originalArgs = { data: {} };
+      const result = await extension.query.$allModels.create({
+        args: originalArgs,
+        query: mockQuery,
+        model: "UnknownModel",
+      });
+
+      expect(result).toBeDefined();
+      expect(result.data).not.toHaveProperty("id");
+    });
+
+    it("should handle createMany operation", async () => {
+      const extension = createPrefixedIdsExtension({
+        prefixes: {
+          Test: "test",
+        },
+      });
+
+      const result = await extension.query.$allModels.createMany({
+        args: {
+          data: [{}, {}],
+        },
+        query: mockQuery,
+        model: "Test",
+      });
+
+      expect(result).toBeDefined();
+      expect(result.data).toHaveLength(2);
+      expect(result.data[0]).toHaveProperty("id");
+      expect(result.data[1]).toHaveProperty("id");
+    });
+  });
+
+  describe("extendPrismaClient", () => {
+    it("should extend the Prisma client with the extension", () => {
+      const extendedPrisma = extendPrismaClient(prisma, {
+        prefixes: {
+          Test: "test",
+        },
+      });
+
+      expect(prisma.$extends).toHaveBeenCalled();
+    });
+
+    it("should not throw error if prefixes are not provided", () => {
+      expect(() => {
+        extendPrismaClient(prisma, {} as any);
+      }).not.toThrow();
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,84 @@
+import { PrismaClient } from "@prisma/client";
+import { customAlphabet } from "nanoid";
+
+// Define ModelName type based on Prisma's model names
+type ModelName = string;
+
+export type PrefixConfig<ModelName extends string> = {
+  prefixes: Record<ModelName, string>;
+  idGenerator?: (prefix: string) => string;
+};
+
+const defaultIdGenerator = (prefix: string): string => {
+  const nanoid = customAlphabet("0123456789abcdefghijklmnopqrstuvwxyz", 24);
+  return `${prefix}_${nanoid()}`;
+};
+
+type QueryArgs = {
+  args: any;
+  query: (args: any) => Promise<any>;
+  model: ModelName;
+};
+
+export function createPrefixedIdsExtension<ModelName extends string>(
+  config: PrefixConfig<ModelName>,
+): {
+  name: string;
+  query: {
+    $allModels: {
+      create: (args: QueryArgs) => Promise<any>;
+      createMany: (args: QueryArgs) => Promise<any>;
+    };
+  };
+} {
+  const { prefixes, idGenerator = defaultIdGenerator } = config;
+
+  const prefixedId = (modelName: ModelName): string | null => {
+    if (modelName in prefixes) {
+      return idGenerator(prefixes[modelName]);
+    }
+    return null;
+  };
+
+  return {
+    name: "prefixedIds",
+    query: {
+      $allModels: {
+        create: ({ args, query, model }: QueryArgs): Promise<any> => {
+          if (args.data && !args.data.id) {
+            const id = prefixedId(model as ModelName);
+            if (id) {
+              args.data.id = id;
+            }
+          }
+          return query(args);
+        },
+
+        createMany: ({ args, query, model }: QueryArgs): Promise<any> => {
+          if (model in prefixes && args.data && Array.isArray(args.data)) {
+            args.data = (args.data as Record<string, any>[]).map((item) => {
+              if (!item.id) {
+                const id = prefixedId(model as ModelName);
+                if (id) {
+                  return {
+                    ...item,
+                    id,
+                  };
+                }
+              }
+              return item;
+            });
+          }
+          return query(args);
+        },
+      },
+    },
+  };
+}
+
+export function extendPrismaClient<ModelName extends string = string>(
+  prisma: PrismaClient,
+  config: PrefixConfig<ModelName>,
+): PrismaClient {
+  return prisma.$extends(createPrefixedIdsExtension(config));
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "**/*.test.ts"]
+} 

package/tsconfig.test.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "types": ["jest", "node"],
+    "esModuleInterop": true
+  },
+  "include": ["src/**/*.test.ts", "src/**/__tests__/**/*"],
+  "exclude": ["node_modules"]
+}