feat(tz): ensure a pit of success with failfast on unexpected timezones

package.json

@@ -38,6 +38,7 @@
     "postinstall": "[ -d .git ] && npx husky install || exit 0"
   },
   "dependencies": {
+    "@ehmpathy/error-fns": "1.3.1",
     "expect": "29.4.2",
     "flat": "5.0.2",
     "lodash.uniq": "4.5.0",

src/practices/environments/best-practice/src/utils/environment.ts

@@ -1,3 +1,4 @@
+import { UnexpectedCodePathError } from '@ehmpathy/error-fns';
 import { createIsOfEnum } from 'type-fns';
 
 export enum Stage {
@@ -7,6 +8,22 @@ export enum Stage {
 }
 export const isOfStage = createIsOfEnum(Stage);
 
+/**
+ * verify that the server is on UTC timezone
+ *
+ * why?
+ * - non UTC timezone usage causes problems and takes a while to track down
+ * - by failing fast if the server our code runs in is not in UTC, we avoid these issues
+ * =>
+ * - create a pit of success
+ */
+const TIMEZONE = process.env.TZ;
+if (TIMEZONE !== 'UTC')
+  throw new UnexpectedCodePathError(
+    'env.TZ is not set to UTC. this can cause issues. please set the env var',
+    { found: TIMEZONE, desire: 'UTC' },
+  );
+
 /**
  * this allows us to infer what the stage should be in environments that do not have STAGE specified
  * - e.g., when running locally

src/practices/serverless/best-practice/serverless.yml

@@ -17,6 +17,7 @@ provider:
     environment: ${self:provider.stage}
     product: ${self:service}
   environment:
+    TZ: UTC # guarantee that utc timezone will be used explicitly, to facilitate a pit of success
     NODE_ENV: production # deploy with production optimizations of all resources, to make `dev` and `prod` stage deployments equivalent functionally (i.e., the same code paths in dev and prod)
     STAGE: ${self:provider.stage} # deploy specifying which stage we're targeting, to enable targeting the correct config + resources (e.g., hit dev db -vs- prod db)
     AWS_NODEJS_CONNECTION_REUSE_ENABLED: true # https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/node-reusing-connections.html