{"id":21956919,"url":"https://github.com/transomjs/transom-core","last_synced_at":"2025-04-23T15:24:31.847Z","repository":{"id":26606875,"uuid":"109336841","full_name":"transomjs/transom-core","owner":"transomjs","description":"Transom-core is a foundation for building low-code REST APIs. Write only the code that makes your API special.","archived":false,"fork":false,"pushed_at":"2025-02-26T07:23:21.000Z","size":583,"stargazers_count":10,"open_issues_count":11,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-19T00:16:54.095Z","etag":null,"topics":["metadata","nodejs","restify","transomjs"],"latest_commit_sha":null,"homepage":"https://transomjs.github.io/","language":"JavaScript","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/transomjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-11-03T01:23:47.000Z","updated_at":"2024-01-13T01:55:13.000Z","dependencies_parsed_at":"2024-11-27T17:00:44.641Z","dependency_job_id":"fdb7b428-4918-4cea-b31c-6db564a5ea8a","html_url":"https://github.com/transomjs/transom-core","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transomjs%2Ftransom-core","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transomjs%2Ftransom-core/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transomjs%2Ftransom-core/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/transomjs%2Ftransom-core/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/transomjs","download_url":"https://codeload.github.com/transomjs/transom-core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250458417,"owners_count":21433869,"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":["metadata","nodejs","restify","transomjs"],"created_at":"2024-11-29T08:40:25.388Z","updated_at":"2025-04-23T15:24:31.827Z","avatar_url":"https://github.com/transomjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# transom-core\nTransom-core is a foundation for low-code REST API and realtime server development. Transom applications use metadata to configure pre-built and tested modules that allow developers to quickly piece together services that 'just work'! \n\n[![Build Status](https://travis-ci.org/transomjs/transom-core.svg?branch=master)](https://travis-ci.org/transomjs/transom-core)\n[![Coverage Status](https://coveralls.io/repos/github/transomjs/transom-core/badge.svg?branch=master)](https://coveralls.io/github/transomjs/transom-core?branch=master)\n\n## Based on many projects you already know!\nTransom uses Restify as it's core. We use Passport for authentication, Mongoose for data, SocketIO for realtime updates, Nodemailer for sending emails created with EJS templates!\n\n#### Need something else?\nDid we miss your favorite project or something you need for your product? Create a Transom module and let us know about it!\n\n## Extensible\nA transom server without modules, is just an empty Restify server. Adding functionality goes quickly with well thought out modules to provide common REST API functions. Features not available in an existing module can be added directly to the (Restify) server as custom routes or rolled into a custom module that can be loaded along-side with other Transom modules.\n\n## Installation\n```bash\n$ npm install --save @transomjs/transom-core\n```\n\n## Usage Example\n#### myApi.js\nAn API definition is quite simply a JavaScript Object. It can be a single file, but it doesn't need to be. Break it up into logical pieces as needed or as your project grows. \n * Checkout the API definition file from our \u003ca target=\"_blank\" href=\"https://github.com/4umfreak/transom-mongoose-example/blob/master/myApi.js\"\u003etransom-mongoose-example\u003c/a\u003e app.\n \n#### index.js\nThe following simple example is the `index.js` file from a REST API built with Transom. \n* Import the Transom-core and create a new instance.\n* Import and configure any Transom modules.\n* Import your API definition; This is the metadata that defines your API.\n* Call transom.initialize() with your metadata object. It will return a Promise that resolves to your Restify server.\n* Call server.listen()\n\n```javascript\n// Require your API definition\nconst myApi = require('./myApi');\n\n// Require the Transom-core and any Transom modules\nconst Transom = require('@transomjs/transom-core');\nconst transomMongoose = require('@transomjs/transom-mongoose');\n\n// Instantiate Transom\nconst transom = new Transom();\n\n// Register and configure Transom modules\ntransom.configure(transomMongoose, {\n  mongodb_uri: 'mongodb://localhost/transom-dev'\n});\n\n// Initialize all modules at once, returning a Restify server instance.\ntransom.initialize(myApi).then(function(server){\n\n\t// Add any additional routes as necessary.\n\tserver.get('/hello', function (req, res, next) {\n\t  res.json({hello: 'world'});\n\t  next();\n\t});\n\n\t// Add your own Error handlers\n\n\t// Start the server!\n\tserver.listen(7000, function () {\n\t\tconsole.log('%s listening at %s', server.name, server.url);\n\t});\n});\n```\n\n## Example apps\nWe've created a few small apis to demonstrate the usage of individual plugins:\n\n* https://github.com/binaryops-wiebo/transom-scaffold-example\n* https://github.com/4umfreak/transom-smtp-example\n* https://github.com/4umfreak/transom-mongoose-example\n* https://github.com/binaryops-wiebo/transom-functions-simple-example\n* https://github.com/binaryops-wiebo/transom-functions-secured-example\n* https://github.com/binaryops-wiebo/transom-socketio-internal-example\n\n## Want to add something before the Transom plugins?\nThat's easy too. Simply create your own server instance and pass it to Transom after it's been initilized.\n```javascript\n// Create your own Restify server instance and initialize it as needed.\nconst server = restify.createServer();\nserver.use(myCustomPlugin);\n// Later, initialize the registered Transom modules.\ntransom.initialize(server, myApi);\n```\n\n## What does the metadata look like?\n\nIf you can create [simple JavaScript Objects](https://github.com/4umfreak/transom-mongoose-example/blob/master/myApi.js), you can handle the metadata. By using JavaScript Objects, we can piece together bits of metadata from just about anywhere. \n\n## Configuring Transom-Core\n\nTransomCore uses attributes from the `transom` node in the definition file to apply defaults on start-up. If you don't need to make any specific configuration changes, the node can be dropped altogether to use the provided defaults.\n```javascript\nconst myApi = {\n\ttransom: {\n\t\trequestLogger: {},\n\t\tcors: {\n\t\t\torigins: ['http://localhost:8080', 'http://my-dev-server']\n\t\t},\n\t\tbodyParser: {\n\t\t\tmapParams: true\n\t\t},\n\t\tqueryParser: {\n\t\t\tmapParams: true\n\t\t},\n\t\tcookieParser: {},\n\t\turlEncodedBodyParser: {\n\t\t\tmapParams: true\n\t\t},\n\t\tgzipResponse: {},\n\t\tfullResponse: {},\n\t\tfavicon: {\n\t\t\tpath: \"/assets/favicon.ico\"\n\t\t}\n\t}\n};\n```\n\n### TransomCore plugins\nThe following plugins come standard in a Transom based server because we've found them to be both necessary and useful. Options provided in the definition are passed directly to each plugin unless otherwise documented below. See the documentation on each respective plugin as it's going to be more current than if we copied it here.\n\nIf you would prefer not to use any of the individual plugins applied in core, set the corresponding option to false. The following config disables the default `favicon` plugin.\n```javascript\nconst myApi = {\n\ttransom: {\n\t\tfavicon: false\n\t}\n};\n```\n\n#### requestLogger\nhttp://restify.com/docs/plugins-api/#requestlogger\nThe `requestLogger` option can be used a number of ways depending on your need to customize logging within your API.\n\n* Disable request logging by setting `requestLogger` to false. TransomJS will defer to Restify's default logger but log output will not include a unique `req_id` on each individual request.\n```javascript\ntransom: {\n\trequestLogger: false\n}\n```\n* Create your own Bunyan logger object and pass it in as `log`. Restify will use your logger and include a unique `req_id` on each individual request.\n```javascript\ntransom: {\n\trequestLogger: {\n\t\tlog: myCustomBunyan\n\t}\n}\n```\n* Define a custom [Bunyan logger](https://www.npmjs.com/package/bunyan), Restify will create a new Bunyan logger using your configuration.\n```javascript\ntransom: {\n\trequestLogger: {\n\t\tname: 'MyTestLogger',\n\t\tstreams: [\n\t\t\t{\n\t\t\t\tstream: process.stdout,\n\t\t\t\tlevel: \"debug\"\n\t\t\t}\n\t\t]\n\t}\n}\n```\n\n#### cors\nhttps://www.npmjs.com/package/restify-cors-middleware2\nThe `authorization` header is added to the `allowHeaders` option automatically as it's required for Bearer authentication.\nThe `origins` option is set to a wildcard for easier development and can be set with an environment variable when moving to test or production. Both preflight \u0026 actual middleware are applied. Keep in mind that `http://localhost:8100` is different than `http://127.0.0.1:8100` which is again different than `http://[::]:8100` even though they *may* all resolve to the same service. CORs middleware can accept an array of String, or regEx to match acceptable URI patters. See the official documentation for additional details.\n\n#### bodyParser\nhttp://restify.com/docs/plugins-api/#bodyparser\nThe `mapParams` option is set to true by default. Many Transom modules will only look for submitted values in req.params, rather than having to check in each of req.query or req.body.\n\n#### urlEncodedBodyParser\nA child plugin of the bodyParser. The `mapParams` option is set to true by default.\n\n#### queryParser\nhttp://restify.com/docs/plugins-api/#queryparser The `mapParams` option is set to true by default.\n\n#### cookieParser\nhttps://www.npmjs.com/package/restify-cookies Looking for cookies named `access_token` by default.\n\n#### gzipResponse\nhttp://restify.com/docs/plugins-api/#gzipresponse\n\n#### fullResponse\nhttp://restify.com/docs/plugins-api/#fullresponse\n\n#### favicon\nhttps://www.npmjs.com/package/serve-favicon\nIf a `path` option is not provided, an icon will be served from ./node_modules/transom-core/images/favicon.ico.\n\n\n## Transom modules\n\nTransom modules can be simple middleware, or complex ORM solutions. The following demonstrates how simple a Transom module can really be.\n\n```javascript\nfunction TransomConsole() {\n\tthis.initialize = function(server, options) {\n\t\tconsole.log(\"Initializing Transom-console.\");\n\t\tserver.use(function(req, res, next) {\n\t\t\tconsole.log(\"Transom-console...\", req.url);\n\t\t\tnext();\n\t\t});\n\t}\n}\nmodule.exports = new TransomConsole();\n```\n\n## Need Support?\nTransomJS is developed and maintained by [BinaryOps Software Inc.](https://binaryops.ca) in Canada.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransomjs%2Ftransom-core","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftransomjs%2Ftransom-core","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftransomjs%2Ftransom-core/lists"}