dolphin-server-modules 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,140 @@
+# Dolphin Server Modules 🐬
+
+A world-class, extremely lightweight, and 100% modular backend utility package for Node.js. It provides plug-and-play modules for Authentication, standard CRUD operations, Next.js/Express Controllers, and Zod validation. 
+
+Build production-grade APIs in minutes!
+
+## 📦 Installation
+
+```bash
+npm install dolphin-server-modules
+```
+
+You will also need to install `argon2` and `zod` if you are using the auth and validation modules respectively:
+```bash
+npm install argon2 zod
+```
+
+## 🚀 100% Modular Structure
+You can import exactly what you need without bloating your project.
+
+```typescript
+import { createAuth } from 'dolphin-server-modules/auth';
+import { createCRUD } from 'dolphin-server-modules/crud';
+import { createDolphinController } from 'dolphin-server-modules/controller';
+import { validateStructure } from 'dolphin-server-modules/middleware/zod';
+```
+
+---
+
+## 🔒 1. Auth Module (`/auth`)
+Production-ready authentication supporting **argon2 password hashing**, **JWT**, and **TOTP (2FA)**. It also ships with internal memory LRU caches for protecting against token-reuse and rate-limiting.
+
+```typescript
+import { createAuth } from 'dolphin-server-modules/auth';
+
+const auth = createAuth({ 
+  secret: 'YOUR_SUPER_SECRET_KEY', 
+  cookieMaxAge: 7 * 86400000 // 7 days
+});
+
+// Register
+const user = await auth.register(db, { email: 'user@example.com', password: 'password123' });
+
+// Login (Supports 2FA Totp)
+const session = await auth.login(db, { email: 'user@example.com', password: 'password123' });
+console.log(session.accessToken);
+```
+
+---
+
+## 💾 2. CRUD Module (`/crud`)
+A powerful Factory interface for databases providing instant pagination, soft-deletes, and ownership-checks out of the box.
+
+```typescript
+import { createCRUD } from 'dolphin-server-modules/crud';
+
+const crud = createCRUD(myDatabaseAdapter, { 
+    softDelete: true, 
+    enforceOwnership: true 
+});
+
+// Automatically creates a record with generated IDs and createdAt fields
+const newPost = await crud.create('posts', { title: 'Hello World' }, 'user_id_1');
+
+// Read with Advanced Filtering
+const posts = await crud.read('posts', { 
+    $or: [{ title: { $like: 'Hello' } }, { rating: { $gt: 4 } }] 
+});
+
+// Soft Delete
+await crud.deleteOne('posts', newPost.id, 'user_id_1');
+
+// Restore Soft Deleted
+await crud.restore('posts', newPost.id, 'user_id_1');
+```
+
+---
+
+## 🎮 3. Controller Module (`/controller`)
+Easily convert your `crud` instance into instant API Controllers. Supports Next.js App Router, Pages API, and Express out of the box.
+
+```typescript
+import { createDolphinController, createNextAppRoute } from 'dolphin-server-modules/controller';
+
+const postController = createDolphinController(crud, 'posts');
+
+// Next.js App Router API Route (app/api/posts/route.ts)
+export const { GET, POST, PUT, DELETE } = createNextAppRoute(postController);
+```
+
+---
+
+## 🍃 4. Mongoose Adapter (`/adapters/mongoose`)
+An official, fully typed Mongoose adapter for seamless integration with the Auth and CRUD modules. It handles mapping `id` to `_id`, query mapping (`$like` to `$regex`), and works independently!
+
+```typescript
+import { createMongooseAdapter } from 'dolphin-server-modules/adapters/mongoose';
+import { User, RefreshToken, Post } from './my-mongoose-models';
+
+const dbAdapter = createMongooseAdapter({
+  User,
+  RefreshToken,
+  models: {
+    posts: Post // Maps the 'posts' collection to the generic Post model
+  }
+});
+
+// Now pass dbAdapter to createAuth or createCRUD initializers!
+```
+
+---
+
+## ✅ 5. Zod Validation Middleware (`/middleware/zod`)
+Validate your data effortlessly using `zod`. Protect your endpoints from bad data.
+
+```typescript
+import { z } from 'zod';
+import { validateAppRoute } from 'dolphin-server-modules/middleware/zod';
+
+const userSchema = z.object({
+  name: z.string().min(2),
+  age: z.number().gte(18)
+});
+
+// App Router Handler wrapped with validation
+const myPostHandler = validateAppRoute(userSchema, async (req, validatedData) => {
+    console.log(validatedData.name); // 100% typed and safe
+    return new Response('Success');
+});
+```
+
+---
+
+## 🌐 Hosting Docs via GitHub Pages
+To host this documentation cleanly:
+1. Go to your repository **Settings** on GitHub.
+2. Click on **Pages** on the left sidebar.
+3. Under **Build and deployment**, select **Deploy from a branch**.
+4. Select `main` branch and `/ (root)` folder.
+5. Click **Save**. GitHub will automatically host this README as your documentation website!

package/adapters/mongoose/index.ts

@@ -0,0 +1,142 @@
+import type { Model } from 'mongoose';
+
+export interface MongooseAdapterConfig {
+  User: Model<any>;
+  RefreshToken: Model<any>;
+  models?: Record<string, Model<any>>;
+}
+
+export function createMongooseAdapter(config: MongooseAdapterConfig) {
+  // Map MongoDB document to the standard BaseDocument shape
+  const mapDoc = (doc: any) => {
+    if (!doc) return null;
+    const obj = doc.toObject && typeof doc.toObject === 'function' ? doc.toObject() : { ...doc };
+    if (obj._id) {
+      obj.id = obj._id.toString();
+      delete obj._id;
+    }
+    delete obj.__v;
+    return obj;
+  };
+
+  // Convert standard QueryFilter to Mongoose Query format
+  const mapQuery = (query: any) => {
+    if (!query) return {};
+    const parsed: any = {};
+    for (const [key, val] of Object.entries(query)) {
+      if (key === 'id') {
+        parsed['_id'] = val;
+      } else if (key === '$and' || key === '$or') {
+        parsed[key] = (val as any[]).map(mapQuery);
+      } else if (typeof val === 'object' && val !== null && !Array.isArray(val)) {
+        const ops: any = {};
+        for (const [op, opVal] of Object.entries(val)) {
+          if (op === '$like') {
+            ops['$regex'] = opVal;
+            ops['$options'] = 'i';
+          } else {
+            ops[op] = opVal;
+          }
+        }
+        parsed[key] = ops;
+      } else {
+        parsed[key] = val;
+      }
+    }
+    return parsed;
+  };
+
+  // Convert standard sorting to Mongoose sort format
+  const mapSort = (sort?: Record<string, 'asc' | 'desc'>) => {
+    if (!sort) return undefined;
+    const result: Record<string, 1 | -1> = {};
+    for (const [k, v] of Object.entries(sort)) {
+      result[k] = v === 'asc' ? 1 : -1;
+    }
+    return result;
+  };
+
+  // Helper to fetch generic CRUD models
+  const getModel = (collection: string): Model<any> => {
+    if (!config.models || !config.models[collection]) {
+      throw new Error(`Model for collection '${collection}' not found in MongooseAdapterConfig`);
+    }
+    return config.models[collection];
+  };
+
+  return {
+    // ==========================================
+    // AUTHENTICATION ADAPTER METHODS
+    // ==========================================
+    async createUser(data: any) {
+      const user = await config.User.create(data);
+      return mapDoc(user);
+    },
+    async findUserByEmail(email: string) {
+      const user = await config.User.findOne({ email });
+      return mapDoc(user);
+    },
+    async findUserById(id: string) {
+      const user = await config.User.findById(id);
+      return mapDoc(user);
+    },
+    async updateUser(id: string, data: any) {
+      const user = await config.User.findByIdAndUpdate(id, data, { new: true });
+      return mapDoc(user);
+    },
+    async saveRefreshToken(data: any) {
+      await config.RefreshToken.create(data);
+    },
+    async findRefreshToken(token: string) {
+      const rt = await config.RefreshToken.findOne({ token });
+      return mapDoc(rt);
+    },
+    async deleteRefreshToken(token: string) {
+      await config.RefreshToken.deleteOne({ token });
+    },
+
+    // ==========================================
+    // CRUD ADAPTER METHODS
+    // ==========================================
+    async create(collection: string, data: any) {
+      const Model = getModel(collection);
+      const doc = await Model.create(data);
+      return mapDoc(doc);
+    },
+    async read(collection: string, query: any) {
+      const Model = getModel(collection);
+      const docs = await Model.find(mapQuery(query));
+      return docs.map(mapDoc);
+    },
+    async update(collection: string, query: any, data: any) {
+      const Model = getModel(collection);
+      await Model.updateMany(mapQuery(query), data);
+      
+      // Return updated documents if we can map them back, otherwise minimal info
+      // Since updateMany doesn't return the updated docs in mongoose, we can just return a generic success object 
+      // or fetch them. The interface expects Promise<any>. We will fetch them to match typical behavior.
+      const docs = await Model.find(mapQuery({ ...query, ...data }));
+      return docs.map(mapDoc);
+    },
+    async delete(collection: string, query: any) {
+      const Model = getModel(collection);
+      await Model.deleteMany(mapQuery(query));
+      return { deleted: true };
+    },
+    async advancedRead(collection: string, query: any, options: any) {
+      const Model = getModel(collection);
+      let mQuery = Model.find(mapQuery(query));
+      if (options.sort) {
+        mQuery = mQuery.sort(mapSort(options.sort));
+      }
+      if (options.offset !== undefined) {
+        mQuery = mQuery.skip(options.offset);
+      }
+      if (options.limit !== undefined) {
+        mQuery = mQuery.limit(options.limit);
+      }
+      const docs = await mQuery;
+      return docs.map(mapDoc);
+    }
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dolphin-server-modules",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Core utility modules for Auth, CRUD, and Controllers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,8 @@
     "./auth": "./dist/auth/auth.js",
     "./controller": "./dist/controller/controller.js",
     "./crud": "./dist/curd/crud.js",
-    "./middleware/zod": "./dist/middleware/zod.js"
+    "./middleware/zod": "./dist/middleware/zod.js",
+    "./adapters/mongoose": "./dist/adapters/mongoose/index.js"
   },
   "scripts": {
     "build": "tsc",
@@ -33,6 +34,7 @@
     "@types/jest": "^29.5.12",
     "@types/node": "^20.11.30",
     "jest": "^29.7.0",
+    "mongoose": "^9.3.2",
     "ts-jest": "^29.1.2",
     "typescript": "^5.4.3"
   }