monapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 monapi contributors
+
+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,385 @@
+# monapi
+
+Auto-generate secure, extensible REST APIs for MongoDB collections using configuration only.
+
+Define a schema. Get a full CRUD API. No boilerplate.
+
+## Install
+
+```bash
+npm install monapi
+```
+
+**Peer dependencies:**
+
+```bash
+npm install express mongoose
+```
+
+## Quick Start
+
+```ts
+import express from 'express'
+import mongoose, { Schema } from 'mongoose'
+import { Monapi } from 'monapi'
+
+const app = express()
+app.use(express.json())
+
+mongoose.connect('mongodb://localhost:27017/myapp')
+
+const UserSchema = new Schema({
+  name: { type: String, required: true },
+  email: { type: String, required: true },
+  age: { type: Number },
+  role: { type: String, enum: ['admin', 'user'], default: 'user' },
+})
+
+const monapi = new Monapi({ connection: mongoose.connection })
+
+monapi.resource('users', { schema: UserSchema })
+
+app.use('/api', monapi.router())
+app.listen(3000)
+```
+
+This generates:
+
+```
+GET    /api/users           List users
+GET    /api/users/:id       Get user by id
+POST   /api/users           Create user
+PUT    /api/users/:id       Replace user
+PATCH  /api/users/:id       Partial update user
+DELETE /api/users/:id       Delete user
+```
+
+## Filtering
+
+### Simple equality
+
+```
+GET /api/users?role=admin
+GET /api/users?age=25&active=true
+```
+
+### Operators (double-underscore syntax)
+
+```
+GET /api/users?age__gt=18&age__lt=30
+GET /api/users?role__in=admin,moderator
+GET /api/users?name__like=john
+GET /api/users?email__exists=true
+```
+
+| Operator | MongoDB | Example |
+|----------|---------|---------|
+| `__eq` | `$eq` | `?role__eq=admin` |
+| `__ne` | `$ne` | `?role__ne=banned` |
+| `__gt` | `$gt` | `?age__gt=18` |
+| `__gte` | `$gte` | `?age__gte=18` |
+| `__lt` | `$lt` | `?age__lt=65` |
+| `__lte` | `$lte` | `?age__lte=65` |
+| `__in` | `$in` | `?role__in=admin,user` |
+| `__nin` | `$nin` | `?role__nin=banned` |
+| `__like` | `$regex` (case-insensitive) | `?name__like=john` |
+| `__exists` | `$exists` | `?phone__exists=true` |
+
+### Advanced bracket syntax
+
+```
+GET /api/users?filter[age][gt]=18&filter[age][lt]=30
+```
+
+### Auto type coercion
+
+Query values are automatically coerced:
+- `"25"` becomes `25` (number)
+- `"true"` / `"false"` becomes boolean
+- `"2024-01-15"` becomes a Date object
+
+## Sorting
+
+```
+GET /api/users?sort=name              # ascending
+GET /api/users?sort=-createdAt        # descending
+GET /api/users?sort=role,-createdAt   # multiple fields
+```
+
+## Pagination
+
+```
+GET /api/users?page=2&limit=20
+```
+
+List responses include metadata:
+
+```json
+{
+  "data": [...],
+  "meta": {
+    "page": 2,
+    "limit": 20,
+    "total": 150,
+    "totalPages": 8
+  }
+}
+```
+
+## Field Selection
+
+```
+GET /api/users?fields=name,email
+```
+
+## Query Configuration
+
+Control what's filterable and sortable per collection:
+
+```ts
+monapi.resource('users', {
+  schema: UserSchema,
+  query: {
+    allowedFilters: ['name', 'email', 'age', 'role'],
+    allowedSorts: ['name', 'age', 'createdAt'],
+    defaultSort: '-createdAt',
+    defaultLimit: 20,
+    maxLimit: 100,
+  },
+})
+```
+
+## Lifecycle Hooks
+
+Run custom logic before or after any operation:
+
+```ts
+monapi.resource('users', {
+  schema: UserSchema,
+  hooks: {
+    beforeCreate: async (ctx) => {
+      ctx.data.slug = slugify(ctx.data.name)
+    },
+    afterCreate: async (ctx) => {
+      await sendWelcomeEmail(ctx.result.email)
+    },
+    beforeFind: async (ctx) => {
+      // Inject tenant filter
+      ctx.query.filter.tenantId = ctx.user?.tenantId
+    },
+    beforeDelete: async (ctx) => {
+      // Prevent deletion
+      if (ctx.user?.role !== 'admin') {
+        ctx.preventDefault = true
+        ctx.res.status(403).json({ error: { message: 'Only admins can delete' } })
+      }
+    },
+  },
+})
+```
+
+Available hooks: `beforeFind`, `afterFind`, `beforeCreate`, `afterCreate`, `beforeUpdate`, `afterUpdate`, `beforeDelete`, `afterDelete`.
+
+### Hook Context
+
+Every hook receives a mutable `HookContext`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `collection` | string | Collection name |
+| `operation` | string | `'find'`, `'create'`, `'update'`, `'patch'`, `'delete'` |
+| `user` | User | Authenticated user (from `req.user`) |
+| `query` | MongoQuery | MongoDB query object (find operations) |
+| `data` | any | Request body (create/update operations) |
+| `result` | any | Database result (after hooks) |
+| `id` | string | Document ID (get/update/delete) |
+| `req` | Request | Express request |
+| `res` | Response | Express response |
+| `meta` | object | Custom metadata |
+| `preventDefault` | boolean | Set `true` to skip the default operation |
+
+## Authentication & Authorization
+
+### Auth middleware
+
+Provide your own auth middleware to populate `req.user`:
+
+```ts
+const monapi = new Monapi({
+  connection: mongoose.connection,
+  auth: {
+    middleware: (req, res, next) => {
+      const token = req.headers.authorization?.split(' ')[1]
+      req.user = verifyToken(token)
+      next()
+    },
+  },
+})
+```
+
+### Role-based permissions
+
+```ts
+monapi.resource('posts', {
+  schema: PostSchema,
+  permissions: {
+    list: ['admin', 'user'],         // any of these roles
+    get: ['admin', 'user'],
+    create: ['admin', 'editor'],
+    update: ['admin', 'editor'],
+    delete: ['admin'],
+  },
+})
+```
+
+### Custom permission functions
+
+```ts
+monapi.resource('posts', {
+  schema: PostSchema,
+  permissions: {
+    update: async (ctx) => {
+      // Only allow authors to edit their own posts
+      const post = await PostModel.findById(ctx.id)
+      return post?.author.toString() === ctx.user.id
+    },
+    delete: (ctx) => ctx.user.roles?.includes('admin'),
+  },
+})
+```
+
+## Custom Middleware
+
+Inject middleware at different levels:
+
+```ts
+monapi.resource('users', {
+  schema: UserSchema,
+  middleware: {
+    all: [rateLimiter],                    // all operations
+    create: [validateCaptcha],             // only create
+    delete: [requireSuperAdmin],           // only delete
+  },
+})
+```
+
+## Custom Handlers
+
+Override any default handler:
+
+```ts
+monapi.resource('users', {
+  schema: UserSchema,
+  handlers: {
+    list: async (req, res, next) => {
+      // Completely custom list implementation
+      const users = await UserModel.aggregate([...])
+      res.json({ data: users, meta: { page: 1, limit: 10, total: users.length } })
+    },
+  },
+})
+```
+
+## Global Defaults
+
+```ts
+const monapi = new Monapi({
+  connection: mongoose.connection,
+  defaults: {
+    pagination: {
+      limit: 20,         // default page size
+      maxLimit: 100,      // maximum allowed page size
+    },
+    security: {
+      maxRegexLength: 50,     // max length for __like patterns
+    },
+  },
+})
+```
+
+## Response Formats
+
+### List response
+
+```json
+{
+  "data": [
+    { "_id": "...", "name": "John", "email": "john@test.com" }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 42,
+    "totalPages": 3
+  }
+}
+```
+
+### Single document response
+
+```json
+{
+  "data": {
+    "_id": "...",
+    "name": "John",
+    "email": "john@test.com"
+  }
+}
+```
+
+### Error response
+
+```json
+{
+  "error": {
+    "code": "NOT_FOUND",
+    "message": "users with id '123' not found"
+  }
+}
+```
+
+## Security
+
+monapi enforces safe defaults:
+
+- Filters only work on schema-defined fields (when `allowedFilters` is set or adapter is provided)
+- All filter operators are whitelisted (no raw MongoDB operators)
+- `$` prefixed field names are blocked everywhere (filters, sort, projection, patch body)
+- Regex patterns have length limits
+- Maximum filter count enforced
+- Pagination limits enforced (configurable `maxLimit`)
+- Patch bodies reject `$` operators (no `$set`, `$unset` injection)
+- Production error responses hide internal details
+
+## API Reference
+
+### `new Monapi(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `connection` | `mongoose.Connection` | *required* | MongoDB connection |
+| `basePath` | `string` | `''` | Base path prefix for routes |
+| `auth` | `AuthConfig` | - | Auth configuration |
+| `defaults` | `DefaultConfig` | - | Global defaults |
+| `logger` | `Logger` | console logger | Custom logger |
+
+### `monapi.resource(name, config)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `schema` | `Schema \| Model` | Mongoose schema or model |
+| `model` | `Model` | Explicit Mongoose model (optional) |
+| `query` | `QueryConfig` | Filter/sort/pagination config |
+| `hooks` | `LifecycleHooks` | Before/after hooks |
+| `permissions` | `PermissionConfig` | Role-based or custom permissions |
+| `middleware` | `MiddlewareConfig` | Custom middleware per operation |
+| `handlers` | `CRUDHandlers` | Override default handlers |
+| `adapter` | `SchemaAdapter` | Custom schema adapter |
+
+### `monapi.router()`
+
+Returns an Express `Router` with all registered collection routes.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,315 @@
+import { Request, Response, NextFunction, RequestHandler, Router } from 'express';
+import { FilterQuery, SortOrder, Model, Schema, Connection } from 'mongoose';
+
+type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'like' | 'exists';
+interface FilterCondition {
+    operator: FilterOperator;
+    value: any;
+}
+interface ParsedFilters {
+    [field: string]: FilterCondition;
+}
+interface QueryOptions {
+    page?: number;
+    limit?: number;
+    sort?: string | string[];
+    fields?: string | string[];
+    [key: string]: any;
+}
+interface MongoQuery {
+    filter: FilterQuery<any>;
+    sort?: {
+        [key: string]: SortOrder;
+    };
+    skip?: number;
+    limit?: number;
+    projection?: {
+        [key: string]: 0 | 1;
+    };
+}
+interface PaginationMeta {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages?: number;
+}
+interface QueryConfig {
+    allowedFilters?: string[];
+    allowedSorts?: string[];
+    defaultSort?: string;
+    defaultLimit?: number;
+    maxLimit?: number;
+}
+declare enum FieldType {
+    String = "string",
+    Number = "number",
+    Boolean = "boolean",
+    Date = "date",
+    ObjectId = "objectid",
+    Array = "array",
+    Object = "object",
+    Mixed = "mixed"
+}
+
+type CRUDOperation = 'find' | 'create' | 'update' | 'patch' | 'delete';
+interface User {
+    id: string;
+    roles?: string[];
+    [key: string]: any;
+}
+interface HookContext {
+    collection: string;
+    operation: CRUDOperation;
+    user?: User;
+    query?: MongoQuery;
+    data?: any;
+    result?: any;
+    id?: string;
+    req: Request;
+    res: Response;
+    meta?: Record<string, any>;
+    preventDefault?: boolean;
+}
+type HookFunction = (ctx: HookContext) => Promise<void> | void;
+interface LifecycleHooks {
+    beforeFind?: HookFunction;
+    afterFind?: HookFunction;
+    beforeCreate?: HookFunction;
+    afterCreate?: HookFunction;
+    beforeUpdate?: HookFunction;
+    afterUpdate?: HookFunction;
+    beforeDelete?: HookFunction;
+    afterDelete?: HookFunction;
+}
+interface HookEntry {
+    collection: string;
+    operation: keyof LifecycleHooks;
+    handler: HookFunction;
+    priority?: number;
+}
+
+interface PermissionContext {
+    user: User;
+    collection: string;
+    operation: CRUDOperation;
+    data?: any;
+    id?: string;
+    req: Request;
+}
+type PermissionFunction = (ctx: PermissionContext) => boolean | Promise<boolean>;
+type Permission = string[] | PermissionFunction;
+interface PermissionConfig {
+    list?: Permission;
+    get?: Permission;
+    create?: Permission;
+    update?: Permission;
+    patch?: Permission;
+    delete?: Permission;
+}
+interface FieldPermission {
+    read?: string[];
+    write?: string[];
+}
+interface FieldPermissions {
+    [fieldName: string]: FieldPermission;
+}
+type AuthMiddleware = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+interface AuthConfig {
+    middleware?: AuthMiddleware;
+    jwtSecret?: string;
+    jwtOptions?: {
+        algorithm?: string;
+        expiresIn?: string;
+    };
+    sessionSecret?: string;
+}
+
+interface ValidationResult {
+    valid: boolean;
+    errors?: ValidationError$1[];
+    data?: any;
+}
+interface ValidationError$1 {
+    field: string;
+    message: string;
+    code?: string;
+}
+interface FieldMetadata {
+    name: string;
+    type: FieldType;
+    required?: boolean;
+    default?: any;
+    enum?: any[];
+}
+interface SchemaAdapter {
+    getFields(): string[];
+    getFieldType(field: string): FieldType;
+    getFieldMetadata(field: string): FieldMetadata | undefined;
+    getAllFieldsMetadata(): FieldMetadata[];
+    validate(data: unknown): Promise<ValidationResult> | ValidationResult;
+    getMongooseModel?(): Model<any> | undefined;
+    getMongooseSchema?(): Schema | undefined;
+}
+declare enum SchemaType {
+    Mongoose = "mongoose",
+    Typegoose = "typegoose",
+    Zod = "zod",
+    Joi = "joi",
+    Yup = "yup",
+    Unknown = "unknown"
+}
+interface SchemaOptions {
+    strict?: boolean;
+    timestamps?: boolean;
+    validateBeforeSave?: boolean;
+}
+
+type Handler = (req: Request, res: Response, next: NextFunction) => void | Promise<void>;
+interface CRUDHandlers {
+    list: Handler;
+    get: Handler;
+    create: Handler;
+    update: Handler;
+    patch: Handler;
+    delete: Handler;
+}
+interface MiddlewareConfig {
+    all?: RequestHandler[];
+    list?: RequestHandler[];
+    get?: RequestHandler[];
+    create?: RequestHandler[];
+    update?: RequestHandler[];
+    patch?: RequestHandler[];
+    delete?: RequestHandler[];
+}
+interface CollectionConfig {
+    schema: Schema | Model<any> | any;
+    validator?: any;
+    model?: Model<any>;
+    handlers?: Partial<CRUDHandlers>;
+    hooks?: Partial<LifecycleHooks>;
+    middleware?: MiddlewareConfig;
+    permissions?: PermissionConfig;
+    fields?: FieldPermissions;
+    query?: QueryConfig;
+    adapter?: SchemaAdapter;
+}
+interface DefaultConfig {
+    pagination?: {
+        limit?: number;
+        maxLimit?: number;
+    };
+    security?: {
+        maxRegexLength?: number;
+        maxRegexComplexity?: number;
+        maxQueryCost?: number;
+    };
+    query?: QueryConfig;
+}
+interface MonapiConfig {
+    connection: Connection;
+    basePath?: string;
+    framework?: 'express' | 'fastify';
+    defaults?: DefaultConfig;
+    auth?: AuthConfig;
+    logger?: Logger;
+}
+interface Logger {
+    info(message: string, meta?: any): void;
+    warn(message: string, meta?: any): void;
+    error(message: string, meta?: any): void;
+    debug(message: string, meta?: any): void;
+}
+interface ListResponse<T = any> {
+    data: T[];
+    meta: {
+        page: number;
+        limit: number;
+        total: number;
+    };
+}
+interface SingleResponse<T = any> {
+    data: T;
+}
+interface ErrorResponse {
+    error: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+}
+
+declare class Monapi {
+    private config;
+    private logger;
+    private collections;
+    private authMiddleware?;
+    constructor(config: MonapiConfig);
+    resource(name: string, collectionConfig: CollectionConfig): this;
+    router(): Router;
+    getModel(name: string): Model<any> | undefined;
+    getAdapter(name: string): SchemaAdapter | undefined;
+    private resolveModel;
+}
+
+declare class MongooseAdapter implements SchemaAdapter {
+    private schema;
+    private model?;
+    constructor(schemaOrModel: Schema | Model<any>);
+    private isModel;
+    getFields(): string[];
+    getFieldType(field: string): FieldType;
+    getFieldMetadata(field: string): FieldMetadata | undefined;
+    getAllFieldsMetadata(): FieldMetadata[];
+    validate(data: unknown): Promise<ValidationResult>;
+    private basicValidation;
+    getMongooseModel(): Model<any> | undefined;
+    getMongooseSchema(): Schema;
+}
+
+declare function detectSchemaType(schema: any): SchemaType;
+declare function createSchemaAdapter(schema: Schema | Model<any> | any): SchemaAdapter;
+
+declare class MonapiError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    readonly details?: any;
+    constructor(message: string, statusCode: number, code: string, details?: any);
+}
+declare class NotFoundError extends MonapiError {
+    constructor(resource: string, id?: string);
+}
+declare class ValidationError extends MonapiError {
+    constructor(message: string, details?: any);
+}
+declare class ForbiddenError extends MonapiError {
+    constructor(message?: string);
+}
+declare class UnauthorizedError extends MonapiError {
+    constructor(message?: string);
+}
+declare class BadRequestError extends MonapiError {
+    constructor(message: string, details?: any);
+}
+
+interface FilterParserOptions {
+    adapter?: SchemaAdapter;
+    queryConfig?: QueryConfig;
+    maxRegexLength?: number;
+    maxFilters?: number;
+}
+declare function parseFilters(query: Record<string, any>, options?: FilterParserOptions): FilterQuery<any>;
+
+interface QueryBuilderOptions {
+    adapter?: SchemaAdapter;
+    queryConfig?: QueryConfig;
+    defaultLimit?: number;
+    maxLimit?: number;
+    maxRegexLength?: number;
+}
+declare function buildQuery(queryParams: Record<string, any>, options?: QueryBuilderOptions): MongoQuery;
+declare function buildPaginationMeta(total: number, page: number, limit: number): PaginationMeta;
+
+declare function createErrorHandler(logger?: Logger): (err: Error, _req: Request, res: Response, _next: NextFunction) => void;
+
+export { type AuthConfig, type AuthMiddleware, BadRequestError, type CRUDHandlers, type CRUDOperation, type CollectionConfig, type DefaultConfig, type ErrorResponse, type FieldMetadata, type FieldPermission, type FieldPermissions, FieldType, type FilterCondition, type FilterOperator, ForbiddenError, type Handler, type HookContext, type HookEntry, type HookFunction, type LifecycleHooks, type ListResponse, type Logger, type MiddlewareConfig, Monapi, type MonapiConfig, MonapiError, type MongoQuery, MongooseAdapter, NotFoundError, type PaginationMeta, type ParsedFilters, type Permission, type PermissionConfig, type PermissionContext, type PermissionFunction, type QueryConfig, type QueryOptions, type SchemaAdapter, type SchemaOptions, SchemaType, type ValidationError$1 as SchemaValidationError, type SingleResponse, UnauthorizedError, type User, ValidationError, type ValidationResult, buildPaginationMeta, buildQuery, createErrorHandler, createSchemaAdapter, detectSchemaType, parseFilters };