{"id":20525803,"url":"https://github.com/knovator/masters-node","last_synced_at":"2025-07-06T17:07:09.461Z","repository":{"id":40626389,"uuid":"506969072","full_name":"knovator/masters-node","owner":"knovator","description":" NodeJS package that integrate API for master/submaster in nodejs application","archived":false,"fork":false,"pushed_at":"2024-08-14T09:28:08.000Z","size":450,"stargazers_count":8,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-14T11:52:05.986Z","etag":null,"topics":["expressjs","masters","mongodb","nodejs"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@knovator/masters-node","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/knovator.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-24T10:26:41.000Z","updated_at":"2024-08-07T08:47:40.000Z","dependencies_parsed_at":"2024-08-14T10:46:49.689Z","dependency_job_id":null,"html_url":"https://github.com/knovator/masters-node","commit_stats":{"total_commits":59,"total_committers":4,"mean_commits":14.75,"dds":0.2033898305084746,"last_synced_commit":"b074f1afcb9f51a660f3efa482bd5dd4b3f3f4ac"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/knovator/masters-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knovator%2Fmasters-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knovator%2Fmasters-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knovator%2Fmasters-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knovator%2Fmasters-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/knovator","download_url":"https://codeload.github.com/knovator/masters-node/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/knovator%2Fmasters-node/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259910672,"owners_count":22930703,"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","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":["expressjs","masters","mongodb","nodejs"],"created_at":"2024-11-15T23:09:43.588Z","updated_at":"2025-07-06T17:07:09.441Z","avatar_url":"https://github.com/knovator.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv id=\"top\"\u003e\u003c/div\u003e\n\n\u003c!-- PROJECT LOGO --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n  \u003c!-- \u003ca href=\"https://github.com/knovator/masters-node\"\u003e\n    \u003cimg src=\"images/logo.png\" alt=\"Logo\" width=\"80\" height=\"80\"\u003e\n  \u003c/a\u003e --\u003e\n\n\u003ch3 align=\"center\"\u003e@knovator/masters-node\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    NodeJS package that integrate API for @knovator/masters-node in nodejs application\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/knovator/masters-node\"\u003e\u003cstrong\u003eExplore the docs »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://github.com/knovator/masters-node\"\u003eView Demo\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/knovator/masters-node/issues\"\u003eReport Bug\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/knovator/masters-node/issues\"\u003eRequest Feature\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\n      \u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#built-with\"\u003eBuilt With\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#parameter-explanations\"\u003eParameter Explanations\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003ca href=\"#routes-infomration\"\u003eRoutes Information\u003c/a\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003ca href=\"#response-codes\"\u003eResponse Codes\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#custom-validation-messages\"\u003eValidation Messages\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#http-status-codes\"\u003eHTTP Status Codes\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#routes\"\u003eRoutes\u003c/a\u003e\u003c/li\u003e\n        \u003cli\u003e\u003ca href=\"#i18n-code-for-messages\"\u003ei18n Message Codes\u003c/a\u003e\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usecases\"\u003eUsecases\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\n\n`@knovator/masters-node` is built with intent to faster development cycle by providing plug \u0026 play facility for masters/submasters, that is used almost on every project.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n### Built With\n\n* [Typescript](https://www.typescriptlang.org/)\n* [mongoose](https://mongoosejs.com/)\n* [Express](https://expressjs.com/)\n* [dotenv](https://www.npmjs.com/package/dotenv)\n* [mongoose-paginate-v2](https://www.npmjs.com/package/mongoose-paginate-v2)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nTo integrate `@knovator/masters-node`, you should be having basic `nodejs` application up and running with `express` (optionally using `mongoose` for `mongodb` database). `@knovator/masters-node` add routes for **masters** in application.\n\n### Prerequisites\n\n- It's good start to have `nodejs` application up and running with `express` (optionally using `mongoose` for `mongodb` database). Good to have used [i18next](https://www.npmjs.com/package/i18next) to add message in response codes.\n- `routes` uses `mongoose` connection established by application, so it's required to connect to database before using package. Example,\n  ```js\n  // db.js\n  const mongoose = require('mongoose');\n\n  mongoose\n    .connect('mongodb://localhost:27017/knovator')\n    .then(() =\u003e console.info('Database connected'))\n    .catch((err) =\u003e {\n      console.error('DB Error', err);\n    });\n\n  module.exports = mongoose;\n  ```\n- Image upload route for `upload` \u0026 `remove` is needed to declare externally. Example,\n  ```js\n  // fileRoute.js\n  const express = require('express');\n  const router = express.Router();\n\n  router.post(`/files/upload`, (req, res) =\u003e {\n      // TO DO: some file storage operation\n      let uri = \"/image.jpg\";\n      let id = \"62c54b15524b6b59d2313c02\";\n      res.json({\n        code: 'SUCCESS',\n        data: { id, uri },\n        message: 'File uploaded successfully'\n      });\n  });\n\n  router.delete(`/files/remove/:id`, (req, res) =\u003e {\n      // TO DO: some file remove operation\n      res.json({\n          code: 'SUCCESS',\n          data: {},\n          message: 'File removed successfully'\n      })\n  })\n\n  module.exports = router;\n  ```\n\n\n\n**Sample App file**\n  ```js\n    require('./src/db');\n    require('./src/models/file');\n\n    const cors = require('cors');\n    const express = require(\"express\");\n    const fileRoutes = require('./fileRoute.js');\n    const PORT = 8080;\n\n    const app = express();\n    app.use(cors());\n    app.use(express.static(\"public\"));\n    app.use(fileRoutes);\n\n    // ...\n    app.listen(PORT, () =\u003e {\n        console.log(`App started on ${PORT}`);\n    });\n  ```\n\n\n### Installation\n\n\u003c!-- 1. Get a free API Key at [https://example.com](https://example.com) --\u003e\n1. Install library\n   ```sh\n   npm install @knovator/masters-node\n   # or\n   yarn add @knovator/masters-node\n   ```\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nApp/Main file is a good place to use `@knovator/masters-node`\n  ```js\n    ...\n    const { masters } = require('masters-node');\n    \n    // ...\n    app.use(\"/admin/masters\", masters());\n    app.listen(PORT, () =\u003e {\n        console.log(`App started on ${PORT}`);\n    });\n  ```\n\nMasters package allows providing `authentication`, `logger` and `catchAsync` functions as parameters.\n  ```js\n  app.use(\"/admin/masters\", masters({\n    authentication: (req, res, next) =\u003e {...},\n    logger: console,\n    catchAsync: (function) =\u003e (req, res, next) =\u003e {...}\n  }));\n  ```\n\n### parameter explanations\n\n- `authentication`\n  - Provides ability to add authentication to routes\n    ```js\n    // default\n    (_req, _res, next) =\u003e {\n      return next();\n    }\n    ```\n- `logger`\n  - Provides ability to add logging for Database and Validation\n    ```js\n    // default\n    console\n    ```\n- `catchAsync`\n  - Wraps functions to handle async errors\n      ```js\n      // default\n      function catchAsync(fn) {\n        return function (req, res, next) {\n          Promise.resolve(fn(req, res, next)).catch((err) =\u003e {\n            // this.logger.error(err.message);\n            res.status(internalServerError).json({\n              code: RESPONSE_CODE.ERROR,\n              message: err.message,\n              data: {},\n            });\n          });\n        };\n      }\n      ```\n## Routes Infomration\n\nResponse follows following structure\n```js\n{\n  code: RESPONSE_CODES,\n  message: \"\" // if internationalized is applied\n  data: {}\n}\n```\n\n### Response Codes\n| Code | Description |\n| --- | ----------- |\n| SUCCESS | When request fullfiled without error |\n| ERROR | When request fullfiled with error |\n\n### Custom Validation messages\n| Message | Description |\n| --- | ----------- |\n| Master exists | When master/submaster with same code is exist in database |\n\n### HTTP Status Codes\n| HTTP | Description |\n| --- | ----------- |\n| 200 | When request fullfiled without error |\n| 201 | When document is created |\n| 500 | When internal server occurred |\n| 422 | When Validation error occurred |\n\n### Routes\n| Route | Description |\n| --- | ----------- |\n| `/create` | Creates Master/SubMaster record |\n| `/update:id` | Updates Master/SubMaster record |\n| `/partial-update/activate/:id` | Turn on/off `isActive` field based on body data |\n| `/partial-update/default/:id` | Turn on/off `isDefault` field based on body data |\n| `/partial-update/web-visible/:id` | Turn on/off `isWebVisible` field based on body data |\n| `/partial-update/sequence/:id` | Sets sequence of record with `:id`, and updates affected records sequence |\n| `/delete` | Delete the record whose `id` send in body |\n\n### `i18n` code for messages\n\nNextjs [i18n](https://www.npmjs.com/package/i18next) package adds facility for internationalization in nodejs application, and it's used in following mannerr\n```js\n// usage\nreq?.i18n?.(CODE)\n```\n| CODE | Description |\n| --- | ----------- |\n| `(master/submaster).create` | When record is created |\n| `(master/submaster).update` | When record is updated |\n| `(master/submaster).activate` | When `isActive` is set to true |\n| `(master/submaster).deactivate` | When `isActive` is set to false |\n| `(master/submaster).display` | When `isWebVisible` is set to true |\n| `(master/submaster).notDisplay` | When `isWebVisible` is set to false |\n| `(master/submaster).default` | When `isDefault` is set to true |\n| `(master/submaster).notDefault` | When `isDefault` is set to false |\n| `submaster.seq` | When sequence is updated |\n| `(master/submaster).delete` | When delete is performed |\n| `(master/submaster).findAll` | When all data is fetched |\n| `(master/submaster).notFound` | When Master/Submaster data is not found |\n\n### `descriptor` codes\n| Code | Description |\n| --- | ----------- |\n| `master.create` | For Create API |\n| `master.update` | For Update API |\n| `master.active` | For `isActive` toggle API |\n| `master.default` | For `isDefault` toggle API |\n| `master.webVisible` | For `isWebVisible` toggle API |\n| `master.sequence` | For `sequence` update API |\n| `master.softDelete` | For Soft-Delete API |\n| `master.list` | For List API |\n\n- You can prefix descriptors by adding `MASTERS_DESCRIPTOR_PREFIX` in environment variables.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n## Usecases\n\n`@knovator/masters` is combination of two packages `@knovator/masters-admin` and `@knovator/masters-admin`. It is designed plug and play masters module in your project. It is useful in following cases:\n\n- Your app needs master, submaster facility to build things like `state` with `city`, `experiences` with `skills`, `categories` with `subcategories` etc.\n- You want to let admin manage masters and submasters data from admin panel.\n- You want to show masters and submasters data somewhere in your app.\n\nIf you have any other usecase, please open an issue with tag `usecase`. We will try to add it in our roadmap.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the MIT License. See `LICENSE.txt` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nKnovator Technologies\n- Twitter [@knovator](https://twitter.com/knovator)\n- Web [https://knovator.com/](https://knovator.com/)\n\nProject Link: [https://github.com/knovator/masters-node](https://github.com/knovator/masters-node)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknovator%2Fmasters-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknovator%2Fmasters-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknovator%2Fmasters-node/lists"}