@ls-stack/utils 3.37.0 → 3.39.0

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)