@mabdolalizadeh/responser 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Abdolalizadeh
+
+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

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @mabdolalizadeh/responser
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standardized and lightweight HTTP response helper for Express.js APIs.
+
+Supports both **ES Modules (`import`)** and **CommonJS (`require`)**, with full TypeScript declarations included.
+
+---
+
+## 📦 Installation
+
+### Option 1: Install directly from GitHub (No registry or publishing needed!)
+
+You can install directly into any project immediately:
+
+```bash
+npm install github:mabdolalizadeh/responser
+```
+
+Or using shorthand:
+```bash
+npm install mabdolalizadeh/responser
+```
+
+To lock to a specific branch, commit, or tag:
+```bash
+npm install mabdolalizadeh/responser#v1.0.0
+```
+
+### Option 2: Install from NPM or GitHub Packages (If published)
+
+```bash
+npm install @mabdolalizadeh/responser
+```
+
+---
+
+## 🚀 Quick Start
+
+### ES Modules (ESM)
+```javascript
+import express from 'express';
+import { Responser } from '@mabdolalizadeh/responser';
+
+const app = express();
+app.use(express.json());
+
+app.get('/users/:id', (req, res) => {
+    const responser = new Responser(res);
+
+    if (req.params.id !== '1') {
+        return responser.send404({ entity: 'User' });
+    }
+
+    return responser.send200({ body: { id: 1, name: 'Alice' } });
+});
+```
+
+### CommonJS (CJS)
+```javascript
+const express = require('express');
+const { Responser } = require('@mabdolalizadeh/responser');
+// or: const Responser = require('@mabdolalizadeh/responser');
+```
+
+---
+
+## 💡 Usage Patterns
+
+### 1. Instance-based (Recommended)
+
+```javascript
+app.post('/register', (req, res) => {
+    const responser = new Responser(res);
+
+    // Validate required fields
+    const [ok, missing] = Responser.checkMissing(['email', 'password'], req.body);
+    if (!ok) {
+        return responser.send400({ missings: missing });
+    }
+
+    return responser.send201({ body: { message: 'Registered successfully' } });
+});
+```
+
+### 2. Static Methods (No `new` needed)
+
+```javascript
+app.get('/health', (req, res) => {
+    return Responser.send200(res, { body: { status: 'healthy' } });
+});
+```
+
+---
+
+## 📖 API Reference
+
+### Response Format
+
+- **Success (200, 201):** `{ "ok": true, "body": ... }`
+- **No Content (204):** Empty body
+- **Error (400, 401, 403, 404, 500):** `{ "ok": false, "error": "..." }`
+
+### Methods
+
+| Method | Status | Default Error / Response Format | Options |
+|---|---|---|---|
+| `send200({ body })` | `200` | `{ ok: true, body }` | `{ body?: any }` |
+| `send201({ body })` | `201` | `{ ok: true, body }` | `{ body?: any }` |
+| `send204()` | `204` | Empty body | None |
+| `send400({ msg, missings })` | `400` | Auto-formats missing fields or `"Bad request"` | `{ msg?: string, missings?: string[] }` |
+| `send401({ msg })` | `401` | `"You should be authenticated"` | `{ msg?: string }` |
+| `send403({ msg })` | `403` | `"You don't have permission to see this resource"` | `{ msg?: string }` |
+| `send404({ msg, entity })` | `404` | `"<Entity> not found"` or `"Not found"` | `{ msg?: string, entity?: string }` |
+| `send500({ msg, err })` | `500` | `"Internal server error"` (logs `err` to console) | `{ msg?: string, err?: Error }` |
+
+### Field Validation Helper: `Responser.checkMissing`
+
+```javascript
+const [isValid, missingFields] = Responser.checkMissing(
+    ['name', 'email', 'password'],
+    req.body
+);
+
+if (!isValid) {
+    // missingFields is ['password'] if password wasn't provided
+    return responser.send400({ missings: missingFields });
+    // Output: { ok: false, error: "1 field is missing. password" }
+}
+```
+
+---
+
+## 📄 License
+
+MIT © [Mohammad Abdolalizadeh](https://github.com/mabdolalizadeh)

package/index.cjs

@@ -0,0 +1,162 @@
+class Responser {
+    constructor(res) {
+        this.res = res;
+    }
+
+    /**
+     * Check whether required fields are missing.
+     *
+     * @param {Array} base - Required fields.
+     * @param {Array|Object} taken - Provided fields or object.
+     * @returns {[boolean, Array|null]}
+     */
+    static checkMissing(base = [], taken = []) {
+        const takenKeys = new Set(
+            Array.isArray(taken)
+                ? taken
+                : Object.keys(taken ?? {})
+        );
+
+        const missing = base.filter(key => !takenKeys.has(key));
+
+        return missing.length === 0
+            ? [true, null]
+            : [false, missing];
+    }
+
+    /**
+     * Send a JSON response.
+     *
+     * @private
+     */
+    _sendJson(status, payload) {
+        return this.res.status(status).json(payload);
+    }
+
+    /**
+     * Send a successful response.
+     */
+    send200({ body } = {}) {
+        return this._sendJson(200, {
+            ok: true,
+            body
+        });
+    }
+
+    /**
+     * Send a resource-created response.
+     */
+    send201({ body } = {}) {
+        return this._sendJson(201, {
+            ok: true,
+            body
+        });
+    }
+
+    /**
+     * Send an empty successful response.
+     */
+    send204() {
+        return this.res.status(204).send();
+    }
+
+    /**
+     * Send a bad-request response.
+     */
+    send400({ msg, missings, missing } = {}) {
+        const missingFields = missings ?? missing;
+
+        const error = msg ?? (
+            Array.isArray(missingFields) && missingFields.length > 0
+                ? `${missingFields.length} field${missingFields.length > 1 ? 's are' : ' is'} missing. ${missingFields.join(', ')}`
+                : 'Bad request'
+        );
+
+        return this._sendJson(400, {
+            ok: false,
+            error
+        });
+    }
+
+    /**
+     * Send an unauthorized response.
+     */
+    send401({ msg } = {}) {
+        return this._sendJson(401, {
+            ok: false,
+            error: msg ?? 'You should be authenticated'
+        });
+    }
+
+    /**
+     * Send a forbidden response.
+     */
+    send403({ msg } = {}) {
+        return this._sendJson(403, {
+            ok: false,
+            error: msg ?? "You don't have permission to see this resource"
+        });
+    }
+
+    /**
+     * Send a not-found response.
+     */
+    send404({ msg, entity } = {}) {
+        return this._sendJson(404, {
+            ok: false,
+            error: msg ?? `${entity ? `${entity} not` : 'Not'} found`
+        });
+    }
+
+    /**
+     * Send an internal-server-error response.
+     */
+    send500({ msg, err } = {}) {
+        if (err) {
+            console.error(err);
+        }
+
+        return this._sendJson(500, {
+            ok: false,
+            error: msg ?? 'Internal server error'
+        });
+    }
+
+    // Static shortcuts (backward compatible).
+
+    static send200(res, options) {
+        return new Responser(res).send200(options);
+    }
+
+    static send201(res, options) {
+        return new Responser(res).send201(options);
+    }
+
+    static send204(res) {
+        return new Responser(res).send204();
+    }
+
+    static send400(res, options) {
+        return new Responser(res).send400(options);
+    }
+
+    static send401(res, options) {
+        return new Responser(res).send401(options);
+    }
+
+    static send403(res, options) {
+        return new Responser(res).send403(options);
+    }
+
+    static send404(res, options) {
+        return new Responser(res).send404(options);
+    }
+
+    static send500(res, options) {
+        return new Responser(res).send500(options);
+    }
+}
+
+module.exports = Responser;
+module.exports.Responser = Responser;
+module.exports.default = Responser;

package/index.d.ts

@@ -0,0 +1,89 @@
+export interface SendOptions {
+    body?: any;
+}
+
+export interface Send400Options {
+    msg?: string;
+    missings?: string[];
+    missing?: string[];
+}
+
+export interface SendErrorOptions {
+    msg?: string;
+}
+
+export interface Send404Options {
+    msg?: string;
+    entity?: string;
+}
+
+export interface Send500Options {
+    msg?: string;
+    err?: any;
+}
+
+export declare class Responser {
+    res: any;
+    constructor(res: any);
+
+    /**
+     * Check whether required fields are missing.
+     *
+     * @param base Required fields.
+     * @param taken Provided fields array or request body object.
+     * @returns [isValid, missingFieldsOrNull]
+     */
+    static checkMissing(base?: string[], taken?: string[] | Record<string, any> | null): [boolean, string[] | null];
+
+    /**
+     * Send a 200 OK response with `{ ok: true, body }`.
+     */
+    send200(options?: SendOptions): any;
+
+    /**
+     * Send a 201 Created response with `{ ok: true, body }`.
+     */
+    send201(options?: SendOptions): any;
+
+    /**
+     * Send a 204 No Content response.
+     */
+    send204(): any;
+
+    /**
+     * Send a 400 Bad Request response with `{ ok: false, error }`.
+     */
+    send400(options?: Send400Options): any;
+
+    /**
+     * Send a 401 Unauthorized response with `{ ok: false, error }`.
+     */
+    send401(options?: SendErrorOptions): any;
+
+    /**
+     * Send a 403 Forbidden response with `{ ok: false, error }`.
+     */
+    send403(options?: SendErrorOptions): any;
+
+    /**
+     * Send a 404 Not Found response with `{ ok: false, error }`.
+     */
+    send404(options?: Send404Options): any;
+
+    /**
+     * Send a 500 Internal Server Error response with `{ ok: false, error }`.
+     */
+    send500(options?: Send500Options): any;
+
+    // Static helper methods
+    static send200(res: any, options?: SendOptions): any;
+    static send201(res: any, options?: SendOptions): any;
+    static send204(res: any): any;
+    static send400(res: any, options?: Send400Options): any;
+    static send401(res: any, options?: SendErrorOptions): any;
+    static send403(res: any, options?: SendErrorOptions): any;
+    static send404(res: any, options?: Send404Options): any;
+    static send500(res: any, options?: Send500Options): any;
+}
+
+export default Responser;

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@mabdolalizadeh/responser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Standardized JSON response helper for Express.js",
+  "type": "module",
+  "main": "./index.cjs",
+  "module": "./responser.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./responser.js",
+      "require": "./index.cjs"
+    }
+  },
+  "files": [
+    "responser.js",
+    "index.cjs",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mabdolalizadeh/responser.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mabdolalizadeh/responser/issues"
+  },
+  "homepage": "https://github.com/mabdolalizadeh/responser#readme",
+  "keywords": [
+    "express",
+    "response",
+    "json",
+    "http",
+    "api",
+    "rest",
+    "helper",
+    "responser"
+  ],
+  "author": "mabdolalizadeh <m.abdolalizadeh@outlook.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/responser.js

@@ -0,0 +1,162 @@
+
+export default class Responser {
+    constructor(res) {
+        this.res = res;
+    }
+
+    /**
+     * Check whether required fields are missing.
+     *
+     * @param {Array} base - Required fields.
+     * @param {Array|Object} taken - Provided fields or object.
+     * @returns {[boolean, Array|null]}
+     */
+    static checkMissing(base = [], taken = []) {
+        const takenKeys = new Set(
+            Array.isArray(taken)
+                ? taken
+                : Object.keys(taken ?? {})
+        );
+
+        const missing = base.filter(key => !takenKeys.has(key));
+
+        return missing.length === 0
+            ? [true, null]
+            : [false, missing];
+    }
+
+    /**
+     * Send a JSON response.
+     *
+     * @private
+     */
+    _sendJson(status, payload) {
+        return this.res.status(status).json(payload);
+    }
+
+    /**
+     * Send a successful response.
+     */
+    send200({ body } = {}) {
+        return this._sendJson(200, {
+            ok: true,
+            body
+        });
+    }
+
+    /**
+     * Send a resource-created response.
+     */
+    send201({ body } = {}) {
+        return this._sendJson(201, {
+            ok: true,
+            body
+        });
+    }
+
+    /**
+     * Send an empty successful response.
+     */
+    send204() {
+        return this.res.status(204).send();
+    }
+
+    /**
+     * Send a bad-request response.
+     */
+    send400({ msg, missings, missing } = {}) {
+        const missingFields = missings ?? missing;
+
+        const error = msg ?? (
+            Array.isArray(missingFields) && missingFields.length > 0
+                ? `${missingFields.length} field${missingFields.length > 1 ? 's are' : ' is'} missing. ${missingFields.join(', ')}`
+                : 'Bad request'
+        );
+
+        return this._sendJson(400, {
+            ok: false,
+            error
+        });
+    }
+
+    /**
+     * Send an unauthorized response.
+     */
+    send401({ msg } = {}) {
+        return this._sendJson(401, {
+            ok: false,
+            error: msg ?? 'You should be authenticated'
+        });
+    }
+
+    /**
+     * Send a forbidden response.
+     */
+    send403({ msg } = {}) {
+        return this._sendJson(403, {
+            ok: false,
+            error: msg ?? "You don't have permission to see this resource"
+        });
+    }
+
+    /**
+     * Send a not-found response.
+     */
+    send404({ msg, entity } = {}) {
+        return this._sendJson(404, {
+            ok: false,
+            error: msg ?? `${entity ? `${entity} not` : 'Not'} found`
+        });
+    }
+
+    /**
+     * Send an internal-server-error response.
+     */
+    send500({ msg, err } = {}) {
+        if (err) {
+            console.error(err);
+        }
+
+        return this._sendJson(500, {
+            ok: false,
+            error: msg ?? 'Internal server error'
+        });
+    }
+
+    // Static shortcuts (backward compatible).
+
+    static send200(res, options) {
+        return new Responser(res).send200(options);
+    }
+
+    static send201(res, options) {
+        return new Responser(res).send201(options);
+    }
+
+    static send204(res) {
+        return new Responser(res).send204();
+    }
+
+    static send400(res, options) {
+        return new Responser(res).send400(options);
+    }
+
+    static send401(res, options) {
+        return new Responser(res).send401(options);
+    }
+
+    static send403(res, options) {
+        return new Responser(res).send403(options);
+    }
+
+    static send404(res, options) {
+        return new Responser(res).send404(options);
+    }
+
+    static send500(res, options) {
+        return new Responser(res).send500(options);
+    }
+}
+
+export { Responser };
+