create-epic-graphql-server 0.5.0

package/.eslintignore

@@ -0,0 +1,7 @@
+.eslintrc.js
+node_modules
+.vscode
+specs
+bin
+build
+tsconfig.json

package/.eslintrc.js

@@ -0,0 +1,198 @@
+module.exports = {
+  root: true,
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'script',
+    project: ['./tsconfig.json'],
+    tsconfigRootDir: __dirname,
+  },
+  env: {
+    node: true,
+    es2021: true,
+  },
+  extends: [
+    'plugin:@typescript-eslint/recommended',
+  ],
+  plugins: [
+    '@typescript-eslint',
+  ],
+  rules: {
+    // 📜 @typescript-eslint
+    'quotes': 'off',
+    '@typescript-eslint/quotes': ['error', 'single'],
+    'no-dupe-class-members': 'off',  // handled by .ts
+    'no-undef': 'off',  // handled by .ts
+    '@typescript-eslint/consistent-type-assertions': 'error',
+    'no-array-constructor': 'off',
+    '@typescript-eslint/no-array-constructor': 'error',
+    'no-var': 'error',  // makes 'no-redeclare' irrelevant
+    // 'no-redeclare': 'off',  // see above
+    // '@typescript-eslint/no-redeclare': 'error',  // see above
+    'no-use-before-define': 'off',
+    '@typescript-eslint/no-use-before-define': [
+      'error',
+      {
+        'functions': true,
+        'classes': true,
+        'variables': true,
+        'allowNamedExports': true,
+        'enums': true,
+        'typedefs': true,
+        'ignoreTypeReferences': true,
+      },
+    ],
+    'no-unused-expressions': 'off',
+    '@typescript-eslint/no-unused-expressions': [
+      'error',
+      {
+        'allowShortCircuit': true,
+        'allowTernary': true,
+        'allowTaggedTemplates': true,
+      },
+    ],
+    'no-unused-vars': 'off',
+    '@typescript-eslint/no-unused-vars': [
+      'error',
+      {
+        'args': 'none',
+        'ignoreRestSiblings': true,
+      },
+    ],
+    'no-useless-constructor': 'off',
+    '@typescript-eslint/no-useless-constructor': 'error',
+    '@typescript-eslint/no-var-requires': 'off',
+    '@typescript-eslint/explicit-module-boundary-types': 'off',
+    '@typescript-eslint/consistent-type-imports': [
+      'warn',
+      {
+        prefer: 'type-imports',
+        disallowTypeAnnotations: false,
+      },
+    ],
+
+    // 📜 eslint
+    'array-callback-return': 'error',
+    'default-case': 'error',
+    'dot-location': ['error', 'property'],
+    'eqeqeq': ['error', 'always'],
+    'new-parens': 'error',
+    'no-caller': 'error',
+    'no-cond-assign': ['error', 'except-parens'],
+    'no-const-assign': 'error',
+    'no-control-regex': 'error',
+    'no-delete-var': 'error',
+    'no-dupe-args': 'error',
+    'no-dupe-keys': 'error',
+    'no-duplicate-case': 'error',
+    'no-empty-character-class': 'error',
+    'no-empty-pattern': 'error',
+    'no-eval': 'error',
+    'no-ex-assign': 'error',
+    'no-extend-native': 'error',
+    'no-extra-bind': 'error',
+    'no-extra-label': 'error',
+    'no-fallthrough': 'error',
+    'no-func-assign': 'error',
+    'no-implied-eval': 'error',
+    'no-invalid-regexp': 'error',
+    'no-iterator': 'error',
+    'no-label-var': 'error',
+    'no-labels': [
+      'error',
+      {
+        'allowLoop': true,
+        'allowSwitch': false,
+      },
+    ],
+    'no-lone-blocks': 'error',
+    'no-loop-func': 'error',
+    'no-mixed-operators': [
+      'error',
+      {
+        'groups': [
+          ['&', '|', '^', '~', '<<', '>>', '>>>'],
+          ['==', '!=', '===', '!==', '>', '>=', '<', '<='],
+          ['&&', '||'],
+          ['in', 'instanceof'],
+        ],
+        'allowSamePrecedence': false,
+      },
+    ],
+    'no-multi-str': 'error',
+    'no-native-reassign': 'error',
+    'no-negated-in-lhs': 'error',
+    'no-new-func': 'error',
+    'no-new-object': 'error',
+    'no-new-symbol': 'error',
+    'no-new-wrappers': 'error',
+    'no-obj-calls': 'error',
+    'no-octal': 'error',
+    'no-octal-escape': 'error',
+    'no-redeclare': 'error',
+    'no-regex-spaces': 'error',
+    'no-restricted-syntax': ['error', 'WithStatement'],
+    'no-script-url': 'error',
+    'no-self-assign': 'error',
+    'no-self-compare': 'error',
+    'no-sequences': 'error',
+    'no-shadow-restricted-names': 'error',
+    'no-sparse-arrays': 'error',
+    'no-template-curly-in-string': 'error',
+    'no-this-before-super': 'error',
+    'no-throw-literal': 'error',
+    'no-unreachable': 'error',
+    'no-unused-labels': 'error',
+    'no-useless-computed-key': 'error',
+    'no-useless-concat': 'error',
+    'no-useless-escape': 'error',
+    'no-useless-rename': [
+      'error',
+      {
+        'ignoreDestructuring': false,
+        'ignoreImport': false,
+        'ignoreExport': false,
+      },
+    ],
+    'no-with': 'error',
+    'no-whitespace-before-property': 'error',
+    'require-yield': 'error',
+    'rest-spread-spacing': ['error', 'never'],
+    'strict': ['error', 'never'],
+    'unicode-bom': ['error', 'never'],
+    'use-isnan': 'error',
+    'valid-typeof': 'error',
+    'getter-return': 'error',
+
+    // 📜 eslint, some additional styles
+    'array-element-newline': ['error', 'consistent'],
+    'comma-dangle': ['error', {
+      'arrays': 'always-multiline',
+      'objects': 'always-multiline',
+      'imports': 'always-multiline',
+      'exports': 'always-multiline',
+      // 'functions': 'never'
+    }],
+    'semi': ['error', 'never'],
+    'curly': ['error', 'multi-line'],
+    'indent': [
+      'error',
+      2,
+      {
+        'SwitchCase': 1,
+      },
+    ],
+    'arrow-spacing': ['error'],
+    'object-curly-spacing': ['error', 'always'],
+    'array-bracket-spacing': ['error', 'never'],
+    'no-irregular-whitespace': ['error'],
+    'eol-last': ['error', 'always'],
+    'no-trailing-spaces': [
+      'error',
+      {
+        'skipBlankLines': false,
+        'ignoreComments': true,
+      },
+    ],
+  },
+}

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+npm test
+npm run 'lint'

package/LICENSE

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

@@ -0,0 +1,228 @@
+![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FdaveKontro%2Fcreate-epic-graphql-server%2Fmain%2Fpackage.json&query=%24.version&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAACXBIWXMAAA7EAAAOxAGVKw4bAAABnUlEQVR4nO2bT0vEMBDFE+lBjCgoHvMx9Puf/Rq5eRGUIEIhngpS2HRet+nLn/ldM8m+fTuZLs3EGpzXFMP7jnmnYJ23UDz6ASmGhM45E9SAG3D9OzD+dNAfCDIgxRAxOfWDZkB3IAY8F1NxPE/SQHHBqL34rZEWQ90CwriXoioKIM1YkQEpho/r5NSLbgG2ADablbK16r9m62kwfAZMbAHzPBtjjJkmuZRlzgIydw3dgD3ir/nCa7rfAls1rHsDtlADcoOtPwIlaAawBbBRAzJj96epKEyull00IMXwXUZOXegWYAtgowawBbBRA9gC2KgBbAFs1AC2ADZqAFsAGzWALYCNGsAWwCZ7cNjLW+HcAenwGaAGsAWwUQPYAthkDbDOP5wlpBTW+dvc+FYG9HA28JsbpHSIrFtcFtDOj//r7O0aoRhwVIvLEesMXwRFHdWt/iWWdIwPnwFqgCTIOi++gdEa0gz4LKqiAHpjRMjwBkC3LFt5HCK3R4fPAMgA6/xjKSFHYZ2HrveiGfAFxjP4QYLhLWCdf0Pn1Mwf/j9N4kR1HlsAAAAASUVORK5CYII=&label=version&labelColor=%23ff883e&color=%23fff5e3)
+![Dynamic JSON Badge](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FdaveKontro%2Fcreate-epic-graphql-server%2Fmain%2Fpackage.json&query=%24.engines.node&logo=nodedotjs&label=node&labelColor=%23ff883e&color=%23fff5e3)
+![Static Badge](https://img.shields.io/badge/npm->=v10-%23fff5e3?logo=npm&labelColor=%23ff883e)
+
+# Create Epic GraphQL Server
+This module provides a configured [GraphQL](https://www.npmjs.com/package/graphql) server.  
+
+Having a preconfigured server will jump-start your project so you never have to begin from scratch.  
+
+Use GraphQL to unify you data into a single API. Take advantage of the powerful, intuitive GraphQL query language.  
+
+Interact with this project template live [here](https://www.createepicgraphqlserver.com/).  
+
+## installation
+first install globally  
+```
+npm install -g create-epic-graphql-server
+```
+
+then create your project  
+```
+npx create-epic-graphql-server --name={my-project}
+```
+
+## usage
+spin up the mock database (described below) `npm run dev:db`  
+
+now spin up the development server `npm run dev`  
+
+congrats, your API is now live!  
+
+### Graph*i*QL
+use the Graph*i*QL IDE to interact with your development server's API  
+
+this project provides the [ruru](https://www.npmjs.com/package/ruru) Graph*i*QL interface on `http://localhost:3000` (by default) during development  
+
+sample queries are provided later in this document  
+
+### mock database
+in order to get up and running quickly without the need to initially plug into a real database, this project provides a mock database via [json-server](https://www.npmjs.com/package/json-server)  
+
+the database starts when you run `npm run dev:db`, which automatically creates and runs of the file `db.json5`; the db file is seeded upon each startup from `db-seed.json`  
+
+see file `/src/config/db.ts` to understand how the database works; you will likely, eventually remove this file when you plug into a real database and replace the contents of `/src/models` with actual database models... that said, the provided pattern gives you scaffolding to build around  
+
+⚠️ please note this mock database is not intended or suited for production use ⚠️  
+
+## schema and types
+the schema sits at the heart of the GraphQL service  
+
+the types describe what data you can query, and the schema is the collection of what the service provides  
+
+a sample schema has been configured in `/src/schema/schema` with model validation, read all, read on, mutations, etc... again, your usecase will necessitate alterations to the schema, but the provided pattern might help you along the way  
+
+## test suite
+the test suite is enabled to run unit and integration tests  
+
+to create a test add a file tp `specs/` and follow this file naming format: `*.spec.ts`  
+
+tests run automatically during development via `npm run dev` or the test suite stand alone like so  
+
+```
+npm run test
+npm run test:watch
+```
+
+## linting
+linting rules are in `.eslintrc.js`; install the [ESLint](https://www.npmjs.com/package/eslint) pluggin if using vscode  
+
+```
+npm run lint
+```
+
+## custom logger
+A customized [winston](https://www.npmjs.com/package/winston) logger instance resides in `utilities/logger`, with usage found thoughout the codebase methods are provide to log a timestamp or the current node environment  
+
+## pre-commit
+scripts in `.husky/pre-commit` are run on commits for quality control  
+
+add or remove scripts you'd like run before code is commited  
+
+## environmental settings
+you can create a `.env` file at the project root and add the following variables  
+
+also add any additional variables your project needs  
+
+### develop (dev server)
+```
+# optional but recommended
+NODE_ENV=development
+PORT={port number}
+# optional
+JSON_SERVER_PORT={dev db port, default 3210}
+```
+
+### production (build)
+```
+# optional but recommended
+NODE_ENV=production
+PORT={port number}
+```
+
+## query samples
+Run these queries against the development server to get a feel the GraphQL query language. 
+
+### get all orders
+```
+  {
+    orders {
+      __typename
+      id
+      name
+      notes
+      status
+      customer {
+        __typename
+        name
+      }
+    }
+  }
+```
+
+### get all customers
+```
+  {
+    customers {
+      id
+      name
+      email
+      phone
+    }
+  }
+```
+
+### get an order by id
+```
+  {
+    order(id: "2") {
+      id
+      name
+      status
+      customer {
+        name
+      }
+    }
+  }
+```
+
+### get orders by status
+```
+  {
+    orders(filter: { status: "Not Started" }) {
+      id
+      name
+      status
+    }
+  }
+```
+
+### create a customer
+```
+  mutation {
+    addCustomer(
+      name: "Tom Hill",
+      email: "tom@example.com",
+      phone: "555-5555"
+    ) {
+      id
+      name
+      email
+      phone
+    }
+  }
+```
+
+### create an order
+- use id from new customer "Tom Hill"
+
+```
+  mutation {
+    addOrder(
+      name: productOne,
+      status: notStarted,
+      customerId: "{id}"
+    ) {
+      id
+      name
+      status
+      customer {
+        id
+        name
+      }
+    }
+  }
+```
+
+### update and order
+- use id from new order created above
+
+```
+  mutation {
+    updateOrder(
+      id: "{id}",
+      status: processing,
+    ) {
+      id
+      name
+      status
+      customer {
+        id
+        name
+      }
+    }
+  }
+```
+
+### delete a customer by id
+- use id from new customer "Tom Hill"
+- resolver is setup to delete associated orders too
+
+```
+  mutation {
+    deleteCustomer(id: "{id}") {
+      id
+      name
+    }
+  }
+```

package/bin/create-epic-graphql-server.js

@@ -0,0 +1,81 @@
+#! /usr/bin/env node
+const { writeFile } = require('fs/promises')
+const { execSync } = require('child_process')
+const path = require('path')
+const yargs = require('yargs/yargs')
+const { hideBin } = require('yargs/helpers')
+const packageJson = require('../package.json')
+
+const run = async () => {
+  const repo = 'https://github.com/daveKontro/create-epic-graphql-server/tarball/main'
+
+  const execCommand = (command) => {
+    try {
+      execSync(command, { stdio: 'inherit' })
+    } catch (error) {
+      console.error(`${command} failed`, error)
+      process.exit(1)
+    }
+
+    return true
+  }
+
+  // consume arguments
+  const argv = yargs(hideBin(process.argv)).argv
+
+  if (!argv.name) {
+    console.error('WARNING add a project name like so: npx create-epic-graphql-server --name={my-project}')
+    process.exit(1)
+  }
+
+  const projectPaths = {
+    root: path.resolve('.', argv.name),
+    get bin() { return path.resolve(this.root, 'bin') },
+    get env() { return path.resolve(this.root, '.env') },
+    get packageJson() { return path.resolve(this.root, 'package.json') },
+  }
+
+  const isNameDotCommand = (argv.name === '.')
+  const projectName = isNameDotCommand ? path.basename(process.cwd()) : argv.name
+
+  console.info('')
+  console.info(`Your project name is: ${projectName}`)
+  console.info('')
+
+  // create project
+  execCommand(`curl -L ${repo} | tar zx --one-top-level=${argv.name} --strip-components 1`)
+
+  // groom project
+  if (packageJson.hasOwnProperty('name')) packageJson.name = projectName
+  if (packageJson.hasOwnProperty('version')) packageJson.version = '1.0.0'
+  if (packageJson.hasOwnProperty('description')) packageJson.description = ''
+  if (packageJson.hasOwnProperty('author')) packageJson.author = ''
+  if (packageJson.hasOwnProperty('bin')) delete packageJson.bin
+  if (packageJson.hasOwnProperty('repository')) delete packageJson.repository
+  if (packageJson.dependencies.hasOwnProperty('yargs')) delete packageJson.dependencies.yargs
+
+  execCommand(`rm ${projectPaths.packageJson}`)
+  execCommand(`rm -rf ${projectPaths.bin}`)
+
+  try {
+    await writeFile(projectPaths.packageJson, JSON.stringify(packageJson, null, 2), {
+      encoding: 'utf8',
+    })
+  } catch (error) {
+    console.error('package.json creation failed', error)
+    process.exit(1)
+  }
+
+  execCommand(`touch ${projectPaths.env}`)
+
+  // install project dependencies
+  execCommand(`npm --prefix ${projectPaths.root} install`)
+
+  // finish up
+  console.info('')
+  console.info('Thanks for using Create Epic GraphQL Server!')
+
+  process.exit(0)
+}
+
+run()

package/db-seed.json5

@@ -0,0 +1,37 @@
+{
+  customers: [
+    {
+      id: '1',
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+      phone: '555-1234'
+    },
+    {
+      id: '2',
+      name: 'John Smith',
+      email: 'john@example.com',
+      phone: '555-9876'
+    }
+  ],
+  orders: [
+    {
+      id: '1',
+      name: 'Product One',
+      notes: 'Urgent delivery',
+      status: 'Processing',
+      customerId: '1'
+    },
+    {
+      id: '2',
+      name: 'Product Two',
+      status: 'Not Started',
+      customerId: '2'
+    },
+    {
+      id: '3',
+      name: 'Product Three',
+      status: 'Not Started',
+      customerId: '1'
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "create-epic-graphql-server",
+  "version": "0.5.0",
+  "description": "a configured graphql server",
+  "main": "index.js",
+  "bin": {
+    "create-epic-graphql-server": "bin/create-epic-graphql-server.js"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "start": "node ./build/index.js",
+    "dev": "concurrently \"tsx watch ./src/index.ts\" \"npm run test:watch:min\"",
+    "dev:db": "dotenv -e .env -- bash -c 'cp db-seed.json5 db.json5 && json-server db.json5 --port ${JSON_SERVER_PORT:-3210}'",
+    "test": "mocha --require ts-node/register specs/**/*.ts",
+    "test:watch": "mocha --require ts-node/register specs/**/*.ts --watch --watch-files src/**/*.ts,specs/**/*.ts",
+    "test:watch:min": "mocha --require ts-node/register specs/**/*.ts --watch --watch-files src/**/*.ts,specs/**/*.ts --reporter min",
+    "lint": "eslint src/**/*.{ts,json}",
+    "lint:fix": "eslint --fix src/**/*.{ts,json}",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "template",
+    "server",
+    "graphql",
+    "node",
+    "express",
+    "typescript",
+    "eslint",
+    "mocha",
+    "chai",
+    "sinon",
+    "supertest",
+    "javascript"
+  ],
+  "author": "David Kontrovitz",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "4.1.2",
+    "concurrently": "9.2.0",
+    "cors": "2.8.5",
+    "dotenv-cli": "8.0.0",
+    "dotenv-flow": "4.1.0",
+    "express": "5.1.0",
+    "graphql": "16.11.0",
+    "graphql-http": "1.22.4",
+    "helmet": "8.1.0",
+    "husky": "9.1.7",
+    "json-server": "1.0.0-beta.3",
+    "ruru": "2.0.0-beta.22",
+    "winston": "3.17.0",
+    "winston-daily-rotate-file": "5.0.0",
+    "yargs": "17.7.2",
+    "zod": "3.24.4"
+  },
+  "devDependencies": {
+    "@types/chai": "4.3.11",
+    "@types/chalk": "0.4.31",
+    "@types/dotenv-flow": "3.3.3",
+    "@types/express": "5.0.2",
+    "@types/mocha": "10.0.10",
+    "@types/node": "22.15.18",
+    "@types/sinon": "17.0.4",
+    "@types/supertest": "6.0.3",
+    "@typescript-eslint/eslint-plugin": "6.5.0",
+    "@typescript-eslint/parser": "6.5.0",
+    "chai": "4.3.10",
+    "eslint": "8.57.1",
+    "mocha": "9.2.2",
+    "sinon": "21.0.0",
+    "supertest": "7.1.1",
+    "ts-node": "10.9.2",
+    "tsx": "4.19.4",
+    "typescript": "5.8.3"
+  }
+}

package/specs/Customer.spec.ts

@@ -0,0 +1,41 @@
+import { expect } from 'chai'
+import { customerSchema } from '../src/models/Customer'
+
+describe('customerSchema', () => {
+  it('accepts a valid customer object', () => {
+    const data = {
+      name: 'John Doe',
+      email: 'john@example.com',
+      phone: '555-1234'
+    }
+
+    const parsed = customerSchema.parse(data)
+    expect(parsed).to.deep.equal(data)
+  })
+
+  it('allows an optional id', () => {
+    const data = {
+      id: 'cust-1',
+      name: 'Jane Doe',
+      email: 'jane@example.com',
+      phone: '555-5678'
+    }
+
+    const parsed = customerSchema.parse(data)
+    expect(parsed).to.deep.equal(data)
+  })
+
+  it('fails if email is invalid', () => {
+    const data = {
+      name: 'Invalid Email',
+      email: 'not-an-email',
+      phone: '555-0000'
+    }
+
+    expect(() => customerSchema.parse(data)).to.throw()
+  })
+
+  it('fails if required fields are missing', () => {
+    expect(() => customerSchema.parse({})).to.throw()
+  })
+})