@poppinss/utils 7.0.0 → 7.1.0

package/README.md

@@ -119,6 +119,55 @@ import lodash from '@poppinss/utils/lodash'
 lodash.pick(collection, keys)
 ```
 
+## Number helpers
+
+The number helpers are available from the `@poppinss/utils/number` subpath.
+
+```ts
+import number from '@poppinss/utils/number'
+```
+
+### clamp
+
+Constrain a number to an inclusive range.
+
+```ts
+number.clamp(15, 0, 10) // 10
+number.clamp(-2, 0, 10) // 0
+number.clamp(5, 0, 10) // 5
+```
+
+### between
+
+Check whether a number is inside an inclusive range. You may specify the bounds in either order.
+
+```ts
+number.between(5, 0, 10) // true
+number.between(5, 10, 0) // true
+number.between(11, 0, 10) // false
+```
+
+### toFinite
+
+Convert a value to a finite number. The method returns `0` when conversion fails or produces a non-finite number. You may provide a different fallback as the second argument.
+
+```ts
+number.toFinite('42') // 42
+number.toFinite('invalid') // 0
+number.toFinite(Number.POSITIVE_INFINITY, 10) // 10
+```
+
+### parse
+
+Convert a value to a finite number without using a fallback. The method returns `null` for empty input, failed conversions, and non-finite numbers.
+
+```ts
+number.parse('42') // 42
+number.parse('') // null
+number.parse('invalid') // null
+number.parse(Number.POSITIVE_INFINITY) // null
+```
+
 ## FS helpers
 
 ### fsReadAll
@@ -457,6 +506,17 @@ flatten({
 // }
 ```
 
+## unique
+
+Return a new array with duplicate values removed while preserving the first occurrence order.
+
+```ts
+import { unique } from '@poppinss/utils'
+
+unique(['foo', 'bar', 'foo', 'baz'])
+// ['foo', 'bar', 'baz']
+```
+
 ## isScriptFile
 
 A filter to know if the file path ends with `.js`, `.json`, `.cjs`, `.mjs`, or `.ts`. In the case of `.ts` files, the `.d.ts` returns false.
@@ -496,6 +556,32 @@ const values = ['1_foo_bar', '12_foo_bar'].sort(naturalSort)
 // Default sorting: ['1_foo_bar', '12_foo_bar']
 ```
 
+## getGitWorktree
+
+Returns information about the linked Git worktree containing the current working directory. The method returns `null` when called from the primary worktree, outside a Git repository, or when Git is unavailable.
+
+```ts
+import { getGitWorktree } from '@poppinss/utils'
+
+const worktree = await getGitWorktree()
+
+if (worktree) {
+  console.log(worktree)
+  // {
+  //   name: 'feature-auth',
+  //   slug: 'feature-auth',
+  //   hash: '8d31cbe490f2',
+  //   path: '/projects/worktrees/feature-auth'
+  // }
+}
+```
+
+You may pass a different directory as the first argument. The `slug` is URL-safe, and the `hash` contains the first twelve characters of a SHA-256 hash generated from the canonical worktree path.
+
+```ts
+await getGitWorktree('/projects/worktrees/feature-auth/server')
+```
+
 ## safeEqual
 
 Check if two buffer or string values are the same. This method does not leak any timing information and prevents [timing attack](https://javascript.plainenglish.io/what-are-timing-attacks-and-how-to-prevent-them-using-nodejs-158cc7e2d70c).

package/build/index.d.ts

@@ -1,6 +1,7 @@
 export { Secret } from './src/secret.js';
 export { compose } from './src/compose.js';
 export { flatten } from './src/flatten.js';
+export { unique } from './src/unique.js';
 export { safeEqual } from './src/safe_equal.js';
 export { naturalSort } from './src/natural_sort.js';
 export { isScriptFile } from './src/is_script_file.js';
@@ -9,3 +10,4 @@ export { MessageBuilder } from './src/message_builder.js';
 export { ImportsBag, type ImportInfo } from './src/imports_bag.js';
 export { defineStaticProperty } from './src/define_static_property.js';
 export { detectAIAgent, isRunningInAIAgent } from './src/detect_ai_agent.js';
+export { getGitWorktree, type GitWorktree } from './src/get_git_worktree.js';

package/build/index.js

@@ -1,14 +1,27 @@
-import { n as safeParse, t as safeStringify } from "./safe_stringify-DenlQd3-.js";
-import { n as naturalSort, t as isScriptFile } from "./is_script_file-CbSEfxE_.js";
+import { n as safeParse, t as safeStringify } from "./main-B9qlOEvt.js";
+import { n as naturalSort, t as isScriptFile } from "./is_script_file-D0Om5zlQ.js";
 import { RuntimeException } from "./modules/exception.js";
-import "./modules/json/main.js";
 import { flattie } from "flattie";
 import { Buffer } from "node:buffer";
-import { timingSafeEqual } from "node:crypto";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { basename, isAbsolute, relative, sep } from "node:path";
 import string from "@poppinss/string";
 import lodash from "@poppinss/utils/lodash";
+import { promisify } from "node:util";
+import { realpath } from "node:fs/promises";
+import { execFile } from "node:child_process";
+//#region src/secret.ts
 const REDACTED = "[redacted]";
+/**
+* Define a Secret value that hides itself from the logs or the console
+* statements.
+*
+* The idea is to prevent accidental leaking of sensitive information.
+* Idea borrowed from.
+* https://transcend.io/blog/keep-sensitive-values-out-of-your-logs-with-types
+*/
 var Secret = class Secret {
+	/** The secret value */
 	#value;
 	#keyword;
 	constructor(value, redactedKeyword) {
@@ -30,64 +43,156 @@ var Secret = class Secret {
 	toString() {
 		return this.#keyword;
 	}
+	/**
+	* Returns the original value
+	*/
 	release() {
 		return this.#value;
 	}
+	/**
+	* Transform the original value and create a new
+	* secret from it.
+	*/
 	map(transformFunc) {
 		return new Secret(transformFunc(this.#value));
 	}
 };
+//#endregion
+//#region src/compose.ts
 function compose(superclass, ...mixins) {
 	return mixins.reduce((c, mixin) => mixin(c), superclass);
 }
+//#endregion
+//#region src/flatten.ts
+/**
+* Recursively flatten an object/array.
+*/
 function flatten(input, glue, keepNullish) {
 	return flattie(input, glue, keepNullish);
 }
+//#endregion
+//#region src/unique.ts
+/**
+* Return a new array with duplicate values removed while preserving order.
+*/
+function unique(values) {
+	return Array.from(new Set(values));
+}
+//#endregion
+//#region src/safe_equal.ts
+/**
+* Compare two values to see if they are equal. The comparison is done in
+* a way to avoid timing-attacks.
+*/
 function safeEqual(trustedValue, userInput) {
 	if (typeof trustedValue === "string" && typeof userInput === "string") {
+		/**
+		* The length of the comparison value.
+		*/
 		const trustedLength = Buffer.byteLength(trustedValue);
+		/**
+		* Expected value
+		*/
 		const trustedValueBuffer = Buffer.alloc(trustedLength, 0, "utf-8");
 		trustedValueBuffer.write(trustedValue);
+		/**
+		* Actual value (taken from user input)
+		*/
 		const userValueBuffer = Buffer.alloc(trustedLength, 0, "utf-8");
 		userValueBuffer.write(userInput);
+		/**
+		* Ensure values are same and also have same length
+		*/
 		return timingSafeEqual(trustedValueBuffer, userValueBuffer) && trustedLength === Buffer.byteLength(userInput);
 	}
 	return timingSafeEqual(Buffer.from(trustedValue), Buffer.from(userInput));
 }
+//#endregion
+//#region src/import_default.ts
+/**
+* Dynamically import a module and ensure it has a default export
+*/
 async function importDefault(importFn, filePath) {
 	const moduleExports = await importFn();
-	if (!("default" in moduleExports)) throw new RuntimeException(filePath ? `Missing "export default" in module "${filePath}"` : `Missing "export default" from lazy import "${importFn}"`, { cause: { source: importFn } });
+	/**
+	* Make sure a default export exists
+	*/
+	if (!("default" in moduleExports)) {
+		const errorMessage = filePath ? `Missing "export default" in module "${filePath}"` : `Missing "export default" from lazy import "${importFn}"`;
+		throw new RuntimeException(errorMessage, { cause: { source: importFn } });
+	}
 	return moduleExports.default;
 }
+//#endregion
+//#region src/message_builder.ts
+/**
+* Message builder exposes an API to "JSON.stringify" values by
+* encoding purpose and expiry date inside them.
+*
+* The return value must be further encrypted to prevent tempering.
+*/
 var MessageBuilder = class {
 	#getExpiryDate(expiresIn) {
 		if (!expiresIn) return;
 		const expiryMs = string.milliseconds.parse(expiresIn);
 		return new Date(Date.now() + expiryMs);
 	}
+	/**
+	* Returns a boolean telling, if message has been expired or not
+	*/
 	#isExpired(message) {
 		if (!message.expiryDate) return false;
 		const expiryDate = new Date(message.expiryDate);
 		return Number.isNaN(expiryDate.getTime()) || expiryDate < /* @__PURE__ */ new Date();
 	}
+	/**
+	* Builds a message by encoding expiry date and purpose inside it.
+	*/
 	build(message, expiresIn, purpose) {
+		const expiryDate = this.#getExpiryDate(expiresIn);
 		return safeStringify({
 			message,
 			purpose,
-			expiryDate: this.#getExpiryDate(expiresIn)
+			expiryDate
 		});
 	}
+	/**
+	* Verifies the message for expiry and purpose.
+	*/
 	verify(message, purpose) {
 		const parsed = safeParse(message);
+		/**
+		* After JSON.parse we do not receive a valid object
+		*/
 		if (typeof parsed !== "object" || !parsed) return null;
+		/**
+		* Missing ".message" property
+		*/
 		if (!parsed.message) return null;
+		/**
+		* Ensure purposes are same.
+		*/
 		if (parsed.purpose !== purpose) return null;
+		/**
+		* Ensure isn't expired
+		*/
 		if (this.#isExpired(parsed)) return null;
 		return parsed.message;
 	}
 };
+//#endregion
+//#region src/imports_bag.ts
+/**
+* ImportsBag manages and deduplicates imports from the same source
+*/
 var ImportsBag = class {
+	/**
+	* Map of source to ImportInfo
+	*/
 	#imports = /* @__PURE__ */ new Map();
+	/**
+	* Generate import statement from ImportInfo
+	*/
 	#generateImportStatement(imp) {
 		const parts = [];
 		if (imp.defaultImport || imp.namedImports && imp.namedImports.length > 0) {
@@ -104,15 +209,30 @@ var ImportsBag = class {
 		}
 		return parts.join("\n");
 	}
+	/**
+	* Add an import to the bag
+	*/
 	add(importInfo) {
 		const existing = this.#imports.get(importInfo.source);
 		if (existing) {
+			/**
+			* Set default import (replaces existing if present)
+			*/
 			if (importInfo.defaultImport) existing.defaultImport = importInfo.defaultImport;
+			/**
+			* Set default type import (replaces existing if present)
+			*/
 			if (importInfo.defaultTypeImport) existing.defaultTypeImport = importInfo.defaultTypeImport;
+			/**
+			* Merge named imports without deduplication (deduplication happens in toArray)
+			*/
 			if (importInfo.namedImports) {
 				if (!existing.namedImports) existing.namedImports = [];
 				existing.namedImports.push(...importInfo.namedImports);
 			}
+			/**
+			* Merge type imports without deduplication (deduplication happens in toArray)
+			*/
 			if (importInfo.typeImports) {
 				if (!existing.typeImports) existing.typeImports = [];
 				existing.typeImports.push(...importInfo.typeImports);
@@ -126,22 +246,38 @@ var ImportsBag = class {
 		});
 		return this;
 	}
+	/**
+	* Get deduplicated imports as an array
+	*/
 	toArray() {
 		return Array.from(this.#imports.values()).map((imp) => ({
 			source: imp.source,
 			defaultImport: imp.defaultImport,
 			defaultTypeImport: imp.defaultTypeImport,
-			namedImports: imp.namedImports ? [...new Set(imp.namedImports)] : void 0,
-			typeImports: imp.typeImports ? [...new Set(imp.typeImports)] : void 0
+			namedImports: imp.namedImports ? unique(imp.namedImports) : void 0,
+			typeImports: imp.typeImports ? unique(imp.typeImports) : void 0
 		}));
 	}
+	/**
+	* Get deduplicated imports as a formatted string
+	*/
 	toString() {
 		return this.toArray().map((imp) => this.#generateImportStatement(imp)).join("\n");
 	}
 };
+//#endregion
+//#region src/define_static_property.ts
+/**
+* Define static properties on a class with inheritance in play.
+*/
 function defineStaticProperty(self, propertyName, { initialValue, strategy }) {
 	if (!self.hasOwnProperty(propertyName)) {
 		const value = self[propertyName];
+		/**
+		* Define the property as it is when the strategy is set
+		* to "define". Or the value on the prototype chain
+		* is set to undefined.
+		*/
 		if (strategy === "define" || value === void 0) {
 			Object.defineProperty(self, propertyName, {
 				value: initialValue,
@@ -159,6 +295,19 @@ function defineStaticProperty(self, propertyName, { initialValue, strategy }) {
 		});
 	}
 }
+//#endregion
+//#region src/detect_ai_agent.ts
+/**
+* Detects which AI coding agent the code is running under.
+* Checks for environment variables set by different AI coding assistants:
+* - CLAUDECODE='1' for Claude Code
+* - GEMINI_CLI='1' for Gemini
+* - GITHUB_COPILOT_CLI_MODE='1' for GitHub Copilot
+* - WINDSURF_SESSION='1' or TERM_PROGRAM='windsurf' for Windsurf
+* - CODEX_CLI='1' or CODEX_SANDBOX='1' for Codex
+* - OPENCODE='1' for OpenCode
+* - CURSOR_AGENT='1' for Cursor
+*/
 function detectAIAgent() {
 	if (process.env.CLAUDECODE === "1") return "claude";
 	if (process.env.GEMINI_CLI === "1") return "gemini";
@@ -169,7 +318,67 @@ function detectAIAgent() {
 	if (process.env.CURSOR_AGENT === "1") return "cursor";
 	return null;
 }
+/**
+* Returns true if the code is running within any AI coding agent.
+*/
 function isRunningInAIAgent() {
 	return detectAIAgent() !== null;
 }
-export { ImportsBag, MessageBuilder, Secret, compose, defineStaticProperty, detectAIAgent, flatten, importDefault, isRunningInAIAgent, isScriptFile, naturalSort, safeEqual };
+//#endregion
+//#region src/get_git_worktree.ts
+const execFileAsync = promisify(execFile);
+/**
+* Returns true when the target path is inside the parent path.
+*/
+function isPathInside(parent, target) {
+	const relativePath = relative(parent, target);
+	return relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+/**
+* Returns information about the linked Git worktree containing the given
+* directory. Returns null for the main worktree and directories outside a
+* Git repository.
+*/
+async function getGitWorktree(cwd = process.cwd()) {
+	try {
+		const [{ stdout }, resolvedCwd] = await Promise.all([execFileAsync("git", [
+			"worktree",
+			"list",
+			"--porcelain",
+			"-z"
+		], {
+			cwd,
+			encoding: "utf8",
+			windowsHide: true
+		}), realpath(cwd)]);
+		const worktreePaths = stdout.split("\0").filter((field) => field.startsWith("worktree ")).map((field) => field.slice(9));
+		const currentWorktree = (await Promise.all(worktreePaths.map(async (worktreePath, index) => {
+			try {
+				return {
+					index,
+					path: await realpath(worktreePath)
+				};
+			} catch {
+				return null;
+			}
+		}))).filter((worktree) => {
+			return worktree !== null && isPathInside(worktree.path, resolvedCwd);
+		}).sort((current, next) => next.path.length - current.path.length)[0];
+		if (!currentWorktree || currentWorktree.index === 0) return null;
+		const name = basename(currentWorktree.path);
+		const hash = createHash("sha256").update(currentWorktree.path).digest("hex").slice(0, 12);
+		return {
+			name,
+			hash,
+			path: currentWorktree.path,
+			slug: string.slug(name, {
+				lower: true,
+				strict: true
+			}) || `worktree-${hash}`
+		};
+	} catch {
+		return null;
+	}
+}
+//#endregion
+export { ImportsBag, MessageBuilder, Secret, compose, defineStaticProperty, detectAIAgent, flatten, getGitWorktree, importDefault, isRunningInAIAgent, isScriptFile, naturalSort, safeEqual, unique };

package/build/{is_script_file-CbSEfxE_.js → is_script_file-D0Om5zlQ.js}

@@ -1,20 +1,33 @@
 import { extname } from "node:path";
+//#region src/natural_sort.ts
+let collator;
+/**
+* Perform natural sorting with "Array.sort()" method
+*/
 function naturalSort(current, next) {
-	return current.localeCompare(next, void 0, {
+	collator ??= new Intl.Collator(void 0, {
 		numeric: true,
 		sensitivity: "base"
 	});
+	return collator.compare(current, next);
 }
+//#endregion
+//#region src/is_script_file.ts
 const JS_MODULES = [
 	".js",
 	".json",
 	".cjs",
 	".mjs"
 ];
+/**
+* Returns `true` when file ends with `.js`, `.json` or
+* `.ts` but not `.d.ts`.
+*/
 function isScriptFile(filePath) {
 	const ext = extname(filePath);
 	if (JS_MODULES.includes(ext)) return true;
 	if (ext === ".ts" && !filePath.endsWith(".d.ts")) return true;
 	return false;
 }
+//#endregion
 export { naturalSort as n, isScriptFile as t };

package/build/{safe_stringify-DenlQd3-.js → main-B9qlOEvt.js}

@@ -1,11 +1,11 @@
-import "node:module";
+//#region \0rolldown/runtime.js
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __copyProps = (to, from, except, desc) => {
 	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
 		key = keys[i];
@@ -16,14 +16,26 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
+//#endregion
+//#region modules/json/safe_parse.ts
 var import_secure_json_parse = (/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const hasBuffer = typeof Buffer !== "undefined";
 	const suspectProtoRx = /"(?:_|\\u005[Ff])(?:_|\\u005[Ff])(?:p|\\u0070)(?:r|\\u0072)(?:o|\\u006[Ff])(?:t|\\u0074)(?:o|\\u006[Ff])(?:_|\\u005[Ff])(?:_|\\u005[Ff])"\s*:/;
 	const suspectConstructorRx = /"(?:c|\\u0063)(?:o|\\u006[Ff])(?:n|\\u006[Ee])(?:s|\\u0073)(?:t|\\u0074)(?:r|\\u0072)(?:u|\\u0075)(?:c|\\u0063)(?:t|\\u0074)(?:o|\\u006[Ff])(?:r|\\u0072)"\s*:/;
+	/**
+	* @description Internal parse function that parses JSON text with security checks.
+	* @private
+	* @param {string|Buffer} text - The JSON text string or Buffer to parse.
+	* @param {Function} [reviver] - The JSON.parse() optional reviver argument.
+	* @param {import('./types').ParseOptions} [options] - Optional configuration object.
+	* @returns {*} The parsed object.
+	* @throws {SyntaxError} If a forbidden prototype property is found and `options.protoAction` or
+	* `options.constructorAction` is `'error'`.
+	*/
 	function _parse(text, reviver, options) {
 		if (options == null) {
 			if (reviver !== null && typeof reviver === "object") {
@@ -49,6 +61,14 @@ var import_secure_json_parse = (/* @__PURE__ */ __commonJSMin(((exports, module)
 			safe: options && options.safe
 		});
 	}
+	/**
+	* @description Scans and filters an object for forbidden prototype properties.
+	* @param {Object} obj - The object being scanned.
+	* @param {import('./types').ParseOptions} [options] - Optional configuration object.
+	* @returns {Object|null} The filtered object, or `null` if safe mode is enabled and issues are found.
+	* @throws {SyntaxError} If a forbidden prototype property is found and `options.protoAction` or
+	* `options.constructorAction` is `'error'`.
+	*/
 	function filter(obj, { protoAction = "error", constructorAction = "error", safe } = {}) {
 		let next = [obj];
 		while (next.length) {
@@ -73,6 +93,15 @@ var import_secure_json_parse = (/* @__PURE__ */ __commonJSMin(((exports, module)
 		}
 		return obj;
 	}
+	/**
+	* @description Parses a given JSON-formatted text into an object.
+	* @param {string|Buffer} text - The JSON text string or Buffer to parse.
+	* @param {Function} [reviver] - The `JSON.parse()` optional reviver argument, or options object.
+	* @param {import('./types').ParseOptions} [options] - Optional configuration object.
+	* @returns {*} The parsed object.
+	* @throws {SyntaxError} If the JSON text is malformed or contains forbidden prototype properties
+	* when `options.protoAction` or `options.constructorAction` is `'error'`.
+	*/
 	function parse(text, reviver, options) {
 		const { stackTraceLimit } = Error;
 		Error.stackTraceLimit = 0;
@@ -82,6 +111,12 @@ var import_secure_json_parse = (/* @__PURE__ */ __commonJSMin(((exports, module)
 			Error.stackTraceLimit = stackTraceLimit;
 		}
 	}
+	/**
+	* @description Safely parses a given JSON-formatted text into an object.
+	* @param {string|Buffer} text - The JSON text string or Buffer to parse.
+	* @param {Function} [reviver] - The `JSON.parse()` optional reviver argument.
+	* @returns {*|null|undefined} The parsed object, `null` if security issues found, or `undefined` on parse error.
+	*/
 	function safeParse(text, reviver) {
 		const { stackTraceLimit } = Error;
 		Error.stackTraceLimit = 0;
@@ -99,12 +134,17 @@ var import_secure_json_parse = (/* @__PURE__ */ __commonJSMin(((exports, module)
 	module.exports.safeParse = safeParse;
 	module.exports.scan = filter;
 })))();
+/**
+* A drop-in replacement for JSON.parse with prototype poisoning protection.
+*/
 function safeParse(jsonString, reviver) {
 	return (0, import_secure_json_parse.parse)(jsonString, reviver, {
 		protoAction: "remove",
 		constructorAction: "remove"
 	});
 }
+//#endregion
+//#region node_modules/safe-stable-stringify/esm/wrapper.js
 var import_safe_stable_stringify = /* @__PURE__ */ __toESM((/* @__PURE__ */ __commonJSMin(((exports, module) => {
 	const { hasOwnProperty } = Object.prototype;
 	const stringify = configure();
@@ -132,7 +172,7 @@ var import_safe_stable_stringify = /* @__PURE__ */ __toESM((/* @__PURE__ */ __co
 		}
 		return array;
 	}
-	const typedArrayPrototypeGetSymbolToStringTag = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Object.getPrototypeOf(new Int8Array())), Symbol.toStringTag).get;
+	const typedArrayPrototypeGetSymbolToStringTag = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Object.getPrototypeOf(/* @__PURE__ */ new Int8Array())), Symbol.toStringTag).get;
 	function isTypedArrayWithEntries(value) {
 		return typedArrayPrototypeGetSymbolToStringTag.call(value) !== void 0 && value.length !== 0;
 	}
@@ -513,15 +553,22 @@ var import_safe_stable_stringify = /* @__PURE__ */ __toESM((/* @__PURE__ */ __co
 		}
 		return stringify;
 	}
-})))(), 1);
+})))());
 const configure = import_safe_stable_stringify.configure;
 import_safe_stable_stringify.default;
 import_safe_stable_stringify.default;
+//#endregion
+//#region modules/json/safe_stringify.ts
 const stringify = configure({
 	bigint: false,
 	circularValue: void 0,
 	deterministic: false
 });
+/**
+* Replacer to handle custom data types.
+*
+* - Bigints are converted to string
+*/
 function jsonStringifyReplacer(replacer) {
 	return function(key, value) {
 		const val = replacer ? replacer.call(this, key, value) : value;
@@ -529,7 +576,12 @@ function jsonStringifyReplacer(replacer) {
 		return val;
 	};
 }
+/**
+* String Javascript values to a JSON string. Handles circular
+* references and bigints
+*/
 function safeStringify(value, replacer, space) {
 	return stringify(value, jsonStringifyReplacer(replacer), space);
 }
+//#endregion
 export { safeParse as n, safeStringify as t };

package/build/modules/assert.js

@@ -1,18 +1,37 @@
 import { inspect } from "node:util";
 import { AssertionError } from "node:assert";
+//#region modules/assert.ts
+/**
+* @alias "assertExists"
+*/
 function assert(value, message) {
 	return assertExists(value, message);
 }
+/**
+* Assert the value is turthy or raise an exception.
+*
+* Truthy value excludes, undefined, null, and false values.
+*/
 function assertExists(value, message) {
 	if (!value) throw new AssertionError({ message: message ?? "value is falsy" });
 }
+/**
+* Throws error when method is called
+*/
 function assertUnreachable(x) {
 	throw new AssertionError({ message: `unreachable code executed: ${inspect(x)}` });
 }
+/**
+* Assert the value is not null.
+*/
 function assertNotNull(value, message) {
 	if (value === null) throw new AssertionError({ message: message ?? "unexpected null value" });
 }
+/**
+* Assert the value is not undefined.
+*/
 function assertIsDefined(value, message) {
 	if (value === void 0) throw new AssertionError({ message: message ?? "unexpected undefined value" });
 }
+//#endregion
 export { assert, assertExists, assertIsDefined, assertNotNull, assertUnreachable };

package/build/modules/base64.js

@@ -1,3 +1,8 @@
+//#region modules/base64.ts
+/**
+* Helper class to base64 encode/decode values with option
+* for url encoding and decoding
+*/
 var Base64 = class {
 	encode(data, encoding) {
 		if (typeof data === "string") return Buffer.from(data, encoding).toString("base64");
@@ -23,4 +28,5 @@ var Base64 = class {
 	}
 };
 const base64 = new Base64();
+//#endregion
 export { base64 as default };

package/build/modules/fs/main.js

@@ -1,9 +1,27 @@
-import { n as naturalSort, t as isScriptFile } from "../../is_script_file-CbSEfxE_.js";
+import { n as naturalSort, t as isScriptFile } from "../../is_script_file-D0Om5zlQ.js";
 import { extname, join, relative, sep } from "node:path";
 import string from "@poppinss/string";
 import lodash from "@poppinss/utils/lodash";
 import { readdir, stat } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
+//#region modules/fs/fs_read_all.ts
+/**
+* Returns an array of file paths from the given location. You can
+* optionally filter and sort files by passing relevant options
+*
+* ```ts
+* await fsReadAll(new URL('./', import.meta.url))
+*
+* await fsReadAll(new URL('./', import.meta.url), {
+*   filter: (filePath) => filePath.endsWith('.js')
+* })
+
+* await fsReadAll(new URL('./', import.meta.url), {
+*   absolute: true,
+*   unixPaths: true
+* })
+* ```
+*/
 async function fsReadAll(location, options) {
 	const normalizedLocation = typeof location === "string" ? location : fileURLToPath(location);
 	const normalizedOptions = Object.assign({
@@ -11,6 +29,10 @@ async function fsReadAll(location, options) {
 		sort: naturalSort
 	}, options);
 	const pathType = normalizedOptions.pathType || "relative";
+	/**
+	* Check to see if the root directory exists and ignore
+	* error when "ignoreMissingRoot" is set to true
+	*/
 	try {
 		await stat(normalizedLocation);
 	} catch (error) {
@@ -22,7 +44,9 @@ async function fsReadAll(location, options) {
 		withFileTypes: true
 	})).filter((dirent) => {
 		if (!dirent.isFile()) return false;
-		if (dirent.name.startsWith(".") || dirent.parentPath.split(sep).some((segment) => segment.startsWith("."))) return false;
+		if (dirent.name.startsWith(".")) return false;
+		const relativePath = relative(normalizedLocation, dirent.parentPath);
+		if (relativePath && relativePath.split(sep).some((segment) => segment.startsWith("."))) return false;
 		return true;
 	}).map((file) => {
 		switch (pathType) {
@@ -36,13 +60,45 @@ async function fsReadAll(location, options) {
 	if (normalizedOptions.filter) return files.filter(normalizedOptions.filter).sort(normalizedOptions.sort);
 	return files.sort(normalizedOptions.sort);
 }
+//#endregion
+//#region modules/fs/fs_import_all.ts
+/**
+* Import the file and update the values collection with the default
+* export.
+*/
 async function importFile(basePath, fileURL, values, options) {
+	/**
+	* Converting URL to file path
+	*/
 	const filePath = fileURLToPath(fileURL);
+	/**
+	* Grab file extension
+	*/
 	const fileExtension = extname(filePath);
 	const collectionKey = relative(basePath, filePath).replace(new RegExp(`${fileExtension}$`), "").split(sep);
+	/**
+	* Import module
+	*/
 	const exportedValue = fileExtension === ".json" ? await import(fileURL, { with: { type: "json" } }) : await import(fileURL);
 	lodash.set(values, options.transformKeys ? options.transformKeys(collectionKey) : collectionKey, exportedValue.default ? exportedValue.default : { ...exportedValue });
 }
+/**
+* Returns an array of file paths from the given location. You can
+* optionally filter and sort files by passing relevant options
+*
+* ```ts
+* await fsReadAll(new URL('./', import.meta.url))
+*
+* await fsReadAll(new URL('./', import.meta.url), {
+*   filter: (filePath) => filePath.endsWith('.js')
+* })
+
+* await fsReadAll(new URL('./', import.meta.url), {
+*   absolute: true,
+*   unixPaths: true
+* })
+* ```
+*/
 async function fsImportAll(location, options) {
 	options = options || {};
 	const collection = {};
@@ -52,7 +108,11 @@ async function fsImportAll(location, options) {
 		...options,
 		pathType: "url"
 	});
+	/**
+	* Parallelly import all the files and mutate the values collection
+	*/
 	await Promise.all(files.map((file) => importFile(normalizedLocation, file, collection, options)));
 	return collection;
 }
+//#endregion
 export { fsImportAll, fsReadAll };

package/build/modules/json/main.js

@@ -1,2 +1,2 @@
-import { n as safeParse, t as safeStringify } from "../../safe_stringify-DenlQd3-.js";
+import { n as safeParse, t as safeStringify } from "../../main-B9qlOEvt.js";
 export { safeParse, safeStringify };

package/build/modules/number.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Collection of number helpers to clamp and parse numeric values.
+ *
+ * @example
+ * number.clamp(15, 0, 10)  // 10
+ * number.between(5, 0, 10) // true
+ * number.parse('42')       // 42
+ * number.toFinite('abc', 0) // 0
+ */
+declare const number: {
+    /**
+     * Constrain a number to stay within the given bounds.
+     *
+     * @param value - The number to constrain
+     * @param min - The lower bound
+     * @param max - The upper bound
+     *
+     * @example
+     * number.clamp(15, 0, 10) // 10
+     * number.clamp(-2, 0, 10) // 0
+     * number.clamp(5, 0, 10)  // 5
+     */
+    clamp(value: number, min: number, max: number): number;
+    /**
+     * Check if a number is inside an inclusive range. The bounds may be
+     * passed in either order.
+     *
+     * @param value - The number to test
+     * @param min - One end of the range
+     * @param max - The other end of the range
+     *
+     * @example
+     * number.between(5, 0, 10)  // true
+     * number.between(0, 0, 10)  // true
+     * number.between(11, 0, 10) // false
+     * number.between(5, 10, 0)  // true
+     */
+    between(value: number, min: number, max: number): boolean;
+    /**
+     * Convert a value to a finite number. Returns the fallback when the
+     * result is `NaN` or `Infinity`.
+     *
+     * @param value - The value to convert
+     * @param fallback - Value to return when conversion fails. Defaults to `0`
+     *
+     * @example
+     * number.toFinite(5)                        // 5
+     * number.toFinite('42')                     // 42
+     * number.toFinite(Number.NaN)               // 0
+     * number.toFinite(Number.POSITIVE_INFINITY) // 0
+     * number.toFinite('abc', 10)                // 10
+     */
+    toFinite(value: unknown, fallback?: number): number;
+    /**
+     * Parse a value into a finite number. Returns `null` for empty input,
+     * `NaN`, and `Infinity` instead of substituting a fallback.
+     *
+     * @param value - The value to parse
+     *
+     * @example
+     * number.parse(5)                        // 5
+     * number.parse('42')                     // 42
+     * number.parse('')                       // null
+     * number.parse(null)                    // null
+     * number.parse(Number.NaN)              // null
+     * number.parse(Number.POSITIVE_INFINITY) // null
+     */
+    parse(value: unknown): number | null;
+};
+export default number;

package/build/modules/number.js

@@ -0,0 +1,95 @@
+//#region modules/number.ts
+/**
+* Coerce an unknown value to a finite number without allowing numeric
+* conversion errors to escape.
+*/
+function toFiniteNumber(value) {
+	try {
+		const numericValue = typeof value === "number" ? value : Number(value);
+		return Number.isFinite(numericValue) ? numericValue : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Collection of number helpers to clamp and parse numeric values.
+*
+* @example
+* number.clamp(15, 0, 10)  // 10
+* number.between(5, 0, 10) // true
+* number.parse('42')       // 42
+* number.toFinite('abc', 0) // 0
+*/
+const number = {
+	/**
+	* Constrain a number to stay within the given bounds.
+	*
+	* @param value - The number to constrain
+	* @param min - The lower bound
+	* @param max - The upper bound
+	*
+	* @example
+	* number.clamp(15, 0, 10) // 10
+	* number.clamp(-2, 0, 10) // 0
+	* number.clamp(5, 0, 10)  // 5
+	*/
+	clamp(value, min, max) {
+		if (value < min) return min;
+		else if (value > max) return max;
+		else return value;
+	},
+	/**
+	* Check if a number is inside an inclusive range. The bounds may be
+	* passed in either order.
+	*
+	* @param value - The number to test
+	* @param min - One end of the range
+	* @param max - The other end of the range
+	*
+	* @example
+	* number.between(5, 0, 10)  // true
+	* number.between(0, 0, 10)  // true
+	* number.between(11, 0, 10) // false
+	* number.between(5, 10, 0)  // true
+	*/
+	between(value, min, max) {
+		return value >= Math.min(min, max) && value <= Math.max(min, max);
+	},
+	/**
+	* Convert a value to a finite number. Returns the fallback when the
+	* result is `NaN` or `Infinity`.
+	*
+	* @param value - The value to convert
+	* @param fallback - Value to return when conversion fails. Defaults to `0`
+	*
+	* @example
+	* number.toFinite(5)                        // 5
+	* number.toFinite('42')                     // 42
+	* number.toFinite(Number.NaN)               // 0
+	* number.toFinite(Number.POSITIVE_INFINITY) // 0
+	* number.toFinite('abc', 10)                // 10
+	*/
+	toFinite(value, fallback = 0) {
+		return toFiniteNumber(value) ?? fallback;
+	},
+	/**
+	* Parse a value into a finite number. Returns `null` for empty input,
+	* `NaN`, and `Infinity` instead of substituting a fallback.
+	*
+	* @param value - The value to parse
+	*
+	* @example
+	* number.parse(5)                        // 5
+	* number.parse('42')                     // 42
+	* number.parse('')                       // null
+	* number.parse(null)                    // null
+	* number.parse(Number.NaN)              // null
+	* number.parse(Number.POSITIVE_INFINITY) // null
+	*/
+	parse(value) {
+		if (value === null || value === void 0 || value === "") return null;
+		return toFiniteNumber(value);
+	}
+};
+//#endregion
+export { number as default };

package/build/modules/string/main.js

@@ -1,3 +1,5 @@
 import string from "@poppinss/string";
+//#region modules/string/main.ts
 var main_default = string;
+//#endregion
 export { main_default as default };

package/build/modules/string/string_builder.js

@@ -1,3 +1,5 @@
 import StringBuilder from "@poppinss/string/builder";
+//#region modules/string/string_builder.ts
 var string_builder_default = StringBuilder;
+//#endregion
 export { string_builder_default as default };

package/build/src/get_git_worktree.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Information about a linked Git worktree.
+ */
+export type GitWorktree = {
+    /**
+     * Basename of the worktree directory.
+     */
+    name: string;
+    /**
+     * URL-safe slug generated from the worktree name.
+     */
+    slug: string;
+    /**
+     * First twelve characters of the SHA-256 hash for the canonical path.
+     */
+    hash: string;
+    /**
+     * Canonical absolute path to the worktree.
+     */
+    path: string;
+};
+/**
+ * Returns information about the linked Git worktree containing the given
+ * directory. Returns null for the main worktree and directories outside a
+ * Git repository.
+ */
+export declare function getGitWorktree(cwd?: string): Promise<GitWorktree | null>;

package/build/src/unique.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Return a new array with duplicate values removed while preserving order.
+ */
+export declare function unique<Value>(values: readonly Value[]): Value[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppinss/utils",
-  "version": "7.0.0",
+  "version": "7.1.0",
   "description": "Handy utilities for repetitive work",
   "main": "build/index.js",
   "type": "module",
@@ -24,6 +24,7 @@
     "./assert": "./build/modules/assert.js",
     "./base64": "./build/modules/base64.js",
     "./exception": "./build/modules/exception.js",
+    "./number": "./build/modules/number.js",
     "./types": "./build/modules/types.js"
   },
   "scripts": {
@@ -42,34 +43,34 @@
     "quick:test": "node --import=@poppinss/ts-exec bin/test.ts"
   },
   "devDependencies": {
-    "@adonisjs/eslint-config": "^3.0.0",
-    "@adonisjs/logger": "^6.0.7",
-    "@adonisjs/prettier-config": "^1.4.5",
+    "@adonisjs/eslint-config": "^3.1.0",
+    "@adonisjs/logger": "^7.1.1",
+    "@adonisjs/prettier-config": "^1.5.0",
     "@adonisjs/tsconfig": "^2.0.0",
     "@japa/assert": "^4.2.0",
     "@japa/expect-type": "^2.0.4",
     "@japa/runner": "^5.3.0",
     "@poppinss/ts-exec": "^1.4.4",
-    "@release-it/conventional-changelog": "^10.0.5",
+    "@release-it/conventional-changelog": "^12.0.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^25.3.0",
-    "c8": "^10.1.3",
-    "eslint": "^10.0.2",
-    "fs-extra": "^11.3.3",
-    "lodash": "^4.17.23",
+    "@types/node": "^26.4.1",
+    "c8": "^12.0.0",
+    "eslint": "^10.10.0",
+    "fs-extra": "^11.4.0",
+    "lodash": "^4.18.1",
     "lodash-cli": "^4.17.5",
     "move-file-cli": "^3.0.0",
-    "prettier": "^3.8.1",
-    "release-it": "^19.2.4",
+    "prettier": "^3.9.6",
+    "release-it": "^21.0.2",
     "safe-stable-stringify": "^2.5.0",
     "secure-json-parse": "^4.1.0",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3"
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "@poppinss/exception": "^1.2.3",
     "@poppinss/object-builder": "^1.1.0",
-    "@poppinss/string": "^1.7.1",
+    "@poppinss/string": "^1.7.2",
     "@poppinss/types": "^1.2.1",
     "flattie": "^1.1.1"
   },
@@ -101,6 +102,7 @@
       "./modules/assert.ts",
       "./modules/base64.ts",
       "./modules/exception.ts",
+      "./modules/number.ts",
       "./modules/types.ts"
     ],
     "external": [