@ls-stack/utils 3.36.0 → 3.38.0

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/testUtils.md

@@ -14,7 +14,7 @@
 function compactSnapshot(value, options): string;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:363](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L363)
+Defined in: [packages/utils/src/testUtils.ts:364](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L364)
 
 Produces a more compact and readable snapshot of a value using yaml.
 By default booleans are shown as `✅` and `❌`, use `showBooleansAs` to disable/configure this.

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