@devmoods/express-extras 0.56.0 → 0.57.1

package/README.md

@@ -1,33 +1,101 @@
 # @devmoods/express-extras
 
-> Kubernetes-ready utilities for rapid Node.js application development
+> Express evolved: Type-safe routing, elegant transactions, and production-ready patterns for modern Node.js
 
 _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.
 
 - 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`
+- Thin layer on top of [Express](https://expressjs.com) with better support for `async`/`await` and type safety.
+
+```typescript
+const router = createRouter();
+
+router.put(
+  '/posts/:id',
+  {
+    request: type({ title: 'string' }),
+    response: type({ id: 'number', title: 'string' }),
+  },
+  async (req) => {
+    await delay(1000);
+    return {
+      id: req.params.id,
+      ...req.body,
+    };
+  },
+);
+```
+
+- Clean graceful shutdown procedures and built-in health checks. Runs perfectly in Kubernetes.
 - PostgreSQL with transactions and migrations
+
+```bash
+bin/dx manage migrate up
+```
+
+```typescript
+await postgres.transaction(() => {
+  const post = await postgres.get<{ title: string }>(
+    sql`SELECT title FROM posts WHERE id = ${id} FOR UPDATE`,
+  );
+
+  await postgres.query(
+    sql`UPDATE posts SET ${sql.spreadUpdate({ title: post.title.split('').reverse().join('') })} WHERE id = ${id}`,
+  );
+
+  try {
+    // Nested transactions with savepoints
+    await postgres.transaction(() => {
+    })
+  } catch () {
+  }
+
+  throw new Error('please rollback');
+});
+```
+
+- CSRF protection
+- Built in auth backends! Email+password, passwordless, easy to extend with more
+- OpenAPI v3 generator
 - Redis
-- Slack (and Discord) client for sending operational notifications
+- Slack/Discord client for sending operational notifications
 - CLI commands inspired by Django's management commands
-- Delayed jobs with [Faktory](https://contribsys.com/faktory/)
-- Validation of HTTP requests using [JSON Schema](https://json-schema.org/)s
+
+```bash
+bin/dx manage --help
+```
+
+```typescript
+registerManagementCommand((command, cli) => {
+  command('hello').action(() => {
+    cli.writeLine('Hello World');
+  });
+});
+```
+
+- Delayed/async jobs with [Faktory](https://contribsys.com/faktory/)
+- Validation of HTTP requests using [Standard Schema](https://github.com/standard-schema/standard-schema), including [`jsonSchema()`](https://json-schema.org/) and [arktype](https://arktype.io/).
 - Logging helpers to write well-formatted contextual JSON logs to `stdout`
+
+```typescript
+const logger = getLogger();
+
+logger.info('hello world', { foo: 'bar', baz: 10 });
+// {"level":"info","hostname":"machine.local","pid":43149,"name":"default","message":"hello world","foo":"bar","baz":10,"time":"2024-01-02T17:25:28.610Z","v":1}
+```
+
 - Request local context using [AsyncLocalStorage](https://nodejs.org/api/async_context.html) (e.g. request ids)
 - [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
+- [The Twelve-Factor App](https://12factor.net/)
 
 ## Goals
 
-- Time-to-market
+- Time-to-market and top-notch developer experience.
 
 ## Non-goals
 
-- _Encourage deviating from the chosen path_
+- Support for multiple different database vendors and job processing systems.
 
 ## Example
 

package/dist/auth/token.js

@@ -105,6 +105,7 @@ export function setAccessTokenCookie(res, token) {
     }
     else {
         res.cookie(ACCESS_TOKEN_COOKIE_NAME, token, {
+            expires: new Date(Date.now() + config.value.AUTH_TOKEN_EXPIRES_IN * 1000),
             httpOnly: true,
             sameSite,
             secure: process.env.NODE_ENV === 'production',

package/dist/router.d.ts

@@ -19,19 +19,19 @@ export declare class TypedRouter {
     get<Path extends string, RequestBodySchema extends StandardSchemaV1<any> | undefined = undefined, ResponseBodySchema extends StandardSchemaV1<any> | undefined = undefined, RequestQuerySchema extends StandardSchemaV1<any> | undefined = undefined>(path: Path, validation: ValidationSpec<RequestBodySchema, ResponseBodySchema, RequestQuerySchema>, ...middleware: [
         ...RequestHandler[],
         TypedRequestHandler<ExtractParams<Path>, ResponseBodySchema, RequestBodySchema, RequestQuerySchema>
-    ]): void;
+    ]): this;
     post<Path extends string, RequestBodySchema extends StandardSchemaV1<any> | undefined = undefined, ResponseBodySchema extends StandardSchemaV1<any> | undefined = undefined, RequestQuerySchema extends StandardSchemaV1<any> | undefined = undefined>(path: Path, validation: ValidationSpec<RequestBodySchema, ResponseBodySchema, RequestQuerySchema>, ...middleware: [
         ...RequestHandler[],
         TypedRequestHandler<ExtractParams<Path>, ResponseBodySchema, RequestBodySchema, RequestQuerySchema>
-    ]): void;
+    ]): this;
     put<Path extends string, RequestBodySchema extends StandardSchemaV1<any> | undefined = undefined, ResponseBodySchema extends StandardSchemaV1<any> | undefined = undefined, RequestQuerySchema extends StandardSchemaV1<any> | undefined = undefined>(path: Path, validation: ValidationSpec<RequestBodySchema, ResponseBodySchema, RequestQuerySchema>, ...middleware: [
         ...RequestHandler[],
         TypedRequestHandler<ExtractParams<Path>, ResponseBodySchema, RequestBodySchema, RequestQuerySchema>
-    ]): void;
+    ]): this;
     delete<Path extends string, RequestBodySchema extends StandardSchemaV1<any> | undefined = undefined, ResponseBodySchema extends StandardSchemaV1<any> | undefined = undefined, RequestQuerySchema extends StandardSchemaV1<any> | undefined = undefined>(path: Path, validation: ValidationSpec<RequestBodySchema, ResponseBodySchema, RequestQuerySchema>, ...middleware: [
         ...RequestHandler[],
         TypedRequestHandler<ExtractParams<Path>, ResponseBodySchema, RequestBodySchema, RequestQuerySchema>
-    ]): void;
+    ]): this;
     use(...middleware: RequestHandler[]): this;
     use(...middleware: [string, ...RequestHandler[]]): this;
     getRouter(): import("express-serve-static-core").Router;

package/dist/router.js

@@ -23,6 +23,7 @@ export class TypedRouter {
             query: validation.query,
             response: validation.response,
         }), ...middleware, asyncMiddleware(handler));
+        return this;
     }
     use(...middleware) {
         this.router.use(...middleware);

package/dist/validate.js

@@ -104,6 +104,7 @@ export function jsonSchema(schema) {
     const ajv = new Ajv({
         allErrors: true,
         validateFormats: false,
+        coerceTypes: true,
     });
     ajv.addKeyword('$enumNames');
     ajv.addKeyword('$bitiforms');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devmoods/express-extras",
-  "version": "0.56.0",
+  "version": "0.57.1",
   "description": "Kubernetes-ready utilities for rapid Node.js application development",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,7 +44,7 @@
   ],
   "license": "ISC",
   "devDependencies": {
-    "@devmoods/eslint-config": "^2.6.0",
+    "@devmoods/eslint-config": "^2.7.0",
     "@types/koa-compose": "^3.2.8",
     "@types/node": "22.13.10",
     "@types/supertest": "^6.0.2",