{"_id":"@bradkovach/guid","_rev":"1-2ad945ca87171b9a18620d37b35661a2","name":"@bradkovach/guid","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bradkovach/guid","version":"1.0.0","description":"Zero-dependency RFC 4122-compliant GUID/UUID generation library.","scripts":{"clean":"rm -rf dist/","test":"mocha --config .mocharc","test:watch":"mocha --config .mocharc --watch","test:coverage":"nyc npm run test","build":"npm run clean && tsc"},"main":"./dist/Guid.js","types":"./dist/Guid.d.ts","repository":{"type":"git","url":"git+https://github.com/bradkovach/guid.git"},"prettier":{"tabWidth":4,"printWidth":100,"singleQuote":true},"devDependencies":{"@istanbuljs/nyc-config-typescript":"^1.0.2","@types/chai":"^4.3.3","@types/mocha":"^10.0.0","chai":"^4.3.6","mocha":"^10.0.0","nyc":"^15.1.0","prettier":"^2.7.1","ts-node":"^10.9.1"},"gitHead":"d63e55c3838fa8a4535c7c368f6a35f7cfb34631","bugs":{"url":"https://github.com/bradkovach/guid/issues"},"homepage":"https://github.com/bradkovach/guid#readme","_id":"@bradkovach/guid@1.0.0","_nodeVersion":"16.13.2","_npmVersion":"8.1.2","dist":{"integrity":"sha512-TDjYkzFLaBK5jmJpsC5VvbBzvnlYSs2ah/f6pFSGUbG1cfm1l47kNmn6betvY7KJ/ICVh+mK+ZoBdtf7lT6C0A==","shasum":"4ae1e8850ea62f855446fa84e65e07b7aee5852b","tarball":"https://registry.npmjs.org/@bradkovach/guid/-/guid-1.0.0.tgz","fileCount":4,"unpackedSize":19076,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIDP9H3LJAyjTTQetkWyKGIjjrKG627PfMRL0RN8POM39AiEAg/kReozErnNftrtUezJjOMfXmIGkFDZvJ73HZRQ92uM="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjQ0S+ACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmpKCw/+KvUDiyaI95Gq1Y7Neq/g8BUIB1o1F/L4RwzYdMB4sKNBH+ke\r\nLrGdSSzOeFOpEaBS7LeOgbn+Z0mV9J9DwhwzN/+RAfL/iP7v7Yr6L+0Ai0oY\r\nHT7xgsYdnYkZNXNTUzqV1of2eGtKxphbUxMIMf0x8aBNdbJy/UXUIrXLP7Hm\r\nmaklt+wGWY89WlF/tY5bnX3JW6PZ+vHw4EQcpU2idgtD077VrEtn2XlOhQca\r\nZ1rk5/2RxVlWoXk5RogrXVv2dXhtCV8KtJgpCiWYcYBpqZPIhXdQ0jSXVsxt\r\nibhHJ7SFdrRM1NnGZyORzEL8CZQxXTlymWgg6u4MMJ8yKxP6k7EPM4R7lMCv\r\naeDgKed2AaRIXT+mUcS1Ob6TBto9xU83xjgB4aPk/1zp117kha08qn99uvn5\r\naef9iHJINbZNenlP1IGAdDOXA5zvoX+ZRFNbyytVGzFQOglSF2VDjGIf2GtA\r\n6LzCcDVGv0TudrkmLJCT7l0e/SD3VXrY624AR+W9M/NPbpyicpNeEwf96+fz\r\nbVx62nXaFKzZ+Gvb9TebPBwIEi/W/4qSBjCPdt4ebzrLTVZ1VchI3hmR8Yk4\r\nBRLqWJOmoncDO0fNDPmNQt20omc31DHbdgRPpUwW6OQAWH9BiHqn6crqqYab\r\nckACO65gU8bXiKl/2AQKo+ftOcxQBBNhNuI=\r\n=uWGV\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"bradkovach","email":"bradkovach@gmail.com"},"directories":{},"maintainers":[{"name":"bradkovach","email":"bradkovach@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/guid_1.0.0_1665352894073_0.616258422526367"},"_hasShrinkwrap":false},"1.0.1":{"name":"@bradkovach/guid","version":"1.0.1","description":"Zero-dependency RFC 4122-compliant GUID/UUID generation library.","main":"./cjs/index.js","module":"./mjs/index.mjs","exports":{".":{"import":"./mjs/index.mjs","types":"./index.d.ts","require":"./cjs/index.js"},"./util":{"import":"./mjs/util/index.mjs","types":"./util/index.d.js","require":"./cjs/util/index.js"}},"repository":{"type":"git","url":"git+https://github.com/bradkovach/guid.git"},"gitHead":"b6867bd02fc152a473d5f9fe3f9ff7dfb9c6c12f","bugs":{"url":"https://github.com/bradkovach/guid/issues"},"homepage":"https://github.com/bradkovach/guid#readme","_id":"@bradkovach/guid@1.0.1","_nodeVersion":"16.13.2","_npmVersion":"8.1.2","dist":{"integrity":"sha512-4r6B2anZs4kySzYg54mqwfUQiZnylffEHxFQd4O3U5oDA9rU1hlS7Ul/bdBXyAtzmZkIu4LoCYrj4v0KqJl32Q==","shasum":"ea84e12971f01f149ea15c90de4fc24ebdaf9908","tarball":"https://registry.npmjs.org/@bradkovach/guid/-/guid-1.0.1.tgz","fileCount":26,"unpackedSize":37157,"signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIFM8Lsu4jFv3FoVNzDyvZgRM28H+eEUI3zDLQpvoVEfdAiEA3syOXxThXRKjAtHZmX0qLrXgy1P0fKIJq9ITX9Un3fg="}],"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJjSkmnACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2VmqCQA/+JTKBUa5Rmya03R9k0ZcHsbaYxmt/HIuKKzDjj+NjefYrANhh\r\ncreGBMRMv8gIgMpfdK5S+XMPzOYjtny8HAayLw3LC0xoc2vCeUImKjdUFECe\r\n9rN/AVkhsSx0Ju2Vz9J7zayi0CisdAXisULeTLsnuJ10b4ktO+unaPllSeV9\r\n2NBg+F/ILttxht1kC5IgCe8qQSyTmVefq8H3/D951hAPooAZdZewwAES+F+5\r\ncROzLbYzBPW2TioOj7AP3BmwLW3lnJXTEnpc78ZDPPVLl+FINwnNB4VjPbLE\r\nVC9QMbfvuqk1vghYO4KaDQNeDxGDeAk4AKDt+9azuECaRNc1Q+pqdT1vG2kg\r\nJsNUzjvJqRJDrBIOwr7t55bh+OkO5SYfTzx2IUWdMbiY4Q3OISUATeyHbuzm\r\n4JhNR6pVEBv8tlCZPg32FQS9i0+h8A4CcWimDQIhSk2wxMKQIIYiyf7/mtrx\r\nOLbWB4BepHZSMhVoIrUpRJ+CcUwVf1j5ODFzF5AH8sE0Cg60GgNWmNJj1KcW\r\nCbC527L4rRAxh8SnBNO75LwuSHc6kp1DvtCBxObWX3/0DdaUsuK3nZnXDSX5\r\n3J1BB9KaYKMN/fya4apyXeC6jgBjiKzswwYYp7UZsaCW99nnmDaE42oGT6Ug\r\nHmyqLil8AOdP3RMwtd/h7cU12KOPE3Q8cWU=\r\n=SFzk\r\n-----END PGP SIGNATURE-----\r\n"},"_npmUser":{"name":"bradkovach","email":"bradkovach@gmail.com"},"directories":{},"maintainers":[{"name":"bradkovach","email":"bradkovach@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/guid_1.0.1_1665812903031_0.8582039933864374"},"_hasShrinkwrap":false}},"time":{"created":"2022-10-09T22:01:34.016Z","1.0.0":"2022-10-09T22:01:34.287Z","modified":"2022-10-15T05:48:23.220Z","1.0.1":"2022-10-15T05:48:23.156Z"},"maintainers":[{"name":"bradkovach","email":"bradkovach@gmail.com"}],"description":"Zero-dependency RFC 4122-compliant GUID/UUID generation library.","homepage":"https://github.com/bradkovach/guid#readme","repository":{"type":"git","url":"git+https://github.com/bradkovach/guid.git"},"bugs":{"url":"https://github.com/bradkovach/guid/issues"},"readme":"Zero-dependency RFC 4122-compliant GUID/UUID library written with TypeScript, modern crypto and a proper internal byte representation.\n\n# Quick Start\n\n## Install from npm\n\n```bash\nnpm install --save @bradkovach/guid\n```\n\n## Create, Parse, Serialize!\n\n```typescript\nimport { Guid } from '@bradkovach/guid';\n\n// Create\n\n// Random, valid v4 GUID/UUID\nlet guid = Guid.newGuid();\n\n// Random, sequential v4 \"COMB\" GUID/UUID\n// These are time based and also use an internal\n// serial number to ensure that they are always sequential\n// even if they are generated in a loop\nlet combGuid = Guid.newCombGuid();\n\n// Empty GUID\nlet emptyGuid = Guid.Empty;\n\n// Parse\n\n// parse any guid-like string from bin/oct/dec/hex bases\nlet parsedFromString = Guid.fromString(myString);\n\n// create a guid from existing byte array\nlet parsedFromBytes = Guid.fromBytes(myBytes);\n\n// Serialize\n\n// To hex\nlet hex = guid.toString();\n\n// To decimal\nlet dec = guid.toString(10);\n\n// To octal\nlet oct = guid.toString(8);\n\n// To binary\nlet bin = guid.toString(2);\n```\n\n# Usage\n\nCreation of new `Guid` instances is performed by calling static methods on the `Guid` class. `Guid` does not offer a public constructor.\n\n## Static Methods\n\n### Create from string\n\n`Guid.fromString(guidString:string): Guid`\n\nThis library can parse GUID/UUID strings in binary, octal, decimal and hexadecimal formats and normalizes internally to accommodate lots of common formats, including braced (Microsoft-style), padded with whitespace inside braces, uppercase/lowercase variants.\n\n```typescript\nimport { Guid } from '@bradkovach/guid';\n\n// all will work\nlet guid0 = Guid.fromString('c87c33e1-f9a9-43a7-bebb-d33a70883dc6');\nlet guid1 = Guid.fromString('83870266-9493-42CE-9EE6-8F3AA9D04401');\nlet guid2 = Guid.fromString('{fa20be72-8325-42e8-b62b-149ba613edcd}');\nlet guid3 = Guid.fromString('{18F66861-F882-4E95-BDEE-9499C7022C63}');\nlet guid4 = Guid.fromString('{ fa20be72-8325-42e8-b62b-149ba613edcd }');\nlet guid5 = Guid.fromString('{ 18F66861-F882-4E95-BDEE-9499C7022C63 }');\n\n// as a binary string\nlet guid6 = Guid.fromString(\n    '10010111110000110101110110110111111110011010101001001101001000001011101111010011010000010000100111000000110011010000100111000110'\n);\nlet guid7 = Guid.fromString(\n    '{10010111110000110101110110110111111110011010101001001101001000001011101111010011010000010000100111000000110011010000100111000110}'\n);\nlet guid8 = Guid.fromString(\n    '{10010111110000110101110110110111111110011010101001001101001000001011101111010011010000010000100111000000110011010000100111000110}'\n);\n```\n\n### Create from bytes\n\n`Guid.fromBytes(bytes: Uint8Array): Guid`\n\nThe static `Guid.fromBytes(bytes)` method will construct a new Guid instance. `fromBytes` will set the version and variant bits, ensuring that the resulting Guid represents a valid v4 GUID/UUID.\n\n```typescript\nimport { Guid } from '@bradkovach/guid';\n\n// construct from existing 16-byte array\n// This will set version and variant fields\nlet myBytes = getExistingGuidBytes();\nlet guid = Guid.fromBytes(myBytes);\n```\n\n### Memoization\n\nCall static member `Guid.memoize(base)` to improve the performance of serialization. Internally, `Guid` caches the string representation for the base and byte value when `toString(base)` is called. In benchmarks, this improves serialization performance about 7x.\n\nIf you need to clear the memoized string store, call `Guid.clearMemoizedStrings()`.\n\n### Serializing bytes\n\nCall static `Guid.getByteSerializer(base)` to get a function that will turn a valid byte (number from 0-255) into a string representation in any supported javascript base (2-36).\n\n```typescript\nimport { Guid } from '@bradkovach/guid';\n\nconst hexSerializer = Guid.getByteSerializer(16);\nconst hexString = [1, 2, 3, 4, 5].map(hexSerializer).join('');\n```\n\n### Resize random bytes pool\n\n`Guid.resizePool(guidCount)`\n\nIf you intend to generate a lot of `Guid` instances (in a loop), you may want to resize the random byte pool to a larger number to improve performance.\n\nBy default the pool is large enough for 256 Guids. Provide a `guidCount` integer greater than zero to allocate `guidCount * BYTES_IN_GUID` bytes of random data. If the bytes are used, the pool will refill with new random data.\n\nThe random bytes pool is not accessible publicly, but the `RandomBytesPool` class is available.\n\n## Instance Methods\n\nThese methods can be called on a `Guid` instance.\n\n### `toBytes(): Uint8Array`\n\nReturns a copy of the internal byte array.\n\n### `toString(base: number = 16): string`\n\nReturns a string representing the Guid in your chosen base. This can be called with any supported JS base from 2 through 36. Unit tests support bin/oct/dec/hex.\n\nGenerated GUID/UUID strings will include hyphens. Use the `normalizeGuidString` utility to strip these hyphens.\n\n```typescript\nimport { Guid } from '@bradkovach/guid';\n\nlet guid = Guid.newGuid();\n\nlet bin = guid.toString(2);\nlet oct = guid.toString(8);\nlet dec = guid.toString(10);\nlet hex = guid.toString(16);\n```\n\n### `valueOf(): BigInt`\n\nConverts the Guid into a BigInt. Creating Guid instances from a `BigInt` is not supported, however, the following should produce a string that can be parsed by `Guid.fromString()`.\n\n```typescript\nlet bigInt = Guid.newGuid().valueOf();\nlet hexGuid = bigInt.toString(16).padStart(32, '0');\nlet cloned = Guid.fromString(hexGuid);\n```\n\n## Equality and Comparison\n\nWhen you're working with COMB Guid instances, or guids created from comb guids, you can compare using less-than/greater-than. This could be useful for comparing Correlation IDs to compare which correlation ID happened first.\n\n```typescript\nimport { Guid } from '@bradkovach/guid';\n\nlet guidOne = Guid.newCombGuid();\nlet guidTwo = Guid.newCombGuid();\n\n// compare using LT/GT\nlet isLessThan = guidOne < guidTwo; // true\nlet isGreaterThan = guidOne > guidTwo; // false\n\n// compare value equality\nlet guidOneClone = Guid.fromBytes(guidOne.toBytes());\nlet isEqualValue = guidOne.valueOf() === guidOneClone.valueOf(); // true\n\n// compare object identity\nlet isEqualIdentity = guidOne === guidOneClone; // false\n```\n\n## Helpful Constants\n\nA number of constants are available. These should be used to cut down on arbitrary magic numbers.\n\n### `BYTES_IN_GUID: number = 16`\n\nUsed for instantiating arrays.\n\n### `BYTE_MIN: number = 0`\n\nMinimum valid value of a byte. Used for comparing byte values and to make code intent clearer.\n\n### `BYTE_MAX: number = 255`\n\nMaximum valid value of a byte. Used for comparing byte values and to make code intent clearer.\n\n## Class `RandomBytePool`\n\n`Guid` uses a private static instance of `RandomBytePool` to manage its random data. `RandomBytePool` can be instantiated and used if you want a source of random bytes. `RandomBytePool` is a standalone class to ensure 100% test coverage of its functionality.\n\nThe pool will automatically resize itself if `getBytes(count)` is called with a count greater than the length of the pool. `Guid` uses `RandomBytePool` by allocating in increments of `BYTES_IN_GUID`, and it reads values in these increments as well. Although even multiples aren't required when reading bytes with `getBytes(count)`, this is the most efficient memory allocation.\n\nThe pool can be resized after instantiation by calling `resize(newSize)`. This can be used to shrink or expand the pool.\n\n```typescript --run\nimport { RandomBytePool, BYTES_IN_GUID } from '@bradkovach/guid';\n\n// instantiate with 256 bytes\nlet rbp = new RandomBytePool(256);\n\n// => returns 5 random bytes\nlet five = rbp.getBytes(5);\n\n// => returns 1024 bytes, after resizing the pool.\nlet tooMany = rbp.getBytes(1024);\n\n// resizes the pool to 128 Guids worth of random bytes\nrbp.resize(128 * BYTES_IN_GUID);\n\n// Returns false when the pool hasn't\n// yet been read from.\nlet isInitialized = rbp.initialized;\n\n// Returns the length of the internal array\nconsole.log(rbp.length);\n\n// Returns the index of the next random byte\nconsole.log(rbp.currentIdx);\n```\n\n## Utilities\n\nThese functions are used internally by `Guid` to safely verify and normalize strings before parsing. If you are dealing with inconsistent data, these functions may be helpful.\n\n```typescript\nimport * as util from '@bradkovach/guid/util';\n\n// or\n\nimport { ensureByte, isValidVersion4GuidForBase, normalizeGuidString } from '@bradkovach/guid/util';\n```\n\n### `util.ensureByte(byte): void`\n\nThrows an error when `byte` is not a number between 0 and 255, inclusive. Can be used to stop execution of code.\n\n### `util.isValidVersion4GuidForBase(guid, base): boolean`\n\nNormalizes and tests a guid string for validity in the provided base. Should work in all JS bases, but is tested in 2, 8, 10 and 16.\n\n### `util.normalizeGuidString(guid): string`\n\nNormalizes a guid string by trimming, removing braces, removing hyphens and returning lowercase.\n\n# Acknowledgements\n\nI used the following resources to learn everything there is to know about the RFC 4122 standard, and its implementation.\n\n-   [IETF RFC 4122](https://www.ietf.org/rfc/rfc4122.txt)\n-   [uuidjs/uuid](https://github.com/uuidjs/uuid/)\n-   [Generate a UUID compliant with RFC 4122](https://www.cryptosys.net/pki/uuid-rfc4122.html)\n-   [Add a header containing a correlation id](https://learn.microsoft.com/en-us/azure/api-management/policies/add-correlation-id)\n\n# Contributing\n\nPull requests are welcome! Please ensure that new code includes test coverage.\n\n```bash\n# clone with http\nhttps://github.com/bradkovach/guid.git\n\n# clone with ssh\ngit clone git@github.com:bradkovach/guid.git\n\n# open\ncd guid\n\n# restore packages\nnpm install\n\n# run tests in watch mode\n# probably the fastest way to develop\nnpm run test:watch\n\n# check code coverage\nnpm run test:coverage\n\n# build artifacts using bradkovach-guid-test package name\n# this can be linked with `npm link` and used in another\n# test project with `npm link bradkovach-guid-test`\nnpm run build-dev\n\n# build artifacts using @bradkovach/guid package name\nnpm run build-prod\n```\n\n# Motivation\n\n-   Provide a proper TypeScript implementation of UUID/GUID generation using byte arrays.\n-   Sharpen skills working with bits/bytes in TS/JS.\n-   Build a high-performance COMB Guid implementation that I can use for logging.\n","readmeFilename":"README.md"}