feat: add a constructor

thewilkybarkid · Jan 6, 2025 · 8bb8a6f · 8bb8a6f
1 parent b32d121
commit 8bb8a6f
Show file tree

Hide file tree

Showing 4 changed files with 65 additions and 0 deletions.
diff --git a/docs/modules/index.ts.md b/docs/modules/index.ts.md
@@ -13,6 +13,7 @@ Added in v0.1.0
 <h2 class="text-delta">Table of contents</h2>
 
 - [constructors](#constructors)
+  - [Uuid](#uuid)
   - [v4](#v4)
 - [model](#model)
   - [Uuid (type alias)](#uuid-type-alias)
@@ -23,6 +24,26 @@ Added in v0.1.0
 
 # constructors
 
+## Uuid
+
+**Signature**
+
+```ts
+export declare function Uuid(uuid: string): Uuid
+```
+
+**Example**
+
+```ts
+import { Uuid } from 'uuid-ts'
+
+const uuid = Uuid('224d8877-d59f-409f-aed0-5157df78357f')
+
+assert.deepStrictEqual(uuid, '224d8877-d59f-409f-aed0-5157df78357f')
+```
+
+Added in v0.1.1
+
 ## v4
 
 **Signature**

diff --git a/src/index.ts b/src/index.ts
@@ -28,6 +28,25 @@ interface UuidBrand<V extends UuidVersion> {
 // constructors
 // -------------------------------------------------------------------------------------
 
+/**
+ * @example
+ * import { Uuid } from 'uuid-ts'
+ *
+ * const uuid = Uuid('224d8877-d59f-409f-aed0-5157df78357f')
+ *
+ * assert.deepStrictEqual(uuid, '224d8877-d59f-409f-aed0-5157df78357f')
+ *
+ * @category constructors
+ * @since 0.1.1
+ */
+export function Uuid(uuid: string): Uuid {
+  if (!isUuid(uuid)) {
+    throw new Error('Not a UUID')
+  }
+
+  return uuid
+}
+
 /**
  * @category constructors
  * @since 0.1.0

diff --git a/test-d/index.ts b/test-d/index.ts
@@ -30,6 +30,13 @@ expectTypeOf(uuid1).toMatchTypeOf(uuid)
 expectTypeOf(uuid).not.toMatchTypeOf(uuid1)
 expectTypeOf(uuid1).not.toMatchTypeOf(uuid2)
 
+//
+// Uuid
+//
+
+expectTypeOf(_.Uuid(string)).toMatchTypeOf<Uuid>()
+expectTypeOf(_.Uuid(uuid)).toMatchTypeOf<Uuid>()
+
 //
 // v4
 //

diff --git a/test/index.test.ts b/test/index.test.ts
@@ -4,6 +4,24 @@ import * as _ from '../src'
 
 describe('uuid-ts', () => {
   describe('constructors', () => {
+    describe('Uuid', () => {
+      test('with an UUID', () => {
+        fc.assert(
+          fc.property(fc.uuid(), uuid => {
+            expect(_.Uuid(uuid)).toStrictEqual(uuid)
+          }),
+        )
+      })
+
+      test('with a non-UUID', () => {
+        fc.assert(
+          fc.property(fc.anything(), value => {
+            expect(() => _.Uuid(value as string)).toThrow(new Error('Not a UUID'))
+          }),
+        )
+      })
+    })
+
     describe('v4', () => {
       test('generates a v4 UUID', () => {
         const uuid = _.v4()()