{"id":10986,"library":"guid-typescript","title":"Guid TypeScript","description":"Guid TypeScript is a lightweight JavaScript library focused on generating RFC4122-compliant GUIDs (also known as UUIDs) specifically for TypeScript environments. It is currently at version 1.0.9, suggesting a stable codebase with a focus on maintenance rather than rapid feature development. The library provides a `Guid` class that encapsulates GUID values, offering both static methods for creating new GUIDs (`create`, `createEmpty`, `raw`), parsing strings into `Guid` instances (`parse`), and validating potential GUID values (`isGuid`). Additionally, `Guid` instances include methods for comparison (`equals`), emptiness checks (`isEmpty`), and conversion to string or JSON formats (`toString`, `toJSON`). Its key differentiator lies in providing strong TypeScript typing, which allows developers to leverage type safety when working with GUIDs as objects, rather than managing them as raw strings. This approach helps prevent common errors associated with string manipulation and ensures consistency across an application's data models.","status":"maintenance","version":"1.0.9","language":"javascript","source_language":"en","source_url":"https://github.com/NicolasDeveloper/guid-typescript","tags":["javascript","typescript","guid","identifier"],"install":[{"cmd":"npm install guid-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add guid-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add guid-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The `Guid` class is a named export. Attempting to use a default import will result in runtime errors.","wrong":"import Guid from 'guid-typescript';","symbol":"Guid class","correct":"import { Guid } from 'guid-typescript';"},{"note":"When using CommonJS, `Guid` must be destructured as it is a named export.","wrong":"const Guid = require('guid-typescript');","symbol":"Guid class (CommonJS)","correct":"const { Guid } = require('guid-typescript');"},{"note":"All creation, validation, and utility methods (like `create`, `isGuid`, `parse`) are static methods on the `Guid` class itself, not top-level named exports.","wrong":"import { create } from 'guid-typescript'; create();","symbol":"Static methods (e.g., create)","correct":"import { Guid } from 'guid-typescript'; Guid.create();"}],"quickstart":{"code":"import { Guid } from \"guid-typescript\";\n\ninterface IUser {\n    id: Guid;\n    username: string;\n}\n\nclass User implements IUser {\n    public id: Guid;\n    public username: string;\n\n    constructor(username: string) {\n        this.id = Guid.create(); // Generates a new unique GUID\n        this.username = username;\n        console.log(`New user created: ${this.username} with ID: ${this.id.toString()}`);\n    }\n\n    static isValidUserId(potentialId: any): boolean {\n        // Checks if a given value is a valid Guid instance or string representation\n        return Guid.isGuid(potentialId);\n    }\n\n    equals(otherUser: User): boolean {\n        // Compares two Guid instances\n        return this.id.equals(otherUser.id);\n    }\n}\n\n// Example Usage\nconst user1 = new User(\"alice_ts\");\nconst user2 = new User(\"bob_ts\");\n\nconst emptyGuid = Guid.createEmpty(); // Creates an all-zero GUID\nconst rawGuidString = Guid.raw();    // Creates a new GUID as a string\nconst parsedGuid = Guid.parse(\"a1b2c3d4-e5f6-7890-1234-567890abcdef\"); // Parses a GUID string\n\nconsole.log(`\\nUser 1 ID (raw string format): ${user1.id.raw()}`);\nconsole.log(`Is emptyGuid really empty? ${emptyGuid.isEmpty()}`); // true\nconsole.log(`Generated raw GUID string: ${rawGuidString}`);\nconsole.log(`Does user1 ID equal user2 ID? ${user1.equals(user2)}`); // false\nconsole.log(`Is \"hello-world\" a valid Guid string? ${User.isValidUserId(\"hello-world\")}`); // false\nconsole.log(`Is parsedGuid an actual Guid instance? ${User.isValidUserId(parsedGuid)}`); // true\nconsole.log(`Parsed GUID value: ${parsedGuid.toString()}`);","lang":"typescript","description":"Demonstrates basic GUID creation, checking for emptiness, comparing GUIDs, parsing a string into a Guid instance, and validating GUIDs within a TypeScript class context."},"warnings":[{"fix":"Use `myGuidObject.toString() === 'some-guid-string'` or `Guid.isGuid(potentialGuidString)` for comparisons involving strings.","message":"Directly comparing `Guid` objects with raw GUID strings (e.g., `myGuidObject == 'some-guid-string'`) will not work as expected due to type mismatch. Always use `myGuidObject.toString()` or `myGuidObject.raw()` for string comparisons, or `Guid.isGuid()` for validation.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Wrap `Guid.parse()` calls in a `try...catch` block, or validate the string first using `Guid.isGuid()` before attempting to parse: `if (Guid.isGuid(myString)) { try { Guid.parse(myString); } catch (e) { /* handle error */ } }`","message":"`Guid.parse(guidString)` will throw an `Error` if the input `guidString` is not a valid RFC4122 GUID format. It does not return `null` or `undefined` for invalid inputs.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Explicitly define ID properties as `id: Guid` and use `Guid.create()`, `Guid.parse()`, or `.toString()` when interacting with string-based APIs.","message":"When migrating from older JavaScript GUID libraries that might return plain strings, ensure that type annotations are updated to `Guid` for consistency and type safety. Mixing `Guid` objects and `string` types for IDs can lead to unexpected behavior or TypeScript compilation errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Use the static factory method `Guid.create()` to generate new GUIDs, and ensure `import { Guid } from 'guid-typescript';` or `const { Guid } = require('guid-typescript');`.","cause":"Attempting to instantiate `Guid` directly using `new Guid()` after an incorrect `import Guid from 'guid-typescript;'` statement, or if `require` was used without destructuring.","error":"TypeError: Guid is not a constructor"},{"fix":"Ensure `Guid` is imported as a named export (`import { Guid } from 'guid-typescript';`) and call the method as `Guid.create()`.","cause":"This usually occurs when `Guid` was imported incorrectly, possibly as a default import when it's a named export, or when attempting to call `create()` as a top-level function.","error":"TypeError: Guid.create is not a function"},{"fix":"Validate the input string format using `Guid.isGuid(myString)` before calling `Guid.parse(myString)`. If the string is not valid, handle the error gracefully.","cause":"The string passed to `Guid.parse()` does not conform to the RFC4122 GUID (UUID) format.","error":"Error: String does not represent a Guid"}],"ecosystem":"npm"}