{"id":19118500,"url":"https://github.com/dolphjs/core","last_synced_at":"2026-04-11T14:06:05.408Z","repository":{"id":164997082,"uuid":"621586392","full_name":"dolphjs/core","owner":"dolphjs","description":"The core engine for the dolphjs framework","archived":false,"fork":false,"pushed_at":"2023-11-15T22:09:21.000Z","size":342,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-01T14:07:01.828Z","etag":null,"topics":["dolphjs","expressjs","nodejs","software-development"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dolphjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-03-31T01:02:27.000Z","updated_at":"2024-09-25T19:03:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"c461d98e-f462-43a7-bc15-21455b90fecb","html_url":"https://github.com/dolphjs/core","commit_stats":{"total_commits":85,"total_committers":3,"mean_commits":"28.333333333333332","dds":"0.11764705882352944","last_synced_commit":"de55b44346704b021b59371f41f9087c8085352d"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dolphjs/core","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolphjs%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolphjs%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolphjs%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolphjs%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dolphjs","download_url":"https://codeload.github.com/dolphjs/core/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dolphjs%2Fcore/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266645149,"owners_count":23961658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dolphjs","expressjs","nodejs","software-development"],"created_at":"2024-11-09T05:06:38.460Z","updated_at":"2025-12-30T22:06:51.159Z","avatar_url":"https://github.com/dolphjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"looking for the dolphjs framework? [https://github.com/dolphjs/dolph]\n# DolphJs\n\nDolphJs is an express.js library for making software development easier. It takes care of the tiring services and functions developers need to go setup for every project.\n\nDolphJs makes use of an appoach that set's up your nodejs applicaion environment to the very best. It employs a robust and flexible codebase system fused together wit the best error handling middlewares and out of the box utilities like the `catchAsync`.\n\n# Sponsors\n\n![dolph](https://raw.githubusercontent.com/dolphjs/core/main/assets/questgig.jpeg)\n\n## Prerequisites\n\n1.Git 2. Node: any 16.x version starting with v16.0.0 or greater 3. Package Manager [Yarn, Npm or Pnpm](recommended`yarn`)(\u003chttps://yarnpkg.com/lang/en/docs/install/\u003e) 4. A fork of the repo (for any contributions)\n\n## Installation\n\nTo install the package, run:\n\n`npm install @dolphjs/core`\n\nor `npm install @dolphjs/cli -g` to make use of the CLI tool (recommended). [https://github.com/dolphjs/cli]\nand run with `dolph create-app 'app-name'`\n\n## Usage\n\nTo use the package, you'll need to require it in your project and then set up your routes.\n\nHere's an example of how you can use it:\n\n```javascript\n    const Dolph, { catchAsync, AppRes httpStatus, Router } = require('@dolphjs/core');\n\n    class TestController {\n     constructor() {}\n\n     getMsg = catchAsync(async (req, res, next) =\u003e {\n      res.send('welcome to this endpoint');\n     });\n     sendMsg = catchAsync(async (req, res, next) =\u003e {\n      const { body } = req;\n      if (!body.name)\n       return next(\n        new AppRes(\n         httpStatus.BAD_REQUEST,\n         'error, provide name in json'\n        )\n       );\n\n      res.status(httpStatus.OK).json(body);\n     });\n    }\n\n    class TestRoute {\n     path = '/test';\n     router = Router();\n     controller = new TestController();\n     constructor() {\n      this.initializeRoutes();\n     }\n     initializeRoutes() {\n      this.router.get(`${this.path}`, this.controller.getMsg);\n      this.router.post(`${this.path}`, this.controller.sendMsg);\n     }\n    }\n\n    const dolph = new Dolph([new TestRoute()], '1919', \"development\", { url: null }, []);\n\n    dolph.listen();\n```\n\nor\n\n```javascript\nconst { Router } = require('@dolphjs/core');\nconst router = Router();\n\nrouter.get('/', (req, res) =\u003e {\n  res.send('Heyoooo!!');\n});\n\nconst routes = [{ path: '/api/v1', router }];\n\nconst dolph = new Dolph(routes, '1919', 'development', null, []);\ndolph.listen();\n```\n\nThe `Dolph` class takes 5 arguments when instantiated: `routes`, `port` ,`node_env`, `mongodb connection params` and `middleware`\n\n- `routes` is an array of the applications routes\n- `port` is the port you want your server to run on\n- `node_env` is your node environment which is set to \"development\" by default when you run `node run dev` . This env can be imported thus:\n\n```javascript\nrequire('dotenv').config({});\nconst nodeEnv = process.env.NODE_ENV;\n```\n\n- `mongodb connection params` is only used if your making use of a mongodb database. It is an object with two fields: `url` and `options` which are the mongodb url and mongodb options respectively. If your making use of another databse or don't want to connect it through mongodb, you can connect it outside the function and also set the `url` param to `false`:\n\n```javascript\nconst mongoConfig = {\n  url: 'mongodb://127.0.0.1:27017/dolphjs',\n  options: {\n    useNewUrlParser: true,\n    useUnifiedTopology: true,\n    autoIndex: true,\n    dbName: 'dolphjs',\n  },\n};\nnew Dolph(routes, '1313', 'development', { url: mongoConfig.url, options: mongoConfig.options }, []);\n```\n\nor\n\n```javascript\nconst mongoConfig = {\n  url: 'mongodb://127.0.0.1:27017/dolphjs',\n  options: {\n    useNewUrlParser: true,\n    useUnifiedTopology: true,\n    autoIndex: true,\n    dbName: 'dolphjs',\n  },\n};\nnew Dolph(routes, '1313', 'development', { url: null }, []);\nmongoose.connect(mongoConfig.url, mongoConfig.options).then().catch();\n```\n\n- `middlewares` is an array of middlewares you want to pass to the `express.app` function embedded inside of dolphjs' engine.\n\nHere's an example:\n\n```javascript\nconst cors = require('cors');\nnew Dolph(routes, '1313', 'development', { url: null }, [cors({ origin: '*' })]);\n```\n\n## CatchAsync\n\nThe `catchAsync` function is a utility function that wraps your route handler functions and catches any errors that may occur inside them. This is useful for handling errors in an async route handler without having to use try-catch blocks.\n\nHere's an example of how you can use it:\n\n```javascript\nconst { catchAsync } = require('@dolphjs/core');\nconst routeHandler = catchAsync(async (req, res, next) =\u003e {\n  // your route code here\n});\nmodule.exports = routerHandler;\n```\n\n## AppRes\n\nThe `AppRes` class is a custom error class that you can use to return custom error responses to the client. It takes two arguments: an HTTP status code and a message.\n\nHere's an example of how you can use it:\n\n```javascript\nif (!body.name) return next(new Dolph.AppRes(httpStatus.BAD_REQUEST, 'error, provide name in json'));\n```\n\n## HttpStatus\n\nThe `httpStatus` object is an object containing commonly used HTTP status codes as properties. You can use this to set the status code of your custom error responses.\nIt is just an export of the original http-status package, here [https://github.com/adaltas/node-http-status]\n\nHere's an example of how you can use it:\n\n```javascript\nconst { AppRes, httpStatus } = require('@dolphjs/core');\nnew AppRes(httpStatus.BAD_REQUEST, 'error message');\n```\n\n## MediaParser\n\nThe `mediaParser` function uses the `multer` package under the hood to parse media files. Thus freeing you from the stress of setting up the package.\n\nHere's an example of how you can use it:\n\n```javascript\nconst { Router, mediaParser } = require('@dolphjs/core');\nconst TestController = require('@/controllers/test.controller');\n\nclass TestRoute {\n  path = '/test';\n  router = Router();\n  controller = new TestController();\n  constructor() {\n    this.initializeRoutes();\n  }\n  initializeRoutes() {\n    this.router.get(`${this.path}`, this.controller.getMsg);\n    this.router.post(\n      `${this.path}`,\n      mediaParser({ type: 'single', storage: {}, fieldname: 'upload' }),\n      this.controller.sendMsg\n    );\n  }\n}\n```\n\nalternatively,\n\n```javascript\nconst { Router, mediaParser } = require('@dolphjs/core');\nconst TestController = require('@/controllers/test.controller');\n\nconst router = Router();\n\nrouter.get(`${this.path}`, new TestController().getMsg);\nrouter.post(`${this.path}`, mediaParser({ type: 'single', storage: {}, fieldname: 'upload' }), new TestController().sendMsg);\n\nconst routes = [{ path: '/', router }];\n```\n\nIt accepts five arguments: `allowedExtensions` `type`, `storage`, `fieldname`, `limit`\n\n- the `allowedExtensions` param takes an array of file extensions the application should allow. If left empty as in the example above, it uses the default which includes:\n\n```javascript\n[\n  '.jpeg',\n  '.png',\n  '.jpg',\n  '.xlsx',\n  '.mp3',\n  '.mp4',\n  '.doc',\n  '.docx',\n  '.pdf',\n  '.txt',\n  '.webm',\n  '.wmv',\n  '.mpeg',\n  '.mkv',\n  '.mov',\n  '.flv',\n  '.html',\n  '.xml',\n  '.xhtml',\n  '.avi',\n  '.wav',\n  '.bmi',\n];\n```\n\n- the current version of dolphjs supports two types : `single` \u0026\u0026 `array`\n\n- the `single` type is used for uploading a single media file\n- the `array` type is used to upload an array of files with a common fieldname\n\n- the storage parameter defaults to an empty object but takes the same fields you would pass to the `diskStorage` function in multer [https://github.com/expressjs/multer] which means files wouldn't be stored in the filesystem.\n  Leaving it empty is ideal when you want to get the file path and store in a cloud service like `AWS` or `Cloudinary`.\n\n- the fieldname parameter specifies the name that would be used to identify the file(s) from the frontend or API tetsing tool.\n\n- the limit parameter is only used when the `type` paramter is set to `array`. This sets the max amount of files it's allowed to parse.\n\n## Pick\n\nThe `pick` function allows for getting fields and values and setting to an object:\n\n```javascript\nconst filter = pick(req.query, ['limit', 'page']);\n// console.log(filter)\n// filter = {limit: 20, page: 1}\n```\n\nthe above code takes the limit and page properties of `req.query` express offers and adds them to a new object `filter`.\n\n## Usage With Websockets\n\nIncase you wonder how you'll attach a websocket server to the dolph engine then this would be of help:\nusing socket.io -\n\n```javascript\nconst io = require('socket.io');\n\nconst dolph = new Dolph(routes, '1313', 'development', { url: mongoConfig.url, options: mongoConfig.options }, middlewares);\nconst server = dolph.listen();\n\nconst socket = io(server, {\n  cors: {\n    origin: '*',\n    credentials: true,\n  },\n});\n\nglobal.onlineUsers = new Map();\n\nsocket.on('connection', (socket) =\u003e {\n  socket.on('add-user', (userId) =\u003e {\n    onlineUsers.set(userId, socket.id);\n\n    if (onlineUsers.get(userId)) {\n      socket.emit('active', userId);\n    }\n  });\n});\n```\n\n## Note\n\nDolphjs makes use of the following middleware packages so you don't need to install them again:\n\n- helmet\n- httpStatus\n- express\n\nIf you need a better guide on how to setup a dolphjs application it's best you view an example application built with dolphjs [https://github.com/dolphjs/example] or better still, use the CLI application which sets up your dolphjs application just how you want it.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details\n\n## Contributing\n\n### Create a branch\n\n1. `git checkout main` from any folder in your local `dolphjs` repository\n2. `git pull origin main` to ensure you have the latest main code\n3. `git checkout -b the-name-of-your-branch` (replacing `the-name-of-your-branch` with a suitable name) to create a branch\n\n### Make the change\n\n1. Save the files and test\n2. The application should be able to receive and send requests and response respectfully\n3. Run `yarn lint`. (This will run Prettier and ESLint.)\n\n### Push it\n\n1. `git add -A \u0026\u0026 git commit -m \"Your message\"` (replacing `Your message` with a commit message, such as `Fix Media processing error`) to stage and commit your changes\n2. `git push your-fork-name the-name-of-your-branch`\n3. Go to the [dolphjs/core repo](https://github.com/dolphjs/core) and you should see recently pushed branches.\n4. Follow GitHub's instructions.\n5. If possible, include screenshots of visual changes. A preview build is triggered after your changes are pushed to GitHub.\n\n### Please note that this package is still in it's beta stage and a lot of features would be added in later versions will be released in the future. Stay tuned for updates and new features\n\n### BENCHMARK\n\nDolphJS is very performant, to run benchmarks is very simple:\n\n```shell\n  yarn benchmark\n```\n\nor\n\n```shell\n  npm run benchmark\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdolphjs%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdolphjs%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdolphjs%2Fcore/lists"}