@deciosfernandes/uuidv7-timestamp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 deciosfernandes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @deciosfernandes/uuidv7-timestamp
+
+Extract epoch timestamp from UUID v7 strings (TypeScript).
+
+This tiny library extracts the timestamp encoded in UUID v7 values (the first 48 bits / first 12 hex chars) and returns it as milliseconds, a Date, or an ISO string.
+
+## Installation
+
+npm:
+```bash
+npm install @deciosfernandes/uuidv7-timestamp
+```
+
+yarn:
+```bash
+yarn add @deciosfernandes/uuidv7-timestamp
+```
+
+## Usage
+
+```ts
+import { extractTimestampFromUuidV7, extractTimestampAsDate } from '@deciosfernandes/uuidv7-timestamp';
+
+const uuid = '017f7f58-89ab-7000-8123-0123456789ab';
+const millis = extractTimestampFromUuidV7(uuid);
+const date = extractTimestampAsDate(uuid);
+console.log(millis, date.toISOString());
+```
+
+## API
+
+- extractTimestampFromUuidV7(uuid: string): number — returns epoch milliseconds encoded in the UUID v7.
+- extractTimestampAsDate(uuid: string): Date — returns a Date instance.
+- extractTimestampAsISOString(uuid: string): string — returns an ISO 8601 string.
+
+## Notes
+
+- The function validates the UUID format and ensures the version nibble is `7`. If the UUID is not v7, an Error is thrown.
+- The timestamp is assumed to be the first 48 bits of the UUID per the v7 draft layout.
+
+## License
+
+MIT

package/dist/index.cjs.js

@@ -0,0 +1,76 @@
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+/**
+ * Extract timestamp from UUID v7 strings.
+ *
+ * The timestamp for UUID v7 is encoded in the first 48 bits (12 hex chars) of the UUID.
+ * This module exposes three helpers:
+ * - extractTimestampFromUuidV7(uuid): number (epoch millis)
+ * - extractTimestampAsDate(uuid): Date
+ * - extractTimestampAsISOString(uuid): string
+ */
+const HEX_32_RE = /^[0-9a-fA-F]{32}$/;
+/**
+ * Extracts the epoch milliseconds timestamp from a UUID v7 string.
+ * Caller must pass a UUID v7 (validation is performed and an error thrown if it's not v7).
+ *
+ * @param uuid - UUID string (hyphenated or not)
+ * @returns epoch milliseconds (number)
+ * @throws Error if input is not a valid UUID string or not version 7
+ */
+function extractTimestampFromUuidV7(uuid) {
+    if (typeof uuid !== 'string' || uuid.length === 0) {
+        throw new Error('uuid must be a non-empty string');
+    }
+    // Normalize: remove hyphens
+    const normalized = uuid.replace(/-/g, '');
+    if (!HEX_32_RE.test(normalized)) {
+        throw new Error('invalid UUID format');
+    }
+    // Version nibble is the first hex char of the 3rd UUID segment.
+    // In the normalized string it's at index 12 (0-based).
+    const versionChar = normalized[12];
+    if (versionChar !== '7') {
+        throw new Error(`expected UUID v7 (version nibble = 7), got version nibble = ${versionChar}`);
+    }
+    // Timestamp for UUID v7 is the top 48 bits: time_low (8 hex) + time_mid (4 hex) => first 12 hex chars
+    const timeHex = normalized.slice(0, 12); // 12 hex chars => 48 bits
+    const millisBig = BigInt(`0x${timeHex}`);
+    const millis = Number(millisBig);
+    if (!Number.isFinite(millis)) {
+        throw new Error('extracted timestamp is not a finite number');
+    }
+    return millis;
+}
+/**
+ * Same as extractTimestampFromUuidV7 but returns a Date instance.
+ *
+ * @param uuid - UUID v7 string
+ * @returns Date representing the timestamp encoded in the UUID
+ */
+function extractTimestampAsDate(uuid) {
+    const ms = extractTimestampFromUuidV7(uuid);
+    return new Date(ms);
+}
+/**
+ * Convenience: returns an ISO string for the timestamp contained in the UUID v7.
+ *
+ * @param uuid - UUID v7 string
+ * @returns ISO 8601 string (UTC)
+ */
+function extractTimestampAsISOString(uuid) {
+    return extractTimestampAsDate(uuid).toISOString();
+}
+var index = {
+    extractTimestampFromUuidV7,
+    extractTimestampAsDate,
+    extractTimestampAsISOString
+};
+
+exports.default = index;
+exports.extractTimestampAsDate = extractTimestampAsDate;
+exports.extractTimestampAsISOString = extractTimestampAsISOString;
+exports.extractTimestampFromUuidV7 = extractTimestampFromUuidV7;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * Extract timestamp from UUID v7 strings.\n *\n * The timestamp for UUID v7 is encoded in the first 48 bits (12 hex chars) of the UUID.\n * This module exposes three helpers:\n * - extractTimestampFromUuidV7(uuid): number (epoch millis)\n * - extractTimestampAsDate(uuid): Date\n * - extractTimestampAsISOString(uuid): string\n */\n\nconst HEX_32_RE = /^[0-9a-fA-F]{32}$/;\n\n/**\n * Extracts the epoch milliseconds timestamp from a UUID v7 string.\n * Caller must pass a UUID v7 (validation is performed and an error thrown if it's not v7).\n *\n * @param uuid - UUID string (hyphenated or not)\n * @returns epoch milliseconds (number)\n * @throws Error if input is not a valid UUID string or not version 7\n */\nexport function extractTimestampFromUuidV7(uuid: string): number {\n  if (typeof uuid !== 'string' || uuid.length === 0) {\n    throw new Error('uuid must be a non-empty string');\n  }\n\n  // Normalize: remove hyphens\n  const normalized = uuid.replace(/-/g, '');\n\n  if (!HEX_32_RE.test(normalized)) {\n    throw new Error('invalid UUID format');\n  }\n\n  // Version nibble is the first hex char of the 3rd UUID segment.\n  // In the normalized string it's at index 12 (0-based).\n  const versionChar = normalized[12];\n  if (versionChar !== '7') {\n    throw new Error(`expected UUID v7 (version nibble = 7), got version nibble = ${versionChar}`);\n  }\n\n  // Timestamp for UUID v7 is the top 48 bits: time_low (8 hex) + time_mid (4 hex) => first 12 hex chars\n  const timeHex = normalized.slice(0, 12); // 12 hex chars => 48 bits\n  const millisBig = BigInt(`0x${timeHex}`);\n  const millis = Number(millisBig);\n\n  if (!Number.isFinite(millis)) {\n    throw new Error('extracted timestamp is not a finite number');\n  }\n\n  return millis;\n}\n\n/**\n * Same as extractTimestampFromUuidV7 but returns a Date instance.\n *\n * @param uuid - UUID v7 string\n * @returns Date representing the timestamp encoded in the UUID\n */\nexport function extractTimestampAsDate(uuid: string): Date {\n  const ms = extractTimestampFromUuidV7(uuid);\n  return new Date(ms);\n}\n\n/**\n * Convenience: returns an ISO string for the timestamp contained in the UUID v7.\n *\n * @param uuid - UUID v7 string\n * @returns ISO 8601 string (UTC)\n */\nexport function extractTimestampAsISOString(uuid: string): string {\n  return extractTimestampAsDate(uuid).toISOString();\n}\n\nexport default {\n  extractTimestampFromUuidV7,\n  extractTimestampAsDate,\n  extractTimestampAsISOString\n};"],"names":[],"mappings":";;;;AAAA;;;;;;;;AAQG;AAEH,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;;;;;AAOG;AACG,SAAU,0BAA0B,CAAC,IAAY,EAAA;IACrD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;AACjD,QAAA,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;KACpD;;IAGD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAE1C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;AAC/B,QAAA,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;KACxC;;;AAID,IAAA,MAAM,WAAW,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;AACnC,IAAA,IAAI,WAAW,KAAK,GAAG,EAAE;AACvB,QAAA,MAAM,IAAI,KAAK,CAAC,+DAA+D,WAAW,CAAA,CAAE,CAAC,CAAC;KAC/F;;AAGD,IAAA,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,OAAO,CAAA,CAAE,CAAC,CAAC;AACzC,IAAA,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAEjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;AAC5B,QAAA,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;KAC/D;AAED,IAAA,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;AAKG;AACG,SAAU,sBAAsB,CAAC,IAAY,EAAA;AACjD,IAAA,MAAM,EAAE,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;AAC5C,IAAA,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED;;;;;AAKG;AACG,SAAU,2BAA2B,CAAC,IAAY,EAAA;AACtD,IAAA,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AACpD,CAAC;AAED,YAAe;IACb,0BAA0B;IAC1B,sBAAsB;IACtB,2BAA2B;CAC5B;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Extract timestamp from UUID v7 strings.
+ *
+ * The timestamp for UUID v7 is encoded in the first 48 bits (12 hex chars) of the UUID.
+ * This module exposes three helpers:
+ * - extractTimestampFromUuidV7(uuid): number (epoch millis)
+ * - extractTimestampAsDate(uuid): Date
+ * - extractTimestampAsISOString(uuid): string
+ */
+/**
+ * Extracts the epoch milliseconds timestamp from a UUID v7 string.
+ * Caller must pass a UUID v7 (validation is performed and an error thrown if it's not v7).
+ *
+ * @param uuid - UUID string (hyphenated or not)
+ * @returns epoch milliseconds (number)
+ * @throws Error if input is not a valid UUID string or not version 7
+ */
+declare function extractTimestampFromUuidV7(uuid: string): number;
+/**
+ * Same as extractTimestampFromUuidV7 but returns a Date instance.
+ *
+ * @param uuid - UUID v7 string
+ * @returns Date representing the timestamp encoded in the UUID
+ */
+declare function extractTimestampAsDate(uuid: string): Date;
+/**
+ * Convenience: returns an ISO string for the timestamp contained in the UUID v7.
+ *
+ * @param uuid - UUID v7 string
+ * @returns ISO 8601 string (UTC)
+ */
+declare function extractTimestampAsISOString(uuid: string): string;
+declare const _default: {
+    extractTimestampFromUuidV7: typeof extractTimestampFromUuidV7;
+    extractTimestampAsDate: typeof extractTimestampAsDate;
+    extractTimestampAsISOString: typeof extractTimestampAsISOString;
+};
+
+export { _default as default, extractTimestampAsDate, extractTimestampAsISOString, extractTimestampFromUuidV7 };

package/dist/index.esm.js

@@ -0,0 +1,69 @@
+/**
+ * Extract timestamp from UUID v7 strings.
+ *
+ * The timestamp for UUID v7 is encoded in the first 48 bits (12 hex chars) of the UUID.
+ * This module exposes three helpers:
+ * - extractTimestampFromUuidV7(uuid): number (epoch millis)
+ * - extractTimestampAsDate(uuid): Date
+ * - extractTimestampAsISOString(uuid): string
+ */
+const HEX_32_RE = /^[0-9a-fA-F]{32}$/;
+/**
+ * Extracts the epoch milliseconds timestamp from a UUID v7 string.
+ * Caller must pass a UUID v7 (validation is performed and an error thrown if it's not v7).
+ *
+ * @param uuid - UUID string (hyphenated or not)
+ * @returns epoch milliseconds (number)
+ * @throws Error if input is not a valid UUID string or not version 7
+ */
+function extractTimestampFromUuidV7(uuid) {
+    if (typeof uuid !== 'string' || uuid.length === 0) {
+        throw new Error('uuid must be a non-empty string');
+    }
+    // Normalize: remove hyphens
+    const normalized = uuid.replace(/-/g, '');
+    if (!HEX_32_RE.test(normalized)) {
+        throw new Error('invalid UUID format');
+    }
+    // Version nibble is the first hex char of the 3rd UUID segment.
+    // In the normalized string it's at index 12 (0-based).
+    const versionChar = normalized[12];
+    if (versionChar !== '7') {
+        throw new Error(`expected UUID v7 (version nibble = 7), got version nibble = ${versionChar}`);
+    }
+    // Timestamp for UUID v7 is the top 48 bits: time_low (8 hex) + time_mid (4 hex) => first 12 hex chars
+    const timeHex = normalized.slice(0, 12); // 12 hex chars => 48 bits
+    const millisBig = BigInt(`0x${timeHex}`);
+    const millis = Number(millisBig);
+    if (!Number.isFinite(millis)) {
+        throw new Error('extracted timestamp is not a finite number');
+    }
+    return millis;
+}
+/**
+ * Same as extractTimestampFromUuidV7 but returns a Date instance.
+ *
+ * @param uuid - UUID v7 string
+ * @returns Date representing the timestamp encoded in the UUID
+ */
+function extractTimestampAsDate(uuid) {
+    const ms = extractTimestampFromUuidV7(uuid);
+    return new Date(ms);
+}
+/**
+ * Convenience: returns an ISO string for the timestamp contained in the UUID v7.
+ *
+ * @param uuid - UUID v7 string
+ * @returns ISO 8601 string (UTC)
+ */
+function extractTimestampAsISOString(uuid) {
+    return extractTimestampAsDate(uuid).toISOString();
+}
+var index = {
+    extractTimestampFromUuidV7,
+    extractTimestampAsDate,
+    extractTimestampAsISOString
+};
+
+export { index as default, extractTimestampAsDate, extractTimestampAsISOString, extractTimestampFromUuidV7 };
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.esm.js","sources":["../src/index.ts"],"sourcesContent":["/**\n * Extract timestamp from UUID v7 strings.\n *\n * The timestamp for UUID v7 is encoded in the first 48 bits (12 hex chars) of the UUID.\n * This module exposes three helpers:\n * - extractTimestampFromUuidV7(uuid): number (epoch millis)\n * - extractTimestampAsDate(uuid): Date\n * - extractTimestampAsISOString(uuid): string\n */\n\nconst HEX_32_RE = /^[0-9a-fA-F]{32}$/;\n\n/**\n * Extracts the epoch milliseconds timestamp from a UUID v7 string.\n * Caller must pass a UUID v7 (validation is performed and an error thrown if it's not v7).\n *\n * @param uuid - UUID string (hyphenated or not)\n * @returns epoch milliseconds (number)\n * @throws Error if input is not a valid UUID string or not version 7\n */\nexport function extractTimestampFromUuidV7(uuid: string): number {\n  if (typeof uuid !== 'string' || uuid.length === 0) {\n    throw new Error('uuid must be a non-empty string');\n  }\n\n  // Normalize: remove hyphens\n  const normalized = uuid.replace(/-/g, '');\n\n  if (!HEX_32_RE.test(normalized)) {\n    throw new Error('invalid UUID format');\n  }\n\n  // Version nibble is the first hex char of the 3rd UUID segment.\n  // In the normalized string it's at index 12 (0-based).\n  const versionChar = normalized[12];\n  if (versionChar !== '7') {\n    throw new Error(`expected UUID v7 (version nibble = 7), got version nibble = ${versionChar}`);\n  }\n\n  // Timestamp for UUID v7 is the top 48 bits: time_low (8 hex) + time_mid (4 hex) => first 12 hex chars\n  const timeHex = normalized.slice(0, 12); // 12 hex chars => 48 bits\n  const millisBig = BigInt(`0x${timeHex}`);\n  const millis = Number(millisBig);\n\n  if (!Number.isFinite(millis)) {\n    throw new Error('extracted timestamp is not a finite number');\n  }\n\n  return millis;\n}\n\n/**\n * Same as extractTimestampFromUuidV7 but returns a Date instance.\n *\n * @param uuid - UUID v7 string\n * @returns Date representing the timestamp encoded in the UUID\n */\nexport function extractTimestampAsDate(uuid: string): Date {\n  const ms = extractTimestampFromUuidV7(uuid);\n  return new Date(ms);\n}\n\n/**\n * Convenience: returns an ISO string for the timestamp contained in the UUID v7.\n *\n * @param uuid - UUID v7 string\n * @returns ISO 8601 string (UTC)\n */\nexport function extractTimestampAsISOString(uuid: string): string {\n  return extractTimestampAsDate(uuid).toISOString();\n}\n\nexport default {\n  extractTimestampFromUuidV7,\n  extractTimestampAsDate,\n  extractTimestampAsISOString\n};"],"names":[],"mappings":"AAAA;;;;;;;;AAQG;AAEH,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;;;;;AAOG;AACG,SAAU,0BAA0B,CAAC,IAAY,EAAA;IACrD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE;AACjD,QAAA,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;KACpD;;IAGD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAE1C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE;AAC/B,QAAA,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;KACxC;;;AAID,IAAA,MAAM,WAAW,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;AACnC,IAAA,IAAI,WAAW,KAAK,GAAG,EAAE;AACvB,QAAA,MAAM,IAAI,KAAK,CAAC,+DAA+D,WAAW,CAAA,CAAE,CAAC,CAAC;KAC/F;;AAGD,IAAA,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,CAAC,KAAK,OAAO,CAAA,CAAE,CAAC,CAAC;AACzC,IAAA,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAEjC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;AAC5B,QAAA,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;KAC/D;AAED,IAAA,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;AAKG;AACG,SAAU,sBAAsB,CAAC,IAAY,EAAA;AACjD,IAAA,MAAM,EAAE,GAAG,0BAA0B,CAAC,IAAI,CAAC,CAAC;AAC5C,IAAA,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;AACtB,CAAC;AAED;;;;;AAKG;AACG,SAAU,2BAA2B,CAAC,IAAY,EAAA;AACtD,IAAA,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;AACpD,CAAC;AAED,YAAe;IACb,0BAA0B;IAC1B,sBAAsB;IACtB,2BAA2B;CAC5B;;;;"}

package/dist/index.js

@@ -0,0 +1,66 @@
+/**
+ * Extract timestamp from UUID v7 strings.
+ *
+ * The timestamp for UUID v7 is encoded in the first 48 bits (12 hex chars) of the UUID.
+ * This module exposes three helpers:
+ * - extractTimestampFromUuidV7(uuid): number (epoch millis)
+ * - extractTimestampAsDate(uuid): Date
+ * - extractTimestampAsISOString(uuid): string
+ */
+const HEX_32_RE = /^[0-9a-fA-F]{32}$/;
+/**
+ * Extracts the epoch milliseconds timestamp from a UUID v7 string.
+ * Caller must pass a UUID v7 (validation is performed and an error thrown if it's not v7).
+ *
+ * @param uuid - UUID string (hyphenated or not)
+ * @returns epoch milliseconds (number)
+ * @throws Error if input is not a valid UUID string or not version 7
+ */
+export function extractTimestampFromUuidV7(uuid) {
+    if (typeof uuid !== 'string' || uuid.length === 0) {
+        throw new Error('uuid must be a non-empty string');
+    }
+    // Normalize: remove hyphens
+    const normalized = uuid.replace(/-/g, '');
+    if (!HEX_32_RE.test(normalized)) {
+        throw new Error('invalid UUID format');
+    }
+    // Version nibble is the first hex char of the 3rd UUID segment.
+    // In the normalized string it's at index 12 (0-based).
+    const versionChar = normalized[12];
+    if (versionChar !== '7') {
+        throw new Error(`expected UUID v7 (version nibble = 7), got version nibble = ${versionChar}`);
+    }
+    // Timestamp for UUID v7 is the top 48 bits: time_low (8 hex) + time_mid (4 hex) => first 12 hex chars
+    const timeHex = normalized.slice(0, 12); // 12 hex chars => 48 bits
+    const millisBig = BigInt(`0x${timeHex}`);
+    const millis = Number(millisBig);
+    if (!Number.isFinite(millis)) {
+        throw new Error('extracted timestamp is not a finite number');
+    }
+    return millis;
+}
+/**
+ * Same as extractTimestampFromUuidV7 but returns a Date instance.
+ *
+ * @param uuid - UUID v7 string
+ * @returns Date representing the timestamp encoded in the UUID
+ */
+export function extractTimestampAsDate(uuid) {
+    const ms = extractTimestampFromUuidV7(uuid);
+    return new Date(ms);
+}
+/**
+ * Convenience: returns an ISO string for the timestamp contained in the UUID v7.
+ *
+ * @param uuid - UUID v7 string
+ * @returns ISO 8601 string (UTC)
+ */
+export function extractTimestampAsISOString(uuid) {
+    return extractTimestampAsDate(uuid).toISOString();
+}
+export default {
+    extractTimestampFromUuidV7,
+    extractTimestampAsDate,
+    extractTimestampAsISOString
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deciosfernandes/uuidv7-timestamp",
+  "version": "0.1.0",
+  "description": "Extract epoch timestamp from UUID v7 strings (millis, Date, ISO) for TypeScript/Angular apps.",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc && rollup -c",
+    "clean": "rm -rf dist .turbo cache",
+    "test": "vitest",
+    "lint": "eslint . --ext .ts",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/deciosfernandes/uuidv7-timestamp.git"
+  },
+  "keywords": [
+    "uuid",
+    "uuidv7",
+    "timestamp",
+    "typescript",
+    "angular"
+  ],
+  "author": "deciosfernandes",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^24.0.0",
+    "@rollup/plugin-node-resolve": "^15.0.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^5.0.0",
+    "@typescript-eslint/parser": "^5.0.0",
+    "eslint": "^8.0.0",
+    "rollup": "^3.0.0",
+    "rollup-plugin-dts": "^5.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.3.0"
+  }
+}