{"_id":"@chaisser/uuid-v7","name":"@chaisser/uuid-v7","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@chaisser/uuid-v7","version":"1.0.0","description":"Time-ordered UUID v7 generator","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepublishOnly":"npm run build"},"keywords":["uuid","v7","time","ordered","generator","typescript"],"license":"MIT","devDependencies":{"@types/node":"^22.10.2","tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^2.1.8"},"engines":{"node":">=16.0.0"},"publishConfig":{"access":"public"},"gitHead":"a517cb0f52aa2f75720aeba6e96ae89e47b4cab7","_id":"@chaisser/uuid-v7@1.0.0","_nodeVersion":"26.1.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-+eIKmu658sKBjCIEg6n0YjcCBkBy+JzWQn7li1PzAmn9/vT1Gk040Y9rfwgctOzYUzlLVvrctcZtKg4lXywyZw==","shasum":"11036d18efb8ed0ee9523dddaf6a5032ae6f6592","tarball":"https://registry.npmjs.org/@chaisser/uuid-v7/-/uuid-v7-1.0.0.tgz","fileCount":8,"unpackedSize":37475,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCMNCviozfSFwb6yErpBPDEc2HIdW0N5VmLMIeFUZi0kgIhAKwzH/NU32s3w/f5XlOIxYdmcU0vZ6/lJFgtlPCSjS7z"}]},"_npmUser":{"name":"chaisser","email":"doruk.karaboncuk@gmail.com"},"directories":{},"maintainers":[{"name":"chaisser","email":"doruk.karaboncuk@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/uuid-v7_1.0.0_1778547822144_0.8207362909529226"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-12T01:03:42.046Z","1.0.0":"2026-05-12T01:03:42.301Z","modified":"2026-05-12T01:03:42.499Z"},"maintainers":[{"name":"chaisser","email":"doruk.karaboncuk@gmail.com"}],"description":"Time-ordered UUID v7 generator","keywords":["uuid","v7","time","ordered","generator","typescript"],"license":"MIT","readme":"# 🆔 @chaisser/uuid-v7\n\n> **Time-ordered UUID v7 generator with full TypeScript support**\n\n---\n\n## ✨ Features\n\n- 🎯 **Type-safe** - Full TypeScript support with strict types\n- ⏰ **Time-ordered** - UUID v7 with embedded millisecond timestamps (RFC 9562)\n- 🔄 **UUID v4** - Also generates UUID v4 (random, RFC 4122)\n- ✅ **Validation** - Validate and detect UUID versions\n- 🧹 **Formatting** - Shorten, format, and parse UUIDs\n- 🪶 **Zero dependencies** - Lightweight and tree-shakeable\n- 🏎️ **ESM + CJS** - Dual module format support\n- 🔐 **Crypto-safe** - Uses `crypto.getRandomValues` for secure randomness\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @chaisser/uuid-v7\n# or\nyarn add @chaisser/uuid-v7\n# or\npnpm add @chaisser/uuid-v7\n```\n\n---\n\n## 🚀 Quick Start\n\n```typescript\nimport {\n  generateUUID,\n  generateUUIDv4,\n  validateUUID,\n  isUUIDv7,\n  isUUIDv4,\n  getUUIDVersion,\n  NIL_UUID,\n  shortenUUID,\n  formatUUID,\n} from '@chaisser/uuid-v7';\n\n// Generate UUID v7 (time-ordered)\nconst id = generateUUID();\nconsole.log(id); // 01914d2c-a3b7-7d4e-8f12-5a6b7c8d9e0f\n\n// Generate UUID v4 (random)\nconst v4 = generateUUIDv4();\nconsole.log(v4); // 550e8400-e29b-41d4-a716-446655440144\n\n// Validate and check version\nconsole.log(validateUUID(id)); // true\nconsole.log(getUUIDVersion(id)); // 7\nconsole.log(isUUIDv7(id)); // true\nconsole.log(isUUIDv4(v4)); // true\n\n// Format utilities\nconsole.log(shortenUUID(id)); // 01914d2ca3b77d4e8f125a6b7c8d9e0f\nconsole.log(formatUUID('0123456789abcdef0123456789abcdef')); // 01234567-89ab-cdef-0123-456789abcdef\n```\n\n---\n\n## 📖 What It Does\n\nThis package generates RFC 9562 compliant UUID v7 identifiers with embedded millisecond timestamps, making them naturally sortable by creation time. It also supports UUID v4 generation, format validation, version detection, and common formatting operations.\n\n---\n\n## 🎯 How It Works\n\nThe package provides utilities organized into categories:\n\n- **Generation** - Create UUID v7 (time-ordered) and v4 (random) identifiers\n- **Validation** - Check if strings are valid UUIDs and detect their version\n- **Formatting** - Shorten (remove dashes) or format (add dashes) UUID strings\n- **Parsing** - Extract the embedded timestamp from UUID v7\n- **Nil UUID** - Special all-zeros UUID constant and utilities\n\n---\n\n## 🎨 What It's Useful For\n\n- **Database Keys** - Time-ordered primary keys that sort naturally\n- **Distributed Systems** - Generate unique IDs without coordination\n- **API Identifiers** - Request IDs, trace IDs, session tokens\n- **Data Migration** - Generate sortable identifiers for imported records\n- **Logging** - Correlate log entries with time-ordered trace IDs\n- **URL-Safe Tokens** - Shorten UUIDs for use in URLs\n\n---\n\n## 💡 Usage Examples\n\n### Generating UUIDs\n\n```typescript\nimport { generateUUID, generateUUIDSimple, generateUUIDv4, generateUUIDv7Time } from '@chaisser/uuid-v7';\n\n// Time-ordered UUID v7 (recommended)\nconst id1 = generateUUID();\nconsole.log(id1); // 01914d2c-a3b7-7d4e-8f12-5a6b7c8d9e0f\n\n// Alias with explicit name\nconst id2 = generateUUIDv7Time();\n\n// Simple UUID v7 (no timestamp, just version bits)\nconst id3 = generateUUIDSimple();\n\n// Random UUID v4\nconst id4 = generateUUIDv4();\nconsole.log(getUUIDVersion(id4)); // 4\n\n// Generate multiple at once\nconst ids = generateUUIDs(5);\nconsole.log(ids.length); // 5\n\n// With nil UUID included\nconst idsWithNil = generateUUIDs(3, true);\nconsole.log(idsWithNil[0]); // 00000000-0000-0000-0000-000000000000\n```\n\n### Validation\n\n```typescript\nimport { validateUUID, isUUID, isUUIDv4, isUUIDv7, getUUIDVersion } from '@chaisser/uuid-v7';\n\nconst v7 = generateUUID();\nconst v4 = generateUUIDv4();\n\n// General validation\nvalidateUUID(v7);          // true\nvalidateUUID('not-a-uuid'); // false\nvalidateUUID(NIL_UUID);    // true\n\n// Version-specific checks\nisUUIDv7(v7);  // true\nisUUIDv4(v7);  // false\nisUUIDv4(v4);  // true\nisUUIDv7(v4);  // false\n\n// Get version number\ngetUUIDVersion(v7);        // 7\ngetUUIDVersion(v4);        // 4\ngetUUIDVersion('invalid'); // null\n```\n\n### Formatting\n\n```typescript\nimport { shortenUUID, formatUUID } from '@chaisser/uuid-v7';\n\nconst uuid = generateUUID();\n\n// Remove dashes\nconst short = shortenUUID(uuid);\nconsole.log(short); // 01914d2ca3b77d4e8f125a6b7c8d9e0f (32 chars)\n\n// Add dashes back\nconst formatted = formatUUID(short);\nconsole.log(formatted); // 01914d2c-a3b7-7d4e-8f12-5a6b7c8d9e0f\n```\n\n### Parsing\n\n```typescript\nimport { parseUUIDv7 } from '@chaisser/uuid-v7';\n\nconst uuid = generateUUID();\nconst parsed = parseUUIDv7(uuid);\n\nconsole.log(parsed?.version);    // 7\nconsole.log(parsed?.timestamp);  // 1700000000000 (Unix ms)\n\n// Returns null for non-v7 UUIDs\nparseUUIDv7(generateUUIDv4()); // null\nparseUUIDv7('invalid');        // null\n```\n\n### Nil UUID\n\n```typescript\nimport { NIL_UUID, isNilUUID, generateNilUUID } from '@chaisser/uuid-v7';\n\nconsole.log(NIL_UUID);        // 00000000-0000-0000-0000-000000000000\nisNilUUID(NIL_UUID);          // true\nisNilUUID(generateUUID());    // false\ngenerateNilUUID();            // 00000000-0000-0000-0000-000000000000\n```\n\n---\n\n## 📚 API Reference\n\n### Generation\n\n| Function | Returns | Description |\n|---|---|---|\n| `generateUUID()` | `string` | UUID v7 with embedded timestamp |\n| `generateUUIDv7Time()` | `string` | Alias for `generateUUID()` |\n| `generateUUIDSimple()` | `string` | UUID v7 without timestamp |\n| `generateUUIDv4()` | `string` | Random UUID v4 |\n| `randomUUID()` | `string` | Alias for `generateUUID()` |\n| `generateUUIDs(count, nil?)` | `string[]` | Generate multiple UUIDs |\n| `generateNilUUID()` | `string` | Returns the nil UUID constant |\n\n### Validation\n\n| Function | Returns | Description |\n|---|---|---|\n| `validateUUID(uuid)` | `boolean` | Validates UUID format |\n| `isUUID(uuid)` | `boolean` | Same as `validateUUID` |\n| `isUUIDv4(uuid)` | `boolean` | Checks format + version nibble = 4 |\n| `isUUIDv7(uuid)` | `boolean` | Checks format + version nibble = 7 |\n| `isNilUUID(uuid)` | `boolean` | Checks if uuid equals `NIL_UUID` |\n| `getUUIDVersion(uuid)` | `4 \\| 7 \\| null` | Returns the UUID version |\n\n### Formatting\n\n| Function | Returns | Description |\n|---|---|---|\n| `shortenUUID(uuid)` | `string` | Remove dashes (32 hex chars) |\n| `formatUUID(uuid)` | `string` | Add dashes (8-4-4-4-12) |\n| `parseUUIDv7(uuid)` | `{ version, timestamp } \\| null` | Extract timestamp from v7 |\n\n### Constants\n\n| Name | Value |\n|---|---|\n| `NIL_UUID` | `'00000000-0000-0000-0000-000000000000'` |\n\n---\n\n## 🔗 Related Packages\n\nExplore our other utility packages in the @chaisser namespace:\n\n- **@chaisser/uuid-v7** (this package) - Time-ordered UUID v7 generator\n- [@chaisser/string-wizard](https://www.npmjs.com/package/@chaisser/string-wizard) - Advanced string manipulation\n- [@chaisser/type-guard](https://www.npmjs.com/package/@chaisser/type-guard) - Runtime type guards and validators\n- [@chaisser/human-time](https://www.npmjs.com/package/@chaisser/human-time) - Human-readable time formatting\n- [@chaisser/obj-path](https://www.npmjs.com/package/@chaisser/obj-path) - Object path traversal\n- [@chaisser/regex-humanizer](https://www.npmjs.com/package/@chaisser/regex-humanizer) - Regex pattern explanation\n- [@chaisser/debounce-throttle](https://www.npmjs.com/package/@chaisser/debounce-throttle) - Rate limiting utilities\n- [@chaisser/color-utils](https://www.npmjs.com/package/@chaisser/color-utils) - Color conversion utilities\n- [@chaisser/deep-clone](https://www.npmjs.com/package/@chaisser/deep-clone) - Deep cloning functions\n- [@chaisser/array-group-by](https://www.npmjs.com/package/@chaisser/array-group-by) - Array grouping utilities\n- [@chaisser/password-strength](https://www.npmjs.com/package/@chaisser/password-strength) - Password strength checker\n- [@chaisser/wait-for](https://www.npmjs.com/package/@chaisser/wait-for) - Promise-based wait utilities\n- [@chaisser/merge-objects](https://www.npmjs.com/package/@chaisser/merge-objects) - Object merge utilities\n- [@chaisser/chunk-array](https://www.npmjs.com/package/@chaisser/chunk-array) - Array chunking functions\n- [@chaisser/event-emitter](https://www.npmjs.com/package/@chaisser/event-emitter) - Typed event emitter\n\n---\n\n## 🔒 License\n\n**MIT** - Free to use in personal and commercial projects\n\n---\n\n## 👨 Developed by\n\n**Doruk Karaboncuk** <doruk.karaboncuk@interaktifis.com>\n\n---\n\n## 📄 Repository\n\n- **GitHub:** [@chaisser](https://github.com/chaisser)\n- **NPM:** [@chaisser/uuid-v7](https://www.npmjs.com/package/@chaisser/uuid-v7)\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Feel free to:\n- Report bugs\n- Suggest new features\n- Submit pull requests\n- Improve documentation\n\n---\n\n## 📞 Support\n\nFor issues, questions, or suggestions, please reach out through:\n- **Email:** doruk.karaboncuk@interaktifis.com\n- **GitHub Issues:** [Create an issue](https://github.com/chaisser/uuid-v7/issues)\n\n---\n\n<div align=\"center\">\n\nMade with ❤️ by [@chaisser](https://www.npmjs.com/package/@chaisser)\n\n[![npm](https://img.shields.io/npm/v/@chaisser%2Fuuid-v7-blue)](https://www.npmjs.com/package/@chaisser/uuid-v7)\n[![license](https://img.shields.io/npm/l/@chaisser/uuid-v7-blue)](https://www.npmjs.com/package/@chaisser/uuid-v7)\n[![downloads](https://img.shields.io/npm/dm/@chaisser%2Fuuid-v7-blue)](https://www.npmjs.com/package/@chaisser/uuid-v7)\n[![typescript](https://img.shields.io/badge/typescript-5.7.2-blue)](https://www.npmjs.com/package/@chaisser/uuid-v7)\n\n</div>\n","readmeFilename":"README.md","_rev":"1-000a34d472429b1d55d95ac241c52dd6"}