time-machine-js 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# time-machine-js
+
+A zero-dependency, framework-agnostic utility that monkey-patches `Date.now()` globally to simulate a different point in time. Works identically in browser and Node.js environments.
+
+## Features
+
+- **Zero dependencies**: No external dependencies required.
+- **Framework agnostic**: Use it with React, Vue, Vanilla JS, or Node.js.
+- **Global patch**: Affects `Date.now()` globally, ensuring `new Date()` and other time-dependent utilities work as expected.
+- **Dual Exports**: Ships with both ESM and CJS support.
+- **TypeScript**: Fully typed with included definitions.
+
+## Installation
+
+```bash
+npm install time-machine-js
+```
+
+## API
+
+The core API consists of four main functions:
+
+### `travel(timestamp: number, mode: 'flowing' | 'frozen'): void`
+Moves the environment time to the specified Unix timestamp.
+- `flowing`: Time continues to advance normally from the specified point.
+- `frozen`: Time remains fixed at the specify timestamp.
+
+### `returnToPresent(): void`
+Restores the original `Date.now` and clears internal state.
+
+### `getOffset(): number | null`
+Returns the current offset in ms (flowing mode) or the frozen timestamp (frozen mode). Returns `null` if inactive.
+
+### `isActive(): boolean`
+Returns `true` if the time machine is currently active.
+
+## Persistence (Browser Only)
+
+For environments with `localStorage`, you can manually save and restore the time machine state across page reloads:
+
+### `save(storageKey?: string): void`
+Writes the current mode and offset/timestamp to `localStorage`. Defaults to `__timeMachine__`.
+
+### `restore(storageKey?: string): boolean`
+Reads the state from `localStorage` and activates it. Returns `true` if a state was found and applied.
+
+## Usage
+
+### Basic Example
+```javascript
+import { travel, returnToPresent } from 'time-machine-js';
+
+// Travel to Jan 1st, 2025
+travel(new Date('2025-01-01').getTime(), 'frozen');
+console.log(new Date().toISOString()); // 2025-01-01T00:00:00.000Z
+
+returnToPresent();
+console.log(new Date().getFullYear()); // Current year
+```
+
+### Persistence
+```javascript
+import { restore, save, travel } from 'time-machine-js';
+
+// On app initialization
+restore();
+
+// Later
+travel(Date.now() + 3600000, 'flowing');
+save();
+```
+
+## Caveats
+
+### `new Date()`
+In most modern JavaScript environments (V8, Node.js), the `Date` constructor uses `Date.now()` internally to determine the current time. This means monkey-patching `Date.now()` is sufficient to "travel" for both `Date.now()` and `new Date()`.
+
+### `performance.now()`
+`performance.now()` is **not** patched by this utility, as it represents a monotonic clock used for high-resolution profiling rather than wall-clock time.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,48 @@
+/**
+ * Valid modes for the time machine.
+ * - 'flowing': Time continues to advance normally but from a specified offset.
+ * - 'frozen': Time remains fixed at the specify timestamp.
+ */
+type TimeMachineMode = 'flowing' | 'frozen';
+/**
+ * Monkey-patches Date.now() to simulate a different point in time.
+ *
+ * @param timestamp - The Unix timestamp in milliseconds to travel to.
+ * @param mode - The mode of travel: 'flowing' or 'frozen'.
+ *
+ * @example
+ * travel(new Date('2025-01-01').getTime(), 'frozen');
+ */
+declare function travel(timestamp: number, mode: TimeMachineMode): void;
+/**
+ * Restores the original Date.now and clears the internal state.
+ */
+declare function returnToPresent(): void;
+/**
+ * Returns the current offset in milliseconds when in 'flowing' mode,
+ * the frozen timestamp when in 'frozen' mode, or null if inactive.
+ *
+ * @returns The offset, frozen timestamp, or null.
+ */
+declare function getOffset(): number | null;
+/**
+ * Returns whether the time machine is currently active.
+ *
+ * @returns True if active, false otherwise.
+ */
+declare function isActive(): boolean;
+/**
+ * Saves the current time machine state to localStorage (browser only).
+ *
+ * @param storageKey - The key to use in localStorage. Defaults to '__timeMachine__'.
+ */
+declare function save(storageKey?: string): void;
+/**
+ * Restores the time machine state from localStorage (browser only).
+ *
+ * @param storageKey - The key to search for in localStorage. Defaults to '__timeMachine__'.
+ * @returns True if state was found and restored, false otherwise.
+ */
+declare function restore(storageKey?: string): boolean;
+
+export { type TimeMachineMode, getOffset, isActive, restore, returnToPresent, save, travel };

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Valid modes for the time machine.
+ * - 'flowing': Time continues to advance normally but from a specified offset.
+ * - 'frozen': Time remains fixed at the specify timestamp.
+ */
+type TimeMachineMode = 'flowing' | 'frozen';
+/**
+ * Monkey-patches Date.now() to simulate a different point in time.
+ *
+ * @param timestamp - The Unix timestamp in milliseconds to travel to.
+ * @param mode - The mode of travel: 'flowing' or 'frozen'.
+ *
+ * @example
+ * travel(new Date('2025-01-01').getTime(), 'frozen');
+ */
+declare function travel(timestamp: number, mode: TimeMachineMode): void;
+/**
+ * Restores the original Date.now and clears the internal state.
+ */
+declare function returnToPresent(): void;
+/**
+ * Returns the current offset in milliseconds when in 'flowing' mode,
+ * the frozen timestamp when in 'frozen' mode, or null if inactive.
+ *
+ * @returns The offset, frozen timestamp, or null.
+ */
+declare function getOffset(): number | null;
+/**
+ * Returns whether the time machine is currently active.
+ *
+ * @returns True if active, false otherwise.
+ */
+declare function isActive(): boolean;
+/**
+ * Saves the current time machine state to localStorage (browser only).
+ *
+ * @param storageKey - The key to use in localStorage. Defaults to '__timeMachine__'.
+ */
+declare function save(storageKey?: string): void;
+/**
+ * Restores the time machine state from localStorage (browser only).
+ *
+ * @param storageKey - The key to search for in localStorage. Defaults to '__timeMachine__'.
+ * @returns True if state was found and restored, false otherwise.
+ */
+declare function restore(storageKey?: string): boolean;
+
+export { type TimeMachineMode, getOffset, isActive, restore, returnToPresent, save, travel };

package/dist/index.js

@@ -0,0 +1,98 @@
+"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, {
+  getOffset: () => getOffset,
+  isActive: () => isActive,
+  restore: () => restore,
+  returnToPresent: () => returnToPresent,
+  save: () => save,
+  travel: () => travel
+});
+module.exports = __toCommonJS(index_exports);
+var _realDateNow = Date.now.bind(Date);
+var state = {
+  isActive: false,
+  mode: null,
+  offset: null,
+  frozenTimestamp: null
+};
+function travel(timestamp, mode) {
+  state.isActive = true;
+  state.mode = mode;
+  if (mode === "frozen") {
+    state.frozenTimestamp = timestamp;
+    state.offset = null;
+    Date.now = () => state.frozenTimestamp;
+  } else {
+    state.frozenTimestamp = null;
+    state.offset = timestamp - _realDateNow();
+    Date.now = () => _realDateNow() + state.offset;
+  }
+}
+function returnToPresent() {
+  state.isActive = false;
+  state.mode = null;
+  state.offset = null;
+  state.frozenTimestamp = null;
+  Date.now = _realDateNow;
+}
+function getOffset() {
+  if (!state.isActive) return null;
+  return state.mode === "frozen" ? state.frozenTimestamp : state.offset;
+}
+function isActive() {
+  return state.isActive;
+}
+function save(storageKey = "__timeMachine__") {
+  if (typeof localStorage === "undefined" || !state.isActive) return;
+  const savedState = {
+    mode: state.mode,
+    value: state.mode === "frozen" ? state.frozenTimestamp : state.offset
+  };
+  localStorage.setItem(storageKey, JSON.stringify(savedState));
+}
+function restore(storageKey = "__timeMachine__") {
+  if (typeof localStorage === "undefined") return false;
+  const data = localStorage.getItem(storageKey);
+  if (!data) return false;
+  try {
+    const savedState = JSON.parse(data);
+    if (savedState.mode === "frozen") {
+      travel(savedState.value, "frozen");
+    } else {
+      const targetTimestamp = _realDateNow() + savedState.value;
+      travel(targetTimestamp, "flowing");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getOffset,
+  isActive,
+  restore,
+  returnToPresent,
+  save,
+  travel
+});

package/dist/index.mjs

@@ -0,0 +1,68 @@
+// src/index.ts
+var _realDateNow = Date.now.bind(Date);
+var state = {
+  isActive: false,
+  mode: null,
+  offset: null,
+  frozenTimestamp: null
+};
+function travel(timestamp, mode) {
+  state.isActive = true;
+  state.mode = mode;
+  if (mode === "frozen") {
+    state.frozenTimestamp = timestamp;
+    state.offset = null;
+    Date.now = () => state.frozenTimestamp;
+  } else {
+    state.frozenTimestamp = null;
+    state.offset = timestamp - _realDateNow();
+    Date.now = () => _realDateNow() + state.offset;
+  }
+}
+function returnToPresent() {
+  state.isActive = false;
+  state.mode = null;
+  state.offset = null;
+  state.frozenTimestamp = null;
+  Date.now = _realDateNow;
+}
+function getOffset() {
+  if (!state.isActive) return null;
+  return state.mode === "frozen" ? state.frozenTimestamp : state.offset;
+}
+function isActive() {
+  return state.isActive;
+}
+function save(storageKey = "__timeMachine__") {
+  if (typeof localStorage === "undefined" || !state.isActive) return;
+  const savedState = {
+    mode: state.mode,
+    value: state.mode === "frozen" ? state.frozenTimestamp : state.offset
+  };
+  localStorage.setItem(storageKey, JSON.stringify(savedState));
+}
+function restore(storageKey = "__timeMachine__") {
+  if (typeof localStorage === "undefined") return false;
+  const data = localStorage.getItem(storageKey);
+  if (!data) return false;
+  try {
+    const savedState = JSON.parse(data);
+    if (savedState.mode === "frozen") {
+      travel(savedState.value, "frozen");
+    } else {
+      const targetTimestamp = _realDateNow() + savedState.value;
+      travel(targetTimestamp, "flowing");
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+export {
+  getOffset,
+  isActive,
+  restore,
+  returnToPresent,
+  save,
+  travel
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "time-machine-js",
+  "version": "1.0.0",
+  "description": "A zero-dependency utility to monkey-patch Date.now() globally.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "time",
+    "travel",
+    "date",
+    "manipulation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.2",
+    "typescript": "^5.3.3",
+    "vitest": "^1.3.1"
+  }
+}