declapract-typescript-ehmpathy 0.17.0

package/dist/practices/persist-with-rds/best-practice/config/dev.json.declapract.ts

@@ -0,0 +1,15 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents: context.declaredFileContents }; // init as declared if file dne
+
+  return {
+    contents: JSON.stringify(
+      { ...JSON.parse(contents), ...JSON.parse(context.declaredFileContents!) },
+      null,
+      2,
+    ),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/config/prod.json

@@ -0,0 +1,20 @@
+{
+  "database": {
+    "admin": {
+      "host": "@declapract{variable.databaseClusterHost.prod}",
+      "port": 5432,
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}",
+      "username": "@declapract{variable.databaseUserName.cicdUser}",
+      "password": "__PARAM__"
+    },
+    "service": {
+      "host": "@declapract{variable.databaseClusterHost.prod}",
+      "port": 5432,
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}",
+      "username": "@declapract{variable.databaseUserName.serviceUser}",
+      "password": "__PARAM__"
+    }
+  }
+}

package/dist/practices/persist-with-rds/best-practice/config/prod.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/practices/persist-with-rds/best-practice/config/test.json

@@ -0,0 +1,20 @@
+{
+  "database": {
+    "admin": {
+      "host": "localhost",
+      "port": 7821,
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}",
+      "username": "@declapract{variable.databaseUserName.cicdUser}",
+      "password": "__CHANG3_ME__"
+    },
+    "service": {
+      "host": "localhost",
+      "port": 7821,
+      "database": "@declapract{variable.databaseName}",
+      "schema": "@declapract{variable.databaseName}",
+      "username": "@declapract{variable.databaseUserName.serviceUser}",
+      "password": "__CHANG3_ME__"
+    }
+  }
+}

package/dist/practices/persist-with-rds/best-practice/config/test.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/practices/persist-with-rds/best-practice/package.json

@@ -0,0 +1,27 @@
+{
+  "dependencies": {
+    "pg": "@declapract{check.minVersion('8.3.0')}",
+    "yesql": "@declapract{check.minVersion('4.1.3')}"
+  },
+  "devDependencies": {
+    "sql-code-generator": "@declapract{check.minVersion('0.9.0')}",
+    "sql-dao-generator": "@declapract{check.minVersion('0.2.0')}",
+    "sql-schema-control": "@declapract{check.minVersion('0.7.3')}",
+    "sql-schema-generator": "@declapract{check.minVersion('0.21.1')}",
+    "@types/yesql": "@declapract{check.minVersion('3.2.2')}",
+    "@types/pg": "@declapract{check.minVersion('7.14.3')}"
+  },
+  "scripts": {
+    "generate:dao": "npx sql-dao-generator generate && npm run fix:format",
+    "generate:schema": "npx sql-schema-generator generate -c codegen.sql.schema.yml",
+    "generate:types-from-sql": "npx sql-code-generator generate -c codegen.sql.types.yml",
+    "provision:docker:prepare": "cp provision/schema/sql/init/.extensions.sql provision/docker/integration_test_db/init/extensions.sql && cp provision/schema/sql/init/.schema.sql provision/docker/integration_test_db/init/schema.sql && cp provision/schema/sql/init/.user.cicd.sql provision/docker/integration_test_db/init/user.cicd.sql",
+    "provision:docker:up": "docker-compose -f ./provision/docker/integration_test_db/docker-compose.yml up -d --force-recreate --build --renew-anon-volumes",
+    "provision:docker:await": "docker-compose -f ./provision/docker/integration_test_db/docker-compose.yml exec -T postgres /root/wait-for-postgres.sh",
+    "provision:docker:down": "docker-compose -f ./provision/docker/integration_test_db/docker-compose.yml down",
+    "provision:schema:plan": "npx sql-schema-control plan -c provision/schema/control.yml",
+    "provision:schema:apply": "npx sql-schema-control apply -c provision/schema/control.yml",
+    "provision:schema:sync": "npx sql-schema-control sync -c provision/schema/control.yml",
+    "provision:integration-test-db": "npm run provision:docker:prepare && npm run provision:docker:up && npm run provision:docker:await && npm run provision:schema:plan && npm run provision:schema:apply && npm run provision:schema:plan"
+  }
+}

package/dist/practices/persist-with-rds/best-practice/package.json.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS;

package/dist/practices/persist-with-rds/best-practice/provision/aws/product/parameter-store.tf

@@ -0,0 +1,24 @@
+resource "aws_ssm_parameter" "secret_database_admin_password" {
+  name  = "${local.parameter_store_namespace}.database.admin.password"
+  type  = "SecureString"
+  value = "__IGNORED__" # "ignored" since we dont want to check in secrets to version control (terraform.lifecycle.ignore_changes -> value isn't overwritten)
+  tags  = local.tags
+  count = var.environment == "prod" ? 1 : 0 # only needed in prod env, in other envs its hardcoded in config.${env}.json since it's not sensitive
+  lifecycle {
+    ignore_changes = [
+      value # we only need the real value on the first initialization, afterwards, users shouldn't have this
+    ]
+  }
+}
+resource "aws_ssm_parameter" "secret_database_service_password" {
+  name  = "${local.parameter_store_namespace}.database.service.password"
+  type  = "SecureString"
+  value = "__IGNORED__" # "ignored" since we dont want to check in secrets to version control (terraform.lifecycle.ignore_changes -> value isn't overwritten)
+  tags  = local.tags
+  count = var.environment == "prod" ? 1 : 0 # only needed in prod env, in other envs its hardcoded in config.${env}.json since it's not sensitive
+  lifecycle {
+    ignore_changes = [
+      value # we only need the real value on the first initialization, afterwards, users shouldn't have this
+    ]
+  }
+}

package/dist/practices/persist-with-rds/best-practice/provision/aws/product/parameter-store.tf.declapract.ts

@@ -0,0 +1,18 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // i.e., check that the contents of the file contains what's declared (default is equals)
+
+export const fix: FileFixFunction = (contents, context) => {
+  if (!contents) return { contents: context.declaredFileContents };
+  return {
+    contents: contents
+      .replace(
+        /value\s+\= var\.secret_database_\w+_password/g,
+        `value = "__IGNORED__" # "ignored" since we dont want to check in secrets to version control (terraform.lifecycle.ignore_changes -> value isn't overwritten)`,
+      )
+      .replace(
+        /local\.tags\n\s+lifecycle/g,
+        `local.tags\n  count = var.environment == "prod" ? 1 : 0 # only needed in prod env, in other envs its hardcoded in config.\${env}.json since it's not sensitive\n  lifecycle`,
+      ),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/provision/docker/integration_test_db/build-image.dockerfile

@@ -0,0 +1,7 @@
+FROM postgres:10.7
+
+COPY init/ /docker-entrypoint-initdb.d/
+
+ADD wait-for-postgres.sh /root/
+RUN chmod +x /root/wait-for-postgres.sh
+

package/dist/practices/persist-with-rds/best-practice/provision/docker/integration_test_db/docker-compose.yml

@@ -0,0 +1,13 @@
+version: '3'
+services:
+  postgres:
+    build:
+      context: .
+      dockerfile: build-image.dockerfile
+    container_name: @declapract{variable.databaseName}
+    command: postgres -c 'max_connections=500'
+    ports:
+      - 7821:5432
+    environment:
+      POSTGRES_PASSWORD: a-secure-password # default user is `postgres`
+      POSTGRES_DB: @declapract{variable.databaseName} # creates the database for us automatically

package/dist/practices/persist-with-rds/best-practice/provision/docker/integration_test_db/init/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!readme.md

package/dist/practices/persist-with-rds/best-practice/provision/docker/integration_test_db/init/readme.md

@@ -0,0 +1,3 @@
+all .sql files in this dir will be executed against db on load
+
+WARNING: if any of the files here cause an error when run, then the container will never be created, silently!

package/dist/practices/persist-with-rds/best-practice/provision/docker/integration_test_db/wait-for-postgres.sh

@@ -0,0 +1,15 @@
+#!/bin/sh
+# wait until postgres is really available
+maxcounter=45
+
+echo "waiting for postgres server to begin accepting connections..."
+counter=1
+while ! psql "dbname=$POSTGRES_DB host=localhost user=postgres password=$POSTGRES_PASSWORD port=5432" -c '\l' > /dev/null 2>&1; do
+    sleep 1
+    counter=`expr $counter + 1`
+    if [ $counter -gt $maxcounter ]; then
+        >&2 echo "we have been waiting for postgres too long already; failing"
+        exit 1
+    fi;
+done
+echo "connected to postgres instance successfuly"

package/dist/practices/persist-with-rds/best-practice/provision/schema/connection.config.js

@@ -0,0 +1,23 @@
+const Config = require('config-with-paramstore').default;
+
+const configInstance = new Config();
+const getConfig = async () =>
+  configInstance.get(process.env.DEPLOYMENT_STAGE || undefined);
+
+const promiseSchemaControlConfig = async () => {
+  const config = await getConfig();
+  const dbConfig = config.database.admin; // NOTE: schema control must have DDL privileges
+  const schemaControlConfig = {
+    host: dbConfig.host,
+    port: dbConfig.port,
+    database: dbConfig.schema, // i.e., db = schema
+    schema: dbConfig.schema,
+    username: dbConfig.username,
+    password: dbConfig.password,
+  };
+  return schemaControlConfig;
+};
+
+module.exports = {
+  promiseConfig: promiseSchemaControlConfig,
+};

package/dist/practices/persist-with-rds/best-practice/provision/schema/control.yml

@@ -0,0 +1,7 @@
+language: postgres
+dialect: 10.7
+connection: ./connection.config.js
+strict: true
+definitions:
+  - ./sql/init.yml
+  - ./sql/domain.yml

package/dist/practices/persist-with-rds/best-practice/provision/schema/deploy.database.sh

@@ -0,0 +1,71 @@
+#####################################################
+## initilize the database in a live cluster
+## - in other words, it does all of the things that docker does for us when we spin up a cluster without the db already
+## - i.e.,
+##    - create the database
+##    - install the extensions
+##    - creates the schema
+##    - creates the cicd user
+##    - grants the cicd user ownership of the db
+## - note:
+##   - requires pg admin access
+##   - requires _you_ to change the passwords in prod manually
+##
+## usage example:
+## ```sh
+## ./provision/schema/deploy.database.sh dev $(op get item @declapract{variable.organizationName}db.dev.postgres | jq -r .details.password)
+## ```
+#####################################################
+
+# check that user has defined the environment that they want this key created for correctly
+ENVIRONMENT=$1;
+if [ "$ENVIRONMENT" != "prod" ] && [ "$ENVIRONMENT" != "dev" ]; then
+  echo "\nerror: Environment, the first argument, must be specified as either 'prod' or 'dev'. You specified '$ENVIRONMENT'";
+  exit 1;
+fi
+
+# check that user is authed into correct account
+AWS_ACCOUNT_ID=$(aws sts get-caller-identity | jq -r '.Account');
+EXPECTED_AWS_ACCOUNT_ID=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.awsAccountId.prod}" || echo "@declapract{variable.awsAccountId.dev}");
+if [ "$AWS_ACCOUNT_ID" != "$EXPECTED_AWS_ACCOUNT_ID" ]; then
+  echo "\nerror: the AWS_ACCOUNT that you are signed into is not correct for the environment you specified. You are authed into account '$AWS_ACCOUNT_ID' but the correct account id for '$ENVIRONMENT' IS '$EXPECTED_AWS_ACCOUNT_ID'";
+  exit 1;
+fi
+
+# check that pg admin password was specified
+POSTGRES_ADMIN_PASSWORD="$2"
+if [ -z $POSTGRES_ADMIN_PASSWORD ]; then
+  echo "\nerror: POSTGRES_ADMIN_PASSWORD must be defined as second arg";
+  exit 1;
+fi;
+
+# define the postgres connecition string
+CLUSTER_HOST=$([ "$ENVIRONMENT" = 'prod' ] && echo "@declapract{variable.databaseClusterHost.prod}" || echo "@declapract{variable.databaseClusterHost.dev}");
+CLUSTER_CONNECTION_STRING=postgresql://postgres:$POSTGRES_ADMIN_PASSWORD@$CLUSTER_HOST:5432
+ROOT_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/postgres
+SVC_DB_CONNECTION_STRING=$CLUSTER_CONNECTION_STRING/@declapract{variable.databaseName}
+
+# define path to the init sqls
+SRC_PATH=$(readlink --canonicalize "$0");
+SRC_DIR=$(dirname $SRC_PATH);
+INIT_SQLS_DIR=$SRC_DIR/sql/init;
+
+# run the create database command on root db
+echo "\n 🔨 creating the database..."
+psql $ROOT_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.database.sql
+
+echo "\n 🔨 installing the extensions..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.extensions.sql
+
+echo "\n 🔨 creating the schema..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.schema.sql
+
+echo "\n 🔨 creating the cicd user..."
+psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.user.cicd.sql
+
+if [ "$ENVIRONMENT" = "prod" ]; then
+  echo "\n 🔨 granting reads to the datalakedb user..." # only in prod env; we dont want dev's testing data in our datalake
+  psql $SVC_DB_CONNECTION_STRING -f $INIT_SQLS_DIR/.user.datalakedb.sql
+fi;
+
+echo "\n 🎉 done"

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.database.sql

@@ -0,0 +1,10 @@
+/**
+ * this command creates the database that the service will use
+ * - this not managed by sql-schema-control
+ *   - requires superuser privileges
+ *   - sql-schema-control needs a db to run _in_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+ */
+CREATE DATABASE @declapract{variable.databaseName};

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.extensions.sql

@@ -0,0 +1,16 @@
+/**
+ * postgres databases use extensions to increase functionality
+ * - we have a minimum set of extensions that are required for sql-schema-generator
+ * - services may also include their own extensions if they want additional functionality
+ * - this is not managed by sql-schema-control
+ *   - requires superuser privileges, cicd user only has db_owner privileges
+ * - this is applied
+ *   - automatically for integration-test db (through `provision/docker/.../init/` directory, with files cp'd by npm provision scripts)
+ *   - by the deployment script for live deployments
+ */
+
+-- extensions required for all sql-schema-generator resources:
+CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
+CREATE EXTENSION IF NOT EXISTS "pgcrypto";
+
+-- extensions required for custom use cases in this service:

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.extensions.sql.declapract.ts

@@ -0,0 +1,37 @@
+import { FileCheckType, FileFixFunction } from 'declapract';
+
+const grabCreateExtensionLinesFromContents = (contents: string) =>
+  contents
+    .split('\n')
+    .filter((line) => line.startsWith('CREATE EXTENSION IF NOT EXISTS'));
+
+export const check = FileCheckType.CONTAINS;
+
+export const fix: FileFixFunction = (contents, context) => {
+  // if the file doesn't exist, create what we want to see - with an additional example of how it can be extended
+  if (!contents)
+    return {
+      contents: `${context.declaredFileContents!.trim()}\n-- CREATE EXTENSION IF NOT EXISTS ...`,
+    };
+
+  // if the file does exist, then find all the custom create extension lines
+  const requiredCreateExtensionLines = grabCreateExtensionLinesFromContents(
+    context.declaredFileContents!,
+  );
+  const foundCreateExtensionLines =
+    grabCreateExtensionLinesFromContents(contents);
+  const foundCustomCreateExtensionLines = foundCreateExtensionLines.filter(
+    (foundCreateExtensionLine) =>
+      !requiredCreateExtensionLines.some((requiredCreateExtensionLine) =>
+        foundCreateExtensionLine.includes(requiredCreateExtensionLine),
+      ), // if this found create-extension statement is not a required one, then its custom
+  );
+
+  // and set the contents equal to what we want to see + their custom ones
+  return {
+    contents: [
+      context.declaredFileContents!.trim(),
+      ...foundCustomCreateExtensionLines,
+    ].join('\n'),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.schema.sql

@@ -0,0 +1,11 @@
+/**
+ * this command creates the schema that the service + sql-schema-control will use
+ * - this command must be run inside of the database that was created for this service
+ * - this creates a schema with the same name as the database
+ * - this not managed by sql-schema-control
+ *   - sql-schema-control needs a schema to run _in_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+*/
+CREATE SCHEMA @declapract{variable.databaseName};

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.user.cicd.sql

@@ -0,0 +1,14 @@
+/**
+ * creates a cicd user, with total control over the database and the schema, to be used by sql-schema-control
+ * - full control required since it'll be managing all resources for this db
+ * - this not managed by sql-schema-control
+ *   - requires superuser privileges
+ *   - sql-schema-control needs a user to run _under_
+ * - this is applied
+ *   - automatically for integration-test db
+ *   - by the deployment script for live deployments
+ */
+CREATE USER @declapract{variable.databaseUserName.cicdUser} WITH PASSWORD '__CHANG3_ME__'; -- create cicd user
+ALTER DATABASE @declapract{variable.databaseName} OWNER TO @declapract{variable.databaseUserName.cicdUser}; -- make the cicd user the owner of the database
+ALTER SCHEMA @declapract{variable.databaseName} OWNER TO @declapract{variable.databaseUserName.cicdUser}; -- make the cicd user the owner of the schema, too
+ALTER USER @declapract{variable.databaseUserName.cicdUser} WITH CREATEROLE; -- allow the cicd user to create other users

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/.user.datalakedb.sql

@@ -0,0 +1,12 @@
+/**
+ * grants read access to `datalakedb_federated_query_reader` so that we can query this db from redshift
+ * - this not managed by sql-schema-control
+ *   - since it does not apply in integration test environment (since that user wont exist there)
+ * - this is applied
+ *   - by the deployment script for live deployments
+ */
+GRANT USAGE ON SCHEMA @declapract{variable.databaseName} TO datalakedb_federated_query_reader;
+GRANT SELECT ON ALL TABLES IN SCHEMA @declapract{variable.databaseName} TO datalakedb_federated_query_reader;
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT SELECT ON TABLES TO datalakedb_federated_query_reader;
+
+-- don't forget to hop into the datalakedb and add the ext_@declapract{variable.databaseName}

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/default_transaction_isolation.sql

@@ -0,0 +1,6 @@
+/**
+ * we want `read-committed` as the default txn isolation level on our databases
+ * - its _required_ to support high concurrency operations for the upserts generated by `sql-schema-generator`
+ * - this is done automatically by sql-schema-control under the cicd user
+ */
+ALTER DATABASE @declapract{variable.databaseName} SET DEFAULT_TRANSACTION_ISOLATION TO 'read committed';

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init/user.service.sql

@@ -0,0 +1,16 @@
+/**
+ * the service user has maximally restricted permissions
+ * - this is the user that the service will be using to interact with the database
+ * - insert only, baby!
+ */
+CREATE USER @declapract{variable.databaseUserName.serviceUser} WITH PASSWORD '__CHANG3_ME__';
+-- ALTER USER @declapract{variable.databaseUserName.serviceUser} WITH PASSWORD '__actual_password__';
+
+-- grant usage
+GRANT USAGE ON SCHEMA @declapract{variable.databaseName} TO @declapract{variable.databaseUserName.serviceUser};
+
+-- grant specific privileges to resources in the schema, for all created now and onward (i.e., all)
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT SELECT, INSERT, UPDATE ON TABLES TO @declapract{variable.databaseUserName.serviceUser};
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT EXECUTE ON FUNCTIONS TO @declapract{variable.databaseUserName.serviceUser};
+ALTER DEFAULT PRIVILEGES IN SCHEMA @declapract{variable.databaseName} GRANT USAGE, SELECT ON SEQUENCES TO @declapract{variable.databaseUserName.serviceUser};
+

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init.yml

@@ -0,0 +1,9 @@
+- type: change
+  id: init_default_txn_isolation
+  author: declapract
+  path: ./init/default_transaction_isolation.sql
+
+- type: change
+  id: init_service_user
+  author: declapract
+  path: ./init/user.service.sql

package/dist/practices/persist-with-rds/best-practice/provision/schema/sql/init.yml.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.CONTAINS; // contains since the user may have exclusions in that "for" object

package/dist/practices/persist-with-rds/best-practice/src/utils/config/getConfig.ts

@@ -0,0 +1,2 @@
+// placeholder export to satisfy getDatabaseConnection import; this practice only checks that the file exists
+export const getConfig = 'placeholder' as any;

package/dist/practices/persist-with-rds/best-practice/src/utils/config/getConfig.ts.declapract.ts

@@ -0,0 +1,3 @@
+import { FileCheckType } from 'declapract';
+
+export const check = FileCheckType.EXISTS;

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getDatabaseConnection.integration.test.ts

@@ -0,0 +1,10 @@
+import { getDatabaseConnection } from './getDatabaseConnection';
+
+describe('getDatabaseConnection', () => {
+  it('should be able to connect and execute a query', async () => {
+    const dbConnection = await getDatabaseConnection();
+    const result = await dbConnection.query({ sql: 'select 1' });
+    expect(result.rows.length).toEqual(1);
+    await dbConnection.end();
+  });
+});

package/dist/practices/persist-with-rds/best-practice/src/utils/database/getDatabaseConnection.ts

@@ -0,0 +1,65 @@
+import pg, { Client, QueryResult } from 'pg';
+
+import { getConfig } from '../config/getConfig';
+
+// https://github.com/brianc/node-postgres/pull/353#issuecomment-283709264
+pg.types.setTypeParser(20, (value) => parseInt(value, 10)); // cast bigints to numbers; by default, pg returns bigints as strings, since max val of bigint is bigger than max safe value in js
+pg.types.setTypeParser(1700, (value) => parseFloat(value)); // cast numerics to numbers; by default, pg returns numerics as strings
+
+export interface DatabaseConnection {
+  query: (args: { sql: string; values?: any[] }) => Promise<QueryResult<any>>;
+  end: () => Promise<void>;
+}
+
+export class DatabaseQueryError extends Error {
+  constructor({
+    sql,
+    values,
+    caught,
+  }: {
+    sql: string;
+    values?: any[];
+    caught: Error;
+  }) {
+    const message = `
+caught error querying database: ${caught.message}
+
+sql:
+  ${sql.trim()}
+
+values:
+  ${JSON.stringify(values)}
+    `.trim();
+    super(message);
+  }
+}
+
+export const getDatabaseConnection = async (): Promise<DatabaseConnection> => {
+  const config = await getConfig();
+  const dbConfig = config.database.service;
+  const client = new Client({
+    host: dbConfig.host,
+    user: dbConfig.username,
+    password: dbConfig.password,
+    database: dbConfig.schema,
+    port: dbConfig.port,
+  });
+  await client.connect();
+  await client.query(`SET search_path TO ${dbConfig.schema}, public;`); // https://www.postgresql.org/docs/current/ddl-schemas.html#DDL-SCHEMAS-
+  const dbConnection = {
+    query: ({ sql, values }: { sql: string; values?: (string | number)[] }) =>
+      client.query(sql, values),
+    end: () => client.end(),
+  };
+  return {
+    query: (args: { sql: string; values?: any[] }) =>
+      dbConnection.query(args).catch((error) => {
+        throw new DatabaseQueryError({
+          sql: args.sql,
+          values: args.values ?? [],
+          caught: error,
+        });
+      }),
+    end: () => dbConnection.end(),
+  };
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseConnection.ts

@@ -0,0 +1,38 @@
+import {
+  DatabaseConnection,
+  getDatabaseConnection,
+} from './getDatabaseConnection';
+
+/**
+ * wraps the input function and gives it a managed database connection
+ *
+ * managed meaning: it is opened when it is passed in and it is closed when the logic finishes running or throws an error.
+ *
+ * example usage:
+ * ```
+ *   const findById = withDatabaseConnection(({ id, dbConnection }: { id: string; dbConnection: DatabaseConnection }) => {
+ *     // do logic with dbConnection
+ *   });
+ *   // ...
+ *   await findById({ id: 821 }); // note how we dont have to pass in the dbConnection
+ * ```
+ */
+export const withDatabaseConnection = <
+  P extends { dbConnection: DatabaseConnection },
+  R,
+>(
+  logic: (args: P) => R | Promise<R>,
+) => {
+  return async (args: Omit<P, 'dbConnection'>) => {
+    // open the db connection
+    const dbConnection = await getDatabaseConnection();
+
+    // try and run the logic with db connection
+    try {
+      return await logic({ ...args, dbConnection } as P); // as P because: https://github.com/microsoft/TypeScript/issues/35858
+    } finally {
+      // make sure to close the db connection, both when `logic` throws an error or succeeds
+      await dbConnection.end();
+    }
+  };
+};

package/dist/practices/persist-with-rds/best-practice/src/utils/database/withDatabaseTransaction.ts

@@ -0,0 +1,20 @@
+import { DatabaseConnection } from './getDatabaseConnection';
+
+export const withDatabaseTransaction = <
+  P extends { dbConnection: DatabaseConnection },
+  R,
+>(
+  logic: (args: P) => R | Promise<R>,
+): typeof logic => {
+  return (async (args: P) => {
+    await args.dbConnection.query({ sql: 'START TRANSACTION' }); // begin transaction
+    try {
+      const result = await logic({ ...args }); // run the request
+      await args.dbConnection.query({ sql: 'COMMIT' }); // commit if successful
+      return result;
+    } catch (error) {
+      await args.dbConnection.query({ sql: 'ROLLBACK' }); // rollback if not successful
+      throw error;
+    }
+  }) as typeof logic;
+};

package/dist/practices/prettier/bad-practices/format-script/package.json.declapract.ts

@@ -0,0 +1,26 @@
+import { FileCheckFunction, FileFixFunction } from 'declapract';
+
+export const check: FileCheckFunction = (contents) => {
+  if (!contents) throw new Error('fine, does not match bad practice'); // if not defined, doesn't have the script
+  const parsedContents = JSON.parse(contents);
+  if (typeof parsedContents.scripts.format === 'string') return; // matches bad practice file
+  throw new Error('fine, does not have format script');
+};
+
+export const fix: FileFixFunction = (contents) => {
+  // parse the contents
+  if (!contents) return {}; // do nothing if no contents, shouldn't have reached here to begin with
+  const parsedContents = JSON.parse(contents);
+
+  // remove "format"
+  const fixedContents = {
+    ...parsedContents,
+    scripts: {
+      ...parsedContents.scripts,
+      format: undefined, // remove format
+    },
+  };
+
+  // and return the fixed json
+  return { contents: JSON.stringify(fixedContents, null, 2) };
+};

package/dist/practices/prettier/best-practice/.prettierignore

@@ -0,0 +1 @@
+*.md

package/dist/practices/prettier/best-practice/package.json

@@ -0,0 +1,10 @@
+{
+  "devDependencies": {
+    "prettier": "@declapract{check.minVersion('2.8.1')}",
+    "@trivago/prettier-plugin-sort-imports": "@declapract{check.minVersion('2.0.4')}"
+  },
+  "scripts": {
+    "fix:format:prettier": "prettier --write '**/*.ts' --config ./prettier.config.js",
+    "test:format:prettier": "prettier --parser typescript --check 'src/**/*.ts' --config ./prettier.config.js"
+  }
+}