@devmoods/express-extras 0.21.0 → 0.22.1

package/README.md

@@ -2,18 +2,21 @@
 
 > Kubernetes-ready utilities for rapid Node.js application development
 
-_Extremely opinionated_ set of utilities for cranking out Node.js apps in a timely manner.
+_Extremely opinionated_ set of utilities for cranking out production-ready Node.js apps in a timely manner. We assume you are using PostgreSQL as the main database, Redis for data you don't want in Postgres and [Faktory](https://contribsys.com/faktory/) for background jobs.
 
-- Express (with cool helpers for simple async/await)
-- PostgreSQL (w/ transactions) + Migrations
+- Only works with [ECMAScript Modules (ESM)](https://nodejs.org/api/esm.html)
+- Thin layer on top of [Express](https://expressjs.com) with better support for `async`/`await`
+- PostgreSQL with transactions and migrations
 - Redis
-- Slack Notifications
-- JSON Schema validation of incoming requests
-- Logging
-- Graceful Shutdown
+- Slack 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
-- Request Context using Continuation-Local-Storage
-- [RFC 7807 Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807)
+- 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
 
 ## Goals
 
@@ -21,127 +24,12 @@ _Extremely opinionated_ set of utilities for cranking out Node.js apps in a time
 
 ## Non-goals
 
-- Be extremely flexible and configurable
+- _Encourage deviating from the chosen path_
 
 ## Example
 
 > See the [example/](./example) folder for a complete example.
 
-```typescript
-require('dotenv-safe').config({
-  allowEmptyValues: true,
-});
-
-import http from 'http';
-import express from 'express';
-import * as Sentry from '@sentry/node';
-import helmet from 'helmet';
-import bodyParser from 'body-parser';
-import {
-  errorHandler,
-  envPort,
-  validateBody,
-  route,
-  listen,
-  withRequestContext,
-  ApiError,
-  createLogger,
-  createPostgres,
-  getRequestId,
-  sql,
-} from '@devmoods/express-extras';
-
-const app = express();
-const server = http.createServer(app);
-const postgres = createPostgres();
-const logger = createLogger({
-  name: 'example-app',
-  getContext() {
-    return {
-      requestId: getRequestId(),
-    };
-  },
-});
-const slack = createSlack({
-  webhookUrl: process.env.SLACK_WEBHOOK_URL!,
-});
-
-app.set('port', envPort());
-app.use(Sentry.Handlers.requestHandler());
-app.use(helmet());
-app.use(bodyParser.json());
-app.use(withRequestContext());
-
-app.get(
-  '/posts',
-  route(async () => {
-    const posts = await postgres.query('SELECT * FROM posts LIMIT 10');
-    return posts;
-  }),
-);
-
-app.post(
-  '/posts',
-  validateBody({
-    type: 'object',
-    properties: {
-      title: {
-        type: 'string',
-        minLength: 3,
-      },
-      content: {
-        type: 'string',
-        minLength: 3,
-      },
-    },
-    required: ['title', 'content'],
-  }),
-  route(async ({ body: { title, content } }) => {
-    const post = { title, content };
-
-    await postgres.insert(
-      sql`INSERT INTO posts (title, content) VALUES (${title}, ${content})`,
-    );
-
-    slack.postMessage(`New post created with title ${title}`);
-
-    return [201, post];
-  }),
-);
-
-app.use((req, res, next) => {
-  next(NotFound());
-});
-
-app.use(
-  Sentry.Handlers.errorHandler({
-    shouldHandleError(error) {
-      return true;
-    },
-  }),
-);
-
-app.use(
-  errorHandler({
-    onError(error) {
-      if (error instanceof ApiError && error.status < 500) {
-        logger.warn(error.message, { error });
-      } else {
-        logger.error(error);
-      }
-    },
-  }),
-);
-
-listen(server, {
-  port: app.get('port'),
-  logger,
-  async onShutdown() {
-    await Promise.all([redis.quit(), postgres.end()]);
-  },
-});
-```
-
 ## Configure
 
 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`.

package/dist/auth.d.ts

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

package/dist/auth.js

@@ -14,9 +14,10 @@ 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, onResetRequested, onPasswordChanged, }) {
+export function createAuth({ getUserByToken, methods: { emailAndPassword }, filterUser = (x) => x, redis, tokenExpiry = TOKEN_EXPIRES_IN, onResetRequested, onPasswordChanged, onUserVerified, }) {
     const useCurrentUser = () => useContext('currentUser');
     const setCurrentUser = (user) => setContext('currentUser', user);
+    const skipPasswordCheck = async () => true;
     const createRouter = () => {
         const router = Router();
         router.get('/me', middleware(), route(() => {
@@ -55,27 +56,20 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             setAccessTokenCookie(res, null);
             res.redirect('/');
         }));
-        const skipPasswordCheck = async () => true;
         const tokenSchema = {
-            type: 'object',
-            properties: {
-                token: { type: 'string', minLength: 50, maxLength: 64 },
-            },
-        };
-        const emailSchema = {
             type: 'string',
-            minLength: 4,
+            minLength: 50,
+            maxLength: 64,
         };
+        const passwordSchema = { type: 'string', minLength: 8 };
+        const emailSchema = { type: 'string', minLength: 4 };
         if (emailAndPassword) {
-            router.post('/reset/:token', validateParams(tokenSchema), validateBody({
+            router.post('/change-password', validateBody({
                 type: 'object',
-                properties: {
-                    password: { type: 'string', minLength: 8 },
-                },
-                required: ['password'],
+                properties: { token: tokenSchema, password: passwordSchema },
+                required: ['token', 'password'],
             }), route(async (req) => {
-                const { password } = req.body;
-                const { token } = req.params;
+                const { password, token } = req.body;
                 const email = await redis.get(token);
                 if (!email) {
                     logger.info('invalid reset token', { token });
@@ -88,9 +82,41 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
                 logger.info('user changed password');
                 return 200;
             }));
+            router.post('/verify-email', validateBody({
+                type: 'object',
+                properties: { token: tokenSchema, email: emailSchema },
+                required: ['token', 'email'],
+            }), route(async (req) => {
+                const { token } = req.body;
+                const email = await redis.get(token);
+                if (!email) {
+                    logger.info('invalid verification token', { token });
+                    throw BadRequest('invalid verification token');
+                }
+                if (email !== req.body.email) {
+                    logger.info('email verification mismatch', {
+                        expected: email,
+                        actual: req.body.email,
+                    });
+                    throw BadRequest('invalid verification token');
+                }
+                const user = await emailAndPassword(email, skipPasswordCheck);
+                setCurrentUser(user);
+                await onUserVerified?.(user);
+                await redis.del(token);
+                logger.info('user verified');
+                return 200;
+            }));
         }
-        router.get('/reset/:token', validateParams(tokenSchema), route(async (req) => {
-            const token = req.params.token;
+        /**
+         * Check that a reset token is valid.
+         */
+        router.get('/reset/:token', validateParams({
+            type: 'object',
+            properties: { token: tokenSchema },
+            required: ['token'],
+        }), route(async (req) => {
+            const { token } = req.params;
             const email = await redis.get(token);
             if (!email) {
                 logger.info('invalid reset token', { token });
@@ -98,11 +124,12 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             }
             return 200;
         }));
+        /**
+         * Request password reset
+         */
         router.post('/reset', middleware(false), validateBody({
             type: 'object',
-            properties: {
-                email: emailSchema,
-            },
+            properties: { email: emailSchema },
             required: ['email'],
         }), route(async (req) => {
             const email = req.body.email;
@@ -170,10 +197,28 @@ export function createAuth({ getUserByToken, methods: { emailAndPassword }, filt
             }
         };
     }
+    async function createVerificationToken(email) {
+        if (!emailAndPassword) {
+            throw new Error('Not applicable for login method');
+        }
+        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,
+            });
+            return temporaryToken;
+        }
+        catch (error) {
+            logger.error(error, 'could not create verification token');
+            throw error;
+        }
+    }
     return {
         createRouter,
         useCurrentUser,
         middleware,
+        createVerificationToken,
     };
 }
 /**

package/dist/context.d.ts

@@ -13,5 +13,5 @@ export declare function useContext<T>(key: string): T | undefined;
 /**
  * Set a value on the request context
  */
-export declare function setContext<T>(key: string, value: T): Map<string, any> | undefined;
+export declare function setContext<T>(key: string, value: T): void;
 export declare function useRequestId(): string | undefined;

package/dist/context.js

@@ -32,7 +32,7 @@ export function useContext(key) {
 export function setContext(key, value) {
     const store = requestContext.getStore();
     if (store) {
-        return store.set(key, value);
+        store.set(key, value);
     }
 }
 export function useRequestId() {

package/dist/faktory.d.ts

@@ -0,0 +1,22 @@
+export interface JobsOptions {
+    queueName: string;
+}
+export declare function createJobs({ queueName }: JobsOptions): {
+    job: <K extends Record<string, any>, T extends (input: K) => void | Promise<any>>(fn: T) => {
+        $job: boolean;
+        jobName: string;
+        readonly executionCount: number;
+        delay(args?: Parameters<T>[0] | undefined): Promise<void>;
+        execute(args: Parameters<T>[0]): Promise<any>;
+    };
+    queueName: string;
+};
+export type Task = ReturnType<ReturnType<typeof createJobs>['job']>;
+export interface FaktoryWorkerOptions {
+    jobs: unknown[];
+    queueName: string;
+}
+export declare function useJobId(): string | undefined;
+export declare function createFaktoryWorker({ queueName, jobs, }: FaktoryWorkerOptions): Promise<{
+    start(): Promise<void>;
+}>;

package/dist/faktory.js

@@ -0,0 +1,108 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { randomUUID } from 'crypto';
+import { create } from 'faktory-worker';
+import { getLogger } from './logger.js';
+const logger = getLogger('faktory');
+const JOB_ID = 'jobId';
+export function createJobs({ queueName }) {
+    const faktory = create();
+    function job(fn) {
+        const jobName = fn.name;
+        let executionCount = 0;
+        if (jobName == null) {
+            throw new Error('Can not create job without a name');
+        }
+        return {
+            $job: true,
+            jobName,
+            get executionCount() {
+                return executionCount;
+            },
+            async delay(args) {
+                const jid = randomUUID();
+                try {
+                    const client = await faktory.connect();
+                    const j = client.job(jobName, args);
+                    j.jid = jid;
+                    j.queue = queueName;
+                    await j.push();
+                    await client.close();
+                }
+                catch (error) {
+                    logger.error(error, 'Failed to create job', {
+                        jobId: jid,
+                        jobName,
+                        args: JSON.stringify(args),
+                    });
+                }
+            },
+            async execute(args) {
+                try {
+                    const result = await fn(args);
+                    executionCount += 1;
+                    return result;
+                }
+                catch (error) {
+                    logger.error(error);
+                    throw error;
+                }
+            },
+        };
+    }
+    return { job, queueName };
+}
+const context = new AsyncLocalStorage();
+export function useJobId() {
+    const store = context.getStore();
+    if (store) {
+        return store.get(JOB_ID);
+    }
+}
+export async function createFaktoryWorker({ queueName, jobs, }) {
+    const faktory = create();
+    const filter = (j) => !!Object.prototype.hasOwnProperty.call(j, '$job');
+    const availableJobs = jobs.filter(filter);
+    for (const job of availableJobs) {
+        faktory.register(job.jobName, job.execute);
+    }
+    return {
+        async start() {
+            try {
+                logger.info('faktory started', {
+                    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();
+                    await context.run(new Map(), async () => {
+                        const store = context.getStore();
+                        if (store) {
+                            store.set(JOB_ID, jobId);
+                        }
+                        await next();
+                    });
+                    const duration = getDurationInMilliseconds(start);
+                    logger.info('job succeeded', {
+                        jobName: ctx.job.jobtype,
+                        jobId,
+                        duration,
+                    });
+                });
+                await faktory.work({
+                    queues: [queueName],
+                });
+            }
+            catch (error) {
+                logger.error(error);
+                process.exit(1);
+            }
+        },
+    };
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from './auth.js';
 export * from './context.js';
 export * from './email.js';
 export * from './errors.js';
+export * from './faktory.js';
 export * from './listen.js';
 export * from './logger.js';
 export * from './middleware.js';

package/dist/index.js

@@ -2,6 +2,7 @@ export * from './auth.js';
 export * from './context.js';
 export * from './email.js';
 export * from './errors.js';
+export * from './faktory.js';
 export * from './listen.js';
 export * from './logger.js';
 export * from './middleware.js';

package/dist/logger.js

@@ -43,6 +43,7 @@ export function createLogger({ name, getContext, silent = () => process.env.NODE
             level: LEVELS_TO_NAME[level],
             hostname,
             pid,
+            name,
             message,
             ...context,
             time: new Date().toISOString(),

package/dist/middleware.d.ts

@@ -1,6 +1,5 @@
 import bodyParser from 'body-parser';
 import type { RequestHandler } from 'express';
-import { type ErrorHandlerOptions } from './errors.js';
 type UrlencodedParser = typeof bodyParser.urlencoded;
 type JsonParser = typeof bodyParser.json;
 export declare const urlencodedParser: UrlencodedParser;
@@ -23,17 +22,10 @@ export declare function before({ cookies, helmet: useHelmet, json: useJson, allo
  * unknown routes.
  */
 export declare function notFound(): RequestHandler;
-export interface AfterMiddlewareOptions {
-    onError?: ErrorHandlerOptions['onError'];
-}
 /**
  * Register middlewares that must come after the app routes.
- *
- * Currently attaches:
- * - notFound()
  */
-type After = ReturnType<typeof notFound>;
-export declare function after(): After;
+export declare function after(): RequestHandler;
 /**
  * Alias of `route()`
  */

package/dist/middleware.js

@@ -84,8 +84,25 @@ export function notFound() {
         next(NotFound(`Could not ${req.method} ${req.path}`));
     };
 }
+/**
+ * In production, we could directly proxy the url
+ * to an analytics service from nginx, but in dev
+ * we serve a dummy script to avoid 404.
+ */
+function analyticsProxy() {
+    return (req, res, next) => {
+        if (req.originalUrl === '/analytics.js') {
+            res.setHeader('Content-type', 'text/javascript');
+            return res.status(200).end('// no-op analytics proxy');
+        }
+        next();
+    };
+}
+/**
+ * Register middlewares that must come after the app routes.
+ */
 export function after() {
-    return notFound();
+    return compose([analyticsProxy(), notFound()]);
 }
 /**
  * Alias of `route()`

package/dist/routes.d.ts

@@ -1,2 +1,2 @@
-import type { RequestHandler, Express } from 'express';
+import type { Express, RequestHandler } from 'express';
 export declare function createDocsRouter(app: Express, extras?: Record<string, any>): RequestHandler;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devmoods/express-extras",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "description": "Kubernetes-ready utilities for rapid Node.js application development",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,17 +8,6 @@
   "bin": {
     "migrate": "bin/migrate"
   },
-  "scripts": {
-    "start": "ts-node --esm example/index.ts",
-    "clean": "rm -rf dist",
-    "lint": "eslint src",
-    "test": "NODE_ENV=test vitest",
-    "build": "pnpm run clean && tsc --project tsconfig.build.json",
-    "prepublishOnly": "pnpm run clean && pnpm run build",
-    "prettier": "prettier --write '**/*.{js,css,md,ts,tsx}'",
-    "import-sort": "import-sort --write '**/*.{js,jsx,ts,tsx}'",
-    "format": "pnpm run import-sort && pnpm run prettier"
-  },
   "author": {
     "name": "hanse",
     "email": "hanse@koren.im"
@@ -47,6 +36,7 @@
     "eslint-plugin-prettier": "^5.0.0",
     "eslint-plugin-react": "^7.33.1",
     "eslint-plugin-react-hooks": "^4.6.0",
+    "faktory-worker": "^4.5.1",
     "import-sort-cli": "6.0.0",
     "import-sort-style-module": "6.0.0",
     "isomorphic-fetch": "3.0.0",
@@ -65,6 +55,7 @@
     "@types/cookie-parser": "^1.4.3",
     "@types/express": "^4.17.17",
     "@types/jsonwebtoken": "^9.0.2",
+    "@types/koa-compose": "^3.2.5",
     "@types/nodemailer": "^6.4.9",
     "@types/pg": "^8.10.2",
     "@types/uuid": "^9.0.2",
@@ -100,5 +91,19 @@
       "@typescript-eslint/no-shadow": "off",
       "react-hooks/rules-of-hooks": "off"
     }
+  },
+  "peerDependencies": {
+    "faktory-worker": "^4.5.1"
+  },
+  "scripts": {
+    "start": "ts-node --esm example/index.ts",
+    "start:worker": "ts-node --esm example/worker.ts",
+    "clean": "rm -rf dist",
+    "lint": "eslint src",
+    "test": "NODE_ENV=test vitest",
+    "build": "pnpm run clean && tsc --project tsconfig.build.json",
+    "prettier": "prettier --write '**/*.{js,css,md,ts,tsx}'",
+    "import-sort": "import-sort --write '**/*.{js,jsx,ts,tsx}'",
+    "format": "pnpm run import-sort && pnpm run prettier"
   }
-}
+}