{"_id":"@badrddinb/tuid","name":"@badrddinb/tuid","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@badrddinb/tuid","version":"1.0.0","description":"A sortable, unique, and unlimited timestamp-based universal unique identifier (TUID) generator with validation and parsing support.","main":"dist/index.js","types":"dist/index.d.ts","repository":{"type":"git","url":"git+https://github.com/badrddinb/tuid.git"},"directories":{"test":"test"},"scripts":{"test":"jest","build":"tsc"},"keywords":["TUID","UUID","identifier","unique-id","sortable","timestamp","universal"],"author":{"name":"Badreddine Bendriss"},"license":"CC-BY-NC-4.0","devDependencies":{"@types/jest":"29.5.13","jest":"29.7.0","ts-jest":"29.2.5","ts-node":"10.9.2","typescript":"5.6.3"},"_id":"@badrddinb/tuid@1.0.0","gitHead":"ba0568832bea00b0b2fa7a3535027e0a1f0d169f","bugs":{"url":"https://github.com/badrddinb/tuid/issues"},"homepage":"https://github.com/badrddinb/tuid#readme","_nodeVersion":"20.10.0","_npmVersion":"10.2.3","dist":{"integrity":"sha512-povGGHbosC6aRioxSz7tb7+HyqhzCESdl9S1IsvlCJF8ZSd2/PV/S3K3EzZ63P/oDH2hgIIJZiSiTAWyHye5Kg==","shasum":"4aa547df638c1f9cdfbd8b35fc198573a454baca","tarball":"https://registry.npmjs.org/@badrddinb/tuid/-/tuid-1.0.0.tgz","fileCount":11,"unpackedSize":34306,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQCNVVe9jPrMTdGM8GQyjI79MbsXgl6nJfEjeE7VIkPUSwIgcVQSPTUeCr7Z6WxdaeWwEGriJsw5DP9PPY+oipzAStE="}]},"_npmUser":{"name":"badrddinb","email":"badrddin.bendriss@gmail.com"},"maintainers":[{"name":"badrddinb","email":"badrddin.bendriss@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/tuid_1.0.0_1728616484787_0.45491212861013963"},"_hasShrinkwrap":false}},"time":{"created":"2024-10-11T03:14:44.703Z","1.0.0":"2024-10-11T03:14:44.997Z","modified":"2024-10-11T03:14:45.268Z"},"maintainers":[{"name":"badrddinb","email":"badrddin.bendriss@gmail.com"}],"description":"A sortable, unique, and unlimited timestamp-based universal unique identifier (TUID) generator with validation and parsing support.","homepage":"https://github.com/badrddinb/tuid#readme","keywords":["TUID","UUID","identifier","unique-id","sortable","timestamp","universal"],"repository":{"type":"git","url":"git+https://github.com/badrddinb/tuid.git"},"author":{"name":"Badreddine Bendriss"},"bugs":{"url":"https://github.com/badrddinb/tuid/issues"},"license":"CC-BY-NC-4.0","readme":"# TUID\n\nTUID (Timestamp-based Unique ID) is a simple, efficient, and scalable package for generating **sortable, unique, and\nunlimited timestamp-based unique identifiers (TUIDs)**. It offers functions for generating, validating, and parsing\nTUIDs, all implemented with minimal dependencies and full TypeScript support.\n\n## Features\n\n- **Sortable**: TUIDs are generated in a way that ensures they are lexicographically sortable based on the timestamp.\n- **Unlimited**: You can generate as many unique IDs as you need without worry about collisions.\n- **Timestamp-based**: The IDs include a timestamp for easy chronological sorting.\n- **Validation**: Check whether a string is a valid TUID and identify its version.\n- **Parsing**: Decompose a TUID into its meaningful components, such as timestamp, machine ID, sequence number, and\n  additional random strings.\n- **TypeScript Support**: Fully typed to take advantage of TypeScript features.\n\n## Installation\n\nTo install TUID, simply run:\n\n```bash\nnpm install @badrddinb/tuid\n```\n\nor, using Yarn:\n\n```bash\nyarn add @badrddinb/tuid\n```\n\n## Usage\n\nTUID is designed to be straightforward. Here's how to generate, validate, and parse TUIDs in your project:\n\n### Generate a TUID\n\n```typescript\nimport TUIDGenerator from 'tuid';\n\n// Create a new generator for TUID v1 (current version)\nconst generator = new TUIDGenerator(1);\n\n// Generate a TUID\nconst tuid = generator.generateV1();\nconsole.log(tuid); // Outputs a unique, sortable TUID like \"1697034958283-512-3-abc1-def2\"\n```\n\n### Validate a TUID\n\nYou can validate if a string is a valid TUID and optionally check for the version.\n\n```typescript\nimport TUIDGenerator from 'tuid';\n\n// A valid TUID string\nconst tuid = '1697034958283-512-3-abc1-def2';\n\nconst isValid = TUIDGenerator.isValidTUID(tuid);\nconsole.log(isValid); // true or false\n```\n\n### Parse a TUID\n\nA TUID can be parsed into its individual components:\n\n```typescript\nimport TUIDGenerator from 'tuid';\n\n// A valid TUID string\nconst tuid = '1697034958283-512-3-abc1-def2';\n\nconst parsed = TUIDGenerator.parseTUID(tuid);\n\nconsole.log(parsed);\n/*\nOutputs:\n{\n  \"timestamp\": 1697034958283,\n  \"machineId\": 512,\n  \"sequence\": 3,\n  \"randomString1\": \"abc1\",\n  \"randomString2\": \"def2\"\n}\n*/\n```\n\n### Get TUID Version\n\nDetermine the version of a given TUID (currently, only version 1 is supported):\n\n```typescript\nimport TUIDGenerator from 'tuid';\n\nconst tuid = '1697034958283-512-3-abc1-def2';\nconst version = TUIDGenerator.getTUIDVersion(tuid);\nconsole.log(version); // 'v1'\n```\n\n## API Reference\n\n### `TUIDGenerator`\n\n#### `constructor(machineId: number)`\n\n- `machineId`: The ID of the machine generating the TUID. This must be a value between 0 and 1023.\n\n#### `generateV1(): string`\n\nGenerates a new TUID v1, which is sortable, unique, and timestamp-based.\n\n#### `static isValidTUID(tuid: string): boolean`\n\nChecks if a given string is a valid TUID v1.\n\n#### `static getTUIDVersion(tuid: string): 'v1' | 'unknown'`\n\nReturns the version of the TUID if it's valid, otherwise returns `'unknown'`.\n\n#### `static parseTUID(tuid: string): { timestamp: number, machineId: number, sequence: number, randomString1: string, randomString2: string } | null`\n\nParses a TUID into its components: timestamp, machine ID, sequence number, and two random strings.\n\n## TypeScript\n\nTUID is fully written in TypeScript and includes type declarations for seamless integration into TypeScript projects.\nHere’s an example:\n\n```typescript\nimport TUIDGenerator from 'tuid';\n\nconst generator: TUIDGenerator = new TUIDGenerator(1);\nconst tuid: string = generator.generateV1();\n```\n\n## TUID Type\n\nIf you wish to define a custom type for TUIDs:\n\n```typescript\nexport type TUID = `${number}-${number}-${number}-${string}-${string}`;\n```\n\nThis allows you to use the `TUID` type in your project:\n\n```typescript\nconst id: TUID = generator.generateV1();\n```\n\n## Contributing\n\nFeel free to contribute by opening issues, suggesting features, or submitting pull requests. For any contributions:\n\n1. Fork the repository\n2. Create a new branch (\\`git checkout -b feature-branch\\`)\n3. Commit your changes (\\`git commit -m 'Add new feature'\\`)\n4. Push to the branch (\\`git push origin feature-branch\\`)\n5. Open a pull request\n\n## License\n\nThis project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC\n4.0). [Learn more about the license here](https://creativecommons.org/licenses/by-nc/4.0/).\n\nThis means:\n\n- You can use, modify, and distribute this code as long as it's for non-commercial purposes.\n- Proper attribution is required.\n- Commercial use of this package is not permitted.\n\n## Acknowledgements\n\nInspired by common UUID and ULID libraries, with added support for sorting and parsing.\n","readmeFilename":"README.md"}