feat(init): initialize based on as-command

.depcheckrc.yml

@@ -0,0 +1,13 @@
+ignores:
+  - depcheck
+  - declapract
+  - declapract-typescript-ehmpathy
+  - '@commitlint/config-conventional'
+  - '@trivago/prettier-plugin-sort-imports'
+  - '@tsconfig/node-lts-strictest'
+  - serverless-prune-plugin
+  - core-js
+  - ts-jest
+  - ts-node
+  - husky
+  - if-env

.eslintrc.js

@@ -0,0 +1,48 @@
+module.exports = {
+  parser: '@typescript-eslint/parser', // Specifies the ESLint parser
+  extends: [
+    'plugin:@typescript-eslint/recommended', // Uses the recommended rules from the @typescript-eslint/eslint-plugin
+    'plugin:import/recommended', // specifies good import rules
+    'airbnb-typescript/base', // uses the airbnb recommended rules
+    'plugin:prettier/recommended', // Enables eslint-plugin-prettier and displays prettier errors as ESLint errors. Make sure this is always the last configuration in the extends array.
+  ],
+  parserOptions: {
+    project: './tsconfig.json',
+    ecmaVersion: 2018, // Allows for the parsing of modern ECMAScript features
+    sourceType: 'module', // Allows for the use of imports
+  },
+  rules: {
+    '@typescript-eslint/explicit-module-boundary-types': 'warn', // makes code-reviews easier + code quality better by explicitly defining outputs of exported functions+classes
+    '@typescript-eslint/explicit-function-return-type': 'off', // prefer '@typescript-eslint/explicit-module-boundary-types' since it only requires the check on exported functions+classes
+    'sort-imports': 'off',
+    'import/prefer-default-export': 'off', // default export = bad
+    'import/no-default-export': 'error', // require named exports - they make it easier to refactor, enforce consistency, and increase constraints
+    '@typescript-eslint/no-non-null-assertion': 'off', // we use these to help typescript out when we know something it doesnt, and cant easily express that
+    'import/no-extraneous-dependencies': [
+      'error',
+      {
+        devDependencies: [
+          '**/*.test.ts',
+          '**/*.test.integration.ts',
+          '**/*.test.acceptance.ts',
+          'acceptance/**/*.ts',
+          '**/__test_utils__/**/*.ts',
+          'provision/**/*.ts',
+        ],
+      },
+    ],
+    '@typescript-eslint/no-explicit-any': 'off', // sometimes this is a valid definition
+    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    'import/no-cycle': 'off',
+    'max-classes-per-file': 'off',
+    '@typescript-eslint/no-use-before-define': 'off',
+    '@typescript-eslint/no-floating-promises': 'error',
+    'prefer-destructuring': 'off',
+    '@typescript-eslint/no-non-null-assertion': 'off',
+    'lines-between-class-members': 'off',
+    '@typescript-eslint/lines-between-class-members': 'off',
+    'no-return-await': 'off', // this does not help anything and actually leads to bugs if we subsequently wrap the return in a try catch without remembering to _then_ add await
+    '@typescript-eslint/return-await': 'off',
+    '@typescript-eslint/no-unsafe-declaration-merging': 'off', // dobjs are built off of this
+  },
+};

.gitattributes

@@ -0,0 +1,2 @@
+# exclude package-lock from git diff; https://stackoverflow.com/a/72834452/3068233
+package-lock.json -diff

.github/workflows/.install.yml

@@ -0,0 +1,46 @@
+name: .install
+
+on:
+  workflow_call:
+    outputs:
+      node-modules-cache-key:
+        description: a max(stable) cache key to the node modules of this commit's dependencies
+        value: ${{ jobs.npm.outputs.node-modules-cache-key }}
+
+jobs:
+  npm:
+    runs-on: ubuntu-20.04
+    outputs:
+      node-modules-cache-key: ${{ steps.cache.outputs.cache-primary-key }}
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: node-modules deps hash
+        id: deps-hash
+        run: |
+          PACKAGE_DEPS_HASH=$(jq '.packages' package-lock.json | jq 'del(."".version)' | md5sum | awk '{print $1}');
+          echo "PACKAGE_DEPS_HASH=$PACKAGE_DEPS_HASH"
+          echo "package-deps-hash=$PACKAGE_DEPS_HASH" >> "$GITHUB_OUTPUT"
+      - name: node-modules cache get
+        uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: ./node_modules
+          key: ${{ runner.os }}-node-${{ steps.deps-hash.outputs.package-deps-hash }}
+
+      - name: node-modules cache miss install
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: npm ci --ignore-scripts --prefer-offline --no-audit
+
+      - name: node-modules cache set
+        if: steps.cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: ./node_modules
+          key: ${{ steps.cache.outputs.cache-primary-key }}

.github/workflows/.publish-npm.yml

@@ -0,0 +1,44 @@
+name: .publish-npm
+
+on:
+  workflow_call:
+    secrets:
+      npm-auth-token:
+        required: true
+        description: required credentials to authenticate with the aws account under which to publish
+
+jobs:
+  install:
+    uses: ./.github/workflows/.install.yml
+
+  publish:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          registry-url: 'https://registry.npmjs.org/'
+          node-version-file: '.nvmrc'
+
+      - name: node-modules cache get
+        uses: actions/cache/restore@v4
+        id: cache
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: node-modules cache miss install
+        if: steps.cache.outputs.cache-hit != 'true'
+        run: npm ci --ignore-scripts --prefer-offline --no-audit
+
+      - name: build
+        run: npm run build
+
+      - name: publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.npm-auth-token }}

.github/workflows/.test.yml

@@ -0,0 +1,213 @@
+name: .test
+
+on:
+  workflow_call:
+    inputs:
+      aws-region:
+        type: string
+        description: the aws region within which we should run the tests
+        required: false
+      aws-account-id:
+        type: string
+        description: the id of the account the credentials are expected to access
+        required: false
+    secrets:
+      aws-access-key-id:
+        required: false
+        description: required credentials to authenticate with aws the aws account against which to run the tests
+      aws-secret-access-key:
+        required: false
+        description: required credentials to authenticate with aws the aws account against which to run the tests
+
+jobs:
+  # install the dependencies
+  install:
+    uses: ./.github/workflows/.install.yml
+
+  # run tests in parallel
+  test-commits:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # we need all commits to test:commits
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:commits
+        run: npm run test:commits
+
+  test-types:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:types
+        run: npm run test:types
+
+  test-format:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:format
+        run: npm run test:format
+
+  test-lint:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:lint
+        run: npm run test:lint
+
+  test-unit:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: test:unit
+        run: THOROUGH=true npm run test:unit
+
+  test-integration:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: configure aws credentials
+        if: "${{ inputs.aws-account-id != '' }}"
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials
+        with:
+          aws-access-key-id: ${{ secrets.aws-access-key-id }}
+          aws-secret-access-key: ${{ secrets.aws-secret-access-key }}
+          aws-region: ${{ inputs.aws-region }}
+
+      - name: confirm aws credentials
+        if: "${{ inputs.aws-account-id != '' }}"
+        run: |
+          [[ ${{steps.credentials.outputs.aws-account-id}} != ${{ inputs.aws-account-id }} ]] \
+            && echo 'wrong aws account' && exit 1 \
+            || echo 'correct aws account';
+
+      - name: provision:integration-test-db
+        run: npm run provision:integration-test-db --if-present
+
+      - name: test:integration
+        run: THOROUGH=true npm run test:integration
+
+  test-acceptance-locally:
+    runs-on: ubuntu-20.04
+    needs: [install]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: set node-version
+        uses: actions/setup-node@v3
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: get node-modules from cache
+        uses: actions/cache/restore@v4
+        with:
+          path: ./node_modules
+          key: ${{ needs.install.outputs.node-modules-cache-key }}
+
+      - name: configure aws credentials
+        if: "${{ inputs.aws-account-id != '' }}"
+        uses: aws-actions/configure-aws-credentials@v1
+        id: credentials
+        with:
+          aws-access-key-id: ${{ secrets.aws-access-key-id }}
+          aws-secret-access-key: ${{ secrets.aws-secret-access-key }}
+          aws-region: ${{ inputs.aws-region }}
+
+      - name: confirm aws credentials
+        if: "${{ inputs.aws-account-id != '' }}"
+        run: |
+          [[ ${{steps.credentials.outputs.aws-account-id}} != ${{ inputs.aws-account-id }} ]] \
+            && echo 'wrong aws account' && exit 1 \
+            || echo 'correct aws account';
+
+      - name: provision:integration-test-db
+        run: npm run provision:integration-test-db --if-present
+
+      - name: test:acceptance:locally
+        run: npm run test:acceptance:locally

.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - v*
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }} # per [workflow] x [branch, tag]
+  cancel-in-progress: true #  cancel workflows for non-latest commits
+
+jobs:
+  test:
+    uses: ./.github/workflows/.test.yml
+
+  publish:
+    uses: ./.github/workflows/.publish-npm.yml
+    needs: [test]
+    secrets:
+      npm-auth-token: ${{ secrets.NPM_TOKEN }}