Guid TypeScript

Common errors

• TypeError: Guid is not a constructor

  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.
  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');`.

• TypeError: Guid.create is not a function

  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.
  fix Ensure `Guid` is imported as a named export (`import { Guid } from 'guid-typescript';`) and call the method as `Guid.create()`.

• Error: String does not represent a Guid

  cause The string passed to `Guid.parse()` does not conform to the RFC4122 GUID (UUID) format.
  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.

Warnings

• gotcha 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.
  Fix: Use `myGuidObject.toString() === 'some-guid-string'` or `Guid.isGuid(potentialGuidString)` for comparisons involving strings.
• gotcha `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.
  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 */ } }`
• gotcha 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.
  Fix: Explicitly define ID properties as `id: Guid` and use `Guid.create()`, `Guid.parse()`, or `.toString()` when interacting with string-based APIs.

Install

• npm install guid-typescript npm
• yarn add guid-typescript yarn
• pnpm add guid-typescript pnpm

Imports

• Guid class
  wrong:

  import Guid from 'guid-typescript';

  correct:

  import { Guid } from 'guid-typescript';

  The `Guid` class is a named export. Attempting to use a default import will result in runtime errors.
• Guid class (CommonJS)
  wrong:

  const Guid = require('guid-typescript');

  correct:

  const { Guid } = require('guid-typescript');

  When using CommonJS, `Guid` must be destructured as it is a named export.
• Static methods (e.g., create)
  wrong:

  import { create } from 'guid-typescript'; create();

  correct:

  import { Guid } from 'guid-typescript'; Guid.create();

  All creation, validation, and utility methods (like `create`, `isGuid`, `parse`) are static methods on the `Guid` class itself, not top-level named exports.

Quickstart

Demonstrates basic GUID creation, checking for emptiness, comparing GUIDs, parsing a string into a Guid instance, and validating GUIDs within a TypeScript class context.

import { Guid } from "guid-typescript";

interface IUser {
    id: Guid;
    username: string;
}

class User implements IUser {
    public id: Guid;
    public username: string;

    constructor(username: string) {
        this.id = Guid.create(); // Generates a new unique GUID
        this.username = username;
        console.log(`New user created: ${this.username} with ID: ${this.id.toString()}`);
    }

    static isValidUserId(potentialId: any): boolean {
        // Checks if a given value is a valid Guid instance or string representation
        return Guid.isGuid(potentialId);
    }

    equals(otherUser: User): boolean {
        // Compares two Guid instances
        return this.id.equals(otherUser.id);
    }
}

// Example Usage
const user1 = new User("alice_ts");
const user2 = new User("bob_ts");

const emptyGuid = Guid.createEmpty(); // Creates an all-zero GUID
const rawGuidString = Guid.raw();    // Creates a new GUID as a string
const parsedGuid = Guid.parse("a1b2c3d4-e5f6-7890-1234-567890abcdef"); // Parses a GUID string

console.log(`\nUser 1 ID (raw string format): ${user1.id.raw()}`);
console.log(`Is emptyGuid really empty? ${emptyGuid.isEmpty()}`); // true
console.log(`Generated raw GUID string: ${rawGuidString}`);
console.log(`Does user1 ID equal user2 ID? ${user1.equals(user2)}`); // false
console.log(`Is "hello-world" a valid Guid string? ${User.isValidUserId("hello-world")}`); // false
console.log(`Is parsedGuid an actual Guid instance? ${User.isValidUserId(parsedGuid)}`); // true
console.log(`Parsed GUID value: ${parsedGuid.toString()}`);