From a2c48b3a7790c910a673fa25e45329534ddf31cf Mon Sep 17 00:00:00 2001
From: kobenguyent <7845001+kobenguyent@users.noreply.github.com>
Date: Tue, 5 Aug 2025 12:26:55 +0000
Subject: [PATCH] feat: make falso instantiable

---
 README.md                                | 17 +++++++++++++++--
 package-lock.json                        |  2 +-
 packages/falso/src/falso-class.ts        | 19 +++++++++++++++++++
 packages/falso/src/index.ts              |  1 +
 packages/falso/src/tests/address.spec.ts | 20 ++++++++++++++++++++
 packages/falso/src/tests/amount.spec.ts  |  9 +++++++++
 6 files changed, 65 insertions(+), 3 deletions(-)
 create mode 100644 packages/falso/src/falso-class.ts

diff --git a/README.md b/README.md
index 7dab7c0b6..904cafce0 100644
--- a/README.md
+++ b/README.md
@@ -61,12 +61,25 @@ yarn add @ngneat/falso
 
 ### Usage
 
+#### Static Usage (default)
+
 ```ts
-import { randEmail, randFullName } from '@ngneat/falso';
+import falso, { randEmail, randFullName } from '@ngneat/falso';
 
 const user = { email: randEmail(), name: randFullName() };
-
 const emails = randEmail({ length: 10 });
+
+// Or using the default instance
+const email = falso.randEmail();
+```
+
+#### Instantiable Usage
+
+```ts
+import { Falso } from '@ngneat/falso';
+
+const myFalso = new Falso();
+const email = myFalso.randEmail();
 ```
 
 You can specify the length of elements you want to generate. Below is an example of generating 10 emails with length equal or smaller than 20 characters.
diff --git a/package-lock.json b/package-lock.json
index 2fd7101a5..96a78b520 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -23136,7 +23136,7 @@
     },
     "packages/falso": {
       "name": "@ngneat/falso",
-      "version": "7.3.0",
+      "version": "8.0.2",
       "license": "MIT",
       "dependencies": {
         "seedrandom": "3.0.5",
diff --git a/packages/falso/src/falso-class.ts b/packages/falso/src/falso-class.ts
new file mode 100644
index 000000000..8ba6dcdf0
--- /dev/null
+++ b/packages/falso/src/falso-class.ts
@@ -0,0 +1,19 @@
+import * as generators from './index';
+
+class Falso {
+  [key: string]: any;
+
+  constructor() {
+    // Optionally, allow for custom seeding or config here
+  }
+}
+
+// Attach all generator functions to the Falso prototype
+Object.entries(generators).forEach(([key, fn]) => {
+  if (typeof fn === 'function') {
+    Falso.prototype[key] = fn;
+  }
+});
+
+export { Falso };
+export const falso = new Falso();
diff --git a/packages/falso/src/index.ts b/packages/falso/src/index.ts
index 9ddf5657e..1d174d3e2 100644
--- a/packages/falso/src/index.ts
+++ b/packages/falso/src/index.ts
@@ -1,3 +1,4 @@
+export { Falso, falso } from './falso-class';
 export { randAbbreviation } from './lib/abbreviation';
 export { randAccessory } from './lib/accessory';
 export { randAccount } from './lib/account';
diff --git a/packages/falso/src/tests/address.spec.ts b/packages/falso/src/tests/address.spec.ts
index d4b051475..054708cbb 100644
--- a/packages/falso/src/tests/address.spec.ts
+++ b/packages/falso/src/tests/address.spec.ts
@@ -4,6 +4,7 @@ import * as randCountyFunctions from '../lib/county';
 import * as randCountryFunctions from '../lib/country';
 import * as randZipCodeFunctions from '../lib/zip-code';
 import { randAddress } from '../lib/address';
+import { Falso } from '../falso-class';
 
 describe('randAddress', () => {
   let randStreetAddressSpy: jest.SpyInstance;
@@ -49,6 +50,25 @@ describe('randAddress', () => {
     });
   });
 
+  it('should create address entity using Falso instance', () => {
+    randStreetAddressSpy.mockReturnValue('221B Baker Street');
+    randCitySpy.mockReturnValue('London');
+    randCountySpy.mockReturnValue('Greater London');
+    randCountrySpy.mockReturnValue('United Kingdom');
+    randZipCodeSpy.mockReturnValue('NW1 6XE');
+
+    const falso = new Falso();
+    const result = falso.randAddress();
+
+    expect(result).toEqual({
+      street: '221B Baker Street',
+      city: 'London',
+      county: 'Greater London',
+      country: 'United Kingdom',
+      zipCode: 'NW1 6XE',
+    });
+  });
+
   describe('includeCounty IS passed', () => {
     let includeCounty: boolean;
 
diff --git a/packages/falso/src/tests/amount.spec.ts b/packages/falso/src/tests/amount.spec.ts
index a50c7c848..54a6e7421 100644
--- a/packages/falso/src/tests/amount.spec.ts
+++ b/packages/falso/src/tests/amount.spec.ts
@@ -1,4 +1,5 @@
 import { randAmount } from '../lib/amount';
+import { Falso } from '../falso-class';
 
 describe('amount', () => {
   it('should return a random amount between min and max default values', () => {
@@ -8,6 +9,14 @@ describe('amount', () => {
     expect(res).toBeLessThanOrEqual(max);
   });
 
+  it('should return a random amount using Falso instance', () => {
+    const [min, max] = [1.0, 9999.99];
+    const falso = new Falso();
+    const res = falso.randAmount();
+    expect(res).toBeGreaterThanOrEqual(min);
+    expect(res).toBeLessThanOrEqual(max);
+  });
+
   it('should return a list of random amount between min and max default values', () => {
     const [min, max] = [1.0, 9999.99];
     const res = randAmount({ min, max, length: 10 });