@ls-stack/utils 3.37.0 → 3.38.0

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 };

package/dist/typedStrings.js

@@ -0,0 +1,57 @@
+// src/typedStrings.ts
+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");
+  }
+}
+export {
+  asNonEmptyStringOrNull,
+  asNonEmptyStringOrThrow,
+  assertStringIsNonEmpty,
+  isNonEmptyString,
+  splitTypedString,
+  splitTypedStringAt,
+  stringContains,
+  stringEndsWith,
+  stringStartsWith
+};

package/dist/typingFnUtils.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var typingFnUtils_exports = {};
 __export(typingFnUtils_exports, {
   asNonPartial: () => asNonPartial,
+  asPartialUndefinedValues: () => asPartialUndefinedValues,
   asType: () => asType,
   isObjKey: () => isObjKey,
   isSubTypeOf: () => isSubTypeOf,
@@ -62,9 +63,13 @@ function isObjKey(key, obj) {
 }
 function unionsAreTheSame(_diff) {
 }
+function asPartialUndefinedValues(value) {
+  return value;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   asNonPartial,
+  asPartialUndefinedValues,
   asType,
   isObjKey,
   isSubTypeOf,

package/dist/typingFnUtils.d.cts

@@ -1,3 +1,4 @@
+import { PartialPossiblyUndefinedValues } from './typeUtils.cjs';
 import { NonPartial } from './typingUtils.cjs';
 
 declare function asNonPartial<T extends Record<string, unknown>>(obj: T): NonPartial<T>;
@@ -60,5 +61,6 @@ type UnionDiff<T, U> = [
  * @param _diff - null if unions are identical, or an object describing the errors
  */
 declare function unionsAreTheSame<T, U>(_diff: UnionDiff<T, U>): void;
+declare function asPartialUndefinedValues<T extends Record<string, unknown>>(value: PartialPossiblyUndefinedValues<T>): T;
 
-export { asNonPartial, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typeOnRightExtendsLeftType, typedObjectEntries, typedObjectKeys, unionsAreTheSame };
+export { asNonPartial, asPartialUndefinedValues, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typeOnRightExtendsLeftType, typedObjectEntries, typedObjectKeys, unionsAreTheSame };

package/dist/typingFnUtils.d.ts

@@ -1,3 +1,4 @@
+import { PartialPossiblyUndefinedValues } from './typeUtils.js';
 import { NonPartial } from './typingUtils.js';
 
 declare function asNonPartial<T extends Record<string, unknown>>(obj: T): NonPartial<T>;
@@ -60,5 +61,6 @@ type UnionDiff<T, U> = [
  * @param _diff - null if unions are identical, or an object describing the errors
  */
 declare function unionsAreTheSame<T, U>(_diff: UnionDiff<T, U>): void;
+declare function asPartialUndefinedValues<T extends Record<string, unknown>>(value: PartialPossiblyUndefinedValues<T>): T;
 
-export { asNonPartial, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typeOnRightExtendsLeftType, typedObjectEntries, typedObjectKeys, unionsAreTheSame };
+export { asNonPartial, asPartialUndefinedValues, asType, isObjKey, isSubTypeOf, narrowStringToUnion, typeOnRightExtendsLeftType, typedObjectEntries, typedObjectKeys, unionsAreTheSame };

package/dist/typingFnUtils.js

@@ -30,8 +30,12 @@ function isObjKey(key, obj) {
 }
 function unionsAreTheSame(_diff) {
 }
+function asPartialUndefinedValues(value) {
+  return value;
+}
 export {
   asNonPartial,
+  asPartialUndefinedValues,
   asType,
   isObjKey,
   isSubTypeOf,

package/docs/_media/modules.md

@@ -48,6 +48,7 @@
 - [time](time.md)
 - [timers](timers.md)
 - [tsResult](tsResult/README.md)
+- [typedStrings](typedStrings.md)
 - [typeGuards](typeGuards.md)
 - [typeUtils](typeUtils/README.md)
 - [typeUtils.typesTest](typeUtils.typesTest.md)

package/docs/modules.md

@@ -48,6 +48,7 @@
 - [time](time.md)
 - [timers](timers.md)
 - [tsResult](tsResult/README.md)
+- [typedStrings](typedStrings.md)
 - [typeGuards](typeGuards.md)
 - [typeUtils](typeUtils/README.md)
 - [typeUtils.typesTest](typeUtils.typesTest.md)

package/docs/typeUtils/README.md

@@ -142,6 +142,24 @@ Defined in: [packages/utils/src/typeUtils.ts:7](https://github.com/lucasols/util
 
 ***
 
+### PartialPossiblyUndefinedValues\<T\>
+
+```ts
+type PartialPossiblyUndefinedValues<T> = Prettify<Partial<Pick<T, KeysWithUndefinedValues<T>>> & Omit<T, KeysWithUndefinedValues<T>>>;
+```
+
+Defined in: [packages/utils/src/typeUtils.ts:156](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeUtils.ts#L156)
+
+Marks all possible undefined values as partial at the root level of the object.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+***
+
 ### PartialRecord\<K, T\>
 
 ```ts

package/docs/typedStrings.md

@@ -0,0 +1,458 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / typedStrings
+
+# typedStrings
+
+## Type Aliases
+
+### NonEmptyString
+
+```ts
+type NonEmptyString = string & object;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:171](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L171)
+
+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.
+
+#### Type declaration
+
+##### \_\_nonEmptyString
+
+```ts
+__nonEmptyString: true;
+```
+
+#### Example
+
+```ts
+function processName(name: NonEmptyString) {
+  // name is guaranteed to be non-empty
+  return name.toUpperCase();
+}
+```
+
+***
+
+### StringContaining\<T\>
+
+```ts
+type StringContaining<T> = string extends T ? never : `${string}${T}${string}`;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:12](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L12)
+
+A type representing a string that contains a specific substring.
+Uses template literal types to ensure type safety at compile time.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+The substring that must be contained within the string
+
+#### Example
+
+```ts
+type EmailString = StringContaining<'@'>; // string that contains '@'
+const email: EmailString = 'user@example.com'; // ✓ valid
+```
+
+***
+
+### StringEndingWith\<T\>
+
+```ts
+type StringEndingWith<T> = string extends T ? never : `${string}${T}`;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:40](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L40)
+
+A type representing a string that ends with a specific substring.
+Uses template literal types to ensure the string ends with the specified suffix.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+The substring that the string must end with
+
+#### Example
+
+```ts
+type JavaFile = StringEndingWith<'.java'>; // string ending with '.java'
+const filename: JavaFile = 'HelloWorld.java'; // ✓ valid
+```
+
+***
+
+### StringStartingWith\<T\>
+
+```ts
+type StringStartingWith<T> = string extends T ? never : `${T}${string}`;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:26](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L26)
+
+A type representing a string that starts with a specific substring.
+Uses template literal types to ensure the string begins with the specified prefix.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+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
+```
+
+## Functions
+
+### asNonEmptyStringOrNull()
+
+```ts
+function asNonEmptyStringOrNull(str): null | NonEmptyString;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:208](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L208)
+
+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.
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to convert
+
+#### Returns
+
+`null` \| [`NonEmptyString`](#nonemptystring)
+
+The string as `NonEmptyString` or `null` if empty
+
+***
+
+### asNonEmptyStringOrThrow()
+
+```ts
+function asNonEmptyStringOrThrow(str): NonEmptyString;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:194](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L194)
+
+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.
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to convert
+
+#### Returns
+
+[`NonEmptyString`](#nonemptystring)
+
+The string as `NonEmptyString`
+
+#### Throws
+
+Error if the string is empty
+
+***
+
+### assertStringIsNonEmpty()
+
+```ts
+function assertStringIsNonEmpty(str): asserts str is NonEmptyString;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:222](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L222)
+
+Assertion function that ensures a string is non-empty.
+Throws an error if the string is empty, otherwise narrows the type to `NonEmptyString`.
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to assert as non-empty
+
+#### Returns
+
+`asserts str is NonEmptyString`
+
+#### Throws
+
+Error if the string is empty
+
+***
+
+### isNonEmptyString()
+
+```ts
+function isNonEmptyString(str): str is NonEmptyString;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:182](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L182)
+
+Type guard function that checks if a string is non-empty.
+Narrows the type to `NonEmptyString` when the check passes.
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to check
+
+#### Returns
+
+`str is NonEmptyString`
+
+`true` if the string has length > 0, `false` otherwise
+
+***
+
+### splitTypedString()
+
+```ts
+function splitTypedString<T>(str, separator): [string, string, ...string[]];
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:103](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L103)
+
+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.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### str
+
+A string that contains, starts with, or ends with the separator
+
+[`StringContaining`](#stringcontaining)\<`NoInfer`\<`T`\>\> | [`StringStartingWith`](#stringstartingwith)\<`NoInfer`\<`T`\>\> | [`StringEndingWith`](#stringendingwith)\<`NoInfer`\<`T`\>\>
+
+##### separator
+
+`T`
+
+The separator to split by
+
+#### Returns
+
+\[`string`, `string`, `...string[]`\]
+
+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']
+```
+
+***
+
+### splitTypedStringAt()
+
+```ts
+function splitTypedStringAt<T>(
+   str, 
+   separator, 
+   splitAtNSeparatorPos): [string, string];
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:129](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L129)
+
+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.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### str
+
+A string that contains, starts with, or ends with the separator
+
+[`StringContaining`](#stringcontaining)\<`NoInfer`\<`T`\>\> | [`StringStartingWith`](#stringstartingwith)\<`NoInfer`\<`T`\>\> | [`StringEndingWith`](#stringendingwith)\<`NoInfer`\<`T`\>\>
+
+##### separator
+
+`T`
+
+The separator to split by
+
+##### splitAtNSeparatorPos
+
+`number` = `1`
+
+The position of the separator to split at (1-based)
+
+#### Returns
+
+\[`string`, `string`\]
+
+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'
+```
+
+***
+
+### stringContains()
+
+```ts
+function stringContains<T>(str, substring): str is StringContaining<T>;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:51](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L51)
+
+Type guard function that checks if a string contains a specific substring.
+Narrows the type to `StringContaining<T>` when the check passes.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to check
+
+##### substring
+
+`T`
+
+The substring to search for
+
+#### Returns
+
+`str is StringContaining<T>`
+
+`true` if the string contains the substring, `false` otherwise
+
+***
+
+### stringEndsWith()
+
+```ts
+function stringEndsWith<T>(str, substring): str is StringEndingWith<T>;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:81](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L81)
+
+Type guard function that checks if a string ends with a specific substring.
+Narrows the type to `StringEndingWith<T>` when the check passes.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to check
+
+##### substring
+
+`T`
+
+The substring to check for at the end
+
+#### Returns
+
+`str is StringEndingWith<T>`
+
+`true` if the string ends with the substring, `false` otherwise
+
+***
+
+### stringStartsWith()
+
+```ts
+function stringStartsWith<T>(str, substring): str is StringStartingWith<T>;
+```
+
+Defined in: [packages/utils/src/typedStrings.ts:66](https://github.com/lucasols/utils/blob/main/packages/utils/src/typedStrings.ts#L66)
+
+Type guard function that checks if a string starts with a specific substring.
+Narrows the type to `StringStartingWith<T>` when the check passes.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### str
+
+`string`
+
+The string to check
+
+##### substring
+
+`T`
+
+The substring to check for at the beginning
+
+#### Returns
+
+`str is StringStartingWith<T>`
+
+`true` if the string starts with the substring, `false` otherwise

package/docs/typingFnUtils/-internal-.md

@@ -8,13 +8,29 @@
 
 ## Type Aliases
 
+### KeysWithUndefinedValues\<T\>
+
+```ts
+type KeysWithUndefinedValues<T> = { [K in keyof T]: undefined extends T[K] ? K : never }[keyof T];
+```
+
+Defined in: [packages/utils/src/typeUtils.ts:149](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeUtils.ts#L149)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+***
+
 ### UnionDiff\<T, U\>
 
 ```ts
 type UnionDiff<T, U> = [T] extends [U] ? [U] extends [T] ? null : object : [U] extends [T] ? object : object;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:92](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L92)
+Defined in: [packages/utils/src/typingFnUtils.ts:93](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L93)
 
 #### Type Parameters
 

package/docs/typingFnUtils/README.md

@@ -18,7 +18,7 @@
 const isSubTypeOf: <BaseType, SubType>() => unknown = typeOnRightExtendsLeftType;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:78](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L78)
+Defined in: [packages/utils/src/typingFnUtils.ts:79](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L79)
 
 Type helper to check if a type is a subtype of another type.
 
@@ -54,7 +54,7 @@ use typeOnRightExtendsLeftType instead
 function asNonPartial<T>(obj): NonPartial<T>;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:3](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L3)
+Defined in: [packages/utils/src/typingFnUtils.ts:4](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L4)
 
 #### Type Parameters
 
@@ -74,13 +74,39 @@ Defined in: [packages/utils/src/typingFnUtils.ts:3](https://github.com/lucasols/
 
 ***
 
+### asPartialUndefinedValues()
+
+```ts
+function asPartialUndefinedValues<T>(value): T;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:110](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L110)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+#### Parameters
+
+##### value
+
+\{ \[P in string \| number \| symbol\]: (Partial\<Pick\<T, KeysWithUndefinedValues\<T\>\>\> & Omit\<T, KeysWithUndefinedValues\<T\>\>)\[P\] \}
+
+#### Returns
+
+`T`
+
+***
+
 ### asType()
 
 ```ts
 function asType<T>(value): T;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:37](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L37)
+Defined in: [packages/utils/src/typingFnUtils.ts:38](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L38)
 
 a safe way to cast types, use to substitute the `as Type`
 
@@ -108,7 +134,7 @@ a safe way to cast types, use to substitute the `as Type`
 function isObjKey<T>(key, obj): key is keyof T;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:85](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L85)
+Defined in: [packages/utils/src/typingFnUtils.ts:86](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L86)
 
 Type helper to narrow a string to a key of an object.
 
@@ -140,7 +166,7 @@ Type helper to narrow a string to a key of an object.
 function narrowStringToUnion<T>(key, union): undefined | T;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:46](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L46)
+Defined in: [packages/utils/src/typingFnUtils.ts:47](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L47)
 
 narrow a string to a union of strings
 
@@ -172,7 +198,7 @@ narrow a string to a union of strings
 function typedObjectEntries<T>(obj): NonNullable<{ [K in string | number | symbol]: [K, T[K]] }[keyof T]>[];
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:13](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L13)
+Defined in: [packages/utils/src/typingFnUtils.ts:14](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L14)
 
 a wrapper to Object.entries with a better typing inference
 
@@ -200,7 +226,7 @@ a wrapper to Object.entries with a better typing inference
 function typedObjectKeys<T>(obj): keyof T[];
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:27](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L27)
+Defined in: [packages/utils/src/typingFnUtils.ts:28](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L28)
 
 a wrapper to Object.keys with a better typing inference
 
@@ -228,7 +254,7 @@ keyof `T`[]
 function typeOnRightExtendsLeftType<BaseType, SubType>(): unknown;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:70](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L70)
+Defined in: [packages/utils/src/typingFnUtils.ts:71](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L71)
 
 Type helper to check if a type is a subtype of another type.
 
@@ -260,7 +286,7 @@ Returns undefined, only used for type checking
 function unionsAreTheSame<T, U>(_diff): void;
 ```
 
-Defined in: [packages/utils/src/typingFnUtils.ts:107](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L107)
+Defined in: [packages/utils/src/typingFnUtils.ts:108](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L108)
 
 Type helper to compare two union types and determine their relationship.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.37.0",
+  "version": "3.38.0",
   "license": "MIT",
   "files": [
     "dist",
@@ -200,6 +200,10 @@
       "import": "./dist/typeUtils.typesTest.js",
       "require": "./dist/typeUtils.typesTest.cjs"
     },
+    "./typedStrings": {
+      "import": "./dist/typedStrings.js",
+      "require": "./dist/typedStrings.cjs"
+    },
     "./typingFnUtils": {
       "import": "./dist/typingFnUtils.js",
       "require": "./dist/typingFnUtils.cjs"