speedly 2.0.38 → 2.0.42

package/README.md

@@ -1,171 +1,470 @@
-**Overview**
-
-- **Project**: `speedly` — a lightweight express utility framework that bundles auth middlewares, database model handlers, file uploader helpers, request validators, API documentation loader and small utilities to speed up building REST APIs.
-- **Entry point exports**: `auth`, `db`, `uploader`, `validator`, `models`, `modules`, `utils`, `document` (see below for details and examples).
-
-**Quick Start**
-
-- **Install**: add the project to your workspace or import the package in your service.
-- **Basic server skeleton**:
-
-```
-import express from 'express'
-import { auth, db, uploader, validator, models, modules, utils, document } from './src'
-
-const app = express();
-app.use(express.json());
-
-// Mount example module router
-app.use('/api/translation', modules.translation);
-
-// Swagger docs (served at /docs)
-document(app, require('path').join(process.cwd(), 'src/modules'));
-
-app.listen(3000);
-```
-
-**Exports Reference**
-
-**`auth`**
-
-- **Type**: default export (object)
-- **Purpose**: Provides simple express middlewares for access control. Each function returns an Express middleware that inspects the request using a configurable `customValidator` (from `getConfig('auth')`) and either allows, forbids or rejects the request.
-- **API**:
-  - `auth.user()` → middleware that enforces a `user` access type.
-  - `auth.admin(config?)` → middleware for admin access. Optionally pass `{ permission }` to require a specific admin permission (the middleware names themselves include the permission, e.g. `auth:admin:PERM`).
-  - `auth.any()` → middleware that accepts any authenticated-type logic configured by the `customValidator`.
-- **Notes**: `auth` reads default options from `getConfig('auth')`. The `customValidator` should return truthy to allow or falsy to forbid; `null` is treated as unauthorized.
-
-**`db`**
-
-- **Type**: default export (factory function)
-- **Purpose**: Creates Express middlewares that operate on a Mongoose model (or other model loaded from the `models` path). Designed to simplify CRUD endpoints by composing handler builders like `.find()`, `.create()`, `.findByIdAndUpdate()`, etc.
-- **How to use**: call `db(collectionName, config?)` to get a model handler factory, then chain action methods and use the returned function as an Express middleware.
-- **Common methods returned by `db('collection')`**:
-  - `.find(match = {})`
-  - `.create(body = {})`
-  - `.updateOne(match, body)`
-  - `.updateMany(match, body)`
-  - `.deleteOne(match)`
-  - `.deleteMany(match)`
-  - `.findOne(match)`
-  - `.findOneAndUpdate(match, body)`
-  - `.aggregate(pipeline)`
-  - `.findById(id)`
-  - `.findByIdAndUpdate(id, body)`
-  - `.findByIdAndDelete(id)`
-- **Query behavior**: The produced middleware reads query params like `search`, `filters`, `sort`, `page`, `limit`, and `select` to modify results. Pagination behaviour can be controlled via `getConfig('db')` (e.g., `pagination.quantity`, `pagination.detailed`).
-- **Config**: second argument allows overriding `{ path, type: 'internal'|'external', message }`. When `type` is `internal` the loader resolves models relative to the library; when `external` it resolves from the host app and `configs.path`.
-- **Example**:
-
-```
-// GET /api/translation -> finds translations
-app.get('/api/translation', db('translation', { type: 'internal' }).find());
-
-// POST /api/translation -> create translation documents
-app.post('/api/translation', db('translation', { type: 'internal' }).create());
-```
-
-**`uploader`**
-
-- **Type**: default export (factory)
-- **Purpose**: Provides file uploading middlewares built on `multer` and convenience helpers that optionally save media metadata to a `media` collection.
-- **Signature**: `uploader(destination = '/image', config?)` returns an object with methods `{ single, array, fields, any, none }` which are wrappers around multer handlers.
-- **Config options** (defaults obtained from `getConfig('uploader')`):
-  - `saveInDb` (boolean) — whether to persist metadata in a `media` collection
-  - `prefix` (string) — prefix for saved filenames
-  - `limit` (number) — max upload size in MB
-  - `format` (RegExp) — allowed file extensions
-  - `path` (string) — base path to save files (default `../../../public` in library defaults)
-- **Returned helpers**:
-  - `single(fieldName)` — middleware saving a single file and setting the file URL into `req.body[fieldName]`. If `saveInDb` is true it will store a doc in `media` and set `req.mediaId`.
-  - `array(fieldName, maxCount)` — accept multiple files and set an array of URLs into `req.body[fieldName]`.
-  - `fields(fieldsArray)` — accept mixed fields (multer-style field definitions).
-  - `any()` and `none()` — passthrough multer helpers.
-- **Example**:
-
-```
-app.post('/upload', uploader('/images').single('photo'), (req,res) => {
-	res.json({ url: req.body.photo });
-});
-```
-
-**`validator`**
-
-- **Type**: default export (generic factory)
-- **Purpose**: A small wrapper around `yup` to validate `req.body`, `req.params`, and `req.query`. On failure it forwards an error object to `next()` with `status: 405` and a message.
-- **Signature**: `validator({ body?: yup.Schema, params?: yup.Schema, query?: yup.Schema })` returns an Express `RequestHandler`.
-- **Behavior**: strips unknown fields, assigns validated values back to `req.body`, `req.params`, and `req.query`. The created middleware is annotated with `__validationSchema` (used by automatic documentation generator).
-- **Example**:
-
-```
-import * as yup from 'yup';
-const schema = { body: yup.object({ text: yup.string().required() }) };
-app.post('/translate', validator(schema), handler);
-```
-
-**`models`**
-
-- **Type**: object containing Mongoose models
-- **Currently included**:
-  - `translation` — Mongoose model with fields `{ text: String, lang: String, translatedText: String }` and timestamps.
-- **Purpose**: Direct access to low-level models for custom operations (e.g., prefetch, caching or complex queries).
-
-**`modules`**
-
-- **Type**: object of `express.Router` instances keyed by module name
-- **Included**:
-  - `translation` — router defined in `src/modules/translation/translation.routes.ts` with routes:
-    - `GET /` → `db('translation', {type:'internal'}).find()`
-    - `POST /` → guarded by a simple body `auth` check inside the route and then `create()`
-    - `PUT /:id` → `auth.admin()` + `validator(...)` + `findByIdAndUpdate()`
-- **Mounting**: `app.use('/api/translation', modules.translation)`
-
-**`utils`**
-
-- **Type**: object of helper utilities
-- **Included**:
-  - `translator` — a small translation helper that attempts multiple external translation providers and caches successful translations to the `translation` model. Signature: `translator(text = 'unspecified text', lang = 'fa') => Promise<string>`.
-- **Behavior**: Normalizes text, looks up local cache (`translation` model), attempts external services (a worker proxy and optionally `one-api`), writes the result to DB, and returns the translated text. Falls back to the formatted original text on failure.
-
-**`document`**
-
-- **Type**: default export (function)
-- **Purpose**: Scans `src/modules` routers and mounts a Swagger UI at `/docs` with automatically generated OpenAPI paths and basic security scheme.
-- **Signature**: `document(app: Express, baseDir?: string)` — `baseDir` defaults to `path.join(process.cwd(), 'src/module')` in the loader. Use a correct path to your modules folder (e.g., `path.join(process.cwd(), 'src/modules')`).
-- **What it detects**: routes, http methods, `yup` validation schemas (to document request bodies), and auth middlewares (to add security hints and descriptions).
-
-**Configuration & Environment**
-
-- Use `getConfig(key)` (internal) to supply runtime options for `auth`, `db`, `uploader`, and `translate` providers. Typical environment keys used by the modules:
-  - `JWT_KEY` (used by auth-related configs)
-  - `DB_URL` (database connection string if using external db config)
-  - `one_api_token` (optional token for the alternate translator provider)
-
-**Examples**
-
-- Mounting everything in a small app:
-
-```
-import express from 'express';
-import { modules, document } from './src';
-import path from 'path';
-
-const app = express();
-app.use(express.json());
-app.use('/api/translation', modules.translation);
-document(app, path.join(process.cwd(), 'src/modules'));
-app.listen(3000);
-```
-
-**Developer Notes**
-
-- `db` middleware attaches pagination, `search` and `filters` behavior using `req.query`. Use `type: 'internal'` when you want the model path resolved inside the package, or `external` to resolve from the consumer app.
-- `validator` attaches `__validationSchema` to middlewares which `document` uses to generate OpenAPI schemas.
-- `uploader` writes files to disk under the configured `path` and returns public URLs prefixed with `/static`.
-
-If you'd like, I can also:
-
-- add usage examples/tests around each exported function
-- add API reference tables per-method for `db` handlers
-- generate a small example express app under `examples/` using these exports
+# speedly
+
+A lightweight Express utility framework that bundles auth middlewares, database model handlers, file uploader helpers, request validators, an API documentation loader, and small utilities to speed up building REST APIs.
+
+## Installation
+
+```bash
+npm install speedly
+```
+
+Install peer dependencies (Express, Mongoose, and Multer are required):
+
+```bash
+npm install express mongoose multer
+```
+
+## Quick Start
+
+```js
+const speedly = require('speedly');
+const mongoose = require('mongoose');
+
+const app = speedly();
+
+mongoose.connect('mongodb://localhost:27017/myapp')
+  .catch(err => { console.error('MongoDB connection error:', err); process.exit(1); });
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+  console.log('API docs at   http://localhost:3000/docs');
+});
+```
+
+Or with ESM:
+
+```js
+import speedly from 'speedly';
+import mongoose from 'mongoose';
+
+const app = speedly();
+
+await mongoose.connect('mongodb://localhost:27017/myapp');
+
+app.listen(3000);
+```
+
+`speedly()` returns a fully configured Express app with JSON parsing, URL-encoded body parsing, static file serving, a home route, a 404 handler, an error handler, and Swagger documentation pre-wired.
+
+### Init options
+
+```js
+const app = speedly({
+  jsonParser: true,         // default: true
+  urlEncodedParser: true,   // default: true
+  cookieParser: true,       // default: true
+  staticFiles: true,        // default: true — serves /public at /static
+  homeHandler: true,        // default: true — GET / returns a welcome page
+  notFoundHandler: true,    // default: true
+  errorHandler: true,       // default: true
+  documentation: true,      // default: true — mounts Swagger UI at /docs
+});
+```
+
+---
+
+## API Reference
+
+### `speedly/kit` — auth, db, uploader, validator
+
+```js
+const { auth, db, uploader, validator } = require('speedly/kit');
+```
+
+#### `auth`
+
+Express middlewares for access control.
+
+```js
+const { auth } = require('speedly/kit');
+
+// Require an authenticated user
+app.get('/profile', auth.user(), handler);
+
+// Require an admin
+app.delete('/post/:id', auth.admin(), handler);
+
+// Require an admin with a specific permission
+app.get('/users', auth.admin({ permission: 'OWNER' }), handler);
+
+// Accept any authenticated request
+app.get('/dashboard', auth.any(), handler);
+```
+
+- `auth.user()` — enforces user-level authentication.
+- `auth.admin(config?)` — enforces admin access. Pass `{ permission }` to require a specific permission string (e.g. `'OWNER'`, `'ADMIN'`).
+- `auth.any()` — accepts any authenticated request regardless of role.
+
+#### `db`
+
+Creates Express route handlers that run Mongoose operations on a model. Supports pagination, search, sort, and field selection via query params (`?search=`, `?page=`, `?limit=`, `?sort=`, `?select=`).
+
+```js
+const { db } = require('speedly/kit');
+
+// GET /posts — list all posts (supports ?search=, ?page=, ?limit=)
+app.get('/posts', db('post').find());
+
+// POST /posts — create a new post
+app.post('/posts', db('post').create());
+
+// GET /posts/:id — get post by id
+app.get('/posts/:id', db('post').findById());
+
+// PUT /posts/:id — update post by id
+app.put('/posts/:id', db('post').findByIdAndUpdate());
+
+// DELETE /posts/:id — delete post by id
+app.delete('/posts/:id', db('post').findByIdAndDelete());
+```
+
+Available methods: `.find()`, `.create()`, `.findOne()`, `.findById()`, `.findByIdAndUpdate()`, `.findByIdAndDelete()`, `.updateOne()`, `.updateMany()`, `.deleteOne()`, `.deleteMany()`, `.findOneAndUpdate()`, `.aggregate()`.
+
+You can pass a callback to build the query dynamically from `req`:
+
+```js
+// GET /posts/:slug — find by slug and increment view count
+app.get('/posts/:slug',
+  db('post').findOneAndUpdate(
+    req => ({ slug: req.params.slug }, { $inc: { views: 1 } })
+  ).populate('author_id')
+);
+
+// POST /posts — create with author set from authenticated user
+app.post('/posts',
+  auth.admin(),
+  db('post').create(req => ({ author_id: req.user._id }))
+);
+```
+
+Chain `.populate()` and `.select()` to control what is returned:
+
+```js
+app.get('/posts',
+  db('post').find()
+    .populate([{ path: 'author_id', select: '-password' }, 'thumbnail_id'])
+);
+
+app.get('/me',
+  auth.user(),
+  db('user').findOne(req => ({ _id: req.user._id }))
+    .populate('role_id')
+    .select('-password')
+);
+```
+
+Pass `{ type: 'internal' }` to resolve speedly's built-in models:
+
+```js
+app.get('/translations', db('translation', { type: 'internal' }).find());
+```
+
+#### `uploader`
+
+File upload middlewares built on `multer`, with optional metadata persistence to a `media` collection.
+
+```js
+const { uploader } = require('speedly/kit');
+
+// Single file upload
+app.post('/upload', uploader('/images').single('photo'), (req, res) => {
+  res.json({ url: req.body.photo });
+});
+
+// Multiple files
+app.post('/gallery', uploader('/images').array('photos', 10), (req, res) => {
+  res.json({ urls: req.body.photos });
+});
+```
+
+Config options: `saveInDb`, `prefix`, `limit` (MB), `format` (RegExp), `path`.
+
+#### `validator`
+
+Request validation middleware built on `yup`. Validates `req.body`, `req.params`, and `req.query`.
+
+```js
+const { validator } = require('speedly/kit');
+const yup = require('yup');
+
+app.post(
+  '/posts',
+  validator({
+    body: yup.object({
+      title: yup.string().required(),
+      slug:  yup.string().required(),
+      status: yup.string().oneOf(['draft', 'published', 'hidden']),
+    }),
+  }),
+  handler
+);
+
+// Validate route params
+app.put(
+  '/posts/:id',
+  validator({
+    params: yup.object({ id: yup.string().required() }),
+    body:   yup.object({ title: yup.string() }),
+  }),
+  handler
+);
+```
+
+On validation failure, calls `next({ status: 405, message: '...' })`.
+
+---
+
+### `speedly/modules` — built-in routers
+
+```js
+const { translation } = require('speedly/modules');
+
+app.use('/api/translation', translation);
+```
+
+Includes a `translation` router with:
+- `GET /` — list translations (supports `?search=`, `?page=`, `?limit=`)
+- `POST /` — create a translation
+- `PUT /:id` — update a translation (requires admin auth)
+
+---
+
+### `speedly/document` — Swagger UI
+
+Scans your module routers and mounts a Swagger UI at `/docs`.
+
+```js
+const document = require('speedly/document');
+const path = require('path');
+
+document(app, path.join(process.cwd(), 'src/modules'));
+// Visit http://localhost:3000/docs
+```
+
+Automatically detects routes, HTTP methods, `yup` validation schemas, and auth middlewares to generate OpenAPI documentation.
+
+---
+
+### `speedly/util` — utilities
+
+```js
+const { translator } = require('speedly/util');
+
+const result = await translator('Hello', 'fa');
+console.log(result); // translated text
+```
+
+`translator(text, lang)` — translates text to the target language, caching results in the `translation` model.
+
+---
+
+### `speedly/model` — Mongoose models
+
+```js
+const { translation } = require('speedly/model');
+
+const docs = await translation.find({ lang: 'fa' });
+```
+
+Includes the `translation` model with fields: `text`, `lang`, `translatedText`, and timestamps.
+
+---
+
+## Examples
+
+### Blog API
+
+A full blog REST API with auth-protected write routes and public read routes.
+
+**`src/modules/blog/blog.validator.js`**
+
+```js
+const { validator } = require('speedly/kit');
+const yup = require('yup');
+
+const paramId = yup.object({
+  id: yup.string().required('id is required'),
+});
+
+const schema = yup.object({
+  title:        yup.string().required(),
+  slug:         yup.string().required().matches(/^[\d\w-]+$/i, 'slug can only contain letters, numbers and dashes'),
+  subTitle:     yup.string(),
+  content:      yup.string(),
+  status:       yup.string().oneOf(['draft', 'published', 'hidden']),
+});
+
+exports.post   = { body: schema };
+exports.put    = { params: paramId, body: schema };
+exports.delete = { params: paramId };
+```
+
+**`src/modules/blog/blog.routes.js`**
+
+```js
+const express = require('express');
+const { auth, db, validator } = require('speedly/kit');
+const v = require('./blog.validator');
+
+const router = express.Router();
+
+// Public: list all posts with author and thumbnail populated
+router.get('/',
+  db('blog').find()
+    .populate([{ path: 'author_id', select: '-password' }, 'thumbnail_id'])
+);
+
+// Public: get single post by slug and increment view count
+router.get('/:slug',
+  db('blog').findOneAndUpdate(
+    req => ({ slug: req.params.slug }, { $inc: { views: 1 } })
+  ).populate([{ path: 'author_id', select: '-password' }, 'thumbnail_id'])
+);
+
+// Admin only: create / update / delete
+router.post('/',   auth.admin(), validator(v.post),   db('blog').create(req => ({ author_id: req.user._id })));
+router.put('/:id', auth.admin(), validator(v.put),    db('blog').findByIdAndUpdate());
+router.delete('/:id', auth.admin(), validator(v.delete), db('blog').findByIdAndDelete());
+
+module.exports = router;
+```
+
+### User & Auth Routes
+
+Registration, login, and profile routes with OTP flow.
+
+**`src/modules/user/user.routes.js`**
+
+```js
+const express = require('express');
+const { auth, db, validator } = require('speedly/kit');
+const yup = require('yup');
+
+const router = express.Router();
+
+const phoneSchema = yup.object({
+  // Iranian mobile format: 11 digits starting with 09 — adjust regex for your region
+  phone: yup.string().required().matches(/^09\d{9}$/, 'Enter an 11-digit phone number starting with 09'),
+});
+
+// Check phone number and send OTP
+router.post('/check-phone',
+  validator({ body: phoneSchema }),
+  myUserController.checkPhone   // your custom controller
+);
+
+// Register / login with OTP
+router.post('/register',
+  validator({ body: phoneSchema }),
+  myUserController.register
+);
+
+// Get current user profile
+router.get('/me',
+  auth.user(),
+  db('user').findOne(req => ({ _id: req.user._id }))
+    .populate('role_id')
+    .select('-password')
+);
+
+// Admin: list all users
+router.get('/',
+  auth.admin({ permission: 'OWNER' }),
+  db('user').find()
+);
+
+// Admin: create / update / delete user
+router.post('/',      auth.admin(), db('user').create());
+router.put('/:id',    auth.admin(), db('user').findByIdAndUpdate());
+router.delete('/:id', auth.admin(), db('user').findByIdAndDelete());
+
+module.exports = router;
+```
+
+### Role Management
+
+CRUD routes for roles, restricted to users with the `OWNER` permission.
+
+**`src/modules/role/role.routes.js`**
+
+```js
+const express = require('express');
+const { auth, db, validator } = require('speedly/kit');
+const yup = require('yup');
+
+const router = express.Router();
+
+const schema = yup.object({
+  title:  yup.string().required(),
+  access: yup.string().required().oneOf(['OWNER', 'ADMIN', 'EXPERT']),
+});
+
+router.get('/',    auth.admin({ permission: 'OWNER' }), db('role').find());
+router.post('/',   auth.admin({ permission: 'OWNER' }), validator({ body: schema }), db('role').create());
+router.put('/:id', auth.admin({ permission: 'OWNER' }), validator({ body: schema }), db('role').findByIdAndUpdate());
+router.delete('/:id', auth.admin({ permission: 'OWNER' }), db('role').findByIdAndDelete());
+
+module.exports = router;
+```
+
+### File Upload
+
+```js
+const express = require('express');
+const { auth, uploader } = require('speedly/kit');
+
+const router = express.Router();
+
+// Single image upload (saves file info to the media collection)
+router.post('/image',
+  auth.user(),
+  uploader('/images', { saveInDb: true, limit: 5 /* max file size in MB */, format: /image\/(jpeg|png|webp)/ }).single('photo'),
+  (req, res) => res.json({ url: req.body.photo })
+);
+
+// Multiple file upload
+router.post('/gallery',
+  auth.user(),
+  uploader('/images').array('photos', 10),
+  (req, res) => res.json({ urls: req.body.photos })
+);
+
+module.exports = router;
+```
+
+### Putting It All Together
+
+**`src/app.js`**
+
+```js
+const speedly = require('speedly');
+const mongoose = require('mongoose');
+const { translation } = require('speedly/modules');
+
+const blogRoutes = require('./modules/blog/blog.routes');
+const userRoutes = require('./modules/user/user.routes');
+const roleRoutes = require('./modules/role/role.routes');
+
+const app = speedly();
+
+mongoose.connect(process.env.MONGO_URI || 'mongodb://localhost:27017/myapp');
+
+// Built-in translation module
+app.use('/api/translation', translation);
+
+// Application routes
+app.use('/api/blogs', blogRoutes);
+app.use('/api/users', userRoutes);
+app.use('/api/roles', roleRoutes);
+
+app.listen(3000, () => {
+  console.log('Running on http://localhost:3000');
+  console.log('API docs:   http://localhost:3000/docs');
+});
+```
+
+---
+
+## License
+
+MIT

package/dist/cjs/config/init.js

@@ -47,8 +47,8 @@ function speedly(config = {}) {
         app.use("/static", express_1.default.static("public"));
     if (finalConfig.homeHandler) {
         app.get("/", (req, res) => {
-            res.send(`<h1>Welcome to ${require(path_1.default.join(process.cwd(), "package.json")).name} App</h1>
-      <p>Your app is running successfully.</p>
+            res.send(`<h1>Welcome to ${require(path_1.default.join(process.cwd(), "package.json")).name} App</h1>
+      <p>Your app is running successfully.</p>
      ${finalConfig.documentation
                 ? '<p>Visit <a href="/docs">/docs</a> for API documentation.</p>'
                 : ""}`);