@ls-stack/utils 3.18.0 → 3.20.0

package/docs/typeGuards.md

@@ -0,0 +1,399 @@
+[**@ls-stack/utils**](README.md)
+
+***
+
+[@ls-stack/utils](modules.md) / typeGuards
+
+# typeGuards
+
+## Type Aliases
+
+### NonEmptyArray\<T\>
+
+```ts
+type NonEmptyArray<T> = [T, ...T[]];
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:128](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L128)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+## Functions
+
+### arrayHasAtLeastXItems()
+
+#### Call Signature
+
+```ts
+function arrayHasAtLeastXItems<T>(array, minLength): array is [T, ...T[]];
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:136](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L136)
+
+##### Type Parameters
+
+###### T
+
+`T`
+
+##### Parameters
+
+###### array
+
+`T`[]
+
+###### minLength
+
+`1`
+
+##### Returns
+
+`array is [T, ...T[]]`
+
+#### Call Signature
+
+```ts
+function arrayHasAtLeastXItems<T>(array, minLength): array is [T, T, ...T[]];
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:140](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L140)
+
+##### Type Parameters
+
+###### T
+
+`T`
+
+##### Parameters
+
+###### array
+
+`T`[]
+
+###### minLength
+
+`2`
+
+##### Returns
+
+`array is [T, T, ...T[]]`
+
+#### Call Signature
+
+```ts
+function arrayHasAtLeastXItems<T>(array, minLength): array is [T, T, T, ...T[]];
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:144](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L144)
+
+##### Type Parameters
+
+###### T
+
+`T`
+
+##### Parameters
+
+###### array
+
+`T`[]
+
+###### minLength
+
+`3`
+
+##### Returns
+
+`array is [T, T, T, ...T[]]`
+
+#### Call Signature
+
+```ts
+function arrayHasAtLeastXItems<T>(array, minLength): array is [T, T, T, T, ...T[]];
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:148](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L148)
+
+##### Type Parameters
+
+###### T
+
+`T`
+
+##### Parameters
+
+###### array
+
+`T`[]
+
+###### minLength
+
+`4`
+
+##### Returns
+
+`array is [T, T, T, T, ...T[]]`
+
+#### Call Signature
+
+```ts
+function arrayHasAtLeastXItems<T>(array, minLength): array is [T, T, T, T, T, ...T[]];
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:152](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L152)
+
+##### Type Parameters
+
+###### T
+
+`T`
+
+##### Parameters
+
+###### array
+
+`T`[]
+
+###### minLength
+
+`5`
+
+##### Returns
+
+`array is [T, T, T, T, T, ...T[]]`
+
+***
+
+### isFunction()
+
+```ts
+function isFunction(value): value is (args: any[]) => any;
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:51](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L51)
+
+Type guard to check if a value is a function.
+
+Returns true if the value is a function of any kind (regular function,
+arrow function, method, constructor, etc.).
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+The value to check
+
+#### Returns
+
+`value is (args: any[]) => any`
+
+True if the value is a function, false otherwise
+
+#### Example
+
+```typescript
+if (isFunction(value)) {
+  // TypeScript knows value is (...args: any[]) => any
+  const result = value();
+}
+
+isFunction(() => {});           // true
+isFunction(function() {});      // true
+isFunction(Math.max);           // true
+isFunction('string');           // false
+isFunction({});                 // false
+```
+
+***
+
+### isNonEmptyArray()
+
+```ts
+function isNonEmptyArray<T>(value): value is NonEmptyArray<T>;
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:130](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L130)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### value
+
+`T`[] | readonly `T`[]
+
+#### Returns
+
+`value is NonEmptyArray<T>`
+
+***
+
+### isObject()
+
+```ts
+function isObject(value): value is Record<string, unknown>;
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:24](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L24)
+
+Type guard to check if a value is a plain object (not null, not an array).
+
+Returns true if the value is an object that is not null and not an array.
+This is useful for distinguishing between objects and other types.
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+The value to check
+
+#### Returns
+
+`value is Record<string, unknown>`
+
+True if the value is a plain object, false otherwise
+
+#### Example
+
+```typescript
+if (isObject(value)) {
+  // TypeScript knows value is Record<string, unknown>
+  console.log(value.someProperty);
+}
+
+isObject({});           // true
+isObject({ a: 1 });     // true
+isObject(null);         // false
+isObject([]);           // false
+isObject('string');     // false
+```
+
+***
+
+### isPlainObject()
+
+```ts
+function isPlainObject(value): value is Record<string, unknown>;
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:109](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L109)
+
+Type guard to check if a value is a plain object (created by Object literal or Object constructor).
+
+Returns true if the value is a plain object - an object created by the Object
+constructor or object literal syntax. This excludes instances of classes,
+built-in objects like Date, RegExp, etc.
+
+#### Parameters
+
+##### value
+
+`any`
+
+The value to check
+
+#### Returns
+
+`value is Record<string, unknown>`
+
+True if the value is a plain object, false otherwise
+
+#### Example
+
+```typescript
+if (isPlainObject(value)) {
+  // TypeScript knows value is Record<string, unknown>
+  console.log(Object.keys(value));
+}
+
+isPlainObject({});                    // true
+isPlainObject({ a: 1 });              // true
+isPlainObject(Object.create(null));   // true
+isPlainObject(new Date());            // false
+isPlainObject(/regex/);               // false
+isPlainObject(new MyClass());         // false
+isPlainObject([]);                    // false
+```
+
+***
+
+### isPromise()
+
+```ts
+function isPromise(value): value is Promise<unknown>;
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:79](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L79)
+
+Type guard to check if a value is a Promise or thenable object.
+
+Returns true if the value is an object with a `then` method that is a function.
+This covers both native Promises and thenable objects that implement the
+Promise interface.
+
+#### Parameters
+
+##### value
+
+`unknown`
+
+The value to check
+
+#### Returns
+
+`value is Promise<unknown>`
+
+True if the value is a Promise or thenable, false otherwise
+
+#### Example
+
+```typescript
+if (isPromise(value)) {
+  // TypeScript knows value is Promise<unknown>
+  const result = await value;
+}
+
+isPromise(Promise.resolve());           // true
+isPromise(new Promise(() => {}));       // true
+isPromise({ then: () => {} });          // true
+isPromise({ then: 'not a function' });  // false
+isPromise('string');                    // false
+```
+
+***
+
+### isTruthy()
+
+```ts
+function isTruthy<T>(value): value is Exclude<T, undefined | null | false | "" | 0 | 0n>;
+```
+
+Defined in: [packages/utils/src/typeGuards.ts:163](https://github.com/lucasols/utils/blob/main/packages/utils/src/typeGuards.ts#L163)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### value
+
+`T`
+
+#### Returns
+
+value is Exclude\<T, undefined \| null \| false \| "" \| 0 \| 0n\>

package/docs/typingFnUtils/-internal-.md

@@ -0,0 +1,27 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / [typingFnUtils](README.md) / \<internal\>
+
+# \<internal\>
+
+## Type Aliases
+
+### 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:77](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L77)
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### U
+
+`U`

package/docs/typingFnUtils/README.md

@@ -0,0 +1,293 @@
+[**@ls-stack/utils**](../README.md)
+
+***
+
+[@ls-stack/utils](../modules.md) / typingFnUtils
+
+# typingFnUtils
+
+## Modules
+
+- [\<internal\>](-internal-.md)
+
+## Variables
+
+### ~~isSubTypeOf()~~
+
+```ts
+const isSubTypeOf: <BaseType, SubType>() => unknown = typeOnRightExtendsLeftType;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:65](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L65)
+
+Type helper to check if a type is a subtype of another type.
+
+#### Type Parameters
+
+##### BaseType
+
+`BaseType`
+
+The base type to check against
+
+##### SubType
+
+`SubType`
+
+The type that should extend BaseType
+
+#### Returns
+
+`unknown`
+
+Returns undefined, only used for type checking
+
+#### Deprecated
+
+use typeOnRightExtendsLeftType instead
+
+## Functions
+
+### asNonPartial()
+
+```ts
+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)
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+#### Parameters
+
+##### obj
+
+`T`
+
+#### Returns
+
+[`NonPartial`](../typingUtils.md#nonpartial)\<`T`\>
+
+***
+
+### asType()
+
+```ts
+function asType<T>(value): T;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:28](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L28)
+
+a safe way to cast types, use to substitute the `as Type`
+
+#### Type Parameters
+
+##### T
+
+`T` = `unknown`
+
+#### Parameters
+
+##### value
+
+`T`
+
+#### Returns
+
+`T`
+
+***
+
+### isObjKey()
+
+```ts
+function isObjKey<T>(key, obj): key is keyof T;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:70](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L70)
+
+Type helper to narrow a string to a key of an object.
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+#### Parameters
+
+##### key
+
+`unknown`
+
+##### obj
+
+`T`
+
+#### Returns
+
+`key is keyof T`
+
+***
+
+### narrowStringToUnion()
+
+```ts
+function narrowStringToUnion<T>(key, union): undefined | T;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:33](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L33)
+
+narrow a string to a union of strings
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `string`
+
+#### Parameters
+
+##### key
+
+`undefined` | `null` | `string`
+
+##### union
+
+`Set`\<`T`\> | `T`[] | readonly `T`[]
+
+#### Returns
+
+`undefined` \| `T`
+
+***
+
+### typedObjectEntries()
+
+```ts
+function typedObjectEntries<T>(obj): NonNullable<{ [K in string | number | symbol]: [K, T[K]] }[keyof T]>[];
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:10](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L10)
+
+a wrapper to Object.entries with a better typing inference
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+#### Parameters
+
+##### obj
+
+`T`
+
+#### Returns
+
+`NonNullable`\<\{ \[K in string \| number \| symbol\]: \[K, T\[K\]\] \}\[keyof `T`\]\>[]
+
+***
+
+### typedObjectKeys()
+
+```ts
+function typedObjectKeys<T>(obj): keyof T[];
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:21](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L21)
+
+a wrapper to Object.keys with a better typing inference
+
+#### Type Parameters
+
+##### T
+
+`T` *extends* `Record`\<`string`, `unknown`\>
+
+#### Parameters
+
+##### obj
+
+`T`
+
+#### Returns
+
+keyof `T`[]
+
+***
+
+### typeOnRightExtendsLeftType()
+
+```ts
+function typeOnRightExtendsLeftType<BaseType, SubType>(): unknown;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:57](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L57)
+
+Type helper to check if a type is a subtype of another type.
+
+#### Type Parameters
+
+##### BaseType
+
+`BaseType`
+
+The base type to check against
+
+##### SubType
+
+`SubType`
+
+The type that should extend BaseType
+
+#### Returns
+
+`unknown`
+
+Returns undefined, only used for type checking
+
+***
+
+### unionsAreTheSame()
+
+```ts
+function unionsAreTheSame<T, U>(_diff): void;
+```
+
+Defined in: [packages/utils/src/typingFnUtils.ts:93](https://github.com/lucasols/utils/blob/main/packages/utils/src/typingFnUtils.ts#L93)
+
+Type helper to compare two union types and determine their relationship.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+The first union type (left side)
+
+##### U
+
+`U`
+
+The second union type (right side)
+
+#### Parameters
+
+##### \_diff
+
+[`UnionDiff`](-internal-.md#uniondiff)\<`T`, `U`\>
+
+null if unions are identical, or an object describing the errors
+
+#### Returns
+
+`void`
+
+void - This function is only used for type checking