@ls-stack/utils 3.36.0 → 3.38.0

package/dist/asyncQueue.cjs

@@ -61,10 +61,10 @@ var AsyncQueue = class {
     this.#signal = signal;
     this.#taskTimeout = taskTimeout;
     this.events.on("error", (e) => {
-      this.failures.push(e);
+      this.failures.push(e.payload);
     });
     this.events.on("complete", (e) => {
-      this.completions.push(e);
+      this.completions.push(e.payload);
     });
   }
   #enqueue(task) {

package/dist/asyncQueue.js

@@ -32,10 +32,10 @@ var AsyncQueue = class {
     this.#signal = signal;
     this.#taskTimeout = taskTimeout;
     this.events.on("error", (e) => {
-      this.failures.push(e);
+      this.failures.push(e.payload);
     });
     this.events.on("complete", (e) => {
-      this.completions.push(e);
+      this.completions.push(e.payload);
     });
   }
   #enqueue(task) {

package/dist/testUtils.cjs

@@ -1347,6 +1347,7 @@ function compactSnapshot(value, {
   maxLineLength = 100,
   showUndefined = false,
   showBooleansAs = true,
+  replaceValues,
   rejectKeys,
   filterKeys,
   sortKeys,
@@ -1364,6 +1365,9 @@ function compactSnapshot(value, {
       });
     }
   }
+  if (replaceValues) {
+    processedValue = applyValueReplacements(processedValue, replaceValues);
+  }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `
 ${yamlStringify(processedValue, {
@@ -1373,6 +1377,46 @@ ${yamlStringify(processedValue, {
     ...options
   })}`;
 }
+function applyValueReplacements(value, replaceValues, visited = /* @__PURE__ */ new Set(), currentPath = "") {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
 function replaceBooleansWithEmoji(value, showBooleansAs, visited = /* @__PURE__ */ new Set()) {
   if (showBooleansAs === false) {
     return value;

package/dist/testUtils.d.cts

@@ -88,11 +88,12 @@ declare function waitController(): {
  * @param options.rejectKeys - The keys to reject.
  * @param options.filterKeys - The keys to filter.
  * @param options.ignoreProps - The props to ignore.
+ * @param options.replaceValues - Function to replace values at specific paths. Returns `false` to keep original value or `{newValue}` to replace.
  * @param options.sortKeys - Sort all keys by a specific order (default: `simpleValuesFirst`).
  * @param options.sortPatterns - Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
  * @returns The compact snapshot of the value.
  */
-declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
+declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, replaceValues, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
     showBooleansAs?: boolean | {
         props?: Record<string, {
             trueText?: string;
@@ -102,6 +103,9 @@ declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLengt
         trueText?: string;
         falseText?: string;
     };
+    replaceValues?: (value: unknown, path: string) => false | {
+        newValue: unknown;
+    };
     rejectKeys?: string[] | string;
     filterKeys?: string[] | string;
     sortKeys?: 'asc' | 'desc' | 'simpleValuesFirst' | false;

package/dist/testUtils.d.ts

@@ -88,11 +88,12 @@ declare function waitController(): {
  * @param options.rejectKeys - The keys to reject.
  * @param options.filterKeys - The keys to filter.
  * @param options.ignoreProps - The props to ignore.
+ * @param options.replaceValues - Function to replace values at specific paths. Returns `false` to keep original value or `{newValue}` to replace.
  * @param options.sortKeys - Sort all keys by a specific order (default: `simpleValuesFirst`).
  * @param options.sortPatterns - Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
  * @returns The compact snapshot of the value.
  */
-declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
+declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, replaceValues, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
     showBooleansAs?: boolean | {
         props?: Record<string, {
             trueText?: string;
@@ -102,6 +103,9 @@ declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLengt
         trueText?: string;
         falseText?: string;
     };
+    replaceValues?: (value: unknown, path: string) => false | {
+        newValue: unknown;
+    };
     rejectKeys?: string[] | string;
     filterKeys?: string[] | string;
     sortKeys?: 'asc' | 'desc' | 'simpleValuesFirst' | false;

package/dist/testUtils.js

@@ -261,6 +261,7 @@ function compactSnapshot(value, {
   maxLineLength = 100,
   showUndefined = false,
   showBooleansAs = true,
+  replaceValues,
   rejectKeys,
   filterKeys,
   sortKeys,
@@ -278,6 +279,9 @@ function compactSnapshot(value, {
       });
     }
   }
+  if (replaceValues) {
+    processedValue = applyValueReplacements(processedValue, replaceValues);
+  }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `
 ${yamlStringify(processedValue, {
@@ -287,6 +291,46 @@ ${yamlStringify(processedValue, {
     ...options
   })}`;
 }
+function applyValueReplacements(value, replaceValues, visited = /* @__PURE__ */ new Set(), currentPath = "") {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
 function replaceBooleansWithEmoji(value, showBooleansAs, visited = /* @__PURE__ */ new Set()) {
   if (showBooleansAs === false) {
     return value;

package/dist/typeUtils.d.cts

@@ -35,5 +35,12 @@ type DeepReplaceValueImpl<T, ReplaceType, NewType, SkipPaths extends string | un
  * @template SkipTypes - The types to skip in transverse and replace.
  */
 type DeepReplaceValue<T, ReplaceType, NewType, SkipPaths extends string | undefined = undefined, SkipTypes = DefaultSkipTransverseDeepReplace> = DeepReplaceValueImpl<T, ReplaceType, NewType, SkipPaths, SkipTypes>;
+type KeysWithUndefinedValues<T extends Record<string, unknown>> = {
+    [K in keyof T]: undefined extends T[K] ? K : never;
+}[keyof T];
+/**
+ * Marks all possible undefined values as partial at the root level of the object.
+ */
+type PartialPossiblyUndefinedValues<T extends Record<string, unknown>> = Prettify<Partial<Pick<T, KeysWithUndefinedValues<T>>> & Omit<T, KeysWithUndefinedValues<T>>>;
 
-export type { DeepPrettify, DeepReplaceValue, DefaultSkipTransverseDeepReplace, IsAny, NonPartial, ObjKeysWithValuesOfType, PartialRecord, Prettify };
+export type { DeepPrettify, DeepReplaceValue, DefaultSkipTransverseDeepReplace, IsAny, NonPartial, ObjKeysWithValuesOfType, PartialPossiblyUndefinedValues, PartialRecord, Prettify };

package/dist/typeUtils.d.ts

@@ -35,5 +35,12 @@ type DeepReplaceValueImpl<T, ReplaceType, NewType, SkipPaths extends string | un
  * @template SkipTypes - The types to skip in transverse and replace.
  */
 type DeepReplaceValue<T, ReplaceType, NewType, SkipPaths extends string | undefined = undefined, SkipTypes = DefaultSkipTransverseDeepReplace> = DeepReplaceValueImpl<T, ReplaceType, NewType, SkipPaths, SkipTypes>;
+type KeysWithUndefinedValues<T extends Record<string, unknown>> = {
+    [K in keyof T]: undefined extends T[K] ? K : never;
+}[keyof T];
+/**
+ * Marks all possible undefined values as partial at the root level of the object.
+ */
+type PartialPossiblyUndefinedValues<T extends Record<string, unknown>> = Prettify<Partial<Pick<T, KeysWithUndefinedValues<T>>> & Omit<T, KeysWithUndefinedValues<T>>>;
 
-export type { DeepPrettify, DeepReplaceValue, DefaultSkipTransverseDeepReplace, IsAny, NonPartial, ObjKeysWithValuesOfType, PartialRecord, Prettify };
+export type { DeepPrettify, DeepReplaceValue, DefaultSkipTransverseDeepReplace, IsAny, NonPartial, ObjKeysWithValuesOfType, PartialPossiblyUndefinedValues, PartialRecord, Prettify };

package/dist/typedStrings.cjs

@@ -0,0 +1,90 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/typedStrings.ts
+var typedStrings_exports = {};
+__export(typedStrings_exports, {
+  asNonEmptyStringOrNull: () => asNonEmptyStringOrNull,
+  asNonEmptyStringOrThrow: () => asNonEmptyStringOrThrow,
+  assertStringIsNonEmpty: () => assertStringIsNonEmpty,
+  isNonEmptyString: () => isNonEmptyString,
+  splitTypedString: () => splitTypedString,
+  splitTypedStringAt: () => splitTypedStringAt,
+  stringContains: () => stringContains,
+  stringEndsWith: () => stringEndsWith,
+  stringStartsWith: () => stringStartsWith
+});
+module.exports = __toCommonJS(typedStrings_exports);
+function stringContains(str, substring) {
+  return str.includes(substring);
+}
+function stringStartsWith(str, substring) {
+  return str.startsWith(substring);
+}
+function stringEndsWith(str, substring) {
+  return str.endsWith(substring);
+}
+function splitTypedString(str, separator) {
+  return str.split(separator);
+}
+function splitTypedStringAt(str, separator, splitAtNSeparatorPos = 1) {
+  const parts = str.split(separator);
+  let leftPart = parts[0];
+  let rightPart = parts.slice(1).join(separator);
+  if (leftPart === void 0) {
+    throw new Error("String does not contain the separator");
+  }
+  if (splitAtNSeparatorPos > 1) {
+    leftPart = parts.slice(0, splitAtNSeparatorPos).join(separator);
+    rightPart = parts.slice(splitAtNSeparatorPos).join(separator);
+  }
+  return [leftPart, rightPart];
+}
+function isNonEmptyString(str) {
+  return str.length > 0;
+}
+function asNonEmptyStringOrThrow(str) {
+  if (isNonEmptyString(str)) {
+    return str;
+  }
+  throw new Error("String is empty");
+}
+function asNonEmptyStringOrNull(str) {
+  if (isNonEmptyString(str)) {
+    return str;
+  }
+  return null;
+}
+function assertStringIsNonEmpty(str) {
+  if (!isNonEmptyString(str)) {
+    throw new Error("String is empty");
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  asNonEmptyStringOrNull,
+  asNonEmptyStringOrThrow,
+  assertStringIsNonEmpty,
+  isNonEmptyString,
+  splitTypedString,
+  splitTypedStringAt,
+  stringContains,
+  stringEndsWith,
+  stringStartsWith
+});

package/dist/typedStrings.d.cts

@@ -0,0 +1,152 @@
+/**
+ * A type representing a string that contains a specific substring.
+ * Uses template literal types to ensure type safety at compile time.
+ *
+ * @template T - The substring that must be contained within the string
+ * @example
+ * ```ts
+ * type EmailString = StringContaining<'@'>; // string that contains '@'
+ * const email: EmailString = 'user@example.com'; // ✓ valid
+ * ```
+ */
+type StringContaining<T extends string> = string extends T ? never : `${string}${T}${string}`;
+/**
+ * A type representing a string that starts with a specific substring.
+ * Uses template literal types to ensure the string begins with the specified prefix.
+ *
+ * @template T - The substring that the string must start with
+ * @example
+ * ```ts
+ * type HttpUrl = StringStartingWith<'http'>; // string starting with 'http'
+ * const url: HttpUrl = 'https://example.com'; // ✓ valid
+ * ```
+ */
+type StringStartingWith<T extends string> = string extends T ? never : `${T}${string}`;
+/**
+ * A type representing a string that ends with a specific substring.
+ * Uses template literal types to ensure the string ends with the specified suffix.
+ *
+ * @template T - The substring that the string must end with
+ * @example
+ * ```ts
+ * type JavaFile = StringEndingWith<'.java'>; // string ending with '.java'
+ * const filename: JavaFile = 'HelloWorld.java'; // ✓ valid
+ * ```
+ */
+type StringEndingWith<T extends string> = string extends T ? never : `${string}${T}`;
+/**
+ * Type guard function that checks if a string contains a specific substring.
+ * Narrows the type to `StringContaining<T>` when the check passes.
+ *
+ * @param str - The string to check
+ * @param substring - The substring to search for
+ * @returns `true` if the string contains the substring, `false` otherwise
+ */
+declare function stringContains<T extends string>(str: string, substring: T): str is StringContaining<T>;
+/**
+ * Type guard function that checks if a string starts with a specific substring.
+ * Narrows the type to `StringStartingWith<T>` when the check passes.
+ *
+ * @param str - The string to check
+ * @param substring - The substring to check for at the beginning
+ * @returns `true` if the string starts with the substring, `false` otherwise
+ */
+declare function stringStartsWith<T extends string>(str: string, substring: T): str is StringStartingWith<T>;
+/**
+ * Type guard function that checks if a string ends with a specific substring.
+ * Narrows the type to `StringEndingWith<T>` when the check passes.
+ *
+ * @param str - The string to check
+ * @param substring - The substring to check for at the end
+ * @returns `true` if the string ends with the substring, `false` otherwise
+ */
+declare function stringEndsWith<T extends string>(str: string, substring: T): str is StringEndingWith<T>;
+/**
+ * Splits a typed string by a separator that is guaranteed to exist in the string.
+ * Returns an array with at least two elements: the parts before and after the first separator,
+ * plus any additional parts if there are multiple separators.
+ *
+ * @param str - A string that contains, starts with, or ends with the separator
+ * @param separator - The separator to split by
+ * @returns An array with at least two string elements
+ * @example
+ * ```ts
+ * const path: StringContaining<'/'> = 'src/utils/types.ts';
+ * const [first, second, ...rest] = splitTypedString(path, '/');
+ * // first: 'src', second: 'utils', rest: ['types.ts']
+ * ```
+ */
+declare function splitTypedString<T extends string>(str: StringContaining<NoInfer<T>> | StringStartingWith<NoInfer<T>> | StringEndingWith<NoInfer<T>>, separator: T): [string, string, ...string[]];
+/**
+ * Splits a typed string at a specific occurrence of the separator.
+ * Unlike `splitTypedString`, this returns exactly two parts: everything before
+ * the nth separator and everything after it.
+ *
+ * @param str - A string that contains, starts with, or ends with the separator
+ * @param separator - The separator to split by
+ * @param splitAtNSeparatorPos - The position of the separator to split at (1-based)
+ * @returns A tuple with exactly two string elements
+ * @example
+ * ```ts
+ * const path: StringContaining<'.'> = 'file.name.ext';
+ * const [name, ext] = splitTypedStringAt(path, '.', 2);
+ * // name: 'file.name', ext: 'ext'
+ * ```
+ */
+declare function splitTypedStringAt<T extends string>(str: StringContaining<NoInfer<T>> | StringStartingWith<NoInfer<T>> | StringEndingWith<NoInfer<T>>, separator: T, 
+/**
+ * The position of the separator to split at.
+ * @default 1 - split at the first separator
+ */
+splitAtNSeparatorPos?: number): [string, string];
+/**
+ * A branded type representing a string that is guaranteed to be non-empty (length > 0).
+ * This type provides compile-time safety by preventing empty strings from being
+ * assigned without proper validation.
+ *
+ * @example
+ * ```ts
+ * function processName(name: NonEmptyString) {
+ *   // name is guaranteed to be non-empty
+ *   return name.toUpperCase();
+ * }
+ * ```
+ */
+type NonEmptyString = string & {
+    __nonEmptyString: true;
+};
+/**
+ * Type guard function that checks if a string is non-empty.
+ * Narrows the type to `NonEmptyString` when the check passes.
+ *
+ * @param str - The string to check
+ * @returns `true` if the string has length > 0, `false` otherwise
+ */
+declare function isNonEmptyString(str: string): str is NonEmptyString;
+/**
+ * Converts a string to `NonEmptyString` or throws an error if the string is empty.
+ * Use this when you need to ensure a string is non-empty and want to fail fast.
+ *
+ * @param str - The string to convert
+ * @returns The string as `NonEmptyString`
+ * @throws Error if the string is empty
+ */
+declare function asNonEmptyStringOrThrow(str: string): NonEmptyString;
+/**
+ * Converts a string to `NonEmptyString` or returns `null` if the string is empty.
+ * Use this when empty strings should be handled gracefully rather than throwing errors.
+ *
+ * @param str - The string to convert
+ * @returns The string as `NonEmptyString` or `null` if empty
+ */
+declare function asNonEmptyStringOrNull(str: string): NonEmptyString | null;
+/**
+ * Assertion function that ensures a string is non-empty.
+ * Throws an error if the string is empty, otherwise narrows the type to `NonEmptyString`.
+ *
+ * @param str - The string to assert as non-empty
+ * @throws Error if the string is empty
+ */
+declare function assertStringIsNonEmpty(str: string): asserts str is NonEmptyString;
+
+export { type NonEmptyString, type StringContaining, type StringEndingWith, type StringStartingWith, asNonEmptyStringOrNull, asNonEmptyStringOrThrow, assertStringIsNonEmpty, isNonEmptyString, splitTypedString, splitTypedStringAt, stringContains, stringEndsWith, stringStartsWith };

package/dist/typedStrings.d.ts

@@ -0,0 +1,152 @@
+/**
+ * A type representing a string that contains a specific substring.
+ * Uses template literal types to ensure type safety at compile time.
+ *
+ * @template T - The substring that must be contained within the string
+ * @example
+ * ```ts
+ * type EmailString = StringContaining<'@'>; // string that contains '@'
+ * const email: EmailString = 'user@example.com'; // ✓ valid
+ * ```
+ */
+type StringContaining<T extends string> = string extends T ? never : `${string}${T}${string}`;
+/**
+ * A type representing a string that starts with a specific substring.
+ * Uses template literal types to ensure the string begins with the specified prefix.
+ *
+ * @template T - The substring that the string must start with
+ * @example
+ * ```ts
+ * type HttpUrl = StringStartingWith<'http'>; // string starting with 'http'
+ * const url: HttpUrl = 'https://example.com'; // ✓ valid
+ * ```
+ */
+type StringStartingWith<T extends string> = string extends T ? never : `${T}${string}`;
+/**
+ * A type representing a string that ends with a specific substring.
+ * Uses template literal types to ensure the string ends with the specified suffix.
+ *
+ * @template T - The substring that the string must end with
+ * @example
+ * ```ts
+ * type JavaFile = StringEndingWith<'.java'>; // string ending with '.java'
+ * const filename: JavaFile = 'HelloWorld.java'; // ✓ valid
+ * ```
+ */
+type StringEndingWith<T extends string> = string extends T ? never : `${string}${T}`;
+/**
+ * Type guard function that checks if a string contains a specific substring.
+ * Narrows the type to `StringContaining<T>` when the check passes.
+ *
+ * @param str - The string to check
+ * @param substring - The substring to search for
+ * @returns `true` if the string contains the substring, `false` otherwise
+ */
+declare function stringContains<T extends string>(str: string, substring: T): str is StringContaining<T>;
+/**
+ * Type guard function that checks if a string starts with a specific substring.
+ * Narrows the type to `StringStartingWith<T>` when the check passes.
+ *
+ * @param str - The string to check
+ * @param substring - The substring to check for at the beginning
+ * @returns `true` if the string starts with the substring, `false` otherwise
+ */
+declare function stringStartsWith<T extends string>(str: string, substring: T): str is StringStartingWith<T>;
+/**
+ * Type guard function that checks if a string ends with a specific substring.
+ * Narrows the type to `StringEndingWith<T>` when the check passes.
+ *
+ * @param str - The string to check
+ * @param substring - The substring to check for at the end
+ * @returns `true` if the string ends with the substring, `false` otherwise
+ */
+declare function stringEndsWith<T extends string>(str: string, substring: T): str is StringEndingWith<T>;
+/**
+ * Splits a typed string by a separator that is guaranteed to exist in the string.
+ * Returns an array with at least two elements: the parts before and after the first separator,
+ * plus any additional parts if there are multiple separators.
+ *
+ * @param str - A string that contains, starts with, or ends with the separator
+ * @param separator - The separator to split by
+ * @returns An array with at least two string elements
+ * @example
+ * ```ts
+ * const path: StringContaining<'/'> = 'src/utils/types.ts';
+ * const [first, second, ...rest] = splitTypedString(path, '/');
+ * // first: 'src', second: 'utils', rest: ['types.ts']
+ * ```
+ */
+declare function splitTypedString<T extends string>(str: StringContaining<NoInfer<T>> | StringStartingWith<NoInfer<T>> | StringEndingWith<NoInfer<T>>, separator: T): [string, string, ...string[]];
+/**
+ * Splits a typed string at a specific occurrence of the separator.
+ * Unlike `splitTypedString`, this returns exactly two parts: everything before
+ * the nth separator and everything after it.
+ *
+ * @param str - A string that contains, starts with, or ends with the separator
+ * @param separator - The separator to split by
+ * @param splitAtNSeparatorPos - The position of the separator to split at (1-based)
+ * @returns A tuple with exactly two string elements
+ * @example
+ * ```ts
+ * const path: StringContaining<'.'> = 'file.name.ext';
+ * const [name, ext] = splitTypedStringAt(path, '.', 2);
+ * // name: 'file.name', ext: 'ext'
+ * ```
+ */
+declare function splitTypedStringAt<T extends string>(str: StringContaining<NoInfer<T>> | StringStartingWith<NoInfer<T>> | StringEndingWith<NoInfer<T>>, separator: T, 
+/**
+ * The position of the separator to split at.
+ * @default 1 - split at the first separator
+ */
+splitAtNSeparatorPos?: number): [string, string];
+/**
+ * A branded type representing a string that is guaranteed to be non-empty (length > 0).
+ * This type provides compile-time safety by preventing empty strings from being
+ * assigned without proper validation.
+ *
+ * @example
+ * ```ts
+ * function processName(name: NonEmptyString) {
+ *   // name is guaranteed to be non-empty
+ *   return name.toUpperCase();
+ * }
+ * ```
+ */
+type NonEmptyString = string & {
+    __nonEmptyString: true;
+};
+/**
+ * Type guard function that checks if a string is non-empty.
+ * Narrows the type to `NonEmptyString` when the check passes.
+ *
+ * @param str - The string to check
+ * @returns `true` if the string has length > 0, `false` otherwise
+ */
+declare function isNonEmptyString(str: string): str is NonEmptyString;
+/**
+ * Converts a string to `NonEmptyString` or throws an error if the string is empty.
+ * Use this when you need to ensure a string is non-empty and want to fail fast.
+ *
+ * @param str - The string to convert
+ * @returns The string as `NonEmptyString`
+ * @throws Error if the string is empty
+ */
+declare function asNonEmptyStringOrThrow(str: string): NonEmptyString;
+/**
+ * Converts a string to `NonEmptyString` or returns `null` if the string is empty.
+ * Use this when empty strings should be handled gracefully rather than throwing errors.
+ *
+ * @param str - The string to convert
+ * @returns The string as `NonEmptyString` or `null` if empty
+ */
+declare function asNonEmptyStringOrNull(str: string): NonEmptyString | null;
+/**
+ * Assertion function that ensures a string is non-empty.
+ * Throws an error if the string is empty, otherwise narrows the type to `NonEmptyString`.
+ *
+ * @param str - The string to assert as non-empty
+ * @throws Error if the string is empty
+ */
+declare function assertStringIsNonEmpty(str: string): asserts str is NonEmptyString;
+
+export { type NonEmptyString, type StringContaining, type StringEndingWith, type StringStartingWith, asNonEmptyStringOrNull, asNonEmptyStringOrThrow, assertStringIsNonEmpty, isNonEmptyString, splitTypedString, splitTypedStringAt, stringContains, stringEndsWith, stringStartsWith };