Guid Typescript

1.0.3 · active · verified Sun Apr 19

typescript-guid is a lightweight utility library for generating, parsing, and manipulating Globally Unique Identifiers (GUIDs), also commonly known as UUIDs, within TypeScript and JavaScript environments. The current stable version is 1.0.3. The library offers a comprehensive set of static methods for creating new GUIDs, including empty GUIDs, parsing GUID strings into `Guid` objects, and validating arbitrary values against the GUID format. `Guid` instances support comparisons (case-insensitive since v1.0.1), emptiness checks, and serialization to string or JSON formats. It is a direct evolution of the original `guid-typescript` project, distinguished by its strong emphasis on type safety and a TypeScript-first API design, ensuring seamless integration into modern TypeScript codebases. The project's release cadence is primarily driven by bug fixes and dependency updates, indicating a stable and mature codebase.

Common errors

```
TypeError: Guid is not a constructor
```
cause Attempting to create a `Guid` instance using `new Guid()` instead of a static factory method.

fix Use static factory methods like `Guid.create()` to generate a new GUID, or `Guid.parse(guidString)` to create one from a string.
```
SyntaxError: Named export 'Guid' not found. The requested module 'typescript-guid' does not provide an export named 'Guid'
```
cause This error often occurs when trying to `import { Guid } from 'typescript-guid'` in a CommonJS-only environment where the package might be transpiled or bundled incorrectly, or if the `package.json` entry points are misconfigured for your runtime.

fix Verify that your Node.js project or build setup correctly handles ES Modules. For Node.js, ensure `"type": "module"` is set in your `package.json` or use a transpiler like Babel/TypeScript to convert ESM to CommonJS if strictly necessary for an older runtime.

Warnings

gotcha The `equals` method, used for comparing two `Guid` instances, became case-insensitive starting from version 1.0.1. If your application previously relied on case-sensitive GUID comparisons for any reason, this change might alter behavior.
Fix: Review any code that compares `Guid` objects using the `equals` method. If case-sensitivity was a requirement, you may need to implement custom string comparison after converting GUIDs to string format.
gotcha The library primarily targets modern JavaScript environments and ships with ES module (ESM) syntax. Using `require()` for imports in Node.js projects configured for ESM, or in browser environments without proper transpilation, can lead to runtime errors.
Fix: Always use `import { Guid } from 'typescript-guid';` for importing the library. Ensure your project is configured to handle ES modules (e.g., via `"type": "module"` in `package.json` for Node.js, or a bundler like Webpack/Rollup for browser applications).

Install

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

Imports

Guid
wrong:
```
const { Guid } = require('typescript-guid');
```
correct:
```
import { Guid } from 'typescript-guid';
```
The library primarily uses ES module syntax. While CommonJS might work in some transpiled setups, `import` is the recommended and type-safe approach.
Guid.create
wrong:
```
const newGuid = new Guid();
```
correct:
```
const newGuid = Guid.create();
```
GUIDs are created via static factory methods like `Guid.create()` or `Guid.parse()`, not directly instantiating the class.
Guid.isGuid
wrong:
```
if (myValue instanceof Guid) { /* ... */ }
```
correct:
```
if (Guid.isGuid(myValue)) { /* ... */ }
```
`isGuid` provides robust validation for any type, not just `Guid` instances. `instanceof` only checks the prototype chain.

Quickstart

This quickstart demonstrates creating new GUIDs, parsing existing ones, comparing `Guid` instances, and validating GUID strings. It showcases the primary API methods for common UUID operations.

import { Guid } from "typescript-guid";

// Example class demonstrating basic Guid usage
export class UserProfile {
    public readonly id: Guid;
    public name: string;

    constructor(name: string, existingId?: string) {
        this.id = existingId ? Guid.parse(existingId) : Guid.create();
        this.name = name;
    }

    public equals(otherProfile: UserProfile): boolean {
        return this.id.equals(otherProfile.id);
    }

    public toString(): string {
        return `User: ${this.name}, ID: ${this.id.toString()}`;
    }
}

// Usage example:
const user1 = new UserProfile('Alice');
const user2 = new UserProfile('Bob', user1.id.toString()); // Bob gets Alice's ID
const user3 = new UserProfile('Charlie');

console.log(user1.toString());
console.log(user2.toString());
console.log(user3.toString());
console.log(`Are user1 and user2 the same? ${user1.equals(user2)}`); // Should be true
console.log(`Are user1 and user3 the same? ${user1.equals(user3)}`); // Should be false

// Check if a string is a valid Guid
const potentialGuid = "b77d409a-10cd-4a47-8e94-b0cd0ab50aa1";
console.log(`'${potentialGuid}' is a Guid: ${Guid.isGuid(potentialGuid)}`);

view raw JSON →