time-machine-js-plugin-express 1.0.0

package/README.md

@@ -0,0 +1,71 @@
+# time-machine-js-plugin-express
+
+An Express.js middleware plugin for [`time-machine-js`](https://www.npmjs.com/package/time-machine-js). It allows you to easily manipulate the global server time globally via environment variables or on a per-request basis using HTTP headers.
+
+## Installation
+
+```bash
+npm install time-machine-js-plugin-express
+```
+
+## Usage
+
+### 1. Global Initialization via Environment Variable
+
+You can automatically set the server's time upon initialization by reading from the `TIME_MACHINE_TRAVEL_TO` environment variable.
+
+Make sure your environment variable is set before your app starts:
+
+```bash
+# .env
+TIME_MACHINE_TRAVEL_TO="2020-01-01T00:00:00Z"
+```
+
+Then initialize it in your code:
+
+```typescript
+import { initTimeMachineFromEnv } from "time-machine-js-plugin-express";
+
+// Initialize with a preferred mode ('flowing' or 'frozen')
+initTimeMachineFromEnv({ mode: "flowing" });
+```
+
+### 2. Per-Request Time Travel via Middleware
+
+You can allow clients to travel to a specific time for the duration of a single HTTP request using a custom header. The middleware automatically handles reverting the time back to its previous state after the request finishes.
+
+```typescript
+import express from "express";
+import { timeMachineMiddleware } from "time-machine-js-plugin-express";
+
+const app = express();
+
+// Use the middleware globally or on specific routes
+app.use(
+  timeMachineMiddleware({
+    // Optional: customize the header name (default is 'x-time-traveled-to')
+    headerName: "x-time-traveled-to",
+  }),
+);
+
+app.get("/current-time", (req, res) => {
+  res.json({ time: new Date().toISOString() });
+});
+
+app.listen(3000, () => console.log("Server running on port 3000"));
+```
+
+**Testing the request:**
+
+```bash
+curl -H "x-time-traveled-to: 1999-12-31T23:59:59Z" http://localhost:3000/current-time
+# Output will reflect the traveled time
+```
+
+## Concurrency Note for Node.js
+
+Because `time-machine-js` patches `Date.now()` globally, Node.js applications that process multiple requests concurrently may experience side-effects where one request's modified time bleeds into another request running at the exact same time. This plugin is most optimal for development, testing, and staging environments.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,17 @@
+import { TimeMachineMode } from 'time-machine-js';
+import { Request, Response, NextFunction } from 'express';
+
+interface TimeMachineMiddlewareOptions {
+    /**
+     * Header name to look for to trigger time travel.
+     * @default 'x-time-traveled-to'
+     */
+    headerName?: string;
+}
+interface TimeMachineOptions {
+    mode: TimeMachineMode;
+}
+declare function initTimeMachineFromEnv(config: TimeMachineOptions): void;
+declare function timeMachineMiddleware(options?: TimeMachineMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
+
+export { type TimeMachineMiddlewareOptions, type TimeMachineOptions, initTimeMachineFromEnv, timeMachineMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { TimeMachineMode } from 'time-machine-js';
+import { Request, Response, NextFunction } from 'express';
+
+interface TimeMachineMiddlewareOptions {
+    /**
+     * Header name to look for to trigger time travel.
+     * @default 'x-time-traveled-to'
+     */
+    headerName?: string;
+}
+interface TimeMachineOptions {
+    mode: TimeMachineMode;
+}
+declare function initTimeMachineFromEnv(config: TimeMachineOptions): void;
+declare function timeMachineMiddleware(options?: TimeMachineMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
+
+export { type TimeMachineMiddlewareOptions, type TimeMachineOptions, initTimeMachineFromEnv, timeMachineMiddleware };

package/dist/index.js

@@ -0,0 +1,89 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  initTimeMachineFromEnv: () => initTimeMachineFromEnv,
+  timeMachineMiddleware: () => timeMachineMiddleware
+});
+module.exports = __toCommonJS(index_exports);
+var import_time_machine_js = require("time-machine-js");
+var envTimeSet = false;
+function initTimeMachineFromEnv(config) {
+  if (envTimeSet) return;
+  const envDate = process.env.TIME_MACHINE_TRAVEL_TO;
+  if (envDate) {
+    const timestamp = new Date(envDate).getTime();
+    if (!isNaN(timestamp)) {
+      (0, import_time_machine_js.travel)(timestamp, config.mode);
+      envTimeSet = true;
+    } else {
+      console.warn(
+        `[time-machine-js-plugin-express] Invalid date format in TIME_MACHINE_TRAVEL_TO: ${envDate}`
+      );
+    }
+  }
+}
+function timeMachineMiddleware(options = {}) {
+  const headerName = (options.headerName || "x-time-traveled-to").toLowerCase();
+  return (req, res, next) => {
+    const headerValue = req.headers[headerName];
+    const resolvedHeaderValue = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (!resolvedHeaderValue || typeof resolvedHeaderValue !== "string") {
+      return next();
+    }
+    const targetDate = new Date(resolvedHeaderValue);
+    const targetTimestamp = targetDate.getTime();
+    if (isNaN(targetTimestamp)) {
+      console.warn(
+        `[time-machine-js-plugin-express] Invalid date received in header ${headerName}: ${resolvedHeaderValue}`
+      );
+      return next();
+    }
+    const wasActive = (0, import_time_machine_js.isActive)();
+    const currentMode = (0, import_time_machine_js.getMode)();
+    const currentOffset = (0, import_time_machine_js.getOffset)();
+    let originalTimestamp = null;
+    if (wasActive && currentMode === "flowing" && currentOffset !== null) {
+      originalTimestamp = Date.now();
+    } else if (wasActive && currentMode === "frozen" && currentOffset !== null) {
+      originalTimestamp = currentOffset;
+    }
+    (0, import_time_machine_js.travel)(targetTimestamp, "flowing");
+    let reverted = false;
+    const revertTime = () => {
+      if (reverted) return;
+      if (wasActive && originalTimestamp !== null && currentMode !== null) {
+        (0, import_time_machine_js.travel)(originalTimestamp, currentMode);
+      } else if (!wasActive) {
+        (0, import_time_machine_js.returnToPresent)();
+      }
+      reverted = true;
+    };
+    res.on("finish", revertTime);
+    res.on("close", revertTime);
+    next();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  initTimeMachineFromEnv,
+  timeMachineMiddleware
+});

package/dist/index.mjs

@@ -0,0 +1,69 @@
+// src/index.ts
+import {
+  travel,
+  returnToPresent,
+  getMode,
+  getOffset,
+  isActive
+} from "time-machine-js";
+var envTimeSet = false;
+function initTimeMachineFromEnv(config) {
+  if (envTimeSet) return;
+  const envDate = process.env.TIME_MACHINE_TRAVEL_TO;
+  if (envDate) {
+    const timestamp = new Date(envDate).getTime();
+    if (!isNaN(timestamp)) {
+      travel(timestamp, config.mode);
+      envTimeSet = true;
+    } else {
+      console.warn(
+        `[time-machine-js-plugin-express] Invalid date format in TIME_MACHINE_TRAVEL_TO: ${envDate}`
+      );
+    }
+  }
+}
+function timeMachineMiddleware(options = {}) {
+  const headerName = (options.headerName || "x-time-traveled-to").toLowerCase();
+  return (req, res, next) => {
+    const headerValue = req.headers[headerName];
+    const resolvedHeaderValue = Array.isArray(headerValue) ? headerValue[0] : headerValue;
+    if (!resolvedHeaderValue || typeof resolvedHeaderValue !== "string") {
+      return next();
+    }
+    const targetDate = new Date(resolvedHeaderValue);
+    const targetTimestamp = targetDate.getTime();
+    if (isNaN(targetTimestamp)) {
+      console.warn(
+        `[time-machine-js-plugin-express] Invalid date received in header ${headerName}: ${resolvedHeaderValue}`
+      );
+      return next();
+    }
+    const wasActive = isActive();
+    const currentMode = getMode();
+    const currentOffset = getOffset();
+    let originalTimestamp = null;
+    if (wasActive && currentMode === "flowing" && currentOffset !== null) {
+      originalTimestamp = Date.now();
+    } else if (wasActive && currentMode === "frozen" && currentOffset !== null) {
+      originalTimestamp = currentOffset;
+    }
+    travel(targetTimestamp, "flowing");
+    let reverted = false;
+    const revertTime = () => {
+      if (reverted) return;
+      if (wasActive && originalTimestamp !== null && currentMode !== null) {
+        travel(originalTimestamp, currentMode);
+      } else if (!wasActive) {
+        returnToPresent();
+      }
+      reverted = true;
+    };
+    res.on("finish", revertTime);
+    res.on("close", revertTime);
+    next();
+  };
+}
+export {
+  initTimeMachineFromEnv,
+  timeMachineMiddleware
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "time-machine-js-plugin-express",
+  "version": "1.0.0",
+  "main": "./dist/index.js",
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test:watch": "vitest start"
+  },
+  "keywords": [],
+  "author": "williamp29 <williamp.olmos@gmail.com>",
+  "license": "MIT",
+  "description": "Express middleware for time-machine-js",
+  "dependencies": {
+    "time-machine-js": "^1.1.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.3.0",
+    "@types/supertest": "^6.0.3",
+    "express": "^5.2.1",
+    "supertest": "^7.2.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "express": "^4.17.1 || ^5.0.0",
+    "time-machine-js": "^1.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WilliamPinto-Olmos/time-machine-js-plugin-express.git"
+  },
+  "bugs": {
+    "url": "https://github.com/WilliamPinto-Olmos/time-machine-js-plugin-express/issues"
+  },
+  "homepage": "https://github.com/WilliamPinto-Olmos/time-machine-js-plugin-express#readme",
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}