diff --git a/package.json b/package.json index 9d5f10a..6102fef 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "server-generator", - "version": "1.0.0", + "version": "0.1.0", "description": "Generates express middleware that manages collections and persists them as json files.", "main": "dist/server-generator.js", "scripts": { diff --git a/package.json b/package.json index 9d5f10a..6102fef 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "server-generator", - "version": "1.0.0", + "version": "0.1.0", "description": "Generates express middleware that manages collections and persists them as json files.", "main": "dist/server-generator.js", "scripts": { diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..375815e --- /dev/null +++ b/readme.md @@ -0,0 +1,98 @@ +Server Generator +================ +Code generator that creates middleware functions for express JS that manage collections and persists them as json files. + +# Example +Description of the domain model in `characters.model.json`: +```json +{ + "$schema": "https://infinity.synoikos.de/schemata/server-generator.schema.json ", + "collections": [ + { + "name": "Characters", + "entities": { + "name": "Character", + "properties": [ + { + "key": "name", + "type": "string", + "isNullable": false + }, + { + "key": "backstory", + "type": "string", + "isNullable": false + } + ] + } + } + ] +} +``` + +Generate the code: +```bash +server-generator --typescript-output-folder src --openapi-output src/openapi.json characters.model.json +``` + +Resulting files in *src*: +- `CharactersDataAccess.ts` +- `CharactersMiddleware.ts` +- `CharactersModel.ts` +- `openapi.json` +- `util.ts` + +# Commandline options +The most reliable source of documentation of commandline options is to just run `server-generator --help`. + +``` +Options: + --help Show help [boolean] + --version Show version number [boolean] + --typescript-output-folder Output folder for the generated server code. + [string] [required] + --openapi-output File name of the generated OpenAPI description. + [string] [required] +``` + +# Install +Prerequisites: node, npm, typescript +1. clone this repo +2. `npm run build-generator` +3. `chmod +x dist/server-generator.js` +4. `sudo npm install -g` + +# Motivation +In hobby projects, where I focus on the frontend of a cool litle web app, I run quite fast into the question of persistence. I could store everything in the browser. But that is not very safe, and I can't get the data onto other devices. + +There has to be some kind of web service, that persists the data. Even if the app only ever runs locally. The pattern is always the same: +- create CRUD endpoints +- dump the data into files +- read the data from files + +This projects attempts to collapse all the dull boilerplate into a concise description of the domain model. + +## Why generate explicit code? +Why not just write a super generic server, that reads the model descripion and does everything, that my generated code does as well? Maybe I will do that as well. + +Generating explicit code leaves the option to turn the generator off and develop the code further. + +It is also much easier to see, what is going on under the hood. + +# Dev notes for myself +To install this tool globally, run: +```bash +sudo npm install -g +``` +This creates a just a link to the `dist/server-generator.js`. The first line in that file, tells bash with which environment to execute this script. + +```bash +#!/usr/bin/env node +``` + +That means, that no update or re-install is necessary, if this project gets developed further. + +To use it, execute the following command in your workspace directory. That is the directory, in which you want to create the root folder for the new project. +```bash +server-generator +``` diff --git a/package.json b/package.json index 9d5f10a..6102fef 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "server-generator", - "version": "1.0.0", + "version": "0.1.0", "description": "Generates express middleware that manages collections and persists them as json files.", "main": "dist/server-generator.js", "scripts": { diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..375815e --- /dev/null +++ b/readme.md @@ -0,0 +1,98 @@ +Server Generator +================ +Code generator that creates middleware functions for express JS that manage collections and persists them as json files. + +# Example +Description of the domain model in `characters.model.json`: +```json +{ + "$schema": "https://infinity.synoikos.de/schemata/server-generator.schema.json ", + "collections": [ + { + "name": "Characters", + "entities": { + "name": "Character", + "properties": [ + { + "key": "name", + "type": "string", + "isNullable": false + }, + { + "key": "backstory", + "type": "string", + "isNullable": false + } + ] + } + } + ] +} +``` + +Generate the code: +```bash +server-generator --typescript-output-folder src --openapi-output src/openapi.json characters.model.json +``` + +Resulting files in *src*: +- `CharactersDataAccess.ts` +- `CharactersMiddleware.ts` +- `CharactersModel.ts` +- `openapi.json` +- `util.ts` + +# Commandline options +The most reliable source of documentation of commandline options is to just run `server-generator --help`. + +``` +Options: + --help Show help [boolean] + --version Show version number [boolean] + --typescript-output-folder Output folder for the generated server code. + [string] [required] + --openapi-output File name of the generated OpenAPI description. + [string] [required] +``` + +# Install +Prerequisites: node, npm, typescript +1. clone this repo +2. `npm run build-generator` +3. `chmod +x dist/server-generator.js` +4. `sudo npm install -g` + +# Motivation +In hobby projects, where I focus on the frontend of a cool litle web app, I run quite fast into the question of persistence. I could store everything in the browser. But that is not very safe, and I can't get the data onto other devices. + +There has to be some kind of web service, that persists the data. Even if the app only ever runs locally. The pattern is always the same: +- create CRUD endpoints +- dump the data into files +- read the data from files + +This projects attempts to collapse all the dull boilerplate into a concise description of the domain model. + +## Why generate explicit code? +Why not just write a super generic server, that reads the model descripion and does everything, that my generated code does as well? Maybe I will do that as well. + +Generating explicit code leaves the option to turn the generator off and develop the code further. + +It is also much easier to see, what is going on under the hood. + +# Dev notes for myself +To install this tool globally, run: +```bash +sudo npm install -g +``` +This creates a just a link to the `dist/server-generator.js`. The first line in that file, tells bash with which environment to execute this script. + +```bash +#!/usr/bin/env node +``` + +That means, that no update or re-install is necessary, if this project gets developed further. + +To use it, execute the following command in your workspace directory. That is the directory, in which you want to create the root folder for the new project. +```bash +server-generator +``` diff --git a/src/characters.model.json b/src/characters.model.json index 3e05037..ff33845 100644 --- a/src/characters.model.json +++ b/src/characters.model.json @@ -6,8 +6,16 @@ "entities": { "name": "Character", "properties": [ - { "key": "name", "type": "string", "isNullable": false }, - { "key": "backstory", "type": "string", "isNullable": false } + { + "key": "name", + "type": "string", + "isNullable": false + }, + { + "key": "backstory", + "type": "string", + "isNullable": false + } ] } }