@resq-sw/helpers 0.1.0

package/lib/formatting/string.d.ts

@@ -0,0 +1,22 @@
+//#region src/formatting/string.d.ts
+/**
+ * Copyright 2026 ResQ
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+declare function capitalize(str: string): string;
+declare function truncate(str: string, length: number): string;
+declare function slugify(str: string): string;
+//#endregion
+export { capitalize, slugify, truncate };
+//# sourceMappingURL=string.d.ts.map

package/lib/formatting/string.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.d.ts","names":[],"sources":["../../src/formatting/string.ts"],"mappings":";;AAgBA;;;;;AAIA;;;;;AAKA;;;;iBATgB,UAAA,CAAW,GAAA;AAAA,iBAIX,QAAA,CAAS,GAAA,UAAa,MAAA;AAAA,iBAKtB,OAAA,CAAQ,GAAA"}

package/lib/formatting/string.js

@@ -0,0 +1,30 @@
+//#region src/formatting/string.ts
+/**
+* Copyright 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+function capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function truncate(str, length) {
+	if (str.length <= length) return str;
+	return str.slice(0, length) + "...";
+}
+function slugify(str) {
+	return str.toLowerCase().replaceAll(/[^\w ]+/g, "").replaceAll(/ +/g, "-");
+}
+//#endregion
+export { capitalize, slugify, truncate };
+
+//# sourceMappingURL=string.js.map

package/lib/formatting/string.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"string.js","names":[],"sources":["../../src/formatting/string.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nexport function capitalize(str: string): string {\n  return str.charAt(0).toUpperCase() + str.slice(1)\n}\n\nexport function truncate(str: string, length: number): string {\n  if (str.length <= length) return str\n  return str.slice(0, length) + '...'\n}\n\nexport function slugify(str: string): string {\n  return str\n    .toLowerCase()\n    .replaceAll(/[^\\w ]+/g, '')\n    .replaceAll(/ +/g, '-')\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,SAAgB,WAAW,KAAqB;AAC9C,QAAO,IAAI,OAAO,EAAE,CAAC,aAAa,GAAG,IAAI,MAAM,EAAE;;AAGnD,SAAgB,SAAS,KAAa,QAAwB;AAC5D,KAAI,IAAI,UAAU,OAAQ,QAAO;AACjC,QAAO,IAAI,MAAM,GAAG,OAAO,GAAG;;AAGhC,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,IACJ,aAAa,CACb,WAAW,YAAY,GAAG,CAC1B,WAAW,OAAO,IAAI"}

package/lib/helpers.d.ts

@@ -0,0 +1,142 @@
+//#region src/helpers.d.ts
+/**
+ * Copyright 2026 ResQ
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Converts an object to a formatted JSON string with proper indentation.
+ *
+ * @param {object} obj - The object to convert to a JSON string
+ * @returns {string} A properly formatted JSON string representation of the input object with 2-space indentation
+ *
+ * @example
+ * ```ts
+ * const obj = { name: "John", age: 30 };
+ * const jsonString = Stringify(obj);
+ * // Returns:
+ * // {
+ * //   "name": "John",
+ * //   "age": 30
+ * // }
+ * ```
+ *
+ * @remarks
+ * - Uses JSON.stringify() internally with null replacer and 2-space indent
+ * - Handles circular references by throwing an error
+ * - Preserves object structure and nesting
+ * - Useful for debugging, logging, and data serialization
+ * - Safe with primitives, arrays, objects, null and undefined
+ */
+declare const Stringify: (obj: object) => string;
+/**
+ * Constructs a fully qualified URL based on the current globalThis's location,
+ * with an optional path.
+ *
+ * @param {string} [path=''] - Optional path to append to the base URL
+ * @returns {string} Complete URL with proper formatting and protocol
+ *
+ * @example
+ * ```ts
+ * // Assuming current page is "http://localhost:5173/dashboard"
+ * getURL("api/users") // Returns "http://localhost:5173/api/users"
+ * getURL() // Returns "http://localhost:5173"
+ *
+ * // Assuming current page is "[https://example.com/products](https://example.com/products)"
+ * getURL("test") // Returns "[https://example.com/test](https://example.com/test)"
+ * ```
+ *
+ * @remarks
+ * - Uses globalThis.location.origin as the base URL.
+ * - Removes trailing slashes from base URL.
+ * - Removes leading slashes from path.
+ * - Handles empty/undefined path gracefully.
+ * - Suitable for client-side contexts where the API/resource is on the same origin.
+ * - NOT recommended for defining a fixed API base URL across environments or for server-side use.
+ */
+declare const getURL: (path?: string) => string;
+type Success<T> = {
+  readonly success: true;
+  readonly value: T;
+};
+type Failure<E> = {
+  readonly success: false;
+  readonly error: E;
+};
+type Result<T, E> = Success<T> | Failure<E>;
+/**
+ * Creates a successful result
+ * @param value The value to wrap in a success result
+ */
+declare const success: <T>(value: T) => Success<T>;
+/**
+ * Creates a failed result
+ * @param error The error to wrap in a failure result
+ */
+declare const failure: <E>(error: E) => Failure<E>;
+type ExtractAsyncArgs<Args extends Array<unknown>> = Args extends Array<infer PotentialArgTypes> ? [PotentialArgTypes] : [];
+declare const catchError: <Args extends Array<unknown>, ReturnType>(asyncFunction: (...args: ExtractAsyncArgs<Args>) => Promise<ReturnType>, ...args: ExtractAsyncArgs<Args>) => Promise<Result<ReturnType, Error>>;
+/**
+ * Maps a successful result to a new value
+ * @param fn Mapping function to apply to the successful value
+ */
+declare const map: <T, U, E>(fn: (value: T) => U) => ((result: Result<T, E>) => Result<U, E>);
+/**
+ * Chains a result-returning function after a successful result
+ * @param fn Function that returns a new result
+ */
+declare const bindResult: <T, U, E>(fn: (value: T) => Result<U, E>) => ((result: Result<T, E>) => Result<U, E>);
+/**
+ * Applies a series of functions to an input value, short-circuiting on the first failure
+ * @param input Initial input value
+ * @param functions Array of functions to apply sequentially
+ * @returns Final result after applying all functions or first encountered failure
+ */
+declare function railway<TInput, T1, E>(input: TInput, fn1: (input: TInput) => Result<T1, E>): Result<T1, E>;
+declare function railway<TInput, T1, T2, E>(input: TInput, fn1: (input: TInput) => Result<T1, E>, fn2: (input: T1) => Result<T2, E>): Result<T2, E>;
+declare function railway<TInput, T1, T2, T3, E>(input: TInput, fn1: (input: TInput) => Result<T1, E>, fn2: (input: T1) => Result<T2, E>, fn3: (input: T2) => Result<T3, E>): Result<T3, E>;
+declare function railway<TInput, T1, T2, T3, T4, E>(input: TInput, fn1: (input: TInput) => Result<T1, E>, fn2: (input: T1) => Result<T2, E>, fn3: (input: T2) => Result<T3, E>, fn4: (input: T3) => Result<T4, E>): Result<T4, E>;
+declare function railway<TInput, T1, T2, T3, T4, T5, E>(input: TInput, fn1: (input: TInput) => Result<T1, E>, fn2: (input: T1) => Result<T2, E>, fn3: (input: T2) => Result<T3, E>, fn4: (input: T3) => Result<T4, E>, fn5: (input: T4) => Result<T5, E>): Result<T5, E>;
+/**
+ * Recovers from a failure by applying a function to the error
+ * @param fn Function to handle the error and return a new result
+ */
+declare const recover: <T, E1, E2>(fn: (error: E1) => Result<T, E2>) => ((result: Result<T, E1>) => Result<T, E2>);
+/**
+ * Taps into a result chain for side effects without modifying the value
+ * @param fn Side effect function to execute on success
+ */
+declare const tap: <T, E>(fn: (value: T) => void) => ((result: Result<T, E>) => Result<T, E>);
+/**
+ * Checks if a value is a number
+ * @param value The value to check
+ */
+declare const isNumber: (value: unknown) => value is number;
+/**
+ * Checks if a value is a string
+ * @param value The value to check
+ */
+declare const isString: (value: unknown) => value is string;
+/**
+ * Checks if a value is a function
+ * @param value The value to check
+ */
+declare const isFunction: (value: unknown) => value is Function;
+/**
+ * Checks if a value is a promise
+ * @param value The value to check
+ */
+declare const isPromise: (value: unknown) => value is Promise<unknown>;
+//#endregion
+export { Stringify, bindResult, catchError, failure, getURL, isFunction, isNumber, isPromise, isString, map, railway, recover, success, tap };
+//# sourceMappingURL=helpers.d.ts.map

package/lib/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","names":[],"sources":["../src/helpers.ts"],"mappings":"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"}

package/lib/helpers.js

@@ -0,0 +1,159 @@
+import { Logger } from "@resq-sw/logger";
+//#region src/helpers.ts
+/**
+* Copyright 2026 ResQ
+*
+* Licensed under the Apache License, Version 2.0 (the "License");
+* you may not use this file except in compliance with the License.
+* You may obtain a copy of the License at
+*
+*     http://www.apache.org/licenses/LICENSE-2.0
+*
+* Unless required by applicable law or agreed to in writing, software
+* distributed under the License is distributed on an "AS IS" BASIS,
+* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+* See the License for the specific language governing permissions and
+* limitations under the License.
+*/
+const logger = Logger.getLogger("[helpers]");
+/**
+* Converts an object to a formatted JSON string with proper indentation.
+*
+* @param {object} obj - The object to convert to a JSON string
+* @returns {string} A properly formatted JSON string representation of the input object with 2-space indentation
+*
+* @example
+* ```ts
+* const obj = { name: "John", age: 30 };
+* const jsonString = Stringify(obj);
+* // Returns:
+* // {
+* //   "name": "John",
+* //   "age": 30
+* // }
+* ```
+*
+* @remarks
+* - Uses JSON.stringify() internally with null replacer and 2-space indent
+* - Handles circular references by throwing an error
+* - Preserves object structure and nesting
+* - Useful for debugging, logging, and data serialization
+* - Safe with primitives, arrays, objects, null and undefined
+*/
+const Stringify = (obj) => {
+	return JSON.stringify(obj, null, 2);
+};
+/**
+* Constructs a fully qualified URL based on the current globalThis's location,
+* with an optional path.
+*
+* @param {string} [path=''] - Optional path to append to the base URL
+* @returns {string} Complete URL with proper formatting and protocol
+*
+* @example
+* ```ts
+* // Assuming current page is "http://localhost:5173/dashboard"
+* getURL("api/users") // Returns "http://localhost:5173/api/users"
+* getURL() // Returns "http://localhost:5173"
+*
+* // Assuming current page is "[https://example.com/products](https://example.com/products)"
+* getURL("test") // Returns "[https://example.com/test](https://example.com/test)"
+* ```
+*
+* @remarks
+* - Uses globalThis.location.origin as the base URL.
+* - Removes trailing slashes from base URL.
+* - Removes leading slashes from path.
+* - Handles empty/undefined path gracefully.
+* - Suitable for client-side contexts where the API/resource is on the same origin.
+* - NOT recommended for defining a fixed API base URL across environments or for server-side use.
+*/
+const getURL = (path = "") => {
+	let url = "";
+	if (typeof globalThis !== "undefined" && globalThis.location?.origin) url = globalThis.location.origin;
+	else {
+		const envBaseUrl = process?.env?.["VITE_BASE_URL"] || process?.env?.["NEXT_PUBLIC_BASE_URL"] || process?.env?.["BASE_URL"];
+		if (envBaseUrl && typeof envBaseUrl === "string") url = envBaseUrl;
+		else {
+			logger.warn("getURL: 'globalThis' is not defined and no environment base URL found. This function relies on client-side context. Returning empty string.");
+			return "";
+		}
+	}
+	url = url.replace(/\/+$/, "");
+	const sanitizedPath = path.replace(/^\/+/, "");
+	return sanitizedPath ? `${url}/${sanitizedPath}` : url;
+};
+/**
+* Creates a successful result
+* @param value The value to wrap in a success result
+*/
+const success = (value) => Object.freeze({
+	success: true,
+	value
+});
+/**
+* Creates a failed result
+* @param error The error to wrap in a failure result
+*/
+const failure = (error) => Object.freeze({
+	success: false,
+	error
+});
+const catchError = async (asyncFunction, ...args) => {
+	try {
+		return success(await asyncFunction(...args));
+	} catch (error) {
+		logger.error("catchError", error);
+		return failure(error instanceof Error ? error : new Error(String(error)));
+	}
+};
+/**
+* Maps a successful result to a new value
+* @param fn Mapping function to apply to the successful value
+*/
+const map = (fn) => (result) => result.success ? success(fn(result.value)) : result;
+/**
+* Chains a result-returning function after a successful result
+* @param fn Function that returns a new result
+*/
+const bindResult = (fn) => (result) => result.success ? fn(result.value) : result;
+function railway(input, ...functions) {
+	return functions.reduce((result, fn) => result.success ? fn(result.value) : result, success(input));
+}
+/**
+* Recovers from a failure by applying a function to the error
+* @param fn Function to handle the error and return a new result
+*/
+const recover = (fn) => (result) => result.success ? result : fn(result.error);
+/**
+* Taps into a result chain for side effects without modifying the value
+* @param fn Side effect function to execute on success
+*/
+const tap = (fn) => (result) => {
+	if (result.success) fn(result.value);
+	return result;
+};
+/**
+* Checks if a value is a number
+* @param value The value to check
+*/
+const isNumber = (value) => typeof value === "number";
+/**
+* Checks if a value is a string
+* @param value The value to check
+*/
+const isString = (value) => typeof value === "string";
+/**
+* Checks if a value is a function
+* @param value The value to check
+*/
+const isFunction = (value) => typeof value === "function";
+/**
+* Checks if a value is a promise
+* @param value The value to check
+*/
+const isPromise = (value) => !!value && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+//#endregion
+export { Stringify, bindResult, catchError, failure, getURL, isFunction, isNumber, isPromise, isString, map, railway, recover, success, tap };
+
+//# sourceMappingURL=helpers.js.map

package/lib/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","names":[],"sources":["../src/helpers.ts"],"sourcesContent":["/**\n * Copyright 2026 ResQ\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *     http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { Logger } from '@resq-sw/logger';\n\nconst logger = Logger.getLogger('[helpers]');\n\n/**\n * Converts an object to a formatted JSON string with proper indentation.\n *\n * @param {object} obj - The object to convert to a JSON string\n * @returns {string} A properly formatted JSON string representation of the input object with 2-space indentation\n *\n * @example\n * ```ts\n * const obj = { name: \"John\", age: 30 };\n * const jsonString = Stringify(obj);\n * // Returns:\n * // {\n * //   \"name\": \"John\",\n * //   \"age\": 30\n * // }\n * ```\n *\n * @remarks\n * - Uses JSON.stringify() internally with null replacer and 2-space indent\n * - Handles circular references by throwing an error\n * - Preserves object structure and nesting\n * - Useful for debugging, logging, and data serialization\n * - Safe with primitives, arrays, objects, null and undefined\n */\nexport const Stringify = (obj: object): string => {\n  return JSON.stringify(obj, null, 2);\n};\n\n/**\n * Constructs a fully qualified URL based on the current globalThis's location,\n * with an optional path.\n *\n * @param {string} [path=''] - Optional path to append to the base URL\n * @returns {string} Complete URL with proper formatting and protocol\n *\n * @example\n * ```ts\n * // Assuming current page is \"http://localhost:5173/dashboard\"\n * getURL(\"api/users\") // Returns \"http://localhost:5173/api/users\"\n * getURL() // Returns \"http://localhost:5173\"\n *\n * // Assuming current page is \"[https://example.com/products](https://example.com/products)\"\n * getURL(\"test\") // Returns \"[https://example.com/test](https://example.com/test)\"\n * ```\n *\n * @remarks\n * - Uses globalThis.location.origin as the base URL.\n * - Removes trailing slashes from base URL.\n * - Removes leading slashes from path.\n * - Handles empty/undefined path gracefully.\n * - Suitable for client-side contexts where the API/resource is on the same origin.\n * - NOT recommended for defining a fixed API base URL across environments or for server-side use.\n */\nexport const getURL = (path = ''): string => {\n  let url = '';\n\n  // Use the current globalThis's  origin as the base URL if available.\n  // globalThis.location.origin includes the protocol, hostname, and port (e.g., \"https://example.com:8080\")\n  if (typeof globalThis !== 'undefined' && globalThis.location?.origin) {\n    url = globalThis.location.origin;\n  } else {\n    // This function will not work correctly in a non-browser environment (e.g., during SSR or build processes)\n    // where `globalThis` is not defined. We'll attempt to use environment variables for a more reliable default.\n    const envBaseUrl =\n      process?.env?.['VITE_BASE_URL'] ||\n      process?.env?.['NEXT_PUBLIC_BASE_URL'] ||\n      process?.env?.['BASE_URL'];\n\n    if (envBaseUrl && typeof envBaseUrl === 'string') {\n      url = envBaseUrl;\n    } else {\n      logger.warn(\n        \"getURL: 'globalThis' is not defined and no environment base URL found. This function relies on client-side context. Returning empty string.\",\n      );\n      return '';\n    }\n  }\n\n  // Remove any trailing slashes from the base URL (globalThis.location.origin typically doesn't have one, but for consistency)\n  url = url.replace(/\\/+$/, '');\n\n  // Remove any leading slashes from the path\n  const sanitizedPath = path.replace(/^\\/+/, '');\n\n  // Combine the URL and path, ensuring a single slash in between if a path exists\n  return sanitizedPath ? `${url}/${sanitizedPath}` : url;\n};\n\ntype Success<T> = {\n  readonly success: true;\n  readonly value: T;\n};\n\ntype Failure<E> = {\n  readonly success: false;\n  readonly error: E;\n};\n\ntype Result<T, E> = Success<T> | Failure<E>;\n\n/**\n * Creates a successful result\n * @param value The value to wrap in a success result\n */\nexport const success = <T>(value: T): Success<T> => Object.freeze({ success: true, value });\n\n/**\n * Creates a failed result\n * @param error The error to wrap in a failure result\n */\nexport const failure = <E>(error: E): Failure<E> => Object.freeze({ success: false, error });\n\ntype ExtractAsyncArgs<Args extends Array<unknown>> =\n  Args extends Array<infer PotentialArgTypes> ? [PotentialArgTypes] : [];\n\nexport const catchError = async <Args extends Array<unknown>, ReturnType>(\n  asyncFunction: (...args: ExtractAsyncArgs<Args>) => Promise<ReturnType>,\n  ...args: ExtractAsyncArgs<Args>\n): Promise<Result<ReturnType, Error>> => {\n  try {\n    const result = await asyncFunction(...args);\n    return success(result);\n  } catch (error) {\n    logger.error('catchError', error);\n    return failure(error instanceof Error ? error : new Error(String(error)));\n  }\n};\n\n/**\n * Maps a successful result to a new value\n * @param fn Mapping function to apply to the successful value\n */\nexport const map =\n  <T, U, E>(fn: (value: T) => U): ((result: Result<T, E>) => Result<U, E>) =>\n  (result) =>\n    result.success ? success(fn(result.value)) : result;\n\n/**\n * Chains a result-returning function after a successful result\n * @param fn Function that returns a new result\n */\nexport const bindResult =\n  <T, U, E>(fn: (value: T) => Result<U, E>): ((result: Result<T, E>) => Result<U, E>) =>\n  (result) =>\n    result.success ? fn(result.value) : result;\n\n/**\n * Applies a series of functions to an input value, short-circuiting on the first failure\n * @param input Initial input value\n * @param functions Array of functions to apply sequentially\n * @returns Final result after applying all functions or first encountered failure\n */\nexport function railway<TInput, T1, E>(\n  input: TInput,\n  fn1: (input: TInput) => Result<T1, E>,\n): Result<T1, E>;\nexport function railway<TInput, T1, T2, E>(\n  input: TInput,\n  fn1: (input: TInput) => Result<T1, E>,\n  fn2: (input: T1) => Result<T2, E>,\n): Result<T2, E>;\nexport function railway<TInput, T1, T2, T3, E>(\n  input: TInput,\n  fn1: (input: TInput) => Result<T1, E>,\n  fn2: (input: T1) => Result<T2, E>,\n  fn3: (input: T2) => Result<T3, E>,\n): Result<T3, E>;\nexport function railway<TInput, T1, T2, T3, T4, E>(\n  input: TInput,\n  fn1: (input: TInput) => Result<T1, E>,\n  fn2: (input: T1) => Result<T2, E>,\n  fn3: (input: T2) => Result<T3, E>,\n  fn4: (input: T3) => Result<T4, E>,\n): Result<T4, E>;\nexport function railway<TInput, T1, T2, T3, T4, T5, E>(\n  input: TInput,\n  fn1: (input: TInput) => Result<T1, E>,\n  fn2: (input: T1) => Result<T2, E>,\n  fn3: (input: T2) => Result<T3, E>,\n  fn4: (input: T3) => Result<T4, E>,\n  fn5: (input: T4) => Result<T5, E>,\n): Result<T5, E>;\nexport function railway<TInput, TOutput, E>(\n  input: TInput,\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  ...functions: Array<(input: any) => Result<any, E>>\n): Result<TOutput, E> {\n  return functions.reduce<Result<any, E>>(\n    (result, fn) => (result.success ? fn(result.value) : result),\n    success(input),\n  ) as Result<TOutput, E>;\n}\n\n/**\n * Recovers from a failure by applying a function to the error\n * @param fn Function to handle the error and return a new result\n */\nexport const recover =\n  <T, E1, E2>(fn: (error: E1) => Result<T, E2>): ((result: Result<T, E1>) => Result<T, E2>) =>\n  (result) =>\n    result.success ? result : fn(result.error);\n\n/**\n * Taps into a result chain for side effects without modifying the value\n * @param fn Side effect function to execute on success\n */\nexport const tap =\n  <T, E>(fn: (value: T) => void): ((result: Result<T, E>) => Result<T, E>) =>\n  (result) => {\n    if (result.success) {\n      fn(result.value);\n    }\n    return result;\n  };\n\n/**\n * Checks if a value is a number\n * @param value The value to check\n */\nexport const isNumber = (value: unknown): value is number => typeof value === 'number';\n\n/**\n * Checks if a value is a string\n * @param value The value to check\n */\nexport const isString = (value: unknown): value is string => typeof value === 'string';\n\n/**\n * Checks if a value is a function\n * @param value The value to check\n */\n// eslint-disable-next-line @typescript-eslint/ban-types\nexport const isFunction = (value: unknown): value is Function => typeof value === 'function';\n\n/**\n * Checks if a value is a promise\n * @param value The value to check\n */\nexport const isPromise = (value: unknown): value is Promise<unknown> =>\n  !!value &&\n  (typeof value === 'object' || typeof value === 'function') &&\n  typeof (value as Promise<unknown>).then === 'function';\n"],"mappings":";;;;;;;;;;;;;;;;;AAkBA,MAAM,SAAS,OAAO,UAAU,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;AA0B5C,MAAa,aAAa,QAAwB;AAChD,QAAO,KAAK,UAAU,KAAK,MAAM,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BrC,MAAa,UAAU,OAAO,OAAe;CAC3C,IAAI,MAAM;AAIV,KAAI,OAAO,eAAe,eAAe,WAAW,UAAU,OAC5D,OAAM,WAAW,SAAS;MACrB;EAGL,MAAM,aACJ,SAAS,MAAM,oBACf,SAAS,MAAM,2BACf,SAAS,MAAM;AAEjB,MAAI,cAAc,OAAO,eAAe,SACtC,OAAM;OACD;AACL,UAAO,KACL,8IACD;AACD,UAAO;;;AAKX,OAAM,IAAI,QAAQ,QAAQ,GAAG;CAG7B,MAAM,gBAAgB,KAAK,QAAQ,QAAQ,GAAG;AAG9C,QAAO,gBAAgB,GAAG,IAAI,GAAG,kBAAkB;;;;;;AAmBrD,MAAa,WAAc,UAAyB,OAAO,OAAO;CAAE,SAAS;CAAM;CAAO,CAAC;;;;;AAM3F,MAAa,WAAc,UAAyB,OAAO,OAAO;CAAE,SAAS;CAAO;CAAO,CAAC;AAK5F,MAAa,aAAa,OACxB,eACA,GAAG,SACoC;AACvC,KAAI;AAEF,SAAO,QADQ,MAAM,cAAc,GAAG,KAAK,CACrB;UACf,OAAO;AACd,SAAO,MAAM,cAAc,MAAM;AACjC,SAAO,QAAQ,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,MAAM,CAAC,CAAC;;;;;;;AAQ7E,MAAa,OACD,QACT,WACC,OAAO,UAAU,QAAQ,GAAG,OAAO,MAAM,CAAC,GAAG;;;;;AAMjD,MAAa,cACD,QACT,WACC,OAAO,UAAU,GAAG,OAAO,MAAM,GAAG;AAsCxC,SAAgB,QACd,OAEA,GAAG,WACiB;AACpB,QAAO,UAAU,QACd,QAAQ,OAAQ,OAAO,UAAU,GAAG,OAAO,MAAM,GAAG,QACrD,QAAQ,MAAM,CACf;;;;;;AAOH,MAAa,WACC,QACX,WACC,OAAO,UAAU,SAAS,GAAG,OAAO,MAAM;;;;;AAM9C,MAAa,OACJ,QACN,WAAW;AACV,KAAI,OAAO,QACT,IAAG,OAAO,MAAM;AAElB,QAAO;;;;;;AAOX,MAAa,YAAY,UAAoC,OAAO,UAAU;;;;;AAM9E,MAAa,YAAY,UAAoC,OAAO,UAAU;;;;;AAO9E,MAAa,cAAc,UAAsC,OAAO,UAAU;;;;;AAMlF,MAAa,aAAa,UACxB,CAAC,CAAC,UACD,OAAO,UAAU,YAAY,OAAO,UAAU,eAC/C,OAAQ,MAA2B,SAAS"}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+import { obfuscateLink } from "./browser/html-entities.js";
+import { getBrowser, getPlatform, isAndroid, isAndroidChrome, isAndroidEdge, isAndroidFirefox, isAndroidOpera, isChrome, isChromeOS, isEdge, isFirefox, isIOS, isIOSChrome, isIOSEdge, isIOSFirefox, isIOSOpera, isIOSSafari, isMacOS, isMacOSChrome, isMacOSEdge, isOpera, isSafari, isTouchScreen, isWindows, isWindowsChrome, isWindowsEdge } from "./browser/platform.js";
+import { DateFormatOptions } from "./formatting/date.types.js";
+import { formatDate, formatDateOnly, formatDatePeriod, formatDateTime, formatMonthYear, formatRelativeTime } from "./formatting/date.js";
+import { formatBytes, formatNumber, formatPercent } from "./formatting/number.js";
+import { capitalize, slugify, truncate } from "./formatting/string.js";
+import { Stringify, bindResult, catchError, failure, getURL, isFunction, isNumber, isPromise, isString, map, railway, recover, success, tap } from "./helpers.js";
+import { parseCodePath, parseCodePathDetailed } from "./parse-code-path.js";
+import { TaskExec } from "./task-exec.js";
+import { TimedTask } from "./task-exec.types.js";
+export { DateFormatOptions, Stringify, TaskExec, TimedTask, bindResult, capitalize, catchError, failure, formatBytes, formatDate, formatDateOnly, formatDatePeriod, formatDateTime, formatMonthYear, formatNumber, formatPercent, formatRelativeTime, getBrowser, getPlatform, getURL, isAndroid, isAndroidChrome, isAndroidEdge, isAndroidFirefox, isAndroidOpera, isChrome, isChromeOS, isEdge, isFirefox, isFunction, isIOS, isIOSChrome, isIOSEdge, isIOSFirefox, isIOSOpera, isIOSSafari, isMacOS, isMacOSChrome, isMacOSEdge, isNumber, isOpera, isPromise, isSafari, isString, isTouchScreen, isWindows, isWindowsChrome, isWindowsEdge, map, obfuscateLink, parseCodePath, parseCodePathDetailed, railway, recover, slugify, success, tap, truncate };

package/lib/index.js

@@ -0,0 +1,9 @@
+import { Stringify, bindResult, catchError, failure, getURL, isFunction, isNumber, isPromise, isString, map, railway, recover, success, tap } from "./helpers.js";
+import { parseCodePath, parseCodePathDetailed } from "./parse-code-path.js";
+import { TaskExec } from "./task-exec.js";
+import { formatDate, formatDateOnly, formatDatePeriod, formatDateTime, formatMonthYear, formatRelativeTime } from "./formatting/date.js";
+import { formatBytes, formatNumber, formatPercent } from "./formatting/number.js";
+import { capitalize, slugify, truncate } from "./formatting/string.js";
+import { getBrowser, getPlatform, isAndroid, isAndroidChrome, isAndroidEdge, isAndroidFirefox, isAndroidOpera, isChrome, isChromeOS, isEdge, isFirefox, isIOS, isIOSChrome, isIOSEdge, isIOSFirefox, isIOSOpera, isIOSSafari, isMacOS, isMacOSChrome, isMacOSEdge, isOpera, isSafari, isTouchScreen, isWindows, isWindowsChrome, isWindowsEdge } from "./browser/platform.js";
+import { obfuscateLink } from "./browser/html-entities.js";
+export { Stringify, TaskExec, bindResult, capitalize, catchError, failure, formatBytes, formatDate, formatDateOnly, formatDatePeriod, formatDateTime, formatMonthYear, formatNumber, formatPercent, formatRelativeTime, getBrowser, getPlatform, getURL, isAndroid, isAndroidChrome, isAndroidEdge, isAndroidFirefox, isAndroidOpera, isChrome, isChromeOS, isEdge, isFirefox, isFunction, isIOS, isIOSChrome, isIOSEdge, isIOSFirefox, isIOSOpera, isIOSSafari, isMacOS, isMacOSChrome, isMacOSEdge, isNumber, isOpera, isPromise, isSafari, isString, isTouchScreen, isWindows, isWindowsChrome, isWindowsEdge, map, obfuscateLink, parseCodePath, parseCodePathDetailed, railway, recover, slugify, success, tap, truncate };

package/lib/parse-code-path.d.ts

@@ -0,0 +1,85 @@
+//#region src/parse-code-path.d.ts
+/**
+ * Copyright 2026 ResQ
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Parses and constructs a formatted string representing the code location, including the file path,
+ * associated entity name (such as a function, class, component, or decorator), and human context.
+ *
+ * The result is useful for debugging, developer logging, and traceability—matching the entity (function, class, etc.)
+ * and the context in source code references.
+ *
+ * @template C The type of the context value.
+ * @template T The type of the entity parameter.
+ * @param {C} context - A description, situation, or custom value relevant to this code path.
+ * @param {T} entity - The entity whose name is included; may be a function, class, object, component, decorator, or their name.
+ * @returns {string} A formatted string: "location: <path> @<entity>: <context>".
+ * @throws {Error} This function does not throw directly, but see {@link getFilePath}, which may throw in rare stack-trace parsing errors.
+ * @example
+ * // Function usage
+ * function myFunction() {}
+ * parseCodePath('initialization', myFunction);
+ * // => "location: /current/dir/file.js @myFunction: initialization"
+ *
+ * // Class usage
+ * class MyClass {}
+ * parseCodePath('instantiating MyClass', MyClass);
+ * // => "location: ... @MyClass: instantiating MyClass"
+ *
+ * // String as entity
+ * parseCodePath('some context', 'EntityAsString');
+ * // => "location: ... @EntityAsString: some context"
+ *
+
+ * @see parseCodePathDetailed
+
+ * @readonly
+ * @public
+ * @version 1.0.0
+ */
+declare const parseCodePath: <C, T>(context: C, entity: T) => string;
+/**
+ * Parses and constructs a detailed formatted location string, including file path, entity, and context,
+ * with optional line number, ISO timestamp, and custom prefix control. Useful for enhanced debugging or audit logs.
+ *
+ * @template C The type of the context parameter.
+ * @template T The type of entity (function, class, etc.).
+ * @param {C} context - Context description of the operation or location.
+ * @param {T} entity - The entity whose name is included.
+ * @param {object} [options] - Optional configuration for output.
+ * @param {boolean} [options.includeLineNumber] - If true, appends the call site line number.
+ * @param {boolean} [options.includeTimestamp] - If true, appends an ISO 8601 timestamp.
+ * @param {string}  [options.customPrefix] - Custom prefix instead of default "location".
+ * @returns {string} Detailed formatted location string.
+ * @throws {Error} Does not throw directly but relies on internal getFilePath logic.
+ * @example
+ * parseCodePathDetailed('init', MyClass, {includeLineNumber: true, includeTimestamp: true});
+ * // => "location: ...:42 [2024-06-01T08:00:00.000Z] @MyClass: init"
+ *
+
+ * @see parseCodePath
+
+ * @readonly
+ * @public
+ * @version 1.0.0
+ */
+declare const parseCodePathDetailed: <C, T>(context: C, entity: T, options?: {
+  includeLineNumber?: boolean;
+  includeTimestamp?: boolean;
+  customPrefix?: string;
+}) => string;
+//#endregion
+export { parseCodePath, parseCodePathDetailed };
+//# sourceMappingURL=parse-code-path.d.ts.map

package/lib/parse-code-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-code-path.d.ts","names":[],"sources":["../src/parse-code-path.ts"],"mappings":";;AAmDA;;;;;;;;;;;;AAkHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAlHa,aAAA,SAAuB,OAAA,EAAS,CAAA,EAAG,MAAA,EAAQ,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;cAkH3C,qBAAA,SACX,OAAA,EAAS,CAAA,EACT,MAAA,EAAQ,CAAA,EACR,OAAA;EACE,iBAAA;EACA,gBAAA;EACA,YAAA;AAAA"}