@geekmidas/testkit 10.0.0-alpha.3 → 10.0.0-alpha.30

package/dist/context.d.mts

@@ -0,0 +1,55 @@
+//#region src/context.d.ts
+/**
+ * The test a request belongs to.
+ *
+ * A feature test drives an app the way it runs deployed: a browser calls the
+ * API, the API calls the auth server, each over a URL. In a test those URLs are
+ * served in-process, and every request made on behalf of one test has to reach
+ * *that test's* transactions — its own call to the API, and the API's call to
+ * the auth server made while handling it.
+ *
+ * The id travels two ways. In-process, an `AsyncLocalStorage` carries it
+ * through every await a test and its handlers make. On the wire it is the
+ * `x-test-context-id` header, which a stamped `fetch` adds to every request made
+ * inside a context, so whatever serves the URL can find the context again —
+ * without any caller, including code under test, writing the header.
+ */
+/** The header a test context travels in between client and server. */
+export declare const TEST_CONTEXT_HEADER = "x-test-context-id";
+/**
+ * Which side of a URL the running code is on.
+ *
+ * `client` is the test itself and the frontend it renders — what a browser
+ * does. `server` is a handler serving a request. The difference matters for
+ * cookies: a browser attaches its cookies to what it sends, a server forwards
+ * only what it was handed. A server call that picked up the browser's cookies
+ * would hide the bug of a server that forgets to forward them.
+ */
+export type TestSide = 'client' | 'server';
+export interface TestContext {
+  readonly id: string;
+  readonly side: TestSide;
+}
+/** The context the running code belongs to, if any. */
+export declare function currentTestContext(): TestContext | undefined;
+/** Run `fn` as the client side of the test `id`. */
+export declare function runInTestContext<T>(id: string, fn: () => T): T;
+/**
+ * Run `fn` as a server handling a request for the test `id` — what whatever
+ * serves a URL in-process wraps each request in.
+ */
+export declare function runAsServer<T>(id: string, fn: () => T): T;
+/** The test a request was made for, read off its header. */
+export declare function testContextOf(request: Request): string | undefined;
+/** `fetch`, adding the current test's id to every request made inside one. */
+export declare function stampedFetch(inner: typeof fetch): typeof fetch;
+/**
+ * Stamp the global `fetch` with the current test's id.
+ *
+ * Install it after anything else that patches `fetch` — MSW's interceptor in
+ * particular — so the stamp is added before the request is intercepted.
+ * Returns what puts the previous `fetch` back.
+ */
+export declare function installContextFetch(): () => void;
+//#endregion
+//# sourceMappingURL=context.d.mts.map

package/dist/context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.mts","names":[],"sources":["../src/context.ts"],"mappings":";;;;;;;;;;;;;;;;;qBAmBa;;;;;;;;;;YAWD;iBAEK;WACP;WACA,MAAM;;;wBAMA,sBAAsB;;wBAKtB,iBAAiB,GAAG,YAAY,UAAU,IAAI;;;;;wBAQ9C,YAAY,GAAG,YAAY,UAAU,IAAI;;wBAKzC,cAAc,SAAS;;wBAKvB,aAAa,cAAc,eAAe;;;;;;;;wBAoB1C"}

package/dist/context.mjs

@@ -0,0 +1,73 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/context.ts
+/**
+* The test a request belongs to.
+*
+* A feature test drives an app the way it runs deployed: a browser calls the
+* API, the API calls the auth server, each over a URL. In a test those URLs are
+* served in-process, and every request made on behalf of one test has to reach
+* *that test's* transactions — its own call to the API, and the API's call to
+* the auth server made while handling it.
+*
+* The id travels two ways. In-process, an `AsyncLocalStorage` carries it
+* through every await a test and its handlers make. On the wire it is the
+* `x-test-context-id` header, which a stamped `fetch` adds to every request made
+* inside a context, so whatever serves the URL can find the context again —
+* without any caller, including code under test, writing the header.
+*/
+/** The header a test context travels in between client and server. */
+const TEST_CONTEXT_HEADER = "x-test-context-id";
+const storage = new AsyncLocalStorage();
+/** The context the running code belongs to, if any. */
+function currentTestContext() {
+	return storage.getStore();
+}
+/** Run `fn` as the client side of the test `id`. */
+function runInTestContext(id, fn) {
+	return storage.run({
+		id,
+		side: "client"
+	}, fn);
+}
+/**
+* Run `fn` as a server handling a request for the test `id` — what whatever
+* serves a URL in-process wraps each request in.
+*/
+function runAsServer(id, fn) {
+	return storage.run({
+		id,
+		side: "server"
+	}, fn);
+}
+/** The test a request was made for, read off its header. */
+function testContextOf(request) {
+	return request.headers.get("x-test-context-id") ?? void 0;
+}
+/** `fetch`, adding the current test's id to every request made inside one. */
+function stampedFetch(inner) {
+	return (input, init) => {
+		const context = currentTestContext();
+		if (!context) return inner(input, init);
+		const request = new Request(input, init);
+		if (!request.headers.has("x-test-context-id")) request.headers.set(TEST_CONTEXT_HEADER, context.id);
+		return inner(request);
+	};
+}
+/**
+* Stamp the global `fetch` with the current test's id.
+*
+* Install it after anything else that patches `fetch` — MSW's interceptor in
+* particular — so the stamp is added before the request is intercepted.
+* Returns what puts the previous `fetch` back.
+*/
+function installContextFetch() {
+	const previous = globalThis.fetch;
+	globalThis.fetch = stampedFetch(previous);
+	return () => {
+		globalThis.fetch = previous;
+	};
+}
+//#endregion
+export { TEST_CONTEXT_HEADER, currentTestContext, installContextFetch, runAsServer, runInTestContext, stampedFetch, testContextOf };
+
+//# sourceMappingURL=context.mjs.map

package/dist/context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.mjs","names":[],"sources":["../src/context.ts"],"sourcesContent":["/**\n * The test a request belongs to.\n *\n * A feature test drives an app the way it runs deployed: a browser calls the\n * API, the API calls the auth server, each over a URL. In a test those URLs are\n * served in-process, and every request made on behalf of one test has to reach\n * *that test's* transactions — its own call to the API, and the API's call to\n * the auth server made while handling it.\n *\n * The id travels two ways. In-process, an `AsyncLocalStorage` carries it\n * through every await a test and its handlers make. On the wire it is the\n * `x-test-context-id` header, which a stamped `fetch` adds to every request made\n * inside a context, so whatever serves the URL can find the context again —\n * without any caller, including code under test, writing the header.\n */\n\nimport { AsyncLocalStorage } from 'node:async_hooks';\n\n/** The header a test context travels in between client and server. */\nexport const TEST_CONTEXT_HEADER = 'x-test-context-id';\n\n/**\n * Which side of a URL the running code is on.\n *\n * `client` is the test itself and the frontend it renders — what a browser\n * does. `server` is a handler serving a request. The difference matters for\n * cookies: a browser attaches its cookies to what it sends, a server forwards\n * only what it was handed. A server call that picked up the browser's cookies\n * would hide the bug of a server that forgets to forward them.\n */\nexport type TestSide = 'client' | 'server';\n\nexport interface TestContext {\n\treadonly id: string;\n\treadonly side: TestSide;\n}\n\nconst storage = new AsyncLocalStorage<TestContext>();\n\n/** The context the running code belongs to, if any. */\nexport function currentTestContext(): TestContext | undefined {\n\treturn storage.getStore();\n}\n\n/** Run `fn` as the client side of the test `id`. */\nexport function runInTestContext<T>(id: string, fn: () => T): T {\n\treturn storage.run({ id, side: 'client' }, fn);\n}\n\n/**\n * Run `fn` as a server handling a request for the test `id` — what whatever\n * serves a URL in-process wraps each request in.\n */\nexport function runAsServer<T>(id: string, fn: () => T): T {\n\treturn storage.run({ id, side: 'server' }, fn);\n}\n\n/** The test a request was made for, read off its header. */\nexport function testContextOf(request: Request): string | undefined {\n\treturn request.headers.get(TEST_CONTEXT_HEADER) ?? undefined;\n}\n\n/** `fetch`, adding the current test's id to every request made inside one. */\nexport function stampedFetch(inner: typeof fetch): typeof fetch {\n\treturn (input, init) => {\n\t\tconst context = currentTestContext();\n\t\tif (!context) return inner(input, init);\n\n\t\tconst request = new Request(input, init);\n\t\tif (!request.headers.has(TEST_CONTEXT_HEADER)) {\n\t\t\trequest.headers.set(TEST_CONTEXT_HEADER, context.id);\n\t\t}\n\t\treturn inner(request);\n\t};\n}\n\n/**\n * Stamp the global `fetch` with the current test's id.\n *\n * Install it after anything else that patches `fetch` — MSW's interceptor in\n * particular — so the stamp is added before the request is intercepted.\n * Returns what puts the previous `fetch` back.\n */\nexport function installContextFetch(): () => void {\n\tconst previous = globalThis.fetch;\n\tglobalThis.fetch = stampedFetch(previous);\n\treturn () => {\n\t\tglobalThis.fetch = previous;\n\t};\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAmBA,MAAa,sBAAsB;AAkBnC,MAAM,UAAU,IAAI,kBAA+B;;AAGnD,SAAgB,qBAA8C;CAC7D,OAAO,QAAQ,SAAS;AACzB;;AAGA,SAAgB,iBAAoB,IAAY,IAAgB;CAC/D,OAAO,QAAQ,IAAI;EAAE;EAAI,MAAM;CAAS,GAAG,EAAE;AAC9C;;;;;AAMA,SAAgB,YAAe,IAAY,IAAgB;CAC1D,OAAO,QAAQ,IAAI;EAAE;EAAI,MAAM;CAAS,GAAG,EAAE;AAC9C;;AAGA,SAAgB,cAAc,SAAsC;CACnE,OAAO,QAAQ,QAAQ,IAAA,mBAAuB,KAAK,KAAA;AACpD;;AAGA,SAAgB,aAAa,OAAmC;CAC/D,QAAQ,OAAO,SAAS;EACvB,MAAM,UAAU,mBAAmB;EACnC,IAAI,CAAC,SAAS,OAAO,MAAM,OAAO,IAAI;EAEtC,MAAM,UAAU,IAAI,QAAQ,OAAO,IAAI;EACvC,IAAI,CAAC,QAAQ,QAAQ,IAAA,mBAAuB,GAC3C,QAAQ,QAAQ,IAAI,qBAAqB,QAAQ,EAAE;EAEpD,OAAO,MAAM,OAAO;CACrB;AACD;;;;;;;;AASA,SAAgB,sBAAkC;CACjD,MAAM,WAAW,WAAW;CAC5B,WAAW,QAAQ,aAAa,QAAQ;CACxC,aAAa;EACZ,WAAW,QAAQ;CACpB;AACD"}

package/dist/faker.cjs

@@ -1,9 +1,263 @@
-const require_faker = require('./faker-B14IEMIN.cjs');
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _faker_js_faker = require("@faker-js/faker");
+//#region src/faker.ts
+/**
+* Atomic counter implementation for thread-safe sequence generation.
+* Provides a clean abstraction for generating sequential numbers in tests.
+* While JavaScript is single-threaded, this class makes the intent explicit.
+*
+* @example
+* ```typescript
+* const counter = new AtomicCounter(100);
+* console.log(counter.increment()); // 101
+* console.log(counter.increment()); // 102
+* console.log(counter.get()); // 102
+* counter.reset(200);
+* console.log(counter.increment()); // 201
+* ```
+*/
+var AtomicCounter = class {
+	/**
+	* The current counter value.
+	* @private
+	*/
+	value;
+	/**
+	* Creates a new atomic counter.
+	* @param initialValue - The starting value (default: 0)
+	*/
+	constructor(initialValue = 0) {
+		this.value = initialValue;
+	}
+	/**
+	* Increments the counter and returns the new value.
+	* @returns The incremented value
+	*/
+	increment() {
+		return ++this.value;
+	}
+	/**
+	* Gets the current counter value without incrementing.
+	* @returns The current value
+	*/
+	get() {
+		return this.value;
+	}
+	/**
+	* Resets the counter to a specific value.
+	* @param value - The new value (default: 0)
+	*/
+	reset(value = 0) {
+		this.value = value;
+	}
+};
+/**
+* Generates random timestamp fields for database records.
+* Creates a createdAt date in the past and an updatedAt date between creation and now.
+* Milliseconds are set to 0 for cleaner database storage.
+*
+* @returns Object with createdAt and updatedAt Date fields
+*
+* @example
+* ```typescript
+* const { createdAt, updatedAt } = timestamps();
+* console.log(createdAt); // 2023-05-15T10:30:00.000Z
+* console.log(updatedAt); // 2023-11-20T14:45:00.000Z
+*
+* // Use in factory
+* const user = {
+*   name: 'John Doe',
+*   ...timestamps()
+* };
+* ```
+*/
+function timestamps() {
+	const createdAt = faker.date.past();
+	const updatedAt = faker.date.between({
+		from: createdAt,
+		to: /* @__PURE__ */ new Date()
+	});
+	createdAt.setMilliseconds(0);
+	updatedAt.setMilliseconds(0);
+	return {
+		createdAt,
+		updatedAt
+	};
+}
+/**
+* Generates a reverse domain name identifier.
+* Useful for creating unique identifiers that follow domain naming conventions.
+*
+* @param suffix - Optional suffix to append to the identifier
+* @returns A reverse domain name string (e.g., "com.example.feature123")
+*
+* @example
+* ```typescript
+* console.log(identifier()); // "com.example.widget1"
+* console.log(identifier('user')); // "org.acme.user"
+* console.log(identifier('api')); // "net.demo.api"
+* ```
+*/
+function identifier(suffix) {
+	return [
+		faker.internet.domainSuffix(),
+		faker.internet.domainWord(),
+		suffix ? suffix : faker.internet.domainWord() + sequence("identifier")
+	].join(".");
+}
+/**
+* Storage for named sequence counters.
+* Each sequence maintains its own independent counter.
+* @private
+*/
+const sequences = /* @__PURE__ */ new Map();
+/**
+* Generates sequential numbers for a named sequence.
+* Useful for creating unique IDs or numbered test data.
+* Each named sequence maintains its own counter.
+*
+* @param name - The sequence name (default: 'default')
+* @returns The next number in the sequence
+*
+* @example
+* ```typescript
+* console.log(sequence()); // 1
+* console.log(sequence()); // 2
+* console.log(sequence('user')); // 1
+* console.log(sequence('user')); // 2
+* console.log(sequence()); // 3
+*
+* // Use in factories
+* const email = `user${sequence('email')}@example.com`;
+* ```
+*/
+function sequence(name = "default") {
+	if (!sequences.has(name)) sequences.set(name, new AtomicCounter());
+	return sequences.get(name).increment();
+}
+/**
+* Resets a named sequence counter to a specific value.
+* Useful for resetting sequences between test suites.
+*
+* @param name - The sequence name to reset (default: 'default')
+* @param value - The new starting value (default: 0)
+*
+* @example
+* ```typescript
+* sequence('user'); // 1
+* sequence('user'); // 2
+* resetSequence('user');
+* sequence('user'); // 1
+*
+* resetSequence('order', 1000);
+* sequence('order'); // 1001
+* ```
+*/
+function resetSequence(name = "default", value = 0) {
+	if (sequences.has(name)) sequences.get(name).reset(value);
+	else sequences.set(name, new AtomicCounter(value));
+}
+/**
+* Resets all sequence counters.
+* Useful for cleaning up between test suites to ensure predictable sequences.
+*
+* @example
+* ```typescript
+* // In test setup
+* beforeEach(() => {
+*   resetAllSequences();
+* });
+*
+* it('starts sequences from 1', () => {
+*   expect(sequence()).toBe(1);
+*   expect(sequence('user')).toBe(1);
+* });
+* ```
+*/
+function resetAllSequences() {
+	sequences.clear();
+}
+/**
+* Generates a random price as a number.
+* Converts faker's string price to a numeric value.
+*
+* @returns A random price number
+*
+* @example
+* ```typescript
+* const productPrice = price(); // 29.99
+* const total = price() * quantity; // Numeric calculation
+* ```
+*/
+function price() {
+	return +faker.commerce.price();
+}
+function coordinateInRadius(center, radius) {
+	const d = radius / 6378137;
+	const theta = 2 * Math.PI * Math.random();
+	const r = d * Math.sqrt(Math.random());
+	const lat1 = center.lat * Math.PI / 180;
+	const lng1 = center.lng * Math.PI / 180;
+	const lat2 = Math.asin(Math.sin(lat1) * Math.cos(r) + Math.cos(lat1) * Math.sin(r) * Math.cos(theta));
+	const lng2 = lng1 + Math.atan2(Math.sin(theta) * Math.sin(r) * Math.cos(lat1), Math.cos(r) - Math.sin(lat1) * Math.sin(lat2));
+	return {
+		lat: lat2 * 180 / Math.PI,
+		lng: lng2 * 180 / Math.PI
+	};
+}
+function coordinateOutsideRadius(center, minRadiusMeters, maxRadiusMeters) {
+	const earth = 6378137;
+	const minD = minRadiusMeters / earth;
+	const maxD = maxRadiusMeters / earth;
+	const theta = 2 * Math.PI * Math.random();
+	const r = Math.sqrt(minD * minD + (maxD * maxD - minD * minD) * Math.random());
+	const lat1 = center.lat * Math.PI / 180;
+	const lng1 = center.lng * Math.PI / 180;
+	const lat2 = Math.asin(Math.sin(lat1) * Math.cos(r) + Math.cos(lat1) * Math.sin(r) * Math.cos(theta));
+	const normalizedLng = ((lng1 + Math.atan2(Math.sin(theta) * Math.sin(r) * Math.cos(lat1), Math.cos(r) - Math.sin(lat1) * Math.sin(lat2))) * 180 / Math.PI + 540) % 360 - 180;
+	return {
+		lat: lat2 * 180 / Math.PI,
+		lng: normalizedLng
+	};
+}
+/**
+* Enhanced faker instance with additional utility methods for testing.
+* Extends @faker-js/faker with custom methods for common test data generation patterns.
+*
+* @example
+* ```typescript
+* import { faker } from '@geekmidas/testkit';
+*
+* // Use standard faker methods
+* const name = faker.person.fullName();
+* const email = faker.internet.email();
+*
+* // Use custom extensions
+* const { createdAt, updatedAt } = faker.timestamps();
+* const id = faker.identifier('user');
+* const orderNumber = faker.sequence('order');
+* const productPrice = faker.price();
+* ```
+*/
+const faker = Object.freeze(Object.assign({}, _faker_js_faker.faker, {
+	timestamps,
+	identifier,
+	sequence,
+	resetSequence,
+	resetAllSequences,
+	price,
+	coordinates: {
+		within: coordinateInRadius,
+		outside: coordinateOutsideRadius
+	}
+}));
+//#endregion
+exports.coordinateInRadius = coordinateInRadius;
+exports.faker = faker;
+exports.identifier = identifier;
+exports.resetAllSequences = resetAllSequences;
+exports.resetSequence = resetSequence;
+exports.sequence = sequence;
+exports.timestamps = timestamps;
 
-exports.coordinateInRadius = require_faker.coordinateInRadius;
-exports.faker = require_faker.faker;
-exports.identifier = require_faker.identifier;
-exports.resetAllSequences = require_faker.resetAllSequences;
-exports.resetSequence = require_faker.resetSequence;
-exports.sequence = require_faker.sequence;
-exports.timestamps = require_faker.timestamps;
+//# sourceMappingURL=faker.cjs.map

package/dist/faker.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"faker.cjs","names":["baseFaker"],"sources":["../src/faker.ts"],"sourcesContent":["import { faker as baseFaker } from '@faker-js/faker';\n\n// NOTE: This is a simple way to extend `faker` with additional methods\n\n/**\n * Atomic counter implementation for thread-safe sequence generation.\n * Provides a clean abstraction for generating sequential numbers in tests.\n * While JavaScript is single-threaded, this class makes the intent explicit.\n *\n * @example\n * ```typescript\n * const counter = new AtomicCounter(100);\n * console.log(counter.increment()); // 101\n * console.log(counter.increment()); // 102\n * console.log(counter.get()); // 102\n * counter.reset(200);\n * console.log(counter.increment()); // 201\n * ```\n */\nclass AtomicCounter {\n\t/**\n\t * The current counter value.\n\t * @private\n\t */\n\tprivate value: number;\n\n\t/**\n\t * Creates a new atomic counter.\n\t * @param initialValue - The starting value (default: 0)\n\t */\n\tconstructor(initialValue = 0) {\n\t\tthis.value = initialValue;\n\t}\n\n\t/**\n\t * Increments the counter and returns the new value.\n\t * @returns The incremented value\n\t */\n\tincrement(): number {\n\t\t// In Node.js, JavaScript is single-threaded within the event loop,\n\t\t// so this operation is already atomic. However, this class provides\n\t\t// a cleaner abstraction and makes the intent explicit.\n\t\treturn ++this.value;\n\t}\n\n\t/**\n\t * Gets the current counter value without incrementing.\n\t * @returns The current value\n\t */\n\tget(): number {\n\t\treturn this.value;\n\t}\n\n\t/**\n\t * Resets the counter to a specific value.\n\t * @param value - The new value (default: 0)\n\t */\n\treset(value = 0): void {\n\t\tthis.value = value;\n\t}\n}\n\n/**\n * Generates random timestamp fields for database records.\n * Creates a createdAt date in the past and an updatedAt date between creation and now.\n * Milliseconds are set to 0 for cleaner database storage.\n *\n * @returns Object with createdAt and updatedAt Date fields\n *\n * @example\n * ```typescript\n * const { createdAt, updatedAt } = timestamps();\n * console.log(createdAt); // 2023-05-15T10:30:00.000Z\n * console.log(updatedAt); // 2023-11-20T14:45:00.000Z\n *\n * // Use in factory\n * const user = {\n *   name: 'John Doe',\n *   ...timestamps()\n * };\n * ```\n */\nexport function timestamps(): Timestamps {\n\tconst createdAt = faker.date.past();\n\tconst updatedAt = faker.date.between({\n\t\tfrom: createdAt,\n\t\tto: new Date(),\n\t});\n\n\tcreatedAt.setMilliseconds(0);\n\tupdatedAt.setMilliseconds(0);\n\n\treturn { createdAt, updatedAt };\n}\n\n/**\n * Generates a reverse domain name identifier.\n * Useful for creating unique identifiers that follow domain naming conventions.\n *\n * @param suffix - Optional suffix to append to the identifier\n * @returns A reverse domain name string (e.g., \"com.example.feature123\")\n *\n * @example\n * ```typescript\n * console.log(identifier()); // \"com.example.widget1\"\n * console.log(identifier('user')); // \"org.acme.user\"\n * console.log(identifier('api')); // \"net.demo.api\"\n * ```\n */\nexport function identifier(suffix?: string): string {\n\treturn [\n\t\tfaker.internet.domainSuffix(),\n\t\tfaker.internet.domainWord(),\n\t\tsuffix ? suffix : faker.internet.domainWord() + sequence('identifier'),\n\t].join('.');\n}\n\n/**\n * Storage for named sequence counters.\n * Each sequence maintains its own independent counter.\n * @private\n */\nconst sequences = new Map<string, AtomicCounter>();\n\n/**\n * Generates sequential numbers for a named sequence.\n * Useful for creating unique IDs or numbered test data.\n * Each named sequence maintains its own counter.\n *\n * @param name - The sequence name (default: 'default')\n * @returns The next number in the sequence\n *\n * @example\n * ```typescript\n * console.log(sequence()); // 1\n * console.log(sequence()); // 2\n * console.log(sequence('user')); // 1\n * console.log(sequence('user')); // 2\n * console.log(sequence()); // 3\n *\n * // Use in factories\n * const email = `user${sequence('email')}@example.com`;\n * ```\n */\nexport function sequence(name = 'default'): number {\n\tif (!sequences.has(name)) {\n\t\tsequences.set(name, new AtomicCounter());\n\t}\n\n\tconst counter = sequences.get(name) as AtomicCounter;\n\treturn counter.increment();\n}\n\n/**\n * Resets a named sequence counter to a specific value.\n * Useful for resetting sequences between test suites.\n *\n * @param name - The sequence name to reset (default: 'default')\n * @param value - The new starting value (default: 0)\n *\n * @example\n * ```typescript\n * sequence('user'); // 1\n * sequence('user'); // 2\n * resetSequence('user');\n * sequence('user'); // 1\n *\n * resetSequence('order', 1000);\n * sequence('order'); // 1001\n * ```\n */\nexport function resetSequence(name = 'default', value = 0): void {\n\tif (sequences.has(name)) {\n\t\tconst counter = sequences.get(name) as AtomicCounter;\n\t\tcounter.reset(value);\n\t} else {\n\t\tsequences.set(name, new AtomicCounter(value));\n\t}\n}\n\n/**\n * Resets all sequence counters.\n * Useful for cleaning up between test suites to ensure predictable sequences.\n *\n * @example\n * ```typescript\n * // In test setup\n * beforeEach(() => {\n *   resetAllSequences();\n * });\n *\n * it('starts sequences from 1', () => {\n *   expect(sequence()).toBe(1);\n *   expect(sequence('user')).toBe(1);\n * });\n * ```\n */\nexport function resetAllSequences(): void {\n\tsequences.clear();\n}\n\n/**\n * Generates a random price as a number.\n * Converts faker's string price to a numeric value.\n *\n * @returns A random price number\n *\n * @example\n * ```typescript\n * const productPrice = price(); // 29.99\n * const total = price() * quantity; // Numeric calculation\n * ```\n */\nfunction price(): number {\n\treturn +faker.commerce.price();\n}\n\ntype Coordinate = {\n\tlat: number;\n\tlng: number;\n};\n\nexport function coordinateInRadius(\n\tcenter: Coordinate,\n\tradius: number,\n): Coordinate {\n\t// Earth's radius in meters\n\tconst earth = 6378137;\n\t// Convert radius from meters to degrees\n\tconst d = radius / earth;\n\n\t// Random bearing and distance\n\tconst theta = 2 * Math.PI * Math.random();\n\tconst r = d * Math.sqrt(Math.random());\n\n\tconst lat1 = (center.lat * Math.PI) / 180;\n\tconst lng1 = (center.lng * Math.PI) / 180;\n\n\tconst lat2 = Math.asin(\n\t\tMath.sin(lat1) * Math.cos(r) +\n\t\t\tMath.cos(lat1) * Math.sin(r) * Math.cos(theta),\n\t);\n\tconst lng2 =\n\t\tlng1 +\n\t\tMath.atan2(\n\t\t\tMath.sin(theta) * Math.sin(r) * Math.cos(lat1),\n\t\t\tMath.cos(r) - Math.sin(lat1) * Math.sin(lat2),\n\t\t);\n\n\treturn {\n\t\tlat: (lat2 * 180) / Math.PI,\n\t\tlng: (lng2 * 180) / Math.PI,\n\t};\n}\n\nfunction coordinateOutsideRadius(\n\tcenter: Coordinate,\n\tminRadiusMeters: number,\n\tmaxRadiusMeters: number,\n): Coordinate {\n\t// Earth's radius in meters\n\tconst earth = 6378137;\n\n\t// Convert radii from meters to radians\n\tconst minD = minRadiusMeters / earth;\n\tconst maxD = maxRadiusMeters / earth;\n\n\t// Random bearing\n\tconst theta = 2 * Math.PI * Math.random();\n\n\t// Random distance in annular ring (uniform distribution by area)\n\t// For uniform distribution in annulus: r = sqrt(r_min² + (r_max² - r_min²) * random)\n\tconst r = Math.sqrt(\n\t\tminD * minD + (maxD * maxD - minD * minD) * Math.random(),\n\t);\n\n\tconst lat1 = (center.lat * Math.PI) / 180;\n\tconst lng1 = (center.lng * Math.PI) / 180;\n\n\tconst lat2 = Math.asin(\n\t\tMath.sin(lat1) * Math.cos(r) +\n\t\t\tMath.cos(lat1) * Math.sin(r) * Math.cos(theta),\n\t);\n\tconst lng2 =\n\t\tlng1 +\n\t\tMath.atan2(\n\t\t\tMath.sin(theta) * Math.sin(r) * Math.cos(lat1),\n\t\t\tMath.cos(r) - Math.sin(lat1) * Math.sin(lat2),\n\t\t);\n\n\t// Normalize longitude to [-180, 180]\n\tconst normalizedLng = (((lng2 * 180) / Math.PI + 540) % 360) - 180;\n\n\treturn {\n\t\tlat: (lat2 * 180) / Math.PI,\n\t\tlng: normalizedLng,\n\t};\n}\n\n/**\n * Enhanced faker instance with additional utility methods for testing.\n * Extends @faker-js/faker with custom methods for common test data generation patterns.\n *\n * @example\n * ```typescript\n * import { faker } from '@geekmidas/testkit';\n *\n * // Use standard faker methods\n * const name = faker.person.fullName();\n * const email = faker.internet.email();\n *\n * // Use custom extensions\n * const { createdAt, updatedAt } = faker.timestamps();\n * const id = faker.identifier('user');\n * const orderNumber = faker.sequence('order');\n * const productPrice = faker.price();\n * ```\n */\nexport const faker = Object.freeze(\n\tObject.assign({}, baseFaker, {\n\t\ttimestamps,\n\t\tidentifier,\n\t\tsequence,\n\t\tresetSequence,\n\t\tresetAllSequences,\n\t\tprice,\n\t\tcoordinates: {\n\t\t\twithin: coordinateInRadius,\n\t\t\toutside: coordinateOutsideRadius,\n\t\t},\n\t}),\n);\n\n/**\n * Type definition for timestamp fields.\n * Used by the timestamps() function to generate date fields.\n */\nexport type Timestamps = {\n\t/** The creation date */\n\tcreatedAt: Date;\n\t/** The last update date */\n\tupdatedAt: Date;\n};\n\n/**\n * Type definition for the enhanced faker factory.\n * Includes all standard faker methods plus custom extensions.\n */\nexport type FakerFactory = typeof faker;\n"],"mappings":"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"}

package/dist/faker.d.cts

@@ -1,2 +1,162 @@
-import { FakerFactory, Timestamps, coordinateInRadius, faker, identifier, resetAllSequences, resetSequence, sequence, timestamps } from "./faker-Cg76aFNO.cjs";
-export { FakerFactory, Timestamps, coordinateInRadius, faker, identifier, resetAllSequences, resetSequence, sequence, timestamps };
+//#region src/faker.d.ts
+/**
+ * Generates random timestamp fields for database records.
+ * Creates a createdAt date in the past and an updatedAt date between creation and now.
+ * Milliseconds are set to 0 for cleaner database storage.
+ *
+ * @returns Object with createdAt and updatedAt Date fields
+ *
+ * @example
+ * ```typescript
+ * const { createdAt, updatedAt } = timestamps();
+ * console.log(createdAt); // 2023-05-15T10:30:00.000Z
+ * console.log(updatedAt); // 2023-11-20T14:45:00.000Z
+ *
+ * // Use in factory
+ * const user = {
+ *   name: 'John Doe',
+ *   ...timestamps()
+ * };
+ * ```
+ */
+export declare function timestamps(): Timestamps;
+/**
+ * Generates a reverse domain name identifier.
+ * Useful for creating unique identifiers that follow domain naming conventions.
+ *
+ * @param suffix - Optional suffix to append to the identifier
+ * @returns A reverse domain name string (e.g., "com.example.feature123")
+ *
+ * @example
+ * ```typescript
+ * console.log(identifier()); // "com.example.widget1"
+ * console.log(identifier('user')); // "org.acme.user"
+ * console.log(identifier('api')); // "net.demo.api"
+ * ```
+ */
+export declare function identifier(suffix?: string): string;
+/**
+ * Generates sequential numbers for a named sequence.
+ * Useful for creating unique IDs or numbered test data.
+ * Each named sequence maintains its own counter.
+ *
+ * @param name - The sequence name (default: 'default')
+ * @returns The next number in the sequence
+ *
+ * @example
+ * ```typescript
+ * console.log(sequence()); // 1
+ * console.log(sequence()); // 2
+ * console.log(sequence('user')); // 1
+ * console.log(sequence('user')); // 2
+ * console.log(sequence()); // 3
+ *
+ * // Use in factories
+ * const email = `user${sequence('email')}@example.com`;
+ * ```
+ */
+export declare function sequence(name?: string): number;
+/**
+ * Resets a named sequence counter to a specific value.
+ * Useful for resetting sequences between test suites.
+ *
+ * @param name - The sequence name to reset (default: 'default')
+ * @param value - The new starting value (default: 0)
+ *
+ * @example
+ * ```typescript
+ * sequence('user'); // 1
+ * sequence('user'); // 2
+ * resetSequence('user');
+ * sequence('user'); // 1
+ *
+ * resetSequence('order', 1000);
+ * sequence('order'); // 1001
+ * ```
+ */
+export declare function resetSequence(name?: string, value?: number): void;
+/**
+ * Resets all sequence counters.
+ * Useful for cleaning up between test suites to ensure predictable sequences.
+ *
+ * @example
+ * ```typescript
+ * // In test setup
+ * beforeEach(() => {
+ *   resetAllSequences();
+ * });
+ *
+ * it('starts sequences from 1', () => {
+ *   expect(sequence()).toBe(1);
+ *   expect(sequence('user')).toBe(1);
+ * });
+ * ```
+ */
+export declare function resetAllSequences(): void;
+/**
+ * Generates a random price as a number.
+ * Converts faker's string price to a numeric value.
+ *
+ * @returns A random price number
+ *
+ * @example
+ * ```typescript
+ * const productPrice = price(); // 29.99
+ * const total = price() * quantity; // Numeric calculation
+ * ```
+ */
+declare function price(): number;
+type Coordinate = {
+  lat: number;
+  lng: number;
+};
+export declare function coordinateInRadius(center: Coordinate, radius: number): Coordinate;
+declare function coordinateOutsideRadius(center: Coordinate, minRadiusMeters: number, maxRadiusMeters: number): Coordinate;
+/**
+ * Enhanced faker instance with additional utility methods for testing.
+ * Extends @faker-js/faker with custom methods for common test data generation patterns.
+ *
+ * @example
+ * ```typescript
+ * import { faker } from '@geekmidas/testkit';
+ *
+ * // Use standard faker methods
+ * const name = faker.person.fullName();
+ * const email = faker.internet.email();
+ *
+ * // Use custom extensions
+ * const { createdAt, updatedAt } = faker.timestamps();
+ * const id = faker.identifier('user');
+ * const orderNumber = faker.sequence('order');
+ * const productPrice = faker.price();
+ * ```
+ */
+export declare const faker: Readonly<import("@faker-js/faker").Faker & {
+  timestamps: typeof timestamps;
+  identifier: typeof identifier;
+  sequence: typeof sequence;
+  resetSequence: typeof resetSequence;
+  resetAllSequences: typeof resetAllSequences;
+  price: typeof price;
+  coordinates: {
+    within: typeof coordinateInRadius;
+    outside: typeof coordinateOutsideRadius;
+  };
+}>;
+/**
+ * Type definition for timestamp fields.
+ * Used by the timestamps() function to generate date fields.
+ */
+export type Timestamps = {
+  /** The creation date */
+  createdAt: Date;
+  /** The last update date */
+  updatedAt: Date;
+};
+/**
+ * Type definition for the enhanced faker factory.
+ * Includes all standard faker methods plus custom extensions.
+ */
+export type FakerFactory = typeof faker;
+//#endregion
+//# sourceMappingURL=faker.d.cts.map

package/dist/faker.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"faker.d.cts","names":[],"sources":["../src/faker.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;wBAkFgB,cAAc;;;;;;;;;;;;;;;wBA2Bd,WAAW;;;;;;;;;;;;;;;;;;;;;wBAmCX,SAAS;;;;;;;;;;;;;;;;;;;wBA2BT,cAAc,eAAkB;;;;;;;;;;;;;;;;;;wBA0BhC;;;;;;;;;;;;;iBAgBP;KAIJ;EACJ;EACA;;wBAGe,mBACf,QAAQ,YACR,iBACE;iBA8BM,wBACR,QAAQ,YACR,yBACA,0BACE;;;;;;;;;;;;;;;;;;;;qBA2DU,OAAK,mCAAA;;;;;;;;IASf,eAAM;IACN,gBAAO;;;;;;;YASE;;EAEX,WAAW;;EAEX,WAAW;;;;;;YAOA,sBAAsB"}