@luxass/utils 2.0.0 → 2.1.0

package/dist/index.d.ts

@@ -1,5 +1,24 @@
 import { isNotNull$1 as isNotNull, isNotNullish$1 as isNotNullish, isNotUndefined$1 as isNotUndefined, isTruthy$1 as isTruthy } from "./guards.d-n1BzCANy.js";
 import { clamp$1 as clamp } from "./number.d-C2Xuq3Is.js";
-import { capitalize$1 as capitalize, dedent$1 as dedent, dedentRaw$1 as dedentRaw, sanitizeIdentifier$1 as sanitizeIdentifier, toCamelCase$1 as toCamelCase, toKebabCase$1 as toKebabCase, toPascalCase$1 as toPascalCase, toSnakeCase$1 as toSnakeCase } from "./string.d-BSY3kSBV.js";
+import { capitalize$1 as capitalize, dedent$1 as dedent, dedentRaw$1 as dedentRaw, formatStr$1 as formatStr, sanitizeIdentifier$1 as sanitizeIdentifier, toCamelCase$1 as toCamelCase, toKebabCase$1 as toKebabCase, toPascalCase$1 as toPascalCase, toSnakeCase$1 as toSnakeCase } from "./string.d-B2ppMtlR.js";
 import { Arrayable, Awaitable, ElementOf, InferArguments, Nullable, Nullish } from "./types.d-BcKIY6l3.js";
-export { Arrayable, Awaitable, ElementOf, InferArguments, Nullable, Nullish, capitalize, clamp, dedent, dedentRaw, isNotNull, isNotNullish, isNotUndefined, isTruthy, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };
+
+//#region src/common.d.ts
+declare class InvariantError extends Error {
+  readonly message: string;
+  constructor(message: string, ...positionals: any[]);
+}
+
+/**
+* Asserts that a condition is truthy. If the condition is falsy, throws an InvariantError.
+* This function is useful for ensuring invariants and preconditions in code.
+*
+* @param {unknown} predicate - The condition to check
+* @param {string} message - Error message to display if the condition fails
+* @param {unknown[]} positionals - Values to substitute into the error message using formatStr
+* @throws {InvariantError} Throws when the predicate is falsy
+*/
+declare function invariant(predicate: unknown, message: string, ...positionals: unknown[]): asserts predicate;
+
+//#endregion
+export { Arrayable, Awaitable, ElementOf, InferArguments, InvariantError, Nullable, Nullish, capitalize, clamp, dedent, dedentRaw, formatStr, invariant, isNotNull, isNotNullish, isNotUndefined, isTruthy, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/index.js

@@ -1,5 +1,27 @@
 import { isNotNull, isNotNullish, isNotUndefined, isTruthy } from "./guards-O1HGJraI.js";
-import { clamp } from "./number-Bfr1z0Nr.js";
-import { capitalize, dedent, dedentRaw, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase } from "./string-bY1lSRQs.js";
+import { capitalize, dedent, dedentRaw, formatStr, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase } from "./string-pQApOGKP.js";
+import { clamp } from "./number-BS9T5WGO.js";
 
-export { capitalize, clamp, dedent, dedentRaw, isNotNull, isNotNullish, isNotUndefined, isTruthy, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };
+//#region src/common.ts
+var InvariantError = class extends Error {
+	constructor(message, ...positionals) {
+		super(message);
+		this.message = message;
+		this.message = formatStr(message, ...positionals);
+	}
+};
+/**
+* Asserts that a condition is truthy. If the condition is falsy, throws an InvariantError.
+* This function is useful for ensuring invariants and preconditions in code.
+*
+* @param {unknown} predicate - The condition to check
+* @param {string} message - Error message to display if the condition fails
+* @param {unknown[]} positionals - Values to substitute into the error message using formatStr
+* @throws {InvariantError} Throws when the predicate is falsy
+*/
+function invariant(predicate, message, ...positionals) {
+	if (!predicate) throw new InvariantError(message, ...positionals);
+}
+
+//#endregion
+export { InvariantError, capitalize, clamp, dedent, dedentRaw, formatStr, invariant, isNotNull, isNotNullish, isNotUndefined, isTruthy, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/number.js

@@ -1,3 +1,3 @@
-import { clamp } from "./number-Bfr1z0Nr.js";
+import { clamp } from "./number-BS9T5WGO.js";
 
 export { clamp };

package/dist/{string-bY1lSRQs.js → string-pQApOGKP.js}

@@ -136,6 +136,51 @@ function sanitizeIdentifier(str) {
 	const cleaned = str.replace(/[^\w$]/g, "");
 	return /^[A-Z_$]/i.test(cleaned) ? cleaned : `_${cleaned}`;
 }
+const POSITION_REGEX = /(%?)(%([sdijo]))/g;
+/** @internal */
+function serializePositional(positional, flag) {
+	if (flag === "s") return positional;
+	if (flag === "d" || flag === "i") return Number(positional);
+	if (flag === "j") return JSON.stringify(positional);
+	if (flag === "o") {
+		if (typeof positional === "string") return positional;
+		const json = JSON.stringify(positional);
+		if (json === "{}" || json === "[]" || /^\[object .+?\]$/.test(json)) return positional;
+		return json;
+	}
+}
+/**
+* Formats a string by replacing placeholders with positional values
+* @param {string} message - The string containing placeholders to be replaced
+* @param {...any} positionals - The values to insert into the placeholders
+* @returns {string} The formatted string
+*
+* @example
+* ```ts
+* formatStr("Hello %s", "world") // "Hello world"
+* formatStr("Count: %d", 5) // "Count: 5"
+* formatStr("Data: %j", { name: "test" }) // "Data: {"name":"test"}"
+* formatStr("Object: %o", { id: 1 }) // "Object: {"id":1}"
+* formatStr("Escaped %%s", "value") // "Escaped %s"
+* formatStr("Extra args", 1, 2) // "Extra args 1 2"
+* ```
+*/
+function formatStr(message, ...positionals) {
+	if (!positionals.length) return message;
+	let positionalIndex = 0;
+	let formattedMessage = message.replace(POSITION_REGEX, (match, isEscaped, _, flag) => {
+		const positional = positionals[positionalIndex];
+		const value = serializePositional(positional, flag);
+		if (!isEscaped) {
+			positionalIndex++;
+			return value;
+		}
+		return match;
+	});
+	if (positionalIndex < positionals.length) formattedMessage += ` ${positionals.slice(positionalIndex).join(" ")}`;
+	formattedMessage = formattedMessage.replace(/%{2}/g, "%");
+	return formattedMessage;
+}
 
 //#endregion
-export { capitalize, dedent, dedentRaw, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };
+export { capitalize, dedent, dedentRaw, formatStr, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/{string.d-BSY3kSBV.d.ts → string.d-B2ppMtlR.d.ts}

@@ -114,6 +114,23 @@ declare function dedentRaw(strings: TemplateStringsArray, ...values: unknown[]):
                                                                                          * ```
                                                                                          */
 
-declare function sanitizeIdentifier(str: string): string;
+declare function sanitizeIdentifier(str: string): string; /**
+                                                          * Formats a string by replacing placeholders with positional values
+                                                          * @param {string} message - The string containing placeholders to be replaced
+                                                          * @param {...any} positionals - The values to insert into the placeholders
+                                                          * @returns {string} The formatted string
+                                                          *
+                                                          * @example
+                                                          * ```ts
+                                                          * formatStr("Hello %s", "world") // "Hello world"
+                                                          * formatStr("Count: %d", 5) // "Count: 5"
+                                                          * formatStr("Data: %j", { name: "test" }) // "Data: {"name":"test"}"
+                                                          * formatStr("Object: %o", { id: 1 }) // "Object: {"id":1}"
+                                                          * formatStr("Escaped %%s", "value") // "Escaped %s"
+                                                          * formatStr("Extra args", 1, 2) // "Extra args 1 2"
+                                                          * ```
+                                                          */
+
+declare function formatStr(message: string, ...positionals: unknown[]): string;
 //#endregion
-export { capitalize as capitalize$1, dedent as dedent$1, dedentRaw as dedentRaw$1, sanitizeIdentifier as sanitizeIdentifier$1, toCamelCase as toCamelCase$1, toKebabCase as toKebabCase$1, toPascalCase as toPascalCase$1, toSnakeCase as toSnakeCase$1 };
+export { capitalize as capitalize$1, dedent as dedent$1, dedentRaw as dedentRaw$1, formatStr as formatStr$1, sanitizeIdentifier as sanitizeIdentifier$1, toCamelCase as toCamelCase$1, toKebabCase as toKebabCase$1, toPascalCase as toPascalCase$1, toSnakeCase as toSnakeCase$1 };

package/dist/string.d.ts

@@ -1,2 +1,2 @@
-import { capitalize$1 as capitalize, dedent$1 as dedent, dedentRaw$1 as dedentRaw, sanitizeIdentifier$1 as sanitizeIdentifier, toCamelCase$1 as toCamelCase, toKebabCase$1 as toKebabCase, toPascalCase$1 as toPascalCase, toSnakeCase$1 as toSnakeCase } from "./string.d-BSY3kSBV.js";
-export { capitalize, dedent, dedentRaw, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };
+import { capitalize$1 as capitalize, dedent$1 as dedent, dedentRaw$1 as dedentRaw, formatStr$1 as formatStr, sanitizeIdentifier$1 as sanitizeIdentifier, toCamelCase$1 as toCamelCase, toKebabCase$1 as toKebabCase, toPascalCase$1 as toPascalCase, toSnakeCase$1 as toSnakeCase } from "./string.d-B2ppMtlR.js";
+export { capitalize, dedent, dedentRaw, formatStr, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/dist/string.js

@@ -1,3 +1,3 @@
-import { capitalize, dedent, dedentRaw, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase } from "./string-bY1lSRQs.js";
+import { capitalize, dedent, dedentRaw, formatStr, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase } from "./string-pQApOGKP.js";
 
-export { capitalize, dedent, dedentRaw, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };
+export { capitalize, dedent, dedentRaw, formatStr, sanitizeIdentifier, toCamelCase, toKebabCase, toPascalCase, toSnakeCase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luxass/utils",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A collection of utilities for JavaScript/TypeScript",
   "type": "module",
   "author": {