@devmoods/express-extras 0.22.3 → 0.23.0

package/README.md

@@ -8,15 +8,17 @@ _Extremely opinionated_ set of utilities for cranking out production-ready Node.
 - Thin layer on top of [Express](https://expressjs.com) with better support for `async`/`await`
 - PostgreSQL with transactions and migrations
 - Redis
-- Slack notifications
+- Slack (and Discord) client for sending notifications
 - Delayed jobs with [Faktory](https://contribsys.com/faktory/)
-- Validation of requests using [JSON Schemas](https://json-schema.org/)
-- Logging helpers
-- Graceful shutdown
-- Read configuration from `.env` files
+- Validation of HTTP requests using [JSON Schemas](https://json-schema.org/)
+- Logging helpers to write well-formatted contextual JSON logs to `stdout`
 - Request local context using [AsyncLocalStorage](https://nodejs.org/api/async_context.html)
 - [RFC 7807 Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807) by default
 - Works best with the [PnPM](https://pnpm.io/) package manager
+- Uses [Sentry](https://sentry.io/) for external error monitoring
+- Inspired by [The Twelve-Factor App](https://12factor.net/)
+  - Graceful shutdown
+  - Read configuration from `.env` files
 
 ## Goals
 
@@ -35,13 +37,22 @@ _Extremely opinionated_ set of utilities for cranking out production-ready Node.
 Put environment variables in `.env` at the application will automatically read those on startup. For test configuration in unit and integrations tests, use `.env.test`.
 
 ```bash
-READINESS_PROBE_MS=0
+NODE_ENV=development
+PORT=3000
+READINESS_PROBE_MS=
 FORCE_EXIT_TIMEOUT=
-SLACK_WEBHOOK_URL=
-REDIS_URL=
-PGUSER=my_database
+
+APP_JWT_SECRET=123456
+
 PGHOST=localhost
+PGUSER=my_database
 PGPASSWORD=
 PGDATABASE=my_database_dev
 PGPORT=5432
+
+REDIS_URL=
+
+SLACK_WEBHOOK_URL=
+SENTRY_DSN=
+SLACK_WEBHOOK_URL=
 ```

package/dist/auth.d.ts

@@ -10,18 +10,18 @@ export interface AuthOptions<UserModel extends Record<string, any>> {
     redis: RedisClient;
     filterUser(user: UserModel): Partial<UserModel>;
     tokenExpiry?: number;
-    onPasswordResetRequested?(user: UserModel, temporaryToken: string): void | Promise<void>;
+    onPasswordResetRequest?(user: UserModel, temporaryToken: string): void | Promise<void>;
     onPasswordChanged?(user: UserModel, newPassword: string): Promise<void>;
+    onEmailVerificationRequest?(user: UserModel, verificationToken: string): Promise<void>;
     onEmailVerified?(user: UserModel): Promise<void>;
-    onEmailVerificationRequest?(email: string): Promise<void>;
 }
 export interface CreateAuth<UserModel extends Record<string, any>> {
     createRouter: () => Router;
     useCurrentUser: () => UserModel | undefined;
     middleware: (authorize?: boolean) => RequestHandler;
-    createVerificationToken(email: string): Promise<string>;
+    createVerificationToken(user: UserModel): Promise<string>;
 }
-export declare function createAuth<UserModel extends Record<string, any>>({ getUserByToken, methods: { emailAndPassword }, filterUser, redis, tokenExpiry, onPasswordResetRequested, onPasswordChanged, onEmailVerified, onEmailVerificationRequest, }: AuthOptions<UserModel>): CreateAuth<UserModel>;
+export declare function createAuth<UserModel extends Record<string, any>>({ getUserByToken, methods: { emailAndPassword }, filterUser, redis, tokenExpiry, onPasswordResetRequest, onPasswordChanged, onEmailVerified, onEmailVerificationRequest, }: AuthOptions<UserModel>): CreateAuth<UserModel>;
 /**
  * Extract a Bearer token from the HTTP Authorization header
  * of `req`.

package/dist/auth.js

@@ -14,7 +14,7 @@ const TEMP_TOKEN_EXIRES_IN = 3600;
 export function createAuthToken(payload, secret = process.env.APP_JWT_SECRET) {
     return jwt.sign(payload, secret, { expiresIn: TOKEN_EXPIRES_IN });
 }
-export function createAuth({ getUserByToken, methods: { emailAndPassword }, filterUser = (x) => x, redis, tokenExpiry = TOKEN_EXPIRES_IN, onPasswordResetRequested, onPasswordChanged, onEmailVerified, onEmailVerificationRequest, }) {
+export function createAuth({ getUserByToken, methods: { emailAndPassword }, filterUser = (x) => x, redis, tokenExpiry = TOKEN_EXPIRES_IN, onPasswordResetRequest, onPasswordChanged, onEmailVerified, onEmailVerificationRequest, }) {
     const useCurrentUser = () => useContext('currentUser');
     const setCurrentUser = (user) => setContext('currentUser', user);
     const skipPasswordCheck = async () => true;
@@ -88,7 +88,15 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 required: ['email'],
             }), route(async (req) => {
                 const { email } = req.body;
-                await onEmailVerificationRequest?.(email);
+                if (!emailAndPassword) {
+                    throw new Error('Not applicable for login method');
+                }
+                const user = await emailAndPassword(email, skipPasswordCheck);
+                const verificationToken = crypto.randomBytes(32).toString('hex');
+                await redis.set(verificationToken, user.email, {
+                    EX: TEMP_TOKEN_EXIRES_IN,
+                });
+                await onEmailVerificationRequest?.(user, verificationToken);
                 return 202;
             }));
             router.post('/verify-email', validateBody({
@@ -96,20 +104,20 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 properties: { token: tokenSchema, email: emailSchema },
                 required: ['token', 'email'],
             }), route(async (req) => {
-                const { token } = req.body;
-                const email = await redis.get(token);
-                if (!email) {
+                const { token, email } = req.body;
+                const storedEmail = await redis.get(token);
+                if (!storedEmail) {
                     logger.info('invalid verification token', { token });
                     throw BadRequest('invalid verification token');
                 }
-                if (email !== req.body.email) {
+                if (storedEmail !== email) {
                     logger.info('email verification mismatch', {
-                        expected: email,
-                        actual: req.body.email,
+                        expected: storedEmail,
+                        actual: email,
                     });
                     throw BadRequest('invalid verification token');
                 }
-                const user = await emailAndPassword(email, skipPasswordCheck);
+                const user = await emailAndPassword(storedEmail, skipPasswordCheck);
                 setCurrentUser(user);
                 await onEmailVerified?.(user);
                 await redis.del(token);
@@ -141,7 +149,7 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             properties: { email: emailSchema },
             required: ['email'],
         }), route(async (req) => {
-            const email = req.body.email;
+            const { email } = req.body;
             if (!emailAndPassword) {
                 throw new Error('Not applicable for login method');
             }
@@ -151,7 +159,7 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 await redis.set(temporaryToken, user.email, {
                     EX: TEMP_TOKEN_EXIRES_IN,
                 });
-                await onPasswordResetRequested?.(user, temporaryToken);
+                await onPasswordResetRequest?.(user, temporaryToken);
                 logger.info('password reset request', { email });
             }
             catch (error) {
@@ -206,12 +214,8 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             }
         };
     }
-    async function createVerificationToken(email) {
-        if (!emailAndPassword) {
-            throw new Error('Not applicable for login method');
-        }
+    async function createVerificationToken(user) {
         try {
-            const user = await emailAndPassword(email, skipPasswordCheck);
             const temporaryToken = crypto.randomBytes(32).toString('hex');
             await redis.set(temporaryToken, user.email, {
                 EX: TEMP_TOKEN_EXIRES_IN,

package/dist/faktory.js

@@ -2,6 +2,7 @@ import { AsyncLocalStorage } from 'async_hooks';
 import { randomUUID } from 'crypto';
 import { create } from 'faktory-worker';
 import { getLogger } from './logger.js';
+import { startTimer } from './utils.js';
 const logger = getLogger('faktory');
 const JOB_ID = 'jobId';
 export function createJobs({ queueName }) {
@@ -29,7 +30,7 @@ export function createJobs({ queueName }) {
                     await client.close();
                 }
                 catch (error) {
-                    logger.error(error, 'Failed to create job', {
+                    logger.error(error, 'failed to create job', {
                         jobId: jid,
                         jobName,
                         args: JSON.stringify(args),
@@ -72,15 +73,9 @@ export async function createFaktoryWorker({ queueName, jobs, }) {
                     queueName,
                     availableJobs: availableJobs.map((j) => j.jobName),
                 });
-                const getDurationInMilliseconds = (start) => {
-                    const NS_PER_SEC = 1e9;
-                    const NS_TO_S = 1e9;
-                    const diff = process.hrtime(start);
-                    return (diff[0] * NS_PER_SEC + diff[1]) / NS_TO_S;
-                };
                 faktory.use(async (ctx, next) => {
                     const jobId = ctx.job.jid;
-                    const start = process.hrtime();
+                    const timer = startTimer();
                     await context.run(new Map(), async () => {
                         const store = context.getStore();
                         if (store) {
@@ -88,7 +83,7 @@ export async function createFaktoryWorker({ queueName, jobs, }) {
                         }
                         await next();
                     });
-                    const duration = getDurationInMilliseconds(start);
+                    const duration = timer.getDuration();
                     logger.info('job succeeded', {
                         jobName: ctx.job.jobtype,
                         jobId,

package/dist/listen.js

@@ -1,8 +1,8 @@
 import { createTerminus } from '@godaddy/terminus';
 import { getLogger } from './logger.js';
-const logger = getLogger('core');
-const READINESS_PERIOD_MS = parseInt(process.env.DM_READINESS_PERIOD_MS || '', 10) || 0;
-const FORCE_EXIT_TIMEOUT = parseInt(process.env.DM_FORCE_EXIT_TIMEOUT || '', 10) || 1000;
+const logger = getLogger('http');
+const READINESS_PERIOD_MS = parseInt(process.env.READINESS_PERIOD_MS || '', 10) || 0;
+const FORCE_EXIT_TIMEOUT = parseInt(process.env.FORCE_EXIT_TIMEOUT || '', 10) || 1000;
 /**
  * Listen on the given port and setup proper signal
  * handlers for terminating the process properly.

package/dist/middleware.d.ts

@@ -29,4 +29,4 @@ export declare function after(): RequestHandler;
 /**
  * Alias of `route()`
  */
-export declare function asyncMiddleware(fn: RequestHandler): RequestHandler;
+export declare function asyncMiddleware<RequestBody, RequestQuery = void>(fn: RequestHandler<Record<string, string>, any, RequestBody, RequestQuery>): RequestHandler<Record<string, string>, any, RequestBody, RequestQuery>;

package/dist/middleware.js

@@ -6,9 +6,10 @@ import helmet from 'helmet';
 import { withRequestContext } from './context.js';
 import { NotFound } from './errors.js';
 import { getLogger } from './logger.js';
+import { startTimer } from './utils.js';
 export const urlencodedParser = bodyParser.urlencoded;
 export const jsonParser = bodyParser.json;
-const logger = getLogger('core');
+const logger = getLogger('http');
 export { asyncMiddleware as route };
 /**
  * Register middleware that must come before the app routes.
@@ -19,7 +20,6 @@ export function before({ cookies = false, helmet: useHelmet = true, json: useJso
         logRequestDuration(),
         Sentry.Handlers.requestHandler(),
         Sentry.Handlers.tracingHandler(),
-        analyticsProxy(),
         useHelmet &&
             helmet({
                 contentSecurityPolicy: {
@@ -44,17 +44,12 @@ export function before({ cookies = false, helmet: useHelmet = true, json: useJso
             }),
         useJson && jsonParser(),
         cookies && cookieParser(),
+        analyticsProxy(),
     ].filter(Boolean));
 }
 function logRequestDuration() {
-    const getDurationInMilliseconds = (start) => {
-        const NS_PER_SEC = 1e9;
-        const NS_TO_S = 1e9;
-        const diff = process.hrtime(start);
-        return (diff[0] * NS_PER_SEC + diff[1]) / NS_TO_S;
-    };
     return (req, res, next) => {
-        const start = process.hrtime();
+        const timer = startTimer();
         logger.info('http request', {
             method: req.method,
             url: req.originalUrl,
@@ -62,7 +57,7 @@ function logRequestDuration() {
             ip: req.ip,
         });
         res.on('finish', () => {
-            const duration = getDurationInMilliseconds(start);
+            const duration = timer.getDuration();
             logger.info('http response', {
                 method: req.method,
                 url: req.originalUrl,

package/dist/migrate.d.ts

@@ -10,7 +10,7 @@ interface MigrationFileAPI {
     down(fn: any): Promise<string> | Promise<void> | string | void;
 }
 export declare function cli(): Promise<void>;
-interface MigratorOptions {
+export interface MigratorOptions {
     postgres?: ReturnType<typeof createPostgres>;
     migrationTableName?: string;
     verbose?: boolean;
@@ -23,8 +23,9 @@ export declare class Migrator {
     private filenameRegExp;
     private verbose;
     constructor({ postgres, pathToMigrations, migrationTableName, verbose, }?: MigratorOptions);
-    init(): Promise<import("pg").QueryResult<import("pg").QueryResultRow>>;
-    create(name: string | null | undefined): Promise<string>;
+    init(): Promise<boolean>;
+    isInstalled(): Promise<boolean>;
+    create(name: string | null | undefined, format?: 'ts' | 'sql'): Promise<string>;
     runMigrations(direction: 'up' | 'down'): Promise<number>;
     log(...args: any[]): void;
     executeMigration(migrations: Migration[], currentVersion: number, direction: 'up' | 'down'): Promise<number>;

package/dist/migrate.js

@@ -9,7 +9,7 @@ Usage
   $ migrate init
   $ migrate up
   $ migrate down
-  $ migrate create <name>
+  $ migrate create <name> [--typescript]
 `, {
         description: 'PostgreSQL migration tool',
         importMeta: import.meta,
@@ -32,12 +32,18 @@ Usage
                 case 'down':
                     await migrator.runMigrations(action);
                     break;
-                case 'init':
-                    await migrator.init();
-                    migrator.log(chalk.green('Migrations table was successfully setup.'));
+                case 'init': {
+                    const created = await migrator.init();
+                    if (created) {
+                        migrator.log(chalk.green('Migrations table was successfully setup.'));
+                    }
+                    else {
+                        migrator.log(chalk.green('Migrations table already existing.'));
+                    }
                     break;
+                }
                 case 'create': {
-                    const createdMigration = await migrator.create(args[0]);
+                    const createdMigration = await migrator.create(args[0], cli.flags.typescript ? 'ts' : 'sql');
                     migrator.log(chalk.green('Created migration', createdMigration));
                     break;
                 }
@@ -61,15 +67,30 @@ export class Migrator {
         this.verbose = verbose;
     }
     async init() {
-        return this.postgres.query(`
-      CREATE TABLE ${this.migrationTableName} (
+        if (await this.isInstalled()) {
+            return false;
+        }
+        await fs.mkdir(this.pathToMigrations, { recursive: true });
+        await this.postgres.query(`
+      CREATE TABLE IF NOT EXISTS ${this.migrationTableName} (
         id serial PRIMARY KEY,
         version int NOT NULL,
         run_at timestamp NOT NULL
       );
     `);
+        return true;
+    }
+    async isInstalled() {
+        try {
+            await this.postgres.query(`SELECT * FROM ${this.migrationTableName}`);
+            await fs.stat(this.pathToMigrations);
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
     }
-    async create(name) {
+    async create(name, format = 'sql') {
         if (!name) {
             throw new Error('Missing positional argument <name>');
         }
@@ -77,15 +98,25 @@ export class Migrator {
         const lastVersion = existingMigrations.length
             ? existingMigrations[existingMigrations.length - 1].version
             : 0;
-        const filename = path.join(this.pathToMigrations, `${lastVersion + 1}_${name}.ts`);
-        const template = `// Generated ${new Date()}\n\nexport function up(query: any) {\n\n}\n\nexport function down(query: any) {\n\n}\n`;
-        await fs.writeFile(filename, template);
+        const filename = path.join(this.pathToMigrations, `${lastVersion + 1}_${name}.${format}`);
+        const getTemplate = () => {
+            switch (format) {
+                case 'sql':
+                    return `-- Migration ${name} created ${new Date()}\n\nSELECT 1;\n\n-- ROLLBACK --\n\nSELECT 1;\n`;
+                case 'ts':
+                    return `// Migration ${name} created ${new Date()}\n\nexport function up(query: any) {}\n\nexport function down(query: any) {}\n`;
+            }
+        };
+        await fs.writeFile(filename, getTemplate());
         return filename;
     }
     async runMigrations(direction) {
         if (direction !== 'up' && direction !== 'down') {
             throw new Error('Only up and down are supported.');
         }
+        if (!(await this.isInstalled())) {
+            await this.init();
+        }
         const migrations = await this.getMigrations();
         const currentVersion = await this.getCurrentVersion();
         return this.executeMigration(migrations, currentVersion, direction);
@@ -159,9 +190,9 @@ export class Migrator {
             return import(filename);
         }
         const content = await fs.readFile(filename, 'utf-8');
-        const [up, down] = content.split('-- ROLLBACK --');
+        const [up, down] = content.split(/[-\s]+ROLLBACK[-\s]+/i);
         return {
-            useTransaction: !content.includes('-- NO TRANSACTION --'),
+            useTransaction: !/[-\s]+NO[\s]*TRANSACTION[-\s]+/i.test(content),
             up() {
                 return up.trim();
             },

package/dist/sentry.d.ts

@@ -58,6 +58,7 @@ export declare function createSentryOptions(app: Application | null, options?: S
     profilesSampler?: ((samplingContext: import("@sentry/types").SamplingContext) => number | boolean) | undefined;
     serverName?: string | undefined;
     includeLocalVariables?: boolean | undefined;
+    clientClass?: typeof Sentry.NodeClient | undefined;
     shouldCreateSpanForRequest?(this: void, url: string): boolean;
     onFatalError?(this: void, error: Error): void;
 };

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Start a high resolution timer
+ *
+ */
+export declare function startTimer(): {
+    getDuration(): number;
+};

package/dist/utils.js

@@ -0,0 +1,13 @@
+/**
+ * Start a high resolution timer
+ *
+ */
+export function startTimer() {
+    const start = process.hrtime();
+    return {
+        getDuration() {
+            const elapsed = process.hrtime(start);
+            return (elapsed[0] * 1e9 + elapsed[1]) / 1e9;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devmoods/express-extras",
-  "version": "0.22.3",
+  "version": "0.23.0",
   "description": "Kubernetes-ready utilities for rapid Node.js application development",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,12 +24,13 @@
   "license": "ISC",
   "devDependencies": {
     "@devmoods/eslint-config": "^1.2.0",
-    "@sentry/types": "^7.60.1",
+    "@sentry/types": "^7.61.1",
     "@types/express-serve-static-core": "^4.17.35",
-    "@types/node": "20.4.5",
-    "@types/supertest": "2.0.12",
-    "@typescript-eslint/eslint-plugin": "^6.2.0",
-    "@typescript-eslint/parser": "^6.2.0",
+    "@types/node": "20.4.7",
+    "@types/supertest": "^2.0.12",
+    "@typescript-eslint/eslint-plugin": "^6.2.1",
+    "@typescript-eslint/parser": "^6.2.1",
+    "@vitest/expect": "^0.34.1",
     "chalk": "^5.3.0",
     "eslint": "^8.46.0",
     "eslint-plugin-jsx-a11y": "^6.7.1",
@@ -39,17 +40,16 @@
     "faktory-worker": "^4.5.1",
     "import-sort-cli": "6.0.0",
     "import-sort-style-module": "6.0.0",
-    "isomorphic-fetch": "3.0.0",
-    "prettier": "3.0.0",
+    "prettier": "3.0.1",
     "supertest": "6.3.3",
     "ts-node": "10.9.1",
     "typescript": "5.1.6",
-    "vitest": "^0.33.0"
+    "vitest": "^0.34.1"
   },
   "dependencies": {
     "@devmoods/fetch": "^3.3.0",
     "@godaddy/terminus": "^4.12.1",
-    "@sentry/node": "^7.60.1",
+    "@sentry/node": "^7.61.1",
     "@types/bcrypt": "^5.0.0",
     "@types/body-parser": "^1.19.2",
     "@types/cookie-parser": "^1.4.3",
@@ -58,6 +58,7 @@
     "@types/koa-compose": "^3.2.5",
     "@types/nodemailer": "^6.4.9",
     "@types/pg": "^8.10.2",
+    "@types/superagent": "^4.1.18",
     "@types/uuid": "^9.0.2",
     "ajv": "^8.12.0",
     "bcrypt": "^5.1.0",
@@ -71,7 +72,7 @@
     "jsonwebtoken": "^9.0.1",
     "meow": "^12.0.1",
     "nodemailer": "^6.9.4",
-    "pg": "^8.11.1",
+    "pg": "^8.11.2",
     "redis": "^4.6.7",
     "sql-template-strings": "^2.2.2",
     "uuid": "^9.0.0"